Build tools

The C++ programs the build uses, and how to run one by hand

Build tools

OctoMY's build tools are C++ programs under src/tools/, built by the same build that uses them. A contributor can run every one of them by hand, and each explains itself with --help.

This section documents the tools a contributor invokes directly. A tool that only ever runs as a build step is documented by the how-to that covers the step it belongs to.

Tool	What it does
`apidocs`	Derives what QDoc may read from the tree, and writes the generated configuration for the API reference
`lint`	Runs the policy checks of the tree, and the exception and RTTI check of the build
`winvm`	Runs the local Windows 11 build VM on libvirt and QEMU: install, provision, start and stop, detached builds, snapshots and the sysroot of a cross build
`icon`	Cuts the icon sheet into one SVG per icon, and renders an application's icon for Windows, MSIX and Android. See icon below
`memstress`	Tests the memory of a machine: fills large blocks with a known pattern, reads them back, copies them and reads again. See memstress below

Invoking a tool

Build and run a tool with qbs, from the repository root. Arguments go after --:

qbs run -p <tool> -- <arguments>

Every tool follows the same three conventions:

Its answer goes to standard output. Progress, warnings and the summary go to standard error, so a build rule can parse the answer.
--quiet leaves errors only. --verbose prints the decisions taken. Both mean the same thing in every tool.
A wrong command line exits 2. Work that was attempted and failed exits 1. A caller can tell the two apart without reading text.

icon

icon is the one tool for the icons of the tree. Each verb takes --help.

Verb	What it does
`icon export <icons.svg> <folder> [flags]`	Cuts the master sheet into one SVG per cutout. `--check` writes nothing and fails when the folder differs from the sheet. `--auto-tag` and `--align-grid` edit the master. See Regenerate the icons
`icon ico <svg> <ico> [<rc>]`	Writes a Windows `.ico` with the seven sizes a window icon carries, and the `.rc` that names it. `--sizes 16,32` picks other sizes
`icon msix <svg> <folder>`	Writes the MSIX tile PNGs at five scales. `--profile app` writes the two tiles of one application, and `package`, the default, adds the store logo and the wide tile
`icon android <app>`	Writes the sixteen launcher rasters of `src/<app>/android/res/` from `icons/window/app/<app>.svg`. `--root <checkout>` names the checkout

icon replaces icon-export, iconmanager and window-icon. The three old programs stay until the build farm runs icon.

memstress

memstress finds memory that loses bits: unstable timings, an unstable fabric clock or too little voltage. In this project that failure shows as a corrupted object file, a link that fails for no clear reason, or a test that fails once and then passes. It is installed, so that you can run it on a machine that does not build the tree.

memstress -gb 40 -seconds 1800 -threads 16

Option	Meaning	Default
`-gb <n>`	The memory to test, in GiB. It is committed and touched before the test starts, so leave a few GiB free	40
`-mib <n>`	The memory to test, in MiB. Overrides `-gb`
`-seconds <n>`	How long to run	1800
`-threads <n>`	Worker threads. Each thread needs two blocks, so a small run gets fewer threads	16
`--inject-fault`	Changes one bit after the first write. The run must then exit 1. Use it to prove that the check can fail

The options take one dash or two. One dash is the form of the first version, which notes and scheduled tasks on the Windows machines still use.

Exit	Meaning
0	No mismatch
1	At least one mismatch
2	The memory could not be committed, or the command line was wrong. Nothing was tested

Read the signature, not only the count. A few mismatches with one changed bit each (the xor= field has one bit set) is the hardware. A whole block that is different is a defect in the test. A rate that increases during the run is the modules getting warm, so a two-minute run can pass where a thirty-minute run fails. On Windows, start a long run through schtasks, so that it continues after the SSH session that started it closes.