Building Guide

Сборка системы SAPFOR поддерживается как в Microsoft Windows так и в Unix-подобных системах. Начиная с Windows 10, c установленным Anniversary Update, возможна сборка анализатора в Bash on Ubuntu on Windows (инструкцию по установке Bash on Ubuntu on Windows можно посмотреть здесь).

Можно выполнить быструю сборку системы с предустановленными настройками используя Docker и редактор Microsoft Visual Studio Code, либо можно выполнить сборку в ручном режиме на поддерживаемых системах.

Get started with Docker

Данный способ сборки позволяет собрать систему SAPFOR со всеми компонентами (статический и динамический анализатор, интерактивная оболочка и система тестирования с базовым набором тестов) внутри контейнера, c возможностью использования и разработки SAPFOR с помощью редактора Microsoft Visual Studio Code.

Предварительно должны быть установлены:

1. Docker Desktop, инструкцию по установке можно найти здесь,
2. Microsoft Visual Stuido Code с расширением Remote Containers; данное расширение входит в пакет расширений Microsoft для С++ разработчиков C/C++ Extension Pack.

Чтобы создать контейнер необходимо:

1. Выполнить команду Visual Studio Code Remote-Containers: Clone Repository in Container Volume. Для этого необходимо в Visual Studio Code открыть Command Palette комбинацией клавиш Ctrl+Shift+P, ввести имя команды и нажать Enter.
2. В появившемся окне ввести путь до объединенного репозитория SAPFOR https://github.com/dvm-system/sapfor и нажать Enter. В результате будет создан контейнер на основе Ubuntu и установлены необходимые пакеты (загрузка и установка компонент может занять некоторое время).
3. Внутри контейнера выполнить команду Visual Studio Code CMake: Build (воспользовавшись Command Palette доступной по комбинации Ctrl+Shift+P). В результате будет выполнена сборка системы SAPFOR внутри контейнера.
4. Внутри контейнера выполнить команду Visual Studio Code CMake: Install. В результате анализатор системы SAPFOR станет доступен из интегрированного в Visual Studio Code терминала (комбинация Ctr+`), а запуск интерактивной оболочки стент возможен из контекстного меню доступного по щелчку правой конопки мыши на файлах, содержащих С/С++ код.

Замечание. Если при сборке SAPFOR значительно возрастает объем потребляемой оперативной памяти, то можно уменьшит количество одновременно запущенных задач. Для этого нужно октрыть панель настроек Visual Studio Code (выполнив комнаду Preferences: Open Settings (UI)) и явно указать значение свойства Cmake: Parallel Jobs для расширения CMake Tools configuration.

Customize your build

Для сборки системы необходимо наличие системы контроля версий Git, компилятора С++ с поддержкой С++17, CMake версии не ниже 3.4.3. Также необходимо наличие LLVM и Clang версии 15.x. В Unix-подобных системах, а также в Bash on Ubuntu on Windows можно использовать готовые пакеты LLVM и Clang, в ОС Windows потребуется сборка LLVM и Clang из исходных кодов (в этом случае дополнительно должен быть установлен Python версии 2.7).

Исходные коды LLVM и Clang могут быть загружены из официального монолитного GIT-репозитория. Для конфигурирования сборки SAPFOR используется CMake, при этом LLVM и Clang могут быть собраны/установлены отдельно в виде пакетов, либо их сборка может быть сконфигурирована автоматически вместе с SAPFOR (см. соответствующие опции CMake ниже). Инструкцию по сборке LLVM и Clang можно найти здесь (важно, чтобы в списке собираемых пакетов был указан clang).

Предупреждение. Для сборки TSAR обязательно наличие LLVM версии 15.x, возможность сборки с использованием других версий LLVM не гарантируется. Переключится на ветвь, соответствующую требуемому выпуску LLVM, можно выполнив команду git checkout release/15.x.

Возможность сборки проверена в ОС Windows 10 с помощью Microsoft Visual Studio Community 2022, в ОС Ubuntu 20.04 LTS c помощью GCC 9.3.0. Для построения проекта Visual Studio применялся CMake 3.17.3, для построения Makefile в OC Ubuntu применялся CMake 3.16.3.

Для сборки анализатора потребуется доступ к функциональности, предоставляемой Base Construction Library (BCL) и доступной из репозитория BCL. Для удобства сборки может быть использован репозиторий SAPFOR, интегрирующий основные компоненты системы SAPFOR. Для его загрузки следует выполнить:

git clone --recurse-submodules https://github.com/dvm-system/sapfor
git submodule foreach git fetch origin
git submodule foreach git checkout master

Предположим, что репозиторий уже загружен и локальная копия создана в каталоге path-to-sapfor.

Сборка системы выполняется в два этапа:

1. Построение проекта для Microsoft Visual Studio или Makefile с помощью инструмента CMake.
2. Сборка системы средствами Microsoft Visual Studio или утилиты make.

Построение проекта с помощью CMake

Запускаем графический интерфейс с помощью команды cmake-gui:

Предупреждение. Для работы с графическим интерфейсом в Bash on Ubuntu on Windows необходимо в ОС Windows 10 предварительно установить и запустить Xming X Server for Windows. Кроме того, в Bash один раз нужно отредактировать файл .bashrc, расположенный в домашней директории, добавив в его конец строку export DISPLAY=localhost:0.0. Чтобы изменения вступили в силу нужно выполнить команду source .bashrc.

1. В поле Where is the source-code указываем пусть к общему репозиторию SAPFOR path-to-sapfor.
2. В поле Where to build the binaries указываем путь, где должен располагаться проект Microsoft Visual Studio или makefile в случае Unix-подобной ОС.
3. Нажимаем кнопку Configure.
4. Если директории, где предполагается разместить проект не существует, то в появившемся окне нажимаем Yes.
5. В появившемся окне выбираем установленную версию Microsoft Visual Studio (ОС Windows) или доступный компилятор GCC, Clang (Unix-подобная ОС) нажимаем Finish. При использовании Microsoft Visual Studio для сборки LLVM рекомендуется использовать опцию -Thost=x64. Это связано с тем, что Visual Studio по умолчанию использует x86 компилятор для сборки даже 64-разрядных проектов. Данную опцию можно задать Графический интерфейс CMake версии 3.15.3 позволяет задать данную при выборе версии Visual Studio, в соответсвующем окне нужно указать host=x64. Также данную опцию можно указать при использовании CMake из командной строки.

Visual Studio generators use the x86 host compiler by default, even for 64-bit targets.
This can result in linker instability and out of memory errors.
To use the 64-bit host compiler, pass -Thost=x64 on the CMake command line.

Красным цветом будут выделены появившиеся после конфигурации опции сборки.

Для сборки анализатора и других инструментов требуются исходные коды LLVM, если опция PACKAGE_LLVM отключена, или ранее установленные пакеты LLVM и Clang, если данная опция установлена.

Предупреждение. По умолчанию установлен режим, предполагающий сборку необходимых библиотек LLVM из исходных кодов. В этом режиме путь до директории с исходными кодами должен быть задан в LLVM_PROJECT_DIR. Для использования ранее установленных/собранных пакетов LLVM должна быть установлена опция PACKAGE_LLVM. Путь до требуемых пакетов (директория, в которой расположен файл LLVMConfig.cmake) может быть указан с помощью LLVM_DIR. Точная версия используемых пакетов LLVM может быть задана с помощью LLVM_VERSION.

Основные собираемые инструменты, входящие в состав системы SAPFOR, могут быть выбраны с помощью следующих опций:

• BUILD_TSAR - включает сборку статического анализатор TSAR системы SAPFOR в проект,
• BUILD_DYNA - включает сборку динамического анализатора DYNA системы SAPFOR в проект,
• TSAR_SERVER - включает сборку статического анализатора TSAR в виде серверного приложения, обеспечивающего возможность подключится к анализатору с помощью механизма сокетов для управления процессом анализа и преобразования программ,
• BUILD_ADVISOR - включает сборку и установку интерактивной оболочки системы SAPFOR, реализованной в виде расширения редактора Microsoft Visual Studio Code, для ее использования исходные коды расширения должны быть размещены в директории path-to-sapfor/gui.

Предупреждение. Для сборки TSAR обязательно наличие LLVM версии 15.x.

Если включен режим сборки LLVM из исходных кодов, то дополнительно к анализатору TSAR в одном проекте возможна одновременная сборка следующих инструментов LLVM :

• BUILD_CLANG - включает сборку C/C++ компилятора Clang в проект,
• BUILD_OPT - включает сборку средства оптимизации программ opt в проект,
• BUILD_LLC - включает сборку статического компилятора внутреннего представления LLVM llc в проект,
• BUILD_PROFILE - включает сборку runtime-библиотеки для построения покрытия исходного кода программы с помощью Clang в проект.

Параметр CMAKE_INSTALL_PREFIX указывает конечный путь установки инструментов после сборки проекта INSTALL в Visual Studio или после выполнения команды make install. Если задать указанный путь в переменной окружения PATH, то инструменты могут быть использованы из любого места на локальной машине. Параметр CMAKE_CONFIGURATION_TYPES, доступный в OC Windows, указывает какие конфигурации проекта должны быть построены, например: Release и Debug. Конкретную конфигурацию сборки можно выбрать непосредственно в Visual Studio. В случае Unix-подобных OC доступен параметр CMAKE_BUILD_TYPE, позволяющий задать под какую конфигурацию будет настроен Makefile. Для сборки проекта в другой конфигурации в случае Unix-подобных OC необходимо перезапустить cmake, указав нужную конфигурацию.

Также доступны дополнительные опции, позволяющие сконфигурировать сборку и установку библиотеки BCL, а также структуру папок используемую в представлении проекта в Visual Studio.

После того, как настройки были выполнены нужно нажать Configure. Может потребоваться нажать Configure несколько раз, так как некоторые параметры сборки, зависящие от других параметров, становятся доступны только после конфигурирования параметров, от которых они зависят. Когда конфигурация будет окончательно завершена и все параметры заданы, необходимо нажать Generate.

По умолчанию (опция PACKAGE_LLVM отключена) необходимые компоненты LLVM собираются из иходных кодов в процессе сборки анализатора. Путь к исходным кодам LLVM можно указать с помощью LLVM_PROJECT_DIR. При этом по умолчанию считается, что LLVM был загружен в виде монолитного репозитория (опция LLVM_PROJECT_DIR должна указывать на корневую директорию).

Предупреждение. Если выбрана опция сборки LLVM из исходных кодов, дополнительно должен быть установлен Python версии 2.7.

PACKAGE_LLVM

Если установлена, то данная опция подразумевает, что LLVM и Clang уже установлены и должны использоваться в качестве отдельных пакетов, а не собираться вместе с анализатором TSAR. Опция поддерживается как на Unix-подобных системах, так и в OC Windows.

В Unix-подобных системах должны быть установлены следующие пакеты (на примере Ubuntu 18.04 LTS):

sudo apt-get install llvm-15.0-dev libclang-15.0-dev zlib1g-dev

Предупреждение. При возникновении ошибок во время поиска нужных библиотек следует проверить были ли добавлены пути к нужным репозиториям в файле /etc/apt/sources.list. В данном файле должны присутствовать репозитории вида deb http://apt.llvm.org/ ... и deb-src http://apt.llvm.org/ ... . Точные пути в зависимости от версии операционной системы доступны здесь. При необходимости они могут быть добавлены в /etc/apt/sources.list вручную.

В ОС Windows соответствующие пакеты могут быть собраны из исходных кодов. В зависимости от того, какие были использованы библиотеки при сборке LLVM (опции Visual Studio /MDd (Debug) или /MD (Release)) необходимо выставить опцию LLVM_PACKAGE_DEBUG.

Если LLVM требуемой версии не будет найдена автоматически, то можно использовать переменные CMake LLVM_DIR и LLVM_VERSION для задания пути до конфигурационных файлов LLVM и требуемой версии LLVM.

Сборка сконфигурированного проекта

В результате выполнения шагов, описанных выше в директории указанной в Where to build the binaries будет создан проект Microsoft Visual Studio с названием SAPFOR или Makefile.

Сборка инструментов в Microsoft Visual Studio или с помощью утилиты make происходит в два этапа. Первый этап включает в себя сборку инструментов и сохранение соответствующих исполняемых файлов, библиотек и т.д. внутри проекта. На следующем этапе сборка специального проекта INSTALL или выполнение make install позволяет скопировать собранные инструменты в директорию указанную в CMAKE_INSTALL_PREFIX.

Структура проекта Visual Studio будет следующей:

• tsar - проект статического анализатора TSAR (доступен при наличии опции BUILD_TSAR).
• tsar-server - проект статического анализатора в виде серверного приложения (доступен при наличии опции TSAR_SERVER).
• TSARServer - проект статического анализатора в виде динамической библиотеки (доступен при наличии опции TSAR_SERVER).
• TSARTool - ядро статического анализатора (собирается на основе проектов с префиксом TSAR), используемое в tsar и TSARServer.
• da - runtime-библиотека динаического анализатора SAPFOR (подробнее см. раздел Instrumentation).
• CLANG_BUILD - проект компилятора Clang (доступен при наличии опции BUILD_CLANG).
• OPT_BUILD - проект средства оптимизации opt (доступен при наличии опции BUILD_OPT).
• LLC_BUILD - проект статического компилятора внутреннего представления LLVM llc (доступен при наличии опции BUILD_LLC).
• PROFILE_BUILD - runtime-библиотека для построения покрытия исходного кода (доступна при наличии опции BUILD_PROFILE).
• ALL_BUILD - проект для сборки всех инструментов (в зависимости от опций CMake).
• INSTALL - проект расположен в CMakePredefinedTargets и применяется для конечной установки инструментов по пути указанном в CMAKE_INSTALL_PREFIX.
• Вспомогательные проекты, нужные для сборки.

Чтобы собрать и установить все инструменты нужно последовательно собрать проекты ALL_BUILD и INSTALL в Visual Studio, либо выполнить в директории, указанной в Where to build the binaries:

make
sudo make install

Допускается многопоточная сборка, для этого может быть использована опция -j утилиты make, например, для сборки на 6-ядерном процессоре может использовать

make -j6

Переменные, используемые для конфигурации CMake

Имя	Описание	Умолчание	Совместимость
PACKAGE_LLVM	сборка SAPFOR на основе предварительно установленных пакетов LLVM и Clang	ON
LLVM_PROJECT_DIR	путь до исходных кодов LLVM		PACKAGE_LLVM=OFF
LLVM_VERSION	версия установленного/собираемого пакета LLVM который должен быть использован для сборки анализатора	15.0
LLVM_DIR	позволяет указать путь до установленного пакета LLVM, если он не был найден автоматически		PACKAGE_LLVM
BUILD_TSAR	указывает необходимость сборки анализатора	ON	All
TSAR_SERVER	указывает необходимость сборки анализатора в виде серверного приложения	OFF	BUILD_TSAR
BUILD_DYNA	указывает необходимость сборки динамического анализатора, входящего в состав SAPFOR	OFF	All
BUILD_ADVISOR	указывает необходимость сборки интерактивной оболочки SAPFOR в виде расширения редактора Microsoft Visual Studio Code	OFF	TSAR_SERVER
BUILD_CLANG	указывает необходимость сборки компилятора Clang	OFF	PACKAGE_LLVM=OFF
BUILD_OPT	указывает необходимость сборки инструмента оптимизации LLVM	OFF	PACKAGE_LLVM=OFF
BUILD_LLC	указывает необходимость сборки компилятора LLVM IR	OFF	PACKAGE_LLVM=OFF
BUILD_PROFILE	указывает необходимость сборки runtime-библиотек для профилирования	OFF	PACKAGE_LLVM=OFF
USE_JSON_BCL	активирует возможность получения результатов динамического анализа в JSON-формате, необходима для использования результатов динамического анализа в инструменте tsar	OFF	BUILD_DYNA
TSAR_DIRTY_BUILD	отключает указание номера фиксации в GIT-репозитории TSAR при задании версии системы SAPFOR	ON	ALL
TSAR_ENABLE_LLVM_DUMP	разрешает использовать методы LLVM dump() при отладочной сборке анализатора, может быть отключена при ошибках компоновки, вызванных разными типами сборки LLVM и TSAR (например, Release и Debug соответственно)	ON	All
LLVM_PACKAGE_DEBUG	указывает тип сборки пакета LLVM, если он не может быть определен автоматически, позволяет устранить проблемы компоновки, вызванные использование разных версий системных библиотек в LLVM и TSAR	OFF	PACKAGE_LLVM Windows ОS
CMAKE_INSTALL_PREFIX	путь установки всех собранных компонент (проект INSTALL Visual Studio или результат make install)	Определяется CMake	All
TSAR_FOLDER	каталог в IDE разработчика для проекта инструмента tsar	Tools	All, Windows ОS
TSAR_SERVER_FOLDER	каталог в IDE разработчика для проекта библиотеки TSARServer	Tools	All, Windows ОS
TSAR_LIBRARY_FOLDER	каталог в IDE разработчика для проектов вспомогательных библиотек TSAR...	Tsar libraries	All, Windows ОS
DYNA_FOLDER	каталог в IDE разработчика для проекта библиотеки динамического анализа DYNA	DYNA Runtime	BUILD_DYNA
BCL_INSTALL	указывает необходимость установки BCL (Base Construction Library), входящей в состав в SAPFOR при установки остальных собранных компонентов	ON	All
BCL_EXAMPLE	указывает необходимость установки примеров, входящих в состав BCL (не требуется)	ON	All
BCL_LEGACY	позволяет использовать устаревшие части BCL (не требуется)	OFF	All
BCL_NODEJS_SOCKET	позволяет использовать обертку вокруг Node.js, входящую в состав BCL, для организации клиент-серверного взаимодействия (не требуется)	ON	ALL
BCL_TEST	включает тесты в сборку BCL	ON	BUILD_TESTING
BUILD_TESTING	включает тесты в сборку SAPFOR, позволяет использовать CTest для тестирования (см. здесь)	ON	PTS_EXECUTABLE
PTS_EXECUTABLE	указывает путь до установленного инструмена PTS, используемого для запуска тестов (см. здесь)		ALL