developer.md

Developer

Generally honor:

• Documenting C++ Code

More serious: The source code has partially doxygen documentation which is partially expressive, but outdated. A documentation marathon is required if the source base is stable.

Build: Requisites

For Ubuntu please have a look at the files in .devcontainer and the scripts.

For Fedora:

sudo dnf install gcc clang clang-tools-extra cmake ninja-build

Build: Conan Profile

It is important to set up the right Conan profile, e.g. setup the right compiler and path. E.g. for Clang profile clang, [buildenv]and [conf] are added manually:

$ cat .conan2/profiles/clang 
[settings]
arch=x86_64
build_type=Release
compiler=clang
compiler.cppstd=gnu17
compiler.libcxx=libstdc++11
compiler.version=19
os=Linux

[buildenv]
CC=clang
CXX=clang++

[conf]
tools.build:compiler_executables={ "c": "/usr/bin/clang", "cpp": "/usr/bin/clang++" }

Further, if during conan install one gets c++: error: unrecognized command-line option ‘-stdlib=libstdc++’ then the compiler aren't correctly setup - it's not a valid flag for GCC.

Build: Customize CMake build

CMake supports two files, CMakePresets.json and CMakeUserPresets.json, that allow users to specify common configure, build, and test options and share them with others. For more information see cmake-presets.

CCache on Linux

To use, e.g. CCache (a fast C/C++ compiler cache) for CMake's configure phase, write your own CMakeUserPresets.json using e.g. GNU compiler with

{
    "version": 8,
    "include": [
        "cmake/presets/common.json"
    ], 
    "configurePresets": [
        {
            "name": "gcc-ccache",
            "displayName": "GnuC (CCache)",
            "description": "GnuC compiler using compiler (CCache)",
            "inherits": [
                "gcc",
                "ccache"
            ]
        }
    ],
    "buildPresets": [
        {
            "name": "gcc-ccache-release",
            "displayName": "Release",
            "description": "Release build with GnuC",
            "configuration": "Release",
            "configurePreset": "gcc-ccache"
        }
    ],
    "testPresets": [
        {
            "name": "gcc-ccache-release-test",
            "displayName": "Release Test",
            "description": "Test GnuC build",
            "configuration": "Release",
            "configurePreset": "gcc-ccache",
            "inherits": [
                "default-testPreset"
            ]
        }
    ],
    "workflowPresets": [
        {
            "name": "GnuC Release (CCache)",
            "displayName": "CI GnuC Release (CCache)",
            "description": "Continuous Integration/Continuous Delivery using GnUC (Release)",
            "steps": [
                {
                    "type": "configure",
                    "name": "gcc-ccache"
                },
                {
                    "type": "build",
                    "name": "gcc-ccache-release"
                },
                {
                    "type": "test",
                    "name": "gcc-ccache-release-test"
                }
            ]
        }
    ]
}

The cmake/presets/common.json presets already contains a predefined "ccache" section:

        {
            "name": "ccache",
            "description": "ccache - compiler cache",
            "hidden": true,
            "cacheVariables": {
                "CMAKE_CXX_COMPILER_LAUNCHER": "ccache",
                "CCACHE_BASEDIR": "${sourceDir}",
                "CCACHE_SLOPPINESS": "pch_defines,time_macros",
                "CCACHE_DIR": "~/.cache/ccache" 
            }
        },

Also, there are some already pre-configured user CMake presets below cmake/presets/user. Simply copy one of your choice to ${source_dir} as CMakeUserPresets.json - this file is excluded from git, see .gitignore.

Linting: Clang Tidy

The .clang-tidy config file applies some checks and disabled others.

Disabled checks:

There are disabled checks which shouldn't be. Enabling this checks requires more effort:

• misc-no-recursion: Until the ast_printer recursive call chain has been solved.

• cert-err58-cpp: It's correct, but depend on others libraries.

• cppcoreguidelines-pro-bounds-array-to-pointer-decay: Ignored at this time. With C++20 with get std::span aka gsl::span aka gsl:: gsl::array_view.

• bugprone-branch-clone: This check ignores the C++ [[fallthrough]] attribute specifier, hence twice the source annotations. But it checks and examines conditional operators, so we can't it disable completely. Hopefully later Clang-tidy version will honor those attribute specifier.

• readability-identifier-naming Here a lot of effort is required to consolidate and unify all the naming, e.g. see .clang-tidy or .clang-tidy as example.

Permanently disabled checks:

• modernize-use-trailing-return-type: This transformation is purely stylistic. We are not quite that modern.

• modernize-use-nodiscard: This would affect a lot of value returning member functions everywhere and doesn't give any additional information.

• readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers: This goes too far to force this everywhere.

• readability-redundant-access-specifiers: This is correct, but is used here for classification purposes.

• cppcoreguidelines-pro-type-vararg: By using Boost UTF this rule is triggered on each BOOST_TEST macros. No c-style vararg functions are written in this project.

Formatting: Clang-Format

The source format is given by Clang-Format's configuration .clang-format, or even simpler by EditorConfig's .editorconfig.