Skip to content

configuration-files.md

Latest commit

 

History

History
186 lines (145 loc) · 8.17 KB

configuration-files.md

File metadata and controls

186 lines (145 loc) · 8.17 KB
Raw
title Configuration Files Reference
audience users, developers
prerequisites packaging, CLI commands
related cli-commands.md, python-api.md, ../guide/building-shared-library.md, ../../developer/quality-assurance.md
status maintained
publication draft

Configuration Files Reference

prik currently has no user-authored project configuration file for wrapper builds. The stable file contracts are generated build replay files and repository tooling configuration. Command-line flags and Python API arguments remain the source of truth for selecting wrapper inputs.

Use CLI Commands Reference for the option surface and Python API Reference for the equivalent library entrypoints.

prik-build.json

prik-build.json is emitted only for semantic .pyi wrapper builds that use Makefile mode:

python3 -m prik generate --makefile contracts/module.pyi \
  --native-fortran-sources native/module.f90 \
  --out-dir build/module \
  --json

The manifest is written to <out-dir>/prik-build.json before Makefile.prik. It is a replay contract for the .pyi build, not a general project settings file.

Stable top-level fields:

Field Meaning
schema_version Manifest schema version. The current supported value is 2.
build_kind Manifest kind. The current supported value is pyi-wrapper.
entry_contract Entry semantic .pyi path used for the build.
contract_paths Complete discovered .pyi import graph. Replay fails if the current graph differs.
extension Requested and resolved Python extension names.
output Output directory, shared-library path, and strict-name setting.
compiler Input-language compiler executable, compiler profile, and wrapper/native flag values recorded by the build.
native_build_plan Native compilation units, produced objects, prebuilt artifacts, module/include directories, library directories, and ordered link items.

Relative paths are resolved relative to the manifest directory during replay. Schema 2 records the selected input-language compiler executable and the build-wide include directories needed to reproduce native, bridge, binding, and link commands; schema 1 manifests are no longer accepted. Use:

python3 -m prik --build-manifest build/module/prik-build.json
python3 -m prik generate --makefile --build-manifest build/module/prik-build.json

The first command reads the existing manifest and rebuilds from it; it does not generate a manifest. The second also reads the existing manifest, then regenerates Makefile.prik without positional contracts or repeated native build flags. The preceding generate --makefile command is what writes a new prik-build.json.

Replay accepts only settings that are defined as overrides: --out, --compiler, -I/--include-dir, --json, --verbose, --no-color, and --debug. The manifest remains authoritative for its output directory, language, preprocessing recipe, wrapper behavior, native inputs, and ordered link plan. Passing one of those saved settings again is an error rather than an ignored command-line value.

Makefile.prik

Makefile.prik is generated by --makefile. It records the compile and link commands prik would run for the selected wrapper build. Makefile mode does not compile the shared library at generation time.

Run it with GNU Make:

make -f build/module/Makefile.prik -j4

The generated Makefile may expose override variables for native and wrapper flags, such as PRIK_FFLAGS, PRIK_CFLAGS, and PRIK_LDFLAGS. Treat the file as generated output: regenerate it after changing source inputs, semantic contracts, native artifacts, compiler flags, output names, or the prik version.

For semantic .pyi builds, the Makefile depends on prik-build.json, the complete .pyi graph, and native link inputs. For source-driven builds, the Makefile records the selected native source ordering and generated wrapper artifacts.

pyproject.toml

The repository pyproject.toml is developer-facing configuration. It defines package metadata, optional QA dependencies, pytest markers, coverage behavior, Ruff, Bandit, Vulture, and Radon settings.

The coverage contract is:

Section Current role
[tool.coverage.run] Measures branch coverage for prik, writes parallel data, and stores relative paths.
[tool.coverage.report] Shows missing lines, keeps covered files visible, reports with precision 2, and enforces fail_under = 90.

When investigating coverage failures that involve subprocesses, run coverage with COVERAGE_PROCESS_START=pyproject.toml, combine parallel data, then report. The maintained workflow is documented in Quality Assurance.

codecov.yml

The repository-level codecov.yml mirrors the blocking 90% coverage.py project floor for Codecov reporting. Changed-line, or patch, coverage is reported as informational so a very small patch is not judged by an implicit 100% target. This does not relax the local or CI project gate, and reachable new behavior is still expected to have focused tests.

Do not treat pyproject.toml as a user wrapper-build configuration file. Wrapper users select inputs through CLI flags, Python API arguments, semantic .pyi contracts, and generated manifests.

mkdocs.yml

mkdocs.yml is the documentation-site configuration. It sets docs_dir: docs, selects MkDocs' built-in Read the Docs theme, owns the complete intended navigation tree, and loads the publication hook. The theme configuration keeps the sidebar expanded through four navigation levels. A local stylesheet keeps its scrollbar visible and draggable when the navigation is longer than the screen. The same stylesheet keeps the page body adjacent to the sidebar with a 1200px maximum width, balancing readable prose with room for code and tables. Code and result blocks use the available page width up to a consistent 56rem cap; long lines scroll inside the block. Local JavaScript and CSS add an accessible copy control to every rendered code, command-output, and result block, with separate space reserved beside the text. The production hook includes only pages whose front matter says publication: reviewed. A draft lane index suppresses its complete User, Developer, or Maintainer lane. Links from documentation pages to existing source, tests, configuration, and other repository evidence are rendered as GitHub links because those files are outside the MkDocs source tree. Links between documentation pages remain site-relative and are never rewritten to GitHub.

Preview exactly what GitHub Pages will publish with:

python3 -m mkdocs serve

Include unpublished pages locally while reviewing them with:

PRIK_DOCS_INCLUDE_DRAFTS=1 python3 -m mkdocs serve

Changing a page from publication: draft to publication: reviewed makes it eligible for the next production deployment. New pages must also be reachable from the appropriate area index and mkdocs.yml navigation.

Documentation-only changes normally run:

python3 -m pytest -q tests/shared/docs
python3 -m mkdocs build --strict
git diff --check

The documentation tests verify metadata, publication filtering, TODO policy for unfinished pages, navigation for required areas, visible deferred-doc boundaries, reference links, and documentation checklist synchronization.

Evidence And Maintenance

Manifest and Makefile replay behavior is covered by test_pyi_build_modes.py and source-build Makefile behavior by test_build_modes.py.

Tooling configuration is covered by test_documentation_structure.py, test_documentation_examples.py, and test_check_static_analysis_versions.py.

When a generated file contract changes, update this page with the CLI reference, Python API reference, shared-library build guide, and wrapper tests that prove the replay or Makefile behavior.