Compilation Units - Library Units
Author: JTC1/SC22/WG9/ARG, by Randall Brukardt, ARG Editor

Ada Reference Manual — Legal Information

# 10.1.1 Compilation Units - Library Units

1
A library_item is a compilation unit that is the declaration, body, or renaming of a library unit. Each library unit (except Standard) has a parent unit, which is a library package or generic library package. A library unit is a child of its parent unit. The root library units are the children of the predefined library package Standard.

#### Syntax

2
compilation ::= {compilation_unit}
3
compilation_unit ::=
context_clause library_item
| context_clause subunit
4
library_item ::= [private] library_unit_declaration
| library_unit_body
| [private] library_unit_renaming_declaration
5
library_unit_declaration ::=
subprogram_declaration | package_declaration
| generic_declaration | generic_instantiation
6
library_unit_renaming_declaration ::=
package_renaming_declaration
| generic_renaming_declaration
| subprogram_renaming_declaration
7
library_unit_body ::= subprogram_body | package_body
8
parent_unit_name ::= name
8.1/2
An overriding_indicator is not allowed in a subprogram_declaration, generic_instantiation, or subprogram_renaming_declaration that declares a library unit.
9
A library unit is a program unit that is declared by a library_item. When a program unit is a library unit, the prefix “library” is used to refer to it (or “generic library” if generic), as well as to its declaration and body, as in “library procedure”, “library package_body”, or “generic library package”. The term compilation unit is used to refer to a compilation_unit. When the meaning is clear from context, the term is also used to refer to the library_item of a compilation_unit or to the proper_body of a subunit (that is, the compilation_unit without the context_clause and the separate (parent_unit_name)).
10
The parent declaration of a library_item (and of the library unit) is the declaration denoted by the parent_unit_name, if any, of the defining_program_unit_name of the library_item. If there is no parent_unit_name, the parent declaration is the declaration of Standard, the library_item is a root library_item, and the library unit (renaming) is a root library unit (renaming). The declaration and body of Standard itself have no parent declaration. The parent unit of a library_item or library unit is the library unit declared by its parent declaration.
11
The children of a library unit occur immediately within the declarative region of the declaration of the library unit. The ancestors of a library unit are itself, its parent, its parent's parent, and so on. (Standard is an ancestor of every library unit.) The descendant relation is the inverse of the ancestor relation.
12
A library_unit_declaration or a library_unit_renaming_declaration is private if the declaration is immediately preceded by the reserved word private; it is otherwise public. A library unit is private or public according to its declaration. The public descendants of a library unit are the library unit itself, and the public descendants of its public children. Its other descendants are private descendants.
12.1/2
For each library package_declaration in the environment, there is an implicit declaration of a limited view of that library package. The limited view of a package contains:
12.2/2

- For each nested package_declaration, a declaration of the limited view of that package, with the same defining_program_unit_name.

12.3/2

- For each type_declaration in the visible part, an incomplete view of the type; if the type_declaration is tagged, then the view is a tagged incomplete view.

12.4/2
The limited view of a library package_declaration is private if that library package_declaration is immediately preceded by the reserved word private.
12.5/2
There is no syntax for declaring limited views of packages, because they are always implicit. The implicit declaration of a limited view of a library package is not the declaration of a library unit (the library package_declaration is); nonetheless, it is a library_item. The implicit declaration of the limited view of a library package forms an (implicit) compilation unit whose context_clause is empty.
12.6/2
A library package_declaration is the completion of the declaration of its limited view.

#### Legality Rules

13
The parent unit of a library_item shall be a library package or generic library package.
14
If a defining_program_unit_name of a given declaration or body has a parent_unit_name, then the given declaration or body shall be a library_item. The body of a program unit shall be a library_item if and only if the declaration of the program unit is a library_item. In a library_unit_renaming_declaration, the (old) name shall denote a library_item.
15/2
A parent_unit_name (which can be used within a defining_program_unit_name of a library_item and in the separate clause of a subunit), and each of its prefixes, shall not denote a renaming_declaration. On the other hand, a name that denotes a library_unit_renaming_declaration is allowed in a nonlimited_with_clause and other places where the name of a library unit is allowed.
16
If a library package is an instance of a generic package, then every child of the library package shall either be itself an instance or be a renaming of a library unit.
17
A child of a generic library package shall either be itself a generic unit or be a renaming of some other child of the same generic unit. The renaming of a child of a generic package shall occur only within the declarative region of the generic package.
18
A child of a parent generic package shall be instantiated or renamed only within the declarative region of the parent generic.
19/2
For each child C of some parent generic package P, there is a corresponding declaration C nested immediately within each instance of P. For the purposes of this rule, if a child C itself has a child D, each corresponding declaration for C has a corresponding child D. The corresponding declaration for a child within an instance is visible only within the scope of a with_clause that mentions the (original) child generic unit.
20
A library subprogram shall not override a primitive subprogram.
21
The defining name of a function that is a compilation unit shall not be an operator_symbol.

#### Static Semantics

22
A subprogram_renaming_declaration that is a library_unit_renaming_declaration is a renaming-as-declaration, not a renaming-as-body.
23
There are two kinds of dependences among compilation units:
24

- The semantic dependences (see below) are the ones needed to check the compile-time rules across compilation unit boundaries; a compilation unit depends semantically on the other compilation units needed to determine its legality. The visibility rules are based on the semantic dependences.

25

- The elaboration dependences (see 10.2) determine the order of elaboration of library_items.

26/2
A library_item depends semantically upon its parent declaration. A subunit depends semantically upon its parent body. A library_unit_body depends semantically upon the corresponding library_unit_declaration, if any. The declaration of the limited view of a library package depends semantically upon the declaration of the limited view of its parent. The declaration of a library package depends semantically upon the declaration of its limited view. A compilation unit depends semantically upon each library_item mentioned in a with_clause of the compilation unit. In addition, if a given compilation unit contains an attribute_reference of a type defined in another compilation unit, then the given compilation unit depends semantically upon the other compilation unit. The semantic dependence relationship is transitive.

#### Dynamic Semantics

26.1/2
The elaboration of the declaration of the limited view of a package has no effect.
NOTES
27
1 A simple program may consist of a single compilation unit. A compilation need not have any compilation units; for example, its text can consist of pragmas.
28
2 The designator of a library function cannot be an operator_symbol, but a nonlibrary renaming_declaration is allowed to rename a library function as an operator. Within a partition, two library subprograms are required to have distinct names and hence cannot overload each other. However, renaming_declarations are allowed to define overloaded names for such subprograms, and a locally declared subprogram is allowed to overload a library subprogram. The expanded name Standard.L can be used to denote a root library unit L (unless the declaration of Standard is hidden) since root library unit declarations occur immediately within the declarative region of package Standard.

#### Examples

29
Examples of library units:
30
package Rational_Numbers.IO is -- public child of Rational_Numbers, see 7.1
procedure Put(R : in Rational);
procedure Get(R : out Rational);
end Rational_Numbers.IO;
31
private procedure Rational_Numbers.Reduce(R : in out Rational);
-- private child of Rational_Numbers
32
with Rational_Numbers.Reduce; -- refer to a private child
package body Rational_Numbers is
...
end Rational_Numbers;
33
with Rational_Numbers.IO; use Rational_Numbers;
with Ada.Text_io; -- see A.10
procedure Main is -- a root library procedure
R : Rational;
begin
R := 5/3; -- construct a rational number, see 7.1
Ada.Text_IO.Put("The answer is: ");
IO.Put(R);
Ada.Text_IO.New_Line;
end Main;
34
with Rational_Numbers.IO;
package Rational_IO renames Rational_Numbers.IO;
-- a library unit renaming declaration
35
Each of the above library_items can be submitted to the compiler separately.

Sponsored by Ada-Europe