GPRbuild Reference

GPRbuild is a multi-language build tool for GPR project trees. It compiles sources, binds Ada programs, builds libraries, and links executables, using a persistent build database and checksum-based change detection for reliable incremental builds.

GPRbuild2, the current build engine, models the build as a directed acyclic graph (DAG) of actions and is the recommended engine.

Build Engine Selection

Two build engines are available. Set the GNAT_GPR_ENGINE environment variable, or pass --gpr=n on the command line (takes precedence):

1 / legacy: The original GPRbuild engine. Current default.
2 / new: GPRbuild2: DAG-based execution, checksum-based change detection, persistent build database. The recommended engine.

GNAT_GPR_ENGINE=2 gprbuild -P my_proj.gpr
gprbuild --gpr=2 -P my_proj.gpr

The rest of this chapter documents GPRbuild2 behavior and switches.

Command Line

Syntax

gprbuild [<proj>.gpr] [switches] [mains]
 {[-cargs[:<lang>] opts] [-bargs[:<lang>] opts]
  [-largs opts] [-kargs opts] [-gargs opts]}

Project file

See Common Command-Line Options for project file discovery rules and the project search path environment variables.

Main sources

Main source files to build may be listed on the command line by simple file name or full path. When a simple name is given, GPRbuild searches the entire project tree for a source whose basename matches. If the name matches sources in more than one project, GPRbuild reports an error. If no mains are given on the command line, GPRbuild uses the Main attribute of the root project. If that is also absent, no executable is built.

Pass-through option groups

Options may be forwarded to individual tools by preceding them with a section switch. Each section switch introduces options that apply up to the next section switch or end of the command line.

-cargs: All compilers (all languages).
-cargs:lang: The compiler for lang only.
-bargs: All binder drivers.
-bargs:lang: The binder driver for lang only.
-largs: The linker.
-kargs: GPRconfig (auto-configuration invocation).
-gargs / -margs: GPRbuild itself (useful after other section switches).

Switches

Project, configuration, and common diagnostics switches are documented in Common Command-Line Options. The sections below cover GPRbuild-specific switches.

Phase selection

-c: Include only compile actions in the DAG.
-b: Include only bind actions in the DAG.
-l: Include only link actions in the DAG.

Note

These switches are compatibility filters over GPRbuild2’s action DAG. -c maps cleanly to compile actions. -b includes not only the binder invocation but also the compilation of the binder-generated Ada source, so it involves actual compile steps. -l may cover a range of intermediate actions beyond the final linker call: intermediate archive creation, partial linking, linker-options section generation, and similar housekeeping. In the legacy engine these stages were driven by separate tools (gprbind for -b, gprlib for -l); GPRbuild2 models them as ordinary actions in the DAG with no distinct stage boundaries, and -b / -l simply select the corresponding subsets.

-u: Compile only the source files named on the command line (or all sources of the main project if none named). No binding or linking.
-U: Compile only the source files named on the command line (or all sources of all projects if none named). No binding or linking.
-r: With -c or -u and no entry points: compile all sources of all projects recursively.
-z: Build without generating an OS-level entry point. Normally GPRbuild produces a main symbol that the operating system calls to start the program, driving Ada elaboration and invoking the main subprogram. With -z, that symbol is omitted so the resulting objects can be linked with a main subprogram written in another language — for example a C main that handles startup and then calls into Ada code.

Build behavior

-f: Force re-execution of all actions, ignoring stored signatures.
-jnum: Maximum number of actions to run in parallel. -j0 uses one job per CPU core. If GPRbuild is invoked from a Makefile and the invoking make provides a jobserver, GPRbuild2 acquires job slots from it rather than running freely: -j then acts as an upper bound on the slots requested, with actual parallelism capped by what the jobserver makes available.
-k: Keep executing independent actions after a failure. Actions that depend on a failed action are skipped.
-p / --create-missing-dirs: Force creation of object, library, and executable directories that lie outside the project directory. Directories relative to the project directory (including relocated ones via --relocate-build-tree) are created automatically without this switch. GPRbuild refuses by default to create directories outside the project tree — whether specified as absolute paths or as relative paths that escape the project directory (e.g. ../other) — and -p overrides that restriction.
-R: Do not pass a run-path option to the linker, even when Run_Path_Option is declared.
-o name: Name the output executable name. Requires exactly one entry point.
-eInn: Index of the main unit in a multi-unit source file.
--no-indirect-imports: After each successful compilation, verify that the source only uses files from directly imported projects. A violation invalidates the compilation artifacts.
--indirect-imports: Allow use of files from directly or indirectly imported projects (default). Cancels a preceding --no-indirect-imports.
--no-object-check: Do not verify that an object file was produced after compilation.
--no-split-units: Require all parts of an Ada compilation unit to come from the same project view.
--no-sal-binding: Reuse binder artifacts from a previous build for Stand-Alone Libraries. Unsafe; may produce incorrect results if sources have changed.
--restricted-to-languages=lang1,lang2: Include only compile actions for the listed languages in the DAG.
--compiler-subst=lang,tool: Use tool instead of the configured compiler for lang.
--temp-dir=[os|obj]: Control where GPRbuild places temporary files: os uses the system temporary directory; obj uses the object directory of the owning project.
--unchecked-shared-lib-imports: Allow shared library projects to import non-shared-library projects.

Output and diagnostics

See Common Command-Line Options for the -q, -v, -F, -we, -ws, and -wn switches.

-d: Display per-action progress lines.
--no-warnings-replay / -n: Do not replay the warnings of actions that were skipped because they were up to date. By default, GPRbuild2 replays such warnings.

Build artifacts

--build-script=file: Write a shell script to file that reproduces the build. This is a best-effort output: the generated script may not be portable and will only work reliably for simple cases. It nonetheless gives a useful overview of the commands GPRbuild executed.
--create-map-file[=file]: Ask the linker to generate a map file. Defaults to the executable name with a .map extension.
--keep-temp-files: Do not delete temporary files created during the build.

Compiler compatibility switches

The following switches are accepted for compatibility with Ada compilers and are forwarded to the Ada compiler:

-g[opt], -O[level], -fno-inline, -fstack-check, -nostdinc, -nostdlib

Build Execution

GPRbuild2 models the build as a directed acyclic graph (DAG) of actions. Each action is an atomic invocation of an external tool (compiler, binder, archiver, linker, etc.) with a defined set of inputs and outputs. Dependency edges encode execution order: for example, a link action depends on all compile actions whose objects it consumes.

After loading the project tree, GPRbuild2 populates the DAG from the project configuration and the set of entry points - executables declared via the Main attribute or on the command line, libraries, and any additional units specified via the Roots attribute. The process manager then traverses the DAG in topological order, running independent actions in parallel up to the -j limit.

Each action’s up-to-dateness is determined by a signature: checksums over all inputs (source files, dependency closures, switches, configuration) and expected outputs. An action is re-executed only when its signature has changed since the last successful run. Signatures are persisted in a build database across invocations.

Action kinds include (non-exhaustive):

Compile - invoke the language compiler on a single source file.
Ada bind - invoke gprbind / gnatbind for an Ada entry point to produce the bind artifacts.
Post-bind - compile the binder-generated Ada source.
Link - invoke the linker to produce an executable or shared library.
Archive - invoke the archive builder (gprlib) to produce a static library.

The -c, -b, and -l switches restrict which action kinds are included in the DAG for a given invocation.

Project package

The Builder package of the main project may provide default switches and global compilation switches that apply to every invocation. See Package Builder Attributes in the Attributes Reference for the full attribute list and descriptions.

The following switches are not accepted in Builder'Switches and must be given on the command line: -o, -r, -u, -U, -z, --build-script, --compiler-subst, --no-sal-binding, --restricted-to-languages, and --temp-dir. The common switches documented in Common Command-Line Options are likewise command-line only.

project My_App is
   package Builder is
      for Switches ("Ada") use ("-j4", "-k");
      for Global_Compilation_Switches ("Ada") use ("-O2");
   end Builder;
end My_App;

Exit Codes

0: Success (warnings may have been issued).
1: General error (invalid option, missing file, etc.).
4: Underlying tool error (compiler, linker, etc.).
5: Project parsing error.
7: Critical internal error.