Attributes
Attributes communicate build properties to GPR tools. They are declared with
the for ... use syntax described in Project File Language; this
chapter lists all predefined attributes and their semantics.
Default values
Every attribute has a default value that applies when no declaration is present. The default is indicated in each attribute’s description below.
Interaction with the configuration project
When an attribute is declared in the configuration project but not in the user project, the user project inherits the configuration value.
When a single-value attribute is declared in both, the user project’s declaration takes precedence.
For list attributes marked configuration concatenable, the final value is the concatenation of the configuration project’s value followed by the user project’s value.
Reading attribute values
Attribute values may be referenced in expressions anywhere in a project file. If an attribute has not been set, its value defaults as described in each attribute’s entry. For the reference syntax see Project File Language.
How to read the attribute descriptions
Each attribute entry below indicates:
Type -
single(string) orlist(string list).Read-only - the attribute is set by the build system; user declarations are forbidden.
Indexed by - the kind of index accepted; see Project File Language for the full description of each index kind. Possible values:
language - case-insensitive language identifier
file name - simple file name without directory components
source glob - simple file name or glob pattern; case sensitivity is host-dependent
source glob or language - either a source glob or a language identifier; resolution priority: exact file name, glob, language,
othersunit - Ada unit name, case-insensitive
string - arbitrary string key
external reference - name of an external variable
Others index allowed - the
othersindex is accepted as a catch-all for this attribute.Configuration concatenable - for list attributes, the final value is the configuration value concatenated with the user value.
Inheritance - by default, attributes are inherited from extended projects. Deviations are noted as not inherited from extended or concatenated from extended.
In addition to the attributes listed here, individual tools may define their own attributes in standard or tool-specific packages; refer to each tool’s documentation.
Project Level Attributes
Configuration - Archives
Archive_Builder: list value, not inherited from extended project
Warning
Empty value is not supported yet in non GNATcoll.Project-based tools
Name of the application used to create a static library (archive), followed by its required options. If the value is empty, the object files listed in the archive recipe are copied to the library directory instead.
Archive_Builder_Append_Option: list value, not inherited from extended project
Options passed to the archive builder when appending files to an existing archive.
Archive_Indexer: list value, not inherited from extended project
Name of the archive indexer executable, followed by its required options.
Archive_Prefix: single value, not inherited from extended project
Prefix for archive file names. Defaults to
"lib".
Archive_Suffix: single value, not inherited from extended project
Extension for archive file names. Defaults to
".a".
Library_Partial_Linker: list value, not inherited from extended project
Name of the partial linker executable, followed by its required options. An empty list disables partial linking.
Directories
Create_Missing_Dirs: single value
Applies to the main project only. When set to
"true", automatically creates missing object, library, and executable directories. Accepted values (case-insensitive):"true"or"false".
Exec_Dir: single value, not inherited from extended project
Directory where executables are placed.
Gpr_Registry_Dirs: list value, not inherited from extended project
List of directories containing JSON files with external package and attribute definitions. All JSON files found in the listed directories are loaded at project tree initialization.
Ignore_Source_Sub_Dirs: list value, not inherited from extended project
List of simple names or patterns for subdirectories to exclude from the source directory list, including their own subdirectories.
Inherit_Source_Path: list value, indexed by a language
Indexed by language name. Lists additional languages whose source directories are included in the source search path of the indexed language.
Object_Dir: single value, not inherited from extended project
Directory where the compiler places object files.
Source_Dirs: list value, not inherited from extended project
List of source directories for the project.
Configuration - General
Config_Prj_File: single value
The main configuration project file.
Default_Language: single value, not inherited from extended project
Default language for the project when
Languagesis not declared. The value is a case-insensitive language name.
Disable_Linking: single value, not inherited from extended project
Indicates whether linking is disabled on the platform. Accepted values (case-insensitive):
"true"or"false"(default).
Object_Generated: single value, indexed by a language
Indexed by language name. Indicates whether compiling a source of the language produces an object file. Accepted values (case-insensitive):
"true"(default) or"false".
Objects_Linked: single value, indexed by a language
Indexed by language name. Indicates whether object files produced for the language are linked into executables. Accepted values (case-insensitive):
"true"(default) or"false".
Required_Toolchain_Version: single value, indexed by a language
Indexed by language name. Expected value for
Toolchain_Versionfor the language, typically set in an auto-generated configuration project. Project processing aborts ifRequired_Toolchain_VersionandToolchain_Versiondo not match.
Run_Path_Option: list value, not inherited from extended project
Switches used to specify the run-path option when linking an executable.
Run_Path_Origin: single value, not inherited from extended project
String that may substitute the executable directory path in run-path options.
Runtime: single value, indexed by a language
Indexed by language name. Applies to the main project and any extended projects. Specifies the runtime directory for the language’s compiler. When
--RTSis specified on the command line,'Runtimefor that language reflects the command-line value instead.
Runtime_Dir: single value, indexed by a language
Indexed by language name. Path of the runtime directory for the language.
Runtime_Library_Dir: single value, indexed by a language, not inherited from extended project
Indexed by language name. Path of the directory containing runtime libraries. Obsolete.
Runtime_Source_Dir: single value, indexed by a language
Indexed by language name. Path of the directory containing runtime library sources. Obsolete.
Runtime_Source_Dirs: list value, indexed by a language
Indexed by language name. Paths of the directories containing runtime library sources. Not normally declared directly.
Separate_Run_Path_Options: single value, not inherited from extended project
Indicates whether multiple separate run-path options may be passed to the linker. Accepted values (case-insensitive):
"true"or"false"(default).
Target: single value
Applies to the main project only. Name of the target platform. When
--target=is specified on the command line,'Targetreflects that value instead.
Toolchain_Version: single value, indexed by a language
Indexed by language name. Records the version of the toolchain used for the language.
Toolchain_Name: single value, indexed by a language
Indexed by language name. Applies to the main project and any extended projects. Identifies the toolchain used for the language.
Toolchain_Description: single value, indexed by a language
Obsolescent. No longer used.
Source Files
Excluded_Source_Files: list value, not inherited from extended project
List of simple file names excluded from the project’s sources. Use this to remove sources that are inherited or found in source directories but should not be part of this project.
Excluded_Source_List_File: single value, not inherited from extended project
Name of a text file listing file simple names to exclude from the project’s sources.
Interfaces: set value, case-sensitive
List of file names that form the interface of the project.
Locally_Removed_Files: list value, not inherited from extended project
Obsolescent. Equivalent to
Excluded_Source_Files.
Source_Files: list value, not inherited from extended project
List of source file simple names for the project.
Source_List_File: single value, not inherited from extended project
Name of a text file listing source file simple names, one per line.
Aggregate Projects
External: single value, indexed by an external reference
Indexed by external reference name. Sets the value of the external reference to use when parsing the aggregated projects.
Project_Files: list value, not inherited from extended project
List of project files aggregated by this project.
Project_Path: list value, not inherited from extended project
Additional directories added to the project search path when locating aggregated projects.
General
Externally_Built: single value, not inherited from extended project
Marks the project as externally built. Accepted values (case-insensitive):
"true"or"false"(default).
Languages: set value, case-insensitive
List of languages used in the project’s sources.
Main: list value
List of main sources for the executables.
Name: single value, read-only, not inherited from extended project
The name of the project.
Project_Dir: single value, read-only, not inherited from extended project
Path of the project directory.
Roots: list value, indexed by a source glob or language
Indexed by source file name, language name, or
"*". Lists units from the main project that must be bound and linked, together with their closures, into the indexed executable. Resolution order: exact source file name, then language name, then"*".
Warning_Message: single value
Emits a user-defined warning message during project processing.
Libraries
Leading_Library_Options: list value, configuration concatenable, not inherited from extended project
Options placed at the beginning of the linker command line when building a shared library.
Library_Auto_Init: single value, not inherited from extended project
Controls whether a Stand-Alone Library is automatically initialized at load time. Accepted values (case-insensitive):
"true"or"false". Defaults to the value ofLibrary_Auto_Init_Supported. Cannot be set to"true"whenLibrary_Auto_Init_Supportedis"false".
Library_Dir: single value
Directory where the library is placed. Must be declared in every library project.
Library_Encapsulated_Options: list value, configuration concatenable, not inherited from extended project
Additional link options required when building an encapsulated Stand-Alone Library.
Library_Encapsulated_Supported: single value, not inherited from extended project
Indicates whether encapsulated Stand-Alone Libraries are supported on the platform. Accepted values (case-insensitive):
"true"or"false"(default).
Library_Interface: set value, case-insensitive
List of unit names that form the interface of a Stand-Alone Library.
Library_Kind: single value, not inherited from extended project
Accepted values (case-insensitive):
"static"for archives (default),"static-pic"for archives of position-independent code, or"dynamic"/"relocatable"for shared libraries.
Library_Name: single value
Name of the library. Must be declared or inherited in every library project.
Library_Options: list value, configuration concatenable, not inherited from extended project
Additional switches (“last switches”) passed when linking a shared library or a static standalone library. For a simple static library or when partial linking is disabled, values are restricted to paths to object files (absolute or relative to the object directory).
Library_Reference_Symbol_File: single value, not inherited from extended project
Name of the reference symbol file.
Library_Rpath_Options: list value, indexed by a language, configuration concatenable
Indexed by language name. Compiler options used to determine the run-path entry for a shared library built from sources of the language. The compiler is invoked with these options; its output is a shared library path whose directory is added to the run-path option when linking.
Library_Src_Dir: single value, not inherited from extended project
Directory where copies of the interface sources of a Stand-Alone Library are placed.
Library_Standalone: single value, not inherited from extended project
Accepted values (case-insensitive):
"standard"for non-encapsulated Stand-Alone Libraries,"encapsulated"for encapsulated Stand-Alone Libraries, or"no"for a regular (non-SAL) library project.
Library_Symbol_File: single value, not inherited from extended project
Name of the library symbol file.
Library_Symbol_Policy: single value, not inherited from extended project
Accepted values (case-insensitive):
"restricted"or"unrestricted".
Library_Version: single value, not inherited from extended project
Internal version string of the library file (for shared library versioning).
For more details see the attribute semantics.
Configuration - Shared Libraries
Library_Auto_Init_Supported: single value, not inherited from extended project
Indicates whether automatic initialization of Stand-Alone Libraries is supported on the platform. Accepted values (case-insensitive):
"true"or"false"(default).
Library_Install_Name_Option: single value, not inherited from extended project
Option prefix that, concatenated with the library file path, sets the install name of a shared library at link time.
Library_Major_Minor_Id_Supported: single value, not inherited from extended project
Indicates whether major/minor version identifiers in shared library names are supported on the platform. Accepted values (case-insensitive):
"true"or"false"(default).
Library_Version_Switches: list value, configuration concatenable, not inherited from extended project
Switches used to set the internal (soname) name of a shared library.
Shared_Library_Minimum_Switches: list value, not inherited from extended project
Minimum required switches when linking a shared library.
Shared_Library_Prefix: single value, not inherited from extended project
Prefix for shared library file names. Defaults to
"lib".
Shared_Library_Suffix: single value, not inherited from extended project
Extension for shared library file names. Defaults to
".so".
Symbolic_Link_Supported: single value, not inherited from extended project
Indicates whether symbolic links are supported on the platform. Accepted values (case-insensitive):
"true"or"false"(default).
Configuration - Libraries
Library_Builder: single value, not inherited from extended project
Path of the application used to build libraries (typically
gprlib).
Library_Support: single value, not inherited from extended project
Accepted values (case-insensitive):
"none"(default),"static_only", or"full".
Linker_Lib_Dir_Option: single value, not inherited from extended project
Option used to add a library directory to the linker search path.
Package Binder Attributes
General
Default_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by language name. Switches passed to the binder for the language when no
Switchesentry matches.
Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Switches passed to the binder for the matching executable or language.
Configuration - Binding
Driver: single value, indexed by a language
Indexed by language name. Name of the binder executable for the language.
Objects_Path: single value, indexed by a language
Indexed by language name. Name of the environment variable that holds the object directory search path for the binder.
Prefix: single value, indexed by a language
Indexed by language name. Prefix applied to binder exchange file names for the language, allowing distinct exchange files when binding multiple languages.
Required_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Mandatory switches always passed to the binder for the language.
Package Builder Attributes
Default_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by language name. Builder switches used when building an executable for the language and no
Switchesentry applies.
Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Builder switches applied when building the matching executable.
Executable: single value, indexed by a file name
Indexed by executable source file name. Simple file name of the resulting executable.
Executable_Suffix: single value
Extension appended to executable file names. Defaults to
.exeon Windows, empty on other platforms.
Global_Compilation_Switches: list value, indexed by a language, “others” index allowed, configuration concatenable
Indexed by language name. Compilation switches applied globally when building an executable.
Global_Config_File: single value, indexed by a language
Indexed by language name. File name of a configuration file passed to the compiler for every source of the language in the project tree.
Global_Configuration_Pragmas: single value
File name of a configuration pragmas file passed to the Ada compiler for every Ada source in the project tree.
Package Clean Attributes
Switches: list value, configuration concatenable
Applies to the main project only. Switches passed to the cleaning application.
Artifacts_In_Exec_Dir: list value
List of file name patterns (regular expressions) deleted by
gprcleanin the main project’s executable directory.
Artifacts_In_Object_Dir: list value
List of file name patterns (regular expressions) deleted by
gprcleanin the project’s object directory.
Object_Artifact_Extensions: list value, indexed by a language
Indexed by language name. Extensions of files derived from source file names that
gprcleanremoves from the object directory.
Source_Artifact_Extensions: list value, indexed by a language
Indexed by language name. Extensions of files derived from object file names that
gprcleanremoves from the object directory.
Package Compiler Attributes
General
Default_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by language name. Switches passed to the compiler for the language when no
Switchesentry applies.
Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Switches passed to the compiler for the matching source or language.
Local_Config_File: single value, indexed by a language
Indexed by language name. File name of a configuration file passed to the compiler for every source of the language in this project.
Local_Configuration_Pragmas: single value
File name of a configuration pragmas file passed to the Ada compiler for every Ada source in this project.
Configuration - Compiling
Driver: single value, indexed by a language
Indexed by language name. Name of the compiler executable for the language.
Required_Switches: list value, indexed by a language, configuration concatenable
Equivalent to
Leading_Required_Switches.
Dependency_Kind: single value, indexed by a language
Indexed by language name. Accepted values (case-insensitive):
"none"(default),"makefile","ali_file", or"ali_closure".
Language_Kind: single value, indexed by a language
Indexed by language name. Accepted values (case-insensitive):
"file_based"(default) or"unit_based".
Leading_Required_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Mandatory switches placed at the beginning of the compiler command line for the language.
Multi_Unit_Object_Separator: single value, indexed by a language
Indexed by language name. String inserted in the object file name before the unit index when compiling a unit from a multi-unit source.
Multi_Unit_Switches: list value, indexed by a language
Indexed by language name. Switches used to identify the unit to compile in a multi-unit source. The unit’s index within the source is appended to the last switch in the list.
Object_File_Suffix: single value, indexed by a language
Indexed by language name. Extension of object files produced by the compiler. Defaults to the platform’s standard object file extension.
Object_File_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass the output object file path to the compiler. Defaults to
"-o".
Source_File_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches placed immediately before the source file path when invoking the compiler.
Trailing_Required_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Mandatory switches placed at the end of the compiler command line for the language.
Configuration - Config Files
Config_Body_File_Name: single value, indexed by a language
Indexed by language name. Template for identifying a body-specific configuration entry in a configuration file.
Config_Body_File_Name_Index: single value, indexed by a language
Indexed by language name. Template for identifying a body-specific configuration entry for a unit within a multi-unit source in a configuration file.
Config_Body_File_Name_Pattern: single value, indexed by a language
Indexed by language name. Template matching all body configuration entries for the language in a configuration file.
Config_File_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass a configuration file to the compiler.
Config_File_Unique: single value, indexed by a language
Indexed by language name. When
"true", only one configuration file is passed to the compiler. Accepted values (case-insensitive):"true"or"false"(default).
Config_Spec_File_Name: single value, indexed by a language
Indexed by language name. Template for identifying a spec-specific configuration entry in a configuration file.
Config_Spec_File_Name_Index: single value, indexed by a language
Indexed by language name. Template for identifying a spec-specific configuration entry for a unit within a multi-unit source in a configuration file.
Config_Spec_File_Name_Pattern: single value, indexed by a language
Indexed by language name. Template matching all spec configuration entries for the language in a configuration file.
Configuration - Dependencies
Dependency_Driver: list value, indexed by a language
Indexed by language name. Executable, followed by required switches, used to generate dependency files for sources of the language.
Dependency_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to specify the dependency file to the compiler, when the dependency kind is file-based and
Dependency_Driveris not set.
Configuration - Search Paths
Include_Path: single value, indexed by a language
Indexed by language name. Name of the environment variable that holds all source search directories for the compiler.
Include_Path_File: single value, indexed by a language
Indexed by language name. Name of the environment variable whose value is a text file listing the source search directories for the compiler.
Include_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass a source search directory to the compiler.
Object_Path_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass a text file listing object directories to the compiler. When not declared, no such file is created.
Configuration - Mapping Files
Mapping_Body_Suffix: single value, indexed by a language
Indexed by language name. Suffix used in mapping files to mark a source as a body.
Mapping_File_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass a mapping file to the compiler.
Mapping_Spec_Suffix: single value, indexed by a language
Indexed by language name. Suffix used in mapping files to mark a source as a spec.
Configuration - Response Files
Max_Command_Line_Length: single value
Maximum number of characters in the compiler command line before a response file is used.
Response_File_Format: single value, indexed by a language
Indexed by language name. Format of the response file generated when the compiler command line exceeds
Max_Command_Line_Length. Accepted values (case-insensitive):"none","gnu","object_list","gcc_gnu","gcc_option_list", or"gcc_object_list".
Response_File_Switches: list value, indexed by a language, configuration concatenable
Indexed by language name. Switches used to pass a response file to the compiler.
Package Gnatls Attributes
Switches: list value
Applies to the main project only. Switches passed to
gnatls.
Package Install Attributes
Prefix: single value
Installation destination directory. A relative path is resolved against the global prefix (
--prefixoption value, or the default installation prefix).
Active: single value
Controls whether the project is installed. Setting this to
"false"(case-insensitive) skips installation; all other values enable it.
Artifacts: list value, indexed by a file name
Indexed by installation directory. Lists non-source files to install. Relative directory indexes are resolved against
Prefix. If the same file name appears more than once, the last entry wins. A missing artifact produces a warning.
Exec_Subdir: single value
Subdirectory under
Prefixwhere executables are installed. Default:bin/.
Install_Name: single value
Name used to record the installation. Defaults to the project name without extension.
Install_Project: single value
Controls whether a relocatable project file is generated and installed. Accepted values:
"true"(default) or"false".
Lib_Subdir: single value
Subdirectory under
Prefixwhere library files are installed. Default:lib/.
Mode: single value
Installation mode. Accepted values (case-insensitive):
"dev"(default) - full developer installation including sources, ALI files, and libraries;"usage"- end-user installation including only shared libraries and executables.
Project_Subdir: single value
Subdirectory under
Prefixwhere the generated GPR project file and installation manifests are placed. Default:share/gpr/.
Required_Artifacts: list value, indexed by a file name
Same as
Artifacts, but a missing file raises an error instead of a warning.
Side_Debug: single value
When set to
"true", strips debug symbols from executables and shared libraries and writes them to a side file with a.debugextension. Accepted values (case-insensitive):"false"(default) or"true".
Sources_Subdir: single value
Subdirectory under
Prefixwhere source files are installed. Default:include/.
Package Linker Attributes
General
Default_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Warning
Index “others” is not supported yet in gprbuild or GNATcoll.Projects-based tools
Indexed by language name. Linker switches used when no
Switchesentry applies for an executable of the language.
Required_Switches: list value, configuration concatenable
Mandatory switches always passed to the linker.
Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Switches passed to the linker for the matching executable.
Group_End_Switch: single value
Switch that ends a link group.
Group_Start_Switch: single value
Switch that begins a link group (a set of libraries linked with recursive symbol resolution).
Leading_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Switches placed at the beginning of the linker command line for the matching executable.
Linker_Options: list value, configuration concatenable
Additional linker switches for imported subsystems. Ignored when set in the main project; applied when set in any directly or indirectly imported project. Complements
Linker'Switchesin the main project. Use this to declare per-subsystem external library dependencies instead of repeating them in every top-level project.
Trailing_Switches: list value, indexed by a source glob or language, “others” index allowed, configuration concatenable
Indexed by source file name or language name. Switches placed at the end of the linker command line for the matching executable. These may override
Required_Switches.
Unconditional_Linking: single value, indexed by a language
Indexed by language name. When set, the link phase always explicitly includes all object files produced for the language.
Configuration - Linking
Driver: single value
Name of the linker executable.
Configuration - Response Files
Max_Command_Line_Length: single value
Maximum number of characters in the linker command line before a response file is used.
Response_File_Format: single value
Format of the response file generated when the linker command line exceeds
Max_Command_Line_Length. Accepted values (case-insensitive):"none","gnu","object_list","gcc_gnu","gcc_option_list", or"gcc_object_list".
Response_File_Switches: list value, configuration concatenable
Switches used to pass a response file to the linker.
Package Naming Attributes
Body: single value, indexed by a unit
Indexed by unit name. File name of the unit’s body.
Body_Suffix: single value, indexed by a language
Warning
Also has case-insensitive values in gprbuild and GNATcoll.Project-based tools
Indexed by language name. File name extension for body files of the language.
Casing: single value
Accepted values (case-insensitive):
"lowercase","uppercase", or"mixedcase". Specifies the expected casing of Ada source file names.
Dot_Replacement: single value
String that replaces the dot separator in Ada unit names when forming source file names.
Implementation: single value, indexed by a unit
Equivalent to
Body.
Implementation_Exceptions: list value, indexed by a language
Indexed by language name. List of body files for the language that do not follow the standard naming scheme and may reside outside the declared source directories.
Implementation_Suffix: single value, indexed by a language
Warning
Also has case-insensitive values in gprbuild and GNATcoll.Project-based tools
Equivalent to
Body_Suffix.
Separate_Suffix: single value
File name extension for Ada subunit files.
Spec: single value, indexed by a unit
Indexed by unit name. File name of the unit’s spec.
Spec_Suffix: single value, indexed by a language
Warning
Also has case-insensitive values in gprbuild and GNATcoll.Project-based tools
Indexed by language name. File name extension for spec files of the language.
Specification: single value, indexed by a unit
Equivalent to
Spec.
Specification_Exceptions: list value, indexed by a language
Indexed by language name. List of spec files for the language that do not follow the standard naming scheme and may reside outside the declared source directories.
Specification_Suffix: single value, indexed by a language
Warning
Also has case-insensitive values in gprbuild and GNATcoll.Project-based tools
Equivalent to
Spec_Suffix.