Basis Guide on software installation: Build and Installation

This document describes the common procedure to build and install any software developed at and distributed by SBIA. In particular, software built on top of BASIS, a meta-project which defines the Build system And Software Implementation Standard established in the fall of 2011. See the Overview [insert home basis link] page for details on this meta-project.

If you obtained a binary distribution package for a supported platform, please follow the installation instructions corresponding to your operating system. The build step can be omitted in this case.

In case of problems to build, install, or use the software, please contact the SBIA Group at the University of Pennsylvania, PA, at sbia-software at uphs.upenn.edu.

Package Names

The file names of the distribution packages follow the convention <package>-<version>-<arch><ext>, where <package> is the name of the package in lowercase letters, and <version> is the package version in the format <major>.<minor>.<patch>. The <arch> file name part specifies the operating system and hardware architecture, i.e.,

The file name extension <ext> is .tar.gz for a compressed tarball, .deb for a Debian package, and .rpm for a RPM package.

Binary Distribution Package

Debian Package

This package can be installed on Debian and its derivatives such as Ubuntu using the Advanced Package Tool (APT):

sudo apt-get install <package>-<version>-<arch>.deb

RPM Package

This package can be installed on Red Hat Enterprise Linux and its derivatives such as CentOS and openSUSE using the Yellowdog Updater, Modified (YUM):

sudo yum install <package>-<version>-<arch>.rpm

Mac OS

Bundles for Mac OS might be available for some software packages, but this is not supported by default. Please refer to the INSTALL file which is located in the top directory of the respective software package.

Windows

Currently, Microsoft Windows is not supported as operating system. The software development at SBIA is based on Linux, in particular CentOS, and most software packages are therefore dependent on a Unix-based operating system. Thus, building and executing SBIA software under Windows will most likely require an installation of Cygwin and the build of the software from sources as described below. Some packages, on the other side, can be build on Windows as well, using, for example, Microsoft Visual Studio as build tool. The Visual Studio project files have to be generated using CMake (see Building From Sources).

As an alternative, consider the use of a Live Linux Distribution, a dual boot installation of Linux or an installation of a Linux operating system in a virtual machine using virtualization tools such as VirtualBox or proprietary virtualization solutions available for your host operating system.

Building From Sources

In the following, we assume you obtained a copy of the source package as compressed tarball (.tar.gz). The name and version part of the package file is referred to as Bash variable:

package=<package>-<version>

Prerequisites

The following software packages are prerequisites for any software that is based on BASIS. When you are building BASIS itself, the dependency on BASIS is obviously already fulfilled. Furthermore, the stated package versions are the minimum versions for which it is known that the software is working with. Newer versions will usually be fine as well if not otherwise stated, but less certainly older versions.

Required Packages

This section summarizes software packages which have to be installed on your system before this software can be build from its sources.

Optional Packages

The packages named in the following table are used only if installed on your system, and their presence is generally no requirement and you will likely be able to use the basic components of the software without these. See the <code>INSTALL</code> file of the software package for details and which packages are indeed made use of or required by this software.

Extract sources

At first, extract the downloaded source package, e.g.:

tar -xzf $package-source.tar.gz ~

This will extract the sources to a new diretory in your home directory named “<package>-<version>-source”.

Configure

Create a directory for the build tree of the package and change to it, e.g.:

mkdir ~/$package-build cd ~/$package-build

Note

An in-source build, i.e., building the software within the source tree is not supported to force a clear separation of source and build tree.

To configure the build tree, run CMake’s graphical tool ccmake:

ccmake ~/$package-source

Press c to trigger the configuration step of CMake. Warnings can be ignored by pressing e. Once all CMake variables are configured properly, which might require the repeated execution of CMake’s configure step, press g. This will generate the configuration files for the selected build tool (i.e., GNU Make Makefiles in our case) and exit CMake.

Variables which specify the location of other required or optionally used packages if available are named <Package>_DIR. These variables usually have to be set to the directory which contains a file named <Package>Config.cmake or <package>-config.cmake. Alternatively, or if the package does not provide such CMake package configuration file, the installation prefix, i.e., root directory should be specified. See the build instructions of the particular software package you are building for more details on the particular <Package>_DIR variables that may have to be set if the packages were not found automatically by CMake.

See the documentation of the available default configuration options for more options that can be used to configure the build of any BASIS-based project. Please refer also to the package specific build instructions given in the INSTALL file or software manual of the corresponding package for information on available additional project specific configuration options.

Note

The ccmake tool also provides a brief description to each variable in the status bar.

Build

To build the executables and libraries, run GNU Make in the root directory of the configured build tree:

make

In order to build the documentation, the -DBUILD_DOCUMENTATION option has to be set to ON. If not done before, this option can be enabled using the command:

cmake -D BUILD_DOCUMENTATION:BOOL=ON ~/$package-build

Note that the build of the documentation may require the build of the software beforehand. If the software was not build before, the build of the documentation will also trigger the build of the software.

Each software package provides different documentation. In general, however, each software has a manual, which by default is being build by the manual target if the software manual is not already included as PDF document. In the latter case, the manual does not have to be build. Instead, the PDF file will simply be copied (and renamed) during the installation. Otherwise, in order to build the manual from source files such as reStructuredText or LaTeX, run the command:

make manual

If the software provides a software library for use in your own code, the API documentation may be useful which can be build using the apidoc target:

make apidoc

The advanced -DBASIS_INSTALL_APIDOC_DIR configuration option can be set to an absolute path or a path relative to the -DCMAKE_INSTALL_PREFIX directory in order to modify the installation directory for the API documentation which is generated from the in-source comments using tools such as Doxygen and Sphinx. This can be useful, for example, to install the documentation in the document directory of a web server.

Some software packages further generate a project web site from text files marked up using a lightweight markup language such as reStructuredText. This web site can be build using the site target:

make site

This will generate the HTML pages and corresponding static files of the web site in doc/site/html/. If you prefer a single directory per document which results in prettier URLs without the .html extension, run the following command instead: