Packages - GNAT Reference Manual

Next: Package Renamings, Previous: Case Construction, Up: Project File Reference

13.13 Packages

A package provides a grouping of variable declarations and attribute declarations to be used when invoking various GNAT tools. The name of the package indicates the tool(s) to which it applies. Syntax:

     package_declaration ::=
       package_spec | package_renaming
     
     package_spec ::=
       package package_identifier is
         {simple_declarative_item}
       end package_identifier ;
     
     package_identifier ::=
       Naming | Builder | Compiler | Binder |
       Linker | Finder  | Cross_Reference |
       gnatls | IDE     | Pretty_Printer

13.13.1 Package Naming

The attributes of a Naming package specifies the naming conventions that apply to the source files in a project. When invoking other GNAT tools, they will use the sources in the source directories that satisfy these naming conventions.

The following attributes apply to a Naming package:

Casing

This is a simple attribute whose value is a string. Legal values of this string are "lowercase", "uppercase" or "mixedcase". These strings are themselves case insensitive.

If Casing is not specified, then the default is "lowercase".

Dot_Replacement

This is a simple attribute whose string value satisfies the following requirements:

It must not be empty
It cannot start or end with an alphanumeric character
It cannot be a single underscore
It cannot start with an underscore followed by an alphanumeric
It cannot contain a dot '.' if longer than one character

If Dot_Replacement is not specified, then the default is "-".

Spec_Suffix

This is an associative array attribute, defined on language names, whose image is a string that must satisfy the following conditions:

It must not be empty
It cannot start with an alphanumeric character
It cannot start with an underscore followed by an alphanumeric character

For Ada, the attribute denotes the suffix used in file names that contain library unit declarations, that is to say units that are package and subprogram declarations. If Spec_Suffix ("Ada") is not specified, then the default is ".ads".

For C and C++, the attribute denotes the suffix used in file names that contain prototypes.

Body_Suffix

This is an associative array attribute defined on language names, whose image is a string that must satisfy the following conditions:

It must not be empty
It cannot start with an alphanumeric character
It cannot start with an underscore followed by an alphanumeric character
It cannot be a suffix of Spec_Suffix

For Ada, the attribute denotes the suffix used in file names that contain library bodies, that is to say units that are package and subprogram bodies. If Body_Suffix ("Ada") is not specified, then the default is ".adb".

For C and C++, the attribute denotes the suffix used in file names that contain source code.

Separate_Suffix

This is a simple attribute whose value satisfies the same conditions as Body_Suffix.

This attribute is specific to Ada. It denotes the suffix used in file names that contain separate bodies. If it is not specified, then it defaults to same value as Body_Suffix ("Ada").

Spec

This is an associative array attribute, specific to Ada, defined over compilation unit names. The image is a string that is the name of the file that contains that library unit. The file name is case sensitive if the conventions of the host operating system require it.

Body

This is an associative array attribute, specific to Ada, defined over compilation unit names. The image is a string that is the name of the file that contains the library unit body for the named unit. The file name is case sensitive if the conventions of the host operating system require it.

Specification_Exceptions

This is an associative array attribute defined on language names, whose value is a list of strings.

This attribute is not significant for Ada.

For C and C++, each string in the list denotes the name of a file that contains prototypes, but whose suffix is not necessarily the Spec_Suffix for the language.

Implementation_Exceptions

This is an associative array attribute defined on language names, whose value is a list of strings.

This attribute is not significant for Ada.

For C and C++, each string in the list denotes the name of a file that contains source code, but whose suffix is not necessarily the Body_Suffix for the language.

The following attributes of package Naming are obsolescent. They are kept as synonyms of other attributes for compatibility with previous versions of the Project Manager.

Specification_Suffix: This is a synonym of Spec_Suffix.
Implementation_Suffix: This is a synonym of Body_Suffix.
Specification: This is a synonym of Spec.
Implementation: This is a synonym of Body.

13.13.2 package Compiler

The attributes of the Compiler package specify the compilation options to be used by the underlying compiler.

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies the compilation options to be used when compiling a component written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies the compilation options to be used when compiling the named file. If a file is not specified in the Switches attribute, it is compiled with the options specified by Default_Switches of its language, if defined.
Local_Configuration_Pragmas.: This is a simple attribute, whose value is a path name that designates a file containing configuration pragmas to be used for all invocations of the compiler for immediate sources of the project.

13.13.3 package Builder

The attributes of package Builder specify the compilation, binding, and linking options to be used when building an executable for a project. The following attributes apply to package Builder:

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when building a main written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when building the named main file. If a main file is not specified in the Switches attribute, it is built with the options specified by Default_Switches of its language, if defined.
Global_Configuration_Pragmas: This is a simple attribute, whose value is a path name that designates a file that contains configuration pragmas to be used in every build of an executable. If both local and global configuration pragmas are specified, a compilation makes use of both sets.
Executable: This is an associative array attribute. Its domain is a set of main source file names. Its range is a simple string that specifies the executable file name to be used when linking the specified main source. If a main source is not specified in the Executable attribute, the executable file name is deducted from the main source file name. This attribute has no effect if its value is the empty string.
Executable_Suffix: This is a simple attribute whose value is the suffix to be added to the executables that don't have an attribute Executable specified.

13.13.4 package Gnatls

The attributes of package Gnatls specify the tool options to be used when invoking the library browser gnatls. The following attributes apply to package Gnatls:

Switches: This is a single attribute with a string list value. Each nonempty string in the list is an option when invoking gnatls.

13.13.5 package Binder

The attributes of package Binder specify the options to be used when invoking the binder in the construction of an executable. The following attributes apply to package Binder:

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when binding a main written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when binding the named main file. If a main file is not specified in the Switches attribute, it is bound with the options specified by Default_Switches of its language, if defined.

13.13.6 package Linker

The attributes of package Linker specify the options to be used when invoking the linker in the construction of an executable. The following attributes apply to package Linker:

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when linking a main written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when linking the named main file. If a main file is not specified in the Switches attribute, it is linked with the options specified by Default_Switches of its language, if defined.
Linker_Options: This is a string list attribute. Its value specifies additional options that be given to the linker when linking an executable. This attribute is not used in the main project, only in projects imported directly or indirectly.

13.13.7 package Cross_Reference

The attributes of package Cross_Reference specify the tool options to be used when invoking the library tool gnatxref. The following attributes apply to package Cross_Reference:

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatxref on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatxref on the named main source. If a source is not specified in the Switches attribute, gnatxref will be called with the options specified by Default_Switches of its language, if defined.

13.13.8 package Finder

The attributes of package Finder specify the tool options to be used when invoking the search tool gnatfind. The following attributes apply to package Finder:

Default_Switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatfind on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatfind on the named main source. If a source is not specified in the Switches attribute, gnatfind will be called with the options specified by Default_Switches of its language, if defined.

13.13.9 package Pretty_Printer

The attributes of package Pretty_Printer specify the tool options to be used when invoking the formatting tool gnatpp. The following attributes apply to package Pretty_Printer:

Default_switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatpp on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatpp on the named main source. If a source is not specified in the Switches attribute, gnatpp will be called with the options specified by Default_Switches of its language, if defined.

13.13.10 package gnatstub

The attributes of package gnatstub specify the tool options to be used when invoking the tool gnatstub. The following attributes apply to package gnatstub:

Default_switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatstub on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatstub on the named main source. If a source is not specified in the Switches attribute, gnatpp will be called with the options specified by Default_Switches of its language, if defined.

13.13.11 package Eliminate

The attributes of package Eliminate specify the tool options to be used when invoking the tool gnatelim. The following attributes apply to package Eliminate:

Default_switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatelim on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatelim on the named main source. If a source is not specified in the Switches attribute, gnatelim will be called with the options specified by Default_Switches of its language, if defined.

13.13.12 package Metrics

The attributes of package Metrics specify the tool options to be used when invoking the tool gnatmetric. The following attributes apply to package Metrics:

Default_switches: This is an associative array attribute. Its domain is a set of language names. Its range is a string list that specifies options to be used when calling gnatmetric on a source written in that language, for which no file-specific switches have been specified.
Switches: This is an associative array attribute. Its domain is a set of file names. Its range is a string list that specifies options to be used when calling gnatmetric on the named main source. If a source is not specified in the Switches attribute, gnatmetric will be called with the options specified by Default_Switches of its language, if defined.

13.13.13 package IDE

The attributes of package IDE specify the options to be used when using an Integrated Development Environment such as GPS.

Remote_Host: This is a simple attribute. Its value is a string that designates the remote host in a cross-compilation environment, to be used for remote compilation and debugging. This field should not be specified when running on the local machine.
Program_Host: This is a simple attribute. Its value is a string that specifies the name of IP address of the embedded target in a cross-compilation environment, on which the program should execute.
Communication_Protocol: This is a simple string attribute. Its value is the name of the protocol to use to communicate with the target in a cross-compilation environment, e.g. "wtx" or "vxworks".
Compiler_Command: This is an associative array attribute, whose domain is a language name. Its value is string that denotes the command to be used to invoke the compiler. The value of Compiler_Command ("Ada") is expected to be compatible with gnatmake, in particular in the handling of switches.
Debugger_Command: This is simple attribute, Its value is a string that specifies the name of the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
Default_Switches: This is an associative array attribute. Its indexes are the name of the external tools that the GNAT Programming System (GPS) is supporting. Its value is a list of switches to use when invoking that tool.
Gnatlist: This is a simple attribute. Its value is a string that specifies the name of the gnatls utility to be used to retrieve information about the predefined path; e.g., "gnatls", "powerpc-wrs-vxworks-gnatls".
VCS_Kind: This is a simple attribute. Its value is a string used to specify the Version Control System (VCS) to be used for this project, e.g. CVS, RCS ClearCase or Perforce.
VCS_File_Check: This is a simple attribute. Its value is a string that specifies the command used by the VCS to check the validity of a file, either when the user explicitly asks for a check, or as a sanity check before doing the check-in.
VCS_Log_Check: This is a simple attribute. Its value is a string that specifies the command used by the VCS to check the validity of a log file.
VCS_Repository_Root: The VCS repository root path. This is used to create tags or branches of the repository. For subversion the value should be the URL as specified to check-out the working copy of the repository.
VCS_Patch_Root: The local root directory to use for building patch file. All patch chunks will be relative to this path. The root project directory is used if this value is not defined.