head	14.16;
access;
symbols
	rel-7-10-4:14.15
	STABLE:14.15.0.2
	stable-branch:14.4
	rel-7-10-2:14.15
	rel-7-10-0:14.14
	rel-7-8-4:14.13
	rel-7-8-2:14.9
	rel-7-8-0:14.9
	trimnurbs-branch:14.9.0.2
	help:14.9
	temp_tag:14.9
	bobWinPort-20051223-freeze:14.8
	postmerge-20051223-bobWinPort:14.9
	premerge-20051223-bobWinPort:14.9
	rel-7-6-6:14.9
	rel-7-6-4:14.9
	rel-7-6-2:14.8
	rel-7-6-branch:14.8.0.6
	rel-7-6-0:14.8
	rel-7-4-2:14.8
	rel-7-4-branch:14.8.0.4
	bobWinPort:14.8.0.2
	rel-7-4-0:14.8
	rel-7-2-6:14.6
	rel-7-2-4:14.4
	rel-7-2-2:14.3
	rel-7-2-0:14.2
	rel-7-0-4:14.1
	rel-7-0-2:14.1
	rel-7-0-1:14.1
	opensource-post:14.1
	opensource-pre:11.8
	rel-7-0-branch:11.8.0.2
	rel-7-0:11.8
	ansi-20040405-merged:11.5
	premerge-autoconf:11.5
	ansi-20040316-freeze:11.5
	postmerge-20040315-windows:11.5
	premerge-20040315-windows:11.5
	windows-20040315-freeze:11.5
	autoconf-20031203:11.5
	autoconf-20031202:11.5
	phong-branch:11.5.0.10
	photonmap-branch:11.5.0.8
	rel-6-1-DP:11.5
	windows-branch:11.5.0.6
	rel-6-0-2:11.5
	ansi-branch:11.5.0.4
	rel-6-0-1-branch:11.5.0.2
	hartley-6-0-post:11.5
	hartley-6-0-pre:11.5
	rel-6-0-1:11.5
	rel-6-0:11.5
	AUTOCONF:11.5.0.12;
locks; strict;
comment	@# @;


14.16
date	2007.11.29.22.22.40;	author brlcad;	state Exp;
branches;
next	14.15;

14.15
date	2007.05.31.02.30.16;	author brlcad;	state Exp;
branches;
next	14.14;

14.14
date	2007.01.27.01.07.30;	author brlcad;	state Exp;
branches;
next	14.13;

14.13
date	2006.08.26.17.54.16;	author brlcad;	state Exp;
branches;
next	14.12;

14.12
date	2006.07.29.21.56.22;	author brlcad;	state Exp;
branches;
next	14.11;

14.11
date	2006.07.29.21.49.18;	author lbutler;	state Exp;
branches;
next	14.10;

14.10
date	2006.06.24.02.23.47;	author brlcad;	state Exp;
branches;
next	14.9;

14.9
date	2005.10.23.04.44.25;	author brlcad;	state Exp;
branches;
next	14.8;

14.8
date	2005.07.10.21.53.42;	author brlcad;	state Exp;
branches
	14.8.6.1;
next	14.7;

14.7
date	2005.07.10.05.54.37;	author twingy;	state Exp;
branches;
next	14.6;

14.6
date	2005.05.28.02.20.53;	author brlcad;	state Exp;
branches;
next	14.5;

14.5
date	2005.05.22.23.19.45;	author brlcad;	state Exp;
branches;
next	14.4;

14.4
date	2005.04.12.23.29.54;	author brlcad;	state Exp;
branches;
next	14.3;

14.3
date	2005.03.13.18.27.02;	author brlcad;	state Exp;
branches;
next	14.2;

14.2
date	2005.02.13.20.59.10;	author lbutler;	state Exp;
branches;
next	14.1;

14.1
date	2004.11.16.19.42.08;	author morrison;	state Exp;
branches;
next	11.8;

11.8
date	2004.10.16.00.18.26;	author butler;	state Exp;
branches;
next	11.7;

11.7
date	2004.05.17.20.24.22;	author morrison;	state Exp;
branches;
next	11.6;

11.6
date	2004.03.18.18.15.13;	author erikg;	state dead;
branches;
next	11.5;

11.5
date	2002.03.22.19.07.35;	author morrison;	state Exp;
branches
	11.5.12.1;
next	11.4;

11.4
date	2002.03.22.18.54.12;	author morrison;	state Exp;
branches;
next	11.3;

11.3
date	2002.03.22.18.26.36;	author morrison;	state Exp;
branches;
next	11.2;

11.2
date	2002.03.22.16.24.33;	author kermit;	state Exp;
branches;
next	11.1;

11.1
date	2002.03.21.15.34.25;	author butler;	state Exp;
branches;
next	;

11.5.12.1
date	2004.03.15.12.19.49;	author erikg;	state dead;
branches;
next	;

14.8.6.1
date	2005.11.13.13.46.08;	author brlcad;	state Exp;
branches;
next	;


desc
@@


14.16
log
@sync options with configure: add dtrace, remove automatic
@
text
@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


TABLE OF CONTENTS
-----------------
  Introduction
  Table of Contents
  Quick Installation
  Installing from Binary
  Installing from Source
  Configuration Options
  Compilation Options
  Testing Functionality
  Installation Options
  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 relocateable 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 CVS checkout/export, or
  2) from a source distribution tarball

Using the latest CVS 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 CVS Checkout/Export:

If you have obtained the BRL-CAD sources from the CVS 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.  Alises:
	--enable-run-time-debug
	--enable-runtime-debugging
	--enable-run-time-debugging

--enable-64bit-build attempts to force compilation to produce 64-bit
binaries and libraries.  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-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-adrt-build turns on compilation of the Advanced Distributed
Ray-Tracer (ADRT), a high-performance triangle ray-tracer.  Default is
"auto", depending on whether SDL and Python are detected during
configuration.  Aliases:
	--enable-adrt

--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.  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-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

--with-sdl informs configure that it should run sdl-config to locate
SDL functionality.  SDL IS ONLY USED BY ADRT (see above).  Default is
"auto", and if Python is also found then compilation of ADRT can be
enabled.  Aliases:
	--with-libsdl

--with-python informs configure that it should run python to locate
Python functionality.  PYTHON IS ONLY USED BY ADRT (see above).
Default is "auto", and if SDL is also found then compilation of ADRT
can be enabled.  Aliases:
	--with-libpython


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.


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
applicaation.  Running "benchmark" should invoke the BRL-CAD Benchmark
and test the performance of the binaries as installed on a given
system.


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: 14.15 $
@


14.15
log
@kaboom! .. document all of the configure options we provide (both the --enable and --with options), including what they mean and do in detail.  includes all of the various available aliases too that are available.
@
text
@a278 7
--enable-automatic-flags tells configure whether it is allowed to
automatically modify compilation flags (e.g. extra optimization flags
and other CFLAGS).  Default is "yes".  Aliases:
	--enable-auto-flags
	--enable-auto-flag
	--enable-automatic-flag

d365 12
a429 12
--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

d497 4
d691 1
a691 1
$Revision: 14.14 $
@


14.14
log
@ws, last test..looking good ;)
@
text
@a233 8
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.

d245 337
d694 1
a694 1
$Revision: 14.13 $
@


14.13
log
@more detailed testing section, with details on testing functionality before and after installation.  also, make the quick instructions be an optimized build.  give examples on how to provide custom flags during configure and make too.
@
text
@d318 1
a318 1
TESTING FUNCTIONALITY 
d365 1
a365 1
$Revision: 14.12 $
@


14.12
log
@revert -- I doubt these changes support the intel mac parallel code.. careful not to commit INSTALL as it is often automatically overwritten by automake
@
text
@d28 1
a30 1
  Testing an Install
d43 2
a44 2
and install BRL-CAD quickly into the /usr/brlcad directory.  If you
have a configure script, run the following:
d46 1
a46 1
  ./configure
d49 1
a50 1
  make test
d58 3
a60 2
See the reporting problems section of this document to report the
problem.
d124 9
a132 4
There are a couple means to obtain the BRL-CAD sources, via either a
CVS checkout/export or a source distribution tarball.  Using the
latest CVS sources is recommended where possible, since it will have
the latest changes.
d159 1
a159 1
use.  See the Configuration Options section below for details on how
d174 1
a174 1
BRL-CAD Benchmark performance testing), use the --enable-optimized
d189 1
a189 1
See the Configuration Options below for more details on all of the
d197 1
a197 1
See the Compilation Options section in this document for more details
d201 1
a201 1
Testing a Compilation:
d211 3
a213 2
See the Testing An Install section of this document for more details
on testing your BRL-CAD distribution.
d216 1
a216 1
Installing a Compilation:
d226 1
a226 1
See the Installation Options section of this document for more details
d269 14
d314 2
a315 3
manner as shown above for PATH.  Conversely, you could use the
`brlman' command that is already preconfigured to locate the BRL-CAD
manpages.
d318 4
a321 2
TESTING AN INSTALL
------------------
d323 1
a323 1
After BRL-CAD is installed, you can test the installation via:
d327 23
a349 6
This will run a series of tests on the installed sources to make sure
that they behave as they should.  Similarly, 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 applicaation.
d365 1
a365 1
$Revision: 14.10 $
@


14.11
log
@changes to support Intel Mac parallel code
@
text
@d1 2
a2 2
Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
Foundation, Inc.
d4 1
a4 2
   This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
d6 3
a8 2
Basic Installation
==================
d10 259
a268 95
   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').

   It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring.  (Caching is
disabled by default to prevent problems with accidental use of stale
cache files.)

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.

   The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'.  You only need
`configure.ac' if you want to change it or regenerate `configure' using
a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  Run `./configure --help'
for details on some of the pertinent environment variables.

   You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment.  Here
is an example:

     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix

   *Note Defining Variables::, for more details.

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not support the `VPATH'
variable, you have to compile the package for one architecture at a
time in the source code directory.  After you have installed the
package for one architecture, use `make distclean' before reconfiguring
for another architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
a270 119
   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' cannot figure out
automatically, but needs to determine by the type of machine the package
will run on.  Usually, assuming the package is built to be run on the
_same_ architectures, `configure' can figure that out, but if it prints
a message saying it cannot guess the machine type, give it the
`--build=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS KERNEL-OS

   See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.

   If you are _building_ compiler tools for cross-compiling, you should
use the `--target=TYPE' option to select the type of system they will
produce code for.

   If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

   Variables not defined in a site shell script can be set in the
environment passed to `configure'.  However, some packages 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/local2/bin/gcc

will cause the specified gcc to be used as the C compiler (unless it is
overridden in the site shell script).

`configure' Invocation
======================

   `configure' recognizes the following options to control how it
operates.

`--help'
`-h'
     Print a summary of the options to `configure', and exit.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.
d272 52
a323 2
`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.
d325 2
@


14.10
log
@too many impatient folks don't actually read the Installing from Binary section and try to run configure/autogen.sh on a binary distribution so try to make it more clear up-front in the Quick Installation section, and move the binary instructions up higher in the file.
@
text
@d1 2
a2 2
The Installation Guide to BRL-CAD
=================================
d4 2
a5 1
Please read this document if you are interested in installing BRL-CAD.
d7 2
a8 3
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.
d10 95
a104 259
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


TABLE OF CONTENTS
-----------------
  Introduction
  Table of Contents
  Quick Installation
  Installing from Binary
  Installing from Source
  Configuration Options
  Compilation Options
  Installation Options
  Post-Installation
  Testing an Install
  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 BRL-CAD quickly into the /usr/brlcad directory.  If you
have a configure script, run the following:

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

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.

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 relocateable 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, via either a
CVS checkout/export or a source distribution tarball.  Using the
latest CVS sources is recommended where possible, since it will have
the latest changes.


Starting From a CVS Checkout/Export:

If you have obtained the BRL-CAD sources from the CVS 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 testing), 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 a 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 An Install section of this document for more details
on testing your BRL-CAD distribution.


Installing a 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
---------------------

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.

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.


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


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
d107 119
d227 2
a228 52
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 could use the
`brlman' command that is already preconfigured to locate the BRL-CAD
manpages.


TESTING AN INSTALL
------------------

After BRL-CAD is installed, you can test the installation via:

  make test

This will run a series of tests on the installed sources to make sure
that they behave as they should.  Similarly, 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 applicaation.


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.

a229 2
---
$Revision: 14.9 $
@


14.9
log
@trailing ws
@
text
@d24 1
a25 1
  Installing from Binary
d37 5
d75 45
a223 45
INSTALLING FROM BINARY
----------------------

There are a variety of different kinds of BRL-CAD binary
distributions.  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, 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 relocateable 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.


d326 1
a326 1
$Revision: 14.8 $
@


14.8
log
@revert the mistaken commit of the generic install instructions
@
text
@d29 1
a29 1
  Post-Installation 
d321 1
a321 1
$Revision: 14.6 $
@


14.8.6.1
log
@merge changes from HEAD aka rel-7-6-4 to the rel-7-6-branch just in case someone peeks a gander or tries to continue/build the branch
@
text
@d29 1
a29 1
  Post-Installation
d321 1
a321 1
$Revision$
@


14.7
log
@IGVT->IVAT 100%
@
text
@d1 2
a2 2
Installation Instructions
*************************
d4 1
a4 2
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005 Free
Software Foundation, Inc.
d6 3
a8 2
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
d10 4
a13 223
Basic Installation
==================

These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').

   It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring.  (Caching is
disabled by default to prevent problems with accidental use of stale
cache files.)

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.

   The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'.  You only need
`configure.ac' if you want to change it or regenerate `configure' using
a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

Some systems require unusual options for compilation or linking that the
`configure' script does not know about.  Run `./configure --help' for
details on some of the pertinent environment variables.

   You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment.  Here
is an example:

     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix

   *Note Defining Variables::, for more details.

Compiling For Multiple Architectures
====================================

You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not support the `VPATH'
variable, you have to compile the package for one architecture at a
time in the source code directory.  After you have installed the
package for one architecture, use `make distclean' before reconfiguring
for another architecture.

Installation Names
==================

By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PREFIX'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PREFIX', the package will
use PREFIX as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=DIR' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS KERNEL-OS

   See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.

   If you are _building_ compiler tools for cross-compiling, you should
use the `--target=TYPE' option to select the type of system they will
produce code for.

   If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

Variables not defined in a site shell script can be set in the
environment passed to `configure'.  However, some packages 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/local2/bin/gcc

causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script).  Here is a another example:

     /bin/bash ./configure CONFIG_SHELL=/bin/bash

Here the `CONFIG_SHELL=/bin/bash' operand causes subsequent
configuration-related scripts to be executed by `/bin/bash'.

`configure' Invocation
======================

`configure' recognizes the following options to control how it operates.

`--help'
`-h'
     Print a summary of the options to `configure', and exit.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.
d15 2
a16 2
`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.
d18 304
@


14.6
log
@minor rewording on trackers
@
text
@d1 2
a2 2
The Installation Guide to BRL-CAD
=================================
d4 2
a5 1
Please read this document if you are interested in installing BRL-CAD.
d7 2
a8 3
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.
d10 223
a232 4
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:
d234 2
a235 2
  doc/README.MacOSX	-- Apple Mac OS X
  doc/README.IRIX	-- SGI IRIX and IRIX64
a236 304

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


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

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

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

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.

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 SOURCE
----------------------

There are a couple means to obtain the BRL-CAD sources, via either a
CVS checkout/export or a source distribution tarball.  Using the
latest CVS sources is recommended where possible, since it will have
the latest changes.


Starting From a CVS Checkout/Export:

If you have obtained the BRL-CAD sources from the CVS 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 testing), 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 a 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 An Install section of this document for more details
on testing your BRL-CAD distribution.


Installing a 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.


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

There are a variety of different kinds of BRL-CAD binary
distributions.  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, 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 relocateable 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.


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

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.

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.


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


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 could use the
`brlman' command that is already preconfigured to locate the BRL-CAD
manpages.


TESTING AN INSTALL
------------------

After BRL-CAD is installed, you can test the installation via:

  make test

This will run a series of tests on the installed sources to make sure
that they behave as they should.  Similarly, 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 applicaation.


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: 14.5 $
@


14.5
log
@replace the generic installation/configuration instructions with an initial full-blown overview of the compilation/installation process and available options.  still needs to overview the various --enable/--with options, but it's way better that the previous generic instructions
@
text
@d303 3
a305 2
without any options should display a usage message.  Running `mged'
without any options will start the solid modeler GUI.
d315 2
a316 2
request to http://sourceforge.net/tracker/?group_id=105292&atid=640805
and http://sourceforge.net/tracker/?group_id=105292&atid=640803
d321 1
a321 1
$Revision: 14.3 $
@


14.4
log
@separate out the irix notes into it's own readme in the doc directory.  refer readers to the doc/README.* files in INSTALL
@
text
@d1 2
a2 2
Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
Foundation, Inc.
d4 1
a4 2
   This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
d6 3
a8 2
Basic Installation
==================
d10 254
a263 95
   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').

   It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring.  (Caching is
disabled by default to prevent problems with accidental use of stale
cache files.)

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.

   The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'.  You only need
`configure.ac' if you want to change it or regenerate `configure' using
a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  Run `./configure --help'
for details on some of the pertinent environment variables.

   You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment.  Here
is an example:

     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix

   *Note Defining Variables::, for more details.

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not support the `VPATH'
variable, you have to compile the package for one architecture at a
time in the source code directory.  After you have installed the
package for one architecture, use `make distclean' before reconfiguring
for another architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
a265 119
   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' cannot figure out
automatically, but needs to determine by the type of machine the package
will run on.  Usually, assuming the package is built to be run on the
_same_ architectures, `configure' can figure that out, but if it prints
a message saying it cannot guess the machine type, give it the
`--build=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS KERNEL-OS

   See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.

   If you are _building_ compiler tools for cross-compiling, you should
use the `--target=TYPE' option to select the type of system they will
produce code for.

   If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

   Variables not defined in a site shell script can be set in the
environment passed to `configure'.  However, some packages 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/local2/bin/gcc

will cause the specified gcc to be used as the C compiler (unless it is
overridden in the site shell script).

`configure' Invocation
======================

   `configure' recognizes the following options to control how it
operates.

`--help'
`-h'
     Print a summary of the options to `configure', and exit.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.
d267 45
a311 2
`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.
d313 4
a316 2
Please refer to the doc/README.* documents for platform-specific
compilation options, installation details, and other notes.
a317 2
	doc/README.IRIX
	doc/README.MacOSX
@


14.3
log
@add an rcs revision number for change tracking
@
text
@d230 2
d233 2
a234 21


IRIX Note:
        Note by setting the compiler flags, configure seems to skip the check 
	for maximum shell command line length is skipped.  Be careful not to 
	place the source in adirectory too deep.  The libtool script wrapper 
	which runs bwish builds a command line that is too long for the shell 
	to handle.  So for example, placing the source in:
		/vld3/butler/BRLCAD/mips64_brlcad-7.2.0
	is known to cause a build failure.  On the other hand, the
	following:
		/vld3/butler/BRLCAD/m6_72
	resulted in a successful build.

For IRIX 64bit build:
	export SGI_ABI=-64
	./configure CC=cc CFLAGS=-64 LDFLAGS=-64 --enable-64bit-build

For IRIX 23bit build:
	export SGI_ABI=-n32
	./configure CC=cc 
d237 1
a237 1
$Revision: $
@


14.2
log
@Revised notes on how to build on Irix systems based upon experiences with
over-running the maximum command line length.  If the path is too deep, libtool
will construct a command line for relinking and running btclsh which exceeds
the maximum command line length.  This results in a build failure.
@
text
@d253 2
@


14.1
log
@dawn of a new revision.  it shall be numbered 14 to match release 7.  begin the convergence by adding emacs/vi local variable footer blocks to encourage consistent formatting.
@
text
@d232 15
a246 1
On IRIX
d248 3
a250 1
or
@


11.8
log
@added hint at end of file for correct syntax for building on the ever-troublesome IRIX
@
text
@@


11.7
log
@initial standard autotools INSTALL file so there are instructions post checkout
@
text
@d230 7
@


11.6
log
@merge of AUTOCONF branch in to HEAD
@
text
@d1 2
a2 1
To compile and install the BRLCAD source, perform the following steps:
d4 2
a5 1
	% mkdir /usr/brlcad
d7 2
a8 37
If you choose a directory other than /usr/brlcad, you will need to set the
environment variable BRLCAD_ROOT to be the name of this directory.  Because a
number of paths are compiled into the package, it is not possible to compile
the package for one location, then move it to another.  Be sure that
/usr/brlcad/bin or $BRLCAD_ROOT/bin is in your shell path.  For example:

	sh:
		BRLCAD_ROOT=/foobar/brlcad 
		PATH=$PATH:/foobar/brlcad/bin
		export PATH
	csh:
	 	setenv BRLCAD_ROOT /foobar/brlcad
	 	set path=($path /foobar/brlcad/bin)

Compile:
	% cd /foobar/brlcad
	% sh setup.sh

	The next step can take a considerable amount of time on some systems:
	
	sh:
		make > make.log 2>&1
	csh:
		make >& make.log

Install:
	Review the log of compilation, then run:

		make install

This process should proceed without problems on the following systems:

	RedHat Linux 7.2
	FreeBSD 4.5
	SunOS 5.8 (Solaris)
	Irix 6.5
	Mac OS X (With X11 installed -- INSTALL.pmac for details)
d10 216
a225 3
For binary and source download instructions see:

		http://ftp.arl.army.mil/brlcad
d227 2
@


11.5
log
@removed the mac os x specific stuff and put those details in their own INSTALL.pmac file
@
text
@@


11.5.12.1
log
@autogenerated...
@
text
@@


11.4
log
@added some comments about the MacOSX installation (since make install will fail and Tcl may give problems)
@
text
@d41 1
a41 1
	Mac OS X (With X11 installed -- see notes below)
a46 34

Max OS X Installation Notes:

Being that this is the newest architecture to be added, there are some
issues to keep in mind with the installation when building from source.
First, XFree86 will need to be installed if you want a gui.  The XDarwin
project will include the X11 libraries and headers necessary to properly
build Tk (the only component that presently "requires" X) and may be
found at:

	http://www.xdarwin.org

To build and install, the instructions above will all work with the
exception of the "make install" step.  Run this instead:

	cake install

If the build and install fails for whatever reason (i.e. if after
building and installing, mged doesn't start properly when you type 
'mged"), then the system default Tcl library is most likely getting
in the way.  You can temporarily move it out of the way by doing:

	sudo mv /usr/lib/libtcl.dylib /usr/lib/libtcl.dylib.backup
	sudo mv /usr/lib/libtcl8.3.dylib /usr/lib/libtcl8.3.dylib.backup
	sudo mv /usr/lib/libtclstub8.3.a /usr/lib/libtclstub8.3.a.backup
	sudo mv /System/Library/Tcl /System/Library/Tcl.backup

Then you should be able to do:

	cake clobber
	cake
	cake install

Happy installation!
@


11.3
log
@there are still some systems that give problems with "make install" -- does not install anything.  so for now, it's left as cake and cake install.
@
text
@d20 1
a20 1
	% cd brlcad
d26 1
a26 1
		% cake > cake.log 2>&1
d28 1
a28 1
		% cake >& cake.log
d31 1
a31 1
	Review the log of compilation, then type:
d33 1
a33 1
		% cake install
d41 1
a41 1
	Mac OS X (With X11 server/libraries/headers installed)
d43 38
a80 1
For download instructions see:
a81 1
	 http://ftp.arl.army.mil/brlcad
@


11.2
log
@typo in csh.
@
text
@d26 1
a26 1
		% make > make.log 2>&1
d28 1
a28 1
		% make >& make.log
d33 1
a33 1
		% make install
@


11.1
log
@updated 6.0 installation instructions
@
text
@d17 1
a17 1
	 	set path=($path /foobar/brlcad)
@

