How to install XEphem Version 3.2.2, either for just yourself or system-wide:


1) Build the executable:

    1.1. Explode xephem-3.2.2.tar.gz:

	$ tar xfz xephem-3.2.2.tar.gz

    1.2. Build the libastro.a library first:

	$ cd xephem-3.2.2/libastro
	$ xmkmf
	$ make

    If xmkmf does not work, start with Makefile.smple and proceed manually.

    1.3. Move up and over to the XEphem source and build it next:

	$ cd ../GUI/xephem
	$ xmkmf
	$ make

    If you get errors about Xm, you must find your Motif include files and
    library. Ask your sys admin to help, or try lesstif (www.lesstif.org).
    It might be just that your imake is not set up correctly in which case
    try Makefile.smple and proceed manually. See below for some more hints.

2) For the very curious, try it now; then choose File->Quit and go to the next
   step:

	$ ./xephem

	If you get a message "X Resources out of date" you have installed
	XEphem before and must locate and remove the old resource file.

Next do either 3a or 3b, not both:

3a) Installing XEphem for just yourself without root permission (see
    next step for system-wide multiuser installation):

    3a.1 Copy the executable where you keep your private programs:

	$ cp xephem $HOME/bin			# or where ever

    3a.2 Create a directory off your HOME called XEphem for all per-user files

	$ mkdir $HOME/XEphem

    3a.3 Copy XEphem.ad there, renamed to XEphem:

	$ cp XEphem.ad $HOME/XEphem/XEphem	# note the name change

    3a.4 Study the default resources and modify as desired. Be sure to at least
    edit XEphem.ShareDir to the full path of the directory containing the
    directories auxil/, fifos/, and fits/ and catalogs/. (These are in the
    source directory of the original tar kit; where you are now, if you
    have been following along).

	$ vi $HOME/XEphem/XEphem                # edit resources as desired

3b) Installing XEphem for multiple users (requires root permission) (skip if
    installing just for yourself):

    3b.1 Copy the executable where everyone can find it:

	$ cp xephem /usr/local/bin		# or where ever

    3b.2 Create a directory for system-wide read-only files to be shared by all
    XEphem users and fill with the defaults included in this kit:

	$ mkdir /usr/local/lib/XEphem		# or where ever
	$ cp -R auxil /usr/local/lib/XEphem	# copy auxil dir and contents
	$ cp -R catalogs /usr/local/lib/XEphem	# copy catalogs dir and contents
	$ cp -R fifos /usr/local/lib/XEphem	# copy fifos dir and contents
	$ cp -R fits /usr/local/lib/XEphem	# copy fits dir and contents
    
    3b.3 Study the default resources and set to values suitable for your
    site. Be sure to at least set XEphem.ShareDir to the directory chosen
    above.

    3b.4 Copy the default resource file named just XEphem where ever your X
    programs can find it:

	$ cp XEphem.ad /usr/lib/X11/app-defaults/XEphem	# or where ever

    3b.5 Tell each new user to perform the following steps:

	Create a directory off their HOME named XEphem:

	    $ mkdir $HOME/XEphem

	If they want to change the defaults, copy XEphem into
	    $HOME/XEphem and edit it as desired. N.B: Instruct them not to
	    change XEphem.ShareDir.

	    $ cp /usr/lib/X11/app-defaults/XEphem $HOME/XEphem # local copy
	    $ vi $HOME/XEphem/XEphem		# edit as desired

4) Fetch some more catalogs, if desired:

    Several were included with the tar kit but there are more. They go in
    the catalogs/ directory (which in turn is in where ever XEphem.ShareDir
    is set). Check the XEphem web page for where to get more catalogs.

5) That should do it. There is lots of help built-in. Enjoy! 

	$ xephem &

Let me know what you think.



Elwood Downey
ecdowney@ClearSkyInstitute.com
http://www.ClearSkyInstitute.com


========================= Miscellaneous Build hints ==========================


You must have Motif! The first clue of trouble is when compiling calmenu.c
you will see messages about not finding many include files of the form
"Xm/??". If you are sure you have Motif, then the compiler is not looking in
the right places. Once you know where they are located, add the include
directory with a -I argument in CFLAGS and the libXm* library with a -L
argument in LDFLAGS in the makefile.

On systems without ANSI C compilers add -D_NO_PROTO to CFLAGS.

On older USL/AT&T systems (such as SVR3.2) add -DSYSV to CFLAGS.

If you get regcmp or regex undefined from libXm on SVR4.2 add "-lgen"
to LIBS. Or try the crude replacement, below, for these functions in
terms of re_comp and re_exec.

Remember, timezone support from the operating system is only supported if
your compiler #defines __STDC__. Try to do this, as it is very useful.
For example on AIX you should use the xlc compiler; on Digital UNIX,
use the -std1 compiler option; on HPUX use the -Aa compiler option.

If running a Linux executable under FreeBSD in Linux emulation mode, be
sure to set up a symbolic link to your locatime timezone file in
/usr/share/timezone from /emul/linux/var/lib/zoneinfo. In general, if you
are sure you have an ANSI C compiler and you still do not get a timezone
name and offset when you start xephem, make sure you have either the TZ
environment variable or the current timezone links set up.

If you get undefines that begin with Xm add "-lXIM" to LIBS right after
"-lXm".

On SunOS systems, if your get dlopen/dlsym/dlclose undefined, try
fiddling with whether you use static or dynamic libs; best luck seems
to be with using all dynamic libs. It appears these three functions are
never called, however, since I can `chmod +x xephem' and it seems to
run ok.

On one HP 9000 I found that the X and Motif include files and libs were
in /usr/{include,lib}/{X11R4,Motif1.1}. There was no xmkmf or imake so I
used the "Stock" entry in Makefile.smple with the following flags:
    CFLAGS = $(CLDFLAGS) -O -D_NO_PROTO -I/usr/include/X11R4 -I/usr/include/Motif1.1
    LDFLAGS = $(CLDFLAGS) -L/usr/lib/X11R4 -L/usr/lib/Motif1.1

HP9000/300 systems (68030 CPU) running HP-UX 9.00 and gcc can run into
unexpected bugs within gcc. For example, the Sky View will not display
any Fixed objects! Ron Murray <ron@merlin.ece.curtin.edu.au> has some
workarounds and has graciously volunteered to assist people with these
systems.

On Digital UNIX, if you get runtime error messages about alignments, add this
compiler switch:  -assume noaligned_objects.

If you are behind a Socks firewall, xephem will try using the following
environment variables if they are set. The code has only been tested with
Socks version 4, but I am told version 5 should work too.
    SOCKS_NS	the name of the socks firewall host, or its IP address.
    SOCKS_PORT	the socks port to use; the default is 1080.

On OSF/1, be sure to use the -std1 compiler switch to turn on the ANSI C
compiler.

On AIX, be sure to invoke the ANSI C compiler, xlc.

I have searched carefully through the output of running all of xephem
through lint and gcc on UnixWare, Linux and SunOS and can rationalize
all the warnings, so don not let these bother you too much.

Avoid Motif 1.2.0; I start trusting Motif 1.2 around 1.2.4.

The left and right scales in the Sky View do not display their numeric
values under Solaris 5.4 -- I have no idea why.

If xephem does not work well on your color display, or the colormap is
out of entries, xephem can be operated using mostly black and white by
running it as: xephem -fg black -bg white. Let me know if you would like
an option to use a private colormap.

The BackSpace and Delete keys do not work correctly on many Linux systems.
The following commands should correct the problem (I have them in my
.xinitrc):
    xmodmap -e "keycode 22 = BackSpace"
    xmodmap -e "keycode 107 = Delete"

If running under UnixWare 2.0 with mwm, you will get traditional Motif
dialog behavior if you set Mwm*secondariesOnTop: True.

If you are having trouble using the Hubble GSC CDROMs on a Sun workstation,
you can find useful tips at http://www.stsci.edu/ftp/software/cdrom.sun.

As of 1.3.87, Linux could not read the Hubble GSC CDROM from the Sony
CDU31a drive, but I know it does work OK with an IDE or SCSI CD drive. I
will continue to work this issue (since I own the Sony drive :-( ) so
contact me for the latest status. UPDATE: I just tried kernal 2.0.23 and
it works fine -- so if you have been looking for a reason to move to the
2.0 kernal series this might be it :-)

If you wish to avoid building the executable altogether, such as if you do
not have Motif, check the XEphem web page for contributed statically-linked
binary executables.

If running under the Afterstep window manager, it may help if you add
DecorateTransients to the .steprc file.

If you are using a monochrome display, the resources in XEphem.bw.ad
will get you started, but I have not tried these in years.
