Tips for Building and Installing xephem v3.0.

Building xephem is intended to be straightforward. The idea is just to
compile all the *.c files and link with your X, Motif and UNIX libraries to
form the xephem executable program.


Once built, xephem requires several supporting files.  Defaults for all of
these are correct if the executable is run from the source directory where the
build was performed. To get color, be sure to install the X resource file,
XEphem.ad, where xephem can find it. There are many ways to do this, but one
way is to use the following command before running xephem:

    xrdb -merge XEphem.ad


Begin the build process by untaring everything into a fresh directory. You will
find all the source is in one directory, xephem_3.0. There will also be several
subdirectories containing other files but these are not important for now.


Start by constructing a suitable Makefile. If your system is fully set up for
using xmkmf or imake with Motif then try the supplied Imakefile by typing:

    xmkmf

or something like:

    imake -I/usr/lib/X11/config -DuseInstalled

then:

    make


If this doesn't work (which is too often the case in my experience) there is
also a sample stand-alone Makefile called Makefile.smple. Copy it to "makefile"
then find and uncomment the group of flags and libraries that looks close to
the way Motif programs are built on your system. Then type "make" which should
compile everything with the Motif include files and link with the X, Motif and
UNIX libraries as you would any Motif application. Don't forget the math
library, -lm.


If you are on VMS, there are some sample files which may help in the vms/
directory.


Here are some additional hints about compiling, linking and running xephem:

    You must have Motif! The first clue of trouble is when compiling calmenu.c
    you'll see messages about not finding many include files of the form
    "Xm/??". If you're 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.

    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 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't 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 am told 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've 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 on iraf.noao.edu in contrib/xephem/xephem_2.9 for
    contributed statically-linked binary executables.

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

    Finally, check the xephem home page for the latest build tips:
    	http://iraf.noao.edu/~ecdowney/xephem.html#hints


Follows is a summary of each of the runtime files used by xephem and, where
appropriate, the names of the related X resources which define them. Remember,
these are all already correctly located by default with respect to the build 
(source) directory, xephem_3.0.

    xephem: the main executable; put where you want locally installed X
	programs to live.

    xephem.hlp: help file; point at it with the resource:
	XEphem.HELPFILE

    *.edb: sample astronomical databases; put them all in a directory and
	name it by setting the X resource: XEphem.DBdirectory.

    xephem_sites: sample Earth sites file; point at it with the resource:
	XEphem.SITESFILE

    xephem.man: nroff source for manual; process the output with something like
	"nroff -man xephem.man" and place either/both where you want man pages
	for locally installed X programs.

    ppm.xe: the PPM catalog. This file is too large to be included in the base
        xephem distribtion. See the Help for the MainMenu->Objects->Field Stars
	dialog for information about this file and where to get it.

    fullmoon.fts: FITS file of full moon image; point at it with the resource:
	XEphem.MoonFile

    mars.fts: FITS file of Mars albedo; point at it with the resource:
	XEphem.MarsFile

    moon_db: list of lunar features; point at it with the resource:
	XEphem.MoonDB

    XEphem.ad: sample resource file; name it XEphem and place it where you
	want application default resources for locally installed X programs.
	Or put XEphem in, say, your home directory and set the environment
	variable XUSERFILESEARCHPATH to $HOME/%N. Or, load it on your X server
	by typing "xrdb -merge XEphem.ad".

    work/xephem.ps: this is the default name of Postscript save file. This is
	set with the X resource: XEphem*SaveAs*textString. Related, is the
	command which is issued to print. This command is assumed to accept the
	name of a postscript file to print as its one and only argument. The
	name of the command that is issued is in the X resource:
	XEphem*Print*textString.


If you would like to pull out just the astronomical functionality from xephem
for your own programs, start with obj_cir(). This is basically the dividing
line between the user interface and the astronomical functions.


If you get regcmp or regex undefined, you might try the functions below
which attempt to minimally implement them in terms of re_comp and re_exec.
The reg* functions historically came from the System V lineage of UNIX, while
the re_* functions came from the BSD lineage. To try these alternatives, put
them into a file, say, regcmp.c, and add regcmp.o to the OBJS list n the make
file and remake.


Finally, if you have really tried on your own and and still aren't getting
anywhere, feel free to contact me: Elwood Downey, ecdowney@noao.edu.

Enjoy!



=============================== regcmp.c ======================================

#include <stdio.h>

extern char *malloc();
extern char *re_comp();
extern int re_exec();

/* given an RE:
 *   compile and return malloced internal form if ok
 *   else return NULL if fail
 * N.B. we assume the entire pattern is in the first string.
 * N.B. we assume the caller has no interest within the returned string.
 */
char *
regcmp (re)
char *re;
{
	/* re_comp() returns NULL if RE compiled ok, else ptr to err message */
	if (re_comp (re) == NULL)
	    return (malloc ("Dummy RE"));
	return (NULL);
}

/* given compiled RE and subject:
 *   return ptr to next unmatched char if match found
 *   else return NULL if no match
 * N.B. we assume subject does not request any returned values.
 * N.B. we assume "next unmatched char" is the trailing \0 of subject.
 */
char *
regex (re, subject)
char *re, *subject;
{
	/* re_exec() returns 1 if match found, else 0 */
	if (re_exec(subject) == 1)
	    return (subject+strlen(subject));
	return (NULL);
}

======================== end of regcmp.c =====================================
