* :ref:`The_File_Cleanup_Utility_gnatclean`
* :ref:`The_GNAT_Library_Browser_gnatls`
- * :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
- * :ref:`The_Ada_to_HTML_Converter_gnathtml`
- * :ref:`The_Ada-to-XML_Converter_gnat2xml`
* :ref:`The_Coding_Standard_Verifier_gnatcheck`
* :ref:`The_GNAT_Metrics_Tool_gnatmetric`
* :ref:`The_GNAT_Pretty_Printer_gnatpp`
* :ref:`The_File_Cleanup_Utility_gnatclean`
* :ref:`The_GNAT_Library_Browser_gnatls`
- * :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
- * :ref:`The_Ada_to_HTML_Converter_gnathtml`
Other GNAT utilities are described elsewhere in this manual:
/home/comar/local/adainclude/unchconv.ads
-.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind:
-
-The Cross-Referencing Tools ``gnatxref`` and ``gnatfind``
-=========================================================
-
-.. index:: ! gnatxref
-.. index:: ! gnatfind
-
-The compiler generates cross-referencing information (unless
-you set the :switch:`-gnatx` switch), which are saved in the :file:`.ali` files.
-This information indicates where in the source each entity is declared and
-referenced. Note that entities in package Standard are not included, but
-entities in all other predefined units are included in the output.
-
-Before using any of these two tools, you need to compile successfully your
-application, so that GNAT gets a chance to generate the cross-referencing
-information.
-
-The two tools ``gnatxref`` and ``gnatfind`` take advantage of this
-information to provide the user with the capability to easily locate the
-declaration and references to an entity. These tools are quite similar,
-the difference being that ``gnatfind`` is intended for locating
-definitions and/or references to a specified entity or entities, whereas
-``gnatxref`` is oriented to generating a full report of all
-cross-references.
-
-To use these tools, you must not compile your application using the
-:switch:`-gnatx` switch on the ``gnatmake`` command line
-(see :ref:`The_GNAT_Make_Program_gnatmake`). Otherwise, cross-referencing
-information will not be generated.
-
-.. _gnatxref_Switches:
-
-``gnatxref`` Switches
----------------------
-
-The command invocation for ``gnatxref`` is:
-
- ::
-
- $ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
-
-where
-
-``sourcefile1`` [, ``sourcefile2`` ...]
- identify the source files for which a report is to be generated. The
- ``with``\ ed units will be processed too. You must provide at least one file.
-
- These file names are considered to be regular expressions, so for instance
- specifying :file:`source\*.adb` is the same as giving every file in the current
- directory whose name starts with :file:`source` and whose extension is
- :file:`adb`.
-
- You shouldn't specify any directory name, just base names. ``gnatxref``
- and ``gnatfind`` will be able to locate these files by themselves using
- the source path. If you specify directories, no result is produced.
-
-The following switches are available for ``gnatxref``:
-
-
-.. index:: --version (gnatxref)
-
-:switch:`--version`
- Display copyright and version, then exit disregarding all other options.
-
-
-.. index:: --help (gnatxref)
-
-:switch:`--help`
- If :switch:`--version` was not used, display usage, then exit disregarding
- all other options.
-
-
-.. index:: -a (gnatxref)
-
-:switch:`-a`
- If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
- the read-only files found in the library search path. Otherwise, these files
- will be ignored. This option can be used to protect Gnat sources or your own
- libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
- much faster, and their output much smaller. Read-only here refers to access
- or permissions status in the file system for the current user.
-
-
-.. index:: -aIDIR (gnatxref)
-
-:switch:`-aI{DIR}`
- When looking for source files also look in directory DIR. The order in which
- source file search is undertaken is the same as for ``gnatmake``.
-
-
-.. index:: -aODIR (gnatxref)
-
-:switch:`aO{DIR}`
- When -searching for library and object files, look in directory
- DIR. The order in which library files are searched is the same as for
- ``gnatmake``.
-
-
-.. index:: -nostdinc (gnatxref)
-
-:switch:`-nostdinc`
- Do not look for sources in the system default directory.
-
-
-.. index:: -nostdlib (gnatxref)
-
-:switch:`-nostdlib`
- Do not look for library files in the system default directory.
-
-
-.. index:: --ext (gnatxref)
-
-:switch:`--ext={extension}`
- Specify an alternate ali file extension. The default is ``ali`` and other
- extensions (e.g. ``gli`` for C/C++ sources) may be specified via this switch.
- Note that if this switch overrides the default, only the new extension will
- be considered.
-
-
-.. index:: --RTS (gnatxref)
-
-:switch:`--RTS={rts-path}`
- Specifies the default location of the runtime library. Same meaning as the
- equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
-
-
-.. index:: -d (gnatxref)
-
-:switch:`-d`
- If this switch is set ``gnatxref`` will output the parent type
- reference for each matching derived types.
-
-
-.. index:: -f (gnatxref)
-
-:switch:`-f`
- If this switch is set, the output file names will be preceded by their
- directory (if the file was found in the search path). If this switch is
- not set, the directory will not be printed.
-
-
-.. index:: -g (gnatxref)
-
-:switch:`-g`
- If this switch is set, information is output only for library-level
- entities, ignoring local entities. The use of this switch may accelerate
- ``gnatfind`` and ``gnatxref``.
-
-
-.. index:: -IDIR (gnatxref)
-
-:switch:`-I{DIR}`
- Equivalent to :switch:`-aODIR -aIDIR`.
-
-
-.. index:: -pFILE (gnatxref)
-
-:switch:`-p{FILE}`
- Specify a configuration file to use to list the source and object directories.
-
- If a file is specified, then the content of the source directory and object
- directory lines are added as if they had been specified respectively
- by :switch:`-aI` and :switch:`-aO`.
-
- See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
- of this configuration file.
-
-:switch:`-u`
- Output only unused symbols. This may be really useful if you give your
- main compilation unit on the command line, as ``gnatxref`` will then
- display every unused entity and 'with'ed package.
-
-:switch:`-v`
- Instead of producing the default output, ``gnatxref`` will generate a
- :file:`tags` file that can be used by vi. For examples how to use this
- feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output
- to the standard output, thus you will have to redirect it to a file.
-
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say ``gnatxref -ag`` instead of ``gnatxref -a -g``.
-
-.. _gnatfind_Switches:
-
-``gnatfind`` Switches
----------------------
-
-The command invocation for ``gnatfind`` is:
-
- ::
-
- $ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
-
-with the following iterpretation of the command arguments:
-
-*pattern*
- An entity will be output only if it matches the regular expression found
- in *pattern*, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`.
-
- Omitting the pattern is equivalent to specifying ``*``, which
- will match any entity. Note that if you do not provide a pattern, you
- have to provide both a sourcefile and a line.
-
- Entity names are given in Latin-1, with uppercase/lowercase equivalence
- for matching purposes. At the current time there is no support for
- 8-bit codes other than Latin-1, or for wide characters in identifiers.
-
-*sourcefile*
- ``gnatfind`` will look for references, bodies or declarations
- of symbols referenced in :file:`sourcefile`, at line ``line``
- and column ``column``. See :ref:`Examples_of_gnatfind_Usage`
- for syntax examples.
-
-*line*
- A decimal integer identifying the line number containing
- the reference to the entity (or entities) to be located.
-
-
-*column*
- A decimal integer identifying the exact location on the
- line of the first character of the identifier for the
- entity reference. Columns are numbered from 1.
-
-
-*file1 file2 ...*
- The search will be restricted to these source files. If none are given, then
- the search will be conducted for every library file in the search path.
- These files must appear only after the pattern or sourcefile.
-
- These file names are considered to be regular expressions, so for instance
- specifying :file:`source\*.adb` is the same as giving every file in the current
- directory whose name starts with :file:`source` and whose extension is
- :file:`adb`.
-
- The location of the spec of the entity will always be displayed, even if it
- isn't in one of :file:`file1`, :file:`file2`, ... The
- occurrences of the entity in the separate units of the ones given on the
- command line will also be displayed.
-
- Note that if you specify at least one file in this part, ``gnatfind`` may
- sometimes not be able to find the body of the subprograms.
-
-At least one of 'sourcefile' or 'pattern' has to be present on
-the command line.
-
-The following switches are available:
-
-.. index:: --version (gnatfind)
-
-:switch:`--version`
- Display copyright and version, then exit disregarding all other options.
-
-
-.. index:: --help (gnatfind)
-
-:switch:`--help`
- If :switch:`--version` was not used, display usage, then exit disregarding
- all other options.
-
-
-.. index:: -a (gnatfind)
-
-:switch:`-a`
- If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
- the read-only files found in the library search path. Otherwise, these files
- will be ignored. This option can be used to protect Gnat sources or your own
- libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
- much faster, and their output much smaller. Read-only here refers to access
- or permission status in the file system for the current user.
-
-
-.. index:: -aIDIR (gnatfind)
-
-:switch:`-aI{DIR}`
- When looking for source files also look in directory DIR. The order in which
- source file search is undertaken is the same as for ``gnatmake``.
-
-
-.. index:: -aODIR (gnatfind)
-
-:switch:`-aO{DIR}`
- When searching for library and object files, look in directory
- DIR. The order in which library files are searched is the same as for
- ``gnatmake``.
-
-
-.. index:: -nostdinc (gnatfind)
-
-:switch:`-nostdinc`
- Do not look for sources in the system default directory.
-
-
-.. index:: -nostdlib (gnatfind)
-
-:switch:`-nostdlib`
- Do not look for library files in the system default directory.
-
-
-.. index:: --ext (gnatfind)
-
-:switch:`--ext={extension}`
- Specify an alternate ali file extension. The default is ``ali`` and other
- extensions may be specified via this switch. Note that if this switch
- overrides the default, only the new extension will be considered.
-
-
-.. index:: --RTS (gnatfind)
-
-:switch:`--RTS={rts-path}`
- Specifies the default location of the runtime library. Same meaning as the
- equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
-
-
-.. index:: -d (gnatfind)
-
-:switch:`-d`
- If this switch is set, then ``gnatfind`` will output the parent type
- reference for each matching derived types.
-
-
-.. index:: -e (gnatfind)
-
-:switch:`-e`
- By default, ``gnatfind`` accept the simple regular expression set for
- ``pattern``. If this switch is set, then the pattern will be
- considered as full Unix-style regular expression.
-
-
-.. index:: -f (gnatfind)
-
-:switch:`-f`
- If this switch is set, the output file names will be preceded by their
- directory (if the file was found in the search path). If this switch is
- not set, the directory will not be printed.
-
-
-.. index:: -g (gnatfind)
-
-:switch:`-g`
- If this switch is set, information is output only for library-level
- entities, ignoring local entities. The use of this switch may accelerate
- ``gnatfind`` and ``gnatxref``.
-
-
-.. index:: -IDIR (gnatfind)
-
-:switch:`-I{DIR}`
- Equivalent to :switch:`-aODIR -aIDIR`.
-
-
-.. index:: -pFILE (gnatfind)
-
-:switch:`-p{FILE}`
- Specify a configuration file to use to list the source and object directories.
-
- If a file is specified, then the content of the source directory and object
- directory lines are added as if they had been specified respectively
- by :switch:`-aI` and :switch:`-aO`.
-
- See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
- of this configuration file.
-
-.. index:: -r (gnatfind)
-
-:switch:`-r`
- By default, ``gnatfind`` will output only the information about the
- declaration, body or type completion of the entities. If this switch is
- set, the ``gnatfind`` will locate every reference to the entities in
- the files specified on the command line (or in every file in the search
- path if no file is given on the command line).
-
-
-.. index:: -s (gnatfind)
-
-:switch:`-s`
- If this switch is set, then ``gnatfind`` will output the content
- of the Ada source file lines were the entity was found.
-
-
-.. index:: -t (gnatfind)
-
-:switch:`-t`
- If this switch is set, then ``gnatfind`` will output the type hierarchy for
- the specified type. It act like -d option but recursively from parent
- type to parent type. When this switch is set it is not possible to
- specify more than one file.
-
-
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say ``gnatxref -ag`` instead of
-``gnatxref -a -g``.
-
-As stated previously, ``gnatfind`` will search in every directory in the
-search path. You can force it to look only in the current directory if
-you specify ``*`` at the end of the command line.
-
-.. _Configuration_Files_for_gnatxref_and_gnatfind:
-
-Configuration Files for ``gnatxref`` and ``gnatfind``
------------------------------------------------------
-
-Configuration files are used by ``gnatxref`` and ``gnatfind`` to specify
-the list of source and object directories to consider. They can be
-specified via the :switch:`-p` switch.
-
-The following lines can be included, in any order in the file:
-
-* *src_dir=DIR*
- [default: ``"./"``].
- Specifies a directory where to look for source files. Multiple ``src_dir``
- lines can be specified and they will be searched in the order they
- are specified.
-
-* *obj_dir=DIR*
- [default: ``"./"``].
- Specifies a directory where to look for object and library files. Multiple
- ``obj_dir`` lines can be specified, and they will be searched in the order
- they are specified
-
-Any other line will be silently ignored.
-
-.. _Regular_Expressions_in_gnatfind_and_gnatxref:
-
-Regular Expressions in ``gnatfind`` and ``gnatxref``
-----------------------------------------------------
-
-As specified in the section about ``gnatfind``, the pattern can be a
-regular expression. Two kinds of regular expressions
-are recognized:
-
-* *Globbing pattern*
- These are the most common regular expression. They are the same as are
- generally used in a Unix shell command line, or in a DOS session.
-
- Here is a more formal grammar:
-
- ::
-
- regexp ::= term
- term ::= elmt -- matches elmt
- term ::= elmt elmt -- concatenation (elmt then elmt)
- term ::= * -- any string of 0 or more characters
- term ::= ? -- matches any character
- term ::= [char {char}] -- matches any character listed
- term ::= [char - char] -- matches any character in range
-
-* *Full regular expression*
- The second set of regular expressions is much more powerful. This is the
- type of regular expressions recognized by utilities such as ``grep``.
-
- The following is the form of a regular expression, expressed in same BNF
- style as is found in the Ada Reference Manual:
-
- ::
-
- regexp ::= term {| term} -- alternation (term or term ...)
-
- term ::= item {item} -- concatenation (item then item)
-
- item ::= elmt -- match elmt
- item ::= elmt * -- zero or more elmt's
- item ::= elmt + -- one or more elmt's
- item ::= elmt ? -- matches elmt or nothing
-
- elmt ::= nschar -- matches given character
- elmt ::= [nschar {nschar}] -- matches any character listed
- elmt ::= [^ nschar {nschar}] -- matches any character not listed
- elmt ::= [char - char] -- matches chars in given range
- elmt ::= \\ char -- matches given character
- elmt ::= . -- matches any single character
- elmt ::= ( regexp ) -- parens used for grouping
-
- char ::= any character, including special characters
- nschar ::= any character except ()[].*+?^
-
- Here are a few examples:
-
- ``abcde|fghi``
- will match any of the two strings ``abcde`` and ``fghi``,
-
- ``abc*d``
- will match any string like ``abd``, ``abcd``, ``abccd``,
- ``abcccd``, and so on,
-
- ``[a-z]+``
- will match any string which has only lowercase characters in it (and at
- least one character.
-
-
-.. _Examples_of_gnatxref_Usage:
-
-Examples of ``gnatxref`` Usage
-------------------------------
-
-General Usage
-^^^^^^^^^^^^^
-
-For the following examples, we will consider the following units:
-
- .. code-block:: ada
-
- main.ads:
- 1: with Bar;
- 2: package Main is
- 3: procedure Foo (B : in Integer);
- 4: C : Integer;
- 5: private
- 6: D : Integer;
- 7: end Main;
-
- main.adb:
- 1: package body Main is
- 2: procedure Foo (B : in Integer) is
- 3: begin
- 4: C := B;
- 5: D := B;
- 6: Bar.Print (B);
- 7: Bar.Print (C);
- 8: end Foo;
- 9: end Main;
-
- bar.ads:
- 1: package Bar is
- 2: procedure Print (B : Integer);
- 3: end bar;
-
-The first thing to do is to recompile your application (for instance, in
-that case just by doing a ``gnatmake main``, so that GNAT generates
-the cross-referencing information.
-You can then issue any of the following commands:
-
- * ``gnatxref main.adb``
- ``gnatxref`` generates cross-reference information for main.adb
- and every unit 'with'ed by main.adb.
-
- The output would be:
-
- ::
-
- B Type: Integer
- Decl: bar.ads 2:22
- B Type: Integer
- Decl: main.ads 3:20
- Body: main.adb 2:20
- Ref: main.adb 4:13 5:13 6:19
- Bar Type: Unit
- Decl: bar.ads 1:9
- Ref: main.adb 6:8 7:8
- main.ads 1:6
- C Type: Integer
- Decl: main.ads 4:5
- Modi: main.adb 4:8
- Ref: main.adb 7:19
- D Type: Integer
- Decl: main.ads 6:5
- Modi: main.adb 5:8
- Foo Type: Unit
- Decl: main.ads 3:15
- Body: main.adb 2:15
- Main Type: Unit
- Decl: main.ads 2:9
- Body: main.adb 1:14
- Print Type: Unit
- Decl: bar.ads 2:15
- Ref: main.adb 6:12 7:12
-
-
- This shows that the entity ``Main`` is declared in main.ads, line 2, column 9,
- its body is in main.adb, line 1, column 14 and is not referenced any where.
-
- The entity ``Print`` is declared in :file:`bar.ads`, line 2, column 15 and it
- is referenced in :file:`main.adb`, line 6 column 12 and line 7 column 12.
-
-
- * ``gnatxref package1.adb package2.ads``
- ``gnatxref`` will generates cross-reference information for
- :file:`package1.adb`, :file:`package2.ads` and any other package ``with``\ ed by any
- of these.
-
-
-Using ``gnatxref`` with ``vi``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``gnatxref`` can generate a tags file output, which can be used
-directly from ``vi``. Note that the standard version of ``vi``
-will not work properly with overloaded symbols. Consider using another
-free implementation of ``vi``, such as ``vim``.
-
- ::
-
- $ gnatxref -v gnatfind.adb > tags
-
-
-The following command will generate the tags file for ``gnatfind`` itself
-(if the sources are in the search path!):
-
- ::
-
- $ gnatxref -v gnatfind.adb > tags
-
-From ``vi``, you can then use the command :samp:`:tag {entity}`
-(replacing ``entity`` by whatever you are looking for), and vi will
-display a new file with the corresponding declaration of entity.
-
-
-.. _Examples_of_gnatfind_Usage:
-
-Examples of ``gnatfind`` Usage
-------------------------------
-
-* ``gnatfind -f xyz:main.adb``
- Find declarations for all entities xyz referenced at least once in
- main.adb. The references are search in every library file in the search
- path.
-
- The directories will be printed as well (as the ``-f``
- switch is set)
-
- The output will look like:
-
- ::
-
- directory/main.ads:106:14: xyz <= declaration
- directory/main.adb:24:10: xyz <= body
- directory/foo.ads:45:23: xyz <= declaration
-
- I.e., one of the entities xyz found in main.adb is declared at
- line 12 of main.ads (and its body is in main.adb), and another one is
- declared at line 45 of foo.ads
-
-* ``gnatfind -fs xyz:main.adb``
- This is the same command as the previous one, but ``gnatfind`` will
- display the content of the Ada source file lines.
-
- The output will look like:
-
- ::
-
- directory/main.ads:106:14: xyz <= declaration
- procedure xyz;
- directory/main.adb:24:10: xyz <= body
- procedure xyz is
- directory/foo.ads:45:23: xyz <= declaration
- xyz : Integer;
-
- This can make it easier to find exactly the location your are looking
- for.
-
-
-* ``gnatfind -r "*x*":main.ads:123 foo.adb``
- Find references to all entities containing an x that are
- referenced on line 123 of main.ads.
- The references will be searched only in main.ads and foo.adb.
-
-
-* ``gnatfind main.ads:123``
- Find declarations and bodies for all entities that are referenced on
- line 123 of main.ads.
-
- This is the same as ``gnatfind "*":main.adb:123```
-
-* ``gnatfind mydir/main.adb:123:45``
- Find the declaration for the entity referenced at column 45 in
- line 123 of file main.adb in directory mydir. Note that it
- is usual to omit the identifier name when the column is given,
- since the column position identifies a unique reference.
-
- The column has to be the beginning of the identifier, and should not
- point to any character in the middle of the identifier.
-
-
-.. _The_Ada_to_HTML_Converter_gnathtml:
-
-The Ada to HTML Converter ``gnathtml``
-======================================
-
-.. index:: ! gnathtml
-
-``gnathtml`` is a Perl script that allows Ada source files to be browsed using
-standard Web browsers. For installation information, see :ref:`Installing_gnathtml`.
-
-Ada reserved keywords are highlighted in a bold font and Ada comments in
-a blue font. Unless your program was compiled with the gcc :switch:`-gnatx`
-switch to suppress the generation of cross-referencing information, user
-defined variables and types will appear in a different color; you will
-be able to click on any identifier and go to its declaration.
-
-.. _Invoking_gnathtml:
-
-Invoking ``gnathtml``
----------------------
-
-The command line is as follows:
-
- ::
-
- $ perl gnathtml.pl [ switches ] ada-files
-
-You can specify as many Ada files as you want. ``gnathtml`` will generate
-an html file for every ada file, and a global file called :file:`index.htm`.
-This file is an index of every identifier defined in the files.
-
-The following switches are available:
-
-.. index:: -83 (gnathtml)
-
-:samp:`83`
- Only the Ada 83 subset of keywords will be highlighted.
-
-.. index:: -cc (gnathtml)
-
-:samp:`cc {color}`
- This option allows you to change the color used for comments. The default
- value is green. The color argument can be any name accepted by html.
-
-.. index:: -d (gnathtml)
-
-:samp:`d`
- If the Ada files depend on some other files (for instance through
- ``with`` clauses, the latter files will also be converted to html.
- Only the files in the user project will be converted to html, not the files
- in the run-time library itself.
-
-.. index:: -D (gnathtml)
-
-:samp:`D`
- This command is the same as :switch:`-d` above, but ``gnathtml`` will
- also look for files in the run-time library, and generate html files for them.
-
-.. index:: -ext (gnathtml)
-
-:samp:`ext {extension}`
- This option allows you to change the extension of the generated HTML files.
- If you do not specify an extension, it will default to :file:`htm`.
-
-.. index:: -f (gnathtml)
-
-:samp:`f`
- By default, gnathtml will generate html links only for global entities
- ('with'ed units, global variables and types,...). If you specify
- :switch:`-f` on the command line, then links will be generated for local
- entities too.
-
-.. index:: -l (gnathtml)
-
-:samp:`l {number}`
- If this switch is provided and ``number`` is not 0, then
- ``gnathtml`` will number the html files every ``number`` line.
-
-.. index:: -I (gnathtml)
-
-:samp:`I {dir}`
- Specify a directory to search for library files (:file:`.ALI` files) and
- source files. You can provide several -I switches on the command line,
- and the directories will be parsed in the order of the command line.
-
-.. index:: -o (gnathtml)
-
-:samp:`o {dir}`
- Specify the output directory for html files. By default, gnathtml will
- saved the generated html files in a subdirectory named :file:`html/`.
-
-.. index:: -p (gnathtml)
-
-:samp:`p {file}`
- If you are using Emacs and the most recent Emacs Ada mode, which provides
- a full Integrated Development Environment for compiling, checking,
- running and debugging applications, you may use :file:`.gpr` files
- to give the directories where Emacs can find sources and object files.
-
- Using this switch, you can tell gnathtml to use these files.
- This allows you to get an html version of your application, even if it
- is spread over multiple directories.
-
-.. index:: -sc (gnathtml)
-
-:samp:`sc {color}`
- This switch allows you to change the color used for symbol
- definitions.
- The default value is red. The color argument can be any name accepted by html.
-
-.. index:: -t (gnathtml)
-
-:samp:`t {file}`
- This switch provides the name of a file. This file contains a list of
- file names to be converted, and the effect is exactly as though they had
- appeared explicitly on the command line. This
- is the recommended way to work around the command line length limit on some
- systems.
-
-.. _Installing_gnathtml:
-
-Installing ``gnathtml``
------------------------
-
-``Perl`` needs to be installed on your machine to run this script.
-``Perl`` is freely available for almost every architecture and
-operating system via the Internet.
-
-On Unix systems, you may want to modify the first line of the script
-``gnathtml``, to explicitly specify where Perl
-is located. The syntax of this line is:
-
- ::
-
- #!full_path_name_to_perl
-
-Alternatively, you may run the script using the following command line:
-
- ::
-
- $ perl gnathtml.pl [ switches ] files
-
-
-
-
-.. -- +---------------------------------------------------------------------+
-.. -- | The following sections are present only in the PRO and GPL editions |
-.. -- +---------------------------------------------------------------------+
-
-.. only:: PRO or GPL
-
- .. _The_Ada-to-XML_converter_gnat2xml:
-
- The Ada-to-XML converter ``gnat2xml``
- =====================================
-
- .. index:: ! gnat2xml
- .. index:: XML generation
-
- The ``gnat2xml`` tool is an ASIS-based utility that converts
- Ada source code into XML.
-
- ``gnat2xml`` is a project-aware tool
- (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
- ``gnat2xml`` switches is named ``gnat2xml``.
-
- .. _Switches_for_``gnat2xml``:
-
- Switches for ``gnat2xml``
- -------------------------
-
- ``gnat2xml`` takes Ada source code as input, and produces XML
- that conforms to the schema.
-
- Usage:
-
- ::
-
- $ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches]
-
- Options:
-
- :switch:`--help`
- Generate usage information and quit, ignoring all other options
-
- :switch:`-h`
- Same as ``--help``
-
- :switch:`--version`
- Print version and quit, ignoring all other options
-
- :switch:`-P{file}`
- indicates the name of the project file that describes
- the set of sources to be processed. The exact set of argument
- sources depends on other options specified, see below.
-
- :switch:`-U`
- If a project file is specified and no argument source is explicitly
- specified, process all the units of the closure of the argument project.
- Otherwise this option has no effect.
-
- :switch:`-U {main_unit}`
- If a project file is specified and no argument source
- is explicitly specified (either directly or by means of :switch:`-files`
- option), process the closure of units rooted at ``main_unit``.
- Otherwise this option has no effect.
-
- :switch:`-X{name}={value}`
- Indicates that external variable ``name`` in
- the argument project has the value ``value``. Has no effect if no
- project is specified.
-
- :switch:`--RTS={rts-path}`
- Specifies the default location of the runtime
- library. Same meaning as the equivalent ``gnatmake`` flag
- (:ref:`Switches_for_gnatmake`).
-
- :switch:`--incremental`
- Incremental processing on a per-file basis. Source files are
- only processed if they have been modified, or if files they depend
- on have been modified. This is similar to the way gnatmake/gprbuild
- only compiles files that need to be recompiled. A project file
- is required in this mode.
-
- :switch:`-j{n}`
- In :switch:`--incremental` mode, use ``n`` ``gnat2xml``
- processes to perform XML generation in parallel. If ``n`` is 0, then
- the maximum number of parallel tree creations is the number of core
- processors on the platform.
-
- :switch:`--output-dir={dir}`
- Generate one .xml file for each Ada source file, in
- directory :file:`dir`. (Default is to generate the XML to standard
- output.)
-
- :switch:`-I{include-dir}`
- Directories to search for dependencies.
- You can also set the ADA_INCLUDE_PATH environment variable for this.
-
- :switch:`--compact`
- Debugging version, with interspersed source, and a more
- compact representation of "sloc". This version does not conform
- to any schema.
-
- :switch:`--rep-clauses`
- generate representation clauses (see :ref:`Generating_Representation_Clauses`).
-
- :switch:`-files={filename}`
- Take as arguments the files listed in text file ``file``.
- Text file ``file`` may contain empty lines that are ignored.
- Each nonempty line should contain the name of an existing file.
- Several such switches may be specified simultaneously.
-
- :switch:`--ignore={filename}`
- Do not process the sources listed in a specified file. This option cannot
- be used in incremental mode.
-
- :switch:`-q`
- Quiet
-
- :switch:`-v`
- Verbose
-
- :switch:`-cargs` ...
- Options to pass to gcc
-
- If a project file is specified and no argument source is explicitly
- specified, and no :switch:`-U` is specified, then the set of processed
- sources is all the immediate units of the argument project.
-
- Example:
-
- ::
-
- $ gnat2xml -v -output-dir=xml-files *.ad[sb]
-
- The above will create \*.xml files in the :file:`xml-files` subdirectory.
- For example, if there is an Ada package Mumble.Dumble, whose spec and
- body source code lives in mumble-dumble.ads and mumble-dumble.adb,
- the above will produce xml-files/mumble-dumble.ads.xml and
- xml-files/mumble-dumble.adb.xml.
-
- .. _Other_Programs:
-
- Other Programs
- --------------
-
- The distribution includes two other programs that are related to
- ``gnat2xml``:
-
- ``gnat2xsd`` is the schema generator, which generates the schema
- to standard output, based on the structure of Ada as encoded by
- ASIS. You don't need to run ``gnat2xsd`` in order to use
- ``gnat2xml``. To generate the schema, type:
-
-
- ::
-
- $ gnat2xsd > ada-schema.xsd
-
-
- ``gnat2xml`` generates XML files that will validate against
- :file:`ada-schema.xsd`.
-
- ``xml2gnat`` is a back-translator that translates the XML back into
- Ada source code. This is primarily for the purpose of testing
- ``gnat2xml``, rather than for users. The Ada generated by ``xml2gnat``
- has identical semantics to the original Ada code passed to
- ``gnat2xml``. It is not textually identical, however --- for example,
- no attempt is made to preserve the original indentation.
-
- The ``xml2gnat`` command line contains a list of the same Ada files
- passed to gnat2xml (not the names of xml files). The xml files are
- assumed to be in an 'xml' subdirectory of the directory in which the
- Ada source files are. So for example, if the Ada source file is
- some/dir/mumble.adb, then the xml file is found in
- some/dir/xml/mumble.adb.xml. You should use the :switch:`--output-dir`
- switch of ``gnat2xml`` to tell it to generate the output in the xml
- subdirectory, so ``xml2gnat`` can find it.
-
- Output goes into subdirectories "generated_ada" and "self_rep" of the
- output directory, which is the current directory by default, but can
- be overridden with --output-dir=dir on the command line.
-
- .. _Structure_of_the_XML:
-
- Structure of the XML
- --------------------
-
- The primary documentation for the structure of the XML generated by
- ``gnat2xml`` is the schema (see ``gnat2xsd`` above). The
- following documentation gives additional details needed to understand
- the schema and therefore the XML.
-
- The elements listed under Defining Occurrences, Usage Occurrences, and
- Other Elements represent the syntactic structure of the Ada program.
- Element names are given in lower case, with the corresponding element
- type Capitalized_Like_This. The element and element type names are
- derived directly from the ASIS enumeration type Flat_Element_Kinds,
- declared in Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_``
- removed. For example, the ASIS enumeration literal
- An_Assignment_Statement corresponds to the XML element
- assignment_statement of XML type Assignment_Statement.
-
- To understand the details of the schema and the corresponding XML, it is
- necessary to understand the ASIS standard, as well as the GNAT-specific
- extension to ASIS.
-
- A defining occurrence is an identifier (or character literal or operator
- symbol) declared by a declaration. A usage occurrence is an identifier
- (or ...) that references such a declared entity. For example, in:
-
-
- .. code-block:: ada
-
- type T is range 1..10;
- X, Y : constant T := 1;
-
-
- The first 'T' is the defining occurrence of a type. The 'X' is the
- defining occurrence of a constant, as is the 'Y', and the second 'T' is
- a usage occurrence referring to the defining occurrence of T.
-
- Each element has a 'sloc' (source location), and subelements for each
- syntactic subtree, reflecting the Ada grammar as implemented by ASIS.
- The types of subelements are as defined in the ASIS standard. For
- example, for the right-hand side of an assignment_statement we have
- the following comment in asis-statements.ads:
-
- .. code-block:: ada
-
- ------------------------------------------------------------------------------
- -- 18.3 function Assignment_Expression
- ------------------------------------------------------------------------------
-
- function Assignment_Expression
- (Statement : Asis.Statement)
- return Asis.Expression;
-
- ------------------------------------------------------------------------------
- ...
- -- Returns the expression from the right hand side of the assignment.
- ...
- -- Returns Element_Kinds:
- -- An_Expression
-
-
- The corresponding sub-element of type Assignment_Statement is:
-
- ::
-
- <xsd:element name="assignment_expression_q" type="Expression_Class"/>
-
- where Expression_Class is defined by an xsd:choice of all the
- various kinds of expression.
-
- The 'sloc' of each element indicates the starting and ending line and
- column numbers. Column numbers are character counts; that is, a tab
- counts as 1, not as however many spaces it might expand to.
-
- Subelements of type Element have names ending in '_q' (for ASIS
- "Query"), and those of type Element_List end in '_ql'
- ("Query returning List").
-
- Some subelements are 'Boolean'. For example, Private_Type_Definition
- has has_abstract_q and has_limited_q, to indicate whether those
- keywords are present, as in ``type T is abstract limited private;``.
- False is represented by a Nil_Element. True is represented
- by an element type specific to that query (for example, Abstract and
- Limited).
-
- The root of the tree is a Compilation_Unit, with attributes:
-
- * unit_kind, unit_class, and unit_origin. These are strings that match the
- enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins
- in package Asis.
-
- * unit_full_name is the full expanded name of the unit, starting from a
- root library unit. So for ``package P.Q.R is ...``,
- ``unit_full_name="P.Q.R"``. Same for ``separate (P.Q) package R is ...``.
-
- * def_name is the same as unit_full_name for library units; for subunits,
- it is just the simple name.
-
- * source_file is the name of the Ada source file. For example, for
- the spec of ``P.Q.R``, ``source_file="p-q-r.ads"``. This allows one to
- interpret the source locations --- the 'sloc' of all elements
- within this Compilation_Unit refers to line and column numbers
- within the named file.
-
- Defining occurrences have these attributes:
-
- * def_name is the simple name of the declared entity, as written in the Ada
- source code.
-
- * def is a unique URI of the form:
-
- ::
-
- ada://kind/fully/qualified/name
-
- where:
-
- * kind indicates the kind of Ada entity being declared (see below), and
-
- * fully/qualified/name, is the fully qualified name of the Ada
- entity, with each of 'fully', 'qualified', and 'name' being
- mangled for uniqueness. We do not document the mangling
- algorithm, which is subject to change; we just guarantee that the
- names are unique in the face of overloading.
-
- * type is the type of the declared object, or ``null`` for
- declarations of things other than objects.
-
- Usage occurrences have these attributes:
-
- * ref_name is the same as the def_name of the corresponding defining
- occurrence. This attribute is not of much use, because of
- overloading; use ref for lookups, instead.
-
- * ref is the same as the def of the corresponding defining
- occurrence.
-
- In summary, ``def_name`` and ``ref_name`` are as in the source
- code of the declaration, possibly overloaded, whereas ``def`` and
- ``ref`` are unique-ified.
-
- Literal elements have this attribute:
-
- * lit_val is the value of the literal as written in the source text,
- appropriately escaped (e.g. ``"`` |rightarrow| ``"``). This applies
- only to numeric and string literals. Enumeration literals in Ada are
- not really "literals" in the usual sense; they are usage occurrences,
- and have ref_name and ref as described above. Note also that string
- literals used as operator symbols are treated as defining or usage
- occurrences, not as literals.
-
- Elements that can syntactically represent names and expressions (which
- includes usage occurrences, plus function calls and so forth) have this
- attribute:
-
- * type. If the element represents an expression or the name of an object,
- 'type' is the 'def' for the defining occurrence of the type of that
- expression or name. Names of other kinds of entities, such as package
- names and type names, do not have a type in Ada; these have type="null"
- in the XML.
-
- Pragma elements have this attribute:
-
- * pragma_name is the name of the pragma. For language-defined pragmas, the
- pragma name is redundant with the element kind (for example, an
- assert_pragma element necessarily has pragma_name="Assert"). However, all
- implementation-defined pragmas are lumped together in ASIS as a single
- element kind (for example, the GNAT-specific pragma Unreferenced is
- represented by an implementation_defined_pragma element with
- pragma_name="Unreferenced").
-
- Defining occurrences of formal parameters and generic formal objects have this
- attribute:
-
- * mode indicates that the parameter is of mode 'in', 'in out', or 'out'.
-
- All elements other than Not_An_Element have this attribute:
-
- * checks is a comma-separated list of run-time checks that are needed
- for that element. The possible checks are: do_accessibility_check,
- do_discriminant_check,do_division_check,do_length_check,
- do_overflow_check,do_range_check,do_storage_check,do_tag_check.
-
- The "kind" part of the "def" and "ref" attributes is taken from the ASIS
- enumeration type Flat_Declaration_Kinds, declared in
- Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` removed, and
- any trailing ``_Declaration`` or ``_Specification`` removed. Thus, the
- possible kinds are as follows:
-
- ::
-
- ordinary_type
- task_type
- protected_type
- incomplete_type
- tagged_incomplete_type
- private_type
- private_extension
- subtype
- variable
- constant
- deferred_constant
- single_task
- single_protected
- integer_number
- real_number
- enumeration_literal
- discriminant
- component
- loop_parameter
- generalized_iterator
- element_iterator
- procedure
- function
- parameter
- procedure_body
- function_body
- return_variable
- return_constant
- null_procedure
- expression_function
- package
- package_body
- object_renaming
- exception_renaming
- package_renaming
- procedure_renaming
- function_renaming
- generic_package_renaming
- generic_procedure_renaming
- generic_function_renaming
- task_body
- protected_body
- entry
- entry_body
- entry_index
- procedure_body_stub
- function_body_stub
- package_body_stub
- task_body_stub
- protected_body_stub
- exception
- choice_parameter
- generic_procedure
- generic_function
- generic_package
- package_instantiation
- procedure_instantiation
- function_instantiation
- formal_object
- formal_type
- formal_incomplete_type
- formal_procedure
- formal_function
- formal_package
- formal_package_declaration_with_box
-
- .. _Generating_Representation_Clauses:
-
- Generating Representation Clauses
- ---------------------------------
-
- If the :switch:`--rep-clauses` switch is given, ``gnat2xml`` will
- generate representation clauses for certain types showing the
- representation chosen by the compiler. The information is produced by
- the ASIS 'Data Decomposition' facility --- see the
- ``Asis.Data_Decomposition`` package for details.
-
- Not all types are supported. For example, ``Type_Model_Kind`` must
- be ``A_Simple_Static_Model``. Types declared within generic units
- have no representation. The clauses that are generated include
- ``attribute_definition_clauses`` for ``Size`` and
- ``Component_Size``, as well as
- ``record_representation_clauses``.
-
- There is no guarantee that the generated representation clauses could
- have actually come from legal Ada code; Ada has some restrictions that
- are not necessarily obeyed by the generated clauses.
-
- The representation clauses are surrounded by comment elements to
- indicate that they are automatically generated, something like this:
-
- ::
-
- <comment text="--gen+">
- ...
- <attribute_definition_clause>
- ...
- <comment text="--gen-">
- ...
-
-
.. only:: PRO or GPL
.. _The_Coding_Standard_Verifier_gnatcheck:
* The File Cleanup Utility gnatclean::
* The GNAT Library Browser gnatls::
-* The Cross-Referencing Tools gnatxref and gnatfind::
-* The Ada to HTML Converter gnathtml::
The File Cleanup Utility gnatclean
* Switches for gnatls::
* Example of gnatls Usage::
-The Cross-Referencing Tools gnatxref and gnatfind
-
-* gnatxref Switches::
-* gnatfind Switches::
-* Configuration Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
-
-Examples of gnatxref Usage
-
-* General Usage::
-* Using gnatxref with vi::
-
-The Ada to HTML Converter gnathtml
-
-* Invoking gnathtml::
-* Installing gnathtml::
-
GNAT and Program Execution
* Running and Debugging Ada Programs::
@item
@ref{137,,The GNAT Library Browser gnatls}
-
-@item
-@ref{138,,The Cross-Referencing Tools gnatxref and gnatfind}
-
-@item
-@ref{139,,The Ada to HTML Converter gnathtml}
@end itemize
Other GNAT utilities are described elsewhere in this manual:
@menu
* The File Cleanup Utility gnatclean::
* The GNAT Library Browser gnatls::
-* The Cross-Referencing Tools gnatxref and gnatfind::
-* The Ada to HTML Converter gnathtml::
@end menu
@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{13a}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136}
+@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136}
@section The File Cleanup Utility @code{gnatclean}
@end menu
@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{13b}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{13c}
+@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{13a}
@subsection Running @code{gnatclean}
normal mode is listed, but no file is actually deleted.
@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{13d}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13e}
+@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c}
@subsection Switches for @code{gnatclean}
where @code{gnatclean} was invoked.
@end table
-@node The GNAT Library Browser gnatls,The Cross-Referencing Tools gnatxref and gnatfind,The File Cleanup Utility gnatclean,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13f}
+@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs
+@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d}
@section The GNAT Library Browser @code{gnatls}
@end menu
@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{141}
+@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f}
@subsection Running @code{gnatls}
@end table
@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{143}
+@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141}
@subsection Switches for @code{gnatls}
@end table
@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{144}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{145}
+@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{143}
@subsection Example of @code{gnatls} Usage
@end example
@end quotation
-@node The Cross-Referencing Tools gnatxref and gnatfind,The Ada to HTML Converter gnathtml,The GNAT Library Browser gnatls,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-cross-referencing-tools-gnatxref-and-gnatfind}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs id9}@anchor{146}
-@section The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
-
-
-@geindex gnatxref
-
-@geindex gnatfind
-
-The compiler generates cross-referencing information (unless
-you set the @code{-gnatx} switch), which are saved in the @code{.ali} files.
-This information indicates where in the source each entity is declared and
-referenced. Note that entities in package Standard are not included, but
-entities in all other predefined units are included in the output.
-
-Before using any of these two tools, you need to compile successfully your
-application, so that GNAT gets a chance to generate the cross-referencing
-information.
-
-The two tools @code{gnatxref} and @code{gnatfind} take advantage of this
-information to provide the user with the capability to easily locate the
-declaration and references to an entity. These tools are quite similar,
-the difference being that @code{gnatfind} is intended for locating
-definitions and/or references to a specified entity or entities, whereas
-@code{gnatxref} is oriented to generating a full report of all
-cross-references.
-
-To use these tools, you must not compile your application using the
-@code{-gnatx} switch on the @code{gnatmake} command line
-(see @ref{c6,,Building with gnatmake}). Otherwise, cross-referencing
-information will not be generated.
-
-@menu
-* gnatxref Switches::
-* gnatfind Switches::
-* Configuration Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
-
-@end menu
-
-@node gnatxref Switches,gnatfind Switches,,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id10}@anchor{147}@anchor{gnat_ugn/gnat_utility_programs gnatxref-switches}@anchor{148}
-@subsection @code{gnatxref} Switches
-
-
-The command invocation for @code{gnatxref} is:
-
-@quotation
-
-@example
-$ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
-@end example
-@end quotation
-
-where
-
-
-@table @asis
-
-@item @code{sourcefile1} [, @code{sourcefile2} ...]
-
-identify the source files for which a report is to be generated. The
-@code{with}ed units will be processed too. You must provide at least one file.
-
-These file names are considered to be regular expressions, so for instance
-specifying @code{source*.adb} is the same as giving every file in the current
-directory whose name starts with @code{source} and whose extension is
-@code{adb}.
-
-You shouldn't specify any directory name, just base names. @code{gnatxref}
-and @code{gnatfind} will be able to locate these files by themselves using
-the source path. If you specify directories, no result is produced.
-@end table
-
-The following switches are available for @code{gnatxref}:
-
-@geindex --version (gnatxref)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatxref)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -a (gnatxref)
-
-
-@table @asis
-
-@item @code{-a}
-
-If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
-the read-only files found in the library search path. Otherwise, these files
-will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
-much faster, and their output much smaller. Read-only here refers to access
-or permissions status in the file system for the current user.
-@end table
-
-@geindex -aIDIR (gnatxref)
-
-
-@table @asis
-
-@item @code{-aI@emph{DIR}}
-
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @code{gnatmake}.
-@end table
-
-@geindex -aODIR (gnatxref)
-
-
-@table @asis
-
-@item @code{aO@emph{DIR}}
-
-When -searching for library and object files, look in directory
-DIR. The order in which library files are searched is the same as for
-@code{gnatmake}.
-@end table
-
-@geindex -nostdinc (gnatxref)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Do not look for sources in the system default directory.
-@end table
-
-@geindex -nostdlib (gnatxref)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-@end table
-
-@geindex --ext (gnatxref)
-
-
-@table @asis
-
-@item @code{--ext=@emph{extension}}
-
-Specify an alternate ali file extension. The default is @code{ali} and other
-extensions (e.g. @code{gli} for C/C++ sources) may be specified via this switch.
-Note that if this switch overrides the default, only the new extension will
-be considered.
-@end table
-
-@geindex --RTS (gnatxref)
-
-
-@table @asis
-
-@item @code{--RTS=@emph{rts-path}}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
-@end table
-
-@geindex -d (gnatxref)
-
-
-@table @asis
-
-@item @code{-d}
-
-If this switch is set @code{gnatxref} will output the parent type
-reference for each matching derived types.
-@end table
-
-@geindex -f (gnatxref)
-
-
-@table @asis
-
-@item @code{-f}
-
-If this switch is set, the output file names will be preceded by their
-directory (if the file was found in the search path). If this switch is
-not set, the directory will not be printed.
-@end table
-
-@geindex -g (gnatxref)
-
-
-@table @asis
-
-@item @code{-g}
-
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
-@end table
-
-@geindex -IDIR (gnatxref)
-
-
-@table @asis
-
-@item @code{-I@emph{DIR}}
-
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
-
-@geindex -pFILE (gnatxref)
-
-
-@table @asis
-
-@item @code{-p@emph{FILE}}
-
-Specify a configuration file to use to list the source and object directories.
-
-If a file is specified, then the content of the source directory and object
-directory lines are added as if they had been specified respectively
-by @code{-aI} and @code{-aO}.
-
-See @ref{149,,Configuration Files for gnatxref and gnatfind} for the syntax
-of this configuration file.
-
-@item @code{-u}
-
-Output only unused symbols. This may be really useful if you give your
-main compilation unit on the command line, as @code{gnatxref} will then
-display every unused entity and 'with'ed package.
-
-@item @code{-v}
-
-Instead of producing the default output, @code{gnatxref} will generate a
-@code{tags} file that can be used by vi. For examples how to use this
-feature, see @ref{14a,,Examples of gnatxref Usage}. The tags file is output
-to the standard output, thus you will have to redirect it to a file.
-@end table
-
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say @code{gnatxref -ag} instead of @code{gnatxref -a -g}.
-
-@node gnatfind Switches,Configuration Files for gnatxref and gnatfind,gnatxref Switches,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id11}@anchor{14b}@anchor{gnat_ugn/gnat_utility_programs gnatfind-switches}@anchor{14c}
-@subsection @code{gnatfind} Switches
-
-
-The command invocation for @code{gnatfind} is:
-
-@quotation
-
-@example
-$ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
-@end example
-@end quotation
-
-with the following iterpretation of the command arguments:
-
-
-@table @asis
-
-@item @emph{pattern}
-
-An entity will be output only if it matches the regular expression found
-in @emph{pattern}, see @ref{14d,,Regular Expressions in gnatfind and gnatxref}.
-
-Omitting the pattern is equivalent to specifying @code{*}, which
-will match any entity. Note that if you do not provide a pattern, you
-have to provide both a sourcefile and a line.
-
-Entity names are given in Latin-1, with uppercase/lowercase equivalence
-for matching purposes. At the current time there is no support for
-8-bit codes other than Latin-1, or for wide characters in identifiers.
-
-@item @emph{sourcefile}
-
-@code{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @code{sourcefile}, at line @code{line}
-and column @code{column}. See @ref{14e,,Examples of gnatfind Usage}
-for syntax examples.
-
-@item @emph{line}
-
-A decimal integer identifying the line number containing
-the reference to the entity (or entities) to be located.
-
-@item @emph{column}
-
-A decimal integer identifying the exact location on the
-line of the first character of the identifier for the
-entity reference. Columns are numbered from 1.
-
-@item @emph{file1 file2 ...}
-
-The search will be restricted to these source files. If none are given, then
-the search will be conducted for every library file in the search path.
-These files must appear only after the pattern or sourcefile.
-
-These file names are considered to be regular expressions, so for instance
-specifying @code{source*.adb} is the same as giving every file in the current
-directory whose name starts with @code{source} and whose extension is
-@code{adb}.
-
-The location of the spec of the entity will always be displayed, even if it
-isn't in one of @code{file1}, @code{file2}, ... The
-occurrences of the entity in the separate units of the ones given on the
-command line will also be displayed.
-
-Note that if you specify at least one file in this part, @code{gnatfind} may
-sometimes not be able to find the body of the subprograms.
-@end table
-
-At least one of 'sourcefile' or 'pattern' has to be present on
-the command line.
-
-The following switches are available:
-
-@geindex --version (gnatfind)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatfind)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -a (gnatfind)
-
-
-@table @asis
-
-@item @code{-a}
-
-If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
-the read-only files found in the library search path. Otherwise, these files
-will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
-much faster, and their output much smaller. Read-only here refers to access
-or permission status in the file system for the current user.
-@end table
-
-@geindex -aIDIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-aI@emph{DIR}}
-
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @code{gnatmake}.
-@end table
-
-@geindex -aODIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-aO@emph{DIR}}
-
-When searching for library and object files, look in directory
-DIR. The order in which library files are searched is the same as for
-@code{gnatmake}.
-@end table
-
-@geindex -nostdinc (gnatfind)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Do not look for sources in the system default directory.
-@end table
-
-@geindex -nostdlib (gnatfind)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-@end table
-
-@geindex --ext (gnatfind)
-
-
-@table @asis
-
-@item @code{--ext=@emph{extension}}
-
-Specify an alternate ali file extension. The default is @code{ali} and other
-extensions may be specified via this switch. Note that if this switch
-overrides the default, only the new extension will be considered.
-@end table
-
-@geindex --RTS (gnatfind)
-
-
-@table @asis
-
-@item @code{--RTS=@emph{rts-path}}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
-@end table
-
-@geindex -d (gnatfind)
-
-
-@table @asis
-
-@item @code{-d}
-
-If this switch is set, then @code{gnatfind} will output the parent type
-reference for each matching derived types.
-@end table
-
-@geindex -e (gnatfind)
-
-
-@table @asis
-
-@item @code{-e}
-
-By default, @code{gnatfind} accept the simple regular expression set for
-@code{pattern}. If this switch is set, then the pattern will be
-considered as full Unix-style regular expression.
-@end table
-
-@geindex -f (gnatfind)
-
-
-@table @asis
-
-@item @code{-f}
-
-If this switch is set, the output file names will be preceded by their
-directory (if the file was found in the search path). If this switch is
-not set, the directory will not be printed.
-@end table
-
-@geindex -g (gnatfind)
-
-
-@table @asis
-
-@item @code{-g}
-
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
-@end table
-
-@geindex -IDIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-I@emph{DIR}}
-
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
-
-@geindex -pFILE (gnatfind)
-
-
-@table @asis
-
-@item @code{-p@emph{FILE}}
-
-Specify a configuration file to use to list the source and object directories.
-
-If a file is specified, then the content of the source directory and object
-directory lines are added as if they had been specified respectively
-by @code{-aI} and @code{-aO}.
-
-See @ref{149,,Configuration Files for gnatxref and gnatfind} for the syntax
-of this configuration file.
-@end table
-
-@geindex -r (gnatfind)
-
-
-@table @asis
-
-@item @code{-r}
-
-By default, @code{gnatfind} will output only the information about the
-declaration, body or type completion of the entities. If this switch is
-set, the @code{gnatfind} will locate every reference to the entities in
-the files specified on the command line (or in every file in the search
-path if no file is given on the command line).
-@end table
-
-@geindex -s (gnatfind)
-
-
-@table @asis
-
-@item @code{-s}
-
-If this switch is set, then @code{gnatfind} will output the content
-of the Ada source file lines were the entity was found.
-@end table
-
-@geindex -t (gnatfind)
-
-
-@table @asis
-
-@item @code{-t}
-
-If this switch is set, then @code{gnatfind} will output the type hierarchy for
-the specified type. It act like -d option but recursively from parent
-type to parent type. When this switch is set it is not possible to
-specify more than one file.
-@end table
-
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say @code{gnatxref -ag} instead of
-@code{gnatxref -a -g}.
-
-As stated previously, @code{gnatfind} will search in every directory in the
-search path. You can force it to look only in the current directory if
-you specify @code{*} at the end of the command line.
-
-@node Configuration Files for gnatxref and gnatfind,Regular Expressions in gnatfind and gnatxref,gnatfind Switches,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs configuration-files-for-gnatxref-and-gnatfind}@anchor{149}@anchor{gnat_ugn/gnat_utility_programs id12}@anchor{14f}
-@subsection Configuration Files for @code{gnatxref} and @code{gnatfind}
-
-
-Configuration files are used by @code{gnatxref} and @code{gnatfind} to specify
-the list of source and object directories to consider. They can be
-specified via the @code{-p} switch.
-
-The following lines can be included, in any order in the file:
-
-
-@itemize *
-
-@item
-
-@table @asis
-
-@item @emph{src_dir=DIR}
-
-[default: @code{"./"}].
-Specifies a directory where to look for source files. Multiple @code{src_dir}
-lines can be specified and they will be searched in the order they
-are specified.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{obj_dir=DIR}
-
-[default: @code{"./"}].
-Specifies a directory where to look for object and library files. Multiple
-@code{obj_dir} lines can be specified, and they will be searched in the order
-they are specified
-@end table
-@end itemize
-
-Any other line will be silently ignored.
-
-@node Regular Expressions in gnatfind and gnatxref,Examples of gnatxref Usage,Configuration Files for gnatxref and gnatfind,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id13}@anchor{150}@anchor{gnat_ugn/gnat_utility_programs regular-expressions-in-gnatfind-and-gnatxref}@anchor{14d}
-@subsection Regular Expressions in @code{gnatfind} and @code{gnatxref}
-
-
-As specified in the section about @code{gnatfind}, the pattern can be a
-regular expression. Two kinds of regular expressions
-are recognized:
-
-
-@itemize *
-
-@item
-
-@table @asis
-
-@item @emph{Globbing pattern}
-
-These are the most common regular expression. They are the same as are
-generally used in a Unix shell command line, or in a DOS session.
-
-Here is a more formal grammar:
-
-@example
-regexp ::= term
-term ::= elmt -- matches elmt
-term ::= elmt elmt -- concatenation (elmt then elmt)
-term ::= * -- any string of 0 or more characters
-term ::= ? -- matches any character
-term ::= [char @{char@}] -- matches any character listed
-term ::= [char - char] -- matches any character in range
-@end example
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{Full regular expression}
-
-The second set of regular expressions is much more powerful. This is the
-type of regular expressions recognized by utilities such as @code{grep}.
-
-The following is the form of a regular expression, expressed in same BNF
-style as is found in the Ada Reference Manual:
-
-@example
-regexp ::= term @{| term@} -- alternation (term or term ...)
-
-term ::= item @{item@} -- concatenation (item then item)
-
-item ::= elmt -- match elmt
-item ::= elmt * -- zero or more elmt's
-item ::= elmt + -- one or more elmt's
-item ::= elmt ? -- matches elmt or nothing
-
-elmt ::= nschar -- matches given character
-elmt ::= [nschar @{nschar@}] -- matches any character listed
-elmt ::= [^ nschar @{nschar@}] -- matches any character not listed
-elmt ::= [char - char] -- matches chars in given range
-elmt ::= \\ char -- matches given character
-elmt ::= . -- matches any single character
-elmt ::= ( regexp ) -- parens used for grouping
-
-char ::= any character, including special characters
-nschar ::= any character except ()[].*+?^
-@end example
-
-Here are a few examples:
-
-@quotation
-
-
-@table @asis
-
-@item @code{abcde|fghi}
-
-will match any of the two strings @code{abcde} and @code{fghi},
-
-@item @code{abc*d}
-
-will match any string like @code{abd}, @code{abcd}, @code{abccd},
-@code{abcccd}, and so on,
-
-@item @code{[a-z]+}
-
-will match any string which has only lowercase characters in it (and at
-least one character.
-@end table
-@end quotation
-@end table
-@end itemize
-
-@node Examples of gnatxref Usage,Examples of gnatfind Usage,Regular Expressions in gnatfind and gnatxref,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatxref-usage}@anchor{14a}@anchor{gnat_ugn/gnat_utility_programs id14}@anchor{151}
-@subsection Examples of @code{gnatxref} Usage
-
-
-@menu
-* General Usage::
-* Using gnatxref with vi::
-
-@end menu
-
-@node General Usage,Using gnatxref with vi,,Examples of gnatxref Usage
-@anchor{gnat_ugn/gnat_utility_programs general-usage}@anchor{152}
-@subsubsection General Usage
-
-
-For the following examples, we will consider the following units:
-
-@quotation
-
-@example
-main.ads:
-1: with Bar;
-2: package Main is
-3: procedure Foo (B : in Integer);
-4: C : Integer;
-5: private
-6: D : Integer;
-7: end Main;
-
-main.adb:
-1: package body Main is
-2: procedure Foo (B : in Integer) is
-3: begin
-4: C := B;
-5: D := B;
-6: Bar.Print (B);
-7: Bar.Print (C);
-8: end Foo;
-9: end Main;
-
-bar.ads:
-1: package Bar is
-2: procedure Print (B : Integer);
-3: end bar;
-@end example
-@end quotation
-
-The first thing to do is to recompile your application (for instance, in
-that case just by doing a @code{gnatmake main}, so that GNAT generates
-the cross-referencing information.
-You can then issue any of the following commands:
-
-@quotation
-
-
-@itemize *
-
-@item
-@code{gnatxref main.adb}
-@code{gnatxref} generates cross-reference information for main.adb
-and every unit 'with'ed by main.adb.
-
-The output would be:
-
-@quotation
-
-@example
-B Type: Integer
- Decl: bar.ads 2:22
-B Type: Integer
- Decl: main.ads 3:20
- Body: main.adb 2:20
- Ref: main.adb 4:13 5:13 6:19
-Bar Type: Unit
- Decl: bar.ads 1:9
- Ref: main.adb 6:8 7:8
- main.ads 1:6
-C Type: Integer
- Decl: main.ads 4:5
- Modi: main.adb 4:8
- Ref: main.adb 7:19
-D Type: Integer
- Decl: main.ads 6:5
- Modi: main.adb 5:8
-Foo Type: Unit
- Decl: main.ads 3:15
- Body: main.adb 2:15
-Main Type: Unit
- Decl: main.ads 2:9
- Body: main.adb 1:14
-Print Type: Unit
- Decl: bar.ads 2:15
- Ref: main.adb 6:12 7:12
-@end example
-@end quotation
-
-This shows that the entity @code{Main} is declared in main.ads, line 2, column 9,
-its body is in main.adb, line 1, column 14 and is not referenced any where.
-
-The entity @code{Print} is declared in @code{bar.ads}, line 2, column 15 and it
-is referenced in @code{main.adb}, line 6 column 12 and line 7 column 12.
-
-@item
-@code{gnatxref package1.adb package2.ads}
-@code{gnatxref} will generates cross-reference information for
-@code{package1.adb}, @code{package2.ads} and any other package @code{with}ed by any
-of these.
-@end itemize
-@end quotation
-
-@node Using gnatxref with vi,,General Usage,Examples of gnatxref Usage
-@anchor{gnat_ugn/gnat_utility_programs using-gnatxref-with-vi}@anchor{153}
-@subsubsection Using @code{gnatxref} with @code{vi}
-
-
-@code{gnatxref} can generate a tags file output, which can be used
-directly from @code{vi}. Note that the standard version of @code{vi}
-will not work properly with overloaded symbols. Consider using another
-free implementation of @code{vi}, such as @code{vim}.
-
-@quotation
-
-@example
-$ gnatxref -v gnatfind.adb > tags
-@end example
-@end quotation
-
-The following command will generate the tags file for @code{gnatfind} itself
-(if the sources are in the search path!):
-
-@quotation
-
-@example
-$ gnatxref -v gnatfind.adb > tags
-@end example
-@end quotation
-
-From @code{vi}, you can then use the command @code{:tag @emph{entity}}
-(replacing @code{entity} by whatever you are looking for), and vi will
-display a new file with the corresponding declaration of entity.
-
-@node Examples of gnatfind Usage,,Examples of gnatxref Usage,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id15}@anchor{154}@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatfind-usage}@anchor{14e}
-@subsection Examples of @code{gnatfind} Usage
-
-
-
-@itemize *
-
-@item
-@code{gnatfind -f xyz:main.adb}
-Find declarations for all entities xyz referenced at least once in
-main.adb. The references are search in every library file in the search
-path.
-
-The directories will be printed as well (as the @code{-f}
-switch is set)
-
-The output will look like:
-
-@quotation
-
-@example
-directory/main.ads:106:14: xyz <= declaration
-directory/main.adb:24:10: xyz <= body
-directory/foo.ads:45:23: xyz <= declaration
-@end example
-@end quotation
-
-I.e., one of the entities xyz found in main.adb is declared at
-line 12 of main.ads (and its body is in main.adb), and another one is
-declared at line 45 of foo.ads
-
-@item
-@code{gnatfind -fs xyz:main.adb}
-This is the same command as the previous one, but @code{gnatfind} will
-display the content of the Ada source file lines.
-
-The output will look like:
-
-@example
-directory/main.ads:106:14: xyz <= declaration
- procedure xyz;
-directory/main.adb:24:10: xyz <= body
- procedure xyz is
-directory/foo.ads:45:23: xyz <= declaration
- xyz : Integer;
-@end example
-
-This can make it easier to find exactly the location your are looking
-for.
-
-@item
-@code{gnatfind -r "*x*":main.ads:123 foo.adb}
-Find references to all entities containing an x that are
-referenced on line 123 of main.ads.
-The references will be searched only in main.ads and foo.adb.
-
-@item
-@code{gnatfind main.ads:123}
-Find declarations and bodies for all entities that are referenced on
-line 123 of main.ads.
-
-This is the same as @code{gnatfind "*":main.adb:123`}
-
-@item
-@code{gnatfind mydir/main.adb:123:45}
-Find the declaration for the entity referenced at column 45 in
-line 123 of file main.adb in directory mydir. Note that it
-is usual to omit the identifier name when the column is given,
-since the column position identifies a unique reference.
-
-The column has to be the beginning of the identifier, and should not
-point to any character in the middle of the identifier.
-@end itemize
-
-@node The Ada to HTML Converter gnathtml,,The Cross-Referencing Tools gnatxref and gnatfind,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-ada-to-html-converter-gnathtml}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs id16}@anchor{155}
-@section The Ada to HTML Converter @code{gnathtml}
-
-
-@geindex gnathtml
-
-@code{gnathtml} is a Perl script that allows Ada source files to be browsed using
-standard Web browsers. For installation information, see @ref{156,,Installing gnathtml}.
-
-Ada reserved keywords are highlighted in a bold font and Ada comments in
-a blue font. Unless your program was compiled with the gcc @code{-gnatx}
-switch to suppress the generation of cross-referencing information, user
-defined variables and types will appear in a different color; you will
-be able to click on any identifier and go to its declaration.
-
-@menu
-* Invoking gnathtml::
-* Installing gnathtml::
-
-@end menu
-
-@node Invoking gnathtml,Installing gnathtml,,The Ada to HTML Converter gnathtml
-@anchor{gnat_ugn/gnat_utility_programs invoking-gnathtml}@anchor{157}@anchor{gnat_ugn/gnat_utility_programs id17}@anchor{158}
-@subsection Invoking @code{gnathtml}
-
-
-The command line is as follows:
-
-@quotation
-
-@example
-$ perl gnathtml.pl [ switches ] ada-files
-@end example
-@end quotation
-
-You can specify as many Ada files as you want. @code{gnathtml} will generate
-an html file for every ada file, and a global file called @code{index.htm}.
-This file is an index of every identifier defined in the files.
-
-The following switches are available:
-
-@geindex -83 (gnathtml)
-
-
-@table @asis
-
-@item @code{83}
-
-Only the Ada 83 subset of keywords will be highlighted.
-@end table
-
-@geindex -cc (gnathtml)
-
-
-@table @asis
-
-@item @code{cc @emph{color}}
-
-This option allows you to change the color used for comments. The default
-value is green. The color argument can be any name accepted by html.
-@end table
-
-@geindex -d (gnathtml)
-
-
-@table @asis
-
-@item @code{d}
-
-If the Ada files depend on some other files (for instance through
-@code{with} clauses, the latter files will also be converted to html.
-Only the files in the user project will be converted to html, not the files
-in the run-time library itself.
-@end table
-
-@geindex -D (gnathtml)
-
-
-@table @asis
-
-@item @code{D}
-
-This command is the same as @code{-d} above, but @code{gnathtml} will
-also look for files in the run-time library, and generate html files for them.
-@end table
-
-@geindex -ext (gnathtml)
-
-
-@table @asis
-
-@item @code{ext @emph{extension}}
-
-This option allows you to change the extension of the generated HTML files.
-If you do not specify an extension, it will default to @code{htm}.
-@end table
-
-@geindex -f (gnathtml)
-
-
-@table @asis
-
-@item @code{f}
-
-By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
-@code{-f} on the command line, then links will be generated for local
-entities too.
-@end table
-
-@geindex -l (gnathtml)
-
-
-@table @asis
-
-@item @code{l @emph{number}}
-
-If this switch is provided and @code{number} is not 0, then
-@code{gnathtml} will number the html files every @code{number} line.
-@end table
-
-@geindex -I (gnathtml)
-
-
-@table @asis
-
-@item @code{I @emph{dir}}
-
-Specify a directory to search for library files (@code{.ALI} files) and
-source files. You can provide several -I switches on the command line,
-and the directories will be parsed in the order of the command line.
-@end table
-
-@geindex -o (gnathtml)
-
-
-@table @asis
-
-@item @code{o @emph{dir}}
-
-Specify the output directory for html files. By default, gnathtml will
-saved the generated html files in a subdirectory named @code{html/}.
-@end table
-
-@geindex -p (gnathtml)
-
-
-@table @asis
-
-@item @code{p @emph{file}}
-
-If you are using Emacs and the most recent Emacs Ada mode, which provides
-a full Integrated Development Environment for compiling, checking,
-running and debugging applications, you may use @code{.gpr} files
-to give the directories where Emacs can find sources and object files.
-
-Using this switch, you can tell gnathtml to use these files.
-This allows you to get an html version of your application, even if it
-is spread over multiple directories.
-@end table
-
-@geindex -sc (gnathtml)
-
-
-@table @asis
-
-@item @code{sc @emph{color}}
-
-This switch allows you to change the color used for symbol
-definitions.
-The default value is red. The color argument can be any name accepted by html.
-@end table
-
-@geindex -t (gnathtml)
-
-
-@table @asis
-
-@item @code{t @emph{file}}
-
-This switch provides the name of a file. This file contains a list of
-file names to be converted, and the effect is exactly as though they had
-appeared explicitly on the command line. This
-is the recommended way to work around the command line length limit on some
-systems.
-@end table
-
-@node Installing gnathtml,,Invoking gnathtml,The Ada to HTML Converter gnathtml
-@anchor{gnat_ugn/gnat_utility_programs installing-gnathtml}@anchor{156}@anchor{gnat_ugn/gnat_utility_programs id18}@anchor{159}
-@subsection Installing @code{gnathtml}
-
-
-@code{Perl} needs to be installed on your machine to run this script.
-@code{Perl} is freely available for almost every architecture and
-operating system via the Internet.
-
-On Unix systems, you may want to modify the first line of the script
-@code{gnathtml}, to explicitly specify where Perl
-is located. The syntax of this line is:
-
-@quotation
-
-@example
-#!full_path_name_to_perl
-@end example
-@end quotation
-
-Alternatively, you may run the script using the following command line:
-
-@quotation
-
-@example
-$ perl gnathtml.pl [ switches ] files
-@end example
-@end quotation
-
-@c -- +---------------------------------------------------------------------+
-
-@c -- | The following sections are present only in the PRO and GPL editions |
-
-@c -- +---------------------------------------------------------------------+
-
-
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
-@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{15b}
+@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145}
@chapter GNAT and Program Execution
@itemize *
@item
-@ref{15c,,Running and Debugging Ada Programs}
+@ref{146,,Running and Debugging Ada Programs}
@item
-@ref{15d,,Profiling}
+@ref{147,,Profiling}
@item
-@ref{15e,,Improving Performance}
+@ref{148,,Improving Performance}
@item
-@ref{15f,,Overflow Check Handling in GNAT}
+@ref{149,,Overflow Check Handling in GNAT}
@item
-@ref{160,,Performing Dimensionality Analysis in GNAT}
+@ref{14a,,Performing Dimensionality Analysis in GNAT}
@item
-@ref{161,,Stack Related Facilities}
+@ref{14b,,Stack Related Facilities}
@item
-@ref{162,,Memory Management Issues}
+@ref{14c,,Memory Management Issues}
@end itemize
@menu
@end menu
@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{163}
+@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{146}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{14d}
@section Running and Debugging Ada Programs
@end menu
@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{165}
+@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14f}
@subsection The GNAT Debugger GDB
variables, and more generally to report on the state of execution.
@node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{167}
+@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151}
@subsection Running GDB
describes some of the additional commands that can be given to @code{GDB}.
@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{169}
+@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{153}
@subsection Introduction to GDB Commands
(for example, c for continue, bt for backtrace).
@node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{16b}
+@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155}
@subsection Using Ada Expressions
For details on the supported Ada syntax, see @cite{Debugging with GDB}.
@node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{16d}
+@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{157}
@subsection Calling User-Defined Subprograms
the elements in the desired format.
@node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{16f}
+@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{159}
@subsection Using the @emph{next} Command in a Function
that was stepped through.
@node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{170}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{171}
+@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15b}
@subsection Stopping When Ada Exceptions Are Raised
@geindex Tasks (in gdb)
@node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{172}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{173}
+@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d}
@subsection Ada Tasks
@geindex Generics
@node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{174}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{175}
+@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f}
@subsection Debugging Generic Units
@geindex Remote Debugging with gdbserver
@node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{176}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{177}
+@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{161}
@subsection Remote Debugging with gdbserver
@geindex Abnormal Termination or Failure to Terminate
@node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{178}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{179}
+@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163}
@subsection GNAT Abnormal Termination or Failure to Terminate
@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
front-end of GNAT, and can be run independently (normally it is just
called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
-would on a C program (but @ref{164,,The GNAT Debugger GDB} for caveats). The
+would on a C program (but @ref{14e,,The GNAT Debugger GDB} for caveats). The
@code{where} command is the first line of attack; the variable
@code{lineno} (seen by @code{print lineno}), used by the second phase of
@code{gnat1} and by the @code{gcc} backend, indicates the source line at
@end itemize
@node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{17a}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{17b}
+@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{165}
@subsection Naming Conventions for GNAT Source Files
@end itemize
@node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{17d}
+@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{167}
@subsection Getting Internal Debugging Information
@geindex stack unwinding
@node Stack Traceback,Pretty-Printers for the GNAT runtime,Getting Internal Debugging Information,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{17f}
+@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{169}
@subsection Stack Traceback
@end menu
@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{181}
+@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16b}
@subsubsection Non-Symbolic Traceback
@geindex symbolic
@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{183}
+@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d}
@subsubsection Symbolic Traceback
program.
@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{184}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{185}
+@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{16f}
@subsection Pretty-Printers for the GNAT runtime
@geindex Profiling
@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{15d}@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{186}
+@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147}@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170}
@section Profiling
@end menu
@node Profiling an Ada Program with gprof,,,Profiling
-@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{187}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{188}
+@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{171}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{172}
@subsection Profiling an Ada Program with gprof
@end menu
@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{189}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{18a}
+@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{174}
@subsubsection Compilation for profiling
gnatmake switch to force full recompilation.
@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{18b}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{18c}
+@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{176}
@subsubsection Program execution
already exists, it will be overwritten.
@node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{18e}
+@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{178}
@subsubsection Running gprof
@end table
@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{18f}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{190}
+@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{179}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{17a}
@subsubsection Interpretation of profiling results
spent in each of those callers/called subprograms.
@node Improving Performance,Overflow Check Handling in GNAT,Profiling,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{15e}
+@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{148}
@section Improving Performance
@end menu
@node Performance Considerations,Text_IO Suggestions,,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{192}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{193}
+@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17d}
@subsection Performance Considerations
@end menu
@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{194}@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{195}
+@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17f}
@subsubsection Controlling Run-Time Checks
checks) in the program source.
@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{196}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{197}
+@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181}
@subsubsection Use of Restrictions
possibility of an immediate abort at any point.
@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{198}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
+@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
@subsubsection Optimization Levels
See further discussion of this point in @ref{100,,Inlining of Subprograms}.
@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{19a}
+@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184}
@subsubsection Debugging Optimized Code
which removes both debugging information and global symbols.
@node Inlining of Subprograms,Floating_Point_Operations,Debugging Optimized Code,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100}
+@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100}
@subsubsection Inlining of Subprograms
improves performance for your program.
@node Floating_Point_Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{19c}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{19d}
+@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187}
@subsubsection Floating_Point_Operations
switches.
@node Vectorization of loops,Other Optimization Switches,Floating_Point_Operations,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{19f}
+@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{189}
@subsubsection Vectorization of loops
omit the non-vectorized version of the loop as well as the run-time test.
@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{1a1}
+@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{18b}
@subsubsection Other Optimization Switches
chapter of @cite{Using the GNU Compiler Collection (GCC)}.
@node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{1a2}
+@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{18c}
@subsubsection Optimization and Strict Aliasing
particularly if you are getting the warnings described above.
@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{1a4}
+@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{18e}
@subsubsection Aliased Variables and Optimization
that is, it will produce the expected results.
@node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{1a6}
+@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190}
@subsubsection Atomic Variables and Optimization
useful to disable it.
@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{1a8}
+@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{192}
@subsubsection Passive Task Optimization
to be modified, only the task definition itself.
@node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{1aa}
+@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{194}
@subsection @code{Text_IO} Suggestions
be buffered using @code{Interfaces.C_Streams.setvbuf}.
@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{1ab}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{1ac}
+@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{195}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{196}
@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
@end menu
@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{1ae}
+@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{198}
@subsubsection About unused subprogram/data elimination
In both cases GNU binutils version 2.16 or later are required to enable it.
@node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{1b0}
+@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{19a}
@subsubsection Compilation options
and data of the GNAT library from your executable.
@node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{1b1}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{1b2}
+@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c}
@subsubsection Example of unused subprogram/data elimination
@geindex Checks (overflow)
@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{15f}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{1b3}
+@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d}
@section Overflow Check Handling in GNAT
@end menu
@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{1b4}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{1b5}
+@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19f}
@subsection Background
would prefer this precondition to be considered True at run time).
@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1b6}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1b7}
+@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1}
@subsection Management of Overflows in GNAT
range checks).
@node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1b8}
+@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1a2}
@subsection Specifying the Desired Mode
type (@code{STRICT} mode).
@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1b9}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1ba}
+@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a4}
@subsection Default Settings
intermediate results.
@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1bb}@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1bc}
+@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a6}
@subsection Implementation Notes
platforms).
@node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1bd}@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{160}
+@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{14a}
@section Performing Dimensionality Analysis in GNAT
dimension vector for the formal parameter).
@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1be}@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{161}
+@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8}@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b}
@section Stack Related Facilities
@end menu
@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1bf}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5}
+@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5}
@subsection Stack Overflow Checking
operating system documentation.
@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1c0}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
+@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
@subsection Static Stack Usage Analysis
bytes. The wording is in keeping with the qualifier documented above.
@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1c1}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{113}
+@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{113}
@subsection Dynamic Stack Usage Analysis
stack-usage reports at run time. See its body for the details.
@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1c2}
+@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac}
@section Memory Management Issues
@end menu
@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1c3}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1c4}
+@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ae}
@subsection Some Useful Memory Pools
@end quotation
@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1c5}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1c6}
+@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1b0}
@subsection The GNAT Debug Pool Facility
@c -- E.g. Ada |nbsp| 95
@node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top
-@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1c8}
+@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}
@chapter Platform-Specific Information
@end menu
@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id2}@anchor{1c9}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1ca}
+@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4}
@section Run-Time Libraries
@end menu
@node Summary of Run-Time Configurations,,,Run-Time Libraries
-@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1cb}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1cc}
+@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b6}
@subsection Summary of Run-Time Configurations
@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1cd}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1ce}
+@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b8}
@section Specifying a Run-Time Library
Selecting another run-time library temporarily can be
achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1cf}
+@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1b9}
@geindex SCHED_FIFO scheduling policy
@geindex SCHED_RR scheduling policy
@end menu
@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id5}@anchor{1d0}
+@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba}
@subsection Choosing the Scheduling Policy
@geindex GNU/Linux
@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id6}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1d2}
+@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bc}
@section GNU/Linux Topics
@end menu
@node Required Packages on GNU/Linux,,,GNU/Linux Topics
-@anchor{gnat_ugn/platform_specific_information id7}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1d4}
+@anchor{gnat_ugn/platform_specific_information id7}@anchor{1bd}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1be}
@subsection Required Packages on GNU/Linux
@geindex Windows
@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1d5}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1d6}
+@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0}
@section Microsoft Windows Topics
@end menu
@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1d8}
+@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c2}
@subsection Using GNAT on Windows
@end itemize
@node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id10}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1da}
+@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c4}
@subsection Using a network installation of GNAT
serious performance penalty.
@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id11}@anchor{1db}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1dc}
+@anchor{gnat_ugn/platform_specific_information id11}@anchor{1c5}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1c6}
@subsection CONSOLE and WINDOWS subsystems
@end quotation
@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id12}@anchor{1dd}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1de}
+@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1c8}
@subsection Temporary Files
directories.
@node Disabling Command Line Argument Expansion,Windows Socket Timeouts,Temporary Files,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1df}
+@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1c9}
@subsection Disabling Command Line Argument Expansion
@end example
@node Windows Socket Timeouts,Mixed-Language Programming on Windows,Disabling Command Line Argument Expansion,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1e0}
+@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1ca}
@subsection Windows Socket Timeouts
Check_Selector should be added before any socket read or write operations.
@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Windows Socket Timeouts,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id13}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1e2}
+@anchor{gnat_ugn/platform_specific_information id13}@anchor{1cb}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1cc}
@subsection Mixed-Language Programming on Windows
Encapsulate your C++ code in a DLL to be linked with your Ada
application. In this case, use the Microsoft or whatever environment to
build the DLL and use GNAT to build your executable
-(@ref{1e3,,Using DLLs with GNAT}).
+(@ref{1cd,,Using DLLs with GNAT}).
@item
Or you can encapsulate your Ada code in a DLL to be linked with the
other part of your application. In this case, use GNAT to build the DLL
-(@ref{1e4,,Building DLLs with GNAT Project files}) and use the Microsoft
+(@ref{1ce,,Building DLLs with GNAT Project files}) and use the Microsoft
or whatever environment to build your executable.
@end itemize
@end menu
@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1e6}
+@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1cf}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1d0}
@subsubsection Windows Calling Conventions
@end menu
@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1e7}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1e8}
+@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d2}
@subsubsection @code{C} Calling Convention
When importing a variable defined in C, you should always use the @code{C}
calling convention unless the object containing the variable is part of a
DLL (in which case you should use the @code{Stdcall} calling
-convention, @ref{1e9,,Stdcall Calling Convention}).
+convention, @ref{1d3,,Stdcall Calling Convention}).
@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1e9}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1ea}
+@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4}
@subsubsection @code{Stdcall} Calling Convention
will be handled as a @code{C} calling convention on non-Windows platforms.
@node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1eb}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1ec}
+@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d5}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}
@subsubsection @code{Win32} Calling Convention
@code{Stdcall} calling convention described above.
@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id18}@anchor{1ed}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1ee}
+@anchor{gnat_ugn/platform_specific_information id18}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d8}
@subsubsection @code{DLL} Calling Convention
@code{Stdcall} calling convention described above.
@node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id19}@anchor{1ef}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1f0}
+@anchor{gnat_ugn/platform_specific_information id19}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1da}
@subsubsection Introduction to Dynamic Link Libraries (DLLs)
Unix shared libraries, is the fact that on most Unix systems all public
routines are exported by default in a Unix shared library, while under
Windows it is possible (but not required) to list exported routines in
-a definition file (see @ref{1f1,,The Definition File}).
+a definition file (see @ref{1db,,The Definition File}).
@node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id20}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1e3}
+@anchor{gnat_ugn/platform_specific_information id20}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cd}
@subsubsection Using DLLs with GNAT
@end menu
@node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information id21}@anchor{1f3}@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1f4}
+@anchor{gnat_ugn/platform_specific_information id21}@anchor{1dd}@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1de}
@subsubsection Creating an Ada Spec for the DLL Services
@end quotation
@node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information id22}@anchor{1f5}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1f6}
+@anchor{gnat_ugn/platform_specific_information id22}@anchor{1df}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1e0}
@subsubsection Creating an Import Library
DLL. Otherwise read on.
@geindex Definition file
-@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1f1}
+@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1db}
@subsubheading The Definition File
@end table
Note that you must specify the correct suffix (@code{@@@emph{nn}})
-(see @ref{1e5,,Windows Calling Conventions}) for a Stdcall
+(see @ref{1cf,,Windows Calling Conventions}) for a Stdcall
calling convention function in the exported symbols list.
There can actually be other sections in a definition file, but these
sections are not relevant to the discussion at hand.
-@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1f7}
+@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1e1}
@subsubheading Creating a Definition File Automatically
You can automatically create the definition file @code{API.def}
-(see @ref{1f1,,The Definition File}) from a DLL.
+(see @ref{1db,,The Definition File}) from a DLL.
For that use the @code{dlltool} program as follows:
@quotation
@end example
Note that if some routines in the DLL have the @code{Stdcall} convention
-(@ref{1e5,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
+(@ref{1cf,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
suffix then you'll have to edit @code{api.def} to add it, and specify
@code{-k} to @code{gnatdll} when creating the import library.
definition file and add the right suffix.
@end itemize
@end quotation
-@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1f8}
+@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e2}
@subsubheading GNAT-Style Import Library
To create a static import library from @code{API.dll} with the GNAT tools
you should create the .def file, then use @code{gnatdll} tool
-(see @ref{1f9,,Using gnatdll}) as follows:
+(see @ref{1e3,,Using gnatdll}) as follows:
@quotation
be @code{libxyz.a}. Note that in the previous example option
@code{-e} could have been removed because the name of the definition
file (before the @code{.def} suffix) is the same as the name of the
-DLL (@ref{1f9,,Using gnatdll} for more information about @code{gnatdll}).
+DLL (@ref{1e3,,Using gnatdll} for more information about @code{gnatdll}).
@end quotation
-@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1fa}
+@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e4}
@subsubheading Microsoft-Style Import Library
A Microsoft import library is needed only if you plan to make an
Ada DLL available to applications developed with Microsoft
-tools (@ref{1e2,,Mixed-Language Programming on Windows}).
+tools (@ref{1cc,,Mixed-Language Programming on Windows}).
To create a Microsoft-style import library for @code{API.dll} you
should create the .def file, then build the actual import library using
@end quotation
@node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id23}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1e4}
+@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1ce}
@subsubsection Building DLLs with GNAT Project files
of shared libraries, so it is not possible to have library level tasks in SALs.
@node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{1fc}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1fd}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{1e6}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7}
@subsubsection Building DLLs with GNAT
It is important to note that in this case all symbols found in the
object files are automatically exported. It is possible to restrict
the set of symbols to export by passing to @code{gcc} a definition
-file (see @ref{1f1,,The Definition File}).
+file (see @ref{1db,,The Definition File}).
For example:
@example
@end quotation
@node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{1fe}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1ff}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9}
@subsubsection Building DLLs with gnatdll
@geindex building
Note that it is preferred to use GNAT Project files
-(@ref{1e4,,Building DLLs with GNAT Project files}) or the built-in GNAT
-DLL support (@ref{1fc,,Building DLLs with GNAT}) or to build DLLs.
+(@ref{1ce,,Building DLLs with GNAT Project files}) or the built-in GNAT
+DLL support (@ref{1e6,,Building DLLs with GNAT}) or to build DLLs.
This section explains how to build DLLs containing Ada code using
@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
You need to mark each Ada entity exported by the DLL with a @code{C} or
@code{Stdcall} calling convention to avoid any Ada name mangling for the
entities exported by the DLL
-(see @ref{200,,Exporting Ada Entities}). You can
+(see @ref{1ea,,Exporting Ada Entities}). You can
skip this step if you plan to use the Ada DLL only from Ada applications.
@item
Your Ada code must export an initialization routine which calls the routine
@code{adainit} generated by @code{gnatbind} to perform the elaboration of
-the Ada code in the DLL (@ref{201,,Ada DLLs and Elaboration}). The initialization
+the Ada code in the DLL (@ref{1eb,,Ada DLLs and Elaboration}). The initialization
routine exported by the Ada DLL must be invoked by the clients of the DLL
to initialize the DLL.
@item
When useful, the DLL should also export a finalization routine which calls
routine @code{adafinal} generated by @code{gnatbind} to perform the
-finalization of the Ada code in the DLL (@ref{202,,Ada DLLs and Finalization}).
+finalization of the Ada code in the DLL (@ref{1ec,,Ada DLLs and Finalization}).
The finalization routine exported by the Ada DLL must be invoked by the
clients of the DLL when the DLL services are no further needed.
@item
You must provide a definition file listing the exported entities
-(@ref{1f1,,The Definition File}).
+(@ref{1db,,The Definition File}).
@item
Finally you must use @code{gnatdll} to produce the DLL and the import
-library (@ref{1f9,,Using gnatdll}).
+library (@ref{1e3,,Using gnatdll}).
@end itemize
Note that a relocatable DLL stripped using the @code{strip}
@end menu
@node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{203}
+@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{1ed}
@subsubsection Limitations When Using Ada DLLs from Ada
Windows object handles, etc.
@node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{200}@anchor{gnat_ugn/platform_specific_information id26}@anchor{204}
+@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1ee}
@subsubsection Exporting Ada Entities
Note that if you do not export the Ada entities with a @code{C} or
@code{Stdcall} convention you will have to provide the mangled Ada names
in the definition file of the Ada DLL
-(@ref{205,,Creating the Definition File}).
+(@ref{1ef,,Creating the Definition File}).
@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{201}@anchor{gnat_ugn/platform_specific_information id27}@anchor{206}
+@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{1eb}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0}
@subsubsection Ada DLLs and Elaboration
(@ref{a0,,Binding with Non-Ada Main Programs}). See the body of
@code{Initialize_Api} for an example. Note that the GNAT binder is
automatically invoked during the DLL build process by the @code{gnatdll}
-tool (@ref{1f9,,Using gnatdll}).
+tool (@ref{1e3,,Using gnatdll}).
When a DLL is loaded, Windows systematically invokes a routine called
@code{DllMain}. It would therefore be possible to call @code{adainit}
newly created task to complete its initialization.
@node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id28}@anchor{207}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{202}
+@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f1}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{1ec}
@subsubsection Ada DLLs and Finalization
See the body of @code{Finalize_Api} for an
example. As already pointed out the GNAT binder is automatically invoked
during the DLL build process by the @code{gnatdll} tool
-(@ref{1f9,,Using gnatdll}).
+(@ref{1e3,,Using gnatdll}).
@node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id29}@anchor{208}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{209}
+@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{1f3}
@subsubsection Creating a Spec for Ada DLLs
@end menu
@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{205}@anchor{gnat_ugn/platform_specific_information id30}@anchor{20a}
+@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{1ef}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f4}
@subsubsection Creating the Definition File
@end quotation
@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id31}@anchor{20b}
+@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f5}
@subsubsection Using @code{gnatdll}
is loaded into memory.
@item
-@code{gnatdll} uses @code{dlltool} (see @ref{20c,,Using dlltool}) to build the
+@code{gnatdll} uses @code{dlltool} (see @ref{1f6,,Using dlltool}) to build the
export table (@code{api.exp}). The export table contains the relocation
information in a form which can be used during the final link to ensure
that the Windows loader is able to place the DLL anywhere in memory.
$ gnatlink api api.exp -o api.dll -mdll
@end example
@end itemize
-@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{20c}
+@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f6}
@subsubheading Using @code{dlltool}
@item @code{-k}
Kill @code{@@@emph{nn}} from exported names
-(@ref{1e5,,Windows Calling Conventions}
+(@ref{1cf,,Windows Calling Conventions}
for a discussion about @code{Stdcall}-style symbols.
@end table
@end table
@node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{20d}@anchor{gnat_ugn/platform_specific_information id32}@anchor{20e}
+@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f8}
@subsubsection GNAT and Windows Resources
@end menu
@node Building Resources,Compiling Resources,,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{20f}@anchor{gnat_ugn/platform_specific_information id33}@anchor{210}
+@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa}
@subsubsection Building Resources
Microsoft documentation.
@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{211}@anchor{gnat_ugn/platform_specific_information id34}@anchor{212}
+@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc}
@subsubsection Compiling Resources
@end quotation
@node Using Resources,,Compiling Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{213}@anchor{gnat_ugn/platform_specific_information id35}@anchor{214}
+@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe}
@subsubsection Using Resources
@end quotation
@node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{215}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{216}
+@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{200}
@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
@item
Produce a .def file for the symbols you need to interface with, either by
hand or automatically with possibly some manual adjustments
-(see @ref{1f7,,Creating Definition File Automatically}):
+(see @ref{1e1,,Creating Definition File Automatically}):
@end enumerate
@quotation
Make sure that MSVS command-line tools are accessible on the path.
@item
-Create the Microsoft-style import library (see @ref{1fa,,MSVS-Style Import Library}):
+Create the Microsoft-style import library (see @ref{1e4,,MSVS-Style Import Library}):
@end enumerate
@quotation
@end enumerate
@node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id36}@anchor{217}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{218}
+@anchor{gnat_ugn/platform_specific_information id36}@anchor{201}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{202}
@subsubsection Debugging a DLL
@end menu
@node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information id37}@anchor{219}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{21a}
+@anchor{gnat_ugn/platform_specific_information id37}@anchor{203}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{204}
@subsubsection Program and DLL Both Built with GCC/GNAT
@code{ada_main} and that in the DLL there is an entry point named
@code{ada_dll}.
-The DLL (@ref{1f0,,Introduction to Dynamic Link Libraries (DLLs)}) and
+The DLL (@ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) and
program must have been built with the debugging information (see GNAT -g
switch). Here are the step-by-step instructions for debugging it:
At this stage a breakpoint is set inside the DLL. From there on
you can use the standard approach to debug the whole program
-(@ref{163,,Running and Debugging Ada Programs}).
+(@ref{14d,,Running and Debugging Ada Programs}).
@node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{21b}@anchor{gnat_ugn/platform_specific_information id38}@anchor{21c}
+@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{205}@anchor{gnat_ugn/platform_specific_information id38}@anchor{206}
@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
DLL named @code{test.dll} containing an Ada entry point named
@code{ada_dll}.
-The DLL (see @ref{1f0,,Introduction to Dynamic Link Libraries (DLLs)}) must have
+The DLL (see @ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) must have
been built with debugging information (see the GNAT @code{-g} option).
@subsubheading Debugging the DLL Directly
This will run the program until it reaches the breakpoint that has been
set. From that point you can use the standard way to debug a program
-as described in (@ref{163,,Running and Debugging Ada Programs}).
+as described in (@ref{14d,,Running and Debugging Ada Programs}).
@end itemize
It is also possible to debug the DLL by attaching to a running process.
This last step will resume the process execution, and stop at
the breakpoint we have set. From there you can use the standard
approach to debug a program as described in
-@ref{163,,Running and Debugging Ada Programs}.
+@ref{14d,,Running and Debugging Ada Programs}.
@node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}@anchor{gnat_ugn/platform_specific_information id39}@anchor{21d}
+@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}@anchor{gnat_ugn/platform_specific_information id39}@anchor{207}
@subsubsection Setting Stack Size from @code{gnatlink}
@end itemize
@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}@anchor{gnat_ugn/platform_specific_information id40}@anchor{21e}
+@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}@anchor{gnat_ugn/platform_specific_information id40}@anchor{208}
@subsubsection Setting Heap Size from @code{gnatlink}
@end itemize
@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{21f}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{220}
+@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{209}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{20a}
@subsection Windows Specific Add-Ons
@end menu
@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{221}@anchor{gnat_ugn/platform_specific_information id41}@anchor{222}
+@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20b}@anchor{gnat_ugn/platform_specific_information id41}@anchor{20c}
@subsubsection Win32Ada
@end quotation
@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id42}@anchor{223}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{224}
+@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{20e}
@subsubsection wPOSIX
@end quotation
@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{225}@anchor{gnat_ugn/platform_specific_information id43}@anchor{226}
+@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{20f}@anchor{gnat_ugn/platform_specific_information id43}@anchor{210}
@section Mac OS Topics
@end menu
@node Codesigning the Debugger,,,Mac OS Topics
-@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{227}
+@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{211}
@subsection Codesigning the Debugger
in the Unix group @code{_developer}.
@node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top
-@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{228}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{229}
+@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{212}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{213}
@chapter Example of Binder Output File
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{22b}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{214}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{215}
@chapter Elaboration Order Handling in GNAT
@end menu
@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{22d}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{217}
@section Elaboration Code
@end itemize
@node Elaboration Order,Checking the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{22f}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{219}
@section Elaboration Order
respect to control and data flow.
@node Checking the Elaboration Order,Controlling the Elaboration Order in Ada,Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{231}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21b}
@section Checking the Elaboration Order
@end itemize
@node Controlling the Elaboration Order in Ada,Controlling the Elaboration Order in GNAT,Checking the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{232}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{233}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21d}
@section Controlling the Elaboration Order in Ada
orders exist) even if maintenance changes the bodies of targets.
@node Controlling the Elaboration Order in GNAT,Mixing Elaboration Models,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{234}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{235}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{21f}
@section Controlling the Elaboration Order in GNAT
may not diagnose certain elaboration issues or install run-time checks.
@node Mixing Elaboration Models,ABE Diagnostics,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{236}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{237}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{221}
@section Mixing Elaboration Models
The warnings can be suppressed by binder switch @code{-ws}.
@node ABE Diagnostics,SPARK Diagnostics,Mixing Elaboration Models,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{238}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{239}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{223}
@section ABE Diagnostics
elaborated at that point.
@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{23a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{23b}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{225}
@section SPARK Diagnostics
@end quotation
@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{23c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{23d}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{227}
@section Elaboration Circularities
@end itemize
@node Resolving Elaboration Circularities,Elaboration-related Compiler Switches,Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{23e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{23f}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{229}
@section Resolving Elaboration Circularities
@end itemize
@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{240}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{241}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{22b}
@section Elaboration-related Compiler Switches
@end table
@node Summary of Procedures for Elaboration Control,Inspecting the Chosen Elaboration Order,Elaboration-related Compiler Switches,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{242}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{243}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22d}
@section Summary of Procedures for Elaboration Control
@end itemize
@node Inspecting the Chosen Elaboration Order,,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{244}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{245}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{22f}
@section Inspecting the Chosen Elaboration Order
@end quotation
@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top
-@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{246}@anchor{gnat_ugn/inline_assembler id1}@anchor{247}
+@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{230}@anchor{gnat_ugn/inline_assembler id1}@anchor{231}
@chapter Inline Assembler
@end menu
@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id2}@anchor{248}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{249}
+@anchor{gnat_ugn/inline_assembler id2}@anchor{232}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{233}
@section Basic Assembler Syntax
@node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler
-@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{24a}@anchor{gnat_ugn/inline_assembler id3}@anchor{24b}
+@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{234}@anchor{gnat_ugn/inline_assembler id3}@anchor{235}
@section A Simple Example of Inline Assembler
@code{nothing.out}.
@node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id4}@anchor{24c}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{24d}
+@anchor{gnat_ugn/inline_assembler id4}@anchor{236}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{237}
@section Output Variables in Inline Assembler
@end quotation
@node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id5}@anchor{24e}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{24f}
+@anchor{gnat_ugn/inline_assembler id5}@anchor{238}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{239}
@section Input Variables in Inline Assembler
@end quotation
@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id6}@anchor{250}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{251}
+@anchor{gnat_ugn/inline_assembler id6}@anchor{23a}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23b}
@section Inlining Inline Assembler Code
thus saving the overhead of stack frame setup and an out-of-line call.
@node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler
-@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{252}@anchor{gnat_ugn/inline_assembler id7}@anchor{253}
+@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23c}@anchor{gnat_ugn/inline_assembler id7}@anchor{23d}
@section Other @code{Asm} Functionality
@end menu
@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{254}@anchor{gnat_ugn/inline_assembler id8}@anchor{255}
+@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{23e}@anchor{gnat_ugn/inline_assembler id8}@anchor{23f}
@subsection The @code{Clobber} Parameter
@end itemize
@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{256}@anchor{gnat_ugn/inline_assembler id9}@anchor{257}
+@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{240}@anchor{gnat_ugn/inline_assembler id9}@anchor{241}
@subsection The @code{Volatile} Parameter
problems.
@node GNU Free Documentation License,Index,Inline Assembler,Top
-@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{258}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{259}
+@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{242}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{243}
@chapter GNU Free Documentation License
projects / gcc.git / commitdiff