mcpp.toml

[package]
name         = "offscreen-triangle"
namespace    = "example"
version      = "0.1.0"
description  = "A Vulkan graphics pipeline rendering offscreen, with a software rasteriser behind the same seam"
accelerators = ["vulkan"]

[language]
standard   = "c++23"
modules    = true
import_std = true

# One edge. `mcpp.rules.spirv` declares the shader compiler it drives, so this
# project names no payload for it.
[build-dependencies.mcpp]
plugins = { version = "0.5.2", features = ["rules-spirv"], host-module = true }

# The Khronos loader. Unconditional, and the reason is a rule of the engine
# rather than a preference: A DEPENDENCY CANNOT BE CONDITIONED ON A LAYER.
# `accelerator` is resolved FROM the dependency graph, so a dependency chosen by
# it would decide the answer it is asking. mcpp says so and ignores the
# predicate -- measured here, where an earlier revision of this file gated these
# three entries on `cfg(accelerator = "vulkan")` and the build failed on
# `vulkan/vulkan.h: No such file or directory`, because the header's package had
# been silently dropped while the source that includes it was kept.
#
# `[build]` sources under the same predicate DO apply, which is what makes the
# seam work: the CPU leg below is selected by the accelerator, and only the
# packages are unconditional.
[dependencies.compat]
vulkan = "1.4.357.2"

# THE ADAPTER IS NOT NAMED HERE, AND THAT IS THE POINT.
#
# `compat.vulkan` declares `compat.vulkan-runtime` itself on Linux -- the
# adapter that makes the host's own ICDs reachable from a binary running under
# mcpp's private loader, which macOS and Windows do not need because dyld and
# the PE loader have no private-loader problem to work around.
#
# Naming it here as well pinned one version in two places, in two repositories,
# with nothing enforcing that they agree. They drifted three times in one day:
# the loader package moved its pin, this file moved its own, and an installed
# copy of `compat.vulkan` still recorded the previous one -- each time the build
# stopped with `irreconcilable versions`, and each time the fix was to edit the
# other place. A dependency that another dependency already declares is a
# second copy of a decision; the version it needs is the one that package says
# it needs.

# A Vulkan device that needs no GPU, so this example runs on a machine that has
# none. It is a DEVICE and therefore a payload; the drivers a real GPU needs are
# the host's, and `compat.vulkan` models those as a capability. Published for
# Linux alone, so the predicate names the platform rather than the accelerator.
[target.'cfg(linux)'.xlings.workspace]
"xim:mesa-lavapipe" = "26.2.1"

# THE OTHER TWO PLATFORMS GET A DEVICE TOO, AND FOR THE SAME REASON.
#
# These were absent while the example was built but not run on macOS and
# Windows, which made the omission invisible: a program that never runs never
# asks the loader for a device. Declaring the driver here rather than installing
# it from a CI step is what makes the EXAMPLE complete -- anyone who checks it
# out gets a machine that can run it, not only the runner that had an extra
# command.
#
# macOS has no native Vulkan. MoltenVK is an implementation on top of Metal, and
# the specification calls that a portability driver: the loader does not hand it
# to `vkEnumeratePhysicalDevices` unless the instance asked for portability
# enumeration, which `src/vulkan/render.cpp` now does. The two halves are one
# change -- the package without the enumeration finds no device, and the
# enumeration without the package has nothing to find.
[target.'cfg(macos)'.xlings.workspace]
"xim:moltenvk" = "1.4.2"

# WINDOWS DECLARES NO DEVICE, AND WHAT RULED OUT THE OBVIOUS CAUSES IS IN
# `.github/workflows/ci-windows.yml` BESIDE THE STEP THAT WAS WITHDRAWN.
#
# Four things were measured and none of them is it: the loader is present (the
# program runs and reports for itself), the ICD manifest now parses (a real
# defect, fixed in openxlings/xim-pkgindex#781), `vulkan_lvp.dll` imports only
# system DLLs, and both spellings of the driver-files variable were set.
#
# Declaring the driver here would download 56 MB that produces no device, so it
# is not declared until the remaining cause is known.

[build]
accel = "vulkan1.2"
sources = [
  "src/*.cppm",
  "src/*.cpp",
  # Two globs rather than one over `shaders/*`: the stages are different things
  # and the manifest is where a reader learns which ones this project has.
  { glob = "shaders/*.vert", accel = "vulkan1.2" },
  { glob = "shaders/*.frag", accel = "vulkan1.2" },
]
include_dirs = ["include"]

[target.'cfg(accelerator = "vulkan")'.build]
sources = ["src/vulkan/*.cpp"]

# The same triangle, rasterised in software. The pixel assertions are the
# contract and both legs satisfy it; `device_name()` is what tells them apart.
[target.'cfg(not(accelerator = "vulkan"))'.build]
sources = ["src/cpu/*.cpp"]

[targets.offscreen-triangle]
kind = "bin"
main = "src/main.cpp"