diff options
Diffstat (limited to 'gcc/ada/doc')
| -rw-r--r-- | gcc/ada/doc/Makefile | 2 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat-style.rst | 691 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_advice.rst | 16 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst | 21 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst | 69 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst | 25 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst | 220 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst | 20 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst | 14 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst | 2 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst | 68 | ||||
| -rw-r--r-- | gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst | 3 | ||||
| -rw-r--r-- | gcc/ada/doc/share/conf.py | 42 | ||||
| -rw-r--r-- | gcc/ada/doc/share/gnat.sty | 72 |
14 files changed, 1137 insertions, 128 deletions
diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile index 9a435eb..4adfd36 100644 --- a/gcc/ada/doc/Makefile +++ b/gcc/ada/doc/Makefile @@ -14,7 +14,7 @@ ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \ -c $(SOURCEDIR)/share \ -d $(BUILDDIR)/$*/doctrees \ $(SOURCEDIR) -DOC_LIST=gnat_rm gnat_ugn +DOC_LIST=gnat_rm gnat_ugn gnat-style FMT_LIST=html pdf txt info .PHONY: help clean diff --git a/gcc/ada/doc/gnat-style.rst b/gcc/ada/doc/gnat-style.rst new file mode 100644 index 0000000..527e7ba --- /dev/null +++ b/gcc/ada/doc/gnat-style.rst @@ -0,0 +1,691 @@ +GNAT Coding Style: A Guide for GNAT Developers +============================================== + +General +------- + +Most of GNAT is written in Ada using a consistent style to ensure +readability of the code. This document has been written to help +maintain this consistent style, while having a large group of developers +work on the compiler. + +For the coding style in the C parts of the compiler and run time, +see the GNU Coding Guidelines. + +This document is structured after the Ada Reference Manual. +Those familiar with that document should be able to quickly +lookup style rules for particular constructs. + +Lexical Elements +---------------- + +Character Set and Separators +**************************** + +.. index:: Character set +.. index:: ASCII +.. index:: Separators +.. index:: End-of-line +.. index:: Line length +.. index:: Indentation + +* The character set used should be plain 7-bit ASCII. + The only separators allowed are space and the end-of-line sequence. + No other control character or format effector (such as ``HT``, + ``VT``, ``FF`` ) + should be used. + The normal end-of-line sequence is used, which may be + ``LF``, ``CR/LF`` or ``CR``, + depending on the host system. An optional ``SUB`` + ( ``16#1A#`` ) may be present as the + last character in the file on hosts using that character as file terminator. + +* Files that are checked in or distributed should be in host format. + +* A line should never be longer than 79 characters, not counting the line + separator. + +* Lines must not have trailing blanks. + +* Indentation is 3 characters per level for ``if`` statements, loops, and + ``case`` statements. + For exact information on required spacing between lexical + elements, see file style.adb. + + .. index:: style.adb file + +Identifiers +*********** + +* Identifiers will start with an upper case letter, and each letter following + an underscore will be upper case. + + .. index:: Casing (for identifiers) + + Short acronyms may be all upper case. + All other letters are lower case. + An exception is for identifiers matching a foreign language. In particular, + we use all lower case where appropriate for C. + +* Use underscores to separate words in an identifier. + + .. index:: Underscores + +* Try to limit your use of abbreviations in identifiers. + It is ok to make a few abbreviations, explain what they mean, and then + use them frequently, but don't use lots of obscure abbreviations. An + example is the ``ALI`` word which stands for Ada Library + Information and is by convention always written in upper-case when + used in entity names. + + .. code-block:: ada + + procedure Find_ALI_Files; + +* Don't use the variable name ``I``, use ``J`` instead; ``I`` is too + easily confused with ``1`` in some fonts. Similarly don't use the + variable ``O``, which is too easily mistaken for the number ``0``. + +Numeric Literals +**************** + +* Numeric literals should include underscores where helpful for + readability. + + .. index:: Underscores + + .. code-block:: ada + + 1_000_000 + 16#8000_0000# + 3.14159_26535_89793_23846 + +Reserved Words +************** + +* Reserved words use all lower case. + + .. index:: Casing (for reserved words) + + .. code-block:: ada + + return else + +* The words ``Access``, ``Delta`` and ``Digits`` are + capitalized when used as attribute_designator. + +Comments +******** + +* A comment starts with ``--`` followed by two spaces. + The only exception to this rule (i.e. one space is tolerated) is when the + comment ends with a single space followed by ``--``. + It is also acceptable to have only one space between ``--`` and the start + of the comment when the comment is at the end of a line, + after some Ada code. + +* Every sentence in a comment should start with an upper-case letter (including + the first letter of the comment). + + .. index:: Casing (in comments) + +* When declarations are commented with 'hanging' comments, i.e. + comments after the declaration, there is no blank line before the + comment, and if it is absolutely necessary to have blank lines within + the comments, e.g. to make paragraph separations within a single comment, + these blank lines *do* have a ``--`` (unlike the + normal rule, which is to use entirely blank lines for separating + comment paragraphs). The comment starts at same level of indentation + as code it is commenting. + + .. index:: Blank lines (in comments) + .. index:: Indentation + + .. code-block:: ada + + z : Integer; + -- Integer value for storing value of z + -- + -- The previous line was a blank line. + +* Comments that are dubious or incomplete, or that comment on possibly + wrong or incomplete code, should be preceded or followed by ``???``. + +* Comments in a subprogram body must generally be surrounded by blank lines. + An exception is a comment that follows a line containing a single keyword + ( ``begin``, ``else``, ``loop`` ): + + .. code-block:: ada + + begin + -- Comment for the next statement + + A := 5; + + -- Comment for the B statement + + B := 6; + end; + +* In sequences of statements, comments at the end of the lines should be + aligned. + + .. index:: Alignment (in comments) + + .. code-block:: ada + + My_Identifier := 5; -- First comment + Other_Id := 6; -- Second comment + +* Short comments that fit on a single line are *not* ended with a + period. Comments taking more than a line are punctuated in the normal + manner. + +* Comments should focus on *why* instead of *what*. + Descriptions of what subprograms do go with the specification. + +* Comments describing a subprogram spec should specifically mention the + formal argument names. General rule: write a comment that does not + depend on the names of things. The names are supplementary, not + sufficient, as comments. + +* *Do not* put two spaces after periods in comments. + +Declarations and Types +---------------------- + +* In entity declarations, colons must be surrounded by spaces. Colons + should be aligned. + + .. index:: Alignment (in declarations) + + .. code-block:: ada + + Entity1 : Integer; + My_Entity : Integer; + +* Declarations should be grouped in a logical order. + Related groups of declarations may be preceded by a header comment. + +* All local subprograms in a subprogram or package body should be declared + before the first local subprogram body. + +* Do not declare local entities that hide global entities. + + .. index:: Hiding of outer entities + +* Do not declare multiple variables in one declaration that spans lines. + Start a new declaration on each line, instead. + +* The defining_identifiers of global declarations serve as + comments of a sort. So don't choose terse names, but look for names + that give useful information instead. + +* Local names can be shorter, because they are used only within + one context, where comments explain their purpose. + +* When starting an initialization or default expression on the line that follows + the declaration line, use 2 characters for indentation. + + .. code-block:: ada + + Entity1 : Integer := + Function_Name (Parameters, For_Call); + +* If an initialization or default expression needs to be continued on subsequent + lines, the continuations should be indented from the start of the expression. + + .. code-block:: ada + + Entity1 : Integer := Long_Function_Name + (parameters for call); + +Expressions and Names +--------------------- + +* Every operator must be surrounded by spaces. An exception is that + this rule does not apply to the exponentiation operator, for which + there are no specific layout rules. The reason for this exception + is that sometimes it makes clearer reading to leave out the spaces + around exponentiation. + + .. index:: Operators + + .. code-block:: ada + + E := A * B**2 + 3 * (C - D); + +* Use parentheses where they clarify the intended association of operands + with operators: + + .. index:: Parenthesization of expressions + + .. code-block:: ada + + (A / B) * C + +Statements +---------- + +Simple and Compound Statements +****************************** + +* Use only one statement or label per line. + +* A longer sequence_of_statements may be divided in logical + groups or separated from surrounding code using a blank line. + + +If Statements +************* + +* When the ``if``, ``elsif`` or ``else`` keywords fit on the + same line with the condition and the ``then`` keyword, then the + statement is formatted as follows: + + .. index:: Alignment (in an if statement) + + .. code-block:: ada + + if condition then + ... + elsif condition then + ... + else + ... + end if; + + When the above layout is not possible, ``then`` should be aligned + with ``if``, and conditions should preferably be split before an + ``and`` or ``or`` keyword a follows: + + .. code-block:: ada + + if long_condition_that_has_to_be_split + and then continued_on_the_next_line + then + ... + end if; + + The ``elsif``, ``else`` and ``end if`` always line up with + the ``if`` keyword. The preferred location for splitting the line + is before ``and`` or ``or``. The continuation of a condition is + indented with two spaces or as many as needed to make nesting clear. + As an exception, if conditions are closely related either of the + following is allowed: + + .. code-block:: ada + + if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf + or else + x = asldkjhalkdsjfhhfd + or else + x = asdfadsfadsf + then + ... + end if; + + if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else + x = asldkjhalkdsjfhhfd or else + x = asdfadsfadsf + then + ... + end if; + +* Conditions should use short-circuit forms ( ``and then``, + ``or else`` ), except when the operands are boolean variables + or boolean constants. + + .. index:: Short-circuit forms + +* Complex conditions in ``if`` statements are indented two characters: + + .. index:: Indentation (in if statements) + + .. code-block:: ada + + if this_complex_condition + and then that_other_one + and then one_last_one + then + ... + end if; + + There are some cases where complex conditionals can be laid out + in manners that do not follow these rules to preserve better + parallelism between branches, e.g. + + .. code-block:: ada + + if xyz.abc (gef) = 'c' + or else + xyz.abc (gef) = 'x' + then + ... + end if; + +* Every ``if`` block is preceded and followed by a blank line, except + where it begins or ends a sequence_of_statements. + + .. index:: Blank lines (in an if statement) + + .. code-block:: ada + + A := 5; + + if A = 5 then + null; + end if; + + A := 6; + +Case Statements +*************** + +* Layout is as below. For long ``case`` statements, the extra indentation + can be saved by aligning the ``when`` clauses with the opening ``case``. + + .. code-block:: ada + + case expression is + when condition => + ... + when condition => + ... + end case; + +Loop Statements +*************** + +* When possible, have ``for`` or ``while`` on one line with the + condition and the ``loop`` keyword. + + .. code-block:: ada + + for J in S'Range loop + ... + end loop; + + If the condition is too long, split the condition (see 'If + statements' above) and align ``loop`` with the ``for`` or + ``while`` keyword. + + .. index:: Alignment (in a loop statement) + + .. code-block:: ada + + while long_condition_that_has_to_be_split + and then continued_on_the_next_line + loop + ... + end loop; + + If the loop_statement has an identifier, it is laid out as follows: + + .. code-block:: ada + + Outer : while not condition loop + ... + end Outer; + +Block Statements +**************** + +* The ``declare`` (optional), ``begin`` and ``end`` words + are aligned, except when the block_statement is named. There + is a blank line before the ``begin`` keyword: + + .. index:: Alignment (in a block statement) + + .. code-block:: ada + + Some_Block : declare + ... + + begin + ... + end Some_Block; + +Subprograms +----------- + +Subprogram Declarations +*********************** + +* Do not write the ``in`` for parameters. + + .. code-block:: ada + + function Length (S : String) return Integer; + +* When the declaration line for a procedure or a function is too long to fit + the entire declaration (including the keyword procedure or function) on a + single line, then fold it, putting a single parameter on a line, aligning + the colons, as in: + + .. code-block:: ada + + procedure Set_Heading + (Source : String; + Count : Natural; + Pad : Character := Space; + Fill : Boolean := True); + + In the case of a function, if the entire spec does not fit on one line, then + the return may appear after the last parameter, as in: + + .. code-block:: ada + + function Head + (Source : String; + Count : Natural; + Pad : Character := Space) return String; + + Or it may appear on its own as a separate line. This form is preferred when + putting the return on the same line as the last parameter would result in + an overlong line. The return type may optionally be aligned with the types + of the parameters (usually we do this aligning if it results only in a small + number of extra spaces, and otherwise we don't attempt to align). So two + alternative forms for the above spec are: + + .. code-block:: ada + + function Head + (Source : String; + Count : Natural; + Pad : Character := Space) + return String; + + function Head + (Source : String; + Count : Natural; + Pad : Character := Space) + return String; + +Subprogram Bodies +***************** + +* Function and procedure bodies should usually be sorted alphabetically. Do + not attempt to sort them in some logical order by functionality. For a + sequence of subprogram specs, a general alphabetical sorting is also + usually appropriate, but occasionally it makes sense to group by major + function, with appropriate headers. + +* All subprograms have a header giving the function name, with the following + format: + + .. code-block:: ada + + ----------------- + -- My_Function -- + ----------------- + + procedure My_Function is + begin + ... + end My_Function; + + Note that the name in the header is preceded by a single space, + not two spaces as for other comments. These headers are used on + nested subprograms as well as outer level subprograms. They may + also be used as headers for sections of comments, or collections + of declarations that are related. + +* Every subprogram body must have a preceding subprogram_declaration, + which includes proper client documentation so that you do not need to + read the subprogram body in order to understand what the subprogram does and + how to call it. All subprograms should be documented, without exceptions. + + .. index:: Blank lines (in subprogram bodies) + +* A sequence of declarations may optionally be separated from the following + begin by a blank line. Just as we optionally allow blank lines in general + between declarations, this blank line should be present only if it improves + readability. Generally we avoid this blank line if the declarative part is + small (one or two lines) and the body has no blank lines, and we include it + if the declarative part is long or if the body has blank lines. + +* If the declarations in a subprogram contain at least one nested + subprogram body, then just before the ``begin`` of the enclosing + subprogram, there is a comment line and a blank line: + + .. code-block:: ada + + -- Start of processing for Enclosing_Subprogram + + begin + ... + end Enclosing_Subprogram; + +* When nested subprograms are present, variables that are referenced by any + nested subprogram should precede the nested subprogram specs. For variables + that are not referenced by nested procedures, the declarations can either also + be before any of the nested subprogram specs (this is the old style, more + generally used). Or then can come just before the begin, with a header. The + following example shows the two possible styles: + + .. code-block:: ada + + procedure Style1 is + Var_Referenced_In_Nested : Integer; + Var_Referenced_Only_In_Style1 : Integer; + + proc Nested; + -- Comments ... + + ------------ + -- Nested -- + ------------ + + procedure Nested is + begin + ... + end Nested; + + -- Start of processing for Style1 + + begin + ... + end Style1; + + procedure Style2 is + Var_Referenced_In_Nested : Integer; + + proc Nested; + -- Comments ... + + ------------ + -- Nested -- + ------------ + + procedure Nested is + begin + ... + end Nested; + + -- Local variables + + Var_Referenced_Only_In_Style2 : Integer; + + -- Start of processing for Style2 + + begin + ... + end Style2; + + For new code, we generally prefer Style2, but we do not insist on + modifying all legacy occurrences of Style1, which is still much + more common in the sources. + +Packages and Visibility Rules +----------------------------- + +* All program units and subprograms have their name at the end: + + .. code-block:: ada + + package P is + ... + end P; + +* We will use the style of ``use`` -ing ``with`` -ed packages, with + the context clauses looking like: + + .. index:: use clauses + + .. code-block:: ada + + with A; use A; + with B; use B; + +* Names declared in the visible part of packages should be + unique, to prevent name clashes when the packages are ``use`` d. + + .. index:: Name clash avoidance + + .. code-block:: ada + + package Entity is + type Entity_Kind is ...; + ... + end Entity; + +* After the file header comment, the context clause and unit specification + should be the first thing in a program_unit. + +* Preelaborate, Pure and Elaborate_Body pragmas should be added right after the + package name, indented an extra level and using the parameterless form: + + .. code-block:: ada + + package Preelaborate_Package is + pragma Preelaborate; + ... + end Preelaborate_Package; + +Program Structure and Compilation Issues +---------------------------------------- + +* Every GNAT source file must be compiled with the ``-gnatg`` + switch to check the coding style. + (Note that you should look at + style.adb to see the lexical rules enforced by ``-gnatg`` ). + + .. index:: -gnatg option (to gcc) + .. index:: style.adb file + +* Each source file should contain only one compilation unit. + +* Filenames should be 8 or fewer characters, followed by the ``.adb`` + extension for a body or ``.ads`` for a spec. + + .. index:: File name length + +* Unit names should be distinct when 'krunch'ed to 8 characters + (see krunch.ads) and the filenames should match the unit name, + except that they are all lower case. + + .. index:: krunch.ads file + +.. toctree:: + share/gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/implementation_advice.rst b/gcc/ada/doc/gnat_rm/implementation_advice.rst index e86ad0a..e7649b0 100644 --- a/gcc/ada/doc/gnat_rm/implementation_advice.rst +++ b/gcc/ada/doc/gnat_rm/implementation_advice.rst @@ -799,6 +799,22 @@ flushed before the ``Get_Immediate`` call. A special unit ``Interfaces.Vxworks.IO`` is provided that contains routines to enable this functionality. +.. index:: Containers + +RM A.18: ``Containers`` +================================ + +All implementation advice pertaining to Ada.Containers and its +child units (that is, all implementation advice occurring within +section A.18 and its subsections) is followed except for A.18.24(17): + + "Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. " + +The implementations of the two Reference_Preserving_Key functions of +the generic package Ada.Containers.Bounded_Ordered_Sets each currently make +use of dynamic allocation; other operations on bounded ordered set objects +follow the implementation advice. + .. index:: Export RM B.1(39-41): Pragma ``Export`` diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst b/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst index 6f39de6..b09a4bb 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst @@ -397,6 +397,19 @@ This aspect is equivalent to :ref:`pragma No_Tagged_Streams<Pragma-No_Tagged_Str argument specifying a root tagged type (thus this aspect can only be applied to such a type). +Aspect No_Task_Parts +======================== +.. index:: No_Task_Parts + +Applies to a type. If True, requires that the type and any descendants +do not have any task parts. The rules for this aspect are the same as +for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), +replacing "controlled" with "task". + +If No_Task_Parts is True for a type T, then the compiler can optimize +away certain tasking-related code that would otherwise be needed +for T'Class, because descendants of T might contain tasks. + Aspect Object_Size ================== .. index:: Object_Size @@ -548,12 +561,6 @@ Aspect Universal_Aliasing This boolean aspect is equivalent to :ref:`pragma Universal_Aliasing<Pragma-Universal_Aliasing>`. -Aspect Universal_Data -===================== -.. index:: Universal_Data - -This aspect is equivalent to :ref:`pragma Universal_Data<Pragma-Universal_Data>`. - Aspect Unmodified ================= .. index:: Unmodified @@ -566,7 +573,7 @@ Aspect Unreferenced This boolean aspect is equivalent to :ref:`pragma Unreferenced<Pragma-Unreferenced>`. -When using the ``-gnat2020`` switch, this aspect is also supported on formal +When using the ``-gnat2022`` switch, this aspect is also supported on formal parameters, which is in particular the only form possible for expression functions. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst index f8d41ea..665170c 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst @@ -196,7 +196,7 @@ Attribute Default_Bit_Order .. index:: Default_Bit_Order ``Standard'Default_Bit_Order`` (``Standard`` is the only -permissible prefix), provides the value ``System.Default_Bit_Order`` +allowed prefix), provides the value ``System.Default_Bit_Order`` as a ``Pos`` value (0 for ``High_Order_First``, 1 for ``Low_Order_First``). This is used to construct the definition of ``Default_Bit_Order`` in package ``System``. @@ -210,7 +210,7 @@ Attribute Default_Scalar_Storage_Order .. index:: Default_Scalar_Storage_Order ``Standard'Default_Scalar_Storage_Order`` (``Standard`` is the only -permissible prefix), provides the current value of the default scalar storage +allowed prefix), provides the current value of the default scalar storage order (as specified using pragma ``Default_Scalar_Storage_Order``, or equal to ``Default_Bit_Order`` if unspecified) as a ``System.Bit_Order`` value. This is a static attribute. @@ -665,7 +665,7 @@ Attribute Maximum_Alignment .. index:: Maximum_Alignment ``Standard'Maximum_Alignment`` (``Standard`` is the only -permissible prefix) provides the maximum useful alignment value for the +allowed prefix) provides the maximum useful alignment value for the target. This is a static value that can be used to specify the alignment for an object, guaranteeing that it is properly aligned in all cases. @@ -674,7 +674,7 @@ Attribute Max_Integer_Size ========================== .. index:: Max_Integer_Size -``Standard'Max_Integer_Size`` (``Standard`` is the only permissible +``Standard'Max_Integer_Size`` (``Standard`` is the only allowed prefix) provides the size of the largest supported integer type for the target. The result is a static constant. @@ -1057,6 +1057,46 @@ If a component of ``T`` is itself of a record or array type, the specfied attribute definition clause must be provided for the component type as well if desired. +Representation changes that explicitly or implicitly toggle the scalar storage +order are not supported and may result in erroneous execution of the program, +except when performed by means of an instance of ``Ada.Unchecked_Conversion``. + +In particular, overlays are not supported and a warning is given for them: + +.. code-block:: ada + + type Rec_LE is record + I : Integer; + end record; + + for Rec_LE use record + I at 0 range 0 .. 31; + end record; + + for Rec_LE'Bit_Order use System.Low_Order_First; + for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; + + type Rec_BE is record + I : Integer; + end record; + + for Rec_BE use record + I at 0 range 0 .. 31; + end record; + + for Rec_BE'Bit_Order use System.High_Order_First; + for Rec_BE'Scalar_Storage_Order use System.High_Order_First; + + R_LE : Rec_LE; + + R_BE : Rec_BE; + for R_BE'Address use R_LE'Address; + +``warning: overlay changes scalar storage order [enabled by default]`` + +In most cases, such representation changes ought to be replaced by an +instantiation of a function or procedure provided by ``GNAT.Byte_Swapping``. + Note that the scalar storage order only affects the in-memory data representation. It has no effect on the representation used by stream attributes. @@ -1164,7 +1204,7 @@ Attribute Storage_Unit ====================== .. index:: Storage_Unit -``Standard'Storage_Unit`` (``Standard`` is the only permissible +``Standard'Storage_Unit`` (``Standard`` is the only allowed prefix) provides the same value as ``System.Storage_Unit``. Attribute Stub_Type @@ -1195,7 +1235,7 @@ Attribute System_Allocator_Alignment .. index:: System_Allocator_Alignment ``Standard'System_Allocator_Alignment`` (``Standard`` is the only -permissible prefix) provides the observable guaranted to be honored by +allowed prefix) provides the observable guaranted to be honored by the system allocator (malloc). This is a static value that can be used in user storage pools based on malloc either to reject allocation with alignment too large or to enable a realignment circuitry if the @@ -1205,7 +1245,7 @@ Attribute Target_Name ===================== .. index:: Target_Name -``Standard'Target_Name`` (``Standard`` is the only permissible +``Standard'Target_Name`` (``Standard`` is the only allowed prefix) provides a static string value that identifies the target for the current compilation. For GCC implementations, this is the standard gcc target name without the terminating slash (for @@ -1216,7 +1256,7 @@ Attribute To_Address .. index:: To_Address The ``System'To_Address`` -(``System`` is the only permissible prefix) +(``System`` is the only allowed prefix) denotes a function identical to ``System.Storage_Elements.To_Address`` except that it is a static attribute. This means that if its argument is @@ -1587,6 +1627,15 @@ Multi-dimensional arrays can be modified, as shown by this example: which changes element (1,2) to 20 and (3,4) to 30. +Attribute Valid_Image +======================= +.. index:: Valid_Image + +The ``'Valid_Image`` attribute is defined for enumeration types other than +those in package Standard. This attribute is a function that takes +a String, and returns Boolean. ``T'Valid_Image (S)`` returns True +if and only if ``T'Value (S)`` would not raise Constraint_Error. + Attribute Valid_Scalars ======================= .. index:: Valid_Scalars @@ -1650,7 +1699,7 @@ Attribute Wchar_T_Size ====================== .. index:: Wchar_T_Size -``Standard'Wchar_T_Size`` (``Standard`` is the only permissible +``Standard'Wchar_T_Size`` (``Standard`` is the only allowed prefix) provides the size in bits of the C ``wchar_t`` type primarily for constructing the definition of this type in package ``Interfaces.C``. The result is a static constant. @@ -1659,6 +1708,6 @@ Attribute Word_Size =================== .. index:: Word_Size -``Standard'Word_Size`` (``Standard`` is the only permissible +``Standard'Word_Size`` (``Standard`` is the only allowed prefix) provides the value ``System.Word_Size``. The result is a static constant. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst b/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst index 10fcfc9..8d0be38 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst @@ -129,20 +129,29 @@ There are no nonstandard real types. "What combinations of requested decimal precision and range are supported for floating point types. See 3.5.7(7)." -The precision and range is as defined by the IEEE standard. +The precision and range are defined by the IEEE Standard for Floating-Point +Arithmetic (IEEE 754-2019). * "The predefined floating point types declared in ``Standard``. See 3.5.7(16)." -====================== ==================================================== +====================== =============================================== Type Representation -====================== ==================================================== -*Short_Float* 32 bit IEEE short -*Float* (Short) 32 bit IEEE short -*Long_Float* 64 bit IEEE long -*Long_Long_Float* 64 bit IEEE long (80 bit IEEE long on x86 processors) -====================== ==================================================== +====================== =============================================== +*Short_Float* IEEE Binary32 (Single) +*Float* IEEE Binary32 (Single) +*Long_Float* IEEE Binary64 (Double) +*Long_Long_Float* IEEE Binary64 (Double) on non-x86 architectures + IEEE 80-bit Extended on x86 architecture +====================== =============================================== + +The default rounding mode specified by the IEEE 754 Standard is assumed for +static computations, i.e. round to nearest, ties to even. The input routines +yield correctly rounded values for Short_Float, Float and Long_Float at least. +The output routines can compute up to twice as many exact digits as the value +of ``T'Digits`` for any type, for example 30 digits for Long_Float; if more +digits are requested, zeros are printed. * "The small of an ordinary fixed point type. See 3.5.9(8)." diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst index 74b9718..6c81ca7 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -2062,27 +2062,6 @@ string or a static string expressions that evaluates to the null string. In this case, no external name is generated. This form still allows the specification of parameter mechanisms. -Pragma Export_Value -=================== - -Syntax: - - -:: - - pragma Export_Value ( - [Value =>] static_integer_EXPRESSION, - [Link_Name =>] static_string_EXPRESSION); - - -This pragma serves to export a static integer value for external use. -The first argument specifies the value to be exported. The Link_Name -argument specifies the symbolic name to be associated with the integer -value. This pragma is useful for defining a named static value in Ada -that can be referenced in assembly language units to be linked with -the application. This pragma is currently supported only for the -AAMP target and is ignored for other targets. - Pragma Export_Valued_Procedure ============================== @@ -2210,7 +2189,7 @@ extension mode (the use of Off as a parameter cancels the effect of the *-gnatX* command switch). In extension mode, the latest version of the Ada language is -implemented (currently Ada 202x), and in addition a small number +implemented (currently Ada 2022), and in addition a number of GNAT specific extensions are recognized as follows: * Constrained attribute for generic objects @@ -2235,6 +2214,169 @@ of GNAT specific extensions are recognized as follows: This new aggregate syntax for arrays and containers is provided under -gnatX to experiment and confirm this new language syntax. +* Additional ``when`` constructs + + In addition to the ``exit when CONDITION`` control structure, several + additional constructs are allowed following this format. Including + ``return when CONDITION``, ``goto when CONDITION``, and + ``raise [with EXCEPTION_MESSAGE] when CONDITION.`` + + Some examples: + + .. code-block:: ada + + return Result when Variable > 10; + + raise Program_Error with "Element is null" when Element = null; + + goto End_Of_Subprogram when Variable = -1; + +* Casing on composite values (aka pattern matching) + + The selector for a case statement may be of a composite type, subject to + some restrictions (described below). Aggregate syntax is used for choices + of such a case statement; however, in cases where a "normal" aggregate would + require a discrete value, a discrete subtype may be used instead; box + notation can also be used to match all values. + + Consider this example: + + .. code-block:: ada + + type Rec is record + F1, F2 : Integer; + end record; + + procedure Caser_1 (X : Rec) is + begin + case X is + when (F1 => Positive, F2 => Positive) => + Do_This; + when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => + Do_That; + when others => + Do_The_Other_Thing; + end case; + end Caser_1; + + If Caser_1 is called and both components of X are positive, then + Do_This will be called; otherwise, if either component is nonnegative + then Do_That will be called; otherwise, Do_The_Other_Thing will be called. + + If the set of values that match the choice(s) of an earlier alternative + overlaps the corresponding set of a later alternative, then the first + set shall be a proper subset of the second (and the later alternative + will not be executed if the earlier alternative "matches"). All possible + values of the composite type shall be covered. The composite type of the + selector shall be a nonlimited untagged (but possibly discriminated) + record type, all of whose subcomponent subtypes are either static discrete + subtypes or record types that meet the same restrictions. Support for arrays + is planned, but not yet implemented. + + In addition, pattern bindings are supported. This is a mechanism + for binding a name to a component of a matching value for use within + an alternative of a case statement. For a component association + that occurs within a case choice, the expression may be followed by + "is <identifier>". In the special case of a "box" component association, + the identifier may instead be provided within the box. Either of these + indicates that the given identifer denotes (a constant view of) the matching + subcomponent of the case selector. + + Consider this example (which uses type Rec from the previous example): + + .. code-block:: ada + + procedure Caser_2 (X : Rec) is + begin + case X is + when (F1 => Positive is Abc, F2 => Positive) => + Do_This (Abc) + when (F1 => Natural is N1, F2 => <N2>) | + (F1 => <N2>, F2 => Natural is N1) => + Do_That (Param_1 => N1, Param_2 => N2); + when others => + Do_The_Other_Thing; + end case; + end Caser_2; + + This example is the same as the previous one with respect to + determining whether Do_This, Do_That, or Do_The_Other_Thing will + be called. But for this version, Do_This takes a parameter and Do_That + takes two parameters. If Do_This is called, the actual parameter in the + call will be X.F1. + + If Do_That is called, the situation is more complex because there are two + choices for that alternative. If Do_That is called because the first choice + matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero + or negative), then the actual parameters of the call will be (in order) + X.F1 and X.F2. If Do_That is called because the second choice matched (and + the first one did not), then the actual parameters will be reversed. + + Within the choice list for single alternative, each choice must + define the same set of bindings and the component subtypes for + for a given identifer must all statically match. Currently, the case + of a binding for a nondiscrete component is not implemented. + +* Fixed lower bounds for array types and subtypes + + Unconstrained array types and subtypes can be specified with a lower bound + that is fixed to a certain value, by writing an index range that uses the + syntax "<lower-bound-expression> .. <>". This guarantees that all objects + of the type or subtype will have the specified lower bound. + + For example, a matrix type with fixed lower bounds of zero for each + dimension can be declared by the following: + + .. code-block:: ada + + type Matrix is + array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; + + Objects of type Matrix declared with an index constraint must have index + ranges starting at zero: + + .. code-block:: ada + + M1 : Matrix (0 .. 9, 0 .. 19); + M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE + + Similarly, a subtype of String can be declared that specifies the lower + bound of objects of that subtype to be 1: + + .. code-block:: ada + + subtype String_1 is String (1 .. <>); + + If a string slice is passed to a formal of subtype String_1 in a call to + a subprogram S, the slice's bounds will "slide" so that the lower bound + is 1. Within S, the lower bound of the formal is known to be 1, so, unlike + a normal unconstrained String formal, there is no need to worry about + accounting for other possible lower-bound values. Sliding of bounds also + occurs in other contexts, such as for object declarations with an + unconstrained subtype with fixed lower bound, as well as in subtype + conversions. + + Use of this feature increases safety by simplifying code, and can also + improve the efficiency of indexing operations, since the compiler statically + knows the lower bound of unconstrained array formals when the formal's + subtype has index ranges with static fixed lower bounds. + +* Prefixed-view notation for calls to primitive subprograms of untagged types + + Since Ada 2005, calls to primitive subprograms of a tagged type that + have a "prefixed view" (see RM 4.1.3(9.2)) have been allowed to be + written using the form of a selected_component, with the first actual + parameter given as the prefix and the name of the subprogram as a + selector. This prefixed-view notation for calls is extended so as to + also allow such syntax for calls to primitive subprograms of untagged + types. The primitives of an untagged type T that have a prefixed view + are those where the first formal parameter of the subprogram either + is of type T or is an anonymous access parameter whose designated type + is T. For a type that has a component that happens to have the same + simple name as one of the type's primitive subprograms, where the + component is visible at the point of a selected_component using that + name, preference is given to the component in a selected_component + (as is currently the case for tagged types with such component names). .. _Pragma-Extensions_Visible: @@ -3114,13 +3256,7 @@ Syntax: This program unit pragma is supported for parameterless protected procedures -as described in Annex C of the Ada Reference Manual. On the AAMP target -the pragma can also be specified for nonprotected parameterless procedures -that are declared at the library level (which includes procedures -declared at the top level of a library package). In the case of AAMP, -when this pragma is applied to a nonprotected procedure, the instruction -``IERET`` is generated for returns from the procedure, enabling -maskable interrupts, in place of the normal return instruction. +as described in Annex C of the Ada Reference Manual. Pragma Interrupt_State ====================== @@ -6914,32 +7050,6 @@ For a detailed description of the strict aliasing optimization, and the situations in which it must be suppressed, see the section on ``Optimization and Strict Aliasing`` in the :title:`GNAT User's Guide`. -.. _Pragma-Universal_Data: - -Pragma Universal_Data -===================== - -Syntax: - - -:: - - pragma Universal_Data [(library_unit_Name)]; - - -This pragma is supported only for the AAMP target and is ignored for -other targets. The pragma specifies that all library-level objects -(Counter 0 data) associated with the library unit are to be accessed -and updated using universal addressing (24-bit addresses for AAMP5) -rather than the default of 16-bit Data Environment (DENV) addressing. -Use of this pragma will generally result in less efficient code for -references to global data associated with the library unit, but -allows such data to be located anywhere in memory. This pragma is -a library unit pragma, but can also be used as a configuration pragma -(including use in the :file:`gnat.adc` file). The functionality -of this pragma is also available by applying the -univ switch on the -compilations of units where universal addressing of the data is desired. - .. _Pragma-Unmodified: Pragma Unmodified diff --git a/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst b/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst index e818ab5..9f419a7 100644 --- a/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst +++ b/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst @@ -672,6 +672,26 @@ aliasing all views of the object (which may be manipulated by different tasks, say) must be consistent, so it is imperative that the object, once created, remain invariant. +.. _Image_Values_For_Nonscalar_Types: + +Image Values For Nonscalar Types +================================ + +Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes +for nonscalar types; earlier Ada versions defined these attributes only +for scalar types. Ada RM 4.10 provides some general guidance regarding +the default implementation of these attributes and the GNAT compiler +follows that guidance. However, beyond that the precise details of the +image text generated in these cases are deliberately not documented and are +subject to change. In particular, users should not rely on formatting details +(such as spaces or line breaking), record field order, image values for access +types, image values for types that have ancestor or subcomponent types +declared in non-Ada2022 code, image values for predefined types, or the +compiler's choices regarding the implementation permissions described in +Ada RM 4.10. This list is not intended to be exhaustive. If more precise +control of image text is required for some type T, then T'Put_Image should be +explicitly specified. + .. _Strict_Conformance_to_the_Ada_Reference_Manual: Strict Conformance to the Ada Reference Manual diff --git a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst index e448816..355b139 100644 --- a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst +++ b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst @@ -203,7 +203,8 @@ type (signed or modular), as in this example: function Shift_Left (Value : T; - Amount : Natural) return T; + Amount : Natural) return T + with Import, Convention => Intrinsic; The function name must be one of @@ -215,11 +216,12 @@ The result type must be the same as the type of ``Value``. The shift amount must be Natural. The formal parameter names can be anything. -A more convenient way of providing these shift operators is to use -the Provide_Shift_Operators pragma, which provides the function declarations -and corresponding pragma Import's for all five shift functions. Note that in -using these provided shift operations, shifts performed on negative numbers -will result in modification of the sign bit. +A more convenient way of providing these shift operators is to use the +Provide_Shift_Operators pragma, which provides the function declarations and +corresponding pragma Import's for all five shift functions. For signed types +the semantics of these operators is to interpret the bitwise result of the +corresponding operator for modular type. In particular, shifting a negative +number may change its sign bit to positive. .. _Source_Location: diff --git a/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst index c13a882..f755fc1 100644 --- a/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst @@ -1738,7 +1738,7 @@ of the use of this pragma. This may cause an overlay to have this unintended clobbering effect. The compiler avoids this for scalar types, but not for composite objects (where in general the effect of ``Initialize_Scalars`` is part of the initialization routine -for the composite object: +for the composite object): :: diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst index 82e992a..07c38df 100644 --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -1233,6 +1233,13 @@ Alphabetical List of All Switches marker is specified, the callgraph is decorated with information about dynamically allocated objects. +.. index:: -fdiagnostics-format (gcc) + +:switch:`-fdiagnostics-format=json` + Makes GNAT emit warning and error messages as JSON. Inhibits printing of + text warning and errors messages except if :switch:`-gnatv` or + :switch:`-gnatl` are present. + .. index:: -fdump-scos (gcc) @@ -1380,6 +1387,12 @@ Alphabetical List of All Switches Allow full Ada 2012 features (same as :switch:`-gnat12`) +.. index:: -gnat2022 (gcc) + +:switch:`-gnat2022` + Allow full Ada 2022 features + + :switch:`-gnat83` Enforce Ada 83 restrictions. @@ -1463,9 +1476,9 @@ Alphabetical List of All Switches :switch:`-gnatd` Specify debug options for the compiler. The string of characters after - the :switch:`-gnatd` specify the specific debug options. The possible - characters are 0-9, a-z, A-Z, optionally preceded by a dot. See - compiler source file :file:`debug.adb` for details of the implemented + the :switch:`-gnatd` specifies the specific debug options. The possible + characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore. + See compiler source file :file:`debug.adb` for details of the implemented debug options. Certain debug options are relevant to applications programmers, and these are documented at appropriate points in this users guide. @@ -1735,8 +1748,7 @@ Alphabetical List of All Switches in bits.` ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is - 64 for the majority of GCC targets (but can be different on some targets like - AAMP). + 64 for the majority of GCC targets (but can be different on some targets). ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT`` documented as follows: `Define this macro to be the value 1 if instructions @@ -1775,8 +1787,9 @@ Alphabetical List of All Switches where ``name`` is the string name of the type (which can have single spaces embedded in the name (e.g. long double), ``digs`` is the number of digits for the floating-point type, ``float_rep`` is - the float representation (I/V/A for IEEE-754-Binary, Vax_Native, - AAMP), ``size`` is the size in bits, ``alignment`` is the + the float representation (I for IEEE-754-Binary, which is + the only one supported at this time), + ``size`` is the size in bits, ``alignment`` is the alignment in bits. The name is followed by at least two blanks, fields are separated by at least one blank, and a LF character immediately follows the alignment field. @@ -1896,7 +1909,7 @@ Alphabetical List of All Switches .. index:: -gnati (gcc) :switch:`-gnati{c}` - Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w). + Identifier character set (``c`` = 1/2/3/4/5/9/p/8/f/n/w). For details of the possible selections for ``c``, see :ref:`Character_Set_Control`. @@ -1997,8 +2010,7 @@ Alphabetical List of All Switches by the front end and will be visible in the :switch:`-gnatG` output. - When using a gcc-based back end (in practice this means using any version - of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of + When using a gcc-based back end, then the use of :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred. Historically front end inlining was more extensive than the gcc back end inlining, but that is no longer the case. @@ -3247,7 +3259,7 @@ of the pragma in the :title:`GNAT_Reference_manual`). :switch:`-gnatw.I` *Disable warnings on overlapping actuals.* - This switch disables warnings on overlapping actuals in a call.. + This switch disables warnings on overlapping actuals in a call. .. index:: -gnatwj (gcc) @@ -3424,7 +3436,10 @@ of the pragma in the :title:`GNAT_Reference_manual`). with no size clause. The guess in both cases is that 2**x was intended rather than x. In addition expressions of the form 2*x for small x generate a warning (the almost certainly accurate guess being that - 2**x was intended). The default is that these warnings are given. + 2**x was intended). This switch also activates warnings for negative + literal values of a modular type, which are interpreted as large positive + integers after wrap-around. The default is that these warnings are given. + .. index:: -gnatw.M (gcc) @@ -4620,8 +4635,18 @@ checks to be performed. The following checks are defined: in the string after :switch:`-gnaty` then proper indentation is checked, with the digit indicating the indentation level required. A value of zero turns off this style check. - The general style of required indentation is as specified by - the examples in the Ada Reference Manual. Full line comments must be + The rule checks that the following constructs start on a column that is + a multiple of the alignment level: + + * beginnings of declarations (except record component declarations) + and statements; + + * beginnings of the structural components of compound statements; + + * ``end`` keyword that completes the declaration of a program unit declaration + or body or that completes a compound statement. + + Full line comments must be aligned with the ``--`` starting on a column that is a multiple of the alignment level, or they may be aligned the same way as the following non-blank line (this is useful when full line comments appear in the middle @@ -5499,15 +5524,23 @@ indicate Ada 83 compatibility mode. for further information). +.. index:: -gnat2022 (gcc) +.. index:: Ada 2022 mode + +:switch:`-gnat2022` (Ada 2022 mode) + This switch directs the compiler to implement the Ada 2022 version of the + language. + + .. index:: -gnatX (gcc) .. index:: Ada language extensions .. index:: GNAT extensions :switch:`-gnatX` (Enable GNAT Extensions) This switch directs the compiler to implement the latest version of the - language (currently Ada 2012) and also to enable certain GNAT implementation + language (currently Ada 2022) and also to enable certain GNAT implementation extensions that are not part of any Ada standard. For a full list of these - extensions, see the GNAT reference manual. + extensions, see the GNAT reference manual, ``Pragma Extensions_Allowed``. .. _Character_Set_Control: @@ -5660,8 +5693,7 @@ Subprogram Inlining Control This switch activates front-end inlining which also generates additional dependencies. - When using a gcc-based back end (in practice this means using any version - of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of + When using a gcc-based back end, then the use of :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred. Historically front end inlining was more extensive than the gcc back end inlining, but that is no longer the case. diff --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst index 46d589a..39b9ca1 100644 --- a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst +++ b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst @@ -1672,8 +1672,7 @@ additional source files as follows: not require that the code generation be optimized. Like :switch:`-gnatn`, the use of this switch generates additional dependencies. - When using a gcc-based back end (in practice this means using any version - of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of + When using a gcc-based back end, then the use of :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred. Historically front end inlining was more extensive than the gcc back end inlining, but that is no longer the case. diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py index e6fafcf..0f7f963 100644 --- a/gcc/ada/doc/share/conf.py +++ b/gcc/ada/doc/share/conf.py @@ -18,9 +18,11 @@ import latex_elements DOCS = { 'gnat_rm': { - 'title': u'GNAT Reference Manual'}, + 'title': 'GNAT Reference Manual'}, 'gnat_ugn': { - 'title': u'GNAT User\'s Guide for Native Platforms'}} + 'title': 'GNAT User\'s Guide for Native Platforms'}, + 'gnat-style': { + 'title': 'GNAT Coding Style: A Guide for GNAT Developers'}} # Then retrieve the source directory root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) @@ -28,12 +30,12 @@ gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads') basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER') texi_fsf = True # Set to False when FSF doc is switched to sphinx by default -with open(gnatvsn_spec, 'rb') as fd: +with open(gnatvsn_spec, 'r') as fd: gnatvsn_content = fd.read() def get_copyright(): - return u'2008-%s, Free Software Foundation' % time.strftime('%Y') + return '2008-%s, Free Software Foundation' % time.strftime('%Y') def get_gnat_version(): @@ -41,18 +43,18 @@ def get_gnat_version(): r'constant String := "([^\(\)]+)\(.*\)?";', gnatvsn_content) if m: - return m.group(1).strip() + return m.group(1).strip().decode() else: if texi_fsf and os.path.exists(basever): return '' try: - with open(basever, 'rb') as fd: + with open(basever) as fd: return fd.read() - except: + except Exception: pass - print 'cannot find GNAT version in gnatvsn.ads or in ' + basever + print('cannot find GNAT version in gnatvsn.ads or in ' + basever) sys.exit(1) @@ -64,18 +66,18 @@ def get_gnat_build_type(): 'FSF': 'FSF', 'GPL': 'GPL'}[m.group(1).strip()] else: - print 'cannot compute GNAT build type' + print('cannot compute GNAT build type') sys.exit(1) # First retrieve the name of the documentation we are building doc_name = os.environ.get('DOC_NAME', None) if doc_name is None: - print 'DOC_NAME environment variable should be set' + print('DOC_NAME environment variable should be set') sys.exit(1) if doc_name not in DOCS: - print '%s is not a valid documentation name' % doc_name + print('%s is not a valid documentation name' % doc_name) sys.exit(1) @@ -84,11 +86,11 @@ exclude_patterns = [] for d in os.listdir(root_source_dir): if d not in ('share', doc_name, doc_name + '.rst'): exclude_patterns.append(d) - print 'ignoring %s' % d + print('ignoring %s' % d) if doc_name == 'gnat_rm': exclude_patterns.append('share/gnat_project_manager.rst') - print 'ignoring share/gnat_project_manager.rst' + print('ignoring share/gnat_project_manager.rst') extensions = [] templates_path = ['_templates'] @@ -103,7 +105,7 @@ copyright = get_copyright() version = get_gnat_version() release = get_gnat_version() -pygments_style = 'sphinx' +pygments_style = None tags.add(get_gnat_build_type()) html_theme = 'sphinxdoc' if os.path.isfile('adacore_transparent.png'): @@ -119,8 +121,8 @@ copyright_macros = { 'date': time.strftime("%b %d, %Y"), 'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO' else 'GPL', - 'name': u'GNU Ada', - 'tool': u'GNAT', + 'name': 'GNU Ada', + 'tool': 'GNAT', 'version': version} latex_elements = { @@ -134,13 +136,13 @@ latex_elements = { 'tableofcontents': latex_elements.TOC % copyright_macros} latex_documents = [ - (master_doc, '%s.tex' % doc_name, project, u'AdaCore', 'manual')] + (master_doc, '%s.tex' % doc_name, project, 'AdaCore', 'manual')] texinfo_documents = [ (master_doc, doc_name, project, - u'AdaCore', doc_name, doc_name, '')] + 'AdaCore', doc_name, doc_name, '')] def setup(app): - app.add_lexer('ada', ada_pygments.AdaLexer()) - app.add_lexer('gpr', ada_pygments.GNATProjectLexer()) + app.add_lexer('ada', ada_pygments.AdaLexer) + app.add_lexer('gpr', ada_pygments.GNATProjectLexer) diff --git a/gcc/ada/doc/share/gnat.sty b/gcc/ada/doc/share/gnat.sty new file mode 100644 index 0000000..1a152fb --- /dev/null +++ b/gcc/ada/doc/share/gnat.sty @@ -0,0 +1,72 @@ +% Needed to generate footers with total number of pages +\RequirePackage{lastpage} + +% AdaCore specific maketitle +\renewcommand{\maketitle}{% + \begin{titlepage}% + \let\footnotesize\small + \let\footnoterule\relax + \rule{\textwidth}{1pt}% + \ifsphinxpdfoutput + \begingroup + % These \defs are required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \def\and{and } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright}% + \sphinxlogo% + {\rm\Huge \@title \par}% + {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par} + \vfill + {\LARGE\py@HeaderFamily + \par} + \vfill\vfill + {\large + \@date \par + \vfill + \py@authoraddress \par + }% + \end{flushright}%\par + \@thanks + \end{titlepage}% + \cleardoublepage% + \setcounter{footnote}{0}% + \let\thanks\relax\let\maketitle\relax +} + +% AdaCore specific headers/footers +% Redefine the 'normal' header/footer style when using "fancyhdr" package: +\@ifundefined{fancyhf}{}{ + % Use \pagestyle{normal} as the primary pagestyle for text. + \fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage\ of \pageref*{LastPage}}} + \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} + \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} + \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} + % define chaptermark with \@chappos when \@chappos is available for Japanese + \ifx\@chappos\undefined\else + \def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}} + \fi + } + % Update the plain style so we get the page number & footer line, + % but not a chapter or section title. This is to keep the first + % page of a chapter and the blank page between chapters `clean.' + \fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage\ of \pageref*{LastPage}}} + \fancyfoot[LO,RE]{{\py@HeaderFamily \GNATFullDocumentName}} + \fancyhead[LE,RO]{{\py@HeaderFamily \@title\ \GNATVersion}} + \renewcommand{\headrulewidth}{0.0pt} + \renewcommand{\footrulewidth}{0.4pt} + } +} |