xmake notes and tips and tricks

We use xmake to build code in this tree. We also use xmake to handle some of our third-party dependencies which are not in the tree.

This document is intended as a basic guide on how to accomplish some common things when working with the Zen codebase.

The official documentation for xmake is located here: https://xmake.io/ it covers most features but isn't necessarily rich in examples on how to accomplish things on different platforms and environments.

Build basics

xmake is what I'd call a "stateful" build system in that there is a 'configuration' step which you will generally want to run before actually building the code. This allows you to specify which mode you want to build (in our case, "debug" or "release"), and also allows you to perform additional configuration of options such as whether we should include support for Sentry crash reporting, use of 'mimalloc' for memory allocations etc etc

Configure xmake for building 'debug' (which includes building all third-party packages) and triggering a build, issue these commands in the shell:

dev/zen> xmake config --mode=debug
dev/zen> xmake

If all goes well, you will be able to run the compiled programs using:

dev/zen> xmake run zenserver
dev/zen> xmake run zen

Cleaning out all build state

You may run into build issues at some point due to bad on-disk state. For instance your workstation could crash at an inopportune moment leaving things in an inconsistent state, or you may run into bugs in compilers or the build system itself.

When faced with this it's good to be able to wipe out all state which influences the build. Since xmake uses a number of different locations to store state it's not entirely obvious at first how to accomplish this.

Windows

dev\zen> rmdir /s /q .xmake build %LOCALAPPDATA%\.xmake %TEMP%\.xmake

Linux / MacOS

dev/zen> rm -rf .xmake build ~/.xmake