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ビルドシステムは、モジュラーコード開発を容易にするように設計されています。モジュラーとは、サブプロジェクトをシンチベースのトップレベルプロジェクトに組み込むことができ、トップレベルのプロジェクトのビルドターゲットに自動的に追加されることを意味します。これにより、サブプロジェクトのセットの機能を組み合わせた新しいプロジェクトを簡単に作成できます。これにより、ユーザーは機能を構築し、トップレベルプロジェクトの機能を制御できます。
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を使用して追加できます。このサブディレクトリには、特定のアプリケーションに必要なCmakeターゲットを追加するCmakelists.txtファイルを含める必要があります。
シンチサブディレクトリ。これは、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-ヘルププロジェクト
さらに、このファイルは、次の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によって生成される情報の一部に影響します。このオプションが有効になっている場合、次の機能をオンにします。
cmakeオプション： enable_cinch_verbose（デフォルトオフ）
より詳細なビルド出力を有効にします。
cmakeオプション： enable_documentation（デフォルトオフ）
Cinchには、CinchコマンドラインユーティリティとPandocを使用して実装された強力なドキュメント施設があります。ドキュメントを作成するには、「doc」サブディレクトリで作成する必要がある各ドキュメントの構成ファイルを定義します。次に、プロジェクトのどの側面を含めるべきかを文書化するMarkDown（.MD）またはLaTex（.TEX）ファイルをソースツリーに追加します。警告は、これらのドキュメントフラグメントには、それぞれの先頭に特別なコメントヘッダーがあるはずです。
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
この特別なヘッダーは、ドキュメントがどのドキュメントが意図されているか、それが表示されるセクションを示します。 <!-- CINCHDOCコメントを開始すると、ヘッダーは複数の行にまたがる場合があります。属性（ドキュメント、セクションなど）が指定されていない場合、ユーティリティはデフォルトのドキュメントとセクション（「デフォルト」と「デフォルト」）を使用します。異なるドキュメントとセクションを対象とした複数のフラグメントは、単一の入力ファイルに含まれる場合があります。ラテックスフラグメントの場合、フォームのヘッダーを使用します。
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
ラテックススタイルのCinchdocヘッダーは、単一の行にある必要があります。
ビルドターゲットは、Config DirectoryのDocument.cmakeファイルに追加できます。各ターゲットは、呼び出して作成する必要があります。
CINCH_ADD_DOC （ターゲット名config.pyトップレベル - 検索ダイレクトリー出力）
Target-Nameビルドターゲットラベル、つまり、「ターゲットネーム」を呼び出してドキュメントターゲットを生成できるように、ターゲットが作成されます。
config.pyプロジェクトのトップレベルディレクトリの「doc」サブディレクトリに存在する必要がある構成ファイル。このファイルには、ドキュメントにCinchコマンドラインインターフェイスオプションを設定する単一のPython辞書Optsが含まれている必要があります。
トップレベルの検索ダイレクトリーMarkdownドキュメントファイルを検索するディレクトリツリーのヘッドへの相対パス。
出力Pandocが生成する必要がある出力ファイルの名前。
cmakeオプション： enable_doxygen（デフォルトオフ） cmakeオプション： enable_doxygen_warn（デフォルトオフ）
Cinchは、Doxygenを使用したインターフェイスドキュメントをサポートしています。 doxygen構成ファイルは「doxygen.conf.in」と呼ばれ、「doc」サブディレクトリに存在する必要があります。 Doxygenの使用に関するドキュメントについては、Doxygenのホームページをご覧ください。
enable_doxygen_warnがオンに設定されている場合、通常のドキシゲン診断と警告は抑制されません。
cmakeオプション： enable_unit_tests（デフォルトオフ）
Cinchは、CTEST（ネイティブCmakeテスト施設）とGoogleTest（C ++サポート用）の組み合わせを使用した単体テストをサポートしています。単体テストが有効になっている場合、Cinchは「テスト」ターゲットを作成します。プロジェクトの任意のサブディレクトリにユニットテストを追加することができます。テストソースコードを作成し、 'cinch_add_unit（ターゲット[ソースリスト]）'関数を使用してターゲットを追加します。
Cinchは、CMake構成ステップ中にシステムにローカルGoogleTestインストールを確認します。 GoogleTestが見つからない場合、Cinchによって構築されます（GoogleTestソースコードはCinchに含まれています）。
cmakeオプション： clog_enable_stdlog（デフォルトオフ）
cmakeオプション： clog_strip_level（デフォルト "0"）
cmakeオプション： clog_tag_bits（デフォルト "16"）
cmakeオプション： clog_color_output（デフォルトオフ）
Cinchには、Trace、Info、Warn、Error、および致命的なログレポート（Googleログと同様）のサポートがあります。詰まりを使用してロギング情報には2つのインターフェイススタイルがあります。
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）
重大度とメッセージを使用して、すべてのNTH反復を出力します。この方法は、致命的な重症度レベルやアサーションについて定義されていません。
clog_assert（テスト、メッセージ）
テストが真実であると主張します。テストがfalseの場合、この呼び出しはclog_fatal（メッセージ）を実行します。
clog_add_buffer（名前、ostream、colorized）
rdbuf（）のostream引数によって定義されたバッファーを追加します。 2番目のパラメーター名は、バッファに関連付けるための文字列名で、後続の呼び出しでClogバッファーインターフェイスに使用できます。最後のパラメーターは、バッファが色の出力をサポートするかどうかを示します。
clog_enable_buffer（name）
名前で識別されたバッファーを有効にします。
clog_disable_buffer（name）
名前で識別されたバッファーを無効にします。
詰まりは、複数の出力ストリームに一度に出力を書き込むことができます。ユーザーは、さまざまな出力ストリームを追加および有効化/無効にすることにより、どの詰まりログファイルと出力が作成されるかを制御できます。デフォルトでは、 clog_enable_stdlog環境変数が定義されている場合、clogはstd :: clog（これはデフォルトのC ++ログioStreamではなく、詰まりの一部ではない）に誘導します。他の出力ストリームは、ユーザーアプリケーションによって追加する必要があります。例として、ユーザーアプリケーションが詰まりを詰まらせて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詰まりの出力は、特定の重大度レベルを指定することにより、コンパイル時に制御できます。 CLOG_STRIP_LEVELで指定されたものよりも重大度レベルが低いロギングメッセージは無効になります。これは、clogがclog_strip_level> = 5の出力を生成しないことを意味することに注意してください。
異なる重大度レベルには、次の動作があります。
トレース
重大度レベル0（1未満）でのみ有効
トレース出力は、細粒のロギング情報に適しています。
情報
重大度レベルが2未満で有効になります
情報出力は、通常のロギング情報に適しています。
警告
3未満の重症度レベルで有効になります
警告出力は、警告を発行するのに役立ちます。 clog_color_outputが有効になると、WARNメッセージが黄色で表示されます。
エラー
重大度レベルが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
通常の詰まりインターフェイスは、一連のマクロを介して実装されます。詰まりをより強く制御する必要がある上級ユーザーは、低レベルの詰まりインターフェイスに直接アクセスするために、独自のインターフェイス（マクロまたはその他）を作成できます。詰まりのログメッセージは、 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 describle'）
Cinchは、Gitを使用するプロジェクトのバージョン情報を自動的に作成できます。この機能では、「Git Describs」関数を使用します。これは、そのタグと部分的なハッシュキー以降のコミット数に基づいて、パッチレベルで最新の注釈付きタグからバージョンを作成します。たとえば、最新の注釈付きタグが「1.0」であり、それ以来35のコミットがあった場合、Cinchが作成したバージョンは次のようになります：1.0-35-G2F657A
実際のリリースでは、このアプローチは最適ではない場合があります。この場合、Cinchを使用すると、Version_Creationオプションを介してCMAKEに静的バージョンを指定することにより、自動バージョンをオーバーライドできます。これを目的のバージョンに設定するだけで、使用されます。
このソフトウェアはオープンソースのリリースが承認されており、 LA-CC-15-070が割り当てられています。
Copyright（c）2016、Los Alamos National Security、LLC All Rights Reserved。
Copyright2016。LosAlamosNational Security、LLC。このソフトウェアは、ロスアラモス国立研究所（LANL）の米国政府契約DE-AC52-06NA25396の下で生産されました。これは、米国エネルギー省のLos Alamos National Security、LLCが運営しています。米国政府には、このソフトウェアを使用、再現、配布する権利があります。政府もロス・アラモス国家安全保障、LLCも、このソフトウェアの使用に対する保証、明示的、または黙示を問わず、または責任を負いません。ソフトウェアがデリバティブ作業を生成するように変更された場合、LANLから利用可能なバージョンと混同しないように、そのような変更されたソフトウェアを明確にマークする必要があります。
さらに、変更のある条件が満たされていれば、再配布とソース形式およびバイナリ形式での使用が許可されています。
ソースコードの再配布は、上記の著作権通知、この条件リスト、および次の免責事項を保持する必要があります。
バイナリ形式の再配布は、上記の著作権通知、この条件リスト、および分布に提供されたドキュメントおよび/またはその他の資料の次の免責事項を再現する必要があります。
Los Alamos National Security、LLC、LLC、Los Alamos National Laboratory、Lanl、米国政府の名前も、その貢献者の名前も、事前の書面による許可なしにこのソフトウェアから派生した製品を支持または宣伝するために使用することもできません。
このソフトウェアは、Los Alamos National Security、LLC、および貢献者によって「現状のまま」、および特定の目的に対する商品性と適合性の暗黙の保証を含むがこれらに限定されない明示的または黙示的な保証によって提供されます。いかなる場合でも、Los Alamos National Security、LLCまたは貢献者は、直接的、間接的、偶発的、特別な、模範的、または結果的な損害に対して責任を負います（代替品またはサービスの調達を含むがこれらに限定されません。または、契約、厳格な責任、または不法行為（過失などを含む）であっても、このソフトウェアの使用から生じたあらゆる責任のあるものであれば、利益。そのようなダメージ。
