Building Guide

Сборка анализатора поддерживается как в Microsoft Windows так и в Unix-подобных системах. Начиная с Windows 10, c установленным Anniversary Update, возможна сборка анализатора в Bash on Ubuntu on Windows (инструкцию по установке Bash on Ubuntu on Windows можно посмотреть здесь). Для сборки системы необходимо наличие системы контроля версий Git, компилятора С++ с поддержкой С++11, CMake версии не ниже 3.4.3. Также необходимо наличие LLVM и Clang версии 11.0. В 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).

Замечание. Если планируется использовать анализатор для работы с программами на языке Фортран, то предварительно должен быть собран Flang, соответствующая инструкция по установке доступна здесь. Собранные таким образом пакеты LLVM и Clang должны быть далее использованы для сборки анализатора.

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

Возможность сборки проверена в ОС Windows 10 с помощью Microsoft Visual Studio Community 2019, в ОС Ubuntu 18.04 LTS c помощью GCC 7.5.0. Для построения проекта Visual Studio применялся CMake 3.17.3, для построения Makefile в OC Ubuntu и FreeBSD применялся CMake 3.10.2. Сборка в версиях Microsoft Visual Studio ниже Microsoft Visual Studio 2015 невозможна из-за недостаточной поддержки стандарта C++11 в поставляемом компиляторе.

Для сборки анализатора потребуется доступ к функциональности, предоставляемой 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 в виде серверного приложения, обеспечивающего возможность подключится к анализатору с помощью механизма сокетов для управления процессом анализа и преобразования программ.

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

Если включен режим сборки 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-11.0-dev libclang-11.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 который должен быть использован для сборки анализатора	11.0
LLVM_DIR	позволяет указать путь до установленного пакета LLVM, если он не был найден автоматически		PACKAGE_LLVM
BUILD_TSAR	указывает необходимость сборки анализатора	ON	All
BUILD_DYNA	указывает сборки динамического анализатора, входящего в состав SAPFOR	OFF	All
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
TSAR_SERVER	указывает необходимость сборки анализатора в виде серверного приложения	OFF	BUILD_TSAR
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