INSTALL for vhclmaps-0.7 Instructions for building vhclmaps-0.7.5 from source: 0. Compilation Environment Tools you will need before you can build: 0.a. a Unix machine. We've built on Linux, SunOS and Irix. It should build on most any Unix machine with similar config changes. 0.b. The gcc compiler. Recently we've been building and testing with gcc-2.8.1 and egcs-1.0.3. gcc-2.7.2.1 will probably still work. You will also need an equivalent copy of libstdc++. 0.c. An installed copy of X11R6 as distributed by the Open Group, or an equivalent (XFree86 for Linux, or X11R5 from MIT). If you use a vendor's X11 product, the product should be based on X11R4 or later and the product should include imake and the config files. If imake is not in the same place as the other X11 binaries are or anywhere else on your system, you can get the sources for imake from the X11R5 or X11R6 distribution at several public ftp archives (such as ftp.x.org). Check to see which cpp will get used by imake with "which cpp". You may have problems with other than a gcc C preprocessor. 0.d. You need to obtain, build, and install ivtools-0.8 (from http://www.ivtools.org/ivtools/) according to its INSTALL instructions before you can build vhclmaps-0.7. You can build ivtools with or without --enable-install-relative supplied to its configure script. Tips on building clippoly and ACE for use of vhclmaps and ivtools can be found in the ivtools INSTALL file. 0.e. You need to obtain, build and install PROJ-4.3 cartographic projection library from ftp://kai.er.usgs.gov/pub/PROJ.4/PROJ.4.3.3.tar.gz. 0.f. If you want to build the 3D elevation map viewer you will need to obtain vtk-2.2 (home page: http://www.kitware.com/vtk.html). You will also need to obtain the Mesa 3D graphics library (home page: http://www.mesa3d.org) unless you want to use another renderer supported by vtk. We currently use Mesa-3.0. For Mesa, type plain "make" to see a list of supported OS'es, then something like "make linux-elf". For vtk edit the Mesa pathnames (MESA_INCLUDE and MESA_LIB) in user.make and then use --with-mesa and --with-shared for configure. 1. Configuring vhclmaps: 1.a. You no longer need to set your CPU environment variable to build vhclmaps (or ivtools), but you still need a CPU specific configuration file. Ready-made configurations that have been known to work exist for LINUX, SUN4 (and Solaris), and SGI. Use "make CPU" from the top directory to see the symbol vhclmaps will use for your OS (grep config/arch.def for ArchitectureName to get a complete list of possible OS'es). Then look for a matching config/site.def. file, where is the value returned by "make CPU". If it is there proceed to step 1.b. Other variants of Unix can be attempted by creating the corresponding config/site.def., i.e. site.def.AIX or site.def.MIPS. Use SUN4 for Solaris as well as SunOS. Although SUN5 would be more correct, the config files automatically determine the difference between the two OS'es by checking for SVR4'ness. 1.b Run the configure script in the top-level directory, by entering "./configure" followed by any of the following arguments: --x-includes=DIR X include files are in DIR --x-libraries=DIR X library files are in DIR --enable-install-relative[=ARG] install relative to source tree --enable-install-subdir[=ARG] install in vhclmaps sub-directory --prefix=DIR to use when install-relative is false (default is /usr/local) --enable-use-rpath[=ARG] use -rpath when linking, to embed shared-library pathnames in executable. --enable and --with options recognized: --with-ace= Path to ACE includes --with-ace-libs= Path to ACE libraries --with-clippoly= Path to clippoly includes --with-clippoly-libs= Path to clippoly libraries --with-ivtools= Path to ivtools includes --with-ivtools-libs= Path to ivtools libraries --with-vtk= Path to vtk includes --with-vtk-libs= Path to vtk libraries --with-proj= Path to PROJ includes --with-proj-libs= Path to PROJ libraries --with-opengl= Path to OpenGL If the arguments for ACE, clippoly, vtk, or opengl are not supplied, the configure script prints a reminder, then proceeds to set up to build vhclmaps without these libraries. The configure script is usually able to automatically determine --x-includes and --x-libraries (except on Dec Alpha for some reason). (=0 or =1 can be substituted for =ARG. Default is =1 when not specified.) If you want to run the executables without installing them, use --enable-use-rpath to embed the shared library pathnames into the executables at link time. Here is an example of using the configure script with ACE, clippoly, Mesa, vtk, and ivtools libraries (ivtools is required): ./configure --with-clippoly=/proj/clippoly \ --with-ace=/proj/ACE_wrappers --with-vtk=/proj/vtk \ --with-opengl=/proj/Mesa-3.0 --with-ivtools=/usr/local/ivtools Running the configure script generates two files, a config/config.mk that gets included into each Makefile when used, and a config/config--gcc.defs that gets used by "make Makefiles" described below. is something like linux.The last line of output from the configure script shows this pathname. Verify that this is the same as the file included at the end of the config/site.def. file. Change the site.def. file if necessary. Also you may want to review the rest of the entries in the site.def. file to see if they are good defaults for your system. ** See http://www.ivtools.org/vhclmaps/faq.html for more info. 2. Compiling vhclmaps: 2.a. cd to the vhclmaps-0.7/ directory (you'd already be in this directory after running the configure script). 2.b. Compile it with a "make World" command. This command: - regenerates the top-level Makefile to snap it to the current directory ("make Makefile"). - runs through the source tree and generates all the other Makefile's ("make Makefiles"). - generates compilation dependencies for each directory with code to compile -- see the Makefile.depend file in each sub-directory ("make depend"). - compiles and links everything ("make -k"). If you have any trouble at this stage take a look at: http://www.ivtools.org/ivtools/faq.html#SourceBuild 3. Testing: Each directory under vhclmaps-0.7/src that begins in lower case (except for "scripts") contains executables for each particular viewer in $CPU/a.out. "cd" to each particular directory and read the README files that go into further detail on how to use the viewers. vhclmaps-0.7/src/utils contains sub-directories of map utility/test programs. 4. Installation: "make install" is supported for all the libraries, map viewers and the elevation map utilities if vtk has been configured. "make uninstall" is supported as well. When relative install is enabled (--enable-install-relative for the configure script), the binaries are installed in vhclmaps-0.7/bin/, the libraries are installed in vhclmaps-0.7/lib/, and the run-time X resource and config files are installed in vhclmaps-0.7/lib/vhclmaps. When relative install is disabled (the default for the configure script) the binaries are installed as stripped executables in `prefix`/bin the libraries are installed in `prefix`/lib, and the run-time X resource and config files are installed in `prefix`/lib/vhclmaps.