cinch
Release 1.0
Cinch是一组实用程序和配置选项，旨在使CMAKE构建易于使用和管理。
Cinch使用标准的CMAKE安装功能。但是，由于Cinch取决于其自己的命令行工具（Cinch-Utils）来构建其文档，因此必须将其安装在本节中记录的阶段中。
安装cinch-utils的说明在这里。
要安装cinch文档，您应该在启用文档的cinch build目录中运行cmake：
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
Cinch Build System旨在使模块化代码开发变得容易。通过模块化，我们的意思是，可以将子项目纳入基于CINC的顶级项目中，并且它们将自动添加到顶级项目的构建目标中。这使得创建结合一组子弹的功能的新项目变得容易。这使用户可以构建功能并控制顶级项目的功能。
Cinch禁止用户创建现场构建，即构建源自Cinch项目的顶级项目目录。如果用户试图配置这种构建，则CMAKE将出于错误和指令即可清理和创建源源外构建。
Cinch通过在项目源布局上施加特定结构来简化构建系统的维护。
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
您也可以在项目目录下有任何数量的子模型。
该项目顶级目录。
应用程序目标子目录。可以使用下面记录的cinch_add_application_directory添加应用程序目标。该子目录应包含一个cmakelists.txt文件，该文件添加了特定应用程序所需的任何CMAKE目标。
cinch子目录。应从Cinch Git服务器进行检查：'git clone-recursive [email protected]：losalamos/cinch.git'。
创建一个文件，该文件设置cmake_minimum_required（） ，并包括cinch projectLists.txt文件。
项目配置目录。该目录在下面详细介绍。
文档子目录。此子目录应包含用于Cinch生成的指南文档的配置文件，以及Doxygen接口文档。
库目标源子目录。可以使用下面记录的cinch_add_library_target添加库目标。
配置子目录必须包含以下提供项目专业化的文件。尽管所有文件都必须存在，但具有内容的唯一文件是project.cmake文件。
这个文件不能为空。至少，它必须通过调用CMAKE项目功能来为整个项目设置名称，版本和启用语言来指定顶级项目的名称。有关更多文档，请在具有有效CMAKE安装的机器上提示，键入：
％cmake -HELP项目
此外，此文件可以调用以下cinch函数（它们也可以剩下null）：
cinch_add_application_directory（在此记录）
添加一个特定于项目的构建目录，在搜索列表文件时应包含CMAKE。该目录应包含有效的cmakelists.txt文件，该文件配置其他构建目标。
cinch_add_library_target（在此处记录）
添加一个库目标以为该项目构建。
cinch_add_subproject（在此处记录）
在此项目中添加一个子项目。
该文件用于指定用于定位已安装的第三方软件包的CMAKE FIND_PACKAGE要求。该文件的内容可以是任何有效的cmake命令集。该文件中设置的值将用于低级cmakelists.txt文件，用于配置源级构建选项。
该文件用于使用cinch_add_doc接口添加文档目标（单独处理doxygen文档）。
Cinch提供了各种命令行选项，可以在CMAKE配置线上传递以影响其行为。
cmake选项： enable_cinch_development（默认关闭）
将Cinch纳入开发模式。此选项会影响Cinch生成的某些信息，这对非释放候选人有帮助。如果启用了此选项，它将打开以下功能：
cmake选项： enable_cinch_verbose（默认关闭）
启用更详细的构建输出。
cmake选项： enable_documentation（默认关闭）
Cinch拥有使用Cinch命令行实用程序和Pandoc实施的强大文档设施。要创建文档，请为每个文档定义一个应在“ DOC”子目录中创建的配置文件。然后，将标记（.md）或乳胶（.tex）文件添加到文档中，该文件应包括项目的哪个方面。需要注意的是，这些文档片段应在每种形式的开头时具有特殊的评论标题：
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
此特殊标题指示该片段的意图以及应在其中显示的部分。如果<!-- CINCHDOC开始评论，则标题可能跨越多行。如果未指定属性（文档，部分等），则该实用程序将使用默认文档和部分（'默认值'和'默认值'）。单个输入文件中可以包含用于不同文档和部分的多个片段。对于乳胶片段，请使用形式的标头：
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
乳胶风格的cinchdoc标头必须在一条线上。
可以将构建目标添加到Config Directory中的文档中的文件。每个目标都应通过调用：
cinch_add_doc （target-name config.py顶级搜索目录输出）
目标名称构建目标标签，即，将创建一个制造目标，以便可以调用“制造目标名称”以生成文档目标。
config.py必须播放项目顶级目录的“ DOC”子目录中的配置文件。该文件应包含一个单个Python字典选择，该字典为您的文档设置了cinch命令行界面选项。
顶级搜索指导到目录树的头部的相对路径在其中搜索标记文档文件。
输出应由Pandoc生成的输出文件的名称。
cmake选项： enable_doxygen（默认关闭） cmake选项： enable_doxygen_warn（默认为OFF）
Cinch使用doxygen支持接口文档。 doxygen配置文件应称为'doxygen.conf.in'，并应位于“ doc”子目录中。有关使用Doxygen的文档，请查看Doxygen首页。
如果将ENABLE_DOXYGEN_WARN设置为ON，则不会抑制正常的Doxygen诊断和警告。
cmake选项： enable_unit_tests（默认关闭）
Cinch使用CTEST（本机Cmake测试设施）和Googletest（用于C ++支持）的组合来支持单位测试。如果启用了单元测试，CINCH将创建一个“测试”目标。可以在项目的任何子目录中添加单元测试，只是创建测试源代码并使用'cinch_add_unit（target [source list]）'函数添加目标。
Cinch将在CMAKE配置步骤中检查系统上的本地Googletest安装。如果找不到googletest，它将由cinch构建（cinch包含googletest源代码）。
cmake选项： clog_enable_stdlog（默认关闭）
cmake选项： clog_strip_level（默认“ 0”）
cmake选项： clog_tag_bits（默认为“ 16”）
cmake选项： clog_color_output（默认关闭）
Cinch支持跟踪，信息，警告，错误和致命日志报告（类似于Google日志）。有两种接口样式用于使用Clog：插入样式，例如
clog (info) << "This is some information" << std::endl;和方法接口，例如
clog_info ( " This is some information " );两种接口样式均适用于所有严重性级别（下面讨论）。
注意：堵塞可自动用于cinch单元测试。
clog_init ( " group1,group2,group3 " ); clog (error) << "This is an error level severity message" << std::endl; clog_info ( " The number is " << number); clog_every_n（严重性，消息，n）
使用严重性和消息输出每次迭代。该方法未针对致命的严重程度或断言定义。
clog_assert（测试，消息）
断言该测试是正确的。如果测试是错误的，则此调用将执行clog_fatal（消息） 。
clog_add_buffer（name，ostream，着色）
添加由RDBUF（）中的Ostream参数定义的缓冲区。第二个参数名称是要与缓冲区相关联的字符串名称，可用于堵塞缓冲区接口的随后调用。最后一个参数指示缓冲区是否支持颜色输出。
clog_enable_buffer（名称）
启用按名称标识的缓冲区。
clog_disable_buffer（名称）
禁用按名称标识的缓冲区。
堵塞可以一次将输出写入多个输出流。用户可以通过添加和启用/禁用各种输出流来控制哪些堵塞日志文件和输出。默认情况下，Clog将输出定义为std :: clog（这是默认的C ++日志iostream，而不是clog的一部分）。其他输出流必须由用户应用程序添加。例如，如果用户应用程序希望堵塞输出转到名为output.log的文件，则可以执行以下操作：
# include < ofstream >
# include " cinchlog.h "
int main ( int argc, char ** argv) {
// Initialize CLOG with output for all tag groups (discussed below)
clog_init ( " all " );
// Open an output stream for "output.log"
std::ofstream output ( " output.log " );
// Add the stream to CLOG:
// param 1 ("output") The string name of the buffer.
// param 2 (output) The stream (CLOG will call stream.rdbuf() on this).
// param 3 (false) A boolean denoting whether or not the buffer
// supports colorization.
//
// Note that output is automatically enabled for buffers when they
// are added. Buffers can be disable with clog_disable_buffer(string name),
// and re-enabled with clog_enable_buffer(string name).
clog_add_buffer ( " output " , output, false );
// Write some information to the output file (and to std::clog if enabled)
clog (info) << " This will go to output.log " << std::endl;
return 0 ;
} // main可以通过指定特定的严重性水平来控制木log输出。任何比Clog_Strip_level指定的消息级别低的记录消息都将被禁用。请注意，这意味着堵塞不会为clog_strip_level> = 5产生输出。
不同的严重程度具有以下行为：
痕迹
仅适用于严重程度0（小于1）
跟踪输出适用于细粒度的记录信息。
信息
启用了小于2的严重性水平
信息输出适用于正常的记录信息。
警告
启用了小于3的严重程度
警告输出对于发出警告很有用。当启用Clog_Color_Output时，警告消息将以黄色显示。
错误
启用了小于4的严重程度
错误输出对于发出非致命错误很有用。当启用Clog_color_output时，将以红色显示错误消息。
致命的
启用了小于5的严重程度
致命错误输出对于发出致命错误很有用。致命错误会打印一条消息，丢弃当前的堆栈跟踪，然后调用std :: exit（1）。当启用Clog_color_output时，将以红色显示致命消息。
通过在源代码中添加范围的范围，可以对堵塞输出的运行时控制。这些被称为标签组，因为示波器部分用标签标记。可能的标签组的数量由clog_tag_bits控制（默认为16）。通过将标签组指定为Clog_Init函数，可以在运行时启用或禁用标签组。通常，这些由用户应用程序解释的命令行标志控制。这是使用GFLAGS控制输出的示例代码：
# include < gflags/gflags.h >
// Create a command-line flag "--groups" with default value "all"
DEFINE_string (groups, " all " , " Specify the active tag groups " );
# include " cinchlog.h "
int main ( int argc, char ** argv) {
// Parse the command-line arguments
gflags::ParseCommandLineFlags (&argc, &argv, true );
// If the user has specified tag groups with --groups=group1, ...
// these groups will be enabled. Recall that the default is "all".
clog_init (FLAGS_groups);
{
// Create a new tag scope. Log messages within this scope will
// only be output if tag group "tag1" or tag group "all" is enabled.
clog_tag_scope (tag1);
clog (info) << " Enabled for tag group tag1 " << std::endl;
clog (warn) << " This is a warning in group tag1 " << std::endl;
} // scope
{
// Create a new tag scope. Log messages within this scope will
// only be output if tag group "tag2" or tag group "all" is enabled.
clog_tag_scope (tag2);
clog (info) << " Enabled for tag group tag2 " << std::endl;
clog (error) << " This is an error in group tag2 " << std::endl;
} // scope
clog (info) << " This output is not scoped " << std::endl;
return 0 ;
} // main示例代码运行：
% ./example --groups=tag1
% [I1225 11:59:59 example.cc:22] Enabled for tag group tag1
% [W1225 11:59:59 example.cc:24] This is a warning in group tag1
% [I1225 11:59:59 example.cc:37] This output is not scoped
% ./example --groups=tag2
% [I1225 11:59:59 example.cc:32] Enabled for tag group tag1
% [E1225 11:59:59 example.cc:34] This is an error in group tag2
% [I1225 11:59:59 example.cc:37] This output is not scoped
% ./example
% [I1225 11:59:59 example.cc:22] Enabled for tag group tag1
% [W1225 11:59:59 example.cc:24] This is a warning in group tag1
% [I1225 11:59:59 example.cc:32] Enabled for tag group tag1
% [E1225 11:59:59 example.cc:34] This is an error in group tag2
% [I1225 11:59:59 example.cc:37] This output is not scoped
正常的堵塞界面是通过一组宏实现的。需要更大控制堵塞的高级用户可以创建自己的接口（宏或其他），以直接访问低级堵塞接口。 clog中的日志消息源自cinch :: log_message_t类型，该类型提供构造函数，虚拟驱动器和虚拟流方法：
template < typename P>
struct log_message_t
{
// Constructor:
// param 1 (file) The originating file of the message (__FILE__)
// param 2 (line) The originating line of the mesasge (__LINE__)
// param 3 (predicate) A predicate function that can be used to
// control output.
log_message_t (
const char * file,
int line,
P && predicate
)
{
// See cinchlog.h for implementation.
} // log_message_t
// Destructor.
virtual
~log_message_t ()
{
// See cinchlog.h for implementation.
} // ~log_message_t
// Stream method.
virtual
std::ostream &
stream ()
{
// See cinchlog.h for implementation.
} // stream
}; // struct log_message_t希望自定义堵塞的用户可以通过覆盖这种类型的虚拟方法以及提供自定义谓词来改变默认行为。以这种方式实现了许多基本堵塞功能，例如，以下代码实现了跟踪级别的严重性输出：
# define severity_message_t ( severity, P, format )
struct severity ## _log_message_t
: public log_message_t <P>
{
severity ## _log_message_t (
const char * file,
int line,
P && predicate = true_state)
: log_message_t <P>(file, line, predicate) {}
~severity ## _log_message_t ()
{
/* Clean colors from the stream */
clog_t::instance (). stream () << COLOR_PLAIN;
}
std::ostream &
stream () override
/* This is replaced by the scoped logic */
format
};
// ----------------------------------------------------------------------------//
// Define the insertion style severity levels.
// ----------------------------------------------------------------------------//
# define message_stamp
timestamp () << " " << rstrip<'/'>(file_) << ":" << line_
severity_message_t(trace, decltype(cinch::true_state),
{
# if CLOG_STRIP_LEVEL < 1
if ( clog_t::instance (). tag_enabled () && predicate_ ()) {
std::ostream & stream = clog_t::instance (). stream ();
stream << OUTPUT_CYAN ( " [T " ) << OUTPUT_LTGRAY (message_stamp);
stream << OUTPUT_CYAN ( " ] " );
return stream;
}
else {
return clog_t::instance (). null_stream ();
} // if
# else
return clog_t::instance (). null_stream ();
# endif
});有兴趣的用户应查看源代码以获取更多示例。
cmake选项： version_creation（默认'git描述'）
Cinch可以自动为使用Git的项目创建版本信息。此功能使用“ git描述”函数，该功能根据该标签和部分哈希键，从最新的注释标签中创建一个版本，该版本具有基于补丁的级别。例如，如果最新的注释标签是“ 1.0”，并且从那以后进行了35个提交，则cinch创建的版本将类似于：1.0-35-G2F657A
对于实际发行版，这种方法可能不是最佳的。在这种情况下，CINCH允许您通过通过version_creation选项指定静态版本来覆盖自动版本。只需将其设置为所需的版本即可使用。
该软件已被批准用于开源发布，并已分配了LA-CC-15-070 。
版权所有（C）2016，Los Alamos National Security，LLC保留所有权利。
版权所有2016。LosAlamos National Security，LLC。该软件是根据美国政府合同DE-AC52-06NA25396的Los Alamos国家实验室（LANL）生产的，该软件由Los Alamos National Security，LLC为美国能源部运营。美国政府有权使用，复制和分发此软件。政府和洛斯阿拉莫斯国家安全，有限责任公司均不对使用本软件的任何保证，明示或暗示任何保修，也不承担任何责任。如果修改软件以生成衍生作品，则应明确标记此类修改的软件，以免将其与LANL可用的版本混淆。
此外，只要满足以下条件：
源代码的再分配必须保留上述版权通知，此条件列表和以下免责声明。
二进制形式的重新分配必须复制上述版权通知，此条件列表以及文档和/或分发提供的其他材料中的以下免责声明。
Los Alamos National Security，LLC，Los Alamos National Laboratory，Lanl，美国政府的名称都不是未经特定事先书面许可而在此软件的情况下使用该软件衍生出的产品的名称。
该软件由Los Alamos National Security，LLC和贡献者“原样”提供，以及任何明示或暗示的担保，包括但不限于对特定目的的适销性和适用性的隐含保证。洛斯阿拉莫斯国家安全，有限责任公司或贡献者均不对任何直接，间接，偶然，特殊，特殊，示例性或结果损失负责（包括但不限于替代商品或服务的采购；数据，数据，数据，数据，数据，数据，数据，数据，数据，数据，数据然而这样的损害。
