Repository files navigation

Cinch is a set of utilities and configuration options designed to makecmake builds easy to use and manage.

Cinch uses standard CMake install features. However, because Cinch dependson 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 arehere.

To install the Cinch documentation, you should run cmake in the Cinchbuild 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-basedtop-level project, and they will be automatically added to the top-levelproject's build targets. This makes it easy to create new projects thatcombine the capabilities of a set of subprojects. This allows users tobuild up functionality and control the functionality of the top-levelproject.

Cinch prohibits users from creating in-place builds, i.e., builds that arerooted in the top-level project directory of a Cinch project. If the userattempts to configure such a build, cmake will exit with an error andinstructions for how to clean up and create an out-of-source build.

Cinch eases build system maintainence by imposing a specific structure onthe 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 addedusing thecinch_add_application_directory documentedbelow. This subdirectoryshould contain a CMakeLists.txt file that adds whatever cmake targets areneeded for the specific application.

The Cinch subdirectory. This should be checked-out from the Cinchgit server: 'git clone --recursivegit@github.com:losalamos/cinch.git'.

Create a file, whichs setscmake_minimum_required() and includes the Cinch ProjectLists.txt file.

The project configuration directory. This directory is covered indetailbelow.

The documentation subdirectory. This subdirectory should contain configurationfiles for Cinch-generatedguide documentation, andfordoxygen interface documentation.

A library target source subdirectory. Library targets can be addedusing thecinch_add_library_target documentedbelow.

The config subdirectory must contain the following filesthat provide specialization of the project. Although all ofthe files must exist, the only file that is required to have contentis theproject.cmake file.

This file cannot be empty. At a minimum, it must specify the nameof the top-level project by calling the CMakeproject function toset the name, version and enabled languages for the entire project.For more documentation, at a prompt on a machine with a valid CMakeinstallation, type:

% cmake --help project

Additionally, this file may call the following Cinchfunction (They may also be left Null):

• cinch_add_application_directory (documentedhere)

  Add a project-specific build directory that should be includedby CMake when searching for list files. This directory should containa valid CMakeLists.txt file that configures additional build targets.

• cinch_add_library_target (documentedhere)

  Add a library target to build for this project.

• cinch_add_subproject (documentedhere)

  Add a subproject to this project.

This file is used to specify CMake find_package requirements forlocating installed third-party packages. The content of this filecan be any set of valid CMake commands. Values that are set in thisfile will be available to low-level CMakeLists.txt files for configuringsource-level build options.

This file is used to add documentation targets with thecinch_add_docinterface (Doxygen documentation is handled separately).

Cinch provides various command-line options that may be passed on the cmakeconfiguration line to affect its behavior.

CMake Option:ENABLE_CINCH_DEVELOPMENT (default OFF)

Put Cinch into development mode. This option effects some of the informationthat 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 sourceinputs 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 Cinchcommand-line utility andPandoc.To create documentation, define aconfiguration file for each document that should be created in the 'doc'subdirectory. Then, add markdown (.md) or latex (.tex) files to the sourcetree that document whichever aspects of the project should be included. Thecaveat is that these documentation fragments should have a special commentheader 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 intendedand the section within which it should appear. Headers may spanmultiple lines provided that<!-- CINCHDOC begins the comment.If no attributes(DOCUMENT, SECTION, etc.) are specified, the utility will use adefault document and section ('Default' and 'Default'). Multiplefragments intended for different documents and sections may be includedwithin 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 configdirectory. 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 createdsuch that 'make target-name' can be called to generate the documentationtarget.

config.py A configuration file that must live in the 'doc' subdirectoryof the top-level directory of your project. This file should contain asingle python dictionaryopts that sets the Cinch command-lineinterface options for your docuement.

top-level-search-directory Therelative path to the head of thedirectory 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 doxygenconfiguration file should be called 'doxygen.conf.in' and should residein the 'doc' subdirectory. For documentation on using Doxygen, pleasetake a look at theDoxygen 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 testsmay be added in any subdirectory of the project simply be creating thetest 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 duringthe Cmake configuration step. If GoogleTest is not found, it will bebuilt 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 fromthe most recent annotated tag with a patch level based on the number ofcommits since that tag and a partial hash key. For example, if the mostrecent annotated tag is "1.0" and there have been 35 commits since, theCinch-created version would be similar to: 1.0-35-g2f657a

For actual releases, this approach may not be optimal. In this case, Cinchallows you to override the automatic versioning by specifying a static versionto cmake via the VERSION_CREATION option. Simply set this to thedesired version and it will be used.

This software has been approved for open source release and has been assignedLA-CC-15-070.

Copyright (c) 2016, Los Alamos National Security, LLCAll 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:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. 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.

3. 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.