clang_libraries_companion
v0.2.0
該存儲庫包含與以下幻燈片相關的所有代碼示例：
幻燈片甲板可下載：
存儲庫的組織如下：
每個代碼示例或一組代碼示例都是作為單獨的CMAKE項目構成的。這使用戶可以嘗試單個代碼示例，而無需構建所有代碼示例。為方便起見，提供了兩個cmakelists.txt文件，它們構建了所有下屬項目。所有項目都可以使用提供的構建腳本（調用這兩個Cmake Superbuilds）構建。
該存儲庫採用基於GitHub動作的CI工作流。每次推動新提交時，存儲庫中的代碼示例都會構建並作為基本的理智測試運行。該CI工作流是一個示例，以說明LLVM Project（在https://apt.llvm.org/）提供的LLVM/Clang Ubuntu APT軟件包如何在GitHub-Hosted Linux Runners中使用。 CI工作流目前構建以下幾種組合：
代碼示例具有以下軟件依賴性：
這些依賴項必須在構建代碼示例之前安裝。
如果C ++標準庫不支持STD ::格式，則可以自動安裝FMT庫的自定義版本（作為構建過程的一部分）以提供此支持。 （FMT庫的自定義版本提供了一個名為“格式”的標準庫標頭，並在該標頭的std名稱空間中放置了一些關鍵聲明。）C ++標準庫中包含的GCC版本13及更高版本包含STD ::格式。
為了方便起見，提供了一個Dockerfile，以構建包含所有必要軟件依賴性的容器化環境。以後的部分提供了有關此Dockerfile的更多信息。
代碼示例採用了基於CMAKE的構建過程。每個代碼示例或相關示例組均以單獨的CMAKE項目結構。為了方便起見，提供了一個腳本，用於構建所有代碼示例。
一些代碼示例需要std ::格式（在C ++ 20中引入）。如果使用的C ++標準庫實現不支持STD ::格式，則可以自動安裝FMT庫的自定義版本（作為構建過程的一部分），以提供此支持。
要構建所有代碼示例（並且可以選擇運行所有相關的演示），請執行以下操作：
初始化環境，以便將在構建時間成功找到必要的軟件依賴項（例如，可執行文件，標題或庫）。通常僅在某些軟件依賴項安裝在通常通過構建過程中找不到它們的位置時，才需要此步驟。當需要此步驟時，可能看起來像以下幾個：
# 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
將當前的工作目錄設置為克隆GIT存儲庫的工作樹的頂級目錄。
使用適當的選項調用構建腳本。名義上，腳本被調用如下：
./build --defaults
如果使用的C ++標準庫碰巧支持STD ::格式，則可以將“ -no-fmt”選項添加到上面的構建腳本的調用中（因此不使用FMT庫的自定義版本）。也就是說，可以使用以下命令：
./build --defaults --no-fmt
構建腳本支持許多選項。有關詳細的用法信息，請使用“ -h”或“ -help”選項調用腳本。命令行參數以從左到右順序進行處理。因此，如果通過多個命令行選項建立設置，則最右邊選項的設置會生效。
如果需要，請使用命令運行演示腳本（作為基本理智測試）：
./build --demo
構建過程的輸出放置在目錄中：
每個CMAKE項目的輸出都放置在具有與該項目相同名稱的目錄中。例如，將幻燈片示例中的名為Cyclomation_complexity的項目的構建輸出放置在目錄中：
slides/examples/tmp_build/cyclomatic_complexity
大多數項目都有一個演示腳本（稱為“演示”或包含“演示”的名稱）。例如，要運行Cyclomatic_complexity項目的演示腳本，請使用命令：
slides/examples/tmp_build/cyclomatic_complexity/demo
提供了可用於創建Podman/Docker容器的Dockerfile，該容器具有所有必要的軟件依賴項，用於在此存儲庫中構建和運行代碼示例。下面給出了有關如何使用此容器化環境的說明。儘管這些說明使用（無根）Podman，但Podman和Docker程序幾乎具有相同的命令行接口。因此，在說明中應該可以將“ Docker”代替“ Podman”。
令$ top_dir表示克隆git存儲庫的工作樹的頂級目錄（即，包含您當前正在讀取的名為readme.md的文件的目錄）。請注意，$ top_dir應該是絕對路徑。
使用命令將工作目錄設置為工作樹的頂級目錄：
cd $TOP_DIR
使用命令構建容器：
podman build --tag cl-demo - < podman/Dockerfile
創建容器的臨時實例，並使用命令在容器中運行bash殼：
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
請注意，可能不需要“ - cap-add”和“ - security-opt”選項。
如果您不希望在退出Bash Shell後刪除容器，請省略“ -RM”選項。
如前一節中所述，繼續構建並運行演示腳本。例如，可能會從容器中運行的bash shell中調用以下命令：
./build --defaults
有時，使用地址消毒劑（ASAN）可能會出現問題，例如，由於正在運行代碼的平台中的怪癖。可以通過環境變量Asan_options來控制ASAN的運行時行為，其值是鍵值對的結腸分離列表（例如，“ derboside = 1：detect_leaks = 0”）。
在某些平台上，已經觀察到代碼示例中使用的一些庫具有內存洩漏。如果Asan抱怨某些具有內存洩漏的庫，則可以通過在ASAN_Options環境變量中的ASAN選項列表中添加“ detect_leaks = 0”來禁用內存洩漏檢測。例如，可以將ASAN_OPTIONS設置為如下：
ASAN_OPTIONS=detect_leaks=0
似乎記憶中的用戶中毒有時會導致Asan的誤報（即使用後使用錯誤），具體取決於LLVM/Clang的構建方式。這可能是由於在LLVM/Clang庫中處理用戶中毒的方式以及使用這些庫的應用程序的不一致所致。如果遇到此問題，則可以通過將“ allow_user_poisoning = 0”添加到ASAN_OPTIONS環境變量中的ASAN選項列表中來禁用用戶中毒。例如，可以將ASAN_OPTIONS設置為如下：
ASAN_OPTIONS=allow_user_poisoning=0
該軟件應與大多數基於UNIX的系統一起使用（前提是安裝了必要的軟件依賴項）。 GitHub CI工作流（上面討論）確保該軟件應在Ubuntu Linux和MacOS上可靠地構建和運行。作者的主要開發平台是Fedora Linux。因此，該軟件也應在此平台上可靠地工作。
