Binary Install:

To install a binary release of Source-Navigator, extract the
files from the archive and add the resulting sourcenavigator-<version>/bin
directory to your PATH. There is no need to run an installer.
You can run Source-Navigator from the command line using the
snavigator script. Windows users can also double-click on
the snavigator.exe executable in the Windows Explorer.

Generic Build Notes:

These build/install instructions assume that you have already
downloaded and extracted the source files from the zip or tar file.

We also suggest installing into a directory other than /usr
or /usr/local. Some users have reported version conflicts
between already installed packages like Tcl, Tk, Itcl, and
Tix and the versions of these packages that sourcenav depends
on. By installing into an application specific directory
like /opt/sourcenav, these problems can be avoided.


Source Layout:

The main application code is located in the subdirectory 
snavigator/ and is a mixture of C- and Tcl/Tk-code.
In db4/ a copy of the Berkeley DB library is located, whereas
under tcl/, tk/, tix/ and itcl/ verified versions of those libraries
are provided.
The build process automatically configures and uses those
libraries.

The configure script, by default, does not cache the results of tests.
To enable caching use the option --cache-file=<file>. Alternatively
--config-cache and -C are an alias for --cache-file=config.cache


UNIX Build:

GNU tools must be on the PATH before the configure script
is run. GNU make and gcc are required to build Source-Navigator.
If the GNU make executable on your system is installed as
gmake, type gmake instead of make in the following instructions.

To build under a UNIX system, simply run the configure script.
The following commands assume that the user wants to install into 
a non-default location (/opt/sourcenav) that is owned by root.
If the install directory is not owned by root, then you don't need 
to become root before the make install step.

% ./configure --prefix=/opt/sourcenav
% make
(become root)
% make install


Windows Build (gcc on msys/mingw):

The Windows version of Source-Navigator is now built with gcc.
The Mingw and Msys packages provide a minimal environment
and the compiler needed to build Win32 applications on
a Win32 system. Get the MSYS and MinGW installers here:

http://sourceforge.net/project/showfiles.php?group_id=2435

Install BOTH MSYS and MinGW and then start the msys shell.
You can then run the configure script in the normal way from inside 
the shell.

% ./configure --prefix=/opt/sourcenav --enable-mingw
  (the --enable-mingw is for db4)
% make
% make install

As there are a couple of header files missing in the default msys package,
most prominently socket.h - you might want to get them from somewhere, 
e.g. FreeBSD.


Windows Build (VC++):

Building with VC++ is significantly more tricky when compared to
the gcc build. We only suggest this method of building if you
have a specific reason to want to build with VC++ and you know
what you are doing. Be sure to follow the build instructions exactly.

Cygwin is required to build with VC++. The current release of
Cygwin can be found here:

http://cygwin.com/

Note that this build process has only been tested on binmode
Cygwin mount points. Since binmode is the default mount type,
it should just work by default.

One needs to run the vcvars32.bat that comes with VC++ before
starting the Cygwin bash shell. Typically, this is done by
starting command.com on Windows 95/98 or cmd.exe under NT, then
run the vcvars32.bat script in the VC++ bin directory.

After VC++ env vars are setup, start a bash shell by cd'ing to
the Cygwin root directory and running cygwin.bat. This will
start the bash shell where unix like commands can be entered.

Unfortunately, the current Cygwin grep.exe executable does not
deal with a input CRLF sequence properly. This issue needs
to be worked around by installing a version of grep that does
deal with CRLF sequences, otherwise the configure script will
generate an error since it checks the grep executable for
this problem.

A working Win32 grep executable can be found here:

http://unxutils.sourceforge.net/UnxUtils.zip

Unzip the archive in a temp directory, you won't need
all these utilities, only the grep.exe is needed. Now
create an empty directory grep will be saved, something
like ~/grep should work. Copy the usr/local/wbin/grep.exe
executable from the temp directory into ~/grep and finally
put the grep directory at the front of your PATH env var
so that it is used instead of the Cygwin version of grep.

export PATH=$HOME/grep:${PATH}

You can now run the configure script in the normal way. Of course,
there are a couple of things to take note of. First, the configure
script must be run with a relative path (../sourcenav-5.2.0/configure).
Second, the --prefix path must be passed as a fully qualified Windows
style path containing forward slashes (like D:/Cygwin/opt/sourcenav).
The following example shows how a patch like /opt/sourcenav mounted
at D:/Cygwin/opt/sourcenav would be passed.

% ./configure --host=windows32 --prefix=D:/Cygwin/opt/sourcenav
% make
% make install


Debug Build:

If you encounter a crashing bug in Source-Navigator and would like
to investigate the cause, there are a couple of debug build options
that could be useful. The first option is to pass the --enable-symbols
option to the configure script. This option will compile the
Source-Navigator executables with debug symbols. Debug symbols
can help to track down the exact cause of a crashing problem
inside a debugger.

One can also pass the --enable-symbols=mem option to the configure
script to compile with symbols and memory checking enabled. In this
mode, each allocation and deallocation is checked to make sure
the correct amount of memory is being returned to the system. Guard
regions are also placed at the front and end of each memory region
to check for memory overwriting problems. This memory debug mode
will slow down normal execution so it is only advised when
investigating a specific memory allocation problem.

