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