User Guide

Статический анализатор TSAR принимает на вход файл, содержащий программу на языке С/С++, либо внутреннее представление LLVM (LLVM IR). Тип файла определяется по расширению, для файлов содержащих LLVM IR должно быть задано расширение *.ll.

Запустить анализатор можно командой

tsar [ options ] < source0 > [...< sourceN >]

Все доступные опции можно посмотреть выполнив

tsar -help

Опции разделены на следующие категории:

• Compilation options управляют обработкой исходных кодов (основные стандартные опции компиляторов), выдачей диагностических сообщений, в данной группе также содержаться опции, отвечающие за инструментацию программ для выполнения динамического анализа.

• Analysis options управляют выполнением анализа программ.

• Debugging options позволяют получить результаты различных анализов, доступных в TSAR (-print-only=), в данной группе также содержаться опции доступные при сборке анализатора в отладочном режиме, позволяющие получить подробную информацию о выполнении проходов TSAR.

• General options, данная группа содержит опции для запуска доступных преобразований исходных кодов (source-to-source), а также опции отображающие структуру памяти, используемой в программе.

• Transformation options управляют выполняемыми преобразованиями.

Особенности анализа программ рассмотрены здесь, подробнее о преобразовании программ можно посмотреть здесь, возможности инструментации программ для выполнения динамического анализа описаны здесь.

Опция -help отображает только основные опции, посмотреть дополнтиельные опции можно, воспользовавшись опцией -help-hidden.

JSON Compilation Database

Информация, необходимая для выполнения синтаксического и семантического анализ исходного кода, также может быть задана с помощью JSON Compilation Database, которая может быть загружена из файла compile_commands.json.

Чтобы указать путь к директории, в которой расположен данный файл можно воспользоваться опцией -build-path, или -p. Опции, непосредственно управляющие статическим анализом программы, должны быть заданы явно в командной строке и не должны быть указаны в Compilation Database. При использовании compile_comands.json все явно указанные в командной строке опции, также будут использованы при анализе программы.

Файл compile_commands.json моежт быть написан вручную или построен автоматически с помощью инструмента CMake (в случае генерации Makefile или Ninja). В случае использования CMake необходимо задать опцию CMAKE_EXPORT_COMPILE_COMMANDS.

Работа с многофайловым проектом

Исследование программ, образованных набором из нескольких файлов на языке С/С++, выполняется в несколько этапов. Основная идея данных этапов - получить общее представление всей программы в виде одного файла, содержащего LLVM IR и связанного через отладочную информацию со всем исходными файлами программы, после чего выполнять исследование уже объединенного файлом.

Для этого сначала необходимо получить для каждого исходного файла его представление в виде LLVM IR:

tsar -emit-llvm file1.c file2.c ... fileN.c

В итоге будут построены файлы file1.ll, file2.ll, ..., fileN.ll. Для построения LLVM IR для отдельных файлов необходимо использовать анализатор TSAR, так как он может добавлять дополнительную отладочную информацию в представление программы, отсутствующую при построении LLVM IR обычным компилятором Clang.

На следующем шаге файлы должны быть объединены в единый файл с помощью инструмента llvm-link, являюегося часть поставки пакетов LLVM:

llvm-link -S file1.ll file2.ll ... fileN.ll -o all.ll

В итоге будет построен единый файл all.ll, содержащий объединенное представление для всей программы с сохранением ссылок на исходные файлы на языке высокого уровня.

Полученный объединенный файл может быть передан TSAR для дальнейшей работы:

tsar [options] all.ll