13.9 Project Attributes

The following attributes apply to a project. All of them are simple attributes.

Object_Dir

Expression must be a path name. The attribute defines the directory in which the object files created by the build are to be placed. If not specified, object files are placed in the project directory.

Exec_Dir

Expression must be a path name. The attribute defines the directory in which the executables created by the build are to be placed. If not specified, executables are placed in the object directory.

Source_Dirs

Expression must be a list of path names. The attribute defines the directories in which the source files for the project are to be found. If not specified, source files are found in the project directory. If a string in the list ends with "/**", then the directory that precedes "/**" and all of its subdirectories (recursively) are included in the list of source directories.

Excluded_Source_Dirs

Expression must be a list of strings. Each entry designates a directory that is not to be included in the list of source directories of the project. This is normally used when there are strings ending with "/**" in the value of attribute Source_Dirs.

Source_Files

Expression must be a list of file names. The attribute defines the individual files, in the project directory, which are to be used as sources for the project. File names are path_names that contain no directory information. If the project has no sources the attribute must be declared explicitly with an empty list.

Excluded_Source_Files (Locally_Removed_Files)

Expression must be a list of strings that are legal file names. Each file name must designate a source that would normally be a source file in the source directories of the project or, if the project file is an extending project file, inherited by the current project file. It cannot designate an immediate source that is not inherited. Each of the source files in the list are not considered to be sources of the project file: they are not inherited. Attribute Locally_Removed_Files is obsolescent, attribute Excluded_Source_Files is preferred.

Source_List_File

Expression must a single path name. The attribute defines a text file that contains a list of source file names to be used as sources for the project

Library_Dir

Expression must be a path name. The attribute defines the directory in which a library is to be built. The directory must exist, must be distinct from the project's object directory, and must be writable.

Library_Name

Expression must be a string that is a legal file name, without extension. The attribute defines a string that is used to generate the name of the library to be built by the project.

Library_Kind

Argument must be a string value that must be one of the following "static", "dynamic" or "relocatable". This string is case-insensitive. If this attribute is not specified, the library is a static library. Otherwise, the library may be dynamic or relocatable. This distinction is operating-system dependent.

Library_Version

Expression must be a string value whose interpretation is platform dependent. On UNIX, it is used only for dynamic/relocatable libraries as the internal name of the library (the "soname"). If the library file name (built from the Library_Name) is different from the Library_Version, then the library file will be a symbolic link to the actual file whose name will be Library_Version.

Library_Interface

Expression must be a string list. Each element of the string list must designate a unit of the project. If this attribute is present in a Library Project File, then the project file is a Stand-alone Library_Project_File.

Library_Auto_Init

Expression must be a single string "true" or "false", case-insensitive. If this attribute is present in a Stand-alone Library Project File, it indicates if initialization is automatic when the dynamic library is loaded.

Library_Options

Expression must be a string list. Indicates additional switches that are to be used when building a shared library.

Library_GCC

Expression must be a single string. Designates an alternative to "gcc" for building shared libraries.

Library_Src_Dir

Expression must be a path name. The attribute defines the directory in which the sources of the interfaces of a Stand-alone Library will be copied. The directory must exist, must be distinct from the project's object directory and source directories of all projects in the project tree, and must be writable.

Library_Src_Dir

Expression must be a path name. The attribute defines the directory in which the ALI files of a Library will be copied. The directory must exist, must be distinct from the project's object directory and source directories of all projects in the project tree, and must be writable.

Library_Symbol_File

Expression must be a single string. Its value is the single file name of a symbol file to be created when building a stand-alone library when the symbol policy is either "compliant", "controlled" or "restricted", on platforms that support symbol control, such as VMS. When symbol policy is "direct", then a file with this name must exist in the object directory.

Library_Reference_Symbol_File

Expression must be a single string. Its value is the path name of a reference symbol file that is read when the symbol policy is either "compliant" or "controlled", on platforms that support symbol control, such as VMS, when building a stand-alone library. The path may be an absolute path or a path relative to the project directory.

Library_Symbol_Policy

Expression must be a single string. Its case-insensitive value can only be "autonomous", "default", "compliant", "controlled", "restricted" or "direct".

This attribute is not taken into account on all platforms. It controls the policy for exported symbols and, on some platforms (like VMS) that have the notions of major and minor IDs built in the library files, it controls the setting of these IDs.

"autonomous" or "default": exported symbols are not controlled.

"compliant": if attribute Library_Reference_Symbol_File is not defined, then it is equivalent to policy "autonomous". If there are exported symbols in the reference symbol file that are not in the object files of the interfaces, the major ID of the library is increased. If there are symbols in the object files of the interfaces that are not in the reference symbol file, these symbols are put at the end of the list in the newly created symbol file and the minor ID is increased.

"controlled": the attribute Library_Reference_Symbol_File must be defined. The library will fail to build if the exported symbols in the object files of the interfaces do not match exactly the symbol in the symbol file.

"restricted": The attribute Library_Symbol_File must be defined. The library will fail to build if there are symbols in the symbol file that are not in the exported symbols of the object files of the interfaces. Additional symbols in the object files are not added to the symbol file.

"direct": The attribute Library_Symbol_File must be defined and must designate an existing file in the object directory. This symbol file is passed directly to the underlying linker without any symbol processing.

Main

Expression must be a list of strings that are legal file names. These file names designate existing compilation units in the source directory that are legal main subprograms.

When a project file is elaborated, as part of the execution of a gnatmake command, one or several executables are built and placed in the Exec_Dir. If the gnatmake command does not include explicit file names, the executables that are built correspond to the files specified by this attribute.

Externally_Built

Expression must be a single string. Its value must be either "true" of "false", case-insensitive. The default is "false". When the value of this attribute is "true", no attempt is made to compile the sources or to build the library, when the project is a library project.

Main_Language

This is a simple attribute. Its value is a string that specifies the language of the main program.

Languages

Expression must be a string list. Each string designates a programming language that is known to GNAT. The strings are case-insensitive.