cinch
Release 1.0
Cinch - это набор утилит и параметров конфигурации, предназначенные для того, чтобы сделать сборки Cmake простыми в использовании и управлении.
Cinch использует стандартные функции установки Cmake. Однако, поскольку Cinch зависит от своего собственного инструмента командной строки (Cinch-Utils) для создания своей документации, он должен быть установлен на этапах, документированных в этом разделе.
Направления для установки утилизаторов привязки здесь.
Чтобы установить документацию CINCH, вы должны запустить CMAKE в каталоге CINCH Build с включенной документацией:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
Система сборки CINCH предназначена для облегчения разработки модульного кода. Под модулем мы подразумеваем, что субпроекты могут быть включены в проект верхнего уровня на основе CINCH, и они будут автоматически добавлены в целевые показатели проекта верхнего уровня. Это позволяет легко создавать новые проекты, которые сочетают в себе возможности набора подпроектов. Это позволяет пользователям создавать функциональность и управлять функциональностью проекта верхнего уровня.
Cinch запрещает пользователям создавать сборки на месте, то есть сборки, которые основаны на проекте проекта Top Level в проекте 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 GIT: 'git клон-рекурсивный [email protected]: losalamos/cinch.git'.
Создайте файл, который устанавливает cmake_minimum_required () и включает файл cinch Projectlists.txt.
Каталог конфигурации проекта. Этот каталог подробно описан ниже.
Документация подкаканала. Эта подкатария должна содержать файлы конфигурации для документации по сгенерированию CINCH и для документации по интерфейсу доксигена.
Библиотечный целевой источник подкаталога. Цели библиотеки могут быть добавлены с помощью CINCH_ADD_LIBRARY_TARGE, документированного ниже.
Подкаталог конфигурации должен содержать следующие файлы, которые обеспечивают специализацию проекта. Хотя все файлы должны существовать, единственный файл, который требуется для получения контента, - это файл project.cmake .
Этот файл не может быть пустым. Как минимум, он должен указать имя проекта верхнего уровня, вызвав функцию проекта Cmake, чтобы установить имя, версию и включенные языки для всего проекта. Для получения дополнительной документации, по приглашению на машине с действительной установкой Cmake, тип:
% Cmake -HELP Project
Кроме того, этот файл может вызвать следующую функцию CINCH (они также могут оставаться нулевыми):
cinch_add_application_directory (задокументирован здесь)
Добавьте каталог сборки, специфичный для проекта, который должен быть включен CMAKE при поиске файлов списков. Этот каталог должен содержать действительный файл cmakelists.txt, который настраивает дополнительные цели сборки.
cinch_add_library_target (документирован здесь)
Добавьте библиотечную цель для создания для этого проекта.
cinch_add_subproject (задокументирован здесь)
Добавьте субпроект в этот проект.
Этот файл используется для указания требований cmake find_package для поиска установленных сторонних пакетов. Содержание этого файла может быть любым набором действительных команд Cmake. Значения, установленные в этом файле, будут доступны для файлов cmakelists.txt низкоуровневого cmakelists.txt для настройки параметров сборки на уровне источника.
Этот файл используется для добавления целей документации с интерфейсом cinch_add_doc (документация доксигена обрабатывается отдельно).
Cinch предоставляет различные параметры командной строки, которые могут быть переданы в строке конфигурации Cmake, чтобы повлиять на ее поведение.
Опция Cmake: enable_cinch_development (по умолчанию OFF)
Поместите привод в режим разработки. Этот вариант влияет на некоторую информацию, которая генерируется CINCH, которая полезна для кандидатов, не обработанных высвобождением. Если эта опция включена, она включит следующие функции:
Опция Cmake: enable_cinch_verbose (по умолчанию OFF)
Включить более подробный выход сборки.
Опция Cmake: enable_documentation (по умолчанию OFF)
У Cinch есть мощный объект документации, реализованный с использованием утилиты Cinch Commandline и Pandoc. Чтобы создать документацию, определите файл конфигурации для каждого документа, который должен быть создан в подкаталоге «Док». Затем добавьте файлы Markdown (.md) или латекс (. Предостережение заключается в том, что эти фрагменты документации должны иметь специальный заголовок комментариев в начале каждой, формы:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
Этот специальный заголовок указывает, для какого документа предназначен фрагмент, и раздел, в котором он должен появляться. Заголовки могут охватывать несколько строк, при условии, что <!-- CINCHDOC начинает комментарий. Если не указано атрибуты (документ, раздел и т. Д.), Утилита будет использовать документ по умолчанию и раздел («по умолчанию» и «по умолчанию»). Несколько фрагментов, предназначенных для различных документов и разделов, могут быть включены в один входной файл. Для фрагментов латекса используйте заголовок формы:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
Заголовки Cinchdoc в латексном стиле должны быть на одной линии.
Цели сборки могут быть добавлены в файл document.cmake в каталоге конфигурации. Каждая цель должна быть создана по телефону:
cinch_add_doc (target-name config.py tope-search-directory output)
Целевая название целевой метки сборки, то есть, будет создана цель, чтобы «сделать целевую имену» может быть вызвана для генерации цели документации.
config.py Файл конфигурации, который должен жить в подкаталоге «Док» высокопоставленного каталога вашего проекта. Этот файл должен содержать один словарь Python, который устанавливает параметры интерфейса командной строки CINCH для вашего документа.
На верхнем уровне-поиске относительного пути к главе дерева каталогов, в котором можно найти файлы документации Markdown.
Выведите имя выходного файла, который должен быть создан Pandoc.
Параметр Cmake: enable_doxygen (default Off) Параметр Cmake: enable_doxygen_warn (по умолчанию OFF)
CINCH поддерживает интерфейсную документацию с использованием Doxygen. Файл конфигурации доксигена должен называться «doxygen.conf.in» и должен находиться в подкаталоге «Док». Для документации об использовании доксигена, пожалуйста, посмотрите на домашнюю страницу Doxygen.
Если включен enable_doxygen_warn, нормальная диагностика доксигена и предупреждения не будут подавлены.
Опция Cmake: enable_unit_tests (по умолчанию OFF)
CINCH поддерживает модульные тестирование с использованием комбинации CTEST (нативное предприятие Cmake Testing) и Googletest (для поддержки C ++). Если модульные тесты включены, Cinch создаст цель «тестового». Модульные тесты могут быть добавлены в любом подкаталоге проекта, просто создайте исходный код тестирования и добавление цели с использованием функции 'cinch_add_unit (Target [Source List])'.
Cinch проверит на локальную установку Googletest в системе на этапе конфигурации Cmake. Если Googletest не найден, он будет построен Cinch (исходный код GoogleTest включен в CINCH).
Опция Cmake: clog_enable_stdlog (по умолчанию OFF)
Параметр Cmake: clog_strip_level (по умолчанию "0")
Параметр Cmake: clog_tag_bits (по умолчанию "16")
Параметр Cmake: clog_color_output (по умолчанию OFF)
Cinch поддерживает трассировку, информацию, предупреждение, ошибку и отчеты о фатальных журналах (аналогично журналу Google). Существует два стиля интерфейса для ведения информации о ведении журнала с использованием CLOG: стиль вставки, например,
clog (info) << "This is some information" << std::endl;и интерфейс метода, например,
clog_info ( " This is some information " );Оба стиля интерфейса доступны для всех уровней серьезности (обсуждается ниже).
Примечание: заполнение автоматически доступна для тестов на блок.
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)
Выводит каждую N -й итерацию, используя серьезность и сообщение . Этот метод не определяется для уровня или утверждений о смертельной тяжести.
clog_assert (тест, сообщение)
Утверждайте, что тест верен. Если тест является ложным, этот вызов выполнит clog_fatal (сообщение) .
clog_add_buffer (имя, острим, раскрашен)
Добавьте буфер, определяемый аргументом Ostream в rdbuf (). Второе имя параметра - это название строки, которое нужно ассоциировать с буфером и может использоваться в последующих вызовах в интерфейс буфера засорения. Последний параметр указывает, поддерживает ли буфер выход цвета.
clog_enable_buffer (имя)
Включить буфер, идентифицированный по имени .
clog_disable_buffer (имя)
Отключить буфер, идентифицированный по имени .
CLOG может записать вывод в несколько выходных потоков одновременно. Пользователи могут управлять тем, какие файлы журнала и выводы засорение создаются путем добавления и отключения/отключения различных выходных потоков. По умолчанию затолога направляет вывод на std :: clog (это iostream log c ++ по умолчанию и не является частью заполнения), когда определена переменная среды Clog_enable_stdlog . Другие выходные потоки должны быть добавлены пользовательским приложением. В качестве примера, если пользовательский приложение хотела, чтобы вывод засорения перейти в файл с именем 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
Warn Вывод полезен для выпуска предупреждений. При включении CLOG_COLOR_OUTPUT , сообщения WARN будут отображаться в желтом.
ошибка
Включено для уровней тяжести менее 4
Вывод ошибки полезен для выпуска нерадостных ошибок. При включении CLOG_COLOR_OUTPUT , сообщения об ошибках будут отображаться красным.
фатальный
Включено для уровней тяжести менее 5
Выход по ошибке фатальной ошибки полезен для выпуска смертельных ошибок. Фатальные ошибки распечатайте сообщение, сбросите текущую трассу стека и вызовите Std :: Exit (1). Когда включен CLOG_COLOR_Output , фатальные сообщения будут отображаться красным.
Контроль времени выполнения вывода засорения возможна путем добавления разделам в исходном коде. Они называются группами тегов , потому что раздел Scoped помечен тегом. Количество возможных групп тегов контролируется CLOG_TAG_BITS (по умолчанию 16). Группы тегов могут быть включены или отключены во время выполнения, указав список групп тегов на функцию 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
Нормальный интерфейс засорения реализован через набор макросов. Расширенные пользователи, которые нуждаются в большем контроле над засолом, могут создавать свои собственные интерфейсы (макрос или иным образом), чтобы непосредственно получить доступ к интерфейсу низкого уровня. Сообщения журнала в затолчке, полученные из типа 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 коммита, версия, созданная с подсказкой, была бы аналогична: 1.0-35-G2F657A
Для фактических выпусков этот подход может быть не оптимальным. В этом случае Cinch позволяет вам переопределить автоматическое управление версией, указав статическую версию Cmake через опцию version_creation. Просто установите это на желаемую версию, и она будет использоваться.
Это программное обеспечение было одобрено для выпуска с открытым исходным кодом и было назначено LA-CC-15-070 .
Copyright (C) 2016, Los Alamos National Security, LLC Все права защищены.
Copyright 2016. Los Alamos National Security, LLC. Это программное обеспечение было произведено в соответствии с правительственным контрактом США DE-AC52-06NA25396 для Лос-Аламос Национальной лаборатории (LANL), которая управляется Los Alamos National Security, LLC для Министерства энергетики США. Правительство США имеет права использовать, воспроизводить и распространять это программное обеспечение. Ни правительство, ни Лос -Аламос National Security, LLC не дают никакой гарантии, явного или подразумеваемого, или несут какую -либо ответственность за использование этого программного обеспечения. Если программное обеспечение модифицировано для создания производных работ, такое модифицированное программное обеспечение должно быть четко обозначено, чтобы не путать его с версией, доступной от LANL.
Кроме того, перераспределение и использование в исходных и бинарных формах, с изменением или без нее, разрешены при условии, что следующие условия выполняются:
Перераспределение исходного кода должно сохранить вышеуказанное уведомление об авторском праве, этот список условий и следующее отказ от ответственности.
Перераспределение в двоичной форме должно воспроизводить вышеуказанное уведомление об авторском праве, этот список условий и следующее отказ от ответственности в документации и/или других материалах, предоставленных при распределении.
Ни название Los Alamos National Security, LLC, Лос -Аламос Национальная лаборатория, LANL, правительство США или названия его участников могут использоваться для поддержки или продвижения продуктов, полученных из этого программного обеспечения, без конкретного предварительного письменного разрешения.
Это программное обеспечение предоставляется Los Alamos National Security, LLC и участниками «как есть», и любые явные или подразумеваемые гарантии, включая, помимо прочего, подразумеваемые гарантии товарной пригодности и пригодности для конкретной цели, отказываются. Ни в коем случае не будет нести ответственность за национальную безопасность Los Alamos, LLC или участники за любые прямые, косвенные, случайные, особые, образцовые или косвенные убытки (включая, но не ограничиваясь, закупку заместительных товаров или услуг; потеря использования, данные, данные, Или прибыль; или прерывание бизнеса), однако, вызвано и по какой -либо теории ответственности, будь то в контракте, строгой ответственности или деликте (включая халатность или иное) Такой урон.
