qcdx 0.1.0__tar.gz

qcdx-0.1.0/.github/actions/pk-setup/action.yml

@@ -0,0 +1,157 @@
+name: pk-setup
+description: >-
+  Toolchain, Conan and the Conan cache for a verify/release target. Used by
+  verify.yml and release.yml to only have to set up target once in one place.
+
+inputs:
+  target:
+    description: A target name from cmake/projectkit/scripts/pklib/targets.py.
+    required: true
+  msystem:
+    description: MSYS2 environment (UCRT64, CLANG64, CLANGARM64), Windows only.
+    default: ''
+  cache:
+    description: "'save' restores & saves Conan cache, 'restore' doesn't save."
+    default: save
+  conan-version:
+    default: '2.33.0'
+  llvm-mingw-tag:
+    default: '20260616'
+  llvm-mingw-asset:
+    # Linux x86_64 UCRT build of the pinned release.
+    default: llvm-mingw-20260616-ucrt-ubuntu-22.04-x86_64.tar.xz
+  llvm-mingw-sha256:
+    default: 534b92e067b22a6b4441f48ae9240a3341b17825d04d577eab0cf85c44b4deda
+
+runs:
+  using: composite
+  steps:
+    # -------------------------------------------------------------------------
+    #  Linux and macOS
+    # -------------------------------------------------------------------------
+
+    - if: runner.os != 'Windows'
+      uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
+
+    - if: runner.os != 'Windows'
+      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      with:
+        python-version: '3.12'
+
+    - name: Install Conan
+      if: runner.os != 'Windows'
+      shell: bash
+      run: python -m pip install --disable-pip-version-check "conan==${{ inputs.conan-version }}"
+
+    # Conan only accepts compiler.cstd=23 from GCC 14. apt should only run when
+    # something is missing.
+    - name: Install Linux packages
+      if: runner.os == 'Linux'
+      shell: bash
+      env:
+        TARGET: ${{ inputs.target }}
+      run: |
+        packages=()
+        command -v g++-14 >/dev/null || packages+=(g++-14)
+        case "$TARGET" in
+          cross-x86_64-mingw-w64)  packages+=(g++-mingw-w64-x86-64) ;;
+          cross-aarch64-linux-gnu) command -v aarch64-linux-gnu-gcc >/dev/null || packages+=(g++-aarch64-linux-gnu) ;;
+          cross-x86_64-linux-gnu)  command -v x86_64-linux-gnu-gcc  >/dev/null || packages+=(g++-x86-64-linux-gnu) ;;
+        esac
+        if [ ${#packages[@]} -gt 0 ]; then
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq --no-install-recommends "${packages[@]}"
+        fi
+        if [ "$TARGET" = cross-x86_64-mingw-w64 ]; then
+          sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
+          sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
+        fi
+        echo "CC=gcc-14" >> "$GITHUB_ENV"
+        echo "CXX=g++-14" >> "$GITHUB_ENV"
+
+    - name: Install llvm-mingw
+      if: inputs.target == 'cross-aarch64-mingw-llvm-w64'
+      shell: bash
+      env:
+        TAG: ${{ inputs.llvm-mingw-tag }}
+        ASSET: ${{ inputs.llvm-mingw-asset }}
+        SHA256: ${{ inputs.llvm-mingw-sha256 }}
+      run: |
+        archive="$RUNNER_TEMP/$ASSET"
+        curl -fsSL -o "$archive" "https://github.com/mstorsjo/llvm-mingw/releases/download/${TAG}/${ASSET}"
+        echo "${SHA256}  ${archive}" | sha256sum -c -
+        mkdir -p "$RUNNER_TEMP/llvm-mingw"
+        tar -xJf "$archive" -C "$RUNNER_TEMP/llvm-mingw" --strip-components=1
+        rm -f "$archive"
+        echo "$RUNNER_TEMP/llvm-mingw/bin" >> "$GITHUB_PATH"
+
+    - name: Point Conan at the runner temp directory
+      if: runner.os != 'Windows'
+      shell: bash
+      run: echo "CONAN_HOME=$RUNNER_TEMP/conan2" >> "$GITHUB_ENV"
+
+    # -------------------------------------------------------------------------
+    # Windows (MSYS2)
+    # -------------------------------------------------------------------------
+
+    - if: runner.os == 'Windows'
+      uses: msys2/setup-msys2@66cd2cce69caa17b53920067426061ca1de3a884 # v2.32.0
+      with:
+        msystem: ${{ inputs.msystem }}
+        update: true
+        install: git
+        pacboy: >-
+          toolchain:p
+          cmake:p
+          ninja:p
+          python-pip:p
+          pkgconf:p
+
+    # Visual Studio is installed on the runner used, Conan prefers
+    # MSVC on Windows, CC/CXX override it.
+    - name: Select the MSYS2 compiler
+      if: runner.os == 'Windows'
+      shell: pwsh
+      env:
+        MSYSTEM_NAME: ${{ inputs.msystem }}
+      run: |
+        if ($env:MSYSTEM_NAME -like 'CLANG*') { $cc = 'clang'; $cxx = 'clang++' } else { $cc = 'gcc'; $cxx = 'g++' }
+        "CC=$cc" >> $env:GITHUB_ENV
+        "CXX=$cxx" >> $env:GITHUB_ENV
+        "CONAN_HOME=$env:RUNNER_TEMP\conan2" >> $env:GITHUB_ENV
+
+    - name: Install Conan
+      if: runner.os == 'Windows'
+      shell: msys2 {0}
+      run: python -m pip install --disable-pip-version-check --break-system-packages "conan==${{ inputs.conan-version }}"
+
+    # -------------------------------------------------------------------------
+    # Conan cache
+    # -------------------------------------------------------------------------
+
+    # The key is shared with verify.yml, and caches saved on main can be read
+    # from every branch and tag: release runs will reuse verify's packages,
+    # NEVER storing a wasteful second copy.
+    - if: inputs.cache == 'save'
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: ${{ runner.temp }}/conan2/p
+        key: conan-${{ inputs.target }}-${{ hashFiles('conanfile.py', 'deps.json', 'conan.lock', 'profiles/**') }}
+        restore-keys: conan-${{ inputs.target }}-
+
+    - if: inputs.cache == 'restore'
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: ${{ runner.temp }}/conan2/p
+        key: conan-${{ inputs.target }}-${{ hashFiles('conanfile.py', 'deps.json', 'conan.lock', 'profiles/**') }}
+        restore-keys: conan-${{ inputs.target }}-
+
+    - name: Detect the default Conan profile
+      if: runner.os != 'Windows'
+      shell: bash
+      run: conan profile detect --force
+
+    - name: Detect the default Conan profile
+      if: runner.os == 'Windows'
+      shell: msys2 {0}
+      run: conan profile detect --force

qcdx-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# QCDX package repository. template/ has its own .gitignore, the one every new
+# project starts with.
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Build output (python -m build, the zipapp, CMake checks)
+build/
+stage/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Written by the release workflow (the commit a build came from)
+src/qcdx/_commit.py
+
+# conan create (test_package)
+CMakeUserPresets.json

qcdx-0.1.0/CMakeLists.txt

@@ -0,0 +1,53 @@
+# The QCDX kit (ProjectKit) as a CMake package. Projects made with 'pk new'
+# vendor the kit and never need this; it is for using ProjectKit modules in an
+# existing CMake project:
+#
+#   cmake -S . -B build && cmake --install build --prefix /usr/local
+#   find_package(QCDX 0.1 REQUIRED)        # in the consuming project
+#   include(ProjectKit)
+#
+# or without installing anything (CMake 3.24+):
+#
+#   include(FetchContent)
+#   FetchContent_Declare(qcdx URL <release qcdx-X.Y.Z.tar.gz> URL_HASH SHA256=...)
+#   FetchContent_MakeAvailable(qcdx)
+#   find_package(QCDX 0.1 REQUIRED)
+#   include(ProjectKit)
+
+cmake_minimum_required(VERSION 3.25)
+
+file(STRINGS "${CMAKE_CURRENT_LIST_DIR}/cmake/projectkit/VERSION" _qcdx_version LIMIT_COUNT 1)
+
+project(QCDX
+  VERSION       ${_qcdx_version}
+  DESCRIPTION   "ProjectKit: CMake modules and scripts for C and C++ projects"
+  HOMEPAGE_URL  "https://github.com/cooldood155/QCDX"
+  LANGUAGES     NONE)
+
+# Added by FetchContent or add_subdirectory: point find_package(QCDX) at this
+# tree. QCDX_DIR is what find_package checks first; the redirect file serves
+# FetchContent_Declare(... FIND_PACKAGE_ARGS) and OVERRIDE_FIND_PACKAGE.
+if(NOT PROJECT_IS_TOP_LEVEL)
+  set(QCDX_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cmake" CACHE PATH "QCDX package configuration" FORCE)
+  if(CMAKE_FIND_PACKAGE_REDIRECTS_DIR)
+    file(WRITE "${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/qcdx-extra.cmake"
+      "include(\"${CMAKE_CURRENT_SOURCE_DIR}/cmake/QCDXConfig.cmake\")\n")
+    file(WRITE "${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/qcdx-extra-version.cmake"
+      "include(\"${CMAKE_CURRENT_SOURCE_DIR}/cmake/QCDXConfigVersion.cmake\")\n")
+  endif()
+  return()
+endif()
+
+# <prefix>/share/qcdx/cmake/ is on find_package's default search path.
+# GNUInstallDirs is not used: it needs a language enabled, only share/ matters.
+set(QCDX_INSTALL_CMAKEDIR "share/qcdx/cmake" CACHE STRING
+  "Where QCDXConfig.cmake and projectkit/ are installed, relative to the prefix")
+
+install(DIRECTORY cmake/projectkit
+  DESTINATION "${QCDX_INSTALL_CMAKEDIR}"
+  USE_SOURCE_PERMISSIONS
+  PATTERN "__pycache__" EXCLUDE
+  PATTERN "*.pyc" EXCLUDE)
+
+install(FILES cmake/QCDXConfig.cmake cmake/QCDXConfigVersion.cmake
+  DESTINATION "${QCDX_INSTALL_CMAKEDIR}")

qcdx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan R. Reumann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qcdx-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.5
+Name: qcdx
+Version: 0.1.0
+Summary: Create, build, test, package and release C and C++ projects with CMake and Conan
+Project-URL: Homepage, https://github.com/cooldood155/QCDX
+Project-URL: Documentation, https://github.com/cooldood155/QCDX#readme
+Project-URL: Issues, https://github.com/cooldood155/QCDX/issues
+Project-URL: Changelog, https://github.com/cooldood155/QCDX/releases
+Author-email: "Evan R. Reumann" <evanrileyreumann@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: build-system,c,c++,cmake,conan,project-template,scaffolding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Provides-Extra: tools
+Requires-Dist: cmake>=3.30; extra == 'tools'
+Requires-Dist: conan<3,>=2.0; extra == 'tools'
+Requires-Dist: ninja; extra == 'tools'
+Description-Content-Type: text/markdown
+
+# QCDX
+
+[![verify](https://github.com/cooldood155/QCDX/actions/workflows/verify.yml/badge.svg)](https://github.com/cooldood155/QCDX/actions/workflows/verify.yml) [![release](https://github.com/cooldood155/QCDX/actions/workflows/release.yml/badge.svg)](https://github.com/cooldood155/QCDX/actions/workflows/release.yml)
+
+[Documentation](#documentation)
+
+A template for C and C++ projects built on **projectkit**, a set of CMake
+modules and scripts under `cmake/projectkit/`. A fresh copy already contains a
+working library, application, test and build-time tool, so it configures,
+builds, tests, installs and packages before you start writting code.
+
+- **CMake 3.30+, Ninja and Conan 2**, with presets for native builds, host
+  tools and cross builds.
+- **One call per target**: `pk_create_library`, `pk_create_app`,
+  `pk_create_test` and `pk_create_tool` find their sources, headers and
+  settings by convention.
+- **C and C++**: C++ libraries, C libraries, and C interfaces implemented in
+  C++, each with a generated export header (`export.hpp` or `export.h`).
+- **Static, shared or both** from one build, chosen per project or pinned per
+  library.
+- **Checks built in**: warnings, hardening, sanitizers, clang-tidy, cppcheck,
+  Valgrind and coverage, each one option away.
+- **`pk`**, one command line for all of it, Conan and CMake never have to be
+  typed by hand.
+
+## Requirements
+
+| Tool | Version |
+| :-- | :-- |
+| CMake | 3.30 or newer |
+| Ninja | any recent |
+| Python | 3.8 or newer |
+| Conan | 2.x |
+| Git | any recent |
+| Compiler | GCC 13+, Clang 18+, AppleClang 15+ or MSVC 19.30+ |
+
+The scripts are Python and run from any shell. On Windows outside an MSYS2
+shell, start them as `python scripts\pk.py ...`.
+
+The default standards are C++23 and C23. Every supported OS, architecture and
+toolchain combination is listed in [`docs/BUILDING.md`](docs/BUILDING.md).
+
+## Quick start
+
+Create a repository from the template, then clone it:
+
+```bash
+gh repo create my-project --template cooldood155/QCDX --public --clone
+cd my-project
+```
+
+Without the GitHub CLI, press **Use this template** on GitHub and clone the
+new repository.
+
+Give the project its own name. The rename covers directories, file names and
+file contents, and refuses to run on a dirty tree so `git diff` shows exactly
+what it changed:
+
+```bash
+./scripts/pk.py rename myproject --description="What this project is" --version=0.1.0
+git diff --stat
+```
+
+Check the tools, then build, run and test:
+
+```bash
+./scripts/pk.py doctor
+./scripts/pk.py build
+./scripts/pk.py run
+./scripts/pk.py test
+```
+
+The first `build` installs the Conan dependencies and configures CMake; later
+builds only rebuild. Every Conan and CMake command `pk` runs is printed before
+it runs, and `-n` prints them without running anything.
+
+Then replace this README with your own project's.
+
+## Everyday commands
+
+| Command | What it does |
+| :-- | :-- |
+| `pk build [TYPE]` | install dependencies, configure and build, each only when needed |
+| `pk run [APP] -- ARGS` | build one application and run it |
+| `pk test [TYPE]` | build with tests and run them with ctest |
+| `pk stage` | install into `stage/`, check the package and write a report |
+| `pk dep ...` | add, change, remove, update and inspect third-party packages |
+| `pk status` | the build trees, their options and dependency state |
+| `pk sync` | pull projectkit updates from this template |
+| `pk full-clean` | remove everything the build generated |
+| `pk help COMMAND` | every flag a command accepts |
+
+Build types are `debug` (default), `release`, `relwithdebinfo` and
+`minsizerel`. Options such as `--werror`, `--lib=shared` or
+`--sanitize=address,undefined` are remembered per build tree.
+
+To type `pk` instead of `./scripts/pk.py` from anywhere inside any project
+made from this template, install the shell function for bash or PowerShell
+once, as described in
+[`PK.md`](cmake/projectkit/docs/PK.md#install-as-a-shell-command).
+
+### Without pk
+
+`pk` only decides which of these steps are needed. They can always be run by
+hand:
+
+```bash
+./scripts/package.py install --build_type=Debug
+cmake --preset native-debug
+cmake --build build/native-debug
+ctest --test-dir build/native-debug --output-on-failure
+```
+
+## Adding code
+
+Each kind of target lives in its own directory, named after the target:
+
+| Target | Sources | Declared in |
+| :-- | :-- | :-- |
+| Library | `src/<name>/`, public headers in `include/<name>/` | `src/CMakeLists.txt` |
+| Application | `apps/<name>/` | `apps/CMakeLists.txt` |
+| Tests (Catch2) | `tests/<name>/` | `tests/CMakeLists.txt` |
+| Build-time tool | `tools/` | `tools/CMakeLists.txt` |
+
+```cmake
+pk_create_library(NAME myproject REQUIRE_SOURCES REQUIRE_PUBLIC_HEADERS)
+pk_create_app(NAME myproject DEFAULT_DIRS LINK_PRIVATE myproject::myproject)
+pk_create_test(NAME myproject)
+```
+
+A library with a C interface and a C++ implementation takes `LANGUAGE C`: its
+public headers are `.h` files, its export header becomes `export.h`, and its
+private headers in `src/<name>/` can be C++.
+
+The full walkthrough, including tools and cross builds, is in
+[`docs/FROM_ZERO_TO_PROJECT.md`](docs/FROM_ZERO_TO_PROJECT.md).
+
+## Dependencies
+
+Third-party packages are declared once, in `deps.json`, and pinned in
+`conan.lock`; both are committed. `conanfile.py` and the CMake creators read
+the deps.json.
+
+```bash
+pk dep add "sqlite3/[>=3.45 <4]"   # declare, lock (pin) and discover package/target
+pk dep ls                          # what is declared, locked and used by what
+pk dep why zlib                    # who pulls this package in and who uses it
+pk dep update sqlite3              # newest version within the range
+pk dep check                       # deps.json, CMake and the lock all match
+```
+
+```cmake
+pk_create_library(NAME myproject ... DEPS_PRIVATE sqlite3)
+```
+
+Versions only change when you ask (`add`, `update`, or a new range); builds
+fail rather than resolve past the lock. Details:
+[`PK_DEP.md`](cmake/projectkit/docs/PK_DEP.md).
+
+## Cross builds
+
+Each cross target is a Conan profile in `profiles/` plus matching presets:
+
+```bash
+pk list
+pk build -x x86_64-mingw-w64
+```
+
+`pk` builds the host tools natively first, then the cross build. Binaries built
+for another system cannot run here, tests are built but not run on cross
+builds.
+
+## Verification and CI
+
+`verify.py` runs the full pipeline for each build type: the preset workflow,
+every library type, installation, a consumer project that sees only the
+installed files, CPack and the host tools.
+
+```bash
+./scripts/verify.py list
+./scripts/verify.py run --build_type=Debug,Release
+```
+
+The same script runs in CI for every push and pull request to `main` that
+changes code: on Linux (`x86_64`, `armv8`), macOS (`armv8`) and Windows (MSYS2
+UCRT64), and as cross builds for Windows `x86_64` (MinGW-w64) and `arm64`
+(llvm-mingw).
+
+## Packaging
+
+```bash
+./scripts/package.py create --build_type=Debug,Release
+```
+
+This builds the Conan package, then builds a small consumer against it. Other
+projects use it like any Conan package:
+
+```cmake
+find_package(myproject REQUIRED)
+target_link_libraries(other PRIVATE myproject::myproject)
+```
+
+## Releases
+
+Push a version tag and CI builds, tests and archives every target provided then
+creates a draft GitHub release with checksums:
+
+```bash
+git tag -s v1.2.0 -m "myproject 1.2.0"
+git push origin v1.2.0
+```
+
+The tag must match `project(VERSION)`. Targets, archive contents, signing and
+a separate releases repository are set in
+`scripts/helpers/release/release.conf`, and every step also runs locally:
+
+```bash
+pk release stage linux-x86_64
+pk release pack linux-x86_64
+```
+
+Details: [`RELEASE.md`](cmake/projectkit/docs/RELEASE.md).
+
+## Keeping projectkit up to date
+
+Every project made from this template carries its own copy of the kit. When
+the template improves, bring the changes in with one command:
+
+```bash
+pk sync -n
+pk sync
+```
+
+Only the template's changes are applied, as a 3-way merge, changes made to the
+kit in your project are kept. The result is a single commit.
+
+## Layout
+
+```text
+my-project/
+  CMakeLists.txt           project(), pk_project_setup and the subdirectories
+  CMakePresets.json        native, host-tools and cross presets
+  conanfile.py             Conan recipe, version read from CMakeLists.txt
+  profiles/                Conan profiles: native, cross targets, CI
+  include/<name>/          public headers
+  src/<name>/              library sources and private headers
+  apps/<name>/             applications
+  tests/<name>/            tests
+  tools/                   build-time tools
+  cmake/projectkit/        the kit, updated with pk sync
+  scripts/                 pk.py, verify.py, package.py, release.py, bootstrap.py, settings
+  docs/                    guides
+```
+
+## Documentation
+
+| Document | Covers |
+| :-- | :-- |
+| [`docs/FROM_ZERO_TO_PROJECT.md`](docs/FROM_ZERO_TO_PROJECT.md) | from an empty directory to a packaged project |
+| [`docs/BUILDING.md`](docs/BUILDING.md) | supported platforms, toolchains and cross targets |
+| [`PK.md`](cmake/projectkit/docs/PK.md) | every `pk` command, flag and setting |
+| [`PK_DEP.md`](cmake/projectkit/docs/PK_DEP.md) | `deps.json`, `conan.lock`, `pk dep` and `DEPS_*` |
+| [`VERIFY.md`](cmake/projectkit/docs/VERIFY.md) | the verification pipeline and its targets |
+| [`RELEASE.md`](cmake/projectkit/docs/RELEASE.md) | tagged releases: targets, archives, checks, signing |
+| [`PACKAGE.md`](cmake/projectkit/docs/PACKAGE.md) | Conan packaging, editable mode and uploads |
+| [`ANALYSER_LAUNCHER.md`](cmake/projectkit/docs/ANALYSER_LAUNCHER.md) | clang-tidy and cppcheck integration |
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).