BRL-CAD/brlcad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
brlcad/INSTALL
T

511 lines
19 KiB
Plaintext
Raw Permalink Blame History

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.26 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. Released files and their checksums are
available from the GitHub releases page (https://github.com/BRL-CAD/brlcad/releases). 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:
* Acquire bext and its dependencies from another repository host
cmake .. -DBRLCAD_REPOSITORY_ROOT=https://git.example.org/brlcad
* Acquire bext and its dependencies from local bare Git mirrors
cmake .. "-DBRLCAD_REPOSITORY_ROOT=/path/to/mirror/BRL-CAD"
* 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_X11_PROVIDER ---
Selects the X11 implementation used by BRL-CAD, Tk, Qt, and OpenGL. Accepted
values are AUTO, SYSTEM, and XMIN. AUTO is the default and deliberately
resolves to SYSTEM so installing Xmin cannot change an existing build.
XMIN selects an installed Xmin client SDK for deterministic GUI testing
without a host X server. The SDK must provide Xmin::ToolkitX11; OpenGL builds
also need Xmin::GL. Set Xmin_ROOT to the SDK installation prefix. Tk and Qt
must be built for the same provider because their public X11 APIs conceal
provider-private state; mixing Xmin and system client libraries is not ABI
safe and is rejected during configuration.
When BRL-CAD manages bext, it derives the matching bext SDK prefix from the
selected Xmin package. Bext then applies its version-matched Tk and Qt patches
automatically to whichever bundled toolkits are selected. No external patch
paths are needed.
A typical Xmin configuration is:
cmake .. -DBRLCAD_X11_PROVIDER=XMIN \
-DXmin_ROOT=/path/to/xmin-prefix
Bext retains advanced TK_EXTRA_PATCHES, TK_CONFIGURE_ARGS, QT_EXTRA_PATCHES,
and QT_XMIN_ROOT controls for custom profiles. The standard BRL-CAD Xmin
configuration does not need them. Refer to bext's Xmin profile documentation
before changing the bundled Tk or Qt revision.
--- 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_REPOSITORY_ROOT ---
Repository URL or local directory containing bext and its dependency
repositories. Defaults to https://github.com/BRL-CAD. The root directly
contains repositories such as bext.git and astyle.git; BRL-CAD does not
append BRL-CAD to the root.
Remote Git URLs (including SSH), native paths, and file:// URLs are supported.
Relative native paths are resolved against the BRL-CAD source directory.
Quote the entire -D argument for paths containing spaces. The setting is
cached and is also passed as BEXT_REPOSITORY_ROOT when BRL-CAD configures
bext, including when BRLCAD_EXT_SOURCE_DIR supplies an existing checkout.
Alternate roots require bext sources with BEXT_REPOSITORY_ROOT support.
Local roots restrict CMake-driven Git acquisition and queries to file
transport, with no online fallback. Mirrors must contain all required pinned
commits and recursive submodules. Dependencies outside bext's canonical URL
prefix require their own Git URL mappings. This setting does not restrict
network access by dependency build scripts or change persistent Git settings.
BRLCAD_EXT_DIR still selects prebuilt outputs, and changing the repository
root alone does not force those outputs to be rebuilt.
To return to the default source:
cmake .. -DBRLCAD_REPOSITORY_ROOT=https://github.com/BRL-CAD
--- BRLCAD_EXT_DIR ---
If specified, BRL-CAD will look in this directory for bext compiled outputs to
bundle and use during the build. Relative paths are resolved against the
BRL-CAD source directory. Distcheck subconfigures reuse this resolved output
directory and preserve BRLCAD_REPOSITORY_ROOT, BRLCAD_EXT_SOURCE_DIR, and
BRLCAD_EXT_PARALLEL when specified.
--- 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. Relative paths are
resolved against the BRL-CAD source directory.
--- 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
AsciiDoc based documentation (includes manuals and man pages for
commands, among other things). It is built with BRL-CAD's bundled
asciiquack processor into HTML and man-page (troff) formats. Defaults
to ON for a full build and OFF for reduced target sets.
Aliases: ENABLE_DOCS, ENABLE_EXTRA_DOCS
Reference in New Issue View Git Blame Copy Permalink