clang_libraries_companion
v0.2.0
Dieses Repository enthält alle Code -Beispiele, die dem folgenden Foliendeck zugeordnet sind:
Das Dia Deck kann unter:
Das Repository ist wie folgt organisiert:
Jedes Codebeispiel oder jede Gruppe von Codebeispielen wird als separates CMake -Projekt strukturiert. Auf diese Weise können Benutzer mit einem individuellen Code -Beispiel experimentieren, ohne alle Codebeispiele erstellen zu müssen. Aus Gründen der Einschätzung werden zwei CMakelists.txt -Dateien bereitgestellt, die alle ihre untergeordneten Projekte erstellen. Alle Projekte können mit einem bereitgestellten Build -Skript erstellt werden (das diese beiden CMAKE -Superbauer aufruft).
Dieses Repository verwendet einen CI -Workflow, der auf GitHub -Aktionen basiert. Jedes Mal, wenn ein neues Komitee vorangetrieben wird, werden die Codebeispiele im Repository als grundlegende Vernunftstest durchgeführt. Dieser CI-Workflow dient als Beispiel, um zu zeigen, wie die LLVM/Clang Ubuntu-APT-Pakete, die vom LLVM-Projekt (unter https://apt.llvm.org/) bereitgestellt werden, in Github-hostierten Linux-Läufern verwendet werden können. Der CI -Workflow baut derzeit für einige Kombinationen der folgenden Kombinationen auf:
Die Code -Beispiele haben die folgenden Softwareabhängigkeiten:
Diese Abhängigkeiten müssen vor dem Erstellen der Code -Beispiele installiert werden.
Wenn die C ++ - Standardbibliothek STD :: Format nicht unterstützt, kann eine benutzerdefinierte Version der FMT -Bibliothek automatisch installiert werden (als Teil des Build -Prozesses), um diese Unterstützung bereitzustellen. (Diese benutzerdefinierte Version der FMT -Bibliothek enthält einen Standard -Bibliotheks -Header mit dem Namen "Format" und legt einige wichtige Deklarationen im STD -Namespace in diesem Header vor.) Die C ++ - Standardbibliothek, die in Version 13 und höher von GCC enthalten ist, hat Unterstützung für STD :: Format.
Aus Gründen der Einschätzung wird eine Dockerfile bereitgestellt, um eine containerisierte Umgebung zu erstellen, die alle erforderlichen Softwareabhängigkeiten enthält. Weitere Informationen zu dieser Dockerfile finden Sie in einem späteren Abschnitt.
Die Code-Beispiele verwenden einen CMake-basierten Build-Prozess. Jedes Codebeispiel oder jede Gruppe verwandter Beispiele wird als separates CMake -Projekt strukturiert. Aus Gründen der Bequemlichkeit wird ein Skript zur Erstellung aller Codebeispiele in einem Schritt bereitgestellt.
Einige der Codebeispiele erfordern STD :: Format (eingeführt in C ++ 20). Wenn die verwendete C ++ - Standard -Bibliotheksimplementierung STD :: Format nicht unterstützt, kann eine benutzerdefinierte Version der FMT -Bibliothek automatisch (als Teil des Build -Prozesses) installiert werden, um diese Unterstützung bereitzustellen.
Um alle Codebeispiele zu erstellen (und optional alle zugehörigen Demos ausführen), machen Sie Folgendes:
Initialisieren Sie die Umgebung so, dass die notwendigen Softwareabhängigkeiten (z. B. ausführbare Überschriften oder Bibliotheken) zum Bauzeit erfolgreich gefunden werden. Dieser Schritt ist in der Regel nur erforderlich, wenn einige der Softwareabhängigkeiten an Stellen installiert werden, an denen sie normalerweise nicht durch den Build -Prozess gefunden werden. Wenn dieser Schritt erforderlich ist, könnte er ungefähr wie folgt aussehen:
# 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
Setzen Sie das aktuelle Arbeitsverzeichnis auf das oberste Verzeichnis des Arbeitsbaums des geklonten Git-Repositorys.
Rufen Sie das Build -Skript mit den entsprechenden Optionen auf. Nominal wird das Skript wie folgt aufgerufen:
./build --defaults
Wenn die verwendete C ++-Standardbibliothek das STD :: Format unterstützt, kann die Option "-No-fmt" zum Aufruf des obigen Build-Skripts hinzugefügt werden (damit die benutzerdefinierte Version der FMT-Bibliothek nicht verwendet wird). Das heißt, der folgende Befehl kann verwendet werden:
./build --defaults --no-fmt
Das Build -Skript unterstützt zahlreiche Optionen. Für detaillierte Nutzungsinformationen rufen Sie das Skript mit der Option "-h" oder "-Help" auf. Die Befehlszeilenargumente werden in Reihenfolge von links nach rechts verarbeitet. In dem Fall, in dem eine Einstellung durch mehr als eine Befehlszeilenoption festgelegt wird, wirkt sich die Einstellung aus der Option rechts in Kraft.
Führen Sie die Demo -Skripte (als grundlegende Vernunftstest) mit dem Befehl aus:
./build --demo
Die Ausgabe des Build -Prozesses wird in den Verzeichnissen platziert:
Die Ausgabe für jedes CMAKE -Projekt wird in einem Verzeichnis mit demselben Namen wie in diesem Projekt platziert. Beispielsweise wird die Build-Ausgabe für das Projekt namens Cyclomatic_Complexität aus den Beispielen für Foliendeck im Verzeichnis platziert:
slides/examples/tmp_build/cyclomatic_complexity
Die meisten Projekte haben ein Demo -Skript (entweder "Demo" oder mit einem Namen, der "Demo" enthält). Verwenden Sie beispielsweise das Demo -Skript für das Projekt Cyclomatic_complexe, verwenden Sie den Befehl:
slides/examples/tmp_build/cyclomatic_complexity/demo
Es wird eine Dockerfile bereitgestellt, mit der ein Podman/Docker -Container mit allen erforderlichen Softwareabhängigkeiten zum Erstellen und Ausführen der Codebeispiele in diesem Repository erstellt werden kann. Anweisungen finden Sie nachstehend, wie diese Container -Umgebung verwendet wird. Obwohl diese Anweisungen (rootloser) Podman verwenden, haben die Podman- und Docker-Programme nahezu identische Befehlszeilenschnittstellen. Es sollte also möglich sein, "Podman" in den Anweisungen "Docker" zu ersetzen.
Lassen Sie $ top_dir das Verzeichnis der obersten Ebene des Arbeitsbaums des geklonten Git-Repositorys bezeichnen (dh das Verzeichnis, das die Datei mit dem Namen Readme.md enthält, die Sie derzeit lesen). Beachten Sie, dass $ top_dir ein absoluter Weg sein sollte.
Stellen Sie das Arbeitsverzeichnis mit dem Befehl auf das Verzeichnis der obersten Ebene des Arbeitsbaums fest:
cd $TOP_DIR
Erstellen Sie den Container mit dem Befehl:
podman build --tag cl-demo - < podman/Dockerfile
Erstellen Sie eine temporäre Instanz des Containers und führen Sie eine Bash -Shell im Container mit dem Befehl aus:
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
Beachten Sie, dass die Optionen "--cap-add" und "-Security-opt" möglicherweise nicht erforderlich sind.
Wenn Sie nicht möchten, dass der Container nach dem Abschluss der Bash-Shell gelöscht wird, lassen Sie die Option "-RM" weg.
Erstellen und führen Sie die Demo -Skripte aus, wie sie in einem früheren Abschnitt ausführlich beschrieben werden. Zum Beispiel könnte man den folgenden Befehl aus der Bash -Shell im Container aufrufen:
./build --defaults
Manchmal kann die Verwendung von Adresseinrichtungen (ASAN) problematisch sein, beispielsweise auf Macken in der Plattform, auf der der Code ausgeführt wird. Das Laufzeitverhalten von Asan kann über die Umgebungsvariable ASAN_Options kontrolliert werden, deren Wert eine dicker getrennte Liste von Schlüsselwertpaaren ist (z. B. "Ausführungen = 1: detect_leaks = 0").
Auf einigen Plattformen wurde beobachtet, dass einige der von den Code -Beispielen verwendeten Bibliotheken Speicherlecks aufweisen. Wenn Asan sich über einige Bibliotheken mit Speicherlecks beschwert, kann die Erkennung von Speicherlecks deaktiviert werden, indem die Liste der Asan -Optionen in der Umgebungsvariablen asan_options hinzugefügt wird. Beispielsweise können Asan_Options wie folgt festgelegt werden:
ASAN_OPTIONS=detect_leaks=0
Es scheint, dass die Benutzervergiftung des Speichers manchmal zu Fehlalarmen von ASAN (nämlich Nutzungsnutzungsfehler) führen kann, je nachdem, wie LLVM/Clang aufgebaut wurde. Dies ist wahrscheinlich auf Inkonsistenzen bei der Verwaltung der LLVM/Clang -Bibliotheken und der Anwendung mit diesen Bibliotheken zurückzuführen. Wenn dieses Problem auftritt, kann die Benutzervergiftung durch Hinzufügen von "degal_user_poisoning = 0" zu der Liste der Asan -Optionen in der Umgebungsvariablen asan_options in die Liste der ASAN -Optionen deaktiviert werden. Beispielsweise können Asan_Options wie folgt festgelegt werden:
ASAN_OPTIONS=allow_user_poisoning=0
Diese Software sollte mit den meisten UNIX-basierten Systemen zusammenarbeiten (vorausgesetzt, die erforderlichen Softwareabhängigkeiten sind installiert). Der GitHub CI -Workflow (oben diskutiert) stellt sicher, dass die Software auf Ubuntu Linux und macOS vernünftigerweise zuverlässig erstellen und ausführen sollte. Die Hauptentwicklungsplattform des Autors ist Fedora Linux. Die Software sollte also auch auf dieser Plattform ziemlich zuverlässig funktionieren.
