gprbuild

Build a project (assuming only one *.gpr file exists in the current directory)

$ gprbuild

$ gprbuild -P [project_name]

$ gprclean

$ gprinstall --prefix [path/to/installation/dir]

gprbuild [OPTIONS] PROJECT_FILE [PROJECT_FILE...]

-P project_file
    Specifies the main project file(s) to build. This is usually the entry point for the build.

-X name=value
    Sets the value of an external variable name. These variables can be used within project files for conditional compilation or path definitions.

-R
    Recursively processes all projects referenced by the main project(s). This is crucial for building entire project hierarchies.

-p
    Creates all necessary object and executable directories if they don't exist. Ensures the build environment is ready.

-f
    Forces recompilation of all sources, ignoring timestamps. Useful for ensuring a clean build from scratch.

-c
    Only compiles source files; does not perform linking to create executables or libraries. Creates object files only.

-l
    Only links compiled object files; does not recompile source files. Assumes all necessary object files are already present.

-m
    Rebuilds objects or executables only if their source files are newer than the compiled output. This is the default incremental build behavior.

-j N
    Specifies the number of parallel jobs to execute. Speeds up compilation on multi-core systems by utilizing multiple CPU cores.

-q
    Runs in quiet mode, suppressing most informational output. Only errors and warnings are typically displayed.

-v
    Runs in verbose mode, displaying detailed information about the build process, including executed commands and dependencies.

-k
    Continues building other projects or source files even if errors occur in some parts of the build. Useful for finding multiple errors.

--clean
    Cleans the project by removing all generated object files, executables, and intermediate build artifacts.

--target=target_name
    Specifies the target for cross-compilation (e.g., arm-elf). Directs gprbuild to use a specific cross-toolchain.

--build-mode=mode
    Sets the build mode, which can affect compilation options (e.g., development for debug, release for optimized builds).

gprbuild is a sophisticated build system primarily used for projects developed with the Ada programming language, but also supporting C and C++. It is part of the GNAT (GNU Ada Toolset) ecosystem provided by AdaCore. Unlike simpler build tools, gprbuild operates based on project files, typically with a .gpr extension, which define the structure, dependencies, and build properties of a software system.

These project files allow for a highly modular and organized approach to complex software development, enabling easy management of source directories, object directories, executable names, libraries, and external toolchain configurations. gprbuild intelligently detects dependencies between sources and projects, ensuring that only necessary components are recompiled. It excels in managing multi-language projects, allowing seamless integration and compilation of Ada, C, and C++ sources within a single build process. Furthermore, it offers robust support for cross-compilation, making it a versatile tool for embedded systems and other specialized targets.

gprbuild relies heavily on the GNAT project file concept, which can have a learning curve for new users. While it supports C and C++, its primary strength and deepest integration are with Ada. It requires a properly configured GNAT (GCC-based) toolchain to function correctly. Its project file syntax can become complex for very large and intricate software systems.

At the core of gprbuild is the GNAT Project File system. These .gpr files are declarative text files that define the components of a project: its source directories, object directories, executables, libraries, compiler/linker options, and dependencies on other projects. They allow for modularity, reusability, and clear separation of concerns, enabling gprbuild to understand the entire build graph and perform efficient, dependency-aware compilations and links.

gprbuild provides extensive and robust support for cross-compilation. By specifying a target architecture using the --target option or through project file configurations, it can seamlessly integrate with cross-compilation toolchains. This makes it an ideal choice for developing software for embedded systems, microcontrollers, and other platforms where the development environment differs from the target execution environment, streamlining the complex cross-build process.

gprbuild was developed by AdaCore as a successor and more powerful alternative to the traditional gnatmake utility. While gnatmake was primarily designed for building single Ada projects, gprbuild was created to address the growing complexity of multi-language projects and the need for a robust, hierarchical build system based on the GNAT Project File (GPR) standard. It became the recommended build tool for Ada projects, especially those involving C/C++ components or cross-compilation, integrating seamlessly with the GNAT toolchain and significantly enhancing build management capabilities for Ada developers.

gnatmake(1), gcc(1), make(1), cmake(1)