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和貢獻者“原樣”提供，以及任何明示或暗示的擔保，包括但不限於對特定目的的適銷性和適用性的隱含保證。洛斯阿拉莫斯國家安全，有限責任公司或貢獻者均不對任何直接，間接，偶然，特殊，特殊，示例性或結果損失負責（包括但不限於替代商品或服務的採購；數據，數據，數據，數據，數據，數據，數據，數據，數據，數據，數據然而這樣的損害。
