Difference between revisions of "Building from SVN"

From BRL-CAD
(I wanted to add a summary for my previous change but apparently I can't so... reverting my reversion.)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Obtain the sources via Subversion ==
 
== Obtain the sources via Subversion ==
  
BRL-CAD has recently [[Cvs2svn|switched from CVS to the Subversion system]]. In the new system some of the earlier complexities inherent to CVS are gone, no ''-dP'' option is required and developers will not need their passwords or usernames until it is time to commit a change.
+
For Windows:
 +
 
 +
Install a Subversion client for Windows, such as TortoiseSVN: https://sourceforge.net/projects/tortoisesvn/
 +
 
 +
To get a checkout after installing TortoiseSVN, right-click in a folder where you want to download the sources, select SVN Checkout and specify https://svn.code.sf.net/p/brlcad/code/brlcad/trunk for the repository URL.
  
 
For Linux/Mac/BSD:
 
For Linux/Mac/BSD:
Line 8: Line 12:
 
Note: If you do not yet have an SVN client installed, go to http://subversion.tigris.org for information on obtaining an appropriate SVN client for your platform. Most modern Linux/BSD/UNIX distributions will also have SVN available in their package repositories.
 
Note: If you do not yet have an SVN client installed, go to http://subversion.tigris.org for information on obtaining an appropriate SVN client for your platform. Most modern Linux/BSD/UNIX distributions will also have SVN available in their package repositories.
  
For Windows:
+
== Configure the build system with CMake ==
 
 
Install a Subversion client for Windows, such as TortoiseSVN: https://sourceforge.net/projects/tortoisesvn/
 
  
To get a checkout after installing TortoiseSVN, right-click in a folder where you want to download the sources, select SVN Checkout and specify https://svn.code.sf.net/p/brlcad/code/brlcad/trunk for the repository URL.
+
BRL-CAD also requires the build tool CMake. Most Linux/BSD/UNIX systems provide a package for CMake. For platforms that do not, CMake is available from http://www.cmake.org
  
 +
Once installed, create a directory where you will compile BRL-CAD and run CMake.
  
== Configure the build system with CMake ==
+
For Windows, you can use the CMake GUI where you specify build and source directories:[[File:Running_cmake_on_windows.png|200px|thumb|right|Running CMake GUI on Windows]]
 
 
BRL-CAD also requires the build tool CMake. Again, most Linux/BSD/UNIX distributions will provide a package for CMake - for platforms that do not, CMake is available from http://www.cmake.org
 
  
For Linux/Mac/BSD, create a build directory and run cmake:
+
For Linux/Mac/BSD, this looks like:
  
 
  cd brlcad
 
  cd brlcad
Line 27: Line 28:
 
  cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release (for a release build)
 
  cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release (for a release build)
  
For Windows, you can use the CMake GUI where you specify build and source directories:[[File:Running_cmake_on_windows.png|200px|thumb|right|Running CMake GUI on Windows]]
+
== Compile and test your build ==
 
When building for multiuser file servers it is often useful to make the install_dir reflect the version and/or architecture of the compile.  An example would be "-DCMAKE_INSTALL_PREFIX=/usr/brlcad/rel-7.20.2" to install into a /usr/brlcad/rel-7.20.2 directory.  (When CMAKE_BUILD_TYPE is set to Release, the installation directory automatically is assigned the appropriate directory and the user doesn't have to do so manually.)  This way a single system can have multiple versions of BRL-CAD installed or multiple binary formats for various architectures if installing on a network file system.  Symbolic links are then usually added to point to the "current" or "main" version that is preferable to provide so that users only need to add /usr/brlcad/bin to their path. Examples include:
 
  
;By version
+
On Windows, simply open the "BRLCAD" solution and Compile.
:/usr/brlcad/rel-7.8.0 (release 7.8.0)
 
:/usr/brlcad/rel-7.6.0 (release 7.6.0)
 
 
 
;By architecture
 
:/usr/brlcad/ia32 (linux on Pentium)
 
:/usr/brlcad/ia64 (linux on Itanium)
 
:/usr/brlcad/x86_64 (linux on Opteron)
 
 
 
;By version and architecture
 
:/usr/brlcad/rel-7.8.0/mips32 (IRIX on MIPS in 32-bit mode, release 7.8.0)
 
:/usr/brlcad/rel-7.8.0/mips64 (IRIX on MIPS in 64-bit mode, release 7.8.0)
 
:/usr/brlcad/rel-7.8.2/mips32 (IRIX on MIPS in 32-bit mode, release 7.8.2)
 
 
 
IMPORTANT!!! - Because BRL-CAD has such a long development history, it predates some library naming conventions in modern operating systems. This means an attempt to configure for an install in the "/usr" path on Linux (for example) will stand a good chance of damaging important system libraries - e.g. BRL-CAD libraries put in "/usr/lib" may overwrite system libraries with the same names. Using "/usr/brlcad" or "/opt/brlcad" means all installed files will be safely contained in the brlcad directory.
 
 
 
 
 
== Compile and test your build ==
 
  
 
On Linux/Mac/BSD, run this in your build directory:
 
On Linux/Mac/BSD, run this in your build directory:
Line 54: Line 36:
 
  make
 
  make
  
At this point, you should have a fully installed and working system. You can test things by doing:
+
If there are no compilation errors, you can test via:
  
 
  make test
 
  make test
 +
 +
You can also run a performance test:
 +
 
  make benchmark
 
  make benchmark
  
 
Both the test and benchmark should report successfully if everything is working correctly. Report any failures to the BRL-CAD [http://sourceforge.net/tracker/?group_id=105292&atid=640802 bug tracker].
 
Both the test and benchmark should report successfully if everything is working correctly. Report any failures to the BRL-CAD [http://sourceforge.net/tracker/?group_id=105292&atid=640802 bug tracker].
  
On Windows, open the BRLCAD solution and Compile.
 
  
== Doxygen ==
+
== Doxygen (OPTIONAL) ==
If you have doxygen installed somewhere CMake can find it, then you can build a browsable XHTML documentation of the source code. This is useful if you want to use BRL-CAD's libraries directly, or if you just want a better overview of how things are structured.
+
If you have doxygen installed somewhere CMake can find it, then you can build a browsable HTML documentation of the source code. This is useful if you want to use BRL-CAD's libraries directly, or if you just want a better overview of how things are structured.
  
To build the XHTML files on a UNIX system, run (from your build directory)
+
To build the HTML files on a Linux/Mac/BSD system, run (from your build directory):
  
 
  make dox
 
  make dox
  
and then open doc/doxygen_output/html/index.xhtml with your web browser of choice
+
and then open doc/doxygen_output/html/index.xhtml with your web browser of choice.
  
== Install ==
+
== Install (OPTIONAL) ==
  
On Linux/Mac/BSD, run this in your build directory:
+
On all systems, you can simply run directly from the build directory without installing.
  
  make install
+
That said, by default BRL-CAD installs into /usr/brlcad or /opt/brlcad on Linux/Mac/BSD and into the standard program directory on Windows. To check your build or install of BRL-CAD, browse to the "bin" directory from the GUI or from cmd.exe and run "mged".
  
If you created a prefix as described above for multiple versions or multiple architectures, you should now create your symbolic links for user convenience and consistency. Example where /usr/brlcad/rel-7.8.0/mips32 was used as the install_dir prefix:
+
== Setup environment (OPTIONAL) ==
  
<pre>% ln -s rel-7.8.0/mips32 /usr/brlcad/stable
+
At this point, all that remains is setting your system PATH environment variable so BRL-CAD utilities can be foundInstallation does not set PATH for you automatically.
% ln -s stable/bin /usr/brlcad/bin
 
% ln -s stable/include /usr/brlcad/include
 
% ln -s stable/lib /usr/brlcad/lib
 
% ln -s stable/man /usr/brlcad/man
 
% ln -s stable/share /usr/brlcad/share
 
% ls -l /usr/brlcad
 
total 48
 
lrwxr-xr-x  1 root  wheel  10 12 Apr 09:00 bin -> stable/bin
 
lrwxr-xr-x  1 root  wheel  14 12 Apr 09:00 include -> stable/include
 
lrwxr-xr-x  1 root  wheel  10 12 Apr 09:00 lib -> stable/lib
 
lrwxr-xr-x  1 root  wheel  10 12 Apr 09:00 man -> stable/man
 
drwxr-xr-x  7 root  wheel  238 11 Apr 18:00 rel-7.8.0
 
lrwxr-xr-x  1 root  wheel  12 12 Apr 09:00 share -> stable/share
 
lrwxr-xr-x  1 root wheel    9 12 Apr 09:00 stable -> rel-7.8.0/mips32</pre>
 
  
''Future versions of BRL-CAD may provide this symbolic link operation for you as a CMake configuration option.''
+
For Windows, setting PATH can be helpful but isn't necessary.  Simply navigate to where you installed BRL-CAD and run from there.
  
On Windows:
+
For Linux/Mac/BSD, you'll either need to specify full paths to applications (e.g., /usr/brlcad/bin/rt) or set your PATH. If the default installation prefix (/usr/brlcad or /opt/brlcad) was used, you should only need to add /usr/brlcad/bin to your PATH in order to find applications (optionally setting MANPATH as well):
 
 
You can run directly from the build directory.  Browse to the "bin" directory from the GUI or from cmd.exe and run applications (e.g., mged).
 
 
 
 
 
== Setup environment (optional) ==
 
 
 
At this point, everything should be ready for use. If the default prefix of /usr/brlcad was used or if the corresponding symbolic links were created, users should only need to add /usr/brlcad/bin to their PATH in order to find binaries for the package (optionally setting their MANPATH as well):
 
  
 
For bash:
 
For bash:
  
  export PATH=/usr/brlcad/bin:$PATH
+
  export PATH="/usr/brlcad/bin:$PATH"
  export MANPATH=/usr/brlcad/man:$MANPATH
+
  export MANPATH="/usr/brlcad/man:$MANPATH"
  
 
For csh/tcsh:
 
For csh/tcsh:
  
 
  set path=( /usr/brlcad/bin $path )
 
  set path=( /usr/brlcad/bin $path )
  setenv MANPATH /usr/brlcd/man:$MANPATH
+
  setenv MANPATH "/usr/brlcd/man:$MANPATH"
 
  rehash
 
  rehash
  
If users do not want to modify their PATH, they can get by providing the full path to the binaries (e.g. /usr/brlcad/bin/mged). To find BRL-CAD manual pages without setting your MANPATH, use the provided "brlman" binary instead of "man".
+
To find BRL-CAD manual pages without setting your MANPATH, use the provided "brlman" binary instead of "man" (e.g., /usr/brlcad/bin/brlman rt).
  
  
== Test installation ==
+
== Test your Build ==
  
If everything went well, there should now be more than 400 command-line applications at your disposal for processing images and geometry. A quick test of functionality (and performance) is to run the BRL-CAD benchmark again, which is installed as the benchmark tool:
+
If compilation went well, there should now be more than 400 command-line applications at your disposal for processing images and geometry. You should be able to run the main modeling application:
  
  benchmark
+
  mged
  
Additionally, you can run the MGED solid modeler:
+
If you didn't install, you may need to specify the path to the tool (e.g., "bin/mged") from the build directory.
 
 
mged
 
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 14:15, 2 December 2019

Obtain the sources via Subversion[edit]

For Windows:

Install a Subversion client for Windows, such as TortoiseSVN: https://sourceforge.net/projects/tortoisesvn/

To get a checkout after installing TortoiseSVN, right-click in a folder where you want to download the sources, select SVN Checkout and specify https://svn.code.sf.net/p/brlcad/code/brlcad/trunk for the repository URL.

For Linux/Mac/BSD:

svn checkout https://svn.code.sf.net/p/brlcad/code/brlcad/trunk brlcad

Note: If you do not yet have an SVN client installed, go to http://subversion.tigris.org for information on obtaining an appropriate SVN client for your platform. Most modern Linux/BSD/UNIX distributions will also have SVN available in their package repositories.

Configure the build system with CMake[edit]

BRL-CAD also requires the build tool CMake. Most Linux/BSD/UNIX systems provide a package for CMake. For platforms that do not, CMake is available from http://www.cmake.org

Once installed, create a directory where you will compile BRL-CAD and run CMake.

For Windows, you can use the CMake GUI where you specify build and source directories:

Running CMake GUI on Windows

For Linux/Mac/BSD, this looks like:

cd brlcad
mkdir build
cd build
cmake .. (for a default build)
cmake .. -DBRLCAD_BUNDLED_LIBS=ON -DCMAKE_BUILD_TYPE=Release (for a release build)

Compile and test your build[edit]

On Windows, simply open the "BRLCAD" solution and Compile.

On Linux/Mac/BSD, run this in your build directory:

make

If there are no compilation errors, you can test via:

make test

You can also run a performance test:

make benchmark

Both the test and benchmark should report successfully if everything is working correctly. Report any failures to the BRL-CAD bug tracker.


Doxygen (OPTIONAL)[edit]

If you have doxygen installed somewhere CMake can find it, then you can build a browsable HTML documentation of the source code. This is useful if you want to use BRL-CAD's libraries directly, or if you just want a better overview of how things are structured.

To build the HTML files on a Linux/Mac/BSD system, run (from your build directory):

make dox

and then open doc/doxygen_output/html/index.xhtml with your web browser of choice.

Install (OPTIONAL)[edit]

On all systems, you can simply run directly from the build directory without installing.

That said, by default BRL-CAD installs into /usr/brlcad or /opt/brlcad on Linux/Mac/BSD and into the standard program directory on Windows. To check your build or install of BRL-CAD, browse to the "bin" directory from the GUI or from cmd.exe and run "mged".

Setup environment (OPTIONAL)[edit]

At this point, all that remains is setting your system PATH environment variable so BRL-CAD utilities can be found. Installation does not set PATH for you automatically.

For Windows, setting PATH can be helpful but isn't necessary. Simply navigate to where you installed BRL-CAD and run from there.

For Linux/Mac/BSD, you'll either need to specify full paths to applications (e.g., /usr/brlcad/bin/rt) or set your PATH. If the default installation prefix (/usr/brlcad or /opt/brlcad) was used, you should only need to add /usr/brlcad/bin to your PATH in order to find applications (optionally setting MANPATH as well):

For bash:

export PATH="/usr/brlcad/bin:$PATH"
export MANPATH="/usr/brlcad/man:$MANPATH"

For csh/tcsh:

set path=( /usr/brlcad/bin $path )
setenv MANPATH "/usr/brlcd/man:$MANPATH"
rehash

To find BRL-CAD manual pages without setting your MANPATH, use the provided "brlman" binary instead of "man" (e.g., /usr/brlcad/bin/brlman rt).


Test your Build[edit]

If compilation went well, there should now be more than 400 command-line applications at your disposal for processing images and geometry. You should be able to run the main modeling application:

mged

If you didn't install, you may need to specify the path to the tool (e.g., "bin/mged") from the build directory.