Software Project Template

Introduction

The starting point for every project is to setup a directory structure which helps to organize the project files. Moreover, in order to configure the build system using CMake, CMakeLists.txt files have to be added to the project with proper CMake code to add build targets with the corresponding build flags to the build system. In order to unify the structure of projects following common practices and further to simply take off the burder from the developer on setting up a basic project, BASIS provides a so-called (Software) Project Template. Please refer to the Filesystem Hierarchy Standard for a definition of the common project directory structure. This directory structure is part of the standard and thus required by BASIS. The project template therefore follows this standard regarding the directory structure. The further purpose of the software project template is to provide template files concerned with the configuration of the build, testing, installation, and packaging. In the following, the prupose of each template file is summarized.

Required Project Files

The following files have to be part of any project which follows the Filesystem Hierarchy Standard. These are thus the minimal set of project files which need to be selected when instantiating a new software project. Besides these files, a project will have either a src/ directory or a modules/ directory, or both of them. See below for a description of these directories.

Relative Path	Description
README.txt	This is the main (root) documentation file. Every user is supposed to first read this file, which in turn will refer them to the more extensive documentation. This file in particular introduces the software package shortly, including a summary of the package files. Moreover, it refers to the INSTALL.txt and COPYING.txt files for details on the build and installation and software license, respectively. Furthermore, references to scientific articles related to the software package shall be included in this file.
AUTHORS.txt	Names the authors of the software package. Moreover, people who notably contributed to the software directly shall be named here as well, even if they did not actually edit any project file. Others, who mostly contributed indirectly should be named in the README.txt file instead.
COPYING.txt	Contains copyright and license information. If some files of the project were copied from other sources, the copyright and license of these files shall be included in this file as well. It is important to clearly state which copyright and license text corresponds to which project file.
INSTALL.txt	Contains build and installation instructions. As the build of all projects which follow BASIS is very similar, this file shall only describe additional steps/CMake variables which are not described in the INSTALL-basis.txt document. The INSTALL-basis.txt file is part of the BASIS installation, and an HTML version is available at https://www.cbica.upenn.edu/sbia/software/installation.html
BasisProject.cmake	This file contains the meta-data of the project such as the project name, its brief description which is used for the packaging, and the dependencies. Note that additional dependencies may be given by the CMake code in the config/Depends.cmake file, if such file is present. This file mainly consists of a call to the basis_project() command. If the project is a module of another project, this file is read by the top-level project to be able to identify its modules and the dependencies among them.
CMakeLists.txt	The root CMake configuration file. Do not edit this file.

Common Project Files

Relative Path	Description
CTestConfig.cmake	The CTest configuration file. This file in particular specifies the URL of the CDash dashboard of the project where test results should be submitted to.
config/Settings.cmake	This is the main CMake script file used to configure the build system, and BASIS in particular. Any CMake code required to configure the build system, such as adding common compiler flags, or adding common definitions which have not yet been added by the generic code used by BASIS to utilize a found dependency should go into this file.
config/ScriptConfig.cmake.in	Please see the documentation on the Build of Script Targets for details on how this script configuration file is used.
data/CMakeLists.txt	This CMake configuration file contains code to simply install every file and directory from the source tree into the INSTALL_DATA_DIR directory of the installation tree.
doc/CMakeLists.txt	This CMake configuration file adds rules to build the documentation form, for example, the in-source comments using Doxygen. Moreover, for every documentation file, such as the user manual, the basis_add_doc() command has to be added to this file.
example/CMakeLists.txt	This CMake configuration file contains by default code to install every file and directory from the source tree into the INSTALL_EXAMPLE_DIR directory of the installation tree. It may be modified to configure and/or build certain files of the example if applicable or required.
src/CMakeLists.txt	The definition of all software build targets shall be added to this file, using the commands basis_add_library() to add a shared, static, or module library, which can also be a module written in a scripting language, and basis_add_executable() to add an executable target, which can be either a binary or a script file. If appropriate, the source code files may be further organized in subdirectories of the src/ directory, in which case either separate CMakeLists.txt files can be used for each subdirectory, or yet all targets are added to the src/CMakeLists.txt file using relative paths which include the subdirectory in which the source files are found. In general, if the number of source code files is low, i.e., close to or below 20, no subdirectory structure is required.
test/CMakeLists.txt	Tests are added to this build configuration file using the basis_add_test() command. The test input files are usually put in a subdirectory named test/input/, while the baseline data of the expected test output is stored inside a subdirectory named test/baseline/. Generally, however, the Filesystem Hierarchy Standard of BASIS does not dictate how the test sources, input, and baseline data are organized inside the test/ directory.
modules/	If the project files are organized into conceptual cohesive groups, similar to the modularization goal of the ITK 4, this directory contains these conceptual modules of the project. The files of each module reside in a subdirectory named after the module. Note that each module itself is a project derived from this project template.

Advanced Project Files

The customization of the following files is usually not required, and hence, in most cases, most of these files need not to be part of a project.

Relative Path	Description
config/Components.cmake	Contains CMake code to configure the components used by component-based installers. Currently, component-based installers are not very well supported by BASIS, and hence this file is mostly unused and is yet subject to change.
config/Config.cmake.in	This is the template of the package configuration file. When the project is configured/installed using CMake, a configured version of this file is copied to the build or installation tree, respectively, where the information about the package configuration is substituted as appropriate for the actual build/installation of the package. For example, the configured file contains the absolute path to the installed public header files such that other packages can easily add this path to their include search path. The find_package() command of CMake, in particular, will look for this file and automatically import the CMake settings when this software package was found. For many projects, the default package configuration file of BASIS which is used if this file is missing in the project's config/ directory, is sufficient and thus this file is often not required.
config/ConfigSettings.cmake	This file sets CMake variables for use in the config/Config.cmake.in file. As the package configuration for the final installation differs from the one of the build tree, this file has to contain CMake code to set the variables used in the config/Config.cmake.in file differently depending on whether the variables are being set for use within the build tree or the installation tree. This file only needs to be present if the project uses a custom config/Config.cmake.in file, which in turn contains CMake variables whose value differs between build tree and installation.
config/ConfigUse.cmake.in	This file is provided for convenience of the user of the software package. It contains CMake code which uses the variables set by the package configuration file (i.e., the file generated from the file config/Config.cmake.in) in order to configure the build system of packages which use this software packages properly such that they can make use of this software. For example, the package configuration sets a variable <Pkg>_INCLUDE_DIRS to a list of include directories which have to be added to the include search path. Then, this file would contain CMake instructions such as the line include_directories(${<Pkg>_INCLUDE_DIRS}) to actually add these directories to the search path for header files.
config/ConfigVersion.cmake.in	This file accompanies the package configuration file generated from the config/Config.cmake.in file. It is used by CMake's find_package() command to identify versions of this software package which are compatible with the version requested by the dependent project. This file needs almost never be customized by a project and thus should not be included in a project's source tree.
config/Depends.cmake	If the generic code used by BASIS is not sufficient to resolve the dependencies on external packages properly, add this file to your project. It can contain CMake code to find and make use of external software packages.
config/Package.cmake	Configures CPack, the package generator of CMake. The packaging of software using CPack is currently not completely supported by BASIS. This template file is yet subject to change.
CTestCustom.cmake.in	This file defines CTest variables which customize CTest.