clang_libraries_companion
v0.2.0
Ce référentiel contient tous les exemples de code associés au jeu de diapositives suivant:
Le jeu de diapositives est disponible en téléchargement sur:
Le référentiel est organisé comme suit:
Chaque exemple de code ou groupe d'exemples de code est structuré comme un projet CMake distinct. Cela permet aux utilisateurs d'expérimenter avec un exemple de code individuel sans avoir à créer tous les exemples de code. Pour plus de commodité, deux fichiers cMakelists.txt sont fournis pour construire tous leurs projets subordonnés. Tous les projets peuvent être construits à l'aide d'un script de construction fourni (qui invoque ces deux superbuilds CMake).
Ce référentiel utilise un flux de travail CI basé sur les actions GitHub. Chaque fois qu'un nouveau commit est poussé, les exemples de code dans le référentiel sont construits et exécutés en tant que test de santé mentale de base. Ce flux de travail CI sert d'exemple pour montrer comment les packages LLVM / Clang Ubuntu APT qui sont fournis par le projet LLVM (sur https://apt.llvm.org/) peuvent être utilisés dans les coureurs Linux Hosted Hosted. Le flux de travail CI se construit actuellement pour quelques combinaisons de ce qui suit:
Les exemples de code ont les dépendances logicielles suivantes:
Ces dépendances doivent être installées avant de construire les exemples de code.
Si la bibliothèque standard C ++ ne prend pas en charge le format STD ::, une version personnalisée de la bibliothèque FMT peut être automatiquement installée (dans le cadre du processus de construction) pour fournir cette prise en charge. (Cette version personnalisée de la bibliothèque FMT fournit un en-tête de bibliothèque standard appelé "Format" et place quelques déclarations de clés dans l'espace de noms STD dans cet en-tête.) La bibliothèque standard C ++ incluse avec la version 13 et supérieure de GCC a pris en charge le format STD ::.
Pour plus de commodité, un Dockerfile est fourni afin de créer un environnement conteneurisé qui comprend toutes les dépendances logicielles nécessaires. Plus d'informations sur ce dockerfile sont fournies dans une section ultérieure.
Les exemples de code utilisent un processus de construction basé sur CMake. Chaque exemple de code ou groupe d'exemples connexes est structuré comme un projet CMake distinct. Pour plus de commodité, un script est fourni pour construire tous les exemples de code en une seule étape.
Certains exemples de code nécessitent un format std :: (introduit dans C ++ 20). Si l'implémentation de la bibliothèque standard C ++ utilisée ne prend pas en charge le format STD ::, une version personnalisée de la bibliothèque FMT peut être automatiquement installée (dans le cadre du processus de construction) pour fournir cette prise en charge.
Pour créer tous les exemples de code (et exécuter éventuellement toutes les démos associées), procédez comme suit:
Initialiser l'environnement de telle sorte que les dépendances logicielles nécessaires (par exemple, les exécutables, les en-têtes ou les bibliothèques) seront trouvées avec succès au moment de la construction. Cette étape n'est généralement requise que si certaines dépendances logicielles sont installées dans des emplacements où ils ne seraient normalement pas trouvés par le processus de construction. Lorsque cette étape est nécessaire, elle peut ressembler à ce qui suit:
# Initialize the following variables used to configure the
# environment:
# cmake_dir
# - The directory under which CMake has been installed
# (e.g., /usr, /usr/local).
# clang_dir
# - The directory under which LLVM/Clang has been installed
# (e.g., /usr, /usr/local).
# gcc_dir
# - The directory under which GCC has been installed
# (e.g., /usr, /usr/local).
# boost_dir
# - The directory under which Boost has been installed
# (e.g., /usr, /usr/local).
# Use the preceding variables to configure the environment by
# setting several key environment variables:
export BOOST_INCLUDEDIR=$boost_dir/include
export BOOST_LIBRARYDIR=$boost_dir/lib
export PATH=$cmake_dir/bin:$clang_dir/bin:$gcc_dir/bin:$PATH
export LD_LIBRARY_PATH=$BOOST_LIBRARYDIR:$LD_LIBRARY_PATH
export CPATH=$boost_dir/include:$CPATH
Définissez le répertoire de travail actuel sur le répertoire de niveau supérieur de l'arborescence fonctionnelle du référentiel GIT cloné.
Invoquez le script de construction avec les options appropriées. Nominalement, le script est invoqué comme suit:
./build --defaults
Si la bibliothèque standard C ++ utilisée se produit pour prendre en charge le format STD ::, l'option "--no-fmt" peut être ajoutée à l'invocation du script de construction ci-dessus (afin que la version personnalisée de la bibliothèque FMT ne soit pas utilisée). C'est-à-dire que la commande suivante peut être utilisée:
./build --defaults --no-fmt
Le script de construction prend en charge de nombreuses options. Pour des informations détaillées d'utilisation, appelez le script avec l'option "-h" ou "- help". Les arguments en ligne de commande sont traités par ordre de gauche à droite. Ainsi, dans le cas où un paramètre est établi par plus d'une option de ligne de commande, le paramètre de l'option la plus à droite prend effet.
Si vous le souhaitez, exécutez les scripts de démonstration (comme test de base de base) avec la commande:
./build --demo
La sortie du processus de construction est placée dans les répertoires:
La sortie de chaque projet CMake est placée dans un répertoire ayant le même nom que ce projet. Par exemple, la sortie de build pour le projet appelé cyclomatic_complexity à partir des exemples de pont de diapositives est placé dans le répertoire:
slides/examples/tmp_build/cyclomatic_complexity
La plupart des projets ont un script de démonstration (soit appelé "démo", soit avec un nom contenant "démo"). Par exemple, pour exécuter le script de démonstration du projet Cyclomatic_Complexity, utilisez la commande:
slides/examples/tmp_build/cyclomatic_complexity/demo
Un dockerfile est fourni qui peut être utilisé pour créer un conteneur Podman / Docker avec toutes les dépendances logicielles nécessaires pour la création et l'exécution des exemples de code dans ce référentiel. Des instructions sont données ci-dessous sur la façon d'utiliser cet environnement conteneurisé. Bien que ces instructions utilisent Podman (sans racine), les programmes Podman et Docker ont des interfaces de ligne de commande presque identiques. Il devrait donc être possible de remplacer "docker" par "podman" dans les instructions.
Soit $ top_dir le répertoire de niveau supérieur de l'arborescence fonctionnelle du référentiel GIT cloné (c'est-à-dire le répertoire qui contient le fichier nommé Readme.md que vous lisez actuellement). Notez que $ top_dir doit être un chemin absolu.
Définissez le répertoire de travail sur le répertoire de niveau supérieur de l'arborescence de travail à l'aide de la commande:
cd $TOP_DIR
Construisez le conteneur à l'aide de la commande:
podman build --tag cl-demo - < podman/Dockerfile
Créez une instance temporaire du conteneur et exécutez un shell bash dans le conteneur à l'aide de la commande:
podman run -i -t --rm -v $TOP_DIR:$TOP_DIR:rw -w $TOP_DIR
--cap-add=SYS_PTRACE --security-opt label=disable
cl-demo /bin/bash
Notez que les options "--CAP-ADD" et "- Security-OPT" peuvent ne pas être nécessaires.
Si vous ne voulez pas que le conteneur soit supprimé après la sortie du shell bash, omettez l'option "--rm".
Procédez pour construire et exécuter les scripts de démonstration comme décrit en détail dans une section antérieure. Par exemple, on peut invoquer la commande suivante de la coque bash fonctionnant dans le conteneur:
./build --defaults
Parfois, l'utilisation du désinfectant d'adresse (ASAN) peut être problématique, en raison, par exemple, des bizarreries dans la plate-forme sur laquelle le code est exécuté. Le comportement d'exécution de l'ASAN peut être contrôlé via la variable d'environnement ASAN_OPTIONS, dont la valeur est une liste séparée par le côlon de paires de valeurs clés (par exemple, "verbosité = 1: détect_leaks = 0").
Sur certaines plateformes, certaines des bibliothèques utilisées par les exemples de code ont été observées pour avoir des fuites de mémoire. Si ASAN se plaint de certaines bibliothèques ayant des fuites de mémoire, la détection des fuites de mémoire peut être désactivée en ajoutant "Detect_leaks = 0" à la liste des options ASAN dans la variable d'environnement ASAN_OPTIONS. Par exemple, ASAN_OPTIONS peut être défini comme suit:
ASAN_OPTIONS=detect_leaks=0
Il semble que l'empoisonnement des utilisateurs de la mémoire puisse parfois entraîner des faux positifs d'ASAN (à savoir, les erreurs d'observation de l'utilisation), selon la façon dont LLVM / Clang a été construite. Cela est probablement dû à des incohérences dans la façon dont l'empoisonnement des utilisateurs est géré dans les bibliothèques LLVM / Clang et l'application à l'aide de ces bibliothèques. Si ce problème est rencontré, l'empoisonnement des utilisateurs peut être désactivé en ajoutant "allow_user_poising = 0" à la liste des options ASAN dans la variable d'environnement ASAN_OPTIONS. Par exemple, ASAN_OPTIONS peut être défini comme suit:
ASAN_OPTIONS=allow_user_poisoning=0
Ce logiciel devrait fonctionner avec la plupart des systèmes basés sur UNIX (à condition que les dépendances logicielles nécessaires soient installées). Le flux de travail GitHub CI (discuté ci-dessus) garantit que le logiciel doit construire et s'exécuter de manière raisonnable sur Ubuntu Linux et MacOS. La principale plate-forme de développement de l'auteur est Fedora Linux. Ainsi, le logiciel devrait également fonctionner de manière assez fiable sur cette plate-forme.
