The Installation Guide to BRL-CAD
=================================

Please read this document if you are interested in installing BRL-CAD.

This document covers the basics of installing BRL-CAD from either a
source or binary distribution.  Please see the 'Reporting Problems'
section if you run into any trouble installing BRL-CAD.

Some platforms have additional platform-specific documentation
provided in the doc/ directory of the source distribution that should
be consulted if that is the platform you are installing on.  This
presently includes the following:

  doc/README.MacOSX	-- Apple Mac OS X
  doc/README.IRIX	-- SGI IRIX and IRIX64
  doc/README.Linux	-- Various Linux distributions


TABLE OF CONTENTS
-----------------
  Introduction
  Table of Contents
  Quick Installation
  Installing from Binary
  Installing from Source
  Configuration Options
  Compilation Options
  Installation Options
  Testing Functionality
  Post-Installation
  Reporting Problems


QUICK INSTALLATION
------------------

If you downloaded a binary distribution of BRL-CAD for your system,
please read the INSTALLING FROM BINARY section of this document down
below.  The rest of this quick installation section is only relevant
to source code distributions of BRL-CAD.

For the impatient or simplistic, the following should compile, test,
and install an optimized BRL-CAD quickly into the /usr/brlcad
directory.  If you have a configure script, run the following:

  ./configure --enable-optimized
  make
  make benchmark
  make test
  make install   # as root, e.g. sudo make install

If you don't have a configure script, run the following to generate
the script then proceed with the steps above:

  sh autogen.sh

If any of the listed steps fail, then something unexpected happened.
See the REPORTING PROBLEMS section of this document to report the
problem or the INSTALLING FROM SOURCE section for more comprehensive
instructions.

Once installed, add /usr/brlcad/bin to your path, and you should be
able to run one of the 400+ applications that constitute BRL-CAD.  For
example, to run the MGED solid modeler:

PATH=/usr/brlcad/bin:$PATH ; export PATH
mged

If you use tcsh or another C-shell based command shell, use this
instead:

set path=( /usr/brlcad/bin $path ) ; rehash
mged


INSTALLING FROM BINARY
----------------------

There are a variety of different kinds of binary distributions of
BRL-CAD.  Some of the binary disributions are sufficiently generic and
are simply a binary commpressed tarball distribution.  Others are
specific to a particular platform such as Debian, Mac OS X, FreeBSD,
and Windows etc.


Generic Binary Distributions:

For the unspecialized binary distributions that are basically
compressed tarballs of the installation root, they should contain the
entire hierarchy of the distribution.  That is to say that they
contain /usr/brlcad in it's entirety so that if you decompress, you
will have a `usr' directory that contains a single `brlcad' directory:

gunzip brlcad-7.2.4_linux_ia64.tar.gz
tar -xvf brlcad-7.2.4_linux_ia64.tar
sudo mv usr/brlcad /usr/.

Of course, there are other compression options possible including zip
and bzip2.  By default, BRL-CAD expects to be installed into
/usr/brlcad and MGED is not relocatable by default.  It's recommended
that you start from a source distribution if you would like to install
into an alternate installation location.

However, if you do desire to install and run BRL-CAD from a different
location, give it a try.. ;) The only problems encountered should be
with running the MGED solid modeler where you will need to set the
BRLCAD_ROOT environment variable to your different install location
(e.g. /usr/local).  If this doesn't work (some platforms are more
problematic than others), you will need to compile and install from a
source distribution.


Mac OS X Disk Mounting Image:

Mount the .dmg and run the Installer .pkg contained therein.  This
will install into /usr/brlcad and will only require confirming that
your environment is set up properly (i.e. add /usr/brlcad/bin to your
path) as described in this document's Installation Options section.


INSTALLING FROM SOURCE
----------------------

There are a couple means to obtain the BRL-CAD sources, usually via
one of the following starting points:

  1) from a SVN checkout/export, or
  2) from a source distribution tarball

Using the latest SVN sources is recommended where possible, since it
will have the latest changes.  See the corresponding section below for
details on how to install from either starting point.


Starting From a SVN Checkout/Export:

If you have obtained the BRL-CAD sources from the SVN revision control
system, you will need to prepare the build for configuration:

  sh autogen.sh

This step requires that you have the GNU Build System (GBS) installed,
which includes a sufficiently recent version of Autoconf, Automake,
and Libtool.  Running autogen.sh will verify that the versions of each
are sufficient and will generate the `configure' script.  If you do
not have sufficient versions of the GBS components installed, you will
either need to install/ugrade them, run autogen.sh on another system
and them copy the files over, or start with a source tarball
distribution (where autogen.sh is automatically run for you).

Once autogen.sh is sucessfully run somewhere, you can continue with
the steps shown next for starting from a source distribution.


Starting From a Source Distribution:

There are many different ways to build BRL-CAD and depending on what
you need/want will determine which configuration options you should
use.  See the CONFIGURATION OPTIONS section below for details on how
to go about selecting which options are appropriate for you.

By default, the default configuration will prepare the build system
for installation into the /usr/brlcad directory (the --prefix option
may be used to change that).  This tradition goes back a couple
decades and is a convenient means to isolate the BRL-CAD solid
modeling system from your system, resolves conflicts, facilitates
uninstalls, and simplifies upgrades.  The default configuration is
performed by running the `configure' script:

  ./configure

By default, an unoptimized debug build of BRL-CAD will be configured
for compilation.  To obtain an optimized build (for example, for
BRL-CAD Benchmark performance evaluation), use the --enable-optimized
configure option:

  ./configure --enable-optimized

By default, all components and functionality will be built except
jove.  However, BRL-CAD does require and include several 3rd party
components.  If your system does not include a sufficient version of
those required 3rd party components, they will be automatically
configured for compilation.  You can force any one of those components
on or off via --enable-FEATURE and --disable-FEATURE arguments to
configure:

  ./configure --enable-termlib --disable-png

See the CONFIGURATION OPTIONS below for more details on all of the
possible settings.

Once configured, you should be able to succesfully build BRL-CAD via
make:

  make

See the COMPILATION OPTIONS section in this document for more details
on compile-time options including options for parallel build support.


Testing the Compilation:

Once the compilation is complete, you can test it before and after
installation.  To test a compilation of BRL-CAD before installation,
you can run the BRL-CAD benchmark.  The benchmark will report if the
results are correct, testing a majority of the core functionality of
BRL-CAD in addition to testing your system's performance:

  make benchmark

See the TESTING FUNCTIONALITY section of this document for more
details on how to ensure that the build completed successfully and
additional tests that may be run.


Installing the Compilation:

After the build successfully completes and assuming the benchmark also
produces correct results, installation may begin.  Like any package,
you must have sufficient filesystem permissions to install.  To
install into a system location, you can generally either become a
super user via the su or sudo commands:

  sudo make install

See the INSTALLATION OPTIONS section of this document for more details
on BRL-CAD installation options and post-install environment
preparations.


CONFIGURATION OPTIONS
---------------------

Variables can be set in the environment passed to `configure'.
However, the build may run configure again during the build, and the
customized values of these variables may be lost.  In order to avoid
this problem, you should set them in the `configure' command line,
using `VAR=value'.  For example:

     ./configure CC=/usr/ucb/bin/cc

will cause the specified executable program to be used as the C
compiler.

By default, BRL-CAD is configured to build the entire package and will
install completely isolated into the /usr/brlcad directory.
Configuration will prepare the build for an unoptimized compilation by
default and will attempt to utilize required system libraries if they
are available, otherwise compiling the required library dependencies
as needed.  Run `./configure --help' for a list of all of the possible
configuration options.  See the ENABLE OPTIONS and WITH OPTIONS lists
below for the arguments presently available to configure in more
descriptive detail.

ENABLE OPTIONS:

The below --enable-* options can be used to enable or disable aspects
of compilation that relate to what and how BRL-CAD will be compiled.
Using --disable-* is the same as --enable-*=no and either can be used
interchangably.  As BRL-CAD is a large bazaar of functionality, there
are a lot of options and configurations possible.  See the section
labeled WITH OPTIONS below for a list of options that enable/disable
optional system functionality.

--enable-almost-everything enables compilation of all 3rd party
sources that are provided within a BRL-CAD source distribution.  If
used, this option effectively turns on all of the below documented
--enable-*-build options.  Default is "auto", 3rd party sources are
compiled only if they are not detected as being available and
functioning as expected.  Aliases:
	--enable-all
	--enable-all-build
	--enable-build-all
	--enable-all-builds
	--enable-everything
	--enable-everything-build
	--enable-build-everything

--enable-only-benchmark prepares the build system to only compile and
install the minimal set of libraries and binaries needed to run the
BRL-CAD Benchmark suite.  Default is "no".  Aliases:
	--enable-only-bench
	--enable-only-benchmarks
	--enable-bench-only
	--enable-benchmark-only
	--enable-benchmarks-only

--enable-only-rtserver prepares the build system to only compile and
install the minimal set of libraries needed for the Java-interfacing
"rtserver" interface (used by ARL for analysis purposes).  Default is
"no".  Aliases:
	--enable-only-rts
	--enable-only-librtserver
	--enable-rts-only
	--enable-rtserver-only
	--enable-librtserver-only

--enable-runtime-debug enables support for application and library
debugging facilities.  Disabling the run-time debugging facilities can
provide a significant (10%-30%) performance boost at the expense of
extensive error checking (that in turn help prevent corruption of your
data).  Default is "yes", and should only be disabled for read-only
render work where performance is critical.  Aliases:
	--enable-run-time-debug
	--enable-runtime-debugging
	--enable-run-time-debugging

--enable-strict-build causes all compilation warnings to be treated as
errors for certain portions of code that has undergone a more thorough
review.  This behavior of this flag is heavily influenced by
compilation settings (such as --enable-warnings) including
optimization flags (such as --enable-optimized).  Default is "yes".
Aliases:
        --enable-strict
        --enable-strict-compile
        --enable-strict-compile-flags

--enable-64bit-build attempts to force compilation to produce 64-bit
binaries and libraries.  Note that it merely *ATTEMPTS* to force
64-bit compilation but in all practicality and likelihood, you will
need to manually specify CFLAGS/CPPFLAGS/CXXFLAGS/LDFLAGS to specify
64-bit compilation.  Default is "auto", where the default compilation
mode as set by the compiler will be utilized.  Aliases:
	--enable-64bit
	--enable-64
	--enable-64-build
	--enable-64-bit
	--enable-64-bit-build

--enable-regex-build turns on compilation of the regular expression
library that is provided in a BRL-CAD source distribution.  Default is
"auto", meaning that libregex will be compiled and installed only if a
suitable system regex library is not found.  Aliases:
	--enable-regex
	--enable-libregex
	--enable-libregex-build

--enable-png-build turns on compilation of the Portable Network
Graphics library that is provided in a BRL-CAD source distribution.
Default is "auto", meaning that libpng will be compiled and installed
only if a suitable system PNG library is not found.  Aliases:
	--enable-png
	--enable-libpng
	--enable-libpng-build

--enable-zlib-build turns on compilation of the zlib library that is
provided in a BRL-CAD source distribution.  Default is "auto", meaning
that libz will be compiled and installed only if a suitable system
zlib is not found.  Aliases:
	--enable-zlib
	--enable-libz
	--enable-libz-build

--enable-urt-build turns on compilation of the Utah Raster Toolkit
that is provided in a BRL-CAD source distribution.  Default is "auto",
meaning that libutahrle will be compiled and installed only if a
suitable system rle library is not found.  Aliases:
	--enable-urt
	--enable-urtoolkit
	--enable-urtoolkit-build
	--enable-utahrle
	--enable-utahrle-build
	--enable-libutahrle
	--enable-libutahrle-build
	--enable-utah-raster-toolkit
	--enable-utah-raster-toolkit-build

--enable-opennurbs-build turns on compilation of the openNURBS library
that is provided in a BRL-CAD source distribution.  Default is "auto",
meaning that libopenNURBS will be compiled and installed only if a
suitable system openNURBS library is not found.  Aliases:
	--enable-opennurbs
	--enable-libopennurbs
	--enable-libopennurbs-build
	--enable-open-nurbs
	--enable-open-nurbs-build

--enable-termlib-build turns on compilation of the termlib library
that is provided in a BRL-CAD source distribution.  Default is "auto",
meaning that libtermlib will be compiled and installed only if a
suitable system termcap or termlib library is not found.  Aliases:
	--enable-termlib
	--enable-termcap
	--enable-termcap-build
	--enable-libtermlib
	--enable-libtermlib-build
	--enable-libtermcap
	--enable-libtermcap-build

--enable-tcl-build turns on compilation of the Tcl library that is
provided in a BRL-CAD source distribution.  Default is "auto", meaning
that libtcl will be compiled and installed only if a suitable system
Tcl library is not found.  Aliases:
	--enable-tcl
	--enable-libtcl
	--enable-libtcl-build

--enable-tk-build turns on compilation of the Tk library that is
provided in a BRL-CAD source distribution.  Default is "auto", meaning
that libtk will be compiled and installed only if a suitable system Tk
library is not found.  Aliases:
	--enable-tk
	--enable-libtk
	--enable-libtk-build

--enable-itcl-build turns on compilation of the Incr Tcl/Tk library
that is provided in a BRL-CAD source distribution.  Default is "auto",
meaning that libitcl and libitk will be compiled and installed only if
a suitable system library (for either) is not found.  Aliases:
	--enable-itcl
	--enable-itk
	--enable-itk-build
	--enable-libitcl
	--enable-libitcl-build
	--enable-libitk
	--enable-libitk-build
	--enable-incrtcl
	--enable-incrtcl-build

--enable-iwidgets-install turns on installation of the Iwidgets
library that is provided in a BRL-CAD source distribution.  Default is
"auto", meaning that the iwidgets tcl scripts will be installed only
if a suitable system Iwidgets functionality is not found.  Aliases:
	--enable-iwidgets
	--enable-iwidgets-build

--enable-blt-build turns on compilation of the Blt library that is
provided in a BRL-CAD source distribution.  Default is "auto", meaning
that libblt will be compiled and installed only if a suitable system
Blt library is not found.  Aliases:
	--enable-blt
	--enable-libblt
	--enable-libblt-build

--enable-tkhtml3-build turns on compilation of the tkhtml3 library that is
provided in a BRL-CAD source distribution.  Default is "yes".
Aliases:
	--enable-tkhtml3

--enable-tkimg-build turns on compilation of the tkimg library that is
provided in a BRL-CAD source distribution.  Default is "auto", meaning
that libtkimg will be compiled and installed only if a suitable system
tkimg library is not found.  Aliases:
	--enable-tkimg
	--enable-libtkimg
	--enable-libtkimg-build

--enable-tnt-install turns on installation of the Template Numerical
Toolkit that is provided in a BRL-CAD source distribution.  Default is
"auto", meaning that the TNT headers will be installed only if
suitable system TNT functionality is not found.  Aliases:
	--enable-tnt
	--enable-tnt-build
	--enable-template-numerical-toolkit
	--enable-template-numerical-toolkit-build
	--enable-template-numerical-toolkit-install

--enable-jove-build turns on compilation of Jonathan's Own Version of
Emacs (jove), a lightweight text editor with functionality similar to
Emacs but with different key bindings that is included in a BRL-CAD
source distribution.  Default is "auto", meaning that jove will be
compiled and installed only if suitable system editor functionality is
not found.  Aliases:
	--enable-jove

--enable-ef-build turns on compilation of the Endgame Framework module
used to provide BRL-CAD geometry import support to the Endgame
Framework application development environment.  Default is "no".
Aliases:
	--enable-ef
	--enable-endgameframework
	--enable-endgameframework-build
	--enable-endgame-framework
	--enable-endgame-framework-build

--enable-ug-build turns on compilation of the Unigraphics (NX)
importer used to provide conversion support from Unigraphics format to
a tessellated BRL-CAD geometry format.  Default is "no".  Aliases:
	--enable-unigraphics
	--enable-ug
	--enable-ug-build
	--enable-nx
	--enable-nx-build

--enable-models-install turns on installation of provided example
geometry models.  Default is "yes".  Aliases:
	--enable-models
	--enable-models-build
	--enable-geometry
	--enable-geometry-build
	--enable-geometry-install

--enable-optimized turns on optimized compilation.  Note that
optimized compilation may potentially change the warnings produced by
the compiler.  You may also need to specify --disable-strict or
--disable-warnings to avoid halting on compilation warnings.  Default
is "no".  Aliases:
	--enable-opt
	--enable-optimize
	--enable-optimization
	--enable-optimizations

--enable-debug turns on debug compilation (debugging symbols).
Default is "yes".  Aliases:
	--enable-debugging

--enable-profiling turns on profile compilation.  Default is "no".
Aliases:
	--enable-profile
	--enable-profiled

--enable-parallel turns on support for SMP architectures.  Default is "yes".
Aliases:
	--enable-parallel-build
	--enable-smp
	--enable-smp-build

--enable-dtrace turns on Sun dtrace support.  Default is "no".
Aliases:
	None

--enable-verbose turns on verbose compilation output effectively
implying --enable-warnings and --enable-progress as described below.
Default is "no".  Aliases:
	--enable-verbosity
	--enable-output-verbose
	--enable-verbose-output
	--enable-build-verbose
	--enable-verbose-build

--enable-warnings turns on verbose compilation warnings, causing
additional compilation flags to be given to the compiler in order to
provoke additional compilation warnings.  Default is "no".  Aliases:
	--enable-warning
	--enable-verbose-warnings
	--enable-warnings-verbose
	--enable-build-warnings
	--enable-warnings-build

--enable-progress turns on verbose compilation progress status,
showing unquelled libtool compilation steps.  Default is "no".
Aliases:
	--enable-verbose-progress
	--enable-progress-verbose
	--enable-build-progress
	--enable-progress-build

WITH OPTIONS:

The below --with-* options enable/disable/locate OPTIONAL SYSTEM
FUNCTIONALITY that should be compiled against.  Contrary to the
--enable-* options, none of the --with-* options are required to
obtain a fully functional BRL-CAD install.  Using --without-* is the
same as --with-*=no and either can be used interchangably (though be
careful of options that expect a PATH instead of "no").  See the
section labeled ENABLE OPTIONS above for a list of options that
enable/disable all other aspects of BRL-CAD compilation.

--with-jdk[=PATH] turns on compilation of code that requires the Java
Development Kit.  The specified PATH should be provided.  Default is
"auto" meaning that if suitable Java functionality is detected, then
code that uses Java will be compiled (librtserver).  Aliases:
	--with-java

--with-proe is in flux with --enable-proe-build.  Consult the help for
current information.

--with-x11[=PATH] informs configure where X11 headers/libraries may be
located.  Default is "auto" meaning that standard/common paths will be
searched for X11 functionality.  Aliases:
	--with-x

--with-ogl informs configure that the OpenGL framebuffer and
display manager interfaces should be compiled (and hence they should
link against a system OpenGL library).  This option has absolutely
nothing to do with shaded displays of geometry in MGED.  Default is
"auto" meaning the interfaces will be automatically compiled if
suitable OpenGL headers and libraries are found.  Aliases:
	--with-opengl

--with-wgl informs configure that it should attempt to compile the
Windows GL framebuffer and display manager interfaces.  This option is
hard-enabled in the MSVC build files for BRL-CAD.  Default is "auto"
for configure meaning that the wgl interfaces will be compiled if the
Windows opengl32 dll is found.  Aliases:
	--with-windowsgl


COMPILATION OPTIONS
-------------------

If you are on a multiprocessor machine, you can compile in parallel
depending on the version of `make' being used.  For the GNU and BSD
make, you can use the -j argument.  For example, to use 4 CPUs:

  make -j4

With the IRIX compiler, the -P option enables parallel build mode and
the PARALLEL environment variable sets the number of CPUs (default is
two):

  PARALLEL=4 make -P

If you would like to pass custom compiler or linker options, there are
several ways this may be achieved both during 'configure' and/or
during 'make'.  These flags include CFLAGS, CPPFLAGS, LDFLAGS, and
LIBS.  Configure supports these as either variables or as --with
options:

./configure CFLAGS="-O3" LDFLAGS="-pthread"
./configure --with-cppflags="-I/opt/include" --with-libs="-lz"

GNU and BSD make support the same flags as overrides of the default
provided flags as well:

make CFLAGS="-O0 -g -pg" LDFLAGS="-L/opt/malloc" LIBS="-lmalloc"


INSTALLATION OPTIONS
--------------------

By default, `make install' will install BRL-CAD's files into
`/usr/brlcad/bin', `/usr/brlcad/man', etc.  You can specify an
installation prefix other than `/usr/brlcad' by giving `configure' the
option `--prefix=PATH'.


Setting Up the Path:

Once installed, you will need to add /usr/brlcad/bin to your system
PATH.  For Bourne shell users, you can run the following:

  PATH=/usr/brlcad/bin:$PATH ; export PATH

For C shell users, this should do the same thing:

  set path=( /usr/brlcad/bin $path ) ; rehash

If you would like to provide BRL-CAD to multiple users, your shell
environment scripts should be edited so that /usr/brlcad/bin is added
to the system path.  This usually entails editing /etc/profile,
/etc/csh.login, /etc/bashrc, and possibly other files depending on
your platform.


Setting Up the Manual Pages Path:

It may be useful to add /usr/brlcad/man to your MANPATH in the same
manner as shown above for PATH.  Conversely, you can use the `brlman'
command that is already preconfigured to locate the BRL-CAD manpages.


Configuring permissions uniformly with group read/write access:

find /usr/brlcad -type d -exec chmod ug+rwx {} \; -exec chmod o+rx {} \; -o -type f -exec chmod ug+rw {} \; -exec chmod o+r {} \;

The above 'find' line will set up permissions across a /usr/brlcad
rooted installation such that 'user' and 'group' will have read-write
access and 'other' will have read access consistently across all
files.  This is a common configuration used by BRL-CAD developers that
allows shared management of installations amongst developers while
having all users maintain read-only access.



TESTING FUNCTIONALITY
---------------------

Testing a Compilation:

After BRL-CAD is compiled, you can test the build via:

  make test

This will run a series of tests on the compiled sources to make sure
that they behave as they should.  If those tests succeed, another
useful test is to ensure that the geometric library computations are
correct by running the BRL-CAD Benchmark:

  make benchmark

The benchmark will run for several minutes computing frames of
well-known ray-trace images, and comparing the validity of the results
as well as overall performance metrics.  The benchmark should report
CORRECT after each section of output and a overal VGR metric of
performance.


Testing an Installation:

After BRL-CAD is installed, simply running `rt' and/or `mged' are good
tests of basic functionality.  Running `rt' without any options should
display version information and a usage message.  Running `mged'
without any options will start the GUI-based solid modeler
application.  Running "benchmark" should invoke the BRL-CAD Benchmark
and test the performance of the binaries as installed on a given
system.


POST-INSTALLATION
-----------------


REPORTING PROBLEMS
------------------

Please report any bugs encountered to the project bug tracker at
http://sourceforge.net/tracker/?group_id=105292&atid=640802

Similarly, please post any request for feature enhancements or support
to http://sourceforge.net/tracker/?group_id=105292&atid=640805 and
http://sourceforge.net/tracker/?group_id=105292&atid=640803
respectively.


---
$Revision: 38766 $
