diff --git a/wiki/Prog/Development/CMake управление проектом.adoc b/wiki/Prog/Development/CMake управление проектом.adoc index ec2045a..55e986f 100644 --- a/wiki/Prog/Development/CMake управление проектом.adoc +++ b/wiki/Prog/Development/CMake управление проектом.adoc @@ -7,15 +7,14 @@ == Полезные ссылки * https://github.com/onqtam/awesome-cmake[Каталог ссылок] -* https://cgold.readthedocs.io/en/latest/index.html[CGold: The -Hitchhiker’s Guide to the CMake] +* https://cgold.readthedocs.io/en/latest/index.html[CGold: The Hitchhiker’s Guide to the CMake] == Структура каталогов проекта Файлы проекта и результаты компиляции размещаются в каталогах: .... -└── cmex +└── project ├── _build │ ├── debug │ │ ├── bin @@ -54,40 +53,41 @@ Hitchhiker’s Guide to the CMake] [cols="2,4",options="header",] |=== -|Каталог |Назначение -|`cmex/_build` |Результаты компиляции -|`cmex/_build/debug` |Результаты компиляции в режиме отладки -|`cmex/_build/debug/bin` | Исполняемые файлы -|`cmex/_build/debug/etc` | Символическая ссылка на каталог `cmex/files/etc` -|`cmex/_build/debug/files/data` | Символическая ссылка на каталог `cmex/files/data` -|`cmex/_build/debug/files/lib` | Символическая ссылка на каталог `cmex/files/lib` -|`cmex/_build/debug/files/log` | Символическая ссылка на каталог `cmex/files/log` -|`cmex/_build/debug/include` | Заголовочные файлы копируемые и генерируемые во время сборки -|`cmex/_build/debug/lib` | Статические и динамические библиотеки -|`cmex/_build/release` |Результаты компиляции в режиме выпуска -|`cmex/.git` |Репозиторий git -|`cmex/cmake` |Файлы с дополнительными функциями для CMake -|`cmex/cmake/cmlib` |Библиотека функций для CMake -|`cmex/cmake/doc` |Правила для автоматической генерации документации -|`cmex/cmake/etc` |Файлы настроек, используемые в CMake -|`cmex/cmake/etc/uncrustify` |Файл настройки для программы автоматического форматирования исходных текстов -|`cmex/cmake/find` |Модули CMake для поиска внешних программ и библиотек -|`cmex/cmake/generators` |Генераторы проектов -|`cmex/doc` |Документация для проекта -|`cmake/files` |Каталог для дополнительных файлов -|`cmake/files/etc` |Каталог для файлов настроек проекта -|`cmake/files/data` |Каталог для неизменяемых файлов -|`cmake/files/lib` |Каталог для изменяемых файлов -|`cmake/files/log` |Каталог для журналов -|`cmex/l10n` |Файлы переводов -|`cmex/src` |Исходные тексты -|`cmex/src/app` |Исходные тексты программ -|`cmex/src/lib` |Исходные тексты библиотек -|`cmex/thirdparty` |Исходные тексты сторонних проектов -|`cmex/tools` |Дополнительные утилиты +|Каталог | Назначение +|`_build` | Результаты компиляции +|`_build/debug` | Результаты компиляции в режиме отладки +|`_build/debug/bin` | Исполняемые файлы +|`_build/debug/etc` | Символическая ссылка на каталог `cmex/files/etc` +|`_build/debug/files/data` | Символическая ссылка на каталог `cmex/files/data` +|`_build/debug/files/lib` | Символическая ссылка на каталог `cmex/files/lib` +|`_build/debug/files/log` | Символическая ссылка на каталог `cmex/files/log` +|`_build/debug/include` | Заголовочные файлы копируемые и генерируемые во время сборки +|`_build/debug/lib` | Статические и динамические библиотеки +|`_build/release` | Результаты компиляции в режиме выпуска (иерархия аналогична `debug`) +|`.git` | Системные файлы репозитория git +|`.gitlab.ci` | Шаблон правил для автоматической сборки на сервере Gitlab +|`cmake` | Файлы с дополнительными функциями для CMake +|`cmake/cmlib` | Библиотека функций для CMake +|`cmake/doc` | Правила для автоматической генерации документации +|`cmake/etc` | Файлы настроек, используемые в CMake +|`cmake/etc/uncrustify` | Файл настройки для программы автоматического форматирования исходных текстов +|`cmake/find` | Модули CMake для поиска внешних программ и библиотек +|`cmake/generators` | Генераторы проектов +|`doc` | Документация для проекта +|`files` | Каталог для дополнительных файлов +|`files/etc` | Каталог для файлов настроек проекта +|`files/data` | Каталог для неизменяемых файлов +|`files/lib` | Каталог для изменяемых файлов +|`files/log` | Каталог для журналов +|`l10n` | Файлы переводов +|`src` | Исходные тексты +|`src/app` | Исходные тексты программы +|`src/lib` | Исходные тексты библиотеки +|`thirdparty` | Исходные тексты дополнительных и сторонних проектов +|`tools` | Дополнительные утилиты |=== -Каталог `_build` создаётся, чтобы избежать попадания получаемых во время +Каталог `_build` создаётся, чтобы избежать попадания создаваемых во время сборки файлов в иерархию основного проекта. Запись результатов сборки проекта внутрь иерархии каталогов с исходными текстами приводит к засорению формируемыми на этапе сборки файлами, которые затрудняют @@ -98,42 +98,118 @@ Hitchhiker’s Guide to the CMake] == Начало проекта -Проект, в котором выполнены приведённые ниже действия, можно посмотреть -https://git.246060.ru/f1x1t/cmex[здесь] или сделать его копию командой: +Проект, в котором выполнены приведённые в данном разделе действия, +можно посмотреть https://git.246060.ru/f1x1t/cmlib-example-base[здесь] +или сделать его копию командой: [source,sh] ---- -git clone --recursive https://git.246060.ru/f1x1t/cmex +git clone --recursive https://git.246060.ru/f1x1t/cmlib-example-base ---- -В каталоге `cmex` нужно создать файл `CMakeLists.txt`: +=== Инициализация подмодулей + +Для начала нужно создать каталог для проекта, перейти в него и +инициализировать репозиторий git: + +[source,sh] +---- +mkdir cmlib-example-base +cd cmlib-example-base +git init +---- + +Для подключения основных подмодулей, содержащих дополнительные функции +для работы с проектом, и фиксации произведённого изменения нужно выполнить: + +[source,sh] +---- +git submodule add git@git.246060.ru:f1x1t/cmlib.git cmake/cmlib +git submodule add git@git.246060.ru:f1x1t/cmake-find.git cmake/find +git submodule add git@git.246060.ru:f1x1t/cmake-generators.git cmake/generators +git submodule add git@git.246060.ru:f1x1t/cmake-doc.git cmake/doc +git submodule add git@git.246060.ru:f1x1t/uncrustify-config.git cmake/etc/uncrustify +git commit -a -m "Начало проекта" +---- + +Отправить изменения в проекте на сервер и сделать ветку `master` основной: + +[source,sh] +---- +git remote add origin АДРЕС_РЕПОЗИТОРИЯ_НА_СЕРВЕРЕ +git push -u origin master +---- + +Загрузить шаблоны для автоматической сборки проекта в разных вариантах +программных окружений и зафиксировать изменения: + +[source,sh] +---- +mkdir .gitlab-ci +wget -O .gitlab-ci/scheduled.yml https://git.246060.ru/f1x1t/gitlab-ci/raw/branch/master/.gitlab-ci/scheduled.yml +wget -O .gitlab-ci.yml https://git.246060.ru/f1x1t/gitlab-ci/raw/branch/master/.gitlab-ci.yml +git add .gitlab-ci.yml .gitlab-ci/scheduled.yml +git commit -m "Настройка автосборки" +---- + +Загрузить файл настройки для анализатора Clang-Tidy: + +[source,sh] +---- +wget https://git.246060.ru/f1x1t/clang-tidy-config/raw/branch/master/.clang-tidy +git add .clang-tidy +git commit -m "Настройка Clang-Tidy" +---- + +Создать стандартные файлы и каталоги: + +[source,sh] +---- +mkdir -p doc/breathe +touch doc/breathe/index.md.in +mkdir -p files/etc +touch files/etc/.keep-directory +mkdir -p files/data +touch files/data/.keep-directory +mkdir -p files/lib +touch files/lib/.keep-directory +mkdir -p files/log +touch files/log/.keep-directory +git add doc files +git commit -m "Стандартные файлы и каталоги" +---- + +Создать файл `.gitignore` для исключения каталогов и файлов из-под контроля git: + +[source,sh] +---- +wget https://git.246060.ru/f1x1t/cmlib-gitignore/raw/branch/master/.gitignore +git add .gitignore +git commit -m "Шаблон для игнорирования каталогов и файлов" +---- + + +=== Базовые инструкции в CMake + +В корневом каталоге проекта нужно создать файл `CMakeLists.txt`: [source,cmake] ---- -# Минимальная версия Cmake +# Минимальная версия CMake cmake_minimum_required(VERSION 3.3) + +# Предпочтительно следовать стандартам принятым в указанном диапазоне версий cmake_policy(VERSION 3.0.2..3.7) # Название и версия проекта и используемые языки программирования -project(cmex VERSION 0.2.0 LANGUAGES C CXX) +project(cmlib-example-base VERSION 0.2.0 LANGUAGES C CXX) ---- Значение версии следует формировать согласно правилам https://semver.org/lang/ru/[семантического версионирования]. -В каталоге `cmex` нужно инициализировать репозиторий и установить -подмодули, содержащие функции для CMake: - -[source,sh] ----- -git init . -git submodule add https://git.246060.ru/f1x1t/cmlib cmake/cmlib -git submodule add https://git.246060.ru/f1x1t/cmake-find cmake/find -git submodule add https://git.246060.ru/f1x1t/cmake-generators cmake/generators -git submodule update --remote --init ----- - -и подключить в файле `CMakeLists.txt`: +Для подключения функций для CMake из библиотеки CMLib, нужно добавить +в файл `CMakeLists.txt` строки: [source,cmake] ---- @@ -148,36 +224,61 @@ list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/find) include(CMLibCommon) ---- -В файле `cmake/etc/organization.txt` записать название организации, -которой принадлежит проект: +В каталоге `cmake/etc` требуется создать файл `Variables.cmake`, +в котором требуется определить значения переменных, используемых +библиотекой CMLib для автоматического создания пакетов, генерации +документации: -.... -ORG, Inc. -.... +[source,cmake] +---- +set(ORGANIZATION_NAME "org") +set(AUTHOR_NAME "John Doe") -В файле `cmake/etc/cpack_ignore.txt` перечислить шаблоны для исключения -из архива, создаваемого целью `dist`. Например: +set(DOXYGEN_PROJECT_TITLE "Пример проекта (начало)") +set(DOXYGEN_GENERATE_LATEX YES) +set(DOXYGEN_GENERATE_HTML YES) -.... -cmake/lib/.git$ -.git$ -files/var -CMakeLists.txt.user -~$ -\\\\..*\\\\.bak$ -\\\\..*\\\\.tmp$ -\\\\..*\\\\.swp$ -.... +set(CPACK_GENERATOR "TXZ;DEB") +set(CPACK_PACKAGE_CONTACT "John Doe ") +set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake project example") +set(CPACK_DEBIAN_PACKAGE_SECTION "misc") +set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional") +set(CPACK_SOURCE_IGNORE_FILES + .git/ + obj.*/ + _build + _output + files/lib + files/log + debian/tmp/ + debian/files + debian/.*\\\\.log$ + debian/.*.substvars + debian/stamp.* + CMakeLists.txt.user.* + cmake/lib/.git$ + ~$ + \\\\..*\\\\.swp$) +---- -Чтобы проверить корректность файла `CMakeLists.txt`, нужно создать -каталог `_build` в каталоге `cmex`, перейти в него и выполнить команды: +Произведённые изменения можно зафиксировать: [source,sh] ---- -cmake .. -make +git add cmake/etc/Variables.cmake CMakeLists.txt +git commit -m "Подключение библиотеки CMLib" ---- +Чтобы проверить корректность подключения CMLib, можно выполнить команду: + +[source,sh] +---- +(mkdir -p _build && cd _build && cmake .. && make && echo OK) +---- + +Если последней строкой вывода будет `OK`, то настройка завершена верно. + + == Поиск системных библиотек Системные библиотеки можно искать с помощью программы `pkgconfig`, diff --git a/wiki/Prog/Development/PVS-Studio.adoc b/wiki/Prog/Development/PVS-Studio.adoc index ad09c97..7cd789d 100644 --- a/wiki/Prog/Development/PVS-Studio.adoc +++ b/wiki/Prog/Development/PVS-Studio.adoc @@ -1,16 +1,116 @@ -Описание Переменная kFlat kOpt kStandard kUser kHome -Путь к каталогу с исполняемым файлом m_binaryDirectory . /opt/proj/bin /usr/bin _build/Debug/bin $HOME/.local/bin -Имя проекта, которое используется при формировании имён файлов и каталогов m_projectName proj proj proj proj proj -Путь к пользовательскому каталогу с файлами настройки m_userConfigDirectory $HOME/.config/proj $HOME/.config/proj $HOME/.config/proj $HOME/.config/proj $HOME/.config/proj -Путь к системному каталогу с файлами настройки m_systemConfigDirectory . /opt/proj/etc /etc/proj _build/Debug/etc $HOME/.config/proj -Имя файла настройки m_configFileName proj.conf proj.conf proj.conf proj.conf proj.conf -Расширение для файла настройки m_configFileExtension conf conf conf conf conf -Путь к пользовательскому каталогу с изменяемыми файлами m_userVarDataDirectory $HOME/.local/share/proj/lib $HOME/.local/share/proj/lib $HOME/.local/share/proj/lib $HOME/.local/share/proj/lib $HOME/.local/share/proj/lib -Путь к системному каталогу с изменяемыми файлами m_systemVarDataDirectory . /opt/proj/files/lib /var/lib/proj _build/Debug/files/lib $HOME/.local/share/proj/lib -Путь к пользовательскому каталогу с неизменяемыми файлами m_userConstDataDirectory $HOME/.local/share/proj/data $HOME/.local/share/proj/data $HOME/.local/share/proj/data $HOME/.local/share/proj/data $HOME/.local/share/proj/data -Путь к системному каталогу с неизменяемыми файлами m_systemConstDataDirectory . /opt/proj/files/data /usr/share/proj _build/Debug/files/data $HOME/.local/share/proj/data -Путь к пользовательскому каталогу с журналами работы m_userLogDirectory $HOME/.local/share/proj/log $HOME/.local/share/proj/log $HOME/.local/share/proj/log $HOME/.local/share/proj/log $HOME/.local/share/proj/log -Путь к системному каталогу с журналами работы m_systemLogDirectory . /opt/proj/files/log /var/log/proj _build/Debug/files/log $HOME/.local/share/proj/log -Путь к каталогу с временными файлами m_tempDirectory $TMPDIR $TMPDIR $TMPDIR $TMPDIR $TMPDIR -Путь к домашнему каталогу текущего пользователя m_homeDirectory $HOME $HOME $HOME $HOME $HOME += PVS-Studio +:category: Программирование +:tags: программирование, C, C++, отладка, +:toc: + +== Информация и лицензия + +https://www.viva64.com/ru/pvs-studio/[PVS-Studio] — это инструмент для +статического анализа исходного кода программ, написанных на языках С, +C++. + +Для использования в Linux нужно чтобы в каталоге `~/.config/PVS-Studio` +находился лицензионный ключ или в начале исходных файлов с расширениями +`*.c`, `*.cpp`, `*.cxx` и т.п. +https://www.viva64.com/ru/b/0457/[присутствовали строки] + +.... +// This is an independent project of an individual developer. Dear PVS-Studio, please check it. + +// PVS-Studio Static Code Analyzer for C, C++ and C#: http://www.viva64.com +.... + +== Настройка и компиляция проекта + +Полное руководство для работы в Linux находится +https://www.viva64.com/ru/m/0036/[здесь], а ниже приведён список типовых +команд. + +Настройка проекта для CMake: + +[source,sh] +---- +cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On +---- + +Сборка проекта с помощью `make`: + +[source,sh] +---- +pvs-studio-analyzer trace -- make -j$(nproc) +---- + +Настройка и сборка проекта с использованием Ninja: + +[source,sh] +---- +cmake -GNinja -DCMAKE_EXPORT_COMPILE_COMMANDS=On +ninja -t compdb +---- + +== Анализ проекта + +Для анализа проектов используется утилита `pvs-studio-analyzer`. По +умолчанию включены только диагностики общего назначения (General +Analysis, GA). Включить дополнительные правила можно с помощью опции +`-a`: + +.... + -a [MODE], --analysis-mode [MODE] + MODE defines the type of warnings: + 1 - 64-bit errors; + 2 - reserved; + 4 - General Analysis; + 8 - Micro-optimizations; + 16 - Customers Specific Requests; + 32 - MISRA. + Modes can be combined by adding the values + Default: 4 +.... + +Выбор типов предупреждений осуществляется на основе побитовой маски из +приведённых выше типов. Чтобы выполнить анализ, исключив проверки MISRA, +нужно выполнить + +[source,sh] +---- +pvs-studio-analyzer analyze -a 29 -j$(nproc) -o pvs.log +---- + +Составление отчёта для просмотра в Qt Creator: + +[source,sh] +---- +plog-converter -t tasklist -o pvs.tasks pvs.log +---- + +При составлении отчёта уровень детализации можно изменять с помощью +ключа `-a` (`--analyzer`), который производит фильтрацию предупреждений +согласно маске, которая имеет вид `MessageType:MessageLevels`, где +`MessageType` может принимать один из следующих типов: `GA`, `OP`, `64`, +`CS`, `MISRA`, а `MessageLevels` может принимать значения от `1` до `3`. +Возможна комбинация разных масок через `;`. Например, при составлении +отчёта для просмотра в формате HTML можно повысить уровень детализации: + +[source,sh] +---- +plog-converter -t fullhtml -a "GA:1,2,3;64:1;OP:1,2;CS:1,2" -o html pvs.log +---- + +Составление отчёта для редактора Vim: + +[source,sh] +---- +plog-converter -a "GA:1,2" -t errorfile -o pvs.err pvs.log +---- + +Для просмотра отчёта в редакторе Vim нужно открыть файл `pvs.err` и +выполнить команды: + +[source,vim] +---- +:set makeprg=cat\ % " выбор программы для компиляции в текущей сессии +:silent make " имитация сборки +:cw " открытие результатов в нижнем окне +----