mcpp.toml

[package]
namespace   = "mcpplibs"
name        = "openkal-windows"
version     = "0.7.2"
description = "An implementation of openkal for Windows, written on the Win32 interfaces and the object manager beneath them, using no C runtime symbol."
license     = "Apache-2.0"

# The layer this package supplies, in the vocabulary the engine resolves.
#
# `mcpp:kernel-abi` names the platform interface a C library sits on. On a
# traditional stack that seam is unnamed — a C library issues system calls or
# calls the platform's own entry points directly — and naming it is what lets
# one C library sit above several platforms. `=openkal` is the interface this
# package answers to; several packages answer to it and the engine knows none
# of them by name.
provides    = ["mcpp:kernel-abi=openkal"]
authors     = ["mcpplibs"]
repo        = "https://github.com/mcpplibs/openkal-windows"

[dependencies]
openkal = "0.12.0"

# The package contributes definitions and no modules. The interface it
# implements is declared by the specification package, which this package
# includes and does not re-export.

# The libraries this environment's own interfaces live in.
#
# ntdll carries the object manager, which is where a name relative to a
# directory is opened --- the operation openkal declares and Win32 does not
# offer. synchronization carries the suspension primitive. shell32 carries the
# operation that splits a command line into a vector, which is this
# environment's own definition of what its argument vector is and is therefore
# used rather than reimplemented.
#
# They are named twice because the two application binary interfaces this
# environment has spell a library differently: one names it as an argument to
# the linker and the other as an input file. Naming them once in the spelling of
# either would make this package build under two of the three toolchains it is
# written for.
# ⚠️ THE PREDICATE IS THE OBJECT ABI, NOT THE C LIBRARY.
#
# These four are Win32 import libraries — a property of the platform interface
# this package implements. `env = "gnu"` was standing in for "the GNU/PE ABI
# rather than the MSVC one", and on a traditional stack the two coincide. They
# stop coinciding the moment the C library comes from the dependency graph: a
# build of `x86_64-windows-gnu` over openkal resolves musl, and one spelled
# `x86_64-windows-musl` is the same build under an honest name. Under the old
# predicate the second one linked with none of these libraries and failed on
# `GetStdHandle`.
[target.'cfg(all(windows, not(env = "msvc")))'.build]
ldflags = ["-lntdll", "-lsynchronization", "-lshell32", "-lkernel32", "-lbcrypt"]

# Exceptions and run-time type information, on the one ABI where their absence
# is asserted.
#
# This package throws nothing and has no virtual function, but a compiler still
# emits a landing pad for every function holding an object with a destructor,
# and each landing pad references its own runtime's personality routine. On this
# ABI the property that the objects reference no C runtime symbol is checked, and
# a program that selects `standalone' here has no such runtime to supply that
# routine --- so the landing pads are not emitted.
#
# On the other ABI the flags are absent, and deliberately. A program using that
# ABI has a C runtime; there the toolchain's defaults are correct, one of the two
# toolchains that reach it would not recognise these spellings, and openkal has
# nothing to say about how a program that has a runtime unwinds.
#
# ⚠️ AND NO LOOP IS REPLACED BY A CALL, WHICH IS WHAT `-fno-builtin` IS FOR.
#
# An optimizing compiler recognises a loop that counts to a terminator and
# emits a call to the library function that does the same. `wide_length` in
# src/env.cpp counts sixteen-bit units and became `wcslen`; a byte loop in
# src/win.cpp became `strlen`. Neither is this environment's: the C library
# above is openkal-musl, whose `wchar_t` is thirty-two bits, so its `wcslen`
# read the command line two units at a time and every argument of a program
# built with `--release` came out shortened by a different amount. The dev
# profile does not optimize and never showed it, which is also why the check
# below now builds both profiles.
cxxflags = ["-fno-exceptions", "-fno-rtti", "-fno-builtin"]

# The other ABI names them in the sources instead --- src/win.cpp for the four
# above and src/random.cpp for bcrypt --- where its compilers record
# the requirement in the object they produce. A library named on the link line
# there would have to be named again by every program that links this package;
# a library named in the object travels with it.

# There is deliberately no guard flag for a function-local static. An earlier
# version disabled it; every static in this package is initialised by a constant,
# so no guard is emitted and the flag was doing nothing under any toolchain.

[features]
default = []

# Whether this implementation is the whole of the program's environment.
#
# Ordinarily a program already carries a runtime that has received control from
# the loader, and this implementation adds nothing. Where it does not, the entry
# point is this implementation's, and the link line names it.
standalone = { defines = ["OKW_STANDALONE"] }