# Overview

The build is a recursive make structure, with several projects vendored in to
`lib` that use their own Makefiles and also one primary `src/Makefile.am` that
defines most of the build.

- ALWAYS run `make -j $(nproc)` to get full parallelism
- ALWAYS run from the top level directory
- ALWAYS run with `2>&1 | tail -N` to limit output
- ALWAYS run `git add <somefile> && ./make-mks` after adding `<somefile>` to
  ensure it is included in the build.
- NEVER run from a subdirectory
- NEVER run with `make -C <somedir>` for any other directory
- NEVER run `cargo` manually, let `make` run it
- NEVER edit `Makefile` or `Makefile.in`, only ever edit `Makefile.am`

## Targets

The main targets are:

  - `all` -- the implicit target, builds `src/stellar-core`
  - `check` -- builds `all` then runs unit and integration tests
  - `clean` -- removes build artifacts
  - `format` -- auto-formats source code with standard rules

If anything goes wrong or is confusing in the build, start by running `make
clean` and trying again. You should have configured with `--enable-ccache` which
means that rebuilding will typically be very cheap. Especially if you run with
`make -j $(nproc)`

## Rust build

The `src/Makefile.am` also delegates to `cargo` to build the rust components
of stellar-core in `src/rust` as well as all the submodules in `src/rust/soroban`.
The integration is quite subtle. You should always let `src/Makefile.am` handle
invoking `cargo`.

## Generated files

Several source files are generated. All .x files in `src/protocol-{curr,next}`
are turned into .cpp and .h files by the `xdrpp` code-generator in `lib/xdrpp`.

Parts of the XDR query system in `src/util/xdrquery` are built by `flex` and
`bison`.

Files like `src/main/StellarCoreVersion.cpp` bake the current version
information into a string constant in stellar-core.

And finally the rust bridge `src/rust/RustBridge.{cpp,h}` is generated by the
`cxxbridge` tool from `src/rust/bridge.rs`.

## Editing the makefiles

Most of the time you won't need to edit `Makefile.am` or `src/Makefile.am` at all.

Files included in the build are driven by the script `./make-mks` which
lists files tracked by git and defines makefile variables based on them.
As soon as you add a .cpp or .h file to git and re-run `./make-mks`
it will be added to the build.