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_targetPRIVATElizardbyte::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_binaryPRIVATElizardbyte::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: localizepermissions: {}on:
push:
branches:
- masterpaths:
- '.github/workflows/localize.yml'
- 'src/**'
- 'locale/sunshine.po'workflow_dispatch:
jobs:
localize:
name: Update Localizationpermissions:
contents: readuses: LizardByte/lizardbyte-common/.github/workflows/localize.yml@mastersecrets:
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

[TOC]