Metadata-Version: 2.2
Name: pyyggdrasil
Version: 0.0.25
Summary: Native dependency provider for Dominik Drexler's planning projects
Author-Email: Dominik Drexler <dominik.drexler@liu.se>
Project-URL: Homepage, https://github.com/planning-and-learning/yggdrasil
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: scikit-build-core<1,>=0.10; extra == "test"
Description-Content-Type: text/markdown

# Yggdrasil

`pyyggdrasil` packages the native dependency prefix used by the planning projects
in this repository family.

The Python distribution name and import package are both `pyyggdrasil`.

`pyyggdrasil` is the base of the planning-and-learning package chain. The shared
workspace layout, the layered install order, and the common
build-from-source and CMake-integration patterns are documented in the
[Planning and Learning build instructions](https://github.com/planning-and-learning/.github/blob/main/profile/README.md#building-from-source);
the sections below cover `pyyggdrasil`-specific details.

## Python Integration

Install the wheel and query the native prefix:

```python
import pyyggdrasil

print(pyyggdrasil.native_prefix())
print(pyyggdrasil.cmake_prefix())  # prefix to put on CMAKE_PREFIX_PATH
print(pyyggdrasil.cmake_dir())     # directory containing yggdrasilConfig.cmake
print(pyyggdrasil.include_dir())
print(pyyggdrasil.library_dirs())
print(pyyggdrasil.cmake_dirs())
```

The same paths are available from the shell:

```bash
python -m pyyggdrasil --prefix
python -m pyyggdrasil --cmake-dir
python -m pyyggdrasil --include-dir
python -m pyyggdrasil --version
```

Python packages that consume this native prefix should depend on:

```toml
dependencies = [
    "pyyggdrasil>=0.0.25,<0.1",
]
```

The bundled shared libraries make the coupling ABI-level, so pin to the same
minor version. The exported CMake package version file uses
`SameMinorVersion` compatibility accordingly.

## Build Python

Build a wheel from source:

```bash
uv build --wheel
```

The build creates `dependencies-build/` and `dependencies-install/`. To package
an existing native prefix without rebuilding dependencies:

```bash
YGGDRASIL_BUILD_NATIVE=OFF \
YGGDRASIL_NATIVE_PREFIX=/path/to/dependencies-install \
uv build --wheel
```

Set `YGGDRASIL_JOBS` to control the native dependency build parallelism.
Set `YGGDRASIL_BUILD_TYPE` to select the dependency build profile; it defaults
to `Release`.

Runtime libraries are stripped in the wheel by default. Disable that for
debugging with:

```bash
YGGDRASIL_STRIP_WHEEL=OFF uv build --wheel
```

## Build C++

### Native Dependencies

Build the native dependency prefix directly with CMake:

```bash
cmake -S src -B dependencies-build \
  -DCMAKE_INSTALL_PREFIX=dependencies-install \
  -DCMAKE_INSTALL_LIBDIR=lib

cmake --build dependencies-build -j4
cmake --install dependencies-build
```

Yggdrasil builds its bundled dependencies as shared libraries. The native
dependency prefix contains C++ headers, shared libraries, and CMake package
configuration files consumed by the other projects.

### Yggdrasil Targets

Configure Yggdrasil separately against the installed dependency prefix:

```bash
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DYGGDRASIL_NATIVE_PREFIX="$PWD/dependencies-install" \
  -DYGGDRASIL_BUILD_TESTS=ON

cmake --build build -j4
ctest --test-dir build
```

CMake options:

| Option | Default | Description |
| --- | --- | --- |
| `YGGDRASIL_BUILD_TESTS` | `OFF` | Build Yggdrasil C++ tests. |
| `YGGDRASIL_ENABLE_FMT_FORMATTERS` | `ON` | Enable Yggdrasil's public fmt formatters. |
| `YGGDRASIL_USE_LLD` | `ON` | Use LLVM `lld` with Clang when available. |
| `YGGDRASIL_ENABLE_LTO` | `ON` | Enable link-time optimization for Release builds. |

Single-config CMake builds default to Release. On GCC and Clang, Debug builds
use `-Og` with debug symbols, RelWithDebInfo keeps frame pointers and disables
LTO, and Release LTO uses GCC LTO or Clang ThinLTO. Editable installs and
wheels disable `YGGDRASIL_USE_LLD` and `YGGDRASIL_ENABLE_LTO` by default for
build reliability. This compiler policy applies only to Yggdrasil's
first-party extension and tests; the `src/` dependency superbuild leaves each
bundled project in control of its own compiler policy.

## CMake Integration

The wheel ships a CMake package config (`yggdrasilConfig.cmake`) defining the
`yggdrasil::yggdrasil` interface target. It carries the include directory,
C++20 as a compile feature, and the bundled dependencies (Boost, fmt, gtl, TBB)
via `find_dependency`. (cista is consumed through the include directory only —
its target exports compile definitions that would otherwise change cista's
hashing and fmt integration.) Downstream CMake projects consume it through
`CMAKE_PREFIX_PATH`:

```bash
cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$(python -m pyyggdrasil --prefix)"
```

```cmake
find_package(yggdrasil 0.0.25 CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE yggdrasil::yggdrasil)
```

For compiler invocations launched from Python, use `pyyggdrasil.include_dir()`
for the C++ headers and `pyyggdrasil.library_dirs()` for installed native
library directories.

## fmt Formatters

Yggdrasil's public `fmt::formatter` specializations are guarded by the
`YGG_ENABLE_FMT_FORMATTERS` macro, which defaults to `1`
(`yggdrasil/core/config.hpp`). Consumers can opt out by defining
`YGG_ENABLE_FMT_FORMATTERS=0`. For Yggdrasil's own builds, the
`YGGDRASIL_ENABLE_FMT_FORMATTERS` CMake option (default `ON`) toggles the
macro.
