lizardbyte-common

Common library and helpers for LizardByte projects.

Overview

ℹ️ About

This repository contains shared helper scripts, repository-level tooling, and C++ helpers used across LizardByte projects.

The current tooling includes Python-managed helpers, reusable GitHub workflows, and a small C++ helper library:

scripts/update_clang_format.py runs clang-format across supported source directories.
scripts/localize.py updates gettext and Babel locale files.
.github/workflows/localize.yml runs the locale helper from GitHub Actions and opens localization update pull requests.
lizardbyte::common provides shared C++ helpers, starting with environment variable manipulation.
lizardbyte::test_support provides shared GoogleTest fixtures and test macros for LizardByte C++ projects.

⚙️ Python Tooling

Install uv and sync the locked tool environment:

uv sync --locked

Run the clang-format helper:

uv run --locked --only-group c lb-update-clang-format

Run gettext extraction:

uv run --locked --only-group locale lb-localize --extract

🗜️ C++ Tooling

Initialize submodules before configuring the C++ targets:

git submodule update --init --recursive

Configure, build, and test the C++ helpers with CMake:

cmake -DBUILD_DOCS=OFF -DBUILD_TESTS=ON -B build -S .
cmake --build build --parallel
ctest --test-dir build --output-on-failure

The C++ library exports the lizardbyte::common target and public headers under lizardbyte/common/.

#include <lizardbyte/common/env.h>
 
std::string value;
if (lizardbyte::common::get_env("MY_ENV", value)) {
  lizardbyte::common::append_env("MY_ENV", "suffix", ";");
}
 
if (lizardbyte::common::is_github_actions()) {
  // Apply GitHub Actions-specific behavior.
}

The optional test support target is available when BUILD_TESTS=ON or LIZARDBYTE_COMMON_BUILD_TEST_SUPPORT=ON.

#include <lizardbyte/common/testing.h>
 
TEST(MySuite, CapturesOutputUntilFailure) {
  std::cout << "only printed when this test fails";
}

Build the Doxygen documentation through the shared doxyconfig submodule:

cmake -DBUILD_DOCS=ON -DBUILD_TESTS=OFF -B build/docs -S .

cmake --build build/docs --target docs

📐 Consuming Projects

Projects with a pyproject.toml can use this repository as a local path dependency. For a submodule at third-party/lizardbyte-common, add the dependency and source to the consuming project's pyproject.toml:

[project]
dependencies = [
    "lizardbyte-common[c]",
]
 
[tool.uv.sources]
lizardbyte-common = { path = "third-party/lizardbyte-common" }

Then sync and run the installed commands from the consuming project root:

uv sync --python 3.14
uv run lb-update-clang-format
uv run lb-localize --extract

Projects without a pyproject.toml can still create a .venv in the consuming project root and install the local checkout into it:

uv venv --python 3.14

uv pip install --editable "third-party/lizardbyte-common[c]"

Then run the commands from the consuming project root:

lb-update-clang-format

lb-localize --extract

CMake projects can consume the C++ helpers from the same submodule:

add_subdirectory(third-party/lizardbyte-common)

target_link_libraries(my_target PRIVATE lizardbyte::common)

To consume the shared GoogleTest support helpers from a project that already builds tests, link the test binary to lizardbyte::test_support:

set(LIZARDBYTE_COMMON_BUILD_TEST_SUPPORT ON)
add_subdirectory(third-party/lizardbyte-common)
target_link_libraries(my_test_binary PRIVATE lizardbyte::test_support)

♾️ Workflows

Reusable GitHub workflows live under .github/workflows/.

localize.yml extracts gettext strings with the shared locale helper and can open a localization update pull request.

name: localize
permissions: {}
 
on:
  push:
    branches:
      - master
    paths:
      - '.github/workflows/localize.yml'
      - 'src/**'
      - 'locale/sunshine.po'
  workflow_dispatch:
 
jobs:
  localize:
    name: Update Localization
    permissions:
      contents: read
    uses: LizardByte/lizardbyte-common/.github/workflows/localize.yml@master
    secrets:
      GH_TOKEN: ${{ secrets.GH_BOT_TOKEN }}

🧪 Tests

Run the pytest suite:

uv run --locked --only-group test-python pytest

Run the C++ GoogleTest suite:

cmake -DBUILD_DOCS=OFF -DBUILD_TESTS=ON -B build -S .
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Table of Contents