# 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
```