clang_libraries_companion
v0.2.0
Этот репозиторий содержит все примеры кода, которые связаны со следующей слайд -колодой:
Слайд -колода доступна для скачивания по адресу:
Репозиторий организован следующим образом:
Каждый пример кода или группа примеров кода структурирована как отдельный проект Cmake. Это позволяет пользователям экспериментировать с отдельным примером кода без необходимости создавать все примеры кода. Для удобства предоставляется два файла cmakelists.txt, которые создают все свои подчиненные проекты. Все проекты могут быть построены с использованием предоставленного сценария сборки (который вызывает эти два супербилдея Cmake).
В этом хранилище используется рабочий процесс CI на основе действий GitHub. Каждый раз, когда появляется новый коммит, примеры кода в репозитории создаются и работают в качестве базового теста на здравомыслие. Этот рабочий процесс CI служит примером, чтобы показать, как пакеты LLVM/Clang Ubuntu APT, которые предоставляются проектом LLVM (по адресу https://apt.llvm.org/), могут использоваться в бегунах Linux с Github-hosted. Рабочий процесс CI в настоящее время создает несколько комбинаций следующего:
Примеры кода имеют следующие программные зависимости:
Эти зависимости должны быть установлены до создания примеров кода.
Если стандартная библиотека C ++ не поддерживает Format Std ::, пользовательская версия библиотеки FMT может быть автоматически установлена (как часть процесса сборки) для предоставления этой поддержки. (Эта пользовательская версия библиотеки FMT содержит стандартный заголовок библиотеки под названием «Формат» и помещает несколько ключевых объявлений в пространство имен STD в этом заголовке.) Стандартная библиотека C ++, включенная в версию 13 и выше GCC, имеет поддержку Format 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 ++, чтобы поддержать Format STD ::, опция «--не-FMT» может быть добавлена в вызов приведенного выше сценария сборки (так что пользовательская версия библиотеки FMT не используется). То есть можно использовать следующую команду:
./build --defaults --no-fmt
Сценарий сборки поддерживает множество вариантов. Для получения подробной информации об использовании, вызовите сценарий с помощью опции "-h" или "-help". Аргументы командной строки обрабатываются в правом порядке. Таким образом, в случае, когда настройка устанавливается более чем одной параметрами командной строки, настройка из самой правой опции вступает в силу.
При желании запустите демонстрационные сценарии (как базовый тест на здравомыслие) с командой:
./build --demo
Выход процесса сборки помещен в каталоги:
Вывод для каждого проекта Cmake помещается в каталог с тем же именем, что и этот проект. Например, вывод сборки для проекта, называемого cyclomatic_complexity из примеров слайд-падения, находится в каталоге:
slides/examples/tmp_build/cyclomatic_complexity
У большинства проектов есть демонстрационный сценарий (либо называемый «демонстрация», либо с именем, содержащим «демонстрацию»). Например, чтобы запустить демонстрационный скрипт для проекта Cyclomatic_complexity, используйте команду:
slides/examples/tmp_build/cyclomatic_complexity/demo
Представлен Dockerfile, который можно использовать для создания контейнера Podman/Docker со всеми необходимыми программными зависимостями для построения и запуска примеров кода в этом хранилище. Ниже приведены инструкции о том, как использовать эту контейнерную среду. Хотя эти инструкции используют (без корней) Podman, программы Podman и Docker имеют почти идентичные интерфейсы командной строки. Таким образом, должно быть возможно заменить «докера» на «Подман» в инструкциях.
Пусть $ 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, опустите опцию «--rm».
Перейдите, чтобы построить и запустить демонстрационные сценарии, как подробно описано в более раннем разделе. Например, можно вызвать следующую команду из оболочки Bash, работающей в контейнере:
./build --defaults
Иногда использование адресного дезинфицирующего средства (ASAN) может быть проблематичным, например, с причудами на платформе, на которой запускается код. Поведение ASAN выполнения может контролироваться с помощью переменной среды ASAN_OPTIONS, значение которого представляет собой список паров ключевых значений (например, "VERBOSITY = 1: DETECT_LEAKS = 0").
На некоторых платформах было обнаружено, что некоторые из библиотек, используемых примерами кода, имеют утечки памяти. Если Asan жалуется на некоторые библиотеки, имеющие утечку памяти, обнаружение утечки памяти может быть отключено, добавив «Detect_Leaks = 0» в список параметров ASAN в переменной среды ASAN_OPTIONS. Например, ASAN_OPTIONS можно установить следующим образом:
ASAN_OPTIONS=detect_leaks=0
Похоже, что отравление пользователем памяти иногда может привести к ложным срабатыванию от ASAN (а именно, ошибки использования-после-poison), в зависимости от того, как был построен LLVM/Clang. Вероятно, это связано с несоответствиями в том, как отравление пользователя обрабатывается в библиотеках LLVM/Clang и в приложении с использованием этих библиотек. Если эта проблема столкнулась, отравление пользователя может быть отключено, добавив «Allive_User_poisoning = 0» в список параметров ASAN в переменной среды ASAN_OPTIONS. Например, ASAN_OPTIONS можно установить следующим образом:
ASAN_OPTIONS=allow_user_poisoning=0
Это программное обеспечение должно работать с большинством систем на основе UNIX (при условии, что необходимые программные зависимости установлены). Рабочий процесс GitHub CI (обсуждаемый выше) гарантирует, что программное обеспечение должно быть достаточно надежно заработать и работать на Ubuntu Linux и MacOS. Основная платформа разработки автора - Fedora Linux. Таким образом, программное обеспечение также должно также довольно надежно работать на этой платформе.
