Cinch is a set of utilities and configuration options designed to make cmake builds easy to use and manage.
Cinch uses standard CMake install features. However, because Cinch depends on its own command-line tool (Cinch-Utils) to build its documentation, it must be installed in the stages documented in this section.
Directions for installing cinch-utils are here.
To install the Cinch documentation, you should run cmake in the Cinch build directory with documentation enabled:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
The Cinch build system is designed to make modular code development easy. By modular, we mean that subprojects can be incorporated into a Cinch-based top-level project, and they will be automatically added to the top-level project's build targets. This makes it easy to create new projects that combine the capabilities of a set of subprojects. This allows users to build up functionality and control the functionality of the top-level project.
Cinch prohibits users from creating in-place builds, i.e., builds that are rooted in the top-level project directory of a Cinch project. If the user attempts to configure such a build, cmake will exit with an error and instructions for how to clean up and create an out-of-source build.
Cinch eases build system maintainence by imposing a specific structure on the project source layout.
project/
app/ (optional application subdirectory)
cinch/
CMakeLists.txt -> cinch/cmake/ProjectLists.txt
config/
documentation.cmake
packages.cmake
project.cmake
doc/
src/ (optional library source subdirectory)
CMakeLists.txt -> cinch/cmake/SourceLists.txt
You may also have any number of submodules under the project directory.
The project top-level directory.
An application target subdirectory. Application targets can be added using the cinch_add_application_directory documented below. This subdirectory should contain a CMakeLists.txt file that adds whatever cmake targets are needed for the specific application.
The Cinch subdirectory. This should be checked-out from the Cinch git server: 'git clone --recursive git@github.com:losalamos/cinch.git'.
Create a file, whichs sets cmake_minimum_required() and includes the Cinch ProjectLists.txt file.
The project configuration directory. This directory is covered in detail below.
The documentation subdirectory. This subdirectory should contain configuration files for Cinch-generated guide documentation, and for doxygen interface documentation.
A library target source subdirectory. Library targets can be added using the cinch_add_library_target documented below.
The config subdirectory must contain the following files that provide specialization of the project. Although all of the files must exist, the only file that is required to have content is the project.cmake file.
This file cannot be empty. At a minimum, it must specify the name of the top-level project by calling the CMake project function to set the name, version and enabled languages for the entire project. For more documentation, at a prompt on a machine with a valid CMake installation, type:
% cmake --help project
Additionally, this file may call the following Cinch function (They may also be left Null):
-
cinch_add_application_directory (documented here)
Add a project-specific build directory that should be included by CMake when searching for list files. This directory should contain a valid CMakeLists.txt file that configures additional build targets.
-
cinch_add_library_target (documented here)
Add a library target to build for this project.
-
cinch_add_subproject (documented here)
Add a subproject to this project.
This file is used to specify CMake find_package requirements for locating installed third-party packages. The content of this file can be any set of valid CMake commands. Values that are set in this file will be available to low-level CMakeLists.txt files for configuring source-level build options.
This file is used to add documentation targets with the cinch_add_doc interface (Doxygen documentation is handled separately).
Cinch provides various command-line options that may be passed on the cmake configuration line to affect its behavior.
CMake Option: ENABLE_CINCH_DEVELOPMENT (default OFF)
Put Cinch into development mode. This option effects some of the information that is generated by Cinch which is helpful for non-release candidates. If this option is enabled, it will turn on the following features:
- Documentation Target Annotation
Documentation targets will have colorized output indicating the source inputs for each section of the documentation.
CMake Option: ENABLE_CINCH_VERBOSE (default OFF)
Enable more detailed build output.
CMake Option: ENABLE_DOCUMENTATION (default OFF)
Cinch has a powerful documentation facility implemented using the Cinch command-line utility and Pandoc. To create documentation, define a configuration file for each document that should be created in the 'doc' subdirectory. Then, add markdown (.md) or latex (.tex) files to the source tree that document whichever aspects of the project should be included. The caveat is that these documentation fragments should have a special comment header at the beginning of each, of the form:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
This special header indicates for which document the fragment is intended
and the section within which it should appear. Headers may span
multiple lines provided that <!-- CINCHDOC begins the comment.
If no attributes
(DOCUMENT, SECTION, etc.) are specified, the utility will use a
default document and section ('Default' and 'Default'). Multiple
fragments intended for different documents and sections may be included
within a single input file. For latex fragments, use a header of the form:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
Latex-style CINCHDOC headers must be on a single line.
Build targets can be added to the documentation.cmake file in the config directory. Each target should be created by calling:
cinch_add_doc(target-name config.py top-level-search-directory output)
target-name The build target label, i.e., a make target will be created such that 'make target-name' can be called to generate the documentation target.
config.py A configuration file that must live in the 'doc' subdirectory of the top-level directory of your project. This file should contain a single python dictionary opts that sets the Cinch command-line interface options for your docuement.
top-level-search-directory The relative path to the head of the directory tree within which to search for markdown documentation files.
output The name of the output file that should be produced by pandoc.
CMake Option: ENABLE_DOXYGEN (default OFF)
Cinch supports interface documentation using Doxygen. The doxygen configuration file should be called 'doxygen.conf.in' and should reside in the 'doc' subdirectory. For documentation on using Doxygen, please take a look at the Doxygen Homepage.
CMake Option: ENABLE_UNIT_TESTS (default OFF)
Cinch has support for unit testing using a combination of CTest (the native CMake testing facility) and GoogleTest (for C++ support). If unit tests are enabled, Cinch will create a 'test' target. Unit tests may be added in any subdirectory of the project simply be creating the test source code and adding a target using the 'cinch_add_unit(target [source list])' function.
Cinch will check for a local GoogleTest installation on the system during the Cmake configuration step. If GoogleTest is not found, it will be built by Cinch (GoogleTest source code is included with Cinch).
CMake Option: VERSION_CREATION (default 'git describe')
Cinch can automatically create version information for projects that use git. This feature uses the 'git describe' function, which creates a version from the most recent annotated tag with a patch level based on the number of commits since that tag and a partial hash key. For example, if the most recent annotated tag is "1.0" and there have been 35 commits since, the Cinch-created version would be similar to: 1.0-35-g2f657a
For actual releases, this approach may not be optimal. In this case, Cinch allows you to override the automatic versioning by specifying a static version to cmake via the VERSION_CREATION option. Simply set this to the desired version and it will be used.
This software has been approved for open source release and has been assigned LA-CC-15-070.
Copyright (c) 2016, Los Alamos National Security, LLC All rights reserved.
Copyright 2016. Los Alamos National Security, LLC. This software was produced under U.S. Government contract DE-AC52-06NA25396 for Los Alamos National Laboratory (LANL), which is operated by Los Alamos National Security, LLC for the U.S. Department of Energy. The U.S. Government has rights to use, reproduce, and distribute this software. NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE. If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.
Additionally, redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of Los Alamos National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LOS ALAMOS NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.