Nightfall is an interactive binary star application for fun, education, and science. FOR MORE INFORMATION, read the manual: *** UserManual.html ***. There is also on-line help available in the interactive version. Nightfall is copyright (c) Rainer Wichmann (rwichman@lsw.uni-heidelberg.de) and is distributed under the terms of the GNU General Public License (see the file 'COPYING'). Nightfall is provided 'as is', and comes with ABSOLUTELY NO WARRANTY. INDEX OF THIS FILE: ================== 1. Requirements 2. Installation 3. Quick start 4. Compilation problems 5. Internationalization 1. REQUIREMENTS: =============== If you have a recent Linux distribution, you should already have all you need (in particular, the GNUPLOT program and the Gtk+ library). If in doubt, read this section. Graphic Output: -------------- For (optional) graphic output, you need either * a recent version of the GNUPLOT program (one that supports the 'set multiplot' option). or * the PGPLOT graphics subroutine library version 5.2 (older version may or may not work). If installed, 'configure' might find it by itself; otherwise you may need to use the 'configure' options '--with-pgplot-include=PFX' (Prefix where PGPLOT header file cpgplot.h is installed), and '--with-pgplot-lib=PFX' (Prefix where PGPLOT library files libpgplot.a, libcpgplot.a are installed). PGPLOT is available at http://astro.caltech.edu/~tjp/pgplot, and free for non-commercial use. Precompiled binaries are available on the 'Linux for Astronomy' CD-ROMs (http://www.randomfactory.com/lfa.html) and for Debian GNU/Linux (http://www.debian.org). Note: Personally, I use mostly PGPLOT, as it produces nicer plots. The GNUPLOT version works, but plots are not that nice sometimes. However, the animation runs smoother with GNUPLOT, flickers a lot with PGPLOT. Graphical User Interface: ------------------------ For interactive use, an (optional) graphical user interface is provided. To use it, you need the GTK+ library installed on your system (version > 1.0.4; again, older version may or may not work). GTK+ is distributed under the terms of the GNU Public License and available at http://www.gtk.org. NOTE: In your Linux distribution, GTK may be split in two packages (run-time libraries and 'development' files). You will need both ! Nightfall will parse a file $HOME/.nightfallrc on startup. Gnome: ----- Nightfall will build with support for the Gnome Desktop, if you have installed it. It does *not* require Gnome - it compiles just as well without it. It is possible to compile just the kernel (i.e. the part of the program that computes the ligtcurve), without any plotting/interactive options. This will be very boring, but will yield the fastest code. Minimum requirement: an ANSI C compiler. 2. INSTALLATION: =============== To install Nightfall on your system, execute the following commands (where '$' is your shell prompt, and '{version.number}' should be replaced with the actual version number of Nightfall): $ gunzip -c nightfall-{version.number}.tar.gz | tar -xvf - $ cd nightfall-{version.number} $ ./DoInstall.sh The 'DoInstall.sh' script will query you for some information, (e.g. the root directory under which to install), and then (optionally) build, test, and install the application. If you want to do it by hand, instead of './DoInstall.sh' run the following sequence of commands: $ ./configure <options> $ make $ make install (type './configure --help' for a full list of options.) Install Directories: ------------------- The binary will be installed in /usr/local/bin by default. Nightfall can read configuration files and datafiles containing observational data. Example files are in the subdirectories 'data'/'cfg'. The files there will be installed in /usr/local/share/Nightfall/cfg' and '/usr/local/share/Nightfall/data' by default. HTML documentation and helpfiles for online help will be installed in '/usr/local/share/Nightfall/doc' by default. ** Change the default **: for installing somewhere else than /usr/local, use the 'configure' option --prefix=/what/ever to replace /usr/local by /what/ever (the 'DoInstall.sh' script will ask for this). Avoid trailing '/', i.e. use /what/ever, NOT /what/ever/ Use --with-doc-prefix=/what/ever (..-data-prefix, ..) to change the default install path for individual data subdirectories (doc/, cfg/, data/, locale/). If data subdirectories have been moved 'by hand' after installation, you need to set the environment variable NIGHTFALL_DATAROOT to the root path where doc/ (on-line help), cfg/ (sample binary stars), data/ (sample lightcurves), locale/ (language support) can be found. Alternatively, you can set NIGHTFALL_DATA_DIR, NIGHTFALL_DOC_DIR, NIGHTFALL_CFG_DIR, NIGHTFALL_LOCALE_DIR seperately. To uninstall, use 'make uninstall'. 3. QUICK STARTUP: ================ After installing Nightfall, two examples of usage would be: Non-interactive: --------------- $ nightfall -A -Db 0.9 80 1.0 0.7 4000. 5000. This should produce an animated view of a binary system. Interactive: ----------- $ nightfall -U This starts in interactive mode. You can then (e.g.) use the menu option 'File->Config.File' to read in a configuration file, then switch on 'ANIMATE' and click on 'COMPUTE' to compute the lightcurve, an finally click 'PlotCurve' to see the final lightcurve with the data overlayed. -- READ THE MANUAL FOR MORE DETAILS -- 4. COMPILATION PROMLEMS: ======================= Note: Use 'make distclean' to delete any files you have already created before running 'configure' with some different option. Second note: By default, nightfall will compile with support for internationalization, and will try to use whatever preinstalled utility is available on your system. These preinstalled utilities may be BROKEN, thus causing compile problems. Read v), or the file ABOUT-NLS, for two possible easy fixes to this problem. i) Have gnuplot, but configure does not find it -- is gnuplot in your path ? if no, update your PATH environment variable -- does it support 'set multiplot' ? ( start interactively by typing 'gnuplot', then type 'set multiplot' to test) if no, update your gnuplot -- does 'gnuplot_x11 -persist' work, or does it give an error message like: gnuplot: bad option: -persist ? if error, update your gnuplot -- There was at least one gnuplot version that supports the required 'multiplot' option, but does not list it as supported. In this case, enforce gnuplot support with: ./configure --with-gnuplot ii) Have gnuplot and pgplot, want gnuplot support -- use: ./configure --with-gnuplot iii) Have pgplot, but configure does not find it -- do you have a fortran compiler (required) ? -- the following files are required: cpgplot.h, libcpgplot.a, libpgplot.a Use ./configure --with-pgplot-include=/my/pgplot/include/dir --with-pgplot-lib=/my/pgplot/lib/dir where '/my/pgplot/include/dir' is the directory where cpgplot.h is located, and '/my/pgplot/lib/dir' is the directory where libcpgplot.a, libpgplot.a are located. iv) Have pgplot, get compile error -- maybe your fortran compiler does not understand the link options required by Gtk. upgrade to a recent version of g77. -- maybe pgplot was compiled with a different fortran compiler. recompile it from source. v) Other compile errors: -- There might be problems related to internationalization, that may be caused by a broken installation of a respective utility on your system. For solving this, you should choose one of the following switches for the 'configure' script: --disable-nls --with-included-gettext like, e.g.: ./configure --with-included-gettext The first switch will completely disable internationalization, i.e. only the english version will be available. The second switch will use the internationalization program that is included in this source code distribution, thus bypassing any preinstalled, maybe broken, utility on your system. 5. INTERNATIONALIZATION: ======================= Currently, besides the default language (english), only german is supported. If you want to make use of this feature, you should: NOT USE at compile time the 'configure' option --disable-nls at runtime set the environment variable LANG to 'de' before starting the application (if your shell is csh: setenv LANG de else: LANG=de; export LANG) NOTE: Currently, the datafiles are installed without changing the decimal point character. Therefore, nightfall enforces the use of the dot, even if (e.g. in the german locale) a comma would be appropriate, otherwise the datafiles would be read incorrectly. Please read the file ABOUT-NLS for more details about internationalization.
