BRL-CAD on Linux README
=======================

Below are installation and platform notes of relevance to particular
Linux distributions.

Table of Contents
-----------------
Parallel Builds
64-bit Compile
32-bit Compile
Arch Linux
Ubuntu/Debian
PPC64 Linux

Parallel Builds
---------------
BRL-CAD compilation can take advantage of multiple CPUs.  With
Make based builds, this is done using the "-j" flag - e.g. a
six core machine will build faster using "make -j6" to utilize
all cores.


64-bit Compile (on a platform that defaults to 32-bit)
--------------

cmake ../brlcad -DBRLCAD_WORD_SIZE=32BIT

32-bit Compile (on a platform that defaults to 64-bit)
--------------

cmake ../brlcad -DBRLCAD_WORD_SIZE=64BIT

* Note that in both of the above situations you need both a compiler that
works in the alternate mode and system libraries of the correct type.


Arch Linux
----------

An example PKGBUILD and needed scripts are provided in misc/archlinux.
Review and edit the PKGBUILD to suit your preferred configuration and
build situation (e.g. building from a tarball vs building from SVN).
Run `makepkg` in that directory to build the package.


Ubuntu/Debian
-------------

Users of Ubuntu, Debian, and other similar packaging distributions of
Linux will need to ensure that a few essentials are in place before
you will be able to compile BRL-CAD.

Following the build instructions in the INSTALL file.  You will need:

gcc (6+, e.g. 6.0.3)
g++ (6+, e.g. 6.0.3)
make (e.g. gnu make 3.8.0)
cmake (3.0.2 or newer)

All three of those have implicit dependencies on other packages.

You will also want to make sure that you have the X11 development
headers installed:

  apt-get install xserver-xorg-dev libx11-dev libxi-dev libxext-dev

Other development packages needed to build on Debian-based platforms:

  for building the Tcl/Tk libraries:  libfontconfig-dev

  for OpenGL: libglu1-mesa-dev

Note there is a supported Debian package generation script in file
'sh/make_deb.sh' which can function only on a Debian or Ubuntu system.
It can be used like so:

  $ cd <BRL-CAD source directory>

  # get help for the script:
  $ ./sh/make_deb.sh

  # create a binary package:
  $ ./sh/make_deb.sh -b

You can customize the script's cmake build options by modifying the
file 'misc/debian/rules'.  Note that the BRL-CAD source directory
should be deleted and recreated for each new attempt at package
generation.


Redhat/CentOS/Fedora
-------------

If you don't already have the necessary development tools:

  yum install gcc gcc-c++ cmake

Development packages for building on Redhat/Fedora platforms:

  yum install libX11-devel
  yum install libXext-devel    # optional
  yum install libXi-devel      # optional
  yum install freetype-devel   # optional
  yum install fontconfig-devel # optional
  yum install mesa-libGL-devel # optional

If you wish to create rpm packages, you'll need rpmbuild

  yum install rpm-build        # optional

When setting up older versions for building BRL-CAD, it is sometimes
necessary to install some non-default compilation tools in addition to the
usual dependencies.  (The default toolchain is sometimes too old to
properly build BRL-CAD, if the compilers don't support sufficiently modern
standards.)  The following example is for CentOS 7:

yum install centos-release-scl
yum install devtoolset-7

Then to run within that environment:

scl enable devtoolset-7 bash


The CMake version is often too old as well.  One way forward is to download the
source code and bootstrap it (do this within the devtoolset enabled bash):

sudo yum install openssl-devel

curl -L -o cmake-3.18.2.tar.gz https://github.com/Kitware/CMake/releases/download/v3.18.2/cmake-3.18.2.tar.gz
tar -xvf cmake-3.18.2.tar.gz
cd cmake-3.18.2
./bootstrap --prefix=/opt/cmake
make -j3 && make install
export PATH=/opt/cmake/bin

From there, with the devtoolset enabled and the PATH set to include the new
CMake, it should be possible to proceed normally with the build.

-------

To determine what particular version of Redhat or Fedora you are
using, check these files:

cat /etc/redhat-release
cat /etc/fedora-release

-------

Note there is a supported rpm package generation script in file
'sh/make_rpm.sh' which can only function on a Fedora or openSUSE
system.  It can be used like so:

  $ cd <BRL-CAD source directory>

  # create an rpm file:
  $ ./sh/make_rpm.sh

It is also possible to create an RPM package using CPack with the
make package build target, on systems with the proper RPM tools.

-------

One issue encountered running CentOS in VirtualBox - networking
is off by default.  To enable, look for a file in
/etc/sysconfig/network-scripts/ called something like enp0s3 and
set ONBOOT=yes (see https://unix.stackexchange.com/a/79273)


PPC64 Linux
-----------

If you happen to be installing on a ppc64 Linux system, the binaries
may not resolve correctly without being installed first.  Be sure to
install before testing applications (i.e., even before running the
benchmark or "make test").
