cinch
Release 1.0
O Cinch é um conjunto de opções de utilitários e configurações projetadas para facilitar o uso e o gerenciamento do CMake.
Cinch usa recursos de instalação cmake padrão. No entanto, como a Cinch depende de sua própria ferramenta de linha de comando (Cinch-Utils) para construir sua documentação, ela deve ser instalada nos estágios documentados nesta seção.
Instruções para a instalação de Cinch-Utils estão aqui.
Para instalar a documentação do Cinch, você deve executar o CMake no diretório de construção do Cinch com a documentação ativada:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
O sistema de compilação Cinch foi projetado para facilitar o desenvolvimento de código modular. Por modular, queremos dizer que os subprojetos podem ser incorporados a um projeto de nível superior baseado em Cinch, e eles serão adicionados automaticamente às metas de construção do projeto de nível superior. Isso facilita a criação de novos projetos que combinam os recursos de um conjunto de subprojetos. Isso permite que os usuários criem funcionalidade e controlem a funcionalidade do projeto de nível superior.
A Cinch proíbe os usuários de criar construções no local, ou seja, construções que estão enraizadas no diretório de projetos de nível superior de um projeto de fila. Se o usuário tentar configurar essa compilação, o CMake sairá com um erro e instruções sobre como limpar e criar uma compilação fora da fonte.
O Cinch facilita a manutenção do sistema, impondo uma estrutura específica ao layout da fonte do projeto.
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
Você também pode ter qualquer número de submódulos no diretório do projeto.
O diretório de nível superior do projeto.
Um subdiretório de destino do aplicativo. As metas de aplicativos podem ser adicionadas usando o CINCH_ADD_APplication_Directory documentado abaixo. Este subdiretório deve conter um arquivo cmakelists.txt que adiciona quaisquer metas de cmake que sejam necessárias para o aplicativo específico.
O subdiretório Cinch. Isso deve ser verificado no servidor Cinch Git: 'Git Clone-Recursive [email protected]: losalamos/chch.git'.
Crie um arquivo, o que define cmake_minimum_required () e inclui o arquivo de projeto Cinch.txt.
O diretório de configuração do projeto. Este diretório é abordado em detalhes abaixo.
O subdiretório de documentação. Este subdiretório deve conter arquivos de configuração para documentação de guia gerada por Cinch e para documentação da interface doxygen.
Um subdiretório de fonte de destino da biblioteca. Os alvos da biblioteca podem ser adicionados usando o CINCH_ADD_LIBRARY_TARGET documentado abaixo.
O subdiretório de configuração deve conter os seguintes arquivos que fornecem especialização do projeto. Embora todos os arquivos devam existir, o único arquivo necessário para ter conteúdo é o arquivo Project.cmake .
Este arquivo não pode estar vazio. No mínimo, deve especificar o nome do projeto de nível superior, chamando a função do projeto CMake para definir o nome, a versão e os idiomas ativados para todo o projeto. Para obter mais documentação, em um prompt em uma máquina com uma instalação válida de cmake, digite:
% Cmake -Projeto Help
Além disso, esse arquivo pode chamar a seguinte função Cinch (eles também podem ficar nulos):
Cinch_add_application_directory (documentado aqui)
Adicione um diretório de construção específico do projeto que deve ser incluído pelo CMake ao pesquisar arquivos de lista. Este diretório deve conter um arquivo cmakelists.txt válido que configure metas de construção adicionais.
Cinch_add_library_target (documentado aqui)
Adicione um alvo da biblioteca para construir para este projeto.
Cinch_add_subProject (documentado aqui)
Adicione um subprojeto a este projeto.
Este arquivo é usado para especificar os requisitos do CMake Find_Package para localizar pacotes instalados de terceiros. O conteúdo deste arquivo pode ser qualquer conjunto de comandos cmake válidos. Os valores definidos neste arquivo estarão disponíveis para arquivos cmakelists.txt de baixo nível para configurar opções de construção no nível da fonte.
Este arquivo é usado para adicionar metas de documentação com a interface Cinch_add_doc (a documentação doxygen é tratada separadamente).
A Cinch fornece várias opções de linha de comando que podem ser transmitidas na linha de configuração do CMAKE para afetar seu comportamento.
Opção CMake: Enable_cinch_development (padrão desativado)
Coloque o Cinch no modo de desenvolvimento. Esta opção afeta algumas das informações geradas pela Cinch, que são úteis para candidatos que não são lançados. Se esta opção estiver ativada, ele ativará os seguintes recursos:
Opção cmake: enable_cinch_verbose (padrão desativado)
Ative a saída de construção mais detalhada.
Opção CMake: Enable_Documentation (padrão desativado)
A Cinch possui uma poderosa instalação de documentação implementada usando o utilitário de linha de comandos Cinch e o Pandoc. Para criar documentação, defina um arquivo de configuração para cada documento que deve ser criado no subdiretório 'doc'. Em seguida, adicione arquivos Markdown (.md) ou LATEX (.Tex) à árvore de origem que documentam os aspectos que os aspectos do projeto devem ser incluídos. A ressalva é que esses fragmentos de documentação devem ter um cabeçalho de comentário especial no início de cada um, do formulário:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
Este cabeçalho especial indica para o qual o documento o fragmento se destina e a seção na qual ele deve aparecer. Os cabeçalhos podem abranger várias linhas, desde que <!-- CINCHDOC inicie o comentário. Se nenhum atributo (documento, seção etc.) for especificado, o utilitário usará um documento e seção padrão ('padrão' e 'padrão'). Vários fragmentos destinados a diferentes documentos e seções podem ser incluídos em um único arquivo de entrada. Para fragmentos de látex, use um cabeçalho do formulário:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
Os cabeçalhos Cinchdoc no estilo látex devem estar em uma única linha.
As metas de construção podem ser adicionadas ao arquivo documentação.cmake no diretório de configuração. Cada alvo deve ser criado ligando:
Cinch_add_doc (NAME-NAM
Nome de destino O rótulo de destino da construção, ou seja, um alvo formar será criado de modo que 'Make Target-Name' possa ser chamado para gerar o destino da documentação.
Config.py Um arquivo de configuração que deve viver no subdiretório 'doc' do diretório de nível superior do seu projeto. Este arquivo deve conter um único dicionário Python OpTs que define as opções de interface da linha de comando Cinch para o seu documento.
Diretório de pesquisa de nível superior O caminho relativo para a cabeça da árvore do diretório na qual procurar arquivos de documentação de marcação.
Saia o nome do arquivo de saída que deve ser produzido pelo Pandoc.
Opção CMake: Enable_doxygen (padrão desativado) Opção CMake: enable_doxygen_warn (padrão desativado)
Cinch suporta a documentação da interface usando doxygen. O arquivo de configuração do doxygen deve ser chamado de 'doxygen.conf.in' e deve residir no subdiretório 'doc'. Para documentação sobre o uso do doxygen, consulte a página inicial doxygen.
Se Enable_doxygen_warn estiver definido, o diagnóstico e os avisos normais doxygen não serão suprimidos.
Opção cmake: enable_unit_tests (padrão desativado)
A Cinch possui suporte para testes de unidade usando uma combinação de CTest (a instalação de teste de CMake nativa) e GoogleTest (para suporte a C ++). Se os testes de unidade estiverem ativados, o Cinch criará um destino de 'teste'. Os testes de unidade podem ser adicionados em qualquer subdiretório do projeto, simplesmente criando o código -fonte do teste e adicionando um destino usando a função 'cinch_add_unit (alvo [lista de origem]).
Cinch verificará uma instalação local do GoogleTest no sistema durante a etapa de configuração do CMake. Se o GoogleTest não for encontrado, ele será construído pelo Cinch (o código -fonte GoogleTest será incluído no Cinch).
Opção CMake: clog_enable_stdlog (padrão desativado)
Opção CMake: clog_strip_level (padrão "0")
Opção CMake: clog_tag_bits (padrão "16")
Opção cmake: clog_color_output (padrão desativado)
Cinch tem suporte para relatórios de rastreamento, informações, aviso, erro e logs fatais (semelhante ao log do Google). Existem dois estilos de interface para informações de registro usando entupimento: estilo de inserção, por exemplo,
clog (info) << "This is some information" << std::endl;e uma interface de método, por exemplo,
clog_info ( " This is some information " );Ambos os estilos de interface estão disponíveis para todos os níveis de gravidade (discutidos abaixo).
NOTA: O entupimento está disponível automaticamente para testes de unidade Cinch.
clog_init ( " group1,group2,group3 " ); clog (error) << "This is an error level severity message" << std::endl; clog_info ( " The number is " << number); cog_every_n (gravidade, mensagem, n)
Saia todas as iteias da Nth usando gravidade e mensagem . Este método não é definido para o nível ou afirmações de gravidade fatal.
clog_assert (teste, mensagem)
Afirmar que o teste é verdadeiro. Se o teste for falso, esta chamada será executada clog_fatal (mensagem) .
clog_add_buffer (nome, ostream, colorizado)
Adicione o buffer definido pelo argumento Ostream em rdbuf (). O segundo nome do parâmetro é o nome da string a se associar ao buffer e pode ser usado nas chamadas subsequentes para a interface buffer de coto. O último parâmetro indica se o buffer suporta ou não a saída de cores.
clog_enable_buffer (nome)
Ativar o buffer identificado pelo nome .
clog_disable_buffer (nome)
Desative o buffer identificado pelo nome .
O entupimento pode gravar saída em vários fluxos de saída de uma só vez. Os usuários podem controlar quais arquivos de log e saída de entupimento são criados adicionando e ativando/desativando vários fluxos de saída. Por padrão, o CLOG direciona a saída para STD :: Clog (este é o log de log c ++ padrão e não faz parte do entupimento) quando a variável de ambiente clog_enable_stdlog é definida. Outros fluxos de saída devem ser adicionados pelo aplicativo do usuário. Como exemplo, se o aplicativo do usuário quisesse a saída de coto para ir a um arquivo chamado Output.log , pode -se fazer o seguinte:
# 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 ;
} // mainA saída de entupimento pode ser controlada no tempo de compilação, especificando um nível de gravidade específico. Quaisquer mensagens de registro com um nível de gravidade mais baixo do que a especificada por clog_strip_level serão desativadas. Observe que isso implica que o entupimento não produzirá nenhuma saída para clog_strip_level> = 5 .
Os diferentes níveis de gravidade têm o seguinte comportamento:
traço
Ativado apenas para o nível de gravidade 0 (menor que 1)
A saída de rastreamento é adequada para informações de log de grão fino.
informações
Ativado para níveis de gravidade menor que 2
A saída de informações é adequada para informações normais de registro.
avisar
Habilitado para níveis de gravidade menor que 3
A produção de aviso é útil para emitir avisos. Quando o crog_color_output estiver ativado, as mensagens de aviso serão exibidas em amarelo.
erro
Habilitado para níveis de gravidade menor que 4
A saída de erro é útil para emitir erros não fatais. Quando Cog_Color_Output estiver ativado, as mensagens de erro serão exibidas em vermelho.
fatal
Habilitado para níveis de gravidade menor que 5
A saída de erro fatal é útil para emitir erros fatais. Erros fatais Imprimem uma mensagem, despejam o rastreamento da pilha atual e ligue para Std :: Exit (1). Quando Cog_Color_Output estiver ativado, as mensagens fatais serão exibidas em vermelho.
O controle de tempo de execução da saída de entupimento é possível adicionando seções de escopo no código -fonte. Eles são chamados de grupos de tags porque a seção Scoped é rotulada com uma tag. O número de grupos de tags possíveis é controlado por clog_tag_bits (padrão 16). Os grupos de tags podem ser ativados ou desativados no tempo de execução especificando a lista de grupos de tags para a função Clog_init . Geralmente, eles são controlados por um sinalizador de linha de comando que é interpretado pelo aplicativo do usuário. Aqui está um código de exemplo usando GFLAGs para controlar a saída:
# 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 ;
} // mainExemplo de código é executado:
% ./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
A interface de coto normal é implementada através de um conjunto de macros. Usuários avançados, que precisam de maior controle sobre o entupimento, podem criar suas próprias interfaces (macro ou de outra forma) para acessar diretamente a interface de entupimento de baixo nível. As mensagens de log em coito derivam do tipo Cinch :: LOG_MESSAGE_T , que fornece um construtor, destruidor virtual e um método de fluxo 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_tOs usuários que desejam personalizar o escado podem alterar o comportamento padrão, substituindo os métodos virtuais desse tipo e fornecendo predicados personalizados. Grande parte da funcionalidade básica do entupimento é implementada dessa maneira, por exemplo, o código a seguir implementa a saída de gravidade do nível de rastreamento:
# 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
});Os usuários interessados devem olhar para o código -fonte para obter mais exemplos.
Opção CMake: Version_creation (padrão 'git descreve')
O Cinch pode criar automaticamente informações de versão para projetos que usam o Git. Esse recurso usa a função 'git descreve', que cria uma versão a partir da tag anotada mais recente com um nível de patch com base no número de começos desde essa tag e uma chave de hash parcial. Por exemplo, se a tag anotada mais recente for "1.0" e houve 35 comissões desde então, a versão criada por Cinch seria semelhante a: 1.0-35-G2F657A
Para lançamentos reais, essa abordagem pode não ser ideal. Nesse caso, o Cinch permite substituir a versão automática especificando uma versão estática para cmake através da opção Version_creation. Basta definir isso na versão desejada e ele será usado.
Este software foi aprovado para liberação de código aberto e foi atribuído ao LA-CC-15-070 .
Copyright (c) 2016, Los Alamos National Security, LLC Todos os direitos reservados.
Copyright 2016. Los Alamos National Security, LLC. Este software foi produzido sob o contrato do governo dos EUA de-AC52-06NA25396 para o Laboratório Nacional de Los Alamos (LANL), que é operado pela Los Alamos National Security, LLC para o Departamento de Energia dos EUA. O governo dos EUA tem direitos de usar, reproduzir e distribuir este software. Nem o governo nem a Los Alamos National Security, LLC fazem qualquer garantia, expressa ou implícita, ou assume qualquer responsabilidade pelo uso deste software. Se o software for modificado para produzir obras derivadas, esse software modificado deve ser claramente marcado, para não confundi -lo com a versão disponível na LANL.
Além disso, são permitidas redistribuição e uso em formas de origem e binária, com ou sem modificação, desde que as seguintes condições sejam atendidas:
As redistribuições do código -fonte devem manter o aviso de direitos autorais acima, esta lista de condições e o seguinte aviso.
As redistribuições em formato binário devem reproduzir o aviso de direitos autorais acima, esta lista de condições e o seguinte aviso na documentação e/ou outros materiais fornecidos com a distribuição.
Nem o nome de Los Alamos National Security, LLC, o Laboratório Nacional de Los Alamos, LANL, o governo dos EUA, nem os nomes de seus colaboradores podem ser usados para endossar ou promover produtos derivados deste software sem permissão prévia por escrito específica.
Este software é fornecido pela Los Alamos National Security, LLC e colaboradores "como está" e quaisquer garantias expressas ou implícitas, incluindo, entre outros, as garantias implícitas de comercialização e aptidão para uma finalidade específica são isoladas. Em nenhum caso a Los Alamos National Security, LLC ou colaboradores será responsável por qualquer dano direto, indireto, incidental, especial, exemplar ou conseqüente (incluindo, entre outros Ou lucros; Tal dano.
