From 0b79ad4cdc1c11d65b3a66d639a7ad870e210b68 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 5 Sep 2023 22:05:44 +0000 Subject: [PATCH 01/44] Add a bunch of useful logs to a conan setup script Tags: Conan, Cpp, Shell --- scripts/conan/setup.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/conan/setup.sh b/scripts/conan/setup.sh index 6e46d06..545418e 100644 --- a/scripts/conan/setup.sh +++ b/scripts/conan/setup.sh @@ -73,8 +73,13 @@ main() { local -r prefix="${1}" + echo -e "\033[0;33mInit a default conan setup\033[0m" init_defaults + + echo -e "\033[0;33mSetup custom conan profiles\033[0m" setup_profiles "${prefix}" + + echo -e "\033[0;33mSetup custom conan remotes\033[0m" setup_remotes } -- GitLab From 7848f87c8ecac45983dcb0db3da68ff1a4dd84d5 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 5 Sep 2023 22:08:32 +0000 Subject: [PATCH 02/44] Restructure documentation for docker images Tags: Docker, Docs --- .vscode/extensions.json | 2 - .vscode/settings.json | 23 +-- docs/dockers.rst | 334 --------------------------------- docs/images/d/clang-format.rst | 40 ++++ docs/images/d/hadolint.rst | 40 ++++ docs/images/d/index.rst | 15 ++ docs/images/g/alpine3.rst | 43 +++++ docs/images/g/centos7.rst | 66 +++++++ docs/images/g/centos8.rst | 60 ++++++ docs/images/g/index.rst | 19 ++ docs/images/g/ubuntu2004.rst | 72 +++++++ docs/images/index.rst | 37 ++++ docs/index.rst | 2 +- 13 files changed, 396 insertions(+), 357 deletions(-) delete mode 100644 docs/dockers.rst create mode 100644 docs/images/d/clang-format.rst create mode 100644 docs/images/d/hadolint.rst create mode 100644 docs/images/d/index.rst create mode 100644 docs/images/g/alpine3.rst create mode 100644 docs/images/g/centos7.rst create mode 100644 docs/images/g/centos8.rst create mode 100644 docs/images/g/index.rst create mode 100644 docs/images/g/ubuntu2004.rst create mode 100644 docs/images/index.rst diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 03943f1..f3a3e6d 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,8 +2,6 @@ // See http://go.microsoft.com/fwlink/?LinkId=827846 // for the documentation about the extensions.json format "recommendations": [ - // Format listfiles so they don't look like crap - "cheshirekow.cmake-format", // Markdown linting and style checking for Visual Studio Code "davidanson.vscode-markdownlint", // Supercharge the Git capabilities built into Visual Studio Code diff --git a/.vscode/settings.json b/.vscode/settings.json index 73b63aa..132a081 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,11 +1,4 @@ { - "[cmake]": { - "editor.defaultFormatter": "cheshirekow.cmake-format" - }, - "cmakeFormat.args": [ - "--config-file", - "${workspaceFolder}/.cmake-format.py" - ], "editor.bracketPairColorization.enabled": true, "editor.detectIndentation": false, "editor.formatOnPaste": false, @@ -23,21 +16,17 @@ "files.associations": { ".clang-tidy": "yaml", ".codespellrc": "ini", - "*.cpp.in": "cpp", - "*.ipp": "cpp", - "*.py.in": "python" }, "files.exclude": { ".git/**": true, "build*/**": true, - "cmake/build/": false, "**/*.vc.db*": true }, "files.insertFinalNewline": true, "files.trimTrailingWhitespace": true, "files.watcherExclude": { + ".git/**": true, "build*/**": true, - "cmake/build/": false, "**/*.vc.db*": true }, "gitlens.codeLens.recentChange.enabled": false, @@ -46,15 +35,9 @@ "search.exclude": { ".git/**": true, "build*/**": true, - "cmake/build/": false, "**/*.vc.db*": true }, - "theme-by-language.themes": { - "*": "Visual Studio Dark", - "c": "Visual Studio Dark - C++", - "cpp": "Visual Studio Dark - C++", - "python": "Default Dark+" - }, "workbench.editor.enablePreview": false, - "workbench.colorTheme": "Visual Studio Dark" + "workbench.colorTheme": "Visual Studio Dark", + "esbonio.sphinx.confDir": "" } diff --git a/docs/dockers.rst b/docs/dockers.rst deleted file mode 100644 index 069e1da..0000000 --- a/docs/dockers.rst +++ /dev/null @@ -1,334 +0,0 @@ -============= -Docker images -============= - -This page provides an information about all custom docker images, which are developed and maintained within this project. - -General purpose -=============== - -Here is listed all docker images with a very general purpose setup, that can be used in wide range of use-cases. - -Alpine 3 Docker -^^^^^^^^^^^^^^^ - -A utility image which contains all possible linters and ``sphinx`` related packages, therefore widely used in documentation and linters jobs. - -*TAGS* - -- ``alpine3:latest`` - -*BASE IMAGE* - Based on official Alpine 3 image with Python 3 (``python:3-alpine3.15``). - -*BUILD TIME* - 2 minutes on average. - -*SYSTEM PACKAGES* - -+-----------------+---------+-------------------------------------------------------------+ -| Package | Version | Purpose | -+=================+=========+=============================================================+ -| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | -+-----------------+---------+-------------------------------------------------------------+ -| ``curl`` | \- | Mainly to upload packages to GitLab. | -+-----------------+---------+-------------------------------------------------------------+ -| ``gcc`` | \- | **Only to build ``licenseheaders`` linter.** | -+-----------------+---------+-------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+-----------------+---------+-------------------------------------------------------------+ -| ``less`` | \- | To update ``less`` and bring support for additional flags. | -+-----------------+---------+-------------------------------------------------------------+ -| ``musl-dev`` | \- | **Only to build ``licenseheaders`` linter.** | -+-----------------+---------+-------------------------------------------------------------+ -| ``shellcheck`` | \- | To provided a shell linter. | -+-----------------+---------+-------------------------------------------------------------+ -| ``shfmt`` | \- | To provided a shell linter. | -+-----------------+---------+-------------------------------------------------------------+ - -*C++ PACKAGES* - None. - -*PYTHON PACKAGES* - Mainly linters and ``sphinx`` related packages. - -CentOS 7 Docker -^^^^^^^^^^^^^^^ - -A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. - -.. warning:: Very painful image with a huge amount of hacks and workarounds. - -*TAGS* - -- ``centos7:latest`` - -*BASE IMAGE* - Based on official CentOS 7 image (``centos:7``). - -*BUILD TIME* - 30 minutes on average. - -*SYSTEM PACKAGES* - -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| Package | Version | Purpose | -+==================================+=========+================================================================================+ -| ``cmake3`` | 3.21.0 | To provide a C/C++ build system. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-gcc`` | 10.2.1 | To provide a C compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-gcc-c++`` | 10.2.1 | To provide a C++ compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-gcc-gfortran`` | 10.2.1 | \- | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-gdb`` | 9.2 | To provide a C/C++ CLI debugger. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libubsan-devel`` | 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-make`` | 4.2.1 | \- | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``doxygen`` | 1.8.5 | To provide a documentation generator for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-toolset-13.0-clang`` | 13.0.1 | To provide a C/C++ compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-toolset-13.0-llvm`` | 13.0.1 | **To fix backtraces from sanitizers** | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``rh-python38-python`` | 3.8 | To provide support of ``python 3`` language. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``rh-python38-python-devel`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``rh-python38-python-pip`` | \- | To provide a python packages manager. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ - -*C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. - -*PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. - -*CI SCRIPTS* - All CI scripts are included in this docker image. - -CentOS 8 Docker -^^^^^^^^^^^^^^^ - -A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. - -*TAGS* - -- ``centos8:latest`` - -*BASE IMAGE* - Based on official CentOS 8 image (``centos:8``). - -*BUILD TIME* - 30 minutes on average. - -*SYSTEM PACKAGES* - -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| Package | Version | Purpose | -+==================================+=========+================================================================================+ -| ``clang`` | 11.0.0 | To provide a C/C++ compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``cmake`` | 3.20.2 | To provide a C/C++ build system. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-gcc`` | 10.2.1 | To provide a C compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-gcc-c++`` | 10.2.1 | To provide a C++ compiler. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-gcc-gfortran`` | 10.2.1 | \- | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-gdb`` | 8.3 | To provide a C/C++ CLI debugger. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libubsan-devel``| 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm`` | 12.0.1 | **To fix backtraces from sanitizers** | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``make`` | 4.2.1 | \- | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``python38-pip`` | 3.8 | To provide support of ``python 3`` language and bring a packages manager | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``python38-devel`` | \- | To provide *dev* files for ``pybind11`` C++ library. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ - -*C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. - -*PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. - -*CI SCRIPTS* - All CI scripts are included in this docker image. - -Ubuntu 20.04 Docker -^^^^^^^^^^^^^^^^^^^ - -A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. - -.. note:: As this system is currently a main one, it can be used as a reference to setup your own C/C++ workspace. - -*TAGS* - -- ``ubuntu2004:latest`` - -*BASE IMAGE* - Based on official Ubuntu 20.04 image (``ubuntu:20.04``). - -*BUILD TIME* - 25 minutes on average. - -*SYSTEM PACKAGES* - - **Package versions dated by 29 March 2023.** - -+----------------------+---------+--------------------------------------------------------------------------------+ -| Package | Version | Purpose | -+======================+=========+================================================================================+ -| ``clang-12`` | 12.0.0 | To provide a C/C++ compiler. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``cmake`` | 3.21.0 | To provide a C/C++ build system. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``cppcheck`` | 1.90 | To provided a C/C++ linter. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``curl`` | 7.68.0 | Mainly to upload packages to GitLab. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``doxygen`` | 1.8.17 | To provide a documentation generator for code which uses C/C++ code. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``g++-10`` | 10.3.0 | To provide a C compiler. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-10`` | 10.3.0 | To provide a C++ compiler. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``graphviz`` | 2.43.0 | To build diagrams and graphs. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``jq`` | \- | To provide ``sed`` for JSON data. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``libgtk-3-dev`` | 3.X | To provide *dev* files for ``sciter`` C++ library. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``libpython3.8-dev`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``lcov`` | 1.14 | To provide graphical front-end for GCC's coverage testing tool ``gcov``. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-12`` | 12.0.0 | **To fix backtraces from sanitizers** | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``make`` | 4.2.1 | \- | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``pkg-config`` | 3.X | Transitive dependency for ``gtk/system`` recipe, required by ```sciter```. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``python3-pip`` | 20.0.2 | To provide support of ``python 3.8.10`` language and bring a packages manager | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``valgrind`` | 3.15.0 | To provide leak sanitizer for code which uses C/C++ code. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``wget`` | 1.20.3 | Mainly to download different stuff. | -+----------------------+---------+--------------------------------------------------------------------------------+ - -*C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. - -*PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. - -*CI SCRIPTS* - All CI scripts are included in this docker image. - -Dedicated -========= - -ClangFormat Docker -^^^^^^^^^^^^^^^^^^ - -A docker image with a patched ``clang-format`` to support custom C++ code style. - -*TAGS* - -- ``clang-format:latest`` - -*BASE IMAGE* - Based on ``alpine:3.15`` and ``python:3-alpine3.15`` images (multi-stage build). - -*BUILD TIME* - 20 minutes on average. - -*SYSTEM PACKAGES* - -*Final* docker image will contain only below additional packages. - -+------------------+---------+-------------------------------------------------------------+ -| Package | Version | Purpose | -+==================+=========+=============================================================+ -| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | -+------------------+---------+-------------------------------------------------------------+ -| ``bash`` | \- | To provide support ``bash`` scripting language. | -+------------------+---------+-------------------------------------------------------------+ -| ``clang-format`` | \- | To provided a C/C++ formatter. | -+------------------+---------+-------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+------------------+---------+-------------------------------------------------------------+ - -*C++ PACKAGES* - None. - -*PYTHON PACKAGES* - None. - -*CI SCRIPTS* - Only ``clang-format`` related CI scripts are included in this docker image. - -HadoLint Docker -^^^^^^^^^^^^^^^ - -A custom ``hadolint`` docker image changed entrypoint and a bunch of new packages. - -*TAGS* - -- ``hadolint:latest`` - -*BASE IMAGE* - Based on official ``hadolint`` image (``hadolint/hadolint:v2.9.3-alpine``). - -*BUILD TIME* - 1 minute on average. - -*SYSTEM PACKAGES* - -*Final* docker image will contain only below additional packages. - -+------------------+---------+-------------------------------------------------------------+ -| Package | Version | Purpose | -+==================+=========+=============================================================+ -| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | -+------------------+---------+-------------------------------------------------------------+ -| ``bash`` | \- | To provide support ``bash`` scripting language. | -+------------------+---------+-------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | -+------------------+---------+-------------------------------------------------------------+ -| ``hadolint`` | \- | To provided a docker file linter. | -+------------------+---------+-------------------------------------------------------------+ - -*C++ PACKAGES* - None. - -*PYTHON PACKAGES* - None. - -*CI SCRIPTS* - Only ``hadolint`` related CI scripts are included in this docker image. diff --git a/docs/images/d/clang-format.rst b/docs/images/d/clang-format.rst new file mode 100644 index 0000000..a922145 --- /dev/null +++ b/docs/images/d/clang-format.rst @@ -0,0 +1,40 @@ +============ +Clang-Format +============ + +A docker image with a patched ``clang-format`` to support custom C++ code style. + +*TAGS* + +- ``clang-format:latest`` + +*BASE IMAGE* + Based on ``alpine:3.15`` and ``python:3-alpine3.15`` images (multi-stage build). + +*BUILD TIME* + 20 minutes on average. + +*SYSTEM PACKAGES* + +*Final* docker image will contain only below additional packages. + ++------------------+---------+-------------------------------------------------------------+ +| Package | Version | Purpose | ++==================+=========+=============================================================+ +| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | ++------------------+---------+-------------------------------------------------------------+ +| ``bash`` | \- | To provide support ``bash`` scripting language. | ++------------------+---------+-------------------------------------------------------------+ +| ``clang-format`` | \- | To provided a C/C++ formatter. | ++------------------+---------+-------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++------------------+---------+-------------------------------------------------------------+ + +*C++ PACKAGES* + None. + +*PYTHON PACKAGES* + None. + +*CI SCRIPTS* + Only ``clang-format`` related CI scripts are included in this docker image. diff --git a/docs/images/d/hadolint.rst b/docs/images/d/hadolint.rst new file mode 100644 index 0000000..038ba7b --- /dev/null +++ b/docs/images/d/hadolint.rst @@ -0,0 +1,40 @@ +======== +HadoLint +======== + +A custom ``hadolint`` docker image with changed entrypoint and a bunch of new packages. + +*TAGS* + +- ``hadolint:latest`` + +*BASE IMAGE* + Based on official ``hadolint`` image (``hadolint/hadolint:v2.9.3-alpine``). + +*BUILD TIME* + 1 minute on average. + +*SYSTEM PACKAGES* + +*Final* docker image will contain only below additional packages. + ++------------------+---------+-------------------------------------------------------------+ +| Package | Version | Purpose | ++==================+=========+=============================================================+ +| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | ++------------------+---------+-------------------------------------------------------------+ +| ``bash`` | \- | To provide support ``bash`` scripting language. | ++------------------+---------+-------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++------------------+---------+-------------------------------------------------------------+ +| ``hadolint`` | \- | To provided a docker file linter. | ++------------------+---------+-------------------------------------------------------------+ + +*C++ PACKAGES* + None. + +*PYTHON PACKAGES* + None. + +*CI SCRIPTS* + Only ``hadolint`` related CI scripts are included in this docker image. diff --git a/docs/images/d/index.rst b/docs/images/d/index.rst new file mode 100644 index 0000000..dc3730c --- /dev/null +++ b/docs/images/d/index.rst @@ -0,0 +1,15 @@ +================ +Dedicated images +================ + +Here is listed all docker images with a very limited setup, that were created to solve a very specific set of problems: + +.. toctree:: + :hidden: + :maxdepth: 1 + + clang-format.rst + hadolint.rst + +- :doc:`clang-format`, +- :doc:`hadolint`. diff --git a/docs/images/g/alpine3.rst b/docs/images/g/alpine3.rst new file mode 100644 index 0000000..56ce6ba --- /dev/null +++ b/docs/images/g/alpine3.rst @@ -0,0 +1,43 @@ +======== +Alpine 3 +======== + +A utility image which contains all possible linters and ``sphinx`` related packages, therefore widely used in documentation and linters jobs. + +*TAGS* + +- ``alpine3:latest`` + +*BASE IMAGE* + Based on official Alpine 3 image with Python 3 (``python:3-alpine3.15``). + +*BUILD TIME* + 2 minutes on average. + +*SYSTEM PACKAGES* + ++-----------------+---------+-------------------------------------------------------------+ +| Package | Version | Purpose | ++=================+=========+=============================================================+ +| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | ++-----------------+---------+-------------------------------------------------------------+ +| ``curl`` | \- | Mainly to upload packages to GitLab. | ++-----------------+---------+-------------------------------------------------------------+ +| ``gcc`` | \- | **Only to build** ``licenseheaders`` **linter.** | ++-----------------+---------+-------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++-----------------+---------+-------------------------------------------------------------+ +| ``less`` | \- | To update ``less`` and bring support for additional flags. | ++-----------------+---------+-------------------------------------------------------------+ +| ``musl-dev`` | \- | **Only to build** ``licenseheaders`` **linter.** | ++-----------------+---------+-------------------------------------------------------------+ +| ``shellcheck`` | \- | To provided a shell scripts linter. | ++-----------------+---------+-------------------------------------------------------------+ +| ``shfmt`` | \- | To provided a shell scripts formatter. | ++-----------------+---------+-------------------------------------------------------------+ + +*C++ PACKAGES* + None. + +*PYTHON PACKAGES* + Mainly linters and ``sphinx`` related packages. diff --git a/docs/images/g/centos7.rst b/docs/images/g/centos7.rst new file mode 100644 index 0000000..2ba93f9 --- /dev/null +++ b/docs/images/g/centos7.rst @@ -0,0 +1,66 @@ +======== +CentOS 7 +======== + +A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. + +.. warning:: Very painful image with a huge amount of hacks and workarounds. + +*TAGS* + +- ``centos7:latest`` + +*BASE IMAGE* + Based on official CentOS 7 image (``centos:7``). + +*BUILD TIME* + 30 minutes on average. + +*SYSTEM PACKAGES* + ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| Package | Version | Purpose | ++==================================+=========+================================================================================+ +| ``cmake3`` | 3.21.0 | To provide a C/C++ build system. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-gcc`` | 10.2.1 | To provide a C compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-gcc-c++`` | 10.2.1 | To provide a C++ compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-gcc-gfortran`` | 10.2.1 | \- | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-gdb`` | 9.2 | To provide a C/C++ CLI debugger. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-libubsan-devel`` | 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``devtoolset-10-make`` | 4.2.1 | \- | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``doxygen`` | 1.8.5 | To provide a documentation generator for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``llvm-toolset-13.0-clang`` | 13.0.1 | To provide a C/C++ compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``llvm-toolset-13.0-llvm`` | 13.0.1 | **To fix backtraces from sanitizers** | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``rh-python38-python`` | 3.8 | To provide support of ``python 3`` language. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``rh-python38-python-devel`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``rh-python38-python-pip`` | \- | To provide a python packages manager. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ + +*C++ PACKAGES* + Only those which are listed in ``Conan.cmake`` file. + +*PYTHON PACKAGES* + Mainly ``conan`` package and ``sphinx`` related packages. + +*CI SCRIPTS* + All CI scripts are included in this docker image. diff --git a/docs/images/g/centos8.rst b/docs/images/g/centos8.rst new file mode 100644 index 0000000..63bc47a --- /dev/null +++ b/docs/images/g/centos8.rst @@ -0,0 +1,60 @@ +======== +CentOS 8 +======== + +A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. + +*TAGS* + +- ``centos8:latest`` + +*BASE IMAGE* + Based on official CentOS 8 image (``centos:8``). + +*BUILD TIME* + 30 minutes on average. + +*SYSTEM PACKAGES* + ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| Package | Version | Purpose | ++==================================+=========+================================================================================+ +| ``clang`` | 11.0.0 | To provide a C/C++ compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``cmake`` | 3.20.2 | To provide a C/C++ build system. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-gcc`` | 10.2.1 | To provide a C compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-gcc-c++`` | 10.2.1 | To provide a C++ compiler. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-gcc-gfortran`` | 10.2.1 | \- | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-gdb`` | 8.3 | To provide a C/C++ CLI debugger. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-toolset-10-libubsan-devel``| 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``llvm`` | 12.0.1 | **To fix backtraces from sanitizers** | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``make`` | 4.2.1 | \- | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``python38-pip`` | 3.8 | To provide support of ``python 3`` language and bring a packages manager | ++----------------------------------+---------+--------------------------------------------------------------------------------+ +| ``python38-devel`` | \- | To provide *dev* files for ``pybind11`` C++ library. | ++----------------------------------+---------+--------------------------------------------------------------------------------+ + +*C++ PACKAGES* + Only those which are listed in ``Conan.cmake`` file. + +*PYTHON PACKAGES* + Mainly ``conan`` package and ``sphinx`` related packages. + +*CI SCRIPTS* + All CI scripts are included in this docker image. diff --git a/docs/images/g/index.rst b/docs/images/g/index.rst new file mode 100644 index 0000000..91d9941 --- /dev/null +++ b/docs/images/g/index.rst @@ -0,0 +1,19 @@ +====================== +General purpose images +====================== + +Here is listed all docker images with a very general purpose setup, that can be used in wide range of use-cases: + +.. toctree:: + :hidden: + :maxdepth: 1 + + alpine3.rst + centos7.rst + centos8.rst + ubuntu2004.rst + +- :doc:`alpine3`, +- :doc:`centos7`, +- :doc:`centos8`, +- :doc:`ubuntu2004`. diff --git a/docs/images/g/ubuntu2004.rst b/docs/images/g/ubuntu2004.rst new file mode 100644 index 0000000..736accd --- /dev/null +++ b/docs/images/g/ubuntu2004.rst @@ -0,0 +1,72 @@ +============ +Ubuntu 20.04 +============ + +A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. + +.. note:: As this system is currently a main one, it can be used as a reference to setup your own C/C++ workspace. + +*TAGS* + +- ``ubuntu2004:latest`` + +*BASE IMAGE* + Based on official Ubuntu 20.04 image (``ubuntu:20.04``). + +*BUILD TIME* + 25 minutes on average. + +*SYSTEM PACKAGES* + + **Package versions dated by 29 March 2023.** + ++----------------------+---------+--------------------------------------------------------------------------------+ +| Package | Version | Purpose | ++======================+=========+================================================================================+ +| ``clang-12`` | 12.0.0 | To provide a C/C++ compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``cmake`` | 3.21.0 | To provide a C/C++ build system. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``cppcheck`` | 1.90 | To provided a C/C++ linter. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``curl`` | 7.68.0 | Mainly to upload packages to GitLab. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``doxygen`` | 1.8.17 | To provide a documentation generator for code which uses C/C++ code. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``g++-10`` | 10.3.0 | To provide a C compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-10`` | 10.3.0 | To provide a C++ compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``graphviz`` | 2.43.0 | To build diagrams and graphs. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``jq`` | \- | To provide ``sed`` for JSON data. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``libgtk-3-dev`` | 3.X | To provide *dev* files for ``sciter`` C++ library. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``libpython3.8-dev`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``lcov`` | 1.14 | To provide graphical front-end for GCC's coverage testing tool ``gcov``. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``llvm-12`` | 12.0.0 | **To fix backtraces from sanitizers** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``make`` | 4.2.1 | \- | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``pkg-config`` | 3.X | Transitive dependency for ``gtk/system`` recipe, required by ``sciter``. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``python3-pip`` | 20.0.2 | To provide support of ``python 3.8.10`` language and bring a packages manager | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``valgrind`` | 3.15.0 | To provide leak sanitizer for code which uses C/C++ code. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``wget`` | 1.20.3 | Mainly to download different stuff. | ++----------------------+---------+--------------------------------------------------------------------------------+ + +*C++ PACKAGES* + Only those which are listed in ``Conan.cmake`` file. + +*PYTHON PACKAGES* + Mainly ``conan`` package and ``sphinx`` related packages. + +*CI SCRIPTS* + All CI scripts are included in this docker image. diff --git a/docs/images/index.rst b/docs/images/index.rst new file mode 100644 index 0000000..a69e398 --- /dev/null +++ b/docs/images/index.rst @@ -0,0 +1,37 @@ +======================= +Pre-build docker images +======================= + +This section provides an information about all custom docker images, which are developed and maintained within this project. + +General purpose +=============== + +Here is listed all docker images with a very general purpose setup, that can be used in wide range of use-cases: + +.. toctree:: + :caption: General purpose + :hidden: + :maxdepth: 1 + + g/index.rst + +- :doc:`g/alpine3`, +- :doc:`g/centos7`, +- :doc:`g/centos8`, +- :doc:`g/ubuntu2004`. + +Dedicated +========= + +Here is listed all docker images with a very limited setup, that were created to solve a very specific set of problems: + +.. toctree:: + :caption: Dedicated + :hidden: + :maxdepth: 1 + + d/index.rst + +- :doc:`d/clang-format`, +- :doc:`d/hadolint`. diff --git a/docs/index.rst b/docs/index.rst index aa6bcfc..3825ba9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,8 +7,8 @@ Common CI/CD Tools :maxdepth: 1 :hidden: + images/index.rst pipelines/index.rst - dockers.rst useful_links.rst .. toctree:: -- GitLab From b64576b5905620cd0d220fcea6d12de735c60d52 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 16 Oct 2023 03:40:43 +0300 Subject: [PATCH 03/44] Bump docker-dind image version to 24.0.0 Tags: CI, Docker --- .gitlab/ci/images/base.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitlab/ci/images/base.yml b/.gitlab/ci/images/base.yml index db4bd66..d276333 100644 --- a/.gitlab/ci/images/base.yml +++ b/.gitlab/ci/images/base.yml @@ -22,9 +22,9 @@ # DOCKER_BUILDKIT=1 environment variable for your GitLab CI job. .docker: - image: docker:19.03.12 + image: docker:24.0.0 services: - - docker:19.03.12-dind + - docker:24.0.0-dind dependencies: [] needs: [] before_script: -- GitLab From e352a454fb22035f8b2be285a0e0b315578736c3 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 16 Oct 2023 03:40:43 +0300 Subject: [PATCH 04/44] Bump hadolist version to 2.12.0 Tags: Docker, HadoLint, Linters --- docker/HadoLint.Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/HadoLint.Dockerfile b/docker/HadoLint.Dockerfile index ff30b3e..2fba9c1 100644 --- a/docker/HadoLint.Dockerfile +++ b/docker/HadoLint.Dockerfile @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -FROM hadolint/hadolint:v2.9.3-alpine +FROM hadolint/hadolint:v2.12.0-alpine # Setup system and install packages -- GitLab From 2851f7237f9f6c5900da830abc6b753ec441ec1f Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 16 Oct 2023 03:40:43 +0300 Subject: [PATCH 05/44] Bump clang-format version to 18 Tags: Docker, ClangFormat, Linters, Patches --- docker/ClangFormat.Dockerfile | 2 +- .../adjust_header_regroup_logic.patch | 4 +- ...support_block_indent_for_braced_init.patch | 26 +++---- ...ort_block_indent_for_template_closer.patch | 70 +++++++++---------- 4 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docker/ClangFormat.Dockerfile b/docker/ClangFormat.Dockerfile index 4a05358..9cb8860 100644 --- a/docker/ClangFormat.Dockerfile +++ b/docker/ClangFormat.Dockerfile @@ -24,7 +24,7 @@ FROM alpine:3.15 as clang-format-build # Pass `--build-arg LLVM_TAG=master` for latest llvm commit ARG LLVM_TAG -ENV LLVM_TAG ${LLVM_TAG:-llvmorg-15-init} +ENV LLVM_TAG ${LLVM_TAG:-llvmorg-18-init} # HadoLint: It's ok to ignore this issue, as we don't care much about pkg versions. # hadolint ignore=DL3018 diff --git a/patches/clang-format/adjust_header_regroup_logic.patch b/patches/clang-format/adjust_header_regroup_logic.patch index 3af2805..94cd59c 100644 --- a/patches/clang-format/adjust_header_regroup_logic.patch +++ b/patches/clang-format/adjust_header_regroup_logic.patch @@ -1,8 +1,8 @@ diff --git a/clang/lib/Tooling/Inclusions/HeaderIncludes.cpp b/clang/lib/Tooling/Inclusions/HeaderIncludes.cpp -index fbceb26c3..7893153fe 100644 +index 15a2024c4..96b772d4b 100644 --- a/clang/lib/Tooling/Inclusions/HeaderIncludes.cpp +++ b/clang/lib/Tooling/Inclusions/HeaderIncludes.cpp -@@ -242,6 +242,12 @@ bool IncludeCategoryManager::isMainHeader(StringRef IncludeName) const { +@@ -243,6 +243,12 @@ bool IncludeCategoryManager::isMainHeader(StringRef IncludeName) const { // headers may not. StringRef HeaderStem = llvm::sys::path::stem(IncludeName); StringRef FileStem = llvm::sys::path::stem(FileName); // foo.cu for foo.cu.cc diff --git a/patches/clang-format/support_block_indent_for_braced_init.patch b/patches/clang-format/support_block_indent_for_braced_init.patch index be29d00..6202501 100644 --- a/patches/clang-format/support_block_indent_for_braced_init.patch +++ b/patches/clang-format/support_block_indent_for_braced_init.patch @@ -1,13 +1,13 @@ -diff --git a/clang/lib/Format/FormatToken.h b/clang/lib/Format/FormatToken.h -index f116a89ac..dcd4856b7 100644 ---- a/clang/lib/Format/FormatToken.h -+++ b/clang/lib/Format/FormatToken.h -@@ -698,7 +698,7 @@ public: - /// list that should be indented with a block indent. - bool opensBlockOrBlockTypeList(const FormatStyle &Style) const { - // C# Does not indent object initialisers as continuations. -- if (is(tok::l_brace) && getBlockKind() == BK_BracedInit && Style.isCSharp()) -+ if (is(tok::l_brace) && getBlockKind() == BK_BracedInit) - return true; - if (is(TT_TemplateString) && opensScope()) - return true; +diff --git a/clang/lib/Format/FormatToken.cpp b/clang/lib/Format/FormatToken.cpp +index d994ed048..c5871e360 100644 +--- a/clang/lib/Format/FormatToken.cpp ++++ b/clang/lib/Format/FormatToken.cpp +@@ -92,7 +92,7 @@ bool FormatToken::isBlockIndentedInitRBrace(const FormatStyle &Style) const { + + bool FormatToken::opensBlockOrBlockTypeList(const FormatStyle &Style) const { + // C# Does not indent object initialisers as continuations. +- if (is(tok::l_brace) && getBlockKind() == BK_BracedInit && Style.isCSharp()) ++ if (is(tok::l_brace) && getBlockKind() == BK_BracedInit) + return true; + if (is(TT_TemplateString) && opensScope()) + return true; diff --git a/patches/clang-format/support_block_indent_for_template_closer.patch b/patches/clang-format/support_block_indent_for_template_closer.patch index 94c2df4..020443f 100644 --- a/patches/clang-format/support_block_indent_for_template_closer.patch +++ b/patches/clang-format/support_block_indent_for_template_closer.patch @@ -1,53 +1,53 @@ diff --git a/clang/lib/Format/ContinuationIndenter.cpp b/clang/lib/Format/ContinuationIndenter.cpp -index 45a4d2355..a767a2987 100644 +index 0ca297a5f..2dba2e8dd 100644 --- a/clang/lib/Format/ContinuationIndenter.cpp +++ b/clang/lib/Format/ContinuationIndenter.cpp -@@ -341,7 +341,7 @@ bool ContinuationIndenter::mustBreak(const LineState &State) { - if (State.Stack.back().BreakBeforeClosingBrace && - Current.closesBlockOrBlockTypeList(Style)) +@@ -367,7 +367,7 @@ bool ContinuationIndenter::mustBreak(const LineState &State) { + Current.isBlockIndentedInitRBrace(Style)))) { return true; -- if (State.Stack.back().BreakBeforeClosingParen && Current.is(tok::r_paren)) -+ if (State.Stack.back().BreakBeforeClosingParen && Current.isOneOf(tok::r_paren, TT_TemplateCloser)) + } +- if (CurrentState.BreakBeforeClosingParen && Current.is(tok::r_paren)) ++ if (CurrentState.BreakBeforeClosingParen && Current.isOneOf(tok::r_paren, TT_TemplateCloser)) return true; - if (Previous.is(tok::semi) && State.LineContainsContinuedForLoopSection) - return true; -@@ -952,7 +952,7 @@ unsigned ContinuationIndenter::addTokenOnNewLine(LineState &State, - opensProtoMessageField(*PreviousNonComment, Style))) - State.Stack.back().BreakBeforeClosingBrace = true; - -- if (PreviousNonComment && PreviousNonComment->is(tok::l_paren)) -+ if (PreviousNonComment && PreviousNonComment->isOneOf(tok::l_paren, TT_TemplateOpener)) - State.Stack.back().BreakBeforeClosingParen = + if (Style.Language == FormatStyle::LK_ObjC && + Style.ObjCBreakBeforeNestedBlockParam && +@@ -1050,7 +1050,7 @@ unsigned ContinuationIndenter::addTokenOnNewLine(LineState &State, + CurrentState.BreakBeforeClosingBrace = true; + } + +- if (PreviousNonComment && PreviousNonComment->is(tok::l_paren)) { ++ if (PreviousNonComment && PreviousNonComment->isOneOf(tok::l_paren, TT_TemplateOpener)) { + CurrentState.BreakBeforeClosingParen = Style.AlignAfterOpenBracket == FormatStyle::BAS_BlockIndent; - -@@ -1051,7 +1051,7 @@ unsigned ContinuationIndenter::getNewLineColumn(const LineState &State) { - Current.Next->isOneOf(tok::semi, tok::kw_const, tok::l_brace))) + } +@@ -1170,7 +1170,7 @@ unsigned ContinuationIndenter::getNewLineColumn(const LineState &State) { return State.Stack[State.Stack.size() - 2].LastSpace; + } if (Style.AlignAfterOpenBracket == FormatStyle::BAS_BlockIndent && -- Current.is(tok::r_paren) && State.Stack.size() > 1) -+ Current.isOneOf(tok::r_paren, TT_TemplateCloser) && State.Stack.size() > 1) - return State.Stack[State.Stack.size() - 2].LastSpace; - if (NextNonComment->is(TT_TemplateString) && NextNonComment->closesScope()) - return State.Stack[State.Stack.size() - 2].LastSpace; +- (Current.is(tok::r_paren) || ++ (Current.isOneOf(tok::r_paren, TT_TemplateCloser) || + (Current.is(tok::r_brace) && + Current.MatchingParen->is(BK_BracedInit))) && + State.Stack.size() > 1) { diff --git a/clang/lib/Format/TokenAnnotator.cpp b/clang/lib/Format/TokenAnnotator.cpp -index 9d130dbb0..e118ca4cf 100644 +index 73840332e..a7317fba2 100644 --- a/clang/lib/Format/TokenAnnotator.cpp +++ b/clang/lib/Format/TokenAnnotator.cpp -@@ -4322,8 +4322,6 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line, +@@ -5482,8 +5482,6 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line, if (Right.is(TT_ImplicitStringLiteral)) return false; - + - if (Right.is(TT_TemplateCloser)) - return false; if (Right.is(tok::r_square) && Right.MatchingParen && - Right.MatchingParen->is(TT_LambdaLSquare)) + Right.MatchingParen->is(TT_LambdaLSquare)) { return false; -@@ -4334,7 +4332,7 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line, - return Right.MatchingParen && Right.MatchingParen->is(BK_Block); - - // We only break before r_paren if we're in a block indented context. -- if (Right.is(tok::r_paren)) { +@@ -5491,7 +5489,7 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line, + + // We only break before r_brace if there was a corresponding break before + // the l_brace, which is tracked by BreakBeforeClosingBrace. +- if (Right.is(tok::r_brace)) { + if (Right.isOneOf(tok::r_paren, TT_TemplateCloser)) { - if (Style.AlignAfterOpenBracket == FormatStyle::BAS_BlockIndent) { - return Right.MatchingParen && - !(Right.MatchingParen->Previous && + return Right.MatchingParen && (Right.MatchingParen->is(BK_Block) || + (Right.isBlockIndentedInitRBrace(Style))); + } -- GitLab From 8ff05ac0acae3fc8328e3c2ec69e4064795eea59 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 17 Sep 2023 02:57:46 +0300 Subject: [PATCH 06/44] Rewrite and re-think project documentation Tags: CI --- .gitlab/ci/lang/cpp/centos_gcc.yml | 1 - .gitlab/ci/lang/cpp/lint/guardonce.yml | 2 +- docs/.dockerignore | 3 - docs/.gitignore | 2 +- docs/_images/artifacts.dark.png | Bin 0 -> 44329 bytes docs/_images/artifacts.drawio | 103 +++ docs/_images/artifacts.png | Bin 0 -> 32944 bytes .../cpp_pipeline_flowchart.dark.png | Bin .../cpp_pipeline_flowchart.drawio | 0 .../cpp_pipeline_flowchart.png | Bin .../docs_pipeline_flowchart.dark.png | Bin .../docs_pipeline_flowchart.drawio | 0 .../docs_pipeline_flowchart.png | Bin .../cicd => _images}/jobs_map.dark.png | Bin .../{_static/cicd => _images}/jobs_map.drawio | 0 docs/{_static/cicd => _images}/jobs_map.png | Bin .../linters_pipeline_flowchart.dark.png | Bin .../linters_pipeline_flowchart.drawio | 0 .../linters_pipeline_flowchart.png | Bin docs/_misc/.gitignore | 1 + docs/_misc/cpp-project-dir-structure.txt | 48 ++ docs/_static/css/s5defs.css | 93 +++ docs/conf.py | 14 +- docs/images/d/clang-format.rst | 8 +- docs/images/d/conan.rst | 48 ++ docs/images/d/hadolint.rst | 4 +- docs/images/d/index.rst | 2 + docs/images/g/alpine3.rst | 4 +- docs/images/g/centos7.rst | 4 +- docs/images/g/centos8.rst | 4 +- docs/images/g/ubuntu2004.rst | 4 +- docs/images/index.rst | 3 + docs/index.rst | 9 +- docs/overview/artifacts.rst | 25 + docs/overview/index.rst | 22 + .../overview.rst => overview/stages.rst} | 54 +- docs/overview/workflow.rst | 24 + docs/pipelines/conan_pipeline.rst | 82 --- docs/pipelines/cpp_pipeline.rst | 153 ---- docs/pipelines/docker_pipeline.rst | 80 --- docs/pipelines/docs/hugo.rst | 3 + docs/pipelines/docs/index.rst | 15 + docs/pipelines/docs/sphinx.rst | 3 + docs/pipelines/docs_pipeline.rst | 131 ---- docs/pipelines/index.rst | 67 +- docs/pipelines/lang/cmake.rst | 122 ++++ docs/pipelines/lang/common.rst | 136 ++++ docs/pipelines/lang/cpp/build.rst | 173 +++++ docs/pipelines/lang/cpp/index.rst | 129 ++++ docs/pipelines/lang/cpp/linters.rst | 334 +++++++++ docs/pipelines/lang/docker/build.rst | 176 +++++ docs/pipelines/lang/docker/index.rst | 20 + docs/pipelines/lang/docker/linters.rst | 68 ++ docs/pipelines/lang/index.rst | 25 + docs/pipelines/lang/python/build.rst | 55 ++ docs/pipelines/lang/python/index.rst | 20 + docs/pipelines/lang/python/linters.rst | 132 ++++ docs/pipelines/lang/shell.rst | 113 +++ docs/pipelines/lang/yaml.rst | 73 ++ docs/pipelines/linters_pipeline.rst | 673 ------------------ docs/pipelines/misc.rst | 91 +++ docs/pipelines/misc_pipeline.rst | 48 -- docs/pipelines/packages/conan.rst | 161 +++++ docs/pipelines/packages/index.rst | 14 + docs/usage.rst | 22 + docs/{pipelines => }/variables.rst | 25 +- ..._guards.sh => check_cpp_include_guards.sh} | 0 67 files changed, 2348 insertions(+), 1278 deletions(-) delete mode 100644 docs/.dockerignore create mode 100644 docs/_images/artifacts.dark.png create mode 100644 docs/_images/artifacts.drawio create mode 100644 docs/_images/artifacts.png rename docs/{_static/cicd => _images}/cpp_pipeline_flowchart.dark.png (100%) rename docs/{_static/cicd => _images}/cpp_pipeline_flowchart.drawio (100%) rename docs/{_static/cicd => _images}/cpp_pipeline_flowchart.png (100%) rename docs/{_static/cicd => _images}/docs_pipeline_flowchart.dark.png (100%) rename docs/{_static/cicd => _images}/docs_pipeline_flowchart.drawio (100%) rename docs/{_static/cicd => _images}/docs_pipeline_flowchart.png (100%) rename docs/{_static/cicd => _images}/jobs_map.dark.png (100%) rename docs/{_static/cicd => _images}/jobs_map.drawio (100%) rename docs/{_static/cicd => _images}/jobs_map.png (100%) rename docs/{_static/cicd => _images}/linters_pipeline_flowchart.dark.png (100%) rename docs/{_static/cicd => _images}/linters_pipeline_flowchart.drawio (100%) rename docs/{_static/cicd => _images}/linters_pipeline_flowchart.png (100%) create mode 100644 docs/_misc/.gitignore create mode 100644 docs/_misc/cpp-project-dir-structure.txt create mode 100644 docs/_static/css/s5defs.css create mode 100644 docs/images/d/conan.rst create mode 100644 docs/overview/artifacts.rst create mode 100644 docs/overview/index.rst rename docs/{pipelines/overview.rst => overview/stages.rst} (75%) create mode 100644 docs/overview/workflow.rst delete mode 100644 docs/pipelines/conan_pipeline.rst delete mode 100644 docs/pipelines/cpp_pipeline.rst delete mode 100644 docs/pipelines/docker_pipeline.rst create mode 100644 docs/pipelines/docs/hugo.rst create mode 100644 docs/pipelines/docs/index.rst create mode 100644 docs/pipelines/docs/sphinx.rst delete mode 100644 docs/pipelines/docs_pipeline.rst create mode 100644 docs/pipelines/lang/cmake.rst create mode 100644 docs/pipelines/lang/common.rst create mode 100644 docs/pipelines/lang/cpp/build.rst create mode 100644 docs/pipelines/lang/cpp/index.rst create mode 100644 docs/pipelines/lang/cpp/linters.rst create mode 100644 docs/pipelines/lang/docker/build.rst create mode 100644 docs/pipelines/lang/docker/index.rst create mode 100644 docs/pipelines/lang/docker/linters.rst create mode 100644 docs/pipelines/lang/index.rst create mode 100644 docs/pipelines/lang/python/build.rst create mode 100644 docs/pipelines/lang/python/index.rst create mode 100644 docs/pipelines/lang/python/linters.rst create mode 100644 docs/pipelines/lang/shell.rst create mode 100644 docs/pipelines/lang/yaml.rst delete mode 100644 docs/pipelines/linters_pipeline.rst create mode 100644 docs/pipelines/misc.rst delete mode 100644 docs/pipelines/misc_pipeline.rst create mode 100644 docs/pipelines/packages/conan.rst create mode 100644 docs/pipelines/packages/index.rst create mode 100644 docs/usage.rst rename docs/{pipelines => }/variables.rst (86%) rename scripts/cicd/lint/{check_include_guards.sh => check_cpp_include_guards.sh} (100%) diff --git a/.gitlab/ci/lang/cpp/centos_gcc.yml b/.gitlab/ci/lang/cpp/centos_gcc.yml index b87661b..bf22af8 100644 --- a/.gitlab/ci/lang/cpp/centos_gcc.yml +++ b/.gitlab/ci/lang/cpp/centos_gcc.yml @@ -21,7 +21,6 @@ build:cpp:centos7:gcc: BPROTO_CI_CMAKE_BUILD_TYPE: "Release" BPROTO_CI_CMAKE_ARGS: >- -DCMOPTS_ENABLE_LTO=ON - -DBPROTO_APPEND_VC_REV=ON CC: gcc CXX: g++ diff --git a/.gitlab/ci/lang/cpp/lint/guardonce.yml b/.gitlab/ci/lang/cpp/lint/guardonce.yml index 044f0bb..c481e97 100644 --- a/.gitlab/ci/lang/cpp/lint/guardonce.yml +++ b/.gitlab/ci/lang/cpp/lint/guardonce.yml @@ -17,7 +17,7 @@ check:cpp:include_guards: - .check - .only-review-hpp script: - - check_include_guards.sh + - check_cpp_include_guards.sh artifacts: when: on_failure expire_in: 1 day diff --git a/docs/.dockerignore b/docs/.dockerignore deleted file mode 100644 index 58821e3..0000000 --- a/docs/.dockerignore +++ /dev/null @@ -1,3 +0,0 @@ -!**.drawio -!**.png -!**.py.in diff --git a/docs/.gitignore b/docs/.gitignore index 58821e3..bff8b61 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,3 @@ +!**.css !**.drawio !**.png -!**.py.in diff --git a/docs/_images/artifacts.dark.png b/docs/_images/artifacts.dark.png new file mode 100644 index 0000000000000000000000000000000000000000..d0aca5f8040166025e6b94a20d83dcf96427fdaf GIT binary patch literal 44329 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 Iol`;+0HSC+ivR!s literal 0 HcmV?d00001 diff --git a/docs/_images/artifacts.drawio b/docs/_images/artifacts.drawio new file mode 100644 index 0000000..aa11a92 --- /dev/null +++ b/docs/_images/artifacts.drawio @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_images/artifacts.png b/docs/_images/artifacts.png new file mode 100644 index 0000000000000000000000000000000000000000..9675a20b84c86729b5d7456c00dfed2e36c24dc4 GIT binary patch literal 32944 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 literal 0 HcmV?d00001 diff --git a/docs/_static/cicd/cpp_pipeline_flowchart.dark.png b/docs/_images/cpp_pipeline_flowchart.dark.png similarity index 100% rename from docs/_static/cicd/cpp_pipeline_flowchart.dark.png rename to docs/_images/cpp_pipeline_flowchart.dark.png diff --git a/docs/_static/cicd/cpp_pipeline_flowchart.drawio b/docs/_images/cpp_pipeline_flowchart.drawio similarity index 100% rename from docs/_static/cicd/cpp_pipeline_flowchart.drawio rename to docs/_images/cpp_pipeline_flowchart.drawio diff --git a/docs/_static/cicd/cpp_pipeline_flowchart.png b/docs/_images/cpp_pipeline_flowchart.png similarity index 100% rename from docs/_static/cicd/cpp_pipeline_flowchart.png rename to docs/_images/cpp_pipeline_flowchart.png diff --git a/docs/_static/cicd/docs_pipeline_flowchart.dark.png b/docs/_images/docs_pipeline_flowchart.dark.png similarity index 100% rename from docs/_static/cicd/docs_pipeline_flowchart.dark.png rename to docs/_images/docs_pipeline_flowchart.dark.png diff --git a/docs/_static/cicd/docs_pipeline_flowchart.drawio b/docs/_images/docs_pipeline_flowchart.drawio similarity index 100% rename from docs/_static/cicd/docs_pipeline_flowchart.drawio rename to docs/_images/docs_pipeline_flowchart.drawio diff --git a/docs/_static/cicd/docs_pipeline_flowchart.png b/docs/_images/docs_pipeline_flowchart.png similarity index 100% rename from docs/_static/cicd/docs_pipeline_flowchart.png rename to docs/_images/docs_pipeline_flowchart.png diff --git a/docs/_static/cicd/jobs_map.dark.png b/docs/_images/jobs_map.dark.png similarity index 100% rename from docs/_static/cicd/jobs_map.dark.png rename to docs/_images/jobs_map.dark.png diff --git a/docs/_static/cicd/jobs_map.drawio b/docs/_images/jobs_map.drawio similarity index 100% rename from docs/_static/cicd/jobs_map.drawio rename to docs/_images/jobs_map.drawio diff --git a/docs/_static/cicd/jobs_map.png b/docs/_images/jobs_map.png similarity index 100% rename from docs/_static/cicd/jobs_map.png rename to docs/_images/jobs_map.png diff --git a/docs/_static/cicd/linters_pipeline_flowchart.dark.png b/docs/_images/linters_pipeline_flowchart.dark.png similarity index 100% rename from docs/_static/cicd/linters_pipeline_flowchart.dark.png rename to docs/_images/linters_pipeline_flowchart.dark.png diff --git a/docs/_static/cicd/linters_pipeline_flowchart.drawio b/docs/_images/linters_pipeline_flowchart.drawio similarity index 100% rename from docs/_static/cicd/linters_pipeline_flowchart.drawio rename to docs/_images/linters_pipeline_flowchart.drawio diff --git a/docs/_static/cicd/linters_pipeline_flowchart.png b/docs/_images/linters_pipeline_flowchart.png similarity index 100% rename from docs/_static/cicd/linters_pipeline_flowchart.png rename to docs/_images/linters_pipeline_flowchart.png diff --git a/docs/_misc/.gitignore b/docs/_misc/.gitignore new file mode 100644 index 0000000..a1d35d9 --- /dev/null +++ b/docs/_misc/.gitignore @@ -0,0 +1 @@ +!*.* diff --git a/docs/_misc/cpp-project-dir-structure.txt b/docs/_misc/cpp-project-dir-structure.txt new file mode 100644 index 0000000..85c91f7 --- /dev/null +++ b/docs/_misc/cpp-project-dir-structure.txt @@ -0,0 +1,48 @@ +my-app + 3rd-party + 3rd-party-cpp-project-1 + ... + 3rd-party-cpp-project-2 + ... + CMakeLists.txt + docs + .gitignore + CMakeLists.txt + index.rst + project + module-1 + docs + api.rst + developer_notes.rst + index.rst + include + module-1 + module-1-api-header-1.hpp + ... + mocks + misc-project-1 + module-1-mock-header-1.hpp + ... + src + ... + tests + ... + CMakeLists.txt + module-2 + ... + misc + misc-module-1 + ... + mist-project-2 + ... + CMakeLists.txt + CMakeLists.txt + tools + lsan.supp + valgrind.supp + .gitignore + .gitlab-ci.yml + CMakeLists.txt + conanfile.py + README.md + requirements.txt diff --git a/docs/_static/css/s5defs.css b/docs/_static/css/s5defs.css new file mode 100644 index 0000000..a5ea8e8 --- /dev/null +++ b/docs/_static/css/s5defs.css @@ -0,0 +1,93 @@ +/* + * CSS hacks and small modification for my Sphinx website + * :copyright: Copyright 2013-2016 Lilian Besson + * :license: GPLv3, see LICENSE for details. + */ + + +/* Colors and text decoration. + For example, :black:`text in black` or :blink:`text blinking` in rST. */ + +.black { + color: black; +} + +.gray { + color: gray; +} + +.grey { + color: gray; +} + +.silver { + color: silver; +} + +.white { + color: white; +} + +.maroon { + color: maroon; +} + +.red { + color: red; +} + +.magenta { + color: magenta; +} + +.fuchsia { + color: fuchsia; +} + +.pink { + color: pink; +} + +.orange { + color: orange; +} + +.yellow { + color: yellow; +} + +.lime { + color: lime; +} + +.green { + color: green; +} + +.olive { + color: olive; +} + +.teal { + color: teal; +} + +.cyan { + color: cyan; +} + +.aqua { + color: aqua; +} + +.blue { + color: blue; +} + +.navy { + color: navy; +} + +.purple { + color: purple; +} diff --git a/docs/conf.py b/docs/conf.py index 7ec1922..73bf619 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ # -- Project information ----------------------------------------------------- author = "Zinchenko Serhii" -project = "Cpp Template Project" +project = "3CT" copyright = f"2020-{datetime.datetime.now().year}, Zinchenko Serhii" # noqa: A001 @@ -18,6 +18,15 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# More can be found here: https://stackoverflow.com/a/60991308. +rst_prolog = """ +.. include:: + +.. By default below line is set to 'incremental' which breaks site a little. +.. default-role:: + +""" + # -- Options for HTML output ------------------------------------------------- @@ -35,6 +44,9 @@ def _generate_last_updated_fmt(): return f"{commit_sha} ({branch}), %y-%m-%d %H:%M:%S" +html_css_files = ["css/s5defs.css"] +html_static_path = ["_static"] + html_copy_source = False html_last_updated_fmt = _generate_last_updated_fmt() diff --git a/docs/images/d/clang-format.rst b/docs/images/d/clang-format.rst index a922145..c473677 100644 --- a/docs/images/d/clang-format.rst +++ b/docs/images/d/clang-format.rst @@ -1,15 +1,19 @@ +.. _images-dedicated-clangformat: + ============ Clang-Format ============ -A docker image with a patched ``clang-format`` to support custom C++ code style. +A docker image with a patched ``clang-format`` to support a custom C++ code style. + +.. _alpine-image: https://hub.docker.com/_/alpine *TAGS* - ``clang-format:latest`` *BASE IMAGE* - Based on ``alpine:3.15`` and ``python:3-alpine3.15`` images (multi-stage build). + Official `alpine:3.15 `_ and `python:3-alpine3.15 `_ images (multi-stage build). *BUILD TIME* 20 minutes on average. diff --git a/docs/images/d/conan.rst b/docs/images/d/conan.rst new file mode 100644 index 0000000..ee13bde --- /dev/null +++ b/docs/images/d/conan.rst @@ -0,0 +1,48 @@ +.. _images-dedicated-conan: + +===== +Conan +===== + +A custom ``conan`` docker image with a limited amount of packages. + +This docker image is provided as a clean setup for testing and deployment of ``conan`` packages that resides in `bPROTO recipes `__ group. + +*TAGS* + +- ``conan:latest`` + +*BASE IMAGE* + Official `ubuntu:20.04 `__ image. + +*BUILD TIME* + 1 minute on average. + +*SYSTEM PACKAGES* + +*Final* docker image will contain only below additional packages. + ++------------------+---------+--------------------------------------------------------------------------------+ +| Package | Version | Purpose | ++==================+=========+================================================================================+ +| ``doxygen`` | \- | To provide a documentation generator for code which uses C/C++ code. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``g++-10`` | 10.3.0 | To provide a C compiler. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-10`` | 10.3.0 | To provide a C++ compiler. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``make`` | \- | \- | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``python3-pip`` | \- | To provide support of ``python 3.8.10`` language and bring a packages manager | ++------------------+---------+--------------------------------------------------------------------------------+ + +*C++ PACKAGES* + None. + +*PYTHON PACKAGES* + Mainly ``conan`` package and ``sphinx`` related packages. + +*CI SCRIPTS* + No scripts are included. diff --git a/docs/images/d/hadolint.rst b/docs/images/d/hadolint.rst index 038ba7b..9b2f2e1 100644 --- a/docs/images/d/hadolint.rst +++ b/docs/images/d/hadolint.rst @@ -1,3 +1,5 @@ +.. _images-dedicated-hadolint: + ======== HadoLint ======== @@ -9,7 +11,7 @@ A custom ``hadolint`` docker image with changed entrypoint and a bunch of new pa - ``hadolint:latest`` *BASE IMAGE* - Based on official ``hadolint`` image (``hadolint/hadolint:v2.9.3-alpine``). + Official `hadolint:v2.12.0-alpine `_ image. *BUILD TIME* 1 minute on average. diff --git a/docs/images/d/index.rst b/docs/images/d/index.rst index dc3730c..6f9f2e9 100644 --- a/docs/images/d/index.rst +++ b/docs/images/d/index.rst @@ -9,7 +9,9 @@ Here is listed all docker images with a very limited setup, that were created to :maxdepth: 1 clang-format.rst + conan.rst hadolint.rst - :doc:`clang-format`, +- :doc:`conan`, - :doc:`hadolint`. diff --git a/docs/images/g/alpine3.rst b/docs/images/g/alpine3.rst index 56ce6ba..07cd379 100644 --- a/docs/images/g/alpine3.rst +++ b/docs/images/g/alpine3.rst @@ -1,3 +1,5 @@ +.. _images-general-alpine3: + ======== Alpine 3 ======== @@ -9,7 +11,7 @@ A utility image which contains all possible linters and ``sphinx`` related packa - ``alpine3:latest`` *BASE IMAGE* - Based on official Alpine 3 image with Python 3 (``python:3-alpine3.15``). + Official `python:3-alpine3.15 `_ image. *BUILD TIME* 2 minutes on average. diff --git a/docs/images/g/centos7.rst b/docs/images/g/centos7.rst index 2ba93f9..6215754 100644 --- a/docs/images/g/centos7.rst +++ b/docs/images/g/centos7.rst @@ -1,3 +1,5 @@ +.. _images-general-centos7: + ======== CentOS 7 ======== @@ -11,7 +13,7 @@ A C++ based image which contains all required and optional packages to build C++ - ``centos7:latest`` *BASE IMAGE* - Based on official CentOS 7 image (``centos:7``). + Official `centos:7 `_ image. *BUILD TIME* 30 minutes on average. diff --git a/docs/images/g/centos8.rst b/docs/images/g/centos8.rst index 63bc47a..965ccc0 100644 --- a/docs/images/g/centos8.rst +++ b/docs/images/g/centos8.rst @@ -1,3 +1,5 @@ +.. _images-general-centos8: + ======== CentOS 8 ======== @@ -9,7 +11,7 @@ A C++ based image which contains all required and optional packages to build C++ - ``centos8:latest`` *BASE IMAGE* - Based on official CentOS 8 image (``centos:8``). + Official `centos:8 `_ image. *BUILD TIME* 30 minutes on average. diff --git a/docs/images/g/ubuntu2004.rst b/docs/images/g/ubuntu2004.rst index 736accd..7e596f6 100644 --- a/docs/images/g/ubuntu2004.rst +++ b/docs/images/g/ubuntu2004.rst @@ -1,3 +1,5 @@ +.. _images-general-ubuntu2004: + ============ Ubuntu 20.04 ============ @@ -11,7 +13,7 @@ A C++ based image which contains all required and optional packages to build C++ - ``ubuntu2004:latest`` *BASE IMAGE* - Based on official Ubuntu 20.04 image (``ubuntu:20.04``). + Official `ubuntu:20.04 `__ image. *BUILD TIME* 25 minutes on average. diff --git a/docs/images/index.rst b/docs/images/index.rst index a69e398..90d7cbc 100644 --- a/docs/images/index.rst +++ b/docs/images/index.rst @@ -1,3 +1,5 @@ +.. _images-index-page: + ======================= Pre-build docker images ======================= @@ -34,4 +36,5 @@ Here is listed all docker images with a very limited setup, that were created to d/index.rst - :doc:`d/clang-format`, +- :doc:`d/conan`, - :doc:`d/hadolint`. diff --git a/docs/index.rst b/docs/index.rst index 3825ba9..496ce65 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,17 @@ -################## -Common CI/CD Tools -################## +####################### +3CT: Common CI/CD Tools +####################### .. toctree:: :caption: Documentation :maxdepth: 1 :hidden: + overview/index.rst images/index.rst pipelines/index.rst + usage.rst + variables.rst useful_links.rst .. toctree:: diff --git a/docs/overview/artifacts.rst b/docs/overview/artifacts.rst new file mode 100644 index 0000000..eeb26b1 --- /dev/null +++ b/docs/overview/artifacts.rst @@ -0,0 +1,25 @@ +========= +Artifacts +========= + +.. _container-registry: https://docs.gitlab.com/ee/user/packages/container_registry/index.html +.. _package-registry: https://docs.gitlab.com/ee/user/packages/package_registry/index.html + +This project tries to utilize GitLab `package `_ and `container `_ registries as they're fullest. + +.. + Flowchart has been generated with the help of https://app.diagrams.net/. + If you need to change flowchart: + 1. Go to the mentioned site. + 2. Import _static/artifacts.drawio. + 3. Change flowchart + 4. Save as .drawio and .png files. + 5. Update appropriate files in _static folder. + +.. image:: /_images/artifacts.png + :alt: C++ Pipeline Flowchart + :class: only-light + +.. image:: /_images/artifacts.dark.png + :alt: C++ Pipeline Flowchart + :class: only-dark diff --git a/docs/overview/index.rst b/docs/overview/index.rst new file mode 100644 index 0000000..4c2d20d --- /dev/null +++ b/docs/overview/index.rst @@ -0,0 +1,22 @@ +======== +Overview +======== + +This page is geared towards developers of the project CI/CD pipelines, and serves as a starting point of understanding core parts of pipelines. + +.. toctree:: + :maxdepth: 1 + :hidden: + + stages.rst + workflow.rst + artifacts.rst + +:doc:`stages` + An exhaustive overview of ideas behind pipeline stages. + +:doc:`workflow` + An overview of triggers for jobs from different stages. + +:doc:`artifacts` + An overview of triggers for jobs from different stages. diff --git a/docs/pipelines/overview.rst b/docs/overview/stages.rst similarity index 75% rename from docs/pipelines/overview.rst rename to docs/overview/stages.rst index b28d65a..ab2ffaa 100644 --- a/docs/pipelines/overview.rst +++ b/docs/overview/stages.rst @@ -1,30 +1,4 @@ -======== -Overview -======== - -This page is geared towards developers of the project CI/CD pipelines, and serves as a starting point of understanding project pipelines. - -General workflow -================ - -A below table shows when jobs of a certain stage will be triggered. - -+--------+---------+-------------------+---------------+ -| Stage | Branch | CI_DEFAULT_BRANCH | Merge request | -+========+=========+===================+===============+ -| build | no | no | **yes** | -+--------+---------+-------------------+---------------+ -| test | no | no | **yes** | -+--------+---------+-------------------+---------------+ -| check | no | no | **yes** | -+--------+---------+-------------------+---------------+ -| report | no | no | **yes** | -+--------+---------+-------------------+---------------+ -| deploy | no | **yes** | no | -+--------+---------+-------------------+---------------+ -| misc | no | **yes** | no | -+--------+---------+-------------------+---------------+ - +=============== Stages overview =============== @@ -38,7 +12,7 @@ Before you start reading a below overview of each pipeline stage, you should fam - Description * - Allow failure - - This section describes whether jobs are allowed to fail. + - This section describes whether job is allowed to fail. * - Artifacts - This section describes what `job artifacts `__ will be generated after a successful run. @@ -47,7 +21,7 @@ Before you start reading a below overview of each pipeline stage, you should fam - This section describes used of `job's cache `__. * - Dependencies - - This section describes what kind of dependencies tends to have. + - This section describes what kind of dependencies job tends to have. Effectively combines `dependencies `__ and `needs `__ directives. * - Environment @@ -55,27 +29,25 @@ Before you start reading a below overview of each pipeline stage, you should fam Right now only custom variables, those ones that defined using project settings, are taken into account. * - Images - - This section describes Docker images that the jobs should run in. + - This section describes Docker images that the job is using. Effectively combines an overall content of `image `__ directive for all jobs. * - Triggers - - This section describes when at what cases jobs will be triggered. + - This section describes when and at what cases job will be triggered. -.. _overview-build-stage: +.. _overview-stages-build-stage: Build stage ----------- This is an *optional* stage for testing new changes that have been made to different parts of the project. -Especially this goes for C++ and Docker files, as these parts require assembling of mentions parts. +Especially this goes for C++ and `Docker `__ files, as these parts require assembling of mentions parts. *ALLOW FAILURE* Jobs are not allowed to fail as any failure means fundamental problems in one of the project parts. *ARTIFACTS* - Jobs generate C++ binaries for application executables and tests runners. - - Job artifacts also include all required CMake and CTest files for running tests. + Jobs may generate any kind of artifacts and might be used by jobs in other stages (like ``test`` stage). .. note:: Please take into account that generation of useful human-readable reports are usually delegated to jobs of the ``report`` stage. @@ -90,7 +62,7 @@ Especially this goes for C++ and Docker files, as these parts require assembling *TRIGGERS* Jobs are triggered only on **merge requests** and if a certain part of the projects have been modified (this can be C++ or Docker files). -.. _overview-test-stage: +.. _overview-stages-test-stage: Test stage ---------- @@ -113,7 +85,7 @@ This is an *optional* stage for running different types of project tests. *TRIGGERS* Jobs are triggered only on **merge requests** and only if parent job from the **build** stage hasn't failed. -.. _overview-check-stage: +.. _overview-stages-check-stage: Check stage ----------- @@ -137,7 +109,7 @@ This is an *optional* stage for executing different linters to diagnose code for *TRIGGERS* Jobs are triggered only on **merge requests** and if a certain part of the projects have been modified (this can be C++, Docker, Shell files and so on...). -.. _overview-report-stage: +.. _overview-stages-report-stage: Report stage ------------ @@ -161,7 +133,7 @@ This is an *optional* utility stage for generating reports for parent jobs in fr *TRIGGERS* Jobs are triggered only on **merge requests** and only if parent job has failed. -.. _overview-deploy-stage: +.. _overview-stages-deploy-stage: Deploy stage ------------ @@ -188,7 +160,7 @@ This is an *optional* stage for deploying different packages to a project or gro .. _registry: https://docs.gitlab.com/ee/user/packages/index.html -.. _overview-misc-stage: +.. _overview-stages-misc-stage: Misc stage ---------- diff --git a/docs/overview/workflow.rst b/docs/overview/workflow.rst new file mode 100644 index 0000000..9c38e96 --- /dev/null +++ b/docs/overview/workflow.rst @@ -0,0 +1,24 @@ +======== +Workflow +======== + +A below table shows when jobs of a certain stage will be triggered. + +.. table:: + :width: 100% + + +--------+---------+-------------------+---------------+ + | Stage | Branch | CI_DEFAULT_BRANCH | Merge request | + +========+=========+===================+===============+ + | build | no | no | **yes** | + +--------+---------+-------------------+---------------+ + | test | no | no | **yes** | + +--------+---------+-------------------+---------------+ + | check | no | no | **yes** | + +--------+---------+-------------------+---------------+ + | report | no | no | **yes** | + +--------+---------+-------------------+---------------+ + | deploy | no | **yes** | no | + +--------+---------+-------------------+---------------+ + | misc | no | **yes** | no | + +--------+---------+-------------------+---------------+ diff --git a/docs/pipelines/conan_pipeline.rst b/docs/pipelines/conan_pipeline.rst deleted file mode 100644 index 842e174..0000000 --- a/docs/pipelines/conan_pipeline.rst +++ /dev/null @@ -1,82 +0,0 @@ -============== -Conan Pipeline -============== - -This is a pipeline for building/testing and deploying new changes that have been made to anything that is directly related to the *conan recipe* part of the project. - -All jobs from docker pipeline stages are triggered only if changes have been made to *conan recipe* related files. -Right now such files are detected by these patterns: - -- ``conandata.yml``, -- ``conanfile.py``. - -**See also:** `Conan packages in the GitLab Package Registry `__. - -Overview -======== - -Build stage ------------ - -This stage is responsible for building conan packages from a clean state to make sure there are no unexpected results. - -*ALLOW FAILURE* - Jobs are not allowed to fail as any failure here means fundamental problems in a specific conan recipe. - -*ARTIFACTS* - Jobs don't generate any artifacts. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*IMAGES* - Nothing specific here. - -*TRIGGERS* - Jobs are triggered only on **merge requests**. - -Deploy stage ------------- - -.. _package registry: https://docs.gitlab.com/ee/user/packages/package_registry - -This stage is responsible for deploying conan packages to the project `package registry`_. - -*ALLOW FAILURE* - Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! - -*ARTIFACTS* - New docker images will be deployed to the project `package registry`_. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_DEPLOY_USER - - Mandatory - - * - BPROTO_CI_DEPLOY_TOKEN - - Mandatory - - * - BPROTO_CI_CONAN_PACKAGE_NAME - - Mandatory - - * - BPROTO_CI_CONAN_PACKAGES_REGISTRY - - Mandatory - -*IMAGES* - Nothing specific here. - -*TRIGGERS* - Jobs are triggered only on ``CI_DEFAULT_BRANCH``. diff --git a/docs/pipelines/cpp_pipeline.rst b/docs/pipelines/cpp_pipeline.rst deleted file mode 100644 index 0619d4d..0000000 --- a/docs/pipelines/cpp_pipeline.rst +++ /dev/null @@ -1,153 +0,0 @@ -============ -C++ Pipeline -============ - -This is a pipeline for testing new changes that have been made to anything that is directly related to the C++ part of the project. -Here we try to build project from a clean state on different types of OS and with different set of build configurations to cover as much as possible. -Additionally to this we try to build project with all available sanitizers to detect different kind of issues as fast as possible. - -All jobs from C++ pipeline stages are triggered only on **merge requests** and only if changes have been made to C++ files. -Right now such files are detected by these patterns: - -- ``**/CMakeLists.txt``, -- ``**/*.cmake``, -- ``**/*.cpp``, -- ``**/*.hpp``, -- ``**/*.ipp``. - -.. note:: Please take into account that we don't include jobs from **check** stage, as they are not directly related to this pipeline. - -Flowchart -========= - -.. - Flowchart has been generated with the help of https://app.diagrams.net/. - If you need to change flowchart: - 1. Go to the mentioned site. - 2. Import _static/cicd/cpp_pipeline_flowchart.drawio. - 3. Change flowchart - 4. Save as .drawio and .png files. - 5. Update appropriate files in _static folder. - -.. image:: /_static/cicd/cpp_pipeline_flowchart.png - :target: ../_images/cicd/cpp_pipeline_flowchart.png - :alt: C++ Pipeline Flowchart - :class: only-light - -.. image:: /_static/cicd/cpp_pipeline_flowchart.dark.png - :target: ../_images/cicd/cpp_pipeline_flowchart.dark.png - :alt: C++ Pipeline Flowchart - :class: only-dark - -Stages overview -=============== - -Build stage ------------ - -*See also test stage overview from* :ref:`overview-build-stage`. - -*ALLOW FAILURE* - Jobs are not allowed to fail as any failure means project can't be fully assembled into distinct binary and library files. - -*ARTIFACTS* - Jobs generate C++ binaries for application executables and tests runners. - - Job artifacts also include all required CMake and CTest files for running tests. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs have no dependencies from other stages or jobs. - -*IMAGES* - All jobs from this stage must use pre-build docker images to decrease overall pipeline time. - -Test stage ----------- - -This is a stage for running all available C++ tests. - -*See also test stage overview from* :ref:`overview-test-stage`. - -Report stage ------------- - -This is a stage to collect all available build information during the *build* stage and deploy it as a job artifacts if build has failed by any reason. - -*See also report stage overview from* :ref:`overview-report-stage`. - -Distribution -============ - -As we try to test as much configurations as possible, in this table all current setups will be tracked. - -.. note:: - Those options, that have been stress emphasized using *italic* and marked as (**yes**\*), are not taking part in a build process right now. - They are put here only to keep a track! - -+------------+-----------------------------------------------------------------------+ -| Options | System Configuration | -+ +-------------------+-------------------+---------------------+---------+ -| | CentOS 7 | CentOS 8 | Ubuntu 20.04 | Windows | -+ +---------+---------+---------+---------+---------+-----------+---------+ -| | Clang | GCC | Clang | GCC | Clang | GCC | MSBuild | -+============+=========+=========+=========+=========+=========+===========+=========+ -| | .. centered:: **Build Configuration** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Type | debug | release | debug | debug | debug | debug | debug | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Asserts | **yes** | no | **yes** | **yes** | **yes** | **yes** | **yes** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Cache | default | default | default | default | default | default | default | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Linter | default | default | default | default | default | default | default | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| LTO | no | **yes** | no | **yes** | no | **yes** | **yes** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| VCS Info | no | **yes** | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Binding** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Batch | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| JS | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Lua | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Python | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Docs** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | no | no | no | no | **yes** | **yes**\* | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Linters** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| *Coverage* | no | no | no | no | no | **yes**\* | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| *CppCheck* | no | no | no | no | no | **yes**\* | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| IWYU | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| LWYU | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Sanitizers** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| ASan | no | no | no | **yes** | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| LSan | no | no | no | **yes** | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| MSan | no | no | no | no | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| UBSan | no | no | no | **yes** | no | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| TSan | no | no | no | no | **yes** | no | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Valgrind | no | no | no | no | no | **yes** | no | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Tests** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Benchmarks | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ -| Tests | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | -+------------+---------+---------+---------+---------+---------+-----------+---------+ diff --git a/docs/pipelines/docker_pipeline.rst b/docs/pipelines/docker_pipeline.rst deleted file mode 100644 index 9902871..0000000 --- a/docs/pipelines/docker_pipeline.rst +++ /dev/null @@ -1,80 +0,0 @@ -=============== -Docker Pipeline -=============== - -This is a pipeline for testing and deploying new changes that have been made to anything that is directly related to the *Docker* part of the project. - -All jobs from docker pipeline stages are triggered only if changes have been made to Docker related files. -Right now such files are detected by these patterns: - -- ``conan/*`` -- ``cmake/Conan.cmake``, -- ``docker/*.Dockerfile``, -- ``scripts/conan/`` -- ``scripts/os/setup_*.sh``, -- ``requirements.txt``. - -Overview -======== - -Build stage ------------ - -This stage is responsible for building Docker images from a clean state to make sure there are no unexpected results. - -*ALLOW FAILURE* - Jobs are not allowed to fail as any failure here means fundamental problems in a specific docker image. - -*ARTIFACTS* - Jobs don't generate any artifacts. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*IMAGES* - Nothing specific here. - -*TRIGGERS* - Jobs are triggered only on **merge requests**. - -Deploy stage ------------- - -This stage is responsible for generated pre-build docker images for our pipelines. -So called pre-build images are crucial part of our project CI/CD as it allows us to decrease execution time of jobs. - -*ALLOW FAILURE* - Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! - -*ARTIFACTS* - New docker images will be deployed to the project `container registry `__. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_DEPLOY_USER - - Mandatory - - * - BPROTO_CI_DEPLOY_TOKEN - - Mandatory - - * - BPROTO_CI_IMAGES_REGISTRY - - Mandatory - -*IMAGES* - Nothing specific here. - -*TRIGGERS* - Jobs are triggered only on ``CI_DEFAULT_BRANCH``. diff --git a/docs/pipelines/docs/hugo.rst b/docs/pipelines/docs/hugo.rst new file mode 100644 index 0000000..b46f5e0 --- /dev/null +++ b/docs/pipelines/docs/hugo.rst @@ -0,0 +1,3 @@ +==== +Hugo +==== diff --git a/docs/pipelines/docs/index.rst b/docs/pipelines/docs/index.rst new file mode 100644 index 0000000..f0d2e25 --- /dev/null +++ b/docs/pipelines/docs/index.rst @@ -0,0 +1,15 @@ +==== +Docs +==== + +These documents cover in-detail all available "sub-pipelines" for generation documentation: + +.. toctree:: + :maxdepth: 1 + :hidden: + + hugo.rst + sphinx.rst + +- :doc:`hugo`, +- :doc:`sphinx`. diff --git a/docs/pipelines/docs/sphinx.rst b/docs/pipelines/docs/sphinx.rst new file mode 100644 index 0000000..7e5c9f9 --- /dev/null +++ b/docs/pipelines/docs/sphinx.rst @@ -0,0 +1,3 @@ +============= +Sphinx (reST) +============= diff --git a/docs/pipelines/docs_pipeline.rst b/docs/pipelines/docs_pipeline.rst deleted file mode 100644 index c71a7bd..0000000 --- a/docs/pipelines/docs_pipeline.rst +++ /dev/null @@ -1,131 +0,0 @@ -============= -Docs Pipeline -============= - -This is a pipeline for testing and deploying new changes that have been made to anything that is directly related to the *documentation* part of the project. - -All jobs from documentation pipeline stages are triggered only if changes have been made to documentation related files. -Right now such files are detected by these patterns: - -- ``docs/**/*`` -- ``project/**/CMakeLists.txt`` -- ``project/**/include/**/*.hpp`` - -As you can see from the above list of files pipeline will take into account both types of the project documentation: Doxygen (C++ files) and Sphinx (RST files) documentation. - -Flowchart -========= - -This is a very generalized flowchart that combines in itself all possible roots of pipeline generation and execution. - -.. - Flowchart has been generated with the help of https://app.diagrams.net/. - If you need to change flowchart: - 1. Go to the mentioned site. - 2. Import _static/cicd/docs_pipeline_flowchart.drawio. - 3. Change flowchart - 4. Save as .drawio and .png files. - 5. Update appropriate files in _static folder. - -.. image:: /_static/cicd/docs_pipeline_flowchart.png - :target: ../_images/cicd/docs_pipeline_flowchart.png - :alt: Docs Pipeline Flowchart - :class: only-light - -.. - fill 4E220F, line EF8C61 - fill 052853, line 4B9AFB -.. image:: /_static/cicd/docs_pipeline_flowchart.dark.png - :target: ../_images/cicd/docs_pipeline_flowchart.dark.png - :alt: Docs Pipeline Flowchart - :class: only-dark - -Stages overview -=============== - -Build stage ------------ - -This stage is responsible for building HTML documentation from a clean state to make sure there are no unexpected results. - -*ALLOW FAILURE* - Jobs are not allowed to fail as any failure here means fundamental problems in documentation generation. - -*ARTIFACTS* - Jobs generate an artifact with a HTML documentation. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*IMAGES* - All jobs from this stage must use one of pre-build docker images to decrease overall pipeline time. - -*TRIGGERS* - Jobs are triggered only on **merge requests**. - -Deploy stage ------------- - -This stage is responsible for building and deploying static HTML documentation files to the project registry. - -*ALLOW FAILURE* - Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! - -*ARTIFACTS* - New version of the documentation will be deployed to the project `generic packages repository `__ in a form an ``tar`` archive. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_DEPLOY_TOKEN - - Mandatory - - * - BPROTO_CI_DOCS_NAME - - Mandatory - - * - BPROTO\_CI\_\*_DOCS_NAME - - Mandatory - - * - BPROTO_CI_GENERIC_PACKAGES_REGISTRY - - Mandatory - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has no dependencies from other stages or jobs. - -*IMAGES* - Nothing specific here. - -*TRIGGERS* - Jobs are triggered only on ``CI_DEFAULT_BRANCH``. - -Misc stage ----------- - -After a successful deploy, job from this stage will trigger a pipeline of `other project `__ using `GitLab API `__. -If external pipeline succeed, new version of documentation will be available on https://bproto.gitlab.io. - -*ALLOW FAILURE* - Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! - -*ARTIFACTS* - Jobs don't generate any artifacts. - -*DEPENDENCIES* - Jobs don't require artifacts from other jobs. - - Jobs has a dependency to a job from *deploy* stage. - -*IMAGES* - No image is required. - -*TRIGGERS* - Jobs are triggered only on ``CI_DEFAULT_BRANCH``. diff --git a/docs/pipelines/index.rst b/docs/pipelines/index.rst index 21861de..3c40093 100644 --- a/docs/pipelines/index.rst +++ b/docs/pipelines/index.rst @@ -1,6 +1,6 @@ -######### -Pipelines -######### +============= +Sub-Pipelines +============= These documents cover in-detail all available "sub-pipelines" and their jobs. @@ -8,17 +8,13 @@ These documents cover in-detail all available "sub-pipelines" and their jobs. :maxdepth: 1 :hidden: - overview.rst - variables.rst - conan_pipeline.rst - cpp_pipeline.rst - docker_pipeline.rst - docs_pipeline.rst - linters_pipeline.rst - misc_pipeline.rst + docs/index.rst + lang/index.rst + misc.rst + packages/index.rst -Sub-Pipelines Concept -===================== +Concept +======= We always try to compose everything into one top-level `GitLab CI/CD pipeline `__ that includes all jobs. This way we can have all `GitLab CI/CD jobs `__, that have been triggered for merge request or a specific branch, in one place. @@ -26,53 +22,36 @@ This way we can have all `GitLab CI/CD jobs `__ *only on changed CMake files* (not diff, but files) which will reformat code accordingly to the established project code style. + +.. note:: + This job is in active development phase and is a subject for a complete rework. + Please follow `this project issue `__ to get more information about the current state of this job. + +*ALLOW FAILURE* + .. warning:: This job is allowed to fail as it's still in development. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.cmake-format.py`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +check:cmake:lint +---------------- + +This job executes `cmake-lint `__ *only on changed CMake files* (not diff, but files) which will diagnose and fix style violations like wrong variable and function names. + +.. note:: + This job is in active development phase and is a subject for a complete rework. + Please follow `this project issue `__ to get more information about the current state of this job. + +*ALLOW FAILURE* + .. warning:: This job is allowed to fail as it's still in development. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.cmake-format.py`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/common.rst b/docs/pipelines/lang/common.rst new file mode 100644 index 0000000..805d33d --- /dev/null +++ b/docs/pipelines/lang/common.rst @@ -0,0 +1,136 @@ +.. _pipelines-lang-common: + +====== +Common +====== + +This is a "sub-pipeline" for linting new changes that have been made to any kind of files of a specific GitLab project. + +Triggers +======== + +All jobs from *common "sub-pipeline"* stages are triggered only on merge requests if changes have been made to any file in git repository. + +Jobs overview +============= + +check:code:license +------------------ + +This job executes `licenseheaders `__ on project source code files, which will detect incorrect license headers. + +.. note:: + This job is in active development phase and is a subject for a complete rework. + Please follow `this project issue `__ to get more information about the current state of this job. + +*ALLOW FAILURE* + .. warning:: This job is allowed to fail as it's still in development. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.license.tmpl`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job will be triggered only on **merge requests** and on all project files except ``3rd-party`` folder. + +check:code:spelling +------------------- + +This job executes `codespell `__ on project source code files, which will detect common misspellings. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.codespellrc`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job will be triggered only on **merge requests** and on all project files except ``3rd-party`` folder. + +check:commits:spelling +---------------------- + +This job executes `codespell `__ on all found branch commits, which will detect common misspellings. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.codespellrc`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Origin + + * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME + - Mandatory + - GitLab + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job will be triggered only on **merge requests**. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/cpp/build.rst b/docs/pipelines/lang/cpp/build.rst new file mode 100644 index 0000000..7f64e79 --- /dev/null +++ b/docs/pipelines/lang/cpp/build.rst @@ -0,0 +1,173 @@ +============ +Build & Test +============ + +This document describes a part of C++ "sub-pipeline" which is responsible for building and testing new changes that have been made to C++ files of a specific GitLab project. + +Here we try to build project from a clean state on different OS's and with different set of build configurations to cover as much as possible. +Additionally to this we try to build project with all available sanitizers to detect different kind of issues as fast as possible. + +Flowchart +========= + +.. + Flowchart has been generated with the help of https://app.diagrams.net/. + If you need to change flowchart: + 1. Go to the mentioned site. + 2. Import _static/cpp_pipeline_flowchart.drawio. + 3. Change flowchart + 4. Save as .drawio and .png files. + 5. Update appropriate files in _static folder. + +.. image:: /_images/cpp_pipeline_flowchart.png + :alt: C++ Pipeline Flowchart + :class: only-light + +.. image:: /_images/cpp_pipeline_flowchart.dark.png + :alt: C++ Pipeline Flowchart + :class: only-dark + +Triggers +======== + +A list of triggers can be found :ref:`here `. + +Stages overview +=============== + +Build stage +----------- + +*ALLOW FAILURE* + Jobs are not allowed to fail as any failure means project can't be fully assembled into distinct binary and library files. + +*ARTIFACTS* + Jobs generate C++ binaries for application executables and tests runners. + + Job artifacts also include all required CMake and CTest files for running tests. + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs have no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Allowed values + - Default + + * - BPROTO_CI_CMAKE_ARGS + - Mandatory + - + - + + * - BPROTO_CI_CMAKE_BUILD_TYPE + - Optional + - | Debug, + | MinSizeRel, + | Release, + | RelWithDebInfo + - Debug + + * - BPROTO_CI_CMAKE_EXTRA_ARGS + - Optional + - + - + + * - CC + - Mandatory + - clang, gcc + - + + * - CXX + - Mandatory + - clang++, g++ + - + + * - CMAKE_GENERATOR + - Mandatory + - + - Unix Makefiles + +*IMAGES* + All jobs from this stage must use pre-build docker images to decrease overall pipeline time. + +*See also build stage overview from* :ref:`overview-stages-build-stage`. + +Test stage +---------- + +This is a stage for running all available C++ tests. + +*See also test stage overview from* :ref:`overview-test-stage`. + +Report stage +------------ + +This is a stage to collect all available build information during the *build* stage and deploy it as a job artifacts if build has failed by any reason. + +*See also report stage overview from* :ref:`overview-stages-report-stage`. + +Distribution +============ + +As we try to test as much configurations as possible, in this table all current setups will be tracked. + ++-------------------+---------------------------------------------------------------------------+ +| Options | System Configuration | ++ +-----------------------+-------------------+---------------------+---------+ +| | CentOS 7 | CentOS 8 | Ubuntu 20.04 | Windows | ++ +---------+-------------+---------+---------+---------+-----------+---------+ +| | Clang | GCC | Clang | GCC | Clang | GCC | MSBuild | ++===================+=========+=============+=========+=========+=========+===========+=========+ +| | .. centered:: **Build Configuration** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Type | debug | **release** | debug | debug | debug | debug | debug | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Asserts | **yes** | no | **yes** | **yes** | **yes** | **yes** | **yes** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Cache | default | default | default | default | default | default | default | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Linter | default | default | default | default | default | default | default | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| LTO | no | **yes** | no | **yes** | no | **yes** | **yes** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| | .. centered:: **Docs** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Docs | no | no | no | no | **yes** | **yes**\* | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| | .. centered:: **Linters** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| LWYU | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| | .. centered:: **Sanitizers** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| ASan | no | no | no | **yes** | no | no | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| LSan | no | no | no | **yes** | no | no | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| MSan | no | no | no | no | no | no | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| UBSan | no | no | no | **yes** | no | no | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| TSan | no | no | no | no | **yes** | no | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Valgrind | no | no | no | no | no | **yes** | no | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| | .. centered:: **Tests** | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ +| Benchmarks | .. centered:: **yes** | ++-------------------+ + +| Unit tests | | ++-------------------+ + +| Component tests | | ++-------------------+ + +| Integration tests | | ++-------------------+ + +| System tests | | ++-------------------+---------+-------------+---------+---------+---------+-----------+---------+ diff --git a/docs/pipelines/lang/cpp/index.rst b/docs/pipelines/lang/cpp/index.rst new file mode 100644 index 0000000..7fab92a --- /dev/null +++ b/docs/pipelines/lang/cpp/index.rst @@ -0,0 +1,129 @@ +.. _pipelines-lang-cpp: + +=== +C++ +=== + +This is a "sub-pipeline" for building, testing and linting new changes that have been made to C++ files of a specific GitLab project. + +.. toctree:: + :maxdepth: 1 + :hidden: + + build.rst + linters.rst + +:doc:`build` + A document which covers all CI jobs responsible for building and testing C++ code. + +:doc:`linters` + A document which covers all CI jobs responsible for linting C++ code. + +.. _pipelines-lang-cpp-limitations: + +Limitations +=========== + +Unlike other "sub-pipeline" like :ref:`CMake `, :ref:`Python ` or :ref:`Shell ` ones, current implementation of C++ "sub-pipeline" is hard to use as a template because it has a few significant limitations. + +Core packages +^^^^^^^^^^^^^ + +Everything here is built using `CMake `__ build system and `Conan `__ package manager. + +It's still possible to integrate other build systems (like `Bazel `__, `b2 `__, `Meson `__ and `Premake `__) and package managers (like `CPM `__ and `vcpkg `__)! +However as of now I have no plans to do that because I use nothing from that and that will require a significant amount of work. + +CMake modules +^^^^^^^^^^^^^ + +Most jobs heavily relay on `CMOPTS `__ and `CppDoc `__ CMake modules. + +Those modules do all the heavy lifting like a seamless integration of sanitizes, linters and other useful tools, hence are essential for this "sub-pipeline". + +Pre-build Docker images +^^^^^^^^^^^^^^^^^^^^^^^ + +Due to the fact that all "sub-pipeline"s (this one is not an exception) try to utilizes :ref:`pre-build docker images ` as much as possible, this will be the rock on which we split in most of the cases. + +.. _gitlab-caching: https://docs.gitlab.com/ee/ci/caching +.. _gitlab-fork: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html + +There is no easy way to add new `conan packages `__ to mentioned docker images so you need either to use `GitLab caching mechanism `_ to some degree or `fork `_ the project to handle that. + +Project structure +^^^^^^^^^^^^^^^^^ + +Most jobs, from the current implementation of the C++ "sub-pipeline", heavily relay on a certain C++ project structure that is shown below. + +.. Generated with the help of https://tree.nathanfriend.io. + +.. _issue: https://gitlab.com/bproto/cicd/-/issues/7 +.. _other issue: https://gitlab.com/bproto/cicd/-/issues/6 +.. _"check:cpp:format": pipeline-lang-cpp-linters-format + +.. parsed-literal:: + + :olive:`green` - is an optional file or directory. + :red:`red` - is a mandatory file or directory. + + my-app/ + :olive:`├── 3rd-party/` :gray:`<- code here is ignored by linters.` + │ ├── 3rd-party-cpp-project-1/ + │ │ └── ... + │ ├── 3rd-party-cpp-project-2/ + │ │ └── ... + │ └── CMakeLists.txt + :olive:`├── docs/` :gray:`<- docs job looks for changes here.` + │ ├── .gitignore + │ ├── CMakeLists.txt + │ └── index.rst + :red:`├── project/` (`issue`_) :gray:`<- 'check:cpp:format' formats code only here.` + │ ├── module-1/ + │ │ :olive:`├── docs/` :gray:`<- docs job looks for changes here.` + │ │ │ ├── api.rst + │ │ │ ├── developer_notes.rst + │ │ │ └── index.rst + │ │ :olive:`├── include/` :gray:`<- docs job looks for changes here.` + │ │ │ └── module-1/ + │ │ │ ├── module-1-api-header-1.hpp + │ │ │ └── ... + │ │ ├── mocks/ + │ │ │ └── misc-project-1/ + │ │ │ ├── module-1-mock-header-1.hpp + │ │ │ └── ... + │ │ ├── src/ + │ │ │ └── ... + │ │ ├── tests/ + │ │ │ └── ... + │ │ └── CMakeLists.txt + │ ├── module-2/ + │ │ └── ... + │ :olive:`├── misc/` (`other issue`_) :gray:`<- 'check:cpp:include_guards' handles this folder in a special way.` + │ │ ├── misc-module-1/ + │ │ │ └── ... + │ │ ├── mist-project-2/ + │ │ │ └── ... + │ │ └── CMakeLists.txt + │ └── CMakeLists.txt + :olive:`├── tools/` :gray:`<- sanitizers look for files with suppressions only here.` + │ ├── lsan.supp + │ └── valgrind.supp + ├── .gitignore + ├── .gitlab-ci.yml + :red:`├── CMakeLists.txt` :gray:`<- most jobs expect this file to be here.` + :olive:`├── conanfile.{py,txt}` :gray:`<- most jobs will use it if exists.` + ├── README.md + └── requirements.txt + +.. _pipelines-lang-cpp-linters-triggers: + +Triggers +======== + +Most of jobs from *C++ "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to C++ files. +Right now such files are detected by these patterns: + +- ``project/**/*.cpp``, +- ``project/**/*.hpp``, +- ``project/**/*.ipp``. diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst new file mode 100644 index 0000000..da88223 --- /dev/null +++ b/docs/pipelines/lang/cpp/linters.rst @@ -0,0 +1,334 @@ +======= +Linters +======= + +This document describes a part of C++ "sub-pipeline" which is responsible for linting new changes that have been made to C++ files of a specific GitLab project. + +Flowchart +========= + +This is a very generalized flowchart that combines in itself all possible roots of pipeline generation and execution. + +.. + Flowchart has been generated with the help of https://app.diagrams.net/. + If you need to change flowchart: + 1. Go to the mentioned site. + 2. Import _static/linters_pipeline_flowchart.drawio. + 3. Change flowchart + 4. Save as .drawio and .png files. + 5. Update appropriate files in _static folder. + +.. image:: /_images/linters_pipeline_flowchart.png + :alt: Linters Pipeline Flowchart + :class: only-light + +.. image:: /_images/linters_pipeline_flowchart.dark.png + :alt: Linters Pipeline Flowchart + :class: only-dark + +Triggers +======== + +Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Jobs overview +============= + +.. _manual_job: https://docs.gitlab.com/ee/ci/jobs/job_control.html#create-a-job-that-must-be-run-manually + +.. _linters-pipeline-check-cpp-coverage: + +check:cpp:coverage +------------------ + +This job calculates an overall coverage of C++ source code by tests. +In order to do that job builds project with compiler specific flags which allow to generate files that can be processed by `Gcov `__. + +At this moment job doesn't reuse artifacts from *build* or *test* stage. +Even so it means pipeline could take much less time, it still much easy to manage a job by itself. + +*ARTIFACTS* + Job will generate a set of files suitable for generating an HTML report. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_CMAKE_ARGS + - Mandatory + +*IMAGES* + :ref:`ubuntu2004:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + As this job is a `manual one `_, it can be triggered only by a user. + +report:cpp:coverage +------------------- + +*ARTIFACTS* + Job produces a statically generated HTML reports using `Gcovr `__. + +*DEPENDENCIES* + Jobs require artifacts from :ref:`linters-pipeline-check-cpp-coverage` job. + +*IMAGES* + `alpine:3 `__. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** and only if :ref:`linters-pipeline-check-cpp-coverage` job has failed. + +.. _pipeline-lang-cpp-linters-format: + +check:cpp:format +---------------- + +This job executes `clang-format `__ *only on changes from C++ files* which will reformat code accordingly to the established project code style. + +.. warning:: + This job uses a docker image with a patched ``clang-format`` to support a custom C++ code style. + +*ALLOW FAILURE* + .. warning:: This job is allowed to fail as it's still in development. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + ``clang-format`` for each input file will try to find the ``.clang-format`` file located in the closest parent directory of the input file. + Different configuration options can be found on `official page `__ + + Default config, which can be found `here `__ and shipped with project C++ related docker images, implements the `following formatting conventions `__ and it's heavily opinionated. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Origin + + * - CI_COMMIT_SHA + - Mandatory + - GitLab + + * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME + - Mandatory + - GitLab + + * - BPROTO_CI_LINTER_TRACE + - Optional + - + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - + +*IMAGES* + :ref:`clang-format:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +check:cpp:include_guards +------------------------ + +This job executes ``checkguard`` from `guardonce `__ package *only on changed C++ files* (not diff, but files) which will detect wrong written `include guards `__. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Current config is hard-coded in `this file `__ and has the following value: + + - ``path | remove - | remove _ | prepend __BPROTO_ | append __ | upper`` + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Origin + + * - CI_PROJECT_DIR + - Mandatory + - GitLab + + * - BPROTO_CI_LINTER_TRACE + - Optional + - + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +.. _pipeline-lang-cpp-linters-cppcheck: + +check:cpp:cppcheck +------------------ + +This job executes `cppcheck `__ *only on changed C++ files* (not diff, but files) which detect bugs and focuses on detecting undefined behavior and dangerous coding constructs. + +*ARTIFACTS* + Job will generate a set of files suitable for generating an HTML report. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.cppcheck`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_CMAKE_GLOBAL_ARGS + - Mandatory + +*IMAGES* + :ref:`ubuntu2004:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + As this job is a `manual one `_, it can be triggered only by a user. + +report:cpp:cppcheck +------------------- + +*ARTIFACTS* + Job produces a statically generated HTML reports using ``cppcheck-htmlreport`` from the `cppcheck `__ package. + +*DEPENDENCIES* + Jobs require artifacts from :ref:`pipeline-lang-cpp-linters-cppcheck` job. + +*IMAGES* + `alpine:3 `__. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** and only if :ref:`pipeline-lang-cpp-linters-cppcheck` job has failed. + +.. _pipeline-lang-cpp-linters-tidy: + +check:cpp:tidy +-------------- + +This job executes `clang-tidy `__ *only on a diff* which will diagnose and fix typical programming errors, like style violations, interface misuse, or bugs that can be deduced via static analysis. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.clang-tidy`` name. + + Default config, which can be found `here `__ and shipped with project C++ related docker images, implements the `following naming conventions `__ and is rather restrictive. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Origin + + * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME + - Mandatory + - GitLab + + * - BPROTO_CI_LINTER_TRACE + - Optional + - + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - + +*IMAGES* + :ref:`ubuntu2004:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + As this job is a `manual one `_, it can be triggered only by a user. + +check:cpp:tidy (nightly) +------------------------ + +This is almost the same job as :ref:`pipeline-lang-cpp-linters-tidy` with one slight difference. +This is a nightly job which checks entire code base on a daily bases. + +The main reason for such separation is ability to detect a set of issues that is impossible to find while only checking files diff. +The downside of this solution is a long running job, which can take more than half an hour to run. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.clang-tidy`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`ubuntu2004:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. diff --git a/docs/pipelines/lang/docker/build.rst b/docs/pipelines/lang/docker/build.rst new file mode 100644 index 0000000..1a96eec --- /dev/null +++ b/docs/pipelines/lang/docker/build.rst @@ -0,0 +1,176 @@ +============== +Build & Deploy +============== + +This is a pipeline for testing and deploying new changes that have been made to anything that is directly related to the *Docker* part of the project. + +.. _pipelines-lang-docker-build-triggers: + +Triggers +======== + +All jobs from *Docker "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to docker files. +Right now such files are detected by below patterns: + +- ``conan/*`` +- ``cmake/Conan.cmake``, +- ``docker/*.Dockerfile``, +- ``scripts/conan/`` +- ``scripts/os/setup_*.sh``, +- ``requirements.txt``. + +Stages overview +=============== + +Build stage +----------- + +This stage is responsible for building `Docker `__ images from a clean state to make sure there are no unexpected results. + +*ALLOW FAILURE* + Jobs are not allowed to fail as any failure means fundamental problems in a specific docker image. + +*ARTIFACTS* + Jobs don't generate any artifacts. + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_DEPLOY_USER + - Mandatory + - + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + - + + * - BPROTO_CI_IMAGES_REGISTRY + - Mandatory + - + + * - *CI_COMMIT_REF_NAME* + - Mandatory + - GitLab + + * - *CI_DEFAULT_BRANCH* + - Mandatory + - GitLab + +*IMAGES* + `docker:19.03.12 `__. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Deploy stage +------------ + +This stage is responsible for generating pre-build docker images for our pipelines. +So called pre-build images are crucial part of our CI/CD as it allows us to decrease execution time of jobs. + +*ALLOW FAILURE* + Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! + +*ARTIFACTS* + New docker images will be deployed to the project `container registry `__. + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_DEPLOY_USER + - Mandatory + - + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + - + + * - BPROTO_CI_IMAGES_REGISTRY + - Mandatory + - + + * - *CI_COMMIT_REF_NAME* + - Mandatory + - GitLab + + * - *CI_DEFAULT_BRANCH* + - Mandatory + - GitLab + +*IMAGES* + `docker:19.03.12 `__. + +*TRIGGERS* + Job is triggered only on ``CI_DEFAULT_BRANCH`` when any file from :ref:`trigger list ` is changed. + +Jobs overview +============= + +.. table:: + :width: 100% + :widths: 40 30 30 + + +--------------------------------+--------+----------------------------------------------------+ + | Job name | Stage | Image | + +================================+========+====================================================+ + | .. centered:: **General purpose images** | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:alpine3`` | build | :ref:`Alipne 3 ` | + +--------------------------------+--------+ + + | ``deploy:docker:alpine3`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:centos7`` | build | :ref:`CentOS 7 ` | + +--------------------------------+--------+ + + | ``deploy:docker:centos7`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:centos8`` | build | :ref:`CentOS 7 ` | + +--------------------------------+--------+ + + | ``deploy:docker:centos8`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:ubuntu2004`` | build | :ref:`Ubuntu 20.04 ` | + +--------------------------------+--------+ + + | ``deploy:docker:ubuntu2004`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | .. centered:: **Dedicated images** | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:clang-format`` | build | :ref:`Clang-Format ` | + +--------------------------------+--------+ + + | ``deploy:docker:clang-format`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:conan`` | build | :ref:`Conan ` | + +--------------------------------+--------+ + + | ``deploy:docker:conan`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:hadolint`` | build | :ref:`HadoLint ` | + +--------------------------------+--------+ + + | ``deploy:docker:hadolint`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ + +Usage +===== + +This is an internal part of the Docker "sub-pipeline" which meant to be used solely by `3CT: Common CI/CD Tools `__ project. diff --git a/docs/pipelines/lang/docker/index.rst b/docs/pipelines/lang/docker/index.rst new file mode 100644 index 0000000..71d0a1e --- /dev/null +++ b/docs/pipelines/lang/docker/index.rst @@ -0,0 +1,20 @@ +.. _pipelines-lang-docker: + +====== +Docker +====== + +This is a "sub-pipeline" for building, linting and deploying new changes that have been made to Docker files of a specific GitLab project. + +.. toctree:: + :maxdepth: 1 + :hidden: + + build.rst + linters.rst + +:doc:`build` + A document which covers all CI jobs responsible for building and deploying docker images. + +:doc:`linters` + A document which covers all CI jobs responsible for linting docker files. diff --git a/docs/pipelines/lang/docker/linters.rst b/docs/pipelines/lang/docker/linters.rst new file mode 100644 index 0000000..41b2dbd --- /dev/null +++ b/docs/pipelines/lang/docker/linters.rst @@ -0,0 +1,68 @@ +======= +Linters +======= + +This is a "sub-pipeline" for linting new changes that have been made to `docker `__ files of a specific GitLab project. + +.. _pipelines-lang-docker-linters-triggers: + +Triggers +======== + +All jobs from *Docker "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to docker files. +Right now such files are detected by these patterns: + +- ``**/.Dockerfile``. + +Jobs overview +============= + +check:docker:lint +----------------- + +This job executes `hadolint `__ *only on changed Docker files* (not diff, but files) which will diagnose bugs that can be deduced via static analysis. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.hadolint.yaml`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`hadolint:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/index.rst b/docs/pipelines/lang/index.rst new file mode 100644 index 0000000..c414fc0 --- /dev/null +++ b/docs/pipelines/lang/index.rst @@ -0,0 +1,25 @@ +========= +Languages +========= + +These documents cover in-detail all available "sub-pipelines" for different programming languages: + +.. toctree:: + :maxdepth: 1 + :hidden: + + common.rst + cmake.rst + cpp/index.rst + docker/index.rst + python/index.rst + shell.rst + yaml.rst + +- :doc:`common`, +- :doc:`cmake`, +- :doc:`cpp/index`, +- :doc:`docker/index`, +- :doc:`python/index`, +- :doc:`shell`, +- :doc:`yaml`. diff --git a/docs/pipelines/lang/python/build.rst b/docs/pipelines/lang/python/build.rst new file mode 100644 index 0000000..1a29781 --- /dev/null +++ b/docs/pipelines/lang/python/build.rst @@ -0,0 +1,55 @@ +============ +Build & Test +============ + +There is no CI jobs in current CI/CD implementation, but there is couple of code snippets that shows how easy it to create a CI job to build and test python code. + +Global cache +============ + +.. code-block:: yaml + + variables: + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + + cache: + key: + files: + - requirements.txt + paths: + - .cache/pip + + example: + image: python:3-alpine3.15 + stage: build-test + before_script: + - pip install -r requirements.txt + script: + # build a package + - pip install . + # or run tests + - pytest + +Job's cache +=========== + +.. code-block:: yaml + + example: + image: python:3-alpine3.15 + stage: build-test + variables: + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + before_script: + - pip install -r requirements.txt + script: + # build a package + - pip install . + # or run tests + - pytest + cache: + key: + files: + - requirements.txt + paths: + - .cache/pip diff --git a/docs/pipelines/lang/python/index.rst b/docs/pipelines/lang/python/index.rst new file mode 100644 index 0000000..25bff45 --- /dev/null +++ b/docs/pipelines/lang/python/index.rst @@ -0,0 +1,20 @@ +.. _pipelines-lang-python: + +====== +Python +====== + +This is a "sub-pipeline" for building, testing and linting new changes that have been made to `python `__ files of a specific GitLab project. + +.. toctree:: + :maxdepth: 1 + :hidden: + + build.rst + linters.rst + +:doc:`build` + A document which covers all CI jobs responsible for building and testing python code. + +:doc:`linters` + A document which covers all CI jobs responsible for linting python code. diff --git a/docs/pipelines/lang/python/linters.rst b/docs/pipelines/lang/python/linters.rst new file mode 100644 index 0000000..fadf173 --- /dev/null +++ b/docs/pipelines/lang/python/linters.rst @@ -0,0 +1,132 @@ +======= +Linters +======= + +This is a "sub-pipeline" for linting new changes that have been made to python files of a specific GitLab project. + +.. _pipelines-lang-python-linters-triggers: + +Triggers +======== + +All jobs from *python "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to python files. +Right now such files are detected by these patterns: + +- ``**/*.py``. + +Jobs overview +============= + +check:python:black +------------------ + +This job executes `black `__ *only on changed python files* (not diff, but files) which will diagnose and fix style violations. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +check:python:flake8 +------------------- + +This job executes `flake8 `__ *only on changed python files* (not diff, but files) which will diagnose and fix style violations, or bugs that can be deduced via static analysis. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.flake8`` name. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +check:python:isort +------------------ + +This job executes `isort `__ *only on changed python files* (not diff, but files) which will diagnose and fix issues related to python imports. + +Different configuration options can be found on `official page `__ + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + ``isort`` for each input file will try to find the ``.isort.cfg`` file located in the closest parent directory of the input file. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/shell.rst b/docs/pipelines/lang/shell.rst new file mode 100644 index 0000000..8d8d16f --- /dev/null +++ b/docs/pipelines/lang/shell.rst @@ -0,0 +1,113 @@ +.. _pipelines-lang-shell: + +===== +Shell +===== + +This is a "sub-pipeline" for linting new changes that have been made to shell scripts of a specific GitLab project. + +.. _pipelines-lang-shell-triggers: + +Triggers +======== + +All jobs from *shell "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to shell scripts. +Right now such files are detected by these patterns: + +- ``**/*.sh``. + +Jobs overview +============= + +check:shell:format +------------------ + +This job executes `shfmt `__ *only on changed Shell files* (not diff, but files) which will diagnose and fix style violations, or bugs that can be deduced via static analysis. + +*ARTIFACTS* + Job will generate a patch file with corrected lines. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.editorconfig`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Type + + * - BPROTO_CI_LINTER_TRACE + - Optional + - Public + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - Internal + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +check:shell:lint +---------------- + +This job executes `shellcheck `__ *only on changed Shell files* (not diff, but files) which will diagnose and fix style violations like wrong variable and function names. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.shellcheck`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Type + + * - BPROTO_CI_LINTER_TRACE + - Optional + - Public + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - Internal + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/yaml.rst b/docs/pipelines/lang/yaml.rst new file mode 100644 index 0000000..174009e --- /dev/null +++ b/docs/pipelines/lang/yaml.rst @@ -0,0 +1,73 @@ +.. _pipelines-lang-yaml: + +==== +YAML +==== + +This is a "sub-pipeline" for linting new changes that have been made to YAML files of a specific GitLab project. + +.. _pipelines-lang-yaml-triggers: + +Triggers +======== + +All jobs from *YAML "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to YAML files. +Right now such files are detected by these patterns: + +- ``**/*.yml``. + +Jobs overview +============= + +check:yaml:format +----------------- + +This job executes `yamllint `__ *only on changed YAML files* (not diff, but files) which will diagnose and fix style violations. + +*ARTIFACTS* + Job will generate a simple log file with all found issues. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.yamllint`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Type + + * - BPROTO_CI_LINTER_TRACE + - Optional + - Public + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + - Internal + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/linters_pipeline.rst b/docs/pipelines/linters_pipeline.rst deleted file mode 100644 index 39a189e..0000000 --- a/docs/pipelines/linters_pipeline.rst +++ /dev/null @@ -1,673 +0,0 @@ -================ -Linters Pipeline -================ - -This is a pipeline for running different linters on all available type of files to check them for consistency of all our code conventions, and to detect possible issues as fast as it's possible. - -Flowchart -========= - -This is a very generalized flowchart that combines in itself all possible roots of pipeline generation and execution. - -.. - Flowchart has been generated with the help of https://app.diagrams.net/. - If you need to change flowchart: - 1. Go to the mentioned site. - 2. Import _static/cicd/linters_pipeline_flowchart.drawio. - 3. Change flowchart - 4. Save as .drawio and .png files. - 5. Update appropriate files in _static folder. - -.. image:: /_static/cicd/linters_pipeline_flowchart.png - :target: ../_images/cicd/linters_pipeline_flowchart.png - :alt: Linters Pipeline Flowchart - :class: only-light - -.. image:: /_static/cicd/linters_pipeline_flowchart.dark.png - :target: ../_images/cicd/linters_pipeline_flowchart.dark.png - :alt: Linters Pipeline Flowchart - :class: only-dark - -Stages overview -=============== - -Check stage ------------ - -This is a stage for running different linters on appropriate set of modified files. - -To avoid duplication of already known information please take a look at **check stage** overview from* :ref:`overview-check-stage`. - -However to avoid going back and force some of the most important information still will be put here. - -All jobs from this stage are triggered only on **merge requests** and if a certain part of the projects have been modified (this can be C++, Docker, Shell files and so on...). - -All jobs are not allowed to fail as all project code must follow established conventions and contain no know defects and issues. - -check:cmake:format -^^^^^^^^^^^^^^^^^^ - -This job executes `cmake-format `__ *only on changed CMake files* (not diff, but files) which will reformat code accordingly to the established project code style. - -Configuration file is located at the root of the repository and has ``.cmake-format.py`` name. - -*ALLOW FAILURE* - .. warning:: This job is allowed to fail as it's still in development. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``*/CMakeLists.txt``, - - ``**/*.cmake``. - -check:cmake:lint -^^^^^^^^^^^^^^^^ - -This job executes `cmake-lint `__ *only on changed CMake files* (not diff, but files) which will diagnose and fix style violations like wrong variable and function names. - -Configuration file is located at the root of the repository and has ``.cmake-format.py`` name. - -*ALLOW FAILURE* - .. warning:: This job is allowed to fail as it's still in development. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``*/CMakeLists.txt``, - - ``**/*.cmake``. - -check:code:license -^^^^^^^^^^^^^^^^^^ - -This job executes `licenseheaders `__ on project source code files, which will detect incorrect license headers. - -Configuration file is located at the root of the repository and has ``.license.tmpl`` name. - -*ALLOW FAILURE* - .. warning:: This job is allowed to fail as it's still in development. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and on all project files except ``3rd-party`` folder. - -check:code:spelling -^^^^^^^^^^^^^^^^^^^ - -This job executes `codespell `__ on project source code files, which will detect common misspellings. - -Configuration file is located at the root of the repository and has ``.codespellrc`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and on all project files except ``3rd-party`` folder. - -check:commits:spelling -^^^^^^^^^^^^^^^^^^^^^^ - -This job executes `codespell `__ on all found branch commits, which will detect common misspellings. - -Configuration file is located at the root of the repository and has ``.codespellrc`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - Origin - - * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME - - Mandatory - - GitLab - -*TRIGGERS* - Job will be triggered only on **merge requests**. - -.. _linters-pipeline-check-cpp-coverage: - -check:cpp:coverage -^^^^^^^^^^^^^^^^^^ - -This job calculates an overall coverage of C++ source code by tests. -In order to do that job builds project with compiler specific flags which allow to generate files that can be processed by `Gcov `__. - -At this moment job doesn't reuse artifacts from *build* or *test* stage. -Even so it means pipeline could take much less time, it still much easy to manage a job by itself. - -*ARTIFACTS* - Job will generate a set of files suitable for generating an HTML report. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_CMAKE_GLOBAL_ARGS - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``project/**/*.cpp``, - - ``project/**/*.hpp``, - - ``project/**/*.ipp``. - -check:cpp:format -^^^^^^^^^^^^^^^^ - -This job executes `clang-format `__ *only on changes from C++ files* which will reformat code accordingly to the established project code style. - -``clang-format`` for each input file will try to find the ``..clang-format`` file located in the closest parent directory of the input file. - -Different configuration options can be found on `official page `__ - -*ALLOW FAILURE* - .. warning:: This job is allowed to fail as it's still in development. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - Origin - - * - CI_COMMIT_SHA - - Mandatory - - GitLab - - * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME - - Mandatory - - GitLab - - * - BPROTO_CI_LINTER_TRACE - - Optional - - - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - - - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``project/**/*.cpp``, - - ``project/**/*.hpp``, - - ``project/**/*.ipp``. - -check:cpp:include_guards -^^^^^^^^^^^^^^^^^^^^^^^^ - -This job executes ``checkguard`` from `guardonce `__ package *only on changed C++ files* (not diff, but files) which will detect wrong written `include guards `__. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - Origin - - * - CI_PROJECT_DIR - - Mandatory - - GitLab - - * - BPROTO_CI_LINTER_TRACE - - Optional - - - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - - - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``project/**/*.cpp``, - - ``project/**/*.hpp``, - - ``project/**/*.ipp``. - -.. _linters-pipeline-check-cpp-cppcheck: - -check:cpp:cppcheck -^^^^^^^^^^^^^^^^^^ - -This job executes `cppcheck `__ *only on changed C++ files* (not diff, but files) which detect bugs and focuses on detecting undefined behavior and dangerous coding constructs. - -Configuration file is located at the root of the repository and has ``.cppcheck`` name. - -*ARTIFACTS* - Job will generate a set of files suitable for generating an HTML report. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_CMAKE_GLOBAL_ARGS - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``project/**/*.cpp``, - - ``project/**/*.hpp``, - - ``project/**/*.ipp``. - -.. _linters-pipeline-check-cpp-tidy: - -check:cpp:tidy -^^^^^^^^^^^^^^ - -This job executes `clang-tidy `__ *only on a diff* which will diagnose and fix typical programming errors, like style violations, interface misuse, or bugs that can be deduced via static analysis. - -Configuration file is located at the root of the repository and has ``.clang-tidy`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - Origin - - * - CI_MERGE_REQUEST_TARGET_BRANCH_NAME - - Mandatory - - GitLab - - * - BPROTO_CI_LINTER_TRACE - - Optional - - - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - - - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``project/**/*.cpp``, - - ``project/**/*.hpp``, - - ``project/**/*.ipp``. - -check:cpp:tidy (nightly) -^^^^^^^^^^^^^^^^^^^^^^^^ - -This is almost the same job as :ref:`linters-pipeline-check-cpp-tidy` with one slight difference. -This is a nightly job which checks entire code base on a daily bases. - -The main reason for such separation is ability to detect a set of issues that is impossible to find while only checking files diff. -The downside of this solution is a long running job, which can take more than half an hour to run. - -check:docker:lint -^^^^^^^^^^^^^^^^^ - -This job executes `hadolint `__ *only on changed Docker files* (not diff, but files) which will diagnose bugs that can be deduced via static analysis. - -Configuration file is located at the root of the repository and has ``.hadolint.yaml`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/.Dockerfile``. - -check:python:black -^^^^^^^^^^^^^^^^^^ - -This job executes `black `__ *only on changed python files* (not diff, but files) which will diagnose and fix style violations. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.py``. - -check:python:flake8 -^^^^^^^^^^^^^^^^^^^ - -This job executes `flake8 `__ *only on changed python files* (not diff, but files) which will diagnose and fix style violations, or bugs that can be deduced via static analysis. - -Configuration file is located at the root of the repository and has ``.flake8`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.py``. - -check:python:isort -^^^^^^^^^^^^^^^^^^ - -This job executes `isort `__ *only on changed python files* (not diff, but files) which will diagnose and fix issues related to python imports. - -``isort`` for each input file will try to find the ``.isort.cfg`` file located in the closest parent directory of the input file. - -Different configuration options can be found on `official page `__ - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.py``. - -check:shell:format -^^^^^^^^^^^^^^^^^^ - -This job executes `shfmt `__ *only on changed Shell files* (not diff, but files) which will diagnose and fix style violations, or bugs that can be deduced via static analysis. - -Configuration file is located at the root of the repository and has ``.editorconfig`` name. - -*ARTIFACTS* - Job will generate a patch file with corrected lines. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.sh``. - -check:shell:lint -^^^^^^^^^^^^^^^^ - -This job executes `shellcheck `__ *only on changed Shell files* (not diff, but files) which will diagnose and fix style violations like wrong variable and function names. - -Configuration file is located at the root of the repository and has ``.shellcheck`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.sh``. - -check:yaml:format -^^^^^^^^^^^^^^^^^ - -This job executes `yamllint `__ *only on changed YAML files* (not diff, but files) which will diagnose and fix style violations. - -Configuration file is located at the root of the repository and has ``.yamllint`` name. - -*ARTIFACTS* - Job will generate a simple log file with all found issues. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_LINTER_TRACE - - Optional - - * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES - - Mandatory - -*TRIGGERS* - Job will be triggered only on **merge requests** and only if there were changes in the below files: - - - ``**/*.yml``. - -Report stage ------------- - -*See also report stage overview from* :ref:`overview-report-stage`. - -report:cpp:coverage -^^^^^^^^^^^^^^^^^^^ - -*ARTIFACTS* - Job produces a statically generated HTML reports using `Gcovr `__. - -*DEPENDENCIES* - Jobs require artifacts from :ref:`linters-pipeline-check-cpp-coverage` job. - -*TRIGGERS* - Jobs are triggered only on **merge requests** and only if :ref:`linters-pipeline-check-cpp-coverage` job has failed. - -report:cpp:cppcheck -^^^^^^^^^^^^^^^^^^^ - -*ARTIFACTS* - Job produces a statically generated HTML reports using ``cppcheck-htmlreport`` from the `cppcheck `__ package. - -*DEPENDENCIES* - Jobs require artifacts from :ref:`linters-pipeline-check-cpp-cppcheck` job. - -*TRIGGERS* - Jobs are triggered only on **merge requests** and only if :ref:`linters-pipeline-check-cpp-cppcheck` job has failed. - -Distribution -============ - -+--------------------------+---------------------------------------------------------+ -| Job | System Configuration | -+ +----------+----------+----------+--------------+---------+ -| | Alpine 3 | CentOS 7 | CentOS 8 | Ubuntu 20.04 | Windows | -+==========================+==========+==========+==========+==============+=========+ -| | .. centered:: **Check stage** | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cmake:format | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cmake:lint | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:code:license | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:code:spelling | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:commits:spelling | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:coverage | no | no | no | **yes** | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:format | Uses its own docker image: ``clang-format``. | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:include_guards | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:cppcheck | no | no | no | **yes** | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:tidy | no | no | no | **yes** | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:cpp:tidy (nightly) | no | no | no | **yes** | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:docker:lint | Uses its own docker image: ``hadolint``. | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:python:black | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:python:flake8 | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:python:isort | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:shell:format | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:shell:lint | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| check:yaml:format | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| | .. centered:: **Report stage** | -+--------------------------+----------+----------+----------+--------------+---------+ -| report:cpp:coverage | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ -| report:cpp:cppcheck | **yes** | no | no | no | no | -+--------------------------+----------+----------+----------+--------------+---------+ diff --git a/docs/pipelines/misc.rst b/docs/pipelines/misc.rst new file mode 100644 index 0000000..852ff2e --- /dev/null +++ b/docs/pipelines/misc.rst @@ -0,0 +1,91 @@ +============= +Miscellaneous +============= + +This is a list of almost all available misc jobs that are currently run in our CI/CD pipelines. + +Jobs overview +============= + +.. _misc-jobs-remove-old-pipelines: + +remove_old_pipelines +-------------------- + +This job executes a custom script that removes outdated pipelines from project pipeline list. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_PRIVATE_API_TOKEN + - Mandatory + - + + * - BPROTO_CI_GENERIC_PACKAGES_REGISTRY + - Mandatory + - + + * - *CI_API_V4_URL* + - Mandatory + - GitLab + + * - *CI_PROJECT_ID* + - Mandatory + - GitLab + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-misc-stage`. + +*TRIGGERS* + Job should be triggered only by a scheduler. + +Scheduled job +^^^^^^^^^^^^^ + +For example GitLab scheduled job can be configured like this: + +.. list-table:: + :header-rows: 1 + :width: 100% + :widths: 40 60 + + * - Name + - Value + + * - Description + - Clean all CI pipelines older than 1 week + + * - Interval Pattern + - Custom (``0 0 * * 0``) + + * - Cron timezone + - ``[UTC 0] UTC`` + + * - Select target branch or tag + - ``main`` + + * - Variables + - ``BPROTO_CI_ENABLE_PIPELINES_CLEANUP`` is ``true`` + +Usage +===== + +In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/misc_pipeline.rst b/docs/pipelines/misc_pipeline.rst deleted file mode 100644 index 32649ad..0000000 --- a/docs/pipelines/misc_pipeline.rst +++ /dev/null @@ -1,48 +0,0 @@ -============= -Misc Pipeline -============= - -This is a list of almost all available misc jobs that are currently run in our CI/CD pipelines. - -Stages overview -=============== - -Misc stage ----------- - -To avoid duplication of already known information please take a look at **misc stage** overview from :ref:`overview-misc-stage`. - -.. _misc-jobs-remove-old-pipelines: - -remove_old_pipelines -^^^^^^^^^^^^^^^^^^^^ - -This job executes a custom script that removes outdated pipelines from project pipeline list. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - Origin - - * - CI_API_V4_URL - - Mandatory - - GitLab - - * - CI_PROJECT_ID - - Mandatory - - GitLab - - * - BPROTO_CI_PRIVATE_API_TOKEN - - Mandatory - - - - * - BPROTO_CI_GENERIC_PACKAGES_REGISTRY - - Mandatory - - - -*TRIGGERS* - Jobs are triggered only by a scheduler. diff --git a/docs/pipelines/packages/conan.rst b/docs/pipelines/packages/conan.rst new file mode 100644 index 0000000..775f67c --- /dev/null +++ b/docs/pipelines/packages/conan.rst @@ -0,0 +1,161 @@ +===== +Conan +===== + +This is a "sub-pipeline" for building, testing and deploying `conan packages `__. + +.. _pipelines-packages-conan-triggers: + +Triggers +======== + +All jobs from docker pipeline stages are triggered only if changes have been made to *conan recipe* related files. +Right now such files are detected by these patterns: + +- ``conandata.yml``, +- ``conanfile.py``. + +**See also:** `Conan packages in the GitLab Package Registry `__. + +Jobs overview +============= + +build:conan +----------- + +This stage is responsible for building conan packages from a clean state to make sure there are no unexpected results. + +*ALLOW FAILURE* + Job is not allowed to fail as any failure here means fundamental problems in a specific conan recipe. + +*ARTIFACTS* + Job doesn't generate any artifacts. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_DEPLOY_USER + - Mandatory + - + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + - + + * - BPROTO_CI_CONAN_PACKAGE_NAME + - Mandatory + - + + * - BPROTO_CI_CONAN_PACKAGES_REGISTRY + - Mandatory + - + + * - *CI_COMMIT_REF_NAME* + - Mandatory + - GitLab + + * - *CI_DEFAULT_BRANCH* + - Mandatory + - GitLab + + * - *CI_PROJECT_ROOT_NAMESPACE* + - Mandatory + - GitLab + +*IMAGES* + :ref:`conan:latest `. + +*STAGE* + :ref:`overview-stages-build-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +deploy:conan +------------ + +.. _package registry: https://docs.gitlab.com/ee/user/packages/package_registry + +This stage is responsible for deploying conan packages to the `package registry`_ defined in ``gitlab`` `remote `__ (which should usually be equal to :ref:`BPROTO_CI_CONAN_PACKAGES_REGISTRY ` environment variable). + +*ALLOW FAILURE* + Job is not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! + +*ARTIFACTS* + New conan package will be deployed to the project `package registry`_. + +*DEPENDENCIES* + Job doesn't generate any artifacts. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_DEPLOY_USER + - Mandatory + - + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + - + + * - BPROTO_CI_CONAN_PACKAGE_NAME + - Mandatory + - + + * - BPROTO_CI_CONAN_PACKAGES_REGISTRY + - Mandatory + - + + * - *CI_COMMIT_REF_NAME* + - Mandatory + - GitLab + + * - *CI_DEFAULT_BRANCH* + - Mandatory + - GitLab + + * - *CI_PROJECT_ROOT_NAMESPACE* + - Mandatory + - GitLab + +*IMAGES* + :ref:`conan:latest `. + +*STAGE* + :ref:`overview-stages-deploy-stage`. + +*TRIGGERS* + Job is triggered only on ``CI_DEFAULT_BRANCH`` when any file from :ref:`trigger list ` is changed. + +Usage +===== + +To correctly use provided CI jobs you need to set :ref:`BPROTO_CI_CONAN_PACKAGES_REGISTRY ` either in `project CI/CD settings `__ or as shown below. + +.. code-block:: yaml + + variables: + BPROTO_CI_CONAN_PACKAGE_NAME: "test_package" + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/conan.yml' diff --git a/docs/pipelines/packages/index.rst b/docs/pipelines/packages/index.rst new file mode 100644 index 0000000..a8feca6 --- /dev/null +++ b/docs/pipelines/packages/index.rst @@ -0,0 +1,14 @@ +======== +Packages +======== + +These documents cover in-detail all available "sub-pipelines" for generating different type of packages. + +.. toctree:: + :maxdepth: 1 + :hidden: + + conan.rst + +:doc:`conan` + A GitLab CI/CD "sub-pipeline" which covers all CI jobs responsible for building and deploying conan packages. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..3dfda3a --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,22 @@ +===== +Usage +===== + +This project can be used mainly be used in two completely distinct ways: + +- as a `CI/CD template `__, +- and as a `fork `__. + +This page will try to cover in-deep those two ways. + +GitLab templates +================ + +Available templates +^^^^^^^^^^^^^^^^^^^ + +Limitations +^^^^^^^^^^^ + +Forks +===== diff --git a/docs/pipelines/variables.rst b/docs/variables.rst similarity index 86% rename from docs/pipelines/variables.rst rename to docs/variables.rst index cf93fd4..6ce6482 100644 --- a/docs/pipelines/variables.rst +++ b/docs/variables.rst @@ -19,14 +19,11 @@ Local CI/CD variables The output contains the content of all variables and other secrets available to the job. The output is uploaded to the GitLab server and visible in job logs. +.. _variables-bproto-ci-conan-package-name: + **BPROTO_CI_CONAN_PACKAGE_NAME**:STRING A name of a conan package which will be used when deploying to the `artifacts `__ package registry. -**BPROTO_CI_DOCS_NAME**:STRING - A name of an archive with generated HTML documentation which will be deployed to the `artifacts `__ package registry. - - Usually defaults to one of ``BPROTO_CI_*_DOCS_NAME`` variables. - **BPROTO_CI_LINTER_TRACE**:STRING Enable debug logging to help troubleshoot problems with linter jobs. Debug logging exposes job execution details that are usually hidden and makes job logs more verbose. @@ -41,11 +38,21 @@ Local CI/CD variables .. note:: This variable is only available for **linter** jobs. +**BPROTO_CI_SPHINX_SOURCE_DIR**:PATH + Path to `Sphinx `__ source files. + + Defaults to ``docs``. + +**BPROTO_CI_SPHINX_WARNINGS_AS_ERRORS**:BOOL + Turn ``sphinx-build`` warnings into errors. + + Defaults to ``false``. + Global CI/CD variables ====================== -**BPROTO_CI_CICD_DOCS_NAME**:STRING - A package name for `CI/CD `__ project HTML docs. +**BPROTO_CI_CONAN_PACKAGES_REGISTRY**:URL + A link to an `artifacts`_'s `conan packages `__ `registry `__. **BPROTO_CI_DEPLOY_TOKEN**:STRING A `deploy token `__ for `artifacts`_'s `packages and registries `__. @@ -77,7 +84,7 @@ GitLab group-level variables +----------+-------------------------------------+----------------------------+-----------+---------+--------------+ | Type | Key | Value | Protected | Masked | Environments | +==========+=====================================+============================+===========+=========+==============+ -| Variable | BPROTO_CI_CICD_DOCS_NAME | cicd_docs | **yes** | no | All | +| Variable | BPROTO_CI_CONAN_PACKAGES_REGISTRY | \- | **yes** | no | All | +----------+-------------------------------------+----------------------------+-----------+---------+--------------+ | Variable | BPROTO_CI_DEPLOY_TOKEN | \- | no | **yes** | All | +----------+-------------------------------------+----------------------------+-----------+---------+--------------+ @@ -93,7 +100,7 @@ GitLab group-level variables +----------+-------------------------------------+----------------------------+-----------+---------+--------------+ .. note:: - To change above environment variables go to `group CI/CD settings `__ to *Variables* section. + To change above environment variables please follow instructions provided by the official `group CI/CD settings `__ user guide. Misc CI/CD variables ==================== diff --git a/scripts/cicd/lint/check_include_guards.sh b/scripts/cicd/lint/check_cpp_include_guards.sh similarity index 100% rename from scripts/cicd/lint/check_include_guards.sh rename to scripts/cicd/lint/check_cpp_include_guards.sh -- GitLab From 745a1af088d3dc36fb8ac3a23d13868503e6a233 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 17 Oct 2023 01:40:27 +0300 Subject: [PATCH 07/44] Fix "ignore" files Tags: Docker --- .dockerignore | 13 +++++++------ .gitignore | 15 ++++++++------- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/.dockerignore b/.dockerignore index de1a0d2..9b08215 100644 --- a/.dockerignore +++ b/.dockerignore @@ -7,10 +7,6 @@ *.* -# But don't ignore these specific directories and subdirectories with specific files: - -!/docker - # But don't ignore these specific files: !.clang-* @@ -20,10 +16,8 @@ !.hadolint.yaml !.license.tmpl !.yamllint -!conanfile.txt !requirements.txt -!**.Dockerfile !**.patch !**.py !**.sh @@ -31,6 +25,13 @@ # ...even if they are in subdirectories !*/ +# But don't ignore these specific directories and subdirectories with specific files: + +!/conan +!/conan/** + +# But ignore these specific directories and subdirectories with specific files: + .git/ .idea/ .venv/ diff --git a/.gitignore b/.gitignore index 64e307b..08d909c 100644 --- a/.gitignore +++ b/.gitignore @@ -7,12 +7,6 @@ *.* -# But don't ignore these specific directories and subdirectories with specific files: - -!/.gitlab -!/docker -!/docs - # But don't ignore these specific files: !.clang-* @@ -25,7 +19,6 @@ !.hadolint.yaml !.license.tmpl !.yamllint -!conanfile.txt !CONTRIBUTING.md !LICENSE !README.md @@ -36,10 +29,18 @@ !**.py !**.rst !**.sh +!**.yml # ...even if they are in subdirectories !*/ +# But don't ignore these specific directories and subdirectories with specific files: + +!/conan +!/conan/** + +# But ignore these specific directories and subdirectories with specific files: + /.idea/ /.venv/ /build/ -- GitLab From 517096ebfd88e6e66d50ee8d54d4857c4d74adb1 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 17 Oct 2023 01:40:56 +0300 Subject: [PATCH 08/44] Fix broken dependencies for python packages --- requirements.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements.txt b/requirements.txt index 7536301..cd4307e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -49,3 +49,5 @@ requests docutils==0.17.1 pygments==2.11.0 + +pyyaml~=5.3.1 # TODO: https://github.com/yaml/pyyaml/issues/601 -- GitLab From 4806f3f2c8105bbdbda39da3cdcfcd0c5621010f Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 17 Oct 2023 01:41:46 +0300 Subject: [PATCH 09/44] Fix broken docs build Tags: Docs --- docs/pipelines/lang/cpp/build.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pipelines/lang/cpp/build.rst b/docs/pipelines/lang/cpp/build.rst index 7f64e79..72c84ce 100644 --- a/docs/pipelines/lang/cpp/build.rst +++ b/docs/pipelines/lang/cpp/build.rst @@ -104,7 +104,7 @@ Test stage This is a stage for running all available C++ tests. -*See also test stage overview from* :ref:`overview-test-stage`. +*See also test stage overview from* :ref:`overview-stages-test-stage`. Report stage ------------ -- GitLab From b3e3a2b9cd3d302c783cb89eaae5d1c49658b437 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 17 Oct 2023 01:42:35 +0300 Subject: [PATCH 10/44] Bump alpine image version Tags: Alpine, Docker --- docker/Alpine3.Dockerfile | 2 +- docs/images/g/alpine3.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docker/Alpine3.Dockerfile b/docker/Alpine3.Dockerfile index aa401a2..9e2ebcf 100644 --- a/docker/Alpine3.Dockerfile +++ b/docker/Alpine3.Dockerfile @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -FROM python:3-alpine3.15 +FROM python:3.12-alpine WORKDIR /tmp diff --git a/docs/images/g/alpine3.rst b/docs/images/g/alpine3.rst index 07cd379..fc3d470 100644 --- a/docs/images/g/alpine3.rst +++ b/docs/images/g/alpine3.rst @@ -11,7 +11,7 @@ A utility image which contains all possible linters and ``sphinx`` related packa - ``alpine3:latest`` *BASE IMAGE* - Official `python:3-alpine3.15 `_ image. + Official `python:3.12-alpine `_ image. *BUILD TIME* 2 minutes on average. -- GitLab From 8f1c05e5798578ab9c8c9f9b0d6fccd430609072 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Tue, 17 Oct 2023 01:43:23 +0300 Subject: [PATCH 11/44] Bump base images version for clang-format Tags: ClangFormat, Docker --- docker/ClangFormat.Dockerfile | 4 ++-- docs/images/d/clang-format.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docker/ClangFormat.Dockerfile b/docker/ClangFormat.Dockerfile index 9cb8860..87beaaa 100644 --- a/docker/ClangFormat.Dockerfile +++ b/docker/ClangFormat.Dockerfile @@ -20,7 +20,7 @@ # Build clang-format # #------------------------------------------------------------------------------# -FROM alpine:3.15 as clang-format-build +FROM alpine:3.18 as clang-format-build # Pass `--build-arg LLVM_TAG=master` for latest llvm commit ARG LLVM_TAG @@ -55,7 +55,7 @@ RUN cmake -GNinja \ # Install clang-format # #------------------------------------------------------------------------------# -FROM python:3-alpine3.15 +FROM python:3-alpine3.18 COPY --from=clang-format-build /build/llvm-project/build/bin/clang-format /usr/bin COPY --from=clang-format-build /build/llvm-project/clang/tools/clang-format/clang-format-diff.py /usr/local/bin/ diff --git a/docs/images/d/clang-format.rst b/docs/images/d/clang-format.rst index c473677..01ad1da 100644 --- a/docs/images/d/clang-format.rst +++ b/docs/images/d/clang-format.rst @@ -13,7 +13,7 @@ A docker image with a patched ``clang-format`` to support a custom C++ code styl - ``clang-format:latest`` *BASE IMAGE* - Official `alpine:3.15 `_ and `python:3-alpine3.15 `_ images (multi-stage build). + Official `alpine:3.18 `_ and `python:3-alpine3.18 `_ images (multi-stage build). *BUILD TIME* 20 minutes on average. -- GitLab From 8f298cc7d931bc3416e25b11406d0d1e729cac40 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 5 Nov 2023 23:11:53 +0000 Subject: [PATCH 12/44] Finish missing parts of project documentation --- README.md | 100 ++++++++++----- docs/conf.py | 4 +- docs/images/g/centos7.rst | 2 +- docs/images/g/centos8.rst | 2 +- docs/images/g/ubuntu2004.rst | 2 +- docs/images/index.rst | 2 +- docs/index.rst | 98 ++++++++++++++- docs/overview/artifacts.rst | 16 ++- docs/overview/index.rst | 4 +- docs/overview/stages.rst | 2 + docs/overview/workflow.rst | 44 +++++++ docs/pipelines/docs/hugo.rst | 2 + docs/pipelines/docs/sphinx.rst | 2 + docs/pipelines/docs/sphinx_old_approach.rst | 131 ++++++++++++++++++++ docs/pipelines/lang/cmake.rst | 2 +- docs/pipelines/lang/common.rst | 2 +- docs/pipelines/lang/cpp/index.rst | 15 ++- docs/pipelines/lang/cpp/linters.rst | 66 ++++++++++ docs/pipelines/lang/python/index.rst | 13 ++ docs/pipelines/lang/python/linters.rst | 13 -- docs/pipelines/lang/shell.rst | 2 +- docs/pipelines/lang/yaml.rst | 2 +- docs/pipelines/packages/conan.rst | 2 + docs/usage.rst | 22 ---- docs/variables.rst | 12 +- requirements.txt | 6 +- 26 files changed, 472 insertions(+), 96 deletions(-) create mode 100644 docs/pipelines/docs/sphinx_old_approach.rst delete mode 100644 docs/usage.rst diff --git a/README.md b/README.md index 1d9aed5..08c8657 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,89 @@ -# Cpp Template Projecte - Common CI/CD Tools +# GitLab Common CI/CD Tools -This repository contains content for our CI/CD. +[caching]: https://docs.gitlab.com/ee/ci/caching +[fork]: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html -## Contributing +**GitLab Common CI/CD Tools** (**GitLab 3CT** for short) provides a [GitLab CI/CD](https://docs.gitlab.com/ee/ci) solution that helps to control the quality of mainly C++ and Python codebases and their surrounding infrastructure. -1. Clone this repository: +While the driving force of this module is to reduce duplication of CI/CD configurations and scripts across projects developed by me ([Zinchenko Serhii](https://gitlab.com/b110011)), it is intended to be useful for any software that wants to utilize GitLab CI/CD to some degree. -```bash -$ mkdir bproto -$ cd bproto -$ git clone https://gitlab.com/bproto/cicd.git -$ cd cicd -``` +This module also may serve as a useful reference for setting up a GitLab CI/CD using good practices. -You can also clone this repository using [GitLab token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). +**Table of contents** (generated with [markdown-toc](http://ecotrust-canada.github.io/markdown-toc/)) -```bash -$ git clone https://oauth2:@gitlab.com/bproto/cicd.git -``` +- [Usage](#usage) + - [CI/CD templates](#cicd-templates) + - [Forks](#forks) +- [License](#license) + +## Usage + +By design this project is intended to be used as a [CI/CD template](https://docs.gitlab.com/ee/ci/examples/index.html) in most of the cases. +However due to some limitations it might be [forked][fork] to bring some changes and then to be used as your own CI/CD template. +Both ways will be covered in-deep down on this page. + +### CI/CD templates -*For alternative ways you can check out [this SO thread](https://stackoverflow.com/questions/25409700).* +This project provides a bunch of useful [GitLab CI/CD pipelines](https://docs.gitlab.com/ee/ci/pipelines/index.html) for different programming languages and frameworks. +Below is a nice list of all available pipelines: -2. Setup a default merge strategy for pulling branches. +[conan-tmpl]: .gitlab/ci/external/conan.yml +[cpp-tmpl]: .gitlab/ci/external/cpp.yml +[hugo-tmpl]: .gitlab/ci/external/hugo.yml +[lite-tmpl]: .gitlab/ci/external/conan.yml +[sphinx-tmpl]: .gitlab/ci/external/sphinx.yml -```bash -$ git config pull.rebase true +- **Documentation** + - Hugo ([.gitlab/ci/external/hugo.yml][hugo-tmpl]) + - Sphinx ([.gitlab/ci/external/sphinx.yml][sphinx-tmpl]) +- **Languages** + - C++ ([.gitlab/ci/external/cpp.yml][cpp-tmpl]) + - CMake ([.gitlab/ci/external/lite.yml][lite-tmpl]) + - Docker ([.gitlab/ci/external/lite.yml][lite-tmpl]) + - Linux shell ([.gitlab/ci/external/lite.yml][lite-tmpl]) + - Python ([.gitlab/ci/external/lite.yml][lite-tmpl]) + - YAML ([.gitlab/ci/external/lite.yml][lite-tmpl]) +- **Packages** + - Conan ([.gitlab/ci/external/conan.yml][conan-tmpl]) + +You can start using those pipelines by including one of them as shown below: + +```yaml +include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' ``` -3. Create a branch. - This can either be an informal user branch or a full-fledged ticket branch tracked in JIRA. +You also need to define below [CI/CD variables](https://docs.gitlab.com/ee/ci/variables) in your [group](https://docs.gitlab.com/ee/ci/variables/#for-a-group) or [project](https://docs.gitlab.com/ee/ci/variables/#for-a-project) CI/CD settings. + +| Type | Key | Value | Protected | Masked | Environments | +| --- | --- | --- | --- | --- | --- | +| Variable | BPROTO_CI_IMAGES_REGISTRY | `registry.gitlab.com/bproto/artifacts` | no | no | All | + +Now you are ready to go! -4. Make and commit your edits. +[overview]: https://bproto.gitlab.io/cicd/overview/index.html +[overview-stages]: https://bproto.gitlab.io/cicd/overview/stages.html +[overview-workflow]: https://bproto.gitlab.io/cicd/overview/workflow.html -5. Push your development branch to GitLab and make a merge request. - The merge request page will help you track the publishing and testing status of your branch. +> To have a better understanding of pipelines implementation, you might also consider looking at an [overview][overview] of different aspects of pipelines, such as a list of implemented [stages][overview-stages] and how the [workflow][overview-workflow] was designed. -6. Once you've passed a code review, ask of repository maintainers to merge your changes to `master` branch. +### Forks -## Prepearing development environment +The general rule of thumb can be answering positive to one of below questions: -*Assuming you are using of Ubuntu based distributions.* +[images]: https://bproto.gitlab.io/cicd/images/index.html +[pipelines-lang-cpp]: https://bproto.gitlab.io/cicd/pipelines/lang/cpp/index.html +[pipelines-lang-cpp-limitations]: https://bproto.gitlab.io/cicd/pipelines/lang/cpp/index.html#limitations -### Installing your favorite code editor +- do I need a different toolchain than is provided by current [pre-build docker image][images]? +- do I need a different set of python package than what is provided by current [pre-build docker image][images] and [caching][caching] can't help you with that? +- do I need to tweak [C++ pipeline][pipelines-lang-cpp] implementation? -Please consult our [documentation](https://bproto.gitlab.io/editors/index.html) for configuration suggestions of your favorite code editor. +Also it's worth to mention that some pipelines, like [C++][pipelines-lang-cpp] one, have [though limitations][pipelines-lang-cpp-limitations] that can be overcome by [caching][caching] packages but you still might decide to [fork][fork] this project and change some lines. -## Editing entirely on GitLab +## License -If you're in a hurry, you don't need to worry about cloning the Developer Guide; you can do everything on GitLab.com. -See [GitLab's documentation](https://docs.gitlab.com/ee/user/project/web_ide/) on editing files and creating branches entirely from [GitLab.com](https://gitlab.com). +All code is licensed under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license. diff --git a/docs/conf.py b/docs/conf.py index 73bf619..3c6ab16 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ # -- Project information ----------------------------------------------------- author = "Zinchenko Serhii" -project = "3CT" +project = "GitLab 3CT" copyright = f"2020-{datetime.datetime.now().year}, Zinchenko Serhii" # noqa: A001 @@ -18,6 +18,8 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +extensions = ["sphinx_copybutton"] + # More can be found here: https://stackoverflow.com/a/60991308. rst_prolog = """ .. include:: diff --git a/docs/images/g/centos7.rst b/docs/images/g/centos7.rst index 6215754..ac08b71 100644 --- a/docs/images/g/centos7.rst +++ b/docs/images/g/centos7.rst @@ -59,7 +59,7 @@ A C++ based image which contains all required and optional packages to build C++ +----------------------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. + Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* Mainly ``conan`` package and ``sphinx`` related packages. diff --git a/docs/images/g/centos8.rst b/docs/images/g/centos8.rst index 965ccc0..5440246 100644 --- a/docs/images/g/centos8.rst +++ b/docs/images/g/centos8.rst @@ -53,7 +53,7 @@ A C++ based image which contains all required and optional packages to build C++ +----------------------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. + Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* Mainly ``conan`` package and ``sphinx`` related packages. diff --git a/docs/images/g/ubuntu2004.rst b/docs/images/g/ubuntu2004.rst index 7e596f6..ddea969 100644 --- a/docs/images/g/ubuntu2004.rst +++ b/docs/images/g/ubuntu2004.rst @@ -65,7 +65,7 @@ A C++ based image which contains all required and optional packages to build C++ +----------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* - Only those which are listed in ``Conan.cmake`` file. + Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* Mainly ``conan`` package and ``sphinx`` related packages. diff --git a/docs/images/index.rst b/docs/images/index.rst index 90d7cbc..ca29c3a 100644 --- a/docs/images/index.rst +++ b/docs/images/index.rst @@ -1,4 +1,4 @@ -.. _images-index-page: +.. _images: ======================= Pre-build docker images diff --git a/docs/index.rst b/docs/index.rst index 496ce65..6ca3949 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,6 @@ -####################### -3CT: Common CI/CD Tools -####################### +========================= +GitLab Common CI/CD Tools +========================= .. toctree:: :caption: Documentation @@ -10,7 +10,6 @@ overview/index.rst images/index.rst pipelines/index.rst - usage.rst variables.rst useful_links.rst @@ -20,3 +19,94 @@ :hidden: git/index.rst + +.. _caching: https://docs.gitlab.com/ee/ci/caching +.. _fork: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html + +.. _`Zinchenko Serhii`: https://gitlab.com/b110011 + +**GitLab Common CI/CD Tools** (**GitLab 3CT** for short) provides a `GitLab CI/CD `__ solution that helps to control the quality of mainly C++ and Python codebases and their surrounding infrastructure. + +While the driving force of this module is to reduce duplication of CI/CD configurations and scripts across projects developed by me (`Zinchenko Serhii`_), it is intended to be useful for any software that wants to utilize GitLab CI/CD to some degree. + +This module also may serve as a useful reference for setting up a GitLab CI/CD using good practices. + +Usage +===== + +By design this project is intended to be used as a `CI/CD template `__ in most of the cases. +However due to some limitations it might be `forked `__ to bring some changes and then to be used as your own CI/CD template. +Both ways will be covered in-deep down on this page. + +CI/CD templates +--------------- + +This project provides a bunch of useful `GitLab CI/CD pipelines `__ for different programming languages and frameworks. +Below is a nice list of all available pipelines: + +.. _conan-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/conan.yml +.. _cpp-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/cpp.yml +.. _hugo-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/hugo.yml +.. _lite-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/conan.yml +.. _sphinx-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/sphinx.yml + +- **Documentation** + - Hugo (`.gitlab/ci/external/hugo.yml `__) + - Sphinx (`.gitlab/ci/external/sphinx.yml `__) +- **Languages** + - C++ (`.gitlab/ci/external/cpp.yml `__) + - CMake (`.gitlab/ci/external/lite.yml `__) + - Docker (`.gitlab/ci/external/lite.yml `__) + - Linux shell (`.gitlab/ci/external/lite.yml `__) + - Python (`.gitlab/ci/external/lite.yml `__) + - YAML (`.gitlab/ci/external/lite.yml `__) +- **Packages** + - Conan (`.gitlab/ci/external/conan.yml `__) + +You can start using those pipelines by including one of them as shown below: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' + +You also need to define below `CI/CD variables `__ in your `group `__ or `project `__ CI/CD settings. + +.. raw:: html + + + ++----------+---------------------------+------------------------------------------+-----------+---------+--------------+ +| Type | Key | Value | Protected | Masked | Environments | ++==========+===========================+==========================================+===========+=========+==============+ +| Variable | BPROTO_CI_IMAGES_REGISTRY | ``registry.gitlab.com/bproto/artifacts`` | no | no | All | ++----------+---------------------------+------------------------------------------+-----------+---------+--------------+ + +Now you are ready to go! + +.. note:: + + To have a better understanding of pipelines implementation, you might also consider looking at an :ref:`overview ` of different aspects of pipelines, such as a list of implemented :ref:`stages ` and how the :ref:`workflow ` was designed. + +Forks +----- + +The general rule of thumb can be answering positive to one of below questions: + +- do I need a different toolchain than is provided by current :ref:`pre-build docker image `? +- do I need a different set of python package than what is provided by current :ref:`pre-build docker image ` and caching_ can't help you with that? +- do I need to tweak :ref:`C++ pipeline ` implementation? + +Also it's worth to mention that some pipelines, like :ref:`C++ ` one, have :ref:`though limitations ` that can be overcome by caching_ packages but you still might decide to `fork `__ this project and change some lines. + +License +======= + +All code is licensed under the `Apache 2.0 `__ license. diff --git a/docs/overview/artifacts.rst b/docs/overview/artifacts.rst index eeb26b1..d697a3b 100644 --- a/docs/overview/artifacts.rst +++ b/docs/overview/artifacts.rst @@ -1,3 +1,5 @@ +.. _overview-artifacts: + ========= Artifacts ========= @@ -5,7 +7,9 @@ Artifacts .. _container-registry: https://docs.gitlab.com/ee/user/packages/container_registry/index.html .. _package-registry: https://docs.gitlab.com/ee/user/packages/package_registry/index.html -This project tries to utilize GitLab `package `_ and `container `_ registries as they're fullest. +An artifacts system for this project is fully based on GitLab `package `_ and `container `_ registries and tries to utilize them to the fullest. + +It's still possible to use `Docker Hub `__ and `JFrog's Artifactory `__ but that will require some work to be done. .. Flowchart has been generated with the help of https://app.diagrams.net/. @@ -17,9 +21,15 @@ This project tries to utilize GitLab `package `_ and `contain 5. Update appropriate files in _static folder. .. image:: /_images/artifacts.png - :alt: C++ Pipeline Flowchart + :alt: Artifacts main repository :class: only-light .. image:: /_images/artifacts.dark.png - :alt: C++ Pipeline Flowchart + :alt: Artifacts main repository :class: only-dark + +Also despite the fact that any GitLab project can enable `package `_ and `container `_ registries, it has been decided to store all "shared" artifacts in a separate GitLab project called "artifacts". + +Here is an example of a such one: https://gitlab.com/bproto/artifacts. + +This approach helps to provide emulate a single source of artifacts and provide a simple way of distinguishing a "local" project only artifacts from those that are supposed to be shared across other projects too. diff --git a/docs/overview/index.rst b/docs/overview/index.rst index 4c2d20d..56a4599 100644 --- a/docs/overview/index.rst +++ b/docs/overview/index.rst @@ -1,3 +1,5 @@ +.. _overview: + ======== Overview ======== @@ -19,4 +21,4 @@ This page is geared towards developers of the project CI/CD pipelines, and serve An overview of triggers for jobs from different stages. :doc:`artifacts` - An overview of triggers for jobs from different stages. + An overview of project ideas around artifacts storage. diff --git a/docs/overview/stages.rst b/docs/overview/stages.rst index ab2ffaa..d2bb4e7 100644 --- a/docs/overview/stages.rst +++ b/docs/overview/stages.rst @@ -1,3 +1,5 @@ +.. _overview-stages: + =============== Stages overview =============== diff --git a/docs/overview/workflow.rst b/docs/overview/workflow.rst index 9c38e96..f22d450 100644 --- a/docs/overview/workflow.rst +++ b/docs/overview/workflow.rst @@ -1,7 +1,12 @@ +.. _overview-workflow: + ======== Workflow ======== +Stages distribution +=================== + A below table shows when jobs of a certain stage will be triggered. .. table:: @@ -22,3 +27,42 @@ A below table shows when jobs of a certain stage will be triggered. +--------+---------+-------------------+---------------+ | misc | no | **yes** | no | +--------+---------+-------------------+---------------+ + +Merge request labels +==================== + +.. _merge requests: https://docs.gitlab.com/ee/user/project/merge_requests/ +.. _label: https://docs.gitlab.com/ee/user/project/labels.html + +Current implementation provides a way to temporary or completely disable pipelines for specific `merge requests`_ by setting special label_. +Below is a list of such labels. + +.. note:: + Do please note that everything will work even you add only one label from the list. + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + + * - ``ci::skip`` + - + + * - ``workflow::paused`` + - Merge requests / issues which are temporarily not worked on + +Also it's recommended, but not required, to add other useful labels. +However if you have already set-up your own labels you can safely skip this part. + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + + * - ``workflow::blocked`` + - Merge requests / issues that are blocked until another issue has been completed + + * - ``workflow::in-development`` + - Merge requests / issues that are actively being worked on by a developer diff --git a/docs/pipelines/docs/hugo.rst b/docs/pipelines/docs/hugo.rst index b46f5e0..6d5da5d 100644 --- a/docs/pipelines/docs/hugo.rst +++ b/docs/pipelines/docs/hugo.rst @@ -1,3 +1,5 @@ +.. _pipelines-docs-hugo: + ==== Hugo ==== diff --git a/docs/pipelines/docs/sphinx.rst b/docs/pipelines/docs/sphinx.rst index 7e5c9f9..10dc2ab 100644 --- a/docs/pipelines/docs/sphinx.rst +++ b/docs/pipelines/docs/sphinx.rst @@ -1,3 +1,5 @@ +.. _pipelines-docs-sphinx: + ============= Sphinx (reST) ============= diff --git a/docs/pipelines/docs/sphinx_old_approach.rst b/docs/pipelines/docs/sphinx_old_approach.rst new file mode 100644 index 0000000..6381294 --- /dev/null +++ b/docs/pipelines/docs/sphinx_old_approach.rst @@ -0,0 +1,131 @@ +:orphan: + +=============== +Docs generation +=============== + +This is a pipeline for testing and deploying new changes that have been made to anything that is directly related to the *documentation* part of the project. + +All jobs from documentation pipeline stages are triggered only if changes have been made to documentation related files. +Right now such files are detected by these patterns: + +- ``docs/**/*`` +- ``project/**/CMakeLists.txt`` +- ``project/**/include/**/*.hpp`` + +As you can see from the above list of files pipeline will take into account both types of the project documentation: Doxygen (C++ files) and Sphinx (RST files) documentation. + +Flowchart +========= + +This is a very generalized flowchart that combines in itself all possible roots of pipeline generation and execution. + +.. + Flowchart has been generated with the help of https://app.diagrams.net/. + If you need to change flowchart: + 1. Go to the mentioned site. + 2. Import _static/docs_pipeline_flowchart.drawio. + 3. Change flowchart + 4. Save as .drawio and .png files. + 5. Update appropriate files in _static folder. + +.. image:: /_images/docs_pipeline_flowchart.png + :alt: Docs Pipeline Flowchart + :class: only-light + +.. + fill 4E220F, line EF8C61 + fill 052853, line 4B9AFB +.. image:: /_images/docs_pipeline_flowchart.dark.png + :alt: Docs Pipeline Flowchart + :class: only-dark + +Stages overview +=============== + +Build stage +----------- + +This stage is responsible for building HTML documentation from a clean state to make sure there are no unexpected results. + +*ALLOW FAILURE* + Jobs are not allowed to fail as any failure here means fundamental problems in documentation generation. + +*ARTIFACTS* + Jobs generate an artifact with a HTML documentation. + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs has no dependencies from other stages or jobs. + +*IMAGES* + All jobs from this stage must use one of pre-build docker images to decrease overall pipeline time. + +*TRIGGERS* + Jobs are triggered only on **merge requests**. + +Deploy stage +------------ + +This stage is responsible for building and deploying static HTML documentation files to the project registry. + +*ALLOW FAILURE* + Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! + +*ARTIFACTS* + New version of the documentation will be deployed to the project `generic packages repository `__ in a form an ``tar`` archive. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + + * - BPROTO_CI_DOCS_NAME + - Mandatory + + * - BPROTO\_CI\_\*_DOCS_NAME + - Mandatory + + * - BPROTO_CI_GENERIC_PACKAGES_REGISTRY + - Mandatory + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs has no dependencies from other stages or jobs. + +*IMAGES* + Nothing specific here. + +*TRIGGERS* + Jobs are triggered only on ``CI_DEFAULT_BRANCH``. + +Misc stage +---------- + +After a successful deploy, job from this stage will trigger a pipeline of `other project `__ using `GitLab API `__. +If external pipeline succeed, new version of documentation will be available on https://bproto.gitlab.io. + +*ALLOW FAILURE* + Jobs are not allowed to fail as these jobs are run only on ``CI_DEFAULT_BRANCH`` after accepting a successful merge request! + +*ARTIFACTS* + Jobs don't generate any artifacts. + +*DEPENDENCIES* + Jobs don't require artifacts from other jobs. + + Jobs has a dependency to a job from *deploy* stage. + +*IMAGES* + No image is required. + +*TRIGGERS* + Jobs are triggered only on ``CI_DEFAULT_BRANCH``. diff --git a/docs/pipelines/lang/cmake.rst b/docs/pipelines/lang/cmake.rst index 67db546..7ab5eef 100644 --- a/docs/pipelines/lang/cmake.rst +++ b/docs/pipelines/lang/cmake.rst @@ -111,7 +111,7 @@ This job executes `cmake-lint `__ * Usage ===== -In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: +In order to use above CI jobs, you need to add the following code to your `.gitlab-ci.yml`: .. code-block:: yaml diff --git a/docs/pipelines/lang/common.rst b/docs/pipelines/lang/common.rst index 805d33d..1f56d8d 100644 --- a/docs/pipelines/lang/common.rst +++ b/docs/pipelines/lang/common.rst @@ -125,7 +125,7 @@ This job executes `codespell `__ Usage ===== -In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: +In order to use above CI jobs, you need to add the following code to your `.gitlab-ci.yml`: .. code-block:: yaml diff --git a/docs/pipelines/lang/cpp/index.rst b/docs/pipelines/lang/cpp/index.rst index 7fab92a..a0f32e3 100644 --- a/docs/pipelines/lang/cpp/index.rst +++ b/docs/pipelines/lang/cpp/index.rst @@ -44,7 +44,7 @@ Those modules do all the heavy lifting like a seamless integration of sanitizes, Pre-build Docker images ^^^^^^^^^^^^^^^^^^^^^^^ -Due to the fact that all "sub-pipeline"s (this one is not an exception) try to utilizes :ref:`pre-build docker images ` as much as possible, this will be the rock on which we split in most of the cases. +Due to the fact that all "sub-pipeline"s (this one is not an exception) try to utilizes :ref:`pre-build docker images ` as much as possible, this will be the rock on which we split in most of the cases. .. _gitlab-caching: https://docs.gitlab.com/ee/ci/caching .. _gitlab-fork: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html @@ -127,3 +127,16 @@ Right now such files are detected by these patterns: - ``project/**/*.cpp``, - ``project/**/*.hpp``, - ``project/**/*.ipp``. + +Usage +===== + +In order to use this "sub-pipeline" you need to add the following code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/cpp.yml' diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index da88223..30875d2 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -307,9 +307,14 @@ This is a nightly job which checks entire code base on a daily bases. The main reason for such separation is ability to detect a set of issues that is impossible to find while only checking files diff. The downside of this solution is a long running job, which can take more than half an hour to run. +However that issue is mitigated a little bit by caching current job result and a commit hash on which that job has run. +So the next job run might do nothing if commit hash hasn't changed from the time of the last run. + *ARTIFACTS* Job will generate a simple log file with all found issues. + Also it will generate and save a simple package (``nightly_clang_tidy``) that contains a result of current job run and a commit hash on which the job has run. + *CONFIG* Configuration file is located at the root of the repository and has ``.clang-tidy`` name. @@ -332,3 +337,64 @@ The downside of this solution is a long running job, which can take more than ha *STAGE* :ref:`overview-stages-check-stage`. + +Unsupported linters +=================== + +Here is a list of C++ linters that haven't been integrated yet. + +**ClangBuildAnalyzer** + Link: https://github.com/aras-p/ClangBuildAnalyzer + + Clang build analysis tool using ``-ftime-trace``. + +**Clang-Include-Fixer** + Link: https://clang.llvm.org/extra/clang-include-fixer.html + + One of the major nuisances of C++ compared to other languages is the manual management of ``#include`` directives in any file. + ``clang-include-fixer`` addresses one aspect of this problem by providing an automated way of adding ``#include`` directives for missing symbols in one translation unit. + +**Clang Static Analyzer** + Link: https://clang-analyzer.llvm.org/ + + The Clang Static Analyzer is a source code analysis tool that finds bugs in C, C++, and Objective-C programs. + +**CodeChecker** + Link: https://github.com/Ericsson/codechecker + + CodeChecker is an analyzer tooling, defect database and viewer extension for the Clang Static Analyzer and Clang-Tidy. + +**flawfinder** + Link: https://github.com/david-a-wheeler/flawfinder + + A static analysis tool for finding vulnerabilities in C/C++ source code. + +**ikos** + Link: https://github.com/NASA-SW-VnV/ikos + + Static analyzer for C/C++ based on the theory of Abstract Interpretation. + +**Infer** + Links: https://github.com/facebook/infer + + A static analyzer for Java, C, C++, and Objective-C. + +**Klocwork** + Link: https://www.perforce.com/products/klocwork + + Klocwork static code analysis and SAST tool for C, C++, C#, Java, JavaScript, Python, and Kotlin identifies software security, quality, and reliability issues helping to enforce compliance with standards. + +**krazy** + Link: https://github.com/Krazy-collection/krazy + + An extensible framework for performing static code checking on files of any format. + +**OCLint** + Link: https://github.com/oclint/oclint + + A static source code analysis tool to improve quality and reduce defects for C, C++ and Objective-C. + +**stack** + Link: https://css.csail.mit.edu/stack + + An analyzer that tries to report code that might be removed by an optimizer. diff --git a/docs/pipelines/lang/python/index.rst b/docs/pipelines/lang/python/index.rst index 25bff45..1b3669c 100644 --- a/docs/pipelines/lang/python/index.rst +++ b/docs/pipelines/lang/python/index.rst @@ -18,3 +18,16 @@ This is a "sub-pipeline" for building, testing and linting new changes that have :doc:`linters` A document which covers all CI jobs responsible for linting python code. + +Usage +===== + +In order to use this "sub-pipeline", you need to add the following code to your `.gitlab-ci.yml`: + +.. code-block:: yaml + + include: + - project: 'bproto/cicd' + ref: main + file: + - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/python/linters.rst b/docs/pipelines/lang/python/linters.rst index fadf173..222b8d7 100644 --- a/docs/pipelines/lang/python/linters.rst +++ b/docs/pipelines/lang/python/linters.rst @@ -117,16 +117,3 @@ Different configuration options can be found on `official page ` is changed. - -Usage -===== - -In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: - -.. code-block:: yaml - - include: - - project: 'bproto/cicd' - ref: main - file: - - '/.gitlab/ci/external/lite.yml' diff --git a/docs/pipelines/lang/shell.rst b/docs/pipelines/lang/shell.rst index 8d8d16f..9668307 100644 --- a/docs/pipelines/lang/shell.rst +++ b/docs/pipelines/lang/shell.rst @@ -102,7 +102,7 @@ This job executes `shellcheck `__ *only Usage ===== -In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: +In order to use above CI jobs, you need to add the following code to your `.gitlab-ci.yml`: .. code-block:: yaml diff --git a/docs/pipelines/lang/yaml.rst b/docs/pipelines/lang/yaml.rst index 174009e..5b4c4aa 100644 --- a/docs/pipelines/lang/yaml.rst +++ b/docs/pipelines/lang/yaml.rst @@ -62,7 +62,7 @@ This job executes `yamllint `__ *only o Usage ===== -In order to use above CI jobs, you need to add the follow code to your `.gitlab-ci.yml`: +In order to use above CI jobs, you need to add the following code to your `.gitlab-ci.yml`: .. code-block:: yaml diff --git a/docs/pipelines/packages/conan.rst b/docs/pipelines/packages/conan.rst index 775f67c..2dbd51d 100644 --- a/docs/pipelines/packages/conan.rst +++ b/docs/pipelines/packages/conan.rst @@ -1,3 +1,5 @@ +.. _pipelines-packages-conan: + ===== Conan ===== diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 3dfda3a..0000000 --- a/docs/usage.rst +++ /dev/null @@ -1,22 +0,0 @@ -===== -Usage -===== - -This project can be used mainly be used in two completely distinct ways: - -- as a `CI/CD template `__, -- and as a `fork `__. - -This page will try to cover in-deep those two ways. - -GitLab templates -================ - -Available templates -^^^^^^^^^^^^^^^^^^^ - -Limitations -^^^^^^^^^^^ - -Forks -===== diff --git a/docs/variables.rst b/docs/variables.rst index 6ce6482..d35ff28 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -22,7 +22,7 @@ Local CI/CD variables .. _variables-bproto-ci-conan-package-name: **BPROTO_CI_CONAN_PACKAGE_NAME**:STRING - A name of a conan package which will be used when deploying to the `artifacts `__ package registry. + A name of a conan package which will be used when deploying to the :ref:`artifacts ` package registry. **BPROTO_CI_LINTER_TRACE**:STRING Enable debug logging to help troubleshoot problems with linter jobs. @@ -52,10 +52,10 @@ Global CI/CD variables ====================== **BPROTO_CI_CONAN_PACKAGES_REGISTRY**:URL - A link to an `artifacts`_'s `conan packages `__ `registry `__. + A link to an :ref:`artifacts `'s `conan packages `__ `registry `__. **BPROTO_CI_DEPLOY_TOKEN**:STRING - A `deploy token `__ for `artifacts`_'s `packages and registries `__. + A `deploy token `__ for :ref:`artifacts `'s `packages and registries `__. **Scopes:** ``read_registry``, ``write_registry``, ``read_package_registry``, ``write_package_registry``. @@ -63,10 +63,10 @@ Global CI/CD variables A user for ``BPROTO_CI_DEPLOY_TOKEN``. **BPROTO_CI_GENERIC_PACKAGES_REGISTRY**:URL - A link to an `artifacts`_'s `generic packages repository `__. + A link to an :ref:`artifacts `'s `generic packages repository `__. **BPROTO_CI_IMAGES_REGISTRY**:URL - A link to an `artifacts`_'s `container registry `__. + A link to an :ref:`artifacts `'s `container registry `__. **BPROTO_CI_PRIVATE_API_TOKEN**:STRING A `private token `__ of ``BPROTO_CI_USER`` with read-write access rights for API calls. @@ -76,8 +76,6 @@ Global CI/CD variables **BPROTO_CI_USER**:STRING An artificial user with maintainer rights. -.. _artifacts: https://gitlab.com/bproto/artifacts - GitLab group-level variables ---------------------------- diff --git a/requirements.txt b/requirements.txt index cd4307e..a88da66 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,14 +12,10 @@ exhale==0.2.4 furo==2022.9.29 sphinx==4.5.0 +sphinx-copybutton sphinx-design -sphinx-jsonschema sphinx-prompt==1.5.0 # >=1.6.0 requires Sphinx<7.0.0,>=6.0.0 -# See https://github.com/sphinx-contrib/openapi/issues/122 -mistune==0.8.4 -sphinxcontrib-openapi==0.7.0 - # Linters black # python -- GitLab From 113563005e0695936186441e1014439760b21bcc Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 6 Nov 2023 01:18:21 +0200 Subject: [PATCH 13/44] Fix links for external YAML files in repo Tags: Docs --- docs/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 6ca3949..fab75fa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,11 +44,11 @@ CI/CD templates This project provides a bunch of useful `GitLab CI/CD pipelines `__ for different programming languages and frameworks. Below is a nice list of all available pipelines: -.. _conan-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/conan.yml -.. _cpp-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/cpp.yml -.. _hugo-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/hugo.yml -.. _lite-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/conan.yml -.. _sphinx-tmpl: https://gitlab.com/bproto/cicd/.gitlab/ci/external/sphinx.yml +.. _conan-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/conan.yml +.. _cpp-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/cpp.yml +.. _hugo-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/hugo.yml +.. _lite-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/conan.yml +.. _sphinx-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/sphinx.yml - **Documentation** - Hugo (`.gitlab/ci/external/hugo.yml `__) -- GitLab From d6a556997f02bedab46aa6a1f72d496a135414b9 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 6 Nov 2023 23:53:08 +0200 Subject: [PATCH 14/44] Redesign C++ pipeline This is a big redesign of current C++ pipeline which tries to solve some particular problems with maintenance. Now we have only one image that contains all packages that we need to run generic jobs for building and running tests, as well as to run some specific jobs (linters in this case). Also now only one image has both GCC and Clang compilers. Other images now have only GCC because it's easier to get a new version of it comparing to Clang. In addition to that I finally dropped support of CentOS 8 because it's dead and pretty useless system as of now. Below is a brief list of all changes. - Drop support of CentOS 8. - Remove Clang from CentOS 7, CentOS 8 and Ubuntu 20.04 and leave only core packages. - Support Ubuntu 23.04 which is now same as Ubuntu 20.04 in terms of packages and usage. - Remove clang jobs for CentOS 7, CentOS 8 and Ubuntu 20.04. - Add new jobs for Ubuntu 23.04 to cover GCC, Clang and all sanitizers. Tags: CI, Conan, Cpp, Dockers, Docs, Linters --- .gitlab/ci/external/cpp.yml | 13 +- .gitlab/ci/images/ubuntu2304.yml | 51 ++++++ .gitlab/ci/index.yml | 13 +- .gitlab/ci/lang/cpp/base.yml | 151 +++--------------- .gitlab/ci/lang/cpp/build/base.yml | 139 ++++++++++++++++ .../{centos_gcc.yml => build/centos7_gcc.yml} | 28 +--- .../centos8_gcc.yml} | 42 ++--- .gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml | 43 +++++ .../ubuntu2304_clang.yml} | 18 +-- .../ubuntu2304_gcc.yml} | 41 ++++- .gitlab/ci/lang/cpp/{ => build}/windows.yml | 20 +-- .gitlab/ci/lang/cpp/lint/clang_tools.yml | 2 +- .gitlab/ci/lang/cpp/lint/coverage.yml | 2 +- .gitlab/ci/lang/cpp/lint/cppcheck.yml | 2 +- docker/Conan.Dockerfile | 8 +- docker/Ubuntu2304.Dockerfile | 56 +++++++ docs/git/tags.rst | 2 + docs/images/d/conan.rst | 22 ++- docs/images/g/alpine3.rst | 20 ++- docs/images/g/centos7.rst | 22 +-- docs/images/g/centos8.rst | 22 +-- docs/images/g/index.rst | 4 +- docs/images/g/ubuntu2004.rst | 34 +--- docs/images/g/ubuntu2304.rst | 80 ++++++++++ docs/pipelines/lang/cpp/build.rst | 106 ++++++------ docs/pipelines/lang/cpp/linters.rst | 8 +- docs/pipelines/lang/docker/build.rst | 4 + scripts/conan/fetch.sh | 7 + scripts/os/setup_centos7.sh | 24 ++- scripts/os/setup_centos8.sh | 10 +- scripts/os/setup_conan.sh | 34 ++-- scripts/os/setup_ubuntu2004.sh | 60 +++---- scripts/os/setup_ubuntu2304.sh | 109 +++++++++++++ 33 files changed, 765 insertions(+), 432 deletions(-) create mode 100644 .gitlab/ci/images/ubuntu2304.yml create mode 100644 .gitlab/ci/lang/cpp/build/base.yml rename .gitlab/ci/lang/cpp/{centos_gcc.yml => build/centos7_gcc.yml} (62%) rename .gitlab/ci/lang/cpp/{centos_clang.yml => build/centos8_gcc.yml} (54%) create mode 100644 .gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml rename .gitlab/ci/lang/cpp/{ubuntu_clang.yml => build/ubuntu2304_clang.yml} (72%) rename .gitlab/ci/lang/cpp/{ubuntu_gcc.yml => build/ubuntu2304_gcc.yml} (60%) rename .gitlab/ci/lang/cpp/{ => build}/windows.yml (85%) create mode 100644 docker/Ubuntu2304.Dockerfile create mode 100644 docs/images/g/ubuntu2304.rst create mode 100644 scripts/os/setup_ubuntu2304.sh diff --git a/.gitlab/ci/external/cpp.yml b/.gitlab/ci/external/cpp.yml index fd5a82a..e8c6820 100644 --- a/.gitlab/ci/external/cpp.yml +++ b/.gitlab/ci/external/cpp.yml @@ -17,14 +17,15 @@ include: ref: main file: - '/.gitlab/ci/external/lite.yml' - # C++ files: - '/.gitlab/ci/lang/cpp/base.yml' + - '/.gitlab/ci/lang/cpp/build/base.yml' + - '/.gitlab/ci/lang/cpp/build/centos7_gcc.yml' + - '/.gitlab/ci/lang/cpp/build/centos8_gcc.yml' # discontinued + - '/.gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml' + - '/.gitlab/ci/lang/cpp/build/ubuntu2304_clang.yml' + - '/.gitlab/ci/lang/cpp/build/ubuntu2304_gcc.yml' + - '/.gitlab/ci/lang/cpp/build/windows.yml' - '/.gitlab/ci/lang/cpp/lint/clang_tools.yml' - '/.gitlab/ci/lang/cpp/lint/coverage.yml' - '/.gitlab/ci/lang/cpp/lint/cppcheck.yml' - '/.gitlab/ci/lang/cpp/lint/guardonce.yml' - - '/.gitlab/ci/lang/cpp/centos_clang.yml' - - '/.gitlab/ci/lang/cpp/centos_gcc.yml' - - '/.gitlab/ci/lang/cpp/ubuntu_clang.yml' - - '/.gitlab/ci/lang/cpp/ubuntu_gcc.yml' - - '/.gitlab/ci/lang/cpp/windows.yml' diff --git a/.gitlab/ci/images/ubuntu2304.yml b/.gitlab/ci/images/ubuntu2304.yml new file mode 100644 index 0000000..f088a92 --- /dev/null +++ b/.gitlab/ci/images/ubuntu2304.yml @@ -0,0 +1,51 @@ +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +.ubuntu2304_changes: &ubuntu2304_changes + - conan/profiles/linux_* + - conan/conanfile.txt + - docker/Ubuntu2304.Dockerfile + - scripts/conan/* + - scripts/os/install_files.sh + - scripts/os/setup_ubuntu2304.sh + - requirements.txt + +.ubuntu2304_variables: &ubuntu2304_variables + DOCKER_IMAGE_NAME: "ubuntu2304:latest" + DOCKER_IMAGE_OS: "Ubuntu2304" + +build:docker:ubuntu2304: + stage: build + extends: .docker + variables: + <<: *ubuntu2304_variables + rules: + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + changes: + *ubuntu2304_changes + +deploy:docker:ubuntu2304: + stage: deploy + extends: .docker + variables: + <<: *ubuntu2304_variables + rules: + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: never + - if: '$CI_PIPELINE_SOURCE == "web"' + when: manual + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + changes: + *ubuntu2304_changes + - !reference [.trigger-docker-on-linters-files-change, rules] diff --git a/.gitlab/ci/index.yml b/.gitlab/ci/index.yml index f5ebadf..c6da9ec 100644 --- a/.gitlab/ci/index.yml +++ b/.gitlab/ci/index.yml @@ -24,21 +24,24 @@ include: - local: '/.gitlab/ci/images/conan.yml' - local: '/.gitlab/ci/images/hadolint.yml' - local: '/.gitlab/ci/images/ubuntu2004.yml' + - local: '/.gitlab/ci/images/ubuntu2304.yml' - local: '/.gitlab/ci/lang/cmake/base.yml' - local: '/.gitlab/ci/lang/cmake/lint/cmakelang.yml' # - local: '/.gitlab/ci/lang/common/lint/codequality.yml' - local: '/.gitlab/ci/lang/common/lint/codespell.yml' - local: '/.gitlab/ci/lang/common/lint/license_headers.yml' - local: '/.gitlab/ci/lang/cpp/base.yml' + - local: '/.gitlab/ci/lang/cpp/build/base.yml' + - local: '/.gitlab/ci/lang/cpp/build/centos7_gcc.yml' + - local: '/.gitlab/ci/lang/cpp/build/centos8_gcc.yml' + - local: '/.gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml' + - local: '/.gitlab/ci/lang/cpp/build/ubuntu2304_clang.yml' + - local: '/.gitlab/ci/lang/cpp/build/ubuntu2304_gcc.yml' + - local: '/.gitlab/ci/lang/cpp/build/windows.yml' - local: '/.gitlab/ci/lang/cpp/lint/clang_tools.yml' - local: '/.gitlab/ci/lang/cpp/lint/coverage.yml' - local: '/.gitlab/ci/lang/cpp/lint/cppcheck.yml' - local: '/.gitlab/ci/lang/cpp/lint/guardonce.yml' - - local: '/.gitlab/ci/lang/cpp/centos_clang.yml' - - local: '/.gitlab/ci/lang/cpp/centos_gcc.yml' - - local: '/.gitlab/ci/lang/cpp/ubuntu_clang.yml' - - local: '/.gitlab/ci/lang/cpp/ubuntu_gcc.yml' - - local: '/.gitlab/ci/lang/cpp/windows.yml' - local: '/.gitlab/ci/lang/docker/lint/hadolint.yml' - local: '/.gitlab/ci/lang/py/base.yml' - local: '/.gitlab/ci/lang/py/lint/black.yml' diff --git a/.gitlab/ci/lang/cpp/base.yml b/.gitlab/ci/lang/cpp/base.yml index 7c57f4b..bfc58c0 100644 --- a/.gitlab/ci/lang/cpp/base.yml +++ b/.gitlab/ci/lang/cpp/base.yml @@ -23,6 +23,25 @@ - "**/*.hpp" - "**/*.ipp" +.only-review-cpp-manual: + only: + rules: + - if: '$CI_PROJECT_NAME == "cicd"' + when: never + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: never + - if: '$CI_PIPELINE_SOURCE == "web"' + when: manual + - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + changes: + - "**/CMakeLists.txt" + - "**/*.cmake" + - "**/*.cpp" + - "**/*.hpp" + - "**/*.ipp" + when: manual + allow_failure: true + .only-review-hpp: only: refs: @@ -30,135 +49,3 @@ changes: - "**/*.hpp" - "**/*.ipp" - -# Build - -.build-cpp: - stage: build - extends: .only-review-cpp - interruptible: false - variables: - # Use prefixed CMake options to avoid UB while executing 'conan install'. - BPROTO_CI_CMAKE_BUILD_TYPE: "Debug" - # This can be defined global wide. - CMAKE_GENERATOR: Unix Makefiles - before_script: - # nproc on GNU/Linux, sysctl on macOS - - NPROC=$(nproc || sysctl -n hw.physicalcpu) 2>/dev/null - # Download all Conan packages - - |- - if [[ -f "${CI_PROJECT_DIR}/conanfile.py" || -f "${CI_PROJECT_DIR}/conanfile.txt" ]]; then - conan install . -if build -of build --build=missing \ - -pr:b "${CC}" \ - -pr:h "${CC}" \ - -s:b build_type="${BPROTO_CI_CMAKE_BUILD_TYPE}" \ - -s:h build_type="${BPROTO_CI_CMAKE_BUILD_TYPE}" - - # Conan will generate this for us. - export BPROTO_CI_CMAKE_TOOLCHAIN_FILE="-DCMAKE_TOOLCHAIN_FILE='conan_toolchain.cmake'" - fi - - export BPROTO_CI_CMAKE_BUILD_TYPE="-DCMAKE_BUILD_TYPE=${BPROTO_CI_CMAKE_BUILD_TYPE}" - - |- - echo -e "BPROTO_CI_CMAKE_BUILD_TYPE:\n\t${BPROTO_CI_CMAKE_BUILD_TYPE}" - echo -e "BPROTO_CI_CMAKE_ARGS:\n\t${BPROTO_CI_CMAKE_ARGS}" - echo -e "BPROTO_CI_CMAKE_EXTRA_ARGS:\n\t${BPROTO_CI_CMAKE_EXTRA_ARGS}" - echo -e "BPROTO_CI_CMAKE_TOOLCHAIN_FILE:\n\t${BPROTO_CI_CMAKE_TOOLCHAIN_FILE}" - script: - - mkdir -p build - - |- - cmake -S. -Bbuild \ - ${BPROTO_CI_CMAKE_BUILD_TYPE} \ - ${BPROTO_CI_CMAKE_ARGS} \ - ${BPROTO_CI_CMAKE_EXTRA_ARGS} \ - ${BPROTO_CI_CMAKE_TOOLCHAIN_FILE} \ - 2>&1 | tee build/ConfigurationLog.txt - - cmake --build build -j${NPROC} 2>&1 | tee build/CompilationLog.txt - artifacts: - expire_in: 2 hrs - when: always - paths: - # Different logs are needed if something happens. - - build/CMakeFiles/CMakeError.log - - build/CMakeFiles/CMakeOutput.log - - build/ConfigurationLog.txt - - build/CompilationLog.txt - - # The main binaries. - - build/bin/ - - # The cache is needed for the installation test. - - build/CMakeCache.txt - - # CTest files are needed for the installation test. - - build/CTestTestfile.cmake - - build/**/CTestTestfile.cmake - - # Dart files are needed for the tests with valgrind. - - build/DartConfiguration.tcl - - # Test stage doesn't checkout repo and use only artifacts. - # So include test configs to an artifact too. - - tools/* - -# Test - -.test-cpp: - stage: test - extends: .only-review-cpp - when: on_success - variables: - # Boost settings - BOOST_TEST_LOGGER: "JUNIT,all,test_results.xml:HRF,warning" - # CTest settings - CTEST_OUTPUT_ON_FAILURE: 1 - # GIT settings - GIT_CHECKOUT: "false" - GIT_STRATEGY: none - # Sanitizers settings - ASAN_OPTIONS: "log_threads=1:verbosity=1" - LSAN_OPTIONS: "log_threads=1:verbosity=1" - TSAN_OPTIONS: "log_threads=1:verbosity=1" - before_script: - # nproc on GNU/Linux, sysctl on macOS - - NPROC=$(nproc || sysctl -n hw.physicalcpu) 2>/dev/null - - |- - asan_supp_file="${CI_PROJECT_DIR}/tools/asan.supp" - if [[ -f "${asan_supp_file}" ]]; then - export ASAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${asan_supp_file}" - fi - - |- - lsan_supp_file="${CI_PROJECT_DIR}/tools/lsan.supp" - if [[ -f "${lsan_supp_file}" ]]; then - export LSAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${lsan_supp_file}" - fi - - |- - tsan_supp_file="${CI_PROJECT_DIR}/tools/tsan.supp" - if [[ -f "${tsan_supp_file}" ]]; then - export TSAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${tsan_supp_file}" - fi - script: - - ctest -j${NPROC} --test-dir build - artifacts: - reports: - junit: - - build/**/test_results.xml - -# Report - -# If build job failed, upload compilation logs in an easily downloadable form. -.report-build-cpp: - extends: - - .only-review-cpp - - .report - script: - - cp /build/CMakeFiles/CMakeError.log . - - cp /build/CMakeFiles/CMakeOutput.log . - artifacts: - expire_in: 1 day - expose_as: 'Build log' - name: "BuildLog-$CI_COMMIT_REF_SLUG" - paths: - - CMakeError.log - - CMakeOutput.log - - ConfigurationLog.txt - - CompilationLog.txt diff --git a/.gitlab/ci/lang/cpp/build/base.yml b/.gitlab/ci/lang/cpp/build/base.yml new file mode 100644 index 0000000..1bb3064 --- /dev/null +++ b/.gitlab/ci/lang/cpp/build/base.yml @@ -0,0 +1,139 @@ +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +.build-cpp: + stage: build + extends: .only-review-cpp + interruptible: false + variables: + # Use prefixed CMake options to avoid UB while executing 'conan install'. + BPROTO_CI_CMAKE_BUILD_TYPE: "Debug" + # This can be defined global wide. + CMAKE_GENERATOR: Unix Makefiles + before_script: + # nproc on GNU/Linux, sysctl on macOS + - NPROC=$(nproc || sysctl -n hw.physicalcpu) 2>/dev/null + # Download all Conan packages + - |- + if [[ -f "${CI_PROJECT_DIR}/conanfile.py" || -f "${CI_PROJECT_DIR}/conanfile.txt" ]]; then + conan install . -if build -of build --build=missing \ + -pr:b "${CC}" \ + -pr:h "${CC}" \ + -s:b build_type="${BPROTO_CI_CMAKE_BUILD_TYPE}" \ + -s:h build_type="${BPROTO_CI_CMAKE_BUILD_TYPE}" + + # Conan will generate this for us. + export BPROTO_CI_CMAKE_TOOLCHAIN_FILE="-DCMAKE_TOOLCHAIN_FILE='conan_toolchain.cmake'" + fi + - export BPROTO_CI_CMAKE_BUILD_TYPE="-DCMAKE_BUILD_TYPE=${BPROTO_CI_CMAKE_BUILD_TYPE}" + - |- + echo -e "BPROTO_CI_CMAKE_BUILD_TYPE:\n\t${BPROTO_CI_CMAKE_BUILD_TYPE}" + echo -e "BPROTO_CI_CMAKE_ARGS:\n\t${BPROTO_CI_CMAKE_ARGS}" + echo -e "BPROTO_CI_CMAKE_EXTRA_ARGS:\n\t${BPROTO_CI_CMAKE_EXTRA_ARGS}" + echo -e "BPROTO_CI_CMAKE_TOOLCHAIN_FILE:\n\t${BPROTO_CI_CMAKE_TOOLCHAIN_FILE}" + script: + - mkdir -p build + - |- + cmake -S. -Bbuild \ + ${BPROTO_CI_CMAKE_BUILD_TYPE} \ + ${BPROTO_CI_CMAKE_ARGS} \ + ${BPROTO_CI_CMAKE_EXTRA_ARGS} \ + ${BPROTO_CI_CMAKE_TOOLCHAIN_FILE} \ + 2>&1 | tee build/ConfigurationLog.txt + - cmake --build build -j${NPROC} 2>&1 | tee build/CompilationLog.txt + artifacts: + expire_in: 2 hrs + when: always + paths: + # Different logs are needed if something happens. + - build/CMakeFiles/CMakeError.log + - build/CMakeFiles/CMakeOutput.log + - build/ConfigurationLog.txt + - build/CompilationLog.txt + + # The main binaries. + - build/bin/ + + # The cache is needed for the installation test. + - build/CMakeCache.txt + + # CTest files are needed for the installation test. + - build/CTestTestfile.cmake + - build/**/CTestTestfile.cmake + + # Dart files are needed for the tests with valgrind. + - build/DartConfiguration.tcl + + # Test stage doesn't checkout repo and use only artifacts. + # So include test configs to an artifact too. + - tools/* + +.test-cpp: + stage: test + extends: .only-review-cpp + when: on_success + variables: + # Boost settings + BOOST_TEST_LOGGER: "JUNIT,all,test_results.xml:HRF,warning" + # CTest settings + CTEST_OUTPUT_ON_FAILURE: 1 + # GIT settings + GIT_CHECKOUT: "false" + GIT_STRATEGY: none + # Sanitizers settings + ASAN_OPTIONS: "log_threads=1:verbosity=1" + LSAN_OPTIONS: "log_threads=1:verbosity=1" + TSAN_OPTIONS: "log_threads=1:verbosity=1" + before_script: + # nproc on GNU/Linux, sysctl on macOS + - NPROC=$(nproc || sysctl -n hw.physicalcpu) 2>/dev/null + - |- + asan_supp_file="${CI_PROJECT_DIR}/tools/asan.supp" + if [[ -f "${asan_supp_file}" ]]; then + export ASAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${asan_supp_file}" + fi + - |- + lsan_supp_file="${CI_PROJECT_DIR}/tools/lsan.supp" + if [[ -f "${lsan_supp_file}" ]]; then + export LSAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${lsan_supp_file}" + fi + - |- + tsan_supp_file="${CI_PROJECT_DIR}/tools/tsan.supp" + if [[ -f "${tsan_supp_file}" ]]; then + export TSAN_OPTIONS="${ASAN_OPTIONS}:suppressions=${tsan_supp_file}" + fi + script: + - ctest -j${NPROC} --test-dir build + artifacts: + reports: + junit: + - build/**/test_results.xml + +# If build job failed, upload compilation logs in an easily downloadable form. +.report-build-cpp: + extends: + - .only-review-cpp + - .report + script: + - cp /build/CMakeFiles/CMakeError.log . + - cp /build/CMakeFiles/CMakeOutput.log . + artifacts: + expire_in: 1 day + expose_as: 'Build log' + name: "BuildLog-$CI_COMMIT_REF_SLUG" + paths: + - CMakeError.log + - CMakeOutput.log + - ConfigurationLog.txt + - CompilationLog.txt diff --git a/.gitlab/ci/lang/cpp/centos_gcc.yml b/.gitlab/ci/lang/cpp/build/centos7_gcc.yml similarity index 62% rename from .gitlab/ci/lang/cpp/centos_gcc.yml rename to .gitlab/ci/lang/cpp/build/centos7_gcc.yml index bf22af8..00f5f29 100644 --- a/.gitlab/ci/lang/cpp/centos_gcc.yml +++ b/.gitlab/ci/lang/cpp/build/centos7_gcc.yml @@ -19,20 +19,7 @@ build:cpp:centos7:gcc: extends: .build-cpp variables: BPROTO_CI_CMAKE_BUILD_TYPE: "Release" - BPROTO_CI_CMAKE_ARGS: >- - -DCMOPTS_ENABLE_LTO=ON - CC: gcc - CXX: g++ - -build:cpp:centos8:gcc: - image: $BPROTO_CI_IMAGES_REGISTRY/centos8:latest - extends: .build-cpp - variables: - BPROTO_CI_CMAKE_ARGS: >- - -DCMOPTS_ENABLE_LTO=OFF - -DCMOPTS_ENABLE_SANITIZER_ADDRESS=ON - -DCMOPTS_ENABLE_SANITIZER_LEAK=ON - -DCMOPTS_ENABLE_SANITIZER_UNDEFINED_BEHAVIOR=ON + BPROTO_CI_CMAKE_ARGS: "-DCMOPTS_ENABLE_LTO=ON" CC: gcc CXX: g++ @@ -45,13 +32,6 @@ test:cpp:centos7:gcc: - job: build:cpp:centos7:gcc artifacts: true -test:cpp:centos8:gcc: - image: $BPROTO_CI_IMAGES_REGISTRY/centos8:latest - extends: .test-cpp - needs: - - job: build:cpp:centos8:gcc - artifacts: true - # Report report:cpp:centos7:gcc: @@ -59,9 +39,3 @@ report:cpp:centos7:gcc: needs: - job: build:cpp:centos7:gcc artifacts: true - -report:cpp:centos8:gcc: - extends: .report-build-cpp - needs: - - job: build:cpp:centos8:gcc - artifacts: true diff --git a/.gitlab/ci/lang/cpp/centos_clang.yml b/.gitlab/ci/lang/cpp/build/centos8_gcc.yml similarity index 54% rename from .gitlab/ci/lang/cpp/centos_clang.yml rename to .gitlab/ci/lang/cpp/build/centos8_gcc.yml index da370e2..27cea99 100644 --- a/.gitlab/ci/lang/cpp/centos_clang.yml +++ b/.gitlab/ci/lang/cpp/build/centos8_gcc.yml @@ -14,48 +14,30 @@ # Build -build:cpp:centos7:clang: - image: $BPROTO_CI_IMAGES_REGISTRY/centos7:latest - extends: .build-cpp - variables: - BPROTO_CI_CMAKE_ARGS: "-DCMOPTS_ENABLE_LTO=OFF" - CC: clang - CXX: clang++ - -build:cpp:centos8:clang: +build:cpp:centos8:gcc: image: $BPROTO_CI_IMAGES_REGISTRY/centos8:latest - extends: .build-cpp + extends: + - .build-cpp + - .only-review-cpp-manual variables: - BPROTO_CI_CMAKE_ARGS: -DCMOPTS_ENABLE_LTO=OFF" - CC: clang - CXX: clang++ + BPROTO_CI_CMAKE_BUILD_TYPE: "Release" + BPROTO_CI_CMAKE_ARGS: "-DCMOPTS_ENABLE_LTO=ON" + CC: gcc + CXX: g++ # Test -test:cpp:centos7:clang: - image: $BPROTO_CI_IMAGES_REGISTRY/centos7:latest - extends: .test-cpp - needs: - - job: build:cpp:centos7:clang - artifacts: true - -test:cpp:centos8:clang: +test:cpp:centos8:gcc: image: $BPROTO_CI_IMAGES_REGISTRY/centos8:latest extends: .test-cpp needs: - - job: build:cpp:centos8:clang + - job: build:cpp:centos8:gcc artifacts: true # Report -report:cpp:centos7:clang: - extends: .report-build-cpp - needs: - - job: build:cpp:centos7:clang - artifacts: true - -report:cpp:centos8:clang: +report:cpp:centos8:gcc: extends: .report-build-cpp needs: - - job: build:cpp:centos8:clang + - job: build:cpp:centos8:gcc artifacts: true diff --git a/.gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml b/.gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml new file mode 100644 index 0000000..d454f6c --- /dev/null +++ b/.gitlab/ci/lang/cpp/build/ubuntu2004_gcc.yml @@ -0,0 +1,43 @@ +# Copyright 2020-2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Build + +build:cpp:ubuntu2004:gcc: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest + extends: + - .build-cpp + - .only-review-cpp-manual + variables: + BPROTO_CI_CMAKE_BUILD_TYPE: "Release" + BPROTO_CI_CMAKE_ARGS: "-DCMOPTS_ENABLE_LTO=ON" + CC: gcc + CXX: g++ + +# Test + +test:cpp:ubuntu2004:gcc: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest + extends: .test-cpp + needs: + - job: build:cpp:ubuntu2004:gcc + artifacts: true + +# Report + +report:cpp:ubuntu2004:gcc: + extends: .report-build-cpp + needs: + - job: build:cpp:ubuntu2004:gcc + artifacts: true diff --git a/.gitlab/ci/lang/cpp/ubuntu_clang.yml b/.gitlab/ci/lang/cpp/build/ubuntu2304_clang.yml similarity index 72% rename from .gitlab/ci/lang/cpp/ubuntu_clang.yml rename to .gitlab/ci/lang/cpp/build/ubuntu2304_clang.yml index b02c722..1a8bb36 100644 --- a/.gitlab/ci/lang/cpp/ubuntu_clang.yml +++ b/.gitlab/ci/lang/cpp/build/ubuntu2304_clang.yml @@ -1,4 +1,4 @@ -# Copyright 2020-2023 Zinchenko Serhii . +# Copyright 2023 Zinchenko Serhii . # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -14,30 +14,30 @@ # Build -build:cpp:ubuntu2004:clang: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest +build:cpp:ubuntu2304:clang: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest extends: .build-cpp variables: BPROTO_CI_CMAKE_ARGS: >- - -DCPPDOC_ENABLE=ON -DCMOPTS_ENABLE_LTO=OFF -DCMOPTS_ENABLE_SANITIZER_THREAD=ON + -DCPPDOC_ENABLE=ON CC: clang CXX: clang++ # Test -test:cpp:ubuntu2004:clang: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest +test:cpp:ubuntu2304:clang: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest extends: .test-cpp needs: - - job: build:cpp:ubuntu2004:clang + - job: build:cpp:ubuntu2304:clang artifacts: true # Report -report:cpp:ubuntu2004:clang: +report:cpp:ubuntu2304:clang: extends: .report-build-cpp needs: - - job: build:cpp:ubuntu2004:clang + - job: build:cpp:ubuntu2304:clang artifacts: true diff --git a/.gitlab/ci/lang/cpp/ubuntu_gcc.yml b/.gitlab/ci/lang/cpp/build/ubuntu2304_gcc.yml similarity index 60% rename from .gitlab/ci/lang/cpp/ubuntu_gcc.yml rename to .gitlab/ci/lang/cpp/build/ubuntu2304_gcc.yml index e8933aa..458c95f 100644 --- a/.gitlab/ci/lang/cpp/ubuntu_gcc.yml +++ b/.gitlab/ci/lang/cpp/build/ubuntu2304_gcc.yml @@ -1,4 +1,4 @@ -# Copyright 2020-2023 Zinchenko Serhii . +# Copyright 2023 Zinchenko Serhii . # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -14,8 +14,20 @@ # Build -build:cpp:ubuntu2004:gcc: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest +build:cpp:ubuntu2304:gcc:1: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest + extends: .build-cpp + variables: + BPROTO_CI_CMAKE_ARGS: >- + -DCMOPTS_ENABLE_LTO=OFF + -DCMOPTS_ENABLE_SANITIZER_ADDRESS=ON + -DCMOPTS_ENABLE_SANITIZER_LEAK=ON + -DCMOPTS_ENABLE_SANITIZER_UNDEFINED_BEHAVIOR=ON + CC: gcc + CXX: g++ + +build:cpp:ubuntu2304:gcc:2: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest extends: .build-cpp variables: BPROTO_CI_CMAKE_ARGS: >- @@ -26,11 +38,18 @@ build:cpp:ubuntu2004:gcc: # Test -test:cpp:ubuntu2004:gcc: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest +test:cpp:ubuntu2304:gcc:1: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest + extends: .test-cpp + needs: + - job: build:cpp:ubuntu2304:gcc:1 + artifacts: true + +test:cpp:ubuntu2304:gcc:2: + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest extends: .test-cpp needs: - - job: build:cpp:ubuntu2004:gcc + - job: build:cpp:ubuntu2304:gcc:2 artifacts: true script: - cd build @@ -56,8 +75,14 @@ test:cpp:ubuntu2004:gcc: # Report -report:cpp:ubuntu2004:gcc: +report:cpp:ubuntu2304:gcc:1: + extends: .report-build-cpp + needs: + - job: build:cpp:ubuntu2304:gcc:1 + artifacts: true + +report:cpp:ubuntu2304:gcc:2: extends: .report-build-cpp needs: - - job: build:cpp:ubuntu2004:gcc + - job: build:cpp:ubuntu2304:gcc:2 artifacts: true diff --git a/.gitlab/ci/lang/cpp/windows.yml b/.gitlab/ci/lang/cpp/build/windows.yml similarity index 85% rename from .gitlab/ci/lang/cpp/windows.yml rename to .gitlab/ci/lang/cpp/build/windows.yml index e31556a..d556543 100644 --- a/.gitlab/ci/lang/cpp/windows.yml +++ b/.gitlab/ci/lang/cpp/build/windows.yml @@ -32,7 +32,9 @@ build:cpp:windows: stage: build - extends: .windows-cpp-tags + extends: + - .only-review-cpp-manual + - .windows-cpp-tags variables: CACHE_DIR: "$CI_PROJECT_DIR\\.cache" # Setup package managers @@ -60,22 +62,6 @@ build:cpp:windows: cmake --build build -j"$env:NUMBER_OF_PROCESSORS" 2>&1 ` | % ToString | Tee-Object build/CompilationLog.txt } - rules: - - if: '$CI_PROJECT_NAME == "cicd"' - when: never - - if: '$CI_PIPELINE_SOURCE == "schedule"' - when: never - - if: '$CI_PIPELINE_SOURCE == "web"' - when: manual - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - changes: - - "**/CMakeLists.txt" - - "**/*.cmake" - - "**/*.cpp" - - "**/*.hpp" - - "**/*.ipp" - when: manual - allow_failure: true artifacts: !reference [.build-cpp, artifacts] diff --git a/.gitlab/ci/lang/cpp/lint/clang_tools.yml b/.gitlab/ci/lang/cpp/lint/clang_tools.yml index 7f69ff7..73f6450 100644 --- a/.gitlab/ci/lang/cpp/lint/clang_tools.yml +++ b/.gitlab/ci/lang/cpp/lint/clang_tools.yml @@ -28,7 +28,7 @@ check:cpp:format: - clang_format.patch .chck-cpp-clang-tidy: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest stage: check extends: - .build-cpp diff --git a/.gitlab/ci/lang/cpp/lint/coverage.yml b/.gitlab/ci/lang/cpp/lint/coverage.yml index 888944d..753f705 100644 --- a/.gitlab/ci/lang/cpp/lint/coverage.yml +++ b/.gitlab/ci/lang/cpp/lint/coverage.yml @@ -17,7 +17,7 @@ # It also worth to mention that such an artifact can occupy quite a lot of # space. check:cpp:coverage: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest stage: check extends: - .build-cpp diff --git a/.gitlab/ci/lang/cpp/lint/cppcheck.yml b/.gitlab/ci/lang/cpp/lint/cppcheck.yml index 299ea33..85e142e 100644 --- a/.gitlab/ci/lang/cpp/lint/cppcheck.yml +++ b/.gitlab/ci/lang/cpp/lint/cppcheck.yml @@ -13,7 +13,7 @@ # limitations under the License. check:cpp:cppcheck: - image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2004:latest + image: $BPROTO_CI_IMAGES_REGISTRY/ubuntu2304:latest stage: check extends: - .build-cpp diff --git a/docker/Conan.Dockerfile b/docker/Conan.Dockerfile index d620e30..0591295 100644 --- a/docker/Conan.Dockerfile +++ b/docker/Conan.Dockerfile @@ -12,10 +12,16 @@ # See the License for the specific language governing permissions and # limitations under the License. -FROM ubuntu:20.04 +FROM ubuntu:23.04 WORKDIR /tmp +# Define a gloval virtial environment for python packages. +# Actual dancing will be done in a setup script. + +ENV DOCKER_PYTHON_VENV=/opt/venv +ENV PATH="$DOCKER_PYTHON_VENV/bin:$PATH" + # Setup system and install packages COPY scripts/os/setup_conan.sh /tmp/ diff --git a/docker/Ubuntu2304.Dockerfile b/docker/Ubuntu2304.Dockerfile new file mode 100644 index 0000000..9e5964b --- /dev/null +++ b/docker/Ubuntu2304.Dockerfile @@ -0,0 +1,56 @@ +# Copyright 2020-2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +FROM ubuntu:23.04 + +WORKDIR /tmp + +# Define a gloval virtial environment for python packages. +# Actual dancing will be done in a setup script. + +ENV DOCKER_PYTHON_VENV=/opt/venv +ENV PATH="$DOCKER_PYTHON_VENV/bin:$PATH" + +# Setup system and install packages + +COPY scripts/os/setup_ubuntu2304.sh /tmp/ +COPY requirements.txt /tmp/ +RUN cd /tmp && bash setup_ubuntu2304.sh && rm -rf ./* + +# Setup Conan + +COPY conan/profiles/linux_clang \ + conan/profiles/linux_gcc \ + scripts/conan/setup.sh \ + /tmp/ +RUN cd /tmp && bash setup.sh && rm -rf ./* + +# Fetch Conan dependencies + +COPY conan/conanfile.txt \ + scripts/conan/fetch.sh \ + /tmp/ +RUN cd /tmp && bash fetch.sh && rm -rf ./* + +# Remove all temporary files + +RUN rm -rf /tmp/* + +# Install CI/CD scripts and linters config files + +COPY scripts/os/install_files.sh /tmp/ +COPY .* scripts/cicd/*.* scripts/cicd/*/* /tmp/ +RUN bash /tmp/install_files.sh && rm -rf /tmp/* + +ENV BASH_ENV "/etc/profile" diff --git a/docs/git/tags.rst b/docs/git/tags.rst index 4b0e786..7b7daf6 100644 --- a/docs/git/tags.rst +++ b/docs/git/tags.rst @@ -92,6 +92,8 @@ That why it's hard to collect all possible cases when a particular tag should be +---------------------------+--------+----------------------------------------+ | Ubuntu 20.04 | Yes | | +---------------------------+--------+----------------------------------------+ + | Ubuntu 23.04 | Yes | | + +---------------------------+--------+----------------------------------------+ | Windows | Yes | | +---------------------------+--------+----------------------------------------+ | .. centered:: **Tools** | diff --git a/docs/images/d/conan.rst b/docs/images/d/conan.rst index ee13bde..1754d6a 100644 --- a/docs/images/d/conan.rst +++ b/docs/images/d/conan.rst @@ -13,7 +13,7 @@ This docker image is provided as a clean setup for testing and deployment of ``c - ``conan:latest`` *BASE IMAGE* - Official `ubuntu:20.04 `__ image. + Official `ubuntu:23.04 `__ image. *BUILD TIME* 1 minute on average. @@ -22,20 +22,30 @@ This docker image is provided as a clean setup for testing and deployment of ``c *Final* docker image will contain only below additional packages. +.. caution:: Package versions dated by 17 October 2023. + +------------------+---------+--------------------------------------------------------------------------------+ | Package | Version | Purpose | +==================+=========+================================================================================+ -| ``doxygen`` | \- | To provide a documentation generator for code which uses C/C++ code. | +| .. centered:: **Compilation** | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``g++-11`` | 11.4.0 | To provide a C compiler. | +------------------+---------+--------------------------------------------------------------------------------+ -| ``g++-10`` | 10.3.0 | To provide a C compiler. | +| ``gcc-11`` | 11.4.0 | To provide a C++ compiler. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``make`` | \- | \- | +------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-10`` | 10.3.0 | To provide a C++ compiler. | +| .. centered:: **Essential** | +------------------+---------+--------------------------------------------------------------------------------+ | ``git`` | \- | To been able to download GitLab project in a job container. | +------------------+---------+--------------------------------------------------------------------------------+ -| ``make`` | \- | \- | +| ``python3-pip`` | 23.0.1 | To bring a python packages manager. | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``python3-venv`` | 3.11.2 | To overcome "externally managed environments" introduced by "PEP 668". | +------------------+---------+--------------------------------------------------------------------------------+ -| ``python3-pip`` | \- | To provide support of ``python 3.8.10`` language and bring a packages manager | +| .. centered:: **Utils** | ++------------------+---------+--------------------------------------------------------------------------------+ +| ``doxygen`` | \- | To provide a documentation generator for code which uses C/C++ code. | +------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* diff --git a/docs/images/g/alpine3.rst b/docs/images/g/alpine3.rst index fc3d470..742d5f8 100644 --- a/docs/images/g/alpine3.rst +++ b/docs/images/g/alpine3.rst @@ -18,25 +18,35 @@ A utility image which contains all possible linters and ``sphinx`` related packa *SYSTEM PACKAGES* +.. caution:: Package versions dated by 29 March 2023. + +-----------------+---------+-------------------------------------------------------------+ | Package | Version | Purpose | +=================+=========+=============================================================+ -| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | +| .. centered:: **Essential** | +-----------------+---------+-------------------------------------------------------------+ -| ``curl`` | \- | Mainly to upload packages to GitLab. | +| ``git`` | \- | To been able to download GitLab project in a job container. | +-----------------+---------+-------------------------------------------------------------+ -| ``gcc`` | \- | **Only to build** ``licenseheaders`` **linter.** | +| .. centered:: **Utils** | +-----------------+---------+-------------------------------------------------------------+ -| ``git`` | \- | To been able to download GitLab project in a job container. | +| ``bat`` | \- | To provided syntax highlighting in GitLab terminal. | ++-----------------+---------+-------------------------------------------------------------+ +| ``curl`` | \- | Mainly to upload packages to GitLab. | +-----------------+---------+-------------------------------------------------------------+ | ``less`` | \- | To update ``less`` and bring support for additional flags. | +-----------------+---------+-------------------------------------------------------------+ -| ``musl-dev`` | \- | **Only to build** ``licenseheaders`` **linter.** | +| .. centered:: **Linters & Sanitizers** | +-----------------+---------+-------------------------------------------------------------+ | ``shellcheck`` | \- | To provided a shell scripts linter. | +-----------------+---------+-------------------------------------------------------------+ | ``shfmt`` | \- | To provided a shell scripts formatter. | +-----------------+---------+-------------------------------------------------------------+ +| .. centered:: **Other** | ++-----------------+---------+-------------------------------------------------------------+ +| ``gcc`` | \- | **Only to build** ``licenseheaders`` **linter.** | ++-----------------+---------+-------------------------------------------------------------+ +| ``musl-dev`` | \- | **Only to build** ``licenseheaders`` **linter.** | ++-----------------+---------+-------------------------------------------------------------+ *C++ PACKAGES* None. diff --git a/docs/images/g/centos7.rst b/docs/images/g/centos7.rst index ac08b71..fe6db03 100644 --- a/docs/images/g/centos7.rst +++ b/docs/images/g/centos7.rst @@ -20,9 +20,13 @@ A C++ based image which contains all required and optional packages to build C++ *SYSTEM PACKAGES* +.. caution:: Package versions dated by 29 March 2023. + +----------------------------------+---------+--------------------------------------------------------------------------------+ | Package | Version | Purpose | +==================================+=========+================================================================================+ +| .. centered:: **Compilation** | ++----------------------------------+---------+--------------------------------------------------------------------------------+ | ``cmake3`` | 3.21.0 | To provide a C/C++ build system. | +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``devtoolset-10-gcc`` | 10.2.1 | To provide a C compiler. | @@ -33,30 +37,20 @@ A C++ based image which contains all required and optional packages to build C++ +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``devtoolset-10-gdb`` | 9.2 | To provide a C/C++ CLI debugger. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``devtoolset-10-libubsan-devel`` | 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ | ``devtoolset-10-make`` | 4.2.1 | \- | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``doxygen`` | 1.8.5 | To provide a documentation generator for code which uses C/C++ code. | +| .. centered:: **Essential** | +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``git`` | \- | To been able to download GitLab project in a job container. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-toolset-13.0-clang`` | 13.0.1 | To provide a C/C++ compiler. | +| ``rh-python38-python`` | 3.8 | To provide support of ``python 3`` language. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-toolset-13.0-llvm`` | 13.0.1 | **To fix backtraces from sanitizers** | +| ``rh-python38-python-pip`` | \- | To provide a python packages manager. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``rh-python38-python`` | 3.8 | To provide support of ``python 3`` language. | +| .. centered:: **Other** | +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``rh-python38-python-devel`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``rh-python38-python-pip`` | \- | To provide a python packages manager. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* Only those which are listed in ``conan/conanfile.txt`` file. diff --git a/docs/images/g/centos8.rst b/docs/images/g/centos8.rst index 5440246..9051c06 100644 --- a/docs/images/g/centos8.rst +++ b/docs/images/g/centos8.rst @@ -4,6 +4,10 @@ CentOS 8 ======== +.. warning:: + + Support of this image has been discontinued! + A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. *TAGS* @@ -18,10 +22,12 @@ A C++ based image which contains all required and optional packages to build C++ *SYSTEM PACKAGES* +.. caution:: Package versions dated by 29 March 2023. + +----------------------------------+---------+--------------------------------------------------------------------------------+ | Package | Version | Purpose | +==================================+=========+================================================================================+ -| ``clang`` | 11.0.0 | To provide a C/C++ compiler. | +| .. centered:: **Compilation** | +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``cmake`` | 3.20.2 | To provide a C/C++ build system. | +----------------------------------+---------+--------------------------------------------------------------------------------+ @@ -33,22 +39,16 @@ A C++ based image which contains all required and optional packages to build C++ +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``gcc-toolset-10-gdb`` | 8.3 | To provide a C/C++ CLI debugger. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libasan-devel`` | 10.2.1 | To provide address sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-liblsan-devel`` | 10.2.1 | To provide leak sanitizer for code which uses C/C++ code. | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libtsan-devel`` | 10.2.1 | To provide thread sanitizer for code which uses C/C++ code. | +| ``make`` | 4.2.1 | \- | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-toolset-10-libubsan-devel``| 10.2.1 | To provide UB sanitizer for code which uses C/C++ code. | +| .. centered:: **Essential** | +----------------------------------+---------+--------------------------------------------------------------------------------+ | ``git`` | \- | To been able to download GitLab project in a job container. | +----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm`` | 12.0.1 | **To fix backtraces from sanitizers** | -+----------------------------------+---------+--------------------------------------------------------------------------------+ -| ``make`` | 4.2.1 | \- | -+----------------------------------+---------+--------------------------------------------------------------------------------+ | ``python38-pip`` | 3.8 | To provide support of ``python 3`` language and bring a packages manager | +----------------------------------+---------+--------------------------------------------------------------------------------+ +| .. centered:: **Other** | ++----------------------------------+---------+--------------------------------------------------------------------------------+ | ``python38-devel`` | \- | To provide *dev* files for ``pybind11`` C++ library. | +----------------------------------+---------+--------------------------------------------------------------------------------+ diff --git a/docs/images/g/index.rst b/docs/images/g/index.rst index 91d9941..a23e718 100644 --- a/docs/images/g/index.rst +++ b/docs/images/g/index.rst @@ -12,8 +12,10 @@ Here is listed all docker images with a very general purpose setup, that can be centos7.rst centos8.rst ubuntu2004.rst + ubuntu2304.rst - :doc:`alpine3`, - :doc:`centos7`, - :doc:`centos8`, -- :doc:`ubuntu2004`. +- :doc:`ubuntu2004`, +- :doc:`ubuntu2304`. diff --git a/docs/images/g/ubuntu2004.rst b/docs/images/g/ubuntu2004.rst index ddea969..01facf9 100644 --- a/docs/images/g/ubuntu2004.rst +++ b/docs/images/g/ubuntu2004.rst @@ -20,48 +20,30 @@ A C++ based image which contains all required and optional packages to build C++ *SYSTEM PACKAGES* - **Package versions dated by 29 March 2023.** +.. caution:: Package versions dated by 29 March 2023. +----------------------+---------+--------------------------------------------------------------------------------+ | Package | Version | Purpose | +======================+=========+================================================================================+ -| ``clang-12`` | 12.0.0 | To provide a C/C++ compiler. | +| .. centered:: **Compilation** | +----------------------+---------+--------------------------------------------------------------------------------+ | ``cmake`` | 3.21.0 | To provide a C/C++ build system. | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``cppcheck`` | 1.90 | To provided a C/C++ linter. | +| ``g++-11`` | 10.3.0 | To provide a C compiler. | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``curl`` | 7.68.0 | Mainly to upload packages to GitLab. | +| ``gcc-11`` | 10.3.0 | To provide a C++ compiler. | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``doxygen`` | 1.8.17 | To provide a documentation generator for code which uses C/C++ code. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``g++-10`` | 10.3.0 | To provide a C compiler. | +| ``make`` | 4.2.1 | \- | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``gcc-10`` | 10.3.0 | To provide a C++ compiler. | +| .. centered:: **Essential** | +----------------------+---------+--------------------------------------------------------------------------------+ | ``git`` | \- | To been able to download GitLab project in a job container. | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``graphviz`` | 2.43.0 | To build diagrams and graphs. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``jq`` | \- | To provide ``sed`` for JSON data. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``libgtk-3-dev`` | 3.X | To provide *dev* files for ``sciter`` C++ library. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``libpython3.8-dev`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``lcov`` | 1.14 | To provide graphical front-end for GCC's coverage testing tool ``gcov``. | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``llvm-12`` | 12.0.0 | **To fix backtraces from sanitizers** | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``make`` | 4.2.1 | \- | -+----------------------+---------+--------------------------------------------------------------------------------+ -| ``pkg-config`` | 3.X | Transitive dependency for ``gtk/system`` recipe, required by ``sciter``. | -+----------------------+---------+--------------------------------------------------------------------------------+ | ``python3-pip`` | 20.0.2 | To provide support of ``python 3.8.10`` language and bring a packages manager | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``valgrind`` | 3.15.0 | To provide leak sanitizer for code which uses C/C++ code. | +| .. centered:: **Other** | +----------------------+---------+--------------------------------------------------------------------------------+ -| ``wget`` | 1.20.3 | Mainly to download different stuff. | +| ``libpython3-dev`` | 3.8 | To provide *dev* files for ``pybind11`` C++ library. | +----------------------+---------+--------------------------------------------------------------------------------+ *C++ PACKAGES* diff --git a/docs/images/g/ubuntu2304.rst b/docs/images/g/ubuntu2304.rst new file mode 100644 index 0000000..24fb33b --- /dev/null +++ b/docs/images/g/ubuntu2304.rst @@ -0,0 +1,80 @@ +.. _images-general-ubuntu2304: + +============ +Ubuntu 23.04 +============ + +A C++ based image which contains all required and optional packages to build C++ projects based on CMake build system. + +.. note:: As this system is currently a main one, it can be used as a reference to setup your own C/C++ workspace. + +*TAGS* + +- ``ubuntu2304:latest`` + +*BASE IMAGE* + Official `ubuntu:23.04 `__ image. + +*BUILD TIME* + 25 minutes on average. + +*SYSTEM PACKAGES* + +.. caution:: Package versions dated by 17 October 2023. + ++----------------------+---------+--------------------------------------------------------------------------------+ +| Package | Version | Purpose | ++======================+=========+================================================================================+ +| .. centered:: **Compilation** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``clang-15`` | 15.0.7 | To provide a C/C++ compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``g++-11`` | 11.4.0 | To provide a C compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``gcc-11`` | 11.4.0 | To provide a C++ compiler. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``cmake`` | 3.25.0 | To provide a C/C++ build system. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``llvm-15`` | 15.0.7 | **To fix backtraces from sanitizers** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``make`` | 4.3 | \- | ++----------------------+---------+--------------------------------------------------------------------------------+ +| .. centered:: **Essential** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``git`` | \- | To been able to download GitLab project in a job container. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``python3-pip`` | 23.0.1 | To bring a python packages manager. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``python3-venv`` | 3.11.2 | To overcome "externally managed environments" introduced by "PEP 668". | ++----------------------+---------+--------------------------------------------------------------------------------+ +| .. centered:: **Linters & Sanitizers** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``clang-tidy-15`` | 15.0.7 | Mainly to upload packages to GitLab. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``cppcheck`` | 2.10 | To provided a C/C++ linter. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``valgrind`` | 3.19.0 | To provide leak sanitizer for code which uses C/C++ code. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| .. centered:: **Utils** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``curl`` | 7.88.1 | Mainly to upload packages to GitLab. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``doxygen`` | 1.9.4 | To provide a documentation generator for code which uses C/C++ code. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``jq`` | \- | To provide ``sed`` for JSON data. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``wget`` | 1.21.3 | Mainly to download different stuff. | ++----------------------+---------+--------------------------------------------------------------------------------+ +| .. centered:: **Other** | ++----------------------+---------+--------------------------------------------------------------------------------+ +| ``libpython3-dev`` | 3.11.2 | To provide *dev* files for ``pybind11`` C++ library. | ++----------------------+---------+--------------------------------------------------------------------------------+ + +*C++ PACKAGES* + Only those which are listed in ``conan/conanfile.txt`` file. + +*PYTHON PACKAGES* + Mainly ``conan`` package and ``sphinx`` related packages. + +*CI SCRIPTS* + All CI scripts are included in this docker image. diff --git a/docs/pipelines/lang/cpp/build.rst b/docs/pipelines/lang/cpp/build.rst index 72c84ce..330c23e 100644 --- a/docs/pipelines/lang/cpp/build.rst +++ b/docs/pipelines/lang/cpp/build.rst @@ -118,56 +118,56 @@ Distribution As we try to test as much configurations as possible, in this table all current setups will be tracked. -+-------------------+---------------------------------------------------------------------------+ -| Options | System Configuration | -+ +-----------------------+-------------------+---------------------+---------+ -| | CentOS 7 | CentOS 8 | Ubuntu 20.04 | Windows | -+ +---------+-------------+---------+---------+---------+-----------+---------+ -| | Clang | GCC | Clang | GCC | Clang | GCC | MSBuild | -+===================+=========+=============+=========+=========+=========+===========+=========+ -| | .. centered:: **Build Configuration** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Type | debug | **release** | debug | debug | debug | debug | debug | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Asserts | **yes** | no | **yes** | **yes** | **yes** | **yes** | **yes** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Cache | default | default | default | default | default | default | default | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Linter | default | default | default | default | default | default | default | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| LTO | no | **yes** | no | **yes** | no | **yes** | **yes** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Docs** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Docs | no | no | no | no | **yes** | **yes**\* | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Linters** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| LWYU | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Sanitizers** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| ASan | no | no | no | **yes** | no | no | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| LSan | no | no | no | **yes** | no | no | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| MSan | no | no | no | no | no | no | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| UBSan | no | no | no | **yes** | no | no | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| TSan | no | no | no | no | **yes** | no | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Valgrind | no | no | no | no | no | **yes** | no | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| | .. centered:: **Tests** | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ -| Benchmarks | .. centered:: **yes** | -+-------------------+ + -| Unit tests | | -+-------------------+ + -| Component tests | | -+-------------------+ + -| Integration tests | | -+-------------------+ + -| System tests | | -+-------------------+---------+-------------+---------+---------+---------+-----------+---------+ ++-------------------+----------------------------------------------------------------------------+ +| Options | System Configuration | ++ +-------------+-------------+----------------+-------------------+-----------+ +| | CentOS 7 | *CentOS 8* | *Ubuntu 20.04* | Ubuntu 23.04 | *Windows* | ++ +-------------+-------------+----------------+-------------------+-----------+ +| | GCC | GCC | GCC | Clang | GCC | MSBuild | ++===================+=============+=============+================+=========+=========+===========+ +| | .. centered:: **Build Configuration** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Type | **release** | **release** | **release** | debug | debug | debug | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Asserts | no | no | no | **yes** | **yes** | **yes** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Cache | default | default | default | default | default | default | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Linter | default | default | default | default | default | default | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| LTO | **yes** | **yes** | **yes** | no | **yes** | **yes** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| | .. centered:: **Docs** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Docs | no | no | no | **yes** | no | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| | .. centered:: **Linters** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| LWYU | **yes** | **yes** | **yes** | **yes** | **yes** | **yes** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| | .. centered:: **Sanitizers** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| ASan | no | no | no | no | **yes** | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| LSan | no | no | no | no | **yes** | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| MSan | no | no | no | no | no | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| UBSan | no | no | no | no | **yes** | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| TSan | no | no | no | **yes** | no | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Valgrind | no | no | no | no | **yes** | no | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| | .. centered:: **Tests** | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ +| Benchmarks | .. centered:: **yes** | ++-------------------+ + +| Unit tests | | ++-------------------+ + +| Component tests | | ++-------------------+ + +| Integration tests | | ++-------------------+ + +| System tests | | ++-------------------+-------------+-------------+----------------+---------+---------+-----------+ diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index 30875d2..56b0889 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -65,7 +65,7 @@ Even so it means pipeline could take much less time, it still much easy to manag - Mandatory *IMAGES* - :ref:`ubuntu2004:latest `. + :ref:`ubuntu2304:latest `. *STAGE* :ref:`overview-stages-check-stage`. @@ -224,7 +224,7 @@ This job executes `cppcheck `__ *only on cha - Mandatory *IMAGES* - :ref:`ubuntu2004:latest `. + :ref:`ubuntu2304:latest `. *STAGE* :ref:`overview-stages-check-stage`. @@ -290,7 +290,7 @@ This job executes `clang-tidy `__ *only - *IMAGES* - :ref:`ubuntu2004:latest `. + :ref:`ubuntu2304:latest `. *STAGE* :ref:`overview-stages-check-stage`. @@ -333,7 +333,7 @@ So the next job run might do nothing if commit hash hasn't changed from the time - Mandatory *IMAGES* - :ref:`ubuntu2004:latest `. + :ref:`ubuntu2304:latest `. *STAGE* :ref:`overview-stages-check-stage`. diff --git a/docs/pipelines/lang/docker/build.rst b/docs/pipelines/lang/docker/build.rst index 1a96eec..c523a0b 100644 --- a/docs/pipelines/lang/docker/build.rst +++ b/docs/pipelines/lang/docker/build.rst @@ -155,6 +155,10 @@ Jobs overview +--------------------------------+--------+ + | ``deploy:docker:ubuntu2004`` | deploy | | +--------------------------------+--------+----------------------------------------------------+ + | ``build:docker:ubuntu2304`` | build | :ref:`Ubuntu 20.04 ` | + +--------------------------------+--------+ + + | ``deploy:docker:ubuntu2304`` | deploy | | + +--------------------------------+--------+----------------------------------------------------+ | .. centered:: **Dedicated images** | +--------------------------------+--------+----------------------------------------------------+ | ``build:docker:clang-format`` | build | :ref:`Clang-Format ` | diff --git a/scripts/conan/fetch.sh b/scripts/conan/fetch.sh index 1f48ef4..63ab2cf 100644 --- a/scripts/conan/fetch.sh +++ b/scripts/conan/fetch.sh @@ -42,6 +42,13 @@ fetch() echo -e "\033[0;33mFetching Conan dependencies for CC=${cc}, CXX=${cxx}, CMAKE_BUILD_TYPE=${type} configuration...\033[0m" + # FMI: https://stackoverflow.com/questions/75103211 + # shellcheck disable=SC2046 + if [ $(command -v "${cxx}" &> /dev/null ; echo $?) -ne 0 ]; then + echo -e "\033[0;31mCould not find compiler set in environment variable CXX (${cxx})! Skipping current setup! \033[0m" + return + fi + # NOTE(szinchen): We need both '-if' and '-of' due to # https://github.com/conan-io/conan/issues/11483. conan install . -if build -of build --build=missing \ diff --git a/scripts/os/setup_centos7.sh b/scripts/os/setup_centos7.sh index a2f6e67..456ba9a 100644 --- a/scripts/os/setup_centos7.sh +++ b/scripts/os/setup_centos7.sh @@ -27,19 +27,14 @@ set -e #------------------------------------------------------------------------------# declare -a INSTALL_PKGS=( - "devtoolset-10-gcc" - "devtoolset-10-gcc-c++" - "devtoolset-10-gcc-gfortran" - "devtoolset-10-gdb" - "devtoolset-10-libasan-devel" - "devtoolset-10-liblsan-devel" - "devtoolset-10-libtsan-devel" - "devtoolset-10-libubsan-devel" - "devtoolset-10-make" - "doxygen" + # compilation + "devtoolset-11-gcc" + "devtoolset-11-gcc-c++" + "devtoolset-11-gcc-gfortran" + "devtoolset-11-gdb" + "devtoolset-11-make" + # essential "git" - "llvm-toolset-13.0-clang" - "llvm-toolset-13.0-llvm" "rh-python38-python" "rh-python38-python-devel" "rh-python38-python-pip" @@ -86,7 +81,7 @@ source /opt/rh/rh-python38/enable # Install packages pip3 install --no-cache-dir -r 'requirements.txt' -pip3 install --no-cache-dir 'cmake==3.21.0' +pip3 install --no-cache-dir 'cmake==3.25.0' #------------------------------------------------------------------------------# # Setup environment # @@ -160,7 +155,6 @@ sed -i -e $'s/Linux:/Linux:\\\n CentOS:/g' "${HOME}/.conan/settings.yml" # Make SCL available globally in user environment. # https://stackoverflow.com/questions/55901985 cat << EOF >> "/etc/profile.d/scl_enable.sh" -source scl_source enable devtoolset-10 -source scl_source enable llvm-toolset-13.0 +source scl_source enable devtoolset-11 source scl_source enable rh-python38 EOF diff --git a/scripts/os/setup_centos8.sh b/scripts/os/setup_centos8.sh index 6f5e334..6b9ff97 100644 --- a/scripts/os/setup_centos8.sh +++ b/scripts/os/setup_centos8.sh @@ -30,19 +30,15 @@ set -e # See https://stackoverflow.com/questions/61590926 declare -a INSTALL_PKGS=( - "clang" + # compilation "cmake" "gcc-toolset-10-gcc" "gcc-toolset-10-gcc-c++" "gcc-toolset-10-gcc-gfortran" "gcc-toolset-10-gdb" - "gcc-toolset-10-libasan-devel" - "gcc-toolset-10-liblsan-devel" - "gcc-toolset-10-libtsan-devel" - "gcc-toolset-10-libubsan-devel" - "git" - "llvm" "make" + # essential + "git" "python38-pip" "python38-devel" ) diff --git a/scripts/os/setup_conan.sh b/scripts/os/setup_conan.sh index c794593..509be28 100644 --- a/scripts/os/setup_conan.sh +++ b/scripts/os/setup_conan.sh @@ -27,12 +27,16 @@ set -e #------------------------------------------------------------------------------# declare -a INSTALL_PKGS=( - "doxygen" - "g++-10" - "gcc-10" - "git" + # compilation + "g++-11" + "gcc-11" "make" + # essential + "git" "python3-pip" + "python3-venv" + # cppdoc + "doxygen" ) # Install @@ -55,21 +59,29 @@ rm -rf /var/lib/apt/lists/* # GCC -update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-10 110 +update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-11 110 update-alternatives \ - --install /usr/bin/gcc gcc /usr/bin/gcc-10 110 \ - --slave /usr/bin/g++ g++ /usr/bin/g++-10 \ - --slave /usr/bin/gcov gcov /usr/bin/gcov-10 \ - --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-10 \ - --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-10 + --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 \ + --slave /usr/bin/g++ g++ /usr/bin/g++-11 \ + --slave /usr/bin/gcov gcov /usr/bin/gcov-11 \ + --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-11 \ + --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-11 #------------------------------------------------------------------------------# # Python # #------------------------------------------------------------------------------# +if [[ -v DOCKER_PYTHON_VENV ]]; then + if [[ -n "${DOCKER_PYTHON_VENV}" ]]; then + python3 -m venv "${DOCKER_PYTHON_VENV}" + # shellcheck disable=SC1091 + source "${DOCKER_PYTHON_VENV}/bin/activate" + fi +fi + declare -a INSTALL_PY_PKGS=( - "cmake==3.21.0" + "cmake==3.25.0" "conan==1.59.0" # cppdoc "breathe==4.32.0" diff --git a/scripts/os/setup_ubuntu2004.sh b/scripts/os/setup_ubuntu2004.sh index b76fe1e..70ab856 100644 --- a/scripts/os/setup_ubuntu2004.sh +++ b/scripts/os/setup_ubuntu2004.sh @@ -27,25 +27,15 @@ set -e #------------------------------------------------------------------------------# declare -a INSTALL_PKGS=( - "clang-12" - "clang-tidy-14" # external - "cmake" # external - "cppcheck" - "curl" - "doxygen" - "g++-10" - "gcc-10" - "git" - "graphviz" - "jq" - "libgtk-3-dev" - "libpython3.8-dev" - "lcov" - "llvm-12" + # compilation + "g++-11" + "gcc-11" "make" - "pkg-config" + # essential + "git" "python3-pip" - "valgrind" + # pybind11 + "libpython3-dev" ) # @@ -56,20 +46,15 @@ declare -a INSTALL_PKGS=( export DEBIAN_FRONTEND=noninteractive export TZ=Europe/Kiev +# We need to enable official Ubuntu Toolchain PPA to get new version of GCC. +# - https://stackoverflow.com/questions/67298443 +# - https://wiki.ubuntu.com/ToolChain#PPA_packages apt-get update -apt-get install --no-install-recommends -y ca-certificates gnupg wget - -# Install clang-*-14 -# FMI https://apt.llvm.org/. - -echo "deb http://apt.llvm.org/focal/ llvm-toolchain-focal-14 main" > /etc/apt/sources.list.d/llvm.list -echo "deb-src http://apt.llvm.org/focal/ llvm-toolchain-focal-14 main" >> /etc/apt/sources.list.d/llvm.list - -wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add - +apt-get install --no-install-recommends -y software-properties-common +add-apt-repository ppa:ubuntu-toolchain-r/test # Install packages -apt-get update apt-get install --no-install-recommends -y "${INSTALL_PKGS[@]}" # @@ -86,27 +71,20 @@ rm -rf /var/lib/apt/lists/* # See https://stackoverflow.com/questions/7832892 # See https://stackoverflow.com/questions/67298443 -# Clang - -update-alternatives \ - --install /usr/bin/clang clang /usr/bin/clang-12 100 \ - --slave /usr/bin/clang++ clang++ /usr/bin/clang++-12 - # GCC -update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-10 110 +update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-11 110 update-alternatives \ - --install /usr/bin/gcc gcc /usr/bin/gcc-10 110 \ - --slave /usr/bin/g++ g++ /usr/bin/g++-10 \ - --slave /usr/bin/gcov gcov /usr/bin/gcov-10 \ - --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-10 \ - --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-10 + --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 \ + --slave /usr/bin/g++ g++ /usr/bin/g++-11 \ + --slave /usr/bin/gcov gcov /usr/bin/gcov-11 \ + --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-11 \ + --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-11 #------------------------------------------------------------------------------# # Python # #------------------------------------------------------------------------------# pip3 install --no-cache-dir -r 'requirements.txt' - -pip3 install --no-cache-dir 'cmake==3.21.0' +pip3 install --no-cache-dir 'cmake==3.25.0' diff --git a/scripts/os/setup_ubuntu2304.sh b/scripts/os/setup_ubuntu2304.sh new file mode 100644 index 0000000..dda1968 --- /dev/null +++ b/scripts/os/setup_ubuntu2304.sh @@ -0,0 +1,109 @@ +#!/usr/bin/env bash + +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# DESCRIPTION: +# +# This script is mainly supposed to be used only by Ubuntu 20.04 docker image to +# provide a pre-build image with all pre-installed and pre-configured system +# packages and project dependencies. + +set -e + +#------------------------------------------------------------------------------# +# Packages # +#------------------------------------------------------------------------------# + +declare -a INSTALL_PKGS=( + # compilation + "clang-15" + "g++-11" + "gcc-11" + "llvm-15" + "make" + # essential + "git" + "python3-pip" + "python3-venv" + # linters / sanitizers + "clang-tidy-15" + "cppcheck" + "valgrind" + # utils + "curl" + "doxygen" + "jq" + # pybind11 + "libpython3-dev" +) + +# +# Install +# + +# set noninteractive installation +export DEBIAN_FRONTEND=noninteractive +export TZ=Europe/Kiev + +# Install packages + +apt-get update +apt-get install --no-install-recommends -y "${INSTALL_PKGS[@]}" + +# +# Clean +# + +apt-get clean +rm -rf /var/lib/apt/lists/* + +#------------------------------------------------------------------------------# +# Packages Aliases # +#------------------------------------------------------------------------------# + +# See https://stackoverflow.com/questions/7832892 +# See https://stackoverflow.com/questions/67298443 + +# Clang + +update-alternatives \ + --install /usr/bin/clang clang /usr/bin/clang-15 100 \ + --slave /usr/bin/clang++ clang++ /usr/bin/clang++-15 + +# GCC + +update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-11 110 + +update-alternatives \ + --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 \ + --slave /usr/bin/g++ g++ /usr/bin/g++-11 \ + --slave /usr/bin/gcov gcov /usr/bin/gcov-11 \ + --slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-11 \ + --slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-11 + +#------------------------------------------------------------------------------# +# Python # +#------------------------------------------------------------------------------# + +if [[ -v DOCKER_PYTHON_VENV ]]; then + if [[ -n "${DOCKER_PYTHON_VENV}" ]]; then + python3 -m venv "${DOCKER_PYTHON_VENV}" + # shellcheck disable=SC1091 + source "${DOCKER_PYTHON_VENV}/bin/activate" + fi +fi + +pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir 'cmake==3.25.0' -- GitLab From f607c8ee2a64feb4bb7bb8ba72f0d66997e17120 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Fri, 17 Nov 2023 22:50:13 +0000 Subject: [PATCH 15/44] Enable colorful CI output for clang-tidy job Tags: ClangTidy, Cpp, Linters --- scripts/cicd/lint/check_cpp_conventions.sh | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/scripts/cicd/lint/check_cpp_conventions.sh b/scripts/cicd/lint/check_cpp_conventions.sh index 6c7d4bd..d2516e8 100644 --- a/scripts/cicd/lint/check_cpp_conventions.sh +++ b/scripts/cicd/lint/check_cpp_conventions.sh @@ -184,7 +184,12 @@ check_all() # Perform check - run-clang-tidy-14 -j "${NPROC}" -p "${CMAKE_BUILD_DIR}" -quiet | tee "${LOG_FILE}" || true + run-clang-tidy \ + -j "${NPROC}" \ + -p "${CMAKE_BUILD_DIR}" \ + -quiet \ + -use-color \ + | tee "${LOG_FILE}" || true # Deploy -- GitLab From 0003c0e573cfdfc718317904a0677fd8b65979ab Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 00:53:08 +0200 Subject: [PATCH 16/44] Move environment variables to their own section Tags: Docker, Docs --- docs/pipelines/lang/docker/build.rst | 93 +++++++++++----------------- 1 file changed, 36 insertions(+), 57 deletions(-) diff --git a/docs/pipelines/lang/docker/build.rst b/docs/pipelines/lang/docker/build.rst index c523a0b..48a2bb8 100644 --- a/docs/pipelines/lang/docker/build.rst +++ b/docs/pipelines/lang/docker/build.rst @@ -4,12 +4,45 @@ Build & Deploy This is a pipeline for testing and deploying new changes that have been made to anything that is directly related to the *Docker* part of the project. +.. _pipelines-lang-docker-environment: + +Environment +=========== + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - Name + - Necessity + - Origin + + * - BPROTO_CI_DEPLOY_USER + - Mandatory + - + + * - BPROTO_CI_DEPLOY_TOKEN + - Mandatory + - + + * - BPROTO_CI_IMAGES_REGISTRY + - Mandatory + - + + * - *CI_COMMIT_REF_NAME* + - Mandatory + - GitLab + + * - *CI_DEFAULT_BRANCH* + - Mandatory + - GitLab + .. _pipelines-lang-docker-build-triggers: Triggers ======== -All jobs from *Docker "sub-pipeline"* stages are triggered only on merge requests and only if changes have been made to docker files. +All jobs from *Docker "sub-pipeline"* stages are triggered and only if changes have been made to docker files. Right now such files are detected by below patterns: - ``conan/*`` @@ -39,34 +72,7 @@ This stage is responsible for building `Docker `__ image Jobs has no dependencies from other stages or jobs. *ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - :width: 100% - - * - Name - - Necessity - - Origin - - * - BPROTO_CI_DEPLOY_USER - - Mandatory - - - - * - BPROTO_CI_DEPLOY_TOKEN - - Mandatory - - - - * - BPROTO_CI_IMAGES_REGISTRY - - Mandatory - - - - * - *CI_COMMIT_REF_NAME* - - Mandatory - - GitLab - - * - *CI_DEFAULT_BRANCH* - - Mandatory - - GitLab + A list of all environment variables can be found :ref:`here `. *IMAGES* `docker:19.03.12 `__. @@ -92,34 +98,7 @@ So called pre-build images are crucial part of our CI/CD as it allows us to decr Jobs has no dependencies from other stages or jobs. *ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - :width: 100% - - * - Name - - Necessity - - Origin - - * - BPROTO_CI_DEPLOY_USER - - Mandatory - - - - * - BPROTO_CI_DEPLOY_TOKEN - - Mandatory - - - - * - BPROTO_CI_IMAGES_REGISTRY - - Mandatory - - - - * - *CI_COMMIT_REF_NAME* - - Mandatory - - GitLab - - * - *CI_DEFAULT_BRANCH* - - Mandatory - - GitLab + A list of all environment variables can be found :ref:`here `. *IMAGES* `docker:19.03.12 `__. -- GitLab From 3e69ca32509976b18576e01d9b44820795d70abb Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 00:54:14 +0200 Subject: [PATCH 17/44] Cover Hugo jobs with documentation Tags: Docs, Hugo --- docs/git/tags.rst | 2 ++ docs/pipelines/docs/hugo.rst | 60 ++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/docs/git/tags.rst b/docs/git/tags.rst index 7b7daf6..6dc30f4 100644 --- a/docs/git/tags.rst +++ b/docs/git/tags.rst @@ -100,5 +100,7 @@ That why it's hard to collect all possible cases when a particular tag should be +---------------------------+--------+----------------------------------------+ | Conan | Yes | | +---------------------------+--------+----------------------------------------+ + | Hugo | Yes | | + +---------------------------+--------+----------------------------------------+ | Sphinx | Yes | | +---------------------------+--------+----------------------------------------+ diff --git a/docs/pipelines/docs/hugo.rst b/docs/pipelines/docs/hugo.rst index 6d5da5d..aca1d8e 100644 --- a/docs/pipelines/docs/hugo.rst +++ b/docs/pipelines/docs/hugo.rst @@ -3,3 +3,63 @@ ==== Hugo ==== + +This is a "sub-pipeline" for building and deploying new changes that have been made to `Hugo `__ files of a specific GitLab project. + +.. _pipelines-docs-hugo-triggers: + +Triggers +======== + +.. caution:: + + Right now all jobs from *Hugo "sub-pipeline"* stages are triggered on any change to repository. + +Jobs overview +============= + +build:docs +---------- + +This job is responsible for building HTML documentation from a clean state to make sure there are no unexpected results. + +*ALLOW FAILURE* + Job is not allowed to fail as any failure here means fundamental problems in documentation generation. + +*ARTIFACTS* + Job generate an artifact with a HTML documentation. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-build-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests**. + +pages +----- + +This stage is responsible for building and deploying static HTML documentation files to the project `GitLab Pages `__. + +*ALLOW FAILURE* + Job is not allowed to fail as any failure here means fundamental problems in documentation generation. + +*ARTIFACTS* + Job generate an artifact with a HTML documentation. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-deploy-stage`. + +*TRIGGERS* + Job is triggered only on ``CI_DEFAULT_BRANCH``. -- GitLab From 8cb63067eb31c8bd815d59e9dd3bcb96e246fd27 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 00:55:53 +0200 Subject: [PATCH 18/44] Cover Sphinx jobs with documentation Tags: Docs, Sphinx --- docs/pipelines/docs/index.rst | 2 +- docs/pipelines/docs/sphinx.rst | 107 +++++++++++++++++++++++++++++++++ docs/variables.rst | 4 ++ 3 files changed, 112 insertions(+), 1 deletion(-) diff --git a/docs/pipelines/docs/index.rst b/docs/pipelines/docs/index.rst index f0d2e25..304c146 100644 --- a/docs/pipelines/docs/index.rst +++ b/docs/pipelines/docs/index.rst @@ -2,7 +2,7 @@ Docs ==== -These documents cover in-detail all available "sub-pipelines" for generation documentation: +These documents cover in-detail all available "sub-pipelines" for documentation generation: .. toctree:: :maxdepth: 1 diff --git a/docs/pipelines/docs/sphinx.rst b/docs/pipelines/docs/sphinx.rst index 10dc2ab..928e4c4 100644 --- a/docs/pipelines/docs/sphinx.rst +++ b/docs/pipelines/docs/sphinx.rst @@ -3,3 +3,110 @@ ============= Sphinx (reST) ============= + +.. _gitlab-pages: https://docs.gitlab.com/ee/user/project/pages + +This is a "sub-pipeline" for building and deploying new changes that have been made to `Sphinx `__ files of a specific GitLab project. + +.. note:: + + Current approach is way more simple than the old one and solely relies on `GitLab Pages `__. + If you still curious about how things worked before, you can look though :doc:`this page ` and investigate `this commit `__. + +.. _pipelines-docs-sphinx-environment: + +Environment +=========== + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + - Default value + + * - :ref:`BPROTO_CI_SPHINX_SOURCE_DIR ` + - Optional + - ``docs`` + + * - :ref:`BPROTO_CI_SPHINX_WARNINGS_AS_ERRORS` + - Optional + - ``false`` + +.. _pipelines-docs-sphinx-triggers: + +Triggers +======== + +All jobs from *Sphinx "sub-pipeline"* stages are triggered and only if changes have been made to CMake files. +Right now such files are detected by these patterns: + +- ``docs/**/*`` +- ``project/**/CMakeLists.txt`` +- ``project/**/include/**/*.hpp`` + +As you can see from the above list of files pipeline will take into account both types of the project documentation: Doxygen (C++ files) and Sphinx (RST files) documentation. + +Jobs overview +============= + +.. _pipelines-docs-sphinx-jobs-overview-build-docs: + +build:docs +---------- + +This job is responsible for building HTML documentation from a clean state to make sure there are no unexpected results. + +*ALLOW FAILURE* + Job is not allowed to fail as any failure here means fundamental problems in documentation generation. + +*ARTIFACTS* + Job generate an artifact with a HTML documentation. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + A list of all environment variables can be found :ref:`here `. + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-build-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + +report:docs +----------- + +This is a stage to simplify access to generated HTML files by :ref:`pipelines-docs-sphinx-jobs-overview-build-docs`. + +*See also report stage overview from* :ref:`overview-stages-report-stage`. + +pages +----- + +This stage is responsible for building and deploying static HTML documentation files to the project `GitLab Pages `_. + +*ALLOW FAILURE* + Job is not allowed to fail as any failure here means fundamental problems in documentation generation. + +*ARTIFACTS* + Job generate an artifact with a HTML documentation. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + A list of all environment variables can be found :ref:`here `. + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-deploy-stage`. + +*TRIGGERS* + Job is triggered only on ``CI_DEFAULT_BRANCH`` when any file from :ref:`trigger list ` is changed. diff --git a/docs/variables.rst b/docs/variables.rst index d35ff28..1bdbffb 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -38,11 +38,15 @@ Local CI/CD variables .. note:: This variable is only available for **linter** jobs. +.. _variables-bproto-ci-sphinx-source-dir: + **BPROTO_CI_SPHINX_SOURCE_DIR**:PATH Path to `Sphinx `__ source files. Defaults to ``docs``. +.. _variables-bproto-ci-sphinx-warnings-as-errors: + **BPROTO_CI_SPHINX_WARNINGS_AS_ERRORS**:BOOL Turn ``sphinx-build`` warnings into errors. -- GitLab From 3835f28f4d7aa5fa85316c3f51bc4d86e258173b Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 21:32:48 +0200 Subject: [PATCH 19/44] Clean triggers for docker images CI jobs Tags: CI, Dockers --- .gitlab/ci/images/centos7.yml | 2 -- .gitlab/ci/images/centos8.yml | 2 -- .gitlab/ci/images/ubuntu2004.yml | 2 -- 3 files changed, 6 deletions(-) diff --git a/.gitlab/ci/images/centos7.yml b/.gitlab/ci/images/centos7.yml index bc5bc81..f86e3ff 100644 --- a/.gitlab/ci/images/centos7.yml +++ b/.gitlab/ci/images/centos7.yml @@ -17,7 +17,6 @@ - conan/conanfile.txt - docker/CentOS7.Dockerfile - scripts/conan/* - - scripts/os/install_files.sh - scripts/os/setup_centos7.sh - requirements.txt @@ -48,4 +47,3 @@ deploy:docker:centos7: - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' changes: *centos7-image-changes - - !reference [.trigger-docker-on-linters-files-change, rules] diff --git a/.gitlab/ci/images/centos8.yml b/.gitlab/ci/images/centos8.yml index 8708d91..ecb8eda 100644 --- a/.gitlab/ci/images/centos8.yml +++ b/.gitlab/ci/images/centos8.yml @@ -17,7 +17,6 @@ - conan/conanfile.txt - docker/CentOS8.Dockerfile - scripts/conan/* - - scripts/os/install_files.sh - scripts/os/setup_centos8.sh - requirements.txt @@ -48,4 +47,3 @@ deploy:docker:centos8: - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' changes: *centos8-image-changes - - !reference [.trigger-docker-on-linters-files-change, rules] diff --git a/.gitlab/ci/images/ubuntu2004.yml b/.gitlab/ci/images/ubuntu2004.yml index 2d73884..b5acb9b 100644 --- a/.gitlab/ci/images/ubuntu2004.yml +++ b/.gitlab/ci/images/ubuntu2004.yml @@ -17,7 +17,6 @@ - conan/conanfile.txt - docker/Ubuntu2004.Dockerfile - scripts/conan/* - - scripts/os/install_files.sh - scripts/os/setup_ubuntu2004.sh - requirements.txt @@ -48,4 +47,3 @@ deploy:docker:ubuntu2004: - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' changes: *ubuntu2004_changes - - !reference [.trigger-docker-on-linters-files-change, rules] -- GitLab From 3fe7142427d5492ec93b45fb4adf16e56cbc27b1 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 21:33:59 +0200 Subject: [PATCH 20/44] Move to pyproject toml file for managing python packages Tags: CI, Dockers, Shell --- .dockerignore | 2 +- .gitignore | 3 +- docker/Alpine3.Dockerfile | 2 +- docker/CentOS7.Dockerfile | 2 +- docker/CentOS8.Dockerfile | 2 +- docker/Conan.Dockerfile | 2 +- docker/Ubuntu2004.Dockerfile | 2 +- docker/Ubuntu2304.Dockerfile | 2 +- docs/images/g/centos7.rst | 2 +- docs/images/g/centos8.rst | 2 +- docs/images/g/ubuntu2004.rst | 2 +- pyproject.toml | 59 ++++++++++++++++++++++++++++++++++ requirements.txt | 49 ---------------------------- scripts/os/setup_alpine3.sh | 2 +- scripts/os/setup_centos7.sh | 2 +- scripts/os/setup_centos8.sh | 2 +- scripts/os/setup_ubuntu2004.sh | 2 +- scripts/os/setup_ubuntu2304.sh | 2 +- 18 files changed, 76 insertions(+), 65 deletions(-) create mode 100644 pyproject.toml delete mode 100644 requirements.txt diff --git a/.dockerignore b/.dockerignore index 9b08215..92a0cd6 100644 --- a/.dockerignore +++ b/.dockerignore @@ -16,7 +16,7 @@ !.hadolint.yaml !.license.tmpl !.yamllint -!requirements.txt +!pyproject.toml !**.patch !**.py diff --git a/.gitignore b/.gitignore index 08d909c..2b718b1 100644 --- a/.gitignore +++ b/.gitignore @@ -21,8 +21,8 @@ !.yamllint !CONTRIBUTING.md !LICENSE +!pyproject.toml !README.md -!requirements.txt !**.Dockerfile !**.patch @@ -41,6 +41,7 @@ # But ignore these specific directories and subdirectories with specific files: +/*.egg-info /.idea/ /.venv/ /build/ diff --git a/docker/Alpine3.Dockerfile b/docker/Alpine3.Dockerfile index 9e2ebcf..76bcca9 100644 --- a/docker/Alpine3.Dockerfile +++ b/docker/Alpine3.Dockerfile @@ -34,7 +34,7 @@ RUN apk add --no-cache bash>=5.1.16 # Setup system and install packages COPY scripts/os/setup_alpine3.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_alpine3.sh && rm -rf ./* # Install CI/CD scripts and linters config files diff --git a/docker/CentOS7.Dockerfile b/docker/CentOS7.Dockerfile index 80b70b0..ca33027 100644 --- a/docker/CentOS7.Dockerfile +++ b/docker/CentOS7.Dockerfile @@ -42,7 +42,7 @@ FROM centos:7 # Setup system and install packages COPY scripts/os/setup_centos7.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_centos7.sh && rm -rf ./* # Enable the SCL for all bash scripts. diff --git a/docker/CentOS8.Dockerfile b/docker/CentOS8.Dockerfile index ddd827a..c87a59e 100644 --- a/docker/CentOS8.Dockerfile +++ b/docker/CentOS8.Dockerfile @@ -19,7 +19,7 @@ WORKDIR /tmp # Setup system and install packages COPY scripts/os/setup_centos8.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_centos8.sh && rm -rf ./* # Enable the SCL for all bash scripts. diff --git a/docker/Conan.Dockerfile b/docker/Conan.Dockerfile index 0591295..1e1cd41 100644 --- a/docker/Conan.Dockerfile +++ b/docker/Conan.Dockerfile @@ -25,5 +25,5 @@ ENV PATH="$DOCKER_PYTHON_VENV/bin:$PATH" # Setup system and install packages COPY scripts/os/setup_conan.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_conan.sh && rm -rf ./* diff --git a/docker/Ubuntu2004.Dockerfile b/docker/Ubuntu2004.Dockerfile index 17582dc..a70af04 100644 --- a/docker/Ubuntu2004.Dockerfile +++ b/docker/Ubuntu2004.Dockerfile @@ -19,7 +19,7 @@ WORKDIR /tmp # Setup system and install packages COPY scripts/os/setup_ubuntu2004.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_ubuntu2004.sh && rm -rf ./* # Setup Conan diff --git a/docker/Ubuntu2304.Dockerfile b/docker/Ubuntu2304.Dockerfile index 9e5964b..996ec5e 100644 --- a/docker/Ubuntu2304.Dockerfile +++ b/docker/Ubuntu2304.Dockerfile @@ -25,7 +25,7 @@ ENV PATH="$DOCKER_PYTHON_VENV/bin:$PATH" # Setup system and install packages COPY scripts/os/setup_ubuntu2304.sh /tmp/ -COPY requirements.txt /tmp/ +COPY pyproject.toml /tmp/ RUN cd /tmp && bash setup_ubuntu2304.sh && rm -rf ./* # Setup Conan diff --git a/docs/images/g/centos7.rst b/docs/images/g/centos7.rst index fe6db03..965146a 100644 --- a/docs/images/g/centos7.rst +++ b/docs/images/g/centos7.rst @@ -56,7 +56,7 @@ A C++ based image which contains all required and optional packages to build C++ Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. + Only ``conan`` package. *CI SCRIPTS* All CI scripts are included in this docker image. diff --git a/docs/images/g/centos8.rst b/docs/images/g/centos8.rst index 9051c06..5ad7e29 100644 --- a/docs/images/g/centos8.rst +++ b/docs/images/g/centos8.rst @@ -56,7 +56,7 @@ A C++ based image which contains all required and optional packages to build C++ Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. + Only ``conan`` package. *CI SCRIPTS* All CI scripts are included in this docker image. diff --git a/docs/images/g/ubuntu2004.rst b/docs/images/g/ubuntu2004.rst index 01facf9..3568197 100644 --- a/docs/images/g/ubuntu2004.rst +++ b/docs/images/g/ubuntu2004.rst @@ -50,7 +50,7 @@ A C++ based image which contains all required and optional packages to build C++ Only those which are listed in ``conan/conanfile.txt`` file. *PYTHON PACKAGES* - Mainly ``conan`` package and ``sphinx`` related packages. + Only ``conan`` package. *CI SCRIPTS* All CI scripts are included in this docker image. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..b02fdde --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,59 @@ +[project] +name = "3ct-packages" +version = "0.0.0" +requires-python = ">=3.8" + +dependencies = [ + # TODO(szinchen): 'pyyaml' is required by 'conan' and 'yamllint', but there + # is an issue occurred while resolving dependencies: + # - https://github.com/yaml/pyyaml/issues/601 + # For time being let's put this here. + "pyyaml~=5.3.1", +] + +[tool.setuptools] +packages = [] + +[project.optional-dependencies] +conan = [ + "conan==1.59.0", + # "conan==2.0.2", # TODO(szinchen): Replace when migration to Conan 2 is finished. +] +docs = [ + # base + "furo==2022.9.29", + "sphinx==4.5.0", + # c++ extensions + "breathe==4.32.0", + "exhale==0.2.4", + # extensions + "sphinx-copybutton", + "sphinx-design", + "sphinx-prompt==1.5.0", # NOTE(szinchen): >=1.6.0 requires Sphinx<7.0.0,>=6.0.0 + # resolving dependencies + "docutils==0.17.1", + "pygments==2.11.0", +] +linters = [ + "black", # python + "codespell", # common + "cmakelang", # cmake + # "cppcheck_codequality", # c++ + # "cppcheck_junit", # c++ + "flake8", # python + "flake8-bandit", # python + "flake8-builtins", # python + "flake8-bugbear", # python + "flake8-comprehensions", # python + "gcovr", # c++ + "guardonce", # c++ + "isort", # python + "licenseheaders", # common + "pep8-naming", # python + "rstcheck", # rst + "yamllint", # yaml +] +misc = [ + "dateparser", + "requests", +] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index a88da66..0000000 --- a/requirements.txt +++ /dev/null @@ -1,49 +0,0 @@ -# Build - -conan==1.59.0 -# TODO(szinchen): Replace when migration to Conan 2 is finished. -#conan==2.0.2 - -# Documentation - -breathe==4.32.0 -exhale==0.2.4 - -furo==2022.9.29 -sphinx==4.5.0 - -sphinx-copybutton -sphinx-design -sphinx-prompt==1.5.0 # >=1.6.0 requires Sphinx<7.0.0,>=6.0.0 - -# Linters - -black # python -codespell # common -cmakelang # cmake -# cppcheck_codequality # c++ -# cppcheck_junit # c++ -flake8 # python -flake8-bandit # python -flake8-builtins # python -flake8-bugbear # python -flake8-comprehensions # python -gcovr # c++ -guardonce # c++ -isort # python -licenseheaders # common -pep8-naming # python -rstcheck # rst -yamllint # yaml - -# Misc - -dateparser -requests - -# Resolving dependencies - -docutils==0.17.1 -pygments==2.11.0 - -pyyaml~=5.3.1 # TODO: https://github.com/yaml/pyyaml/issues/601 diff --git a/scripts/os/setup_alpine3.sh b/scripts/os/setup_alpine3.sh index db20d7b..1d90d8d 100644 --- a/scripts/os/setup_alpine3.sh +++ b/scripts/os/setup_alpine3.sh @@ -51,4 +51,4 @@ rm -rf /var/cache/apk/* # Python # #------------------------------------------------------------------------------# -pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir . '.[linters]' '.[misc]' diff --git a/scripts/os/setup_centos7.sh b/scripts/os/setup_centos7.sh index 456ba9a..55d7467 100644 --- a/scripts/os/setup_centos7.sh +++ b/scripts/os/setup_centos7.sh @@ -80,7 +80,7 @@ source /opt/rh/rh-python38/enable # Install packages -pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir . '.[conan]' pip3 install --no-cache-dir 'cmake==3.25.0' #------------------------------------------------------------------------------# diff --git a/scripts/os/setup_centos8.sh b/scripts/os/setup_centos8.sh index 6b9ff97..1ae8520 100644 --- a/scripts/os/setup_centos8.sh +++ b/scripts/os/setup_centos8.sh @@ -69,7 +69,7 @@ yum -y clean all --enablerepo='*' # Python # #------------------------------------------------------------------------------# -pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir . '.[conan]' #------------------------------------------------------------------------------# # Setup environment # diff --git a/scripts/os/setup_ubuntu2004.sh b/scripts/os/setup_ubuntu2004.sh index 70ab856..26ebe56 100644 --- a/scripts/os/setup_ubuntu2004.sh +++ b/scripts/os/setup_ubuntu2004.sh @@ -86,5 +86,5 @@ update-alternatives \ # Python # #------------------------------------------------------------------------------# -pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir . '.[conan]' pip3 install --no-cache-dir 'cmake==3.25.0' diff --git a/scripts/os/setup_ubuntu2304.sh b/scripts/os/setup_ubuntu2304.sh index dda1968..5dff588 100644 --- a/scripts/os/setup_ubuntu2304.sh +++ b/scripts/os/setup_ubuntu2304.sh @@ -105,5 +105,5 @@ if [[ -v DOCKER_PYTHON_VENV ]]; then fi fi -pip3 install --no-cache-dir -r 'requirements.txt' +pip3 install --no-cache-dir . '.[conan]' '.[docs]' '.[linters]' '.[misc]' pip3 install --no-cache-dir 'cmake==3.25.0' -- GitLab From 031ebf57c7fccc615ff51771b4896b9074e76bbc Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 18 Nov 2023 21:49:18 +0000 Subject: [PATCH 21/44] Add missing python packages for docs generation Tags: Alpine, Docker, Shell --- scripts/os/setup_alpine3.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/os/setup_alpine3.sh b/scripts/os/setup_alpine3.sh index 1d90d8d..e27ad0f 100644 --- a/scripts/os/setup_alpine3.sh +++ b/scripts/os/setup_alpine3.sh @@ -51,4 +51,4 @@ rm -rf /var/cache/apk/* # Python # #------------------------------------------------------------------------------# -pip3 install --no-cache-dir . '.[linters]' '.[misc]' +pip3 install --no-cache-dir . '.[docs]' '.[linters]' '.[misc]' -- GitLab From bfda560db505a002fdb44df69ce3ca6b3c0c6696 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 30 Oct 2022 15:15:56 +0200 Subject: [PATCH 22/44] Add new commit message checks - Check commit message for line length. - Check GitHub/GitLab, JIRA and "tags" section for simple formatting issues. Tags: Linters, Shell --- docs/pipelines/lang/common.rst | 22 ++++- scripts/cicd/lint/check_commit_messages.sh | 97 +++++++++++++++++++++- 2 files changed, 116 insertions(+), 3 deletions(-) diff --git a/docs/pipelines/lang/common.rst b/docs/pipelines/lang/common.rst index 1f56d8d..7fc3ab9 100644 --- a/docs/pipelines/lang/common.rst +++ b/docs/pipelines/lang/common.rst @@ -92,7 +92,27 @@ This job executes `codespell `__ check:commits:spelling ---------------------- -This job executes `codespell `__ on all found branch commits, which will detect common misspellings. +This job performs various checks on commit messages for all found branch commits. + +Below is a list of implemented checks. + +- Check for common misspellings. +- Check that subject and body don't exceed 80 symbols limit. +- Check that GitHub issue references list follows ``GitHub: #1, #2, ...`` format. +- Check that GitHub issue references list follows ``GitLab: #1, #2, ...`` format. +- Check that JIRA issues list follows ``Jira: PROJ-1, PROJ-2, ...`` format. +- Check that tags list follows ``Tags: Bar, Foo, ...`` format. + +Here is an example of a valid message: + + | Fix foo to enable bar + | + | This fixes the broken behavior of the component by doing xyz. + | + | GitHub: #42, #43 + | GitLab: #315, #316 + | Jira: PROJ-101 + | Tags: Bar, Foo *ARTIFACTS* Job will generate a simple log file with all found issues. diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index 5188da5..3c9c228 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -37,6 +37,37 @@ elif [[ -n "${BPROTO_CODESPELL_CFG}" ]]; then declare -r SETTINGS_FILE="${BPROTO_CODESPELL_CFG}" fi +# FMI: +# - https://www.jessesquires.com/blog/2017/08/08/customizing-git-log/ +# - https://stackoverflow.com/questions/33806068 +# - https://stackoverflow.com/questions/76120184 +GIT_PRETTY_LOG_FORMAT=' +commit %C(bold magenta)%H%Creset +Author: %C(bold blue)%an%Creset %C(blue)<%ae>%Creset +Date: %C(bold cyan)%cd %Creset + +%w(120,4,4)%-B%Creset +' + +####################################### +# Extract a trailer part of a commit message with a specified key. +# for typos. +# Arguments: +# $1 - a trailer key +# $2 - a commit hash +# Outputs: +# A content of a specific trailer with new lines and indentation removed. +####################################### +get_trailer() +{ + local -r key="${1}" + local -r commit="${2}" + + # NOTE(b110011): Remove new lines and make one long string. + # If indentation is wrong, we will still get an error when grepping. + git log --format="%(trailers:key=${key})" -n1 "${commit}" | sed -z "s/ \n/,/g" +} + ####################################### # Extract all commits from HEAD of current branch to its parent and check them # for typos. @@ -63,6 +94,16 @@ check() for commit in $(git rev-list "origin/${target_branch}..HEAD"); do git log -n 1 "${commit}" > "${COMMIT_MSG_FILE}" + local -i is_commit_message_logged=0 + log_commit_message() + { + if [[ ${is_commit_message_logged} -eq 0 ]]; then + is_commit_message_logged=1 + + git log --color=always --pretty=format:"${GIT_PRETTY_LOG_FORMAT}" -n1 "${commit}" + fi + } + codespell \ --config "${SETTINGS_FILE}" \ --enable-colors \ @@ -70,11 +111,63 @@ check() > "${CODESPELL_LOG_FILE}" || true if [[ -s "${CODESPELL_LOG_FILE}" ]]; then - cat "${COMMIT_MSG_FILE}" - echo "" + log_commit_message cat "${CODESPELL_LOG_FILE}" echo "" + + continue + fi + + # FMI: https://unix.stackexchange.com/questions/42898 + local long_lines + long_lines="$(git log --pretty=format:"%B" -n1 "${commit}" | grep '^.\{80\}' --color=always)" + if [[ -n "${long_lines}" ]]; then + log_commit_message + echo -e "\033[0;31mBelow lines contain more than 80 symbols:\033[0m" + echo " - ${long_lines//$'\n'/$'\n' - }" # Prepend ' - ' to each line. fi + + check_trailer() + { + local -r key="${1}" + local -r regex="${2}" + local -r message="${3}" + local -r allowed_format="${4}" + + local -r line="$(get_trailer "${key}" "${commit}")" + if [[ -n "${line}" ]]; then + local -r matched_line="$(grep -Eo "${regex}" <<< "${line}")" + if [ "${matched_line}" != "${line}" ]; then + log_commit_message + echo -e "\033[0;31m${message}\033[0m" + echo -e " \033[0;33mAllowed format: ${allowed_format}.\033[0m" + fi + fi + } + + check_trailer \ + 'GitHub' \ + 'GitHub: (#[0-9]+(, ){0,}){0,}' \ + 'Invalid format of GitHub issue references!' \ + 'GitHub: #1, #2' + + check_trailer \ + 'GitLab' \ + 'GitLab: (#[0-9]+(, ){0,}){0,}' \ + 'Invalid format of GitLab issue references!' \ + 'GitLab: #1, #2' + + check_trailer \ + 'Jira' \ + 'Jira: ([a-zA-Z]+-[0-9]+(, ){0,}){0,}' \ + 'Invalid format of JIRA ticket IDs!' \ + 'Jira: MO-1, MO-10' + + check_trailer \ + 'Tags' \ + 'Tags: ([a-zA-Z]+(, ){0,}){0,}' \ + 'Invalid format of commit message tags!' \ + 'Tags: TagA, TagB' done # Restore output to terminal. -- GitLab From d9e32ff227392ae989185043964b72bae736c725 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 19 Nov 2023 00:13:10 +0200 Subject: [PATCH 23/44] Fix small typos Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 2 +- scripts/cicd/lint/filter_files.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index 3c9c228..ca44f14 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -44,7 +44,7 @@ fi GIT_PRETTY_LOG_FORMAT=' commit %C(bold magenta)%H%Creset Author: %C(bold blue)%an%Creset %C(blue)<%ae>%Creset -Date: %C(bold cyan)%cd %Creset +Date: %C(bold cyan)%cd%Creset %w(120,4,4)%-B%Creset ' diff --git a/scripts/cicd/lint/filter_files.sh b/scripts/cicd/lint/filter_files.sh index e54777b..caa9d68 100644 --- a/scripts/cicd/lint/filter_files.sh +++ b/scripts/cicd/lint/filter_files.sh @@ -43,7 +43,7 @@ filter() modified_files="$(git diff-tree --name-only -r "HEAD..origin/${target_branch}" \ | grep -v '3rd-party' | sort)" - # Exclude all deleted filed. + # Exclude all deleted files. while IFS="" read -r file || [[ -n "${file}" ]]; do if [ -r "${file}" ]; then echo "${file}" -- GitLab From f133e59c1200fd3d04fa36b2c915585177ef2270 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 19 Nov 2023 00:22:36 +0200 Subject: [PATCH 24/44] Add a VS Code extension for TOML Tags: VS Code --- .vscode/extensions.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index f3a3e6d..794b3d5 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -16,6 +16,8 @@ "ms-vscode.cmake-tools", // Spelling checker for source code "streetsidesoftware.code-spell-checker", + // Fully-featured TOML support + "tamasfe.even-better-toml", // CMake language support for Visual Studio Code "twxs.cmake", // Syntax highlighting and document symbols for reStructuredText -- GitLab From 8c24748835464c624603bdf87e5769264fbe4c1e Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 19 Nov 2023 01:41:44 +0200 Subject: [PATCH 25/44] Remove scripts for linters from "thin" docker images Tags: CentOS7, CentOS8, Dockers, Ubuntu2004 --- docker/CentOS7.Dockerfile | 6 ------ docker/CentOS8.Dockerfile | 6 ------ docker/Ubuntu2004.Dockerfile | 8 -------- 3 files changed, 20 deletions(-) diff --git a/docker/CentOS7.Dockerfile b/docker/CentOS7.Dockerfile index ca33027..941ab55 100644 --- a/docker/CentOS7.Dockerfile +++ b/docker/CentOS7.Dockerfile @@ -66,9 +66,3 @@ RUN cd /tmp && bash fetch.sh && rm -rf ./* # Remove all temporary files RUN rm -rf /tmp/* - -# Install CI/CD scripts and linters config files - -COPY scripts/os/install_files.sh /tmp/ -COPY .* scripts/cicd/*.* scripts/cicd/*/* /tmp/ -RUN bash /tmp/install_files.sh && rm -rf /tmp/* diff --git a/docker/CentOS8.Dockerfile b/docker/CentOS8.Dockerfile index c87a59e..1682fb3 100644 --- a/docker/CentOS8.Dockerfile +++ b/docker/CentOS8.Dockerfile @@ -43,9 +43,3 @@ RUN cd /tmp && bash fetch.sh && rm -rf ./* # Remove all temporary files RUN rm -rf /tmp/* - -# Install CI/CD scripts and linters config files - -COPY scripts/os/install_files.sh /tmp/ -COPY .* scripts/cicd/*.* scripts/cicd/*/* /tmp/ -RUN bash /tmp/install_files.sh && rm -rf /tmp/* diff --git a/docker/Ubuntu2004.Dockerfile b/docker/Ubuntu2004.Dockerfile index a70af04..d788190 100644 --- a/docker/Ubuntu2004.Dockerfile +++ b/docker/Ubuntu2004.Dockerfile @@ -40,11 +40,3 @@ RUN cd /tmp && bash fetch.sh && rm -rf ./* # Remove all temporary files RUN rm -rf /tmp/* - -# Install CI/CD scripts and linters config files - -COPY scripts/os/install_files.sh /tmp/ -COPY .* scripts/cicd/*.* scripts/cicd/*/* /tmp/ -RUN bash /tmp/install_files.sh && rm -rf /tmp/* - -ENV BASH_ENV "/etc/profile" -- GitLab From 7bb40c3ac727a8b6955316948192a61209522f9b Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 19 Nov 2023 01:45:26 +0200 Subject: [PATCH 26/44] Update tags list for commit messages Tags: Docs --- docs/git/tags.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/git/tags.rst b/docs/git/tags.rst index 6dc30f4..0e946e0 100644 --- a/docs/git/tags.rst +++ b/docs/git/tags.rst @@ -90,9 +90,13 @@ That why it's hard to collect all possible cases when a particular tag should be +---------------------------+--------+----------------------------------------+ | Linux | Yes | | +---------------------------+--------+----------------------------------------+ - | Ubuntu 20.04 | Yes | | + | *Ubuntu 20.04* | **No** | | + + +--------+ + + | Ubuntu2004 | Yes | | +---------------------------+--------+----------------------------------------+ - | Ubuntu 23.04 | Yes | | + | *Ubuntu 23.04* | **No** | | + + +--------+ + + | Ubuntu2304 | Yes | | +---------------------------+--------+----------------------------------------+ | Windows | Yes | | +---------------------------+--------+----------------------------------------+ -- GitLab From 99b40e28666faad41f33f7fe4071a63b00493739 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 19 Nov 2023 22:56:59 +0200 Subject: [PATCH 27/44] Fix return code for commit messages linter Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index ca44f14..233337b 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -84,6 +84,7 @@ get_trailer() check() { local -r target_branch="${1}" + local -i failed=0 git fetch origin "${target_branch}" @@ -97,6 +98,8 @@ check() local -i is_commit_message_logged=0 log_commit_message() { + failed=1 # If we need to call this method, we have hit a jackpot. + if [[ ${is_commit_message_logged} -eq 0 ]]; then is_commit_message_logged=1 @@ -184,7 +187,7 @@ check() # Fail if there are some changes # shellcheck disable=SC2046 - exit $(grep -c "commit.txt" "${LOG_FILE}") + exit ${failed} } ####################################### -- GitLab From e2499f4c05e5460318a013320982e5733ef1aa42 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 00:03:07 +0200 Subject: [PATCH 28/44] Check that values for commit message trailer are sorted GitLab: #25 Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 39 ++++++++++++++++++---- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index 233337b..dea54d7 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -51,7 +51,6 @@ Date: %C(bold cyan)%cd%Creset ####################################### # Extract a trailer part of a commit message with a specified key. -# for typos. # Arguments: # $1 - a trailer key # $2 - a commit hash @@ -68,6 +67,22 @@ get_trailer() git log --format="%(trailers:key=${key})" -n1 "${commit}" | sed -z "s/ \n/,/g" } +####################################### +# Sort line values in ascending order. +# Arguments: +# $1 - input line +# $2 - values delimiter (default: ', ') +# Outputs: +# A line with sorted values. +####################################### +sort_inplace() +{ + local -r line="${1}" + local -r delim="${2:-, }" + + echo "${line}" | sed "s|${delim}|\n|g" | sort | sed ':a;N;$!ba;s|\n|'"${delim}"'|g' +} + ####################################### # Extract all commits from HEAD of current branch to its parent and check them # for typos. @@ -142,8 +157,18 @@ check() local -r matched_line="$(grep -Eo "${regex}" <<< "${line}")" if [ "${matched_line}" != "${line}" ]; then log_commit_message - echo -e "\033[0;31m${message}\033[0m" - echo -e " \033[0;33mAllowed format: ${allowed_format}.\033[0m" + echo -e "\033[0;31mInvalid format of ${message}! \033[0m" + echo -e " \033[0;33mAllowed format: ${allowed_format}\033[0m" + + return # Stop here because we might not be able to correctly perform next check. + fi + + local -r trailer_values=${line#"${key}: "} # Remove key from line. + local -r sorted_trailer_values="$(sort_inplace "${trailer_values}")" + if [[ "${sorted_trailer_values}" != "${trailer_values}" ]]; then + log_commit_message + echo -e "\033[0;31m${message^} are not properly sorted! \033[0m" + echo -e " \033[0;33mCorrent order: ${sorted_trailer_values}\033[0m" fi fi } @@ -151,25 +176,25 @@ check() check_trailer \ 'GitHub' \ 'GitHub: (#[0-9]+(, ){0,}){0,}' \ - 'Invalid format of GitHub issue references!' \ + 'GitHub issue references' \ 'GitHub: #1, #2' check_trailer \ 'GitLab' \ 'GitLab: (#[0-9]+(, ){0,}){0,}' \ - 'Invalid format of GitLab issue references!' \ + 'GitLab issue references' \ 'GitLab: #1, #2' check_trailer \ 'Jira' \ 'Jira: ([a-zA-Z]+-[0-9]+(, ){0,}){0,}' \ - 'Invalid format of JIRA ticket IDs!' \ + 'JIRA ticket IDs' \ 'Jira: MO-1, MO-10' check_trailer \ 'Tags' \ 'Tags: ([a-zA-Z]+(, ){0,}){0,}' \ - 'Invalid format of commit message tags!' \ + 'commit message tags' \ 'Tags: TagA, TagB' done -- GitLab From 078d200c072d6fb7f69ca07b947b5d81f9bc3d14 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 00:55:17 +0200 Subject: [PATCH 29/44] Fix always failing commit messages linter Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index dea54d7..8a32207 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -132,13 +132,12 @@ check() log_commit_message cat "${CODESPELL_LOG_FILE}" echo "" - - continue fi # FMI: https://unix.stackexchange.com/questions/42898 - local long_lines - long_lines="$(git log --pretty=format:"%B" -n1 "${commit}" | grep '^.\{80\}' --color=always)" + # NOTE(b110011): Doing as shellcheck suggests breaking the script. + # shellcheck disable=SC2155 + local long_lines="$(git log --pretty=format:"%B" -n1 "${commit}" | grep '^.\{80\}' --color=always)" if [[ -n "${long_lines}" ]]; then log_commit_message echo -e "\033[0;31mBelow lines contain more than 80 symbols:\033[0m" -- GitLab From dd5aa00810a04f5381721b5924ca653d22f87f75 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 01:06:19 +0200 Subject: [PATCH 30/44] Replace usernames with correct ones --- pyproject.toml | 6 +++--- scripts/cicd/lint/check_cpp_conventions.sh | 4 ++-- scripts/cicd/lint/check_python_imports.sh | 2 +- scripts/conan/fetch.sh | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index b02fdde..8d39900 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ version = "0.0.0" requires-python = ">=3.8" dependencies = [ - # TODO(szinchen): 'pyyaml' is required by 'conan' and 'yamllint', but there + # TODO(b110011): 'pyyaml' is required by 'conan' and 'yamllint', but there # is an issue occurred while resolving dependencies: # - https://github.com/yaml/pyyaml/issues/601 # For time being let's put this here. @@ -17,7 +17,7 @@ packages = [] [project.optional-dependencies] conan = [ "conan==1.59.0", - # "conan==2.0.2", # TODO(szinchen): Replace when migration to Conan 2 is finished. + # "conan==2.0.2", # TODO(b110011): Replace when migration to Conan 2 is finished. ] docs = [ # base @@ -29,7 +29,7 @@ docs = [ # extensions "sphinx-copybutton", "sphinx-design", - "sphinx-prompt==1.5.0", # NOTE(szinchen): >=1.6.0 requires Sphinx<7.0.0,>=6.0.0 + "sphinx-prompt==1.5.0", # NOTE(b110011): >=1.6.0 requires Sphinx<7.0.0,>=6.0.0 # resolving dependencies "docutils==0.17.1", "pygments==2.11.0", diff --git a/scripts/cicd/lint/check_cpp_conventions.sh b/scripts/cicd/lint/check_cpp_conventions.sh index d2516e8..3f4b036 100644 --- a/scripts/cicd/lint/check_cpp_conventions.sh +++ b/scripts/cicd/lint/check_cpp_conventions.sh @@ -51,7 +51,7 @@ if [[ -s "${DEFAULT_CLANGTIDY_CFG}" ]]; then elif [[ -n "${BPROTO_CLANGTIDY_CFG}" ]]; then declare -r CLANGTIDY_CFG="${BPROTO_CLANGTIDY_CFG}" - # TODO(szinchen): This is a workaround for currunt clang-tidy scripts. + # TODO(b110011): This is a workaround for currunt clang-tidy scripts. # Even so 'run-clang-tidy' supports '-config-file', 'clang-tidy-diff' # still doesn't know about this. Therefore it's better to use same # approach for both tools. @@ -64,7 +64,7 @@ else exit 1 fi -# NOTE(szinchen): gmock in gtest/1.11.0 generated some errors in "merge request" +# NOTE(b110011): gmock in gtest/1.11.0 generated some errors in "merge request" # mode, so we want to disable them and clean our pipeline. declare -r DISABLED_GMOCK_CHECKS=( "misc-non-private-member-variables-in-classes" diff --git a/scripts/cicd/lint/check_python_imports.sh b/scripts/cicd/lint/check_python_imports.sh index 809ad78..7849079 100644 --- a/scripts/cicd/lint/check_python_imports.sh +++ b/scripts/cicd/lint/check_python_imports.sh @@ -58,7 +58,7 @@ check() bat --color=always -pp "${PATCH_FILE}" # Make generated patch more GITish - # NOTE(szinchen): To apply generated patch run: + # NOTE(b110011): To apply generated patch run: # git apply -p0 isort.patch sed -i -e 's/:before//g' -e 's/:after//g' "${PATCH_FILE}" diff --git a/scripts/conan/fetch.sh b/scripts/conan/fetch.sh index 63ab2cf..b791971 100644 --- a/scripts/conan/fetch.sh +++ b/scripts/conan/fetch.sh @@ -49,7 +49,7 @@ fetch() return fi - # NOTE(szinchen): We need both '-if' and '-of' due to + # NOTE(b110011): We need both '-if' and '-of' due to # https://github.com/conan-io/conan/issues/11483. conan install . -if build -of build --build=missing \ -pr:b "${cc}" \ @@ -64,7 +64,7 @@ fetch() # https://stackoverflow.com/questions/50247671 conan remove "*" -s -f - # TODO(szinchen): Replace when migration to Conan 2 is finished. + # TODO(b110011): Replace when migration to Conan 2 is finished. # https://docs.conan.io/2/reference/commands/cache.html#conan-cache-clean # https://github.com/conan-io/conan/issues/11562 # conan cache clean "*" -b -d -s @@ -77,7 +77,7 @@ fetch() ####################################### main() { - # TODO(szinchen): Uncomment when migration to Conan 2 is finished. + # TODO(b110011): Uncomment when migration to Conan 2 is finished. # conan profile detect fetch 'clang' 'clang++' 'Debug' -- GitLab From 395c8fff3826f01d89280ad1786851ce0f2c96d9 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 01:20:01 +0200 Subject: [PATCH 31/44] Provide a link to index page of Shpinx HTML artifacts GitLab: #24 Tags: CI, Docs, Shpinx --- .gitlab/ci/docs/sphinx.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.gitlab/ci/docs/sphinx.yml b/.gitlab/ci/docs/sphinx.yml index 13b85b9..aa26412 100644 --- a/.gitlab/ci/docs/sphinx.yml +++ b/.gitlab/ci/docs/sphinx.yml @@ -46,11 +46,15 @@ report:docs: script: - mv build/* . - rm -rf build + environment: + name: sphinx-html-docs-$CI_COMMIT_REF_SLUG + url: https://${CI_PROJECT_ROOT_NAMESPACE}.${CI_PAGES_DOMAIN}/-/${CI_PROJECT_NAME}/-/jobs/${CI_JOB_ID}/artifacts/index.html + auto_stop_in: 1 day artifacts: when: always expire_in: 1 day - expose_as: 'HTML Documentation' - name: "HtmlDocs-$CI_COMMIT_REF_SLUG" + expose_as: 'Sphinx HTML Documentation' + name: "SphinxHtmlDocs-$CI_COMMIT_REF_SLUG" paths: - ./ -- GitLab From be705cbf5bcb3cd7aaa951bde66a7f2f1c432fd4 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 01:45:14 +0200 Subject: [PATCH 32/44] Provide a link to index page of Coverage HTML artifacts GitLab: #24 Tags: CI, Coverage, Cpp, Linters --- .gitlab/ci/lang/cpp/lint/coverage.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitlab/ci/lang/cpp/lint/coverage.yml b/.gitlab/ci/lang/cpp/lint/coverage.yml index 753f705..e555886 100644 --- a/.gitlab/ci/lang/cpp/lint/coverage.yml +++ b/.gitlab/ci/lang/cpp/lint/coverage.yml @@ -57,6 +57,10 @@ report:cpp:coverage: script: - mv build/coverage/* . - rm -rf build + environment: + name: coverage-html-docs-$CI_COMMIT_REF_SLUG + url: https://${CI_PROJECT_ROOT_NAMESPACE}.${CI_PAGES_DOMAIN}/-/${CI_PROJECT_NAME}/-/jobs/${CI_JOB_ID}/artifacts/coverage.html + auto_stop_in: 1 day artifacts: when: always expire_in: 1 day -- GitLab From 4a43061f97c0d4b135edcb7f3bc698473fc9a03c Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 01:49:20 +0200 Subject: [PATCH 33/44] Provide a link to index page of CppCheck HTML artifacts GitLab: #24 Tags: CI, CppCheck, Cpp, Linters --- .gitlab/ci/lang/cpp/lint/cppcheck.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitlab/ci/lang/cpp/lint/cppcheck.yml b/.gitlab/ci/lang/cpp/lint/cppcheck.yml index 85e142e..8def54c 100644 --- a/.gitlab/ci/lang/cpp/lint/cppcheck.yml +++ b/.gitlab/ci/lang/cpp/lint/cppcheck.yml @@ -52,6 +52,10 @@ report:cpp:cppcheck: script: - mv build/cppcheck_results/* . - rm -rf build + environment: + name: cppcheck-html-docs-$CI_COMMIT_REF_SLUG + url: https://${CI_PROJECT_ROOT_NAMESPACE}.${CI_PAGES_DOMAIN}/-/${CI_PROJECT_NAME}/-/jobs/${CI_JOB_ID}/artifacts/index.html + auto_stop_in: 1 day artifacts: when: always expire_in: 1 day -- GitLab From efaca7649045b58fc8af4c33563ae0190efc628b Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 02:43:21 +0200 Subject: [PATCH 34/44] Remove invalid option from 'sed' command Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index 8a32207..2455ce8 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -64,7 +64,7 @@ get_trailer() # NOTE(b110011): Remove new lines and make one long string. # If indentation is wrong, we will still get an error when grepping. - git log --format="%(trailers:key=${key})" -n1 "${commit}" | sed -z "s/ \n/,/g" + git log --format="%(trailers:key=${key})" -n1 "${commit}" | sed "s/ \n/,/g" } ####################################### -- GitLab From 4be35b02e8cc389262cb74de3601724097746b7f Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Mon, 20 Nov 2023 02:48:52 +0200 Subject: [PATCH 35/44] Mark shell variable as readonly Tags: Linters, Shell --- scripts/cicd/lint/check_commit_messages.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/cicd/lint/check_commit_messages.sh b/scripts/cicd/lint/check_commit_messages.sh index 2455ce8..f772575 100644 --- a/scripts/cicd/lint/check_commit_messages.sh +++ b/scripts/cicd/lint/check_commit_messages.sh @@ -41,7 +41,7 @@ fi # - https://www.jessesquires.com/blog/2017/08/08/customizing-git-log/ # - https://stackoverflow.com/questions/33806068 # - https://stackoverflow.com/questions/76120184 -GIT_PRETTY_LOG_FORMAT=' +declare -r GIT_PRETTY_LOG_FORMAT=' commit %C(bold magenta)%H%Creset Author: %C(bold blue)%an%Creset %C(blue)<%ae>%Creset Date: %C(bold cyan)%cd%Creset -- GitLab From 278cfb4b44fa9f4e3aac2758fde0612373ee1594 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 25 Nov 2023 02:41:36 +0200 Subject: [PATCH 36/44] Add missing information for misc jobs Tags: CI, Docs --- docs/pipelines/misc.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/pipelines/misc.rst b/docs/pipelines/misc.rst index 852ff2e..bb7bc12 100644 --- a/docs/pipelines/misc.rst +++ b/docs/pipelines/misc.rst @@ -14,6 +14,9 @@ remove_old_pipelines This job executes a custom script that removes outdated pipelines from project pipeline list. +*ARTIFACTS* + Job doesn't generate any artifacts. + *ENVIRONMENT* .. list-table:: @@ -28,6 +31,10 @@ This job executes a custom script that removes outdated pipelines from project p - Mandatory - + * - BPROTO_CI_ENABLE_PIPELINES_CLEANUP + - Mandatory + - + * - BPROTO_CI_GENERIC_PACKAGES_REGISTRY - Mandatory - -- GitLab From 415b9bf2d856fcb529aeb188506eb8e12d5abdc1 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 25 Nov 2023 02:42:05 +0200 Subject: [PATCH 37/44] Fix description for one of linter scripts Tags: Cpp, Linters, Shell --- scripts/cicd/lint/check_cpp_include_guards.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/cicd/lint/check_cpp_include_guards.sh b/scripts/cicd/lint/check_cpp_include_guards.sh index 454b71d..90444c2 100644 --- a/scripts/cicd/lint/check_cpp_include_guards.sh +++ b/scripts/cicd/lint/check_cpp_include_guards.sh @@ -16,7 +16,7 @@ # # DESCRIPTION: # -# Check C++ header file for correct include guard with help of a guardonce. +# Extract C++ header files and check for correct format of include guards. # # ATTENTION: # @@ -107,7 +107,7 @@ print_files() } ####################################### -# Main entry point for this script. +# Extract C++ files and check their include guards. # Globals: # API_DIRS # LOG_FILENAME -- GitLab From ccf564429be5aea407a6b1bbec538a500819eb46 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 25 Nov 2023 02:47:15 +0200 Subject: [PATCH 38/44] Place cpp linters in alphabet order Tags: Cpp, Docs, Linters --- docs/pipelines/lang/cpp/linters.rst | 108 ++++++++++++++-------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index 56b0889..0eedc0e 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -91,6 +91,60 @@ report:cpp:coverage *TRIGGERS* Job is triggered only on **merge requests** and only if :ref:`linters-pipeline-check-cpp-coverage` job has failed. +.. _pipeline-lang-cpp-linters-cppcheck: + +check:cpp:cppcheck +------------------ + +This job executes `cppcheck `__ *only on changed C++ files* (not diff, but files) which detect bugs and focuses on detecting undefined behavior and dangerous coding constructs. + +*ARTIFACTS* + Job will generate a set of files suitable for generating an HTML report. + +*CONFIG* + Configuration file is located at the root of the repository and has ``.cppcheck`` name. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_CMAKE_GLOBAL_ARGS + - Mandatory + +*IMAGES* + :ref:`ubuntu2304:latest `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + As this job is a `manual one `_, it can be triggered only by a user. + +report:cpp:cppcheck +------------------- + +*ARTIFACTS* + Job produces a statically generated HTML reports using ``cppcheck-htmlreport`` from the `cppcheck `__ package. + +*DEPENDENCIES* + Jobs require artifacts from :ref:`pipeline-lang-cpp-linters-cppcheck` job. + +*IMAGES* + `alpine:3 `__. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** and only if :ref:`pipeline-lang-cpp-linters-cppcheck` job has failed. + .. _pipeline-lang-cpp-linters-format: check:cpp:format @@ -196,60 +250,6 @@ This job executes ``checkguard`` from `guardonce ` is changed. -.. _pipeline-lang-cpp-linters-cppcheck: - -check:cpp:cppcheck ------------------- - -This job executes `cppcheck `__ *only on changed C++ files* (not diff, but files) which detect bugs and focuses on detecting undefined behavior and dangerous coding constructs. - -*ARTIFACTS* - Job will generate a set of files suitable for generating an HTML report. - -*CONFIG* - Configuration file is located at the root of the repository and has ``.cppcheck`` name. - -*DEPENDENCIES* - Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. - -*ENVIRONMENT* - -.. list-table:: - :header-rows: 1 - - * - Name - - Necessity - - * - BPROTO_CI_CMAKE_GLOBAL_ARGS - - Mandatory - -*IMAGES* - :ref:`ubuntu2304:latest `. - -*STAGE* - :ref:`overview-stages-check-stage`. - -*TRIGGERS* - As this job is a `manual one `_, it can be triggered only by a user. - -report:cpp:cppcheck -------------------- - -*ARTIFACTS* - Job produces a statically generated HTML reports using ``cppcheck-htmlreport`` from the `cppcheck `__ package. - -*DEPENDENCIES* - Jobs require artifacts from :ref:`pipeline-lang-cpp-linters-cppcheck` job. - -*IMAGES* - `alpine:3 `__. - -*STAGE* - :ref:`overview-stages-check-stage`. - -*TRIGGERS* - Job is triggered only on **merge requests** and only if :ref:`pipeline-lang-cpp-linters-cppcheck` job has failed. - .. _pipeline-lang-cpp-linters-tidy: check:cpp:tidy -- GitLab From d5a85bba35802d133e3e94a8a05c98b01e2211c5 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 25 Nov 2023 02:48:33 +0200 Subject: [PATCH 39/44] Add a new CI job to find iostream headers Tags: CI, Cpp, Docs, Linters, Shell --- .gitlab/ci/external/cpp.yml | 1 + .gitlab/ci/index.yml | 1 + .gitlab/ci/lang/cpp/lint/iostream.yml | 20 +++++ docs/pipelines/lang/cpp/linters.rst | 56 ++++++++++++++ scripts/cicd/lint/check_cpp_iostream.sh | 97 +++++++++++++++++++++++++ 5 files changed, 175 insertions(+) create mode 100644 .gitlab/ci/lang/cpp/lint/iostream.yml create mode 100644 scripts/cicd/lint/check_cpp_iostream.sh diff --git a/.gitlab/ci/external/cpp.yml b/.gitlab/ci/external/cpp.yml index e8c6820..b114403 100644 --- a/.gitlab/ci/external/cpp.yml +++ b/.gitlab/ci/external/cpp.yml @@ -28,4 +28,5 @@ include: - '/.gitlab/ci/lang/cpp/lint/clang_tools.yml' - '/.gitlab/ci/lang/cpp/lint/coverage.yml' - '/.gitlab/ci/lang/cpp/lint/cppcheck.yml' + - '/.gitlab/ci/lang/cpp/lint/iostream.yml' - '/.gitlab/ci/lang/cpp/lint/guardonce.yml' diff --git a/.gitlab/ci/index.yml b/.gitlab/ci/index.yml index c6da9ec..13fecfd 100644 --- a/.gitlab/ci/index.yml +++ b/.gitlab/ci/index.yml @@ -41,6 +41,7 @@ include: - local: '/.gitlab/ci/lang/cpp/lint/clang_tools.yml' - local: '/.gitlab/ci/lang/cpp/lint/coverage.yml' - local: '/.gitlab/ci/lang/cpp/lint/cppcheck.yml' + - local: '/.gitlab/ci/lang/cpp/lint/iostream.yml' - local: '/.gitlab/ci/lang/cpp/lint/guardonce.yml' - local: '/.gitlab/ci/lang/docker/lint/hadolint.yml' - local: '/.gitlab/ci/lang/py/base.yml' diff --git a/.gitlab/ci/lang/cpp/lint/iostream.yml b/.gitlab/ci/lang/cpp/lint/iostream.yml new file mode 100644 index 0000000..d0e5b51 --- /dev/null +++ b/.gitlab/ci/lang/cpp/lint/iostream.yml @@ -0,0 +1,20 @@ +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +check:cpp:iostream: + extends: + - .check + - .only-review-cpp + script: + - check_cpp_iostream.sh diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index 0eedc0e..1c4306f 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -250,6 +250,62 @@ This job executes ``checkguard`` from `guardonce ` is changed. +check:cpp:iostream +------------------ + +This job executes a simple shell script to find files that includes `iostream `__ library header and report them. + +**Preface** + +.. https://stackoverflow.com/questions/189562 + +.. epigraph:: + + "The most effective debugging tool is still careful thought, coupled with judiciously placed print statements." + + -- Brian Kernighan, "Unix for Beginners" (1979) + +``printf()`` debugging - useful and powerful technique. That said I often forget to remove redundant ```` header after debugging is done. + +It might sound as a small issue however including the ```` header can significantly impact compile time, as it is one of the heaviest standard C++ headers. + +**Suppressing warnings** + +If you need to silence the warning, you can put ``// ignore`` comment on the same line as an ``include`` directive. + +.. code-block:: cpp + + #include // ignore + +*ARTIFACTS* + Job doesn't generate any artifacts. + +*DEPENDENCIES* + Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. + +*ENVIRONMENT* + +.. list-table:: + :header-rows: 1 + + * - Name + - Necessity + + * - BPROTO_CI_LINTER_TRACE + - Optional + + * - BPROTO_CI_MERGE_REQUEST_CHANGED_FILES + - Mandatory + +*IMAGES* + :ref:`alpine:3 `. + +*STAGE* + :ref:`overview-stages-check-stage`. + +*TRIGGERS* + Job is triggered only on **merge requests** when any file from :ref:`trigger list ` is changed. + .. _pipeline-lang-cpp-linters-tidy: check:cpp:tidy diff --git a/scripts/cicd/lint/check_cpp_iostream.sh b/scripts/cicd/lint/check_cpp_iostream.sh new file mode 100644 index 0000000..e1dd9d2 --- /dev/null +++ b/scripts/cicd/lint/check_cpp_iostream.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash + +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# DESCRIPTION: +# +# Extract C++ files and check for inclusion of iostream file. +# +# ATTENTION: +# +# This script is mainly supposed to be used only by CI/CD linter jobs. + +set -e + +####################################### +# Find all 'iosteam' includes in a file. +# Arguments: +# $1 - a file path +# Outputs: +# Writes all found typos to stdout and to a log file. +# Note: +# We don't handle ignored includes here. +####################################### +find_iostream() +{ + grep -Hn -e '#include ' -e '#include "iostream"' --color=always "${1}" +} + +####################################### +# Extract C++ files and check them for iostream file inclusion. +# Globals: +# BPROTO_CI_LINTER_TRACE +# Arguments: +# $1 - a list of files to be checked +# Outputs: +# Writes all found typos to stdout and to a log file. +####################################### +check() +{ + local -i found=0 + + # Extract C++ header files if any. + local -r changed_files="$(echo "${2}" | grep -E ".*\.[chi]pp$")" + + if [[ -n "${changed_files}" ]]; then + if [[ "${BPROTO_CI_LINTER_TRACE}" == "true" ]]; then + echo -e "\033[0;33mDetected changes in ${changed_files}\033[0m" + fi + + while IFS= read -r file; do + if find_iostream "${file}" | grep -v "// ignore"; then + found=1 + fi + done <<< "${changed_files}" + fi + + # Fail if there are some changes + exit ${found} +} + +####################################### +# Main entry point for this script. +# Globals: +# BPROTO_CI_MERGE_REQUEST_CHANGED_FILES +# Arguments: +# $1 - a list of files to be checked +####################################### +main() +{ + if [[ -n "${1}" ]]; then + check "${1}" + elif [[ -v BPROTO_CI_MERGE_REQUEST_CHANGED_FILES ]]; then + # Variable can exist but is empty. + if [[ -n "${BPROTO_CI_MERGE_REQUEST_CHANGED_FILES}" ]]; then + check "${BPROTO_CI_MERGE_REQUEST_CHANGED_FILES}" + else + echo -e "\033[0;33mNo useful changes have been detected in files!\033[0m" + fi + else + echo -e "\033[0;31mFailed to detect modified files!\033[0m" >&2 + exit 1 + fi +} + +main "$@" -- GitLab From 40003c9709ff4b1bc8d135c70eef899ecd5b2e69 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sat, 25 Nov 2023 02:58:02 +0200 Subject: [PATCH 40/44] Fix shell checker warnings Tags: Cpp, Linters, Shell --- scripts/cicd/lint/check_cpp_include_guards.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/cicd/lint/check_cpp_include_guards.sh b/scripts/cicd/lint/check_cpp_include_guards.sh index 90444c2..3a95516 100644 --- a/scripts/cicd/lint/check_cpp_include_guards.sh +++ b/scripts/cicd/lint/check_cpp_include_guards.sh @@ -76,7 +76,7 @@ check_api_file() local -r dir_type="$(echo "${file}" | grep -Eo "${SPECIAL_DIRS}")" # https://wiki.bash-hackers.org/syntax/pe - local -r project="${file%%/${dir_type}*}" # Get path before dir_type + local -r project="${file%%/"${dir_type}"*}" # Get path before dir_type # In CI mode we get sorted list of modified files, so we can optimise this a # little bit. @@ -85,7 +85,7 @@ check_api_file() cd "${destination}" fi - local -r project_file="${file##*${dir_type}/}" # Get path after dir_type + local -r project_file="${file##*"${dir_type}"/}" # Get path after dir_type check_file "${log_file}" "${project_file}" } -- GitLab From 8aa8ca679c91656401053bb649b8d977b5f4a32a Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 10 Dec 2023 04:54:32 +0200 Subject: [PATCH 41/44] Implement a Shpinx extension to simplify links to gitlab content Tags: Docs --- docs/_ext/gitlab_repo.py | 104 +++++++++++++++++++++++++++ docs/conf.py | 13 +++- docs/index.rst | 24 +++---- docs/pipelines/docs/sphinx.rst | 2 +- docs/pipelines/lang/cmake.rst | 4 +- docs/pipelines/lang/common.rst | 2 +- docs/pipelines/lang/cpp/index.rst | 6 +- docs/pipelines/lang/cpp/linters.rst | 6 +- docs/pipelines/lang/docker/build.rst | 2 +- 9 files changed, 134 insertions(+), 29 deletions(-) create mode 100644 docs/_ext/gitlab_repo.py diff --git a/docs/_ext/gitlab_repo.py b/docs/_ext/gitlab_repo.py new file mode 100644 index 0000000..d1d2510 --- /dev/null +++ b/docs/_ext/gitlab_repo.py @@ -0,0 +1,104 @@ +from enum import StrEnum +from typing import TYPE_CHECKING + +from docutils import nodes +from sphinx.errors import ExtensionError +from sphinx.roles import ReferenceRole, SphinxRole +from sphinx.transforms import SphinxTransform + +if TYPE_CHECKING: + from sphinx.application import Sphinx + from sphinx.config import Config + + +class ConfigValues(StrEnum): + BPROTO_REPO_LINK = "bproto_repo_link" + REPO_LINK = "repo_link" + + +def _make_url(title: str, url: str) -> nodes.reference: + if title: + reference = nodes.reference("", "", internal=False, refuri=url) + reference += nodes.strong(title, title) + else: + reference = nodes.reference("", url, internal=False, refuri=url) + + return reference + + +class BaseRepoRole(ReferenceRole): + config_name: str + url_part: str + + def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: + base_url: str = getattr(self.config, self.config_name) + refuri = f"{base_url}/-/{self.url_part}/{self.target}" + + return [_make_url(self.title, refuri)], [] + + +class BProtoCommitRole(BaseRepoRole): + config_name = ConfigValues.BPROTO_REPO_LINK + url_part = "commit" + + +class BProtoIssueRole(BaseRepoRole): + config_name = ConfigValues.BPROTO_REPO_LINK + url_part = "issues" + + +class BProtoUrlRole(SphinxRole): + config_name = ConfigValues.BPROTO_REPO_LINK + + def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: + refuri = getattr(self.config, self.config_name) + return [_make_url(self.text, refuri)], [] + + +class BProtoUrlSubstitutions(SphinxTransform): + config_name = ConfigValues.BPROTO_REPO_LINK + + # run before the default Substitutions + default_priority = 210 + + def apply(self, **kwargs: dict) -> None: + refuri = getattr(self.config, self.config_name) + node = _make_url("", refuri) + + for ref in self.document.findall(nodes.substitution_reference): + if ref["refname"] == "bproto-url": + ref.replace_self(node) + + +class RepoFileRole(BaseRepoRole): + config_name = ConfigValues.REPO_LINK + url_part = "tree/main" + + +def _handle_inited_config(app: "Sphinx", config: "Config") -> None: + for config_name in ConfigValues: + if not getattr(config, config_name.value): + raise ExtensionError(f"'{config_name.value}' config value is empty!") + + +def setup(app: "Sphinx"): + for config_name in ConfigValues: + app.add_config_value(config_name.value, None, "env", [str]) + + app.connect("config-inited", _handle_inited_config) + + app.add_role("bproto-commit", BProtoCommitRole()) + app.add_role("bproto-issue", BProtoIssueRole()) + app.add_role("repo-file", RepoFileRole()) + + # In Shpinx we can define ":bproto-url:`title`". However ":bproto-url:" is an + # invalid use of Sphinx role. To overcome that we also define a "|bproto-url|" + # substitution, which might be quite handy when we just want to get a repo link. + app.add_role("bproto-url", BProtoUrlRole()) + app.add_transform(BProtoUrlSubstitutions) + + return { + "version": "0.0.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/conf.py b/docs/conf.py index 3c6ab16..520f7eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,6 +6,11 @@ import datetime import os +import sys + +# -- Path setup -------------------------------------------------------------- + +sys.path.append(os.path.abspath("./_ext")) # -- Project information ----------------------------------------------------- @@ -18,7 +23,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -extensions = ["sphinx_copybutton"] +extensions = ["sphinx_copybutton", "gitlab_repo"] # More can be found here: https://stackoverflow.com/a/60991308. rst_prolog = """ @@ -26,7 +31,6 @@ .. By default below line is set to 'incremental' which breaks site a little. .. default-role:: - """ # -- Options for HTML output ------------------------------------------------- @@ -87,3 +91,8 @@ def _generate_last_updated_fmt(): html_theme_options = {} html_title = project + +# -- Extensions ------------------------------------------------- + +bproto_repo_link = "https://gitlab.com/bproto/cicd" +repo_link = os.getenv("CI_PROJECT_URL") diff --git a/docs/index.rst b/docs/index.rst index fab75fa..bd8771b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,24 +44,18 @@ CI/CD templates This project provides a bunch of useful `GitLab CI/CD pipelines `__ for different programming languages and frameworks. Below is a nice list of all available pipelines: -.. _conan-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/conan.yml -.. _cpp-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/cpp.yml -.. _hugo-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/hugo.yml -.. _lite-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/conan.yml -.. _sphinx-tmpl: https://gitlab.com/bproto/cicd/-/blob/main/.gitlab/ci/external/sphinx.yml - - **Documentation** - - Hugo (`.gitlab/ci/external/hugo.yml `__) - - Sphinx (`.gitlab/ci/external/sphinx.yml `__) + - Hugo (:repo-file:`.gitlab/ci/external/hugo.yml`) + - Sphinx (:repo-file:`.gitlab/ci/external/sphinx.yml`) - **Languages** - - C++ (`.gitlab/ci/external/cpp.yml `__) - - CMake (`.gitlab/ci/external/lite.yml `__) - - Docker (`.gitlab/ci/external/lite.yml `__) - - Linux shell (`.gitlab/ci/external/lite.yml `__) - - Python (`.gitlab/ci/external/lite.yml `__) - - YAML (`.gitlab/ci/external/lite.yml `__) + - C++ (:repo-file:`.gitlab/ci/external/cpp.yml`) + - CMake (:repo-file:`.gitlab/ci/external/lite.yml`) + - Docker (:repo-file:`.gitlab/ci/external/lite.yml`) + - Linux shell (:repo-file:`.gitlab/ci/external/lite.yml`) + - Python (:repo-file:`.gitlab/ci/external/lite.yml`) + - YAML (:repo-file:`.gitlab/ci/external/lite.yml`) - **Packages** - - Conan (`.gitlab/ci/external/conan.yml `__) + - Conan (:repo-file:`.gitlab/ci/external/conan.yml`) You can start using those pipelines by including one of them as shown below: diff --git a/docs/pipelines/docs/sphinx.rst b/docs/pipelines/docs/sphinx.rst index 928e4c4..7ed365c 100644 --- a/docs/pipelines/docs/sphinx.rst +++ b/docs/pipelines/docs/sphinx.rst @@ -11,7 +11,7 @@ This is a "sub-pipeline" for building and deploying new changes that have been m .. note:: Current approach is way more simple than the old one and solely relies on `GitLab Pages `__. - If you still curious about how things worked before, you can look though :doc:`this page ` and investigate `this commit `__. + If you still curious about how things worked before, you can look though :doc:`this page ` and investigate :bproto-commit:`this commit `. .. _pipelines-docs-sphinx-environment: diff --git a/docs/pipelines/lang/cmake.rst b/docs/pipelines/lang/cmake.rst index 7ab5eef..c1a6029 100644 --- a/docs/pipelines/lang/cmake.rst +++ b/docs/pipelines/lang/cmake.rst @@ -27,7 +27,7 @@ This job executes `cmake-format `__ .. note:: This job is in active development phase and is a subject for a complete rework. - Please follow `this project issue `__ to get more information about the current state of this job. + Please follow :bproto-issue:`this project issue <5>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. @@ -71,7 +71,7 @@ This job executes `cmake-lint `__ * .. note:: This job is in active development phase and is a subject for a complete rework. - Please follow `this project issue `__ to get more information about the current state of this job. + Please follow :bproto-issue:`this project issue <5>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. diff --git a/docs/pipelines/lang/common.rst b/docs/pipelines/lang/common.rst index 7fc3ab9..6548e14 100644 --- a/docs/pipelines/lang/common.rst +++ b/docs/pipelines/lang/common.rst @@ -21,7 +21,7 @@ This job executes `licenseheaders `__ to get more information about the current state of this job. + Please follow :bproto-issue:`this project issue <9>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. diff --git a/docs/pipelines/lang/cpp/index.rst b/docs/pipelines/lang/cpp/index.rst index a0f32e3..9747e6d 100644 --- a/docs/pipelines/lang/cpp/index.rst +++ b/docs/pipelines/lang/cpp/index.rst @@ -58,8 +58,6 @@ Most jobs, from the current implementation of the C++ "sub-pipeline", heavily re .. Generated with the help of https://tree.nathanfriend.io. -.. _issue: https://gitlab.com/bproto/cicd/-/issues/7 -.. _other issue: https://gitlab.com/bproto/cicd/-/issues/6 .. _"check:cpp:format": pipeline-lang-cpp-linters-format .. parsed-literal:: @@ -78,7 +76,7 @@ Most jobs, from the current implementation of the C++ "sub-pipeline", heavily re │ ├── .gitignore │ ├── CMakeLists.txt │ └── index.rst - :red:`├── project/` (`issue`_) :gray:`<- 'check:cpp:format' formats code only here.` + :red:`├── project/` (:bproto-issue:`issue <7>`) :gray:`<- 'check:cpp:format' formats code only here.` │ ├── module-1/ │ │ :olive:`├── docs/` :gray:`<- docs job looks for changes here.` │ │ │ ├── api.rst @@ -99,7 +97,7 @@ Most jobs, from the current implementation of the C++ "sub-pipeline", heavily re │ │ └── CMakeLists.txt │ ├── module-2/ │ │ └── ... - │ :olive:`├── misc/` (`other issue`_) :gray:`<- 'check:cpp:include_guards' handles this folder in a special way.` + │ :olive:`├── misc/` (:bproto-issue:`issue <6>`) :gray:`<- 'check:cpp:include_guards' handles this folder in a special way.` │ │ ├── misc-module-1/ │ │ │ └── ... │ │ ├── mist-project-2/ diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index 1c4306f..2844d5d 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -165,7 +165,7 @@ This job executes `clang-format `_ ``clang-format`` for each input file will try to find the ``.clang-format`` file located in the closest parent directory of the input file. Different configuration options can be found on `official page `__ - Default config, which can be found `here `__ and shipped with project C++ related docker images, implements the `following formatting conventions `__ and it's heavily opinionated. + Default config, which can be found :repo-file:`here <.clang-format>` and shipped with project C++ related docker images, implements the `following formatting conventions ` and it's heavily opinionated. *DEPENDENCIES* Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. @@ -213,7 +213,7 @@ This job executes ``checkguard`` from `guardonce `__ and has the following value: + Current config is hard-coded in :repo-file:`this file ` and has the following value: - ``path | remove - | remove _ | prepend __BPROTO_ | append __ | upper`` @@ -319,7 +319,7 @@ This job executes `clang-tidy `__ *only *CONFIG* Configuration file is located at the root of the repository and has ``.clang-tidy`` name. - Default config, which can be found `here `__ and shipped with project C++ related docker images, implements the `following naming conventions `__ and is rather restrictive. + Default config, which can be found :repo-file:`here <.clang-tidy>` and shipped with project C++ related docker images, implements the `following naming conventions `__ and is rather restrictive. *DEPENDENCIES* Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. diff --git a/docs/pipelines/lang/docker/build.rst b/docs/pipelines/lang/docker/build.rst index 48a2bb8..fe33b20 100644 --- a/docs/pipelines/lang/docker/build.rst +++ b/docs/pipelines/lang/docker/build.rst @@ -156,4 +156,4 @@ Jobs overview Usage ===== -This is an internal part of the Docker "sub-pipeline" which meant to be used solely by `3CT: Common CI/CD Tools `__ project. +This is an internal part of the Docker "sub-pipeline" which meant to be used solely by :bproto-url:`3CT: Common CI/CD Tools` project. -- GitLab From fdb40512d806af11043ccb4a825ec29e67c0a8f6 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 10 Dec 2023 04:56:13 +0200 Subject: [PATCH 42/44] Document better how to fork this project Tags: Docs, Shell --- README.md | 13 +--- docs/fork.rst | 67 ++++++++++++++++++++ docs/index.rst | 10 +-- scripts/fork.sh | 160 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 231 insertions(+), 19 deletions(-) create mode 100644 docs/fork.rst create mode 100644 scripts/fork.sh diff --git a/README.md b/README.md index 08c8657..3aa605d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # GitLab Common CI/CD Tools -[caching]: https://docs.gitlab.com/ee/ci/caching [fork]: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html **GitLab Common CI/CD Tools** (**GitLab 3CT** for short) provides a [GitLab CI/CD](https://docs.gitlab.com/ee/ci) solution that helps to control the quality of mainly C++ and Python codebases and their surrounding infrastructure. @@ -72,17 +71,9 @@ Now you are ready to go! ### Forks -The general rule of thumb can be answering positive to one of below questions: +[forking]: https://bproto.gitlab.io/cicd/overview/index.html -[images]: https://bproto.gitlab.io/cicd/images/index.html -[pipelines-lang-cpp]: https://bproto.gitlab.io/cicd/pipelines/lang/cpp/index.html -[pipelines-lang-cpp-limitations]: https://bproto.gitlab.io/cicd/pipelines/lang/cpp/index.html#limitations - -- do I need a different toolchain than is provided by current [pre-build docker image][images]? -- do I need a different set of python package than what is provided by current [pre-build docker image][images] and [caching][caching] can't help you with that? -- do I need to tweak [C++ pipeline][pipelines-lang-cpp] implementation? - -Also it's worth to mention that some pipelines, like [C++][pipelines-lang-cpp] one, have [though limitations][pipelines-lang-cpp-limitations] that can be overcome by [caching][caching] packages but you still might decide to [fork][fork] this project and change some lines. +If you think, you need to fork this project and adjust it to your personal needs, please consider taking a look at [this documentation page][forking]. ## License diff --git a/docs/fork.rst b/docs/fork.rst new file mode 100644 index 0000000..a17c8a9 --- /dev/null +++ b/docs/fork.rst @@ -0,0 +1,67 @@ +.. _forking-project: + +=============== +Forking project +=============== + +.. _caching: https://docs.gitlab.com/ee/ci/caching +.. _fork: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html + +The general rule of thumb can be answering positive to one of below questions: + +- do I need a different toolchain than is provided by current :ref:`pre-build docker image `? +- do I need a different set of python package than what is provided by current :ref:`pre-build docker image ` and caching_ can't help you with that? +- do I need to tweak :ref:`C++ pipeline ` implementation? + +Also it's worth to mention that some pipelines, like :ref:`C++ ` one, have :ref:`though limitations ` that can be overcome by caching_ packages but you still might decide to `fork `__ this project and change some lines. + +.. note:: + + Cookbook for GitLab forks can be found in `official documentation `__. + There you can find how to fork a project and how to maintain it. + +TODO list +========= + +Mandatory actions +----------------- + +#. Create a separate git branch. + .. note:: + + It's worth to mention - this is a rather personal choice. + However, if you are not planning to integrate your changes into :bproto-url:`parent project`, it's better to have a separate branch which contains only your changes. + +#. Change project path in :repo-file:`CI external files <.gitlab/ci/external>` from ``bproto/cicd`` to your own. + +#. Change macro prefix :repo-file:`clang-tidy config <.clang-tidy>` file from ``BPROTO`` to your own. + +#. Change include guards prefix from ``BPROTO`` to your own in an appropriate :repo-file:`shell script `. + +#. Add project specific python packages to :repo-file:`pyproject.toml `. + +#. Update :repo-file:`conan profiles ` accordingly to your needs. + .. note:: Current profiles set ``c++17`` standard. + +#. Add project specific conan packages to :repo-file:`conanfile.txt `. + +Optional actions +---------------- + +#. Update ``clang-format`` :repo-file:`config file <.clang-format>` to your needs. + +#. Update ``clang-tidy`` :repo-file:`config file <.clang-tidy>` to your needs. + +Automation +========== + +There is a simple shell script that can automate some of mentioned actions. +You can find it under :repo-file:`scripts/fork.sh` path. + +If you've forked :bproto-url:`bproto/cicd` into https://gitlab.com/supercoder/cicd, you can run script as follows: + +.. code-block:: bash + + bash scripts/fork.sh -p MY_PREFIX -r supercoder/cicd + +More information you can get by reading the script code, which is pretty straight forward. diff --git a/docs/index.rst b/docs/index.rst index bd8771b..610468d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ GitLab Common CI/CD Tools overview/index.rst images/index.rst pipelines/index.rst + fork.rst variables.rst useful_links.rst @@ -20,7 +21,6 @@ GitLab Common CI/CD Tools git/index.rst -.. _caching: https://docs.gitlab.com/ee/ci/caching .. _fork: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html .. _`Zinchenko Serhii`: https://gitlab.com/b110011 @@ -92,13 +92,7 @@ Now you are ready to go! Forks ----- -The general rule of thumb can be answering positive to one of below questions: - -- do I need a different toolchain than is provided by current :ref:`pre-build docker image `? -- do I need a different set of python package than what is provided by current :ref:`pre-build docker image ` and caching_ can't help you with that? -- do I need to tweak :ref:`C++ pipeline ` implementation? - -Also it's worth to mention that some pipelines, like :ref:`C++ ` one, have :ref:`though limitations ` that can be overcome by caching_ packages but you still might decide to `fork `__ this project and change some lines. +If you think, you need to fork this project and adjust it to your personal needs, please consider taking a look at :ref:`this documentation page `. License ======= diff --git a/scripts/fork.sh b/scripts/fork.sh new file mode 100644 index 0000000..dc16844 --- /dev/null +++ b/scripts/fork.sh @@ -0,0 +1,160 @@ +#!/usr/bin/env bash + +# Copyright 2023 Zinchenko Serhii . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -e + +# +# CLI +# + +usage() +{ + echo "Usage: $0 [-t ] -p -r + + -t target branch + -p prefix for macro and include guards + -r a repo short path (CI_PROJECT_PATH) +" 1>&2 + exit 1 +} + +while getopts ":t:p:r:" o; do + case "${o}" in + t) + declare -r TARGET_BRANCH="${OPTARG}" + ;; + p) + declare -r PREFIX="${OPTARG}" + ;; + r) + declare -r REPO_PATH="${OPTARG}" + ;; + *) + usage + ;; + esac +done + +shift $((OPTIND - 1)) + +if [ -z "${PREFIX}" ] || [ -z "${REPO_PATH}" ]; then + usage +fi + +if [ -z "${TARGET_BRANCH}" ]; then + declare TARGET_BRANCH="develop" +fi + +# +# Utils +# + +commit() +{ + echo -e "\033[0;32m${1} \033[0m" + git commit -q --message "${1}" --trailer "Tags: ${2}" +} + +commit_if_changed() +{ + local -r file="${1}" + local -r commit_msg="${2}" + local -r commit_tags="${3}" + + if git diff --name-only | grep -q -e "${file}"; then + git add "${file}" + commit "${commit_msg}" "${commit_tags}" + else + echo -e "\033[0;33mHave not detected changes in '${file}' file, skipping.\033[0m" + fi +} + +# +# Checks +# + +# Check 1 + +if [[ $(git rev-parse --show-toplevel 2> /dev/null) != "$PWD" ]]; then + echo -e "\033[0;31m'$0' can be used only in the root of git repository! \033[0m" + exit 1 +fi + +# Check 2 + +if git show-ref -q --heads "${TARGET_BRANCH}"; then + echo -e "\033[0;31m'${TARGET_BRANCH}' branch exists locally! \033[0m" + exit 1 +fi + +if git ls-remote --exit-code --heads origin "${TARGET_BRANCH}"; then + echo -e "\033[0;31m'${TARGET_BRANCH}' branch exists remotely! \033[0m" + exit 1 +fi + +# +# Mandatory actions +# + +# Action 1 + +git checkout -b "${TARGET_BRANCH}" + +# Action 2 + +declare -r EXTERNAL_CI=".gitlab/ci/external" + +find "${EXTERNAL_CI}" -type f -exec sed -i -e "s|project: 'bproto/cicd'|project: '${REPO_PATH}'|g" {} \; +git add "${EXTERNAL_CI}" +commit "Replace project path from 'bproto/cicd' to '${REPO_PATH}' in CI external files" "CI, Cpp" + +# Action 3 + +sed -i "s/BPROTO/${PREFIX}/g" .clang-tidy +git add .clang-tidy +commit "Replace BPROTO with ${PREFIX} in clang-tidy config file" "Cpp, ClangTidy, Linters" + +# Action 4 + +declare -r IG_LINTER="scripts/cicd/lint/check_cpp_include_guards.sh" + +sed -i "s/ __BPROTO_ / __${PREFIX}_ /g" "${IG_LINTER}" +git add "${IG_LINTER}" +commit "Change include guards prefix from BPROTO to ${PREFIX}" "Cpp, Linters, Shell" + +# Action 5 + +commit_if_changed 'pyproject.toml' 'Add project specific python packages' 'Python' + +# Action 6 + +commit_if_changed 'conan/profiles' 'Update conan profiles' 'Cpp, Conan' + +# Action 7 + +commit_if_changed 'conan/conanfile.txt' 'Add project specific conan packages' 'Cpp, Conan' + +# +# Optional actions +# + +# Action 1 + +commit_if_changed '.clang-format' 'Update clang-format config' 'Cpp, ClangFormat, Linters' + +# Action 2 + +commit_if_changed '.clang-tidy' 'Update clang-tidy config' 'Cpp, ClangTidy, Linters' -- GitLab From f84e75bc955d6bc51b50973aa256f81f0313457f Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 10 Dec 2023 05:51:31 +0200 Subject: [PATCH 43/44] Make use of Sphinx domains Tags: Docs --- docs/_ext/gitlab_repo.py | 53 ++++++++++++++++++++-------- docs/fork.rst | 22 ++++++------ docs/index.rst | 18 +++++----- docs/pipelines/docs/sphinx.rst | 2 +- docs/pipelines/lang/cmake.rst | 4 +-- docs/pipelines/lang/common.rst | 2 +- docs/pipelines/lang/cpp/index.rst | 4 +-- docs/pipelines/lang/cpp/linters.rst | 6 ++-- docs/pipelines/lang/docker/build.rst | 2 +- 9 files changed, 68 insertions(+), 45 deletions(-) diff --git a/docs/_ext/gitlab_repo.py b/docs/_ext/gitlab_repo.py index d1d2510..811b49a 100644 --- a/docs/_ext/gitlab_repo.py +++ b/docs/_ext/gitlab_repo.py @@ -2,6 +2,7 @@ from typing import TYPE_CHECKING from docutils import nodes +from sphinx.domains import Domain from sphinx.errors import ExtensionError from sphinx.roles import ReferenceRole, SphinxRole from sphinx.transforms import SphinxTransform @@ -17,13 +18,10 @@ class ConfigValues(StrEnum): def _make_url(title: str, url: str) -> nodes.reference: - if title: - reference = nodes.reference("", "", internal=False, refuri=url) - reference += nodes.strong(title, title) - else: - reference = nodes.reference("", url, internal=False, refuri=url) + if not title: + title = url - return reference + return nodes.reference("", title, internal=False, refuri=url) class BaseRepoRole(ReferenceRole): @@ -37,6 +35,9 @@ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: return [_make_url(self.title, refuri)], [] +# bproto + + class BProtoCommitRole(BaseRepoRole): config_name = ConfigValues.BPROTO_REPO_LINK url_part = "commit" @@ -55,6 +56,9 @@ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: return [_make_url(self.text, refuri)], [] +# In Shpinx we can define ":bproto-url:`title`". However ":bproto-url:" is an +# invalid use of Sphinx role. To overcome that we also define a "|bproto-url|" +# substitution, which might be quite handy when we just want to get a repo link. class BProtoUrlSubstitutions(SphinxTransform): config_name = ConfigValues.BPROTO_REPO_LINK @@ -70,15 +74,39 @@ def apply(self, **kwargs: dict) -> None: ref.replace_self(node) +class BProtoDomain(Domain): + name = "bproto" + label = "bproto repo links" + roles = { + "commit": BProtoCommitRole(), + "issue": BProtoIssueRole(), + "url": BProtoUrlRole(), + } + + +# repo + + class RepoFileRole(BaseRepoRole): config_name = ConfigValues.REPO_LINK url_part = "tree/main" +class RepoDomain(Domain): + name = "repo" + label = "gitlab repo links" + roles = { + "file": RepoFileRole(), + } + + +# setup + + def _handle_inited_config(app: "Sphinx", config: "Config") -> None: for config_name in ConfigValues: if not getattr(config, config_name.value): - raise ExtensionError(f"'{config_name.value}' config value is empty!") + raise ExtensionError(f"{config_name.value!r} config value is empty!") def setup(app: "Sphinx"): @@ -87,16 +115,11 @@ def setup(app: "Sphinx"): app.connect("config-inited", _handle_inited_config) - app.add_role("bproto-commit", BProtoCommitRole()) - app.add_role("bproto-issue", BProtoIssueRole()) - app.add_role("repo-file", RepoFileRole()) - - # In Shpinx we can define ":bproto-url:`title`". However ":bproto-url:" is an - # invalid use of Sphinx role. To overcome that we also define a "|bproto-url|" - # substitution, which might be quite handy when we just want to get a repo link. - app.add_role("bproto-url", BProtoUrlRole()) + app.add_domain(BProtoDomain) app.add_transform(BProtoUrlSubstitutions) + app.add_domain(RepoDomain) + return { "version": "0.0.0", "parallel_read_safe": True, diff --git a/docs/fork.rst b/docs/fork.rst index a17c8a9..8221822 100644 --- a/docs/fork.rst +++ b/docs/fork.rst @@ -30,35 +30,35 @@ Mandatory actions .. note:: It's worth to mention - this is a rather personal choice. - However, if you are not planning to integrate your changes into :bproto-url:`parent project`, it's better to have a separate branch which contains only your changes. + However, if you are not planning to integrate your changes into :bproto:url:`parent project`, it's better to have a separate branch which contains only your changes. -#. Change project path in :repo-file:`CI external files <.gitlab/ci/external>` from ``bproto/cicd`` to your own. +#. Change project path in :repo:file:`CI external files <.gitlab/ci/external>` from ``bproto/cicd`` to your own. -#. Change macro prefix :repo-file:`clang-tidy config <.clang-tidy>` file from ``BPROTO`` to your own. +#. Change macro prefix :repo:file:`clang-tidy config <.clang-tidy>` file from ``BPROTO`` to your own. -#. Change include guards prefix from ``BPROTO`` to your own in an appropriate :repo-file:`shell script `. +#. Change include guards prefix from ``BPROTO`` to your own in an appropriate :repo:file:`shell script `. -#. Add project specific python packages to :repo-file:`pyproject.toml `. +#. Add project specific python packages to :repo:file:`pyproject.toml `. -#. Update :repo-file:`conan profiles ` accordingly to your needs. +#. Update :repo:file:`conan profiles ` accordingly to your needs. .. note:: Current profiles set ``c++17`` standard. -#. Add project specific conan packages to :repo-file:`conanfile.txt `. +#. Add project specific conan packages to :repo:file:`conanfile.txt `. Optional actions ---------------- -#. Update ``clang-format`` :repo-file:`config file <.clang-format>` to your needs. +#. Update ``clang-format`` :repo:file:`config file <.clang-format>` to your needs. -#. Update ``clang-tidy`` :repo-file:`config file <.clang-tidy>` to your needs. +#. Update ``clang-tidy`` :repo:file:`config file <.clang-tidy>` to your needs. Automation ========== There is a simple shell script that can automate some of mentioned actions. -You can find it under :repo-file:`scripts/fork.sh` path. +You can find it under :repo:file:`scripts/fork.sh` path. -If you've forked :bproto-url:`bproto/cicd` into https://gitlab.com/supercoder/cicd, you can run script as follows: +If you've forked :bproto:url:`bproto/cicd` into https://gitlab.com/supercoder/cicd, you can run script as follows: .. code-block:: bash diff --git a/docs/index.rst b/docs/index.rst index 610468d..569e954 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,17 +45,17 @@ This project provides a bunch of useful `GitLab CI/CD pipelines `__. - If you still curious about how things worked before, you can look though :doc:`this page ` and investigate :bproto-commit:`this commit `. + If you still curious about how things worked before, you can look though :doc:`this page ` and investigate :bproto:commit:`this commit `. .. _pipelines-docs-sphinx-environment: diff --git a/docs/pipelines/lang/cmake.rst b/docs/pipelines/lang/cmake.rst index c1a6029..810f557 100644 --- a/docs/pipelines/lang/cmake.rst +++ b/docs/pipelines/lang/cmake.rst @@ -27,7 +27,7 @@ This job executes `cmake-format `__ .. note:: This job is in active development phase and is a subject for a complete rework. - Please follow :bproto-issue:`this project issue <5>` to get more information about the current state of this job. + Please follow :bproto:issue:`this project issue <5>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. @@ -71,7 +71,7 @@ This job executes `cmake-lint `__ * .. note:: This job is in active development phase and is a subject for a complete rework. - Please follow :bproto-issue:`this project issue <5>` to get more information about the current state of this job. + Please follow :bproto:issue:`this project issue <5>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. diff --git a/docs/pipelines/lang/common.rst b/docs/pipelines/lang/common.rst index 6548e14..6c1ceab 100644 --- a/docs/pipelines/lang/common.rst +++ b/docs/pipelines/lang/common.rst @@ -21,7 +21,7 @@ This job executes `licenseheaders ` to get more information about the current state of this job. + Please follow :bproto:issue:`this project issue <9>` to get more information about the current state of this job. *ALLOW FAILURE* .. warning:: This job is allowed to fail as it's still in development. diff --git a/docs/pipelines/lang/cpp/index.rst b/docs/pipelines/lang/cpp/index.rst index 9747e6d..3948864 100644 --- a/docs/pipelines/lang/cpp/index.rst +++ b/docs/pipelines/lang/cpp/index.rst @@ -76,7 +76,7 @@ Most jobs, from the current implementation of the C++ "sub-pipeline", heavily re │ ├── .gitignore │ ├── CMakeLists.txt │ └── index.rst - :red:`├── project/` (:bproto-issue:`issue <7>`) :gray:`<- 'check:cpp:format' formats code only here.` + :red:`├── project/` (:bproto:issue:`issue <7>`) :gray:`<- 'check:cpp:format' formats code only here.` │ ├── module-1/ │ │ :olive:`├── docs/` :gray:`<- docs job looks for changes here.` │ │ │ ├── api.rst @@ -97,7 +97,7 @@ Most jobs, from the current implementation of the C++ "sub-pipeline", heavily re │ │ └── CMakeLists.txt │ ├── module-2/ │ │ └── ... - │ :olive:`├── misc/` (:bproto-issue:`issue <6>`) :gray:`<- 'check:cpp:include_guards' handles this folder in a special way.` + │ :olive:`├── misc/` (:bproto:issue:`issue <6>`) :gray:`<- 'check:cpp:include_guards' handles this folder in a special way.` │ │ ├── misc-module-1/ │ │ │ └── ... │ │ ├── mist-project-2/ diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index 2844d5d..c80c8d8 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -165,7 +165,7 @@ This job executes `clang-format `_ ``clang-format`` for each input file will try to find the ``.clang-format`` file located in the closest parent directory of the input file. Different configuration options can be found on `official page `__ - Default config, which can be found :repo-file:`here <.clang-format>` and shipped with project C++ related docker images, implements the `following formatting conventions ` and it's heavily opinionated. + Default config, which can be found :repo:file:`here <.clang-format>` and shipped with project C++ related docker images, implements the `following formatting conventions `__ and it's heavily opinionated. *DEPENDENCIES* Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. @@ -213,7 +213,7 @@ This job executes ``checkguard`` from `guardonce ` and has the following value: + Current config is hard-coded in :repo:file:`this file ` and has the following value: - ``path | remove - | remove _ | prepend __BPROTO_ | append __ | upper`` @@ -319,7 +319,7 @@ This job executes `clang-tidy `__ *only *CONFIG* Configuration file is located at the root of the repository and has ``.clang-tidy`` name. - Default config, which can be found :repo-file:`here <.clang-tidy>` and shipped with project C++ related docker images, implements the `following naming conventions `__ and is rather restrictive. + Default config, which can be found :repo:file:`here <.clang-tidy>` and shipped with project C++ related docker images, implements the `following naming conventions `__ and is rather restrictive. *DEPENDENCIES* Job doesn't require artifacts from other jobs and has no dependencies from other stages or jobs. diff --git a/docs/pipelines/lang/docker/build.rst b/docs/pipelines/lang/docker/build.rst index fe33b20..9c9e777 100644 --- a/docs/pipelines/lang/docker/build.rst +++ b/docs/pipelines/lang/docker/build.rst @@ -156,4 +156,4 @@ Jobs overview Usage ===== -This is an internal part of the Docker "sub-pipeline" which meant to be used solely by :bproto-url:`3CT: Common CI/CD Tools` project. +This is an internal part of the Docker "sub-pipeline" which meant to be used solely by :bproto:url:`3CT: Common CI/CD Tools` project. -- GitLab From 419983295a779aebbdc0f0963db190e77dcc63d9 Mon Sep 17 00:00:00 2001 From: Zinchenko Serhii Date: Sun, 10 Dec 2023 06:09:01 +0200 Subject: [PATCH 44/44] draft --- docs/_ext/gitlab_docs.py | 77 +++++++++++++++++++++++++++++ docs/conf.py | 2 +- docs/index.rst | 6 +-- docs/overview/stages.rst | 12 ++--- docs/pipelines/index.rst | 4 +- docs/pipelines/lang/cpp/linters.rst | 8 +-- docs/pipelines/packages/conan.rst | 2 +- docs/useful_links.rst | 20 ++++---- docs/variables.rst | 4 +- 9 files changed, 106 insertions(+), 29 deletions(-) create mode 100644 docs/_ext/gitlab_docs.py diff --git a/docs/_ext/gitlab_docs.py b/docs/_ext/gitlab_docs.py new file mode 100644 index 0000000..2fc44f6 --- /dev/null +++ b/docs/_ext/gitlab_docs.py @@ -0,0 +1,77 @@ +from typing import TYPE_CHECKING + +from docutils import nodes +from sphinx.domains import Domain +from sphinx.roles import ReferenceRole +from sphinx.transforms import SphinxTransform + +if TYPE_CHECKING: + from sphinx.application import Sphinx + + +def _make_url(base_url: str, title: str = "", url_part: str = "") -> nodes.reference: + url = base_url + url_part + + if title: + reference = nodes.reference("", "", internal=False, refuri=url) + reference += nodes.strong(title, title) + else: + reference = nodes.reference("", url, internal=False, refuri=url) + + return reference + + +class BaseGitlabDocsRole(ReferenceRole): + base_url: str = "https://docs.gitlab.com/ee/" + section: str + + def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: + url = f"{self.base_url}/{self.section}/" + return [_make_url(url, self.title, self.target)], [] + + +class GitlabCiDocsRole(ReferenceRole): + section = "ci" + + +class GitlabUserDocsRole(ReferenceRole): + section = "user" + + +class GitlabDocsSubstitutions(SphinxTransform): + # run before the default Substitutions + default_priority = 210 + + def apply(self, **kwargs: dict) -> None: + base = _make_url("https://docs.gitlab.com") + ci = _make_url("https://docs.gitlab.com/ee/ci/") + user = _make_url("https://docs.gitlab.com/ee/user/") + + for ref in self.document.findall(nodes.substitution_reference): + refname = ref["refname"] + if refname == "gitlab-docs": + ref.replace_self(base) + elif refname == "gitlab-ci-docs": + ref.replace_self(ci) + elif refname == "gitlab-user-docs": + ref.replace_self(user) + + +class GitlabDocsDomain(Domain): + name = "gitlab-docs" + label = "gitLab.com official documentation" + roles = { + "ci": GitlabCiDocsRole(), + "user": GitlabUserDocsRole(), + } + + +def setup(app: "Sphinx"): + app.add_domain("gitlab-ci-docs", GitlabDocsDomain()) + app.add_transform(GitlabDocsSubstitutions) + + return { + "version": "0.0.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/conf.py b/docs/conf.py index 520f7eb..ff0f3a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -extensions = ["sphinx_copybutton", "gitlab_repo"] +extensions = ["sphinx_copybutton", "gitlab_docs", "gitlab_repo"] # More can be found here: https://stackoverflow.com/a/60991308. rst_prolog = """ diff --git a/docs/index.rst b/docs/index.rst index 569e954..7848a7d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,14 +34,14 @@ This module also may serve as a useful reference for setting up a GitLab CI/CD u Usage ===== -By design this project is intended to be used as a `CI/CD template `__ in most of the cases. +By design this project is intended to be used as a :gitlab-docs:ci:`CI/CD template ` in most of the cases. However due to some limitations it might be `forked `__ to bring some changes and then to be used as your own CI/CD template. Both ways will be covered in-deep down on this page. CI/CD templates --------------- -This project provides a bunch of useful `GitLab CI/CD pipelines `__ for different programming languages and frameworks. +This project provides a bunch of useful :gitlab-docs:ci:`GitLab CI/CD pipelines ` for different programming languages and frameworks. Below is a nice list of all available pipelines: - **Documentation** @@ -67,7 +67,7 @@ You can start using those pipelines by including one of them as shown below: file: - '/.gitlab/ci/external/lite.yml' -You also need to define below `CI/CD variables `__ in your `group `__ or `project `__ CI/CD settings. +You also need to define below :gitlab-docs:ci:`CI/CD variables ` in your :gitlab-docs:ci:`group ` or :gitlab-docs:ci:`project ` CI/CD settings. .. raw:: html diff --git a/docs/overview/stages.rst b/docs/overview/stages.rst index d2bb4e7..81dd593 100644 --- a/docs/overview/stages.rst +++ b/docs/overview/stages.rst @@ -17,22 +17,22 @@ Before you start reading a below overview of each pipeline stage, you should fam - This section describes whether job is allowed to fail. * - Artifacts - - This section describes what `job artifacts `__ will be generated after a successful run. + - This section describes what :gitlab-docs:ci:`job artifacts ` will be generated after a successful run. * - Cache - - This section describes used of `job's cache `__. + - This section describes used of :gitlab-docs:ci:`job's cache `. * - Dependencies - This section describes what kind of dependencies job tends to have. - Effectively combines `dependencies `__ and `needs `__ directives. + Effectively combines :gitlab-docs:ci:`dependencies ` and :gitlab-docs:ci:`needs ` directives. * - Environment - - This section describes what `environment variables `__ jobs use. + - This section describes what :gitlab-docs:ci:`environment variables ` jobs use. Right now only custom variables, those ones that defined using project settings, are taken into account. * - Images - This section describes Docker images that the job is using. - Effectively combines an overall content of `image `__ directive for all jobs. + Effectively combines an overall content of :gitlab-docs:ci:`image ` directive for all jobs. * - Triggers - This section describes when and at what cases job will be triggered. @@ -75,7 +75,7 @@ This is an *optional* stage for running different types of project tests. Jobs are not allowed to fail as all project tests regardless their type must never be broken. *ARTIFACTS* - Jobs will generate `unit test reports `__. + Jobs will generate :gitlab-docs:ci:`unit test reports `. *DEPENDENCIES* Jobs require artifacts from parent jobs. diff --git a/docs/pipelines/index.rst b/docs/pipelines/index.rst index 3c40093..2321aff 100644 --- a/docs/pipelines/index.rst +++ b/docs/pipelines/index.rst @@ -16,8 +16,8 @@ These documents cover in-detail all available "sub-pipelines" and their jobs. Concept ======= -We always try to compose everything into one top-level `GitLab CI/CD pipeline `__ that includes all jobs. -This way we can have all `GitLab CI/CD jobs `__, that have been triggered for merge request or a specific branch, in one place. +We always try to compose everything into one top-level :gitlab-docs:ci:`GitLab CI/CD pipeline ` that includes all jobs. +This way we can have all :gitlab-docs:ci:`GitLab CI/CD jobs `, that have been triggered for merge request or a specific branch, in one place. That said, we still try to decompose a top-level pipeline into smaller ones ("sub-pipelines"). Such approach decrease cognitive overload and makes it much easy to understand certain aspects of our pipeline. diff --git a/docs/pipelines/lang/cpp/linters.rst b/docs/pipelines/lang/cpp/linters.rst index c80c8d8..f9e7ab2 100644 --- a/docs/pipelines/lang/cpp/linters.rst +++ b/docs/pipelines/lang/cpp/linters.rst @@ -34,7 +34,7 @@ Job is triggered only on **merge requests** when any file from :ref:`trigger lis Jobs overview ============= -.. _manual_job: https://docs.gitlab.com/ee/ci/jobs/job_control.html#create-a-job-that-must-be-run-manually +.. |manual-job| replace:: :gitlab-docs:ci:`manual one ` .. _linters-pipeline-check-cpp-coverage: @@ -71,7 +71,7 @@ Even so it means pipeline could take much less time, it still much easy to manag :ref:`overview-stages-check-stage`. *TRIGGERS* - As this job is a `manual one `_, it can be triggered only by a user. + As this job is a |manual-job|, it can be triggered only by a user. report:cpp:coverage ------------------- @@ -125,7 +125,7 @@ This job executes `cppcheck `__ *only on cha :ref:`overview-stages-check-stage`. *TRIGGERS* - As this job is a `manual one `_, it can be triggered only by a user. + As this job is a |manual-job|, it can be triggered only by a user. report:cpp:cppcheck ------------------- @@ -352,7 +352,7 @@ This job executes `clang-tidy `__ *only :ref:`overview-stages-check-stage`. *TRIGGERS* - As this job is a `manual one `_, it can be triggered only by a user. + As this job is a |manual-job|, it can be triggered only by a user. check:cpp:tidy (nightly) ------------------------ diff --git a/docs/pipelines/packages/conan.rst b/docs/pipelines/packages/conan.rst index 2dbd51d..81b726f 100644 --- a/docs/pipelines/packages/conan.rst +++ b/docs/pipelines/packages/conan.rst @@ -149,7 +149,7 @@ This stage is responsible for deploying conan packages to the `package registry` Usage ===== -To correctly use provided CI jobs you need to set :ref:`BPROTO_CI_CONAN_PACKAGES_REGISTRY ` either in `project CI/CD settings `__ or as shown below. +To correctly use provided CI jobs you need to set :ref:`BPROTO_CI_CONAN_PACKAGES_REGISTRY ` either in :gitlab-docs:ci:`project CI/CD settings ` or as shown below. .. code-block:: yaml diff --git a/docs/useful_links.rst b/docs/useful_links.rst index 50d4d07..72f1554 100644 --- a/docs/useful_links.rst +++ b/docs/useful_links.rst @@ -8,32 +8,32 @@ CI/CD **.gitlab-ci.yml** Official GitLab documentation for ``.gitlab-ci.yml`` keyword reference. - Available online at https://docs.gitlab.com/ee/ci/yaml/. + Available online at :gitlab-docs:ci:`yaml`. **GitLab CI/CD pipelines** Official GitLab documentation for managing GitLab CI/CD pipelines. - Available online at https://docs.gitlab.com/ee/ci/pipelines. + Available online at :gitlab-docs:ci:`pipelines`. **GitLab CI/CD jobs** Official GitLab documentation for managing GitLab CI/CD jobs. - Available online at https://docs.gitlab.com/ee/ci/jobs. + Available online at :gitlab-docs:ci:`jobs`. **GitLab CI/CD variables** Official GitLab documentation for managing GitLab CI/CD variables. - Available online at https://docs.gitlab.com/ee/ci/variables. + Available online at :gitlab-docs:ci:`variables`. **GitLab CI/CD pre-defined variables** Official GitLab documentation for managing GitLab CI/CD predefined variables. - Available online at https://docs.gitlab.com/ee/ci/variables/predefined_variables.html. + Available online at :gitlab-docs:ci:`variables/predefined_variables.html`. **GitLab CI/CD caching** Official GitLab documentation for using caching in GitLab CI/CD. - Available online at https://docs.gitlab.com/ee/ci/caching. + Available online at :gitlab-docs:ci:`caching`. Useful artifacts ================ @@ -41,22 +41,22 @@ Useful artifacts **GitLab CI/CD artifacts reports types** Official list of all available GitLab CI/CD artifacts reports types. - Available online at https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html. + Available online at :gitlab-docs:ci:`yaml/artifacts_reports.html`. **Code Quality** Official GitLab documentation for managing code quality reports. - Available online at https://docs.gitlab.com/ee/ci/testing/code_quality.html. + Available online at :gitlab-docs:ci:`testing/code_quality.html`. **Test coverage** Official GitLab documentation for managing test coverage reports. - Available online at https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html. + Available online at :gitlab-docs:ci:`testing/test_coverage_visualization.html`. **Unit tests** Official GitLab documentation for managing unit tests reports. - Available online at https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html. + Available online at :gitlab-docs:ci:`testing/unit_test_reports.html`. Pages ===== diff --git a/docs/variables.rst b/docs/variables.rst index 1bdbffb..d95bb41 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -8,7 +8,7 @@ Local CI/CD variables ===================== **CI_DEBUG_TRACE**:STRING - Predefined GitLab CI variable that enables `debug logging (tracing) `__ to help troubleshoot problems with pipeline configuration or job scripts. + Predefined GitLab CI variable that enables :gitlab-docs:ci:`debug logging (tracing) ` to help troubleshoot problems with pipeline configuration or job scripts. Valid values: ``false`` and ``true``. @@ -102,7 +102,7 @@ GitLab group-level variables +----------+-------------------------------------+----------------------------+-----------+---------+--------------+ .. note:: - To change above environment variables please follow instructions provided by the official `group CI/CD settings `__ user guide. + To change above environment variables please follow instructions provided by the official :gitlab-docs:ci:`group CI/CD settings ` user guide. Misc CI/CD variables ==================== -- GitLab