update

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
+* https://cgold.readthedocs.io/en/latest/index.html[CGold: The Hitchhiker’s Guide to the CMake]
-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` |Результаты компиляции
+|`_build`                  | Результаты компиляции
-|`cmex/_build/debug` |Результаты компиляции в режиме отладки
+|`_build/debug`            | Результаты компиляции в режиме отладки
-|`cmex/_build/debug/bin` | Исполняемые файлы
+|`_build/debug/bin`        | Исполняемые файлы
-|`cmex/_build/debug/etc` | Символическая ссылка на каталог `cmex/files/etc`
+|`_build/debug/etc`        | Символическая ссылка на каталог `cmex/files/etc`
-|`cmex/_build/debug/files/data` | Символическая ссылка на каталог `cmex/files/data`
+|`_build/debug/files/data` | Символическая ссылка на каталог `cmex/files/data`
-|`cmex/_build/debug/files/lib` | Символическая ссылка на каталог `cmex/files/lib`
+|`_build/debug/files/lib`  | Символическая ссылка на каталог `cmex/files/lib`
-|`cmex/_build/debug/files/log` | Символическая ссылка на каталог `cmex/files/log`
+|`_build/debug/files/log`  | Символическая ссылка на каталог `cmex/files/log`
-|`cmex/_build/debug/include` | Заголовочные файлы копируемые и генерируемые во время сборки
+|`_build/debug/include`    | Заголовочные файлы копируемые и генерируемые во время сборки
-|`cmex/_build/debug/lib` | Статические и динамические библиотеки
+|`_build/debug/lib`        | Статические и динамические библиотеки
-|`cmex/_build/release` |Результаты компиляции в режиме выпуска
+|`_build/release`          | Результаты компиляции в режиме выпуска (иерархия аналогична `debug`)
-|`cmex/.git` |Репозиторий git
+|`.git`                    | Системные файлы репозитория git
-|`cmex/cmake` |Файлы с дополнительными функциями для CMake
+|`.gitlab.ci`              | Шаблон правил для автоматической сборки на сервере Gitlab
-|`cmex/cmake/cmlib` |Библиотека функций для CMake
+|`cmake`                   | Файлы с дополнительными функциями для CMake
-|`cmex/cmake/doc` |Правила для автоматической генерации документации
+|`cmake/cmlib`             | Библиотека функций для CMake
-|`cmex/cmake/etc` |Файлы настроек, используемые в CMake
+|`cmake/doc`               | Правила для автоматической генерации документации
-|`cmex/cmake/etc/uncrustify` |Файл настройки для программы автоматического форматирования исходных текстов
+|`cmake/etc`               | Файлы настроек, используемые в CMake
-|`cmex/cmake/find` |Модули CMake для поиска внешних программ и библиотек
+|`cmake/etc/uncrustify`    | Файл настройки для программы автоматического форматирования исходных текстов
-|`cmex/cmake/generators` |Генераторы проектов
+|`cmake/find`              | Модули CMake для поиска внешних программ и библиотек
-|`cmex/doc` |Документация для проекта
+|`cmake/generators`        | Генераторы проектов
-|`cmake/files` |Каталог для дополнительных файлов
+|`doc`                     | Документация для проекта
-|`cmake/files/etc` |Каталог для файлов настроек проекта
+|`files`                   | Каталог для дополнительных файлов
-|`cmake/files/data` |Каталог для неизменяемых файлов
+|`files/etc`               | Каталог для файлов настроек проекта
-|`cmake/files/lib` |Каталог для изменяемых файлов
+|`files/data`              | Каталог для неизменяемых файлов
-|`cmake/files/log` |Каталог для журналов
+|`files/lib`               | Каталог для изменяемых файлов
-|`cmex/l10n` |Файлы переводов
+|`files/log`               | Каталог для журналов
-|`cmex/src` |Исходные тексты
+|`l10n`                    | Файлы переводов
-|`cmex/src/app` |Исходные тексты программ
+|`src`                     | Исходные тексты
-|`cmex/src/lib` |Исходные тексты библиотек
+|`src/app`                 | Исходные тексты программы
-|`cmex/thirdparty` |Исходные тексты сторонних проектов
+|`src/lib`                 | Исходные тексты библиотеки
-|`cmex/tools` |Дополнительные утилиты
+|`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 из библиотеки CMLib, нужно добавить
-подмодули, содержащие функции для CMake:
+в файл `CMakeLists.txt` строки:
-
-[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`:
 
 [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 для автоматического создания пакетов, генерации
+документации:
 
-....
+[source,cmake]
-ORG, Inc.
+----
-....
+set(ORGANIZATION_NAME "org")
+set(AUTHOR_NAME "John Doe")
 
-В файле `cmake/etc/cpack_ignore.txt` перечислить шаблоны для исключения
+set(DOXYGEN_PROJECT_TITLE "Пример проекта (начало)")
-из архива, создаваемого целью `dist`. Например:
+set(DOXYGEN_GENERATE_LATEX YES)
+set(DOXYGEN_GENERATE_HTML YES)
 
-....
+set(CPACK_GENERATOR "TXZ;DEB")
-cmake/lib/.git$
+set(CPACK_PACKAGE_CONTACT "John Doe <box@mail.domain>")
-.git$
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake project example")
-files/var
+set(CPACK_DEBIAN_PACKAGE_SECTION "misc")
-CMakeLists.txt.user
+set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
-~$
+set(CPACK_SOURCE_IGNORE_FILES
-\\\\..*\\\\.bak$
+    .git/
-\\\\..*\\\\.tmp$
+    obj.*/
-\\\\..*\\\\.swp$
+    _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 ..
+git add cmake/etc/Variables.cmake CMakeLists.txt
-make
+git commit -m "Подключение библиотеки CMLib"
 ----
 
+Чтобы проверить корректность подключения CMLib, можно выполнить команду:
+
+[source,sh]
+----
+(mkdir -p _build && cd _build && cmake .. && make && echo OK)
+----
+
+Если последней строкой вывода будет `OK`, то настройка завершена верно.
+
+
 == Поиск системных библиотек
 
 Системные библиотеки можно искать с помощью программы `pkgconfig`,

wiki/Prog/Development/PVS-Studio.adoc

@@ -1,16 +1,116 @@
-Описание	Переменная	kFlat	kOpt	kStandard	kUser	kHome
+= PVS-Studio
-Путь к каталогу с исполняемым файлом	m_binaryDirectory	.	/opt/proj/bin	/usr/bin	_build/Debug/bin	$HOME/.local/bin
+:category: Программирование
-Имя проекта, которое используется при формировании имён файлов и каталогов	m_projectName	proj	proj	proj	proj	proj
+:tags: программирование, C, C++, отладка,
-Путь к пользовательскому каталогу с файлами настройки	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
 
+: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 <src-tree-root>
+----
+
+Сборка проекта с помощью `make`:
+
+[source,sh]
+----
+pvs-studio-analyzer trace -- make -j$(nproc)
+----
+
+Настройка и сборка проекта с использованием Ninja:
+
+[source,sh]
+----
+cmake -GNinja -DCMAKE_EXPORT_COMPILE_COMMANDS=On <src-tree-root>
+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                 " открытие результатов в нижнем окне
+----