The release package¶
What a game developer downloads, how xmake package-release makes it and how it is checked. The plan and the decisions
are in plan.md.
Layout¶
One zip per platform and architecture, named aylo-engine-<version>-<os>-<arch>.zip (os is linux, macos or
windows, arch x86_64 or arm64), holding one folder of the same name:
aylo-engine-<version>-<os>-<arch>/
├── runtime/ what a game ships
│ ├── aylo-runtime(.exe)
│ ├── lib/ the shared libraries that are not plugins: `ecs`, the contracts and the C++ runtime (the
│ │ other engine modules are static, inside aylo-runtime)
│ ├── plugins/ the plugin libraries, real files; the engine scans this folder
│ │ └── backends/ the platform, renderer and audio backends, scanned too
│ └── licenses/ THIRD_PARTY_NOTICES.md
├── tools/aylo-sign(.exe)
├── templates/game/ a game that runs, from examples/games/template/game/
├── manual/ the manual, built for offline reading
├── README.md LICENSE VERSION
└── manifest.json
The engine looks for plugins/ and plugins/backends/ next to the executable, so runtime/ works wherever it is copied.
The build folder has the same layout (build/<platform>/<arch>/<mode>/), so what runs there runs in the zip. No file of
the zip is a symbolic link: every library is one real file, in the one folder that holds it. On Windows, which has no
rpath, the DLLs of lib/ sit next to the executable instead (there is no lib/ folder in the zip), which is where
the DLLs of plugins/ find them. How a binary finds its libraries is in
self-contained.md.
The editor will get its own editor/ folder, outside runtime/, so that shipping the runtime never ships it.
manifest.json holds the version (a nightly build is <version>-nightly.<commit>), the commit, the platform and
arch, the toolchain, the library_abi and the sha256 of every other file of the zip. Its version, commit,
toolchain and ABI are read from aylo-runtime --version, so it cannot disagree with the binary.
A -symbols zip next to it holds the debug information of the binaries (.debug files on Linux, .pdb on Windows). It
is only made when the build has some: a release build is stripped at link time, so there may be none.
The version¶
One place: set_version in the root xmake.lua. aylo-runtime --version prints it:
aylo-engine 0.1.0
commit: 772b71bd
toolchain: clang 21.1.0
library ABI: 1
A nightly build is configured with xmake f --nightly=<commit>, which makes the version 0.1.0-nightly.<commit>.
RTYPE_COMMIT gives the commit to a build made without git. The code is xmake/modules/engine_version.lua; the format
is rtype::core::version::describe (src/rtype/core/version/).
Making it¶
xmake f -y -m release
xmake package-release # builds aylo-runtime and aylo-sign first (--no-build to skip), then packages
The output is in build/package/. Options: --no-build packages what is already built, --no-manual leaves the manual
out (also left out, with a warning, when uvx is not installed). The task refuses a build that is not a release build.
It then:
- copies the runtime,
lib/andplugins/as the build made them, leaving out the libraries made for the tests, adds the C++ runtime tolib/(Linux, withpatchelf) and sets the search paths of the executable and the tool to the folders of the zip ($ORIGIN/lib:$ORIGIN/plugins, and$ORIGIN/../runtime/lib:$ORIGIN/../runtime/pluginsfortools/aylo-sign; on Windows its DLLs are copied next to it); - adds the licenses, the template game, the manual, the README, the version and the license of the repository (with a warning when the repository has none);
- strips what is not stripped and keeps the debug information apart;
- runs
.github/scripts/check-self-contained.sh(.ps1on Windows) onruntime/, when it exists: a missing script is a warning, a failing one stops the package; - writes
manifest.jsonand makes the zips.
Checking it¶
.github/scripts/smoke-test.sh <zip> (.ps1 on Windows) behaves like a user: it unzips into an empty directory and
checks the layout and the hashes of the manifest, the version the runtime reports, the dependencies of runtime/, a
server started on templates/game and a headless client connecting to it, and aylo-sign keygen. Run it on a machine
with no toolchain, such as a bare container, for the answer that counts.
The server's output goes to a file, and a program's output to a file is buffered, so a player joining reaches the log
only when the server stops. The shell script runs the server under stdbuf -oL to see it, and so checks the connection
on Linux; on macOS (no stdbuf) and on Windows it only checks that the server and the client stay up, and says so. A
log line from the engine on stderr when a client connects would make the check the same everywhere.