|
BASIS
version 1.2.3 (revision 2104)
|
|
BASIS
version 1.2.3 (revision 2104)
|
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 Introduction 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.
Visit the SBIA homepage for an overview of publicly available software distribution packages. For each of these packages, download links of the available distribution packages can be requested by submitting this form with a valid email address. An email with the respective download links will be sent to you automatically. If you do not receive an email within 24 hours, please contact the SBIA Group at <sbia-software at uphs.upenn.edu>.
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.,
<arch> | Description |
|---|---|
| linux-x86 | Linux, 32-bit |
| linux-x86_64 | Linux, 64-bit |
| darwin-i386 | Darwin x86 Intel |
| darwin-ppc | Darwin Power PC |
| win32 | Windows, 32-bit |
| win64 | Windows, 64-bit |
| source | Source files |
The file name extension <ext> is "tar.gz" for a compressed tarball, "deb" for a Debian package, and "rpm" for a RPM package.
This package can be installed on Debian and its derivatives such as Ubuntu using, for example, the Advanced Package Tool (APT).
To install the software package, run
sudo apt-get install <package>-<version>-<arch>.deb
in a terminal or use the package manager of your choice.
This package can be installed on Red Hat Enterprise Linux and its derivatives such as CentOS and openSUSE using, for example, the Yellowdog Updater, Modified (YUM).
To install the software package, run
sudo yum install <package>-<version>-<arch>.deb
in a terminal or use the RPM package manager of your choice.
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 root directory of the respective software package.
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 the Software 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.
The build of the software packages developed at SBIA is based on CMake, a cross-platform, open-source build tool. This tool can be used to configure the build system for various build tools which perform the actual build. Because of the focus on Linux-based development at SBIA, build instructions are based on GNU Make and the GNU Compiler Collection.
| Package | Description | ||||||
|---|---|---|---|---|---|---|---|
| GNU Compiler Collection |
| ||||||
| GNU Make |
| ||||||
| CMake 2.8.4 or greater |
If your operating system such as certain Linux distributions do not support CMake 2.8.4 or greater yet, you need to download a more recent CMake version from the download page noted above and install it manually. Often this is easiest accomplished by using the CMake version supported by your platform itself to configure the build system for the more recent CMake version. In order to not conflict with the CMake installation of your particular Linux distribution, it is recommended to install your own build of CMake in a different directory or to at least remove the pre-installed CMake installation prior to installing the new version. | ||||||
| BASIS |
The Build system And Software Implementation Standard (BASIS) among other features defines the project directory structure and provides CMake implementations to ease and standardize the build and installation. Refer to the INSTALL document of the software package you want to build and install for information on which particular BASIS version is required by this package. |
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
pkg=<package>-<version>
At first, extract the downloaded source package, e.g.,
tar xzf $pkg-source.tar.gz ~
This will extract the sources to a new diretory in your home directory named "<package>-<version>-source".
Create a directory for the build tree of the package and change to it, e.g.,
mkdir ~/$pkg-build cd ~/$pkg-build
To configure the build tree, run CMake's graphical tool ccmake
ccmake ~/$pkg-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.
The common CMake variables which configure the build and installation are:
| Option/Variable | Descripion |
|---|---|
| BUILD_CHANGELOG | Request build of ChangeLog as part of the ALL target. Note that the ChangeLog is generated either from the Subversion history if the source tree is a SVN working copy, or from the Git history if it is a Git repository. Otherwise, the ChangeLog cannot be generated and this option is disabled again by BASIS. In case of Subversion, be aware that the generation of the ChangeLog takes several minutes and may require the input of user credentials for access to the Subversion repository. It is recommended to leave this option disabled and to build the "changelog" target separate from the rest of the software package instead (see step 4 below). |
| BUILD_DOCUMENTATION | Whether build and installation instructions for the documentation should be added. If OFF, the build configuration of the doc/ directory is skipped. Otherwise, the "doc" target is added which is used to build the documentation. |
| BUILD_EXAMPLE | Whether the examples should be built (if required) and/or installed. |
| BUILD_TESTING | Whether the testing tree should be built and system tests, i.e., tests that execute the installed programs and compare the outputs to the expected results should be installed (if done so by the software package). |
| CMAKE_BUILD_TYPE | Specify the build configuration to build. If not set, the "Release" configuration will be build. Valid values are "Release", "Debug", "RelWithDebInfo", and "MinSizeRel". |
| INSTALL_LINKS | Whether (symbolic) links should be created (see step 5). |
| INSTALL_PREFIX | Prefix used for package installation (see step 5). |
| INSTALL_SINFIX | Whether to use suffix/infix for installation (see step 5). |
| USE_<Pkg> | If the software you are building has declared optional dependencies, i.e., software packages which it makes use of if available, for each such optional package a USE_<Pkg> option is added by BASIS if this package was found on your system. It can be set to OFF in order to disable the use of this optional dependency by this software. |
Note that INSTALL_PREFIX is initialized by the value of CMAKE_INSTALL_PREFIX, the default used by CMake to specify the installation prefix. Then, the value of CMAKE_INSTALL_PREFIX is forced to be identical to INSTALL_PREFIX, effectively renaming CMAKE_INSTALL_PREFIX to INSTALL_PREFIX.
The advanced CMake settings are:
| Option/Variable | Descripion |
|---|---|
| BASIS_COMPILE_SCRIPTS | Enable compilation of Python modules. If this option is enabled, only the compiled .pyc files are installed. |
| BASIS_DEBUG | Enable debugging messages during build configuration. |
| BASIS_INSTALL_SINFIX | The sinfix to use for the installation if INSTALL_SINFIX is set to ON. Otherwise, this values is ignored. |
| BASIS_MCC_FLAGS | Additional flags for MATLAB Compiler. |
| BASIS_MCC_MATLAB_MODE | Whether to call the MATLAB Compiler in MATLAB mode. If ON, the MATLAB Compiler is called from within a MATLAB interpreter session, which results in the immediate release of the MATLAB Compiler license once the compilation is done. Otherwise, the license is reserved for a fixed amount of time (e.g. 30 min). |
| BASIS_MCC_RETRY_ATTEMPTS | Number of times the compilation of MATLAB Compiler target is repeated in case of a license checkout error. |
| BASIS_MCC_RETRY_DELAY | Delay in seconds between retries to build MATLAB Compiler targets after a license checkout error has occurred. |
| BASIS_MCC_TIMEOUT | Timeout in seconds for the build of a MATLAB Compiler target. If the build of the target could not be finished within the specified time, the build is interrupted. |
| BASIS_MEX_FLAGS | Additional flags for the MEX script. |
| BASIS_MEX_TIMEOUT | Timeout in seconds for the build of MEX-files. |
| BASIS_VERBOSE | Enable verbose messages during build configuration. |
| INSTALL_APIDOC_DIR | Installation directory of the API documentation relative to the INSTALL_PREFIX. |
Please refer also to the package specific build instructions given in the INSTALL file of the corresponding package which is located in the root directory of the source tree or the 'doc' directory of the installation. In this document, additional project specific CMake variables and options may be listed.
ccmake tool also provides a brief description to each variable in the status bar.To build the package executables and libraries, run GNU Make in the root directory of the configured build tree, i.e.,
make
In order to build the documentation, the BUILD_DOCUMENTATION variable has to be set to ON. If not done before, this option can be enabled by using the command:
cmake -D BUILD_DOCUMENTATION=ON ~/$pkg-build
The documentation is build by building the "doc" target, i.e.,
make doc
If the BUILD_DOCUMENTATION option has been set to ON before, the doc target has already been build as part of the software build itself, i.e., when running make as in step 3.
The advanced INSTALL_APIDOC_DIR CMake variable can be set to an absolute path or a path relative to the INSTALL_PREFIX directory in order to modify the installation directory for the API documentation which is generated from the in-source comments. This can be useful, for example, to install the documentation in the document directory of a web server.
If the source tree is a Subversion working copy and you have access to the Subversion repository of the project or if the project source tree is a Git repository, a ChangeLog file can be generated from the commit history by building the "changelog" target, i.e.,
make changelog
In case of Subversion, be aware that the generation of the ChangeLog takes several minutes and may require the input of your user credentials for access to the Subversion repository. Moreover, if the command svn2cl is installed on your system, it will be used to format the ChangeLog. Otherwise, the plain output of the svn log command is used.
First, make sure that the CMake variables INSTALL_PREFIX and INSTALL_SINFIX are set properly by running CMake as follows:
cmake -D "INSTALL_PREFIX=<prefix>" -D "INSTALL_SINFIX=ON|OFF" ~/$pkg-build
This can be omitted if these variables were set already during the configuration of the build tree or if the default values should be used. On Linux, INSTALL_PREFIX is by default set to "/usr/local". Note that the following strings can be used in the specification of this variable which will be substituted by the corresponding package specific values.
| Pattern | Description |
|---|---|
| @PROJECT_NAME@ | The case-sensitive name of the software package. |
| @PROJECT_NAME_UPPER@ | The name of the package in uppercase only. |
| @PROJECT_NAME_LOWER@ | The name of the package in lowercase only. |
| @PROJECT_VERSION@ | The package version. |
| @PROJECT_VERSION_MAJOR@ | The major number of the package version. |
| @PROJECT_VERSION_MINOR@ | The minor number of the package version. |
| @PROJECT_VERSION_PATCH@ | The patch number of the package version. |
After the package was configured successfully, the executables and auxiliary files can be installed using the command
make install
in the root directory of the build tree. This will copy the installation files into the directories specified during the configuration step.
The package files are installed in the following locations:
| Directory | Installed Files |
|---|---|
| <prefix>/bin/<prefix>/ | Main executable files. |
| <prefix>/etc/<prefix>/ | Package configuration files. |
| <prefix>/include/sbia/<package>/ | Include files, where <prefix>/include/ is the directory that needs to be in the search path for include files. |
| <prefix>/lib/<prefix>/ | Libraries and auxiliary executables. |
| <prefix>/lib/python/sbia/<package> | Python modules. |
| <prefix>/lib/perl5/SBIA/<Package> | Perl modules. |
| <prefix>/share/<sinfix>/doc/ | Package documentation files. |
| <prefix>/share/<sinfix>/example/ | Files required to run example as described in the User Manual. |
| <prefix>/share/<sinfix>/man/man.1 | Man pages of main executables. |
| <prefix>/share/<prefix>/man/man.3 | Man pages of library functions. |
where <prefix> is the value of INSTALL_PREFIX and <sinfix> is an empty string if INSTALL_SINFIX is OFF and the package name in lowercase otherwise preceded by the common infix "sbia/" (the default).
If more than one version of a software package shall be installed, include the package version in the <prefix> by setting INSTALL_PREFIX to "/usr/local/@PROJECT_NAME_LOWER@-@PROJECT_VERSION@", for example, and disable the use of the <sinfix> by setting INSTALL_SINFIX to OFF.
Additionally, if both INSTALL_SINFIX and INSTALL_LINKS are ON (the default), the following (symbolic) links are created on UNIX-based systems:
| Link | Value |
|---|---|
| <prefix>/bin/<exec> | <prefix>/bin/<sinfix>/<exec> |
| <prefix>/share/man/man.1/<exec>.1 | <prefix>/share/<sinfix>/man/man.1/<exec>.1 |
| <prefix>/share/man/man.3/<func>.3 | <prefix>/share/<sinfix>/man/man.3/<func>.3 |
After the successful installation, the build tree can be deleted.
In order to ease the execution of the main executable files, we suggest to add either the path ~/$pkg-build/bin/ or <prefix>/bin/ to the search path for executable files, i.e., the PATH environment variable. This is, however, generally no requirement for the correct functioning of the software.
For example,
export PATH="<prefix>/bin/:<prefix>/bin/<sinfix>/:${PATH}"
To be able to use the Python modules of a SBIA software package in your own Python scripts, you need to add the path <prefix>/python/ to the search path for Python modules, e.g.,
export PYTHONPATH="${PYTHONPATH}:<prefix>/lib/python/"
or in your Python script
#! /usr/bin/env python import sys sys.path.append('<prefix>/lib/python/') from sbia.<package> import <module>
To be able to use the Perl modules of a SBIA software package in your own Perl scripts, you need to add the path <prefix>/perl5/ to the search path for Perl modules, e.g.,
export PERL5LIB="${PERL5LIB}:<prefix>/lib/perl5/"
or in your Perl script
use lib '<prefix>/lib/perl5';
use SBIA::<Package>::<Module>;
In order to undo the installation of the package files built from the sources, run the following command in the root directory of the build tree which was used to install the package
cd ~/$pkg-build make uninstall
During the installation, a manifest of all installed files and a CMake script which reads in this list in order to remove these files again is generated and installed in <prefix>/lib/cmake/<package>/.
If INSTALL_SINFIX was set to ON during the installation, a shell script named "uninstall" was written to the <prefix>/bin/<sinfix>/ directory on Unix and a corresponding Batch file on Windows. Additionally, if INSTALL_LINKS was set to ON, a symbolic link named "uninstall_<package>" was created in <prefix>/bin/. Otherwise, if INSTALL_SINFIX was set to OFF, the uninstaller is located in <prefix>/bin/ and named "uninstall_<package>".
Hence, in order to remove all files installed by this package as well as the empty directories left behind inside the installation root directory given by <prefix>, run the command
uninstall_<package>
assuming that you added <prefix>/bin/ to your PATH environment variable.
The advantage of the uninstaller is, that the build tree is no longer required in order to uninstall the software package. Thus, you do not need to keep a copy of the build tree once you installed the software only to be able to uninstall the package again.