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。因此，该软件也应在此平台上可靠地工作。
