[package]

namespace = "mcpplibs"

name = "openkal-windows"

version = "0.10.1"

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"

# WHICH INTERFACES THIS IMPLEMENTATION PROVIDES, DERIVED FROM THE ARTEFACT AND

# NOT WRITTEN BY HAND.

#

# openkal's specification names no set of interfaces: clause 3.3 withdrew the

# one it had named (`hosted`) because a name describing a class of environment

# is falsified by an environment nobody had in mind, and that one was falsified

# inside its own ecosystem within a release. Enumeration by the package

# replaced it, and a build tool reads this array at dependency resolution

# against the `requires-interfaces` a consumer states in its own manifest --

# the first of the three times clause 6.2 tabulates, and the earliest at which

# the question can be answered.

#

# FOURTEEN AND NOT FIFTEEN. `openkal.space` is absent: this environment has no

# operation upon an address space it can supply, and clause 3 says an

# implementation provides an interface in whole or not at all. A consumer that

# needs it is refused here and builds on openkal-linux, which is the whole

# point of stating the set rather than a name for a class of environment.

#

# GENERATED, AND CI DIFFS IT AGAINST THE OBJECTS:

#

# bash .spec/tools/check-surface.sh --toml .spec/SURFACE.txt \

# $(find target -path '*/obj/*' -name '*.o' ! -name '*.m.o')

#

# BACKWARD COMPATIBLE. An engine that predates the key reads `[kernel-abi]` as

# an unknown top-level table and ignores it, so this manifest loads unchanged

# everywhere it loaded before.

[kernel-abi]

provides-interfaces = [

"openkal.abort",

"openkal.stream",

"openkal.memory",

"openkal.env",

"openkal.time",

"openkal.random",

"openkal.fs",

"openkal.process",

"openkal.task",

"openkal.exec",

"openkal.terminal",

"openkal.net",

"openkal.datagram",

"openkal.timeout",

]

[dependencies]

openkal = "0.14.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"] }