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 версии 7.0. В Unix-подобных системах, а также в Bash on Ubuntu on Windows можно использовать готовые пакеты LLVM и Clang, в ОС Windows потребуется сборка LLVM и Clang из исходных кодов (в этом случае дополнительно должен быть установлен Python версии 2.7).

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

Замечание. В ОС Windows для сборки анализатора необходимые версии LLVM и Clang могут быть загружены автоматически при конфигурации проекта с помощью CMake. При этом поддерживается только SVN-репозиторий LLVM и необходимо наличие установленной системы контроля версий Subversion, например, в виде TortoiseSVN. Путь к Subversion должен быть указан в переменной окружения PATH.
Данная возможность считается устаревшей и рекомендуется выполнять ручную загрузку монолитного репозитория LLVM размещенного на GitHub.

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

Предупреждение. Для сборки TSAR обязательно наличие LLVM версии 7.0, возможность сборки с использованием других версий LLVM не гарантируется. В случае использования монолитного GIT-репозитория переключится на ветвь, соответствующую требуемому выпуску LLVM, можно выполнив команду git checkout release/7.x. В случае сборки LLVM из ранее использовавшихся GIT-репозиториев необходимо переключить каждый подпроект (LLVM, Clang и т.д.) на ветвь release_70 отдельно. В случае использования SVN-репозитория сразу должны быть загружены нужные версии проектов LLVM.

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

Для сборки анализатора потребуется доступ к функциональности, предоставляемой 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 и Clang в виде пакетов, поэтому если при конфигурации в CMake требуемые пакеты не будут найдены будет выдана ошибка. Если планируется сборка LLVM и Clang из исходных кодов, то для продолжения сборки должна быть указана соответствующая опция (см. ниже), также может быть указан путь до требуемых пакетов (LLVM_DIR) и их версия (LLVM_VERSION), если они установлены в нестандартное расположение.

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

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

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

Для сборки инструментов нужны исходные коды, либо установленные пакеты LLVM и Clang, способ получения которых можно указать с помощью опций: PACKAGE_LLVM, LOCAL_LLVM, DOWNLOAD_LLVM.

Параметр 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, при необходимости дождаться загрузки LLVM и Clang. Далее снова нажать Configure, а после завершения - Generate.

PACKAGE_LLVM

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

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

sudo apt-get install llvm-7.0-dev libclang-7.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.

LOCAL_LLVM

Данная опция указывает на то, что LLVM и Clang были уже ранее загружены на локальный компьютер и сборка инструментов должна выполняться с использованием этих загруженных версий. Путь к загруженным версиям можно указать с помощью LLVM_SOURCE_DIR. При этом по умолчанию считается, что LLVM был загружен в виде монолитного репозитория, в этом случае LLVM_SOURCE_DIR должен указывать на подкаталог llvm внутри коревого каталога репозитория. Если LLVM был загружен из SVN-репозитория или из немонолитного GIT-репозитория, то необходимо отключить опцию LLVM_MONO_REPO.

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

DOWNLOAD_LLVM

Данная возможность считается устаревшей и рекомендуется выполнять ручную загрузку монолитного репозитория LLVM размещенного на GitHub.

Данная опция указывает на необходимость автоматической загрузки LLVM и Clang во время конфигурации проекта. Кроме того каждый раз при сборке проекта будет выполняться проверка наличия обновлений. Путь к репозиторию LLVM, Clang и опционально к репозиторию runtime-библиотеки профилировщика (опция BUILD_PROFILE) должны быть указан в LLVM_REPO, CLANG_REPO и COMPILER_RT_REPO соответственно. Версии LLVM и Clang должны быть согласованы, по умолчанию используется версия 7.0. Опция LLVM_SOURCE_DIR позволяет задать каталог, в который будут загружены компоненты LLVM.

Предупреждение. Автоматическая загрузка поддерживается только из SVN-репозиторий LLVM и требует устаноленной системы контроля версий Subversion, например, в виде TortoiseSVN. Путь к Subversion должен быть указан в переменной окружения PATH. При этом должна быть отключена опция LLVM_MONO_REPO.

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

В результате выполнения шагов, описанных выше в директории указанной в 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).
• 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
LOCAL_LLVM	выборочная сборка LLVM, Clang и runtime-библиотек вместе с SAPFOR	OFF
DOWNLOAD_LLVM	автоматическая загрузка LLVM, Clang и runtime-библиотек из SVN-репозитория при конфигурировании CMake (устаревшая возможность)	OFF
LLVM_MONO_REPO	указывает, что исходные коды LLVM расположены в монолитном репозитории	ON	LOCAL_LLVM
LLVM_SOURCE_DIR	путь до исходных кодов LLVM		LOCAL_LLVM DOWNLOAD_LLVM
LLVM_REPO	URL адрес SVN-репозитория LLVM	http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_700/final/	DOWNLOAD_LLVM
CLANG_REPO	URL адрес SVN-репозитория Clang	http://llvm.org/svn/llvm-project/cfe/tags/RELEASE_700/final/	DOWNLOAD_LLVM
COMPILER_RT_REPO	URL адрес SVN-репозитория runtime-библиотек	http://llvm.org/svn/llvm-project/compiler-rt/tags/RELEASE_700/final/	DOWNLOAD_LLVM
LLVM_VERSION	версия установленного пакета LLVM который должен быть использован для сборки анализатора	7.0	PACKAGE_LLVM
LLVM_DIR	позволяет указать путь до установленного пакет LLVM, если он не был найден автоматически		PACKAGE_LLVM
BUILD_TSAR	указывает необходимость сборки анализатора	ON	All
BUILD_DYNA	указывает сборки динамического анализатора, входящего в состав SAPFOR	OFF	All
BUILD_CLANG	указывает необходимость сборки компилятора Clang	OFF	LOCAL_LLVM DOWNLOAD_LLVM
BUILD_OPT	указывает необходимость сборки инструмента оптимизации LLVM	OFF	LOCAL_LLVM DOWNLOAD_LLVM
BUILD_LLC	указывает необходимость сборки компилятора LLVM IR	OFF	LOCAL_LLVM DOWNLOAD_LLVM
BUILD_PROFILE	указывает необходимость сборки runtime-библиотек для профилирования	OFF	LOCAL_LLVM DOWNLOAD_LLVM
TSAR_SERVER	указывает необходимость сборки анализатора в виде библиотеки	OFF	BUILD_TSAR
USE_JSON_BCL	активирует возможность получения результатов динамического анализа в JSON-формате, необходима для использования результатов динамического анализа в инструменте tsar	OFF	BUILD_DYNA
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	стандартная опция CMake позволяет использовать CTest в собираемом проекте (не требуется)	ON	All