INSTALL

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

This document covers the installing BRL-CAD from either a source or binary
distribution.  Please see REPORTING PROBLEMS to troubleshoot.

Some platforms have additional platform-specific documentation provided in the
doc/ directory with additional information. This presently includes the
following:

  doc/README.BSD        -- FreeBSD, NetBSD, OpenBSD, etc.
  doc/README.Linux	-- Various Linux distributions
  doc/README.MacOSX	-- Apple Mac OS X
  doc/README.Solaris    -- Oracle Solaris, OpenIndiana (Illumos), etc.
  doc/README.VAX        -- Virtual Address eXtension architecture from DEC.
                           One of the original BRL-CAD platforms. These
                           days, re-created using the simh simulator.
  doc/README.Windows    -- Microsoft Windows


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


QUICK SOURCE INSTALL
--------------------

See https://brlcad.org/wiki/Compiling for a platform-specific walk-through
including instructions for building on Windows.

Required tools:
  - Git must be 2.17 or later
  - CMake must be 3.18 or later
  - Compiler must be C++17-compliant
    - If using Visual Studio, version 2019 (16.8+) or later
    - If using GCC/G++, version 7 or later
    - If using LLVM/Clang 5 or later
    - If using Intel, version 19.0.1 or later

Steps to compile, test, and install an optimized BRL-CAD on non-Windows
platforms:

  git clone https://github.com/BRL-CAD/brlcad.git
  mkdir brlcad/build
  cd brlcad/build
  cmake .. -DENABLE_ALL=ON -DCMAKE_BUILD_TYPE=Release
  make -j4
  make check
  sudo make install

Once installed, run bin/mged or bin/archer to launch BRL-CAD's GUI apps.  See
POST-INSTALLATION for instruction adding bin/ folder to your system PATH to
more easily run geometry converters.


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

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


Generic Binary Distributions:

For binary distributions that are simply compressed tarballs of the
installation root, they should contain the entire hierarchy of the
distribution.  To put that hierarchy in its "installed" location, you just
create the directory and move the expanded tarball contents:

gunzip BRL-CAD_X.Y.Z_Linux_ia64.tar.gz
tar -xvf BRL-CAD_X.Y.Z_Linux_ia64.tar
sudo mkdir /usr/brlcad/rel-X.Y.Z
sudo mv BRL-CAD_X.Y.Z_Linux_ia64/* /usr/brlcad/rel-7.X.Y/

Of course, there are other compression options possible including zip and
bzip2.  By default, BRL-CAD expects to be installed into /usr/brlcad/rel-X.Y.Z.
On some platforms the binary may be relocatable, but this is not guaranteed.
It's recommended that you start from a source distribution if you would like to
install into an alternate installation location.  That said, if you do desire
to install and/or run BRL-CAD from a different location, give it a try...on
some platforms it will work.

Something to be aware of, even if a binary distribution IS relocatable: it will
use its local copies of things like libraries only so long as the "final"
installed target directory that the build was compiled for does not contain a
BRL-CAD installation.  Due to the way path logic is set, an installed copy of a
library in the correct location will always be loaded first, regardless of the
presence of a "local" copy.


Mac OS X Disk Mounting Image:

Mount the .dmg and run the Installer .pkg contained therein.  This will install
into /usr/brlcad/rel-X.Y.Z and will only require confirming that your
environment is set up properly (i.e. add /usr/brlcad/rel-X.Y.Z/bin to your
path) as described in the Quick Installation section.


Validating checksums:

The integrity of distributed files can be verified using checksums that are
published with released files.  Files on SourceForge's file release system can
be found by clicking the 'i' button at the end of each file's name.  If you
re-distribute BRL-CAD, checksums should be retained with the files so others
can validate origination.


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

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

  1) from a Git checkout, or
  2) from a source distribution tarball

Using the latest Git sources is recommended where possible since it
will have the latest changes.

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.

BRL-CAD's dependencies are managed in a separate repository, located at
https://github.com/BRL-CAD/bext  By default BRL-CAD's configure process will
download and manage the necessary dependencies, avoiding the need for user
awareness of the bext repository, but there are a number of scenarios where it
is advantageous for developers to adjust how this process works.

The full dependency stack of BRL-CAD, with all optional and experimental
features enabled, is a VERY large and long compile.  Therefore, the bext build
outputs can be built as their own separate, external project to allow for reuse
of the compiled outputs.  Building bext separately means BRL-CAD won't get a
chance to customize what is and is not built, but the trade-off is that outputs
can be built once and reused over and over.  Doing so can significantly shorten
time spent configuring BRL-CAD builds - reusing bext compiled outputs is
recommended for serious developers.

Various useful configurations for working with bext:

* Get a git clone that has everything which might be needed (large,
  but useful for offline building)

git clone --recurse-submodules https://github.com/BRL-CAD/brlcad

* Have prebuilt bext outputs to reuse - BRL-CAD will simply copy and prepare
  the pre-existing files

cmake .. -DBRLCAD_EXT_DIR=/home/user/bext_output

* Already have an existing bext clone but want BRL-CAD to build bext outputs

cmake .. -DBRLCAD_EXT_SOURCE_DIR=/home/user/bext

* Download, build and bundle only what is needed for librt

cmake .. -DBRLCAD_COMPONENTS=librt

* Build and bundle only what is needed, but don't require internet for bext clone
cmake .. -DBRLCAD_EXT_SOURCE_DIR=/home/user/bext -DBRLCAD_COMPONENTS=librt


By default, the build system will prepare a Debug build and install into the
/usr/brlcad/dev-X.Y.Z directory.   The CMAKE_INSTALL_PREFIX option may be used
to change that directory, or a Release build type may be specified to install
to /usr/brlcad/rel-X.Y.Z - more on this below.  The tradition of non-system
installation paths goes back a couple of 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 `cmake'.  It is not required to do the build in a
directory different from your source directory, but it is much cleaner and
*highly* recommended - this guide will illustrate the build process with the
assumption that the BRL-CAD source code is in the directory brlcad-X.Y.Z and
the directory intended to hold the build output is brlcad-build, located in the
same parent directory as brlcad-X.Y.Z:

  .
  ./brlcad-X.Y.Z
  ./brlcad-build

To start the build process, cd into brlcad-build and run CMake,
pointing it to the source directory:

  cd brlcad-build
  cmake ../brlcad-X.Y.Z

As mentioned earlier, CMake uses two "build types", controlled by
the CMAKE_BUILD_TYPE variable, that are useful for specific purposes:

* Debug (-DCMAKE_BUILD_TYPE=Debug) - Debug is the configuration that most
  developers will want to use when working on BRL-CAD.  It will add
  debug flags to the compile, and sets the default install directory to
  be /usr/brlcad/dev-X.Y.Z - in order to run the resulting installed
  binaries, the developer should ensure that the dev-X.Y.Z  path is
  first in his or her PATH environment variable.

* Release (-DCMAKE_BUILD_TYPE=Release) - A release build is intended for
  final consumption by end users and as such has optimizations enabled.
  It also sets the install path to /usr/brlcad/rel-X.Y.Z - best practice
  for release installation is to set up symbolic links in /usr/brlcad to
  point to the most current BRL-CAD release, while allowing older versions
  to remain installed on the system in case they are needed.

In both of these cases any individual variable may be overridden - for
example, setting -DCMAKE_INSTALL_PREFIX=/usr/brlcad in a Debug build will
override the ../brlcad-install default.  Build types are a convenient way
to bundle sets of settings, but they do not prevent overrides if a more
custom setup is needed.

If the autodetection mechanisms fail to produce a working configuration,
the next simplest approach is typically to enable ALL the third party
components - this is typically a well tested configuration, but will
increase both the build time and final install size of BRL-CAD on
the system.  To set this variable on the command line, use -D to
define ENABLE_ALL for CMake:

  -DENABLE_ALL=ON

To obtain an optimized build (for example, for BRL-CAD Benchmark
performance evaluation), enable BRLCAD_FLAGS_OPTIMIZATION:

  -DBRLCAD_FLAGS_OPTIMIZATION=ON

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

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

  make

(On multicore systems, adding the -j flag (e.g. -j6) is recommended)

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 command and run

  make install

or on operating systems set up to use sudo:

  sudo make install


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

The primary build target to validate a compilation of BRL-CAD is:

  make check

That runs a trio of test sets including "benchmark", "regress", and
"unit".  The first set is a performance test that also validates
whether ray tracing behavior is correct:

  make benchmark

The second test set is our regression tests that run a host of
rigorous integration tests and validate essential behavior:

  make regress

The third set runs unit tests that validate low-level behavior in
BRL-CAD's core libraries:

  make unit

Last but not least, one may simply run all available tests, though
note that some tests will intentionally fail:

  make test


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

Permissions:

Something to be aware of with CMake installations is that umask settings
are ignored by current versions of CMake.  It is a common situation in
Unix environments to want "group" members to have read/write access -
to achieve this, after installation the following find command can be
run (of course, substituting the actual BRL-CAD version for X.Y.Z):

find /usr/brlcad/rel-X.Y.Z -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.


System PATH:

Normally, BRL-CAD's install directories are not in system PATH lists and
consequently BRL-CAD's executables will not be invocable without specifying
their full path.  This is normally handled in Unix environments by adding
the desired BRL-CAD installation's binary directory to the user's local path:

On Windows, the PATH system variable can be set using System Utility
in control panel.  Add the bin/ folder in the install directory to PATH.

On Linux/BSD/other systems:
  In the bash shell: export PATH=/usr/brlcad/rel-X.Y.Z:$PATH
  In the csh shell:  setenv PATH /usr/brlcad/rel-X.Y.Z:$PATH


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

Please report any bugs, support requests, or feature requests to:
  https://github.com/BRL-CAD/brlcad/issues



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

--- ENABLE_ALL ---

If set to ON, and the BRL-CAD configure process is managing the bext
dependencies, instructs bext to default to building local copies of the
dependencies it will enable per the BRL-CAD feature settings, rather than
searching for system versions.


--- BRLCAD_ENABLE_OPENGL ---

Enable support for OpenGL based Display Managers in BRL-CAD.
Default depends on whether OpenGL is successfully detected -
if it is, default is to enable.

Aliases:  ENABLE_OPENGL


--- BRLCAD_COMPONENTS ---

Semicolon separated list of components to enable for building - see
src/source_dirs.cmake for a list of the components that may be specified.


--- BRLCAD_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 "ON", and should only be disabled for read-only render
work where performance is critical.

Aliases:  ENABLE_RUNTIME_DEBUG, ENABLE_RUN_TIME_DEBUG, ENABLE_RUNTIME_DEBUGGING
          ENABLE_RUN_TIME_DEBUGGING


--- BRLCAD_EXT_DIR ---

If specified, BRL-CAD will look in this directory for bext compiled outputs to
bundle and use during the build.


--- BRLCAD_EXT_SOURCE_DIR ---

If specified, BRL-CAD will look in this directory for bext source files. Use
this when you have a pre-existing bext clone and don't want BRL-CAD's configure
process to pull down another copy, but are still looking to have the BRL-CAD
configure process manage producing bext build outputs.


--- BRLCAD_EXT_PARALLEL ---

This number, when specified, describes how many compilation threads to use
when compiling bext sources.  Default is 8.


--- BRLCAD_DEBUGGING ---

Add compiler flags to aid in program debugging.  Defaults to ON.

Aliases:  ENABLE_DEBUG, ENABLE_FLAGS_DEBUG, ENABLE_DEBUG_FLAGS
          BRLCAD_FLAGS_DEBUG


--- BRLCAD_PGO ---

Enable profile-guided optimization build flags.  Defaults to OFF.

Profile-guided optimization builds are possible via two-pass
compilation.  Compile with this flag set, run the benchmark suite,
clean the build, and then compile again with this flag set.  Supported
compilers will utilize data from the first pass to guide optimization,
typically resulting in a significant performance increase:


--- BRLCAD_WARNINGS ---

Use extra warning flags when compiling C/C++ code.  Defaults to ON.

Aliases:  ENABLE_WARNINGS, ENABLE_COMPILER_WARNINGS
          BRLCAD_ENABLE_COMPILER_WARNINGS


--- BRLCAD_ENABLE_STRICT ---

Causes all compilation warnings for C code to be treated as errors.  This is now
the default for BRL-CAD source code, and developers should address issues
discovered by these flags whenever possible rather than disabling strict
mode.

Aliases:  ENABLE_STRICT, ENABLE_STRICT_COMPILE, ENABLE_STRICT_COMPILE_FLAGS


--- ENABLE_ALL_CXX_COMPILE ---

Build all C and C++ files with a C++ compiler.  Defaults to OFF.

EXPERIMENTAL!

Aliases:  ENABLE_ALL_CXX


--- BRLCAD_EXTRADOCS ---

The core option that enables and disables building of BRL-CAD's
DocBook based documentation (includes manuals and man pages for
commands, among other things).  Defaults to ON, but only HTML and MAN
formats are enabled by default - PDF must be enabled separately by use
of this option or one of its aliases.  Note that you may set
environment variable APACHE_FOP to point to your locally installed fop
executable file (which on Linux is usually a shell script with 0755
permissions).

Aliases:  ENABLE_DOCS, ENABLE_EXTRA_DOCS, ENABLE_DOCBOOK