running-make-to-build

name	running-make-to-build
description	how to run make correctly to get a good build, and otherwise understand the build system

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.