CINCH es un conjunto de utilidades y opciones de configuración diseñadas para hacer que CMake las compilaciones sean fáciles de usar y administrar.
CINCH utiliza funciones estándar de instalación de CMake. Sin embargo, debido a que CINCH depende de su propia herramienta de línea de comandos (Canchul-Utils) para crear su documentación, debe instalarse en las etapas documentadas en esta sección.
Las instrucciones para instalar Cinch-Utils están aquí.
Para instalar la documentación CINCH, debe ejecutar CMake en el directorio de compilación CINCH con documentación habilitada:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
El sistema de compilación CINCH está diseñado para facilitar el desarrollo de código modular. Por modular, queremos decir que los subprojects se pueden incorporar a un proyecto de nivel superior basado en CINCH, y se agregarán automáticamente a los objetivos de compilación del proyecto de nivel superior. Esto facilita la creación de nuevos proyectos que combinen las capacidades de un conjunto de subprojects. Esto permite a los usuarios construir funcionalidad y controlar la funcionalidad del proyecto de nivel superior.
CINCH prohíbe a los usuarios crear compilaciones en el lugar, es decir, construcciones que están arraigadas en el directorio de proyectos de alto nivel de un proyecto FINCH. Si el usuario intenta configurar dicha compilación, CMake saldrá con un error e instrucciones sobre cómo limpiar y crear una compilación fuera de casa.
CINCHA facilita el mantenimiento del sistema de construcción imponiendo una estructura específica en el diseño de la fuente del proyecto.
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
También puede tener cualquier número de submódulos en el directorio del proyecto.
El directorio de nivel superior del proyecto.
Un subdirectorio de destino de la aplicación. Los objetivos de aplicación se pueden agregar utilizando el cinch_add_application_directory documentados a continuación. Este subdirectorio debe contener un archivo cmakelists.txt que agrega los objetivos de CMake necesarios para la aplicación específica.
El subdirectorio cinch. Esto debe verificarse desde el servidor Cinch Git: 'Git Clone ---RECURSIVE [email protected]: LOSALAMOS/CINCH.GIT'.
Cree un archivo, que establece cmake_minimum_required () e incluye el archivo FINCHEPROYLISTS.txt.
El directorio de configuración del proyecto. Este directorio está cubierto en detalle a continuación.
El subdirectorio de documentación. Este subdirectorio debe contener archivos de configuración para la documentación de la Guía Generada Cally y para la documentación de la interfaz de Doxygen.
Un subdirectorio de fuente de destino de la biblioteca. Los objetivos de la biblioteca se pueden agregar utilizando el cinch_add_library_target documentado a continuación.
El subdirectorio de configuración debe contener los siguientes archivos que proporcionan especialización del proyecto. Aunque todos los archivos deben existir, el único archivo que se requiere para tener contenido es el archivo Project.cmake .
Este archivo no puede estar vacío. Como mínimo, debe especificar el nombre del proyecto de nivel superior llamando a la función del proyecto CMake para establecer el nombre, la versión y los idiomas habilitados para todo el proyecto. Para obtener más documentación, en una solicitud en una máquina con una instalación válida de CMake, escriba:
% CMake -Proyecto de Help
Además, este archivo puede llamar a la siguiente función cinch (también se puede dejar nulo):
cinch_add_application_directory (documentado aquí)
Agregue un directorio de compilación específico del proyecto que Cmake debe incluir al buscar archivos de lista. Este directorio debe contener un archivo CMAKELists.txt válido que configure objetivos de compilación adicionales.
cinch_add_library_target (documentado aquí)
Agregue un objetivo de biblioteca para construir para este proyecto.
cinch_add_subproject (documentado aquí)
Agregue un subproyecto a este proyecto.
Este archivo se utiliza para especificar los requisitos de CMake Find_Package para localizar paquetes de terceros instalados. El contenido de este archivo puede ser un conjunto de comandos CMake válidos. Los valores establecidos en este archivo estarán disponibles para archivos CMakelists.txt de bajo nivel para configurar las opciones de compilación a nivel de origen.
Este archivo se utiliza para agregar objetivos de documentación con la interfaz CINCH_ADD_DOC (la documentación de Doxygen se maneja por separado).
CINCH proporciona varias opciones de línea de comandos que se pueden pasar en la línea de configuración de CMake para afectar su comportamiento.
Opción CMake: Enable_cinch_develovelo (desactivado)
Pon Finch en modo de desarrollo. Esta opción afecta parte de la información generada por CINCH, que es útil para los candidatos sin liberación. Si esta opción está habilitada, activará las siguientes funciones:
Opción CMake: enable_cinch_verbose (desactivado por defecto)
Habilite la salida de compilación más detallada.
Opción CMake: Enable_Documentation (desactivado por defecto)
CINCH tiene una poderosa instalación de documentación implementada utilizando la utilidad de línea de comandos CINCH y PANDOC. Para crear documentación, defina un archivo de configuración para cada documento que debe crearse en el subdirectorio 'DOC'. Luego, agregue archivos Markdown (.md) o látex (.tex) al árbol de origen que documente los aspectos del proyecto que se debe incluir. La advertencia es que estos fragmentos de documentación deben tener un encabezado de comentarios especial al comienzo de cada uno, de la forma:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
Este encabezado especial indica qué documento está previsto el fragmento y la sección dentro de la cual debe aparecer. Los encabezados pueden abarcar múltiples líneas siempre que <!-- CINCHDOC
comience el comentario. Si no se especifican atributos (documento, sección, etc.), la utilidad usará un documento predeterminado y la sección ('predeterminado' y 'predeterminado')). Se pueden incluir múltiples fragmentos destinados a diferentes documentos y secciones dentro de un solo archivo de entrada. Para fragmentos de látex, use un encabezado del formulario:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
Los encabezados Cinchdoc de estilo látex deben estar en una sola línea.
Los objetivos de compilación se pueden agregar al archivo Documation.cmake en el directorio de configuración. Cada objetivo debe crearse llamando:
CINCH_ADD_DOC (Outpit Target-Name Config.py Top-Level-Search-Directory)
Nombre de destino La etiqueta de destino Build, es decir, se creará un objetivo de marca de tal manera que se pueda llamar a 'Make Target-Name' para generar el objetivo de documentación.
config.py Un archivo de configuración que debe vivir en el subdirectorio 'doc' del directorio de nivel superior de su proyecto. Este archivo debe contener un solo diccionario de Python Opts que establece las opciones de interfaz de línea de comandos CINCH para su documento.
Directorio de búsqueda de nivel superior La ruta relativa al jefe del árbol de directorio dentro del cual buscar archivos de documentación de Markdown.
Salida El nombre del archivo de salida que debe ser producido por PANDOC.
Opción CMake: Enable_DoxyGen (default (apagado) opción CMake: Enable_DoxyGen_warn (Aftavoad Off)
CINCH admite la documentación de la interfaz usando Doxygen. El archivo de configuración de Doxygen debe llamarse 'doxygen.conf.in' y debe residir en el subdirectorio 'DOC'. Para la documentación sobre el uso de Doxygen, eche un vistazo a la página de inicio de Doxygen.
Si habilitar_DOXYGEN_WARN se establece en ON, no se suprimirán los diagnósticos y advertencias normales de doxygen.
Opción CMake: Enable_unit_tests (desactivado por defecto)
CINCH tiene soporte para las pruebas unitarias utilizando una combinación de CTEST (la instalación de prueba CMake nativa) y Googletest (para soporte de C ++). Si las pruebas unitarias están habilitadas, CINCH creará un objetivo de 'prueba'. Las pruebas unitarias se pueden agregar en cualquier subdirectorio del proyecto simplemente crear el código fuente de prueba y agregar un objetivo utilizando la función 'CINCH_ADD_UNIT (Target [Lista de origen])'.
CINCH verificará una instalación local Googletest en el sistema durante el paso de configuración de CMake. Si no se encuentra Googletest, será construido por CINCH (el código fuente de Googletest se incluye con CINCH).
Opción CMake: clog_enable_stdlog (desactivado por defecto)
Opción CMake: CLOG_STRIP_LEVEL (predeterminado "0")
Opción CMake: CLOG_TAG_BITS (predeterminado "16")
Opción CMake: clog_color_output (desactivado por defecto)
CINCH tiene soporte para rastrear, información, advertencia, error e informes fatales de registro (similar al registro de Google). Hay dos estilos de interfaz para la información de registro utilizando Clog: Estilo de inserción, por ejemplo,
clog (info) << "This is some information" << std::endl;
y una interfaz de método, por ejemplo,
clog_info ( " This is some information " );
Ambos estilos de interfaz están disponibles para todos los niveles de gravedad (discutidos a continuación).
Nota: Clog está disponible automáticamente para pruebas unitarias cinchas.
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 (severidad, mensaje, n)
Emite cada enésima iteración utilizando severidad y mensaje . Este método no está definido para el nivel o afirmaciones de gravedad fatal.
clog_assert (prueba, mensaje)
Afirmar que la prueba es verdadera. Si la prueba es falsa, esta llamada ejecutará clog_fatal (mensaje) .
clog_add_buffer (nombre, ostream, colorizado)
Agregue el búfer definido por el argumento Otrream en rdbuf (). El segundo nombre del parámetro es el nombre de la cadena para asociarse con el búfer, y puede usarse en llamadas posteriores a la interfaz de búfer de clog. El último parámetro indica si el búfer admite o no la salida de color.
clog_enable_buffer (nombre)
Habilite el búfer identificado por nombre .
clog_disable_buffer (nombre)
Deshabilite el búfer identificado por nombre .
Clog puede escribir la salida a múltiples transmisiones de salida a la vez. Los usuarios pueden controlar qué archivos de registro y salida se crean agregando y habilitando/deshabilitando varias secuencias de salida. De forma predeterminada, Clog dirige la salida a std :: clog (este es el registro de registro C ++ predeterminado y no forma parte de Clog) cuando se define la variable de entorno CLOG_ENABLE_STDLOG . La aplicación del usuario debe agregar otras secuencias de salida. Como ejemplo, si la aplicación de usuario quisiera que la salida de Clog fuera a un archivo llamado Output.log , uno podría hacer lo siguiente:
# 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
La salida de la obstrucción se puede controlar en el tiempo de compilación especificando un nivel de gravedad particular. Se deshabilitará cualquier mensaje de registro con un nivel de gravedad más bajo que el especificado por CLOG_STRIP_LEVEL . Tenga en cuenta que esto implica que Clog no producirá salida para CLOG_STRIP_LEVEL> = 5 .
Los diferentes niveles de gravedad tienen el siguiente comportamiento:
rastro
Habilitado solo para el nivel de gravedad 0 (menos de 1)
La salida de rastreo es adecuada para la información de registro de grano fino.
información
Habilitado para niveles de gravedad inferior a 2
La salida de información es adecuada para la información de registro normal.
advertir
Habilitado para niveles de gravedad inferiores a 3
La producción advertida es útil para emitir advertencias. Cuando CLOG_COLOR_OUTPUT está habilitado, los mensajes de advertencia se mostrarán en amarillo.
error
Habilitado para niveles de gravedad inferiores a 4
La salida de error es útil para emitir errores no fatales. Cuando CLOG_COLOR_OUTPUT está habilitado, los mensajes de error se mostrarán en rojo.
fatal
Habilitado para niveles de gravedad inferiores a 5
La producción de error fatal es útil para emitir errores fatales. Los errores fatales imprimen un mensaje, volcan el rastro de pila actual y llame a std :: salir (1). Cuando Clog_Color_output está habilitado, los mensajes fatales se mostrarán en rojo.
El control de tiempo de ejecución de la salida de Clog es posible agregando secciones de alcance en el código fuente. Estos se denominan grupos de etiqueta porque la sección de alcance está etiquetada con una etiqueta. El número de grupos de etiquetas posibles está controlado por CLOG_TAG_BITS (predeterminado 16). Los grupos de etiquetas se pueden habilitar o deshabilitar en tiempo de ejecución especificando la lista de grupos de etiquetas a la función CLOG_INIT . En general, estos están controlados por un indicador de línea de comandos que es interpretado por la aplicación del usuario. Aquí hay un código de ejemplo que usa GFLAGS para controlar la salida:
# 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
Código de ejemplo Ejecuta:
% ./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
La interfaz de clog normal se implementa a través de un conjunto de macros. Los usuarios avanzados, que necesitan un mayor control sobre Clog, pueden crear sus propias interfaces (macro o de otro tipo) para acceder directamente a la interfaz Clog de bajo nivel. Los mensajes de registro en Clog Derive del tipo CINCH :: LOG_MESSAGE_T , que proporciona un constructor, destructor virtual y un método de flujo virtual:
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
Los usuarios que deseen personalizar Clog pueden cambiar el comportamiento predeterminado anulando los métodos virtuales de este tipo y proporcionando predicados personalizados. Gran parte de la funcionalidad de Clog Basic se implementa de esta manera, por ejemplo, el siguiente código implementa la salida de gravedad del nivel de rastreo:
# 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
});
Los usuarios interesados deben mirar el código fuente para obtener más ejemplos.
Opción CMake: versión_creation (predeterminado 'Git describir')
CINCH puede crear automáticamente información de versión para proyectos que usan GIT. Esta característica utiliza la función 'Git Describe', que crea una versión de la etiqueta anotada más reciente con un nivel de parche basado en el número de compromisos desde esa etiqueta y una tecla de hash parcial. Por ejemplo, si la etiqueta anotada más reciente es "1.0" y ha habido 35 compromisos desde entonces, la versión creada con cinch sería similar a: 1.0-35-G2F657A
Para las versiones reales, este enfoque puede no ser óptimo. En este caso, CINCH le permite anular el versiones automáticas especificando una versión estática para cmake a través de la opción Version_Creation. Simplemente configure esto en la versión deseada y se utilizará.
Este software ha sido aprobado para el lanzamiento de código abierto y ha sido asignado LA-CC-15-070 .
Copyright (c) 2016, Los Alamos National Security, LLC Todos los derechos reservados.
Copyright 2016. La Securencia Nacional de Los Alamos, LLC. Este software fue producido bajo el contrato del gobierno de EE. UU. De52-06NA25396 para el Laboratorio Nacional de Los Alamos (LANL), que es operado por Los Alamos National Security, LLC para el Departamento de Energía de los Estados Unidos. El gobierno de los Estados Unidos tiene derechos para usar, reproducir y distribuir este software. Ni el Gobierno ni la Seguridad Nacional de Los Alamos, LLC, ofrecen ninguna garantía, expresa o implícita, o asume ninguna responsabilidad por el uso de este software. Si el software se modifica para producir obras derivadas, dicho software modificado debe estar claramente marcado, para no confundirlo con la versión disponible de LANL.
Además, se permiten redistribución y uso en formularios de origen y binarios, con o sin modificación, siempre que se cumplan las siguientes condiciones:
Las redistribuciones del código fuente deben retener el aviso de derechos de autor anterior, esta lista de condiciones y el siguiente descargo de responsabilidad.
Las redistribuciones en forma binaria deben reproducir el aviso de derechos de autor anterior, esta lista de condiciones y el siguiente descargo de responsabilidad en la documentación y/u otros materiales provistos con la distribución.
Ni el nombre de Los Alamos National Security, LLC, Laboratorio Nacional de Los Alamos, LANL, el gobierno de los Estados Unidos, ni los nombres de sus contribuyentes pueden usarse para respaldar o promover productos derivados de este software sin un permiso previo por escrito específico.
Este software es proporcionado por Los Alamos National Security, LLC y los contribuyentes "tal como es" y cualquier garantía expresa o implícita, incluidas, entre otros, las garantías implícitas de comerciabilidad y idoneidad para un propósito particular se renuncian. En ningún caso, Los Alamos National Security, LLC o contribuyentes serán responsables de los daños directos, indirectos, incidentales, especiales, ejemplares o consecuentes (que incluyen, entre otros, la adquisición de bienes o servicios sustitutos; pérdida de uso, datos, O ganancias; Tal daño.