1
2 Nightfall is an interactive binary star application for
3 fun, education, and science.
4 FOR MORE INFORMATION, read the manual: *** UserManual.html ***.
5 There is also on-line help available in the interactive version.
6
7 Nightfall is copyright (c) Rainer Wichmann (rwichman@lsw.uni-heidelberg.de)
8 and is distributed under the terms of the GNU General Public License
9 (see the file 'COPYING'). Nightfall is provided 'as is', and comes
10 with ABSOLUTELY NO WARRANTY.
11
12
13INDEX OF THIS FILE:
14==================
15
161. Requirements
172. Installation
183. Quick start
194. Compilation problems
205. Internationalization
21
22
231. REQUIREMENTS:
24===============
25
26 If you have a recent Linux distribution, you should already have all
27 you need (in particular, the GNUPLOT program and the Gtk+ library).
28 If in doubt, read this section.
29
30 Graphic Output:
31 --------------
32
33 For (optional) graphic output, you need either
34
35 * a recent version of the GNUPLOT program
36 (one that supports the 'set multiplot' option).
37
38 or
39
40 * the PGPLOT graphics subroutine library
41 version 5.2 (older version may or may not work).
42 If installed, 'configure' might find it by itself; otherwise
43 you may need to use the 'configure' options
44 '--with-pgplot-include=PFX' (Prefix where PGPLOT header file
45 cpgplot.h is installed), and
46 '--with-pgplot-lib=PFX' (Prefix where PGPLOT library files
47 libpgplot.a, libcpgplot.a are installed).
48
49 PGPLOT is available at http://astro.caltech.edu/~tjp/pgplot,
50 and free for non-commercial use. Precompiled binaries
51 are available on the 'Linux for Astronomy' CD-ROMs
52 (http://www.randomfactory.com/lfa.html) and for Debian GNU/Linux
53 (http://www.debian.org).
54
55 Note: Personally, I use mostly PGPLOT, as it produces nicer plots.
56 The GNUPLOT version works, but plots are not that nice sometimes.
57 However, the animation runs smoother with GNUPLOT, flickers a lot
58 with PGPLOT.
59
60
61 Graphical User Interface:
62 ------------------------
63
64 For interactive use, an (optional) graphical user interface is
65 provided. To use it, you need the GTK+ library installed on your
66 system (version > 1.0.4; again, older version may or may not work).
67 GTK+ is distributed under the terms
68 of the GNU Public License and available at http://www.gtk.org.
69 NOTE: In your Linux distribution, GTK may be split in two packages
70 (run-time libraries and 'development' files). You will need both !
71
72 Nightfall will parse a file $HOME/.nightfallrc on startup.
73
74 Gnome:
75 -----
76
77 Nightfall will build with support for the Gnome Desktop, if you have
78 installed it. It does *not* require Gnome - it compiles just as well
79 without it.
80
81
82 It is possible to compile just the kernel (i.e. the part of the program
83 that computes the ligtcurve), without any plotting/interactive
84 options. This will be very boring, but will yield the fastest code.
85 Minimum requirement: an ANSI C compiler.
86
87
882. INSTALLATION:
89===============
90
91 To install Nightfall on your system, execute the following commands
92 (where '$' is your shell prompt, and '{version.number}' should be
93 replaced with the actual version number of Nightfall):
94
95 $ gunzip -c nightfall-{version.number}.tar.gz | tar -xvf -
96 $ cd nightfall-{version.number}
97 $ ./DoInstall.sh
98
99 The 'DoInstall.sh' script will query you for some information,
100 (e.g. the root directory under which to install),
101 and then (optionally) build, test, and install the application.
102
103 If you want to do it by hand, instead of './DoInstall.sh' run
104 the following sequence of commands:
105
106 $ ./configure <options>
107 $ make
108 $ make install
109
110 (type './configure --help' for a full list of options.)
111
112 Install Directories:
113 -------------------
114
115 The binary will be installed in /usr/local/bin by default.
116
117 Nightfall can read configuration files and datafiles containing
118 observational data. Example files are in the subdirectories 'data'/'cfg'.
119 The files there will be installed in /usr/local/share/Nightfall/cfg'
120 and '/usr/local/share/Nightfall/data'
121 by default.
122
123 HTML documentation and helpfiles for online help will be installed
124 in '/usr/local/share/Nightfall/doc' by default.
125
126 ** Change the default **: for installing somewhere else than
127 /usr/local, use the 'configure' option --prefix=/what/ever to replace
128 /usr/local by /what/ever (the 'DoInstall.sh' script will ask for this).
129 Avoid trailing '/', i.e. use /what/ever, NOT /what/ever/
130
131 Use --with-doc-prefix=/what/ever (..-data-prefix, ..) to change
132 the default install path for individual data subdirectories (doc/, cfg/,
133 data/, locale/).
134
135 If data subdirectories have been moved 'by hand' after installation,
136 you need to set the environment variable NIGHTFALL_DATAROOT to the
137 root path where doc/ (on-line help), cfg/ (sample binary stars),
138 data/ (sample lightcurves), locale/ (language support) can be found.
139 Alternatively, you can
140 set NIGHTFALL_DATA_DIR, NIGHTFALL_DOC_DIR, NIGHTFALL_CFG_DIR,
141 NIGHTFALL_LOCALE_DIR seperately.
142
143 To uninstall, use 'make uninstall'.
144
145
1463. QUICK STARTUP:
147================
148
149 After installing Nightfall, two examples of usage would be:
150
151 Non-interactive:
152 ---------------
153
154 $ nightfall -A -Db 0.9 80 1.0 0.7 4000. 5000.
155
156 This should produce an animated view of a binary system.
157
158 Interactive:
159 -----------
160
161 $ nightfall -U
162
163 This starts in interactive mode. You can then (e.g.) use the
164 menu option 'File->Config.File' to read in a configuration file, then
165 switch on 'ANIMATE' and click on 'COMPUTE' to compute the lightcurve,
166 an finally click 'PlotCurve' to see the final lightcurve with the
167 data overlayed.
168
169
170 -- READ THE MANUAL FOR MORE DETAILS --
171
172
1734. COMPILATION PROMLEMS:
174=======================
175
176 Note: Use 'make distclean' to delete any files you
177 have already created before running 'configure'
178 with some different option.
179
180 Second note: By default, nightfall will compile with
181 support for internationalization, and will try
182 to use whatever preinstalled utility is available
183 on your system. These preinstalled utilities
184 may be BROKEN, thus causing compile problems.
185 Read v), or the file ABOUT-NLS, for two possible
186 easy fixes to this problem.
187
188i) Have gnuplot, but configure does not find it
189
190 -- is gnuplot in your path ?
191 if no, update your PATH environment variable
192
193 -- does it support 'set multiplot' ?
194 ( start interactively by typing 'gnuplot',
195 then type 'set multiplot' to test)
196 if no, update your gnuplot
197
198 -- does 'gnuplot_x11 -persist' work, or does it
199 give an error message like:
200 gnuplot: bad option: -persist ?
201 if error, update your gnuplot
202
203 -- There was at least one gnuplot version that
204 supports the required 'multiplot' option, but does not
205 list it as supported.
206 In this case, enforce gnuplot support with:
207 ./configure --with-gnuplot
208
209ii) Have gnuplot and pgplot, want gnuplot support
210
211 -- use:
212 ./configure --with-gnuplot
213
214
215
216iii) Have pgplot, but configure does not find it
217
218 -- do you have a fortran compiler (required) ?
219
220 -- the following files are required:
221 cpgplot.h, libcpgplot.a, libpgplot.a
222 Use
223 ./configure --with-pgplot-include=/my/pgplot/include/dir --with-pgplot-lib=/my/pgplot/lib/dir
224 where '/my/pgplot/include/dir' is the directory where
225 cpgplot.h is located, and '/my/pgplot/lib/dir' is the directory
226 where libcpgplot.a, libpgplot.a are located.
227
228
229iv) Have pgplot, get compile error
230
231 -- maybe your fortran compiler does not understand the
232 link options required by Gtk.
233 upgrade to a recent version of g77.
234
235 -- maybe pgplot was compiled with a different fortran compiler.
236 recompile it from source.
237
238v) Other compile errors:
239
240 -- There might be problems related to internationalization,
241 that may be caused by a broken installation of a respective
242 utility on your system.
243 For solving this, you should choose one of the
244 following switches for the 'configure' script:
245
246 --disable-nls
247 --with-included-gettext
248
249 like, e.g.: ./configure --with-included-gettext
250
251 The first switch will completely disable internationalization,
252 i.e. only the english version will be available.
253 The second switch will use the internationalization
254 program that is included in this source code distribution,
255 thus bypassing any preinstalled, maybe broken, utility on
256 your system.
257
258
2595. INTERNATIONALIZATION:
260=======================
261
262 Currently, besides the default language (english), only
263 german is supported. If you want to make use of this
264 feature, you should:
265
266 NOT USE at compile time the 'configure' option
267 --disable-nls
268
269 at runtime set the environment variable LANG to 'de'
270 before starting the application
271 (if your shell is csh: setenv LANG de
272 else: LANG=de; export LANG)
273
274 NOTE: Currently, the datafiles are installed without changing
275 the decimal point character. Therefore, nightfall enforces the
276 use of the dot, even if (e.g. in the german locale) a comma would
277 be appropriate, otherwise the datafiles would be read incorrectly.
278
279 Please read the file ABOUT-NLS for more details about
280 internationalization.
281