m3build processing steps

When m3build is invoqued, it initializes the quake interpreter with values for BUILD_DIR (defaults to the platform name unless specified on the command line), PACKAGE (the name of the current directory), and PACKAGE_DIR (the full path of the current directory). The build_target is also defined as _build_target. It defaults to all (_all), and clean is the other typical value.

The second step is to find and interpret the platform dependent template, specified as BUILD_DIR, or found in the M3_TEMPLATE environment variable. The template directory may be specified on the command line, in the M3_TEMPLATE_DIR environment variable, and defaults to m3config/src within the directory specified in PKG_USE when m3build was compiled. As a last resort, directory ../lib/m3/pkg/m3config/src is searched relative to the directory where the m3build executable may be found.

The next step is to insert all the definitions, and to interpret all the files, specified as command line options.

At this point, a number of quake variables are extracted by the compiler before the processing of the m3makefile starts. The host and target in these descriptions refer to platform types and differ only when cross compiling.

NAMING_CONVENTIONS
Vector containing all the host dependent file extensions (.s, .c, .o, .exe...).
TARGET_NAMING_CONVENTIONS
Vector containing all the target dependent file extensions.
CRship
End of line for .M3SHIP files.
SLship
Path separator for .M3SHIP files.
PKG_USE, BIN_USE, LIB_USE
Location of packages, program executables, and libraries.
PKG_INSTALL, BIN_INSTALL, LIB_INSTALL, MAN_INSTALL, EMACS_INSTALL, DOC_INSTALL, HTML_INSTALL
Where to install packages, program executables, libraries, man pages, emacs lisp files, postscript files, and html files. In most cases the USE and INSTALL directories are the same.
HOST_OS_TYPE
The host operating system type (POSIX or WIN32).

The m3makefile is then processed, and the list of sources built, until the ending Library(), Program(), or OtherPackage() quake function is encountered. At this point, the before_do_m3_hook() quake function is called to set things up before the compilation proceeds. More quake variables are then extracted by m3build.

Options
Table containing compilation options values.
TARGET
Target machine.
M3_COVERAGE_LIB
Library required for coverage analysis.
INTERNAL_BACKEND, M3_BACKEND_OUTPUT
Whether to use the internal backend.
OPTION_GUI
Whether to create a gui WIN32 application.

The compilation then proceeds and m3build calls back a number of template defined quake procedures for various platform dependent tasks:

m3_compile_c
Compile a C file.
m3_link
Link a program.
m3_make_lib
Create static and dynamic libraries.
m3_note_shlib
Add libraries in the list of derived files.
m3_assemble
Assemble an assembly file.
m3_backend
Convert the intermediate language into assembly.
install_file
Install a file during m3ship.
emacs_compile
Compile and emacs lisp file.

In all cases, m3build creates or updates the files .M3EXPORTS (exported files), .M3IMPTAB (location of all imported files), .M3SHIP (files to ship with m3ship), and .M3WEB (information for the browser m3browser). With the all default build_target, the actual compilation is performed. With the clean build_target, the list of derived files (which would have been created by the compilation) is used to clean the build directory.