ernie-renderer 0.2.0.dev5__tar.gz → 0.2.0.dev7__tar.gz

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/.dockerignore

@@ -3,4 +3,5 @@ build
 dist
 .deps
 .venv
-docs/requirements
+requirements
+site

ernie_renderer-0.2.0.dev7/.github/scripts/coverage_badge.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: BSD-3-Clause
+"""Writes a shields.io endpoint badge and a job summary from gcovr's JSON summary."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def badge_colour(percent: float) -> str:
+    if percent >= 80.0:
+        return "brightgreen"
+    if percent >= 70.0:
+        return "green"
+    if percent >= 60.0:
+        return "yellow"
+    return "red"
+
+
+def main(report: Path) -> None:
+    summary = json.loads((report / "summary.json").read_text())
+    lines = summary["line_percent"]
+    branches = summary["branch_percent"]
+    badge = {
+        "schemaVersion": 1,
+        "label": "coverage",
+        "message": f"{lines:.1f}%",
+        "color": badge_colour(lines),
+    }
+    (report / "badge.json").write_text(json.dumps(badge))
+    if step_summary := os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(step_summary, "a") as out:
+            out.write(f"### Coverage\n\nLines {lines:.1f}%, branches {branches:.1f}%\n")
+
+
+if __name__ == "__main__":
+    main(Path(sys.argv[1]))

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/.github/workflows/ci.yml

@@ -156,6 +156,99 @@ jobs:
       - name: Test
         run: ctest --preset ci -j4
 
+  # Line and branch coverage of the C++ library from every test on Linux and lavapipe.
+  coverage:
+    needs: version
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    env:
+      ERNIE_TEST_REQUIRE_VULKAN: "1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install nanobind ninja pytest gcovr
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            .deps/*-src
+            .deps/*-subbuild
+          key: deps-${{ runner.os }}-${{ hashFiles('cmake/third_party/**') }}
+      - name: Install lavapipe
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y mesa-vulkan-drivers libvulkan1
+          icd=$(find /usr/share/vulkan/icd.d -name 'lvp_icd*.json' | head -n1)
+          echo "VK_DRIVER_FILES=$icd" >> "$GITHUB_ENV"
+          echo "VK_ICD_FILENAMES=$icd" >> "$GITHUB_ENV"
+      - name: Configure
+        run: >
+          cmake --preset coverage
+          "-DPython_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')"
+          -DERNIE_TEST_PYTHON=python
+      - name: Build
+        run: cmake --build --preset coverage --parallel 4
+      - name: Test
+        run: ctest --preset coverage -j4
+      - name: Report
+        run: |
+          mkdir -p coverage
+          gcovr --root . --filter 'ernie/' --exclude 'ernie/test/' --exclude '.*_table\.h' \
+            --object-directory build/coverage \
+            --html-details coverage/index.html --json-summary coverage/summary.json --print-summary
+          python .github/scripts/coverage_badge.py coverage
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: coverage
+          path: coverage
+          retention-days: 14
+
+  # The documentation, built strictly so broken links and warnings fail.
+  docs:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: docs
+          path: site
+          retention-days: 14
+
+  # The project site on GitHub Pages, from main: the docs, with the coverage report and its badge
+  # under coverage/.
+  pages:
+    needs: [lint, test, docs, coverage]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: docs
+          path: site
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: coverage
+          path: site/coverage
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - id: deploy
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+
   wheel:
     name: wheel (${{ matrix.platform }})
     needs: version

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/.gitignore

@@ -1,9 +1,11 @@
-# Local design documents
-docs/requirements/
+# Local design documents and tools, not yet part of the repository
+/requirements/
+/tools/
 
 # Build output and fetched dependencies
 build/
 dist/
+site/
 .deps/
 *.egg-info/
 __pycache__/

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/.pre-commit-config.yaml

@@ -16,6 +16,8 @@ repos:
     hooks:
       - id: clang-format
         types_or: [c++, c]
+        # Data tables written by tools/, kept exactly as generated.
+        exclude: _table\.h$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.17.1

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/CMakeLists.txt

@@ -1,5 +1,9 @@
 # SPDX-License-Identifier: BSD-3-Clause
 cmake_minimum_required(VERSION 3.21)
+# Extracted downloads get the time they were extracted, so they rebuild when they change.
+if(POLICY CMP0135)
+    cmake_policy(SET CMP0135 NEW)
+endif()
 
 project(
     Ernie
@@ -10,7 +14,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev5" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev7" CACHE STRING "Pre-release suffix of Ernie's version")
 set(ERNIE_VERSION "${PROJECT_VERSION}${ERNIE_VERSION_SUFFIX}")
 
 option(ERNIE_BUILD_TESTS "Build Ernie's tests" OFF)
@@ -18,6 +22,8 @@ option(ERNIE_BUILD_PYTHON "Build Ernie's Python module" OFF)
 option(ERNIE_BUILD_APP "Build the ernie program" ON)
 option(ERNIE_WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
 option(ERNIE_ASSERTS "Keep assertions in optimised builds" OFF)
+option(ERNIE_TRACY "Send profiling zones to the Tracy profiler too" OFF)
+option(ERNIE_COVERAGE "Instrument Ernie for code coverage (GCC or Clang)" OFF)
 
 get_property(ernie_multi_config GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 if(PROJECT_IS_TOP_LEVEL AND NOT ernie_multi_config AND NOT CMAKE_BUILD_TYPE)
@@ -34,6 +40,10 @@ if(ERNIE_BUILD_PYTHON)
     set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 endif()
 
+include(cmake/third_party/glm.cmake)
+include(cmake/third_party/dlpack.cmake)
+include(cmake/third_party/json.cmake)
+include(cmake/third_party/tracy.cmake)
 include(cmake/third_party/vulkan_headers.cmake)
 include(cmake/third_party/volk.cmake)
 
@@ -68,6 +78,12 @@ if(ERNIE_ASSERTS)
         INTERFACE $<IF:$<CXX_COMPILER_ID:MSVC>,/UNDEBUG,-UNDEBUG>
     )
 endif()
+if(ERNIE_COVERAGE)
+    # Unoptimised, so every line maps to its own counters; atomic, as ParallelFor's threads share
+    # them.
+    target_compile_options(ernie_build_options INTERFACE --coverage -fprofile-update=atomic -O0 -g)
+    target_link_options(ernie_build_options INTERFACE --coverage)
+endif()
 
 add_subdirectory(ernie)
 

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/CMakePresets.json

@@ -32,6 +32,19 @@
         "FETCHCONTENT_BASE_DIR": "${sourceDir}/.deps"
       }
     },
+    {
+      "name": "coverage",
+      "displayName": "Coverage",
+      "description": "Instrumented for code coverage, as CI measures it, in build/coverage",
+      "inherits": "dev",
+      "binaryDir": "${sourceDir}/build/coverage",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "ERNIE_COVERAGE": "ON",
+        "ERNIE_WARNINGS_AS_ERRORS": "ON",
+        "FETCHCONTENT_BASE_DIR": "${sourceDir}/.deps"
+      }
+    },
     {
       "name": "package",
       "displayName": "Packages",
@@ -57,6 +70,10 @@
       "name": "ci",
       "configurePreset": "ci"
     },
+    {
+      "name": "coverage",
+      "configurePreset": "coverage"
+    },
     {
       "name": "package",
       "configurePreset": "package"
@@ -76,6 +93,13 @@
       "output": {
         "outputOnFailure": true
       }
+    },
+    {
+      "name": "coverage",
+      "configurePreset": "coverage",
+      "output": {
+        "outputOnFailure": true
+      }
     }
   ]
 }

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev5
+Version: 0.2.0.dev7
 Summary: Efficient Renderer for Natural and Interplanetary Environments: a physically based, spectral Vulkan ray tracer
 Author: Alex Maietta
 License-Expression: BSD-3-Clause
@@ -16,6 +16,7 @@ Description-Content-Type: text/markdown
 > 🚧 **This project is in active beta development.** This means the API is unstable, features may be added or removed, and breaking changes are likely to occur frequently and without notice as the design is refined.
 
 [![CI](https://github.com/alexmaietta/ernie/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alexmaietta/ernie/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Falexmaietta.github.io%2Fernie%2Fcoverage%2Fbadge.json)](https://alexmaietta.github.io/ernie/coverage/)
 [![Release](https://img.shields.io/github/v/release/alexmaietta/ernie?include_prereleases&sort=semver&color=orange)](https://github.com/alexmaietta/ernie/releases)
 [![PyPI](https://img.shields.io/pypi/v/ernie-renderer?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/ernie-renderer/)
 [![Docs](https://img.shields.io/badge/docs-latest-8A2BE2)](https://alexmaietta.github.io/ernie/)

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/README.md

@@ -1,6 +1,7 @@
 > 🚧 **This project is in active beta development.** This means the API is unstable, features may be added or removed, and breaking changes are likely to occur frequently and without notice as the design is refined.
 
 [![CI](https://github.com/alexmaietta/ernie/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alexmaietta/ernie/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Falexmaietta.github.io%2Fernie%2Fcoverage%2Fbadge.json)](https://alexmaietta.github.io/ernie/coverage/)
 [![Release](https://img.shields.io/github/v/release/alexmaietta/ernie?include_prereleases&sort=semver&color=orange)](https://github.com/alexmaietta/ernie/releases)
 [![PyPI](https://img.shields.io/pypi/v/ernie-renderer?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/ernie-renderer/)
 [![Docs](https://img.shields.io/badge/docs-latest-8A2BE2)](https://alexmaietta.github.io/ernie/)

{ernie_renderer-0.2.0.dev5 → ernie_renderer-0.2.0.dev7}/cmake/ErnieTesting.cmake

@@ -9,6 +9,12 @@ set(ERNIE_TEST_TIMEOUT_unit 10)
 set(ERNIE_TEST_TIMEOUT_gpu 60)
 set(ERNIE_TEST_TIMEOUT_accuracy 120)
 set(ERNIE_TEST_TIMEOUT_python 120)
+# Unoptimised, instrumented coverage builds run several times slower.
+if(ERNIE_COVERAGE)
+    foreach(label unit gpu accuracy python)
+        math(EXPR ERNIE_TEST_TIMEOUT_${label} "${ERNIE_TEST_TIMEOUT_${label}} * 10")
+    endforeach()
+endif()
 
 # Adds the gtest executable ernie_tests_<name> and registers its tests as ernie.<name>.<test>.
 function(ernie_add_test_suite name)

ernie_renderer-0.2.0.dev7/cmake/third_party/dlpack.cmake

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_dlpack v1.3 CACHE STRING "Tag of DLPack to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_dlpack)
+
+include(FetchContent)
+FetchContent_Declare(
+    dlpack
+    GIT_REPOSITORY https://github.com/dmlc/dlpack.git
+    GIT_TAG ${ERNIE_DEP_VERSION_dlpack}
+    GIT_SHALLOW TRUE
+    SOURCE_SUBDIR no-build
+)
+FetchContent_MakeAvailable(dlpack)
+
+# The tensor exchange header, nothing to build.
+add_library(ernie_dlpack INTERFACE)
+target_include_directories(ernie_dlpack SYSTEM INTERFACE "${dlpack_SOURCE_DIR}/include")

ernie_renderer-0.2.0.dev7/cmake/third_party/glm.cmake

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_glm 1.0.3 CACHE STRING "Tag of glm to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_glm)
+
+set(GLM_BUILD_LIBRARY OFF)
+set(GLM_BUILD_TESTS OFF)
+set(GLM_BUILD_INSTALL OFF)
+
+include(FetchContent)
+FetchContent_Declare(
+    glm
+    GIT_REPOSITORY https://github.com/g-truc/glm.git
+    GIT_TAG ${ERNIE_DEP_VERSION_glm}
+    GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(glm)
+
+add_library(ernie_glm INTERFACE)
+target_include_directories(ernie_glm SYSTEM INTERFACE "${glm_SOURCE_DIR}")
+target_compile_definitions(ernie_glm INTERFACE GLM_FORCE_DEPTH_ZERO_TO_ONE)

ernie_renderer-0.2.0.dev7/cmake/third_party/json.cmake

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_json v3.12.0 CACHE STRING "Release of nlohmann/json to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_json)
+
+# The release's single-include archive, without the repository's tests and history.
+include(FetchContent)
+FetchContent_Declare(
+    nlohmann_json
+    URL https://github.com/nlohmann/json/releases/download/${ERNIE_DEP_VERSION_json}/include.zip
+)
+FetchContent_MakeAvailable(nlohmann_json)
+
+add_library(ernie_json INTERFACE)
+target_include_directories(ernie_json SYSTEM INTERFACE "${nlohmann_json_SOURCE_DIR}/single_include")

ernie_renderer-0.2.0.dev7/cmake/third_party/tracy.cmake

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_tracy v0.14.1 CACHE STRING "Tag of Tracy to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_tracy)
+
+# Ernie's profiling zones also go to Tracy when ERNIE_TRACY is on; otherwise this is empty.
+add_library(ernie_tracy INTERFACE)
+if(NOT ERNIE_TRACY)
+    return()
+endif()
+
+# Collect only while a profiler is connected, so a profiling build runs at full speed until then.
+set(TRACY_ENABLE ON CACHE BOOL "" FORCE)
+set(TRACY_ON_DEMAND ON CACHE BOOL "" FORCE)
+
+include(FetchContent)
+FetchContent_Declare(
+    tracy
+    GIT_REPOSITORY https://github.com/wolfpld/tracy.git
+    GIT_TAG ${ERNIE_DEP_VERSION_tracy}
+    GIT_SHALLOW TRUE
+)
+FetchContent_MakeAvailable(tracy)
+set_target_properties(
+    TracyClient
+    PROPERTIES POSITION_INDEPENDENT_CODE ON COMPILE_WARNING_AS_ERROR OFF
+)
+
+target_link_libraries(ernie_tracy INTERFACE Tracy::TracyClient)
+target_compile_definitions(ernie_tracy INTERFACE ERNIE_TRACY=1)

ernie_renderer-0.2.0.dev7/docs/README.md

@@ -0,0 +1,7 @@
+# Docs
+
+```sh
+python -m pip install -r docs/requirements.txt
+mkdocs serve # live preview at http://127.0.0.1:8000
+mkdocs build # static site in site/
+```

ernie_renderer-0.2.0.dev7/docs/index.md

@@ -0,0 +1 @@
+# Ernie

ernie_renderer-0.2.0.dev7/docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.6.1

ernie_renderer-0.2.0.dev7/ernie/core/CMakeLists.txt

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: BSD-3-Clause
+add_library(
+    ernie_core
+    STATIC
+    disk_cache.cpp
+    log.cpp
+    mapped_file.cpp
+    noise.cpp
+    profile_report.cpp
+    profiler.cpp
+    tensor.cpp
+    version.cpp
+)
+target_include_directories(ernie_core PUBLIC "${PROJECT_SOURCE_DIR}")
+target_link_libraries(
+    ernie_core
+    PUBLIC ernie_glm ernie_dlpack ernie_tracy
+    PRIVATE ernie_json ernie_build_options
+)
+find_package(Threads REQUIRED)
+target_link_libraries(ernie_core PUBLIC Threads::Threads)
+set_source_files_properties(
+    version.cpp
+    PROPERTIES
+        COMPILE_DEFINITIONS
+            "ERNIE_VERSION_STRING=\"${ERNIE_VERSION}\";ERNIE_BUILD_TYPE=\"$<CONFIG>\""
+)

ernie_renderer-0.2.0.dev7/ernie/core/disk_cache.cpp

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file disk_cache.cpp
+/// @brief Cache folder lookup and cache key hashing.
+#include "ernie/core/disk_cache.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <random>
+#include <system_error>
+
+namespace ernie {
+
+std::optional<std::filesystem::path> CacheDirectory(const char* variable, std::string_view folder) {
+    namespace fs = std::filesystem;
+    if (const char* own = std::getenv(variable)) {
+        const std::string_view value(own);
+        if (value.empty() || value == "0") {
+            return std::nullopt;
+        }
+        return fs::path(value);
+    }
+    if (const char* xdg = std::getenv("XDG_CACHE_HOME"); xdg != nullptr && *xdg != '\0') {
+        return fs::path(xdg) / "ernie" / folder;
+    }
+#if defined(_WIN32)
+    if (const char* local = std::getenv("LOCALAPPDATA"); local != nullptr && *local != '\0') {
+        return fs::path(local) / "ernie" / folder;
+    }
+#else
+    if (const char* home = std::getenv("HOME"); home != nullptr && *home != '\0') {
+        return fs::path(home) / ".cache" / "ernie" / folder;
+    }
+#endif
+    return std::nullopt;
+}
+
+void CacheKey::Add(std::string_view text) {
+    const std::uint64_t size = text.size();
+    Bytes(&size, sizeof(size));
+    Bytes(text.data(), text.size());
+}
+
+std::string CacheKey::Hex() const {
+    char text[33];
+    std::snprintf(text, sizeof(text), "%016llx%016llx", static_cast<unsigned long long>(hashes_[0]),
+                  static_cast<unsigned long long>(hashes_[1]));
+    return text;
+}
+
+void CacheKey::Bytes(const void* data, std::size_t size) {
+    const auto* bytes = static_cast<const unsigned char*>(data);
+    for (std::uint64_t& hash : hashes_) {
+        for (std::size_t i = 0; i < size; ++i) {
+            hash = (hash ^ bytes[i]) * 0x100000001b3ull;
+        }
+    }
+}
+
+std::optional<std::vector<float>> ReadCachedFloats(const std::filesystem::path& path,
+                                                   std::size_t count) {
+    std::ifstream in(path, std::ios::binary);
+    std::vector<float> values(count);
+    const auto bytes = static_cast<std::streamsize>(count * sizeof(float));
+    if (in.read(reinterpret_cast<char*>(values.data()), bytes) &&
+        in.peek() == std::ifstream::traits_type::eof()) {
+        return values;
+    }
+    return std::nullopt;
+}
+
+void WriteCachedFloats(const std::filesystem::path& path, std::span<const float> values) {
+    namespace fs = std::filesystem;
+    fs::path partial = path;
+    partial += ".part" + std::to_string(std::random_device{}());
+    std::error_code error;
+    fs::create_directories(path.parent_path(), error);
+    {
+        std::ofstream out(partial, std::ios::binary);
+        out.write(reinterpret_cast<const char*>(values.data()),
+                  static_cast<std::streamsize>(values.size_bytes()));
+        if (!out) {
+            error = std::make_error_code(std::errc::io_error);
+        }
+    }
+    if (!error) {
+        fs::rename(partial, path, error);
+    }
+    if (error) {
+        fs::remove(partial, error);
+    }
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev7/ernie/core/disk_cache.h

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file disk_cache.h
+/// @brief Cache folders and keys for caches kept between runs.
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <optional>
+#include <span>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace ernie {
+
+/// @brief Finds where one of Ernie's caches keeps its files.
+/// @param variable An environment variable naming the folder; empty
+///                 or "0" disables the cache.
+/// @param folder   The subfolder of the user's cache folder used
+///                 when `variable` is unset (`$XDG_CACHE_HOME/ernie`,
+///                 `~/.cache/ernie`, `%LOCALAPPDATA%\ernie`).
+/// @return The folder, or nothing when the cache is disabled.
+std::optional<std::filesystem::path> CacheDirectory(const char* variable, std::string_view folder);
+
+/// @brief A 128-bit key over everything a cache entry depends on.
+/// Two 64-bit FNV-1a hashes from different seeds; each piece is
+/// length-prefixed.
+class CacheKey {
+  public:
+    /// @brief Mixes a piece of text into the key.
+    /// @param text The piece to add.
+    void Add(std::string_view text);
+
+    /// @return The key as 32 hex digits, for a file name.
+    std::string Hex() const;
+
+  private:
+    void Bytes(const void* data, std::size_t size);
+
+    std::array<std::uint64_t, 2> hashes_{0xcbf29ce484222325ull, 0x84222325cbf29ce4ull};
+};
+
+/// @brief Reads a cache file of floats.
+/// @param path  The file.
+/// @param count How many floats it must hold.
+/// @return The floats, or nothing if the file is missing or holds a different amount.
+std::optional<std::vector<float>> ReadCachedFloats(const std::filesystem::path& path,
+                                                   std::size_t count);
+
+/// @brief Writes a cache file of floats so that no reader ever sees part of it: written beside it,
+/// then renamed over it. Failures leave no file behind and are otherwise ignored, since a cache
+/// can always be rebuilt.
+/// @param path   The file; its folder is created if needed.
+/// @param values The floats.
+void WriteCachedFloats(const std::filesystem::path& path, std::span<const float> values);
+
+}  // namespace ernie