Common Command-Line Options

GPRbuild, GPRclean, GPRinstall, GPRname, GPRls, and GPRinspect all operate on a GPR project tree and share a common set of command-line options for project loading, configuration, and diagnostics. Tool-specific options are documented in each tool’s own chapter.

GPRconfig is not covered here: it works directly with the compiler knowledge base rather than a project tree and has its own independent option set (see GPRconfig Reference).

Tip

When developing a custom project-aware tool, support most if not all of these options to ensure a consistent user experience across the GPR tool suite.

Project file

Every project-based GPR tool requires a project file. It may be supplied directly with -P or located automatically: the tool uses default.gpr in the current directory, or the sole .gpr file present if there is exactly one. Relative paths are searched against the current directory, then against GPR_PROJECT_PATH_FILE, GPR_PROJECT_PATH, and ADA_PROJECT_PATH (in that order).

GPR_PROJECT_PATH_FILE, when set, names a text file containing one project directory per line. GPR_PROJECT_PATH and ADA_PROJECT_PATH contain colon-separated directory lists.

Project and configuration switches

-P proj

Specify the main project file. The space between -P and the name is optional.

-aP dir

Add dir to the project search path.

-XNAME=value

Set external reference NAME to value for use in project files.

--no-project

Do not use any project file in the current directory; use the default project from <prefix>/share/gpr.

--implicit-with=proj.gpr

Add the given project as an implicit limited with to every project in the tree.

--config=file.cgpr

Use file.cgpr as the configuration project. The file must exist.

--autoconf=file.cgpr

Use file.cgpr as the configuration project, invoking GPRconfig to create it if it does not yet exist.

--target=name

Specify the target for cross-platform builds. Mutually exclusive with --config and --autoconf.

--RTS[:lang]=runtime

Specify the runtime directory for lang (or Ada if lang is omitted).

--db dir

Parse dir as an additional knowledge base directory.

--db-

Do not load the standard knowledge base.

--relocate-build-tree[=dir]

Relocate all object, library, and executable directories under the current working directory (or dir). See Out-of-Tree Builds.

--root-dir=dir

Root directory for --relocate-build-tree relocation. Defaults to the main project directory; override when artifact directories lie outside it. See Out-of-Tree Builds.

--subdirs=dir

Append dir to all object, library, and executable directories, creating them as needed.

--src-subdirs=dir

For each project, prepend obj-dir/dir to the source directories, where obj-dir is the project’s object directory. Useful for temporary source overrides such as instrumentation.

Output and diagnostics

-q

Quiet: display only errors.

-v

Verbose: display full paths and all spawned-process options.

-F

Use full project path names in brief error messages.

-we

Treat project-file warnings as errors.

-ws

Suppress project-file warnings. Does not affect compiler warnings.

-wn

Restore default warning behavior (cancels -we or -ws).

Note

All switches documented in this chapter must be given on the command line. They are not accepted in the Switches attribute of any tool’s project package (Builder'Switches, Clean'Switches, Install'Switches, etc.).