cinch
Release 1.0
Cinch는 Cmake 빌드를 쉽게 사용하고 관리 할 수 있도록 설계된 유틸리티 및 구성 옵션 세트입니다.
Cinch는 표준 CMAKE 설치 기능을 사용합니다. 그러나 Cinch는 문서를 작성하기 위해 자체 명령 줄 도구 (Cinch-utils)에 의존하기 때문에이 섹션에 문서화 된 단계에 설치해야합니다.
Cinch-utils 설치 방향은 여기에 있습니다.
Cinch 문서를 설치하려면 Cinch 빌드 디렉토리에서 CMAKE를 실행하여 문서화를 활성화해야합니다.
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
Cinch 빌드 시스템은 모듈 식 코드 개발을 쉽게하도록 설계되었습니다. 모듈 식으로, 우리는 하위 프로젝트를 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 하위 디렉토리. Cinch Git 서버에서 확인해야합니다.
cmake_minimum_required ()를 설정하고 cinch projectLists.txt 파일을 포함하는 파일을 만듭니다.
프로젝트 구성 디렉토리. 이 디렉토리는 아래에 자세히 설명되어 있습니다.
문서화 서브 디렉토리. 이 하위 디렉토리에는 Cinch-Generated Guide Documentation과 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 Documentation은 별도로 처리됩니다).
CINCH는 CMAKE 구성 줄에 전달 될 수있는 다양한 명령 줄 옵션을 제공하여 동작에 영향을 미칩니다.
cmake 옵션 : enable_cinch_development (기본값)
Cinch를 개발 모드에 넣습니다. 이 옵션은 CINCH가 생성 한 일부 정보에 영향을 미치지 않습니다. 이 옵션이 활성화되면 다음 기능이 켜집니다.
cmake 옵션 : enable_cinch_verbose (기본값 끄기)
보다 자세한 빌드 출력을 활성화하십시오.
cmake 옵션 : enable_documentation (기본값 끄기)
Cinch에는 Cinch Command-Line 유틸리티 및 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 디렉토리의 documentation.cmake 파일에 대상 빌드를 추가 할 수 있습니다. 각 대상은 다음을 호출하여 작성해야합니다.
cinch_add_doc (target-name config.py 최상위 검색-디렉토리 출력)
대상 이름 빌드 대상 레이블 (즉,) '대상 이름'을 호출하여 문서 대상을 생성 할 수 있도록 만들 수 있습니다.
config.py 프로젝트의 최상위 디렉토리의 'doc'서브 디렉토리에 남아야하는 구성 파일. 이 파일에는 Docuement의 Cinch 명령 줄 인터페이스 옵션을 설정하는 단일 Python Dictionary Opts가 포함되어야합니다.
최상위 검색-디렉토리 트리 헤드에 대한 상대 경로는 Markdown 문서화 파일을 검색합니다.
출력 Pandoc에서 생성 해야하는 출력 파일의 이름을 출력하십시오 .
CMAKE 옵션 : ENABLE_DOXYGEN (기본값) CMAKE 옵션 : ENABLE_DOXYGEN_WARN (기본값)
Cinch는 Doxygen을 사용하여 인터페이스 문서를 지원합니다. Doxygen 구성 파일은 'doxygen.conf.in'이라고 불리며 'Doc'하위 디렉토리에 상주해야합니다. Doxygen 사용에 대한 문서를 보려면 Doxygen 홈페이지를 살펴보십시오.
ENABLE_DOXYGEN_WARN이 켜져 있으면 정상적인 Doxygen 진단 및 경고는 억제되지 않습니다.
cmake 옵션 : enable_unit_tests (기본값 끄기)
CINCH는 CTEST (기본 CMAKE 테스트 시설)와 GOOGLETEST (C ++ 지원)의 조합을 사용하여 단위 테스트를 지원합니다. 단위 테스트가 활성화되면 Cinch는 '테스트'대상을 만듭니다. 프로젝트의 하위 디렉토리에 단위 테스트가 추가 될 수 있습니다. 단순히 테스트 소스 코드를 작성하고 'cinch_add_unit (target [source list]) 함수를 사용하여 대상을 추가하는 것입니다.
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는 추적, 정보, 경고, 오류 및 치명적인 로그보고 (Google Log와 유사)를 지원합니다. 막힘을 사용하여 정보 로깅을위한 두 가지 인터페이스 스타일이 있습니다 : 삽입 스타일, 예를 들어,
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 (이름, 타조, 색상화)
rdbuf ()의 타조 인수에 의해 정의 된 버퍼를 추가하십시오. 두 번째 매개 변수 이름 은 버퍼와 연결할 문자열 이름이며, 이후 클로그 버퍼 인터페이스로의 후속 호출에서 사용할 수 있습니다. 마지막 매개 변수는 버퍼가 색상 출력을 지원하는지 여부를 나타냅니다.
clog_enable_buffer (이름)
이름 으로 식별 된 버퍼를 활성화합니다.
clog_disable_buffer (이름)
이름 으로 식별 된 버퍼를 비활성화합니다.
막힘은 한 번에 여러 출력 스트림에 출력을 쓸 수 있습니다. 사용자는 다양한 출력 스트림을 추가하고 활성화하여 생성되는 막힘 로그 파일 및 출력을 제어 할 수 있습니다. 기본적으로 Clog는 Clog_enable_stdlog 환경 변수가 정의 될 때 출력을 std :: clog로 지시합니다 (이것은 기본 c ++ log 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_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)에 의해 제어됩니다. TAG 그룹의 목록을 CLOG_INIT 함수로 지정하여 런타임에 태그 그룹을 활성화하거나 비활성화 할 수 있습니다. 일반적으로 이들은 사용자의 응용 프로그램에 의해 해석되는 명령 줄 플래그로 제어됩니다. 다음은 GFLAG를 사용하여 출력을 제어하는 예제 코드입니다.
# 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 sec장')
Cinch는 GIT를 사용하는 프로젝트에 대한 버전 정보를 자동으로 생성 할 수 있습니다. 이 기능은 'git section'함수를 사용합니다.이 기능은 태그 이후의 커밋 수와 부분 해시 키를 기반으로 패치 레벨을 가진 가장 최근 주석이 달린 태그의 버전을 만듭니다. 예를 들어, 가장 최근의 주석이 달린 태그가 "1.0"이고 이후 35 개의 커밋이있는 경우 Cinch-Created 버전은 다음과 비슷합니다. 1.0-35-G2F657a.
실제 릴리스의 경우이 접근법이 최적이 아닐 수 있습니다. 이 경우 Cinch를 사용하면 version_creation 옵션을 통해 CMake에 정적 버전을 지정하여 자동 버전 설정을 재정의 할 수 있습니다. 이것을 원하는 버전으로 간단히 설정하면 사용됩니다.
이 소프트웨어는 오픈 소스 릴리스에 대한 승인을 받았으며 LA-CC-15-070 이 할당되었습니다.
Copyright (C) 2016, Los Alamos National Security, LLC All Rights Reserved.
Copyright 2016. Los Alamos National Security, LLC. 이 소프트웨어는 미국 에너지 국을 위해 Los Alamos National Security, LLC가 운영하는 LOS Alamos National Laboratory (LANL)의 미국 정부 계약 DE-AC52-06NA25396에 따라 생산되었습니다. 미국 정부는이 소프트웨어를 사용, 재생산 및 배포 할 권리가 있습니다. 정부 나 Los Alamos National Security, LLC는이 소프트웨어 사용에 대한 보증, 명시 적 또는 묵시적 또는 묵시적 보증을하지 않습니다. 소프트웨어가 파생물 작업을 생성하도록 수정 된 경우 LANL에서 사용 가능한 버전과 혼동하지 않도록 이러한 수정 된 소프트웨어를 명확하게 표시해야합니다.
또한, 다음 조건이 충족되면 수정 유무에 관계없이 소스 및 이진 형태의 재분배 및 사용이 허용됩니다.
소스 코드의 재분배는 위의 저작권 통지,이 조건 목록 및 다음 면책 조항을 유지해야합니다.
이진 형식의 재분배는 위의 저작권 통지,이 조건 목록 및 문서의 다음 면책 조항 및 배포와 함께 제공되는 기타 자료를 재현해야합니다.
Los Alamos National Security, LLC, Lanl, LANL, LANL, 미국 정부의 이름은 특정 사전 서면 허가 없이이 소프트웨어에서 파생 된 제품을 보증하거나 홍보하는 데 사용될 수 없습니다.
이 소프트웨어는 Los Alamos National Security, LLC 및 기고자 "그대로"및 상품성에 대한 묵시적 보증과 특정 목적에 대한 적합성을 포함하되 이에 국한되지 않는 명시 적 또는 묵시적 보증에 의해 제공됩니다. 어떠한 경우에도 Alamos National Security, LLC 또는 기고자는 직접, 간접적, 부수적, 특별, 모범적 또는 결과적 손해 (대체 상품 또는 서비스 조달, 사용 손실, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터, 데이터)에 대해 책임을지지 않아야합니다. 또는 이익;; 또는 중단) 그러나, 계약, 엄격한 책임 또는 불법 행위 (과실 또는 기타 포함)에 관계없이 어떤 방식 으로든이 소프트웨어 사용에서 발생하는 경우에도 불구하고,이 소프트웨어의 사용에서 발생하는 경우에도 불구하고, 엄격한 책임 또는 불법 행위에 관계없이 임의의 책임 이론에 이어 그런 손상.
