Difference between revisions of "Compiling"

From BRL-CAD
(Install Dependencies)
(cmake 3.18 now)
 
(33 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
= Compiling BRL-CAD =
 
= Compiling BRL-CAD =
  
This page contains simplified steps for building '''''quickly'''''.
+
This page has simplified steps for building '''''quickly'''''.  See [https://github.com/BRL-CAD/brlcad/blob/main/INSTALL INSTALL] for more detailed instruction.
  
== Install Dev Tools ==
 
  
''If you downloaded the virtual machine disk image, skip this step.''
+
== Step 1: Install Dev Tools ==
  
BRL-CAD uses the CMake build system and may be built with most compilers, so first step is to [http://www.cmake.org/cmake/resources/software.html download and install CMake].  If needed, compiling from their source distribution is actually very easy.
+
To build, you want the latest [https://cmake.org/download/ CMake], a recent compiler, and at least 3GB of disk spaceYou will also want [https://git-scm.com/downloads/guis Git] to obtain the latest source code.
  
* Debian/Ubuntu: <pre>aptitude install build-essential make cmake</pre>
+
* Minimum versions:
 +
** CMake must be 3.18 or later
 +
** Git must be 2.17 or later
 +
** Compiler must be C++11-compliant
 +
*** If using Visual Studio, version 2015 (14.0+) or later
 +
*** If using GCC/G++, version 4.8.1 or later
 +
*** If using LLVM/Clang 3.3 or later
 +
*** If using Intel, version 2015 (15.0+) or later
  
* Fedora: <pre>yum install clang++ make cmake</pre>
 
  
== Install Dependencies ==
+
* '''Windows''': Install [https://gitforwindows.org Git], [https://cmake.org/download/ CMake], and [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] or Professional.  VS Code should also work, but you will need to install the "[https://visualstudio.microsoft.com/downloads/ Build Tools for Visual Studio]" also.
  
''If you downloaded the virtual machine disk image, skip this step.''
 
  
If you're on a Mac or Windows, you're good to go. For Linux, BSD, and other package-managed systems, you'll want to install a few things.
+
* '''Mac''': Install [https://cmake.org/download/ CMake] and XCode or run this in Terminal: <pre>xcode-select --install</pre>
  
* Debian/Ubuntu:
 
** <pre>aptitude install sed byacc flex xsltproc</pre>
 
** <pre>aptitude install libncursesw5-dev libfontconfig-dev</pre>
 
** <pre>aptitude install xserver-xorg-dev</pre>
 
** <pre>aptitude install libx11-dev libxi-devel</pre>
 
  
* Fedora: <pre>yum install libx11-devel</pre>
+
* '''Linux''' and Windows Subsystem for Linux ('''WSL'''):
  
== Download BRL-CAD ==
+
Installing is easiest with a package management system like apt, brew, yum, and dnf that install for you.  Alas, the tools and names change frequently, so the following are platform-specific recommendations that may need to be adjusted for your system.
  
''If you downloaded the virtual machine disk image, run this to make sure you have the latest sources:''
+
** WSL: You should be good to go.
<pre>
+
 
svn up brlcad-svn-trunk
+
** Debian/Ubuntu: <pre>apt install build-essential make cmake</pre>
</pre>
+
 
 +
If you're on an older distribution, you may need to manually install a more recent version of cmake. 
 +
 
 +
** Fedora: <pre>yum install clang++ make cmake</pre>
 +
 
 +
** CentOS: <pre>yum install python3-pip devtoolset-9</pre><pre>pip3 install cmake</pre><pre>scl enable devtoolset-9 bash</pre>
 +
 
 +
 
 +
* BSD: we assume you know what you're doing and can follow the gist
 +
 
 +
== Step 2: Install Dependencies ==
 +
 
 +
* '''Windows''': You can skip this step.
 +
 
 +
* '''Mac''': Install the latest [https://www.xquartz.org XQuartz]
 +
 
 +
* '''Linux''': BRL-CAD needs the Xorg development packages
 +
 
 +
** Debian/Ubuntu: <pre>apt install libc6-dev libfreetype-dev libfontconfig-dev</pre><pre>apt install xserver-xorg-dev libx11-dev libxi-dev libglu1-mesa-dev</pre>
 +
 
 +
** Fedora: <pre>yum install freetype-devel fontconfig-devel</pre><pre>yum install libX11-devel libXext-devel libXi-devel mesa-libGL-devel</pre>
 +
 
 +
== Step 3: Download BRL-CAD ==
 +
 
 +
We recommend obtaining BRL-CAD by forking or cloning our repository on [https://github.com/BRL-CAD/brlcad GitHub].
 +
 
 +
* '''Windows''': If you're going to build with Visual Studio, run Git GUI specifying this repository to clone: <pre>https://github.com/BRL-CAD/brlcad.git</pre>.  If you're building under WSL, clone from the git-bash command line.
 +
 
 +
* '''Mac''': You can either run the Git GUI, or you can run this in Terminal: <pre>git clone https://github.com/BRL-CAD/brlcad.git</pre>
 +
 
 +
* '''Linux''' and '''WSL''': <pre>git clone https://github.com/BRL-CAD/brlcad.git</pre>
 +
 
 +
The "brlcad" folder created after cloning is a full source checkout of BRL-CAD and contains a README with additional info.  If you run into trouble cloning from git, snapshot source releases [https://sourceforge.net/projects/brlcad/files/BRL-CAD%20Source/ are available].
 +
 
 +
 
 +
== Step 4: Create a Build directory ==
 +
 
 +
You can create a build folder anywhere, but it's typically named "build" and is in or near your "brlcad" source directory.
 +
 
 +
* '''Windows''': create a folder named "build" inside your "brlcad" folder
 +
 
 +
* '''Mac''', '''Linux''': <pre>mkdir -p brlcad/build</pre>
 +
 
 +
 
 +
== Step 5: Configure ==
 +
 
 +
It's first recommended during configure and compilation that you temporarily suspend any anti-virus software as they're notorious for issuing false-positives alerts and blocking necessary operations.  Some BRL-CAD tools use temporary network ports that will need to be allowed as well, if prompted.
 +
 
 +
Next, you'll run CMake to configure and generate a build system. 
 +
 
 +
CMake needs to know the top-level source dir (i.e., "brlcad" dir you cloned) and "build" dir you made are located.  For your first time, we also recommend setting these CMake variables to avoid trivial issues:
 +
  BRLCAD_ENABLE_STRICT=OFF
 +
  BRLCAD_ENABLE_COMPILER_WARNINGS=OFF
 +
  BRLCAD_BUNDLED_LIBS=ON
 +
 
 +
* '''Windows''': you can use CMake GUI where you'll specify 1) your source dir (i.e. path to the "brlcad" folder that has README), 2) the build dir, and 3) variables.  CMake does not display variables the first time you run, but you can "+ Add Entry" to add them or run "Configure" to list them.  Once dirs and variables are set, run "Configure" again and finally "Generate" to create a Visual Studio build system.  [[File:Running_cmake_on_windows.png|200px|thumb|right|Running CMake GUI on Windows]]
  
For everyone else, we recommend obtaining the latest sources from our repository:
+
* '''Mac''': You can either run CMake GUI like described for Windows, specifying your source dir, build dir, and the above variables, or you can follow the steps below for Linux in Terminal.
<pre>
 
svn checkout svn://svn.code.sf.net/p/brlcad/code/brlcad/trunk brlcad-svn-trunk
 
</pre>
 
  
If you run into trouble, snapshot release sources may also be obtained from [https://sourceforge.net/projects/brlcad/files/BRL-CAD%20Source/ Sourceforge].
+
* '''Linux''': <pre>cd brlcad/build</pre><pre>cmake .. -DBRLCAD_ENABLE_STRICT=NO -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release</pre>
  
== Configure your Build ==
+
See [https://github.com/BRL-CAD/brlcad/blob/main/INSTALL INSTALL] for more CMake options.
  
Next, set up a build directory and configure your compilation:
+
If CMake was successful, there will be a summary of the build printed at the end, it will say "Configured", and then "Generated" after a build system is finally done being written out for compiling BRL-CAD.
  
<pre>
+
If CMake was unsuccessful, scan the output for any error messages indicating what is failing or missing as it's typically a missing tool, missing library, or erroneous setting.
cd brlcad-svn-trunk
 
mkdir build
 
cd build
 
cmake .. -DBRLCAD_ENABLE_STRICT=NO -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release
 
</pre>
 
  
By default, our build enforces code standards that will halt on trivial issues, so we recommend turning off that strict behavior for your first compile.  By default, it will also search your system for dependencies, but this can be complicated so we tell the build to use our bundled versions.  When you graduate to doing development, you'll want to change the build type to -DCMAKE_BUILD_TYPE=Debug instead of Release.
+
== Step 6: Compile ==
  
BRL-CAD source files contain an [http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/INSTALL INSTALL] file with more detailed instructions if you want to customize the build.
+
'''Windows''': navigate to your build directory and open the BRLCAD.sln file with Visual Studio. You can ignore any warning about a duplicate "regress" target. Compile the default ALL_BUILD solution.
  
== Compile ==
+
'''Mac''', '''Linux''': while still in the build directory from Step 4, run <pre>make</pre>.  If you have multiple cores, you can alternatively compile in parallel specifying a desire number of cores, e.g., <pre>make -j10</pre>
  
You're good to go, now it's time to compile:
+
If the build fails, re-run while capturing all output to a log: make 2>&1 | tee build.log
<pre>
+
Please [https://github.com/BRL-CAD/brlcad/issues report] any build failures.
make
 
</pre>
 
  
Compilation can take anywhere from a couple minutes to an hour depending on your hardware.  If you had a quad-core CPU, you might run '"make -j4" to request compiling in parallel.
+
Note: Compilation can take anywhere from a couple minutes to an hour depending on hardware.  If you had a quad-core CPU, you might run '"make -j4" to speed things up by compiling in parallel.
  
If the build fails, re-run make while capturing all output to a log: make > build.log 2>&1
 
Please report any build failures.
 
  
== Run! ==
+
== Step 7: Run! ==
  
You don't have to install to run BRL-CAD.  You can just run the binaries you just finished compiling.  They are in the brlcad/.build/bin directory.  There are 400+ tools in BRL-CAD.  Here's a couple to get started:
+
You don't have to install to run BRL-CAD.  You can run the binaries you just compiled as they are in the brlcad/build/bin directory.  On Windows, they can be in Debug/ or Release/ folders.  Of the  hundreds of tools in BRL-CAD, here's just a few to get you started:
  
 
<pre>
 
<pre>
Line 78: Line 120:
 
</pre>
 
</pre>
  
The first command will evaluate your system performance.  If you made a Release build, please submit your benchmark results to benchmark at brlcad dot org.
+
The first command (benchmark) will evaluate system performance and you can send results to benchmark at brlcad dot org.
 +
 
 +
The second command (mged) is BRL-CAD's main graphical user interface application.
 +
 
 +
The third command (archer) is BRL-CAD's newer graphical interface under development.
  
The second command runs the main graphical interface.  Be sure to check out the extensive [[Documentation]] and [[Main_Page]] for tutorials.
+
= What next? =
  
The third runs our newer graphical interface that is under development.
+
Be sure to check out the [[Documentation|docs]] and [[Main_Page]] for tutorials and more.
  
== What now? ==
+
Help make BRL-CAD better!  There are many ways you can contribute to open source and you don't need to be an experienced programmer.  We need artists, writers, designers, software developers, and managers.  Contact us on [[IRC]].
  
Help make BRL-CAD better!  There are many ways you can contribute to open source and you don't need to be an experienced programmer.  We do need software developers, but we also need artists, writers, designers, and managers.
+
Please [https://github.com/BRL-CAD/brlcad/issues report] any build failures.
  
 
See [[Deuces]] for really easy ways to get started!
 
See [[Deuces]] for really easy ways to get started!

Latest revision as of 02:44, 4 October 2022

Compiling BRL-CAD[edit]

This page has simplified steps for building quickly. See INSTALL for more detailed instruction.


Step 1: Install Dev Tools[edit]

To build, you want the latest CMake, a recent compiler, and at least 3GB of disk space. You will also want Git to obtain the latest source code.

  • Minimum versions:
    • CMake must be 3.18 or later
    • Git must be 2.17 or later
    • Compiler must be C++11-compliant
      • If using Visual Studio, version 2015 (14.0+) or later
      • If using GCC/G++, version 4.8.1 or later
      • If using LLVM/Clang 3.3 or later
      • If using Intel, version 2015 (15.0+) or later



  • Mac: Install CMake and XCode or run this in Terminal:
    xcode-select --install


  • Linux and Windows Subsystem for Linux (WSL):

Installing is easiest with a package management system like apt, brew, yum, and dnf that install for you. Alas, the tools and names change frequently, so the following are platform-specific recommendations that may need to be adjusted for your system.

    • WSL: You should be good to go.
    • Debian/Ubuntu:
      apt install build-essential make cmake

If you're on an older distribution, you may need to manually install a more recent version of cmake.

    • Fedora:
      yum install clang++ make cmake
    • CentOS:
      yum install python3-pip devtoolset-9
      pip3 install cmake
      scl enable devtoolset-9 bash


  • BSD: we assume you know what you're doing and can follow the gist

Step 2: Install Dependencies[edit]

  • Windows: You can skip this step.
  • Linux: BRL-CAD needs the Xorg development packages
    • Debian/Ubuntu:
      apt install libc6-dev libfreetype-dev libfontconfig-dev
      apt install xserver-xorg-dev libx11-dev libxi-dev libglu1-mesa-dev
    • Fedora:
      yum install freetype-devel fontconfig-devel
      yum install libX11-devel libXext-devel libXi-devel mesa-libGL-devel

Step 3: Download BRL-CAD[edit]

We recommend obtaining BRL-CAD by forking or cloning our repository on GitHub.

  • Windows: If you're going to build with Visual Studio, run Git GUI specifying this repository to clone:
    https://github.com/BRL-CAD/brlcad.git
    . If you're building under WSL, clone from the git-bash command line.
  • Mac: You can either run the Git GUI, or you can run this in Terminal:
    git clone https://github.com/BRL-CAD/brlcad.git
  • Linux and WSL:
    git clone https://github.com/BRL-CAD/brlcad.git

The "brlcad" folder created after cloning is a full source checkout of BRL-CAD and contains a README with additional info. If you run into trouble cloning from git, snapshot source releases are available.


Step 4: Create a Build directory[edit]

You can create a build folder anywhere, but it's typically named "build" and is in or near your "brlcad" source directory.

  • Windows: create a folder named "build" inside your "brlcad" folder
  • Mac, Linux:
    mkdir -p brlcad/build


Step 5: Configure[edit]

It's first recommended during configure and compilation that you temporarily suspend any anti-virus software as they're notorious for issuing false-positives alerts and blocking necessary operations. Some BRL-CAD tools use temporary network ports that will need to be allowed as well, if prompted.

Next, you'll run CMake to configure and generate a build system.

CMake needs to know the top-level source dir (i.e., "brlcad" dir you cloned) and "build" dir you made are located. For your first time, we also recommend setting these CMake variables to avoid trivial issues:

 BRLCAD_ENABLE_STRICT=OFF
 BRLCAD_ENABLE_COMPILER_WARNINGS=OFF
 BRLCAD_BUNDLED_LIBS=ON
  • Windows: you can use CMake GUI where you'll specify 1) your source dir (i.e. path to the "brlcad" folder that has README), 2) the build dir, and 3) variables. CMake does not display variables the first time you run, but you can "+ Add Entry" to add them or run "Configure" to list them. Once dirs and variables are set, run "Configure" again and finally "Generate" to create a Visual Studio build system.
    Running CMake GUI on Windows
  • Mac: You can either run CMake GUI like described for Windows, specifying your source dir, build dir, and the above variables, or you can follow the steps below for Linux in Terminal.
  • Linux:
    cd brlcad/build
    cmake .. -DBRLCAD_ENABLE_STRICT=NO -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

See INSTALL for more CMake options.

If CMake was successful, there will be a summary of the build printed at the end, it will say "Configured", and then "Generated" after a build system is finally done being written out for compiling BRL-CAD.

If CMake was unsuccessful, scan the output for any error messages indicating what is failing or missing as it's typically a missing tool, missing library, or erroneous setting.

Step 6: Compile[edit]

Windows: navigate to your build directory and open the BRLCAD.sln file with Visual Studio. You can ignore any warning about a duplicate "regress" target. Compile the default ALL_BUILD solution.

Mac, Linux: while still in the build directory from Step 4, run

make

. If you have multiple cores, you can alternatively compile in parallel specifying a desire number of cores, e.g.,

make -j10

If the build fails, re-run while capturing all output to a log: make 2>&1 | tee build.log Please report any build failures.

Note: Compilation can take anywhere from a couple minutes to an hour depending on hardware. If you had a quad-core CPU, you might run '"make -j4" to speed things up by compiling in parallel.


Step 7: Run![edit]

You don't have to install to run BRL-CAD. You can run the binaries you just compiled as they are in the brlcad/build/bin directory. On Windows, they can be in Debug/ or Release/ folders. Of the hundreds of tools in BRL-CAD, here's just a few to get you started:

bin/benchmark run
bin/mged
bin/archer

The first command (benchmark) will evaluate system performance and you can send results to benchmark at brlcad dot org.

The second command (mged) is BRL-CAD's main graphical user interface application.

The third command (archer) is BRL-CAD's newer graphical interface under development.

What next?[edit]

Be sure to check out the docs and Main_Page for tutorials and more.

Help make BRL-CAD better! There are many ways you can contribute to open source and you don't need to be an experienced programmer. We need artists, writers, designers, software developers, and managers. Contact us on IRC.

Please report any build failures.

See Deuces for really easy ways to get started!