Contributing to gtopt

Prerequisites

• Clang 21 (preferred) or GCC 14+ for C++26 support
• CMake 3.31.6+
• Dependencies listed in BUILDING.md

See BUILDING.md for full dependency installation instructions, including Apache Arrow (APT or conda) and the Clang 21 install script.

Building and Testing

The primary build target is the test/ sub-project (not the root CMakeLists.txt):

# Configure and build tests (Clang 21 preferred)
cmake -S test -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++
cmake --build build -j$(nproc)

# Run all tests
cd build && ctest --output-on-failure

# Run a specific test (doctest filter syntax)
./build/gtoptTests -tc="test name pattern"

# Check code formatting
cmake --build build --target check-format

# Auto-format code
cmake --build build --target format

Alternative with GCC 14:

CC=gcc-14 CXX=g++-14 cmake -S test -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)

Code Coverage

cmake -S test -B build \
  -DENABLE_TEST_COVERAGE=ON \
  -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
cd build && ctest

C++

• Standard: C++26 (CMAKE_CXX_STANDARD 26). C++23 features are used throughout; adopt C++26 features as Clang 21 / GCC 14 support matures.
• Compiler flags: -Wall -Wpedantic -Wextra -Werror — all warnings are errors.
• Formatting: Enforced by .clang-format (80-char column limit, 2-space indent). The CI auto-formats on every non-main push and commits a fixup.
• Linting: Configured via .clang-tidy with extensive checks enabled.
• Naming conventions:
  • Classes/Structs: PascalCase (e.g. LinearProblem, SimulationLP)
  • Free functions and methods: snake_case (e.g. add_col, get_optvalue, resolve, annual_discount_factor)
  • Local variables and public data members: snake_case
  • Private class members: m_ prefix + _ suffix (e.g. m_simulation_, m_options_) (e.g. m_simulation_, m_options_)
  • Macros: UPPER_CASE
• Include guards: Use #pragma once
• File headers: Doxygen-style (@file, @brief, @date, @author, @copyright)
• Includes: Three sorted groups — <std>, external <pkg/header>, project <gtopt/...>
• Error handling: Prefer std::optional and return values over exceptions
• Modern C++: Use concepts (requires), ranges, std::format, structured bindings, designated initializers, [[nodiscard]], noexcept where appropriate

Python

• Version: Python ≥ 3.12 (CI uses 3.12)
• Formatting: black with 88-char line length (configured in pyproject.toml)
• Import sorting: isort (profile black)
• Linting: ruff + pylint; see .flake8 and .pylintrc
• Type checking: mypy

pip install -e ".[dev]"   # install dev dependencies
black . && isort .
ruff check . && pylint scripts/ guiservice/
mypy scripts/ guiservice/
pytest

Pre-commit Hooks

The project uses pre-commit hooks for automated checks. Install them with:

pip install pre-commit
pre-commit install

Hooks include: trailing whitespace, YAML validation, Black, Flake8, Pylint, ShellCheck, yamllint, markdownlint, and cmake-format.

CI auto-format: The autoformat.yml workflow runs clang-format on every push to non-main branches and commits a fixup automatically. Local violations are therefore non-blocking, but running cmake --build build --target format before pushing keeps the history clean.