cinch
Release 1.0
CINCH est un ensemble d'options d'utilitaires et de configuration conçues pour rendre les versions CMake faciles à utiliser et à gérer.
CINCH utilise des fonctionnalités d'installation CMake standard. Cependant, parce que CINCH dépend de son propre outil de ligne de commande (CINCH-UTILS) pour construire sa documentation, il doit être installé dans les étapes documentées dans cette section.
Les instructions pour l'installation de CINCH-Utils sont là.
Pour installer la documentation CINCH, vous devez exécuter CMake dans le répertoire de construction CINCH avec la documentation activée:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
Le système de construction CINCH est conçu pour faciliter le développement du code modulaire. Par modulaire, nous voulons dire que des sous-projets peuvent être incorporés dans un projet de niveau supérieur basé sur CINCH, et ils seront automatiquement ajoutés aux cibles de construction du projet de niveau supérieur. Cela facilite la création de nouveaux projets qui combinent les capacités d'un ensemble de sous-projets. Cela permet aux utilisateurs de créer des fonctionnalités et de contrôler les fonctionnalités du projet de niveau supérieur.
CINCH interdit aux utilisateurs de créer des builds sur place, c'est-à-dire des builds qui sont enracinés dans le répertoire de projet de niveau supérieur d'un projet CINCH. Si l'utilisateur tente de configurer une telle build, CMake quittera une erreur et des instructions pour nettoyer et créer une version hors de source.
CINCH facilite la maintenance du système de construction en imposant une structure spécifique à la disposition de la source du projet.
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
Vous pouvez également avoir un certain nombre de sous-modules dans le répertoire du projet.
Le répertoire de niveau supérieur du projet.
Un sous-répertoire cible d'application. Les objectifs d'application peuvent être ajoutés à l'aide du CINCH_ADD_APPLICATION_DIRECTORY documenté ci-dessous. Ce sous-répertoire doit contenir un fichier cMakelists.txt qui ajoute les cibles CMake nécessaires pour l'application spécifique.
Le sous-répertoire CINCH. Cela devrait être consulté à partir du serveur CINCH GIT: «Git Clone - Recursif [email protected]: losalamos / cinch.git».
Créer un fichier, qui définit CMake_minimum_Required () et comprend le fichier CINCH projectlists.txt.
Le répertoire de configuration du projet. Ce répertoire est couvert en détail ci-dessous.
Le sous-répertoire de la documentation. Ce sous-répertoire doit contenir des fichiers de configuration pour la documentation du guide généré par CINCH et pour la documentation d'interface Doxygen.
Un sous-répertoire de la source cible de la bibliothèque. Les cibles de la bibliothèque peuvent être ajoutées à l'aide du CINCH_ADD_LIBRARY_TARGET documenté ci-dessous.
Le sous-répertoire de configuration doit contenir les fichiers suivants qui fournissent une spécialisation du projet. Bien que tous les fichiers doivent exister, le seul fichier nécessaire pour avoir du contenu est le fichier project.cmake .
Ce fichier ne peut pas être vide. Au minimum, il doit spécifier le nom du projet de niveau supérieur en appelant la fonction du projet CMake pour définir le nom, la version et les langues activées pour l'ensemble du projet. Pour plus de documentation, à une invite sur une machine avec une installation Cmake valide, Type:
% CMake - Projet d'assistance
De plus, ce fichier peut appeler la fonction CINCH suivante (ils peuvent également être laissés nuls):
cinch_add_application_directory (documenté ici)
Ajoutez un répertoire de construction spécifique au projet qui doit être inclus par CMake lors de la recherche de fichiers de liste. Ce répertoire doit contenir un fichier cMakelists.txt valide qui configure des cibles de construction supplémentaires.
cinch_add_library_target (documenté ici)
Ajoutez une cible de bibliothèque à construire pour ce projet.
cinch_add_subproject (documenté ici)
Ajoutez un sous-projet à ce projet.
Ce fichier est utilisé pour spécifier les exigences CMake find_package pour localiser les packages tiers installés. Le contenu de ce fichier peut être n'importe quel ensemble de commandes CMake valides. Les valeurs définies dans ce fichier seront disponibles sur les fichiers cmakelists.txt de bas niveau pour configurer des options de construction au niveau de la source.
Ce fichier est utilisé pour ajouter des cibles de documentation avec l'interface CINCH_ADD_DOC (la documentation DOXYGEN est gérée séparément).
CINCH fournit diverses options de ligne de commande qui peuvent être transmises sur la ligne de configuration CMake pour affecter son comportement.
Option CMake: activer_cinch_development (par défaut)
Mettez CINCH en mode de développement. Cette option affecte certaines des informations générées par CINCH, ce qui est utile pour les candidats non à libération. Si cette option est activée, elle allumera les fonctionnalités suivantes:
Option CMake: activer_cinch_verbose (par défaut)
Activer la sortie de construction plus détaillée.
Option CMake: activer_documentation (par défaut)
CINCH a une puissante installation de documentation implémentée à l'aide de l'utilitaire de commande de commande CINCH et de Pandoc. Pour créer une documentation, définissez un fichier de configuration pour chaque document qui doit être créé dans le sous-répertoire 'DOC'. Ensuite, ajoutez des fichiers Markdown (.MD) ou latex (.tex) à l'arborescence source qui documentent les aspects du projet. La mise en garde est que ces fragments de documentation devraient avoir un en-tête de commentaire spécial au début de chacun, de la forme:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
Cet en-tête spécial indique quel document le fragment est prévu et la section dans laquelle il devrait apparaître. Les en-têtes peuvent s'étendre sur plusieurs lignes à condition que <!-- CINCHDOC commence le commentaire. Si aucun attribution (document, section, etc.) n'est spécifié, l'utilitaire utilisera un document par défaut et une section («par défaut» et «par défaut»). Plusieurs fragments destinés à différents documents et sections peuvent être inclus dans un seul fichier d'entrée. Pour les fragments de latex, utilisez un en-tête de la forme:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
Les en-têtes Cinchdoc de style latex doivent être sur une seule ligne.
Des cibles de construction peuvent être ajoutées au fichier documentation.cmake dans le répertoire de configuration. Chaque cible doit être créée en appelant:
CINCH_ADD_DOC (Target-Name config.py Top-level-Level-Search-Directory Sortie)
Nom de la cible L'étiquette cible de build, c'est-à-dire une cible de marque sera créée de telle sorte que le nom de target peut être appelé pour générer la cible de documentation.
config.py un fichier de configuration qui doit vivre dans le sous-répertoire «doc» du répertoire de niveau supérieur de votre projet. Ce fichier doit contenir un seul dictionnaire Python qui définit les options d'interface de ligne de commande CINCH pour votre documentation.
Directory de recherche de niveau supérieur Le chemin relatif à la tête de l'arborescence du répertoire dans lequel rechercher des fichiers de documentation Markdown.
Sortie le nom du fichier de sortie qui doit être produit par Pandoc.
Option CMake: Activer_doxygen (par défaut) Option CMake: activer_doxygen_warn (par défaut)
CINCH prend en charge la documentation d'interface à l'aide de doxygen. Le fichier de configuration de Doxygen doit être appelé 'doxygen.conf.in' et doit résider dans le sous-répertoire 'doc'. Pour la documentation sur l'utilisation de Doxygen, veuillez consulter la page d'accueil de Doxygen.
Si activer_doxygen_warn est défini sur ON, les diagnostics et les avertissements normaux de doxygen ne seront pas supprimés.
Option CMake: activer_unit_tests (par défaut)
CINCH prend en charge les tests unitaires en utilisant une combinaison de CTEST (l'installation de test CMake native) et Googlest (pour le support C ++). Si les tests unitaires sont activés, CINCH créera une cible de «test». Des tests unitaires peuvent être ajoutés dans n'importe quel sous-répertoire du projet en créant simplement le code source de test et en ajoutant une cible à l'aide de la fonction 'CINCH_ADD_UNIT (cible [Source List])'.
CINCH vérifiera une installation locale Googlest sur le système pendant l'étape de configuration CMake. Si Googlest n'est pas trouvé, il sera construit par CINCH (le code source Googlest est inclus avec CINCH).
Option CMake: CLOG_ENABLE_STDLOG (par défaut)
Option CMake: Clog_strip_level (par défaut "0")
Option CMake: CLOG_TAG_BITS (par défaut "16")
Option CMake: Clog_Color_Output (par défaut)
CINCH prend en charge la trace, les informations, les avertissements, les erreurs et les rapports de journaux mortels (similaires à Google Log). Il existe deux styles d'interface pour les informations de journalisation à l'aide de Clog: Style d'insertion, par exemple,
clog (info) << "This is some information" << std::endl;et une interface de méthode, par exemple,
clog_info ( " This is some information " );Les deux styles d'interface sont disponibles pour tous les niveaux de gravité (discuté ci-dessous).
Remarque: le sabot est automatiquement disponible pour les tests d'unité 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 (gravité, message, n)
Sortie à chaque itération nième en utilisant la gravité et le message . Cette méthode n'est pas définie pour le niveau de gravité mortelle ou les affirmations.
Clog_assert (test, message)
Affirmer que le test est vrai. Si le test est faux, cet appel exécutera Clog_fatal (message) .
Clog_add_buffer (nom, osstream, colorisé)
Ajoutez le tampon défini par l'argument osstream dans rdbuf (). Le deuxième nom de paramètre est le nom de chaîne à associer au tampon et peut être utilisé dans les appels ultérieurs à l'interface de tampon de slog. Le dernier paramètre indique si le tampon prend en charge ou non la sortie de la couleur.
Clog_enable_buffer (nom)
Activez le tampon identifié par son nom .
Clog_Disable_Buffer (nom)
Désactivez le tampon identifié par son nom .
Clog peut écrire la sortie sur plusieurs flux de sortie à la fois. Les utilisateurs peuvent contrôler quels fichiers journaux de scog et la sortie sont créés en ajoutant et en activant / désactivant divers flux de sortie. Par défaut, Clog dirige la sortie vers STD :: Clog (il s'agit du journal C ++ par défaut et ne fait pas partie de Clog) lorsque la variable d'environnement Clog_enable_Stdlog est définie. D'autres flux de sortie doivent être ajoutés par l'application utilisateur. À titre d'exemple, si l'application utilisateur souhaitait que la sortie de slog se rende dans un fichier nommé output.log , on pourrait effectuer ce qui suit:
# 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 ;
} // mainLa sortie de slog peut être contrôlée au temps de compilation en spécifiant un niveau de gravité particulier. Tous les messages d'enregistrement avec un niveau de gravité inférieur à celui spécifié par Clog_strip_level seront désactivés. Notez que cela implique que Clog ne produira aucune sortie pour Clog_strip_level> = 5 .
Les différents niveaux de gravité ont le comportement suivant:
tracer
Activé uniquement pour la gravité du niveau 0 (moins de 1)
La sortie de trace convient aux informations de journalisation à grain fin.
informations
Activé pour les niveaux de gravité inférieurs à 2
La sortie d'informations convient aux informations de journalisation normales.
avertir
Activé pour les niveaux de gravité inférieurs à 3
La production d'avertissement est utile pour émettre des avertissements. Lorsque CLOG_COLOR_OUTPUT est activé, les messages avertis seront affichés en jaune.
erreur
Activé pour les niveaux de gravité inférieurs à 4
La sortie d'erreur est utile pour émettre des erreurs non mortelles. Lorsque Clog_Color_Output est activé, les messages d'erreur seront affichés en rouge.
fatal
Activé pour les niveaux de gravité inférieurs à 5
La sortie d'erreur mortelle est utile pour émettre des erreurs mortelles. Les erreurs fatales impriment un message, vider la trace actuelle de la pile et appeler std :: exit (1). Lorsque Clog_Color_Output est activé, les messages mortels seront affichés en rouge.
Le contrôle d'exécution de la sortie de slog est possible en ajoutant des sections de portée dans le code source. Ceux-ci sont appelés groupes de balises parce que la section lunette est étiquetée avec une balise. Le nombre de groupes de balises possibles est contrôlé par CLOG_TAG_BITS (par défaut 16). Les groupes de balises peuvent être activés ou désactivés lors de l'exécution en spécifiant la liste des groupes de balises à la fonction Clog_Init . Généralement, ceux-ci sont contrôlés par un drapeau de ligne de commande qui est interprété par l'application de l'utilisateur. Voici un exemple de code utilisant GFLAGS pour contrôler la sortie:
# 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 ;
} // mainExemple de code exécute:
% ./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
L'interface de sabot normal est implémentée via un ensemble de macros. Les utilisateurs avancés, qui ont besoin d'un plus grand contrôle sur Clog, peuvent créer leurs propres interfaces (macro ou autre) pour accéder directement à l'interface de scog de bas niveau. Les messages de journal dans Clog dérivent du type CINCH :: LOG_MESSAGE_T , qui fournit un constructeur, un destructeur virtuel et une méthode de flux virtuel:
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_tLes utilisateurs souhaitant personnaliser le sabot peuvent modifier le comportement par défaut en remplaçant les méthodes virtuelles de ce type et en fournissant des prédicats personnalisés. Une grande partie de la fonctionnalité de base du sabot est implémentée de cette manière, par exemple, le code suivant implémente la sortie de gravité du niveau de trace:
# 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
});Les utilisateurs intéressés doivent consulter le code source pour plus d'exemples.
Option CMake: version_création (par défaut «git décriv»)
CINCH peut créer automatiquement des informations de version pour les projets qui utilisent Git. Cette fonctionnalité utilise la fonction «git décrivent», qui crée une version à partir de la balise annotée la plus récente avec un niveau de correctif basé sur le nombre de valids depuis cette balise et une clé de hachage partielle. Par exemple, si la balise annotée la plus récente est "1.0" et qu'il y a eu 35 commits depuis, la version créée par CINCH serait similaire à: 1.0-35-G2F657A
Pour les versions réelles, cette approche peut ne pas être optimale. Dans ce cas, CINCH vous permet de remplacer le versioning automatique en spécifiant une version statique à CMake via l'option version_création. Réglez simplement ceci sur la version souhaitée et elle sera utilisée.
Ce logiciel a été approuvé pour la version open source et a été affecté à LA-CC-15-070 .
Copyright (C) 2016, Los Alamos National Security, LLC Tous droits réservés.
Copyright 2016. Los Alamos National Security, LLC. Ce logiciel a été produit dans le cadre du contrat du gouvernement américain De-AC52-06NA25396 pour le Los Alamos National Laboratory (LANL), qui est exploité par Los Alamos National Security, LLC pour le Département américain de l'énergie. Le gouvernement américain a le droit d'utiliser, de reproduire et de distribuer ce logiciel. Ni le gouvernement ni la sécurité nationale de Los Alamos, LLC ne garantissent, expressent ou implicites, ni assume toute responsabilité pour l'utilisation de ce logiciel. Si le logiciel est modifié pour produire des travaux dérivés, ces logiciels modifiés doivent être clairement marqués, afin de ne pas le confondre avec la version disponible auprès de LANL.
De plus, la redistribution et l'utilisation dans les formulaires source et binaire, avec ou sans modification, sont autorisées à condition que les conditions suivantes soient remplies:
Les redistributions du code source doivent conserver l'avis de droit d'auteur ci-dessus, cette liste de conditions et l'avertissement suivant.
Les redistributions sous forme binaire doivent reproduire l'avis de droit d'auteur ci-dessus, cette liste de conditions et la clause de non-responsabilité suivante dans la documentation et / ou d'autres documents fournis avec la distribution.
Ni le nom de Los Alamos National Security, LLC, Los Alamos National Laboratory, LANL, le gouvernement américain, ni les noms de ses contributeurs ne peuvent être utilisés pour approuver ou promouvoir des produits dérivés de ce logiciel sans autorisation écrite préalable spécifique.
Ce logiciel est fourni par Los Alamos National Security, LLC et les contributeurs "tel quel" et toutes les garanties expresses ou implicites, y compris, mais sans s'y limiter, les garanties implicites de qualité marchande et d'adéquation à des fins particulières sont déclinées. En aucun cas, LOS ALAMOS National Security, LLC ou contributeurs ne seront responsables de tout dommage directement, indirect, accessoire, spécial, exemplaire ou consécutif (y compris, mais sans s'y limiter Ou des bénéfices; ou une interruption d'entreprise) cependant causée et sur toute théorie de la responsabilité, que ce soit dans un contrat, une responsabilité stricte ou un délit (y compris la négligence De tels dégâts.
