From: Martin Liska Date: Mon, 28 Jun 2021 11:53:49 +0000 (+0200) Subject: sphinx: ada: port to Sphinx X-Git-Tag: basepoints/gcc-14~3373 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0a543515957ff47feba739e6f71062fb2fb99125;p=thirdparty%2Fgcc.git sphinx: ada: port to Sphinx gcc/ada/ChangeLog: * doc/gnat-style.rst: Moved to... * doc/gnat-style/index.rst: ...here. * doc/gnat_rm.rst: Moved to... * doc/gnat_rm/index.rst: ...here. * doc/gnat_ugn.rst: Moved to... * doc/gnat_ugn/index.rst: ...here. * doc/share/latex_elements.py: Moved to... * doc/share/ada_latex_elements.py: ...here. * gcc-interface/Make-lang.in: * doc/Makefile: Removed. * doc/share/conf.py: Removed. * doc/share/gnu_free_documentation_license.rst: Removed. * gnat-style.texi: Removed. * gnat_rm.texi: Removed. * gnat_ugn.texi: Removed. * doc/gnat-style/conf.py: New file. * doc/gnat-style/gnu_free_documentation_license.rst: New file. * doc/gnat_rm/conf.py: New file. * doc/gnat_rm/gnu_free_documentation_license.rst: New file. * doc/gnat_ugn/conf.py: New file. * doc/gnat_ugn/gnu_free_documentation_license.rst: New file. * doc/share/adabaseconf.py: New file. * doc/gnat_rm/security_hardening_features.rst: Add role. * doc/gnat_ugn/platform_specific_information.rst: Remove duplicate definition of |nbsp|. --- diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile deleted file mode 100644 index 4adfd368cc8d..000000000000 --- a/gcc/ada/doc/Makefile +++ /dev/null @@ -1,87 +0,0 @@ -# Makefile for Sphinx documentation - -# You can set these variables from the command line. -SPHINXOPTS = -W -SPHINXBUILD = DOC_NAME=$* sphinx-build -PAPER = -BUILDDIR = build -SOURCEDIR = . - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \ - -c $(SOURCEDIR)/share \ - -d $(BUILDDIR)/$*/doctrees \ - $(SOURCEDIR) -DOC_LIST=gnat_rm gnat_ugn gnat-style -FMT_LIST=html pdf txt info - -.PHONY: help clean - -help: - @echo "Please use \`make ' where is one of" - @echo " DOC_NAME.html to make standalone HTML files" - @echo " DOC_NAME.pdf to make LaTeX files and run them through pdflatex" - @echo " DOC_NAME.txt to make text files" - @echo " DOC_NAME.info to make info files" - @echo " DOC_NAME.texinfo to make Texinfo files" - @echo " DOC_NAME.all to build DOC_NAME for all previous formats" - @echo " all to build all documentations in all formats" - @echo " html-all same as previous rule but only for HTML format" - @echo " pdf-all same as previous rule but only for PDF format" - @echo " txt-all same as previous rule but only for text format" - @echo " info-all same as previous rule but only for info format" - @echo " texinfo-all same as previous rule but only for texinfo format" - @echo "" - @echo "DOC_NAME should be a documentation name in the following list:" - @echo " $(DOC_LIST)" - @echo "" - @echo "source and location can be overridden using SOURCEDIR and BUILDDIR variables" - -clean: - -rm -rf $(BUILDDIR) - -.PHONY: mk_empty_dirs -mk_empty_dirs: - mkdir -p share/_static - -%.html: mk_empty_dirs - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$*/html - -%.pdf: mk_empty_dirs - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/$*/pdf - $(MAKE) -C $(BUILDDIR)/$*/pdf all-pdf LATEXOPTS="-interaction=nonstopmode" - -%.txt: mk_empty_dirs - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/txt - $(MAKE) -C $(BUILDDIR)/$*/txt plaintext - -%.info: mk_empty_dirs - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/info - $(MAKE) -C $(BUILDDIR)/$*/info info - -%.texinfo: mk_empty_dirs - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/texinfo - sed -e 's/^@dircategory/@dircategory GNU Ada Tools/g' < $(BUILDDIR)/$*/texinfo/$*.texi > $(BUILDDIR)/../../$*.texi - -.PHONY: html-all -html-all: $(foreach doc, $(DOC_LIST), $(doc).html) - -.PHONY: pdf-all -pdf-all: $(foreach doc, $(DOC_LIST), $(doc).pdf) - -.PHONY: txt-all -txt-all: $(foreach doc, $(DOC_LIST), $(doc).txt) - -.PHONY: info-all -info-all: $(foreach doc, $(DOC_LIST), $(doc).info) - -.PHONY: texinfo-all -texinfo-all: $(foreach doc, $(DOC_LIST), $(doc).texinfo) - -%.all: - $(MAKE) $(foreach fmt, $(FMT_LIST), $*.$(fmt)) - -.PHONY: all -all: $(foreach fmt, $(FMT_LIST), $(fmt)-all) diff --git a/gcc/ada/doc/gnat-style/conf.py b/gcc/ada/doc/gnat-style/conf.py new file mode 100644 index 000000000000..a413d2632eb1 --- /dev/null +++ b/gcc/ada/doc/gnat-style/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat-style' +project = 'GNAT Coding Style: A Guide for GNAT Developers' +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst new file mode 100644 index 000000000000..33c62cf7fde6 --- /dev/null +++ b/gcc/ada/doc/gnat-style/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat-style.rst b/gcc/ada/doc/gnat-style/index.rst similarity index 99% rename from gcc/ada/doc/gnat-style.rst rename to gcc/ada/doc/gnat-style/index.rst index 527e7ba2a66d..b9428749f1f8 100644 --- a/gcc/ada/doc/gnat-style.rst +++ b/gcc/ada/doc/gnat-style/index.rst @@ -688,4 +688,4 @@ Program Structure and Compilation Issues .. index:: krunch.ads file .. toctree:: - share/gnu_free_documentation_license + gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/conf.py b/gcc/ada/doc/gnat_rm/conf.py new file mode 100644 index 000000000000..e99d1e6bd134 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat_rm' +project = 'GNAT Reference Manual' +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst new file mode 100644 index 000000000000..33c62cf7fde6 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_rm.rst b/gcc/ada/doc/gnat_rm/index.rst similarity index 54% rename from gcc/ada/doc/gnat_rm.rst rename to gcc/ada/doc/gnat_rm/index.rst index 7743ef8b5f43..6c2616a0f1c0 100644 --- a/gcc/ada/doc/gnat_rm.rst +++ b/gcc/ada/doc/gnat_rm/index.rst @@ -39,25 +39,25 @@ GNAT Reference Manual :numbered: :maxdepth: 3 - gnat_rm/about_this_guide - gnat_rm/implementation_defined_pragmas - gnat_rm/implementation_defined_aspects - gnat_rm/implementation_defined_attributes - gnat_rm/standard_and_implementation_defined_restrictions - gnat_rm/implementation_advice - gnat_rm/implementation_defined_characteristics - gnat_rm/intrinsic_subprograms - gnat_rm/representation_clauses_and_pragmas - gnat_rm/standard_library_routines - gnat_rm/the_implementation_of_standard_i_o - gnat_rm/the_gnat_library - gnat_rm/interfacing_to_other_languages - gnat_rm/specialized_needs_annexes - gnat_rm/implementation_of_specific_ada_features - gnat_rm/implementation_of_ada_2012_features - gnat_rm/security_hardening_features - gnat_rm/obsolescent_features - gnat_rm/compatibility_and_porting_guide + about_this_guide + implementation_defined_pragmas + implementation_defined_aspects + implementation_defined_attributes + standard_and_implementation_defined_restrictions + implementation_advice + implementation_defined_characteristics + intrinsic_subprograms + representation_clauses_and_pragmas + standard_library_routines + the_implementation_of_standard_i_o + the_gnat_library + interfacing_to_other_languages + specialized_needs_annexes + implementation_of_specific_ada_features + implementation_of_ada_2012_features + security_hardening_features + obsolescent_features + compatibility_and_porting_guide .. raw:: latex @@ -66,4 +66,4 @@ GNAT Reference Manual .. toctree:: :maxdepth: 3 - share/gnu_free_documentation_license + gnu_free_documentation_license diff --git a/gcc/ada/doc/gnat_rm/security_hardening_features.rst b/gcc/ada/doc/gnat_rm/security_hardening_features.rst index d7c02b94f36d..5a1f2d46326e 100644 --- a/gcc/ada/doc/gnat_rm/security_hardening_features.rst +++ b/gcc/ada/doc/gnat_rm/security_hardening_features.rst @@ -1,3 +1,5 @@ +.. role:: switch(samp) + .. _Security_Hardening_Features: *************************** diff --git a/gcc/ada/doc/gnat_ugn/conf.py b/gcc/ada/doc/gnat_ugn/conf.py new file mode 100644 index 000000000000..94e3c07e836d --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/conf.py @@ -0,0 +1,26 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../share') + +from adabaseconf import * + +name = 'gnat_ugn' +project = "GNAT User's Guide for Native Platforms" +authors = 'AdaCore' + +set_latex_elements(latex_elements, project) + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +tags.add(get_gnat_build_type()) +set_common(name, globals()) diff --git a/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst new file mode 100644 index 000000000000..33c62cf7fde6 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/gnu_free_documentation_license.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/gnu_free_documentation_license.rst diff --git a/gcc/ada/doc/gnat_ugn.rst b/gcc/ada/doc/gnat_ugn/index.rst similarity index 63% rename from gcc/ada/doc/gnat_ugn.rst rename to gcc/ada/doc/gnat_ugn/index.rst index 0ac68763760f..d3d1dac3569e 100644 --- a/gcc/ada/doc/gnat_ugn.rst +++ b/gcc/ada/doc/gnat_ugn/index.rst @@ -40,12 +40,12 @@ GNAT User's Guide for Native Platforms :maxdepth: 3 :numbered: - gnat_ugn/about_this_guide - gnat_ugn/getting_started_with_gnat - gnat_ugn/the_gnat_compilation_model - gnat_ugn/building_executable_programs_with_gnat - gnat_ugn/gnat_utility_programs - gnat_ugn/gnat_and_program_execution + about_this_guide + getting_started_with_gnat + the_gnat_compilation_model + building_executable_programs_with_gnat + gnat_utility_programs + gnat_and_program_execution .. raw:: latex @@ -54,10 +54,10 @@ GNAT User's Guide for Native Platforms .. toctree:: :maxdepth: 3 - A. Platform-Specific Information - B. Example of Binder Output - C. Elaboration Order Handling in GNAT - D. Inline Assembler - E. GNU Free Documentation License + A. Platform-Specific Information + B. Example of Binder Output + C. Elaboration Order Handling in GNAT + D. Inline Assembler + E. GNU Free Documentation License diff --git a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst index 4d25dea3d1e7..3ada65ddade0 100644 --- a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst +++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst @@ -1,11 +1,5 @@ .. role:: switch(samp) -.. -- Non-breaking space in running text - -- E.g. Ada |nbsp| 95 - -.. |nbsp| unicode:: 0xA0 - :trim: - .. _Platform_Specific_Information: ***************************** diff --git a/gcc/ada/doc/share/latex_elements.py b/gcc/ada/doc/share/ada_latex_elements.py similarity index 87% rename from gcc/ada/doc/share/latex_elements.py rename to gcc/ada/doc/share/ada_latex_elements.py index f23b2aff6be1..9578c0296af4 100644 --- a/gcc/ada/doc/share/latex_elements.py +++ b/gcc/ada/doc/share/ada_latex_elements.py @@ -1,5 +1,9 @@ # define some latex elements to be used for PDF output +import os + +folder = os.path.dirname(os.path.realpath(__file__)) + PAGE_BLANK = r''' \makeatletter \def\cleartooddpage{%% @@ -46,7 +50,7 @@ TOC_CMD = r''' \makeatother ''' -with open('copyright.tex', 'r') as fd: +with open(os.path.join(folder, 'copyright.tex'), 'r') as fd: copyright = fd.read() TOC = r''' @@ -62,6 +66,11 @@ LATEX_HYPHEN = r''' \tolerance=1000 ''' +ENCLOSE = r''' +@definfoenclose strong,*,* +@definfoenclose emph,',' +''' + def doc_settings(full_document_name, version): return '\n'.join([ diff --git a/gcc/ada/doc/share/adabaseconf.py b/gcc/ada/doc/share/adabaseconf.py new file mode 100644 index 000000000000..4a80a838c633 --- /dev/null +++ b/gcc/ada/doc/share/adabaseconf.py @@ -0,0 +1,81 @@ +# GNAT build configuration file + +import sys +sys.path.append('.') +sys.path.append('../../../../doc') + +from baseconf import * + +import os +import re +import sys +import time + +import ada_latex_elements + +import ada_pygments + +gnatvsn_content = read_file('ada/gnatvsn.ads') + + +def get_gnat_version(): + m = re.search(r'Gnat_Static_Version_String : ' + + r'constant String := "([^\(\)]+)\(.*\)?";', + gnatvsn_content) + if m: + return m.group(1).strip() + else: + return gcc_BASEVER + + +def get_gnat_build_type(): + m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);', + gnatvsn_content) + if m: + return {'Gnatpro': 'PRO', + 'FSF': 'FSF', + 'GPL': 'GPL'}[m.group(1).strip()] + else: + print('cannot compute GNAT build type') + sys.exit(1) + + +copyright = '2008-%s, Free Software Foundation' % YEAR + +version = get_gnat_version() +release = get_gnat_version() + +if os.path.isfile('adacore_transparent.png'): + html_logo = 'adacore_transparent.png' +if os.path.isfile('favicon.ico'): + html_favicon = 'favicon.ico' + +latex_additional_files = ['../share/gnat.sty'] + +copyright_macros = { + 'date': time.strftime('%b %d, %Y'), + 'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO' + else 'GPL', + 'name': 'GNU Ada', + 'tool': 'GNAT', + 'version': version} + + +def set_latex_elements(latex_elements, title): + elements = { + 'preamble': '\\usepackage{gnat}\n' + + ada_latex_elements.TOC_DEPTH + + ada_latex_elements.PAGE_BLANK + + ada_latex_elements.TOC_CMD + + ada_latex_elements.LATEX_HYPHEN + + ada_latex_elements.doc_settings(title, get_gnat_version()), + 'tableofcontents': ada_latex_elements.TOC % copyright_macros + } + for key, value in elements.items(): + latex_elements.setdefault(key, '') + latex_elements[key] += value + + +def setup(app): + app.add_lexer('ada', ada_pygments.AdaLexer) + app.add_lexer('gpr', ada_pygments.GNATProjectLexer) diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py deleted file mode 100644 index bb36bfa0c6a7..000000000000 --- a/gcc/ada/doc/share/conf.py +++ /dev/null @@ -1,148 +0,0 @@ -# -*- coding: utf-8 -*- -# Style_Check:Python_Fragment (meaning no pyflakes check) -# -# GNAT build configuration file - -import sys -import os -import time -import re - -sys.path.append('.') - -import ada_pygments -import latex_elements - -# Some configuration values for the various documentation handled by -# this conf.py - -DOCS = { - 'gnat_rm': { - 'title': 'GNAT Reference Manual'}, - 'gnat_ugn': { - 'title': 'GNAT User\'s Guide for Native Platforms'}, - 'gnat-style': { - 'title': 'GNAT Coding Style: A Guide for GNAT Developers'}} - -# Then retrieve the source directory -root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) -gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads') -basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER') -texi_fsf = True # Set to False when FSF doc is switched to sphinx by default - -with open(gnatvsn_spec, 'r') as fd: - gnatvsn_content = fd.read() - - -def get_copyright(): - return '2008-%s, Free Software Foundation' % time.strftime('%Y') - - -def get_gnat_version(): - m = re.search(r'Gnat_Static_Version_String : ' + - r'constant String := "([^\(\)]+)\(.*\)?";', - gnatvsn_content) - if m: - return m.group(1).strip() - else: - if texi_fsf and os.path.exists(basever): - return '' - - try: - with open(basever) as fd: - return fd.read() - except Exception: - pass - - print('cannot find GNAT version in gnatvsn.ads or in ' + basever) - sys.exit(1) - - -def get_gnat_build_type(): - m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);', - gnatvsn_content) - if m: - return {'Gnatpro': 'PRO', - 'FSF': 'FSF', - 'GPL': 'GPL'}[m.group(1).strip()] - else: - print('cannot compute GNAT build type') - sys.exit(1) - - -# First retrieve the name of the documentation we are building -doc_name = os.environ.get('DOC_NAME', None) -if doc_name is None: - print('DOC_NAME environment variable should be set') - sys.exit(1) - -if doc_name not in DOCS: - print('%s is not a valid documentation name' % doc_name) - sys.exit(1) - - -# Exclude sources that are not part of the current documentation -exclude_patterns = [] -for d in os.listdir(root_source_dir): - if d not in ('share', doc_name, doc_name + '.rst'): - exclude_patterns.append(d) - print('ignoring %s' % d) - -if doc_name == 'gnat_rm': - exclude_patterns.append('share/gnat_project_manager.rst') - print('ignoring share/gnat_project_manager.rst') - -extensions = [] -templates_path = ['_templates'] -source_suffix = '.rst' -master_doc = doc_name - -# General information about the project. -project = DOCS[doc_name]['title'] - -copyright = get_copyright() - -version = get_gnat_version() -release = get_gnat_version() - -pygments_style = None -tags.add(get_gnat_build_type()) -html_theme = 'sphinxdoc' -if os.path.isfile('adacore_transparent.png'): - html_logo = 'adacore_transparent.png' -if os.path.isfile('favicon.ico'): - html_favicon = 'favicon.ico' - -html_static_path = ['_static'] - -latex_additional_files = ['gnat.sty'] - -copyright_macros = { - 'date': time.strftime("%b %d, %Y"), - 'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO' - else 'GPL', - 'name': 'GNU Ada', - 'tool': 'GNAT', - 'version': version} - -latex_elements = { - 'preamble': '\\usepackage{gnat}\n' + - latex_elements.TOC_DEPTH + - latex_elements.PAGE_BLANK + - latex_elements.TOC_CMD + - latex_elements.LATEX_HYPHEN + - latex_elements.doc_settings(DOCS[doc_name]['title'], - get_gnat_version()), - 'tableofcontents': latex_elements.TOC % copyright_macros} - -latex_documents = [ - (master_doc, '%s.tex' % doc_name, project, 'AdaCore', 'manual')] - -texinfo_documents = [ - (master_doc, doc_name, project, - 'AdaCore', doc_name, doc_name, '')] - - -def setup(app): - app.add_lexer('ada', ada_pygments.AdaLexer) - app.add_lexer('gpr', ada_pygments.GNATProjectLexer) diff --git a/gcc/ada/doc/share/gnu_free_documentation_license.rst b/gcc/ada/doc/share/gnu_free_documentation_license.rst deleted file mode 100644 index 0235545155f4..000000000000 --- a/gcc/ada/doc/share/gnu_free_documentation_license.rst +++ /dev/null @@ -1,458 +0,0 @@ -.. _gnu_fdl: - -****************************** -GNU Free Documentation License -****************************** - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -https://fsf.org/ - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -**Preamble** - -The purpose of this License is to make a manual, textbook, or other -functional and useful document "free" in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of "copyleft", which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -**1. APPLICABILITY AND DEFINITIONS** - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The **Document**, below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as "**you**". You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A "**Modified Version**" of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A "**Secondary Section**" is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The "**Invariant Sections**" are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The "**Cover Texts**" are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A "**Transparent**" copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not "Transparent" is called **Opaque**. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The "**Title Page**" means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, "Title Page" means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The "**publisher**" means any person or entity that distributes -copies of the Document to the public. - -A section "**Entitled XYZ**" means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as "**Acknowledgements**", -"**Dedications**", "**Endorsements**", or "**History**".) -To "**Preserve the Title**" -of such a section when you modify the Document means that it remains a -section "Entitled XYZ" according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -**2. VERBATIM COPYING** - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -**3. COPYING IN QUANTITY** - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -**4. MODIFICATIONS** - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. - -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. - -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - -D. Preserve all the copyright notices of the Document. - -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. - -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -H. Include an unaltered copy of this License. - -I. Preserve the section Entitled "History", Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - -K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the section all - the substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. - -M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - -N. Do not retitle any existing section to be Entitled "Endorsements" - or to conflict in title with any Invariant Section. - -O. Preserve any Warranty Disclaimers. - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled "Endorsements", provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -**5. COMBINING DOCUMENTS** - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled "History" -in the various original documents, forming one section Entitled -"History"; likewise combine any sections Entitled "Acknowledgements", -and any sections Entitled "Dedications". You must delete all sections -Entitled "Endorsements". - -**6. COLLECTIONS OF DOCUMENTS** - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -**7. AGGREGATION WITH INDEPENDENT WORKS** - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an "aggregate" if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -**8. TRANSLATION** - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled "Acknowledgements", -"Dedications", or "History", the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -**9. TERMINATION** - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -**10. FUTURE REVISIONS OF THIS LICENSE** - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -https://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -**11. RELICENSING** - -"Massive Multiauthor Collaboration Site" (or "MMC Site") means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -"Massive Multiauthor Collaboration" (or "MMC") contained in the -site means any set of copyrightable works thus published on the MMC -site. - -"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -"Incorporate" means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is "eligible for relicensing" if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -**ADDENDUM: How to use this License for your documents** - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - - Copyright © YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled "GNU - Free Documentation License". - - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the "with ... Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. diff --git a/gcc/ada/gcc-interface/Make-lang.in b/gcc/ada/gcc-interface/Make-lang.in index 45a4168e8908..71a26e526277 100644 --- a/gcc/ada/gcc-interface/Make-lang.in +++ b/gcc/ada/gcc-interface/Make-lang.in @@ -808,32 +808,24 @@ ada.tags: force # Generate documentation. -doc/gnat_ugn.info: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi $(gcc_docdir)/include/gcc-common.texi \ - gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat_ugn/info/texinfo/gnat_ugn.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/info; \ else true; fi -doc/gnat_rm.info: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat_rm/info/texinfo/gnat_rm.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/info; \ else true; fi -doc/gnat-style.info: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - if [ x$(BUILD_INFO) = xinfo ]; then \ - rm -f $(@)*; \ - $(MAKEINFO) $(MAKEINFOFLAGS) -I$(gcc_docdir)/include \ - -I$(srcdir)/ada -o $@ $<; \ +doc/gnat-style/info/texinfo/gnat-style.info: $(SPHINX_FILES) + + if [ x$(SPHINX_BUILD) = xsphinx-build ]; then \ + make -C $(srcdir)/../doc info SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/info; \ else true; fi -ADA_INFOFILES = doc/gnat_ugn.info doc/gnat_rm.info doc/gnat-style.info +ADA_INFOFILES = doc/gnat_ugn/info/texinfo/gnat_ugn.info \ + doc/gnat_rm/info/texinfo/gnat_rm.info \ + doc/gnat-style/info/texinfo/gnat-style.info ada.info: $(ADA_INFOFILES) @@ -844,26 +836,33 @@ ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn.info \ $(DESTDIR)$(infodir)/gnat_rm.info \ $(DESTDIR)$(infodir)/gnat-style.info -ADA_DVIFILES = doc/gnat_ugn.dvi \ - doc/gnat_rm.dvi doc/gnat-style.dvi +$(DESTDIR)$(infodir)/gnat_ugn.info: doc/gnat_ugn/info/texinfo/gnat_ugn.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ada.dvi: $(ADA_DVIFILES) +$(DESTDIR)$(infodir)/gnat_rm.info: doc/gnat_rm/info/texinfo/gnat_rm.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ada.install-dvi: $(ADA_DVIFILES) - @$(NORMAL_INSTALL) - test -z "$(dvidir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(dvidir)/gcc" - @list='$(ADA_DVIFILES)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(dvi__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/gcc/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/gcc/$$f"; \ - done +$(DESTDIR)$(infodir)/gnat-style.info: doc/gnat-style/info/texinfo/gnat-style.info installdirs + -rm -f $@ + -$(INSTALL_DATA) $< $@ -ADA_PDFFILES = doc/gnat_ugn.pdf \ - doc/gnat_rm.pdf doc/gnat-style.pdf +ADA_PDFFILES = doc/gnat_ugn/pdf/latex/gnat_ugn.pdf\ + doc/gnat_rm/pdf/latex/gnat_rm.pdf \ + doc/gnat-style/pdf/latex/gnat-style.pdf ada.pdf: $(ADA_PDFFILES) +doc/gnat_ugn/pdf/latex/gnat_ugn.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/pdf + +doc/gnat_rm/pdf/latex/gnat_rm.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/pdf + +doc/gnat-style/pdf/latex/gnat-style.pdf: $(SPHINX_FILES) + + make -C $(srcdir)/../doc latexpdf SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/pdf + ada.install-pdf: $(ADA_PDFFILES) @$(NORMAL_INSTALL) test -z "$(pdfdir)/gcc" || $(mkinstalldirs) "$(DESTDIR)$(pdfdir)/gcc" @@ -874,33 +873,18 @@ ada.install-pdf: $(ADA_PDFFILES) $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/gcc/$$f"; \ done -ada.html: +ada.html: doc/gnat_ugn/html/html/index.html doc/gnat_rm/html/html/index.html doc/gnat-style/html/html/index.html -ada.install-html: - -doc/gnat_ugn.dvi: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< - -doc/gnat_rm.dvi: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat_ugn/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_ugn BUILDDIR=$(objdir)/doc/gnat_ugn/html -doc/gnat-style.dvi: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi - $(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat_rm/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat_rm BUILDDIR=$(objdir)/doc/gnat_rm/html -doc/gnat_ugn.pdf: ada/gnat_ugn.texi \ - $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< +doc/gnat-style/html/html/index.html: $(SPHINX_FILES) + + make -C $(srcdir)/../doc html SOURCEDIR=$(abs_srcdir)/ada/doc/gnat-style BUILDDIR=$(objdir)/doc/gnat-style/html -doc/gnat_rm.pdf: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \ - $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< - -doc/gnat-style.pdf: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi - $(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $< +ada.install-html: # Install hooks: # gnat1 is installed elsewhere as part of $(COMPILERS). diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi deleted file mode 100644 index f3b1c29a24f0..000000000000 --- a/gcc/ada/gnat-style.texi +++ /dev/null @@ -1,1437 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnat-style.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 5.1.1.@* -@end ifinfo -@settitle GNAT Coding Style A Guide for GNAT Developers -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory GNU Ada Tools -@direntry -* gnat-style: (gnat-style.info). gnat-style -@end direntry - -@c %**end of header - -@copying -@quotation -GNAT Coding Style: A Guide for GNAT Developers , Aug 25, 2022 - -AdaCore - -Copyright @copyright{} 2008-2022, Free Software Foundation -@end quotation - -@end copying - -@titlepage -@title GNAT Coding Style A Guide for GNAT Developers -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top GNAT Coding Style A Guide for GNAT Developers -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{gnat-style doc}@anchor{0} -@menu -* General:: -* Lexical Elements:: -* Declarations and Types:: -* Expressions and Names:: -* Statements:: -* Subprograms:: -* Packages and Visibility Rules:: -* Program Structure and Compilation Issues:: -* Index:: - -@end menu - -@node General,Lexical Elements,Top,Top -@anchor{gnat-style general}@anchor{1}@anchor{gnat-style gnat-coding-style-a-guide-for-gnat-developers}@anchor{2} -@chapter General - - -Most of GNAT is written in Ada using a consistent style to ensure -readability of the code. This document has been written to help -maintain this consistent style, while having a large group of developers -work on the compiler. - -For the coding style in the C parts of the compiler and run time, -see the GNU Coding Guidelines. - -This document is structured after the Ada Reference Manual. -Those familiar with that document should be able to quickly -lookup style rules for particular constructs. - -@node Lexical Elements,Declarations and Types,General,Top -@anchor{gnat-style lexical-elements}@anchor{3} -@chapter Lexical Elements - - -@menu -* Character Set and Separators:: -* Identifiers:: -* Numeric Literals:: -* Reserved Words:: -* Comments:: - -@end menu - -@node Character Set and Separators,Identifiers,,Lexical Elements -@anchor{gnat-style character-set-and-separators}@anchor{4} -@section Character Set and Separators - - -@geindex Character set - -@geindex ASCII - -@geindex Separators - -@geindex End-of-line - -@geindex Line length - -@geindex Indentation - - -@itemize * - -@item -The character set used should be plain 7-bit ASCII. -The only separators allowed are space and the end-of-line sequence. -No other control character or format effector (such as @code{HT}, -@code{VT}, @code{FF} ) -should be used. -The normal end-of-line sequence is used, which may be -@code{LF}, @code{CR/LF} or @code{CR}, -depending on the host system. An optional @code{SUB} -( @code{16#1A#} ) may be present as the -last character in the file on hosts using that character as file terminator. - -@item -Files that are checked in or distributed should be in host format. - -@item -A line should never be longer than 79 characters, not counting the line -separator. - -@item -Lines must not have trailing blanks. - -@item -Indentation is 3 characters per level for @code{if} statements, loops, and -@code{case} statements. -For exact information on required spacing between lexical -elements, see file style.adb. - -@geindex style.adb file -@end itemize - -@node Identifiers,Numeric Literals,Character Set and Separators,Lexical Elements -@anchor{gnat-style identifiers}@anchor{5} -@section Identifiers - - - -@itemize * - -@item -Identifiers will start with an upper case letter, and each letter following -an underscore will be upper case. - -@geindex Casing (for identifiers) - -Short acronyms may be all upper case. -All other letters are lower case. -An exception is for identifiers matching a foreign language. In particular, -we use all lower case where appropriate for C. - -@item -Use underscores to separate words in an identifier. - -@geindex Underscores - -@item -Try to limit your use of abbreviations in identifiers. -It is ok to make a few abbreviations, explain what they mean, and then -use them frequently, but don’t use lots of obscure abbreviations. An -example is the @code{ALI} word which stands for Ada Library -Information and is by convention always written in upper-case when -used in entity names. - -@example -procedure Find_ALI_Files; -@end example - -@item -Don’t use the variable name @code{I}, use @code{J} instead; @code{I} is too -easily confused with @code{1} in some fonts. Similarly don’t use the -variable @code{O}, which is too easily mistaken for the number @code{0}. -@end itemize - -@node Numeric Literals,Reserved Words,Identifiers,Lexical Elements -@anchor{gnat-style numeric-literals}@anchor{6} -@section Numeric Literals - - - -@itemize * - -@item -Numeric literals should include underscores where helpful for -readability. - -@geindex Underscores - -@example -1_000_000 -16#8000_0000# -3.14159_26535_89793_23846 -@end example -@end itemize - -@node Reserved Words,Comments,Numeric Literals,Lexical Elements -@anchor{gnat-style reserved-words}@anchor{7} -@section Reserved Words - - - -@itemize * - -@item -Reserved words use all lower case. - -@geindex Casing (for reserved words) - -@example -return else -@end example - -@item -The words @code{Access}, @code{Delta} and @code{Digits} are -capitalized when used as attribute_designator. -@end itemize - -@node Comments,,Reserved Words,Lexical Elements -@anchor{gnat-style comments}@anchor{8} -@section Comments - - - -@itemize * - -@item -A comment starts with @code{--} followed by two spaces. -The only exception to this rule (i.e. one space is tolerated) is when the -comment ends with a single space followed by @code{--}. -It is also acceptable to have only one space between @code{--} and the start -of the comment when the comment is at the end of a line, -after some Ada code. - -@item -Every sentence in a comment should start with an upper-case letter (including -the first letter of the comment). - -@geindex Casing (in comments) - -@item -When declarations are commented with ‘hanging’ comments, i.e. -comments after the declaration, there is no blank line before the -comment, and if it is absolutely necessary to have blank lines within -the comments, e.g. to make paragraph separations within a single comment, -these blank lines `do' have a @code{--} (unlike the -normal rule, which is to use entirely blank lines for separating -comment paragraphs). The comment starts at same level of indentation -as code it is commenting. - -@geindex Blank lines (in comments) - -@geindex Indentation - -@example -z : Integer; --- Integer value for storing value of z --- --- The previous line was a blank line. -@end example - -@item -Comments that are dubious or incomplete, or that comment on possibly -wrong or incomplete code, should be preceded or followed by @code{???}. - -@item -Comments in a subprogram body must generally be surrounded by blank lines. -An exception is a comment that follows a line containing a single keyword -( @code{begin}, @code{else}, @code{loop} ): - -@example -begin - -- Comment for the next statement - - A := 5; - - -- Comment for the B statement - - B := 6; -end; -@end example - -@item -In sequences of statements, comments at the end of the lines should be -aligned. - -@geindex Alignment (in comments) - -@example -My_Identifier := 5; -- First comment -Other_Id := 6; -- Second comment -@end example - -@item -Short comments that fit on a single line are `not' ended with a -period. Comments taking more than a line are punctuated in the normal -manner. - -@item -Comments should focus on `why' instead of `what'. -Descriptions of what subprograms do go with the specification. - -@item -Comments describing a subprogram spec should specifically mention the -formal argument names. General rule: write a comment that does not -depend on the names of things. The names are supplementary, not -sufficient, as comments. - -@item -`Do not' put two spaces after periods in comments. -@end itemize - -@node Declarations and Types,Expressions and Names,Lexical Elements,Top -@anchor{gnat-style declarations-and-types}@anchor{9} -@chapter Declarations and Types - - - -@itemize * - -@item -In entity declarations, colons must be surrounded by spaces. Colons -should be aligned. - -@geindex Alignment (in declarations) - -@example -Entity1 : Integer; -My_Entity : Integer; -@end example - -@item -Declarations should be grouped in a logical order. -Related groups of declarations may be preceded by a header comment. - -@item -All local subprograms in a subprogram or package body should be declared -before the first local subprogram body. - -@item -Do not declare local entities that hide global entities. - -@geindex Hiding of outer entities - -@item -Do not declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. - -@item -The defining_identifiers of global declarations serve as -comments of a sort. So don’t choose terse names, but look for names -that give useful information instead. - -@item -Local names can be shorter, because they are used only within -one context, where comments explain their purpose. - -@item -When starting an initialization or default expression on the line that follows -the declaration line, use 2 characters for indentation. - -@example -Entity1 : Integer := - Function_Name (Parameters, For_Call); -@end example - -@item -If an initialization or default expression needs to be continued on subsequent -lines, the continuations should be indented from the start of the expression. - -@example -Entity1 : Integer := Long_Function_Name - (parameters for call); -@end example -@end itemize - -@node Expressions and Names,Statements,Declarations and Types,Top -@anchor{gnat-style expressions-and-names}@anchor{a} -@chapter Expressions and Names - - - -@itemize * - -@item -Every operator must be surrounded by spaces. An exception is that -this rule does not apply to the exponentiation operator, for which -there are no specific layout rules. The reason for this exception -is that sometimes it makes clearer reading to leave out the spaces -around exponentiation. - -@geindex Operators - -@example -E := A * B**2 + 3 * (C - D); -@end example - -@item -Use parentheses where they clarify the intended association of operands -with operators: - -@geindex Parenthesization of expressions - -@example -(A / B) * C -@end example -@end itemize - -@node Statements,Subprograms,Expressions and Names,Top -@anchor{gnat-style statements}@anchor{b} -@chapter Statements - - -@menu -* Simple and Compound Statements:: -* If Statements:: -* Case Statements:: -* Loop Statements:: -* Block Statements:: - -@end menu - -@node Simple and Compound Statements,If Statements,,Statements -@anchor{gnat-style simple-and-compound-statements}@anchor{c} -@section Simple and Compound Statements - - - -@itemize * - -@item -Use only one statement or label per line. - -@item -A longer sequence_of_statements may be divided in logical -groups or separated from surrounding code using a blank line. -@end itemize - -@node If Statements,Case Statements,Simple and Compound Statements,Statements -@anchor{gnat-style if-statements}@anchor{d} -@section If Statements - - - -@itemize * - -@item -When the @code{if}, @code{elsif} or @code{else} keywords fit on the -same line with the condition and the @code{then} keyword, then the -statement is formatted as follows: - -@geindex Alignment (in an if statement) - -@example -if condition then - ... -elsif condition then - ... -else - ... -end if; -@end example - -When the above layout is not possible, @code{then} should be aligned -with @code{if}, and conditions should preferably be split before an -@code{and} or @code{or} keyword a follows: - -@example -if long_condition_that_has_to_be_split - and then continued_on_the_next_line -then - ... -end if; -@end example - -The @code{elsif}, @code{else} and @code{end if} always line up with -the @code{if} keyword. The preferred location for splitting the line -is before @code{and} or @code{or}. The continuation of a condition is -indented with two spaces or as many as needed to make nesting clear. -As an exception, if conditions are closely related either of the -following is allowed: - -@example -if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf - or else - x = asldkjhalkdsjfhhfd - or else - x = asdfadsfadsf -then - ... -end if; - -if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else - x = asldkjhalkdsjfhhfd or else - x = asdfadsfadsf -then - ... -end if; -@end example - -@item -Conditions should use short-circuit forms ( @code{and then}, -@code{or else} ), except when the operands are boolean variables -or boolean constants. - -@geindex Short-circuit forms - -@item -Complex conditions in @code{if} statements are indented two characters: - -@geindex Indentation (in if statements) - -@example -if this_complex_condition - and then that_other_one - and then one_last_one -then - ... -end if; -@end example - -There are some cases where complex conditionals can be laid out -in manners that do not follow these rules to preserve better -parallelism between branches, e.g. - -@example -if xyz.abc (gef) = 'c' - or else - xyz.abc (gef) = 'x' -then - ... -end if; -@end example - -@item -Every @code{if} block is preceded and followed by a blank line, except -where it begins or ends a sequence_of_statements. - -@geindex Blank lines (in an if statement) - -@example -A := 5; - -if A = 5 then - null; -end if; - -A := 6; -@end example -@end itemize - -@node Case Statements,Loop Statements,If Statements,Statements -@anchor{gnat-style case-statements}@anchor{e} -@section Case Statements - - - -@itemize * - -@item -Layout is as below. For long @code{case} statements, the extra indentation -can be saved by aligning the @code{when} clauses with the opening @code{case}. - -@example -case expression is - when condition => - ... - when condition => - ... -end case; -@end example -@end itemize - -@node Loop Statements,Block Statements,Case Statements,Statements -@anchor{gnat-style loop-statements}@anchor{f} -@section Loop Statements - - - -@itemize * - -@item -When possible, have @code{for} or @code{while} on one line with the -condition and the @code{loop} keyword. - -@example -for J in S'Range loop - ... -end loop; -@end example - -If the condition is too long, split the condition (see ‘If -statements’ above) and align @code{loop} with the @code{for} or -@code{while} keyword. - -@geindex Alignment (in a loop statement) - -@example -while long_condition_that_has_to_be_split - and then continued_on_the_next_line -loop - ... -end loop; -@end example - -If the loop_statement has an identifier, it is laid out as follows: - -@example -Outer : while not condition loop - ... -end Outer; -@end example -@end itemize - -@node Block Statements,,Loop Statements,Statements -@anchor{gnat-style block-statements}@anchor{10} -@section Block Statements - - - -@itemize * - -@item -The @code{declare} (optional), @code{begin} and @code{end} words -are aligned, except when the block_statement is named. There -is a blank line before the @code{begin} keyword: - -@geindex Alignment (in a block statement) - -@example -Some_Block : declare - ... - -begin - ... -end Some_Block; -@end example -@end itemize - -@node Subprograms,Packages and Visibility Rules,Statements,Top -@anchor{gnat-style subprograms}@anchor{11} -@chapter Subprograms - - -@menu -* Subprogram Declarations:: -* Subprogram Bodies:: - -@end menu - -@node Subprogram Declarations,Subprogram Bodies,,Subprograms -@anchor{gnat-style subprogram-declarations}@anchor{12} -@section Subprogram Declarations - - - -@itemize * - -@item -Do not write the @code{in} for parameters. - -@example -function Length (S : String) return Integer; -@end example - -@item -When the declaration line for a procedure or a function is too long to fit -the entire declaration (including the keyword procedure or function) on a -single line, then fold it, putting a single parameter on a line, aligning -the colons, as in: - -@example -procedure Set_Heading - (Source : String; - Count : Natural; - Pad : Character := Space; - Fill : Boolean := True); -@end example - -In the case of a function, if the entire spec does not fit on one line, then -the return may appear after the last parameter, as in: - -@example -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) return String; -@end example - -Or it may appear on its own as a separate line. This form is preferred when -putting the return on the same line as the last parameter would result in -an overlong line. The return type may optionally be aligned with the types -of the parameters (usually we do this aligning if it results only in a small -number of extra spaces, and otherwise we don’t attempt to align). So two -alternative forms for the above spec are: - -@example -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) - return String; - -function Head - (Source : String; - Count : Natural; - Pad : Character := Space) - return String; -@end example -@end itemize - -@node Subprogram Bodies,,Subprogram Declarations,Subprograms -@anchor{gnat-style subprogram-bodies}@anchor{13} -@section Subprogram Bodies - - - -@itemize * - -@item -Function and procedure bodies should usually be sorted alphabetically. Do -not attempt to sort them in some logical order by functionality. For a -sequence of subprogram specs, a general alphabetical sorting is also -usually appropriate, but occasionally it makes sense to group by major -function, with appropriate headers. - -@item -All subprograms have a header giving the function name, with the following -format: - -@example ------------------ --- My_Function -- ------------------ - -procedure My_Function is -begin - ... -end My_Function; -@end example - -Note that the name in the header is preceded by a single space, -not two spaces as for other comments. These headers are used on -nested subprograms as well as outer level subprograms. They may -also be used as headers for sections of comments, or collections -of declarations that are related. - -@item -Every subprogram body must have a preceding subprogram_declaration, -which includes proper client documentation so that you do not need to -read the subprogram body in order to understand what the subprogram does and -how to call it. All subprograms should be documented, without exceptions. - -@geindex Blank lines (in subprogram bodies) - -@item -A sequence of declarations may optionally be separated from the following -begin by a blank line. Just as we optionally allow blank lines in general -between declarations, this blank line should be present only if it improves -readability. Generally we avoid this blank line if the declarative part is -small (one or two lines) and the body has no blank lines, and we include it -if the declarative part is long or if the body has blank lines. - -@item -If the declarations in a subprogram contain at least one nested -subprogram body, then just before the @code{begin} of the enclosing -subprogram, there is a comment line and a blank line: - -@example --- Start of processing for Enclosing_Subprogram - -begin - ... -end Enclosing_Subprogram; -@end example - -@item -When nested subprograms are present, variables that are referenced by any -nested subprogram should precede the nested subprogram specs. For variables -that are not referenced by nested procedures, the declarations can either also -be before any of the nested subprogram specs (this is the old style, more -generally used). Or then can come just before the begin, with a header. The -following example shows the two possible styles: - -@example -procedure Style1 is - Var_Referenced_In_Nested : Integer; - Var_Referenced_Only_In_Style1 : Integer; - - proc Nested; - -- Comments ... - - ------------ - -- Nested -- - ------------ - - procedure Nested is - begin - ... - end Nested; - --- Start of processing for Style1 - -begin - ... -end Style1; - -procedure Style2 is - Var_Referenced_In_Nested : Integer; - - proc Nested; - -- Comments ... - - ------------ - -- Nested -- - ------------ - - procedure Nested is - begin - ... - end Nested; - - -- Local variables - - Var_Referenced_Only_In_Style2 : Integer; - --- Start of processing for Style2 - -begin - ... -end Style2; -@end example - -For new code, we generally prefer Style2, but we do not insist on -modifying all legacy occurrences of Style1, which is still much -more common in the sources. -@end itemize - -@node Packages and Visibility Rules,Program Structure and Compilation Issues,Subprograms,Top -@anchor{gnat-style packages-and-visibility-rules}@anchor{14} -@chapter Packages and Visibility Rules - - - -@itemize * - -@item -All program units and subprograms have their name at the end: - -@example -package P is - ... -end P; -@end example - -@item -We will use the style of @code{use} -ing @code{with} -ed packages, with -the context clauses looking like: - -@geindex use clauses - -@example -with A; use A; -with B; use B; -@end example - -@item -Names declared in the visible part of packages should be -unique, to prevent name clashes when the packages are @code{use} d. - -@geindex Name clash avoidance - -@example -package Entity is - type Entity_Kind is ...; - ... -end Entity; -@end example - -@item -After the file header comment, the context clause and unit specification -should be the first thing in a program_unit. - -@item -Preelaborate, Pure and Elaborate_Body pragmas should be added right after the -package name, indented an extra level and using the parameterless form: - -@example -package Preelaborate_Package is - pragma Preelaborate; - ... -end Preelaborate_Package; -@end example -@end itemize - -@node Program Structure and Compilation Issues,Index,Packages and Visibility Rules,Top -@anchor{gnat-style program-structure-and-compilation-issues}@anchor{15} -@chapter Program Structure and Compilation Issues - - - -@itemize * - -@item -Every GNAT source file must be compiled with the @code{-gnatg} -switch to check the coding style. -(Note that you should look at -style.adb to see the lexical rules enforced by @code{-gnatg} ). - -@geindex -gnatg option (to gcc) - -@geindex style.adb file - -@item -Each source file should contain only one compilation unit. - -@item -Filenames should be 8 or fewer characters, followed by the @code{.adb} -extension for a body or @code{.ads} for a spec. - -@geindex File name length - -@item -Unit names should be distinct when ‘krunch’ed to 8 characters -(see krunch.ads) and the filenames should match the unit name, -except that they are all lower case. - -@geindex krunch.ads file -@end itemize - -@menu -* GNU Free Documentation License:: - -@end menu - -@node GNU Free Documentation License,,,Program Structure and Compilation Issues -@anchor{share/gnu_free_documentation_license doc}@anchor{16}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{17}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{18} -@section GNU Free Documentation License - - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -@indicateurl{https://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -`Preamble' - -The purpose of this License is to make a manual, textbook, or other -functional and useful document “free” in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of “copyleft”, which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -`1. APPLICABILITY AND DEFINITIONS' - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The `Document', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as “`you'”. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A “`Modified Version'” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A “`Secondary Section'” is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document’s overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The “`Invariant Sections'” are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The “`Cover Texts'” are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A “`Transparent'” copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not “Transparent” is called `Opaque'. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The “`Title Page'” means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, “Title Page” means -the text near the most prominent appearance of the work’s title, -preceding the beginning of the body of the text. - -The “`publisher'” means any person or entity that distributes -copies of the Document to the public. - -A section “`Entitled XYZ'” means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as “`Acknowledgements'”, -“`Dedications'”, “`Endorsements'”, or “`History'”.) -To “`Preserve the Title'” -of such a section when you modify the Document means that it remains a -section “Entitled XYZ” according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -`2. VERBATIM COPYING' - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -`3. COPYING IN QUANTITY' - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document’s license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -`4. MODIFICATIONS' - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - - -@enumerate A - -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document’s license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled “History”, Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled “History” in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the “History” section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled “Acknowledgements” or “Dedications”, -Preserve the Title of the section, and preserve in the section all -the substance and tone of each of the contributor acknowledgements -and/or dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled “Endorsements”. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled “Endorsements” -or to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version’s license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled “Endorsements”, provided it contains -nothing but endorsements of your Modified Version by various -parties—for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -`5. COMBINING DOCUMENTS' - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled “History” -in the various original documents, forming one section Entitled -“History”; likewise combine any sections Entitled “Acknowledgements”, -and any sections Entitled “Dedications”. You must delete all sections -Entitled “Endorsements”. - -`6. COLLECTIONS OF DOCUMENTS' - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -`7. AGGREGATION WITH INDEPENDENT WORKS' - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an “aggregate” if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation’s users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document’s Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -`8. TRANSLATION' - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled “Acknowledgements”, -“Dedications”, or “History”, the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -`9. TERMINATION' - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -`10. FUTURE REVISIONS OF THIS LICENSE' - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@indicateurl{https://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License “or any later version” applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy’s public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -`11. RELICENSING' - -“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -“Massive Multiauthor Collaboration” (or “MMC”) contained in the -site means any set of copyrightable works thus published on the MMC -site. - -“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -“Incorporate” means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is “eligible for relicensing” if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -`ADDENDUM: How to use this License for your documents' - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@quotation - -Copyright © YEAR YOUR NAME. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled “GNU -Free Documentation License”. -@end quotation - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the “with … Texts.” line with this: - -@quotation - -with the Invariant Sections being LIST THEIR TITLES, with the -Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. -@end quotation - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index,,Program Structure and Compilation Issues,Top -@unnumbered Index - - -@printindex ge - - -@c %**end of body -@bye diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi deleted file mode 100644 index fbd8bb8d6b29..000000000000 --- a/gcc/ada/gnat_rm.texi +++ /dev/null @@ -1,30385 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnat_rm.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 5.2.3.@* -@end ifinfo -@settitle GNAT Reference Manual -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory GNU Ada Tools -@direntry -* gnat_rm: (gnat_rm.info). gnat_rm -@end direntry - -@c %**end of header - -@copying -@quotation -GNAT Reference Manual , Oct 27, 2022 - -AdaCore - -Copyright @copyright{} 2008-2022, Free Software Foundation -@end quotation - -@end copying - -@titlepage -@title GNAT Reference Manual -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top GNAT Reference Manual -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{gnat_rm doc}@anchor{0} -`GNAT, The GNU Ada Development Environment' - - -@include gcc-common.texi -GCC version @value{version-GCC}@* -AdaCore - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being “GNAT Reference -Manual”, and with no Back-Cover Texts. A copy of the license is -included in the section entitled @ref{1,,GNU Free Documentation License}. - -@menu -* About This Guide:: -* Implementation Defined Pragmas:: -* Implementation Defined Aspects:: -* Implementation Defined Attributes:: -* Standard and Implementation Defined Restrictions:: -* Implementation Advice:: -* Implementation Defined Characteristics:: -* Intrinsic Subprograms:: -* Representation Clauses and Pragmas:: -* Standard Library Routines:: -* The Implementation of Standard I/O:: -* The GNAT Library:: -* Interfacing to Other Languages:: -* Specialized Needs Annexes:: -* Implementation of Specific Ada Features:: -* Implementation of Ada 2012 Features:: -* Security Hardening Features:: -* Obsolescent Features:: -* Compatibility and Porting Guide:: -* GNU Free Documentation License:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -About This Guide - -* What This Reference Manual Contains:: -* Conventions:: -* Related Information:: - -Implementation Defined Pragmas - -* Pragma Abort_Defer:: -* Pragma Abstract_State:: -* Pragma Ada_83:: -* Pragma Ada_95:: -* Pragma Ada_05:: -* Pragma Ada_2005:: -* Pragma Ada_12:: -* Pragma Ada_2012:: -* Pragma Ada_2022:: -* Pragma Aggregate_Individually_Assign:: -* Pragma Allow_Integer_Address:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assert_And_Cut:: -* Pragma Assertion_Policy:: -* Pragma Assume:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Async_Readers:: -* Pragma Async_Writers:: -* Pragma Attribute_Definition:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Float_Overflow:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Complete_Representation:: -* Pragma Complex_Representation:: -* Pragma Component_Alignment:: -* Pragma Constant_After_Elaboration:: -* Pragma Contract_Cases:: -* Pragma Convention_Identifier:: -* Pragma CPP_Class:: -* Pragma CPP_Constructor:: -* Pragma CPP_Virtual:: -* Pragma CPP_Vtable:: -* Pragma CPU:: -* Pragma Deadline_Floor:: -* Pragma Default_Initial_Condition:: -* Pragma Debug:: -* Pragma Debug_Policy:: -* Pragma Default_Scalar_Storage_Order:: -* Pragma Default_Storage_Pool:: -* Pragma Depends:: -* Pragma Detect_Blocking:: -* Pragma Disable_Atomic_Synchronization:: -* Pragma Dispatching_Domain:: -* Pragma Effective_Reads:: -* Pragma Effective_Writes:: -* Pragma Elaboration_Checks:: -* Pragma Eliminate:: -* Pragma Enable_Atomic_Synchronization:: -* Pragma Export_Function:: -* Pragma Export_Object:: -* Pragma Export_Procedure:: -* Pragma Export_Valued_Procedure:: -* Pragma Extend_System:: -* Pragma Extensions_Allowed:: -* Pragma Extensions_Visible:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ghost:: -* Pragma Global:: -* Pragma Ident:: -* Pragma Ignore_Pragma:: -* Pragma Implementation_Defined:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* Pragma Import_Function:: -* Pragma Import_Object:: -* Pragma Import_Procedure:: -* Pragma Import_Valued_Procedure:: -* Pragma Independent:: -* Pragma Independent_Components:: -* Pragma Initial_Condition:: -* Pragma Initialize_Scalars:: -* Pragma Initializes:: -* Pragma Inline_Always:: -* Pragma Inline_Generic:: -* Pragma Interface:: -* Pragma Interface_Name:: -* Pragma Interrupt_Handler:: -* Pragma Interrupt_State:: -* Pragma Invariant:: -* Pragma Keep_Names:: -* Pragma License:: -* Pragma Link_With:: -* Pragma Linker_Alias:: -* Pragma Linker_Constructor:: -* Pragma Linker_Destructor:: -* Pragma Linker_Section:: -* Pragma Lock_Free:: -* Pragma Loop_Invariant:: -* Pragma Loop_Optimize:: -* Pragma Loop_Variant:: -* Pragma Machine_Attribute:: -* Pragma Main:: -* Pragma Main_Storage:: -* Pragma Max_Queue_Length:: -* Pragma No_Body:: -* Pragma No_Caching:: -* Pragma No_Component_Reordering:: -* Pragma No_Elaboration_Code_All:: -* Pragma No_Heap_Finalization:: -* Pragma No_Inline:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing:: -* Pragma No_Tagged_Streams:: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Overflow_Mode:: -* Pragma Overriding_Renamings:: -* Pragma Partition_Elaboration_Policy:: -* Pragma Part_Of:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Post:: -* Pragma Postcondition:: -* Pragma Post_Class:: -* Pragma Pre:: -* Pragma Precondition:: -* Pragma Predicate:: -* Pragma Predicate_Failure:: -* Pragma Preelaborable_Initialization:: -* Pragma Prefix_Exception_Messages:: -* Pragma Pre_Class:: -* Pragma Priority_Specific_Dispatching:: -* Pragma Profile:: -* Pragma Profile_Warnings:: -* Pragma Propagate_Exceptions:: -* Pragma Provide_Shift_Operators:: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Rational:: -* Pragma Ravenscar:: -* Pragma Refined_Depends:: -* Pragma Refined_Global:: -* Pragma Refined_Post:: -* Pragma Refined_State:: -* Pragma Relative_Deadline:: -* Pragma Remote_Access_Type:: -* Pragma Rename_Pragma:: -* Pragma Restricted_Run_Time:: -* Pragma Restriction_Warnings:: -* Pragma Reviewable:: -* Pragma Secondary_Stack_Size:: -* Pragma Share_Generic:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma SPARK_Mode:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Debug_Info:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Type_Invariant:: -* Pragma Type_Invariant_Class:: -* Pragma Unchecked_Union:: -* Pragma Unevaluated_Use_Of_Old:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Unused:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Volatile_Full_Access:: -* Pragma Volatile_Function:: -* Pragma Warning_As_Error:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: - -Implementation Defined Aspects - -* Aspect Abstract_State:: -* Aspect Annotate:: -* Aspect Async_Readers:: -* Aspect Async_Writers:: -* Aspect Constant_After_Elaboration:: -* Aspect Contract_Cases:: -* Aspect Depends:: -* Aspect Default_Initial_Condition:: -* Aspect Dimension:: -* Aspect Dimension_System:: -* Aspect Disable_Controlled:: -* Aspect Effective_Reads:: -* Aspect Effective_Writes:: -* Aspect Extensions_Visible:: -* Aspect Favor_Top_Level:: -* Aspect Ghost:: -* Aspect Global:: -* Aspect Initial_Condition:: -* Aspect Initializes:: -* Aspect Inline_Always:: -* Aspect Invariant:: -* Aspect Invariant’Class:: -* Aspect Iterable:: -* Aspect Linker_Section:: -* Aspect Lock_Free:: -* Aspect Max_Queue_Length:: -* Aspect No_Caching:: -* Aspect No_Elaboration_Code_All:: -* Aspect No_Inline:: -* Aspect No_Tagged_Streams:: -* Aspect No_Task_Parts:: -* Aspect Object_Size:: -* Aspect Obsolescent:: -* Aspect Part_Of:: -* Aspect Persistent_BSS:: -* Aspect Predicate:: -* Aspect Pure_Function:: -* Aspect Refined_Depends:: -* Aspect Refined_Global:: -* Aspect Refined_Post:: -* Aspect Refined_State:: -* Aspect Relaxed_Initialization:: -* Aspect Remote_Access_Type:: -* Aspect Secondary_Stack_Size:: -* Aspect Scalar_Storage_Order:: -* Aspect Shared:: -* Aspect Simple_Storage_Pool:: -* Aspect Simple_Storage_Pool_Type:: -* Aspect SPARK_Mode:: -* Aspect Suppress_Debug_Info:: -* Aspect Suppress_Initialization:: -* Aspect Test_Case:: -* Aspect Thread_Local_Storage:: -* Aspect Universal_Aliasing:: -* Aspect Unmodified:: -* Aspect Unreferenced:: -* Aspect Unreferenced_Objects:: -* Aspect Value_Size:: -* Aspect Volatile_Full_Access:: -* Aspect Volatile_Function:: -* Aspect Warnings:: - -Implementation Defined Attributes - -* Attribute Abort_Signal:: -* Attribute Address_Size:: -* Attribute Asm_Input:: -* Attribute Asm_Output:: -* Attribute Atomic_Always_Lock_Free:: -* Attribute Bit:: -* Attribute Bit_Position:: -* Attribute Code_Address:: -* Attribute Compiler_Version:: -* Attribute Constrained:: -* Attribute Default_Bit_Order:: -* Attribute Default_Scalar_Storage_Order:: -* Attribute Deref:: -* Attribute Descriptor_Size:: -* Attribute Elaborated:: -* Attribute Elab_Body:: -* Attribute Elab_Spec:: -* Attribute Elab_Subp_Body:: -* Attribute Emax:: -* Attribute Enabled:: -* Attribute Enum_Rep:: -* Attribute Enum_Val:: -* Attribute Epsilon:: -* Attribute Fast_Math:: -* Attribute Finalization_Size:: -* Attribute Fixed_Value:: -* Attribute From_Any:: -* Attribute Has_Access_Values:: -* Attribute Has_Discriminants:: -* Attribute Has_Tagged_Values:: -* Attribute Img:: -* Attribute Initialized:: -* Attribute Integer_Value:: -* Attribute Invalid_Value:: -* Attribute Iterable:: -* Attribute Large:: -* Attribute Library_Level:: -* Attribute Loop_Entry:: -* Attribute Machine_Size:: -* Attribute Mantissa:: -* Attribute Maximum_Alignment:: -* Attribute Max_Integer_Size:: -* Attribute Mechanism_Code:: -* Attribute Null_Parameter:: -* Attribute Object_Size:: -* Attribute Old:: -* Attribute Passed_By_Reference:: -* Attribute Pool_Address:: -* Attribute Range_Length:: -* Attribute Restriction_Set:: -* Attribute Result:: -* Attribute Safe_Emax:: -* Attribute Safe_Large:: -* Attribute Safe_Small:: -* Attribute Scalar_Storage_Order:: -* Attribute Simple_Storage_Pool:: -* Attribute Small:: -* Attribute Small_Denominator:: -* Attribute Small_Numerator:: -* Attribute Storage_Unit:: -* Attribute Stub_Type:: -* Attribute System_Allocator_Alignment:: -* Attribute Target_Name:: -* Attribute To_Address:: -* Attribute To_Any:: -* Attribute Type_Class:: -* Attribute Type_Key:: -* Attribute TypeCode:: -* Attribute Unconstrained_Array:: -* Attribute Universal_Literal_String:: -* Attribute Unrestricted_Access:: -* Attribute Update:: -* Attribute Valid_Value:: -* Attribute Valid_Scalars:: -* Attribute VADS_Size:: -* Attribute Value_Size:: -* Attribute Wchar_T_Size:: -* Attribute Word_Size:: - -Standard and Implementation Defined Restrictions - -* Partition-Wide Restrictions:: -* Program Unit Level Restrictions:: - -Partition-Wide Restrictions - -* Immediate_Reclamation:: -* Max_Asynchronous_Select_Nesting:: -* Max_Entry_Queue_Length:: -* Max_Protected_Entries:: -* Max_Select_Alternatives:: -* Max_Storage_At_Blocking:: -* Max_Task_Entries:: -* Max_Tasks:: -* No_Abort_Statements:: -* No_Access_Parameter_Allocators:: -* No_Access_Subprograms:: -* No_Allocators:: -* No_Anonymous_Allocators:: -* No_Asynchronous_Control:: -* No_Calendar:: -* No_Coextensions:: -* No_Default_Initialization:: -* No_Delay:: -* No_Dependence:: -* No_Direct_Boolean_Operators:: -* No_Dispatch:: -* No_Dispatching_Calls:: -* No_Dynamic_Attachment:: -* No_Dynamic_Priorities:: -* No_Entry_Calls_In_Elaboration_Code:: -* No_Enumeration_Maps:: -* No_Exception_Handlers:: -* No_Exception_Propagation:: -* No_Exception_Registration:: -* No_Exceptions:: -* No_Finalization:: -* No_Fixed_Point:: -* No_Floating_Point:: -* No_Implicit_Conditionals:: -* No_Implicit_Dynamic_Code:: -* No_Implicit_Heap_Allocations:: -* No_Implicit_Protected_Object_Allocations:: -* No_Implicit_Task_Allocations:: -* No_Initialize_Scalars:: -* No_IO:: -* No_Local_Allocators:: -* No_Local_Protected_Objects:: -* No_Local_Tagged_Types:: -* No_Local_Timing_Events:: -* No_Long_Long_Integers:: -* No_Multiple_Elaboration:: -* No_Nested_Finalization:: -* No_Protected_Type_Allocators:: -* No_Protected_Types:: -* No_Recursion:: -* No_Reentrancy:: -* No_Relative_Delay:: -* No_Requeue_Statements:: -* No_Secondary_Stack:: -* No_Select_Statements:: -* No_Specific_Termination_Handlers:: -* No_Specification_of_Aspect:: -* No_Standard_Allocators_After_Elaboration:: -* No_Standard_Storage_Pools:: -* No_Stream_Optimizations:: -* No_Streams:: -* No_Tagged_Type_Registration:: -* No_Task_Allocators:: -* No_Task_At_Interrupt_Priority:: -* No_Task_Attributes_Package:: -* No_Task_Hierarchy:: -* No_Task_Termination:: -* No_Tasking:: -* No_Terminate_Alternatives:: -* No_Unchecked_Access:: -* No_Unchecked_Conversion:: -* No_Unchecked_Deallocation:: -* No_Use_Of_Entity:: -* Pure_Barriers:: -* Simple_Barriers:: -* Static_Priorities:: -* Static_Storage_Size:: - -Program Unit Level Restrictions - -* No_Elaboration_Code:: -* No_Dynamic_Accessibility_Checks:: -* No_Dynamic_Sized_Objects:: -* No_Entry_Queue:: -* No_Implementation_Aspect_Specifications:: -* No_Implementation_Attributes:: -* No_Implementation_Identifiers:: -* No_Implementation_Pragmas:: -* No_Implementation_Restrictions:: -* No_Implementation_Units:: -* No_Implicit_Aliasing:: -* No_Implicit_Loops:: -* No_Obsolescent_Features:: -* No_Wide_Characters:: -* Static_Dispatch_Tables:: -* SPARK_05:: - -Implementation Advice - -* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. -* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. -* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. -* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. -* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. -* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. -* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. -* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. -* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. -* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. -* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. -* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. -* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. -* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. -* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. -* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. -* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. -* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. -* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. -* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. -* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. -* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. -* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. -* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. -* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. -* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. -* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. -* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. -* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. -* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. -* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. -* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. -* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. -* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. -* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. -* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. -* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. -* RM A.18; Containers: RM A 18 Containers. -* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. -* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. -* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. -* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. -* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. -* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. -* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. -* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. -* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. -* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. -* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. -* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. -* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. -* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. -* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. -* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. -* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. -* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. -* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. -* RM F(7); COBOL Support: RM F 7 COBOL Support. -* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. -* RM G; Numerics: RM G Numerics. -* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. -* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. -* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. -* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. -* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. - -Intrinsic Subprograms - -* Intrinsic Operators:: -* Compilation_ISO_Date:: -* Compilation_Date:: -* Compilation_Time:: -* Enclosing_Entity:: -* Exception_Information:: -* Exception_Message:: -* Exception_Name:: -* File:: -* Line:: -* Shifts and Rotates:: -* Source_Location:: - -Representation Clauses and Pragmas - -* Alignment Clauses:: -* Size Clauses:: -* Storage_Size Clauses:: -* Size of Variant Record Objects:: -* Biased Representation:: -* Value_Size and Object_Size Clauses:: -* Component_Size Clauses:: -* Bit_Order Clauses:: -* Effect of Bit_Order on Byte Ordering:: -* Pragma Pack for Arrays:: -* Pragma Pack for Records:: -* Record Representation Clauses:: -* Handling of Records with Holes:: -* Enumeration Clauses:: -* Address Clauses:: -* Use of Address Clauses for Memory-Mapped I/O:: -* Effect of Convention on Representation:: -* Conventions and Anonymous Access Types:: -* Determining the Representations chosen by GNAT:: - -The Implementation of Standard I/O - -* Standard I/O Packages:: -* FORM Strings:: -* Direct_IO:: -* Sequential_IO:: -* Text_IO:: -* Wide_Text_IO:: -* Wide_Wide_Text_IO:: -* Stream_IO:: -* Text Translation:: -* Shared Files:: -* Filenames encoding:: -* File content encoding:: -* Open Modes:: -* Operations on C Streams:: -* Interfacing to C Streams:: - -Text_IO - -* Stream Pointer Positioning:: -* Reading and Writing Non-Regular Files:: -* Get_Immediate:: -* Treating Text_IO Files as Streams:: -* Text_IO Extensions:: -* Text_IO Facilities for Unbounded Strings:: - -Wide_Text_IO - -* Stream Pointer Positioning: Stream Pointer Positioning<2>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. - -Wide_Wide_Text_IO - -* Stream Pointer Positioning: Stream Pointer Positioning<3>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. - -The GNAT Library - -* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. -* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. -* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. -* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. -* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. -* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. -* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. -* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. -* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. -* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. -* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. -* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. -* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. -* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. -* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. -* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. -* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. -* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. -* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. -* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. -* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. -* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. -* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. -* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. -* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. -* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. -* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. -* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. -* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. -* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. -* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. -* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. -* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. -* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. -* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. -* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. -* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. -* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. -* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. -* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. -* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. -* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. -* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. -* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. -* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. -* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. -* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. -* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. -* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. -* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. -* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. -* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. -* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. -* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. -* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. -* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. -* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. -* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. -* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. -* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. -* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. -* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. -* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. -* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. -* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. -* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. -* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. -* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. -* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. -* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. -* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. -* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. -* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. -* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. -* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. -* GNAT.IO (g-io.ads): GNAT IO g-io ads. -* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. -* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. -* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. -* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. -* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. -* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. -* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. -* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. -* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. -* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. -* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. -* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. -* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. -* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. -* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. -* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. -* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. -* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. -* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. -* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. -* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. -* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. -* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. -* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. -* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. -* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. -* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. -* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. -* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. -* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. -* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. -* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. -* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. -* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. -* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. -* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. -* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. -* GNAT.Table (g-table.ads): GNAT Table g-table ads. -* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. -* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. -* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. -* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. -* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. -* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. -* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. -* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. -* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. -* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. -* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. -* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. -* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. -* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. -* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. -* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. -* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. -* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. -* System.Assertions (s-assert.ads): System Assertions s-assert ads. -* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. -* System.Memory (s-memory.ads): System Memory s-memory ads. -* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. -* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. -* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. -* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. -* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. -* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. -* System.Rident (s-rident.ads): System Rident s-rident ads. -* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. -* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. -* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. -* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. - -Interfacing to Other Languages - -* Interfacing to C:: -* Interfacing to C++:: -* Interfacing to COBOL:: -* Interfacing to Fortran:: -* Interfacing to non-GNAT Ada code:: - -Implementation of Specific Ada Features - -* Machine Code Insertions:: -* GNAT Implementation of Tasking:: -* GNAT Implementation of Shared Passive Packages:: -* Code Generation for Array Aggregates:: -* The Size of Discriminated Records with Default Discriminants:: -* Image Values For Nonscalar Types:: -* Strict Conformance to the Ada Reference Manual:: - -GNAT Implementation of Tasking - -* Mapping Ada Tasks onto the Underlying Kernel Threads:: -* Ensuring Compliance with the Real-Time Annex:: -* Support for Locking Policies:: - -Code Generation for Array Aggregates - -* Static constant aggregates with static bounds:: -* Constant aggregates with unconstrained nominal types:: -* Aggregates with static bounds:: -* Aggregates with nonstatic bounds:: -* Aggregates in assignment statements:: - -Security Hardening Features - -* Register Scrubbing:: -* Stack Scrubbing:: -* Hardened Conditionals:: -* Hardened Booleans:: -* Control Flow Redundancy:: - -Obsolescent Features - -* pragma No_Run_Time:: -* pragma Ravenscar:: -* pragma Restricted_Run_Time:: -* pragma Task_Info:: -* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. - -Compatibility and Porting Guide - -* Writing Portable Fixed-Point Declarations:: -* Compatibility with Ada 83:: -* Compatibility between Ada 95 and Ada 2005:: -* Implementation-dependent characteristics:: -* Compatibility with Other Ada Systems:: -* Representation Clauses:: -* Compatibility with HP Ada 83:: - -Compatibility with Ada 83 - -* Legal Ada 83 programs that are illegal in Ada 95:: -* More deterministic semantics:: -* Changed semantics:: -* Other language compatibility issues:: - -Implementation-dependent characteristics - -* Implementation-defined pragmas:: -* Implementation-defined attributes:: -* Libraries:: -* Elaboration order:: -* Target-specific aspects:: - -@end detailmenu -@end menu - -@node About This Guide,Implementation Defined Pragmas,Top,Top -@anchor{gnat_rm/about_this_guide doc}@anchor{2}@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5} -@chapter About This Guide - - - -This manual contains useful information in writing programs using the -GNAT compiler. It includes information on implementation dependent -characteristics of GNAT, including all the information required by -Annex M of the Ada language standard. - -GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be -invoked in Ada 83 compatibility mode. -By default, GNAT assumes Ada 2012, -but you can override with a compiler switch -to explicitly specify the language version. -(Please refer to the `GNAT User’s Guide' for details on these switches.) -Throughout this manual, references to ‘Ada’ without a year suffix -apply to all the Ada versions of the language. - -Ada is designed to be highly portable. -In general, a program will have the same effect even when compiled by -different compilers on different platforms. -However, since Ada is designed to be used in a -wide variety of applications, it also contains a number of system -dependent features to be used in interfacing to the external world. - -@geindex Implementation-dependent features - -@geindex Portability - -Note: Any program that makes use of implementation-dependent features -may be non-portable. You should follow good programming practice and -isolate and clearly document any sections of your program that make use -of these features in a non-portable manner. - -@menu -* What This Reference Manual Contains:: -* Conventions:: -* Related Information:: - -@end menu - -@node What This Reference Manual Contains,Conventions,,About This Guide -@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} -@section What This Reference Manual Contains - - -This reference manual contains the following chapters: - - -@itemize * - -@item -@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent -pragmas, which can be used to extend and enhance the functionality of the -compiler. - -@item -@ref{8,,Implementation Defined Attributes}, lists GNAT -implementation-dependent attributes, which can be used to extend and -enhance the functionality of the compiler. - -@item -@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT -implementation-dependent restrictions, which can be used to extend and -enhance the functionality of the compiler. - -@item -@ref{a,,Implementation Advice}, provides information on generally -desirable behavior which are not requirements that all compilers must -follow since it cannot be provided on all systems, or which may be -undesirable on some systems. - -@item -@ref{b,,Implementation Defined Characteristics}, provides a guide to -minimizing implementation dependent features. - -@item -@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms -implemented by GNAT, and how they can be imported into user -application programs. - -@item -@ref{d,,Representation Clauses and Pragmas}, describes in detail the -way that GNAT represents data, and in particular the exact set -of representation clauses and pragmas that is accepted. - -@item -@ref{e,,Standard Library Routines}, provides a listing of packages and a -brief description of the functionality that is provided by Ada’s -extensive set of standard library routines as implemented by GNAT. - -@item -@ref{f,,The Implementation of Standard I/O}, details how the GNAT -implementation of the input-output facilities. - -@item -@ref{10,,The GNAT Library}, is a catalog of packages that complement -the Ada predefined library. - -@item -@ref{11,,Interfacing to Other Languages}, describes how programs -written in Ada using GNAT can be interfaced to other programming -languages. - -@item -@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all -of the specialized needs annexes. - -@item -@ref{13,,Implementation of Specific Ada Features}, discusses issues related -to GNAT’s implementation of machine code insertions, tasking, and several -other features. - -@item -@ref{14,,Implementation of Ada 2012 Features}, describes the status of the -GNAT implementation of the Ada 2012 language standard. - -@item -@ref{15,,Security Hardening Features} documents GNAT extensions aimed -at security hardening. - -@item -@ref{16,,Obsolescent Features} documents implementation dependent features, -including pragmas and attributes, which are considered obsolescent, since -there are other preferred ways of achieving the same results. These -obsolescent forms are retained for backwards compatibility. - -@item -@ref{17,,Compatibility and Porting Guide} presents some guidelines for -developing portable Ada code, describes the compatibility issues that -may arise between GNAT and other Ada compilation systems (including those -for Ada 83), and shows how GNAT can expedite porting applications -developed in other Ada environments. - -@item -@ref{1,,GNU Free Documentation License} contains the license for this document. -@end itemize - -@geindex Ada 95 Language Reference Manual - -@geindex Ada 2005 Language Reference Manual - -This reference manual assumes a basic familiarity with the Ada 95 language, as -described in the -@cite{International Standard ANSI/ISO/IEC-8652:1995}. -It does not require knowledge of the new features introduced by Ada 2005 or -Ada 2012. -All three reference manuals are included in the GNAT documentation -package. - -@node Conventions,Related Information,What This Reference Manual Contains,About This Guide -@anchor{gnat_rm/about_this_guide conventions}@anchor{18} -@section Conventions - - -@geindex Conventions -@geindex typographical - -@geindex Typographical conventions - -Following are examples of the typographical and graphic conventions used -in this guide: - - -@itemize * - -@item -@code{Functions}, @code{utility program names}, @code{standard names}, -and @code{classes}. - -@item -@code{Option flags} - -@item -@code{File names} - -@item -@code{Variables} - -@item -`Emphasis' - -@item -[optional information or parameters] - -@item -Examples are described by text - -@example -and then shown this way. -@end example - -@item -Commands that are entered by the user are shown as preceded by a prompt string -comprising the @code{$} character followed by a space. -@end itemize - -@node Related Information,,Conventions,About This Guide -@anchor{gnat_rm/about_this_guide related-information}@anchor{19} -@section Related Information - - -See the following documents for further information on GNAT: - - -@itemize * - -@item -@cite{GNAT User’s Guide for Native Platforms}, -which provides information on how to use the -GNAT development environment. - -@item -@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. - -@item -@cite{Ada 95 Annotated Reference Manual}, which is an annotated version -of the Ada 95 standard. The annotations describe -detailed aspects of the design decision, and in particular contain useful -sections on Ada 83 compatibility. - -@item -@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. - -@item -@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version -of the Ada 2005 standard. The annotations describe -detailed aspects of the design decision. - -@item -@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. - -@item -@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, -which contains specific information on compatibility between GNAT and -DEC Ada 83 systems. - -@item -@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which -describes in detail the pragmas and attributes provided by the DEC Ada 83 -compiler system. -@end itemize - -@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top -@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{1a}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1b}@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7} -@chapter Implementation Defined Pragmas - - -Ada defines a set of pragmas that can be used to supply additional -information to the compiler. These language defined pragmas are -implemented in GNAT and work as described in the Ada Reference Manual. - -In addition, Ada allows implementations to define additional pragmas -whose meaning is defined by the implementation. GNAT provides a number -of these implementation-defined pragmas, which can be used to extend -and enhance the functionality of the compiler. This section of the GNAT -Reference Manual describes these additional pragmas. - -Note that any program using these pragmas might not be portable to other -compilers (although GNAT implements this set of pragmas on all -platforms). Therefore if portability to other compilers is an important -consideration, the use of these pragmas should be minimized. - -@menu -* Pragma Abort_Defer:: -* Pragma Abstract_State:: -* Pragma Ada_83:: -* Pragma Ada_95:: -* Pragma Ada_05:: -* Pragma Ada_2005:: -* Pragma Ada_12:: -* Pragma Ada_2012:: -* Pragma Ada_2022:: -* Pragma Aggregate_Individually_Assign:: -* Pragma Allow_Integer_Address:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assert_And_Cut:: -* Pragma Assertion_Policy:: -* Pragma Assume:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Async_Readers:: -* Pragma Async_Writers:: -* Pragma Attribute_Definition:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Float_Overflow:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Complete_Representation:: -* Pragma Complex_Representation:: -* Pragma Component_Alignment:: -* Pragma Constant_After_Elaboration:: -* Pragma Contract_Cases:: -* Pragma Convention_Identifier:: -* Pragma CPP_Class:: -* Pragma CPP_Constructor:: -* Pragma CPP_Virtual:: -* Pragma CPP_Vtable:: -* Pragma CPU:: -* Pragma Deadline_Floor:: -* Pragma Default_Initial_Condition:: -* Pragma Debug:: -* Pragma Debug_Policy:: -* Pragma Default_Scalar_Storage_Order:: -* Pragma Default_Storage_Pool:: -* Pragma Depends:: -* Pragma Detect_Blocking:: -* Pragma Disable_Atomic_Synchronization:: -* Pragma Dispatching_Domain:: -* Pragma Effective_Reads:: -* Pragma Effective_Writes:: -* Pragma Elaboration_Checks:: -* Pragma Eliminate:: -* Pragma Enable_Atomic_Synchronization:: -* Pragma Export_Function:: -* Pragma Export_Object:: -* Pragma Export_Procedure:: -* Pragma Export_Valued_Procedure:: -* Pragma Extend_System:: -* Pragma Extensions_Allowed:: -* Pragma Extensions_Visible:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ghost:: -* Pragma Global:: -* Pragma Ident:: -* Pragma Ignore_Pragma:: -* Pragma Implementation_Defined:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* Pragma Import_Function:: -* Pragma Import_Object:: -* Pragma Import_Procedure:: -* Pragma Import_Valued_Procedure:: -* Pragma Independent:: -* Pragma Independent_Components:: -* Pragma Initial_Condition:: -* Pragma Initialize_Scalars:: -* Pragma Initializes:: -* Pragma Inline_Always:: -* Pragma Inline_Generic:: -* Pragma Interface:: -* Pragma Interface_Name:: -* Pragma Interrupt_Handler:: -* Pragma Interrupt_State:: -* Pragma Invariant:: -* Pragma Keep_Names:: -* Pragma License:: -* Pragma Link_With:: -* Pragma Linker_Alias:: -* Pragma Linker_Constructor:: -* Pragma Linker_Destructor:: -* Pragma Linker_Section:: -* Pragma Lock_Free:: -* Pragma Loop_Invariant:: -* Pragma Loop_Optimize:: -* Pragma Loop_Variant:: -* Pragma Machine_Attribute:: -* Pragma Main:: -* Pragma Main_Storage:: -* Pragma Max_Queue_Length:: -* Pragma No_Body:: -* Pragma No_Caching:: -* Pragma No_Component_Reordering:: -* Pragma No_Elaboration_Code_All:: -* Pragma No_Heap_Finalization:: -* Pragma No_Inline:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing:: -* Pragma No_Tagged_Streams:: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Overflow_Mode:: -* Pragma Overriding_Renamings:: -* Pragma Partition_Elaboration_Policy:: -* Pragma Part_Of:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Post:: -* Pragma Postcondition:: -* Pragma Post_Class:: -* Pragma Pre:: -* Pragma Precondition:: -* Pragma Predicate:: -* Pragma Predicate_Failure:: -* Pragma Preelaborable_Initialization:: -* Pragma Prefix_Exception_Messages:: -* Pragma Pre_Class:: -* Pragma Priority_Specific_Dispatching:: -* Pragma Profile:: -* Pragma Profile_Warnings:: -* Pragma Propagate_Exceptions:: -* Pragma Provide_Shift_Operators:: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Rational:: -* Pragma Ravenscar:: -* Pragma Refined_Depends:: -* Pragma Refined_Global:: -* Pragma Refined_Post:: -* Pragma Refined_State:: -* Pragma Relative_Deadline:: -* Pragma Remote_Access_Type:: -* Pragma Rename_Pragma:: -* Pragma Restricted_Run_Time:: -* Pragma Restriction_Warnings:: -* Pragma Reviewable:: -* Pragma Secondary_Stack_Size:: -* Pragma Share_Generic:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma SPARK_Mode:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Debug_Info:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Type_Invariant:: -* Pragma Type_Invariant_Class:: -* Pragma Unchecked_Union:: -* Pragma Unevaluated_Use_Of_Old:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Unused:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Volatile_Full_Access:: -* Pragma Volatile_Function:: -* Pragma Warning_As_Error:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: - -@end menu - -@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} -@section Pragma Abort_Defer - - -@geindex Deferring aborts - -Syntax: - -@example -pragma Abort_Defer; -@end example - -This pragma must appear at the start of the statement sequence of a -handled sequence of statements (right after the @code{begin}). It has -the effect of deferring aborts for the sequence of statements (but not -for the declarations or handlers, if any, associated with this statement -sequence). This can also be useful for adding a polling point in Ada code, -where asynchronous abort of tasks is checked when leaving the statement -sequence, and is lighter than, for example, using @code{delay 0.0;}, since with -zero-cost exception handling, propagating exceptions (implicitly used to -implement task abort) cannot be done reliably in an asynchronous way. - -An example of usage would be: - -@example --- Add a polling point to check for task aborts - -begin - pragma Abort_Defer; -end; -@end example - -@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} -@section Pragma Abstract_State - - -Syntax: - -@example -pragma Abstract_State (ABSTRACT_STATE_LIST); - -ABSTRACT_STATE_LIST ::= - null - | STATE_NAME_WITH_OPTIONS - | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) - -STATE_NAME_WITH_OPTIONS ::= - STATE_NAME - | (STATE_NAME with OPTION_LIST) - -OPTION_LIST ::= OPTION @{, OPTION@} - -OPTION ::= - SIMPLE_OPTION - | NAME_VALUE_OPTION - -SIMPLE_OPTION ::= Ghost | Synchronous - -NAME_VALUE_OPTION ::= - Part_Of => ABSTRACT_STATE - | External [=> EXTERNAL_PROPERTY_LIST] - -EXTERNAL_PROPERTY_LIST ::= - EXTERNAL_PROPERTY - | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) - -EXTERNAL_PROPERTY ::= - Async_Readers [=> static_boolean_EXPRESSION] - | Async_Writers [=> static_boolean_EXPRESSION] - | Effective_Reads [=> static_boolean_EXPRESSION] - | Effective_Writes [=> static_boolean_EXPRESSION] - others => static_boolean_EXPRESSION - -STATE_NAME ::= defining_identifier - -ABSTRACT_STATE ::= name -@end example - -For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in -the SPARK 2014 Reference Manual, section 7.1.4. - -@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} -@section Pragma Ada_83 - - -Syntax: - -@example -pragma Ada_83; -@end example - -A configuration pragma that establishes Ada 83 mode for the unit to -which it applies, regardless of the mode set by the command line -switches. In Ada 83 mode, GNAT attempts to be as compatible with -the syntax and semantics of Ada 83, as defined in the original Ada -83 Reference Manual as possible. In particular, the keywords added by Ada 95 -and Ada 2005 are not recognized, optional package bodies are allowed, -and generics may name types with unknown discriminants without using -the @code{(<>)} notation. In addition, some but not all of the additional -restrictions of Ada 83 are enforced. - -Ada 83 mode is intended for two purposes. Firstly, it allows existing -Ada 83 code to be compiled and adapted to GNAT with less effort. -Secondly, it aids in keeping code backwards compatible with Ada 83. -However, there is no guarantee that code that is processed correctly -by GNAT in Ada 83 mode will in fact compile and execute with an Ada -83 compiler, since GNAT does not enforce all the additional checks -required by Ada 83. - -@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} -@section Pragma Ada_95 - - -Syntax: - -@example -pragma Ada_95; -@end example - -A configuration pragma that establishes Ada 95 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 95 features, but which is intended to be usable from -either Ada 83 or Ada 95 programs. - -@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} -@section Pragma Ada_05 - - -Syntax: - -@example -pragma Ada_05; -pragma Ada_05 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2005 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This pragma is useful when writing a reusable component that -itself uses Ada 2005 features, but which is intended to be usable from -either Ada 83 or Ada 95 programs. - -The one argument form (which is not a configuration pragma) -is used for managing the transition from -Ada 95 to Ada 2005 in the run-time library. If an entity is marked -as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 -mode will generate a warning. In addition, in Ada_83 or Ada_95 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2005 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} -@section Pragma Ada_2005 - - -Syntax: - -@example -pragma Ada_2005; -@end example - -This configuration pragma is a synonym for pragma Ada_05 and has the -same syntax and effect. - -@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} -@section Pragma Ada_12 - - -Syntax: - -@example -pragma Ada_12; -pragma Ada_12 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2012 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 2012 features, but which is intended to be usable from -Ada 83, Ada 95, or Ada 2005 programs. - -The one argument form, which is not a configuration pragma, -is used for managing the transition from Ada -2005 to Ada 2012 in the run-time library. If an entity is marked -as Ada_2012 only, then referencing the entity in any pre-Ada_2012 -mode will generate a warning. In addition, in any pre-Ada_2012 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2012 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} -@section Pragma Ada_2012 - - -Syntax: - -@example -pragma Ada_2012; -@end example - -This configuration pragma is a synonym for pragma Ada_12 and has the -same syntax and effect. - -@node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25} -@section Pragma Ada_2022 - - -Syntax: - -@example -pragma Ada_2022; -pragma Ada_2022 (local_NAME); -@end example - -A configuration pragma that establishes Ada 2022 mode for the unit to which -it applies, regardless of the mode set by the command line switches. -This mode is set automatically for the @code{Ada} and @code{System} -packages and their children, so you need not specify it in these -contexts. This pragma is useful when writing a reusable component that -itself uses Ada 2022 features, but which is intended to be usable from -Ada 83, Ada 95, Ada 2005 or Ada 2012 programs. - -The one argument form, which is not a configuration pragma, -is used for managing the transition from Ada -2012 to Ada 2022 in the run-time library. If an entity is marked -as Ada_2022 only, then referencing the entity in any pre-Ada_2022 -mode will generate a warning. In addition, in any pre-Ada_2012 -mode, a preference rule is established which does not choose -such an entity unless it is unambiguously specified. This avoids -extra subprograms marked this way from generating ambiguities in -otherwise legal pre-Ada_2022 programs. The one argument form is -intended for exclusive use in the GNAT run-time library. - -@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26} -@section Pragma Aggregate_Individually_Assign - - -Syntax: - -@example -pragma Aggregate_Individually_Assign; -@end example - -Where possible, GNAT will store the binary representation of a record aggregate -in memory for space and performance reasons. This configuration pragma changes -this behavior so that record aggregates are instead always converted into -individual assignment statements. - -@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27} -@section Pragma Allow_Integer_Address - - -Syntax: - -@example -pragma Allow_Integer_Address; -@end example - -In almost all versions of GNAT, @code{System.Address} is a private -type in accordance with the implementation advice in the RM. This -means that integer values, -in particular integer literals, are not allowed as address values. -If the configuration pragma -@code{Allow_Integer_Address} is given, then integer expressions may -be used anywhere a value of type @code{System.Address} is required. -The effect is to introduce an implicit unchecked conversion from the -integer value to type @code{System.Address}. The reverse case of using -an address where an integer type is required is handled analogously. -The following example compiles without errors: - -@example -pragma Allow_Integer_Address; -with System; use System; -package AddrAsInt is - X : Integer; - Y : Integer; - for X'Address use 16#1240#; - for Y use at 16#3230#; - m : Address := 16#4000#; - n : constant Address := 4000; - p : constant Address := Address (X + Y); - v : Integer := y'Address; - w : constant Integer := Integer (Y'Address); - type R is new integer; - RR : R := 1000; - Z : Integer; - for Z'Address use RR; -end AddrAsInt; -@end example - -Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} -is not a private type. In implementations of @code{GNAT} where -System.Address is a visible integer type, -this pragma serves no purpose but is ignored -rather than rejected to allow common sets of sources to be used -in the two situations. - -@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29} -@section Pragma Annotate - - -Syntax: - -@example -pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); - -ARG ::= NAME | EXPRESSION -@end example - -This pragma is used to annotate programs. IDENTIFIER identifies -the type of annotation. GNAT verifies that it is an identifier, but does -not otherwise analyze it. The second optional identifier is also left -unanalyzed, and by convention is used to control the action of the tool to -which the annotation is addressed. The remaining ARG arguments -can be either string literals or more generally expressions. -String literals (and concatenations of string literals) are assumed to be -either of type -@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} -depending on the character literals they contain. -All other kinds of arguments are analyzed as expressions, and must be -unambiguous. The last argument if present must have the identifier -@code{Entity} and GNAT verifies that a local name is given. - -The analyzed pragma is retained in the tree, but not otherwise processed -by any part of the GNAT compiler, except to generate corresponding note -lines in the generated ALI file. For the format of these note lines, see -the compiler source file lib-writ.ads. This pragma is intended for use by -external tools, including ASIS. The use of pragma Annotate does not -affect the compilation process in any way. This pragma may be used as -a configuration pragma. - -@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a} -@section Pragma Assert - - -Syntax: - -@example -pragma Assert ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma depends on whether the corresponding command -line switch is set to activate assertions. The pragma expands into code -equivalent to the following: - -@example -if assertions-enabled then - if not boolean_EXPRESSION then - System.Assertions.Raise_Assert_Failure - (string_EXPRESSION); - end if; -end if; -@end example - -The string argument, if given, is the message that will be associated -with the exception occurrence if the exception is raised. If no second -argument is given, the default message is @code{file}:@code{nnn}, -where @code{file} is the name of the source file containing the assert, -and @code{nnn} is the line number of the assert. - -Note that, as with the @code{if} statement to which it is equivalent, the -type of the expression is either @code{Standard.Boolean}, or any type derived -from this standard type. - -Assert checks can be either checked or ignored. By default they are ignored. -They will be checked if either the command line switch `-gnata' is -used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used -to enable @code{Assert_Checks}. - -If assertions are ignored, then there -is no run-time effect (and in particular, any side effects from the -expression will not occur at run time). (The expression is still -analyzed at compile time, and may cause types to be frozen if they are -mentioned here for the first time). - -If assertions are checked, then the given expression is tested, and if -it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called -which results in the raising of @code{Assert_Failure} with the given message. - -You should generally avoid side effects in the expression arguments of -this pragma, because these side effects will turn on and off with the -setting of the assertions mode, resulting in assertions that have an -effect on the program. However, the expressions are analyzed for -semantic correctness whether or not assertions are enabled, so turning -assertions on and off cannot affect the legality of a program. - -Note that the implementation defined policy @code{DISABLE}, given in a -pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. - -Note: this is a standard language-defined pragma in versions -of Ada from 2005 on. In GNAT, it is implemented in all versions -of Ada, and the DISABLE policy is an implementation-defined -addition. - -@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b} -@section Pragma Assert_And_Cut - - -Syntax: - -@example -pragma Assert_And_Cut ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma is identical to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Assert_And_Cut} is used to control whether it is ignored or checked -(or disabled). - -The intention is that this be used within a subprogram when the -given test expresion sums up all the work done so far in the -subprogram, so that the rest of the subprogram can be verified -(informally or formally) using only the entry preconditions, -and the expression in this pragma. This allows dividing up -a subprogram into sections for the purposes of testing or -formal verification. The pragma also serves as useful -documentation. - -@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c} -@section Pragma Assertion_Policy - - -Syntax: - -@example -pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); - -pragma Assertion_Policy ( - ASSERTION_KIND => POLICY_IDENTIFIER - @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); - -ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND - -RM_ASSERTION_KIND ::= Assert | - Static_Predicate | - Dynamic_Predicate | - Pre | - Pre'Class | - Post | - Post'Class | - Type_Invariant | - Type_Invariant'Class | - Default_Initial_Condition - -ID_ASSERTION_KIND ::= Assertions | - Assert_And_Cut | - Assume | - Contract_Cases | - Debug | - Ghost | - Initial_Condition | - Invariant | - Invariant'Class | - Loop_Invariant | - Loop_Variant | - Postcondition | - Precondition | - Predicate | - Refined_Post | - Statement_Assertions | - Subprogram_Variant - -POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible -@end example - -This is a standard Ada 2012 pragma that is available as an -implementation-defined pragma in earlier versions of Ada. -The assertion kinds @code{RM_ASSERTION_KIND} are those defined in -the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} -are implementation defined additions recognized by the GNAT compiler. - -The pragma applies in both cases to pragmas and aspects with matching -names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} -applies to both the @code{Precondition} pragma -and the aspect @code{Precondition}. Note that the identifiers for -pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not -Pre_Class and Post_Class), since these pragmas are intended to be -identical to the corresponding aspects. - -If the policy is @code{CHECK}, then assertions are enabled, i.e. -the corresponding pragma or aspect is activated. -If the policy is @code{IGNORE}, then assertions are ignored, i.e. -the corresponding pragma or aspect is deactivated. -This pragma overrides the effect of the `-gnata' switch on the -command line. -If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, -however, if the `-gnatp' switch is specified all assertions are ignored. - -The implementation defined policy @code{DISABLE} is like -@code{IGNORE} except that it completely disables semantic -checking of the corresponding pragma or aspect. This is -useful when the pragma or aspect argument references subprograms -in a with’ed package which is replaced by a dummy package -for the final build. - -The implementation defined assertion kind @code{Assertions} applies to all -assertion kinds. The form with no assertion kind given implies this -choice, so it applies to all assertion kinds (RM defined, and -implementation defined). - -The implementation defined assertion kind @code{Statement_Assertions} -applies to @code{Assert}, @code{Assert_And_Cut}, -@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. - -@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d} -@section Pragma Assume - - -Syntax: - -@example -pragma Assume ( - boolean_EXPRESSION - [, string_EXPRESSION]); -@end example - -The effect of this pragma is identical to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Assume} is used to control whether it is ignored or checked -(or disabled). - -The intention is that this be used for assumptions about the -external environment. So you cannot expect to verify formally -or informally that the condition is met, this must be -established by examining things outside the program itself. -For example, we may have code that depends on the size of -@code{Long_Long_Integer} being at least 64. So we could write: - -@example -pragma Assume (Long_Long_Integer'Size >= 64); -@end example - -This assumption cannot be proved from the program itself, -but it acts as a useful run-time check that the assumption -is met, and documents the need to ensure that it is met by -reference to information outside the program. - -@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e} -@section Pragma Assume_No_Invalid_Values - - -@geindex Invalid representations - -@geindex Invalid values - -Syntax: - -@example -pragma Assume_No_Invalid_Values (On | Off); -@end example - -This is a configuration pragma that controls the assumptions made by the -compiler about the occurrence of invalid representations (invalid values) -in the code. - -The default behavior (corresponding to an Off argument for this pragma), is -to assume that values may in general be invalid unless the compiler can -prove they are valid. Consider the following example: - -@example -V1 : Integer range 1 .. 10; -V2 : Integer range 11 .. 20; -... -for J in V2 .. V1 loop - ... -end loop; -@end example - -if V1 and V2 have valid values, then the loop is known at compile -time not to execute since the lower bound must be greater than the -upper bound. However in default mode, no such assumption is made, -and the loop may execute. If @code{Assume_No_Invalid_Values (On)} -is given, the compiler will assume that any occurrence of a variable -other than in an explicit @code{'Valid} test always has a valid -value, and the loop above will be optimized away. - -The use of @code{Assume_No_Invalid_Values (On)} is appropriate if -you know your code is free of uninitialized variables and other -possible sources of invalid representations, and may result in -more efficient code. A program that accesses an invalid representation -with this pragma in effect is erroneous, so no guarantees can be made -about its behavior. - -It is peculiar though permissible to use this pragma in conjunction -with validity checking (-gnatVa). In such cases, accessing invalid -values will generally give an exception, though formally the program -is erroneous so there are no guarantees that this will always be the -case, and it is recommended that these two options not be used together. - -@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30} -@section Pragma Async_Readers - - -Syntax: - -@example -pragma Async_Readers [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32} -@section Pragma Async_Writers - - -Syntax: - -@example -pragma Async_Writers [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33} -@section Pragma Attribute_Definition - - -Syntax: - -@example -pragma Attribute_Definition - ([Attribute =>] ATTRIBUTE_DESIGNATOR, - [Entity =>] LOCAL_NAME, - [Expression =>] EXPRESSION | NAME); -@end example - -If @code{Attribute} is a known attribute name, this pragma is equivalent to -the attribute definition clause: - -@example -for Entity'Attribute use Expression; -@end example - -If @code{Attribute} is not a recognized attribute name, the pragma is -ignored, and a warning is emitted. This allows source -code to be written that takes advantage of some new attribute, while remaining -compilable with earlier compilers. - -@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34} -@section Pragma C_Pass_By_Copy - - -@geindex Passing by copy - -Syntax: - -@example -pragma C_Pass_By_Copy - ([Max_Size =>] static_integer_EXPRESSION); -@end example - -Normally the default mechanism for passing C convention records to C -convention subprograms is to pass them by reference, as suggested by RM -B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change -this default, by requiring that record formal parameters be passed by -copy if all of the following conditions are met: - - -@itemize * - -@item -The size of the record type does not exceed the value specified for -@code{Max_Size}. - -@item -The record type has @code{Convention C}. - -@item -The formal parameter has this record type, and the subprogram has a -foreign (non-Ada) convention. -@end itemize - -If these conditions are met the argument is passed by copy; i.e., in a -manner consistent with what C expects if the corresponding formal in the -C prototype is a struct (rather than a pointer to a struct). - -You can also pass records by copy by specifying the convention -@code{C_Pass_By_Copy} for the record type, or by using the extended -@code{Import} and @code{Export} pragmas, which allow specification of -passing mechanisms on a parameter by parameter basis. - -@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35} -@section Pragma Check - - -@geindex Assertions - -@geindex Named assertions - -Syntax: - -@example -pragma Check ( - [Name =>] CHECK_KIND, - [Check =>] Boolean_EXPRESSION - [, [Message =>] string_EXPRESSION] ); - -CHECK_KIND ::= IDENTIFIER | - Pre'Class | - Post'Class | - Type_Invariant'Class | - Invariant'Class -@end example - -This pragma is similar to the predefined pragma @code{Assert} except that an -extra identifier argument is present. In conjunction with pragma -@code{Check_Policy}, this can be used to define groups of assertions that can -be independently controlled. The identifier @code{Assertion} is special, it -refers to the normal set of pragma @code{Assert} statements. - -Checks introduced by this pragma are normally deactivated by default. They can -be activated either by the command line option `-gnata', which turns on -all checks, or individually controlled using pragma @code{Check_Policy}. - -The identifiers @code{Assertions} and @code{Statement_Assertions} are not -permitted as check kinds, since this would cause confusion with the use -of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} -pragmas, where they are used to refer to sets of assertions. - -@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36} -@section Pragma Check_Float_Overflow - - -@geindex Floating-point overflow - -Syntax: - -@example -pragma Check_Float_Overflow; -@end example - -In Ada, the predefined floating-point types (@code{Short_Float}, -@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are -defined to be `unconstrained'. This means that even though each -has a well-defined base range, an operation that delivers a result -outside this base range is not required to raise an exception. -This implementation permission accommodates the notion -of infinities in IEEE floating-point, and corresponds to the -efficient execution mode on most machines. GNAT will not raise -overflow exceptions on these machines; instead it will generate -infinities and NaN’s as defined in the IEEE standard. - -Generating infinities, although efficient, is not always desirable. -Often the preferable approach is to check for overflow, even at the -(perhaps considerable) expense of run-time performance. -This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit -range constraints – and indeed such a subtype -can have the same base range as its base type. For example: - -@example -subtype My_Float is Float range Float'Range; -@end example - -Here @code{My_Float} has the same range as -@code{Float} but is constrained, so operations on -@code{My_Float} values will be checked for overflow -against this range. - -This style will achieve the desired goal, but -it is often more convenient to be able to simply use -the standard predefined floating-point types as long -as overflow checking could be guaranteed. -The @code{Check_Float_Overflow} -configuration pragma achieves this effect. If a unit is compiled -subject to this configuration pragma, then all operations -on predefined floating-point types including operations on -base types of these floating-point types will be treated as -though those types were constrained, and overflow checks -will be generated. The @code{Constraint_Error} -exception is raised if the result is out of range. - -This mode can also be set by use of the compiler -switch `-gnateF'. - -@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37} -@section Pragma Check_Name - - -@geindex Defining check names - -@geindex Check names -@geindex defining - -Syntax: - -@example -pragma Check_Name (check_name_IDENTIFIER); -@end example - -This is a configuration pragma that defines a new implementation -defined check name (unless IDENTIFIER matches one of the predefined -check names, in which case the pragma has no effect). Check names -are global to a partition, so if two or more configuration pragmas -are present in a partition mentioning the same name, only one new -check name is introduced. - -An implementation defined check name introduced with this pragma may -be used in only three contexts: @code{pragma Suppress}, -@code{pragma Unsuppress}, -and as the prefix of a @code{Check_Name'Enabled} attribute reference. For -any of these three cases, the check name must be visible. A check -name is visible if it is in the configuration pragmas applying to -the current unit, or if it appears at the start of any unit that -is part of the dependency set of the current unit (e.g., units that -are mentioned in @code{with} clauses). - -Check names introduced by this pragma are subject to control by compiler -switches (in particular -gnatp) in the usual manner. - -@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38} -@section Pragma Check_Policy - - -@geindex Controlling assertions - -@geindex Assertions -@geindex control - -@geindex Check pragma control - -@geindex Named assertions - -Syntax: - -@example -pragma Check_Policy - ([Name =>] CHECK_KIND, - [Policy =>] POLICY_IDENTIFIER); - -pragma Check_Policy ( - CHECK_KIND => POLICY_IDENTIFIER - @{, CHECK_KIND => POLICY_IDENTIFIER@}); - -ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND - -CHECK_KIND ::= IDENTIFIER | - Pre'Class | - Post'Class | - Type_Invariant'Class | - Invariant'Class - -The identifiers Name and Policy are not allowed as CHECK_KIND values. This -avoids confusion between the two possible syntax forms for this pragma. - -POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE -@end example - -This pragma is used to set the checking policy for assertions (specified -by aspects or pragmas), the @code{Debug} pragma, or additional checks -to be checked using the @code{Check} pragma. It may appear either as -a configuration pragma, or within a declarative part of package. In the -latter case, it applies from the point where it appears to the end of -the declarative region (like pragma @code{Suppress}). - -The @code{Check_Policy} pragma is similar to the -predefined @code{Assertion_Policy} pragma, -and if the check kind corresponds to one of the assertion kinds that -are allowed by @code{Assertion_Policy}, then the effect is identical. - -If the first argument is Debug, then the policy applies to Debug pragmas, -disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or -@code{IGNORE}, and allowing them to execute with normal semantics if -the policy is @code{ON} or @code{CHECK}. In addition if the policy is -@code{DISABLE}, then the procedure call in @code{Debug} pragmas will -be totally ignored and not analyzed semantically. - -Finally the first argument may be some other identifier than the above -possibilities, in which case it controls a set of named assertions -that can be checked using pragma @code{Check}. For example, if the pragma: - -@example -pragma Check_Policy (Critical_Error, OFF); -@end example - -is given, then subsequent @code{Check} pragmas whose first argument is also -@code{Critical_Error} will be disabled. - -The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} -to turn on corresponding checks. The default for a set of checks for which no -@code{Check_Policy} is given is @code{OFF} unless the compiler switch -`-gnata' is given, which turns on all checks by default. - -The check policy settings @code{CHECK} and @code{IGNORE} are recognized -as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for -compatibility with the standard @code{Assertion_Policy} pragma. The check -policy setting @code{DISABLE} causes the second argument of a corresponding -@code{Check} pragma to be completely ignored and not analyzed. - -@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39} -@section Pragma Comment - - -Syntax: - -@example -pragma Comment (static_string_EXPRESSION); -@end example - -This is almost identical in effect to pragma @code{Ident}. It allows the -placement of a comment into the object file and hence into the -executable file if the operating system permits such usage. The -difference is that @code{Comment}, unlike @code{Ident}, has -no limitations on placement of the pragma (it can be placed -anywhere in the main source unit), and if more than one pragma -is used, all comments are retained. - -@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a} -@section Pragma Common_Object - - -Syntax: - -@example -pragma Common_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] ); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma enables the shared use of variables stored in overlaid -linker areas corresponding to the use of @code{COMMON} -in Fortran. The single -object @code{LOCAL_NAME} is assigned to the area designated by -the @code{External} argument. -You may define a record to correspond to a series -of fields. The @code{Size} argument -is syntax checked in GNAT, but otherwise ignored. - -@code{Common_Object} is not supported on all platforms. If no -support is available, then the code generator will issue a message -indicating that the necessary attribute for implementation of this -pragma is not available. - -@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} -@section Pragma Compile_Time_Error - - -Syntax: - -@example -pragma Compile_Time_Error - (boolean_EXPRESSION, static_string_EXPRESSION); -@end example - -This pragma can be used to generate additional compile time -error messages. It -is particularly useful in generics, where errors can be issued for -specific problematic instantiations. The first parameter is a boolean -expression. The pragma ensures that the value of an expression -is known at compile time, and has the value False. The set of expressions -whose values are known at compile time includes all static boolean -expressions, and also other values which the compiler can determine -at compile time (e.g., the size of a record type set by an explicit -size representation clause, or the value of a variable which was -initialized to a constant and is known not to have been modified). -If these conditions are not met, an error message is generated using -the value given as the second argument. This string value may contain -embedded ASCII.LF characters to break the message into multiple lines. - -@node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} -@section Pragma Compile_Time_Warning - - -Syntax: - -@example -pragma Compile_Time_Warning - (boolean_EXPRESSION, static_string_EXPRESSION); -@end example - -Same as pragma Compile_Time_Error, except a warning is issued instead -of an error message. If switch `-gnatw_C' is used, a warning is only issued -if the value of the expression is known to be True at compile time, not when -the value of the expression is not known at compile time. -Note that if this pragma is used in a package that -is with’ed by a client, the client will get the warning even though it -is issued by a with’ed package (normally warnings in with’ed units are -suppressed, but this is a special exception to that rule). - -One typical use is within a generic where compile time known characteristics -of formal parameters are tested, and warnings given appropriately. Another use -with a first parameter of True is to warn a client about use of a package, -for example that it is not fully implemented. - -In previous versions of the compiler, combining `-gnatwe' with -Compile_Time_Warning resulted in a fatal error. Now the compiler always emits -a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of -an error. - -@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} -@section Pragma Complete_Representation - - -Syntax: - -@example -pragma Complete_Representation; -@end example - -This pragma must appear immediately within a record representation -clause. Typical placements are before the first component clause -or after the last component clause. The effect is to give an error -message if any component is missing a component clause. This pragma -may be used to ensure that a record representation clause is -complete, and that this invariant is maintained if fields are -added to the record in the future. - -@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} -@section Pragma Complex_Representation - - -Syntax: - -@example -pragma Complex_Representation - ([Entity =>] LOCAL_NAME); -@end example - -The @code{Entity} argument must be the name of a record type which has -two fields of the same floating-point type. The effect of this pragma is -to force gcc to use the special internal complex representation form for -this record, which may be more efficient. Note that this may result in -the code for this type not conforming to standard ABI (application -binary interface) requirements for the handling of record types. For -example, in some environments, there is a requirement for passing -records by pointer, and the use of this pragma may result in passing -this type in floating-point registers. - -@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} -@section Pragma Component_Alignment - - -@geindex Alignments of components - -@geindex Pragma Component_Alignment - -Syntax: - -@example -pragma Component_Alignment ( - [Form =>] ALIGNMENT_CHOICE - [, [Name =>] type_LOCAL_NAME]); - -ALIGNMENT_CHOICE ::= - Component_Size -| Component_Size_4 -| Storage_Unit -| Default -@end example - -Specifies the alignment of components in array or record types. -The meaning of the @code{Form} argument is as follows: - -@quotation - -@geindex Component_Size (in pragma Component_Alignment) -@end quotation - - -@table @asis - -@item `Component_Size' - -Aligns scalar components and subcomponents of the array or record type -on boundaries appropriate to their inherent size (naturally -aligned). For example, 1-byte components are aligned on byte boundaries, -2-byte integer components are aligned on 2-byte boundaries, 4-byte -integer components are aligned on 4-byte boundaries and so on. These -alignment rules correspond to the normal rules for C compilers on all -machines except the VAX. - -@geindex Component_Size_4 (in pragma Component_Alignment) - -@item `Component_Size_4' - -Naturally aligns components with a size of four or fewer -bytes. Components that are larger than 4 bytes are placed on the next -4-byte boundary. - -@geindex Storage_Unit (in pragma Component_Alignment) - -@item `Storage_Unit' - -Specifies that array or record components are byte aligned, i.e., -aligned on boundaries determined by the value of the constant -@code{System.Storage_Unit}. - -@geindex Default (in pragma Component_Alignment) - -@item `Default' - -Specifies that array or record components are aligned on default -boundaries, appropriate to the underlying hardware or operating system or -both. The @code{Default} choice is the same as @code{Component_Size} (natural -alignment). -@end table - -If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must -refer to a local record or array type, and the specified alignment -choice applies to the specified type. The use of -@code{Component_Alignment} together with a pragma @code{Pack} causes the -@code{Component_Alignment} pragma to be ignored. The use of -@code{Component_Alignment} together with a record representation clause -is only effective for fields not specified by the representation clause. - -If the @code{Name} parameter is absent, the pragma can be used as either -a configuration pragma, in which case it applies to one or more units in -accordance with the normal rules for configuration pragmas, or it can be -used within a declarative part, in which case it applies to types that -are declared within this declarative part, or within any nested scope -within this declarative part. In either case it specifies the alignment -to be applied to any record or array type which has otherwise standard -representation. - -If the alignment for a record or array type is not specified (using -pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep -clause), the GNAT uses the default alignment as described previously. - -@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} -@section Pragma Constant_After_Elaboration - - -Syntax: - -@example -pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect -@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. - -@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} -@section Pragma Contract_Cases - - -@geindex Contract cases - -Syntax: - -@example -pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@}); - -CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE - -CASE_GUARD ::= boolean_EXPRESSION | others - -CONSEQUENCE ::= boolean_EXPRESSION -@end example - -The @code{Contract_Cases} pragma allows defining fine-grain specifications -that can complement or replace the contract given by a precondition and a -postcondition. Additionally, the @code{Contract_Cases} pragma can be used -by testing and formal verification tools. The compiler checks its validity and, -depending on the assertion policy at the point of declaration of the pragma, -it may insert a check in the executable. For code generation, the contract -cases - -@example -pragma Contract_Cases ( - Cond1 => Pred1, - Cond2 => Pred2); -@end example - -are equivalent to - -@example -C1 : constant Boolean := Cond1; -- evaluated at subprogram entry -C2 : constant Boolean := Cond2; -- evaluated at subprogram entry -pragma Precondition ((C1 and not C2) or (C2 and not C1)); -pragma Postcondition (if C1 then Pred1); -pragma Postcondition (if C2 then Pred2); -@end example - -The precondition ensures that one and only one of the case guards is -satisfied on entry to the subprogram. -The postcondition ensures that for the case guard that was True on entry, -the corresponding consequence is True on exit. Other consequence expressions -are not evaluated. - -A precondition @code{P} and postcondition @code{Q} can also be -expressed as contract cases: - -@example -pragma Contract_Cases (P => Q); -@end example - -The placement and visibility rules for @code{Contract_Cases} pragmas are -identical to those described for preconditions and postconditions. - -The compiler checks that boolean expressions given in case guards and -consequences are valid, where the rules for case guards are the same as -the rule for an expression in @code{Precondition} and the rules for -consequences are the same as the rule for an expression in -@code{Postcondition}. In particular, attributes @code{'Old} and -@code{'Result} can only be used within consequence expressions. -The case guard for the last contract case may be @code{others}, to denote -any case not captured by the previous cases. The -following is an example of use within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, - Arg >= 100.0 => Sqrt'Result >= 10.0, - others => Sqrt'Result = 0.0)); - ... -end Math_Functions; -@end example - -The meaning of contract cases is that only one case should apply at each -call, as determined by the corresponding case guard evaluating to True, -and that the consequence for this case should hold when the subprogram -returns. - -@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} -@section Pragma Convention_Identifier - - -@geindex Conventions -@geindex synonyms - -Syntax: - -@example -pragma Convention_Identifier ( - [Name =>] IDENTIFIER, - [Convention =>] convention_IDENTIFIER); -@end example - -This pragma provides a mechanism for supplying synonyms for existing -convention identifiers. The @code{Name} identifier can subsequently -be used as a synonym for the given convention in other pragmas (including -for example pragma @code{Import} or another @code{Convention_Identifier} -pragma). As an example of the use of this, suppose you had legacy code -which used Fortran77 as the identifier for Fortran. Then the pragma: - -@example -pragma Convention_Identifier (Fortran77, Fortran); -@end example - -would allow the use of the convention identifier @code{Fortran77} in -subsequent code, avoiding the need to modify the sources. As another -example, you could use this to parameterize convention requirements -according to systems. Suppose you needed to use @code{Stdcall} on -windows systems, and @code{C} on some other system, then you could -define a convention identifier @code{Library} and use a single -@code{Convention_Identifier} pragma to specify which convention -would be used system-wide. - -@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} -@section Pragma CPP_Class - - -@geindex Interfacing with C++ - -Syntax: - -@example -pragma CPP_Class ([Entity =>] LOCAL_NAME); -@end example - -The argument denotes an entity in the current declarative region that is -declared as a record type. It indicates that the type corresponds to an -externally declared C++ class type, and is to be laid out the same way -that C++ would lay out the type. If the C++ class has virtual primitives -then the record must be declared as a tagged record type. - -Types for which @code{CPP_Class} is specified do not have assignment or -equality operators defined (such operations can be imported or declared -as subprograms as required). Initialization is allowed only by constructor -functions (see pragma @code{CPP_Constructor}). Such types are implicitly -limited if not explicitly declared as limited or derived from a limited -type, and an error is issued in that case. - -See @ref{47,,Interfacing to C++} for related information. - -Note: Pragma @code{CPP_Class} is currently obsolete. It is supported -for backward compatibility but its functionality is available -using pragma @code{Import} with @code{Convention} = @code{CPP}. - -@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} -@section Pragma CPP_Constructor - - -@geindex Interfacing with C++ - -Syntax: - -@example -pragma CPP_Constructor ([Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); -@end example - -This pragma identifies an imported function (imported in the usual way -with pragma @code{Import}) as corresponding to a C++ constructor. If -@code{External_Name} and @code{Link_Name} are not specified then the -@code{Entity} argument is a name that must have been previously mentioned -in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name -must be of one of the following forms: - - -@itemize * - -@item -`function' @code{Fname} `return' T` - -@item -`function' @code{Fname} `return' T’Class - -@item -`function' @code{Fname} (…) `return' T` - -@item -`function' @code{Fname} (…) `return' T’Class -@end itemize - -where @code{T} is a limited record type imported from C++ with pragma -@code{Import} and @code{Convention} = @code{CPP}. - -The first two forms import the default constructor, used when an object -of type @code{T} is created on the Ada side with no explicit constructor. -The latter two forms cover all the non-default constructors of the type. -See the GNAT User’s Guide for details. - -If no constructors are imported, it is impossible to create any objects -on the Ada side and the type is implicitly declared abstract. - -Pragma @code{CPP_Constructor} is intended primarily for automatic generation -using an automatic binding generator tool (such as the @code{-fdump-ada-spec} -GCC switch). -See @ref{47,,Interfacing to C++} for more related information. - -Note: The use of functions returning class-wide types for constructors is -currently obsolete. They are supported for backward compatibility. The -use of functions returning the type T leave the Ada sources more clear -because the imported C++ constructors always return an object of type T; -that is, they never return an object whose type is a descendant of type T. - -@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} -@section Pragma CPP_Virtual - - -@geindex Interfacing to C++ - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is completely ignored. -It is retained for compatibility -purposes. It used to be required to ensure compatibility with C++, but -is no longer required for that purpose because GNAT generates -the same object layout as the G++ compiler by default. - -See @ref{47,,Interfacing to C++} for related information. - -@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} -@section Pragma CPP_Vtable - - -@geindex Interfacing with C++ - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is completely ignored. -It used to be required to ensure compatibility with C++, but -is no longer required for that purpose because GNAT generates -the same object layout as the G++ compiler by default. - -See @ref{47,,Interfacing to C++} for related information. - -@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} -@section Pragma CPU - - -Syntax: - -@example -pragma CPU (EXPRESSION); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} -@section Pragma Deadline_Floor - - -Syntax: - -@example -pragma Deadline_Floor (time_span_EXPRESSION); -@end example - -This pragma applies only to protected types and specifies the floor -deadline inherited by a task when the task enters a protected object. -It is effective only when the EDF scheduling policy is used. - -@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4d}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4e} -@section Pragma Default_Initial_Condition - - -Syntax: - -@example -pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect -@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. - -@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4f} -@section Pragma Debug - - -Syntax: - -@example -pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); - -PROCEDURE_CALL_WITHOUT_SEMICOLON ::= - PROCEDURE_NAME -| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART -@end example - -The procedure call argument has the syntactic form of an expression, meeting -the syntactic requirements for pragmas. - -If debug pragmas are not enabled or if the condition is present and evaluates -to False, this pragma has no effect. If debug pragmas are enabled, the -semantics of the pragma is exactly equivalent to the procedure call statement -corresponding to the argument with a terminating semicolon. Pragmas are -permitted in sequences of declarations, so you can use pragma @code{Debug} to -intersperse calls to debug procedures in the middle of declarations. Debug -pragmas can be enabled either by use of the command line switch `-gnata' -or by use of the pragma @code{Check_Policy} with a first argument of -@code{Debug}. - -@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{50} -@section Pragma Debug_Policy - - -Syntax: - -@example -pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); -@end example - -This pragma is equivalent to a corresponding @code{Check_Policy} pragma -with a first argument of @code{Debug}. It is retained for historical -compatibility reasons. - -@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} -@section Pragma Default_Scalar_Storage_Order - - -@geindex Default_Scalar_Storage_Order - -@geindex Scalar_Storage_Order - -Syntax: - -@example -pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); -@end example - -Normally if no explicit @code{Scalar_Storage_Order} is given for a record -type or array type, then the scalar storage order defaults to the ordinary -default for the target. But this default may be overridden using this pragma. -The pragma may appear as a configuration pragma, or locally within a package -spec or declarative part. In the latter case, it applies to all subsequent -types declared within that package spec or declarative part. - -The following example shows the use of this pragma: - -@example -pragma Default_Scalar_Storage_Order (High_Order_First); -with System; use System; -package DSSO1 is - type H1 is record - a : Integer; - end record; - - type L2 is record - a : Integer; - end record; - for L2'Scalar_Storage_Order use Low_Order_First; - - type L2a is new L2; - - package Inner is - type H3 is record - a : Integer; - end record; - - pragma Default_Scalar_Storage_Order (Low_Order_First); - - type L4 is record - a : Integer; - end record; - end Inner; - - type H4a is new Inner.L4; - - type H5 is record - a : Integer; - end record; -end DSSO1; -@end example - -In this example record types with names starting with `L' have @cite{Low_Order_First} scalar -storage order, and record types with names starting with `H' have @code{High_Order_First}. -Note that in the case of @code{H4a}, the order is not inherited -from the parent type. Only an explicitly set @code{Scalar_Storage_Order} -gets inherited on type derivation. - -If this pragma is used as a configuration pragma which appears within a -configuration pragma file (as opposed to appearing explicitly at the start -of a single unit), then the binder will require that all units in a partition -be compiled in a similar manner, other than run-time units, which are not -affected by this pragma. Note that the use of this form is discouraged because -it may significantly degrade the run-time performance of the software, instead -the default scalar storage order ought to be changed only on a local basis. - -@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} -@section Pragma Default_Storage_Pool - - -@geindex Default_Storage_Pool - -Syntax: - -@example -pragma Default_Storage_Pool (storage_pool_NAME | null); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54} -@section Pragma Depends - - -Syntax: - -@example -pragma Depends (DEPENDENCY_RELATION); - -DEPENDENCY_RELATION ::= - null - | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) - -DEPENDENCY_CLAUSE ::= - OUTPUT_LIST =>[+] INPUT_LIST - | NULL_DEPENDENCY_CLAUSE - -NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST - -OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) - -INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) - -OUTPUT ::= NAME | FUNCTION_RESULT -INPUT ::= NAME - -where FUNCTION_RESULT is a function Result attribute_reference -@end example - -For the semantics of this pragma, see the entry for aspect @code{Depends} in the -SPARK 2014 Reference Manual, section 6.1.5. - -@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} -@section Pragma Detect_Blocking - - -Syntax: - -@example -pragma Detect_Blocking; -@end example - -This is a standard pragma in Ada 2005, that is available in all earlier -versions of Ada as an implementation-defined pragma. - -This is a configuration pragma that forces the detection of potentially -blocking operations within a protected operation, and to raise Program_Error -if that happens. - -@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} -@section Pragma Disable_Atomic_Synchronization - - -@geindex Atomic Synchronization - -Syntax: - -@example -pragma Disable_Atomic_Synchronization [(Entity)]; -@end example - -Ada requires that accesses (reads or writes) of an atomic variable be -regarded as synchronization points in the case of multiple tasks. -Particularly in the case of multi-processors this may require special -handling, e.g. the generation of memory barriers. This capability may -be turned off using this pragma in cases where it is known not to be -required. - -The placement and scope rules for this pragma are the same as those -for @code{pragma Suppress}. In particular it can be used as a -configuration pragma, or in a declaration sequence where it applies -till the end of the scope. If an @code{Entity} argument is present, -the action applies only to that entity. - -@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} -@section Pragma Dispatching_Domain - - -Syntax: - -@example -pragma Dispatching_Domain (EXPRESSION); -@end example - -This pragma is standard in Ada 2012, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} -@section Pragma Effective_Reads - - -Syntax: - -@example -pragma Effective_Reads [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} -@section Pragma Effective_Writes - - -Syntax: - -@example -pragma Effective_Writes [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} -in the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} -@section Pragma Elaboration_Checks - - -@geindex Elaboration control - -Syntax: - -@example -pragma Elaboration_Checks (Dynamic | Static); -@end example - -This is a configuration pragma which specifies the elaboration model to be -used during compilation. For more information on the elaboration models of -GNAT, consult the chapter on elaboration order handling in the `GNAT User’s -Guide'. - -The pragma may appear in the following contexts: - - -@itemize * - -@item -Configuration pragmas file - -@item -Prior to the context clauses of a compilation unit’s initial declaration -@end itemize - -Any other placement of the pragma will result in a warning and the effects of -the offending pragma will be ignored. - -If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in -effect. If the pragma argument is @code{Static}, then the static elaboration model -is in effect. - -@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} -@section Pragma Eliminate - - -@geindex Elimination of unused subprograms - -Syntax: - -@example -pragma Eliminate ( - [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , - [ Entity => ] IDENTIFIER | - SELECTED_COMPONENT | - STRING_LITERAL - [, Source_Location => SOURCE_TRACE ] ); - - SOURCE_TRACE ::= STRING_LITERAL -@end example - -This pragma indicates that the given entity is not used in the program to be -compiled and built, thus allowing the compiler to -eliminate the code or data associated with the named entity. Any reference to -an eliminated entity causes a compile-time or link-time error. - -The pragma has the following semantics, where @code{U} is the unit specified by -the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} -argument: - - -@itemize * - -@item -@code{E} must be a subprogram that is explicitly declared either: - - -@itemize * - -@item -Within @code{U}, or - -@item -Within a generic package that is instantiated in @code{U}, or - -@item -As an instance of generic subprogram instantiated in @code{U}. -@end itemize - -Otherwise the pragma is ignored. - -@item -If @code{E} is overloaded within @code{U} then, in the absence of a -@code{Source_Location} argument, all overloadings are eliminated. - -@item -If @code{E} is overloaded within @code{U} and only some overloadings -are to be eliminated, then each overloading to be eliminated -must be specified in a corresponding pragma @code{Eliminate} -with a @code{Source_Location} argument identifying the line where the -declaration appears, as described below. - -@item -If @code{E} is declared as the result of a generic instantiation, then -a @code{Source_Location} argument is needed, as described below. -@end itemize - -Pragma @code{Eliminate} allows a program to be compiled in a system-independent -manner, so that unused entities are eliminated but without -needing to modify the source text. Normally the required set of -@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. - -Any source file change that removes, splits, or -adds lines may make the set of @code{Eliminate} pragmas invalid because their -@code{Source_Location} argument values may get out of date. - -Pragma @code{Eliminate} may be used where the referenced entity is a dispatching -operation. In this case all the subprograms to which the given operation can -dispatch are considered to be unused (are never called as a result of a direct -or a dispatching call). - -The string literal given for the source location specifies the line number -of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: - -@example -SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] - -LBRACKET ::= '[' -RBRACKET ::= ']' - -SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER - -LINE_NUMBER ::= DIGIT @{DIGIT@} -@end example - -Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. - -The source trace that is given as the @code{Source_Location} must obey the -following rules (or else the pragma is ignored), where @code{U} is -the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the -subprogram specified by the @code{Entity} argument: - - -@itemize * - -@item -@code{FILE_NAME} is the short name (with no directory -information) of the Ada source file for @code{U}, using the required syntax -for the underlying file system (e.g. case is significant if the underlying -operating system is case sensitive). -If @code{U} is a package and @code{E} is a subprogram declared in the package -specification and its full declaration appears in the package body, -then the relevant source file is the one for the package specification; -analogously if @code{U} is a generic package. - -@item -If @code{E} is not declared in a generic instantiation (this includes -generic subprogram instances), the source trace includes only one source -line reference. @code{LINE_NUMBER} gives the line number of the occurrence -of the declaration of @code{E} within the source file (as a decimal literal -without an exponent or point). - -@item -If @code{E} is declared by a generic instantiation, its source trace -(from left to right) starts with the source location of the -declaration of @code{E} in the generic unit and ends with the source -location of the instantiation, given in square brackets. This approach is -applied recursively with nested instantiations: the rightmost (nested -most deeply in square brackets) element of the source trace is the location -of the outermost instantiation, and the leftmost element (that is, outside -of any square brackets) is the location of the declaration of @code{E} in -the generic unit. -@end itemize - -Examples: - -@quotation - -@example -pragma Eliminate (Pkg0, Proc); --- Eliminate (all overloadings of) Proc in Pkg0 - -pragma Eliminate (Pkg1, Proc, - Source_Location => "pkg1.ads:8"); --- Eliminate overloading of Proc at line 8 in pkg1.ads - --- Assume the following file contents: --- gen_pkg.ads --- 1: generic --- 2: type T is private; --- 3: package Gen_Pkg is --- 4: procedure Proc(N : T); --- ... ... --- ... end Gen_Pkg; --- --- q.adb --- 1: with Gen_Pkg; --- 2: procedure Q is --- 3: package Inst_Pkg is new Gen_Pkg(Integer); --- ... -- No calls on Inst_Pkg.Proc --- ... end Q; - --- The following pragma eliminates Inst_Pkg.Proc from Q -pragma Eliminate (Q, Proc, - Source_Location => "gen_pkg.ads:4[q.adb:3]"); -@end example -@end quotation - -@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} -@section Pragma Enable_Atomic_Synchronization - - -@geindex Atomic Synchronization - -Syntax: - -@example -pragma Enable_Atomic_Synchronization [(Entity)]; -@end example - -Ada requires that accesses (reads or writes) of an atomic variable be -regarded as synchronization points in the case of multiple tasks. -Particularly in the case of multi-processors this may require special -handling, e.g. the generation of memory barriers. This synchronization -is performed by default, but can be turned off using -@code{pragma Disable_Atomic_Synchronization}. The -@code{Enable_Atomic_Synchronization} pragma can be used to turn -it back on. - -The placement and scope rules for this pragma are the same as those -for @code{pragma Unsuppress}. In particular it can be used as a -configuration pragma, or in a declaration sequence where it applies -till the end of the scope. If an @code{Entity} argument is present, -the action applies only to that entity. - -@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} -@section Pragma Export_Function - - -@geindex Argument passing mechanisms - -Syntax: - -@example -pragma Export_Function ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] result_SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -Use this pragma to make a function externally callable and optionally -provide information on mechanisms to be used for passing parameter and -result values. We recommend, for the purposes of improving portability, -this pragma always be used in conjunction with a separate pragma -@code{Export}, which must precede the pragma @code{Export_Function}. -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is usually -not what is wanted, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. -Pragma @code{Export_Function} -(and @code{Export}, if present) must appear in the same declarative -region as the function to which they apply. - -The @code{internal_name} must uniquely designate the function to which the -pragma applies. If more than one function name exists of this name in -the declarative part you must use the @code{Parameter_Types} and -@code{Result_Type} parameters to achieve the required -unique designation. The @cite{subtype_mark}s in these parameters must -exactly match the subtypes in the corresponding function specification, -using positional notation to match parameters with subtype marks. -The form with an @code{'Access} attribute can be used to match an -anonymous access parameter. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} -@section Pragma Export_Object - - -Syntax: - -@example -pragma Export_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma designates an object as exported, and apart from the -extended rules for external symbols, is identical in effect to the use of -the normal @code{Export} pragma applied to an object. You may use a -separate Export pragma (and you probably should from the point of view -of portability), but it is not required. @code{Size} is syntax checked, -but otherwise ignored by GNAT. - -@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} -@section Pragma Export_Procedure - - -Syntax: - -@example -pragma Export_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Export_Function} except that it -applies to a procedure rather than a function and the parameters -@code{Result_Type} and @code{Result_Mechanism} are not permitted. -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is usually -not what is wanted, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62} -@section Pragma Export_Valued_Procedure - - -Syntax: - -@example -pragma Export_Valued_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -| "" - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Export_Procedure} except that the -first parameter of @code{LOCAL_NAME}, which must be present, must be of -mode @code{out}, and externally the subprogram is treated as a function -with this parameter as the result of the function. GNAT provides for -this capability to allow the use of @code{out} and @code{in out} -parameters in interfacing to external functions (which are not permitted -in Ada functions). -GNAT does not require a separate pragma @code{Export}, but if none is -present, @code{Convention Ada} is assumed, which is almost certainly -not what is wanted since the whole point of this pragma is to interface -with foreign language functions, so it is usually appropriate to use this -pragma in conjunction with a @code{Export} or @code{Convention} -pragma that specifies the desired foreign convention. - -@geindex Suppressing external name - -Special treatment is given if the EXTERNAL is an explicit null -string or a static string expressions that evaluates to the null -string. In this case, no external name is generated. This form -still allows the specification of parameter mechanisms. - -@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63} -@section Pragma Extend_System - - -@geindex System -@geindex extending - -@geindex DEC Ada 83 - -Syntax: - -@example -pragma Extend_System ([Name =>] IDENTIFIER); -@end example - -This pragma is used to provide backwards compatibility with other -implementations that extend the facilities of package @code{System}. In -GNAT, @code{System} contains only the definitions that are present in -the Ada RM. However, other implementations, notably the DEC Ada 83 -implementation, provide many extensions to package @code{System}. - -For each such implementation accommodated by this pragma, GNAT provides a -package @code{Aux_@var{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 -implementation, which provides the required additional definitions. You -can use this package in two ways. You can @code{with} it in the normal -way and access entities either by selection or using a @code{use} -clause. In this case no special processing is required. - -However, if existing code contains references such as -@code{System.@var{xxx}} where `xxx' is an entity in the extended -definitions provided in package @code{System}, you may use this pragma -to extend visibility in @code{System} in a non-standard way that -provides greater compatibility with the existing code. Pragma -@code{Extend_System} is a configuration pragma whose single argument is -the name of the package containing the extended definition -(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under -control of this pragma will be processed using special visibility -processing that looks in package @code{System.Aux_@var{xxx}} where -@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in -package @code{System}, but not found in package @code{System}. - -You can use this pragma either to access a predefined @code{System} -extension supplied with the compiler, for example @code{Aux_DEC} or -you can construct your own extension unit following the above -definition. Note that such a package is a child of @code{System} -and thus is considered part of the implementation. -To compile it you will have to use the `-gnatg' switch -for compiling System units, as explained in the -GNAT User’s Guide. - -@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{64} -@section Pragma Extensions_Allowed - - -@geindex Ada Extensions - -@geindex GNAT Extensions - -Syntax: - -@example -pragma Extensions_Allowed (On | Off | All); -@end example - -This configuration pragma enables (via the “On” or “All” argument) or disables -(via the “Off” argument) the implementation extension mode; the pragma takes -precedence over the `-gnatX' and `-gnatX0' command switches. - -If an argument of “All” is specified, the latest version of the Ada language -is implemented (currently Ada 2022) and, in addition, a number -of GNAT specific extensions are recognized. These extensions are listed -below. An argument of “On” has the same effect except that only -some, not all, of the listed extensions are enabled; those extensions -are identified below. - - -@itemize * - -@item -Constrained attribute for generic objects - -The @code{Constrained} attribute is permitted for objects of -generic types. The result indicates if the corresponding actual -is constrained. - -@item -@code{Static} aspect on intrinsic functions - -The Ada 202x @code{Static} aspect can be specified on Intrinsic imported -functions and the compiler will evaluate some of these intrinsic statically, -in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -@code{[]} aggregates - -This new aggregate syntax for arrays and containers is provided under -gnatX -to experiment and confirm this new language syntax. - -@item -Additional @code{when} constructs - -In addition to the @code{exit when CONDITION} control structure, several -additional constructs are allowed following this format. Including -@code{return when CONDITION}, @code{goto when CONDITION}, and -@code{raise [with EXCEPTION_MESSAGE] when CONDITION.} - -Some examples: - -@example -return Result when Variable > 10; - -raise Program_Error with "Element is null" when Element = null; - -goto End_Of_Subprogram when Variable = -1; -@end example - -@item -Casing on composite values (aka pattern matching) - -The selector for a case statement may be of a composite type, subject to -some restrictions (described below). Aggregate syntax is used for choices -of such a case statement; however, in cases where a “normal” aggregate would -require a discrete value, a discrete subtype may be used instead; box -notation can also be used to match all values. - -Consider this example: - -@example -type Rec is record - F1, F2 : Integer; -end record; - -procedure Caser_1 (X : Rec) is -begin - case X is - when (F1 => Positive, F2 => Positive) => - Do_This; - when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => - Do_That; - when others => - Do_The_Other_Thing; - end case; -end Caser_1; -@end example - -If Caser_1 is called and both components of X are positive, then -Do_This will be called; otherwise, if either component is nonnegative -then Do_That will be called; otherwise, Do_The_Other_Thing will be called. - -If the set of values that match the choice(s) of an earlier alternative -overlaps the corresponding set of a later alternative, then the first -set shall be a proper subset of the second (and the later alternative -will not be executed if the earlier alternative “matches”). All possible -values of the composite type shall be covered. The composite type of the -selector shall be an array or record type that is neither limited -class-wide. Currently, a “when others =>” case choice is required; it is -intended that this requirement will be relaxed at some point. - -If a subcomponent’s subtype does not meet certain restrictions, then -the only value that can be specified for that subcomponent in a case -choice expression is a “box” component association (which matches all -possible values for the subcomponent). This restriction applies if - - -@itemize - - -@item -the component subtype is not a record, array, or discrete type; or - -@item -the component subtype is subject to a non-static constraint or -has a predicate; or - -@item -the component type is an enumeration type that is subject to an -enumeration representation clause; or - -@item -the component type is a multidimensional array type or an -array type with a nonstatic index subtype. -@end itemize - -Support for casing on arrays (and on records that contain arrays) is -currently subject to some restrictions. Non-positional -array aggregates are not supported as (or within) case choices. Likewise -for array type and subtype names. The current implementation exceeds -compile-time capacity limits in some annoyingly common scenarios; the -message generated in such cases is usually “Capacity exceeded in compiling -case statement with composite selector type”. - -In addition, pattern bindings are supported. This is a mechanism -for binding a name to a component of a matching value for use within -an alternative of a case statement. For a component association -that occurs within a case choice, the expression may be followed by -“is ”. In the special case of a “box” component association, -the identifier may instead be provided within the box. Either of these -indicates that the given identifer denotes (a constant view of) the matching -subcomponent of the case selector. Binding is not yet supported for arrays -or subcomponents thereof. - -Consider this example (which uses type Rec from the previous example): - -@example -procedure Caser_2 (X : Rec) is -begin - case X is - when (F1 => Positive is Abc, F2 => Positive) => - Do_This (Abc) - when (F1 => Natural is N1, F2 => ) | - (F1 => , F2 => Natural is N1) => - Do_That (Param_1 => N1, Param_2 => N2); - when others => - Do_The_Other_Thing; - end case; -end Caser_2; -@end example - -This example is the same as the previous one with respect to -determining whether Do_This, Do_That, or Do_The_Other_Thing will -be called. But for this version, Do_This takes a parameter and Do_That -takes two parameters. If Do_This is called, the actual parameter in the -call will be X.F1. - -If Do_That is called, the situation is more complex because there are two -choices for that alternative. If Do_That is called because the first choice -matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero -or negative), then the actual parameters of the call will be (in order) -X.F1 and X.F2. If Do_That is called because the second choice matched (and -the first one did not), then the actual parameters will be reversed. - -Within the choice list for single alternative, each choice must -define the same set of bindings and the component subtypes for -for a given identifer must all statically match. Currently, the case -of a binding for a nondiscrete component is not implemented. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Fixed lower bounds for array types and subtypes - -Unconstrained array types and subtypes can be specified with a lower bound -that is fixed to a certain value, by writing an index range that uses the -syntax “ .. <>”. This guarantees that all objects -of the type or subtype will have the specified lower bound. - -For example, a matrix type with fixed lower bounds of zero for each -dimension can be declared by the following: - -@example -type Matrix is - array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; -@end example - -Objects of type Matrix declared with an index constraint must have index -ranges starting at zero: - -@example -M1 : Matrix (0 .. 9, 0 .. 19); -M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE -@end example - -Similarly, a subtype of String can be declared that specifies the lower -bound of objects of that subtype to be 1: - -@quotation - -@example -subtype String_1 is String (1 .. <>); -@end example -@end quotation - -If a string slice is passed to a formal of subtype String_1 in a call to -a subprogram S, the slice’s bounds will “slide” so that the lower bound -is 1. Within S, the lower bound of the formal is known to be 1, so, unlike -a normal unconstrained String formal, there is no need to worry about -accounting for other possible lower-bound values. Sliding of bounds also -occurs in other contexts, such as for object declarations with an -unconstrained subtype with fixed lower bound, as well as in subtype -conversions. - -Use of this feature increases safety by simplifying code, and can also -improve the efficiency of indexing operations, since the compiler statically -knows the lower bound of unconstrained array formals when the formal’s -subtype has index ranges with static fixed lower bounds. - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Prefixed-view notation for calls to primitive subprograms of untagged types - -Since Ada 2005, calls to primitive subprograms of a tagged type that -have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be -written using the form of a selected_component, with the first actual -parameter given as the prefix and the name of the subprogram as a -selector. This prefixed-view notation for calls is extended so as to -also allow such syntax for calls to primitive subprograms of untagged -types. The primitives of an untagged type T that have a prefixed view -are those where the first formal parameter of the subprogram either -is of type T or is an anonymous access parameter whose designated type -is T. For a type that has a component that happens to have the same -simple name as one of the type’s primitive subprograms, where the -component is visible at the point of a selected_component using that -name, preference is given to the component in a selected_component -(as is currently the case for tagged types with such component names). - -An Extensions_Allowed pragma argument of “On” enables this extension. - -@item -Expression defaults for generic formal functions - -The declaration of a generic formal function is allowed to specify -an expression as a default, using the syntax of an expression function. - -Here is an example of this feature: - -@example -generic - type T is private; - with function Copy (Item : T) return T is (Item); -- Defaults to Item -package Stacks is - - type Stack is limited private; - - procedure Push (S : in out Stack; X : T); -- Calls Copy on X - - function Pop (S : in out Stack) return T; -- Calls Copy to return item - -private - -- ... -end Stacks; -@end example -@end itemize - -@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{65}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{66} -@section Pragma Extensions_Visible - - -Syntax: - -@example -pragma Extensions_Visible [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} -in the SPARK 2014 Reference Manual, section 6.1.7. - -@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{67} -@section Pragma External - - -Syntax: - -@example -pragma External ( - [ Convention =>] convention_IDENTIFIER, - [ Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); -@end example - -This pragma is identical in syntax and semantics to pragma -@code{Export} as defined in the Ada Reference Manual. It is -provided for compatibility with some Ada 83 compilers that -used this pragma for exactly the same purposes as pragma -@code{Export} before the latter was standardized. - -@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{68} -@section Pragma External_Name_Casing - - -@geindex Dec Ada 83 casing compatibility - -@geindex External Names -@geindex casing - -@geindex Casing of External names - -Syntax: - -@example -pragma External_Name_Casing ( - Uppercase | Lowercase - [, Uppercase | Lowercase | As_Is]); -@end example - -This pragma provides control over the casing of external names associated -with Import and Export pragmas. There are two cases to consider: - - -@itemize * - -@item -Implicit external names - -Implicit external names are derived from identifiers. The most common case -arises when a standard Ada Import or Export pragma is used with only two -arguments, as in: - -@example -pragma Import (C, C_Routine); -@end example - -Since Ada is a case-insensitive language, the spelling of the identifier in -the Ada source program does not provide any information on the desired -casing of the external name, and so a convention is needed. In GNAT the -default treatment is that such names are converted to all lower case -letters. This corresponds to the normal C style in many environments. -The first argument of pragma @code{External_Name_Casing} can be used to -control this treatment. If @code{Uppercase} is specified, then the name -will be forced to all uppercase letters. If @code{Lowercase} is specified, -then the normal default of all lower case letters will be used. - -This same implicit treatment is also used in the case of extended DEC Ada 83 -compatible Import and Export pragmas where an external name is explicitly -specified using an identifier rather than a string. - -@item -Explicit external names - -Explicit external names are given as string literals. The most common case -arises when a standard Ada Import or Export pragma is used with three -arguments, as in: - -@example -pragma Import (C, C_Routine, "C_routine"); -@end example - -In this case, the string literal normally provides the exact casing required -for the external name. The second argument of pragma -@code{External_Name_Casing} may be used to modify this behavior. -If @code{Uppercase} is specified, then the name -will be forced to all uppercase letters. If @code{Lowercase} is specified, -then the name will be forced to all lowercase letters. A specification of -@code{As_Is} provides the normal default behavior in which the casing is -taken from the string provided. -@end itemize - -This pragma may appear anywhere that a pragma is valid. In particular, it -can be used as a configuration pragma in the @code{gnat.adc} file, in which -case it applies to all subsequent compilations, or it can be used as a program -unit pragma, in which case it only applies to the current unit, or it can -be used more locally to control individual Import/Export pragmas. - -It was primarily intended for use with OpenVMS systems, where many -compilers convert all symbols to upper case by default. For interfacing to -such compilers (e.g., the DEC C compiler), it may be convenient to use -the pragma: - -@example -pragma External_Name_Casing (Uppercase, Uppercase); -@end example - -to enforce the upper casing of all external symbols. - -@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{69} -@section Pragma Fast_Math - - -Syntax: - -@example -pragma Fast_Math; -@end example - -This is a configuration pragma which activates a mode in which speed is -considered more important for floating-point operations than absolutely -accurate adherence to the requirements of the standard. Currently the -following operations are affected: - - -@table @asis - -@item `Complex Multiplication' - -The normal simple formula for complex multiplication can result in intermediate -overflows for numbers near the end of the range. The Ada standard requires that -this situation be detected and corrected by scaling, but in Fast_Math mode such -cases will simply result in overflow. Note that to take advantage of this you -must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} -under control of the pragma, rather than use the preinstantiated versions. -@end table - -@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6a}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6b} -@section Pragma Favor_Top_Level - - -Syntax: - -@example -pragma Favor_Top_Level (type_NAME); -@end example - -The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram -type. This pragma is an efficiency hint to the compiler, regarding the use of -@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. -The pragma means that nested subprograms are not used with this type, or are -rare, so that the generated code should be efficient in the top-level case. -When this pragma is used, dynamically generated trampolines may be used on some -targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. - -@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6c} -@section Pragma Finalize_Storage_Only - - -Syntax: - -@example -pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); -@end example - -The argument of pragma @code{Finalize_Storage_Only} must denote a local type which -is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The -pragma suppresses the call to @code{Finalize} for declared library-level objects -of the argument type. This is mostly useful for types where finalization is -only used to deal with storage reclamation since in most environments it is -not necessary to reclaim memory just before terminating execution, hence the -name. Note that this pragma does not suppress Finalize calls for library-level -heap-allocated objects (see pragma @code{No_Heap_Finalization}). - -@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6d} -@section Pragma Float_Representation - - -Syntax: - -@example -pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); - -FLOAT_REP ::= VAX_Float | IEEE_Float -@end example - -In the one argument form, this pragma is a configuration pragma which -allows control over the internal representation chosen for the predefined -floating point types declared in the packages @code{Standard} and -@code{System}. This pragma is only provided for compatibility and has no effect. - -The two argument form specifies the representation to be used for -the specified floating-point type. The argument must -be @code{IEEE_Float} to specify the use of IEEE format, as follows: - - -@itemize * - -@item -For a digits value of 6, 32-bit IEEE short format will be used. - -@item -For a digits value of 15, 64-bit IEEE long format will be used. - -@item -No other value of digits is permitted. -@end itemize - -@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6f} -@section Pragma Ghost - - -Syntax: - -@example -pragma Ghost [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK -2014 Reference Manual, section 6.9. - -@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{70}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{71} -@section Pragma Global - - -Syntax: - -@example -pragma Global (GLOBAL_SPECIFICATION); - -GLOBAL_SPECIFICATION ::= - null - | (GLOBAL_LIST) - | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) - -MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST - -MODE_SELECTOR ::= In_Out | Input | Output | Proof_In -GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) -GLOBAL_ITEM ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Global} in the -SPARK 2014 Reference Manual, section 6.1.4. - -@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{72} -@section Pragma Ident - - -Syntax: - -@example -pragma Ident (static_string_EXPRESSION); -@end example - -This pragma is identical in effect to pragma @code{Comment}. It is provided -for compatibility with other Ada compilers providing this pragma. - -@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{73} -@section Pragma Ignore_Pragma - - -Syntax: - -@example -pragma Ignore_Pragma (pragma_IDENTIFIER); -@end example - -This is a configuration pragma -that takes a single argument that is a simple identifier. Any subsequent -use of a pragma whose pragma identifier matches this argument will be -silently ignored. This may be useful when legacy code or code intended -for compilation with some other compiler contains pragmas that match the -name, but not the exact implementation, of a GNAT pragma. The use of this -pragma allows such pragmas to be ignored, which may be useful in CodePeer -mode, or during porting of legacy code. - -@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{74} -@section Pragma Implementation_Defined - - -Syntax: - -@example -pragma Implementation_Defined (local_NAME); -@end example - -This pragma marks a previously declared entity as implementation-defined. -For an overloaded entity, applies to the most recent homonym. - -@example -pragma Implementation_Defined; -@end example - -The form with no arguments appears anywhere within a scope, most -typically a package spec, and indicates that all entities that are -defined within the package spec are Implementation_Defined. - -This pragma is used within the GNAT runtime library to identify -implementation-defined entities introduced in language-defined units, -for the purpose of implementing the No_Implementation_Identifiers -restriction. - -@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{75} -@section Pragma Implemented - - -Syntax: - -@example -pragma Implemented (procedure_LOCAL_NAME, implementation_kind); - -implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any -@end example - -This is an Ada 2012 representation pragma which applies to protected, task -and synchronized interface primitives. The use of pragma Implemented provides -a way to impose a static requirement on the overriding operation by adhering -to one of the three implementation kinds: entry, protected procedure or any of -the above. This pragma is available in all earlier versions of Ada as an -implementation-defined pragma. - -@example -type Synch_Iface is synchronized interface; -procedure Prim_Op (Obj : in out Iface) is abstract; -pragma Implemented (Prim_Op, By_Protected_Procedure); - -protected type Prot_1 is new Synch_Iface with - procedure Prim_Op; -- Legal -end Prot_1; - -protected type Prot_2 is new Synch_Iface with - entry Prim_Op; -- Illegal -end Prot_2; - -task type Task_Typ is new Synch_Iface with - entry Prim_Op; -- Illegal -end Task_Typ; -@end example - -When applied to the procedure_or_entry_NAME of a requeue statement, pragma -Implemented determines the runtime behavior of the requeue. Implementation kind -By_Entry guarantees that the action of requeueing will proceed from an entry to -another entry. Implementation kind By_Protected_Procedure transforms the -requeue into a dispatching call, thus eliminating the chance of blocking. Kind -By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on -the target’s overriding subprogram kind. - -@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{76} -@section Pragma Implicit_Packing - - -@geindex Rational Profile - -Syntax: - -@example -pragma Implicit_Packing; -@end example - -This is a configuration pragma that requests implicit packing for packed -arrays for which a size clause is given but no explicit pragma Pack or -specification of Component_Size is present. It also applies to records -where no record representation clause is present. Consider this example: - -@example -type R is array (0 .. 7) of Boolean; -for R'Size use 8; -@end example - -In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause -does not change the layout of a composite object. So the Size clause in the -above example is normally rejected, since the default layout of the array uses -8-bit components, and thus the array requires a minimum of 64 bits. - -If this declaration is compiled in a region of code covered by an occurrence -of the configuration pragma Implicit_Packing, then the Size clause in this -and similar examples will cause implicit packing and thus be accepted. For -this implicit packing to occur, the type in question must be an array of small -components whose size is known at compile time, and the Size clause must -specify the exact size that corresponds to the number of elements in the array -multiplied by the size in bits of the component type (both single and -multi-dimensioned arrays can be controlled with this pragma). - -@geindex Array packing - -Similarly, the following example shows the use in the record case - -@example -type r is record - a, b, c, d, e, f, g, h : boolean; - chr : character; -end record; -for r'size use 16; -@end example - -Without a pragma Pack, each Boolean field requires 8 bits, so the -minimum size is 72 bits, but with a pragma Pack, 16 bits would be -sufficient. The use of pragma Implicit_Packing allows this record -declaration to compile without an explicit pragma Pack. - -@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{77} -@section Pragma Import_Function - - -Syntax: - -@example -pragma Import_Function ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= - Value -| Reference -@end example - -This pragma is used in conjunction with a pragma @code{Import} to -specify additional information for an imported function. The pragma -@code{Import} (or equivalent pragma @code{Interface}) must precede the -@code{Import_Function} pragma and both must appear in the same -declarative part as the function specification. - -The @code{Internal} argument must uniquely designate -the function to which the -pragma applies. If more than one function name exists of this name in -the declarative part you must use the @code{Parameter_Types} and -@code{Result_Type} parameters to achieve the required unique -designation. Subtype marks in these parameters must exactly match the -subtypes in the corresponding function specification, using positional -notation to match parameters with subtype marks. -The form with an @code{'Access} attribute can be used to match an -anonymous access parameter. - -You may optionally use the @code{Mechanism} and @code{Result_Mechanism} -parameters to specify passing mechanisms for the -parameters and result. If you specify a single mechanism name, it -applies to all parameters. Otherwise you may specify a mechanism on a -parameter by parameter basis using either positional or named -notation. If the mechanism is not specified, the default mechanism -is used. - -@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{78} -@section Pragma Import_Object - - -Syntax: - -@example -pragma Import_Object ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma designates an object as imported, and apart from the -extended rules for external symbols, is identical in effect to the use of -the normal @code{Import} pragma applied to an object. Unlike the -subprogram case, you need not use a separate @code{Import} pragma, -although you may do so (and probably should do so from a portability -point of view). @code{size} is syntax checked, but otherwise ignored by -GNAT. - -@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{79} -@section Pragma Import_Procedure - - -Syntax: - -@example -pragma Import_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Import_Function} except that it -applies to a procedure rather than a function and the parameters -@code{Result_Type} and @code{Result_Mechanism} are not permitted. - -@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7a} -@section Pragma Import_Valued_Procedure - - -Syntax: - -@example -pragma Import_Valued_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} - -TYPE_DESIGNATOR ::= - subtype_NAME -| subtype_Name ' Access - -MECHANISM ::= - MECHANISM_NAME -| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) - -MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - -MECHANISM_NAME ::= Value | Reference -@end example - -This pragma is identical to @code{Import_Procedure} except that the -first parameter of @code{LOCAL_NAME}, which must be present, must be of -mode @code{out}, and externally the subprogram is treated as a function -with this parameter as the result of the function. The purpose of this -capability is to allow the use of @code{out} and @code{in out} -parameters in interfacing to external functions (which are not permitted -in Ada functions). You may optionally use the @code{Mechanism} -parameters to specify passing mechanisms for the parameters. -If you specify a single mechanism name, it applies to all parameters. -Otherwise you may specify a mechanism on a parameter by parameter -basis using either positional or named notation. If the mechanism is not -specified, the default mechanism is used. - -Note that it is important to use this pragma in conjunction with a separate -pragma Import that specifies the desired convention, since otherwise the -default convention is Ada, which is almost certainly not what is required. - -@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7b} -@section Pragma Independent - - -Syntax: - -@example -pragma Independent (Local_NAME); -@end example - -This pragma is standard in Ada 2012 mode (which also provides an aspect -of the same name). It is also available as an implementation-defined -pragma in all earlier versions. It specifies that the -designated object or all objects of the designated type must be -independently addressable. This means that separate tasks can safely -manipulate such objects. For example, if two components of a record are -independent, then two separate tasks may access these two components. -This may place -constraints on the representation of the object (for instance prohibiting -tight packing). - -@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7c} -@section Pragma Independent_Components - - -Syntax: - -@example -pragma Independent_Components (Local_NAME); -@end example - -This pragma is standard in Ada 2012 mode (which also provides an aspect -of the same name). It is also available as an implementation-defined -pragma in all earlier versions. It specifies that the components of the -designated object, or the components of each object of the designated -type, must be -independently addressable. This means that separate tasks can safely -manipulate separate components in the composite object. This may place -constraints on the representation of the object (for instance prohibiting -tight packing). - -@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7d}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7e} -@section Pragma Initial_Condition - - -Syntax: - -@example -pragma Initial_Condition (boolean_EXPRESSION); -@end example - -For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} -in the SPARK 2014 Reference Manual, section 7.1.6. - -@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{7f} -@section Pragma Initialize_Scalars - - -@geindex debugging with Initialize_Scalars - -Syntax: - -@example -pragma Initialize_Scalars - [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; - -TYPE_VALUE_PAIR ::= - SCALAR_TYPE => static_EXPRESSION - -SCALAR_TYPE := - Short_Float -| Float -| Long_Float -| Long_Long_Flat -| Signed_8 -| Signed_16 -| Signed_32 -| Signed_64 -| Unsigned_8 -| Unsigned_16 -| Unsigned_32 -| Unsigned_64 -@end example - -This pragma is similar to @code{Normalize_Scalars} conceptually but has two -important differences. - -First, there is no requirement for the pragma to be used uniformly in all units -of a partition. In particular, it is fine to use this just for some or all of -the application units of a partition, without needing to recompile the run-time -library. In the case where some units are compiled with the pragma, and some -without, then a declaration of a variable where the type is defined in package -Standard or is locally declared will always be subject to initialization, as -will any declaration of a scalar variable. For composite variables, whether the -variable is initialized may also depend on whether the package in which the -type of the variable is declared is compiled with the pragma. - -The other important difference is that the programmer can control the value -used for initializing scalar objects. This effect can be achieved in several -different ways: - - -@itemize * - -@item -At compile time, the programmer can specify the invalid value for a -particular family of scalar types using the optional arguments of the pragma. - -The compile-time approach is intended to optimize the generated code for the -pragma, by possibly using fast operations such as @code{memset}. Note that such -optimizations require using values where the bytes all have the same binary -representation. - -@item -At bind time, the programmer has several options: - - -@itemize * - -@item -Initialization with invalid values (similar to Normalize_Scalars, though -for Initialize_Scalars it is not always possible to determine the invalid -values in complex cases like signed component fields with nonstandard -sizes). - -@item -Initialization with high values. - -@item -Initialization with low values. - -@item -Initialization with a specific bit pattern. -@end itemize - -See the GNAT User’s Guide for binder options for specifying these cases. - -The bind-time approach is intended to provide fast turnaround for testing -with different values, without having to recompile the program. - -@item -At execution time, the programmer can specify the invalid values using an -environment variable. See the GNAT User’s Guide for details. - -The execution-time approach is intended to provide fast turnaround for -testing with different values, without having to recompile and rebind the -program. -@end itemize - -Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction -with the enhanced validity checking that is now provided in GNAT, which checks -for invalid values under more conditions. Using this feature (see description -of the `-gnatV' flag in the GNAT User’s Guide) in conjunction with pragma -@code{Initialize_Scalars} provides a powerful new tool to assist in the detection -of problems caused by uninitialized variables. - -Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the -generated code. This may cause your code to be substantially larger. It may -also cause an increase in the amount of stack required, so it is probably a -good idea to turn on stack checking (see description of stack checking in the -GNAT User’s Guide) when using this pragma. - -@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{81} -@section Pragma Initializes - - -Syntax: - -@example -pragma Initializes (INITIALIZATION_LIST); - -INITIALIZATION_LIST ::= - null - | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) - -INITIALIZATION_ITEM ::= name [=> INPUT_LIST] - -INPUT_LIST ::= - null - | INPUT - | (INPUT @{, INPUT@}) - -INPUT ::= name -@end example - -For the semantics of this pragma, see the entry for aspect @code{Initializes} in the -SPARK 2014 Reference Manual, section 7.1.5. - -@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{82}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{83} -@section Pragma Inline_Always - - -Syntax: - -@example -pragma Inline_Always (NAME [, NAME]); -@end example - -Similar to pragma @code{Inline} except that inlining is unconditional. -Inline_Always instructs the compiler to inline every direct call to the -subprogram or else to emit a compilation error, independently of any -option, in particular `-gnatn' or `-gnatN' or the optimization level. -It is an error to take the address or access of @code{NAME}. It is also an error to -apply this pragma to a primitive operation of a tagged type. Thanks to such -restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. - -@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{84} -@section Pragma Inline_Generic - - -Syntax: - -@example -pragma Inline_Generic (GNAME @{, GNAME@}); - -GNAME ::= generic_unit_NAME | generic_instance_NAME -@end example - -This pragma is provided for compatibility with Dec Ada 83. It has -no effect in GNAT (which always inlines generics), other -than to check that the given names are all names of generic units or -generic instances. - -@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{85} -@section Pragma Interface - - -Syntax: - -@example -pragma Interface ( - [Convention =>] convention_identifier, - [Entity =>] local_NAME - [, [External_Name =>] static_string_expression] - [, [Link_Name =>] static_string_expression]); -@end example - -This pragma is identical in syntax and semantics to -the standard Ada pragma @code{Import}. It is provided for compatibility -with Ada 83. The definition is upwards compatible both with pragma -@code{Interface} as defined in the Ada 83 Reference Manual, and also -with some extended implementations of this pragma in certain Ada 83 -implementations. The only difference between pragma @code{Interface} -and pragma @code{Import} is that there is special circuitry to allow -both pragmas to appear for the same subprogram entity (normally it -is illegal to have multiple @code{Import} pragmas). This is useful in -maintaining Ada 83/Ada 95 compatibility and is compatible with other -Ada 83 compilers. - -@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{86} -@section Pragma Interface_Name - - -Syntax: - -@example -pragma Interface_Name ( - [Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION] - [, [Link_Name =>] static_string_EXPRESSION]); -@end example - -This pragma provides an alternative way of specifying the interface name -for an interfaced subprogram, and is provided for compatibility with Ada -83 compilers that use the pragma for this purpose. You must provide at -least one of @code{External_Name} or @code{Link_Name}. - -@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{87} -@section Pragma Interrupt_Handler - - -Syntax: - -@example -pragma Interrupt_Handler (procedure_LOCAL_NAME); -@end example - -This program unit pragma is supported for parameterless protected procedures -as described in Annex C of the Ada Reference Manual. - -@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{88} -@section Pragma Interrupt_State - - -Syntax: - -@example -pragma Interrupt_State - ([Name =>] value, - [State =>] SYSTEM | RUNTIME | USER); -@end example - -Normally certain interrupts are reserved to the implementation. Any attempt -to attach an interrupt causes Program_Error to be raised, as described in -RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in -many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is -reserved to the implementation, so that @code{Ctrl-C} can be used to -interrupt execution. Additionally, signals such as @code{SIGSEGV}, -@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific -Ada exceptions, or used to implement run-time functions such as the -@code{abort} statement and stack overflow checking. - -Pragma @code{Interrupt_State} provides a general mechanism for overriding -such uses of interrupts. It subsumes the functionality of pragma -@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not -available on Windows. On all other platforms than VxWorks, -it applies to signals; on VxWorks, it applies to vectored hardware interrupts -and may be used to mark interrupts required by the board support package -as reserved. - -Interrupts can be in one of three states: - - -@itemize * - -@item -System - -The interrupt is reserved (no Ada handler can be installed), and the -Ada run-time may not install a handler. As a result you are guaranteed -standard system default action if this interrupt is raised. This also allows -installing a low level handler via C APIs such as sigaction(), outside -of Ada control. - -@item -Runtime - -The interrupt is reserved (no Ada handler can be installed). The run time -is allowed to install a handler for internal control purposes, but is -not required to do so. - -@item -User - -The interrupt is unreserved. The user may install an Ada handler via -Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide -some other action. -@end itemize - -These states are the allowed values of the @code{State} parameter of the -pragma. The @code{Name} parameter is a value of the type -@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in -@code{Ada.Interrupts.Names}. - -This is a configuration pragma, and the binder will check that there -are no inconsistencies between different units in a partition in how a -given interrupt is specified. It may appear anywhere a pragma is legal. - -The effect is to move the interrupt to the specified state. - -By declaring interrupts to be SYSTEM, you guarantee the standard system -action, such as a core dump. - -By declaring interrupts to be USER, you guarantee that you can install -a handler. - -Note that certain signals on many operating systems cannot be caught and -handled by applications. In such cases, the pragma is ignored. See the -operating system documentation, or the value of the array @code{Reserved} -declared in the spec of package @code{System.OS_Interface}. - -Overriding the default state of signals used by the Ada runtime may interfere -with an application’s runtime behavior in the cases of the synchronous signals, -and in the case of the signal used to implement the @code{abort} statement. - -@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{89}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8a} -@section Pragma Invariant - - -Syntax: - -@example -pragma Invariant - ([Entity =>] private_type_LOCAL_NAME, - [Check =>] EXPRESSION - [,[Message =>] String_Expression]); -@end example - -This pragma provides exactly the same capabilities as the Type_Invariant aspect -defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The -Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it -requires the use of the aspect syntax, which is not available except in 2012 -mode, it is not possible to use the Type_Invariant aspect in earlier versions -of Ada. However the Invariant pragma may be used in any version of Ada. Also -note that the aspect Invariant is a synonym in GNAT for the aspect -Type_Invariant, but there is no pragma Type_Invariant. - -The pragma must appear within the visible part of the package specification, -after the type to which its Entity argument appears. As with the Invariant -aspect, the Check expression is not analyzed until the end of the visible -part of the package, so it may contain forward references. The Message -argument, if present, provides the exception message used if the invariant -is violated. If no Message parameter is provided, a default message that -identifies the line on which the pragma appears is used. - -It is permissible to have multiple Invariants for the same type entity, in -which case they are and’ed together. It is permissible to use this pragma -in Ada 2012 mode, but you cannot have both an invariant aspect and an -invariant pragma for the same entity. - -For further details on the use of this pragma, see the Ada 2012 documentation -of the Type_Invariant aspect. - -@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8b} -@section Pragma Keep_Names - - -Syntax: - -@example -pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); -@end example - -The @code{LOCAL_NAME} argument -must refer to an enumeration first subtype -in the current declarative part. The effect is to retain the enumeration -literal names for use by @code{Image} and @code{Value} even if a global -@code{Discard_Names} pragma applies. This is useful when you want to -generally suppress enumeration literal names and for example you therefore -use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you -want to retain the names for specific enumeration types. - -@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8c} -@section Pragma License - - -@geindex License checking - -Syntax: - -@example -pragma License (Unrestricted | GPL | Modified_GPL | Restricted); -@end example - -This pragma is provided to allow automated checking for appropriate license -conditions with respect to the standard and modified GPL. A pragma -@code{License}, which is a configuration pragma that typically appears at -the start of a source file or in a separate @code{gnat.adc} file, specifies -the licensing conditions of a unit as follows: - - -@itemize * - -@item -Unrestricted -This is used for a unit that can be freely used with no license restrictions. -Examples of such units are public domain units, and units from the Ada -Reference Manual. - -@item -GPL -This is used for a unit that is licensed under the unmodified GPL, and which -therefore cannot be @code{with}ed by a restricted unit. - -@item -Modified_GPL -This is used for a unit licensed under the GNAT modified GPL that includes -a special exception paragraph that specifically permits the inclusion of -the unit in programs without requiring the entire program to be released -under the GPL. - -@item -Restricted -This is used for a unit that is restricted in that it is not permitted to -depend on units that are licensed under the GPL. Typical examples are -proprietary code that is to be released under more restrictive license -conditions. Note that restricted units are permitted to @code{with} units -which are licensed under the modified GPL (this is the whole point of the -modified GPL). -@end itemize - -Normally a unit with no @code{License} pragma is considered to have an -unknown license, and no checking is done. However, standard GNAT headers -are recognized, and license information is derived from them as follows. - -A GNAT license header starts with a line containing 78 hyphens. The following -comment text is searched for the appearance of any of the following strings. - -If the string ‘GNU General Public License’ is found, then the unit is assumed -to have GPL license, unless the string ‘As a special exception’ follows, in -which case the license is assumed to be modified GPL. - -If one of the strings -‘This specification is adapted from the Ada Semantic Interface’ or -‘This specification is derived from the Ada Reference Manual’ is found -then the unit is assumed to be unrestricted. - -These default actions means that a program with a restricted license pragma -will automatically get warnings if a GPL unit is inappropriately -@code{with}ed. For example, the program: - -@example -with Sem_Ch3; -with GNAT.Sockets; -procedure Secret_Stuff is - ... -end Secret_Stuff -@end example - -if compiled with pragma @code{License} (@code{Restricted}) in a -@code{gnat.adc} file will generate the warning: - -@example -1. with Sem_Ch3; - | - >>> license of withed unit "Sem_Ch3" is incompatible - -2. with GNAT.Sockets; -3. procedure Secret_Stuff is -@end example - -Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT -compiler and is licensed under the -GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT -run time, and is therefore licensed under the modified GPL. - -@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8d} -@section Pragma Link_With - - -Syntax: - -@example -pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); -@end example - -This pragma is provided for compatibility with certain Ada 83 compilers. -It has exactly the same effect as pragma @code{Linker_Options} except -that spaces occurring within one of the string expressions are treated -as separators. For example, in the following case: - -@example -pragma Link_With ("-labc -ldef"); -@end example - -results in passing the strings @code{-labc} and @code{-ldef} as two -separate arguments to the linker. In addition pragma Link_With allows -multiple arguments, with the same effect as successive pragmas. - -@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8e} -@section Pragma Linker_Alias - - -Syntax: - -@example -pragma Linker_Alias ( - [Entity =>] LOCAL_NAME, - [Target =>] static_string_EXPRESSION); -@end example - -@code{LOCAL_NAME} must refer to an object that is declared at the library -level. This pragma establishes the given entity as a linker alias for the -given target. It is equivalent to @code{__attribute__((alias))} in GNU C -and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol -@code{static_string_EXPRESSION} in the object file, that is to say no space -is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved -to the same address as @code{static_string_EXPRESSION} by the linker. - -The actual linker name for the target must be used (e.g., the fully -encoded name with qualification in Ada, or the mangled name in C++), -or it must be declared using the C convention with @code{pragma Import} -or @code{pragma Export}. - -Not all target machines support this pragma. On some of them it is accepted -only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. - -@example --- Example of the use of pragma Linker_Alias - -package p is - i : Integer := 1; - pragma Export (C, i); - - new_name_for_i : Integer; - pragma Linker_Alias (new_name_for_i, "i"); -end p; -@end example - -@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{8f} -@section Pragma Linker_Constructor - - -Syntax: - -@example -pragma Linker_Constructor (procedure_LOCAL_NAME); -@end example - -@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that -is declared at the library level. A procedure to which this pragma is -applied will be treated as an initialization routine by the linker. -It is equivalent to @code{__attribute__((constructor))} in GNU C and -causes @code{procedure_LOCAL_NAME} to be invoked before the entry point -of the executable is called (or immediately after the shared library is -loaded if the procedure is linked in a shared library), in particular -before the Ada run-time environment is set up. - -Because of these specific contexts, the set of operations such a procedure -can perform is very limited and the type of objects it can manipulate is -essentially restricted to the elementary types. In particular, it must only -contain code to which pragma Restrictions (No_Elaboration_Code) applies. - -This pragma is used by GNAT to implement auto-initialization of shared Stand -Alone Libraries, which provides a related capability without the restrictions -listed above. Where possible, the use of Stand Alone Libraries is preferable -to the use of this pragma. - -@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{90} -@section Pragma Linker_Destructor - - -Syntax: - -@example -pragma Linker_Destructor (procedure_LOCAL_NAME); -@end example - -@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that -is declared at the library level. A procedure to which this pragma is -applied will be treated as a finalization routine by the linker. -It is equivalent to @code{__attribute__((destructor))} in GNU C and -causes @code{procedure_LOCAL_NAME} to be invoked after the entry point -of the executable has exited (or immediately before the shared library -is unloaded if the procedure is linked in a shared library), in particular -after the Ada run-time environment is shut down. - -See @code{pragma Linker_Constructor} for the set of restrictions that apply -because of these specific contexts. - -@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{91}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{92} -@section Pragma Linker_Section - - -Syntax: - -@example -pragma Linker_Section ( - [Entity =>] LOCAL_NAME, - [Section =>] static_string_EXPRESSION); -@end example - -@code{LOCAL_NAME} must refer to an object, type, or subprogram that is -declared at the library level. This pragma specifies the name of the -linker section for the given entity. It is equivalent to -@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to -be placed in the @code{static_string_EXPRESSION} section of the -executable (assuming the linker doesn’t rename the section). -GNAT also provides an implementation defined aspect of the same name. - -In the case of specifying this aspect for a type, the effect is to -specify the corresponding section for all library-level objects of -the type that do not have an explicit linker section set. Note that -this only applies to whole objects, not to components of composite objects. - -In the case of a subprogram, the linker section applies to all previously -declared matching overloaded subprograms in the current declarative part -which do not already have a linker section assigned. The linker section -aspect is useful in this case for specifying different linker sections -for different elements of such an overloaded set. - -Note that an empty string specifies that no linker section is specified. -This is not quite the same as omitting the pragma or aspect, since it -can be used to specify that one element of an overloaded set of subprograms -has the default linker section, or that one object of a type for which a -linker section is specified should has the default linker section. - -The compiler normally places library-level entities in standard sections -depending on the class: procedures and functions generally go in the -@code{.text} section, initialized variables in the @code{.data} section -and uninitialized variables in the @code{.bss} section. - -Other, special sections may exist on given target machines to map special -hardware, for example I/O ports or flash memory. This pragma is a means to -defer the final layout of the executable to the linker, thus fully working -at the symbolic level with the compiler. - -Some file formats do not support arbitrary sections so not all target -machines support this pragma. The use of this pragma may cause a program -execution to be erroneous if it is used to place an entity into an -inappropriate section (e.g., a modified variable into the @code{.text} -section). See also @code{pragma Persistent_BSS}. - -@example --- Example of the use of pragma Linker_Section - -package IO_Card is - Port_A : Integer; - pragma Volatile (Port_A); - pragma Linker_Section (Port_A, ".bss.port_a"); - - Port_B : Integer; - pragma Volatile (Port_B); - pragma Linker_Section (Port_B, ".bss.port_b"); - - type Port_Type is new Integer with Linker_Section => ".bss"; - PA : Port_Type with Linker_Section => ".bss.PA"; - PB : Port_Type; -- ends up in linker section ".bss" - - procedure Q with Linker_Section => "Qsection"; -end IO_Card; -@end example - -@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{93}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{94} -@section Pragma Lock_Free - - -Syntax: -This pragma may be specified for protected types or objects. It specifies that -the implementation of protected operations must be implemented without locks. -Compilation fails if the compiler cannot generate lock-free code for the -operations. - -The current conditions required to support this pragma are: - - -@itemize * - -@item -Protected type declarations may not contain entries - -@item -Protected subprogram declarations may not have nonelementary parameters -@end itemize - -In addition, each protected subprogram body must satisfy: - - -@itemize * - -@item -May reference only one protected component - -@item -May not reference nonconstant entities outside the protected subprogram -scope - -@item -May not contain address representation items, allocators, or quantified -expressions - -@item -May not contain delay, goto, loop, or procedure-call statements - -@item -May not contain exported and imported entities - -@item -May not dereferenced access values - -@item -Function calls and attribute references must be static -@end itemize - -If the Lock_Free aspect is specified to be True for a protected unit -and the Ceiling_Locking locking policy is in effect, then the run-time -actions associated with the Ceiling_Locking locking policy (described in -Ada RM D.3) are not performed when a protected operation of the protected -unit is executed. - -@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{95} -@section Pragma Loop_Invariant - - -Syntax: - -@example -pragma Loop_Invariant ( boolean_EXPRESSION ); -@end example - -The effect of this pragma is similar to that of pragma @code{Assert}, -except that in an @code{Assertion_Policy} pragma, the identifier -@code{Loop_Invariant} is used to control whether it is ignored or checked -(or disabled). - -@code{Loop_Invariant} can only appear as one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -The intention is that it be used to -represent a “loop invariant” assertion, i.e. something that is true each -time through the loop, and which can be used to show that the loop is -achieving its purpose. - -Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that -apply to the same loop should be grouped in the same sequence of -statements. - -To aid in writing such invariants, the special attribute @code{Loop_Entry} -may be used to refer to the value of an expression on entry to the loop. This -attribute can only be used within the expression of a @code{Loop_Invariant} -pragma. For full details, see documentation of attribute @code{Loop_Entry}. - -@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{96} -@section Pragma Loop_Optimize - - -Syntax: - -@example -pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); - -OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector -@end example - -This pragma must appear immediately within a loop statement. It allows the -programmer to specify optimization hints for the enclosing loop. The hints -are not mutually exclusive and can be freely mixed, but not all combinations -will yield a sensible outcome. - -There are five supported optimization hints for a loop: - - -@itemize * - -@item -Ivdep - -The programmer asserts that there are no loop-carried dependencies -which would prevent consecutive iterations of the loop from being -executed simultaneously. - -@item -No_Unroll - -The loop must not be unrolled. This is a strong hint: the compiler will not -unroll a loop marked with this hint. - -@item -Unroll - -The loop should be unrolled. This is a weak hint: the compiler will try to -apply unrolling to this loop preferably to other optimizations, notably -vectorization, but there is no guarantee that the loop will be unrolled. - -@item -No_Vector - -The loop must not be vectorized. This is a strong hint: the compiler will not -vectorize a loop marked with this hint. - -@item -Vector - -The loop should be vectorized. This is a weak hint: the compiler will try to -apply vectorization to this loop preferably to other optimizations, notably -unrolling, but there is no guarantee that the loop will be vectorized. -@end itemize - -These hints do not remove the need to pass the appropriate switches to the -compiler in order to enable the relevant optimizations, that is to say -`-funroll-loops' for unrolling and `-ftree-vectorize' for -vectorization. - -@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{97} -@section Pragma Loop_Variant - - -Syntax: - -@example -pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); -LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION -CHANGE_DIRECTION ::= Increases | Decreases -@end example - -@code{Loop_Variant} can only appear as one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -It allows the specification of quantities which must always -decrease or increase in successive iterations of the loop. In its simplest -form, just one expression is specified, whose value must increase or decrease -on each iteration of the loop. - -In a more complex form, multiple arguments can be given which are interpreted -in a nesting lexicographic manner. For example: - -@example -pragma Loop_Variant (Increases => X, Decreases => Y); -@end example - -specifies that each time through the loop either X increases, or X stays -the same and Y decreases. A @code{Loop_Variant} pragma ensures that the -loop is making progress. It can be useful in helping to show informally -or prove formally that the loop always terminates. - -@code{Loop_Variant} is an assertion whose effect can be controlled using -an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The -policy can be @code{Check} to enable the loop variant check, @code{Ignore} -to ignore the check (in which case the pragma has no effect on the program), -or @code{Disable} in which case the pragma is not even checked for correct -syntax. - -Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that -apply to the same loop should be grouped in the same sequence of -statements. - -The @code{Loop_Entry} attribute may be used within the expressions of the -@code{Loop_Variant} pragma to refer to values on entry to the loop. - -@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{98} -@section Pragma Machine_Attribute - - -Syntax: - -@example -pragma Machine_Attribute ( - [Entity =>] LOCAL_NAME, - [Attribute_Name =>] static_string_EXPRESSION - [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); -@end example - -Machine-dependent attributes can be specified for types and/or -declarations. This pragma is semantically equivalent to -@code{__attribute__((@var{attribute_name}))} (if @code{info} is not -specified) or @code{__attribute__((@var{attribute_name(info})))} -or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C, -where `attribute_name' is recognized by the compiler middle-end -or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note -that a string literal for the optional parameter @code{info} or the -following ones is transformed by default into an identifier, -which may make this pragma unusable for some attributes. -For further information see @cite{GNU Compiler Collection (GCC) Internals}. - -@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{99} -@section Pragma Main - - -Syntax: - -@example -pragma Main - (MAIN_OPTION [, MAIN_OPTION]); - -MAIN_OPTION ::= - [Stack_Size =>] static_integer_EXPRESSION -| [Task_Stack_Size_Default =>] static_integer_EXPRESSION -| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION -@end example - -This pragma is provided for compatibility with OpenVMS VAX Systems. It has -no effect in GNAT, other than being syntax checked. - -@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9a} -@section Pragma Main_Storage - - -Syntax: - -@example -pragma Main_Storage - (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); - -MAIN_STORAGE_OPTION ::= - [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION -| [TOP_GUARD =>] static_SIMPLE_EXPRESSION -@end example - -This pragma is provided for compatibility with OpenVMS VAX Systems. It has -no effect in GNAT, other than being syntax checked. - -@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9b}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9c} -@section Pragma Max_Queue_Length - - -Syntax: - -@example -pragma Max_Entry_Queue (static_integer_EXPRESSION); -@end example - -This pragma is used to specify the maximum callers per entry queue for -individual protected entries and entry families. It accepts a single -integer (-1 or more) as a parameter and must appear after the declaration of an -entry. - -A value of -1 represents no additional restriction on queue length. - -@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9d} -@section Pragma No_Body - - -Syntax: - -@example -pragma No_Body; -@end example - -There are a number of cases in which a package spec does not require a body, -and in fact a body is not permitted. GNAT will not permit the spec to be -compiled if there is a body around. The pragma No_Body allows you to provide -a body file, even in a case where no body is allowed. The body file must -contain only comments and a single No_Body pragma. This is recognized by -the compiler as indicating that no body is logically present. - -This is particularly useful during maintenance when a package is modified in -such a way that a body needed before is no longer needed. The provision of a -dummy body with a No_Body pragma ensures that there is no interference from -earlier versions of the package body. - -@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{9f} -@section Pragma No_Caching - - -Syntax: - -@example -pragma No_Caching [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{No_Caching} in -the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a0} -@section Pragma No_Component_Reordering - - -Syntax: - -@example -pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to a record type declaration in the current -declarative part. The effect is to preclude any reordering of components -for the layout of the record, i.e. the record is laid out by the compiler -in the order in which the components are declared textually. The form with -no argument is a configuration pragma which applies to all record types -declared in units to which the pragma applies and there is a requirement -that this pragma be used consistently within a partition. - -@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a2} -@section Pragma No_Elaboration_Code_All - - -Syntax: - -@example -pragma No_Elaboration_Code_All [(program_unit_NAME)]; -@end example - -This is a program unit pragma (there is also an equivalent aspect of the -same name) that establishes the restriction @code{No_Elaboration_Code} for -the current unit and any extended main source units (body and subunits). -It also has the effect of enforcing a transitive application of this -aspect, so that if any unit is implicitly or explicitly with’ed by the -current unit, it must also have the No_Elaboration_Code_All aspect set. -It may be applied to package or subprogram specs or their generic versions. - -@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a3} -@section Pragma No_Heap_Finalization - - -Syntax: - -@example -pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; -@end example - -Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a -type-specific pragma. - -In its configuration form, the pragma must appear within a configuration file -such as gnat.adc, without an argument. The pragma suppresses the call to -@code{Finalize} for heap-allocated objects created through library-level named -access-to-object types in cases where the designated type requires finalization -actions. - -In its type-specific form, the argument of the pragma must denote a -library-level named access-to-object type. The pragma suppresses the call to -@code{Finalize} for heap-allocated objects created through the specific access type -in cases where the designated type requires finalization actions. - -It is still possible to finalize such heap-allocated objects by explicitly -deallocating them. - -A library-level named access-to-object type declared within a generic unit will -lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not -appear at the library level. - -@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a5} -@section Pragma No_Inline - - -Syntax: - -@example -pragma No_Inline (NAME @{, NAME@}); -@end example - -This pragma suppresses inlining for the callable entity or the instances of -the generic subprogram designated by @code{NAME}, including inlining that -results from the use of pragma @code{Inline}. This pragma is always active, -in particular it is not subject to the use of option `-gnatn' or -`-gnatN'. It is illegal to specify both pragma @code{No_Inline} and -pragma @code{Inline_Always} for the same @code{NAME}. - -@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a6} -@section Pragma No_Return - - -Syntax: - -@example -pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); -@end example - -Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure -declarations in the current declarative part. A procedure to which this -pragma is applied may not contain any explicit @code{return} statements. -In addition, if the procedure contains any implicit returns from falling -off the end of a statement sequence, then execution of that implicit -return will cause Program_Error to be raised. - -One use of this pragma is to identify procedures whose only purpose is to raise -an exception. Another use of this pragma is to suppress incorrect warnings -about missing returns in functions, where the last statement of a function -statement sequence is a call to such a procedure. - -Note that in Ada 2005 mode, this pragma is part of the language. It is -available in all earlier versions of Ada as an implementation-defined -pragma. - -@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a7} -@section Pragma No_Strict_Aliasing - - -Syntax: - -@example -pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to an access type -declaration in the current declarative part. The effect is to inhibit -strict aliasing optimization for the given type. The form with no -arguments is a configuration pragma which applies to all access types -declared in units to which the pragma applies. For a detailed -description of the strict aliasing optimization, and the situations -in which it must be suppressed, see the section on Optimization and Strict Aliasing -in the @cite{GNAT User’s Guide}. - -This pragma currently has no effects on access to unconstrained array types. - -@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a9} -@section Pragma No_Tagged_Streams - - -Syntax: - -@example -pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; -@end example - -Normally when a tagged type is introduced using a full type declaration, -part of the processing includes generating stream access routines to be -used by stream attributes referencing the type (or one of its subtypes -or derived types). This can involve the generation of significant amounts -of code which is wasted space if stream routines are not needed for the -type in question. - -The @code{No_Tagged_Streams} pragma causes the generation of these stream -routines to be skipped, and any attempt to use stream operations on -types subject to this pragma will be statically rejected as illegal. - -There are two forms of the pragma. The form with no arguments must appear -in a declarative sequence or in the declarations of a package spec. This -pragma affects all subsequent root tagged types declared in the declaration -sequence, and specifies that no stream routines be generated. The form with -an argument (for which there is also a corresponding aspect) specifies a -single root tagged type for which stream routines are not to be generated. - -Once the pragma has been given for a particular root tagged type, all subtypes -and derived types of this type inherit the pragma automatically, so the effect -applies to a complete hierarchy (this is necessary to deal with the class-wide -dispatching versions of the stream routines). - -When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously -applied to a tagged type its Expanded_Name and External_Tag are initialized -with empty strings. This is useful to avoid exposing entity names at binary -level but has a negative impact on the debuggability of tagged types. - -@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{aa} -@section Pragma Normalize_Scalars - - -Syntax: - -@example -pragma Normalize_Scalars; -@end example - -This is a language defined pragma which is fully implemented in GNAT. The -effect is to cause all scalar objects that are not otherwise initialized -to be initialized. The initial values are implementation dependent and -are as follows: - - -@table @asis - -@item `Standard.Character' - -Objects whose root type is Standard.Character are initialized to -Character’Last unless the subtype range excludes NUL (in which case -NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Standard.Wide_Character' - -Objects whose root type is Standard.Wide_Character are initialized to -Wide_Character’Last unless the subtype range excludes NUL (in which case -NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Standard.Wide_Wide_Character' - -Objects whose root type is Standard.Wide_Wide_Character are initialized to -the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in -which case NUL is used). This choice will always generate an invalid value if -one exists. - -@item `Integer types' - -Objects of an integer type are treated differently depending on whether -negative values are present in the subtype. If no negative values are -present, then all one bits is used as the initial value except in the -special case where zero is excluded from the subtype, in which case -all zero bits are used. This choice will always generate an invalid -value if one exists. - -For subtypes with negative values present, the largest negative number -is used, except in the unusual case where this largest negative number -is in the subtype, and the largest positive number is not, in which case -the largest positive value is used. This choice will always generate -an invalid value if one exists. - -@item `Floating-Point Types' - -Objects of all floating-point types are initialized to all 1-bits. For -standard IEEE format, this corresponds to a NaN (not a number) which is -indeed an invalid value. - -@item `Fixed-Point Types' - -Objects of all fixed-point types are treated as described above for integers, -with the rules applying to the underlying integer value used to represent -the fixed-point value. - -@item `Modular types' - -Objects of a modular type are initialized to all one bits, except in -the special case where zero is excluded from the subtype, in which -case all zero bits are used. This choice will always generate an -invalid value if one exists. - -@item `Enumeration types' - -Objects of an enumeration type are initialized to all one-bits, i.e., to -the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal -whose Pos value is zero, in which case a code of zero is used. This choice -will always generate an invalid value if one exists. -@end table - -@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ac} -@section Pragma Obsolescent - - -Syntax: - -@example -pragma Obsolescent; - -pragma Obsolescent ( - [Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]); - -pragma Obsolescent ( - [Entity =>] NAME -[,[Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]]); -@end example - -This pragma can occur immediately following a declaration of an entity, -including the case of a record component. If no Entity argument is present, -then this declaration is the one to which the pragma applies. If an Entity -parameter is present, it must either match the name of the entity in this -declaration, or alternatively, the pragma can immediately follow an enumeration -type declaration, where the Entity argument names one of the enumeration -literals. - -This pragma is used to indicate that the named entity -is considered obsolescent and should not be used. Typically this is -used when an API must be modified by eventually removing or modifying -existing subprograms or other entities. The pragma can be used at an -intermediate stage when the entity is still present, but will be -removed later. - -The effect of this pragma is to output a warning message on a reference to -an entity thus marked that the subprogram is obsolescent if the appropriate -warning option in the compiler is activated. If the @code{Message} parameter is -present, then a second warning message is given containing this text. In -addition, a reference to the entity is considered to be a violation of pragma -@code{Restrictions (No_Obsolescent_Features)}. - -This pragma can also be used as a program unit pragma for a package, -in which case the entity name is the name of the package, and the -pragma indicates that the entire package is considered -obsolescent. In this case a client @code{with}ing such a package -violates the restriction, and the @code{with} clause is -flagged with warnings if the warning option is set. - -If the @code{Version} parameter is present (which must be exactly -the identifier @code{Ada_05}, no other argument is allowed), then the -indication of obsolescence applies only when compiling in Ada 2005 -mode. This is primarily intended for dealing with the situations -in the predefined library where subprograms or packages -have become defined as obsolescent in Ada 2005 -(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. - -The following examples show typical uses of this pragma: - -@example -package p is - pragma Obsolescent (p, Message => "use pp instead of p"); -end p; - -package q is - procedure q2; - pragma Obsolescent ("use q2new instead"); - - type R is new integer; - pragma Obsolescent - (Entity => R, - Message => "use RR in Ada 2005", - Version => Ada_05); - - type M is record - F1 : Integer; - F2 : Integer; - pragma Obsolescent; - F3 : Integer; - end record; - - type E is (a, bc, 'd', quack); - pragma Obsolescent (Entity => bc) - pragma Obsolescent (Entity => 'd') - - function "+" - (a, b : character) return character; - pragma Obsolescent (Entity => "+"); -end; -@end example - -Note that, as for all pragmas, if you use a pragma argument identifier, -then all subsequent parameters must also use a pragma argument identifier. -So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} -argument is present, it must be preceded by @code{Message =>}. - -@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ad} -@section Pragma Optimize_Alignment - - -@geindex Alignment -@geindex default settings - -Syntax: - -@example -pragma Optimize_Alignment (TIME | SPACE | OFF); -@end example - -This is a configuration pragma which affects the choice of default alignments -for types and objects where no alignment is explicitly specified. There is a -time/space trade-off in the selection of these values. Large alignments result -in more efficient code, at the expense of larger data space, since sizes have -to be increased to match these alignments. Smaller alignments save space, but -the access code is slower. The normal choice of default alignments for types -and individual alignment promotions for objects (which is what you get if you -do not use this pragma, or if you use an argument of OFF), tries to balance -these two requirements. - -Specifying SPACE causes smaller default alignments to be chosen in two cases. -First any packed record is given an alignment of 1. Second, if a size is given -for the type, then the alignment is chosen to avoid increasing this size. For -example, consider: - -@example -type R is record - X : Integer; - Y : Character; -end record; - -for R'Size use 5*8; -@end example - -In the default mode, this type gets an alignment of 4, so that access to the -Integer field X are efficient. But this means that objects of the type end up -with a size of 8 bytes. This is a valid choice, since sizes of objects are -allowed to be bigger than the size of the type, but it can waste space if for -example fields of type R appear in an enclosing record. If the above type is -compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. - -However, there is one case in which SPACE is ignored. If a variable length -record (that is a discriminated record with a component which is an array -whose length depends on a discriminant), has a pragma Pack, then it is not -in general possible to set the alignment of such a record to one, so the -pragma is ignored in this case (with a warning). - -Specifying SPACE also disables alignment promotions for standalone objects, -which occur when the compiler increases the alignment of a specific object -without changing the alignment of its type. - -Specifying SPACE also disables component reordering in unpacked record types, -which can result in larger sizes in order to meet alignment requirements. - -Specifying TIME causes larger default alignments to be chosen in the case of -small types with sizes that are not a power of 2. For example, consider: - -@example -type R is record - A : Character; - B : Character; - C : Boolean; -end record; - -pragma Pack (R); -for R'Size use 17; -@end example - -The default alignment for this record is normally 1, but if this type is -compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set -to 4, which wastes space for objects of the type, since they are now 4 bytes -long, but results in more efficient access when the whole record is referenced. - -As noted above, this is a configuration pragma, and there is a requirement -that all units in a partition be compiled with a consistent setting of the -optimization setting. This would normally be achieved by use of a configuration -pragma file containing the appropriate setting. The exception to this rule is -that units with an explicit configuration pragma in the same file as the source -unit are excluded from the consistency check, as are all predefined units. The -latter are compiled by default in pragma Optimize_Alignment (Off) mode if no -pragma appears at the start of the file. - -@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{ae} -@section Pragma Ordered - - -Syntax: - -@example -pragma Ordered (enumeration_first_subtype_LOCAL_NAME); -@end example - -Most enumeration types are from a conceptual point of view unordered. -For example, consider: - -@example -type Color is (Red, Blue, Green, Yellow); -@end example - -By Ada semantics @code{Blue > Red} and @code{Green > Blue}, -but really these relations make no sense; the enumeration type merely -specifies a set of possible colors, and the order is unimportant. - -For unordered enumeration types, it is generally a good idea if -clients avoid comparisons (other than equality or inequality) and -explicit ranges. (A `client' is a unit where the type is referenced, -other than the unit where the type is declared, its body, and its subunits.) -For example, if code buried in some client says: - -@example -if Current_Color < Yellow then ... -if Current_Color in Blue .. Green then ... -@end example - -then the client code is relying on the order, which is undesirable. -It makes the code hard to read and creates maintenance difficulties if -entries have to be added to the enumeration type. Instead, -the code in the client should list the possibilities, or an -appropriate subtype should be declared in the unit that declares -the original enumeration type. E.g., the following subtype could -be declared along with the type @code{Color}: - -@example -subtype RBG is Color range Red .. Green; -@end example - -and then the client could write: - -@example -if Current_Color in RBG then ... -if Current_Color = Blue or Current_Color = Green then ... -@end example - -However, some enumeration types are legitimately ordered from a conceptual -point of view. For example, if you declare: - -@example -type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); -@end example - -then the ordering imposed by the language is reasonable, and -clients can depend on it, writing for example: - -@example -if D in Mon .. Fri then ... -if D < Wed then ... -@end example - -The pragma `Ordered' is provided to mark enumeration types that -are conceptually ordered, alerting the reader that clients may depend -on the ordering. GNAT provides a pragma to mark enumerations as ordered -rather than one to mark them as unordered, since in our experience, -the great majority of enumeration types are conceptually unordered. - -The types @code{Boolean}, @code{Character}, @code{Wide_Character}, -and @code{Wide_Wide_Character} -are considered to be ordered types, so each is declared with a -pragma @code{Ordered} in package @code{Standard}. - -Normally pragma @code{Ordered} serves only as documentation and a guide for -coding standards, but GNAT provides a warning switch `-gnatw.u' that -requests warnings for inappropriate uses (comparisons and explicit -subranges) for unordered types. If this switch is used, then any -enumeration type not marked with pragma @code{Ordered} will be considered -as unordered, and will generate warnings for inappropriate uses. - -Note that generic types are not considered ordered or unordered (since the -template can be instantiated for both cases), so we never generate warnings -for the case of generic enumerated types. - -For additional information please refer to the description of the -`-gnatw.u' switch in the GNAT User’s Guide. - -@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{af} -@section Pragma Overflow_Mode - - -Syntax: - -@example -pragma Overflow_Mode - ( [General =>] MODE - [,[Assertions =>] MODE]); - -MODE ::= STRICT | MINIMIZED | ELIMINATED -@end example - -This pragma sets the current overflow mode to the given setting. For details -of the meaning of these modes, please refer to the -‘Overflow Check Handling in GNAT’ appendix in the -GNAT User’s Guide. If only the @code{General} parameter is present, -the given mode applies to all expressions. If both parameters are present, -the @code{General} mode applies to expressions outside assertions, and -the @code{Eliminated} mode applies to expressions within assertions. - -The case of the @code{MODE} parameter is ignored, -so @code{MINIMIZED}, @code{Minimized} and -@code{minimized} all have the same effect. - -The @code{Overflow_Mode} pragma has the same scoping and placement -rules as pragma @code{Suppress}, so it can occur either as a -configuration pragma, specifying a default for the whole -program, or in a declarative scope, where it applies to the -remaining declarations and statements in that scope. - -The pragma @code{Suppress (Overflow_Check)} suppresses -overflow checking, but does not affect the overflow mode. - -The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) -overflow checking, but does not affect the overflow mode. - -@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b0} -@section Pragma Overriding_Renamings - - -@geindex Rational profile - -@geindex Rational compatibility - -Syntax: - -@example -pragma Overriding_Renamings; -@end example - -This is a GNAT configuration pragma to simplify porting -legacy code accepted by the Rational -Ada compiler. In the presence of this pragma, a renaming declaration that -renames an inherited operation declared in the same scope is legal if selected -notation is used as in: - -@example -pragma Overriding_Renamings; -... -package R is - function F (..); - ... - function F (..) renames R.F; -end R; -@end example - -even though -RM 8.3 (15) stipulates that an overridden operation is not visible within the -declaration of the overriding operation. - -@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b1} -@section Pragma Partition_Elaboration_Policy - - -Syntax: - -@example -pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); - -POLICY_IDENTIFIER ::= Concurrent | Sequential -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b2}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b3} -@section Pragma Part_Of - - -Syntax: - -@example -pragma Part_Of (ABSTRACT_STATE); - -ABSTRACT_STATE ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the -SPARK 2014 Reference Manual, section 7.2.6. - -@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b4} -@section Pragma Passive - - -Syntax: - -@example -pragma Passive [(Semaphore | No)]; -@end example - -Syntax checked, but otherwise ignored by GNAT. This is recognized for -compatibility with DEC Ada 83 implementations, where it is used within a -task definition to request that a task be made passive. If the argument -@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 -treats the pragma as an assertion that the containing task is passive -and that optimization of context switch with this task is permitted and -desired. If the argument @code{No} is present, the task must not be -optimized. GNAT does not attempt to optimize any tasks in this manner -(since protected objects are available in place of passive tasks). - -For more information on the subject of passive tasks, see the section -‘Passive Task Optimization’ in the GNAT Users Guide. - -@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b5}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b6} -@section Pragma Persistent_BSS - - -Syntax: - -@example -pragma Persistent_BSS [(LOCAL_NAME)] -@end example - -This pragma allows selected objects to be placed in the @code{.persistent_bss} -section. On some targets the linker and loader provide for special -treatment of this section, allowing a program to be reloaded without -affecting the contents of this data (hence the name persistent). - -There are two forms of usage. If an argument is given, it must be the -local name of a library-level object, with no explicit initialization -and whose type is potentially persistent. If no argument is given, then -the pragma is a configuration pragma, and applies to all library-level -objects with no explicit initialization of potentially persistent types. - -A potentially persistent type is a scalar type, or an untagged, -non-discriminated record, all of whose components have no explicit -initialization and are themselves of a potentially persistent type, -or an array, all of whose constraints are static, and whose component -type is potentially persistent. - -If this pragma is used on a target where this feature is not supported, -then the pragma will be ignored. See also @code{pragma Linker_Section}. - -@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b7} -@section Pragma Post - - -@geindex Post - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Post (Boolean_Expression); -@end example - -The @code{Post} pragma is intended to be an exact replacement for -the language-defined -@code{Post} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b8} -@section Pragma Postcondition - - -@geindex Postcondition - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Postcondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end example - -The @code{Postcondition} pragma allows specification of automatic -postcondition checks for subprograms. These checks are similar to -assertions, but are automatically inserted just prior to the return -statements of the subprogram with which they are associated (including -implicit returns at the end of procedure bodies and associated -exception handlers). - -In addition, the boolean expression which is the condition which -must be true may contain references to function’Result in the case -of a function to refer to the returned value. - -@code{Postcondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). In the case of a -postcondition appearing after a subprogram declaration, the -formal arguments of the subprogram are visible, and can be -referenced in the postcondition expressions. - -The postconditions are collected and automatically tested just -before any return (implicit or explicit) in the subprogram body. -A postcondition is only recognized if postconditions are active -at the time the pragma is encountered. The compiler switch `gnata' -turns on all postconditions by default, and pragma @code{Check_Policy} -with an identifier of @code{Postcondition} can also be used to -control whether postconditions are active. - -The general approach is that postconditions are placed in the spec -if they represent functional aspects which make sense to the client. -For example we might have: - -@example -function Direction return Integer; -pragma Postcondition - (Direction'Result = +1 - or else - Direction'Result = -1); -@end example - -which serves to document that the result must be +1 or -1, and -will test that this is the case at run time if postcondition -checking is active. - -Postconditions within the subprogram body can be used to -check that some internal aspect of the implementation, -not visible to the client, is operating as expected. -For instance if a square root routine keeps an internal -counter of the number of times it is called, then we -might have the following postcondition: - -@example -Sqrt_Calls : Natural := 0; - -function Sqrt (Arg : Float) return Float is - pragma Postcondition - (Sqrt_Calls = Sqrt_Calls'Old + 1); - ... -end Sqrt -@end example - -As this example, shows, the use of the @code{Old} attribute -is often useful in postconditions to refer to the state on -entry to the subprogram. - -Note that postconditions are only checked on normal returns -from the subprogram. If an abnormal return results from -raising an exception, then the postconditions are not checked. - -If a postcondition fails, then the exception -@code{System.Assertions.Assert_Failure} is raised. If -a message argument was supplied, then the given string -will be used as the exception message. If no message -argument was supplied, then the default message has -the form “Postcondition failed at file_name:line”. The -exception is raised in the context of the subprogram -body, so it is possible to catch postcondition failures -within the subprogram body itself. - -Within a package spec, normal visibility rules -in Ada would prevent forward references within a -postcondition pragma to functions defined later in -the same package. This would introduce undesirable -ordering constraints. To avoid this problem, all -postcondition pragmas are analyzed at the end of -the package spec, allowing forward references. - -The following example shows that this even allows -mutually recursive postconditions as in: - -@example -package Parity_Functions is - function Odd (X : Natural) return Boolean; - pragma Postcondition - (Odd'Result = - (x = 1 - or else - (x /= 0 and then Even (X - 1)))); - - function Even (X : Natural) return Boolean; - pragma Postcondition - (Even'Result = - (x = 0 - or else - (x /= 1 and then Odd (X - 1)))); - -end Parity_Functions; -@end example - -There are no restrictions on the complexity or form of -conditions used within @code{Postcondition} pragmas. -The following example shows that it is even possible -to verify performance behavior. - -@example -package Sort is - - Performance : constant Float; - -- Performance constant set by implementation - -- to match target architecture behavior. - - procedure Treesort (Arg : String); - -- Sorts characters of argument using N*logN sort - pragma Postcondition - (Float (Clock - Clock'Old) <= - Float (Arg'Length) * - log (Float (Arg'Length)) * - Performance); -end Sort; -@end example - -Note: postcondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if postcondition -checking is enabled. - -Note that pragma @code{Postcondition} differs from the language-defined -@code{Post} aspect (and corresponding @code{Post} pragma) in allowing -multiple occurrences, allowing occurences in the body even if there -is a separate spec, and allowing a second string parameter, and the -use of the pragma identifier @code{Check}. Historically, pragma -@code{Postcondition} was implemented prior to the development of -Ada 2012, and has been retained in its original form for -compatibility purposes. - -@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b9} -@section Pragma Post_Class - - -@geindex Post - -@geindex Checks -@geindex postconditions - -Syntax: - -@example -pragma Post_Class (Boolean_Expression); -@end example - -The @code{Post_Class} pragma is intended to be an exact replacement for -the language-defined -@code{Post'Class} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -Note: This pragma is called @code{Post_Class} rather than -@code{Post'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Post'Class}, not -@code{Post_Class}. - -@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba} -@section Pragma Pre - - -@geindex Pre - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Pre (Boolean_Expression); -@end example - -The @code{Pre} pragma is intended to be an exact replacement for -the language-defined -@code{Pre} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb} -@section Pragma Precondition - - -@geindex Preconditions - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Precondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end example - -The @code{Precondition} pragma is similar to @code{Postcondition} -except that the corresponding checks take place immediately upon -entry to the subprogram, and if a precondition fails, the exception -is raised in the context of the caller, and the attribute ‘Result -cannot be used within the precondition expression. - -Otherwise, the placement and visibility rules are identical to those -described for postconditions. The following is an example of use -within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Precondition (Arg >= 0.0) - ... -end Math_Functions; -@end example - -@code{Precondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). - -Note: precondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if precondition -checking is enabled. - -Note that pragma @code{Precondition} differs from the language-defined -@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing -multiple occurrences, allowing occurences in the body even if there -is a separate spec, and allowing a second string parameter, and the -use of the pragma identifier @code{Check}. Historically, pragma -@code{Precondition} was implemented prior to the development of -Ada 2012, and has been retained in its original form for -compatibility purposes. - -@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd} -@section Pragma Predicate - - -Syntax: - -@example -pragma Predicate - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -This pragma (available in all versions of Ada in GNAT) encompasses both -the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in -Ada 2012. A predicate is regarded as static if it has an allowed form -for @code{Static_Predicate} and is otherwise treated as a -@code{Dynamic_Predicate}. Otherwise, predicates specified by this -pragma behave exactly as described in the Ada 2012 reference manual. -For example, if we have - -@example -type R is range 1 .. 10; -subtype S is R; -pragma Predicate (Entity => S, Check => S not in 4 .. 6); -subtype Q is R -pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); -@end example - -the effect is identical to the following Ada 2012 code: - -@example -type R is range 1 .. 10; -subtype S is R with - Static_Predicate => S not in 4 .. 6; -subtype Q is R with - Dynamic_Predicate => F(Q) or G(Q); -@end example - -Note that there are no pragmas @code{Dynamic_Predicate} -or @code{Static_Predicate}. That is -because these pragmas would affect legality and semantics of -the program and thus do not have a neutral effect if ignored. -The motivation behind providing pragmas equivalent to -corresponding aspects is to allow a program to be written -using the pragmas, and then compiled with a compiler that -will ignore the pragmas. That doesn’t work in the case of -static and dynamic predicates, since if the corresponding -pragmas are ignored, then the behavior of the program is -fundamentally changed (for example a membership test -@code{A in B} would not take into account a predicate -defined for subtype B). When following this approach, the -use of predicates should be avoided. - -@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{be} -@section Pragma Predicate_Failure - - -Syntax: - -@example -pragma Predicate_Failure - ([Entity =>] type_LOCAL_NAME, - [Message =>] String_Expression); -@end example - -The @code{Predicate_Failure} pragma is intended to be an exact replacement for -the language-defined -@code{Predicate_Failure} aspect, and shares its restrictions and semantics. - -@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bf} -@section Pragma Preelaborable_Initialization - - -Syntax: - -@example -pragma Preelaborable_Initialization (DIRECT_NAME); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c0} -@section Pragma Prefix_Exception_Messages - - -@geindex Prefix_Exception_Messages - -@geindex exception - -@geindex Exception_Message - -Syntax: - -@example -pragma Prefix_Exception_Messages; -@end example - -This is an implementation-defined configuration pragma that affects the -behavior of raise statements with a message given as a static string -constant (typically a string literal). In such cases, the string will -be automatically prefixed by the name of the enclosing entity (giving -the package and subprogram containing the raise statement). This helps -to identify where messages are coming from, and this mode is automatic -for the run-time library. - -The pragma has no effect if the message is computed with an expression other -than a static string constant, since the assumption in this case is that -the program computes exactly the string it wants. If you still want the -prefixing in this case, you can always call -@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. - -@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c1} -@section Pragma Pre_Class - - -@geindex Pre_Class - -@geindex Checks -@geindex preconditions - -Syntax: - -@example -pragma Pre_Class (Boolean_Expression); -@end example - -The @code{Pre_Class} pragma is intended to be an exact replacement for -the language-defined -@code{Pre'Class} aspect, and shares its restrictions and semantics. -It must appear either immediately following the corresponding -subprogram declaration (only other pragmas may intervene), or -if there is no separate subprogram declaration, then it can -appear at the start of the declarations in a subprogram body -(preceded only by other pragmas). - -Note: This pragma is called @code{Pre_Class} rather than -@code{Pre'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Pre'Class}, not -@code{Pre_Class}. - -@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c2} -@section Pragma Priority_Specific_Dispatching - - -Syntax: - -@example -pragma Priority_Specific_Dispatching ( - POLICY_IDENTIFIER, - first_priority_EXPRESSION, - last_priority_EXPRESSION) - -POLICY_IDENTIFIER ::= - EDF_Across_Priorities | - FIFO_Within_Priorities | - Non_Preemptive_Within_Priorities | - Round_Robin_Within_Priorities -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c3} -@section Pragma Profile - - -Syntax: - -@example -pragma Profile (Ravenscar | Restricted | Rational | Jorvik | - GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. This is a -configuration pragma that establishes a set of configuration pragmas -that depend on the argument. @code{Ravenscar} is standard in Ada 2005. -@code{Jorvik} is standard in Ada 202x. -The other possibilities (@code{Restricted}, @code{Rational}, -@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) -are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. - -The set of configuration pragmas is defined in the following sections. - - -@itemize * - -@item -Pragma Profile (Ravenscar) - -The @code{Ravenscar} profile is standard in Ada 2005, -but is available in all earlier -versions of Ada as an implementation-defined pragma. This profile -establishes the following set of configuration pragmas: - - -@itemize * - -@item -@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} - -[RM D.2.2] Tasks are dispatched following a preemptive -priority-ordered scheduling policy. - -@item -@code{Locking_Policy (Ceiling_Locking)} - -[RM D.3] While tasks and interrupts execute a protected action, they inherit -the ceiling priority of the corresponding protected object. - -@item -@code{Detect_Blocking} - -This pragma forces the detection of potentially blocking operations within a -protected operation, and to raise Program_Error if that happens. -@end itemize - -plus the following set of restrictions: - - -@itemize * - -@item -@code{Max_Entry_Queue_Length => 1} - -No task can be queued on a protected entry. - -@item -@code{Max_Protected_Entries => 1} - -@item -@code{Max_Task_Entries => 0} - -No rendezvous statements are allowed. - -@item -@code{No_Abort_Statements} - -@item -@code{No_Dynamic_Attachment} - -@item -@code{No_Dynamic_Priorities} - -@item -@code{No_Implicit_Heap_Allocations} - -@item -@code{No_Local_Protected_Objects} - -@item -@code{No_Local_Timing_Events} - -@item -@code{No_Protected_Type_Allocators} - -@item -@code{No_Relative_Delay} - -@item -@code{No_Requeue_Statements} - -@item -@code{No_Select_Statements} - -@item -@code{No_Specific_Termination_Handlers} - -@item -@code{No_Task_Allocators} - -@item -@code{No_Task_Hierarchy} - -@item -@code{No_Task_Termination} - -@item -@code{Simple_Barriers} -@end itemize - -The Ravenscar profile also includes the following restrictions that specify -that there are no semantic dependencies on the corresponding predefined -packages: - - -@itemize * - -@item -@code{No_Dependence => Ada.Asynchronous_Task_Control} - -@item -@code{No_Dependence => Ada.Calendar} - -@item -@code{No_Dependence => Ada.Execution_Time.Group_Budget} - -@item -@code{No_Dependence => Ada.Execution_Time.Timers} - -@item -@code{No_Dependence => Ada.Task_Attributes} - -@item -@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} -@end itemize - -This set of configuration pragmas and restrictions correspond to the -definition of the ‘Ravenscar Profile’ for limited tasking, devised and -published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. -A description is also available at -@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. - -The original definition of the profile was revised at subsequent IRTAW -meetings. It has been included in the ISO -@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, -and was made part of the Ada 2005 standard. -The formal definition given by -the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and -AI-305) available at -@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and -@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. - -The above set is a superset of the restrictions provided by pragma -@code{Profile (Restricted)}, it includes six additional restrictions -(@code{Simple_Barriers}, @code{No_Select_Statements}, -@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, -@code{No_Relative_Delay} and @code{No_Task_Termination}). This means -that pragma @code{Profile (Ravenscar)}, like the pragma -@code{Profile (Restricted)}, -automatically causes the use of a simplified, -more efficient version of the tasking run-time library. - -@item -Pragma Profile (Jorvik) - -@code{Jorvik} is the new profile added to the Ada 202x draft standard, -previously implemented under the name @code{GNAT_Extended_Ravenscar}. - -The @code{No_Implicit_Heap_Allocations} restriction has been replaced -by @code{No_Implicit_Task_Allocations} and -@code{No_Implicit_Protected_Object_Allocations}. - -The @code{Simple_Barriers} restriction has been replaced by -@code{Pure_Barriers}. - -The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and -@code{No_Relative_Delay} restrictions have been removed. - -Details on the rationale for @code{Jorvik} and implications for use may be -found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, -T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, -Number 10300. - -@item -Pragma Profile (GNAT_Ravenscar_EDF) - -This profile corresponds to the Ravenscar profile but using -EDF_Across_Priority as the Task_Scheduling_Policy. - -@item -Pragma Profile (Restricted) - -This profile corresponds to the GNAT restricted run time. It -establishes the following set of restrictions: - - -@itemize * - -@item -@code{No_Abort_Statements} - -@item -@code{No_Entry_Queue} - -@item -@code{No_Task_Hierarchy} - -@item -@code{No_Task_Allocators} - -@item -@code{No_Dynamic_Priorities} - -@item -@code{No_Terminate_Alternatives} - -@item -@code{No_Dynamic_Attachment} - -@item -@code{No_Protected_Type_Allocators} - -@item -@code{No_Local_Protected_Objects} - -@item -@code{No_Requeue_Statements} - -@item -@code{No_Task_Attributes_Package} - -@item -@code{Max_Asynchronous_Select_Nesting = 0} - -@item -@code{Max_Task_Entries = 0} - -@item -@code{Max_Protected_Entries = 1} - -@item -@code{Max_Select_Alternatives = 0} -@end itemize - -This set of restrictions causes the automatic selection of a simplified -version of the run time that provides improved performance for the -limited set of tasking functionality permitted by this set of restrictions. - -@item -Pragma Profile (Rational) - -The Rational profile is intended to facilitate porting legacy code that -compiles with the Rational APEX compiler, even when the code includes non- -conforming Ada constructs. The profile enables the following three pragmas: - - -@itemize * - -@item -@code{pragma Implicit_Packing} - -@item -@code{pragma Overriding_Renamings} - -@item -@code{pragma Use_VADS_Size} -@end itemize -@end itemize - -@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4} -@section Pragma Profile_Warnings - - -Syntax: - -@example -pragma Profile_Warnings (Ravenscar | Restricted | Rational); -@end example - -This is an implementation-defined pragma that is similar in -effect to @code{pragma Profile} except that instead of -generating @code{Restrictions} pragmas, it generates -@code{Restriction_Warnings} pragmas. The result is that -violations of the profile generate warning messages instead -of error messages. - -@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c5} -@section Pragma Propagate_Exceptions - - -@geindex Interfacing to C++ - -Syntax: - -@example -pragma Propagate_Exceptions; -@end example - -This pragma is now obsolete and, other than generating a warning if warnings -on obsolescent features are enabled, is ignored. -It is retained for compatibility -purposes. It used to be used in connection with optimization of -a now-obsolete mechanism for implementation of exceptions. - -@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c6} -@section Pragma Provide_Shift_Operators - - -@geindex Shift operators - -Syntax: - -@example -pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); -@end example - -This pragma can be applied to a first subtype local name that specifies -either an unsigned or signed type. It has the effect of providing the -five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, -Rotate_Left and Rotate_Right) for the given type. It is similar to -including the function declarations for these five operators, together -with the pragma Import (Intrinsic, …) statements. - -@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c7} -@section Pragma Psect_Object - - -Syntax: - -@example -pragma Psect_Object ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end example - -This pragma is identical in effect to pragma @code{Common_Object}. - -@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c9} -@section Pragma Pure_Function - - -Syntax: - -@example -pragma Pure_Function ([Entity =>] function_LOCAL_NAME); -@end example - -This pragma appears in the same declarative part as a function -declaration (or a set of function declarations if more than one -overloaded declaration exists, in which case the pragma applies -to all entities). It specifies that the function @code{Entity} is -to be considered pure for the purposes of code generation. This means -that the compiler can assume that there are no side effects, and -in particular that two identical calls produce the same result in -the same context. It also means that the function can be used in -an address clause. - -Note that, quite deliberately, there are no static checks to try -to ensure that this promise is met, so @code{Pure_Function} can be used -with functions that are conceptually pure, even if they do modify -global variables. For example, a square root function that is -instrumented to count the number of times it is called is still -conceptually pure, and can still be optimized, even though it -modifies a global variable (the count). Memo functions are another -example (where a table of previous calls is kept and consulted to -avoid re-computation). - -Note also that the normal rules excluding optimization of subprograms -in pure units (when parameter types are descended from System.Address, -or when the full view of a parameter type is limited), do not apply -for the Pure_Function case. If you explicitly specify Pure_Function, -the compiler may optimize away calls with identical arguments, and -if that results in unexpected behavior, the proper action is not to -use the pragma for subprograms that are not (conceptually) pure. - -Note: Most functions in a @code{Pure} package are automatically pure, and -there is no need to use pragma @code{Pure_Function} for such functions. One -exception is any function that has at least one formal of type -@code{System.Address} or a type derived from it. Such functions are not -considered pure by default, since the compiler assumes that the -@code{Address} parameter may be functioning as a pointer and that the -referenced data may change even if the address value does not. -Similarly, imported functions are not considered to be pure by default, -since there is no way of checking that they are in fact pure. The use -of pragma @code{Pure_Function} for such a function will override these default -assumption, and cause the compiler to treat a designated subprogram as pure -in these cases. - -Note: If pragma @code{Pure_Function} is applied to a renamed function, it -applies to the underlying renamed function. This can be used to -disambiguate cases of overloading where some but not all functions -in a set of overloaded functions are to be designated as pure. - -If pragma @code{Pure_Function} is applied to a library-level function, the -function is also considered pure from an optimization point of view, but the -unit is not a Pure unit in the categorization sense. So for example, a function -thus marked is free to @code{with} non-pure units. - -@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ca} -@section Pragma Rational - - -Syntax: - -@example -pragma Rational; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Rational); -@end example - -@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb} -@section Pragma Ravenscar - - -Syntax: - -@example -pragma Ravenscar; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Ravenscar); -@end example - -which is the preferred method of setting the @code{Ravenscar} profile. - -@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cd} -@section Pragma Refined_Depends - - -Syntax: - -@example -pragma Refined_Depends (DEPENDENCY_RELATION); - -DEPENDENCY_RELATION ::= - null - | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) - -DEPENDENCY_CLAUSE ::= - OUTPUT_LIST =>[+] INPUT_LIST - | NULL_DEPENDENCY_CLAUSE - -NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST - -OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) - -INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) - -OUTPUT ::= NAME | FUNCTION_RESULT -INPUT ::= NAME - -where FUNCTION_RESULT is a function Result attribute_reference -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in -the SPARK 2014 Reference Manual, section 6.1.5. - -@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{cf} -@section Pragma Refined_Global - - -Syntax: - -@example -pragma Refined_Global (GLOBAL_SPECIFICATION); - -GLOBAL_SPECIFICATION ::= - null - | (GLOBAL_LIST) - | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) - -MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST - -MODE_SELECTOR ::= In_Out | Input | Output | Proof_In -GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) -GLOBAL_ITEM ::= NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in -the SPARK 2014 Reference Manual, section 6.1.4. - -@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d1} -@section Pragma Refined_Post - - -Syntax: - -@example -pragma Refined_Post (boolean_EXPRESSION); -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in -the SPARK 2014 Reference Manual, section 7.2.7. - -@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d3} -@section Pragma Refined_State - - -Syntax: - -@example -pragma Refined_State (REFINEMENT_LIST); - -REFINEMENT_LIST ::= - (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) - -REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST - -CONSTITUENT_LIST ::= - null - | CONSTITUENT - | (CONSTITUENT @{, CONSTITUENT@}) - -CONSTITUENT ::= object_NAME | state_NAME -@end example - -For the semantics of this pragma, see the entry for aspect @code{Refined_State} in -the SPARK 2014 Reference Manual, section 7.2.2. - -@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d4} -@section Pragma Relative_Deadline - - -Syntax: - -@example -pragma Relative_Deadline (time_span_EXPRESSION); -@end example - -This pragma is standard in Ada 2005, but is available in all earlier -versions of Ada as an implementation-defined pragma. -See Ada 2012 Reference Manual for details. - -@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6} -@section Pragma Remote_Access_Type - - -Syntax: - -@example -pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); -@end example - -This pragma appears in the formal part of a generic declaration. -It specifies an exception to the RM rule from E.2.2(17/2), which forbids -the use of a remote access to class-wide type as actual for a formal -access type. - -When this pragma applies to a formal access type @code{Entity}, that -type is treated as a remote access to class-wide type in the generic. -It must be a formal general access type, and its designated type must -be the class-wide type of a formal tagged limited private type from the -same generic declaration. - -In the generic unit, the formal type is subject to all restrictions -pertaining to remote access to class-wide types. At instantiation, the -actual type must be a remote access to class-wide type. - -@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d7} -@section Pragma Rename_Pragma - - -@geindex Pragmas -@geindex synonyms - -Syntax: - -@example -pragma Rename_Pragma ( - [New_Name =>] IDENTIFIER, - [Renamed =>] pragma_IDENTIFIER); -@end example - -This pragma provides a mechanism for supplying new names for existing -pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for -the Renamed pragma. For example, suppose you have code that was originally -developed on a compiler that supports Inline_Only as an implementation defined -pragma. And suppose the semantics of pragma Inline_Only are identical to (or at -least very similar to) the GNAT implementation defined pragma -Inline_Always. You could globally replace Inline_Only with Inline_Always. - -However, to avoid that source modification, you could instead add a -configuration pragma: - -@example -pragma Rename_Pragma ( - New_Name => Inline_Only, - Renamed => Inline_Always); -@end example - -Then GNAT will treat “pragma Inline_Only …” as if you had written -“pragma Inline_Always …”. - -Pragma Inline_Only will not necessarily mean the same thing as the other Ada -compiler; it’s up to you to make sure the semantics are close enough. - -@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d8} -@section Pragma Restricted_Run_Time - - -Syntax: - -@example -pragma Restricted_Run_Time; -@end example - -This pragma is considered obsolescent, but is retained for -compatibility purposes. It is equivalent to: - -@example -pragma Profile (Restricted); -@end example - -which is the preferred method of setting the restricted run time -profile. - -@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d9} -@section Pragma Restriction_Warnings - - -Syntax: - -@example -pragma Restriction_Warnings - (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); -@end example - -This pragma allows a series of restriction identifiers to be -specified (the list of allowed identifiers is the same as for -pragma @code{Restrictions}). For each of these identifiers -the compiler checks for violations of the restriction, but -generates a warning message rather than an error message -if the restriction is violated. - -One use of this is in situations where you want to know -about violations of a restriction, but you want to ignore some of -these violations. Consider this example, where you want to set -Ada_95 mode and enable style checks, but you want to know about -any other use of implementation pragmas: - -@example -pragma Restriction_Warnings (No_Implementation_Pragmas); -pragma Warnings (Off, "violation of No_Implementation_Pragmas"); -pragma Ada_95; -pragma Style_Checks ("2bfhkM160"); -pragma Warnings (On, "violation of No_Implementation_Pragmas"); -@end example - -By including the above lines in a configuration pragmas file, -the Ada_95 and Style_Checks pragmas are accepted without -generating a warning, but any other use of implementation -defined pragmas will cause a warning to be generated. - -@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{da} -@section Pragma Reviewable - - -Syntax: - -@example -pragma Reviewable; -@end example - -This pragma is an RM-defined standard pragma, but has no effect on the -program being compiled, or on the code generated for the program. - -To obtain the required output specified in RM H.3.1, the compiler must be -run with various special switches as follows: - - -@itemize * - -@item -`Where compiler-generated run-time checks remain' - -The switch `-gnatGL' -may be used to list the expanded code in pseudo-Ada form. -Runtime checks show up in the listing either as explicit -checks or operators marked with @{@} to indicate a check is present. - -@item -`An identification of known exceptions at compile time' - -If the program is compiled with `-gnatwa', -the compiler warning messages will indicate all cases where the compiler -detects that an exception is certain to occur at run time. - -@item -`Possible reads of uninitialized variables' - -The compiler warns of many such cases, but its output is incomplete. -@end itemize - - -A supplemental static analysis tool -may be used to obtain a comprehensive list of all -possible points at which uninitialized data may be read. - - -@itemize * - -@item -`Where run-time support routines are implicitly invoked' - -In the output from `-gnatGL', -run-time calls are explicitly listed as calls to the relevant -run-time routine. - -@item -`Object code listing' - -This may be obtained either by using the `-S' switch, -or the objdump utility. - -@item -`Constructs known to be erroneous at compile time' - -These are identified by warnings issued by the compiler (use `-gnatwa'). - -@item -`Stack usage information' - -Static stack usage data (maximum per-subprogram) can be obtained via the -`-fstack-usage' switch to the compiler. -Dynamic stack usage data (per task) can be obtained via the `-u' switch -to gnatbind -@end itemize - - - -@itemize * - -@item -`Object code listing of entire partition' - -This can be obtained by compiling the partition with `-S', -or by applying objdump -to all the object files that are part of the partition. - -@item -`A description of the run-time model' - -The full sources of the run-time are available, and the documentation of -these routines describes how these run-time routines interface to the -underlying operating system facilities. - -@item -`Control and data-flow information' -@end itemize - - -A supplemental static analysis tool -may be used to obtain complete control and data-flow information, as well as -comprehensive messages identifying possible problems based on this -information. - -@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{db}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dc} -@section Pragma Secondary_Stack_Size - - -Syntax: - -@example -pragma Secondary_Stack_Size (integer_EXPRESSION); -@end example - -This pragma appears within the task definition of a single task declaration -or a task type declaration (like pragma @code{Storage_Size}) and applies to all -task objects of that type. The argument specifies the size of the secondary -stack to be used by these task objects, and must be of an integer type. The -secondary stack is used to handle functions that return a variable-sized -result, for example a function returning an unconstrained String. - -Note this pragma only applies to targets using fixed secondary stacks, like -VxWorks 653 and bare board targets, where a fixed block for the -secondary stack is allocated from the primary stack of the task. By default, -these targets assign a percentage of the primary stack for the secondary stack, -as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, -an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. - -For most targets, the pragma does not apply as the secondary stack grows on -demand: allocated as a chain of blocks in the heap. The default size of these -blocks can be modified via the @code{-D} binder option as described in -@cite{GNAT User’s Guide}. - -Note that no check is made to see if the secondary stack can fit inside the -primary stack. - -Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} -is in effect. - -@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{dd} -@section Pragma Share_Generic - - -Syntax: - -@example -pragma Share_Generic (GNAME @{, GNAME@}); - -GNAME ::= generic_unit_NAME | generic_instance_NAME -@end example - -This pragma is provided for compatibility with Dec Ada 83. It has -no effect in GNAT (which does not implement shared generics), other -than to check that the given names are all names of generic units or -generic instances. - -@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{df} -@section Pragma Shared - - -This pragma is provided for compatibility with Ada 83. The syntax and -semantics are identical to pragma Atomic. - -@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e0} -@section Pragma Short_Circuit_And_Or - - -Syntax: - -@example -pragma Short_Circuit_And_Or; -@end example - -This configuration pragma causes any occurrence of the AND operator applied to -operands of type Standard.Boolean to be short-circuited (i.e. the AND operator -is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This -may be useful in the context of certification protocols requiring the use of -short-circuited logical operators. If this configuration pragma occurs locally -within the file being compiled, it applies only to the file being compiled. -There is no requirement that all units in a partition use this option. - -@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e1} -@section Pragma Short_Descriptors - - -Syntax: - -@example -pragma Short_Descriptors; -@end example - -This pragma is provided for compatibility with other Ada implementations. It -is recognized but ignored by all current versions of GNAT. - -@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e2}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e3} -@section Pragma Simple_Storage_Pool_Type - - -@geindex Storage pool -@geindex simple - -@geindex Simple storage pool - -Syntax: - -@example -pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); -@end example - -A type can be established as a ‘simple storage pool type’ by applying -the representation pragma @code{Simple_Storage_Pool_Type} to the type. -A type named in the pragma must be a library-level immutably limited record -type or limited tagged type declared immediately within a package declaration. -The type can also be a limited private type whose full type is allowed as -a simple storage pool type. - -For a simple storage pool type @code{SSP}, nonabstract primitive subprograms -@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that -are subtype conformant with the following subprogram declarations: - -@example -procedure Allocate - (Pool : in out SSP; - Storage_Address : out System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -procedure Deallocate - (Pool : in out SSP; - Storage_Address : System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -function Storage_Size (Pool : SSP) - return System.Storage_Elements.Storage_Count; -@end example - -Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and -@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then -applying an unchecked deallocation has no effect other than to set its actual -parameter to null. If @code{Storage_Size} is not declared, then the -@code{Storage_Size} attribute applied to an access type associated with -a pool object of type SSP returns zero. Additional operations can be declared -for a simple storage pool type (such as for supporting a mark/release -storage-management discipline). - -An object of a simple storage pool type can be associated with an access -type by specifying the attribute -@ref{e4,,Simple_Storage_Pool}. For example: - -@example -My_Pool : My_Simple_Storage_Pool_Type; - -type Acc is access My_Data_Type; - -for Acc'Simple_Storage_Pool use My_Pool; -@end example - -See attribute @ref{e4,,Simple_Storage_Pool} -for further details. - -@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e6} -@section Pragma Source_File_Name - - -Syntax: - -@example -pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Spec_File_Name => STRING_LITERAL, - [Index => INTEGER_LITERAL]); - -pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Body_File_Name => STRING_LITERAL, - [Index => INTEGER_LITERAL]); -@end example - -Use this to override the normal naming convention. It is a configuration -pragma, and so has the usual applicability of configuration pragmas -(i.e., it applies to either an entire partition, or to all units in a -compilation, or to a single unit, depending on how it is used). -@code{unit_name} is mapped to @code{file_name_literal}. The identifier for -the second argument is required, and indicates whether this is the file -name for the spec or for the body. - -The optional Index argument should be used when a file contains multiple -units, and when you do not want to use @code{gnatchop} to separate then -into multiple files (which is the recommended procedure to limit the -number of recompilations that are needed when some sources change). -For instance, if the source file @code{source.ada} contains - -@example -package B is -... -end B; - -with B; -procedure A is -begin - .. -end A; -@end example - -you could use the following configuration pragmas: - -@example -pragma Source_File_Name - (B, Spec_File_Name => "source.ada", Index => 1); -pragma Source_File_Name - (A, Body_File_Name => "source.ada", Index => 2); -@end example - -Note that the @code{gnatname} utility can also be used to generate those -configuration pragmas. - -Another form of the @code{Source_File_Name} pragma allows -the specification of patterns defining alternative file naming schemes -to apply to all files. - -@example -pragma Source_File_Name - ( [Spec_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -pragma Source_File_Name - ( [Body_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -pragma Source_File_Name - ( [Subunit_File_Name =>] STRING_LITERAL - [,[Casing =>] CASING_SPEC] - [,[Dot_Replacement =>] STRING_LITERAL]); - -CASING_SPEC ::= Lowercase | Uppercase | Mixedcase -@end example - -The first argument is a pattern that contains a single asterisk indicating -the point at which the unit name is to be inserted in the pattern string -to form the file name. The second argument is optional. If present it -specifies the casing of the unit name in the resulting file name string. -The default is lower case. Finally the third argument allows for systematic -replacement of any dots in the unit name by the specified string literal. - -Note that Source_File_Name pragmas should not be used if you are using -project files. The reason for this rule is that the project manager is not -aware of these pragmas, and so other tools that use the project file would not -be aware of the intended naming conventions. If you are using project files, -file naming is controlled by Source_File_Name_Project pragmas, which are -usually supplied automatically by the project manager. A pragma -Source_File_Name cannot appear after a @ref{e7,,Pragma Source_File_Name_Project}. - -For more details on the use of the @code{Source_File_Name} pragma, see the -sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} -in the @cite{GNAT User’s Guide}. - -@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e7} -@section Pragma Source_File_Name_Project - - -This pragma has the same syntax and semantics as pragma Source_File_Name. -It is only allowed as a stand-alone configuration pragma. -It cannot appear after a @ref{e6,,Pragma Source_File_Name}, and -most importantly, once pragma Source_File_Name_Project appears, -no further Source_File_Name pragmas are allowed. - -The intention is that Source_File_Name_Project pragmas are always -generated by the Project Manager in a manner consistent with the naming -specified in a project file, and when naming is controlled in this manner, -it is not permissible to attempt to modify this naming scheme using -Source_File_Name or Source_File_Name_Project pragmas (which would not be -known to the project manager). - -@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e9} -@section Pragma Source_Reference - - -Syntax: - -@example -pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); -@end example - -This pragma must appear as the first line of a source file. -@code{integer_literal} is the logical line number of the line following -the pragma line (for use in error messages and debugging -information). @code{string_literal} is a static string constant that -specifies the file name to be used in error messages and debugging -information. This is most notably used for the output of @code{gnatchop} -with the `-r' switch, to make sure that the original unchopped -source file is the one referred to. - -The second argument must be a string literal, it cannot be a static -string expression other than a string literal. This is because its value -is needed for error messages issued by all phases of the compiler. - -@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{eb} -@section Pragma SPARK_Mode - - -Syntax: - -@example -pragma SPARK_Mode [(On | Off)] ; -@end example - -In general a program can have some parts that are in SPARK 2014 (and -follow all the rules in the SPARK Reference Manual), and some parts -that are full Ada 2012. - -The SPARK_Mode pragma is used to identify which parts are in SPARK -2014 (by default programs are in full Ada). The SPARK_Mode pragma can -be used in the following places: - - -@itemize * - -@item -As a configuration pragma, in which case it sets the default mode for -all units compiled with this pragma. - -@item -Immediately following a library-level subprogram spec - -@item -Immediately within a library-level package body - -@item -Immediately following the @code{private} keyword of a library-level -package spec - -@item -Immediately following the @code{begin} keyword of a library-level -package body - -@item -Immediately within a library-level subprogram body -@end itemize - -Normally a subprogram or package spec/body inherits the current mode -that is active at the point it is declared. But this can be overridden -by pragma within the spec or body as above. - -The basic consistency rule is that you can’t turn SPARK_Mode back -@code{On}, once you have explicitly (with a pragma) turned if -@code{Off}. So the following rules apply: - -If a subprogram spec has SPARK_Mode @code{Off}, then the body must -also have SPARK_Mode @code{Off}. - -For a package, we have four parts: - - -@itemize * - -@item -the package public declarations - -@item -the package private part - -@item -the body of the package - -@item -the elaboration code after @code{begin} -@end itemize - -For a package, the rule is that if you explicitly turn SPARK_Mode -@code{Off} for any part, then all the following parts must have -SPARK_Mode @code{Off}. Note that this may require repeating a pragma -SPARK_Mode (@code{Off}) in the body. For example, if we have a -configuration pragma SPARK_Mode (@code{On}) that turns the mode on by -default everywhere, and one particular package spec has pragma -SPARK_Mode (@code{Off}), then that pragma will need to be repeated in -the package body. - -@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ec} -@section Pragma Static_Elaboration_Desired - - -Syntax: - -@example -pragma Static_Elaboration_Desired; -@end example - -This pragma is used to indicate that the compiler should attempt to initialize -statically the objects declared in the library unit to which the pragma applies, -when these objects are initialized (explicitly or implicitly) by an aggregate. -In the absence of this pragma, aggregates in object declarations are expanded -into assignments and loops, even when the aggregate components are static -constants. When the aggregate is present the compiler builds a static expression -that requires no run-time code, so that the initialized object can be placed in -read-only data space. If the components are not static, or the aggregate has -more that 100 components, the compiler emits a warning that the pragma cannot -be obeyed. (See also the restriction No_Implicit_Loops, which supports static -construction of larger aggregates with static components that include an others -choice.) - -@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ed} -@section Pragma Stream_Convert - - -Syntax: - -@example -pragma Stream_Convert ( - [Entity =>] type_LOCAL_NAME, - [Read =>] function_NAME, - [Write =>] function_NAME); -@end example - -This pragma provides an efficient way of providing user-defined stream -attributes. Not only is it simpler to use than specifying the attributes -directly, but more importantly, it allows the specification to be made in such -a way that the predefined unit Ada.Streams is not loaded unless it is actually -needed (i.e. unless the stream attributes are actually used); the use of -the Stream_Convert pragma adds no overhead at all, unless the stream -attributes are actually used on the designated type. - -The first argument specifies the type for which stream functions are -provided. The second parameter provides a function used to read values -of this type. It must name a function whose argument type may be any -subtype, and whose returned type must be the type given as the first -argument to the pragma. - -The meaning of the @code{Read} parameter is that if a stream attribute directly -or indirectly specifies reading of the type given as the first parameter, -then a value of the type given as the argument to the Read function is -read from the stream, and then the Read function is used to convert this -to the required target type. - -Similarly the @code{Write} parameter specifies how to treat write attributes -that directly or indirectly apply to the type given as the first parameter. -It must have an input parameter of the type specified by the first parameter, -and the return type must be the same as the input type of the Read function. -The effect is to first call the Write function to convert to the given stream -type, and then write the result type to the stream. - -The Read and Write functions must not be overloaded subprograms. If necessary -renamings can be supplied to meet this requirement. -The usage of this attribute is best illustrated by a simple example, taken -from the GNAT implementation of package Ada.Strings.Unbounded: - -@example -function To_Unbounded (S : String) return Unbounded_String - renames To_Unbounded_String; - -pragma Stream_Convert - (Unbounded_String, To_Unbounded, To_String); -@end example - -The specifications of the referenced functions, as given in the Ada -Reference Manual are: - -@example -function To_Unbounded_String (Source : String) - return Unbounded_String; - -function To_String (Source : Unbounded_String) - return String; -@end example - -The effect is that if the value of an unbounded string is written to a stream, -then the representation of the item in the stream is in the same format that -would be used for @code{Standard.String'Output}, and this same representation -is expected when a value of this type is read from the stream. Note that the -value written always includes the bounds, even for Unbounded_String’Write, -since Unbounded_String is not an array type. - -Note that the @code{Stream_Convert} pragma is not effective in the case of -a derived type of a non-limited tagged type. If such a type is specified then -the pragma is silently ignored, and the default implementation of the stream -attributes is used instead. - -@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ee} -@section Pragma Style_Checks - - -Syntax: - -@example -pragma Style_Checks (string_LITERAL | ALL_CHECKS | - On | Off [, LOCAL_NAME]); -@end example - -This pragma is used in conjunction with compiler switches to control the -built in style checking provided by GNAT. The compiler switches, if set, -provide an initial setting for the switches, and this pragma may be used -to modify these settings, or the settings may be provided entirely by -the use of the pragma. This pragma can be used anywhere that a pragma -is legal, including use as a configuration pragma (including use in -the @code{gnat.adc} file). - -The form with a string literal specifies which style options are to be -activated. These are additive, so they apply in addition to any previously -set style check options. The codes for the options are the same as those -used in the `-gnaty' switch to `gcc' or `gnatmake'. -For example the following two methods can be used to enable -layout checking: - - -@itemize * - -@item -@example -pragma Style_Checks ("l"); -@end example - -@item -@example -gcc -c -gnatyl ... -@end example -@end itemize - -The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent -to the use of the @code{gnaty} switch with no options. -See the @cite{GNAT User’s Guide} for details.) - -Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). -In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check -options (i.e. equivalent to @code{-gnatyg}). - -The forms with @code{Off} and @code{On} -can be used to temporarily disable style checks -as shown in the following example: - -@example -pragma Style_Checks ("k"); -- requires keywords in lower case -pragma Style_Checks (Off); -- turn off style checks -NULL; -- this will not generate an error message -pragma Style_Checks (On); -- turn style checks back on -NULL; -- this will generate an error message -@end example - -Finally the two argument form is allowed only if the first argument is -@code{On} or @code{Off}. The effect is to turn of semantic style checks -for the specified entity, as shown in the following example: - -@example -pragma Style_Checks ("r"); -- require consistency of identifier casing -Arg : Integer; -Rf1 : Integer := ARG; -- incorrect, wrong case -pragma Style_Checks (Off, Arg); -Rf2 : Integer := ARG; -- OK, no error -@end example - -@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ef} -@section Pragma Subtitle - - -Syntax: - -@example -pragma Subtitle ([Subtitle =>] STRING_LITERAL); -@end example - -This pragma is recognized for compatibility with other Ada compilers -but is ignored by GNAT. - -@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f0} -@section Pragma Suppress - - -Syntax: - -@example -pragma Suppress (Identifier [, [On =>] Name]); -@end example - -This is a standard pragma, and supports all the check names required in -the RM. It is included here because GNAT recognizes some additional check -names that are implementation defined (as permitted by the RM): - - -@itemize * - -@item -@code{Alignment_Check} can be used to suppress alignment checks -on addresses used in address clauses. Such checks can also be suppressed -by suppressing range checks, but the specific use of @code{Alignment_Check} -allows suppression of alignment checks without suppressing other range checks. -Note that @code{Alignment_Check} is suppressed by default on machines (such as -the x86) with non-strict alignment. - -@item -@code{Atomic_Synchronization} can be used to suppress the special memory -synchronization instructions that are normally generated for access to -@code{Atomic} variables to ensure correct synchronization between tasks -that use such variables for synchronization purposes. - -@item -@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated -for a duplicated tag value when a tagged type is declared. - -@item -@code{Container_Checks} Can be used to suppress all checks within Ada.Containers -and instances of its children, including Tampering_Check. - -@item -@code{Tampering_Check} Can be used to suppress tampering check in the containers. - -@item -@code{Predicate_Check} can be used to control whether predicate checks are -active. It is applicable only to predicates for which the policy is -@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given -predicate is ignored or checked for the whole program, the use of -@code{Suppress} and @code{Unsuppress} with this check name allows a given -predicate to be turned on and off at specific points in the program. - -@item -@code{Validity_Check} can be used specifically to control validity checks. -If @code{Suppress} is used to suppress validity checks, then no validity -checks are performed, including those specified by the appropriate compiler -switch or the @code{Validity_Checks} pragma. - -@item -Additional check names previously introduced by use of the @code{Check_Name} -pragma are also allowed. -@end itemize - -Note that pragma Suppress gives the compiler permission to omit -checks, but does not require the compiler to omit checks. The compiler -will generate checks if they are essentially free, even when they are -suppressed. In particular, if the compiler can prove that a certain -check will necessarily fail, it will generate code to do an -unconditional ‘raise’, even if checks are suppressed. The compiler -warns in this case. - -Of course, run-time checks are omitted whenever the compiler can prove -that they will not fail, whether or not checks are suppressed. - -@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f1} -@section Pragma Suppress_All - - -Syntax: - -@example -pragma Suppress_All; -@end example - -This pragma can appear anywhere within a unit. -The effect is to apply @code{Suppress (All_Checks)} to the unit -in which it appears. This pragma is implemented for compatibility with DEC -Ada 83 usage where it appears at the end of a unit, and for compatibility -with Rational Ada, where it appears as a program unit pragma. -The use of the standard Ada pragma @code{Suppress (All_Checks)} -as a normal configuration pragma is the preferred usage in GNAT. - -@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f2}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f3} -@section Pragma Suppress_Debug_Info - - -Syntax: - -@example -pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); -@end example - -This pragma can be used to suppress generation of debug information -for the specified entity. It is intended primarily for use in debugging -the debugger, and navigating around debugger problems. - -@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f4} -@section Pragma Suppress_Exception_Locations - - -Syntax: - -@example -pragma Suppress_Exception_Locations; -@end example - -In normal mode, a raise statement for an exception by default generates -an exception message giving the file name and line number for the location -of the raise. This is useful for debugging and logging purposes, but this -entails extra space for the strings for the messages. The configuration -pragma @code{Suppress_Exception_Locations} can be used to suppress the -generation of these strings, with the result that space is saved, but the -exception message for such raises is null. This configuration pragma may -appear in a global configuration pragma file, or in a specific unit as -usual. It is not required that this pragma be used consistently within -a partition, so it is fine to have some units within a partition compiled -with this pragma and others compiled in normal mode without it. - -@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f6} -@section Pragma Suppress_Initialization - - -@geindex Suppressing initialization - -@geindex Initialization -@geindex suppression of - -Syntax: - -@example -pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); -@end example - -Here variable_or_subtype_Name is the name introduced by a type declaration -or subtype declaration or the name of a variable introduced by an -object declaration. - -In the case of a type or subtype -this pragma suppresses any implicit or explicit initialization -for all variables of the given type or subtype, -including initialization resulting from the use of pragmas -Normalize_Scalars or Initialize_Scalars. - -This is considered a representation item, so it cannot be given after -the type is frozen. It applies to all subsequent object declarations, -and also any allocator that creates objects of the type. - -If the pragma is given for the first subtype, then it is considered -to apply to the base type and all its subtypes. If the pragma is given -for other than a first subtype, then it applies only to the given subtype. -The pragma may not be given after the type is frozen. - -Note that this includes eliminating initialization of discriminants -for discriminated types, and tags for tagged types. In these cases, -you will have to use some non-portable mechanism (e.g. address -overlays or unchecked conversion) to achieve required initialization -of these fields before accessing any object of the corresponding type. - -For the variable case, implicit initialization for the named variable -is suppressed, just as though its subtype had been given in a pragma -Suppress_Initialization, as described above. - -@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f7} -@section Pragma Task_Name - - -Syntax - -@example -pragma Task_Name (string_EXPRESSION); -@end example - -This pragma appears within a task definition (like pragma -@code{Priority}) and applies to the task in which it appears. The -argument must be of type String, and provides a name to be used for -the task instance when the task is created. Note that this expression -is not required to be static, and in particular, it can contain -references to task discriminants. This facility can be used to -provide different names for different tasks as they are created, -as illustrated in the example below. - -The task name is recorded internally in the run-time structures -and is accessible to tools like the debugger. In addition the -routine @code{Ada.Task_Identification.Image} will return this -string, with a unique task address appended. - -@example --- Example of the use of pragma Task_Name - -with Ada.Task_Identification; -use Ada.Task_Identification; -with Text_IO; use Text_IO; -procedure t3 is - - type Astring is access String; - - task type Task_Typ (Name : access String) is - pragma Task_Name (Name.all); - end Task_Typ; - - task body Task_Typ is - Nam : constant String := Image (Current_Task); - begin - Put_Line ("-->" & Nam (1 .. 14) & "<--"); - end Task_Typ; - - type Ptr_Task is access Task_Typ; - Task_Var : Ptr_Task; - -begin - Task_Var := - new Task_Typ (new String'("This is task 1")); - Task_Var := - new Task_Typ (new String'("This is task 2")); -end; -@end example - -@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f8} -@section Pragma Task_Storage - - -Syntax: - -@example -pragma Task_Storage ( - [Task_Type =>] LOCAL_NAME, - [Top_Guard =>] static_integer_EXPRESSION); -@end example - -This pragma specifies the length of the guard area for tasks. The guard -area is an additional storage area allocated to a task. A value of zero -means that either no guard area is created or a minimal guard area is -created, depending on the target. This pragma can appear anywhere a -@code{Storage_Size} attribute definition clause is allowed for a task -type. - -@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f9}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fa} -@section Pragma Test_Case - - -@geindex Test cases - -Syntax: - -@example -pragma Test_Case ( - [Name =>] static_string_Expression - ,[Mode =>] (Nominal | Robustness) - [, Requires => Boolean_Expression] - [, Ensures => Boolean_Expression]); -@end example - -The @code{Test_Case} pragma allows defining fine-grain specifications -for use by testing tools. -The compiler checks the validity of the @code{Test_Case} pragma, but its -presence does not lead to any modification of the code generated by the -compiler. - -@code{Test_Case} pragmas may only appear immediately following the -(separate) declaration of a subprogram in a package declaration, inside -a package spec unit. Only other pragmas may intervene (that is appear -between the subprogram declaration and a test case). - -The compiler checks that boolean expressions given in @code{Requires} and -@code{Ensures} are valid, where the rules for @code{Requires} are the -same as the rule for an expression in @code{Precondition} and the rules -for @code{Ensures} are the same as the rule for an expression in -@code{Postcondition}. In particular, attributes @code{'Old} and -@code{'Result} can only be used within the @code{Ensures} -expression. The following is an example of use within a package spec: - -@example -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Test_Case (Name => "Test 1", - Mode => Nominal, - Requires => Arg < 10000.0, - Ensures => Sqrt'Result < 10.0); - ... -end Math_Functions; -@end example - -The meaning of a test case is that there is at least one context where -@code{Requires} holds such that, if the associated subprogram is executed in -that context, then @code{Ensures} holds when the subprogram returns. -Mode @code{Nominal} indicates that the input context should also satisfy the -precondition of the subprogram, and the output context should also satisfy its -postcondition. Mode @code{Robustness} indicates that the precondition and -postcondition of the subprogram should be ignored for this test case. - -@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fb}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fc} -@section Pragma Thread_Local_Storage - - -@geindex Task specific storage - -@geindex TLS (Thread Local Storage) - -@geindex Task_Attributes - -Syntax: - -@example -pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); -@end example - -This pragma specifies that the specified entity, which must be -a variable declared in a library-level package, is to be marked as -“Thread Local Storage” (@code{TLS}). On systems supporting this (which -include Windows, Solaris, GNU/Linux, and VxWorks), this causes each -thread (and hence each Ada task) to see a distinct copy of the variable. - -The variable must not have default initialization, and if there is -an explicit initialization, it must be either @code{null} for an -access variable, a static expression for a scalar variable, or a fully -static aggregate for a composite type, that is to say, an aggregate all -of whose components are static, and which does not include packed or -discriminated components. - -This provides a low-level mechanism similar to that provided by -the @code{Ada.Task_Attributes} package, but much more efficient -and is also useful in writing interface code that will interact -with foreign threads. - -If this pragma is used on a system where @code{TLS} is not supported, -then an error message will be generated and the program will be rejected. - -@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fd} -@section Pragma Time_Slice - - -Syntax: - -@example -pragma Time_Slice (static_duration_EXPRESSION); -@end example - -For implementations of GNAT on operating systems where it is possible -to supply a time slice value, this pragma may be used for this purpose. -It is ignored if it is used in a system that does not allow this control, -or if it appears in other than the main program unit. - -@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fe} -@section Pragma Title - - -Syntax: - -@example -pragma Title (TITLING_OPTION [, TITLING OPTION]); - -TITLING_OPTION ::= - [Title =>] STRING_LITERAL, -| [Subtitle =>] STRING_LITERAL -@end example - -Syntax checked but otherwise ignored by GNAT. This is a listing control -pragma used in DEC Ada 83 implementations to provide a title and/or -subtitle for the program listing. The program listing generated by GNAT -does not have titles or subtitles. - -Unlike other pragmas, the full flexibility of named notation is allowed -for this pragma, i.e., the parameters may be given in any order if named -notation is used, and named and positional notation can be mixed -following the normal rules for procedure calls in Ada. - -@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{ff} -@section Pragma Type_Invariant - - -Syntax: - -@example -pragma Type_Invariant - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -The @code{Type_Invariant} pragma is intended to be an exact -replacement for the language-defined @code{Type_Invariant} -aspect, and shares its restrictions and semantics. It differs -from the language defined @code{Invariant} pragma in that it -does not permit a string parameter, and it is -controlled by the assertion identifier @code{Type_Invariant} -rather than @code{Invariant}. - -@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{101} -@section Pragma Type_Invariant_Class - - -Syntax: - -@example -pragma Type_Invariant_Class - ([Entity =>] type_LOCAL_NAME, - [Check =>] EXPRESSION); -@end example - -The @code{Type_Invariant_Class} pragma is intended to be an exact -replacement for the language-defined @code{Type_Invariant'Class} -aspect, and shares its restrictions and semantics. - -Note: This pragma is called @code{Type_Invariant_Class} rather than -@code{Type_Invariant'Class} because the latter would not be strictly -conforming to the allowed syntax for pragmas. The motivation -for providing pragmas equivalent to the aspects is to allow a program -to be written using the pragmas, and then compiled if necessary -using an Ada compiler that does not recognize the pragmas or -aspects, but is prepared to ignore the pragmas. The assertion -policy that controls this pragma is @code{Type_Invariant'Class}, -not @code{Type_Invariant_Class}. - -@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{102} -@section Pragma Unchecked_Union - - -@geindex Unions in C - -Syntax: - -@example -pragma Unchecked_Union (first_subtype_LOCAL_NAME); -@end example - -This pragma is used to specify a representation of a record type that is -equivalent to a C union. It was introduced as a GNAT implementation defined -pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this -pragma, making it language defined, and GNAT fully implements this extended -version in all language modes (Ada 83, Ada 95, and Ada 2005). For full -details, consult the Ada 2012 Reference Manual, section B.3.3. - -@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{103} -@section Pragma Unevaluated_Use_Of_Old - - -@geindex Attribute Old - -@geindex Attribute Loop_Entry - -@geindex Unevaluated_Use_Of_Old - -Syntax: - -@example -pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); -@end example - -This pragma controls the processing of attributes Old and Loop_Entry. -If either of these attributes is used in a potentially unevaluated -expression (e.g. the then or else parts of an if expression), then -normally this usage is considered illegal if the prefix of the attribute -is other than an entity name. The language requires this -behavior for Old, and GNAT copies the same rule for Loop_Entry. - -The reason for this rule is that otherwise, we can have a situation -where we save the Old value, and this results in an exception, even -though we might not evaluate the attribute. Consider this example: - -@example -package UnevalOld is - K : Character; - procedure U (A : String; C : Boolean) -- ERROR - with Post => (if C then A(1)'Old = K else True); -end; -@end example - -If procedure U is called with a string with a lower bound of 2, and -C false, then an exception would be raised trying to evaluate A(1) -on entry even though the value would not be actually used. - -Although the rule guarantees against this possibility, it is sometimes -too restrictive. For example if we know that the string has a lower -bound of 1, then we will never raise an exception. -The pragma @code{Unevaluated_Use_Of_Old} can be -used to modify this behavior. If the argument is @code{Error} then an -error is given (this is the default RM behavior). If the argument is -@code{Warn} then the usage is allowed as legal but with a warning -that an exception might be raised. If the argument is @code{Allow} -then the usage is allowed as legal without generating a warning. - -This pragma may appear as a configuration pragma, or in a declarative -part or package specification. In the latter case it applies to -uses up to the end of the corresponding statement sequence or -sequence of package declarations. - -@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{104} -@section Pragma Unimplemented_Unit - - -Syntax: - -@example -pragma Unimplemented_Unit; -@end example - -If this pragma occurs in a unit that is processed by the compiler, GNAT -aborts with the message @code{xxx not implemented}, where -@code{xxx} is the name of the current compilation unit. This pragma is -intended to allow the compiler to handle unimplemented library units in -a clean manner. - -The abort only happens if code is being generated. Thus you can use -specs of unimplemented packages in syntax or semantic checking mode. - -@node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{106} -@section Pragma Universal_Aliasing - - -Syntax: - -@example -pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; -@end example - -@code{type_LOCAL_NAME} must refer to a type declaration in the current -declarative part. The effect is to inhibit strict type-based aliasing -optimization for the given type. In other words, the effect is as though -access types designating this type were subject to pragma No_Strict_Aliasing. -For a detailed description of the strict aliasing optimization, and the -situations in which it must be suppressed, see the section on -@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. - -@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{107}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108} -@section Pragma Unmodified - - -@geindex Warnings -@geindex unmodified - -Syntax: - -@example -pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); -@end example - -This pragma signals that the assignable entities (variables, -@code{out} parameters, @code{in out} parameters) whose names are listed are -deliberately not assigned in the current source unit. This -suppresses warnings about the -entities being referenced but not assigned, and in addition a warning will be -generated if one of these entities is in fact assigned in the -same unit as the pragma (or in the corresponding body, or one -of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not modified, even though the spec suggests that it might -be. - -For the variable case, warnings are never given for unreferenced variables -whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unmodified} for such -variables, though it is harmless to do so. - -@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{109}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a} -@section Pragma Unreferenced - - -@geindex Warnings -@geindex unreferenced - -Syntax: - -@example -pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); -pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); -@end example - -This pragma signals that the entities whose names are listed are -deliberately not referenced in the current source unit after the -occurrence of the pragma. This -suppresses warnings about the -entities being unreferenced, and in addition a warning will be -generated if one of these entities is in fact subsequently referenced in the -same unit as the pragma (or in the corresponding body, or one -of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not referenced in some particular subprogram implementation -and that this is deliberate. It can also be useful in the case of -objects declared only for their initialization or finalization side -effects. - -If @code{LOCAL_NAME} identifies more than one matching homonym in the -current scope, then the entity most recently declared is the one to which -the pragma applies. Note that in the case of accept formals, the pragma -Unreferenced may appear immediately after the keyword @code{do} which -allows the indication of whether or not accept formals are referenced -or not to be given individually for each accept statement. - -The left hand side of an assignment does not count as a reference for the -purpose of this pragma. Thus it is fine to assign to an entity for which -pragma Unreferenced is given. However, use of an entity as an actual for -an out parameter does count as a reference unless warnings for unread output -parameters are enabled via @code{-gnatw.o}. - -Note that if a warning is desired for all calls to a given subprogram, -regardless of whether they occur in the same unit as the subprogram -declaration, then this pragma should not be used (calls from another -unit would not be flagged); pragma Obsolescent can be used instead -for this purpose, see @ref{ac,,Pragma Obsolescent}. - -The second form of pragma @code{Unreferenced} is used within a context -clause. In this case the arguments must be unit names of units previously -mentioned in @code{with} clauses (similar to the usage of pragma -@code{Elaborate_All}). The effect is to suppress warnings about unreferenced -units and unreferenced entities within these units. - -For the variable case, warnings are never given for unreferenced variables -whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unreferenced} for such -variables, though it is harmless to do so. - -@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c} -@section Pragma Unreferenced_Objects - - -@geindex Warnings -@geindex unreferenced - -Syntax: - -@example -pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); -@end example - -This pragma signals that for the types or subtypes whose names are -listed, objects which are declared with one of these types or subtypes may -not be referenced, and if no references appear, no warnings are given. - -This is particularly useful for objects which are declared solely for their -initialization and finalization effect. Such variables are sometimes referred -to as RAII variables (Resource Acquisition Is Initialization). Using this -pragma on the relevant type (most typically a limited controlled type), the -compiler will automatically suppress unwanted warnings about these variables -not being referenced. - -@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10d} -@section Pragma Unreserve_All_Interrupts - - -Syntax: - -@example -pragma Unreserve_All_Interrupts; -@end example - -Normally certain interrupts are reserved to the implementation. Any attempt -to attach an interrupt causes Program_Error to be raised, as described in -RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in -many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is -reserved to the implementation, so that @code{Ctrl-C} can be used to -interrupt execution. - -If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in -a program, then all such interrupts are unreserved. This allows the -program to handle these interrupts, but disables their standard -functions. For example, if this pragma is used, then pressing -@code{Ctrl-C} will not automatically interrupt execution. However, -a program can then handle the @code{SIGINT} interrupt as it chooses. - -For a full list of the interrupts handled in a specific implementation, -see the source code for the spec of @code{Ada.Interrupts.Names} in -file @code{a-intnam.ads}. This is a target dependent file that contains the -list of interrupts recognized for a given target. The documentation in -this file also specifies what interrupts are affected by the use of -the @code{Unreserve_All_Interrupts} pragma. - -For a more general facility for controlling what interrupts can be -handled, see pragma @code{Interrupt_State}, which subsumes the functionality -of the @code{Unreserve_All_Interrupts} pragma. - -@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10e} -@section Pragma Unsuppress - - -Syntax: - -@example -pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); -@end example - -This pragma undoes the effect of a previous pragma @code{Suppress}. If -there is no corresponding pragma @code{Suppress} in effect, it has no -effect. The range of the effect is the same as for pragma -@code{Suppress}. The meaning of the arguments is identical to that used -in pragma @code{Suppress}. - -One important application is to ensure that checks are on in cases where -code depends on the checks for its correct functioning, so that the code -will compile correctly even if the compiler switches are set to suppress -checks. For example, in a program that depends on external names of tagged -types and wants to ensure that the duplicated tag check occurs even if all -run-time checks are suppressed by a compiler switch, the following -configuration pragma will ensure this test is not suppressed: - -@example -pragma Unsuppress (Duplicated_Tag_Check); -@end example - -This pragma is standard in Ada 2005. It is available in all earlier versions -of Ada as an implementation-defined pragma. - -Note that in addition to the checks defined in the Ada RM, GNAT recognizes a -number of implementation-defined check names. See the description of pragma -@code{Suppress} for full details. - -@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{10f} -@section Pragma Use_VADS_Size - - -@geindex Size -@geindex VADS compatibility - -@geindex Rational profile - -Syntax: - -@example -pragma Use_VADS_Size; -@end example - -This is a configuration pragma. In a unit to which it applies, any use -of the ‘Size attribute is automatically interpreted as a use of the -‘VADS_Size attribute. Note that this may result in incorrect semantic -processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in -the handling of existing code which depends on the interpretation of Size -as implemented in the VADS compiler. See description of the VADS_Size -attribute for further details. - -@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111} -@section Pragma Unused - - -@geindex Warnings -@geindex unused - -Syntax: - -@example -pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); -@end example - -This pragma signals that the assignable entities (variables, -@code{out} parameters, and @code{in out} parameters) whose names are listed -deliberately do not get assigned or referenced in the current source unit -after the occurrence of the pragma in the current source unit. This -suppresses warnings about the entities that are unreferenced and/or not -assigned, and, in addition, a warning will be generated if one of these -entities gets assigned or subsequently referenced in the same unit as the -pragma (in the corresponding body or one of its subunits). - -This is particularly useful for clearly signaling that a particular -parameter is not modified or referenced, even though the spec suggests -that it might be. - -For the variable case, warnings are never given for unreferenced -variables whose name contains one of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names -are typically to be used in cases where such warnings are expected. -Thus it is never necessary to use @code{pragma Unused} for such -variables, though it is harmless to do so. - -@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{112} -@section Pragma Validity_Checks - - -Syntax: - -@example -pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); -@end example - -This pragma is used in conjunction with compiler switches to control the -built-in validity checking provided by GNAT. The compiler switches, if set -provide an initial setting for the switches, and this pragma may be used -to modify these settings, or the settings may be provided entirely by -the use of the pragma. This pragma can be used anywhere that a pragma -is legal, including use as a configuration pragma (including use in -the @code{gnat.adc} file). - -The form with a string literal specifies which validity options are to be -activated. The validity checks are first set to include only the default -reference manual settings, and then a string of letters in the string -specifies the exact set of options required. The form of this string -is exactly as described for the `-gnatVx' compiler switch (see the -GNAT User’s Guide for details). For example the following two -methods can be used to enable validity checking for mode @code{in} and -@code{in out} subprogram parameters: - - -@itemize * - -@item -@example -pragma Validity_Checks ("im"); -@end example - -@item -@example -$ gcc -c -gnatVim ... -@end example -@end itemize - -The form ALL_CHECKS activates all standard checks (its use is equivalent -to the use of the @code{gnatVa} switch). - -The forms with @code{Off} and @code{On} can be used to temporarily disable -validity checks as shown in the following example: - -@example -pragma Validity_Checks ("c"); -- validity checks for copies -pragma Validity_Checks (Off); -- turn off validity checks -A := B; -- B will not be validity checked -pragma Validity_Checks (On); -- turn validity checks back on -A := C; -- C will be validity checked -@end example - -@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114} -@section Pragma Volatile - - -Syntax: - -@example -pragma Volatile (LOCAL_NAME); -@end example - -This pragma is defined by the Ada Reference Manual, and the GNAT -implementation is fully conformant with this definition. The reason it -is mentioned in this section is that a pragma of the same name was supplied -in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 -implementation of pragma Volatile is upwards compatible with the -implementation in DEC Ada 83. - -@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{116} -@section Pragma Volatile_Full_Access - - -Syntax: - -@example -pragma Volatile_Full_Access (LOCAL_NAME); -@end example - -This is similar in effect to pragma Volatile, except that any reference to the -object is guaranteed to be done only with instructions that read or write all -the bits of the object. Furthermore, if the object is of a composite type, -then any reference to a subcomponent of the object is guaranteed to read -and/or write all the bits of the object. - -The intention is that this be suitable for use with memory-mapped I/O devices -on some machines. Note that there are two important respects in which this is -different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} -object is not a sequential action in the RM 9.10 sense and, therefore, does -not create a synchronization point. Second, in the case of @code{pragma Atomic}, -there is no guarantee that all the bits will be accessed if the reference -is not to the whole object; the compiler is allowed (and generally will) -access only part of the object in this case. - -@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118} -@section Pragma Volatile_Function - - -Syntax: - -@example -pragma Volatile_Function [ (static_boolean_EXPRESSION) ]; -@end example - -For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} -in the SPARK 2014 Reference Manual, section 7.1.2. - -@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{119} -@section Pragma Warning_As_Error - - -Syntax: - -@example -pragma Warning_As_Error (static_string_EXPRESSION); -@end example - -This configuration pragma allows the programmer to specify a set -of warnings that will be treated as errors. Any warning that -matches the pattern given by the pragma argument will be treated -as an error. This gives more precise control than -gnatwe, -which treats warnings as errors. - -This pragma can apply to regular warnings (messages enabled by -gnatw) -and to style warnings (messages that start with “(style)”, -enabled by -gnaty). - -The pattern may contain asterisks, which match zero or more characters -in the message. For example, you can use @code{pragma Warning_As_Error -("bits of*unused")} to treat the warning message @code{warning: 960 bits of -"a" unused} as an error. All characters other than asterisk are treated -as literal characters in the match. The match is case insensitive; for -example XYZ matches xyz. - -Note that the pattern matches if it occurs anywhere within the warning -message string (it is not necessary to put an asterisk at the start and -the end of the message, since this is implied). - -Another possibility for the static_string_EXPRESSION which works whether -or not error tags are enabled (`-gnatw.d') is to use a single -`-gnatw' tag string, enclosed in brackets, -as shown in the example below, to treat one category of warnings as errors. -Note that if you want to treat multiple categories of warnings as errors, -you can use multiple pragma Warning_As_Error. - -The above use of patterns to match the message applies only to warning -messages generated by the front end. This pragma can also be applied to -warnings provided by the back end and mentioned in @ref{11a,,Pragma Warnings}. -By using a single full `-Wxxx' switch in the pragma, such warnings -can also be treated as errors. - -The pragma can appear either in a global configuration pragma file -(e.g. @code{gnat.adc}), or at the start of a file. Given a global -configuration pragma file containing: - -@example -pragma Warning_As_Error ("[-gnatwj]"); -@end example - -which will treat all obsolescent feature warnings as errors, the -following program compiles as shown (compile options here are -`-gnatwa.d -gnatl -gnatj55'). - -@example - 1. pragma Warning_As_Error ("*never assigned*"); - 2. function Warnerr return String is - 3. X : Integer; - | - >>> error: variable "X" is never read and - never assigned [-gnatwv] [warning-as-error] - - 4. Y : Integer; - | - >>> warning: variable "Y" is assigned but - never read [-gnatwu] - - 5. begin - 6. Y := 0; - 7. return %ABC%; - | - >>> error: use of "%" is an obsolescent - feature (RM J.2(4)), use """ instead - [-gnatwj] [warning-as-error] - - 8. end; - -8 lines: No errors, 3 warnings (2 treated as errors) -@end example - -Note that this pragma does not affect the set of warnings issued in -any way, it merely changes the effect of a matching warning if one -is produced as a result of other warnings options. As shown in this -example, if the pragma results in a warning being treated as an error, -the tag is changed from “warning:” to “error:” and the string -“[warning-as-error]” is appended to the end of the message. - -@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a} -@section Pragma Warnings - - -Syntax: - -@example -pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); - -DETAILS ::= On | Off -DETAILS ::= On | Off, local_NAME -DETAILS ::= static_string_EXPRESSION -DETAILS ::= On | Off, static_string_EXPRESSION - -TOOL_NAME ::= GNAT | GNATprove - -REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} -@end example - -Note: in Ada 83 mode, a string literal may be used in place of a static string -expression (which does not exist in Ada 83). - -Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the -second form is always understood. If the intention is to use -the fourth form, then you can write @code{NAME & ""} to force the -interpretation as a `static_string_EXPRESSION'. - -Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted -that way. The use of the @code{TOOL_NAME} argument is relevant only to users -of SPARK and GNATprove, see last part of this section for details. - -Normally warnings are enabled, with the output being controlled by -the command line switch. Warnings (@code{Off}) turns off generation of -warnings until a Warnings (@code{On}) is encountered or the end of the -current unit. If generation of warnings is turned off using this -pragma, then some or all of the warning messages are suppressed, -regardless of the setting of the command line switches. - -The @code{Reason} parameter may optionally appear as the last argument -in any of the forms of this pragma. It is intended purely for the -purposes of documenting the reason for the @code{Warnings} pragma. -The compiler will check that the argument is a static string but -otherwise ignore this argument. Other tools may provide specialized -processing for this string. - -The form with a single argument (or two arguments if Reason present), -where the first argument is @code{ON} or @code{OFF} -may be used as a configuration pragma. - -If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for -the specified entity. This suppression is effective from the point where -it occurs till the end of the extended scope of the variable (similar to -the scope of @code{Suppress}). This form cannot be used as a configuration -pragma. - -In the case where the first argument is other than @code{ON} or -@code{OFF}, -the third form with a single static_string_EXPRESSION argument (and possible -reason) provides more precise -control over which warnings are active. The string is a list of letters -specifying which warnings are to be activated and which deactivated. The -code for these letters is the same as the string used in the command -line switch controlling warnings. For a brief summary, use the gnatmake -command with no arguments, which will generate usage information containing -the list of warnings switches supported. For -full details see the section on @code{Warning Message Control} in the -@cite{GNAT User’s Guide}. -This form can also be used as a configuration pragma. - -The warnings controlled by the @code{-gnatw} switch are generated by the -front end of the compiler. The GCC back end can provide additional warnings -and they are controlled by the @code{-W} switch. Such warnings can be -identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the -message which designates the @code{-W`xxx'} switch that controls the message. -The form with a single `static_string_EXPRESSION' argument also works for these -warnings, but the string must be a single full @code{-W`xxx'} switch in this -case. The above reference lists a few examples of these additional warnings. - -The specified warnings will be in effect until the end of the program -or another pragma @code{Warnings} is encountered. The effect of the pragma is -cumulative. Initially the set of warnings is the standard default set -as possibly modified by compiler switches. Then each pragma Warning -modifies this set of warnings as specified. This form of the pragma may -also be used as a configuration pragma. - -The fourth form, with an @code{On|Off} parameter and a string, is used to -control individual messages, based on their text. The string argument -is a pattern that is used to match against the text of individual -warning messages (not including the initial “warning: “ tag). - -The pattern may contain asterisks, which match zero or more characters in -the message. For example, you can use -@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning -message @code{warning: 960 bits of "a" unused}. No other regular -expression notations are permitted. All characters other than asterisk in -these three specific cases are treated as literal characters in the match. -The match is case insensitive, for example XYZ matches xyz. - -Note that the pattern matches if it occurs anywhere within the warning -message string (it is not necessary to put an asterisk at the start and -the end of the message, since this is implied). - -The above use of patterns to match the message applies only to warning -messages generated by the front end. This form of the pragma with a string -argument can also be used to control warnings provided by the back end and -mentioned above. By using a single full @code{-W`xxx'} switch in the pragma, -such warnings can be turned on and off. - -There are two ways to use the pragma in this form. The OFF form can be used -as a configuration pragma. The effect is to suppress all warnings (if any) -that match the pattern string throughout the compilation (or match the --W switch in the back end case). - -The second usage is to suppress a warning locally, and in this case, two -pragmas must appear in sequence: - -@example -pragma Warnings (Off, Pattern); -... code where given warning is to be suppressed -pragma Warnings (On, Pattern); -@end example - -In this usage, the pattern string must match in the Off and On -pragmas, and (if `-gnatw.w' is given) at least one matching -warning must be suppressed. - -Note: if the ON form is not found, then the effect of the OFF form extends -until the end of the file (pragma Warnings is purely textual, so its effect -does not stop at the end of the enclosing scope). - -Note: to write a string that will match any warning, use the string -@code{"***"}. It will not work to use a single asterisk or two -asterisks since this looks like an operator name. This form with three -asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching -@code{pragma Warnings (On, "***")} will be required. This can be -helpful in avoiding forgetting to turn warnings back on. - -Note: the debug flag @code{-gnatd.i} can be -used to cause the compiler to entirely ignore all WARNINGS pragmas. This can -be useful in checking whether obsolete pragmas in existing programs are hiding -real problems. - -Note: pragma Warnings does not affect the processing of style messages. See -separate entry for pragma Style_Checks for control of style messages. - -Users of the formal verification tool GNATprove for the SPARK subset of Ada may -use the version of the pragma with a @code{TOOL_NAME} parameter. - -If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the -compiler or @code{GNATprove} for the formal verification tool. A given tool only -takes into account pragma Warnings that do not specify a tool name, or that -specify the matching tool name. This makes it possible to disable warnings -selectively for each tool, and as a consequence to detect useless pragma -Warnings with switch @code{-gnatw.w}. - -@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11c} -@section Pragma Weak_External - - -Syntax: - -@example -pragma Weak_External ([Entity =>] LOCAL_NAME); -@end example - -@code{LOCAL_NAME} must refer to an object that is declared at the library -level. This pragma specifies that the given entity should be marked as a -weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} -in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead -of a regular symbol, that is to say a symbol that does not have to be -resolved by the linker if used in conjunction with a pragma Import. - -When a weak symbol is not resolved by the linker, its address is set to -zero. This is useful in writing interfaces to external modules that may -or may not be linked in the final executable, for example depending on -configuration settings. - -If a program references at run time an entity to which this pragma has been -applied, and the corresponding symbol was not resolved at link time, then -the execution of the program is erroneous. It is not erroneous to take the -Address of such an entity, for example to guard potential references, -as shown in the example below. - -Some file formats do not support weak symbols so not all target machines -support this pragma. - -@example --- Example of the use of pragma Weak_External - -package External_Module is - key : Integer; - pragma Import (C, key); - pragma Weak_External (key); - function Present return boolean; -end External_Module; - -with System; use System; -package body External_Module is - function Present return boolean is - begin - return key'Address /= System.Null_Address; - end Present; -end External_Module; -@end example - -@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas -@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d} -@section Pragma Wide_Character_Encoding - - -Syntax: - -@example -pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); -@end example - -This pragma specifies the wide character encoding to be used in program -source text appearing subsequently. It is a configuration pragma, but may -also be used at any point that a pragma is allowed, and it is permissible -to have more than one such pragma in a file, allowing multiple encodings -to appear within the same file. - -However, note that the pragma cannot immediately precede the relevant -wide character, because then the previous encoding will still be in -effect, causing “illegal character” errors. - -The argument can be an identifier or a character literal. In the identifier -case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, -@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal -case it is correspondingly one of the characters @code{h}, @code{u}, -@code{s}, @code{e}, @code{8}, or @code{b}. - -Note that when the pragma is used within a file, it affects only the -encoding within that file, and does not affect withed units, specs, -or subunits. - -@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top -@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{120} -@chapter Implementation Defined Aspects - - -Ada defines (throughout the Ada 2012 reference manual, summarized -in Annex K) a set of aspects that can be specified for certain entities. -These language defined aspects are implemented in GNAT in Ada 2012 mode -and work as described in the Ada 2012 Reference Manual. - -In addition, Ada 2012 allows implementations to define additional aspects -whose meaning is defined by the implementation. GNAT provides -a number of these implementation-defined aspects which can be used -to extend and enhance the functionality of the compiler. This section of -the GNAT reference manual describes these additional aspects. - -Note that any program using these aspects may not be portable to -other compilers (although GNAT implements this set of aspects on all -platforms). Therefore if portability to other compilers is an important -consideration, you should minimize the use of these aspects. - -Note that for many of these aspects, the effect is essentially similar -to the use of a pragma or attribute specification with the same name -applied to the entity. For example, if we write: - -@example -type R is range 1 .. 100 - with Value_Size => 10; -@end example - -then the effect is the same as: - -@example -type R is range 1 .. 100; -for R'Value_Size use 10; -@end example - -and if we write: - -@example -type R is new Integer - with Shared => True; -@end example - -then the effect is the same as: - -@example -type R is new Integer; -pragma Shared (R); -@end example - -In the documentation below, such cases are simply marked -as being boolean aspects equivalent to the corresponding pragma -or attribute definition clause. - -@menu -* Aspect Abstract_State:: -* Aspect Annotate:: -* Aspect Async_Readers:: -* Aspect Async_Writers:: -* Aspect Constant_After_Elaboration:: -* Aspect Contract_Cases:: -* Aspect Depends:: -* Aspect Default_Initial_Condition:: -* Aspect Dimension:: -* Aspect Dimension_System:: -* Aspect Disable_Controlled:: -* Aspect Effective_Reads:: -* Aspect Effective_Writes:: -* Aspect Extensions_Visible:: -* Aspect Favor_Top_Level:: -* Aspect Ghost:: -* Aspect Global:: -* Aspect Initial_Condition:: -* Aspect Initializes:: -* Aspect Inline_Always:: -* Aspect Invariant:: -* Aspect Invariant’Class:: -* Aspect Iterable:: -* Aspect Linker_Section:: -* Aspect Lock_Free:: -* Aspect Max_Queue_Length:: -* Aspect No_Caching:: -* Aspect No_Elaboration_Code_All:: -* Aspect No_Inline:: -* Aspect No_Tagged_Streams:: -* Aspect No_Task_Parts:: -* Aspect Object_Size:: -* Aspect Obsolescent:: -* Aspect Part_Of:: -* Aspect Persistent_BSS:: -* Aspect Predicate:: -* Aspect Pure_Function:: -* Aspect Refined_Depends:: -* Aspect Refined_Global:: -* Aspect Refined_Post:: -* Aspect Refined_State:: -* Aspect Relaxed_Initialization:: -* Aspect Remote_Access_Type:: -* Aspect Secondary_Stack_Size:: -* Aspect Scalar_Storage_Order:: -* Aspect Shared:: -* Aspect Simple_Storage_Pool:: -* Aspect Simple_Storage_Pool_Type:: -* Aspect SPARK_Mode:: -* Aspect Suppress_Debug_Info:: -* Aspect Suppress_Initialization:: -* Aspect Test_Case:: -* Aspect Thread_Local_Storage:: -* Aspect Universal_Aliasing:: -* Aspect Unmodified:: -* Aspect Unreferenced:: -* Aspect Unreferenced_Objects:: -* Aspect Value_Size:: -* Aspect Volatile_Full_Access:: -* Aspect Volatile_Function:: -* Aspect Warnings:: - -@end menu - -@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121} -@section Aspect Abstract_State - - -@geindex Abstract_State - -This aspect is equivalent to @ref{1e,,pragma Abstract_State}. - -@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122} -@section Aspect Annotate - - -@geindex Annotate - -There are three forms of this aspect (where ID is an identifier, -and ARG is a general expression), -corresponding to @ref{29,,pragma Annotate}. - - -@table @asis - -@item `Annotate => ID' - -Equivalent to @code{pragma Annotate (ID, Entity => Name);} - -@item `Annotate => (ID)' - -Equivalent to @code{pragma Annotate (ID, Entity => Name);} - -@item `Annotate => (ID ,ID @{, ARG@})' - -Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} -@end table - -@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{123} -@section Aspect Async_Readers - - -@geindex Async_Readers - -This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. - -@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{124} -@section Aspect Async_Writers - - -@geindex Async_Writers - -This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}. - -@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{125} -@section Aspect Constant_After_Elaboration - - -@geindex Constant_After_Elaboration - -This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. - -@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{126} -@section Aspect Contract_Cases - - -@geindex Contract_Cases - -This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence -of clauses being enclosed in parentheses so that syntactically it is an -aggregate. - -@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127} -@section Aspect Depends - - -@geindex Depends - -This aspect is equivalent to @ref{54,,pragma Depends}. - -@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{128} -@section Aspect Default_Initial_Condition - - -@geindex Default_Initial_Condition - -This aspect is equivalent to @ref{4e,,pragma Default_Initial_Condition}. - -@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{129} -@section Aspect Dimension - - -@geindex Dimension - -The @code{Dimension} aspect is used to specify the dimensions of a given -subtype of a dimensioned numeric type. The aspect also specifies a symbol -used when doing formatted output of dimensioned quantities. The syntax is: - -@example -with Dimension => - ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) - -SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL - -DIMENSION_VALUE ::= - RATIONAL -| others => RATIONAL -| DISCRETE_CHOICE_LIST => RATIONAL - -RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] -@end example - -This aspect can only be applied to a subtype whose parent type has -a @code{Dimension_System} aspect. The aspect must specify values for -all dimensions of the system. The rational values are the powers of the -corresponding dimensions that are used by the compiler to verify that -physical (numeric) computations are dimensionally consistent. For example, -the computation of a force must result in dimensions (L => 1, M => 1, T => -2). -For further examples of the usage -of this aspect, see package @code{System.Dim.Mks}. -Note that when the dimensioned type is an integer type, then any -dimension value must be an integer literal. - -@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12a} -@section Aspect Dimension_System - - -@geindex Dimension_System - -The @code{Dimension_System} aspect is used to define a system of -dimensions that will be used in subsequent subtype declarations with -@code{Dimension} aspects that reference this system. The syntax is: - -@example -with Dimension_System => (DIMENSION @{, DIMENSION@}); - -DIMENSION ::= ([Unit_Name =>] IDENTIFIER, - [Unit_Symbol =>] SYMBOL, - [Dim_Symbol =>] SYMBOL) - -SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL -@end example - -This aspect is applied to a type, which must be a numeric derived type -(typically a floating-point type), that -will represent values within the dimension system. Each @code{DIMENSION} -corresponds to one particular dimension. A maximum of 7 dimensions may -be specified. @code{Unit_Name} is the name of the dimension (for example -@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities -of this dimension (for example @code{m} for @code{Meter}). -@code{Dim_Symbol} gives -the identification within the dimension system (typically this is a -single letter, e.g. @code{L} standing for length for unit name @code{Meter}). -The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. -The @code{Dim_Symbol} is used in error messages when numeric operations have -inconsistent dimensions. - -GNAT provides the standard definition of the International MKS system in -the run-time package @code{System.Dim.Mks}. You can easily define -similar packages for cgs units or British units, and define conversion factors -between values in different systems. The MKS system is characterized by the -following aspect: - -@example -type Mks_Type is new Long_Long_Float with - Dimension_System => ( - (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), - (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), - (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), - (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), - (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), - (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), - (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); -@end example - -Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to -represent a theta character (avoiding the use of extended Latin-1 -characters in this context). - -See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users -Guide for detailed examples of use of the dimension system. - -@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12b} -@section Aspect Disable_Controlled - - -@geindex Disable_Controlled - -The aspect @code{Disable_Controlled} is defined for controlled record types. If -active, this aspect causes suppression of all related calls to @code{Initialize}, -@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, -where for example you might want a record to be controlled or not depending on -whether some run-time check is enabled or suppressed. - -@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12c} -@section Aspect Effective_Reads - - -@geindex Effective_Reads - -This aspect is equivalent to @ref{59,,pragma Effective_Reads}. - -@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12d} -@section Aspect Effective_Writes - - -@geindex Effective_Writes - -This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. - -@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12e} -@section Aspect Extensions_Visible - - -@geindex Extensions_Visible - -This aspect is equivalent to @ref{66,,pragma Extensions_Visible}. - -@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12f} -@section Aspect Favor_Top_Level - - -@geindex Favor_Top_Level - -This boolean aspect is equivalent to @ref{6b,,pragma Favor_Top_Level}. - -@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{130} -@section Aspect Ghost - - -@geindex Ghost - -This aspect is equivalent to @ref{6f,,pragma Ghost}. - -@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131} -@section Aspect Global - - -@geindex Global - -This aspect is equivalent to @ref{71,,pragma Global}. - -@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132} -@section Aspect Initial_Condition - - -@geindex Initial_Condition - -This aspect is equivalent to @ref{7e,,pragma Initial_Condition}. - -@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133} -@section Aspect Initializes - - -@geindex Initializes - -This aspect is equivalent to @ref{81,,pragma Initializes}. - -@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134} -@section Aspect Inline_Always - - -@geindex Inline_Always - -This boolean aspect is equivalent to @ref{83,,pragma Inline_Always}. - -@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135} -@section Aspect Invariant - - -@geindex Invariant - -This aspect is equivalent to @ref{8a,,pragma Invariant}. It is a -synonym for the language defined aspect @code{Type_Invariant} except -that it is separately controllable using pragma @code{Assertion_Policy}. - -@node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{136} -@section Aspect Invariant’Class - - -@geindex Invariant'Class - -This aspect is equivalent to @ref{101,,pragma Type_Invariant_Class}. It is a -synonym for the language defined aspect @code{Type_Invariant'Class} except -that it is separately controllable using pragma @code{Assertion_Policy}. - -@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{137} -@section Aspect Iterable - - -@geindex Iterable - -This aspect provides a light-weight mechanism for loops and quantified -expressions over container types, without the overhead imposed by the tampering -checks of standard Ada 2012 iterators. The value of the aspect is an aggregate -with six named components, of which the last three are optional: @code{First}, -@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. -When only the first three components are specified, only the -@code{for .. in} form of iteration over cursors is available. When @code{Element} -is specified, both this form and the @code{for .. of} form of iteration over -elements are available. If the last two components are specified, reverse -iterations over the container can be specified (analogous to what can be done -over predefined containers that support the @code{Reverse_Iterator} interface). -The following is a typical example of use: - -@example -type List is private with - Iterable => (First => First_Cursor, - Next => Advance, - Has_Element => Cursor_Has_Element - [,Element => Get_Element] - [,Last => Last_Cursor] - [,Previous => Retreat]); -@end example - - -@itemize * - -@item -The values of @code{First} and @code{Last} are primitive operations of the -container type that return a @code{Cursor}, which must be a type declared in -the container package or visible from it. For example: -@end itemize - -@example -function First_Cursor (Cont : Container) return Cursor; -function Last_Cursor (Cont : Container) return Cursor; -@end example - - -@itemize * - -@item -The values of @code{Next} and @code{Previous} are primitive operations of the container type that take -both a container and a cursor and yield a cursor. For example: -@end itemize - -@example -function Advance (Cont : Container; Position : Cursor) return Cursor; -function Retreat (Cont : Container; Position : Cursor) return Cursor; -@end example - - -@itemize * - -@item -The value of @code{Has_Element} is a primitive operation of the container type -that takes both a container and a cursor and yields a boolean. For example: -@end itemize - -@example -function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; -@end example - - -@itemize * - -@item -The value of @code{Element} is a primitive operation of the container type that -takes both a container and a cursor and yields an @code{Element_Type}, which must -be a type declared in the container package or visible from it. For example: -@end itemize - -@example -function Get_Element (Cont : Container; Position : Cursor) return Element_Type; -@end example - -This aspect is used in the GNAT-defined formal container packages. - -@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{138} -@section Aspect Linker_Section - - -@geindex Linker_Section - -This aspect is equivalent to @ref{92,,pragma Linker_Section}. - -@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{139} -@section Aspect Lock_Free - - -@geindex Lock_Free - -This boolean aspect is equivalent to @ref{94,,pragma Lock_Free}. - -@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13a} -@section Aspect Max_Queue_Length - - -@geindex Max_Queue_Length - -This aspect is equivalent to @ref{9c,,pragma Max_Queue_Length}. - -@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13b} -@section Aspect No_Caching - - -@geindex No_Caching - -This boolean aspect is equivalent to @ref{9f,,pragma No_Caching}. - -@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13c} -@section Aspect No_Elaboration_Code_All - - -@geindex No_Elaboration_Code_All - -This aspect is equivalent to @ref{a2,,pragma No_Elaboration_Code_All} -for a program unit. - -@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13d} -@section Aspect No_Inline - - -@geindex No_Inline - -This boolean aspect is equivalent to @ref{a5,,pragma No_Inline}. - -@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13e} -@section Aspect No_Tagged_Streams - - -@geindex No_Tagged_Streams - -This aspect is equivalent to @ref{a9,,pragma No_Tagged_Streams} with an -argument specifying a root tagged type (thus this aspect can only be -applied to such a type). - -@node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{13f} -@section Aspect No_Task_Parts - - -@geindex No_Task_Parts - -Applies to a type. If True, requires that the type and any descendants -do not have any task parts. The rules for this aspect are the same as -for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), -replacing “controlled” with “task”. - -If No_Task_Parts is True for a type T, then the compiler can optimize -away certain tasking-related code that would otherwise be needed -for T’Class, because descendants of T might contain tasks. - -@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{140} -@section Aspect Object_Size - - -@geindex Object_Size - -This aspect is equivalent to @ref{141,,attribute Object_Size}. - -@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{142} -@section Aspect Obsolescent - - -@geindex Obsolescent - -This aspect is equivalent to @ref{ac,,pragma Obsolescent}. Note that the -evaluation of this aspect happens at the point of occurrence, it is not -delayed until the freeze point. - -@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{143} -@section Aspect Part_Of - - -@geindex Part_Of - -This aspect is equivalent to @ref{b3,,pragma Part_Of}. - -@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{144} -@section Aspect Persistent_BSS - - -@geindex Persistent_BSS - -This boolean aspect is equivalent to @ref{b6,,pragma Persistent_BSS}. - -@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{145} -@section Aspect Predicate - - -@geindex Predicate - -This aspect is equivalent to @ref{bd,,pragma Predicate}. It is thus -similar to the language defined aspects @code{Dynamic_Predicate} -and @code{Static_Predicate} except that whether the resulting -predicate is static or dynamic is controlled by the form of the -expression. It is also separately controllable using pragma -@code{Assertion_Policy}. - -@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{146} -@section Aspect Pure_Function - - -@geindex Pure_Function - -This boolean aspect is equivalent to @ref{c9,,pragma Pure_Function}. - -@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{147} -@section Aspect Refined_Depends - - -@geindex Refined_Depends - -This aspect is equivalent to @ref{cd,,pragma Refined_Depends}. - -@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{148} -@section Aspect Refined_Global - - -@geindex Refined_Global - -This aspect is equivalent to @ref{cf,,pragma Refined_Global}. - -@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{149} -@section Aspect Refined_Post - - -@geindex Refined_Post - -This aspect is equivalent to @ref{d1,,pragma Refined_Post}. - -@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14a} -@section Aspect Refined_State - - -@geindex Refined_State - -This aspect is equivalent to @ref{d3,,pragma Refined_State}. - -@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14b} -@section Aspect Relaxed_Initialization - - -@geindex Refined_Initialization - -For the syntax and semantics of this aspect, see the SPARK 2014 Reference -Manual, section 6.10. - -@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14c} -@section Aspect Remote_Access_Type - - -@geindex Remote_Access_Type - -This aspect is equivalent to @ref{d6,,pragma Remote_Access_Type}. - -@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14d} -@section Aspect Secondary_Stack_Size - - -@geindex Secondary_Stack_Size - -This aspect is equivalent to @ref{dc,,pragma Secondary_Stack_Size}. - -@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14e} -@section Aspect Scalar_Storage_Order - - -@geindex Scalar_Storage_Order - -This aspect is equivalent to a @ref{14f,,attribute Scalar_Storage_Order}. - -@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{150} -@section Aspect Shared - - -@geindex Shared - -This boolean aspect is equivalent to @ref{df,,pragma Shared} -and is thus a synonym for aspect @code{Atomic}. - -@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{151} -@section Aspect Simple_Storage_Pool - - -@geindex Simple_Storage_Pool - -This aspect is equivalent to @ref{e4,,attribute Simple_Storage_Pool}. - -@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{152} -@section Aspect Simple_Storage_Pool_Type - - -@geindex Simple_Storage_Pool_Type - -This boolean aspect is equivalent to @ref{e3,,pragma Simple_Storage_Pool_Type}. - -@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{153} -@section Aspect SPARK_Mode - - -@geindex SPARK_Mode - -This aspect is equivalent to @ref{eb,,pragma SPARK_Mode} and -may be specified for either or both of the specification and body -of a subprogram or package. - -@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{154} -@section Aspect Suppress_Debug_Info - - -@geindex Suppress_Debug_Info - -This boolean aspect is equivalent to @ref{f3,,pragma Suppress_Debug_Info}. - -@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{155} -@section Aspect Suppress_Initialization - - -@geindex Suppress_Initialization - -This boolean aspect is equivalent to @ref{f6,,pragma Suppress_Initialization}. - -@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{156} -@section Aspect Test_Case - - -@geindex Test_Case - -This aspect is equivalent to @ref{fa,,pragma Test_Case}. - -@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{157} -@section Aspect Thread_Local_Storage - - -@geindex Thread_Local_Storage - -This boolean aspect is equivalent to @ref{fc,,pragma Thread_Local_Storage}. - -@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{158} -@section Aspect Universal_Aliasing - - -@geindex Universal_Aliasing - -This boolean aspect is equivalent to @ref{106,,pragma Universal_Aliasing}. - -@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{159} -@section Aspect Unmodified - - -@geindex Unmodified - -This boolean aspect is equivalent to @ref{108,,pragma Unmodified}. - -@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15a} -@section Aspect Unreferenced - - -@geindex Unreferenced - -This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}. - -When using the @code{-gnat2022} switch, this aspect is also supported on formal -parameters, which is in particular the only form possible for expression -functions. - -@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15b} -@section Aspect Unreferenced_Objects - - -@geindex Unreferenced_Objects - -This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced_Objects}. - -@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15c} -@section Aspect Value_Size - - -@geindex Value_Size - -This aspect is equivalent to @ref{15d,,attribute Value_Size}. - -@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15e} -@section Aspect Volatile_Full_Access - - -@geindex Volatile_Full_Access - -This boolean aspect is equivalent to @ref{116,,pragma Volatile_Full_Access}. - -@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{15f} -@section Aspect Volatile_Function - - -@geindex Volatile_Function - -This boolean aspect is equivalent to @ref{118,,pragma Volatile_Function}. - -@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects -@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{160} -@section Aspect Warnings - - -@geindex Warnings - -This aspect is equivalent to the two argument form of @ref{11a,,pragma Warnings}, -where the first argument is @code{ON} or @code{OFF} and the second argument -is the entity. - -@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top -@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{161}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} -@chapter Implementation Defined Attributes - - -Ada defines (throughout the Ada reference manual, -summarized in Annex K), -a set of attributes that provide useful additional functionality in all -areas of the language. These language defined attributes are implemented -in GNAT and work as described in the Ada Reference Manual. - -In addition, Ada allows implementations to define additional -attributes whose meaning is defined by the implementation. GNAT provides -a number of these implementation-dependent attributes which can be used -to extend and enhance the functionality of the compiler. This section of -the GNAT reference manual describes these additional attributes. It also -describes additional implementation-dependent features of standard -language-defined attributes. - -Note that any program using these attributes may not be portable to -other compilers (although GNAT implements this set of attributes on all -platforms). Therefore if portability to other compilers is an important -consideration, you should minimize the use of these attributes. - -@menu -* Attribute Abort_Signal:: -* Attribute Address_Size:: -* Attribute Asm_Input:: -* Attribute Asm_Output:: -* Attribute Atomic_Always_Lock_Free:: -* Attribute Bit:: -* Attribute Bit_Position:: -* Attribute Code_Address:: -* Attribute Compiler_Version:: -* Attribute Constrained:: -* Attribute Default_Bit_Order:: -* Attribute Default_Scalar_Storage_Order:: -* Attribute Deref:: -* Attribute Descriptor_Size:: -* Attribute Elaborated:: -* Attribute Elab_Body:: -* Attribute Elab_Spec:: -* Attribute Elab_Subp_Body:: -* Attribute Emax:: -* Attribute Enabled:: -* Attribute Enum_Rep:: -* Attribute Enum_Val:: -* Attribute Epsilon:: -* Attribute Fast_Math:: -* Attribute Finalization_Size:: -* Attribute Fixed_Value:: -* Attribute From_Any:: -* Attribute Has_Access_Values:: -* Attribute Has_Discriminants:: -* Attribute Has_Tagged_Values:: -* Attribute Img:: -* Attribute Initialized:: -* Attribute Integer_Value:: -* Attribute Invalid_Value:: -* Attribute Iterable:: -* Attribute Large:: -* Attribute Library_Level:: -* Attribute Loop_Entry:: -* Attribute Machine_Size:: -* Attribute Mantissa:: -* Attribute Maximum_Alignment:: -* Attribute Max_Integer_Size:: -* Attribute Mechanism_Code:: -* Attribute Null_Parameter:: -* Attribute Object_Size:: -* Attribute Old:: -* Attribute Passed_By_Reference:: -* Attribute Pool_Address:: -* Attribute Range_Length:: -* Attribute Restriction_Set:: -* Attribute Result:: -* Attribute Safe_Emax:: -* Attribute Safe_Large:: -* Attribute Safe_Small:: -* Attribute Scalar_Storage_Order:: -* Attribute Simple_Storage_Pool:: -* Attribute Small:: -* Attribute Small_Denominator:: -* Attribute Small_Numerator:: -* Attribute Storage_Unit:: -* Attribute Stub_Type:: -* Attribute System_Allocator_Alignment:: -* Attribute Target_Name:: -* Attribute To_Address:: -* Attribute To_Any:: -* Attribute Type_Class:: -* Attribute Type_Key:: -* Attribute TypeCode:: -* Attribute Unconstrained_Array:: -* Attribute Universal_Literal_String:: -* Attribute Unrestricted_Access:: -* Attribute Update:: -* Attribute Valid_Value:: -* Attribute Valid_Scalars:: -* Attribute VADS_Size:: -* Attribute Value_Size:: -* Attribute Wchar_T_Size:: -* Attribute Word_Size:: - -@end menu - -@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{163} -@section Attribute Abort_Signal - - -@geindex Abort_Signal - -@code{Standard'Abort_Signal} (@code{Standard} is the only allowed -prefix) provides the entity for the special exception used to signal -task abort or asynchronous transfer of control. Normally this attribute -should only be used in the tasking runtime (it is highly peculiar, and -completely outside the normal semantics of Ada, for a user program to -intercept the abort exception). - -@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{164} -@section Attribute Address_Size - - -@geindex Size of `@w{`}Address`@w{`} - -@geindex Address_Size - -@code{Standard'Address_Size} (@code{Standard} is the only allowed -prefix) is a static constant giving the number of bits in an -@code{Address}. It is the same value as System.Address’Size, -but has the advantage of being static, while a direct -reference to System.Address’Size is nonstatic because Address -is a private type. - -@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{165} -@section Attribute Asm_Input - - -@geindex Asm_Input - -The @code{Asm_Input} attribute denotes a function that takes two -parameters. The first is a string, the second is an expression of the -type designated by the prefix. The first (string) argument is required -to be a static expression, and is the constraint for the parameter, -(e.g., what kind of register is required). The second argument is the -value to be used as the input argument. The possible values for the -constant are the same as those used in the RTL, and are dependent on -the configuration file used to built the GCC back end. -@ref{166,,Machine Code Insertions} - -@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{167} -@section Attribute Asm_Output - - -@geindex Asm_Output - -The @code{Asm_Output} attribute denotes a function that takes two -parameters. The first is a string, the second is the name of a variable -of the type designated by the attribute prefix. The first (string) -argument is required to be a static expression and designates the -constraint for the parameter (e.g., what kind of register is -required). The second argument is the variable to be updated with the -result. The possible values for constraint are the same as those used in -the RTL, and are dependent on the configuration file used to build the -GCC back end. If there are no output operands, then this argument may -either be omitted, or explicitly given as @code{No_Output_Operands}. -@ref{166,,Machine Code Insertions} - -@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{168} -@section Attribute Atomic_Always_Lock_Free - - -@geindex Atomic_Always_Lock_Free - -The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. -The result is a Boolean value which is True if the type has discriminants, -and False otherwise. The result indicate whether atomic operations are -supported by the target for the given type. - -@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{169} -@section Attribute Bit - - -@geindex Bit - -@code{obj'Bit}, where @code{obj} is any object, yields the bit -offset within the storage unit (byte) that contains the first bit of -storage allocated for the object. The value of this attribute is of the -type `universal_integer' and is always a nonnegative number smaller -than @code{System.Storage_Unit}. - -For an object that is a variable or a constant allocated in a register, -the value is zero. (The use of this attribute does not force the -allocation of a variable to memory). - -For an object that is a formal parameter, this attribute applies -to either the matching actual parameter or to a copy of the -matching actual parameter. - -For an access object the value is zero. Note that -@code{obj.all'Bit} is subject to an @code{Access_Check} for the -designated object. Similarly for a record component -@code{X.C'Bit} is subject to a discriminant check and -@code{X(I).Bit} and @code{X(I1..I2)'Bit} -are subject to index checks. - -This attribute is designed to be compatible with the DEC Ada 83 definition -and implementation of the @code{Bit} attribute. - -@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16a} -@section Attribute Bit_Position - - -@geindex Bit_Position - -@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one -of the fields of the record type, yields the bit -offset within the record contains the first bit of -storage allocated for the object. The value of this attribute is of the -type `universal_integer'. The value depends only on the field -@code{C} and is independent of the alignment of -the containing record @code{R}. - -@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16b} -@section Attribute Code_Address - - -@geindex Code_Address - -@geindex Subprogram address - -@geindex Address of subprogram code - -The @code{'Address} -attribute may be applied to subprograms in Ada 95 and Ada 2005, but the -intended effect seems to be to provide -an address value which can be used to call the subprogram by means of -an address clause as in the following example: - -@example -procedure K is ... - -procedure L; -for L'Address use K'Address; -pragma Import (Ada, L); -@end example - -A call to @code{L} is then expected to result in a call to @code{K}. -In Ada 83, where there were no access-to-subprogram values, this was -a common work-around for getting the effect of an indirect call. -GNAT implements the above use of @code{Address} and the technique -illustrated by the example code works correctly. - -However, for some purposes, it is useful to have the address of the start -of the generated code for the subprogram. On some architectures, this is -not necessarily the same as the @code{Address} value described above. -For example, the @code{Address} value may reference a subprogram -descriptor rather than the subprogram itself. - -The @code{'Code_Address} attribute, which can only be applied to -subprogram entities, always returns the address of the start of the -generated code of the specified subprogram, which may or may not be -the same value as is returned by the corresponding @code{'Address} -attribute. - -@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16c} -@section Attribute Compiler_Version - - -@geindex Compiler_Version - -@code{Standard'Compiler_Version} (@code{Standard} is the only allowed -prefix) yields a static string identifying the version of the compiler -being used to compile the unit containing the attribute reference. - -@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16d} -@section Attribute Constrained - - -@geindex Constrained - -In addition to the usage of this attribute in the Ada RM, GNAT -also permits the use of the @code{'Constrained} attribute -in a generic template -for any type, including types without discriminants. The value of this -attribute in the generic instance when applied to a scalar type or a -record type without discriminants is always @code{True}. This usage is -compatible with older Ada compilers, including notably DEC Ada. - -@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16e} -@section Attribute Default_Bit_Order - - -@geindex Big endian - -@geindex Little endian - -@geindex Default_Bit_Order - -@code{Standard'Default_Bit_Order} (@code{Standard} is the only -allowed prefix), provides the value @code{System.Default_Bit_Order} -as a @code{Pos} value (0 for @code{High_Order_First}, 1 for -@code{Low_Order_First}). This is used to construct the definition of -@code{Default_Bit_Order} in package @code{System}. - -@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{16f} -@section Attribute Default_Scalar_Storage_Order - - -@geindex Big endian - -@geindex Little endian - -@geindex Default_Scalar_Storage_Order - -@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only -allowed prefix), provides the current value of the default scalar storage -order (as specified using pragma @code{Default_Scalar_Storage_Order}, or -equal to @code{Default_Bit_Order} if unspecified) as a -@code{System.Bit_Order} value. This is a static attribute. - -@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{170} -@section Attribute Deref - - -@geindex Deref - -The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields -the variable of type @code{typ} that is located at the given address. It is similar -to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to -a named access-to-@cite{typ} type, except that it yields a variable, so it can be -used on the left side of an assignment. - -@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{171} -@section Attribute Descriptor_Size - - -@geindex Descriptor - -@geindex Dope vector - -@geindex Descriptor_Size - -Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the -descriptor allocated for a type. The result is non-zero only for unconstrained -array types and the returned value is of type universal integer. In GNAT, an -array descriptor contains bounds information and is located immediately before -the first element of the array. - -@example -type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; -Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); -@end example - -The attribute takes into account any padding due to the alignment of the -component type. In the example above, the descriptor contains two values -of type @code{Short_Short_Integer} representing the low and high bound. But, -since @code{Positive} has an alignment of 4, the size of the descriptor is -@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, -which yields a size of 32 bits, i.e. including 16 bits of padding. - -@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{172} -@section Attribute Elaborated - - -@geindex Elaborated - -The prefix of the @code{'Elaborated} attribute must be a unit name. The -value is a Boolean which indicates whether or not the given unit has been -elaborated. This attribute is primarily intended for internal use by the -generated code for dynamic elaboration checking, but it can also be used -in user programs. The value will always be True once elaboration of all -units has been completed. An exception is for units which need no -elaboration, the value is always False for such units. - -@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{173} -@section Attribute Elab_Body - - -@geindex Elab_Body - -This attribute can only be applied to a program unit name. It returns -the entity for the corresponding elaboration procedure for elaborating -the body of the referenced unit. This is used in the main generated -elaboration procedure by the binder and is not normally used in any -other context. However, there may be specialized situations in which it -is useful to be able to call this elaboration procedure from Ada code, -e.g., if it is necessary to do selective re-elaboration to fix some -error. - -@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{174} -@section Attribute Elab_Spec - - -@geindex Elab_Spec - -This attribute can only be applied to a program unit name. It returns -the entity for the corresponding elaboration procedure for elaborating -the spec of the referenced unit. This is used in the main -generated elaboration procedure by the binder and is not normally used -in any other context. However, there may be specialized situations in -which it is useful to be able to call this elaboration procedure from -Ada code, e.g., if it is necessary to do selective re-elaboration to fix -some error. - -@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{175} -@section Attribute Elab_Subp_Body - - -@geindex Elab_Subp_Body - -This attribute can only be applied to a library level subprogram -name and is only allowed in CodePeer mode. It returns the entity -for the corresponding elaboration procedure for elaborating the body -of the referenced subprogram unit. This is used in the main generated -elaboration procedure by the binder in CodePeer mode only and is unrecognized -otherwise. - -@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{176} -@section Attribute Emax - - -@geindex Ada 83 attributes - -@geindex Emax - -The @code{Emax} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{177} -@section Attribute Enabled - - -@geindex Enabled - -The @code{Enabled} attribute allows an application program to check at compile -time to see if the designated check is currently enabled. The prefix is a -simple identifier, referencing any predefined check name (other than -@code{All_Checks}) or a check name introduced by pragma Check_Name. If -no argument is given for the attribute, the check is for the general state -of the check, if an argument is given, then it is an entity name, and the -check indicates whether an @code{Suppress} or @code{Unsuppress} has been -given naming the entity (if not, then the argument is ignored). - -Note that instantiations inherit the check status at the point of the -instantiation, so a useful idiom is to have a library package that -introduces a check name with @code{pragma Check_Name}, and then contains -generic packages or subprograms which use the @code{Enabled} attribute -to see if the check is enabled. A user of this package can then issue -a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating -the package or subprogram, controlling whether the check will be present. - -@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{178} -@section Attribute Enum_Rep - - -@geindex Representation of enums - -@geindex Enum_Rep - -Note that this attribute is now standard in Ada 202x and is available -as an implementation defined attribute for earlier Ada versions. - -For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a -function with the following spec: - -@example -function S'Enum_Rep (Arg : S'Base) return ; -@end example - -It is also allowable to apply @code{Enum_Rep} directly to an object of an -enumeration type or to a non-overloaded enumeration -literal. In this case @code{S'Enum_Rep} is equivalent to -@code{typ'Enum_Rep(S)} where @code{typ} is the type of the -enumeration literal or object. - -The function returns the representation value for the given enumeration -value. This will be equal to value of the @code{Pos} attribute in the -absence of an enumeration representation clause. This is a static -attribute (i.e., the result is static if the argument is static). - -@code{S'Enum_Rep} can also be used with integer types and objects, -in which case it simply returns the integer value. The reason for this -is to allow it to be used for @code{(<>)} discrete formal arguments in -a generic unit that can be instantiated with either enumeration types -or integer types. Note that if @code{Enum_Rep} is used on a modular -type whose upper bound exceeds the upper bound of the largest signed -integer type, and the argument is a variable, so that the universal -integer calculation is done at run time, then the call to @code{Enum_Rep} -may raise @code{Constraint_Error}. - -@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{179} -@section Attribute Enum_Val - - -@geindex Representation of enums - -@geindex Enum_Val - -Note that this attribute is now standard in Ada 202x and is available -as an implementation defined attribute for earlier Ada versions. - -For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a -function with the following spec: - -@example -function S'Enum_Val (Arg : ) return S'Base; -@end example - -The function returns the enumeration value whose representation matches the -argument, or raises Constraint_Error if no enumeration literal of the type -has the matching value. -This will be equal to value of the @code{Val} attribute in the -absence of an enumeration representation clause. This is a static -attribute (i.e., the result is static if the argument is static). - -@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17a} -@section Attribute Epsilon - - -@geindex Ada 83 attributes - -@geindex Epsilon - -The @code{Epsilon} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17b} -@section Attribute Fast_Math - - -@geindex Fast_Math - -@code{Standard'Fast_Math} (@code{Standard} is the only allowed -prefix) yields a static Boolean value that is True if pragma -@code{Fast_Math} is active, and False otherwise. - -@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17c} -@section Attribute Finalization_Size - - -@geindex Finalization_Size - -The prefix of attribute @code{Finalization_Size} must be an object or -a non-class-wide type. This attribute returns the size of any hidden data -reserved by the compiler to handle finalization-related actions. The type of -the attribute is `universal_integer'. - -@code{Finalization_Size} yields a value of zero for a type with no controlled -parts, an object whose type has no controlled parts, or an object of a -class-wide type whose tag denotes a type with no controlled parts. - -Note that only heap-allocated objects contain finalization data. - -@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17d} -@section Attribute Fixed_Value - - -@geindex Fixed_Value - -For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a -function with the following specification: - -@example -function S'Fixed_Value (Arg : ) return S; -@end example - -The value returned is the fixed-point value @code{V} such that: - -@example -V = Arg * S'Small -@end example - -The effect is thus similar to first converting the argument to the -integer type used to represent @code{S}, and then doing an unchecked -conversion to the fixed-point type. The difference is -that there are full range checks, to ensure that the result is in range. -This attribute is primarily intended for use in implementation of the -input-output functions for fixed-point values. - -@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17e} -@section Attribute From_Any - - -@geindex From_Any - -This internal attribute is used for the generation of remote subprogram -stubs in the context of the Distributed Systems Annex. - -@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{17f} -@section Attribute Has_Access_Values - - -@geindex Access values -@geindex testing for - -@geindex Has_Access_Values - -The prefix of the @code{Has_Access_Values} attribute is a type. The result -is a Boolean value which is True if the is an access type, or is a composite -type with a component (at any nesting depth) that is an access type, and is -False otherwise. -The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has access values. - -@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{180} -@section Attribute Has_Discriminants - - -@geindex Discriminants -@geindex testing for - -@geindex Has_Discriminants - -The prefix of the @code{Has_Discriminants} attribute is a type. The result -is a Boolean value which is True if the type has discriminants, and False -otherwise. The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has discriminants. - -@node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{181} -@section Attribute Has_Tagged_Values - - -@geindex Tagged values -@geindex testing for - -@geindex Has_Tagged_Values - -The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a -Boolean value which is True if the type is a composite type (array or record) -that is either a tagged type or has a subcomponent that is tagged, and is False -otherwise. The intended use of this attribute is in conjunction with generic -definitions. If the attribute is applied to a generic private type, it -indicates whether or not the corresponding actual type has access values. - -@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{182} -@section Attribute Img - - -@geindex Img - -The @code{Img} attribute differs from @code{Image} in that, while both can be -applied directly to an object, @code{Img} cannot be applied to types. - -Example usage of the attribute: - -@example -Put_Line ("X = " & X'Img); -@end example - -which has the same meaning as the more verbose: - -@example -Put_Line ("X = " & T'Image (X)); -@end example - -where @code{T} is the (sub)type of the object @code{X}. - -Note that technically, in analogy to @code{Image}, -@code{X'Img} returns a parameterless function -that returns the appropriate string when called. This means that -@code{X'Img} can be renamed as a function-returning-string, or used -in an instantiation as a function parameter. - -@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{183} -@section Attribute Initialized - - -@geindex Initialized - -For the syntax and semantics of this attribute, see the SPARK 2014 Reference -Manual, section 6.10. - -@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{184} -@section Attribute Integer_Value - - -@geindex Integer_Value - -For every integer type @code{S}, @code{S'Integer_Value} denotes a -function with the following spec: - -@example -function S'Integer_Value (Arg : ) return S; -@end example - -The value returned is the integer value @code{V}, such that: - -@example -Arg = V * T'Small -@end example - -where @code{T} is the type of @code{Arg}. -The effect is thus similar to first doing an unchecked conversion from -the fixed-point type to its corresponding implementation type, and then -converting the result to the target integer type. The difference is -that there are full range checks, to ensure that the result is in range. -This attribute is primarily intended for use in implementation of the -standard input-output functions for fixed-point values. - -@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{185} -@section Attribute Invalid_Value - - -@geindex Invalid_Value - -For every scalar type S, S’Invalid_Value returns an undefined value of the -type. If possible this value is an invalid representation for the type. The -value returned is identical to the value used to initialize an otherwise -uninitialized value of the type if pragma Initialize_Scalars is used, -including the ability to modify the value with the binder -Sxx flag and -relevant environment variables at run time. - -@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{186} -@section Attribute Iterable - - -@geindex Iterable - -Equivalent to Aspect Iterable. - -@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{187} -@section Attribute Large - - -@geindex Ada 83 attributes - -@geindex Large - -The @code{Large} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{188} -@section Attribute Library_Level - - -@geindex Library_Level - -@code{P'Library_Level}, where P is an entity name, -returns a Boolean value which is True if the entity is declared -at the library level, and False otherwise. Note that within a -generic instantiation, the name of the generic unit denotes the -instance, which means that this attribute can be used to test -if a generic is instantiated at the library level, as shown -in this example: - -@example -generic - ... -package Gen is - pragma Compile_Time_Error - (not Gen'Library_Level, - "Gen can only be instantiated at library level"); - ... -end Gen; -@end example - -@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{189} -@section Attribute Loop_Entry - - -@geindex Loop_Entry - -Syntax: - -@example -X'Loop_Entry [(loop_name)] -@end example - -The @code{Loop_Entry} attribute is used to refer to the value that an -expression had upon entry to a given loop in much the same way that the -@code{Old} attribute in a subprogram postcondition can be used to refer -to the value an expression had upon entry to the subprogram. The -relevant loop is either identified by the given loop name, or it is the -innermost enclosing loop when no loop name is given. - -A @code{Loop_Entry} attribute can only occur within an @code{Assert}, -@code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma. -In addition, such a pragma must be one of the items in the sequence -of statements of a loop body, or nested inside block statements that -appear in the sequence of statements of a loop body. -A common use of @code{Loop_Entry} is to compare the current value of objects with -their initial value at loop entry, in a @code{Loop_Invariant} pragma. - -The effect of using @code{X'Loop_Entry} is the same as declaring -a constant initialized with the initial value of @code{X} at loop -entry. This copy is not performed if the loop is not entered, or if the -corresponding pragmas are ignored or disabled. - -@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18a} -@section Attribute Machine_Size - - -@geindex Machine_Size - -This attribute is identical to the @code{Object_Size} attribute. It is -provided for compatibility with the DEC Ada 83 attribute of this name. - -@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18b} -@section Attribute Mantissa - - -@geindex Ada 83 attributes - -@geindex Mantissa - -The @code{Mantissa} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18c}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18d} -@section Attribute Maximum_Alignment - - -@geindex Alignment -@geindex maximum - -@geindex Maximum_Alignment - -@code{Standard'Maximum_Alignment} (@code{Standard} is the only -allowed prefix) provides the maximum useful alignment value for the -target. This is a static value that can be used to specify the alignment -for an object, guaranteeing that it is properly aligned in all -cases. - -@node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{18e} -@section Attribute Max_Integer_Size - - -@geindex Max_Integer_Size - -@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed -prefix) provides the size of the largest supported integer type for -the target. The result is a static constant. - -@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18f} -@section Attribute Mechanism_Code - - -@geindex Return values -@geindex passing mechanism - -@geindex Parameters -@geindex passing mechanism - -@geindex Mechanism_Code - -@code{func'Mechanism_Code} yields an integer code for the -mechanism used for the result of function @code{func}, and -@code{subprog'Mechanism_Code (n)} yields the mechanism -used for formal parameter number `n' (a static integer value, with 1 -meaning the first parameter) of subprogram @code{subprog}. The code returned is: - - -@table @asis - -@item `1' - -by copy (value) - -@item `2' - -by reference -@end table - -@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{190} -@section Attribute Null_Parameter - - -@geindex Zero address -@geindex passing - -@geindex Null_Parameter - -A reference @code{T'Null_Parameter} denotes an imaginary object of -type or subtype @code{T} allocated at machine address zero. The attribute -is allowed only as the default expression of a formal parameter, or as -an actual expression of a subprogram call. In either case, the -subprogram must be imported. - -The identity of the object is represented by the address zero in the -argument list, independent of the passing mechanism (explicit or -default). - -This capability is needed to specify that a zero address should be -passed for a record or other composite object passed by reference. -There is no way of indicating this without the @code{Null_Parameter} -attribute. - -@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{141}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{191} -@section Attribute Object_Size - - -@geindex Size -@geindex used for objects - -@geindex Object_Size - -The size of an object is not necessarily the same as the size of the type -of an object. This is because by default object sizes are increased to be -a multiple of the alignment of the object. For example, -@code{Natural'Size} is -31, but by default objects of type @code{Natural} will have a size of 32 bits. -Similarly, a record containing an integer and a character: - -@example -type Rec is record - I : Integer; - C : Character; -end record; -@end example - -will have a size of 40 (that is @code{Rec'Size} will be 40). The -alignment will be 4, because of the -integer field, and so the default size of record objects for this type -will be 64 (8 bytes). - -If the alignment of the above record is specified to be 1, then the -object size will be 40 (5 bytes). This is true by default, and also -an object size of 40 can be explicitly specified in this case. - -A consequence of this capability is that different object sizes can be -given to subtypes that would otherwise be considered in Ada to be -statically matching. But it makes no sense to consider such subtypes -as statically matching. Consequently, GNAT adds a rule -to the static matching rules that requires object sizes to match. -Consider this example: - -@example - 1. procedure BadAVConvert is - 2. type R is new Integer; - 3. subtype R1 is R range 1 .. 10; - 4. subtype R2 is R range 1 .. 10; - 5. for R1'Object_Size use 8; - 6. for R2'Object_Size use 16; - 7. type R1P is access all R1; - 8. type R2P is access all R2; - 9. R1PV : R1P := new R1'(4); -10. R2PV : R2P; -11. begin -12. R2PV := R2P (R1PV); - | - >>> target designated subtype not compatible with - type "R1" defined at line 3 - -13. end; -@end example - -In the absence of lines 5 and 6, -types @code{R1} and @code{R2} statically match and -hence the conversion on line 12 is legal. But since lines 5 and 6 -cause the object sizes to differ, GNAT considers that types -@code{R1} and @code{R2} are not statically matching, and line 12 -generates the diagnostic shown above. - -Similar additional checks are performed in other contexts requiring -statically matching subtypes. - -@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{192} -@section Attribute Old - - -@geindex Old - -In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage -within @code{Post} aspect), GNAT also permits the use of this attribute -in implementation defined pragmas @code{Postcondition}, -@code{Contract_Cases} and @code{Test_Case}. Also usages of -@code{Old} which would be illegal according to the Ada 2012 RM -definition are allowed under control of -implementation defined pragma @code{Unevaluated_Use_Of_Old}. - -@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{193} -@section Attribute Passed_By_Reference - - -@geindex Parameters -@geindex when passed by reference - -@geindex Passed_By_Reference - -@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns -a value of type @code{Boolean} value that is @code{True} if the type is -normally passed by reference and @code{False} if the type is normally -passed by copy in calls. For scalar types, the result is always @code{False} -and is static. For non-scalar types, the result is nonstatic. - -@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{194} -@section Attribute Pool_Address - - -@geindex Pool_Address - -@code{X'Pool_Address} for any object @code{X} returns the address -of X within its storage pool. This is the same as -@code{X'Address}, except that for an unconstrained array whose -bounds are allocated just before the first component, -@code{X'Pool_Address} returns the address of those bounds, -whereas @code{X'Address} returns the address of the first -component. - -Here, we are interpreting ‘storage pool’ broadly to mean -@code{wherever the object is allocated}, which could be a -user-defined storage pool, -the global heap, on the stack, or in a static memory area. -For an object created by @code{new}, @code{Ptr.all'Pool_Address} is -what is passed to @code{Allocate} and returned from @code{Deallocate}. - -@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{195} -@section Attribute Range_Length - - -@geindex Range_Length - -@code{typ'Range_Length} for any discrete type @cite{typ} yields -the number of values represented by the subtype (zero for a null -range). The result is static for static subtypes. @code{Range_Length} -applied to the index subtype of a one dimensional array always gives the -same result as @code{Length} applied to the array itself. - -@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{196} -@section Attribute Restriction_Set - - -@geindex Restriction_Set - -@geindex Restrictions - -This attribute allows compile time testing of restrictions that -are currently in effect. It is primarily intended for specializing -code in the run-time based on restrictions that are active (e.g. -don’t need to save fpt registers if restriction No_Floating_Point -is known to be in effect), but can be used anywhere. - -There are two forms: - -@example -System'Restriction_Set (partition_boolean_restriction_NAME) -System'Restriction_Set (No_Dependence => library_unit_NAME); -@end example - -In the case of the first form, the only restriction names -allowed are parameterless restrictions that are checked -for consistency at bind time. For a complete list see the -subtype @code{System.Rident.Partition_Boolean_Restrictions}. - -The result returned is True if the restriction is known to -be in effect, and False if the restriction is known not to -be in effect. An important guarantee is that the value of -a Restriction_Set attribute is known to be consistent throughout -all the code of a partition. - -This is trivially achieved if the entire partition is compiled -with a consistent set of restriction pragmas. However, the -compilation model does not require this. It is possible to -compile one set of units with one set of pragmas, and another -set of units with another set of pragmas. It is even possible -to compile a spec with one set of pragmas, and then WITH the -same spec with a different set of pragmas. Inconsistencies -in the actual use of the restriction are checked at bind time. - -In order to achieve the guarantee of consistency for the -Restriction_Set pragma, we consider that a use of the pragma -that yields False is equivalent to a violation of the -restriction. - -So for example if you write - -@example -if System'Restriction_Set (No_Floating_Point) then - ... -else - ... -end if; -@end example - -And the result is False, so that the else branch is executed, -you can assume that this restriction is not set for any unit -in the partition. This is checked by considering this use of -the restriction pragma to be a violation of the restriction -No_Floating_Point. This means that no other unit can attempt -to set this restriction (if some unit does attempt to set it, -the binder will refuse to bind the partition). - -Technical note: The restriction name and the unit name are -intepreted entirely syntactically, as in the corresponding -Restrictions pragma, they are not analyzed semantically, -so they do not have a type. - -@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{197} -@section Attribute Result - - -@geindex Result - -@code{function'Result} can only be used with in a Postcondition pragma -for a function. The prefix must be the name of the corresponding function. This -is used to refer to the result of the function in the postcondition expression. -For a further discussion of the use of this attribute and examples of its use, -see the description of pragma Postcondition. - -@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{198} -@section Attribute Safe_Emax - - -@geindex Ada 83 attributes - -@geindex Safe_Emax - -The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{199} -@section Attribute Safe_Large - - -@geindex Ada 83 attributes - -@geindex Safe_Large - -The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19a} -@section Attribute Safe_Small - - -@geindex Ada 83 attributes - -@geindex Safe_Small - -The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute. - -@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{14f}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19b} -@section Attribute Scalar_Storage_Order - - -@geindex Endianness - -@geindex Scalar storage order - -@geindex Scalar_Storage_Order - -For every array or record type @code{S}, the representation attribute -@code{Scalar_Storage_Order} denotes the order in which storage elements -that make up scalar components are ordered within S. The value given must -be a static expression of type System.Bit_Order. The following is an example -of the use of this feature: - -@example --- Component type definitions - -subtype Yr_Type is Natural range 0 .. 127; -subtype Mo_Type is Natural range 1 .. 12; -subtype Da_Type is Natural range 1 .. 31; - --- Record declaration - -type Date is record - Years_Since_1980 : Yr_Type; - Month : Mo_Type; - Day_Of_Month : Da_Type; -end record; - --- Record representation clause - -for Date use record - Years_Since_1980 at 0 range 0 .. 6; - Month at 0 range 7 .. 10; - Day_Of_Month at 0 range 11 .. 15; -end record; - --- Attribute definition clauses - -for Date'Bit_Order use System.High_Order_First; -for Date'Scalar_Storage_Order use System.High_Order_First; --- If Scalar_Storage_Order is specified, it must be consistent with --- Bit_Order, so it's best to always define the latter explicitly if --- the former is used. -@end example - -Other properties are as for the standard representation attribute @code{Bit_Order} -defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. - -For a record type @code{T}, if @code{T'Scalar_Storage_Order} is -specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: -this means that if a @code{Scalar_Storage_Order} attribute definition -clause is not confirming, then the type’s @code{Bit_Order} shall be -specified explicitly and set to the same value. - -Derived types inherit an explicitly set scalar storage order from their parent -types. This may be overridden for the derived type by giving an explicit scalar -storage order for it. However, for a record extension, the derived type must -have the same scalar storage order as the parent type. - -A component of a record type that is itself a record or an array and that does -not start and end on a byte boundary must have have the same scalar storage -order as the record type. A component of a bit-packed array type that is itself -a record or an array must have the same scalar storage order as the array type. - -No component of a type that has an explicit @code{Scalar_Storage_Order} -attribute definition may be aliased. - -A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. -with a value equal to @code{System.Default_Bit_Order}) has no effect. - -If the opposite storage order is specified, then whenever the value of -a scalar component of an object of type @code{S} is read, the storage -elements of the enclosing machine scalar are first reversed (before -retrieving the component value, possibly applying some shift and mask -operatings on the enclosing machine scalar), and the opposite operation -is done for writes. - -In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components -are relaxed. Instead, the following rules apply: - - -@itemize * - -@item -the underlying storage elements are those at positions -@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} - -@item -the sequence of underlying storage elements shall have -a size no greater than the largest machine scalar - -@item -the enclosing machine scalar is defined as the smallest machine -scalar starting at a position no greater than -@code{position + first_bit / storage_element_size} and covering -storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size} - -@item -the position of the component is interpreted relative to that machine -scalar. -@end itemize - -If no scalar storage order is specified for a type (either directly, or by -inheritance in the case of a derived type), then the default is normally -the native ordering of the target, but this default can be overridden using -pragma @code{Default_Scalar_Storage_Order}. - -If a component of @code{T} is itself of a record or array type, the specfied -@code{Scalar_Storage_Order} does `not' apply to that nested type: an explicit -attribute definition clause must be provided for the component type as well -if desired. - -Representation changes that explicitly or implicitly toggle the scalar storage -order are not supported and may result in erroneous execution of the program, -except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. - -In particular, overlays are not supported and a warning is given for them: - -@example -type Rec_LE is record - I : Integer; -end record; - -for Rec_LE use record - I at 0 range 0 .. 31; -end record; - -for Rec_LE'Bit_Order use System.Low_Order_First; -for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; - -type Rec_BE is record - I : Integer; -end record; - -for Rec_BE use record - I at 0 range 0 .. 31; -end record; - -for Rec_BE'Bit_Order use System.High_Order_First; -for Rec_BE'Scalar_Storage_Order use System.High_Order_First; - -R_LE : Rec_LE; - -R_BE : Rec_BE; -for R_BE'Address use R_LE'Address; -@end example - -@code{warning: overlay changes scalar storage order [enabled by default]} - -In most cases, such representation changes ought to be replaced by an -instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. - -Note that the scalar storage order only affects the in-memory data -representation. It has no effect on the representation used by stream -attributes. - -Note that debuggers may be unable to display the correct value of scalar -components of a type for which the opposite storage order is specified. - -@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e4}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19c} -@section Attribute Simple_Storage_Pool - - -@geindex Storage pool -@geindex simple - -@geindex Simple storage pool - -@geindex Simple_Storage_Pool - -For every nonformal, nonderived access-to-object type @code{Acc}, the -representation attribute @code{Simple_Storage_Pool} may be specified -via an attribute_definition_clause (or by specifying the equivalent aspect): - -@example -My_Pool : My_Simple_Storage_Pool_Type; - -type Acc is access My_Data_Type; - -for Acc'Simple_Storage_Pool use My_Pool; -@end example - -The name given in an attribute_definition_clause for the -@code{Simple_Storage_Pool} attribute shall denote a variable of -a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). - -The use of this attribute is only allowed for a prefix denoting a type -for which it has been specified. The type of the attribute is the type -of the variable specified as the simple storage pool of the access type, -and the attribute denotes that variable. - -It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} -for the same access type. - -If the @code{Simple_Storage_Pool} attribute has been specified for an access -type, then applying the @code{Storage_Pool} attribute to the type is flagged -with a warning and its evaluation raises the exception @code{Program_Error}. - -If the Simple_Storage_Pool attribute has been specified for an access -type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} -returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, -which is intended to indicate the number of storage elements reserved for -the simple storage pool. If the Storage_Size function has not been defined -for the simple storage pool type, then this attribute returns zero. - -If an access type @code{S} has a specified simple storage pool of type -@code{SSP}, then the evaluation of an allocator for that access type calls -the primitive @code{Allocate} procedure for type @code{SSP}, passing -@code{S'Simple_Storage_Pool} as the pool parameter. The detailed -semantics of such allocators is the same as those defined for allocators -in section 13.11 of the @cite{Ada Reference Manual}, with the term -`simple storage pool' substituted for `storage pool'. - -If an access type @code{S} has a specified simple storage pool of type -@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} -for that access type invokes the primitive @code{Deallocate} procedure -for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool -parameter. The detailed semantics of such unchecked deallocations is the same -as defined in section 13.11.2 of the Ada Reference Manual, except that the -term `simple storage pool' is substituted for `storage pool'. - -@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19d} -@section Attribute Small - - -@geindex Ada 83 attributes - -@geindex Small - -The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for -fixed-point types. -GNAT also allows this attribute to be applied to floating-point types -for compatibility with Ada 83. See -the Ada 83 reference manual for an exact description of the semantics of -this attribute when applied to floating-point types. - -@node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{19e} -@section Attribute Small_Denominator - - -@geindex Small - -@geindex Small_Denominator - -@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the -denominator in the representation of @code{typ'Small} as a rational number -with coprime factors (i.e. as an irreducible fraction). - -@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{19f} -@section Attribute Small_Numerator - - -@geindex Small - -@geindex Small_Numerator - -@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the -numerator in the representation of @code{typ'Small} as a rational number -with coprime factors (i.e. as an irreducible fraction). - -@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a0} -@section Attribute Storage_Unit - - -@geindex Storage_Unit - -@code{Standard'Storage_Unit} (@code{Standard} is the only allowed -prefix) provides the same value as @code{System.Storage_Unit}. - -@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a1} -@section Attribute Stub_Type - - -@geindex Stub_Type - -The GNAT implementation of remote access-to-classwide types is -organized as described in AARM section E.4 (20.t): a value of an RACW type -(designating a remote object) is represented as a normal access -value, pointing to a “stub” object which in turn contains the -necessary information to contact the designated remote object. A -call on any dispatching operation of such a stub object does the -remote call, if necessary, using the information in the stub object -to locate the target partition, etc. - -For a prefix @code{T} that denotes a remote access-to-classwide type, -@code{T'Stub_Type} denotes the type of the corresponding stub objects. - -By construction, the layout of @code{T'Stub_Type} is identical to that of -type @code{RACW_Stub_Type} declared in the internal implementation-defined -unit @code{System.Partition_Interface}. Use of this attribute will create -an implicit dependency on this unit. - -@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a2} -@section Attribute System_Allocator_Alignment - - -@geindex Alignment -@geindex allocator - -@geindex System_Allocator_Alignment - -@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only -allowed prefix) provides the observable guaranteed to be honored by -the system allocator (malloc). This is a static value that can be used -in user storage pools based on malloc either to reject allocation -with alignment too large or to enable a realignment circuitry if the -alignment request is larger than this value. - -@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a3} -@section Attribute Target_Name - - -@geindex Target_Name - -@code{Standard'Target_Name} (@code{Standard} is the only allowed -prefix) provides a static string value that identifies the target -for the current compilation. For GCC implementations, this is the -standard gcc target name without the terminating slash (for -example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). - -@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a4} -@section Attribute To_Address - - -@geindex To_Address - -The @code{System'To_Address} -(@code{System} is the only allowed prefix) -denotes a function identical to -@code{System.Storage_Elements.To_Address} except that -it is a static attribute. This means that if its argument is -a static expression, then the result of the attribute is a -static expression. This means that such an expression can be -used in contexts (e.g., preelaborable packages) which require a -static expression and where the function call could not be used -(since the function call is always nonstatic, even if its -argument is static). The argument must be in the range --(2**(m-1)) .. 2**m-1, where m is the memory size -(typically 32 or 64). Negative values are intepreted in a -modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on -a 32 bits machine). - -@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a5} -@section Attribute To_Any - - -@geindex To_Any - -This internal attribute is used for the generation of remote subprogram -stubs in the context of the Distributed Systems Annex. - -@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a6} -@section Attribute Type_Class - - -@geindex Type_Class - -@code{typ'Type_Class} for any type or subtype @cite{typ} yields -the value of the type class for the full type of @cite{typ}. If -@cite{typ} is a generic formal type, the value is the value for the -corresponding actual subtype. The value of this attribute is of type -@code{System.Aux_DEC.Type_Class}, which has the following definition: - -@example -type Type_Class is - (Type_Class_Enumeration, - Type_Class_Integer, - Type_Class_Fixed_Point, - Type_Class_Floating_Point, - Type_Class_Array, - Type_Class_Record, - Type_Class_Access, - Type_Class_Task, - Type_Class_Address); -@end example - -Protected types yield the value @code{Type_Class_Task}, which thus -applies to all concurrent types. This attribute is designed to -be compatible with the DEC Ada 83 attribute of the same name. - -@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a7} -@section Attribute Type_Key - - -@geindex Type_Key - -The @code{Type_Key} attribute is applicable to a type or subtype and -yields a value of type Standard.String containing encoded information -about the type or subtype. This provides improved compatibility with -other implementations that support this attribute. - -@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1a8} -@section Attribute TypeCode - - -@geindex TypeCode - -This internal attribute is used for the generation of remote subprogram -stubs in the context of the Distributed Systems Annex. - -@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1a9} -@section Attribute Unconstrained_Array - - -@geindex Unconstrained_Array - -The @code{Unconstrained_Array} attribute can be used with a prefix that -denotes any type or subtype. It is a static attribute that yields -@code{True} if the prefix designates an unconstrained array, -and @code{False} otherwise. In a generic instance, the result is -still static, and yields the result of applying this test to the -generic actual. - -@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1aa} -@section Attribute Universal_Literal_String - - -@geindex Named numbers -@geindex representation of - -@geindex Universal_Literal_String - -The prefix of @code{Universal_Literal_String} must be a named -number. The static result is the string consisting of the characters of -the number as defined in the original source. This allows the user -program to access the actual text of named numbers without intermediate -conversions and without the need to enclose the strings in quotes (which -would preclude their use as numbers). - -For example, the following program prints the first 50 digits of pi: - -@example -with Text_IO; use Text_IO; -with Ada.Numerics; -procedure Pi is -begin - Put (Ada.Numerics.Pi'Universal_Literal_String); -end; -@end example - -@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ab} -@section Attribute Unrestricted_Access - - -@geindex Access -@geindex unrestricted - -@geindex Unrestricted_Access - -The @code{Unrestricted_Access} attribute is similar to @code{Access} -except that all accessibility and aliased view checks are omitted. This -is a user-beware attribute. - -For objects, it is similar to @code{Address}, for which it is a -desirable replacement where the value desired is an access type. -In other words, its effect is similar to first applying the -@code{Address} attribute and then doing an unchecked conversion to a -desired access type. - -For subprograms, @code{P'Unrestricted_Access} may be used where -@code{P'Access} would be illegal, to construct a value of a -less-nested named access type that designates a more-nested -subprogram. This value may be used in indirect calls, so long as the -more-nested subprogram still exists; once the subprogram containing it -has returned, such calls are erroneous. For example: - -@example -package body P is - - type Less_Nested is not null access procedure; - Global : Less_Nested; - - procedure P1 is - begin - Global.all; - end P1; - - procedure P2 is - Local_Var : Integer; - - procedure More_Nested is - begin - ... Local_Var ... - end More_Nested; - begin - Global := More_Nested'Unrestricted_Access; - P1; - end P2; - -end P; -@end example - -When P1 is called from P2, the call via Global is OK, but if P1 were -called after P2 returns, it would be an erroneous use of a dangling -pointer. - -For objects, it is possible to use @code{Unrestricted_Access} for any -type. However, if the result is of an access-to-unconstrained array -subtype, then the resulting pointer has the same scope as the context -of the attribute, and must not be returned to some enclosing scope. -For instance, if a function uses @code{Unrestricted_Access} to create -an access-to-unconstrained-array and returns that value to the caller, -the result will involve dangling pointers. In addition, it is only -valid to create pointers to unconstrained arrays using this attribute -if the pointer has the normal default ‘fat’ representation where a -pointer has two components, one points to the array and one points to -the bounds. If a size clause is used to force ‘thin’ representation -for a pointer to unconstrained where there is only space for a single -pointer, then the resulting pointer is not usable. - -In the simple case where a direct use of Unrestricted_Access attempts -to make a thin pointer for a non-aliased object, the compiler will -reject the use as illegal, as shown in the following example: - -@example -with System; use System; -procedure SliceUA2 is - type A is access all String; - for A'Size use Standard'Address_Size; - - procedure P (Arg : A) is - begin - null; - end P; - - X : String := "hello world!"; - X2 : aliased String := "hello world!"; - - AV : A := X'Unrestricted_Access; -- ERROR - | ->>> illegal use of Unrestricted_Access attribute ->>> attempt to generate thin pointer to unaliased object - -begin - P (X'Unrestricted_Access); -- ERROR - | ->>> illegal use of Unrestricted_Access attribute ->>> attempt to generate thin pointer to unaliased object - - P (X(7 .. 12)'Unrestricted_Access); -- ERROR - | ->>> illegal use of Unrestricted_Access attribute ->>> attempt to generate thin pointer to unaliased object - - P (X2'Unrestricted_Access); -- OK -end; -@end example - -but other cases cannot be detected by the compiler, and are -considered to be erroneous. Consider the following example: - -@example -with System; use System; -with System; use System; -procedure SliceUA is - type AF is access all String; - - type A is access all String; - for A'Size use Standard'Address_Size; - - procedure P (Arg : A) is - begin - if Arg'Length /= 6 then - raise Program_Error; - end if; - end P; - - X : String := "hello world!"; - Y : AF := X (7 .. 12)'Unrestricted_Access; - -begin - P (A (Y)); -end; -@end example - -A normal unconstrained array value -or a constrained array object marked as aliased has the bounds in memory -just before the array, so a thin pointer can retrieve both the data and -the bounds. But in this case, the non-aliased object @code{X} does not have the -bounds before the string. If the size clause for type @code{A} -were not present, then the pointer -would be a fat pointer, where one component is a pointer to the bounds, -and all would be well. But with the size clause present, the conversion from -fat pointer to thin pointer in the call loses the bounds, and so this -is erroneous, and the program likely raises a @code{Program_Error} exception. - -In general, it is advisable to completely -avoid mixing the use of thin pointers and the use of -@code{Unrestricted_Access} where the designated type is an -unconstrained array. The use of thin pointers should be restricted to -cases of porting legacy code that implicitly assumes the size of pointers, -and such code should not in any case be using this attribute. - -Another erroneous situation arises if the attribute is -applied to a constant. The resulting pointer can be used to access the -constant, but the effect of trying to modify a constant in this manner -is not well-defined. Consider this example: - -@example -P : constant Integer := 4; -type R is access all Integer; -RV : R := P'Unrestricted_Access; -.. -RV.all := 3; -@end example - -Here we attempt to modify the constant P from 4 to 3, but the compiler may -or may not notice this attempt, and subsequent references to P may yield -either the value 3 or the value 4 or the assignment may blow up if the -compiler decides to put P in read-only memory. One particular case where -@code{Unrestricted_Access} can be used in this way is to modify the -value of an @code{in} parameter: - -@example -procedure K (S : in String) is - type R is access all Character; - RV : R := S (3)'Unrestricted_Access; -begin - RV.all := 'a'; -end; -@end example - -In general this is a risky approach. It may appear to “work” but such uses of -@code{Unrestricted_Access} are potentially non-portable, even from one version -of GNAT to another, so are best avoided if possible. - -@node Attribute Update,Attribute Valid_Value,Attribute Unrestricted_Access,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ac} -@section Attribute Update - - -@geindex Update - -The @code{Update} attribute creates a copy of an array or record value -with one or more modified components. The syntax is: - -@example -PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) -PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) -PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION - @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) - -MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION -INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} -INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) -@end example - -where @code{PREFIX} is the name of an array or record object, the -association list in parentheses does not contain an @code{others} -choice and the box symbol @code{<>} may not appear in any -expression. The effect is to yield a copy of the array or record value -which is unchanged apart from the components mentioned in the -association list, which are changed to the indicated value. The -original value of the array or record value is not affected. For -example: - -@example -type Arr is Array (1 .. 5) of Integer; -... -Avar1 : Arr := (1,2,3,4,5); -Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); -@end example - -yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} -begin unmodified. Similarly: - -@example -type Rec is A, B, C : Integer; -... -Rvar1 : Rec := (A => 1, B => 2, C => 3); -Rvar2 : Rec := Rvar1'Update (B => 20); -@end example - -yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), -with @code{Rvar1} being unmodifed. -Note that the value of the attribute reference is computed -completely before it is used. This means that if you write: - -@example -Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); -@end example - -then the value of @code{Avar1} is not modified if @code{Function_Call} -raises an exception, unlike the effect of a series of direct assignments -to elements of @code{Avar1}. In general this requires that -two extra complete copies of the object are required, which should be -kept in mind when considering efficiency. - -The @code{Update} attribute cannot be applied to prefixes of a limited -type, and cannot reference discriminants in the case of a record type. -The accessibility level of an Update attribute result object is defined -as for an aggregate. - -In the record case, no component can be mentioned more than once. In -the array case, two overlapping ranges can appear in the association list, -in which case the modifications are processed left to right. - -Multi-dimensional arrays can be modified, as shown by this example: - -@example -A : array (1 .. 10, 1 .. 10) of Integer; -.. -A := A'Update ((1, 2) => 20, (3, 4) => 30); -@end example - -which changes element (1,2) to 20 and (3,4) to 30. - -@node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1ad} -@section Attribute Valid_Value - - -@geindex Valid_Value - -The @code{'Valid_Value} attribute is defined for enumeration types other than -those in package Standard. This attribute is a function that takes -a String, and returns Boolean. @code{T'Valid_Value (S)} returns True -if and only if @code{T'Value (S)} would not raise Constraint_Error. - -@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1ae} -@section Attribute Valid_Scalars - - -@geindex Valid_Scalars - -The @code{'Valid_Scalars} attribute is intended to make it easier to check the -validity of scalar subcomponents of composite objects. The attribute is defined -for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type -except for tagged private or @code{Unchecked_Union} types. The value of the -attribute is of type @code{Boolean}. - -@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of -@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if -@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent -to attribute @code{'Valid} for scalar types. - -It is not specified in what order the subcomponents are checked, nor whether -any more are checked after any one of them is determined to be invalid. If the -prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated -specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then -only the subcomponents of @code{T} are checked; in other words, components of -extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. - -The compiler will issue a warning if it can be determined at compile time that -the prefix of the attribute has no scalar subcomponents. - -Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of -a large variant record. If the attribute is called in many places in the same -program applied to objects of the same type, it can reduce program size to -write a function with a single use of the attribute, and then call that -function from multiple places. - -@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1af} -@section Attribute VADS_Size - - -@geindex Size -@geindex VADS compatibility - -@geindex VADS_Size - -The @code{'VADS_Size} attribute is intended to make it easier to port -legacy code which relies on the semantics of @code{'Size} as implemented -by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the -same semantic interpretation. In particular, @code{'VADS_Size} applied -to a predefined or other primitive type with no Size clause yields the -Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on -typical machines). In addition @code{'VADS_Size} applied to an object -gives the result that would be obtained by applying the attribute to -the corresponding type. - -@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15d}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b0} -@section Attribute Value_Size - - -@geindex Size -@geindex setting for not-first subtype - -@geindex Value_Size - -@code{type'Value_Size} is the number of bits required to represent -a value of the given subtype. It is the same as @code{type'Size}, -but, unlike @code{Size}, may be set for non-first subtypes. - -@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b1} -@section Attribute Wchar_T_Size - - -@geindex Wchar_T_Size - -@code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed -prefix) provides the size in bits of the C @code{wchar_t} type -primarily for constructing the definition of this type in -package @code{Interfaces.C}. The result is a static constant. - -@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes -@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b2} -@section Attribute Word_Size - - -@geindex Word_Size - -@code{Standard'Word_Size} (@code{Standard} is the only allowed -prefix) provides the value @code{System.Word_Size}. The result is -a static constant. - -@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top -@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b3}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b4}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9} -@chapter Standard and Implementation Defined Restrictions - - -All Ada Reference Manual-defined Restriction identifiers are implemented: - - -@itemize * - -@item -language-defined restrictions (see 13.12.1) - -@item -tasking restrictions (see D.7) - -@item -high integrity restrictions (see H.4) -@end itemize - -GNAT implements additional restriction identifiers. All restrictions, whether -language defined or GNAT-specific, are listed in the following. - -@menu -* Partition-Wide Restrictions:: -* Program Unit Level Restrictions:: - -@end menu - -@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b6} -@section Partition-Wide Restrictions - - -There are two separate lists of restriction identifiers. The first -set requires consistency throughout a partition (in other words, if the -restriction identifier is used for any compilation unit in the partition, -then all compilation units in the partition must obey the restriction). - -@menu -* Immediate_Reclamation:: -* Max_Asynchronous_Select_Nesting:: -* Max_Entry_Queue_Length:: -* Max_Protected_Entries:: -* Max_Select_Alternatives:: -* Max_Storage_At_Blocking:: -* Max_Task_Entries:: -* Max_Tasks:: -* No_Abort_Statements:: -* No_Access_Parameter_Allocators:: -* No_Access_Subprograms:: -* No_Allocators:: -* No_Anonymous_Allocators:: -* No_Asynchronous_Control:: -* No_Calendar:: -* No_Coextensions:: -* No_Default_Initialization:: -* No_Delay:: -* No_Dependence:: -* No_Direct_Boolean_Operators:: -* No_Dispatch:: -* No_Dispatching_Calls:: -* No_Dynamic_Attachment:: -* No_Dynamic_Priorities:: -* No_Entry_Calls_In_Elaboration_Code:: -* No_Enumeration_Maps:: -* No_Exception_Handlers:: -* No_Exception_Propagation:: -* No_Exception_Registration:: -* No_Exceptions:: -* No_Finalization:: -* No_Fixed_Point:: -* No_Floating_Point:: -* No_Implicit_Conditionals:: -* No_Implicit_Dynamic_Code:: -* No_Implicit_Heap_Allocations:: -* No_Implicit_Protected_Object_Allocations:: -* No_Implicit_Task_Allocations:: -* No_Initialize_Scalars:: -* No_IO:: -* No_Local_Allocators:: -* No_Local_Protected_Objects:: -* No_Local_Tagged_Types:: -* No_Local_Timing_Events:: -* No_Long_Long_Integers:: -* No_Multiple_Elaboration:: -* No_Nested_Finalization:: -* No_Protected_Type_Allocators:: -* No_Protected_Types:: -* No_Recursion:: -* No_Reentrancy:: -* No_Relative_Delay:: -* No_Requeue_Statements:: -* No_Secondary_Stack:: -* No_Select_Statements:: -* No_Specific_Termination_Handlers:: -* No_Specification_of_Aspect:: -* No_Standard_Allocators_After_Elaboration:: -* No_Standard_Storage_Pools:: -* No_Stream_Optimizations:: -* No_Streams:: -* No_Tagged_Type_Registration:: -* No_Task_Allocators:: -* No_Task_At_Interrupt_Priority:: -* No_Task_Attributes_Package:: -* No_Task_Hierarchy:: -* No_Task_Termination:: -* No_Tasking:: -* No_Terminate_Alternatives:: -* No_Unchecked_Access:: -* No_Unchecked_Conversion:: -* No_Unchecked_Deallocation:: -* No_Use_Of_Entity:: -* Pure_Barriers:: -* Simple_Barriers:: -* Static_Priorities:: -* Static_Storage_Size:: - -@end menu - -@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b7} -@subsection Immediate_Reclamation - - -@geindex Immediate_Reclamation - -[RM H.4] This restriction ensures that, except for storage occupied by -objects created by allocators and not deallocated via unchecked -deallocation, any storage reserved at run time for an object is -immediately reclaimed when the object no longer exists. - -@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b8} -@subsection Max_Asynchronous_Select_Nesting - - -@geindex Max_Asynchronous_Select_Nesting - -[RM D.7] Specifies the maximum dynamic nesting level of asynchronous -selects. Violations of this restriction with a value of zero are -detected at compile time. Violations of this restriction with values -other than zero cause Storage_Error to be raised. - -@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1b9} -@subsection Max_Entry_Queue_Length - - -@geindex Max_Entry_Queue_Length - -[RM D.7] This restriction is a declaration that any protected entry compiled in -the scope of the restriction has at most the specified number of -tasks waiting on the entry at any one time, and so no queue is required. -Note that this restriction is checked at run time. Violation of this -restriction results in the raising of Program_Error exception at the point of -the call. - -@geindex Max_Entry_Queue_Depth - -The restriction @code{Max_Entry_Queue_Depth} is recognized as a -synonym for @code{Max_Entry_Queue_Length}. This is retained for historical -compatibility purposes (and a warning will be generated for its use if -warnings on obsolescent features are activated). - -@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1ba} -@subsection Max_Protected_Entries - - -@geindex Max_Protected_Entries - -[RM D.7] Specifies the maximum number of entries per protected type. The -bounds of every entry family of a protected unit shall be static, or shall be -defined by a discriminant of a subtype whose corresponding bound is static. - -@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bb} -@subsection Max_Select_Alternatives - - -@geindex Max_Select_Alternatives - -[RM D.7] Specifies the maximum number of alternatives in a selective accept. - -@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1bc} -@subsection Max_Storage_At_Blocking - - -@geindex Max_Storage_At_Blocking - -[RM D.7] Specifies the maximum portion (in storage elements) of a task’s -Storage_Size that can be retained by a blocked task. A violation of this -restriction causes Storage_Error to be raised. - -@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bd} -@subsection Max_Task_Entries - - -@geindex Max_Task_Entries - -[RM D.7] Specifies the maximum number of entries -per task. The bounds of every entry family -of a task unit shall be static, or shall be -defined by a discriminant of a subtype whose -corresponding bound is static. - -@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1be} -@subsection Max_Tasks - - -@geindex Max_Tasks - -[RM D.7] Specifies the maximum number of task that may be created, not -counting the creation of the environment task. Violations of this -restriction with a value of zero are detected at compile -time. Violations of this restriction with values other than zero cause -Storage_Error to be raised. - -@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1bf} -@subsection No_Abort_Statements - - -@geindex No_Abort_Statements - -[RM D.7] There are no abort_statements, and there are -no calls to Task_Identification.Abort_Task. - -@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c0} -@subsection No_Access_Parameter_Allocators - - -@geindex No_Access_Parameter_Allocators - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator as the actual parameter to an access -parameter. - -@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c1} -@subsection No_Access_Subprograms - - -@geindex No_Access_Subprograms - -[RM H.4] This restriction ensures at compile time that there are no -declarations of access-to-subprogram types. - -@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c2} -@subsection No_Allocators - - -@geindex No_Allocators - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator. - -@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c3} -@subsection No_Anonymous_Allocators - - -@geindex No_Anonymous_Allocators - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator of anonymous access type. - -@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c4} -@subsection No_Asynchronous_Control - - -@geindex No_Asynchronous_Control - -[RM J.13] This restriction ensures at compile time that there are no semantic -dependences on the predefined package Asynchronous_Task_Control. - -@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c5} -@subsection No_Calendar - - -@geindex No_Calendar - -[GNAT] This restriction ensures at compile time that there are no semantic -dependences on package Calendar. - -@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c6} -@subsection No_Coextensions - - -@geindex No_Coextensions - -[RM H.4] This restriction ensures at compile time that there are no -coextensions. See 3.10.2. - -@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c7} -@subsection No_Default_Initialization - - -@geindex No_Default_Initialization - -[GNAT] This restriction prohibits any instance of default initialization -of variables. The binder implements a consistency rule which prevents -any unit compiled without the restriction from with’ing a unit with the -restriction (this allows the generation of initialization procedures to -be skipped, since you can be sure that no call is ever generated to an -initialization procedure in a unit with the restriction active). If used -in conjunction with Initialize_Scalars or Normalize_Scalars, the effect -is to prohibit all cases of variables declared without a specific -initializer (including the case of OUT scalar parameters). - -@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c8} -@subsection No_Delay - - -@geindex No_Delay - -[RM H.4] This restriction ensures at compile time that there are no -delay statements and no semantic dependences on package Calendar. - -@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1c9} -@subsection No_Dependence - - -@geindex No_Dependence - -[RM 13.12.1] This restriction ensures at compile time that there are no -dependences on a library unit. For GNAT, this includes implicit implementation -dependences on units of the runtime library that are created by the compiler -to support specific constructs of the language. - -@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1ca} -@subsection No_Direct_Boolean_Operators - - -@geindex No_Direct_Boolean_Operators - -[GNAT] This restriction ensures that no logical operators (and/or/xor) -are used on operands of type Boolean (or any type derived from Boolean). -This is intended for use in safety critical programs where the certification -protocol requires the use of short-circuit (and then, or else) forms for all -composite boolean operations. - -@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cb} -@subsection No_Dispatch - - -@geindex No_Dispatch - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. - -@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1cc} -@subsection No_Dispatching_Calls - - -@geindex No_Dispatching_Calls - -[GNAT] This restriction ensures at compile time that the code generated by the -compiler involves no dispatching calls. The use of this restriction allows the -safe use of record extensions, classwide membership tests and other classwide -features not involving implicit dispatching. This restriction ensures that -the code contains no indirect calls through a dispatching mechanism. Note that -this includes internally-generated calls created by the compiler, for example -in the implementation of class-wide objects assignments. The -membership test is allowed in the presence of this restriction, because its -implementation requires no dispatching. -This restriction is comparable to the official Ada restriction -@code{No_Dispatch} except that it is a bit less restrictive in that it allows -all classwide constructs that do not imply dispatching. -The following example indicates constructs that violate this restriction. - -@example -package Pkg is - type T is tagged record - Data : Natural; - end record; - procedure P (X : T); - - type DT is new T with record - More_Data : Natural; - end record; - procedure Q (X : DT); -end Pkg; - -with Pkg; use Pkg; -procedure Example is - procedure Test (O : T'Class) is - N : Natural := O'Size; -- Error: Dispatching call - C : T'Class := O; -- Error: implicit Dispatching Call - begin - if O in DT'Class then -- OK : Membership test - Q (DT (O)); -- OK : Type conversion plus direct call - else - P (O); -- Error: Dispatching call - end if; - end Test; - - Obj : DT; -begin - P (Obj); -- OK : Direct call - P (T (Obj)); -- OK : Type conversion plus direct call - P (T'Class (Obj)); -- Error: Dispatching call - - Test (Obj); -- OK : Type conversion - - if Obj in T'Class then -- OK : Membership test - null; - end if; -end Example; -@end example - -@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cd} -@subsection No_Dynamic_Attachment - - -@geindex No_Dynamic_Attachment - -[RM D.7] This restriction ensures that there is no call to any of the -operations defined in package Ada.Interrupts -(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, -Detach_Handler, and Reference). - -@geindex No_Dynamic_Interrupts - -The restriction @code{No_Dynamic_Interrupts} is recognized as a -synonym for @code{No_Dynamic_Attachment}. This is retained for historical -compatibility purposes (and a warning will be generated for its use if -warnings on obsolescent features are activated). - -@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1ce} -@subsection No_Dynamic_Priorities - - -@geindex No_Dynamic_Priorities - -[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. - -@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1cf} -@subsection No_Entry_Calls_In_Elaboration_Code - - -@geindex No_Entry_Calls_In_Elaboration_Code - -[GNAT] This restriction ensures at compile time that no task or protected entry -calls are made during elaboration code. As a result of the use of this -restriction, the compiler can assume that no code past an accept statement -in a task can be executed at elaboration time. - -@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d0} -@subsection No_Enumeration_Maps - - -@geindex No_Enumeration_Maps - -[GNAT] This restriction ensures at compile time that no operations requiring -enumeration maps are used (that is Image and Value attributes applied -to enumeration types). - -@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d1} -@subsection No_Exception_Handlers - - -@geindex No_Exception_Handlers - -[GNAT] This restriction ensures at compile time that there are no explicit -exception handlers. It also indicates that no exception propagation will -be provided. In this mode, exceptions may be raised but will result in -an immediate call to the last chance handler, a routine that the user -must define with the following profile: - -@example -procedure Last_Chance_Handler - (Source_Location : System.Address; Line : Integer); -pragma Export (C, Last_Chance_Handler, - "__gnat_last_chance_handler"); -@end example - -The parameter is a C null-terminated string representing a message to be -associated with the exception (typically the source location of the raise -statement generated by the compiler). The Line parameter when nonzero -represents the line number in the source program where the raise occurs. - -@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d2} -@subsection No_Exception_Propagation - - -@geindex No_Exception_Propagation - -[GNAT] This restriction guarantees that exceptions are never propagated -to an outer subprogram scope. The only case in which an exception may -be raised is when the handler is statically in the same subprogram, so -that the effect of a raise is essentially like a goto statement. Any -other raise statement (implicit or explicit) will be considered -unhandled. Exception handlers are allowed, but may not contain an -exception occurrence identifier (exception choice). In addition, use of -the package GNAT.Current_Exception is not permitted, and reraise -statements (raise with no operand) are not permitted. - -@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d3} -@subsection No_Exception_Registration - - -@geindex No_Exception_Registration - -[GNAT] This restriction ensures at compile time that no stream operations for -types Exception_Id or Exception_Occurrence are used. This also makes it -impossible to pass exceptions to or from a partition with this restriction -in a distributed environment. If this restriction is active, the generated -code is simplified by omitting the otherwise-required global registration -of exceptions when they are declared. - -@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d4} -@subsection No_Exceptions - - -@geindex No_Exceptions - -[RM H.4] This restriction ensures at compile time that there are no -raise statements and no exception handlers and also suppresses the -generation of language-defined run-time checks. - -@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d5} -@subsection No_Finalization - - -@geindex No_Finalization - -[GNAT] This restriction disables the language features described in -chapter 7.6 of the Ada 2005 RM as well as all form of code generation -performed by the compiler to support these features. The following types -are no longer considered controlled when this restriction is in effect: - - -@itemize * - -@item -@code{Ada.Finalization.Controlled} - -@item -@code{Ada.Finalization.Limited_Controlled} - -@item -Derivations from @code{Controlled} or @code{Limited_Controlled} - -@item -Class-wide types - -@item -Protected types - -@item -Task types - -@item -Array and record types with controlled components -@end itemize - -The compiler no longer generates code to initialize, finalize or adjust an -object or a nested component, either declared on the stack or on the heap. The -deallocation of a controlled object no longer finalizes its contents. - -@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d6} -@subsection No_Fixed_Point - - -@geindex No_Fixed_Point - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of fixed point types and operations. - -@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d7} -@subsection No_Floating_Point - - -@geindex No_Floating_Point - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of floating point types and operations. - -@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d8} -@subsection No_Implicit_Conditionals - - -@geindex No_Implicit_Conditionals - -[GNAT] This restriction ensures that the generated code does not contain any -implicit conditionals, either by modifying the generated code where possible, -or by rejecting any construct that would otherwise generate an implicit -conditional. Note that this check does not include run time constraint -checks, which on some targets may generate implicit conditionals as -well. To control the latter, constraint checks can be suppressed in the -normal manner. Constructs generating implicit conditionals include comparisons -of composite objects and the Max/Min attributes. - -@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1d9} -@subsection No_Implicit_Dynamic_Code - - -@geindex No_Implicit_Dynamic_Code - -@geindex trampoline - -[GNAT] This restriction prevents the compiler from building ‘trampolines’. -This is a structure that is built on the stack and contains dynamic -code to be executed at run time. On some targets, a trampoline is -built for the following features: @code{Access}, -@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; -nested task bodies; primitive operations of nested tagged types. -Trampolines do not work on machines that prevent execution of stack -data. For example, on windows systems, enabling DEP (data execution -protection) will cause trampolines to raise an exception. -Trampolines are also quite slow at run time. - -On many targets, trampolines have been largely eliminated. Look at the -version of system.ads for your target — if it has -Always_Compatible_Rep equal to False, then trampolines are largely -eliminated. In particular, a trampoline is built for the following -features: @code{Address} of a nested subprogram; -@code{Access} or @code{Unrestricted_Access} of a nested subprogram, -but only if pragma Favor_Top_Level applies, or the access type has a -foreign-language convention; primitive operations of nested tagged -types. - -@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1da} -@subsection No_Implicit_Heap_Allocations - - -@geindex No_Implicit_Heap_Allocations - -[RM D.7] No constructs are allowed to cause implicit heap allocation. - -@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1db} -@subsection No_Implicit_Protected_Object_Allocations - - -@geindex No_Implicit_Protected_Object_Allocations - -[GNAT] No constructs are allowed to cause implicit heap allocation of a -protected object. - -@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1dc} -@subsection No_Implicit_Task_Allocations - - -@geindex No_Implicit_Task_Allocations - -[GNAT] No constructs are allowed to cause implicit heap allocation of a task. - -@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1dd} -@subsection No_Initialize_Scalars - - -@geindex No_Initialize_Scalars - -[GNAT] This restriction ensures that no unit in the partition is compiled with -pragma Initialize_Scalars. This allows the generation of more efficient -code, and in particular eliminates dummy null initialization routines that -are otherwise generated for some record and array types. - -@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1de} -@subsection No_IO - - -@geindex No_IO - -[RM H.4] This restriction ensures at compile time that there are no -dependences on any of the library units Sequential_IO, Direct_IO, -Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. - -@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1df} -@subsection No_Local_Allocators - - -@geindex No_Local_Allocators - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator in subprograms, generic subprograms, tasks, -and entry bodies. - -@node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e0} -@subsection No_Local_Protected_Objects - - -@geindex No_Local_Protected_Objects - -[RM D.7] This restriction ensures at compile time that protected objects are -only declared at the library level. - -@node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1e1} -@subsection No_Local_Tagged_Types - - -@geindex No_Local_Tagged_Types - -[GNAT] This restriction ensures at compile time that tagged types are only -declared at the library level. - -@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e2} -@subsection No_Local_Timing_Events - - -@geindex No_Local_Timing_Events - -[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are -declared at the library level. - -@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e3} -@subsection No_Long_Long_Integers - - -@geindex No_Long_Long_Integers - -[GNAT] This partition-wide restriction forbids any explicit reference to -type Standard.Long_Long_Integer, and also forbids declaring range types whose -implicit base type is Long_Long_Integer, and modular types whose size exceeds -Long_Integer’Size. - -@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e4} -@subsection No_Multiple_Elaboration - - -@geindex No_Multiple_Elaboration - -[GNAT] When this restriction is active and the static elaboration model is -used, and -fpreserve-control-flow is not used, the compiler is allowed to -suppress the elaboration counter normally associated with the unit, even if -the unit has elaboration code. This counter is typically used to check for -access before elaboration and to control multiple elaboration attempts. If the -restriction is used, then the situations in which multiple elaboration is -possible, including non-Ada main programs and Stand Alone libraries, are not -permitted and will be diagnosed by the binder. - -@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e5} -@subsection No_Nested_Finalization - - -@geindex No_Nested_Finalization - -[RM D.7] All objects requiring finalization are declared at the library level. - -@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e6} -@subsection No_Protected_Type_Allocators - - -@geindex No_Protected_Type_Allocators - -[RM D.7] This restriction ensures at compile time that there are no allocator -expressions that attempt to allocate protected objects. - -@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e7} -@subsection No_Protected_Types - - -@geindex No_Protected_Types - -[RM H.4] This restriction ensures at compile time that there are no -declarations of protected types or protected objects. - -@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e8} -@subsection No_Recursion - - -@geindex No_Recursion - -[RM H.4] A program execution is erroneous if a subprogram is invoked as -part of its execution. - -@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e9} -@subsection No_Reentrancy - - -@geindex No_Reentrancy - -[RM H.4] A program execution is erroneous if a subprogram is executed by -two tasks at the same time. - -@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1ea} -@subsection No_Relative_Delay - - -@geindex No_Relative_Delay - -[RM D.7] This restriction ensures at compile time that there are no delay -relative statements and prevents expressions such as @code{delay 1.23;} from -appearing in source code. - -@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1eb} -@subsection No_Requeue_Statements - - -@geindex No_Requeue_Statements - -[RM D.7] This restriction ensures at compile time that no requeue statements -are permitted and prevents keyword @code{requeue} from being used in source -code. - -@geindex No_Requeue - -The restriction @code{No_Requeue} is recognized as a -synonym for @code{No_Requeue_Statements}. This is retained for historical -compatibility purposes (and a warning will be generated for its use if -warnings on oNobsolescent features are activated). - -@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ec} -@subsection No_Secondary_Stack - - -@geindex No_Secondary_Stack - -[GNAT] This restriction ensures at compile time that the generated code -does not contain any reference to the secondary stack. The secondary -stack is used to implement functions returning unconstrained objects -(arrays or records) on some targets. Suppresses the allocation of -secondary stacks for tasks (excluding the environment task) at run time. - -@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ed} -@subsection No_Select_Statements - - -@geindex No_Select_Statements - -[RM D.7] This restriction ensures at compile time no select statements of any -kind are permitted, that is the keyword @code{select} may not appear. - -@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ee} -@subsection No_Specific_Termination_Handlers - - -@geindex No_Specific_Termination_Handlers - -[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler -or to Ada.Task_Termination.Specific_Handler. - -@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1ef} -@subsection No_Specification_of_Aspect - - -@geindex No_Specification_of_Aspect - -[RM 13.12.1] This restriction checks at compile time that no aspect -specification, attribute definition clause, or pragma is given for a -given aspect. - -@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f0} -@subsection No_Standard_Allocators_After_Elaboration - - -@geindex No_Standard_Allocators_After_Elaboration - -[RM D.7] Specifies that an allocator using a standard storage pool -should never be evaluated at run time after the elaboration of the -library items of the partition has completed. Otherwise, Storage_Error -is raised. - -@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f1} -@subsection No_Standard_Storage_Pools - - -@geindex No_Standard_Storage_Pools - -[GNAT] This restriction ensures at compile time that no access types -use the standard default storage pool. Any access type declared must -have an explicit Storage_Pool attribute defined specifying a -user-defined storage pool. - -@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f2} -@subsection No_Stream_Optimizations - - -@geindex No_Stream_Optimizations - -[GNAT] This restriction affects the performance of stream operations on types -@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the -compiler uses block reads and writes when manipulating @code{String} objects -due to their superior performance. When this restriction is in effect, the -compiler performs all IO operations on a per-character basis. - -@node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f3} -@subsection No_Streams - - -@geindex No_Streams - -[GNAT] This restriction ensures at compile/bind time that there are no -stream objects created and no use of stream attributes. -This restriction does not forbid dependences on the package -@code{Ada.Streams}. So it is permissible to with -@code{Ada.Streams} (or another package that does so itself) -as long as no actual stream objects are created and no -stream attributes are used. - -Note that the use of restriction allows optimization of tagged types, -since they do not need to worry about dispatching stream operations. -To take maximum advantage of this space-saving optimization, any -unit declaring a tagged type should be compiled with the restriction, -though this is not required. - -@node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1f4} -@subsection No_Tagged_Type_Registration - - -@geindex No_Tagged_Type_Registration - -[GNAT] If this restriction is active, then class-wide streaming -attributes are not supported. In addition, the subprograms in -Ada.Tags are not supported. -If this restriction is active, the generated code is simplified by -omitting the otherwise-required global registration of tagged types when they -are declared. This restriction may be necessary in order to also apply -the No_Elaboration_Code restriction. - -@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5} -@subsection No_Task_Allocators - - -@geindex No_Task_Allocators - -[RM D.7] There are no allocators for task types -or types containing task subcomponents. - -@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6} -@subsection No_Task_At_Interrupt_Priority - - -@geindex No_Task_At_Interrupt_Priority - -[GNAT] This restriction ensures at compile time that there is no -Interrupt_Priority aspect or pragma for a task or a task type. As -a consequence, the tasks are always created with a priority below -that an interrupt priority. - -@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7} -@subsection No_Task_Attributes_Package - - -@geindex No_Task_Attributes_Package - -[GNAT] This restriction ensures at compile time that there are no implicit or -explicit dependencies on the package @code{Ada.Task_Attributes}. - -@geindex No_Task_Attributes - -The restriction @code{No_Task_Attributes} is recognized as a synonym -for @code{No_Task_Attributes_Package}. This is retained for historical -compatibility purposes (and a warning will be generated for its use if -warnings on obsolescent features are activated). - -@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8} -@subsection No_Task_Hierarchy - - -@geindex No_Task_Hierarchy - -[RM D.7] All (non-environment) tasks depend -directly on the environment task of the partition. - -@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9} -@subsection No_Task_Termination - - -@geindex No_Task_Termination - -[RM D.7] Tasks that terminate are erroneous. - -@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa} -@subsection No_Tasking - - -@geindex No_Tasking - -[GNAT] This restriction prevents the declaration of tasks or task types -throughout the partition. It is similar in effect to the use of -@code{Max_Tasks => 0} except that violations are caught at compile time -and cause an error message to be output either by the compiler or -binder. - -@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb} -@subsection No_Terminate_Alternatives - - -@geindex No_Terminate_Alternatives - -[RM D.7] There are no selective accepts with terminate alternatives. - -@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc} -@subsection No_Unchecked_Access - - -@geindex No_Unchecked_Access - -[RM H.4] This restriction ensures at compile time that there are no -occurrences of the Unchecked_Access attribute. - -@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd} -@subsection No_Unchecked_Conversion - - -@geindex No_Unchecked_Conversion - -[RM J.13] This restriction ensures at compile time that there are no semantic -dependences on the predefined generic function Unchecked_Conversion. - -@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe} -@subsection No_Unchecked_Deallocation - - -@geindex No_Unchecked_Deallocation - -[RM J.13] This restriction ensures at compile time that there are no semantic -dependences on the predefined generic procedure Unchecked_Deallocation. - -@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff} -@subsection No_Use_Of_Entity - - -@geindex No_Use_Of_Entity - -[GNAT] This restriction ensures at compile time that there are no references -to the entity given in the form - -@example -No_Use_Of_Entity => Name -@end example - -where @code{Name} is the fully qualified entity, for example - -@example -No_Use_Of_Entity => Ada.Text_IO.Put_Line -@end example - -@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200} -@subsection Pure_Barriers - - -@geindex Pure_Barriers - -[GNAT] This restriction ensures at compile time that protected entry -barriers are restricted to: - - -@itemize * - -@item -components of the protected object (excluding selection from dereferences), - -@item -constant declarations, - -@item -named numbers, - -@item -enumeration literals, - -@item -integer literals, - -@item -real literals, - -@item -character literals, - -@item -implicitly defined comparison operators, - -@item -uses of the Standard.”not” operator, - -@item -short-circuit operator, - -@item -the Count attribute -@end itemize - -This restriction is a relaxation of the Simple_Barriers restriction, -but still ensures absence of side effects, exceptions, and recursion -during the evaluation of the barriers. - -@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201} -@subsection Simple_Barriers - - -@geindex Simple_Barriers - -[RM D.7] This restriction ensures at compile time that barriers in entry -declarations for protected types are restricted to either static boolean -expressions or references to simple boolean variables defined in the private -part of the protected type. No other form of entry barriers is permitted. - -@geindex Boolean_Entry_Barriers - -The restriction @code{Boolean_Entry_Barriers} is recognized as a -synonym for @code{Simple_Barriers}. This is retained for historical -compatibility purposes (and a warning will be generated for its use if -warnings on obsolescent features are activated). - -@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202} -@subsection Static_Priorities - - -@geindex Static_Priorities - -[GNAT] This restriction ensures at compile time that all priority expressions -are static, and that there are no dependences on the package -@code{Ada.Dynamic_Priorities}. - -@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203} -@subsection Static_Storage_Size - - -@geindex Static_Storage_Size - -[GNAT] This restriction ensures at compile time that any expression appearing -in a Storage_Size pragma or attribute definition clause is static. - -@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205} -@section Program Unit Level Restrictions - - -The second set of restriction identifiers -does not require partition-wide consistency. -The restriction may be enforced for a single -compilation unit without any effect on any of the -other compilation units in the partition. - -@menu -* No_Elaboration_Code:: -* No_Dynamic_Accessibility_Checks:: -* No_Dynamic_Sized_Objects:: -* No_Entry_Queue:: -* No_Implementation_Aspect_Specifications:: -* No_Implementation_Attributes:: -* No_Implementation_Identifiers:: -* No_Implementation_Pragmas:: -* No_Implementation_Restrictions:: -* No_Implementation_Units:: -* No_Implicit_Aliasing:: -* No_Implicit_Loops:: -* No_Obsolescent_Features:: -* No_Wide_Characters:: -* Static_Dispatch_Tables:: -* SPARK_05:: - -@end menu - -@node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206} -@subsection No_Elaboration_Code - - -@geindex No_Elaboration_Code - -[GNAT] This restriction ensures at compile time that no elaboration code is -generated. Note that this is not the same condition as is enforced -by pragma @code{Preelaborate}. There are cases in which pragma -@code{Preelaborate} still permits code to be generated (e.g., code -to initialize a large array to all zeroes), and there are cases of units -which do not meet the requirements for pragma @code{Preelaborate}, -but for which no elaboration code is generated. Generally, it is -the case that preelaborable units will meet the restrictions, with -the exception of large aggregates initialized with an others_clause, -and exception declarations (which generate calls to a run-time -registry procedure). This restriction is enforced on -a unit by unit basis, it need not be obeyed consistently -throughout a partition. - -In the case of aggregates with others, if the aggregate has a dynamic -size, there is no way to eliminate the elaboration code (such dynamic -bounds would be incompatible with @code{Preelaborate} in any case). If -the bounds are static, then use of this restriction actually modifies -the code choice of the compiler to avoid generating a loop, and instead -generate the aggregate statically if possible, no matter how many times -the data for the others clause must be repeatedly generated. - -It is not possible to precisely document -the constructs which are compatible with this restriction, since, -unlike most other restrictions, this is not a restriction on the -source code, but a restriction on the generated object code. For -example, if the source contains a declaration: - -@example -Val : constant Integer := X; -@end example - -where X is not a static constant, it may be possible, depending -on complex optimization circuitry, for the compiler to figure -out the value of X at compile time, in which case this initialization -can be done by the loader, and requires no initialization code. It -is not possible to document the precise conditions under which the -optimizer can figure this out. - -Note that this the implementation of this restriction requires full -code generation. If it is used in conjunction with “semantics only” -checking, then some cases of violations may be missed. - -When this restriction is active, we are not requesting control-flow -preservation with -fpreserve-control-flow, and the static elaboration model is -used, the compiler is allowed to suppress the elaboration counter normally -associated with the unit. This counter is typically used to check for access -before elaboration and to control multiple elaboration attempts. - -@node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207} -@subsection No_Dynamic_Accessibility_Checks - - -@geindex No_Dynamic_Accessibility_Checks - -[GNAT] No dynamic accessibility checks are generated when this restriction is -in effect. Instead, dangling references are prevented via more conservative -compile-time checking. More specifically, existing compile-time checks are -enforced but with more conservative assumptions about the accessibility levels -of the relevant entities. These conservative assumptions eliminate the need for -dynamic accessibility checks. - -These new rules for computing (at compile-time) the accessibility level of an -anonymous access type T are as follows: - - -@itemize * - -@item -If T is a function result type then, from the caller’s perspective, its level -is that of the innermost master enclosing the function call. From the callee’s -perspective, the level of parameters and local variables of the callee is -statically deeper than the level of T. - -For any other accessibility level L such that the level of parameters and local -variables of the callee is statically deeper than L, the level of T (from the -callee’s perspective) is also statically deeper than L. - -@item -If T is the type of a formal parameter then, from the caller’s perspective, -its level is at least as deep as that of the type of the corresponding actual -parameter (whatever that actual parameter might be). From the callee’s -perspective, the level of parameters and local variables of the callee is -statically deeper than the level of T. - -@item -If T is the type of a discriminant then its level is that of the discriminated -type. - -@item -If T is the type of a stand-alone object then its level is the level of the -object. - -@item -In all other cases, the level of T is as defined by the existing rules of Ada. -@end itemize - -@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208} -@subsection No_Dynamic_Sized_Objects - - -@geindex No_Dynamic_Sized_Objects - -[GNAT] This restriction disallows certain constructs that might lead to the -creation of dynamic-sized composite objects (or array or discriminated type). -An array subtype indication is illegal if the bounds are not static -or references to discriminants of an enclosing type. -A discriminated subtype indication is illegal if the type has -discriminant-dependent array components or a variant part, and the -discriminants are not static. In addition, array and record aggregates are -illegal in corresponding cases. Note that this restriction does not forbid -access discriminants. It is often a good idea to combine this restriction -with No_Secondary_Stack. - -@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209} -@subsection No_Entry_Queue - - -@geindex No_Entry_Queue - -[GNAT] This restriction is a declaration that any protected entry compiled in -the scope of the restriction has at most one task waiting on the entry -at any one time, and so no queue is required. This restriction is not -checked at compile time. A program execution is erroneous if an attempt -is made to queue a second task on such an entry. - -@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a} -@subsection No_Implementation_Aspect_Specifications - - -@geindex No_Implementation_Aspect_Specifications - -[RM 13.12.1] This restriction checks at compile time that no -GNAT-defined aspects are present. With this restriction, the only -aspects that can be used are those defined in the Ada Reference Manual. - -@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b} -@subsection No_Implementation_Attributes - - -@geindex No_Implementation_Attributes - -[RM 13.12.1] This restriction checks at compile time that no -GNAT-defined attributes are present. With this restriction, the only -attributes that can be used are those defined in the Ada Reference -Manual. - -@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c} -@subsection No_Implementation_Identifiers - - -@geindex No_Implementation_Identifiers - -[RM 13.12.1] This restriction checks at compile time that no -implementation-defined identifiers (marked with pragma Implementation_Defined) -occur within language-defined packages. - -@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d} -@subsection No_Implementation_Pragmas - - -@geindex No_Implementation_Pragmas - -[RM 13.12.1] This restriction checks at compile time that no -GNAT-defined pragmas are present. With this restriction, the only -pragmas that can be used are those defined in the Ada Reference Manual. - -@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e} -@subsection No_Implementation_Restrictions - - -@geindex No_Implementation_Restrictions - -[GNAT] This restriction checks at compile time that no GNAT-defined restriction -identifiers (other than @code{No_Implementation_Restrictions} itself) -are present. With this restriction, the only other restriction identifiers -that can be used are those defined in the Ada Reference Manual. - -@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f} -@subsection No_Implementation_Units - - -@geindex No_Implementation_Units - -[RM 13.12.1] This restriction checks at compile time that there is no -mention in the context clause of any implementation-defined descendants -of packages Ada, Interfaces, or System. - -@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210} -@subsection No_Implicit_Aliasing - - -@geindex No_Implicit_Aliasing - -[GNAT] This restriction, which is not required to be partition-wide consistent, -requires an explicit aliased keyword for an object to which ‘Access, -‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of -the ‘Unrestricted_Access attribute for objects. Note: the reason that -Unrestricted_Access is forbidden is that it would require the prefix -to be aliased, and in such cases, it can always be replaced by -the standard attribute Unchecked_Access which is preferable. - -@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211} -@subsection No_Implicit_Loops - - -@geindex No_Implicit_Loops - -[GNAT] This restriction ensures that the generated code of the unit marked -with this restriction does not contain any implicit @code{for} loops, either by -modifying the generated code where possible, or by rejecting any construct -that would otherwise generate an implicit @code{for} loop. If this restriction is -active, it is possible to build large array aggregates with all static -components without generating an intermediate temporary, and without generating -a loop to initialize individual components. Otherwise, a loop is created for -arrays larger than about 5000 scalar components. Note that if this restriction -is set in the spec of a package, it will not apply to its body. - -@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212} -@subsection No_Obsolescent_Features - - -@geindex No_Obsolescent_Features - -[RM 13.12.1] This restriction checks at compile time that no obsolescent -features are used, as defined in Annex J of the Ada Reference Manual. - -@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213} -@subsection No_Wide_Characters - - -@geindex No_Wide_Characters - -[GNAT] This restriction ensures at compile time that no uses of the types -@code{Wide_Character} or @code{Wide_String} or corresponding wide -wide types -appear, and that no wide or wide wide string or character literals -appear in the program (that is literals representing characters not in -type @code{Character}). - -@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214} -@subsection Static_Dispatch_Tables - - -@geindex Static_Dispatch_Tables - -[GNAT] This restriction checks at compile time that all the artifacts -associated with dispatch tables can be placed in read-only memory. - -@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions -@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215} -@subsection SPARK_05 - - -@geindex SPARK_05 - -[GNAT] This restriction no longer has any effect and is superseded by -SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that -a codebase respects SPARK 2014 restrictions, mark the code with pragma or -aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as -follows: - -@example -gnatprove -P project.gpr --mode=stone -@end example - -or equivalently: - -@example -gnatprove -P project.gpr --mode=check_all -@end example - -@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top -@anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice id1}@anchor{217}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a} -@chapter Implementation Advice - - -The main text of the Ada Reference Manual describes the required -behavior of all Ada compilers, and the GNAT compiler conforms to -these requirements. - -In addition, there are sections throughout the Ada Reference Manual headed -by the phrase ‘Implementation advice’. These sections are not normative, -i.e., they do not specify requirements that all compilers must -follow. Rather they provide advice on generally desirable behavior. -They are not requirements, because they describe behavior that cannot -be provided on all systems, or may be undesirable on some systems. - -As far as practical, GNAT follows the implementation advice in -the Ada Reference Manual. Each such RM section corresponds to a section -in this chapter whose title specifies the -RM section number and paragraph number and the subject of -the advice. The contents of each section consists of the RM text within -quotation marks, -followed by the GNAT interpretation of the advice. Most often, this simply says -‘followed’, which means that GNAT follows the advice. However, in a -number of cases, GNAT deliberately deviates from this advice, in which -case the text describes what GNAT does and why. - -@geindex Error detection - -@menu -* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. -* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. -* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. -* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. -* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. -* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. -* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. -* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. -* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. -* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. -* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. -* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. -* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. -* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. -* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. -* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. -* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. -* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. -* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. -* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. -* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. -* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. -* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. -* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. -* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. -* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. -* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. -* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. -* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. -* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. -* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. -* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. -* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. -* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. -* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. -* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. -* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. -* RM A.18; Containers: RM A 18 Containers. -* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. -* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. -* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. -* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. -* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. -* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. -* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. -* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. -* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. -* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. -* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. -* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. -* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. -* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. -* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. -* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. -* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. -* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. -* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. -* RM F(7); COBOL Support: RM F 7 COBOL Support. -* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. -* RM G; Numerics: RM G Numerics. -* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. -* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. -* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. -* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. -* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. - -@end menu - -@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218} -@section RM 1.1.3(20): Error Detection - - -@quotation - -“If an implementation detects the use of an unsupported Specialized Needs -Annex feature at run time, it should raise @code{Program_Error} if -feasible.” -@end quotation - -Not relevant. All specialized needs annex features are either supported, -or diagnosed at compile time. - -@geindex Child Units - -@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219} -@section RM 1.1.3(31): Child Units - - -@quotation - -“If an implementation wishes to provide implementation-defined -extensions to the functionality of a language-defined library unit, it -should normally do so by adding children to the library unit.” -@end quotation - -Followed. - -@geindex Bounded errors - -@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a} -@section RM 1.1.5(12): Bounded Errors - - -@quotation - -“If an implementation detects a bounded error or erroneous -execution, it should raise @code{Program_Error}.” -@end quotation - -Followed in all cases in which the implementation detects a bounded -error or erroneous execution. Not all such situations are detected at -runtime. - -@geindex Pragmas - -@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice -@anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c} -@section RM 2.8(16): Pragmas - - -@quotation - -“Normally, implementation-defined pragmas should have no semantic effect -for error-free programs; that is, if the implementation-defined pragmas -are removed from a working program, the program should still be legal, -and should still have the same semantics.” -@end quotation - -The following implementation defined pragmas are exceptions to this -rule: - - -@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} -@headitem - -Pragma - -@tab - -Explanation - -@item - -`Abort_Defer' - -@tab - -Affects semantics - -@item - -`Ada_83' - -@tab - -Affects legality - -@item - -`Assert' - -@tab - -Affects semantics - -@item - -`CPP_Class' - -@tab - -Affects semantics - -@item - -`CPP_Constructor' - -@tab - -Affects semantics - -@item - -`Debug' - -@tab - -Affects semantics - -@item - -`Interface_Name' - -@tab - -Affects semantics - -@item - -`Machine_Attribute' - -@tab - -Affects semantics - -@item - -`Unimplemented_Unit' - -@tab - -Affects legality - -@item - -`Unchecked_Union' - -@tab - -Affects semantics - -@end multitable - - -In each of the above cases, it is essential to the purpose of the pragma -that this advice not be followed. For details see -@ref{7,,Implementation Defined Pragmas}. - -@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d} -@section RM 2.8(17-19): Pragmas - - -@quotation - -“Normally, an implementation should not define pragmas that can -make an illegal program legal, except as follows: - - -@itemize * - -@item -A pragma used to complete a declaration, such as a pragma @code{Import}; - -@item -A pragma used to configure the environment by adding, removing, or -replacing @code{library_items}.” -@end itemize -@end quotation - -See @ref{21c,,RM 2.8(16); Pragmas}. - -@geindex Character Sets - -@geindex Alternative Character Sets - -@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e} -@section RM 3.5.2(5): Alternative Character Sets - - -@quotation - -“If an implementation supports a mode with alternative interpretations -for @code{Character} and @code{Wide_Character}, the set of graphic -characters of @code{Character} should nevertheless remain a proper -subset of the set of graphic characters of @code{Wide_Character}. Any -character set ‘localizations’ should be reflected in the results of -the subprograms defined in the language-defined package -@code{Characters.Handling} (see A.3) available in such a mode. In a mode with -an alternative interpretation of @code{Character}, the implementation should -also support a corresponding change in what is a legal -@code{identifier_letter}.” -@end quotation - -Not all wide character modes follow this advice, in particular the JIS -and IEC modes reflect standard usage in Japan, and in these encoding, -the upper half of the Latin-1 set is not part of the wide-character -subset, since the most significant bit is used for wide character -encoding. However, this only applies to the external forms. Internally -there is no such restriction. - -@geindex Integer types - -@node RM 3 5 4 28 Integer Types,RM 3 5 4 29 Integer Types,RM 3 5 2 5 Alternative Character Sets,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f} -@section RM 3.5.4(28): Integer Types - - -@quotation - -“An implementation should support @code{Long_Integer} in addition to -@code{Integer} if the target machine supports 32-bit (or longer) -arithmetic. No other named integer subtypes are recommended for package -@code{Standard}. Instead, appropriate named integer subtypes should be -provided in the library package @code{Interfaces} (see B.2).” -@end quotation - -@code{Long_Integer} is supported. Other standard integer types are supported -so this advice is not fully followed. These types -are supported for convenient interface to C, and so that all hardware -types of the machine are easily available. - -@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220} -@section RM 3.5.4(29): Integer Types - - -@quotation - -“An implementation for a two’s complement machine should support -modular types with a binary modulus up to @code{System.Max_Int*2+2}. An -implementation should support a non-binary modules up to @code{Integer'Last}.” -@end quotation - -Followed. - -@geindex Enumeration values - -@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221} -@section RM 3.5.5(8): Enumeration Values - - -@quotation - -“For the evaluation of a call on @code{S'Pos} for an enumeration -subtype, if the value of the operand does not correspond to the internal -code for any enumeration literal of its type (perhaps due to an -un-initialized variable), then the implementation should raise -@code{Program_Error}. This is particularly important for enumeration -types with noncontiguous internal codes specified by an -enumeration_representation_clause.” -@end quotation - -Followed. - -@geindex Float types - -@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222} -@section RM 3.5.7(17): Float Types - - -@quotation - -“An implementation should support @code{Long_Float} in addition to -@code{Float} if the target machine supports 11 or more digits of -precision. No other named floating point subtypes are recommended for -package @code{Standard}. Instead, appropriate named floating point subtypes -should be provided in the library package @code{Interfaces} (see B.2).” -@end quotation - -@code{Short_Float} and @code{Long_Long_Float} are also provided. The -former provides improved compatibility with other implementations -supporting this type. The latter corresponds to the highest precision -floating-point type supported by the hardware. On most machines, this -will be the same as @code{Long_Float}, but on some machines, it will -correspond to the IEEE extended form. The notable case is all x86 -implementations, where @code{Long_Long_Float} corresponds to the 80-bit -extended precision format supported in hardware on this processor. -Note that the 128-bit format on SPARC is not supported, since this -is a software rather than a hardware format. - -@geindex Multidimensional arrays - -@geindex Arrays -@geindex multidimensional - -@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223} -@section RM 3.6.2(11): Multidimensional Arrays - - -@quotation - -“An implementation should normally represent multidimensional arrays in -row-major order, consistent with the notation used for multidimensional -array aggregates (see 4.3.3). However, if a pragma @code{Convention} -(@code{Fortran}, …) applies to a multidimensional array type, then -column-major order should be used instead (see B.5, `Interfacing with Fortran').” -@end quotation - -Followed. - -@geindex Duration'Small - -@node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224} -@section RM 9.6(30-31): Duration’Small - - -@quotation - -“Whenever possible in an implementation, the value of @code{Duration'Small} -should be no greater than 100 microseconds.” -@end quotation - -Followed. (@code{Duration'Small} = 10**(-9)). - -@quotation - -“The time base for @code{delay_relative_statements} should be monotonic; -it need not be the same time base as used for @code{Calendar.Clock}.” -@end quotation - -Followed. - -@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225} -@section RM 10.2.1(12): Consistent Representation - - -@quotation - -“In an implementation, a type declared in a pre-elaborated package should -have the same representation in every elaboration of a given version of -the package, whether the elaborations occur in distinct executions of -the same program, or in executions of distinct programs or partitions -that include the given version.” -@end quotation - -Followed, except in the case of tagged types. Tagged types involve -implicit pointers to a local copy of a dispatch table, and these pointers -have representations which thus depend on a particular elaboration of the -package. It is not easy to see how it would be possible to follow this -advice without severely impacting efficiency of execution. - -@geindex Exception information - -@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226} -@section RM 11.4.1(19): Exception Information - - -@quotation - -“@code{Exception_Message} by default and @code{Exception_Information} -should produce information useful for -debugging. @code{Exception_Message} should be short, about one -line. @code{Exception_Information} can be long. @code{Exception_Message} -should not include the -@code{Exception_Name}. @code{Exception_Information} should include both -the @code{Exception_Name} and the @code{Exception_Message}.” -@end quotation - -Followed. For each exception that doesn’t have a specified -@code{Exception_Message}, the compiler generates one containing the location -of the raise statement. This location has the form ‘file_name:line’, where -file_name is the short file name (without path information) and line is the line -number in the file. Note that in the case of the Zero Cost Exception -mechanism, these messages become redundant with the Exception_Information that -contains a full backtrace of the calling sequence, so they are disabled. -To disable explicitly the generation of the source location message, use the -Pragma @code{Discard_Names}. - -@geindex Suppression of checks - -@geindex Checks -@geindex suppression of - -@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227} -@section RM 11.5(28): Suppression of Checks - - -@quotation - -“The implementation should minimize the code executed for checks that -have been suppressed.” -@end quotation - -Followed. - -@geindex Representation clauses - -@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228} -@section RM 13.1 (21-24): Representation Clauses - - -@quotation - -“The recommended level of support for all representation items is -qualified as follows: - -An implementation need not support representation items containing -nonstatic expressions, except that an implementation should support a -representation item for a given entity if each nonstatic expression in -the representation item is a name that statically denotes a constant -declared before the entity.” -@end quotation - -Followed. In fact, GNAT goes beyond the recommended level of support -by allowing nonstatic expressions in some representation clauses even -without the need to declare constants initialized with the values of -such expressions. -For example: - -@example - X : Integer; - Y : Float; - for Y'Address use X'Address;>> - - -"An implementation need not support a specification for the `@w{`}Size`@w{`} -for a given composite subtype, nor the size or storage place for an -object (including a component) of a given composite subtype, unless the -constraints on the subtype and its composite subcomponents (if any) are -all static constraints." -@end example - -Followed. Size Clauses are not permitted on nonstatic components, as -described above. - -@quotation - -“An aliased component, or a component whose type is by-reference, should -always be allocated at an addressable location.” -@end quotation - -Followed. - -@geindex Packed types - -@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229} -@section RM 13.2(6-8): Packed Types - - -@quotation - -“If a type is packed, then the implementation should try to minimize -storage allocated to objects of the type, possibly at the expense of -speed of accessing components, subject to reasonable complexity in -addressing calculations. - -The recommended level of support pragma @code{Pack} is: - -For a packed record type, the components should be packed as tightly as -possible subject to the Sizes of the component subtypes, and subject to -any `record_representation_clause' that applies to the type; the -implementation may, but need not, reorder components or cross aligned -word boundaries to improve the packing. A component whose @code{Size} is -greater than the word size may be allocated an integral number of words.” -@end quotation - -Followed. Tight packing of arrays is supported for all component sizes -up to 64-bits. If the array component size is 1 (that is to say, if -the component is a boolean type or an enumeration type with two values) -then values of the type are implicitly initialized to zero. This -happens both for objects of the packed type, and for objects that have a -subcomponent of the packed type. - -@geindex Address clauses - -@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a} -@section RM 13.3(14-19): Address Clauses - - -@quotation - -“For an array @code{X}, @code{X'Address} should point at the first -component of the array, and not at the array bounds.” -@end quotation - -Followed. - -@quotation - -“The recommended level of support for the @code{Address} attribute is: - -@code{X'Address} should produce a useful result if @code{X} is an -object that is aliased or of a by-reference type, or is an entity whose -@code{Address} has been specified.” -@end quotation - -Followed. A valid address will be produced even if none of those -conditions have been met. If necessary, the object is forced into -memory to ensure the address is valid. - -@quotation - -“An implementation should support @code{Address} clauses for imported -subprograms.” -@end quotation - -Followed. - -@quotation - -“Objects (including subcomponents) that are aliased or of a by-reference -type should be allocated on storage element boundaries.” -@end quotation - -Followed. - -@quotation - -“If the @code{Address} of an object is specified, or it is imported or exported, -then the implementation should not perform optimizations based on -assumptions of no aliases.” -@end quotation - -Followed. - -@geindex Alignment clauses - -@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b} -@section RM 13.3(29-35): Alignment Clauses - - -@quotation - -“The recommended level of support for the @code{Alignment} attribute for -subtypes is: - -An implementation should support specified Alignments that are factors -and multiples of the number of storage elements per word, subject to the -following:” -@end quotation - -Followed. - -@quotation - -“An implementation need not support specified Alignments for -combinations of Sizes and Alignments that cannot be easily -loaded and stored by available machine instructions.” -@end quotation - -Followed. - -@quotation - -“An implementation need not support specified Alignments that are -greater than the maximum @code{Alignment} the implementation ever returns by -default.” -@end quotation - -Followed. - -@quotation - -“The recommended level of support for the @code{Alignment} attribute for -objects is: - -Same as above, for subtypes, but in addition:” -@end quotation - -Followed. - -@quotation - -“For stand-alone library-level objects of statically constrained -subtypes, the implementation should support all alignments -supported by the target linker. For example, page alignment is likely to -be supported for such objects, but not for subtypes.” -@end quotation - -Followed. - -@geindex Size clauses - -@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c} -@section RM 13.3(42-43): Size Clauses - - -@quotation - -“The recommended level of support for the @code{Size} attribute of -objects is: - -A @code{Size} clause should be supported for an object if the specified -@code{Size} is at least as large as its subtype’s @code{Size}, and -corresponds to a size in storage elements that is a multiple of the -object’s @code{Alignment} (if the @code{Alignment} is nonzero).” -@end quotation - -Followed. - -@node RM 13 3 50-56 Size Clauses,RM 13 3 71-73 Component Size Clauses,RM 13 3 42-43 Size Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d} -@section RM 13.3(50-56): Size Clauses - - -@quotation - -“If the @code{Size} of a subtype is specified, and allows for efficient -independent addressability (see 9.10) on the target architecture, then -the @code{Size} of the following objects of the subtype should equal the -@code{Size} of the subtype: - -Aliased objects (including components).” -@end quotation - -Followed. - -@quotation - -“@cite{Size} clause on a composite subtype should not affect the -internal layout of components.” -@end quotation - -Followed. But note that this can be overridden by use of the implementation -pragma Implicit_Packing in the case of packed arrays. - -@quotation - -“The recommended level of support for the @code{Size} attribute of subtypes is: - -The @code{Size} (if not specified) of a static discrete or fixed point -subtype should be the number of bits needed to represent each value -belonging to the subtype using an unbiased representation, leaving space -for a sign bit only if the subtype contains negative values. If such a -subtype is a first subtype, then an implementation should support a -specified @code{Size} for it that reflects this representation.” -@end quotation - -Followed. - -@quotation - -“For a subtype implemented with levels of indirection, the @code{Size} -should include the size of the pointers, but not the size of what they -point at.” -@end quotation - -Followed. - -@geindex Component_Size clauses - -@node RM 13 3 71-73 Component Size Clauses,RM 13 4 9-10 Enumeration Representation Clauses,RM 13 3 50-56 Size Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e} -@section RM 13.3(71-73): Component Size Clauses - - -@quotation - -“The recommended level of support for the @code{Component_Size} -attribute is: - -An implementation need not support specified @code{Component_Sizes} that are -less than the @code{Size} of the component subtype.” -@end quotation - -Followed. - -@quotation - -“An implementation should support specified Component_Sizes that -are factors and multiples of the word size. For such -Component_Sizes, the array should contain no gaps between -components. For other Component_Sizes (if supported), the array -should contain no gaps between components when packing is also -specified; the implementation should forbid this combination in cases -where it cannot support a no-gaps representation.” -@end quotation - -Followed. - -@geindex Enumeration representation clauses - -@geindex Representation clauses -@geindex enumeration - -@node RM 13 4 9-10 Enumeration Representation Clauses,RM 13 5 1 17-22 Record Representation Clauses,RM 13 3 71-73 Component Size Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f} -@section RM 13.4(9-10): Enumeration Representation Clauses - - -@quotation - -“The recommended level of support for enumeration representation clauses -is: - -An implementation need not support enumeration representation clauses -for boolean types, but should at minimum support the internal codes in -the range @code{System.Min_Int .. System.Max_Int}.” -@end quotation - -Followed. - -@geindex Record representation clauses - -@geindex Representation clauses -@geindex records - -@node RM 13 5 1 17-22 Record Representation Clauses,RM 13 5 2 5 Storage Place Attributes,RM 13 4 9-10 Enumeration Representation Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230} -@section RM 13.5.1(17-22): Record Representation Clauses - - -@quotation - -“The recommended level of support for -`record_representation_clause's is: - -An implementation should support storage places that can be extracted -with a load, mask, shift sequence of machine code, and set with a load, -shift, mask, store sequence, given the available machine instructions -and run-time model.” -@end quotation - -Followed. - -@quotation - -“A storage place should be supported if its size is equal to the -@code{Size} of the component subtype, and it starts and ends on a -boundary that obeys the @code{Alignment} of the component subtype.” -@end quotation - -Followed. - -@quotation - -“If the default bit ordering applies to the declaration of a given type, -then for a component whose subtype’s @code{Size} is less than the word -size, any storage place that does not cross an aligned word boundary -should be supported.” -@end quotation - -Followed. - -@quotation - -“An implementation may reserve a storage place for the tag field of a -tagged type, and disallow other components from overlapping that place.” -@end quotation - -Followed. The storage place for the tag field is the beginning of the tagged -record, and its size is Address’Size. GNAT will reject an explicit component -clause for the tag field. - -@quotation - -“An implementation need not support a `component_clause' for a -component of an extension part if the storage place is not after the -storage places of all components of the parent type, whether or not -those storage places had been specified.” -@end quotation - -Followed. The above advice on record representation clauses is followed, -and all mentioned features are implemented. - -@geindex Storage place attributes - -@node RM 13 5 2 5 Storage Place Attributes,RM 13 5 3 7-8 Bit Ordering,RM 13 5 1 17-22 Record Representation Clauses,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231} -@section RM 13.5.2(5): Storage Place Attributes - - -@quotation - -“If a component is represented using some form of pointer (such as an -offset) to the actual data of the component, and this data is contiguous -with the rest of the object, then the storage place attributes should -reflect the place of the actual data, not the pointer. If a component is -allocated discontinuously from the rest of the object, then a warning -should be generated upon reference to one of its storage place -attributes.” -@end quotation - -Followed. There are no such components in GNAT. - -@geindex Bit ordering - -@node RM 13 5 3 7-8 Bit Ordering,RM 13 7 37 Address as Private,RM 13 5 2 5 Storage Place Attributes,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232} -@section RM 13.5.3(7-8): Bit Ordering - - -@quotation - -“The recommended level of support for the non-default bit ordering is: - -If @code{Word_Size} = @code{Storage_Unit}, then the implementation -should support the non-default bit ordering in addition to the default -bit ordering.” -@end quotation - -Followed. Word size does not equal storage size in this implementation. -Thus non-default bit ordering is not supported. - -@geindex Address -@geindex as private type - -@node RM 13 7 37 Address as Private,RM 13 7 1 16 Address Operations,RM 13 5 3 7-8 Bit Ordering,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233} -@section RM 13.7(37): Address as Private - - -@quotation - -“@cite{Address} should be of a private type.” -@end quotation - -Followed. - -@geindex Operations -@geindex on `@w{`}Address`@w{`} - -@geindex Address -@geindex operations of - -@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234} -@section RM 13.7.1(16): Address Operations - - -@quotation - -“Operations in @code{System} and its children should reflect the target -environment semantics as closely as is reasonable. For example, on most -machines, it makes sense for address arithmetic to ‘wrap around’. -Operations that do not make sense should raise @code{Program_Error}.” -@end quotation - -Followed. Address arithmetic is modular arithmetic that wraps around. No -operation raises @code{Program_Error}, since all operations make sense. - -@geindex Unchecked conversion - -@node RM 13 9 14-17 Unchecked Conversion,RM 13 11 23-25 Implicit Heap Usage,RM 13 7 1 16 Address Operations,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235} -@section RM 13.9(14-17): Unchecked Conversion - - -@quotation - -“The @code{Size} of an array object should not include its bounds; hence, -the bounds should not be part of the converted data.” -@end quotation - -Followed. - -@quotation - -“The implementation should not generate unnecessary run-time checks to -ensure that the representation of @code{S} is a representation of the -target type. It should take advantage of the permission to return by -reference when possible. Restrictions on unchecked conversions should be -avoided unless required by the target environment.” -@end quotation - -Followed. There are no restrictions on unchecked conversion. A warning is -generated if the source and target types do not have the same size since -the semantics in this case may be target dependent. - -@quotation - -“The recommended level of support for unchecked conversions is: - -Unchecked conversions should be supported and should be reversible in -the cases where this clause defines the result. To enable meaningful use -of unchecked conversion, a contiguous representation should be used for -elementary subtypes, for statically constrained array subtypes whose -component subtype is one of the subtypes described in this paragraph, -and for record subtypes without discriminants whose component subtypes -are described in this paragraph.” -@end quotation - -Followed. - -@geindex Heap usage -@geindex implicit - -@node RM 13 11 23-25 Implicit Heap Usage,RM 13 11 2 17 Unchecked Deallocation,RM 13 9 14-17 Unchecked Conversion,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236} -@section RM 13.11(23-25): Implicit Heap Usage - - -@quotation - -“An implementation should document any cases in which it dynamically -allocates heap storage for a purpose other than the evaluation of an -allocator.” -@end quotation - -Followed, the only other points at which heap storage is dynamically -allocated are as follows: - - -@itemize * - -@item -At initial elaboration time, to allocate dynamically sized global -objects. - -@item -To allocate space for a task when a task is created. - -@item -To extend the secondary stack dynamically when needed. The secondary -stack is used for returning variable length results. -@end itemize - - -@quotation - -“A default (implementation-provided) storage pool for an -access-to-constant type should not have overhead to support deallocation of -individual objects.” -@end quotation - -Followed. - -@quotation - -“A storage pool for an anonymous access type should be created at the -point of an allocator for the type, and be reclaimed when the designated -object becomes inaccessible.” -@end quotation - -Followed. - -@geindex Unchecked deallocation - -@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237} -@section RM 13.11.2(17): Unchecked Deallocation - - -@quotation - -“For a standard storage pool, @code{Free} should actually reclaim the -storage.” -@end quotation - -Followed. - -@geindex Stream oriented attributes - -@node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238} -@section RM 13.13.2(1.6): Stream Oriented Attributes - - -@quotation - -“If not specified, the value of Stream_Size for an elementary type -should be the number of bits that corresponds to the minimum number of -stream elements required by the first subtype of the type, rounded up -to the nearest factor or multiple of the word size that is also a -multiple of the stream element size.” -@end quotation - -Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. -The Stream_Size may be used to override the default choice. - -The default implementation is based on direct binary representations and is -therefore target- and endianness-dependent. To address this issue, GNAT also -supplies an alternate implementation of the stream attributes @code{Read} and -@code{Write}, which uses the target-independent XDR standard representation for -scalar types. This XDR alternative can be enabled via the binder switch -xdr. - -@geindex XDR representation - -@geindex Read attribute - -@geindex Write attribute - -@geindex Stream oriented attributes - -@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239} -@section RM A.1(52): Names of Predefined Numeric Types - - -@quotation - -“If an implementation provides additional named predefined integer types, -then the names should end with @code{Integer} as in -@code{Long_Integer}. If an implementation provides additional named -predefined floating point types, then the names should end with -@code{Float} as in @code{Long_Float}.” -@end quotation - -Followed. - -@geindex Ada.Characters.Handling - -@node RM A 3 2 49 Ada Characters Handling,RM A 4 4 106 Bounded-Length String Handling,RM A 1 52 Names of Predefined Numeric Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a} -@section RM A.3.2(49): @code{Ada.Characters.Handling} - - -@quotation - -“If an implementation provides a localized definition of @code{Character} -or @code{Wide_Character}, then the effects of the subprograms in -@code{Characters.Handling} should reflect the localizations. -See also 3.5.2.” -@end quotation - -Followed. GNAT provides no such localized definitions. - -@geindex Bounded-length strings - -@node RM A 4 4 106 Bounded-Length String Handling,RM A 5 2 46-47 Random Number Generation,RM A 3 2 49 Ada Characters Handling,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b} -@section RM A.4.4(106): Bounded-Length String Handling - - -@quotation - -“Bounded string objects should not be implemented by implicit pointers -and dynamic allocation.” -@end quotation - -Followed. No implicit pointers or dynamic allocation are used. - -@geindex Random number generation - -@node RM A 5 2 46-47 Random Number Generation,RM A 10 7 23 Get_Immediate,RM A 4 4 106 Bounded-Length String Handling,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c} -@section RM A.5.2(46-47): Random Number Generation - - -@quotation - -“Any storage associated with an object of type @code{Generator} should be -reclaimed on exit from the scope of the object.” -@end quotation - -Followed. - -@quotation - -“If the generator period is sufficiently long in relation to the number -of distinct initiator values, then each possible value of -@code{Initiator} passed to @code{Reset} should initiate a sequence of -random numbers that does not, in a practical sense, overlap the sequence -initiated by any other value. If this is not possible, then the mapping -between initiator values and generator states should be a rapidly -varying function of the initiator value.” -@end quotation - -Followed. The generator period is sufficiently long for the first -condition here to hold true. - -@geindex Get_Immediate - -@node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d} -@section RM A.10.7(23): @code{Get_Immediate} - - -@quotation - -“The @code{Get_Immediate} procedures should be implemented with -unbuffered input. For a device such as a keyboard, input should be -available if a key has already been typed, whereas for a disk -file, input should always be available except at end of file. For a file -associated with a keyboard-like device, any line-editing features of the -underlying operating system should be disabled during the execution of -@code{Get_Immediate}.” -@end quotation - -Followed on all targets except VxWorks. For VxWorks, there is no way to -provide this functionality that does not result in the input buffer being -flushed before the @code{Get_Immediate} call. A special unit -@code{Interfaces.Vxworks.IO} is provided that contains routines to enable -this functionality. - -@geindex Containers - -@node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e} -@section RM A.18: @code{Containers} - - -All implementation advice pertaining to Ada.Containers and its -child units (that is, all implementation advice occurring within -section A.18 and its subsections) is followed except for A.18.24(17): - -@quotation - -“Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ -@end quotation - -The implementations of the two Reference_Preserving_Key functions of -the generic package Ada.Containers.Bounded_Ordered_Sets each currently make -use of dynamic allocation; other operations on bounded ordered set objects -follow the implementation advice. - -@geindex Export - -@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f} -@section RM B.1(39-41): Pragma @code{Export} - - -@quotation - -“If an implementation supports pragma @code{Export} to a given language, -then it should also allow the main subprogram to be written in that -language. It should support some mechanism for invoking the elaboration -of the Ada library units included in the system, and for invoking the -finalization of the environment task. On typical systems, the -recommended mechanism is to provide two subprograms whose link names are -@code{adainit} and @code{adafinal}. @code{adainit} should contain the -elaboration code for library units. @code{adafinal} should contain the -finalization code. These subprograms should have no effect the second -and subsequent time they are called.” -@end quotation - -Followed. - -@quotation - -“Automatic elaboration of pre-elaborated packages should be -provided when pragma @code{Export} is supported.” -@end quotation - -Followed when the main program is in Ada. If the main program is in a -foreign language, then -@code{adainit} must be called to elaborate pre-elaborated -packages. - -@quotation - -“For each supported convention `L' other than @code{Intrinsic}, an -implementation should support @code{Import} and @code{Export} pragmas -for objects of `L'-compatible types and for subprograms, and pragma -@cite{Convention} for `L'-eligible types and for subprograms, -presuming the other language has corresponding features. Pragma -@code{Convention} need not be supported for scalar types.” -@end quotation - -Followed. - -@geindex Package Interfaces - -@geindex Interfaces - -@node RM B 2 12-13 Package Interfaces,RM B 3 63-71 Interfacing with C,RM B 1 39-41 Pragma Export,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{240} -@section RM B.2(12-13): Package @code{Interfaces} - - -@quotation - -“For each implementation-defined convention identifier, there should be a -child package of package Interfaces with the corresponding name. This -package should contain any declarations that would be useful for -interfacing to the language (implementation) represented by the -convention. Any declarations useful for interfacing to any language on -the given hardware architecture should be provided directly in -@code{Interfaces}.” -@end quotation - -Followed. - -@quotation - -“An implementation supporting an interface to C, COBOL, or Fortran should -provide the corresponding package or packages described in the following -clauses.” -@end quotation - -Followed. GNAT provides all the packages described in this section. - -@geindex C -@geindex interfacing with - -@node RM B 3 63-71 Interfacing with C,RM B 4 95-98 Interfacing with COBOL,RM B 2 12-13 Package Interfaces,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{241} -@section RM B.3(63-71): Interfacing with C - - -@quotation - -“An implementation should support the following interface correspondences -between Ada and C.” -@end quotation - -Followed. - -@quotation - -“An Ada procedure corresponds to a void-returning C function.” -@end quotation - -Followed. - -@quotation - -“An Ada function corresponds to a non-void C function.” -@end quotation - -Followed. - -@quotation - -“An Ada @code{in} scalar parameter is passed as a scalar argument to a C -function.” -@end quotation - -Followed. - -@quotation - -“An Ada @code{in} parameter of an access-to-object type with designated -type @code{T} is passed as a @code{t*} argument to a C function, -where @code{t} is the C type corresponding to the Ada type @code{T}.” -@end quotation - -Followed. - -@quotation - -“An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} -parameter of an elementary type @code{T}, is passed as a @code{t*} -argument to a C function, where @code{t} is the C type corresponding to -the Ada type @code{T}. In the case of an elementary @code{out} or -@code{in out} parameter, a pointer to a temporary copy is used to -preserve by-copy semantics.” -@end quotation - -Followed. - -@quotation - -“An Ada parameter of a record type @code{T}, of any mode, is passed as a -@code{t*} argument to a C function, where @code{t} is the C -structure corresponding to the Ada type @code{T}.” -@end quotation - -Followed. This convention may be overridden by the use of the C_Pass_By_Copy -pragma, or Convention, or by explicitly specifying the mechanism for a given -call using an extended import or export pragma. - -@quotation - -“An Ada parameter of an array type with component type @code{T}, of any -mode, is passed as a @code{t*} argument to a C function, where -@code{t} is the C type corresponding to the Ada type @code{T}.” -@end quotation - -Followed. - -@quotation - -“An Ada parameter of an access-to-subprogram type is passed as a pointer -to a C function whose prototype corresponds to the designated -subprogram’s specification.” -@end quotation - -Followed. - -@geindex COBOL -@geindex interfacing with - -@node RM B 4 95-98 Interfacing with COBOL,RM B 5 22-26 Interfacing with Fortran,RM B 3 63-71 Interfacing with C,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{242} -@section RM B.4(95-98): Interfacing with COBOL - - -@quotation - -“An Ada implementation should support the following interface -correspondences between Ada and COBOL.” -@end quotation - -Followed. - -@quotation - -“An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of -the COBOL type corresponding to @code{T}.” -@end quotation - -Followed. - -@quotation - -“An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of -the corresponding COBOL type.” -@end quotation - -Followed. - -@quotation - -“Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the -COBOL type corresponding to the Ada parameter type; for scalars, a local -copy is used if necessary to ensure by-copy semantics.” -@end quotation - -Followed. - -@geindex Fortran -@geindex interfacing with - -@node RM B 5 22-26 Interfacing with Fortran,RM C 1 3-5 Access to Machine Operations,RM B 4 95-98 Interfacing with COBOL,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{243} -@section RM B.5(22-26): Interfacing with Fortran - - -@quotation - -“An Ada implementation should support the following interface -correspondences between Ada and Fortran:” -@end quotation - -Followed. - -@quotation - -“An Ada procedure corresponds to a Fortran subroutine.” -@end quotation - -Followed. - -@quotation - -“An Ada function corresponds to a Fortran function.” -@end quotation - -Followed. - -@quotation - -“An Ada parameter of an elementary, array, or record type @code{T} is -passed as a @code{T} argument to a Fortran procedure, where @code{T} is -the Fortran type corresponding to the Ada type @code{T}, and where the -INTENT attribute of the corresponding dummy argument matches the Ada -formal parameter mode; the Fortran implementation’s parameter passing -conventions are used. For elementary types, a local copy is used if -necessary to ensure by-copy semantics.” -@end quotation - -Followed. - -@quotation - -“An Ada parameter of an access-to-subprogram type is passed as a -reference to a Fortran procedure whose interface corresponds to the -designated subprogram’s specification.” -@end quotation - -Followed. - -@geindex Machine operations - -@node RM C 1 3-5 Access to Machine Operations,RM C 1 10-16 Access to Machine Operations,RM B 5 22-26 Interfacing with Fortran,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{244} -@section RM C.1(3-5): Access to Machine Operations - - -@quotation - -“The machine code or intrinsic support should allow access to all -operations normally available to assembly language programmers for the -target environment, including privileged instructions, if any.” -@end quotation - -Followed. - -@quotation - -“The interfacing pragmas (see Annex B) should support interface to -assembler; the default assembler should be associated with the -convention identifier @code{Assembler}.” -@end quotation - -Followed. - -@quotation - -“If an entity is exported to assembly language, then the implementation -should allocate it at an addressable location, and should ensure that it -is retained by the linking process, even if not otherwise referenced -from the Ada code. The implementation should assume that any call to a -machine code or assembler subprogram is allowed to read or update every -object that is specified as exported.” -@end quotation - -Followed. - -@node RM C 1 10-16 Access to Machine Operations,RM C 3 28 Interrupt Support,RM C 1 3-5 Access to Machine Operations,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{245} -@section RM C.1(10-16): Access to Machine Operations - - -@quotation - -“The implementation should ensure that little or no overhead is -associated with calling intrinsic and machine-code subprograms.” -@end quotation - -Followed for both intrinsics and machine-code subprograms. - -@quotation - -“It is recommended that intrinsic subprograms be provided for convenient -access to any machine operations that provide special capabilities or -efficiency and that are not otherwise available through the language -constructs.” -@end quotation - -Followed. A full set of machine operation intrinsic subprograms is provided. - -@quotation - -“Atomic read-modify-write operations—e.g., test and set, compare and -swap, decrement and test, enqueue/dequeue.” -@end quotation - -Followed on any target supporting such operations. - -@quotation - -“Standard numeric functions—e.g.:, sin, log.” -@end quotation - -Followed on any target supporting such operations. - -@quotation - -“String manipulation operations—e.g.:, translate and test.” -@end quotation - -Followed on any target supporting such operations. - -@quotation - -“Vector operations—e.g.:, compare vector against thresholds.” -@end quotation - -Followed on any target supporting such operations. - -@quotation - -“Direct operations on I/O ports.” -@end quotation - -Followed on any target supporting such operations. - -@geindex Interrupt support - -@node RM C 3 28 Interrupt Support,RM C 3 1 20-21 Protected Procedure Handlers,RM C 1 10-16 Access to Machine Operations,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{246} -@section RM C.3(28): Interrupt Support - - -@quotation - -“If the @code{Ceiling_Locking} policy is not in effect, the -implementation should provide means for the application to specify which -interrupts are to be blocked during protected actions, if the underlying -system allows for a finer-grain control of interrupt blocking.” -@end quotation - -Followed. The underlying system does not allow for finer-grain control -of interrupt blocking. - -@geindex Protected procedure handlers - -@node RM C 3 1 20-21 Protected Procedure Handlers,RM C 3 2 25 Package Interrupts,RM C 3 28 Interrupt Support,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{247} -@section RM C.3.1(20-21): Protected Procedure Handlers - - -@quotation - -“Whenever possible, the implementation should allow interrupt handlers to -be called directly by the hardware.” -@end quotation - -Followed on any target where the underlying operating system permits -such direct calls. - -@quotation - -“Whenever practical, violations of any -implementation-defined restrictions should be detected before run time.” -@end quotation - -Followed. Compile time warnings are given when possible. - -@geindex Package `@w{`}Interrupts`@w{`} - -@geindex Interrupts - -@node RM C 3 2 25 Package Interrupts,RM C 4 14 Pre-elaboration Requirements,RM C 3 1 20-21 Protected Procedure Handlers,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{248} -@section RM C.3.2(25): Package @code{Interrupts} - - -@quotation - -“If implementation-defined forms of interrupt handler procedures are -supported, such as protected procedures with parameters, then for each -such form of a handler, a type analogous to @code{Parameterless_Handler} -should be specified in a child package of @code{Interrupts}, with the -same operations as in the predefined package Interrupts.” -@end quotation - -Followed. - -@geindex Pre-elaboration requirements - -@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{249} -@section RM C.4(14): Pre-elaboration Requirements - - -@quotation - -“It is recommended that pre-elaborated packages be implemented in such a -way that there should be little or no code executed at run time for the -elaboration of entities not already covered by the Implementation -Requirements.” -@end quotation - -Followed. Executable code is generated in some cases, e.g., loops -to initialize large arrays. - -@node RM C 5 8 Pragma Discard_Names,RM C 7 2 30 The Package Task_Attributes,RM C 4 14 Pre-elaboration Requirements,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{24a} -@section RM C.5(8): Pragma @code{Discard_Names} - - -@quotation - -“If the pragma applies to an entity, then the implementation should -reduce the amount of storage used for storing names associated with that -entity.” -@end quotation - -Followed. - -@geindex Package Task_Attributes - -@geindex Task_Attributes - -@node RM C 7 2 30 The Package Task_Attributes,RM D 3 17 Locking Policies,RM C 5 8 Pragma Discard_Names,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24b} -@section RM C.7.2(30): The Package Task_Attributes - - -@quotation - -“Some implementations are targeted to domains in which memory use at run -time must be completely deterministic. For such implementations, it is -recommended that the storage for task attributes will be pre-allocated -statically and not from the heap. This can be accomplished by either -placing restrictions on the number and the size of the task’s -attributes, or by using the pre-allocated storage for the first @code{N} -attribute objects, and the heap for the others. In the latter case, -@code{N} should be documented.” -@end quotation - -Not followed. This implementation is not targeted to such a domain. - -@geindex Locking Policies - -@node RM D 3 17 Locking Policies,RM D 4 16 Entry Queuing Policies,RM C 7 2 30 The Package Task_Attributes,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24c} -@section RM D.3(17): Locking Policies - - -@quotation - -“The implementation should use names that end with @code{_Locking} for -locking policies defined by the implementation.” -@end quotation - -Followed. Two implementation-defined locking policies are defined, -whose names (@code{Inheritance_Locking} and -@code{Concurrent_Readers_Locking}) follow this suggestion. - -@geindex Entry queuing policies - -@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24d} -@section RM D.4(16): Entry Queuing Policies - - -@quotation - -“Names that end with @code{_Queuing} should be used -for all implementation-defined queuing policies.” -@end quotation - -Followed. No such implementation-defined queuing policies exist. - -@geindex Preemptive abort - -@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24e} -@section RM D.6(9-10): Preemptive Abort - - -@quotation - -“Even though the `abort_statement' is included in the list of -potentially blocking operations (see 9.5.1), it is recommended that this -statement be implemented in a way that never requires the task executing -the `abort_statement' to block.” -@end quotation - -Followed. - -@quotation - -“On a multi-processor, the delay associated with aborting a task on -another processor should be bounded; the implementation should use -periodic polling, if necessary, to achieve this.” -@end quotation - -Followed. - -@geindex Tasking restrictions - -@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24f} -@section RM D.7(21): Tasking Restrictions - - -@quotation - -“When feasible, the implementation should take advantage of the specified -restrictions to produce a more efficient implementation.” -@end quotation - -GNAT currently takes advantage of these restrictions by providing an optimized -run time when the Ravenscar profile and the GNAT restricted run time set -of restrictions are specified. See pragma @code{Profile (Ravenscar)} and -pragma @code{Profile (Restricted)} for more details. - -@geindex Time -@geindex monotonic - -@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{250} -@section RM D.8(47-49): Monotonic Time - - -@quotation - -“When appropriate, implementations should provide configuration -mechanisms to change the value of @code{Tick}.” -@end quotation - -Such configuration mechanisms are not appropriate to this implementation -and are thus not supported. - -@quotation - -“It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} -be implemented as transformations of the same time base.” -@end quotation - -Followed. - -@quotation - -“It is recommended that the best time base which exists in -the underlying system be available to the application through -@code{Clock}. @cite{Best} may mean highest accuracy or largest range.” -@end quotation - -Followed. - -@geindex Partition communication subsystem - -@geindex PCS - -@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{251} -@section RM E.5(28-29): Partition Communication Subsystem - - -@quotation - -“Whenever possible, the PCS on the called partition should allow for -multiple tasks to call the RPC-receiver with different messages and -should allow them to block until the corresponding subprogram body -returns.” -@end quotation - -Followed by GLADE, a separately supplied PCS that can be used with -GNAT. - -@quotation - -“The @code{Write} operation on a stream of type @code{Params_Stream_Type} -should raise @code{Storage_Error} if it runs out of space trying to -write the @code{Item} into the stream.” -@end quotation - -Followed by GLADE, a separately supplied PCS that can be used with -GNAT. - -@geindex COBOL support - -@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{252} -@section RM F(7): COBOL Support - - -@quotation - -“If COBOL (respectively, C) is widely supported in the target -environment, implementations supporting the Information Systems Annex -should provide the child package @code{Interfaces.COBOL} (respectively, -@code{Interfaces.C}) specified in Annex B and should support a -@code{convention_identifier} of COBOL (respectively, C) in the interfacing -pragmas (see Annex B), thus allowing Ada programs to interface with -programs written in that language.” -@end quotation - -Followed. - -@geindex Decimal radix support - -@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{253} -@section RM F.1(2): Decimal Radix Support - - -@quotation - -“Packed decimal should be used as the internal representation for objects -of subtype @code{S} when @code{S}’Machine_Radix = 10.” -@end quotation - -Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary -representations. - -@geindex Numerics - -@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{254} -@section RM G: Numerics - - -@quotation - -“If Fortran (respectively, C) is widely supported in the target -environment, implementations supporting the Numerics Annex -should provide the child package @code{Interfaces.Fortran} (respectively, -@code{Interfaces.C}) specified in Annex B and should support a -@code{convention_identifier} of Fortran (respectively, C) in the interfacing -pragmas (see Annex B), thus allowing Ada programs to interface with -programs written in that language.” -@end quotation - -Followed. - -@geindex Complex types - -@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{255} -@section RM G.1.1(56-58): Complex Types - - -@quotation - -“Because the usual mathematical meaning of multiplication of a complex -operand and a real operand is that of the scaling of both components of -the former by the latter, an implementation should not perform this -operation by first promoting the real operand to complex type and then -performing a full complex multiplication. In systems that, in the -future, support an Ada binding to IEC 559:1989, the latter technique -will not generate the required result when one of the components of the -complex operand is infinite. (Explicit multiplication of the infinite -component by the zero component obtained during promotion yields a NaN -that propagates into the final result.) Analogous advice applies in the -case of multiplication of a complex operand and a pure-imaginary -operand, and in the case of division of a complex operand by a real or -pure-imaginary operand.” -@end quotation - -Not followed. - -@quotation - -“Similarly, because the usual mathematical meaning of addition of a -complex operand and a real operand is that the imaginary operand remains -unchanged, an implementation should not perform this operation by first -promoting the real operand to complex type and then performing a full -complex addition. In implementations in which the @code{Signed_Zeros} -attribute of the component type is @code{True} (and which therefore -conform to IEC 559:1989 in regard to the handling of the sign of zero in -predefined arithmetic operations), the latter technique will not -generate the required result when the imaginary component of the complex -operand is a negatively signed zero. (Explicit addition of the negative -zero to the zero obtained during promotion yields a positive zero.) -Analogous advice applies in the case of addition of a complex operand -and a pure-imaginary operand, and in the case of subtraction of a -complex operand and a real or pure-imaginary operand.” -@end quotation - -Not followed. - -@quotation - -“Implementations in which @code{Real'Signed_Zeros} is @code{True} should -attempt to provide a rational treatment of the signs of zero results and -result components. As one example, the result of the @code{Argument} -function should have the sign of the imaginary component of the -parameter @code{X} when the point represented by that parameter lies on -the positive real axis; as another, the sign of the imaginary component -of the @code{Compose_From_Polar} function should be the same as -(respectively, the opposite of) that of the @code{Argument} parameter when that -parameter has a value of zero and the @code{Modulus} parameter has a -nonnegative (respectively, negative) value.” -@end quotation - -Followed. - -@geindex Complex elementary functions - -@node RM G 1 2 49 Complex Elementary Functions,RM G 2 4 19 Accuracy Requirements,RM G 1 1 56-58 Complex Types,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{256} -@section RM G.1.2(49): Complex Elementary Functions - - -@quotation - -“Implementations in which @code{Complex_Types.Real'Signed_Zeros} is -@code{True} should attempt to provide a rational treatment of the signs -of zero results and result components. For example, many of the complex -elementary functions have components that are odd functions of one of -the parameter components; in these cases, the result component should -have the sign of the parameter component at the origin. Other complex -elementary functions have zero components whose sign is opposite that of -a parameter component at the origin, or is always positive or always -negative.” -@end quotation - -Followed. - -@geindex Accuracy requirements - -@node RM G 2 4 19 Accuracy Requirements,RM G 2 6 15 Complex Arithmetic Accuracy,RM G 1 2 49 Complex Elementary Functions,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{257} -@section RM G.2.4(19): Accuracy Requirements - - -@quotation - -“The versions of the forward trigonometric functions without a -@code{Cycle} parameter should not be implemented by calling the -corresponding version with a @code{Cycle} parameter of -@code{2.0*Numerics.Pi}, since this will not provide the required -accuracy in some portions of the domain. For the same reason, the -version of @code{Log} without a @code{Base} parameter should not be -implemented by calling the corresponding version with a @code{Base} -parameter of @code{Numerics.e}.” -@end quotation - -Followed. - -@geindex Complex arithmetic accuracy - -@geindex Accuracy -@geindex complex arithmetic - -@node RM G 2 6 15 Complex Arithmetic Accuracy,RM H 6 15/2 Pragma Partition_Elaboration_Policy,RM G 2 4 19 Accuracy Requirements,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{258} -@section RM G.2.6(15): Complex Arithmetic Accuracy - - -@quotation - -“The version of the @code{Compose_From_Polar} function without a -@code{Cycle} parameter should not be implemented by calling the -corresponding version with a @code{Cycle} parameter of -@code{2.0*Numerics.Pi}, since this will not provide the required -accuracy in some portions of the domain.” -@end quotation - -Followed. - -@geindex Sequential elaboration policy - -@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice -@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{259} -@section RM H.6(15/2): Pragma Partition_Elaboration_Policy - - -@quotation - -“If the partition elaboration policy is @code{Sequential} and the -Environment task becomes permanently blocked during elaboration then the -partition is deadlocked and it is recommended that the partition be -immediately terminated.” -@end quotation - -Not followed. - -@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top -@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{25a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25b}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b} -@chapter Implementation Defined Characteristics - - -In addition to the implementation dependent pragmas and attributes, and the -implementation advice, there are a number of other Ada features that are -potentially implementation dependent and are designated as -implementation-defined. These are mentioned throughout the Ada Reference -Manual, and are summarized in Annex M. - -A requirement for conforming Ada compilers is that they provide -documentation describing how the implementation deals with each of these -issues. In this chapter you will find each point in Annex M listed, -followed by a description of how GNAT handles the implementation dependence. - -You can use this chapter as a guide to minimizing implementation -dependent features in your programs if portability to other compilers -and other operating systems is an important consideration. The numbers -in each entry below correspond to the paragraph numbers in the Ada -Reference Manual. - - -@itemize * - -@item -“Whether or not each recommendation given in Implementation -Advice is followed. See 1.1.2(37).” -@end itemize - -See @ref{a,,Implementation Advice}. - - -@itemize * - -@item -“Capacity limitations of the implementation. See 1.1.3(3).” -@end itemize - -The complexity of programs that can be processed is limited only by the -total amount of available virtual memory, and disk space for the -generated object files. - - -@itemize * - -@item -“Variations from the standard that are impractical to avoid -given the implementation’s execution environment. See 1.1.3(6).” -@end itemize - -There are no variations from the standard. - - -@itemize * - -@item -“Which code_statements cause external -interactions. See 1.1.3(10).” -@end itemize - -Any `code_statement' can potentially cause external interactions. - - -@itemize * - -@item -“The coded representation for the text of an Ada -program. See 2.1(4).” -@end itemize - -See separate section on source representation. - - -@itemize * - -@item -“The semantics of an Ada program whose text is not in -Normalization Form C. See 2.1(4).” -@end itemize - -See separate section on source representation. - - -@itemize * - -@item -“The representation for an end of line. See 2.2(2).” -@end itemize - -See separate section on source representation. - - -@itemize * - -@item -“Maximum supported line length and lexical element -length. See 2.2(15).” -@end itemize - -The maximum line length is 255 characters and the maximum length of -a lexical element is also 255 characters. This is the default setting -if not overridden by the use of compiler switch `-gnaty' (which -sets the maximum to 79) or `-gnatyMnn' which allows the maximum -line length to be specified to be any value up to 32767. The maximum -length of a lexical element is the same as the maximum line length. - - -@itemize * - -@item -“Implementation defined pragmas. See 2.8(14).” -@end itemize - -See @ref{7,,Implementation Defined Pragmas}. - - -@itemize * - -@item -“Effect of pragma @code{Optimize}. See 2.8(27).” -@end itemize - -Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} -parameter, checks that the optimization flag is set, and aborts if it is -not. - - -@itemize * - -@item -“The message string associated with the Assertion_Error exception raised -by the failure of a predicate check if there is no applicable -Predicate_Failure aspect. See 3.2.4(31).” -@end itemize - -In the case of a Dynamic_Predicate aspect, the string is -“Dynamic_Predicate failed at ”, where -“” might be something like “foo.adb:123”. -The Static_Predicate case is handled analogously. - - -@itemize * - -@item -“The predefined integer types declared in -@code{Standard}. See 3.5.4(25).” -@end itemize - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Type - -@tab - -Representation - -@item - -`Short_Short_Integer' - -@tab - -8-bit signed - -@item - -`Short_Integer' - -@tab - -16-bit signed - -@item - -`Integer' - -@tab - -32-bit signed - -@item - -`Long_Integer' - -@tab - -64-bit signed (on most 64-bit targets, -depending on the C definition of long) -32-bit signed (on all other targets) - -@item - -`Long_Long_Integer' - -@tab - -64-bit signed - -@item - -`Long_Long_Long_Integer' - -@tab - -128-bit signed (on 64-bit targets) -64-bit signed (on 32-bit targets) - -@end multitable - - - -@itemize * - -@item -“Any nonstandard integer types and the operators defined -for them. See 3.5.4(26).” -@end itemize - -There are no nonstandard integer types. - - -@itemize * - -@item -“Any nonstandard real types and the operators defined for -them. See 3.5.6(8).” -@end itemize - -There are no nonstandard real types. - - -@itemize * - -@item -“What combinations of requested decimal precision and range -are supported for floating point types. See 3.5.7(7).” -@end itemize - -The precision and range are defined by the IEEE Standard for Floating-Point -Arithmetic (IEEE 754-2019). - - -@itemize * - -@item -“The predefined floating point types declared in -@code{Standard}. See 3.5.7(16).” -@end itemize - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Type - -@tab - -Representation - -@item - -`Short_Float' - -@tab - -IEEE Binary32 (Single) - -@item - -`Float' - -@tab - -IEEE Binary32 (Single) - -@item - -`Long_Float' - -@tab - -IEEE Binary64 (Double) - -@item - -`Long_Long_Float' - -@tab - -IEEE Binary64 (Double) on non-x86 architectures -IEEE 80-bit Extended on x86 architecture - -@end multitable - - -The default rounding mode specified by the IEEE 754 Standard is assumed both -for static and dynamic computations (that is, round to nearest, ties to even). -The input routines yield correctly rounded values for Short_Float, Float, and -Long_Float at least. The output routines can compute up to twice as many exact -digits as the value of @code{T'Digits} for any type, for example 30 digits for -Long_Float; if more digits are requested, zeros are printed. - - -@itemize * - -@item -“The small of an ordinary fixed point type. See 3.5.9(8).” -@end itemize - -The small is the largest power of two that does not exceed the delta. - - -@itemize * - -@item -“What combinations of small, range, and digits are -supported for fixed point types. See 3.5.9(10).” -@end itemize - -For an ordinary fixed point type, on 32-bit platforms, the small must lie in -2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination -is permitted that does not result in a mantissa larger than 63 bits. - -On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the -range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not -result in a mantissa larger than 63 bits, and any combination is permitted -that results in a mantissa between 64 and 127 bits if the small is the -ratio of two integers that lie in 1 .. 2.0**127. - -If the small is the ratio of two integers with 64-bit magnitude on 32-bit -platforms and 128-bit magnitude on 64-bit platforms, which is the case if -no @code{small} clause is provided, then the operations of the fixed point -type are entirely implemented by means of integer instructions. In the -other cases, some operations, in particular input and output, may be -implemented by means of floating-point instructions and may be affected -by accuracy issues on architectures other than x86. - -For a decimal fixed point type, on 32-bit platforms, the small must lie in -1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the -small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. - - -@itemize * - -@item -“The result of @code{Tags.Expanded_Name} for types declared -within an unnamed `block_statement'. See 3.9(10).” -@end itemize - -Block numbers of the form @code{B@var{nnn}}, where `nnn' is a -decimal integer are allocated. - - -@itemize * - -@item -“The sequence of characters of the value returned by Tags.Expanded_Name -(respectively, Tags.Wide_Expanded_Name) when some of the graphic -characters of Tags.Wide_Wide_Expanded_Name are not defined in Character -(respectively, Wide_Character). See 3.9(10.1).” -@end itemize - -This is handled in the same way as the implementation-defined behavior -referenced in A.4.12(34). - - -@itemize * - -@item -“Implementation-defined attributes. See 4.1.4(12).” -@end itemize - -See @ref{8,,Implementation Defined Attributes}. - - -@itemize * - -@item -“The value of the parameter to Empty for some container aggregates. -See 4.3.5(40).” -@end itemize - -As per the suggestion given in the Annotated Ada RM, the default value -of the formal parameter is used if one exists and zero is used otherwise. - - -@itemize * - -@item -“The maximum number of chunks for a parallel reduction expression without -a chunk_specification. See 4.5.10(21).” -@end itemize - -Feature unimplemented. - - -@itemize * - -@item -“Rounding of real static expressions which are exactly half-way between -two machine numbers. See 4.9(38).” -@end itemize - -Round to even is used in all such cases. - - -@itemize * - -@item -“The maximum number of chunks for a parallel generalized iterator without -a chunk_specification. See 5.5.2(10).” -@end itemize - -Feature unimplemented. - - -@itemize * - -@item -“The number of chunks for an array component iterator. See 5.5.2(11).” -@end itemize - -Feature unimplemented. - - -@itemize * - -@item -“Any extensions of the Global aspect. See 6.1.2(43).” -@end itemize - -Feature unimplemented. - - -@itemize * - -@item -“The circumstances the implementation passes in the null value for a view -conversion of an access type used as an out parameter. See 6.4.1(19).” -@end itemize - -Difficult to characterize. - - -@itemize * - -@item -“Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” -@end itemize - -SPARK allows specifying `null' as the Default_Initial_Condition -aspect of a type. See the SPARK reference manual for further details. - - -@itemize * - -@item -“Any implementation-defined time types. See 9.6(6).” -@end itemize - -There are no implementation-defined time types. - - -@itemize * - -@item -“The time base associated with relative delays. See 9.6(20).” -@end itemize - -See 9.6(20). The time base used is that provided by the C library -function @code{gettimeofday}. - - -@itemize * - -@item -“The time base of the type @code{Calendar.Time}. See 9.6(23).” -@end itemize - -The time base used is that provided by the C library function -@code{gettimeofday}. - - -@itemize * - -@item -“The time zone used for package @code{Calendar} -operations. See 9.6(24).” -@end itemize - -The time zone used by package @code{Calendar} is the current system time zone -setting for local time, as accessed by the C library function -@code{localtime}. - - -@itemize * - -@item -“Any limit on `delay_until_statements' of -`select_statements'. See 9.6(29).” -@end itemize - -There are no such limits. - - -@itemize * - -@item -“The result of Calendar.Formatting.Image if its argument represents more -than 100 hours. See 9.6.1(86).” -@end itemize - -Calendar.Time_Error is raised. - - -@itemize * - -@item -“Implementation-defined conflict check policies. See 9.10.1(5).” -@end itemize - -There are no implementation-defined conflict check policies. - - -@itemize * - -@item -“The representation for a compilation. See 10.1(2).” -@end itemize - -A compilation is represented by a sequence of files presented to the -compiler in a single invocation of the `gcc' command. - - -@itemize * - -@item -“Any restrictions on compilations that contain multiple -compilation_units. See 10.1(4).” -@end itemize - -No single file can contain more than one compilation unit, but any -sequence of files can be presented to the compiler as a single -compilation. - - -@itemize * - -@item -“The mechanisms for creating an environment and for adding -and replacing compilation units. See 10.1.4(3).” -@end itemize - -See separate section on compilation model. - - -@itemize * - -@item -“The manner of explicitly assigning library units to a -partition. See 10.2(2).” -@end itemize - -If a unit contains an Ada main program, then the Ada units for the partition -are determined by recursive application of the rules in the Ada Reference -Manual section 10.2(2-6). In other words, the Ada units will be those that -are needed by the main program, and then this definition of need is applied -recursively to those units, and the partition contains the transitive -closure determined by this relationship. In short, all the necessary units -are included, with no need to explicitly specify the list. If additional -units are required, e.g., by foreign language units, then all units must be -mentioned in the context clause of one of the needed Ada units. - -If the partition contains no main program, or if the main program is in -a language other than Ada, then GNAT -provides the binder options `-z' and `-n' respectively, and in -this case a list of units can be explicitly supplied to the binder for -inclusion in the partition (all units needed by these units will also -be included automatically). For full details on the use of these -options, refer to `GNAT Make Program gnatmake' in the -@cite{GNAT User’s Guide}. - - -@itemize * - -@item -“The implementation-defined means, if any, of specifying which compilation -units are needed by a given compilation unit. See 10.2(2).” -@end itemize - -The units needed by a given compilation unit are as defined in -the Ada Reference Manual section 10.2(2-6). There are no -implementation-defined pragmas or other implementation-defined -means for specifying needed units. - - -@itemize * - -@item -“The manner of designating the main subprogram of a -partition. See 10.2(7).” -@end itemize - -The main program is designated by providing the name of the -corresponding @code{ALI} file as the input parameter to the binder. - - -@itemize * - -@item -“The order of elaboration of `library_items'. See 10.2(18).” -@end itemize - -The first constraint on ordering is that it meets the requirements of -Chapter 10 of the Ada Reference Manual. This still leaves some -implementation-dependent choices, which are resolved by analyzing -the elaboration code of each unit and identifying implicit -elaboration-order dependencies. - - -@itemize * - -@item -“Parameter passing and function return for the main -subprogram. See 10.2(21).” -@end itemize - -The main program has no parameters. It may be a procedure, or a function -returning an integer type. In the latter case, the returned integer -value is the return code of the program (overriding any value that -may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). - - -@itemize * - -@item -“The mechanisms for building and running partitions. See 10.2(24).” -@end itemize - -GNAT itself supports programs with only a single partition. The GNATDIST -tool provided with the GLADE package (which also includes an implementation -of the PCS) provides a completely flexible method for building and running -programs consisting of multiple partitions. See the separate GLADE manual -for details. - - -@itemize * - -@item -“The details of program execution, including program -termination. See 10.2(25).” -@end itemize - -See separate section on compilation model. - - -@itemize * - -@item -“The semantics of any non-active partitions supported by the -implementation. See 10.2(28).” -@end itemize - -Passive partitions are supported on targets where shared memory is -provided by the operating system. See the GLADE reference manual for -further details. - - -@itemize * - -@item -“The information returned by @code{Exception_Message}. See 11.4.1(10).” -@end itemize - -Exception message returns the null string unless a specific message has -been passed by the program. - - -@itemize * - -@item -“The result of @code{Exceptions.Exception_Name} for types -declared within an unnamed `block_statement'. See 11.4.1(12).” -@end itemize - -Blocks have implementation defined names of the form @code{B@var{nnn}} -where `nnn' is an integer. - - -@itemize * - -@item -“The information returned by -@code{Exception_Information}. See 11.4.1(13).” -@end itemize - -@code{Exception_Information} returns a string in the following format: - -@example -*Exception_Name:* nnnnn -*Message:* mmmmm -*PID:* ppp -*Load address:* 0xhhhh -*Call stack traceback locations:* -0xhhhh 0xhhhh 0xhhhh ... 0xhhh -@end example - -where - -@quotation - - -@itemize * - -@item -@code{nnnn} is the fully qualified name of the exception in all upper -case letters. This line is always present. - -@item -@code{mmmm} is the message (this line present only if message is non-null) - -@item -@code{ppp} is the Process Id value as a decimal integer (this line is -present only if the Process Id is nonzero). Currently we are -not making use of this field. - -@item -The Load address line, the Call stack traceback locations line and the -following values are present only if at least one traceback location was -recorded. The Load address indicates the address at which the main executable -was loaded; this line may not be present if operating system hasn’t relocated -the main executable. The values are given in C style format, with lower case -letters for a-f, and only as many digits present as are necessary. -The line terminator sequence at the end of each line, including -the last line is a single @code{LF} character (@code{16#0A#}). -@end itemize -@end quotation - - -@itemize * - -@item -“The sequence of characters of the value returned by -Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) -when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name -are not defined in Character (respectively, Wide_Character). -See 11.4.1(12.1).” -@end itemize - -This is handled in the same way as the implementation-defined behavior -referenced in A.4.12(34). - - -@itemize * - -@item -“The information returned by Exception_Information. See 11.4.1(13).” -@end itemize - -The exception name and the source location at which the exception was -raised are included. - - -@itemize * - -@item -“Implementation-defined policy_identifiers and assertion_aspect_marks -allowed in a pragma Assertion_Policy. See 11.4.2(9).” -@end itemize - -Implementation-defined assertion_aspect_marks include Assert_And_Cut, -Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, -Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, -Statement_Assertions, and Subprogram_Variant. Implementation-defined -policy_identifiers include Ignore and Suppressible. - - -@itemize * - -@item -“The default assertion policy. See 11.4.2(10).” -@end itemize - -The default assertion policy is Ignore, although this can be overridden -via compiler switches such as “-gnata”. - - -@itemize * - -@item -“Implementation-defined check names. See 11.5(27).” -@end itemize - -The implementation defined check names include Alignment_Check, -Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, -Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user -program can add implementation-defined check names by means of the pragma -Check_Name. See the description of pragma @code{Suppress} for full details. - - -@itemize * - -@item -“Existence and meaning of second parameter of pragma Unsuppress. -See 11.5(27.1).” -@end itemize - -The legality rules for and semantics of the second parameter of pragma -Unsuppress match those for the second argument of pragma Suppress. - - -@itemize * - -@item -“The cases that cause conflicts between the representation of the -ancestors of a type_declaration. See 13.1(13.1).” -@end itemize - -No such cases exist. - - -@itemize * - -@item -“The interpretation of each representation aspect. See 13.1(20).” -@end itemize - -See separate section on data representations. - - -@itemize * - -@item -“Any restrictions placed upon the specification of representation aspects. -See 13.1(20).” -@end itemize - -See separate section on data representations. - - -@itemize * - -@item -“Implementation-defined aspects, including the syntax for specifying -such aspects and the legality rules for such aspects. See 13.1.1(38).” -@end itemize - -See @ref{120,,Implementation Defined Aspects}. - - -@itemize * - -@item -“The set of machine scalars. See 13.3(8.1).” -@end itemize - -See separate section on data representations. - - -@itemize * - -@item -“The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” -@end itemize - -The Size attribute of an indefinite subtype is not less than the Size -attribute of any object of that type. - - -@itemize * - -@item -“The meaning of Object_Size for indefinite subtypes. See 13.3(58).” -@end itemize - -The Object_Size attribute of an indefinite subtype is not less than the -Object_Size attribute of any object of that type. - - -@itemize * - -@item -“The default external representation for a type tag. See 13.3(75).” -@end itemize - -The default external representation for a type tag is the fully expanded -name of the type in upper case letters. - - -@itemize * - -@item -“What determines whether a compilation unit is the same in -two different partitions. See 13.3(76).” -@end itemize - -A compilation unit is the same in two different partitions if and only -if it derives from the same source file. - - -@itemize * - -@item -“Implementation-defined components. See 13.5.1(15).” -@end itemize - -The only implementation defined component is the tag for a tagged type, -which contains a pointer to the dispatching table. - - -@itemize * - -@item -“If @code{Word_Size} = @code{Storage_Unit}, the default bit -ordering. See 13.5.3(5).” -@end itemize - -@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this -implementation, so no non-default bit ordering is supported. The default -bit ordering corresponds to the natural endianness of the target architecture. - - -@itemize * - -@item -“The contents of the visible part of package @code{System}. See 13.7(2).” -@end itemize - -See the definition of package System in @code{system.ads}. -Note that two declarations are added to package System. - -@example -Max_Priority : constant Positive := Priority'Last; -Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; -@end example - - -@itemize * - -@item -“The range of Storage_Elements.Storage_Offset, the modulus of -Storage_Elements.Storage_Element, and the declaration of -Storage_Elements.Integer_Address. See 13.7.1(11).” -@end itemize - -See the definition of package System.Storage_Elements in @code{s-stoele.ads}. - - -@itemize * - -@item -“The contents of the visible part of package @code{System.Machine_Code}, -and the meaning of `code_statements'. See 13.8(7).” -@end itemize - -See the definition and documentation in file @code{s-maccod.ads}. - - -@itemize * - -@item -“The result of unchecked conversion for instances with scalar result -types whose result is not defined by the language. See 13.9(11).” -@end itemize - -Unchecked conversion between types of the same size -results in an uninterpreted transmission of the bits from one type -to the other. If the types are of unequal sizes, then in the case of -discrete types, a shorter source is first zero or sign extended as -necessary, and a shorter target is simply truncated on the left. -For all non-discrete types, the source is first copied if necessary -to ensure that the alignment requirements of the target are met, then -a pointer is constructed to the source value, and the result is obtained -by dereferencing this pointer after converting it to be a pointer to the -target type. Unchecked conversions where the target subtype is an -unconstrained array are not permitted. If the target alignment is -greater than the source alignment, then a copy of the result is -made with appropriate alignment - - -@itemize * - -@item -“The result of unchecked conversion for instances with nonscalar result -types whose result is not defined by the language. See 13.9(11).” -@end itemize - -See preceding definition for the scalar result case. - - -@itemize * - -@item -“Whether or not the implementation provides user-accessible -names for the standard pool type(s). See 13.11(17).” -@end itemize - -There are 3 different standard pools used by the compiler when -@code{Storage_Pool} is not specified depending whether the type is local -to a subprogram or defined at the library level and whether -@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime -library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and -@code{System.Pool_Local} in files @code{s-poosiz.ads}, -@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the -default pools used. All these pools are accessible by means of @cite{with}ing -these units. - - -@itemize * - -@item -“The meaning of @code{Storage_Size} when neither the Storage_Size nor the -Storage_Pool is specified for an access type. See 13.11(18).” -@end itemize - -@code{Storage_Size} is measured in storage units, and refers to the -total space available for an access type collection, or to the primary -stack space for a task. - - -@itemize * - -@item -“The effect of specifying aspect Default_Storage_Pool on an instance -of a language-defined generic unit. See 13.11.3(5).” -@end itemize - -Instances of language-defined generic units are treated the same as other -instances with respect to the Default_Storage_Pool aspect. - - -@itemize * - -@item -“Implementation-defined restrictions allowed in a pragma -@code{Restrictions}. See 13.12(8.7).” -@end itemize - -See @ref{9,,Standard and Implementation Defined Restrictions}. - - -@itemize * - -@item -“The consequences of violating limitations on -@code{Restrictions} pragmas. See 13.12(9).” -@end itemize - -Restrictions that can be checked at compile time are enforced at -compile time; violations are illegal. For other restrictions, any -violation during program execution results in erroneous execution. - - -@itemize * - -@item -“Implementation-defined usage profiles allowed in a pragma Profile. -See 13.12(15).” -@end itemize - -See @ref{7,,Implementation Defined Pragmas}. - - -@itemize * - -@item -“The contents of the stream elements read and written by the Read and -Write attributes of elementary types. See 13.13.2(9).” -@end itemize - -The representation is the in-memory representation of the base type of -the type, using the number of bits corresponding to the -@code{type'Size} value, and the natural ordering of the machine. - - -@itemize * - -@item -“The names and characteristics of the numeric subtypes -declared in the visible part of package @code{Standard}. See A.1(3).” -@end itemize - -See items describing the integer and floating-point types supported. - - -@itemize * - -@item -“The values returned by Strings.Hash. See A.4.9(3).” -@end itemize - -This hash function has predictable collisions and is subject to -equivalent substring attacks. It is not suitable for construction of a -hash table keyed on possibly malicious user input. - - -@itemize * - -@item -“The value returned by a call to a Text_Buffer Get procedure if any -character in the returned sequence is not defined in Character. -See A.4.12(34).” -@end itemize - -The contents of a buffer is represented internally as a UTF_8 string. -The value return by Text_Buffer.Get is the result of passing that -UTF_8 string to UTF_Encoding.Strings.Decode. - - -@itemize * - -@item -“The value returned by a call to a Text_Buffer Wide_Get procedure if -any character in the returned sequence is not defined in Wide_Character. -See A.4.12(34).” -@end itemize - -The contents of a buffer is represented internally as a UTF_8 string. -The value return by Text_Buffer.Wide_Get is the result of passing that -UTF_8 string to UTF_Encoding.Wide_Strings.Decode. - - -@itemize * - -@item -“The accuracy actually achieved by the elementary -functions. See A.5.1(1).” -@end itemize - -The elementary functions correspond to the functions available in the C -library. Only fast math mode is implemented. - - -@itemize * - -@item -“The sign of a zero result from some of the operators or -functions in @code{Numerics.Generic_Elementary_Functions}, when -@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” -@end itemize - -The sign of zeroes follows the requirements of the IEEE 754 standard on -floating-point. - - -@itemize * - -@item -“The value of -@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” -@end itemize - -Maximum image width is 6864, see library file @code{s-rannum.ads}. - - -@itemize * - -@item -“The value of -@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” -@end itemize - -Maximum image width is 6864, see library file @code{s-rannum.ads}. - - -@itemize * - -@item -“The string representation of a random number generator’s -state. See A.5.2(38).” -@end itemize - -The value returned by the Image function is the concatenation of -the fixed-width decimal representations of the 624 32-bit integers -of the state vector. - - -@itemize * - -@item -“The values of the @code{Model_Mantissa}, -@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, -@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics -Annex is not supported. See A.5.3(72).” -@end itemize - -Running the compiler with `-gnatS' to produce a listing of package -@code{Standard} displays the values of these attributes. - - -@itemize * - -@item -“The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” -@end itemize - -All type representations are contiguous, and the @code{Buffer_Size} is -the value of @code{type'Size} rounded up to the next storage unit -boundary. - - -@itemize * - -@item -“External files for standard input, standard output, and -standard error See A.10(5).” -@end itemize - -These files are mapped onto the files provided by the C streams -libraries. See source file @code{i-cstrea.ads} for further details. - - -@itemize * - -@item -“The accuracy of the value produced by @code{Put}. See A.10.9(36).” -@end itemize - -If more digits are requested in the output than are represented by the -precision of the value, zeroes are output in the corresponding least -significant digit positions. - - -@itemize * - -@item -“Current size for a stream file for which positioning is not supported. -See A.12.1(1.1).” -@end itemize - -Positioning is supported. - - -@itemize * - -@item -“The meaning of @code{Argument_Count}, @code{Argument}, and -@code{Command_Name}. See A.15(1).” -@end itemize - -These are mapped onto the @code{argv} and @code{argc} parameters of the -main program in the natural manner. - - -@itemize * - -@item -“The interpretation of file names and directory names. See A.16(46).” -@end itemize - -These names are interpreted consistently with the underlying file system. - - -@itemize * - -@item -“The maxium value for a file size in Directories. See A.16(87).” -@end itemize - -Directories.File_Size’Last is equal to Long_Long_Integer’Last . - - -@itemize * - -@item -“The result for Directories.Size for a directory or special file. -See A.16(93).” -@end itemize - -Name_Error is raised. - - -@itemize * - -@item -“The result for Directories.Modification_Time for a directory or special file. -See A.16(93).” -@end itemize - -Name_Error is raised. - - -@itemize * - -@item -“The interpretation of a nonnull search pattern in Directories. -See A.16(104).” -@end itemize - -When the @code{Pattern} parameter is not the null string, it is interpreted -according to the syntax of regular expressions as defined in the -@code{GNAT.Regexp} package. - -See @ref{25c,,GNAT.Regexp (g-regexp.ads)}. - - -@itemize * - -@item -“The results of a Directories search if the contents of the directory are -altered while a search is in progress. See A.16(110).” -@end itemize - -The effect of a call to Get_Next_Entry is determined by the current -state of the directory. - - -@itemize * - -@item -“The definition and meaning of an environment variable. See A.17(1).” -@end itemize - -This definition is determined by the underlying operating system. - - -@itemize * - -@item -“The circumstances where an environment variable cannot be defined. -See A.17(16).” - -There are no such implementation-defined circumstances. - -@item -“Environment names for which Set has the effect of Clear. See A.17(17).” -@end itemize - -There are no such names. - - -@itemize * - -@item -“The value of Containers.Hash_Type’Modulus. The value of -Containers.Count_Type’Last. See A.18.1(7).” -@end itemize - -Containers.Hash_Type’Modulus is 2**32. -Containers.Count_Type’Last is 2**31 - 1. - - -@itemize * - -@item -“Implementation-defined convention names. See B.1(11).” -@end itemize - -The following convention names are supported - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Convention Name - -@tab - -Interpretation - -@item - -`Ada' - -@tab - -Ada - -@item - -`Ada_Pass_By_Copy' - -@tab - -Allowed for any types except by-reference types such as limited -records. Compatible with convention Ada, but causes any parameters -with this convention to be passed by copy. - -@item - -`Ada_Pass_By_Reference' - -@tab - -Allowed for any types except by-copy types such as scalars. -Compatible with convention Ada, but causes any parameters -with this convention to be passed by reference. - -@item - -`Assembler' - -@tab - -Assembly language - -@item - -`Asm' - -@tab - -Synonym for Assembler - -@item - -`Assembly' - -@tab - -Synonym for Assembler - -@item - -`C' - -@tab - -C - -@item - -`C_Pass_By_Copy' - -@tab - -Allowed only for record types, like C, but also notes that record -is to be passed by copy rather than reference. - -@item - -`COBOL' - -@tab - -COBOL - -@item - -`C_Plus_Plus (or CPP)' - -@tab - -C++ - -@item - -`Default' - -@tab - -Treated the same as C - -@item - -`External' - -@tab - -Treated the same as C - -@item - -`Fortran' - -@tab - -Fortran - -@item - -`Intrinsic' - -@tab - -For support of pragma @code{Import} with convention Intrinsic, see -separate section on Intrinsic Subprograms. - -@item - -`Stdcall' - -@tab - -Stdcall (used for Windows implementations only). This convention correspond -to the WINAPI (previously called Pascal convention) C/C++ convention under -Windows. A routine with this convention cleans the stack before -exit. This pragma cannot be applied to a dispatching call. - -@item - -`DLL' - -@tab - -Synonym for Stdcall - -@item - -`Win32' - -@tab - -Synonym for Stdcall - -@item - -`Stubbed' - -@tab - -Stubbed is a special convention used to indicate that the body of the -subprogram will be entirely ignored. Any call to the subprogram -is converted into a raise of the @code{Program_Error} exception. If a -pragma @code{Import} specifies convention @code{stubbed} then no body need -be present at all. This convention is useful during development for the -inclusion of subprograms whose body has not yet been written. -In addition, all otherwise unrecognized convention names are also -treated as being synonymous with convention C. In all implementations, -use of such other names results in a warning. - -@end multitable - - - -@itemize * - -@item -“The meaning of link names. See B.1(36).” -@end itemize - -Link names are the actual names used by the linker. - - -@itemize * - -@item -“The manner of choosing link names when neither the link name nor the -address of an imported or exported entity is specified. See B.1(36).” -@end itemize - -The default linker name is that which would be assigned by the relevant -external language, interpreting the Ada name as being in all lower case -letters. - - -@itemize * - -@item -“The effect of pragma @code{Linker_Options}. See B.1(37).” -@end itemize - -The string passed to @code{Linker_Options} is presented uninterpreted as -an argument to the link command, unless it contains ASCII.NUL characters. -NUL characters if they appear act as argument separators, so for example - -@example -pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); -@end example - -causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the -linker. The order of linker options is preserved for a given unit. The final -list of options passed to the linker is in reverse order of the elaboration -order. For example, linker options for a body always appear before the options -from the corresponding package spec. - - -@itemize * - -@item -“The contents of the visible part of package -@code{Interfaces} and its language-defined descendants. See B.2(1).” -@end itemize - -See files with prefix @code{i-} in the distributed library. - - -@itemize * - -@item -“Implementation-defined children of package -@code{Interfaces}. The contents of the visible part of package -@code{Interfaces}. See B.2(11).” -@end itemize - -See files with prefix @code{i-} in the distributed library. - - -@itemize * - -@item -“The definitions of certain types and constants in Interfaces.C. -See B.3(41).” -@end itemize - -See source file @code{i-c.ads}. - - -@itemize * - -@item -“The types @code{Floating}, @code{Long_Floating}, -@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and -@code{COBOL_Character}; and the initialization of the variables -@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in -@code{Interfaces.COBOL}. See B.4(50).” -@end itemize - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem - -COBOL - -@tab - -Ada - -@item - -`Floating' - -@tab - -Float - -@item - -`Long_Floating' - -@tab - -(Floating) Long_Float - -@item - -`Binary' - -@tab - -Integer - -@item - -`Long_Binary' - -@tab - -Long_Long_Integer - -@item - -`Decimal_Element' - -@tab - -Character - -@item - -`COBOL_Character' - -@tab - -Character - -@end multitable - - -For initialization, see the file @code{i-cobol.ads} in the distributed library. - - -@itemize * - -@item -“The types Fortran_Integer, Real, Double_Precision, and Character_Set -in Interfaces.Fortran. See B.5(17).” -@end itemize - -See source file @code{i-fortra.ads}. These types are derived, respectively, -from Integer, Float, Long_Float, and Character. - - -@itemize * - -@item -“Implementation-defined intrinsic subprograms. See C.1(1).” -@end itemize - -See separate section on Intrinsic Subprograms. - - -@itemize * - -@item -“Any restrictions on a protected procedure or its containing type when an -aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” -@end itemize - -There are no such restrictions. - - -@itemize * - -@item -“Any other forms of interrupt handler supported by the Attach_Handler and -Interrupt_Handler aspects. See C.3.1(19).” -@end itemize - -There are no such forms. - - -@itemize * - -@item -“The semantics of some attributes and functions of an entity for which -aspect Discard_Names is True. See C.5(7).” -@end itemize - -If Discard_Names is True for an enumeration type, the Image attribute -provides the image of the Pos of the literal, and Value accepts -Pos values. - -If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true -for a tagged type, its Expanded_Name and External_Tag values are -empty strings. This is useful to avoid exposing entity names at binary -level. - - -@itemize * - -@item -“The modulus and size of Test_and_Set_Flag. See C.6.3(8).” -@end itemize - -The modulus is 2**8. The size is 8. - - -@itemize * - -@item -“The value used to represent the set value for Atomic_Test_and_Set. -See C.6.3(10).” -@end itemize - -The value is 1. - - -@itemize * - -@item -“The result of the @code{Task_Identification.Image} -attribute. See C.7.1(7).” -@end itemize - -The result of this attribute is a string that identifies -the object or component that denotes a given task. If a variable @code{Var} -has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, -where the suffix `XXXXXXXX' -is the hexadecimal representation of the virtual address of the corresponding -task control block. If the variable is an array of tasks, the image of each -task will have the form of an indexed component indicating the position of a -given task in the array, e.g., @code{Group(5)_@var{XXXXXXX}}. If the task is a -component of a record, the image of the task will have the form of a selected -component. These rules are fully recursive, so that the image of a task that -is a subcomponent of a composite object corresponds to the expression that -designates this task. - -If a task is created by an allocator, its image depends on the context. If the -allocator is part of an object declaration, the rules described above are used -to construct its image, and this image is not affected by subsequent -assignments. If the allocator appears within an expression, the image -includes only the name of the task type. - -If the configuration pragma Discard_Names is present, or if the restriction -No_Implicit_Heap_Allocation is in effect, the image reduces to -the numeric suffix, that is to say the hexadecimal representation of the -virtual address of the control block of the task. - - -@itemize * - -@item -“The value of @code{Current_Task} when in a protected entry -or interrupt handler. See C.7.1(17).” -@end itemize - -Protected entries or interrupt handlers can be executed by any -convenient thread, so the value of @code{Current_Task} is undefined. - - -@itemize * - -@item -“Granularity of locking for Task_Attributes. See C.7.2(16).” -@end itemize - -No locking is needed if the formal type Attribute has the size and -alignment of either Integer or System.Address and the bit representation -of Initial_Value is all zeroes. Otherwise, locking is performed. - - -@itemize * - -@item -“The declarations of @code{Any_Priority} and -@code{Priority}. See D.1(11).” -@end itemize - -See declarations in file @code{system.ads}. - - -@itemize * - -@item -“Implementation-defined execution resources. See D.1(15).” -@end itemize - -There are no implementation-defined execution resources. - - -@itemize * - -@item -“Whether, on a multiprocessor, a task that is waiting for -access to a protected object keeps its processor busy. See D.2.1(3).” -@end itemize - -On a multi-processor, a task that is waiting for access to a protected -object does not keep its processor busy. - - -@itemize * - -@item -“The affect of implementation defined execution resources -on task dispatching. See D.2.1(9).” -@end itemize - -Tasks map to threads in the threads package used by GNAT. Where possible -and appropriate, these threads correspond to native threads of the -underlying operating system. - - -@itemize * - -@item -“Implementation-defined task dispatching policies. See D.2.2(3).” -@end itemize - -There are no implementation-defined task dispatching policies. - - -@itemize * - -@item -“The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” -@end itemize - -The value is 10 milliseconds. - - -@itemize * - -@item -“Implementation-defined `policy_identifiers' allowed -in a pragma @code{Locking_Policy}. See D.3(4).” -@end itemize - -The two implementation defined policies permitted in GNAT are -@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On -targets that support the @code{Inheritance_Locking} policy, locking is -implemented by inheritance, i.e., the task owning the lock operates -at a priority equal to the highest priority of any task currently -requesting the lock. On targets that support the -@code{Concurrent_Readers_Locking} policy, locking is implemented with a -read/write lock allowing multiple protected object functions to enter -concurrently. - - -@itemize * - -@item -“Default ceiling priorities. See D.3(10).” -@end itemize - -The ceiling priority of protected objects of the type -@code{System.Interrupt_Priority'Last} as described in the Ada -Reference Manual D.3(10), - - -@itemize * - -@item -“The ceiling of any protected object used internally by -the implementation. See D.3(16).” -@end itemize - -The ceiling priority of internal protected objects is -@code{System.Priority'Last}. - - -@itemize * - -@item -“Implementation-defined queuing policies. See D.4(1).” -@end itemize - -There are no implementation-defined queuing policies. - - -@itemize * - -@item -“Implementation-defined admission policies. See D.4.1(1).” -@end itemize - -There are no implementation-defined admission policies. - - -@itemize * - -@item -“Any operations that implicitly require heap storage -allocation. See D.7(8).” -@end itemize - -The only operation that implicitly requires heap storage allocation is -task creation. - - -@itemize * - -@item -“When restriction No_Dynamic_CPU_Assignment applies to a partition, the -processor on which a task with a CPU value of a Not_A_Specific_CPU will -execute. See D.7(10).” -@end itemize - -Unknown. - - -@itemize * - -@item -“When restriction No_Task_Termination applies to a partition, what happens -when a task terminates. See D.7(15.1).” -@end itemize - -Execution is erroneous in that case. - - -@itemize * - -@item -“The behavior when restriction Max_Storage_At_Blocking is violated. -See D.7(17).” -@end itemize - -Execution is erroneous in that case. - - -@itemize * - -@item -“The behavior when restriction Max_Asynchronous_Select_Nesting is violated. -See D.7(18).” -@end itemize - -Execution is erroneous in that case. - - -@itemize * - -@item -“The behavior when restriction Max_Tasks is violated. See D.7(19).” -@end itemize - -Execution is erroneous in that case. - - -@itemize * - -@item -“Whether the use of pragma Restrictions results in a reduction in program -code or data size or execution time. See D.7(20).” - -Yes it can, but the precise circumstances and properties of such reductions -are difficult to characterize. - -@item -“The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” -@end itemize - -Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . - - -@itemize * - -@item -“When an aborted task that is waiting on a Synchronous_Barrier is aborted. -See D.10.1(13).” -@end itemize - -Difficult to characterize. - - -@itemize * - -@item -“The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. -See D.14.2(7).” -@end itemize - -See source file @code{a-etgrbu.ads}. - - -@itemize * - -@item -“The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” -@end itemize - -See source file @code{s-multip.ads}. - - -@itemize * - -@item -“The processor on which the environment task executes in the absence -of a value for the aspect CPU. See D.16(13).” -@end itemize - -Unknown. - - -@itemize * - -@item -“The means for creating and executing distributed -programs. See E(5).” -@end itemize - -The GLADE package provides a utility GNATDIST for creating and executing -distributed programs. See the GLADE reference manual for further details. - - -@itemize * - -@item -“Any events that can result in a partition becoming -inaccessible. See E.1(7).” -@end itemize - -See the GLADE reference manual for full details on such events. - - -@itemize * - -@item -“The scheduling policies, treatment of priorities, and management of -shared resources between partitions in certain cases. See E.1(11).” -@end itemize - -See the GLADE reference manual for full details on these aspects of -multi-partition execution. - - -@itemize * - -@item -“Whether the execution of the remote subprogram is -immediately aborted as a result of cancellation. See E.4(13).” -@end itemize - -See the GLADE reference manual for details on the effect of abort in -a distributed application. - - -@itemize * - -@item -“The range of type System.RPC.Partition_Id. See E.5(14).” -@end itemize - -System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. - - -@itemize * - -@item -“Implementation-defined interfaces in the PCS. See E.5(26).” -@end itemize - -See the GLADE reference manual for a full description of all -implementation defined interfaces. - - -@itemize * - -@item -“The values of named numbers in the package -@code{Decimal}. See F.2(7).” -@end itemize - - -@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} -@headitem - -Named Number - -@tab - -Value - -@item - -`Max_Scale' - -@tab - -+18 - -@item - -`Min_Scale' - -@tab - --18 - -@item - -`Min_Delta' - -@tab - -1.0E-18 - -@item - -`Max_Delta' - -@tab - -1.0E+18 - -@item - -`Max_Decimal_Digits' - -@tab - -18 - -@end multitable - - - -@itemize * - -@item -“The value of @code{Max_Picture_Length} in the package -@code{Text_IO.Editing}. See F.3.3(16).” - -64 - -@item -“The value of @code{Max_Picture_Length} in the package -@code{Wide_Text_IO.Editing}. See F.3.4(5).” - -64 - -@item -“The accuracy actually achieved by the complex elementary -functions and by other complex arithmetic operations. See G.1(1).” -@end itemize - -Standard library functions are used for the complex arithmetic -operations. Only fast math mode is currently supported. - - -@itemize * - -@item -“The sign of a zero result (or a component thereof) from -any operator or function in @code{Numerics.Generic_Complex_Types}, when -@code{Real'Signed_Zeros} is True. See G.1.1(53).” -@end itemize - -The signs of zero values are as recommended by the relevant -implementation advice. - - -@itemize * - -@item -“The sign of a zero result (or a component thereof) from -any operator or function in -@code{Numerics.Generic_Complex_Elementary_Functions}, when -@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” -@end itemize - -The signs of zero values are as recommended by the relevant -implementation advice. - - -@itemize * - -@item -“Whether the strict mode or the relaxed mode is the -default. See G.2(2).” -@end itemize - -The strict mode is the default. There is no separate relaxed mode. GNAT -provides a highly efficient implementation of strict mode. - - -@itemize * - -@item -“The result interval in certain cases of fixed-to-float -conversion. See G.2.1(10).” -@end itemize - -For cases where the result interval is implementation dependent, the -accuracy is that provided by performing all operations in 64-bit IEEE -floating-point format. - - -@itemize * - -@item -“The result of a floating point arithmetic operation in -overflow situations, when the @code{Machine_Overflows} attribute of the -result type is @code{False}. See G.2.1(13).” -@end itemize - -Infinite and NaN values are produced as dictated by the IEEE -floating-point standard. -Note that on machines that are not fully compliant with the IEEE -floating-point standard, such as Alpha, the `-mieee' compiler flag -must be used for achieving IEEE conforming behavior (although at the cost -of a significant performance penalty), so infinite and NaN values are -properly generated. - - -@itemize * - -@item -“The result interval for division (or exponentiation by a -negative exponent), when the floating point hardware implements division -as multiplication by a reciprocal. See G.2.1(16).” -@end itemize - -Not relevant, division is IEEE exact. - - -@itemize * - -@item -“The definition of close result set, which determines the accuracy of -certain fixed point multiplications and divisions. See G.2.3(5).” -@end itemize - -Operations in the close result set are performed using IEEE long format -floating-point arithmetic. The input operands are converted to -floating-point, the operation is done in floating-point, and the result -is converted to the target type. - - -@itemize * - -@item -“Conditions on a `universal_real' operand of a fixed -point multiplication or division for which the result shall be in the -perfect result set. See G.2.3(22).” -@end itemize - -The result is only defined to be in the perfect result set if the result -can be computed by a single scaling operation involving a scale factor -representable in 64 bits. - - -@itemize * - -@item -“The result of a fixed point arithmetic operation in -overflow situations, when the @code{Machine_Overflows} attribute of the -result type is @code{False}. See G.2.3(27).” -@end itemize - -Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point -types. - - -@itemize * - -@item -“The result of an elementary function reference in -overflow situations, when the @code{Machine_Overflows} attribute of the -result type is @code{False}. See G.2.4(4).” -@end itemize - -IEEE infinite and Nan values are produced as appropriate. - - -@itemize * - -@item -“The value of the angle threshold, within which certain -elementary functions, complex arithmetic operations, and complex -elementary functions yield results conforming to a maximum relative -error bound. See G.2.4(10).” -@end itemize - -Information on this subject is not yet available. - - -@itemize * - -@item -“The accuracy of certain elementary functions for -parameters beyond the angle threshold. See G.2.4(10).” -@end itemize - -Information on this subject is not yet available. - - -@itemize * - -@item -“The result of a complex arithmetic operation or complex -elementary function reference in overflow situations, when the -@code{Machine_Overflows} attribute of the corresponding real type is -@code{False}. See G.2.6(5).” -@end itemize - -IEEE infinite and Nan values are produced as appropriate. - - -@itemize * - -@item -“The accuracy of certain complex arithmetic operations and -certain complex elementary functions for parameters (or components -thereof) beyond the angle threshold. See G.2.6(8).” -@end itemize - -Information on those subjects is not yet available. - - -@itemize * - -@item -“The accuracy requirements for the subprograms Solve, Inverse, -Determinant, Eigenvalues and Eigensystem for type Real_Matrix. -See G.3.1(81).” -@end itemize - -Information on those subjects is not yet available. - - -@itemize * - -@item -“The accuracy requirements for the subprograms Solve, Inverse, -Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. -See G.3.2(149).” -@end itemize - -Information on those subjects is not yet available. - - -@itemize * - -@item -“The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” -@end itemize - -Execution is erroneous in that case. - -@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top -@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c} -@chapter Intrinsic Subprograms - - -@geindex Intrinsic Subprograms - -GNAT allows a user application program to write the declaration: - -@example -pragma Import (Intrinsic, name); -@end example - -providing that the name corresponds to one of the implemented intrinsic -subprograms in GNAT, and that the parameter profile of the referenced -subprogram meets the requirements. This chapter describes the set of -implemented intrinsic subprograms, and the requirements on parameter profiles. -Note that no body is supplied; as with other uses of pragma Import, the -body is supplied elsewhere (in this case by the compiler itself). Note -that any use of this feature is potentially non-portable, since the -Ada standard does not require Ada compilers to implement this feature. - -@menu -* Intrinsic Operators:: -* Compilation_ISO_Date:: -* Compilation_Date:: -* Compilation_Time:: -* Enclosing_Entity:: -* Exception_Information:: -* Exception_Message:: -* Exception_Name:: -* File:: -* Line:: -* Shifts and Rotates:: -* Source_Location:: - -@end menu - -@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260} -@section Intrinsic Operators - - -@geindex Intrinsic operator - -All the predefined numeric operators in package Standard -in @code{pragma Import (Intrinsic,..)} -declarations. In the binary operator case, the operands must have the same -size. The operand or operands must also be appropriate for -the operator. For example, for addition, the operands must -both be floating-point or both be fixed-point, and the -right operand for @code{"**"} must have a root type of -@code{Standard.Integer'Base}. -You can use an intrinsic operator declaration as in the following example: - -@example -type Int1 is new Integer; -type Int2 is new Integer; - -function "+" (X1 : Int1; X2 : Int2) return Int1; -function "+" (X1 : Int1; X2 : Int2) return Int2; -pragma Import (Intrinsic, "+"); -@end example - -This declaration would permit ‘mixed mode’ arithmetic on items -of the differing types @code{Int1} and @code{Int2}. -It is also possible to specify such operators for private types, if the -full views are appropriate arithmetic types. - -@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262} -@section Compilation_ISO_Date - - -@geindex Compilation_ISO_Date - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of -the current compilation (in local time format YYYY-MM-DD). - -@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264} -@section Compilation_Date - - -@geindex Compilation_Date - -Same as Compilation_ISO_Date, except the string is in the form -MMM DD YYYY. - -@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266} -@section Compilation_Time - - -@geindex Compilation_Time - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.Compilation_Time} to obtain the time of -the current compilation (in local time format HH:MM:SS). - -@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268} -@section Enclosing_Entity - - -@geindex Enclosing_Entity - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of -the current subprogram, package, task, entry, or protected subprogram. - -@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a} -@section Exception_Information - - -@geindex Exception_Information' - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Current_Exception}. The only useful -use of the intrinsic import in this case is the one in this unit, -so an application program should simply call the function -@code{GNAT.Current_Exception.Exception_Information} to obtain -the exception information associated with the current exception. - -@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c} -@section Exception_Message - - -@geindex Exception_Message - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Current_Exception}. The only useful -use of the intrinsic import in this case is the one in this unit, -so an application program should simply call the function -@code{GNAT.Current_Exception.Exception_Message} to obtain -the message associated with the current exception. - -@node Exception_Name,File,Exception_Message,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e} -@section Exception_Name - - -@geindex Exception_Name - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Current_Exception}. The only useful -use of the intrinsic import in this case is the one in this unit, -so an application program should simply call the function -@code{GNAT.Current_Exception.Exception_Name} to obtain -the name of the current exception. - -@node File,Line,Exception_Name,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270} -@section File - - -@geindex File - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.File} to obtain the name of the current -file. - -@node Line,Shifts and Rotates,File,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272} -@section Line - - -@geindex Line - -This intrinsic subprogram is used in the implementation of the -library package @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.Line} to obtain the number of the current -source line. - -@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274} -@section Shifts and Rotates - - -@geindex Shift_Left - -@geindex Shift_Right - -@geindex Shift_Right_Arithmetic - -@geindex Rotate_Left - -@geindex Rotate_Right - -In standard Ada, the shift and rotate functions are available only -for the predefined modular types in package @code{Interfaces}. However, in -GNAT it is possible to define these functions for any integer -type (signed or modular), as in this example: - -@example -function Shift_Left - (Value : T; - Amount : Natural) return T -with Import, Convention => Intrinsic; -@end example - -The function name must be one of -Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or -Rotate_Right. T must be an integer type. T’Size must be -8, 16, 32 or 64 bits; if T is modular, the modulus -must be 2**8, 2**16, 2**32 or 2**64. -The result type must be the same as the type of @code{Value}. -The shift amount must be Natural. -The formal parameter names can be anything. - -A more convenient way of providing these shift operators is to use the -Provide_Shift_Operators pragma, which provides the function declarations and -corresponding pragma Import’s for all five shift functions. For signed types -the semantics of these operators is to interpret the bitwise result of the -corresponding operator for modular type. In particular, shifting a negative -number may change its sign bit to positive. - -@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms -@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276} -@section Source_Location - - -@geindex Source_Location - -This intrinsic subprogram is used in the implementation of the -library routine @code{GNAT.Source_Info}. The only useful use of the -intrinsic import in this case is the one in this unit, so an -application program should simply call the function -@code{GNAT.Source_Info.Source_Location} to obtain the current -source file location. - -@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top -@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d} -@chapter Representation Clauses and Pragmas - - -@geindex Representation Clauses - -@geindex Representation Clause - -@geindex Representation Pragma - -@geindex Pragma -@geindex representation - -This section describes the representation clauses accepted by GNAT, and -their effect on the representation of corresponding data objects. - -GNAT fully implements Annex C (Systems Programming). This means that all -the implementation advice sections in chapter 13 are fully implemented. -However, these sections only require a minimal level of support for -representation clauses. GNAT provides much more extensive capabilities, -and this section describes the additional capabilities provided. - -@menu -* Alignment Clauses:: -* Size Clauses:: -* Storage_Size Clauses:: -* Size of Variant Record Objects:: -* Biased Representation:: -* Value_Size and Object_Size Clauses:: -* Component_Size Clauses:: -* Bit_Order Clauses:: -* Effect of Bit_Order on Byte Ordering:: -* Pragma Pack for Arrays:: -* Pragma Pack for Records:: -* Record Representation Clauses:: -* Handling of Records with Holes:: -* Enumeration Clauses:: -* Address Clauses:: -* Use of Address Clauses for Memory-Mapped I/O:: -* Effect of Convention on Representation:: -* Conventions and Anonymous Access Types:: -* Determining the Representations chosen by GNAT:: - -@end menu - -@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a} -@section Alignment Clauses - - -@geindex Alignment Clause - -GNAT requires that all alignment clauses specify 0 or a power of 2, and -all default alignments are always a power of 2. Specifying 0 is the -same as specifying 1. - -The default alignment values are as follows: - - -@itemize * - -@item -`Elementary Types'. - -For elementary types, the alignment is the minimum of the actual size of -objects of the type divided by @code{Storage_Unit}, -and the maximum alignment supported by the target. -(This maximum alignment is given by the GNAT-specific attribute -@code{Standard'Maximum_Alignment}; see @ref{18c,,Attribute Maximum_Alignment}.) - -@geindex Maximum_Alignment attribute - -For example, for type @code{Long_Float}, the object size is 8 bytes, and the -default alignment will be 8 on any target that supports alignments -this large, but on some targets, the maximum alignment may be smaller -than 8, in which case objects of type @code{Long_Float} will be maximally -aligned. - -@item -`Arrays'. - -For arrays, the alignment is equal to the alignment of the component type -for the normal case where no packing or component size is given. If the -array is packed, and the packing is effective (see separate section on -packed arrays), then the alignment will be either 4, 2, or 1 for long packed -arrays or arrays whose length is not known at compile time, depending on -whether the component size is divisible by 4, 2, or is odd. For short packed -arrays, which are handled internally as modular types, the alignment -will be as described for elementary types, e.g. a packed array of length -31 bits will have an object size of four bytes, and an alignment of 4. - -@item -`Records'. - -For the normal unpacked case, the alignment of a record is equal to -the maximum alignment of any of its components. For tagged records, this -includes the implicit access type used for the tag. If a pragma @code{Pack} -is used and all components are packable (see separate section on pragma -@code{Pack}), then the resulting alignment is 1, unless the layout of the -record makes it profitable to increase it. - -A special case is when: - - -@itemize * - -@item -the size of the record is given explicitly, or a -full record representation clause is given, and - -@item -the size of the record is 2, 4, or 8 bytes. -@end itemize - -In this case, an alignment is chosen to match the -size of the record. For example, if we have: - -@example -type Small is record - A, B : Character; -end record; -for Small'Size use 16; -@end example - -then the default alignment of the record type @code{Small} is 2, not 1. This -leads to more efficient code when the record is treated as a unit, and also -allows the type to specified as @code{Atomic} on architectures requiring -strict alignment. -@end itemize - -An alignment clause may specify a larger alignment than the default value -up to some maximum value dependent on the target (obtainable by using the -attribute reference @code{Standard'Maximum_Alignment}). It may also specify -a smaller alignment than the default value for enumeration, integer and -fixed point types, as well as for record types, for example - -@example -type V is record - A : Integer; -end record; - -for V'alignment use 1; -@end example - -@geindex Alignment -@geindex default - -The default alignment for the type @code{V} is 4, as a result of the -Integer field in the record, but it is permissible, as shown, to -override the default alignment of the record with a smaller value. - -@geindex Alignment -@geindex subtypes - -Note that according to the Ada standard, an alignment clause applies only -to the first named subtype. If additional subtypes are declared, then the -compiler is allowed to choose any alignment it likes, and there is no way -to control this choice. Consider: - -@example -type R is range 1 .. 10_000; -for R'Alignment use 1; -subtype RS is R range 1 .. 1000; -@end example - -The alignment clause specifies an alignment of 1 for the first named subtype -@code{R} but this does not necessarily apply to @code{RS}. When writing -portable Ada code, you should avoid writing code that explicitly or -implicitly relies on the alignment of such subtypes. - -For the GNAT compiler, if an explicit alignment clause is given, this -value is also used for any subsequent subtypes. So for GNAT, in the -above example, you can count on the alignment of @code{RS} being 1. But this -assumption is non-portable, and other compilers may choose different -alignments for the subtype @code{RS}. - -@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c} -@section Size Clauses - - -@geindex Size Clause - -The default size for a type @code{T} is obtainable through the -language-defined attribute @code{T'Size} and also through the -equivalent GNAT-defined attribute @code{T'Value_Size}. -For objects of type @code{T}, GNAT will generally increase the type size -so that the object size (obtainable through the GNAT-defined attribute -@code{T'Object_Size}) -is a multiple of @code{T'Alignment * Storage_Unit}. - -For example: - -@example -type Smallint is range 1 .. 6; - -type Rec is record - Y1 : integer; - Y2 : boolean; -end record; -@end example - -In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, -as specified by the RM rules, -but objects of this type will have a size of 8 -(@code{Smallint'Object_Size} = 8), -since objects by default occupy an integral number -of storage units. On some targets, notably older -versions of the Digital Alpha, the size of stand -alone objects of this type may be 32, reflecting -the inability of the hardware to do byte load/stores. - -Similarly, the size of type @code{Rec} is 40 bits -(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but -the alignment is 4, so objects of this type will have -their size increased to 64 bits so that it is a multiple -of the alignment (in bits). This decision is -in accordance with the specific Implementation Advice in RM 13.3(43): - -@quotation - -“A @code{Size} clause should be supported for an object if the specified -@code{Size} is at least as large as its subtype’s @code{Size}, and corresponds -to a size in storage elements that is a multiple of the object’s -@code{Alignment} (if the @code{Alignment} is nonzero).” -@end quotation - -An explicit size clause may be used to override the default size by -increasing it. For example, if we have: - -@example -type My_Boolean is new Boolean; -for My_Boolean'Size use 32; -@end example - -then values of this type will always be 32-bit long. In the case of discrete -types, the size can be increased up to 64 bits on 32-bit targets and 128 bits -on 64-bit targets, with the effect that the entire specified field is used to -hold the value, sign- or zero-extended as appropriate. If more than 64 bits -or 128 bits resp. is specified, then padding space is allocated after the -value, and a warning is issued that there are unused bits. - -Similarly the size of records and arrays may be increased, and the effect -is to add padding bits after the value. This also causes a warning message -to be generated. - -The largest Size value permitted in GNAT is 2**31-1. Since this is a -Size in bits, this corresponds to an object of size 256 megabytes (minus -one). This limitation is true on all targets. The reason for this -limitation is that it improves the quality of the code in many cases -if it is known that a Size value can be accommodated in an object of -type Integer. - -@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e} -@section Storage_Size Clauses - - -@geindex Storage_Size Clause - -For tasks, the @code{Storage_Size} clause specifies the amount of space -to be allocated for the task stack. This cannot be extended, and if the -stack is exhausted, then @code{Storage_Error} will be raised (if stack -checking is enabled). Use a @code{Storage_Size} attribute definition clause, -or a @code{Storage_Size} pragma in the task definition to set the -appropriate required size. A useful technique is to include in every -task definition a pragma of the form: - -@example -pragma Storage_Size (Default_Stack_Size); -@end example - -Then @code{Default_Stack_Size} can be defined in a global package, and -modified as required. Any tasks requiring stack sizes different from the -default can have an appropriate alternative reference in the pragma. - -You can also use the `-d' binder switch to modify the default stack -size. - -For access types, the @code{Storage_Size} clause specifies the maximum -space available for allocation of objects of the type. If this space is -exceeded then @code{Storage_Error} will be raised by an allocation attempt. -In the case where the access type is declared local to a subprogram, the -use of a @code{Storage_Size} clause triggers automatic use of a special -predefined storage pool (@code{System.Pool_Size}) that ensures that all -space for the pool is automatically reclaimed on exit from the scope in -which the type is declared. - -A special case recognized by the compiler is the specification of a -@code{Storage_Size} of zero for an access type. This means that no -items can be allocated from the pool, and this is recognized at compile -time, and all the overhead normally associated with maintaining a fixed -size storage pool is eliminated. Consider the following example: - -@example -procedure p is - type R is array (Natural) of Character; - type P is access all R; - for P'Storage_Size use 0; - -- Above access type intended only for interfacing purposes - - y : P; - - procedure g (m : P); - pragma Import (C, g); - - -- ... - -begin - -- ... - y := new R; -end; -@end example - -As indicated in this example, these dummy storage pools are often useful in -connection with interfacing where no object will ever be allocated. If you -compile the above example, you get the warning: - -@example -p.adb:16:09: warning: allocation from empty storage pool -p.adb:16:09: warning: Storage_Error will be raised at run time -@end example - -Of course in practice, there will not be any explicit allocators in the -case of such an access declaration. - -@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280} -@section Size of Variant Record Objects - - -@geindex Size -@geindex variant record objects - -@geindex Variant record objects -@geindex size - -In the case of variant record objects, there is a question whether Size gives -information about a particular variant, or the maximum size required -for any variant. Consider the following program - -@example -with Text_IO; use Text_IO; -procedure q is - type R1 (A : Boolean := False) is record - case A is - when True => X : Character; - when False => null; - end case; - end record; - - V1 : R1 (False); - V2 : R1; - -begin - Put_Line (Integer'Image (V1'Size)); - Put_Line (Integer'Image (V2'Size)); -end q; -@end example - -Here we are dealing with a variant record, where the True variant -requires 16 bits, and the False variant requires 8 bits. -In the above example, both V1 and V2 contain the False variant, -which is only 8 bits long. However, the result of running the -program is: - -@example -8 -16 -@end example - -The reason for the difference here is that the discriminant value of -V1 is fixed, and will always be False. It is not possible to assign -a True variant value to V1, therefore 8 bits is sufficient. On the -other hand, in the case of V2, the initial discriminant value is -False (from the default), but it is possible to assign a True -variant value to V2, therefore 16 bits must be allocated for V2 -in the general case, even fewer bits may be needed at any particular -point during the program execution. - -As can be seen from the output of this program, the @code{'Size} -attribute applied to such an object in GNAT gives the actual allocated -size of the variable, which is the largest size of any of the variants. -The Ada Reference Manual is not completely clear on what choice should -be made here, but the GNAT behavior seems most consistent with the -language in the RM. - -In some cases, it may be desirable to obtain the size of the current -variant, rather than the size of the largest variant. This can be -achieved in GNAT by making use of the fact that in the case of a -subprogram parameter, GNAT does indeed return the size of the current -variant (because a subprogram has no way of knowing how much space -is actually allocated for the actual). - -Consider the following modified version of the above program: - -@example -with Text_IO; use Text_IO; -procedure q is - type R1 (A : Boolean := False) is record - case A is - when True => X : Character; - when False => null; - end case; - end record; - - V2 : R1; - - function Size (V : R1) return Integer is - begin - return V'Size; - end Size; - -begin - Put_Line (Integer'Image (V2'Size)); - Put_Line (Integer'Image (Size (V2))); - V2 := (True, 'x'); - Put_Line (Integer'Image (V2'Size)); - Put_Line (Integer'Image (Size (V2))); -end q; -@end example - -The output from this program is - -@example -16 -8 -16 -16 -@end example - -Here we see that while the @code{'Size} attribute always returns -the maximum size, regardless of the current variant value, the -@code{Size} function does indeed return the size of the current -variant value. - -@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282} -@section Biased Representation - - -@geindex Size for biased representation - -@geindex Biased representation - -In the case of scalars with a range starting at other than zero, it is -possible in some cases to specify a size smaller than the default minimum -value, and in such cases, GNAT uses an unsigned biased representation, -in which zero is used to represent the lower bound, and successive values -represent successive values of the type. - -For example, suppose we have the declaration: - -@example -type Small is range -7 .. -4; -for Small'Size use 2; -@end example - -Although the default size of type @code{Small} is 4, the @code{Size} -clause is accepted by GNAT and results in the following representation -scheme: - -@example --7 is represented as 2#00# --6 is represented as 2#01# --5 is represented as 2#10# --4 is represented as 2#11# -@end example - -Biased representation is only used if the specified @code{Size} clause -cannot be accepted in any other manner. These reduced sizes that force -biased representation can be used for all discrete types except for -enumeration types for which a representation clause is given. - -@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{284} -@section Value_Size and Object_Size Clauses - - -@geindex Value_Size - -@geindex Object_Size - -@geindex Size -@geindex of objects - -In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum -number of bits required to hold values of type @code{T}. -Although this interpretation was allowed in Ada 83, it was not required, -and this requirement in practice can cause some significant difficulties. -For example, in most Ada 83 compilers, @code{Natural'Size} was 32. -However, in Ada 95 and Ada 2005, -@code{Natural'Size} is -typically 31. This means that code may change in behavior when moving -from Ada 83 to Ada 95 or Ada 2005. For example, consider: - -@example -type Rec is record - A : Natural; - B : Natural; -end record; - -for Rec use record - A at 0 range 0 .. Natural'Size - 1; - B at 0 range Natural'Size .. 2 * Natural'Size - 1; -end record; -@end example - -In the above code, since the typical size of @code{Natural} objects -is 32 bits and @code{Natural'Size} is 31, the above code can cause -unexpected inefficient packing in Ada 95 and Ada 2005, and in general -there are cases where the fact that the object size can exceed the -size of the type causes surprises. - -To help get around this problem GNAT provides two implementation -defined attributes, @code{Value_Size} and @code{Object_Size}. When -applied to a type, these attributes yield the size of the type -(corresponding to the RM defined size attribute), and the size of -objects of the type respectively. - -The @code{Object_Size} is used for determining the default size of -objects and components. This size value can be referred to using the -@code{Object_Size} attribute. The phrase ‘is used’ here means that it is -the basis of the determination of the size. The backend is free to -pad this up if necessary for efficiency, e.g., an 8-bit stand-alone -character might be stored in 32 bits on a machine with no efficient -byte access instructions such as the Alpha. - -The default rules for the value of @code{Object_Size} for -discrete types are as follows: - - -@itemize * - -@item -The @code{Object_Size} for base subtypes reflect the natural hardware -size in bits (run the compiler with `-gnatS' to find those values -for numeric types). Enumeration types and fixed-point base subtypes have -8, 16, 32, or 64 bits for this size, depending on the range of values -to be stored. - -@item -The @code{Object_Size} of a subtype is the same as the -@code{Object_Size} of -the type from which it is obtained. - -@item -The @code{Object_Size} of a derived base type is copied from the parent -base type, and the @code{Object_Size} of a derived first subtype is copied -from the parent first subtype. -@end itemize - -The @code{Value_Size} attribute -is the (minimum) number of bits required to store a value -of the type. -This value is used to determine how tightly to pack -records or arrays with components of this type, and also affects -the semantics of unchecked conversion (unchecked conversions where -the @code{Value_Size} values differ generate a warning, and are potentially -target dependent). - -The default rules for the value of @code{Value_Size} are as follows: - - -@itemize * - -@item -The @code{Value_Size} for a base subtype is the minimum number of bits -required to store all values of the type (including the sign bit -only if negative values are possible). - -@item -If a subtype statically matches the first subtype of a given type, then it has -by default the same @code{Value_Size} as the first subtype. (This is a -consequence of RM 13.1(14): “if two subtypes statically match, -then their subtype-specific aspects are the same”.) - -@item -All other subtypes have a @code{Value_Size} corresponding to the minimum -number of bits required to store all values of the subtype. For -dynamic bounds, it is assumed that the value can range down or up -to the corresponding bound of the ancestor -@end itemize - -The RM defined attribute @code{Size} corresponds to the -@code{Value_Size} attribute. - -The @code{Size} attribute may be defined for a first-named subtype. This sets -the @code{Value_Size} of -the first-named subtype to the given value, and the -@code{Object_Size} of this first-named subtype to the given value padded up -to an appropriate boundary. It is a consequence of the default rules -above that this @code{Object_Size} will apply to all further subtypes. On the -other hand, @code{Value_Size} is affected only for the first subtype, any -dynamic subtypes obtained from it directly, and any statically matching -subtypes. The @code{Value_Size} of any other static subtypes is not affected. - -@code{Value_Size} and -@code{Object_Size} may be explicitly set for any subtype using -an attribute definition clause. Note that the use of these attributes -can cause the RM 13.1(14) rule to be violated. If two access types -reference aliased objects whose subtypes have differing @code{Object_Size} -values as a result of explicit attribute definition clauses, then it -is illegal to convert from one access subtype to the other. For a more -complete description of this additional legality rule, see the -description of the @code{Object_Size} attribute. - -To get a feel for the difference, consider the following examples (note -that in each case the base is @code{Short_Short_Integer} with a size of 8): - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} -@headitem - -Type or subtype declaration - -@tab - -Object_Size - -@tab - -Value_Size - -@item - -@code{type x1 is range 0 .. 5;} - -@tab - -8 - -@tab - -3 - -@item - -@code{type x2 is range 0 .. 5;} -@code{for x2'size use 12;} - -@tab - -16 - -@tab - -12 - -@item - -@code{subtype x3 is x2 range 0 .. 3;} - -@tab - -16 - -@tab - -2 - -@item - -@code{subtype x4 is x2'base range 0 .. 10;} - -@tab - -8 - -@tab - -4 - -@item - -@code{dynamic : x2'Base range -64 .. +63;} - -@tab - -@tab - -@item - -@code{subtype x5 is x2 range 0 .. dynamic;} - -@tab - -16 - -@tab - -3* - -@item - -@code{subtype x6 is x2'base range 0 .. dynamic;} - -@tab - -8 - -@tab - -7* - -@end multitable - - -Note: the entries marked ‘*’ are not actually specified by the Ada -Reference Manual, which has nothing to say about size in the dynamic -case. What GNAT does is to allocate sufficient bits to accommodate any -possible dynamic values for the bounds at run-time. - -So far, so good, but GNAT has to obey the RM rules, so the question is -under what conditions must the RM @code{Size} be used. -The following is a list -of the occasions on which the RM @code{Size} must be used: - - -@itemize * - -@item -Component size for packed arrays or records - -@item -Value of the attribute @code{Size} for a type - -@item -Warning about sizes not matching for unchecked conversion -@end itemize - -For record types, the @code{Object_Size} is always a multiple of the -alignment of the type (this is true for all types). In some cases the -@code{Value_Size} can be smaller. Consider: - -@example -type R is record - X : Integer; - Y : Character; -end record; -@end example - -On a typical 32-bit architecture, the X component will occupy four bytes -and the Y component will occupy one byte, for a total of 5 bytes. As a -result @code{R'Value_Size} will be 40 (bits) since this is the minimum size -required to store a value of this type. For example, it is permissible -to have a component of type R in an array whose component size is -specified to be 40 bits. - -However, @code{R'Object_Size} will be 64 (bits). The difference is due to -the alignment requirement for objects of the record type. The X -component will require four-byte alignment because that is what type -Integer requires, whereas the Y component, a Character, will only -require 1-byte alignment. Since the alignment required for X is the -greatest of all the components’ alignments, that is the alignment -required for the enclosing record type, i.e., 4 bytes or 32 bits. As -indicated above, the actual object size must be rounded up so that it is -a multiple of the alignment value. Therefore, 40 bits rounded up to the -next multiple of 32 yields 64 bits. - -For all other types, the @code{Object_Size} -and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). -Only @code{Size} may be specified for such types. - -Note that @code{Value_Size} can be used to force biased representation -for a particular subtype. Consider this example: - -@example -type R is (A, B, C, D, E, F); -subtype RAB is R range A .. B; -subtype REF is R range E .. F; -@end example - -By default, @code{RAB} -has a size of 1 (sufficient to accommodate the representation -of @code{A} and @code{B}, 0 and 1), and @code{REF} -has a size of 3 (sufficient to accommodate the representation -of @code{E} and @code{F}, 4 and 5). But if we add the -following @code{Value_Size} attribute definition clause: - -@example -for REF'Value_Size use 1; -@end example - -then biased representation is forced for @code{REF}, -and 0 will represent @code{E} and 1 will represent @code{F}. -A warning is issued when a @code{Value_Size} attribute -definition clause forces biased representation. This -warning can be turned off using @code{-gnatw.B}. - -@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286} -@section Component_Size Clauses - - -@geindex Component_Size Clause - -Normally, the value specified in a component size clause must be consistent -with the subtype of the array component with regard to size and alignment. -In other words, the value specified must be at least equal to the size -of this subtype, and must be a multiple of the alignment value. - -In addition, component size clauses are allowed which cause the array -to be packed, by specifying a smaller value. A first case is for -component size values in the range 1 through 63 on 32-bit targets, -and 1 through 127 on 64-bit targets. The value specified may not -be smaller than the Size of the subtype. GNAT will accurately -honor all packing requests in this range. For example, if we have: - -@example -type r is array (1 .. 8) of Natural; -for r'Component_Size use 31; -@end example - -then the resulting array has a length of 31 bytes (248 bits = 8 * 31). -Of course access to the components of such an array is considerably -less efficient than if the natural component size of 32 is used. -A second case is when the subtype of the component is a record type -padded because of its default alignment. For example, if we have: - -@example -type r is record - i : Integer; - j : Integer; - b : Boolean; -end record; - -type a is array (1 .. 8) of r; -for a'Component_Size use 72; -@end example - -then the resulting array has a length of 72 bytes, instead of 96 bytes -if the alignment of the record (4) was obeyed. - -Note that there is no point in giving both a component size clause -and a pragma Pack for the same array type. if such duplicate -clauses are given, the pragma Pack will be ignored. - -@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288} -@section Bit_Order Clauses - - -@geindex Bit_Order Clause - -@geindex bit ordering - -@geindex ordering -@geindex of bits - -For record subtypes, GNAT permits the specification of the @code{Bit_Order} -attribute. The specification may either correspond to the default bit -order for the target, in which case the specification has no effect and -places no additional restrictions, or it may be for the non-standard -setting (that is the opposite of the default). - -In the case where the non-standard value is specified, the effect is -to renumber bits within each byte, but the ordering of bytes is not -affected. There are certain -restrictions placed on component clauses as follows: - - -@itemize * - -@item -Components fitting within a single storage unit. - -These are unrestricted, and the effect is merely to renumber bits. For -example if we are on a little-endian machine with @code{Low_Order_First} -being the default, then the following two declarations have exactly -the same effect: - -@example -type R1 is record - A : Boolean; - B : Integer range 1 .. 120; -end record; - -for R1 use record - A at 0 range 0 .. 0; - B at 0 range 1 .. 7; -end record; - -type R2 is record - A : Boolean; - B : Integer range 1 .. 120; -end record; - -for R2'Bit_Order use High_Order_First; - -for R2 use record - A at 0 range 7 .. 7; - B at 0 range 0 .. 6; -end record; -@end example - -The useful application here is to write the second declaration with the -@code{Bit_Order} attribute definition clause, and know that it will be treated -the same, regardless of whether the target is little-endian or big-endian. - -@item -Components occupying an integral number of bytes. - -These are components that exactly fit in two or more bytes. Such component -declarations are allowed, but have no effect, since it is important to realize -that the @code{Bit_Order} specification does not affect the ordering of bytes. -In particular, the following attempt at getting an endian-independent integer -does not work: - -@example -type R2 is record - A : Integer; -end record; - -for R2'Bit_Order use High_Order_First; - -for R2 use record - A at 0 range 0 .. 31; -end record; -@end example - -This declaration will result in a little-endian integer on a -little-endian machine, and a big-endian integer on a big-endian machine. -If byte flipping is required for interoperability between big- and -little-endian machines, this must be explicitly programmed. This capability -is not provided by @code{Bit_Order}. - -@item -Components that are positioned across byte boundaries. - -but do not occupy an integral number of bytes. Given that bytes are not -reordered, such fields would occupy a non-contiguous sequence of bits -in memory, requiring non-trivial code to reassemble. They are for this -reason not permitted, and any component clause specifying such a layout -will be flagged as illegal by GNAT. -@end itemize - -Since the misconception that Bit_Order automatically deals with all -endian-related incompatibilities is a common one, the specification of -a component field that is an integral number of bytes will always -generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} -if desired. The following section contains additional -details regarding the issue of byte ordering. - -@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{28a} -@section Effect of Bit_Order on Byte Ordering - - -@geindex byte ordering - -@geindex ordering -@geindex of bytes - -In this section we will review the effect of the @code{Bit_Order} attribute -definition clause on byte ordering. Briefly, it has no effect at all, but -a detailed example will be helpful. Before giving this -example, let us review the precise -definition of the effect of defining @code{Bit_Order}. The effect of a -non-standard bit order is described in section 13.5.3 of the Ada -Reference Manual: - -@quotation - -“2 A bit ordering is a method of interpreting the meaning of -the storage place attributes.” -@end quotation - -To understand the precise definition of storage place attributes in -this context, we visit section 13.5.1 of the manual: - -@quotation - -“13 A record_representation_clause (without the mod_clause) -specifies the layout. The storage place attributes (see 13.5.2) -are taken from the values of the position, first_bit, and last_bit -expressions after normalizing those values so that first_bit is -less than Storage_Unit.” -@end quotation - -The critical point here is that storage places are taken from -the values after normalization, not before. So the @code{Bit_Order} -interpretation applies to normalized values. The interpretation -is described in the later part of the 13.5.3 paragraph: - -@quotation - -“2 A bit ordering is a method of interpreting the meaning of -the storage place attributes. High_Order_First (known in the -vernacular as ‘big endian’) means that the first bit of a -storage element (bit 0) is the most significant bit (interpreting -the sequence of bits that represent a component as an unsigned -integer value). Low_Order_First (known in the vernacular as -‘little endian’) means the opposite: the first bit is the -least significant.” -@end quotation - -Note that the numbering is with respect to the bits of a storage -unit. In other words, the specification affects only the numbering -of bits within a single storage unit. - -We can make the effect clearer by giving an example. - -Suppose that we have an external device which presents two bytes, the first -byte presented, which is the first (low addressed byte) of the two byte -record is called Master, and the second byte is called Slave. - -The left most (most significant) bit is called Control for each byte, and -the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost -(least significant) bit. - -On a big-endian machine, we can write the following representation clause - -@example -type Data is record - Master_Control : Bit; - Master_V1 : Bit; - Master_V2 : Bit; - Master_V3 : Bit; - Master_V4 : Bit; - Master_V5 : Bit; - Master_V6 : Bit; - Master_V7 : Bit; - Slave_Control : Bit; - Slave_V1 : Bit; - Slave_V2 : Bit; - Slave_V3 : Bit; - Slave_V4 : Bit; - Slave_V5 : Bit; - Slave_V6 : Bit; - Slave_V7 : Bit; -end record; - -for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 1 range 0 .. 0; - Slave_V1 at 1 range 1 .. 1; - Slave_V2 at 1 range 2 .. 2; - Slave_V3 at 1 range 3 .. 3; - Slave_V4 at 1 range 4 .. 4; - Slave_V5 at 1 range 5 .. 5; - Slave_V6 at 1 range 6 .. 6; - Slave_V7 at 1 range 7 .. 7; -end record; -@end example - -Now if we move this to a little endian machine, then the bit ordering within -the byte is backwards, so we have to rewrite the record rep clause as: - -@example -for Data use record - Master_Control at 0 range 7 .. 7; - Master_V1 at 0 range 6 .. 6; - Master_V2 at 0 range 5 .. 5; - Master_V3 at 0 range 4 .. 4; - Master_V4 at 0 range 3 .. 3; - Master_V5 at 0 range 2 .. 2; - Master_V6 at 0 range 1 .. 1; - Master_V7 at 0 range 0 .. 0; - Slave_Control at 1 range 7 .. 7; - Slave_V1 at 1 range 6 .. 6; - Slave_V2 at 1 range 5 .. 5; - Slave_V3 at 1 range 4 .. 4; - Slave_V4 at 1 range 3 .. 3; - Slave_V5 at 1 range 2 .. 2; - Slave_V6 at 1 range 1 .. 1; - Slave_V7 at 1 range 0 .. 0; -end record; -@end example - -It is a nuisance to have to rewrite the clause, especially if -the code has to be maintained on both machines. However, -this is a case that we can handle with the -@code{Bit_Order} attribute if it is implemented. -Note that the implementation is not required on byte addressed -machines, but it is indeed implemented in GNAT. -This means that we can simply use the -first record clause, together with the declaration - -@example -for Data'Bit_Order use High_Order_First; -@end example - -and the effect is what is desired, namely the layout is exactly the same, -independent of whether the code is compiled on a big-endian or little-endian -machine. - -The important point to understand is that byte ordering is not affected. -A @code{Bit_Order} attribute definition never affects which byte a field -ends up in, only where it ends up in that byte. -To make this clear, let us rewrite the record rep clause of the previous -example as: - -@example -for Data'Bit_Order use High_Order_First; -for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 0 range 8 .. 8; - Slave_V1 at 0 range 9 .. 9; - Slave_V2 at 0 range 10 .. 10; - Slave_V3 at 0 range 11 .. 11; - Slave_V4 at 0 range 12 .. 12; - Slave_V5 at 0 range 13 .. 13; - Slave_V6 at 0 range 14 .. 14; - Slave_V7 at 0 range 15 .. 15; -end record; -@end example - -This is exactly equivalent to saying (a repeat of the first example): - -@example -for Data'Bit_Order use High_Order_First; -for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 1 range 0 .. 0; - Slave_V1 at 1 range 1 .. 1; - Slave_V2 at 1 range 2 .. 2; - Slave_V3 at 1 range 3 .. 3; - Slave_V4 at 1 range 4 .. 4; - Slave_V5 at 1 range 5 .. 5; - Slave_V6 at 1 range 6 .. 6; - Slave_V7 at 1 range 7 .. 7; -end record; -@end example - -Why are they equivalent? Well take a specific field, the @code{Slave_V2} -field. The storage place attributes are obtained by normalizing the -values given so that the @code{First_Bit} value is less than 8. After -normalizing the values (0,10,10) we get (1,2,2) which is exactly what -we specified in the other case. - -Now one might expect that the @code{Bit_Order} attribute might affect -bit numbering within the entire record component (two bytes in this -case, thus affecting which byte fields end up in), but that is not -the way this feature is defined, it only affects numbering of bits, -not which byte they end up in. - -Consequently it never makes sense to specify a starting bit number -greater than 7 (for a byte addressable field) if an attribute -definition for @code{Bit_Order} has been given, and indeed it -may be actively confusing to specify such a value, so the compiler -generates a warning for such usage. - -If you do need to control byte ordering then appropriate conditional -values must be used. If in our example, the slave byte came first on -some machines we might write: - -@example -Master_Byte_First constant Boolean := ...; - -Master_Byte : constant Natural := - 1 - Boolean'Pos (Master_Byte_First); -Slave_Byte : constant Natural := - Boolean'Pos (Master_Byte_First); - -for Data'Bit_Order use High_Order_First; -for Data use record - Master_Control at Master_Byte range 0 .. 0; - Master_V1 at Master_Byte range 1 .. 1; - Master_V2 at Master_Byte range 2 .. 2; - Master_V3 at Master_Byte range 3 .. 3; - Master_V4 at Master_Byte range 4 .. 4; - Master_V5 at Master_Byte range 5 .. 5; - Master_V6 at Master_Byte range 6 .. 6; - Master_V7 at Master_Byte range 7 .. 7; - Slave_Control at Slave_Byte range 0 .. 0; - Slave_V1 at Slave_Byte range 1 .. 1; - Slave_V2 at Slave_Byte range 2 .. 2; - Slave_V3 at Slave_Byte range 3 .. 3; - Slave_V4 at Slave_Byte range 4 .. 4; - Slave_V5 at Slave_Byte range 5 .. 5; - Slave_V6 at Slave_Byte range 6 .. 6; - Slave_V7 at Slave_Byte range 7 .. 7; -end record; -@end example - -Now to switch between machines, all that is necessary is -to set the boolean constant @code{Master_Byte_First} in -an appropriate manner. - -@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c} -@section Pragma Pack for Arrays - - -@geindex Pragma Pack (for arrays) - -Pragma @code{Pack} applied to an array has an effect that depends upon whether the -component type is `packable'. For a component type to be `packable', it must -be one of the following cases: - - -@itemize * - -@item -Any elementary type. - -@item -Any small packed array type with a static size. - -@item -Any small simple record type with a static size. -@end itemize - -For all these cases, if the component subtype size is in the range -1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, -then the effect of the pragma @code{Pack} is exactly as though a -component size were specified giving the component subtype size. - -All other types are non-packable, they occupy an integral number of storage -units and the only effect of pragma Pack is to remove alignment gaps. - -For example if we have: - -@example -type r is range 0 .. 17; - -type ar is array (1 .. 8) of r; -pragma Pack (ar); -@end example - -Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, -and the size of the array @code{ar} will be exactly 40 bits). - -Note that in some cases this rather fierce approach to packing can produce -unexpected effects. For example, in Ada 95 and Ada 2005, -subtype @code{Natural} typically has a size of 31, meaning that if you -pack an array of @code{Natural}, you get 31-bit -close packing, which saves a few bits, but results in far less efficient -access. Since many other Ada compilers will ignore such a packing request, -GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses -might not be what is intended. You can easily remove this warning by -using an explicit @code{Component_Size} setting instead, which never generates -a warning, since the intention of the programmer is clear in this case. - -GNAT treats packed arrays in one of two ways. If the size of the array is -known at compile time and is at most 64 bits on 32-bit targets, and at most -128 bits on 64-bit targets, then internally the array is represented as a -single modular type, of exactly the appropriate number of bits. If the -length is greater than 64 bits on 32-bit targets, and greater than 128 -bits on 64-bit targets, or is not known at compile time, then the packed -array is represented as an array of bytes, and its length is always a -multiple of 8 bits. - -Note that to represent a packed array as a modular type, the alignment must -be suitable for the modular type involved. For example, on typical machines -a 32-bit packed array will be represented by a 32-bit modular integer with -an alignment of four bytes. If you explicitly override the default alignment -with an alignment clause that is too small, the modular representation -cannot be used. For example, consider the following set of declarations: - -@example -type R is range 1 .. 3; -type S is array (1 .. 31) of R; -for S'Component_Size use 2; -for S'Size use 62; -for S'Alignment use 1; -@end example - -If the alignment clause were not present, then a 62-bit modular -representation would be chosen (typically with an alignment of 4 or 8 -bytes depending on the target). But the default alignment is overridden -with the explicit alignment clause. This means that the modular -representation cannot be used, and instead the array of bytes -representation must be used, meaning that the length must be a multiple -of 8. Thus the above set of declarations will result in a diagnostic -rejecting the size clause and noting that the minimum size allowed is 64. - -@geindex Pragma Pack (for type Natural) - -@geindex Pragma Pack warning - -One special case that is worth noting occurs when the base type of the -component size is 8/16/32 and the subtype is one bit less. Notably this -occurs with subtype @code{Natural}. Consider: - -@example -type Arr is array (1 .. 32) of Natural; -pragma Pack (Arr); -@end example - -In all commonly used Ada 83 compilers, this pragma Pack would be ignored, -since typically @code{Natural'Size} is 32 in Ada 83, and in any case most -Ada 83 compilers did not attempt 31 bit packing. - -In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, -GNAT really does pack 31-bit subtype to 31 bits. This may result in a -substantial unintended performance penalty when porting legacy Ada 83 code. -To help prevent this, GNAT generates a warning in such cases. If you really -want 31 bit packing in a case like this, you can set the component size -explicitly: - -@example -type Arr is array (1 .. 32) of Natural; -for Arr'Component_Size use 31; -@end example - -Here 31-bit packing is achieved as required, and no warning is generated, -since in this case the programmer intention is clear. - -@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e} -@section Pragma Pack for Records - - -@geindex Pragma Pack (for records) - -Pragma @code{Pack} applied to a record will pack the components to reduce -wasted space from alignment gaps and by reducing the amount of space -taken by components. We distinguish between `packable' components and -`non-packable' components. -Components of the following types are considered packable: - - -@itemize * - -@item -Components of an elementary type are packable unless they are aliased, -independent or atomic. - -@item -Small packed arrays, where the size is statically known, are represented -internally as modular integers, and so they are also packable. - -@item -Small simple records, where the size is statically known, are also packable. -@end itemize - -For all these cases, if the @code{'Size} value is in the range 1 through 64 on -32-bit targets, and 1 through 128 on 64-bit targets, the components occupy -the exact number of bits corresponding to this value and are packed with no -padding bits, i.e. they can start on an arbitrary bit boundary. - -All other types are non-packable, they occupy an integral number of storage -units and the only effect of pragma @code{Pack} is to remove alignment gaps. - -For example, consider the record - -@example -type Rb1 is array (1 .. 13) of Boolean; -pragma Pack (Rb1); - -type Rb2 is array (1 .. 65) of Boolean; -pragma Pack (Rb2); - -type AF is new Float with Atomic; - -type X2 is record - L1 : Boolean; - L2 : Duration; - L3 : AF; - L4 : Boolean; - L5 : Rb1; - L6 : Rb2; -end record; -pragma Pack (X2); -@end example - -The representation for the record @code{X2} is as follows on 32-bit targets: - -@example -for X2'Size use 224; -for X2 use record - L1 at 0 range 0 .. 0; - L2 at 0 range 1 .. 64; - L3 at 12 range 0 .. 31; - L4 at 16 range 0 .. 0; - L5 at 16 range 1 .. 13; - L6 at 18 range 0 .. 71; -end record; -@end example - -Studying this example, we see that the packable fields @code{L1} -and @code{L2} are of length equal to their sizes, and placed at -specific bit boundaries (and not byte boundaries) to eliminate -padding. But @code{L3} is of a non-packable float type (because -it is aliased), so it is on the next appropriate alignment boundary. - -The next two fields are fully packable, so @code{L4} and @code{L5} are -minimally packed with no gaps. However, type @code{Rb2} is a packed -array that is longer than 64 bits, so it is itself non-packable on -32-bit targets. Thus the @code{L6} field is aligned to the next byte -boundary, and takes an integral number of bytes, i.e., 72 bits. - -@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290} -@section Record Representation Clauses - - -@geindex Record Representation Clause - -Record representation clauses may be given for all record types, including -types obtained by record extension. Component clauses are allowed for any -static component. The restrictions on component clauses depend on the type -of the component. - -@geindex Component Clause - -For all components of an elementary type, the only restriction on component -clauses is that the size must be at least the @code{'Size} value of the type -(actually the Value_Size). There are no restrictions due to alignment, -and such components may freely cross storage boundaries. - -Packed arrays with a size up to and including 64 bits on 32-bit targets, -and up to and including 128 bits on 64-bit targets, are represented -internally using a modular type with the appropriate number of bits, and -thus the same lack of restriction applies. For example, if you declare: - -@example -type R is array (1 .. 49) of Boolean; -pragma Pack (R); -for R'Size use 49; -@end example - -then a component clause for a component of type @code{R} may start on any -specified bit boundary, and may specify a value of 49 bits or greater. - -For packed bit arrays that are longer than 64 bits on 32-bit targets, -and longer than 128 bits on 64-bit targets, there are two cases. If the -component size is a power of 2 (1,2,4,8,16,32,64 bits), including the -important case of single bits or boolean values, then there are no -limitations on placement of such components, and they may start and -end at arbitrary bit boundaries. - -If the component size is not a power of 2 (e.g., 3 or 5), then an array -of this type must always be placed on on a storage unit (byte) boundary -and occupy an integral number of storage units (bytes). Any component -clause that does not meet this requirement will be rejected. - -Any aliased component, or component of an aliased type, must have its -normal alignment and size. A component clause that does not meet this -requirement will be rejected. - -The tag field of a tagged type always occupies an address sized field at -the start of the record. No component clause may attempt to overlay this -tag. When a tagged type appears as a component, the tag field must have -proper alignment - -In the case of a record extension @code{T1}, of a type @code{T}, no component -clause applied to the type @code{T1} can specify a storage location that -would overlap the first @code{T'Object_Size} bits of the record. - -For all other component types, including non-bit-packed arrays, -the component can be placed at an arbitrary bit boundary, -so for example, the following is permitted: - -@example -type R is array (1 .. 10) of Boolean; -for R'Size use 80; - -type Q is record - G, H : Boolean; - L, M : R; -end record; - -for Q use record - G at 0 range 0 .. 0; - H at 0 range 1 .. 1; - L at 0 range 2 .. 81; - R at 0 range 82 .. 161; -end record; -@end example - -@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292} -@section Handling of Records with Holes - - -@geindex Handling of Records with Holes - -As a result of alignment considerations, records may contain “holes” -or gaps which do not correspond to the data bits of any of the components. -Record representation clauses can also result in holes in records. - -GNAT does not attempt to clear these holes, so in record objects, -they should be considered to hold undefined rubbish. The generated -equality routine just tests components so does not access these -undefined bits, and assignment and copy operations may or may not -preserve the contents of these holes (for assignments, the holes -in the target will in practice contain either the bits that are -present in the holes in the source, or the bits that were present -in the target before the assignment). - -If it is necessary to ensure that holes in records have all zero -bits, then record objects for which this initialization is desired -should be explicitly set to all zero values using Unchecked_Conversion -or address overlays. For example - -@example -type HRec is record - C : Character; - I : Integer; -end record; -@end example - -On typical machines, integers need to be aligned on a four-byte -boundary, resulting in three bytes of undefined rubbish following -the 8-bit field for C. To ensure that the hole in a variable of -type HRec is set to all zero bits, -you could for example do: - -@example -type Base is record - Dummy1, Dummy2 : Integer := 0; -end record; - -BaseVar : Base; -RealVar : Hrec; -for RealVar'Address use BaseVar'Address; -@end example - -Now the 8-bytes of the value of RealVar start out containing all zero -bits. A safer approach is to just define dummy fields, avoiding the -holes, as in: - -@example -type HRec is record - C : Character; - Dummy1 : Short_Short_Integer := 0; - Dummy2 : Short_Short_Integer := 0; - Dummy3 : Short_Short_Integer := 0; - I : Integer; -end record; -@end example - -And to make absolutely sure that the intent of this is followed, you -can use representation clauses: - -@example -for Hrec use record - C at 0 range 0 .. 7; - Dummy1 at 1 range 0 .. 7; - Dummy2 at 2 range 0 .. 7; - Dummy3 at 3 range 0 .. 7; - I at 4 range 0 .. 31; -end record; -for Hrec'Size use 64; -@end example - -@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294} -@section Enumeration Clauses - - -The only restriction on enumeration clauses is that the range of values -must be representable. For the signed case, if one or more of the -representation values are negative, all values must be in the range: - -@example -System.Min_Int .. System.Max_Int -@end example - -For the unsigned case, where all values are nonnegative, the values must -be in the range: - -@example -0 .. System.Max_Binary_Modulus; -@end example - -A `confirming' representation clause is one in which the values range -from 0 in sequence, i.e., a clause that confirms the default representation -for an enumeration type. -Such a confirming representation -is permitted by these rules, and is specially recognized by the compiler so -that no extra overhead results from the use of such a clause. - -If an array has an index type which is an enumeration type to which an -enumeration clause has been applied, then the array is stored in a compact -manner. Consider the declarations: - -@example -type r is (A, B, C); -for r use (A => 1, B => 5, C => 10); -type t is array (r) of Character; -@end example - -The array type t corresponds to a vector with exactly three elements and -has a default size equal to @code{3*Character'Size}. This ensures efficient -use of space, but means that accesses to elements of the array will incur -the overhead of converting representation values to the corresponding -positional values, (i.e., the value delivered by the @code{Pos} attribute). - -@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296} -@section Address Clauses - - -@geindex Address Clause - -The reference manual allows a general restriction on representation clauses, -as found in RM 13.1(22): - -@quotation - -“An implementation need not support representation -items containing nonstatic expressions, except that -an implementation should support a representation item -for a given entity if each nonstatic expression in the -representation item is a name that statically denotes -a constant declared before the entity.” -@end quotation - -In practice this is applicable only to address clauses, since this is the -only case in which a nonstatic expression is permitted by the syntax. As -the AARM notes in sections 13.1 (22.a-22.h): - -@quotation - -22.a Reason: This is to avoid the following sort of thing: - -22.b X : Integer := F(…); -Y : Address := G(…); -for X’Address use Y; - -22.c In the above, we have to evaluate the -initialization expression for X before we -know where to put the result. This seems -like an unreasonable implementation burden. - -22.d The above code should instead be written -like this: - -22.e Y : constant Address := G(…); -X : Integer := F(…); -for X’Address use Y; - -22.f This allows the expression ‘Y’ to be safely -evaluated before X is created. - -22.g The constant could be a formal parameter of mode in. - -22.h An implementation can support other nonstatic -expressions if it wants to. Expressions of type -Address are hardly ever static, but their value -might be known at compile time anyway in many -cases. -@end quotation - -GNAT does indeed permit many additional cases of nonstatic expressions. In -particular, if the type involved is elementary there are no restrictions -(since in this case, holding a temporary copy of the initialization value, -if one is present, is inexpensive). In addition, if there is no implicit or -explicit initialization, then there are no restrictions. GNAT will reject -only the case where all three of these conditions hold: - - -@itemize * - -@item -The type of the item is non-elementary (e.g., a record or array). - -@item -There is explicit or implicit initialization required for the object. -Note that access values are always implicitly initialized. - -@item -The address value is nonstatic. Here GNAT is more permissive than the -RM, and allows the address value to be the address of a previously declared -stand-alone variable, as long as it does not itself have an address clause. - -@example -Anchor : Some_Initialized_Type; -Overlay : Some_Initialized_Type; -for Overlay'Address use Anchor'Address; -@end example - -However, the prefix of the address clause cannot be an array component, or -a component of a discriminated record. -@end itemize - -As noted above in section 22.h, address values are typically nonstatic. In -particular the To_Address function, even if applied to a literal value, is -a nonstatic function call. To avoid this minor annoyance, GNAT provides -the implementation defined attribute ‘To_Address. The following two -expressions have identical values: - -@geindex Attribute - -@geindex To_Address - -@example -To_Address (16#1234_0000#) -System'To_Address (16#1234_0000#); -@end example - -except that the second form is considered to be a static expression, and -thus when used as an address clause value is always permitted. - -Additionally, GNAT treats as static an address clause that is an -unchecked_conversion of a static integer value. This simplifies the porting -of legacy code, and provides a portable equivalent to the GNAT attribute -@code{To_Address}. - -Another issue with address clauses is the interaction with alignment -requirements. When an address clause is given for an object, the address -value must be consistent with the alignment of the object (which is usually -the same as the alignment of the type of the object). If an address clause -is given that specifies an inappropriately aligned address value, then the -program execution is erroneous. - -Since this source of erroneous behavior can have unfortunate effects on -machines with strict alignment requirements, GNAT -checks (at compile time if possible, generating a warning, or at execution -time with a run-time check) that the alignment is appropriate. If the -run-time check fails, then @code{Program_Error} is raised. This run-time -check is suppressed if range checks are suppressed, or if the special GNAT -check Alignment_Check is suppressed, or if -@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also -suppressed by default on non-strict alignment machines (such as the x86). - -In some cases, GNAT does not support an address specification (using either -form of aspect specification syntax) for the declaration of an object that has -an indefinite nominal subtype. An object declaration has an indefinite -nominal subtype if it takes its bounds (for an array type), discriminant -values (for a discriminated type whose discriminants lack defaults), or tag -(for a class-wide type) from its initial value, as in - -@example -X : String := Some_Function_Call; --- String has no constraint, so bounds for X come from function call -@end example - -This restriction does not apply if the size of the object’s initial value is -known at compile time and the type of the object is not class-wide. - -@geindex Export - -An address clause cannot be given for an exported object. More -understandably the real restriction is that objects with an address -clause cannot be exported. This is because such variables are not -defined by the Ada program, so there is no external object to export. - -@geindex Import - -It is permissible to give an address clause and a pragma Import for the -same object. In this case, the variable is not really defined by the -Ada program, so there is no external symbol to be linked. The link name -and the external name are ignored in this case. The reason that we allow this -combination is that it provides a useful idiom to avoid unwanted -initializations on objects with address clauses. - -When an address clause is given for an object that has implicit or -explicit initialization, then by default initialization takes place. This -means that the effect of the object declaration is to overwrite the -memory at the specified address. This is almost always not what the -programmer wants, so GNAT will output a warning: - -@example -with System; -package G is - type R is record - M : Integer := 0; - end record; - - Ext : R; - for Ext'Address use System'To_Address (16#1234_1234#); - | ->>> warning: implicit initialization of "Ext" may - modify overlaid storage ->>> warning: use pragma Import for "Ext" to suppress - initialization (RM B(24)) - -end G; -@end example - -As indicated by the warning message, the solution is to use a (dummy) pragma -Import to suppress this initialization. The pragma tell the compiler that the -object is declared and initialized elsewhere. The following package compiles -without warnings (and the initialization is suppressed): - -@example -with System; -package G is - type R is record - M : Integer := 0; - end record; - - Ext : R; - for Ext'Address use System'To_Address (16#1234_1234#); - pragma Import (Ada, Ext); -end G; -@end example - -A final issue with address clauses involves their use for overlaying -variables, as in the following example: - -@geindex Overlaying of objects - -@example -A : Integer; -B : Integer; -for B'Address use A'Address; -@end example - -or alternatively, using the form recommended by the RM: - -@example -A : Integer; -Addr : constant Address := A'Address; -B : Integer; -for B'Address use Addr; -@end example - -In both of these cases, @code{A} and @code{B} become aliased to one another -via the address clause. This use of address clauses to overlay -variables, achieving an effect similar to unchecked conversion -was erroneous in Ada 83, but in Ada 95 and Ada 2005 -the effect is implementation defined. Furthermore, the -Ada RM specifically recommends that in a situation -like this, @code{B} should be subject to the following -implementation advice (RM 13.3(19)): - -@quotation - -“19 If the Address of an object is specified, or it is imported -or exported, then the implementation should not perform -optimizations based on assumptions of no aliases.” -@end quotation - -GNAT follows this recommendation, and goes further by also applying -this recommendation to the overlaid variable (@code{A} in the above example) -in this case. This means that the overlay works “as expected”, in that -a modification to one of the variables will affect the value of the other. - -More generally, GNAT interprets this recommendation conservatively for -address clauses: in the cases other than overlays, it considers that the -object is effectively subject to pragma @code{Volatile} and implements the -associated semantics. - -Note that when address clause overlays are used in this way, there is an -issue of unintentional initialization, as shown by this example: - -@example -package Overwrite_Record is - type R is record - A : Character := 'C'; - B : Character := 'A'; - end record; - X : Short_Integer := 3; - Y : R; - for Y'Address use X'Address; - | ->>> warning: default initialization of "Y" may - modify "X", use pragma Import for "Y" to - suppress initialization (RM B.1(24)) - -end Overwrite_Record; -@end example - -Here the default initialization of @code{Y} will clobber the value -of @code{X}, which justifies the warning. The warning notes that -this effect can be eliminated by adding a @code{pragma Import} -which suppresses the initialization: - -@example -package Overwrite_Record is - type R is record - A : Character := 'C'; - B : Character := 'A'; - end record; - X : Short_Integer := 3; - Y : R; - for Y'Address use X'Address; - pragma Import (Ada, Y); -end Overwrite_Record; -@end example - -Note that the use of @code{pragma Initialize_Scalars} may cause variables to -be initialized when they would not otherwise have been in the absence -of the use of this pragma. This may cause an overlay to have this -unintended clobbering effect. The compiler avoids this for scalar -types, but not for composite objects (where in general the effect -of @code{Initialize_Scalars} is part of the initialization routine -for the composite object): - -@example -pragma Initialize_Scalars; -with Ada.Text_IO; use Ada.Text_IO; -procedure Overwrite_Array is - type Arr is array (1 .. 5) of Integer; - X : Arr := (others => 1); - A : Arr; - for A'Address use X'Address; - | ->>> warning: default initialization of "A" may - modify "X", use pragma Import for "A" to - suppress initialization (RM B.1(24)) - -begin - if X /= Arr'(others => 1) then - Put_Line ("X was clobbered"); - else - Put_Line ("X was not clobbered"); - end if; -end Overwrite_Array; -@end example - -The above program generates the warning as shown, and at execution -time, prints @code{X was clobbered}. If the @code{pragma Import} is -added as suggested: - -@example -pragma Initialize_Scalars; -with Ada.Text_IO; use Ada.Text_IO; -procedure Overwrite_Array is - type Arr is array (1 .. 5) of Integer; - X : Arr := (others => 1); - A : Arr; - for A'Address use X'Address; - pragma Import (Ada, A); -begin - if X /= Arr'(others => 1) then - Put_Line ("X was clobbered"); - else - Put_Line ("X was not clobbered"); - end if; -end Overwrite_Array; -@end example - -then the program compiles without the warning and when run will generate -the output @code{X was not clobbered}. - -@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{298} -@section Use of Address Clauses for Memory-Mapped I/O - - -@geindex Memory-mapped I/O - -A common pattern is to use an address clause to map an atomic variable to -a location in memory that corresponds to a memory-mapped I/O operation or -operations, for example: - -@example -type Mem_Word is record - A,B,C,D : Byte; -end record; -pragma Atomic (Mem_Word); -for Mem_Word_Size use 32; - -Mem : Mem_Word; -for Mem'Address use some-address; -... -Temp := Mem; -Temp.A := 32; -Mem := Temp; -@end example - -For a full access (reference or modification) of the variable (Mem) in this -case, as in the above examples, GNAT guarantees that the entire atomic word -will be accessed, in accordance with the RM C.6(15) clause. - -A problem arises with a component access such as: - -@example -Mem.A := 32; -@end example - -Note that the component A is not declared as atomic. This means that it is -not clear what this assignment means. It could correspond to full word read -and write as given in the first example, or on architectures that supported -such an operation it might be a single byte store instruction. The RM does -not have anything to say in this situation, and GNAT does not make any -guarantee. The code generated may vary from target to target. GNAT will issue -a warning in such a case: - -@example -Mem.A := 32; -| ->>> warning: access to non-atomic component of atomic array, - may cause unexpected accesses to atomic object -@end example - -It is best to be explicit in this situation, by either declaring the -components to be atomic if you want the byte store, or explicitly writing -the full word access sequence if that is what the hardware requires. -Alternatively, if the full word access sequence is required, GNAT also -provides the pragma @code{Volatile_Full_Access} which can be used in lieu of -pragma @code{Atomic} and will give the additional guarantee. - -@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a} -@section Effect of Convention on Representation - - -@geindex Convention -@geindex effect on representation - -Normally the specification of a foreign language convention for a type or -an object has no effect on the chosen representation. In particular, the -representation chosen for data in GNAT generally meets the standard system -conventions, and for example records are laid out in a manner that is -consistent with C. This means that specifying convention C (for example) -has no effect. - -There are four exceptions to this general rule: - - -@itemize * - -@item -`Convention Fortran and array subtypes'. - -If pragma Convention Fortran is specified for an array subtype, then in -accordance with the implementation advice in section 3.6.2(11) of the -Ada Reference Manual, the array will be stored in a Fortran-compatible -column-major manner, instead of the normal default row-major order. - -@item -`Convention C and enumeration types' - -GNAT normally stores enumeration types in 8, 16, or 32 bits as required -to accommodate all values of the type. For example, for the enumeration -type declared by: - -@example -type Color is (Red, Green, Blue); -@end example - -8 bits is sufficient to store all values of the type, so by default, objects -of type @code{Color} will be represented using 8 bits. However, normal C -convention is to use 32 bits for all enum values in C, since enum values -are essentially of type int. If pragma @code{Convention C} is specified for an -Ada enumeration type, then the size is modified as necessary (usually to -32 bits) to be consistent with the C convention for enum values. - -Note that this treatment applies only to types. If Convention C is given for -an enumeration object, where the enumeration type is not Convention C, then -Object_Size bits are allocated. For example, for a normal enumeration type, -with less than 256 elements, only 8 bits will be allocated for the object. -Since this may be a surprise in terms of what C expects, GNAT will issue a -warning in this situation. The warning can be suppressed by giving an explicit -size clause specifying the desired size. - -@item -`Convention C/Fortran and Boolean types' - -In C, the usual convention for boolean values, that is values used for -conditions, is that zero represents false, and nonzero values represent -true. In Ada, the normal convention is that two specific values, typically -0/1, are used to represent false/true respectively. - -Fortran has a similar convention for @code{LOGICAL} values (any nonzero -value represents true). - -To accommodate the Fortran and C conventions, if a pragma Convention specifies -C or Fortran convention for a derived Boolean, as in the following example: - -@example -type C_Switch is new Boolean; -pragma Convention (C, C_Switch); -@end example - -then the GNAT generated code will treat any nonzero value as true. For truth -values generated by GNAT, the conventional value 1 will be used for True, but -when one of these values is read, any nonzero value is treated as True. -@end itemize - -@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c} -@section Conventions and Anonymous Access Types - - -@geindex Anonymous access types - -@geindex Convention for anonymous access types - -The RM is not entirely clear on convention handling in a number of cases, -and in particular, it is not clear on the convention to be given to -anonymous access types in general, and in particular what is to be -done for the case of anonymous access-to-subprogram. - -In GNAT, we decide that if an explicit Convention is applied -to an object or component, and its type is such an anonymous type, -then the convention will apply to this anonymous type as well. This -seems to make sense since it is anomolous in any case to have a -different convention for an object and its type, and there is clearly -no way to explicitly specify a convention for an anonymous type, since -it doesn’t have a name to specify! - -Furthermore, we decide that if a convention is applied to a record type, -then this convention is inherited by any of its components that are of an -anonymous access type which do not have an explicitly specified convention. - -The following program shows these conventions in action: - -@example -package ConvComp is - type Foo is range 1 .. 10; - type T1 is record - A : access function (X : Foo) return Integer; - B : Integer; - end record; - pragma Convention (C, T1); - - type T2 is record - A : access function (X : Foo) return Integer; - pragma Convention (C, A); - B : Integer; - end record; - pragma Convention (COBOL, T2); - - type T3 is record - A : access function (X : Foo) return Integer; - pragma Convention (COBOL, A); - B : Integer; - end record; - pragma Convention (C, T3); - - type T4 is record - A : access function (X : Foo) return Integer; - B : Integer; - end record; - pragma Convention (COBOL, T4); - - function F (X : Foo) return Integer; - pragma Convention (C, F); - - function F (X : Foo) return Integer is (13); - - TV1 : T1 := (F'Access, 12); -- OK - TV2 : T2 := (F'Access, 13); -- OK - - TV3 : T3 := (F'Access, 13); -- ERROR - | ->>> subprogram "F" has wrong convention ->>> does not match access to subprogram declared at line 17 - 38. TV4 : T4 := (F'Access, 13); -- ERROR - | ->>> subprogram "F" has wrong convention ->>> does not match access to subprogram declared at line 24 - 39. end ConvComp; -@end example - -@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas -@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29e} -@section Determining the Representations chosen by GNAT - - -@geindex Representation -@geindex determination of - -@geindex -gnatR (gcc) - -Although the descriptions in this section are intended to be complete, it is -often easier to simply experiment to see what GNAT accepts and what the -effect is on the layout of types and objects. - -As required by the Ada RM, if a representation clause is not accepted, then -it must be rejected as illegal by the compiler. However, when a -representation clause or pragma is accepted, there can still be questions -of what the compiler actually does. For example, if a partial record -representation clause specifies the location of some components and not -others, then where are the non-specified components placed? Or if pragma -@code{Pack} is used on a record, then exactly where are the resulting -fields placed? The section on pragma @code{Pack} in this chapter can be -used to answer the second question, but it is often easier to just see -what the compiler does. - -For this purpose, GNAT provides the option `-gnatR'. If you compile -with this option, then the compiler will output information on the actual -representations chosen, in a format similar to source representation -clauses. For example, if we compile the package: - -@example -package q is - type r (x : boolean) is tagged record - case x is - when True => S : String (1 .. 100); - when False => null; - end case; - end record; - - type r2 is new r (false) with record - y2 : integer; - end record; - - for r2 use record - y2 at 16 range 0 .. 31; - end record; - - type x is record - y : character; - end record; - - type x1 is array (1 .. 10) of x; - for x1'component_size use 11; - - type ia is access integer; - - type Rb1 is array (1 .. 13) of Boolean; - pragma Pack (rb1); - - type Rb2 is array (1 .. 65) of Boolean; - pragma Pack (rb2); - - type x2 is record - l1 : Boolean; - l2 : Duration; - l3 : Float; - l4 : Boolean; - l5 : Rb1; - l6 : Rb2; - end record; - pragma Pack (x2); -end q; -@end example - -using the switch `-gnatR' we obtain the following output: - -@example -Representation information for unit q -------------------------------------- - -for r'Size use ??; -for r'Alignment use 4; -for r use record - x at 4 range 0 .. 7; - _tag at 0 range 0 .. 31; - s at 5 range 0 .. 799; -end record; - -for r2'Size use 160; -for r2'Alignment use 4; -for r2 use record - x at 4 range 0 .. 7; - _tag at 0 range 0 .. 31; - _parent at 0 range 0 .. 63; - y2 at 16 range 0 .. 31; -end record; - -for x'Size use 8; -for x'Alignment use 1; -for x use record - y at 0 range 0 .. 7; -end record; - -for x1'Size use 112; -for x1'Alignment use 1; -for x1'Component_Size use 11; - -for rb1'Size use 13; -for rb1'Alignment use 2; -for rb1'Component_Size use 1; - -for rb2'Size use 72; -for rb2'Alignment use 1; -for rb2'Component_Size use 1; - -for x2'Size use 224; -for x2'Alignment use 4; -for x2 use record - l1 at 0 range 0 .. 0; - l2 at 0 range 1 .. 64; - l3 at 12 range 0 .. 31; - l4 at 16 range 0 .. 0; - l5 at 16 range 1 .. 13; - l6 at 18 range 0 .. 71; -end record; -@end example - -The Size values are actually the Object_Size, i.e., the default size that -will be allocated for objects of the type. -The @code{??} size for type r indicates that we have a variant record, and the -actual size of objects will depend on the discriminant value. - -The Alignment values show the actual alignment chosen by the compiler -for each record or array type. - -The record representation clause for type r shows where all fields -are placed, including the compiler generated tag field (whose location -cannot be controlled by the programmer). - -The record representation clause for the type extension r2 shows all the -fields present, including the parent field, which is a copy of the fields -of the parent type of r2, i.e., r1. - -The component size and size clauses for types rb1 and rb2 show -the exact effect of pragma @code{Pack} on these arrays, and the record -representation clause for type x2 shows how pragma @cite{Pack} affects -this record type. - -In some cases, it may be useful to cut and paste the representation clauses -generated by the compiler into the original source to fix and guarantee -the actual representation to be used. - -@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top -@anchor{gnat_rm/standard_library_routines doc}@anchor{29f}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a0}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e} -@chapter Standard Library Routines - - -The Ada Reference Manual contains in Annex A a full description of an -extensive set of standard library routines that can be used in any Ada -program, and which must be provided by all Ada compilers. They are -analogous to the standard C library used by C programs. - -GNAT implements all of the facilities described in annex A, and for most -purposes the description in the Ada Reference Manual, or appropriate Ada -text book, will be sufficient for making use of these facilities. - -In the case of the input-output facilities, -@ref{f,,The Implementation of Standard I/O}, -gives details on exactly how GNAT interfaces to the -file system. For the remaining packages, the Ada Reference Manual -should be sufficient. The following is a list of the packages included, -together with a brief description of the functionality that is provided. - -For completeness, references are included to other predefined library -routines defined in other sections of the Ada Reference Manual (these are -cross-indexed from Annex A). For further details see the relevant -package declarations in the run-time library. In particular, a few units -are not implemented, as marked by the presence of pragma Unimplemented_Unit, -and in this case the package declaration contains comments explaining why -the unit is not implemented. - - -@table @asis - -@item @code{Ada} `(A.2)' - -This is a parent package for all the standard library packages. It is -usually included implicitly in your program, and itself contains no -useful data or routines. - -@item @code{Ada.Assertions} `(11.4.2)' - -@code{Assertions} provides the @code{Assert} subprograms, and also -the declaration of the @code{Assertion_Error} exception. - -@item @code{Ada.Asynchronous_Task_Control} `(D.11)' - -@code{Asynchronous_Task_Control} provides low level facilities for task -synchronization. It is typically not implemented. See package spec for details. - -@item @code{Ada.Calendar} `(9.6)' - -@code{Calendar} provides time of day access, and routines for -manipulating times and durations. - -@item @code{Ada.Calendar.Arithmetic} `(9.6.1)' - -This package provides additional arithmetic -operations for @code{Calendar}. - -@item @code{Ada.Calendar.Formatting} `(9.6.1)' - -This package provides formatting operations for @code{Calendar}. - -@item @code{Ada.Calendar.Time_Zones} `(9.6.1)' - -This package provides additional @code{Calendar} facilities -for handling time zones. - -@item @code{Ada.Characters} `(A.3.1)' - -This is a dummy parent package that contains no useful entities - -@item @code{Ada.Characters.Conversions} `(A.3.2)' - -This package provides character conversion functions. - -@item @code{Ada.Characters.Handling} `(A.3.2)' - -This package provides some basic character handling capabilities, -including classification functions for classes of characters (e.g., test -for letters, or digits). - -@item @code{Ada.Characters.Latin_1} `(A.3.3)' - -This package includes a complete set of definitions of the characters -that appear in type CHARACTER. It is useful for writing programs that -will run in international environments. For example, if you want an -upper case E with an acute accent in a string, it is often better to use -the definition of @code{UC_E_Acute} in this package. Then your program -will print in an understandable manner even if your environment does not -support these extended characters. - -@item @code{Ada.Command_Line} `(A.15)' - -This package provides access to the command line parameters and the name -of the current program (analogous to the use of @code{argc} and @code{argv} -in C), and also allows the exit status for the program to be set in a -system-independent manner. - -@item @code{Ada.Complex_Text_IO} `(G.1.3)' - -This package provides text input and output of complex numbers. - -@item @code{Ada.Containers} `(A.18.1)' - -A top level package providing a few basic definitions used by all the -following specific child packages that provide specific kinds of -containers. -@end table - -@code{Ada.Containers.Bounded_Priority_Queues} `(A.18.31)' - -@code{Ada.Containers.Bounded_Synchronized_Queues} `(A.18.29)' - -@code{Ada.Containers.Doubly_Linked_Lists} `(A.18.3)' - -@code{Ada.Containers.Generic_Array_Sort} `(A.18.26)' - -@code{Ada.Containers.Generic_Constrained_Array_Sort} `(A.18.26)' - -@code{Ada.Containers.Generic_Sort} `(A.18.26)' - -@code{Ada.Containers.Hashed_Maps} `(A.18.5)' - -@code{Ada.Containers.Hashed_Sets} `(A.18.8)' - -@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} `(A.18.12)' - -@code{Ada.Containers.Indefinite_Hashed_Maps} `(A.18.13)' - -@code{Ada.Containers.Indefinite_Hashed_Sets} `(A.18.15)' - -@code{Ada.Containers.Indefinite_Holders} `(A.18.18)' - -@code{Ada.Containers.Indefinite_Multiway_Trees} `(A.18.17)' - -@code{Ada.Containers.Indefinite_Ordered_Maps} `(A.18.14)' - -@code{Ada.Containers.Indefinite_Ordered_Sets} `(A.18.16)' - -@code{Ada.Containers.Indefinite_Vectors} `(A.18.11)' - -@code{Ada.Containers.Multiway_Trees} `(A.18.10)' - -@code{Ada.Containers.Ordered_Maps} `(A.18.6)' - -@code{Ada.Containers.Ordered_Sets} `(A.18.9)' - -@code{Ada.Containers.Synchronized_Queue_Interfaces} `(A.18.27)' - -@code{Ada.Containers.Unbounded_Priority_Queues} `(A.18.30)' - -@code{Ada.Containers.Unbounded_Synchronized_Queues} `(A.18.28)' - -@code{Ada.Containers.Vectors} `(A.18.2)' - - -@table @asis - -@item @code{Ada.Directories} `(A.16)' - -This package provides operations on directories. - -@item @code{Ada.Directories.Hierarchical_File_Names} `(A.16.1)' - -This package provides additional directory operations handling -hierarchical file names. - -@item @code{Ada.Directories.Information} `(A.16)' - -This is an implementation defined package for additional directory -operations, which is not implemented in GNAT. - -@item @code{Ada.Decimal} `(F.2)' - -This package provides constants describing the range of decimal numbers -implemented, and also a decimal divide routine (analogous to the COBOL -verb DIVIDE … GIVING … REMAINDER …) - -@item @code{Ada.Direct_IO} `(A.8.4)' - -This package provides input-output using a model of a set of records of -fixed-length, containing an arbitrary definite Ada type, indexed by an -integer record number. - -@item @code{Ada.Dispatching} `(D.2.1)' - -A parent package containing definitions for task dispatching operations. - -@item @code{Ada.Dispatching.EDF} `(D.2.6)' - -Not implemented in GNAT. - -@item @code{Ada.Dispatching.Non_Preemptive} `(D.2.4)' - -Not implemented in GNAT. - -@item @code{Ada.Dispatching.Round_Robin} `(D.2.5)' - -Not implemented in GNAT. - -@item @code{Ada.Dynamic_Priorities} `(D.5)' - -This package allows the priorities of a task to be adjusted dynamically -as the task is running. - -@item @code{Ada.Environment_Variables} `(A.17)' - -This package provides facilities for accessing environment variables. - -@item @code{Ada.Exceptions} `(11.4.1)' - -This package provides additional information on exceptions, and also -contains facilities for treating exceptions as data objects, and raising -exceptions with associated messages. - -@item @code{Ada.Execution_Time} `(D.14)' - -This package provides CPU clock functionalities. It is not implemented on -all targets (see package spec for details). - -@item @code{Ada.Execution_Time.Group_Budgets} `(D.14.2)' - -Not implemented in GNAT. - -@item @code{Ada.Execution_Time.Timers} `(D.14.1)’' - -Not implemented in GNAT. - -@item @code{Ada.Finalization} `(7.6)' - -This package contains the declarations and subprograms to support the -use of controlled types, providing for automatic initialization and -finalization (analogous to the constructors and destructors of C++). - -@item @code{Ada.Float_Text_IO} `(A.10.9)' - -A library level instantiation of Text_IO.Float_IO for type Float. - -@item @code{Ada.Float_Wide_Text_IO} `(A.10.9)' - -A library level instantiation of Wide_Text_IO.Float_IO for type Float. - -@item @code{Ada.Float_Wide_Wide_Text_IO} `(A.10.9)' - -A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. - -@item @code{Ada.Integer_Text_IO} `(A.10.9)' - -A library level instantiation of Text_IO.Integer_IO for type Integer. - -@item @code{Ada.Integer_Wide_Text_IO} `(A.10.9)' - -A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. - -@item @code{Ada.Integer_Wide_Wide_Text_IO} `(A.10.9)' - -A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. - -@item @code{Ada.Interrupts} `(C.3.2)' - -This package provides facilities for interfacing to interrupts, which -includes the set of signals or conditions that can be raised and -recognized as interrupts. - -@item @code{Ada.Interrupts.Names} `(C.3.2)' - -This package provides the set of interrupt names (actually signal -or condition names) that can be handled by GNAT. - -@item @code{Ada.IO_Exceptions} `(A.13)' - -This package defines the set of exceptions that can be raised by use of -the standard IO packages. - -@item @code{Ada.Iterator_Interfaces} `(5.5.1)' - -This package provides a generic interface to generalized iterators. - -@item @code{Ada.Locales} `(A.19)' - -This package provides declarations providing information (Language -and Country) about the current locale. - -@item @code{Ada.Numerics} - -This package contains some standard constants and exceptions used -throughout the numerics packages. Note that the constants pi and e are -defined here, and it is better to use these definitions than rolling -your own. - -@item @code{Ada.Numerics.Complex_Arrays} `(G.3.2)' - -Provides operations on arrays of complex numbers. - -@item @code{Ada.Numerics.Complex_Elementary_Functions} - -Provides the implementation of standard elementary functions (such as -log and trigonometric functions) operating on complex numbers using the -standard @code{Float} and the @code{Complex} and @code{Imaginary} types -created by the package @code{Numerics.Complex_Types}. - -@item @code{Ada.Numerics.Complex_Types} - -This is a predefined instantiation of -@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to -build the type @code{Complex} and @code{Imaginary}. - -@item @code{Ada.Numerics.Discrete_Random} - -This generic package provides a random number generator suitable for generating -uniformly distributed values of a specified discrete subtype. - -@item @code{Ada.Numerics.Float_Random} - -This package provides a random number generator suitable for generating -uniformly distributed floating point values in the unit interval. - -@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} - -This is a generic version of the package that provides the -implementation of standard elementary functions (such as log and -trigonometric functions) for an arbitrary complex type. - -The following predefined instantiations of this package are provided: - - -@itemize * - -@item -@code{Short_Float} - -@code{Ada.Numerics.Short_Complex_Elementary_Functions} - -@item -@code{Float} - -@code{Ada.Numerics.Complex_Elementary_Functions} - -@item -@code{Long_Float} - -@code{Ada.Numerics.Long_Complex_Elementary_Functions} -@end itemize - -@item @code{Ada.Numerics.Generic_Complex_Types} - -This is a generic package that allows the creation of complex types, -with associated complex arithmetic operations. - -The following predefined instantiations of this package exist - - -@itemize * - -@item -@code{Short_Float} - -@code{Ada.Numerics.Short_Complex_Complex_Types} - -@item -@code{Float} - -@code{Ada.Numerics.Complex_Complex_Types} - -@item -@code{Long_Float} - -@code{Ada.Numerics.Long_Complex_Complex_Types} -@end itemize - -@item @code{Ada.Numerics.Generic_Elementary_Functions} - -This is a generic package that provides the implementation of standard -elementary functions (such as log an trigonometric functions) for an -arbitrary float type. - -The following predefined instantiations of this package exist - - -@itemize * - -@item -@code{Short_Float} - -@code{Ada.Numerics.Short_Elementary_Functions} - -@item -@code{Float} - -@code{Ada.Numerics.Elementary_Functions} - -@item -@code{Long_Float} - -@code{Ada.Numerics.Long_Elementary_Functions} -@end itemize - -@item @code{Ada.Numerics.Generic_Real_Arrays} `(G.3.1)' - -Generic operations on arrays of reals - -@item @code{Ada.Numerics.Real_Arrays} `(G.3.1)' - -Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). - -@item @code{Ada.Real_Time} `(D.8)' - -This package provides facilities similar to those of @code{Calendar}, but -operating with a finer clock suitable for real time control. Note that -annex D requires that there be no backward clock jumps, and GNAT generally -guarantees this behavior, but of course if the external clock on which -the GNAT runtime depends is deliberately reset by some external event, -then such a backward jump may occur. - -@item @code{Ada.Real_Time.Timing_Events} `(D.15)' - -Not implemented in GNAT. - -@item @code{Ada.Sequential_IO} `(A.8.1)' - -This package provides input-output facilities for sequential files, -which can contain a sequence of values of a single type, which can be -any Ada type, including indefinite (unconstrained) types. - -@item @code{Ada.Storage_IO} `(A.9)' - -This package provides a facility for mapping arbitrary Ada types to and -from a storage buffer. It is primarily intended for the creation of new -IO packages. - -@item @code{Ada.Streams} `(13.13.1)' - -This is a generic package that provides the basic support for the -concept of streams as used by the stream attributes (@code{Input}, -@code{Output}, @code{Read} and @code{Write}). - -@item @code{Ada.Streams.Stream_IO} `(A.12.1)' - -This package is a specialization of the type @code{Streams} defined in -package @code{Streams} together with a set of operations providing -Stream_IO capability. The Stream_IO model permits both random and -sequential access to a file which can contain an arbitrary set of values -of one or more Ada types. - -@item @code{Ada.Strings} `(A.4.1)' - -This package provides some basic constants used by the string handling -packages. - -@item @code{Ada.Strings.Bounded} `(A.4.4)' - -This package provides facilities for handling variable length -strings. The bounded model requires a maximum length. It is thus -somewhat more limited than the unbounded model, but avoids the use of -dynamic allocation or finalization. - -@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} `(A.4.10)' - -Provides case-insensitive comparisons of bounded strings - -@item @code{Ada.Strings.Bounded.Hash} `(A.4.9)' - -This package provides a generic hash function for bounded strings - -@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} `(A.4.9)' - -This package provides a generic hash function for bounded strings that -converts the string to be hashed to lower case. - -@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} `(A.4.10)' - -This package provides a comparison function for bounded strings that works -in a case insensitive manner by converting to lower case before the comparison. - -@item @code{Ada.Strings.Fixed} `(A.4.3)' - -This package provides facilities for handling fixed length strings. - -@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} `(A.4.10)' - -This package provides an equality function for fixed strings that compares -the strings after converting both to lower case. - -@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} `(A.4.9)' - -This package provides a case insensitive hash function for fixed strings that -converts the string to lower case before computing the hash. - -@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} `(A.4.10)' - -This package provides a comparison function for fixed strings that works -in a case insensitive manner by converting to lower case before the comparison. - -@item @code{Ada.Strings.Hash} `(A.4.9)' - -This package provides a hash function for strings. - -@item @code{Ada.Strings.Hash_Case_Insensitive} `(A.4.9)' - -This package provides a hash function for strings that is case insensitive. -The string is converted to lower case before computing the hash. - -@item @code{Ada.Strings.Less_Case_Insensitive} `(A.4.10)' - -This package provides a comparison function for\strings that works -in a case insensitive manner by converting to lower case before the comparison. - -@item @code{Ada.Strings.Maps} `(A.4.2)' - -This package provides facilities for handling character mappings and -arbitrarily defined subsets of characters. For instance it is useful in -defining specialized translation tables. - -@item @code{Ada.Strings.Maps.Constants} `(A.4.6)' - -This package provides a standard set of predefined mappings and -predefined character sets. For example, the standard upper to lower case -conversion table is found in this package. Note that upper to lower case -conversion is non-trivial if you want to take the entire set of -characters, including extended characters like E with an acute accent, -into account. You should use the mappings in this package (rather than -adding 32 yourself) to do case mappings. - -@item @code{Ada.Strings.Unbounded} `(A.4.5)' - -This package provides facilities for handling variable length -strings. The unbounded model allows arbitrary length strings, but -requires the use of dynamic allocation and finalization. - -@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} `(A.4.10)' - -Provides case-insensitive comparisons of unbounded strings - -@item @code{Ada.Strings.Unbounded.Hash} `(A.4.9)' - -This package provides a generic hash function for unbounded strings - -@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} `(A.4.9)' - -This package provides a generic hash function for unbounded strings that -converts the string to be hashed to lower case. - -@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} `(A.4.10)' - -This package provides a comparison function for unbounded strings that works -in a case insensitive manner by converting to lower case before the comparison. - -@item @code{Ada.Strings.UTF_Encoding} `(A.4.11)' - -This package provides basic definitions for dealing with UTF-encoded strings. - -@item @code{Ada.Strings.UTF_Encoding.Conversions} `(A.4.11)' - -This package provides conversion functions for UTF-encoded strings. -@end table - -@code{Ada.Strings.UTF_Encoding.Strings} `(A.4.11)' - -@code{Ada.Strings.UTF_Encoding.Wide_Strings} `(A.4.11)' - - -@table @asis - -@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} `(A.4.11)' - -These packages provide facilities for handling UTF encodings for -Strings, Wide_Strings and Wide_Wide_Strings. -@end table - -@code{Ada.Strings.Wide_Bounded} `(A.4.7)' - -@code{Ada.Strings.Wide_Fixed} `(A.4.7)' - -@code{Ada.Strings.Wide_Maps} `(A.4.7)' - - -@table @asis - -@item @code{Ada.Strings.Wide_Unbounded} `(A.4.7)' - -These packages provide analogous capabilities to the corresponding -packages without @code{Wide_} in the name, but operate with the types -@code{Wide_String} and @code{Wide_Character} instead of @code{String} -and @code{Character}. Versions of all the child packages are available. -@end table - -@code{Ada.Strings.Wide_Wide_Bounded} `(A.4.7)' - -@code{Ada.Strings.Wide_Wide_Fixed} `(A.4.7)' - -@code{Ada.Strings.Wide_Wide_Maps} `(A.4.7)' - - -@table @asis - -@item @code{Ada.Strings.Wide_Wide_Unbounded} `(A.4.7)' - -These packages provide analogous capabilities to the corresponding -packages without @code{Wide_} in the name, but operate with the types -@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead -of @code{String} and @code{Character}. - -@item @code{Ada.Synchronous_Barriers} `(D.10.1)' - -This package provides facilities for synchronizing tasks at a low level -with barriers. - -@item @code{Ada.Synchronous_Task_Control} `(D.10)' - -This package provides some standard facilities for controlling task -communication in a synchronous manner. - -@item @code{Ada.Synchronous_Task_Control.EDF} `(D.10)' - -Not implemented in GNAT. - -@item @code{Ada.Tags} - -This package contains definitions for manipulation of the tags of tagged -values. - -@item @code{Ada.Tags.Generic_Dispatching_Constructor} `(3.9)' - -This package provides a way of constructing tagged class-wide values given -only the tag value. - -@item @code{Ada.Task_Attributes} `(C.7.2)' - -This package provides the capability of associating arbitrary -task-specific data with separate tasks. - -@item @code{Ada.Task_Identification} `(C.7.1)' - -This package provides capabilities for task identification. - -@item @code{Ada.Task_Termination} `(C.7.3)' - -This package provides control over task termination. - -@item @code{Ada.Text_IO} - -This package provides basic text input-output capabilities for -character, string and numeric data. The subpackages of this -package are listed next. Note that although these are defined -as subpackages in the RM, they are actually transparently -implemented as child packages in GNAT, meaning that they -are only loaded if needed. - -@item @code{Ada.Text_IO.Decimal_IO} - -Provides input-output facilities for decimal fixed-point types - -@item @code{Ada.Text_IO.Enumeration_IO} - -Provides input-output facilities for enumeration types. - -@item @code{Ada.Text_IO.Fixed_IO} - -Provides input-output facilities for ordinary fixed-point types. - -@item @code{Ada.Text_IO.Float_IO} - -Provides input-output facilities for float types. The following -predefined instantiations of this generic package are available: - - -@itemize * - -@item -@code{Short_Float} - -@code{Short_Float_Text_IO} - -@item -@code{Float} - -@code{Float_Text_IO} - -@item -@code{Long_Float} - -@code{Long_Float_Text_IO} -@end itemize - -@item @code{Ada.Text_IO.Integer_IO} - -Provides input-output facilities for integer types. The following -predefined instantiations of this generic package are available: - - -@itemize * - -@item -@code{Short_Short_Integer} - -@code{Ada.Short_Short_Integer_Text_IO} - -@item -@code{Short_Integer} - -@code{Ada.Short_Integer_Text_IO} - -@item -@code{Integer} - -@code{Ada.Integer_Text_IO} - -@item -@code{Long_Integer} - -@code{Ada.Long_Integer_Text_IO} - -@item -@code{Long_Long_Integer} - -@code{Ada.Long_Long_Integer_Text_IO} -@end itemize - -@item @code{Ada.Text_IO.Modular_IO} - -Provides input-output facilities for modular (unsigned) types. - -@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} - -Provides input-output facilities for bounded strings. - -@item @code{Ada.Text_IO.Complex_IO (G.1.3)} - -This package provides basic text input-output capabilities for complex -data. - -@item @code{Ada.Text_IO.Editing (F.3.3)} - -This package contains routines for edited output, analogous to the use -of pictures in COBOL. The picture formats used by this package are a -close copy of the facility in COBOL. - -@item @code{Ada.Text_IO.Text_Streams (A.12.2)} - -This package provides a facility that allows Text_IO files to be treated -as streams, so that the stream attributes can be used for writing -arbitrary data, including binary data, to Text_IO files. - -@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} - -This package provides input-output facilities for unbounded strings. - -@item @code{Ada.Unchecked_Conversion (13.9)} - -This generic package allows arbitrary conversion from one type to -another of the same size, providing for breaking the type safety in -special circumstances. - -If the types have the same Size (more accurately the same Value_Size), -then the effect is simply to transfer the bits from the source to the -target type without any modification. This usage is well defined, and -for simple types whose representation is typically the same across -all implementations, gives a portable method of performing such -conversions. - -If the types do not have the same size, then the result is implementation -defined, and thus may be non-portable. The following describes how GNAT -handles such unchecked conversion cases. - -If the types are of different sizes, and are both discrete types, then -the effect is of a normal type conversion without any constraint checking. -In particular if the result type has a larger size, the result will be -zero or sign extended. If the result type has a smaller size, the result -will be truncated by ignoring high order bits. - -If the types are of different sizes, and are not both discrete types, -then the conversion works as though pointers were created to the source -and target, and the pointer value is converted. The effect is that bits -are copied from successive low order storage units and bits of the source -up to the length of the target type. - -A warning is issued if the lengths differ, since the effect in this -case is implementation dependent, and the above behavior may not match -that of some other compiler. - -A pointer to one type may be converted to a pointer to another type using -unchecked conversion. The only case in which the effect is undefined is -when one or both pointers are pointers to unconstrained array types. In -this case, the bounds information may get incorrectly transferred, and in -particular, GNAT uses double size pointers for such types, and it is -meaningless to convert between such pointer types. GNAT will issue a -warning if the alignment of the target designated type is more strict -than the alignment of the source designated type (since the result may -be unaligned in this case). - -A pointer other than a pointer to an unconstrained array type may be -converted to and from System.Address. Such usage is common in Ada 83 -programs, but note that Ada.Address_To_Access_Conversions is the -preferred method of performing such conversions in Ada 95 and Ada 2005. -Neither -unchecked conversion nor Ada.Address_To_Access_Conversions should be -used in conjunction with pointers to unconstrained objects, since -the bounds information cannot be handled correctly in this case. - -@item @code{Ada.Unchecked_Deallocation} `(13.11.2)' - -This generic package allows explicit freeing of storage previously -allocated by use of an allocator. - -@item @code{Ada.Wide_Text_IO} `(A.11)' - -This package is similar to @code{Ada.Text_IO}, except that the external -file supports wide character representations, and the internal types are -@code{Wide_Character} and @code{Wide_String} instead of @code{Character} -and @code{String}. The corresponding set of nested packages and child -packages are defined. - -@item @code{Ada.Wide_Wide_Text_IO} `(A.11)' - -This package is similar to @code{Ada.Text_IO}, except that the external -file supports wide character representations, and the internal types are -@code{Wide_Character} and @code{Wide_String} instead of @code{Character} -and @code{String}. The corresponding set of nested packages and child -packages are defined. -@end table - -For packages in Interfaces and System, all the RM defined packages are -available in GNAT, see the Ada 2012 RM for full details. - -@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top -@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f} -@chapter The Implementation of Standard I/O - - -GNAT implements all the required input-output facilities described in -A.6 through A.14. These sections of the Ada Reference Manual describe the -required behavior of these packages from the Ada point of view, and if -you are writing a portable Ada program that does not need to know the -exact manner in which Ada maps to the outside world when it comes to -reading or writing external files, then you do not need to read this -chapter. As long as your files are all regular files (not pipes or -devices), and as long as you write and read the files only from Ada, the -description in the Ada Reference Manual is sufficient. - -However, if you want to do input-output to pipes or other devices, such -as the keyboard or screen, or if the files you are dealing with are -either generated by some other language, or to be read by some other -language, then you need to know more about the details of how the GNAT -implementation of these input-output facilities behaves. - -In this chapter we give a detailed description of exactly how GNAT -interfaces to the file system. As always, the sources of the system are -available to you for answering questions at an even more detailed level, -but for most purposes the information in this chapter will suffice. - -Another reason that you may need to know more about how input-output is -implemented arises when you have a program written in mixed languages -where, for example, files are shared between the C and Ada sections of -the same program. GNAT provides some additional facilities, in the form -of additional child library packages, that facilitate this sharing, and -these additional facilities are also described in this chapter. - -@menu -* Standard I/O Packages:: -* FORM Strings:: -* Direct_IO:: -* Sequential_IO:: -* Text_IO:: -* Wide_Text_IO:: -* Wide_Wide_Text_IO:: -* Stream_IO:: -* Text Translation:: -* Shared Files:: -* Filenames encoding:: -* File content encoding:: -* Open Modes:: -* Operations on C Streams:: -* Interfacing to C Streams:: - -@end menu - -@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a4} -@section Standard I/O Packages - - -The Standard I/O packages described in Annex A for - - -@itemize * - -@item -Ada.Text_IO - -@item -Ada.Text_IO.Complex_IO - -@item -Ada.Text_IO.Text_Streams - -@item -Ada.Wide_Text_IO - -@item -Ada.Wide_Text_IO.Complex_IO - -@item -Ada.Wide_Text_IO.Text_Streams - -@item -Ada.Wide_Wide_Text_IO - -@item -Ada.Wide_Wide_Text_IO.Complex_IO - -@item -Ada.Wide_Wide_Text_IO.Text_Streams - -@item -Ada.Stream_IO - -@item -Ada.Sequential_IO - -@item -Ada.Direct_IO -@end itemize - -are implemented using the C -library streams facility; where - - -@itemize * - -@item -All files are opened using @code{fopen}. - -@item -All input/output operations use @code{fread}/@cite{fwrite}. -@end itemize - -There is no internal buffering of any kind at the Ada library level. The only -buffering is that provided at the system level in the implementation of the -library routines that support streams. This facilitates shared use of these -streams by mixed language programs. Note though that system level buffering is -explicitly enabled at elaboration of the standard I/O packages and that can -have an impact on mixed language programs, in particular those using I/O before -calling the Ada elaboration routine (e.g., adainit). It is recommended to call -the Ada elaboration routine before performing any I/O or when impractical, -flush the common I/O streams and in particular Standard_Output before -elaborating the Ada code. - -@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a6} -@section FORM Strings - - -The format of a FORM string in GNAT is: - -@example -"keyword=value,keyword=value,...,keyword=value" -@end example - -where letters may be in upper or lower case, and there are no spaces -between values. The order of the entries is not important. Currently -the following keywords defined. - -@example -TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] -SHARED=[YES|NO] -WCEM=[n|h|u|s|e|8|b] -ENCODING=[UTF8|8BITS] -@end example - -The use of these parameters is described later in this section. If an -unrecognized keyword appears in a form string, it is silently ignored -and not considered invalid. - -@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a8} -@section Direct_IO - - -Direct_IO can only be instantiated for definite types. This is a -restriction of the Ada language, which means that the records are fixed -length (the length being determined by @code{type'Size}, rounded -up to the next storage unit boundary if necessary). - -The records of a Direct_IO file are simply written to the file in index -sequence, with the first record starting at offset zero, and subsequent -records following. There is no control information of any kind. For -example, if 32-bit integers are being written, each record takes -4-bytes, so the record at index @code{K} starts at offset -(@code{K}-1)*4. - -There is no limit on the size of Direct_IO files, they are expanded as -necessary to accommodate whatever records are written to the file. - -@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2aa} -@section Sequential_IO - - -Sequential_IO may be instantiated with either a definite (constrained) -or indefinite (unconstrained) type. - -For the definite type case, the elements written to the file are simply -the memory images of the data values with no control information of any -kind. The resulting file should be read using the same type, no validity -checking is performed on input. - -For the indefinite type case, the elements written consist of two -parts. First is the size of the data item, written as the memory image -of a @code{Interfaces.C.size_t} value, followed by the memory image of -the data value. The resulting file can only be read using the same -(unconstrained) type. Normal assignment checks are performed on these -read operations, and if these checks fail, @code{Data_Error} is -raised. In particular, in the array case, the lengths must match, and in -the variant record case, if the variable for a particular read operation -is constrained, the discriminants must match. - -Note that it is not possible to use Sequential_IO to write variable -length array items, and then read the data back into different length -arrays. For example, the following will raise @code{Data_Error}: - -@example -package IO is new Sequential_IO (String); -F : IO.File_Type; -S : String (1..4); -... -IO.Create (F) -IO.Write (F, "hello!") -IO.Reset (F, Mode=>In_File); -IO.Read (F, S); -Put_Line (S); -@end example - -On some Ada implementations, this will print @code{hell}, but the program is -clearly incorrect, since there is only one element in the file, and that -element is the string @code{hello!}. - -In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved -using Stream_IO, and this is the preferred mechanism. In particular, the -above program fragment rewritten to use Stream_IO will work correctly. - -@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ac} -@section Text_IO - - -Text_IO files consist of a stream of characters containing the following -special control characters: - -@example -LF (line feed, 16#0A#) Line Mark -FF (form feed, 16#0C#) Page Mark -@end example - -A canonical Text_IO file is defined as one in which the following -conditions are met: - - -@itemize * - -@item -The character @code{LF} is used only as a line mark, i.e., to mark the end -of the line. - -@item -The character @code{FF} is used only as a page mark, i.e., to mark the -end of a page and consequently can appear only immediately following a -@code{LF} (line mark) character. - -@item -The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} -(line mark, page mark). In the former case, the page mark is implicitly -assumed to be present. -@end itemize - -A file written using Text_IO will be in canonical form provided that no -explicit @code{LF} or @code{FF} characters are written using @code{Put} -or @code{Put_Line}. There will be no @code{FF} character at the end of -the file unless an explicit @code{New_Page} operation was performed -before closing the file. - -A canonical Text_IO file that is a regular file (i.e., not a device or a -pipe) can be read using any of the routines in Text_IO. The -semantics in this case will be exactly as defined in the Ada Reference -Manual, and all the routines in Text_IO are fully implemented. - -A text file that does not meet the requirements for a canonical Text_IO -file has one of the following: - - -@itemize * - -@item -The file contains @code{FF} characters not immediately following a -@code{LF} character. - -@item -The file contains @code{LF} or @code{FF} characters written by -@code{Put} or @code{Put_Line}, which are not logically considered to be -line marks or page marks. - -@item -The file ends in a character other than @code{LF} or @code{FF}, -i.e., there is no explicit line mark or page mark at the end of the file. -@end itemize - -Text_IO can be used to read such non-standard text files but subprograms -to do with line or page numbers do not have defined meanings. In -particular, a @code{FF} character that does not follow a @code{LF} -character may or may not be treated as a page mark from the point of -view of page and line numbering. Every @code{LF} character is considered -to end a line, and there is an implied @code{LF} character at the end of -the file. - -@menu -* Stream Pointer Positioning:: -* Reading and Writing Non-Regular Files:: -* Get_Immediate:: -* Treating Text_IO Files as Streams:: -* Text_IO Extensions:: -* Text_IO Facilities for Unbounded Strings:: - -@end menu - -@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ae} -@subsection Stream Pointer Positioning - - -@code{Ada.Text_IO} has a definition of current position for a file that -is being read. No internal buffering occurs in Text_IO, and usually the -physical position in the stream used to implement the file corresponds -to this logical position defined by Text_IO. There are two exceptions: - - -@itemize * - -@item -After a call to @code{End_Of_Page} that returns @code{True}, the stream -is positioned past the @code{LF} (line mark) that precedes the page -mark. Text_IO maintains an internal flag so that subsequent read -operations properly handle the logical position which is unchanged by -the @code{End_Of_Page} call. - -@item -After a call to @code{End_Of_File} that returns @code{True}, if the -Text_IO file was positioned before the line mark at the end of file -before the call, then the logical position is unchanged, but the stream -is physically positioned right at the end of file (past the line mark, -and past a possible page mark following the line mark. Again Text_IO -maintains internal flags so that subsequent read operations properly -handle the logical position. -@end itemize - -These discrepancies have no effect on the observable behavior of -Text_IO, but if a single Ada stream is shared between a C program and -Ada program, or shared (using @code{shared=yes} in the form string) -between two Ada files, then the difference may be observable in some -situations. - -@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b0} -@subsection Reading and Writing Non-Regular Files - - -A non-regular file is a device (such as a keyboard), or a pipe. Text_IO -can be used for reading and writing. Writing is not affected and the -sequence of characters output is identical to the normal file case, but -for reading, the behavior of Text_IO is modified to avoid undesirable -look-ahead as follows: - -An input file that is not a regular file is considered to have no page -marks. Any @code{Ascii.FF} characters (the character normally used for a -page mark) appearing in the file are considered to be data -characters. In particular: - - -@itemize * - -@item -@code{Get_Line} and @code{Skip_Line} do not test for a page mark -following a line mark. If a page mark appears, it will be treated as a -data character. - -@item -This avoids the need to wait for an extra character to be typed or -entered from the pipe to complete one of these operations. - -@item -@code{End_Of_Page} always returns @code{False} - -@item -@code{End_Of_File} will return @code{False} if there is a page mark at -the end of the file. -@end itemize - -Output to non-regular files is the same as for regular files. Page marks -may be written to non-regular files using @code{New_Page}, but as noted -above they will not be treated as page marks on input if the output is -piped to another Ada program. - -Another important discrepancy when reading non-regular files is that the end -of file indication is not ‘sticky’. If an end of file is entered, e.g., by -pressing the @code{EOT} key, -then end of file -is signaled once (i.e., the test @code{End_Of_File} -will yield @code{True}, or a read will -raise @code{End_Error}), but then reading can resume -to read data past that end of -file indication, until another end of file indication is entered. - -@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b2} -@subsection Get_Immediate - - -@geindex Get_Immediate - -Get_Immediate returns the next character (including control characters) -from the input file. In particular, Get_Immediate will return LF or FF -characters used as line marks or page marks. Such operations leave the -file positioned past the control character, and it is thus not treated -as having its normal function. This means that page, line and column -counts after this kind of Get_Immediate call are set as though the mark -did not occur. In the case where a Get_Immediate leaves the file -positioned between the line mark and page mark (which is not normally -possible), it is undefined whether the FF character will be treated as a -page mark. - -@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b4} -@subsection Treating Text_IO Files as Streams - - -@geindex Stream files - -The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated -as a stream. Data written to a @code{Text_IO} file in this stream mode is -binary data. If this binary data contains bytes 16#0A# (@code{LF}) or -16#0C# (@code{FF}), the resulting file may have non-standard -format. Similarly if read operations are used to read from a Text_IO -file treated as a stream, then @code{LF} and @code{FF} characters may be -skipped and the effect is similar to that described above for -@code{Get_Immediate}. - -@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b6} -@subsection Text_IO Extensions - - -@geindex Text_IO extensions - -A package GNAT.IO_Aux in the GNAT library provides some useful extensions -to the standard @code{Text_IO} package: - - -@itemize * - -@item -function File_Exists (Name : String) return Boolean; -Determines if a file of the given name exists. - -@item -function Get_Line return String; -Reads a string from the standard input file. The value returned is exactly -the length of the line that was read. - -@item -function Get_Line (File : Ada.Text_IO.File_Type) return String; -Similar, except that the parameter File specifies the file from which -the string is to be read. -@end itemize - -@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b8} -@subsection Text_IO Facilities for Unbounded Strings - - -@geindex Text_IO for unbounded strings - -@geindex Unbounded_String -@geindex Text_IO operations - -The package @code{Ada.Strings.Unbounded.Text_IO} -in library files @code{a-suteio.ads/adb} contains some GNAT-specific -subprograms useful for Text_IO operations on unbounded strings: - - -@itemize * - -@item -function Get_Line (File : File_Type) return Unbounded_String; -Reads a line from the specified file -and returns the result as an unbounded string. - -@item -procedure Put (File : File_Type; U : Unbounded_String); -Writes the value of the given unbounded string to the specified file -Similar to the effect of -@code{Put (To_String (U))} except that an extra copy is avoided. - -@item -procedure Put_Line (File : File_Type; U : Unbounded_String); -Writes the value of the given unbounded string to the specified file, -followed by a @code{New_Line}. -Similar to the effect of @code{Put_Line (To_String (U))} except -that an extra copy is avoided. -@end itemize - -In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} -and is optional. If the parameter is omitted, then the standard input or -output file is referenced as appropriate. - -The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library -files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended -@code{Wide_Text_IO} functionality for unbounded wide strings. - -The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library -files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended -@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. - -@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ba} -@section Wide_Text_IO - - -@code{Wide_Text_IO} is similar in most respects to Text_IO, except that -both input and output files may contain special sequences that represent -wide character values. The encoding scheme for a given file may be -specified using a FORM parameter: - -@example -WCEM=`x` -@end example - -as part of the FORM string (WCEM = wide character encoding method), -where @code{x} is one of the following characters - - -@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Character - -@tab - -Encoding - -@item - -`h' - -@tab - -Hex ESC encoding - -@item - -`u' - -@tab - -Upper half encoding - -@item - -`s' - -@tab - -Shift-JIS encoding - -@item - -`e' - -@tab - -EUC Encoding - -@item - -`8' - -@tab - -UTF-8 encoding - -@item - -`b' - -@tab - -Brackets encoding - -@end multitable - - -The encoding methods match those that -can be used in a source -program, but there is no requirement that the encoding method used for -the source program be the same as the encoding method used for files, -and different files may use different encoding methods. - -The default encoding method for the standard files, and for opened files -for which no WCEM parameter is given in the FORM string matches the -wide character encoding specified for the main program (the default -being brackets encoding if no coding method was specified with -gnatW). - - -@table @asis - -@item `Hex Coding' - -In this encoding, a wide character is represented by a five character -sequence: -@end table - -@example -ESC a b c d -@end example - - -@quotation - -where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal -characters (using upper case letters) of the wide character code. For -example, ESC A345 is used to represent the wide character with code -16#A345#. This scheme is compatible with use of the full -@code{Wide_Character} set. -@end quotation - - -@table @asis - -@item `Upper Half Coding' - -The wide character with encoding 16#abcd#, where the upper bit is on -(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and -16#cd#. The second byte may never be a format control character, but is -not required to be in the upper half. This method can be also used for -shift-JIS or EUC where the internal coding matches the external coding. - -@item `Shift JIS Coding' - -A wide character is represented by a two character sequence 16#ab# and -16#cd#, with the restrictions described for upper half encoding as -described above. The internal character code is the corresponding JIS -character according to the standard algorithm for Shift-JIS -conversion. Only characters defined in the JIS code set table can be -used with this encoding method. - -@item `EUC Coding' - -A wide character is represented by a two character sequence 16#ab# and -16#cd#, with both characters being in the upper half. The internal -character code is the corresponding JIS character according to the EUC -encoding algorithm. Only characters defined in the JIS code set table -can be used with this encoding method. - -@item `UTF-8 Coding' - -A wide character is represented using -UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO -10646-1/Am.2. Depending on the character value, the representation -is a one, two, or three byte sequence: -@end table - -@example -16#0000#-16#007f#: 2#0xxxxxxx# -16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# -16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# -@end example - - -@quotation - -where the @code{xxx} bits correspond to the left-padded bits of the -16-bit character value. Note that all lower half ASCII characters -are represented as ASCII bytes and all upper half characters and -other wide characters are represented as sequences of upper-half -(The full UTF-8 scheme allows for encoding 31-bit characters as -6-byte sequences, but in this implementation, all UTF-8 sequences -of four or more bytes length will raise a Constraint_Error, as -will all invalid UTF-8 sequences.) -@end quotation - - -@table @asis - -@item `Brackets Coding' - -In this encoding, a wide character is represented by the following eight -character sequence: -@end table - -@example -[ " a b c d " ] -@end example - - -@quotation - -where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal -characters (using uppercase letters) of the wide character code. For -example, @code{["A345"]} is used to represent the wide character with code -@code{16#A345#}. -This scheme is compatible with use of the full Wide_Character set. -On input, brackets coding can also be used for upper half characters, -e.g., @code{["C1"]} for lower case a. However, on output, brackets notation -is only used for wide characters with a code greater than @code{16#FF#}. - -Note that brackets coding is not normally used in the context of -Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as -a portable way of encoding source files. In the context of Wide_Text_IO -or Wide_Wide_Text_IO, it can only be used if the file does not contain -any instance of the left bracket character other than to encode wide -character values using the brackets encoding method. In practice it is -expected that some standard wide character encoding method such -as UTF-8 will be used for text input output. - -If brackets notation is used, then any occurrence of a left bracket -in the input file which is not the start of a valid wide character -sequence will cause Constraint_Error to be raised. It is possible to -encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO -input will interpret this as a left bracket. - -However, when a left bracket is output, it will be output as a left bracket -and not as [“5B”]. We make this decision because for normal use of -Wide_Text_IO for outputting messages, it is unpleasant to clobber left -brackets. For example, if we write: - -@example -Put_Line ("Start of output [first run]"); -@end example - -we really do not want to have the left bracket in this message clobbered so -that the output reads: -@end quotation - -@example -Start of output ["5B"]first run] -@end example - - -@quotation - -In practice brackets encoding is reasonably useful for normal Put_Line use -since we won’t get confused between left brackets and wide character -sequences in the output. But for input, or when files are written out -and read back in, it really makes better sense to use one of the standard -encoding methods such as UTF-8. -@end quotation - -For the coding schemes other than UTF-8, Hex, or Brackets encoding, -not all wide character -values can be represented. An attempt to output a character that cannot -be represented using the encoding scheme for the file causes -Constraint_Error to be raised. An invalid wide character sequence on -input also causes Constraint_Error to be raised. - -@menu -* Stream Pointer Positioning: Stream Pointer Positioning<2>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. - -@end menu - -@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2bc} -@subsection Stream Pointer Positioning - - -@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling -of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional -case: - -If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the -normal lower ASCII set, i.e. a character in the range: - -@example -Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) -@end example - -then although the logical position of the file pointer is unchanged by -the @code{Look_Ahead} call, the stream is physically positioned past the -wide character sequence. Again this is to avoid the need for buffering -or backup, and all @code{Wide_Text_IO} routines check the internal -indication that this situation has occurred so that this is not visible -to a normal program using @code{Wide_Text_IO}. However, this discrepancy -can be observed if the wide text file shares a stream with another file. - -@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2be} -@subsection Reading and Writing Non-Regular Files - - -As in the case of Text_IO, when a non-regular file is read, it is -assumed that the file contains no page marks (any form characters are -treated as data characters), and @code{End_Of_Page} always returns -@code{False}. Similarly, the end of file indication is not sticky, so -it is possible to read beyond an end of file. - -@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c0} -@section Wide_Wide_Text_IO - - -@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that -both input and output files may contain special sequences that represent -wide wide character values. The encoding scheme for a given file may be -specified using a FORM parameter: - -@example -WCEM=`x` -@end example - -as part of the FORM string (WCEM = wide character encoding method), -where @code{x} is one of the following characters - - -@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Character - -@tab - -Encoding - -@item - -`h' - -@tab - -Hex ESC encoding - -@item - -`u' - -@tab - -Upper half encoding - -@item - -`s' - -@tab - -Shift-JIS encoding - -@item - -`e' - -@tab - -EUC Encoding - -@item - -`8' - -@tab - -UTF-8 encoding - -@item - -`b' - -@tab - -Brackets encoding - -@end multitable - - -The encoding methods match those that -can be used in a source -program, but there is no requirement that the encoding method used for -the source program be the same as the encoding method used for files, -and different files may use different encoding methods. - -The default encoding method for the standard files, and for opened files -for which no WCEM parameter is given in the FORM string matches the -wide character encoding specified for the main program (the default -being brackets encoding if no coding method was specified with -gnatW). - - -@table @asis - -@item `UTF-8 Coding' - -A wide character is represented using -UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO -10646-1/Am.2. Depending on the character value, the representation -is a one, two, three, or four byte sequence: -@end table - -@example -16#000000#-16#00007f#: 2#0xxxxxxx# -16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# -16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# -16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# -@end example - - -@quotation - -where the @code{xxx} bits correspond to the left-padded bits of the -21-bit character value. Note that all lower half ASCII characters -are represented as ASCII bytes and all upper half characters and -other wide characters are represented as sequences of upper-half -characters. -@end quotation - - -@table @asis - -@item `Brackets Coding' - -In this encoding, a wide wide character is represented by the following eight -character sequence if is in wide character range -@end table - -@example -[ " a b c d " ] -@end example - - -@quotation - -and by the following ten character sequence if not -@end quotation - -@example -[ " a b c d e f " ] -@end example - - -@quotation - -where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} -are the four or six hexadecimal -characters (using uppercase letters) of the wide wide character code. For -example, @code{["01A345"]} is used to represent the wide wide character -with code @code{16#01A345#}. - -This scheme is compatible with use of the full Wide_Wide_Character set. -On input, brackets coding can also be used for upper half characters, -e.g., @code{["C1"]} for lower case a. However, on output, brackets notation -is only used for wide characters with a code greater than @code{16#FF#}. -@end quotation - -If is also possible to use the other Wide_Character encoding methods, -such as Shift-JIS, but the other schemes cannot support the full range -of wide wide characters. -An attempt to output a character that cannot -be represented using the encoding scheme for the file causes -Constraint_Error to be raised. An invalid wide character sequence on -input also causes Constraint_Error to be raised. - -@menu -* Stream Pointer Positioning: Stream Pointer Positioning<3>. -* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. - -@end menu - -@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c2} -@subsection Stream Pointer Positioning - - -@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling -of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional -case: - -If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the -normal lower ASCII set, i.e. a character in the range: - -@example -Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) -@end example - -then although the logical position of the file pointer is unchanged by -the @code{Look_Ahead} call, the stream is physically positioned past the -wide character sequence. Again this is to avoid the need for buffering -or backup, and all @code{Wide_Wide_Text_IO} routines check the internal -indication that this situation has occurred so that this is not visible -to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy -can be observed if the wide text file shares a stream with another file. - -@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO -@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c4} -@subsection Reading and Writing Non-Regular Files - - -As in the case of Text_IO, when a non-regular file is read, it is -assumed that the file contains no page marks (any form characters are -treated as data characters), and @code{End_Of_Page} always returns -@code{False}. Similarly, the end of file indication is not sticky, so -it is possible to read beyond an end of file. - -@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c6} -@section Stream_IO - - -A stream file is a sequence of bytes, where individual elements are -written to the file as described in the Ada Reference Manual. The type -@code{Stream_Element} is simply a byte. There are two ways to read or -write a stream file. - - -@itemize * - -@item -The operations @code{Read} and @code{Write} directly read or write a -sequence of stream elements with no control information. - -@item -The stream attributes applied to a stream file transfer data in the -manner described for stream attributes. -@end itemize - -@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c8} -@section Text Translation - - -@code{Text_Translation=xxx} may be used as the Form parameter -passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} -has no effect on Unix systems. Possible values are: - - -@itemize * - -@item -@code{Yes} or @code{Text} is the default, which means to -translate LF to/from CR/LF on Windows systems. - -@code{No} disables this translation; i.e. it -uses binary mode. For output files, @code{Text_Translation=No} -may be used to create Unix-style files on -Windows. - -@item -@code{wtext} translation enabled in Unicode mode. -(corresponds to _O_WTEXT). - -@item -@code{u8text} translation enabled in Unicode UTF-8 mode. -(corresponds to O_U8TEXT). - -@item -@code{u16text} translation enabled in Unicode UTF-16 -mode. (corresponds to_O_U16TEXT). -@end itemize - -@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2ca} -@section Shared Files - - -Section A.14 of the Ada Reference Manual allows implementations to -provide a wide variety of behavior if an attempt is made to access the -same external file with two or more internal files. - -To provide a full range of functionality, while at the same time -minimizing the problems of portability caused by this implementation -dependence, GNAT handles file sharing as follows: - - -@itemize * - -@item -In the absence of a @code{shared=xxx} form parameter, an attempt -to open two or more files with the same full name is considered an error -and is not supported. The exception @code{Use_Error} will be -raised. Note that a file that is not explicitly closed by the program -remains open until the program terminates. - -@item -If the form parameter @code{shared=no} appears in the form string, the -file can be opened or created with its own separate stream identifier, -regardless of whether other files sharing the same external file are -opened. The exact effect depends on how the C stream routines handle -multiple accesses to the same external files using separate streams. - -@item -If the form parameter @code{shared=yes} appears in the form string for -each of two or more files opened using the same full name, the same -stream is shared between these files, and the semantics are as described -in Ada Reference Manual, Section A.14. -@end itemize - -When a program that opens multiple files with the same name is ported -from another Ada compiler to GNAT, the effect will be that -@code{Use_Error} is raised. - -The documentation of the original compiler and the documentation of the -program should then be examined to determine if file sharing was -expected, and @code{shared=xxx} parameters added to @code{Open} -and @code{Create} calls as required. - -When a program is ported from GNAT to some other Ada compiler, no -special attention is required unless the @code{shared=xxx} form -parameter is used in the program. In this case, you must examine the -documentation of the new compiler to see if it supports the required -file sharing semantics, and form strings modified appropriately. Of -course it may be the case that the program cannot be ported if the -target compiler does not support the required functionality. The best -approach in writing portable code is to avoid file sharing (and hence -the use of the @code{shared=xxx} parameter in the form string) -completely. - -One common use of file sharing in Ada 83 is the use of instantiations of -Sequential_IO on the same file with different types, to achieve -heterogeneous input-output. Although this approach will work in GNAT if -@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO -for this purpose (using the stream attributes) - -@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cc} -@section Filenames encoding - - -An encoding form parameter can be used to specify the filename -encoding @code{encoding=xxx}. - - -@itemize * - -@item -If the form parameter @code{encoding=utf8} appears in the form string, the -filename must be encoded in UTF-8. - -@item -If the form parameter @code{encoding=8bits} appears in the form -string, the filename must be a standard 8bits string. -@end itemize - -In the absence of a @code{encoding=xxx} form parameter, the -encoding is controlled by the @code{GNAT_CODE_PAGE} environment -variable. And if not set @code{utf8} is assumed. - - -@table @asis - -@item `CP_ACP' - -The current system Windows ANSI code page. - -@item `CP_UTF8' - -UTF-8 encoding -@end table - -This encoding form parameter is only supported on the Windows -platform. On the other Operating Systems the run-time is supporting -UTF-8 natively. - -@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2ce} -@section File content encoding - - -For text files it is possible to specify the encoding to use. This is -controlled by the by the @code{GNAT_CCS_ENCODING} environment -variable. And if not set @code{TEXT} is assumed. - -The possible values are those supported on Windows: - - -@table @asis - -@item `TEXT' - -Translated text mode - -@item `WTEXT' - -Translated unicode encoding - -@item `U16TEXT' - -Unicode 16-bit encoding - -@item `U8TEXT' - -Unicode 8-bit encoding -@end table - -This encoding is only supported on the Windows platform. - -@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d0} -@section Open Modes - - -@code{Open} and @code{Create} calls result in a call to @code{fopen} -using the mode shown in the following table: - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} -@headitem - -@code{Open} and @code{Create} Call Modes - -@tab - -@tab - -@item - -@tab - -`OPEN' - -@tab - -`CREATE' - -@item - -Append_File - -@tab - -“r+” - -@tab - -“w+” - -@item - -In_File - -@tab - -“r” - -@tab - -“w+” - -@item - -Out_File (Direct_IO) - -@tab - -“r+” - -@tab - -“w” - -@item - -Out_File (all other cases) - -@tab - -“w” - -@tab - -“w” - -@item - -Inout_File - -@tab - -“r+” - -@tab - -“w+” - -@end multitable - - -If text file translation is required, then either @code{b} or @code{t} -is added to the mode, depending on the setting of Text. Text file -translation refers to the mapping of CR/LF sequences in an external file -to LF characters internally. This mapping only occurs in DOS and -DOS-like systems, and is not relevant to other systems. - -A special case occurs with Stream_IO. As shown in the above table, the -file is initially opened in @code{r} or @code{w} mode for the -@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation -subsequently requires switching from reading to writing or vice-versa, -then the file is reopened in @code{r+} mode to permit the required operation. - -@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d2} -@section Operations on C Streams - - -The package @code{Interfaces.C_Streams} provides an Ada program with direct -access to the C library functions for operations on C streams: - -@example -package Interfaces.C_Streams is - -- Note: the reason we do not use the types that are in - -- Interfaces.C is that we want to avoid dragging in the - -- code in this unit if possible. - subtype chars is System.Address; - -- Pointer to null-terminated array of characters - subtype FILEs is System.Address; - -- Corresponds to the C type FILE* - subtype voids is System.Address; - -- Corresponds to the C type void* - subtype int is Integer; - subtype long is Long_Integer; - -- Note: the above types are subtypes deliberately, and it - -- is part of this spec that the above correspondences are - -- guaranteed. This means that it is legitimate to, for - -- example, use Integer instead of int. We provide these - -- synonyms for clarity, but in some cases it may be - -- convenient to use the underlying types (for example to - -- avoid an unnecessary dependency of a spec on the spec - -- of this unit). - type size_t is mod 2 ** Standard'Address_Size; - NULL_Stream : constant FILEs; - -- Value returned (NULL in C) to indicate an - -- fdopen/fopen/tmpfile error - ---------------------------------- - -- Constants Defined in stdio.h -- - ---------------------------------- - EOF : constant int; - -- Used by a number of routines to indicate error or - -- end of file - IOFBF : constant int; - IOLBF : constant int; - IONBF : constant int; - -- Used to indicate buffering mode for setvbuf call - SEEK_CUR : constant int; - SEEK_END : constant int; - SEEK_SET : constant int; - -- Used to indicate origin for fseek call - function stdin return FILEs; - function stdout return FILEs; - function stderr return FILEs; - -- Streams associated with standard files - -------------------------- - -- Standard C functions -- - -------------------------- - -- The functions selected below are ones that are - -- available in UNIX (but not necessarily in ANSI C). - -- These are very thin interfaces - -- which copy exactly the C headers. For more - -- documentation on these functions, see the Microsoft C - -- "Run-Time Library Reference" (Microsoft Press, 1990, - -- ISBN 1-55615-225-6), which includes useful information - -- on system compatibility. - procedure clearerr (stream : FILEs); - function fclose (stream : FILEs) return int; - function fdopen (handle : int; mode : chars) return FILEs; - function feof (stream : FILEs) return int; - function ferror (stream : FILEs) return int; - function fflush (stream : FILEs) return int; - function fgetc (stream : FILEs) return int; - function fgets (strng : chars; n : int; stream : FILEs) - return chars; - function fileno (stream : FILEs) return int; - function fopen (filename : chars; Mode : chars) - return FILEs; - -- Note: to maintain target independence, use - -- text_translation_required, a boolean variable defined in - -- a-sysdep.c to deal with the target dependent text - -- translation requirement. If this variable is set, - -- then b/t should be appended to the standard mode - -- argument to set the text translation mode off or on - -- as required. - function fputc (C : int; stream : FILEs) return int; - function fputs (Strng : chars; Stream : FILEs) return int; - function fread - (buffer : voids; - size : size_t; - count : size_t; - stream : FILEs) - return size_t; - function freopen - (filename : chars; - mode : chars; - stream : FILEs) - return FILEs; - function fseek - (stream : FILEs; - offset : long; - origin : int) - return int; - function ftell (stream : FILEs) return long; - function fwrite - (buffer : voids; - size : size_t; - count : size_t; - stream : FILEs) - return size_t; - function isatty (handle : int) return int; - procedure mktemp (template : chars); - -- The return value (which is just a pointer to template) - -- is discarded - procedure rewind (stream : FILEs); - function rmtmp return int; - function setvbuf - (stream : FILEs; - buffer : chars; - mode : int; - size : size_t) - return int; - - function tmpfile return FILEs; - function ungetc (c : int; stream : FILEs) return int; - function unlink (filename : chars) return int; - --------------------- - -- Extra functions -- - --------------------- - -- These functions supply slightly thicker bindings than - -- those above. They are derived from functions in the - -- C Run-Time Library, but may do a bit more work than - -- just directly calling one of the Library functions. - function is_regular_file (handle : int) return int; - -- Tests if given handle is for a regular file (result 1) - -- or for a non-regular file (pipe or device, result 0). - --------------------------------- - -- Control of Text/Binary Mode -- - --------------------------------- - -- If text_translation_required is true, then the following - -- functions may be used to dynamically switch a file from - -- binary to text mode or vice versa. These functions have - -- no effect if text_translation_required is false (i.e., in - -- normal UNIX mode). Use fileno to get a stream handle. - procedure set_binary_mode (handle : int); - procedure set_text_mode (handle : int); - ---------------------------- - -- Full Path Name support -- - ---------------------------- - procedure full_name (nam : chars; buffer : chars); - -- Given a NUL terminated string representing a file - -- name, returns in buffer a NUL terminated string - -- representing the full path name for the file name. - -- On systems where it is relevant the drive is also - -- part of the full path name. It is the responsibility - -- of the caller to pass an actual parameter for buffer - -- that is big enough for any full path name. Use - -- max_path_len given below as the size of buffer. - max_path_len : integer; - -- Maximum length of an allowable full path name on the - -- system, including a terminating NUL character. -end Interfaces.C_Streams; -@end example - -@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O -@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d4} -@section Interfacing to C Streams - - -The packages in this section permit interfacing Ada files to C Stream -operations. - -@example -with Interfaces.C_Streams; -package Ada.Sequential_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); -end Ada.Sequential_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Direct_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Direct_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Text_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Text_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Wide_Text_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); -end Ada.Wide_Text_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Wide_Wide_Text_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); -end Ada.Wide_Wide_Text_IO.C_Streams; - -with Interfaces.C_Streams; -package Ada.Stream_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); -end Ada.Stream_IO.C_Streams; -@end example - -In each of these six packages, the @code{C_Stream} function obtains the -@code{FILE} pointer from a currently opened Ada file. It is then -possible to use the @code{Interfaces.C_Streams} package to operate on -this stream, or the stream can be passed to a C program which can -operate on it directly. Of course the program is responsible for -ensuring that only appropriate sequences of operations are executed. - -One particular use of relevance to an Ada program is that the -@code{setvbuf} function can be used to control the buffering of the -stream used by an Ada file. In the absence of such a call the standard -default buffering is used. - -The @code{Open} procedures in these packages open a file giving an -existing C Stream instead of a file name. Typically this stream is -imported from a C program, allowing an Ada file to operate on an -existing C file. - -@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top -@anchor{gnat_rm/the_gnat_library doc}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d6}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10} -@chapter The GNAT Library - - -The GNAT library contains a number of general and special purpose packages. -It represents functionality that the GNAT developers have found useful, and -which is made available to GNAT users. The packages described here are fully -supported, and upwards compatibility will be maintained in future releases, -so you can use these facilities with the confidence that the same functionality -will be available in future releases. - -The chapter here simply gives a brief summary of the facilities available. -The full documentation is found in the spec file for the package. The full -sources of these library packages, including both spec and body, are provided -with all GNAT releases. For example, to find out the full specifications of -the SPITBOL pattern matching capability, including a full tutorial and -extensive examples, look in the @code{g-spipat.ads} file in the library. - -For each entry here, the package name (as it would appear in a @code{with} -clause) is given, followed by the name of the corresponding spec file in -parentheses. The packages are children in four hierarchies, @code{Ada}, -@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a -GNAT-specific hierarchy. - -Note that an application program should only use packages in one of these -four hierarchies if the package is defined in the Ada Reference Manual, -or is listed in this section of the GNAT Programmers Reference Manual. -All other units should be considered internal implementation units and -should not be directly @code{with}ed by application code. The use of -a @code{with} clause that references one of these internal implementation -units makes an application potentially dependent on changes in versions -of GNAT, and will generate a warning message. - -@menu -* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. -* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. -* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. -* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. -* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. -* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. -* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. -* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. -* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. -* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. -* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. -* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. -* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. -* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. -* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. -* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. -* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. -* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. -* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. -* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. -* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. -* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. -* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. -* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. -* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. -* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. -* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. -* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. -* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. -* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. -* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. -* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. -* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. -* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. -* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. -* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. -* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. -* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. -* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. -* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. -* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. -* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. -* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. -* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. -* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. -* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. -* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. -* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. -* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. -* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. -* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. -* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. -* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. -* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. -* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. -* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. -* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. -* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. -* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. -* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. -* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. -* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. -* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. -* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. -* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. -* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. -* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. -* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. -* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. -* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. -* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. -* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. -* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. -* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. -* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. -* GNAT.IO (g-io.ads): GNAT IO g-io ads. -* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. -* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. -* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. -* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. -* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. -* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. -* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. -* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. -* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. -* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. -* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. -* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. -* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. -* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. -* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. -* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. -* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. -* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. -* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. -* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. -* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. -* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. -* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. -* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. -* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. -* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. -* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. -* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. -* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. -* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. -* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. -* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. -* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. -* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. -* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. -* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. -* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. -* GNAT.Table (g-table.ads): GNAT Table g-table ads. -* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. -* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. -* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. -* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. -* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. -* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. -* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. -* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. -* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. -* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. -* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. -* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. -* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. -* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. -* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. -* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. -* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. -* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. -* System.Assertions (s-assert.ads): System Assertions s-assert ads. -* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. -* System.Memory (s-memory.ads): System Memory s-memory ads. -* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. -* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. -* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. -* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. -* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. -* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. -* System.Rident (s-rident.ads): System Rident s-rident ads. -* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. -* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. -* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. -* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. - -@end menu - -@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8} -@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) - - -@geindex Ada.Characters.Latin_9 (a-chlat9.ads) - -@geindex Latin_9 constants for Character - -This child of @code{Ada.Characters} -provides a set of definitions corresponding to those in the -RM-defined package @code{Ada.Characters.Latin_1} but with the -few modifications required for @code{Latin-9} -The provision of such a package -is specifically authorized by the Ada Reference Manual -(RM A.3.3(27)). - -@node Ada Characters Wide_Latin_1 a-cwila1 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d9}@anchor{gnat_rm/the_gnat_library id3}@anchor{2da} -@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) - - -@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) - -@geindex Latin_1 constants for Wide_Character - -This child of @code{Ada.Characters} -provides a set of definitions corresponding to those in the -RM-defined package @code{Ada.Characters.Latin_1} but with the -types of the constants being @code{Wide_Character} -instead of @code{Character}. The provision of such a package -is specifically authorized by the Ada Reference Manual -(RM A.3.3(27)). - -@node Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id4}@anchor{2dc} -@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) - - -@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) - -@geindex Latin_9 constants for Wide_Character - -This child of @code{Ada.Characters} -provides a set of definitions corresponding to those in the -GNAT defined package @code{Ada.Characters.Latin_9} but with the -types of the constants being @code{Wide_Character} -instead of @code{Character}. The provision of such a package -is specifically authorized by the Ada Reference Manual -(RM A.3.3(27)). - -@node Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id5}@anchor{2de} -@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) - - -@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) - -@geindex Latin_1 constants for Wide_Wide_Character - -This child of @code{Ada.Characters} -provides a set of definitions corresponding to those in the -RM-defined package @code{Ada.Characters.Latin_1} but with the -types of the constants being @code{Wide_Wide_Character} -instead of @code{Character}. The provision of such a package -is specifically authorized by the Ada Reference Manual -(RM A.3.3(27)). - -@node Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Containers Bounded_Holders a-coboho ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e0} -@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) - - -@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) - -@geindex Latin_9 constants for Wide_Wide_Character - -This child of @code{Ada.Characters} -provides a set of definitions corresponding to those in the -GNAT defined package @code{Ada.Characters.Latin_9} but with the -types of the constants being @code{Wide_Wide_Character} -instead of @code{Character}. The provision of such a package -is specifically authorized by the Ada Reference Manual -(RM A.3.3(27)). - -@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e2} -@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) - - -@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) - -@geindex Formal container for vectors - -This child of @code{Ada.Containers} defines a modified version of -Indefinite_Holders that avoids heap allocation. - -@node Ada Command_Line Environment a-colien ads,Ada Command_Line Remove a-colire ads,Ada Containers Bounded_Holders a-coboho ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id8}@anchor{2e4} -@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) - - -@geindex Ada.Command_Line.Environment (a-colien.ads) - -@geindex Environment entries - -This child of @code{Ada.Command_Line} -provides a mechanism for obtaining environment values on systems -where this concept makes sense. - -@node Ada Command_Line Remove a-colire ads,Ada Command_Line Response_File a-clrefi ads,Ada Command_Line Environment a-colien ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id9}@anchor{2e6} -@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) - - -@geindex Ada.Command_Line.Remove (a-colire.ads) - -@geindex Removing command line arguments - -@geindex Command line -@geindex argument removal - -This child of @code{Ada.Command_Line} -provides a mechanism for logically removing -arguments from the argument list. Once removed, an argument is not visible -to further calls on the subprograms in @code{Ada.Command_Line} will not -see the removed argument. - -@node Ada Command_Line Response_File a-clrefi ads,Ada Direct_IO C_Streams a-diocst ads,Ada Command_Line Remove a-colire ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id10}@anchor{2e8} -@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) - - -@geindex Ada.Command_Line.Response_File (a-clrefi.ads) - -@geindex Response file for command line - -@geindex Command line -@geindex response file - -@geindex Command line -@geindex handling long command lines - -This child of @code{Ada.Command_Line} provides a mechanism facilities for -getting command line arguments from a text file, called a “response file”. -Using a response file allow passing a set of arguments to an executable longer -than the maximum allowed by the system on the command line. - -@node Ada Direct_IO C_Streams a-diocst ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Command_Line Response_File a-clrefi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id11}@anchor{2ea} -@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) - - -@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) - -@geindex C Streams -@geindex Interfacing with Direct_IO - -This package provides subprograms that allow interfacing between -C streams and @code{Direct_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Direct_IO C_Streams a-diocst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec} -@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) - - -@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) - -@geindex Null_Occurrence -@geindex testing for - -This child subprogram provides a way of testing for the null -exception occurrence (@code{Null_Occurrence}) without raising -an exception. - -@node Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Exceptions Traceback a-exctra ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id13}@anchor{2ee} -@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) - - -@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) - -@geindex Null_Occurrence -@geindex testing for - -This child subprogram is used for handling otherwise unhandled -exceptions (hence the name last chance), and perform clean ups before -terminating the program. Note that this subprogram never returns. - -@node Ada Exceptions Traceback a-exctra ads,Ada Sequential_IO C_Streams a-siocst ads,Ada Exceptions Last_Chance_Handler a-elchha ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0} -@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) - - -@geindex Ada.Exceptions.Traceback (a-exctra.ads) - -@geindex Traceback for Exception Occurrence - -This child package provides the subprogram (@code{Tracebacks}) to -give a traceback array of addresses based on an exception -occurrence. - -@node Ada Sequential_IO C_Streams a-siocst ads,Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Exceptions Traceback a-exctra ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2} -@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) - - -@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) - -@geindex C Streams -@geindex Interfacing with Sequential_IO - -This package provides subprograms that allow interfacing between -C streams and @code{Sequential_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Strings Unbounded Text_IO a-suteio ads,Ada Sequential_IO C_Streams a-siocst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4} -@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) - - -@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) - -@geindex C Streams -@geindex Interfacing with Stream_IO - -This package provides subprograms that allow interfacing between -C streams and @code{Stream_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Strings Unbounded Text_IO a-suteio ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Streams Stream_IO C_Streams a-ssicst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6} -@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) - - -@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) - -@geindex Unbounded_String -@geindex IO support - -@geindex Text_IO -@geindex extensions for unbounded strings - -This package provides subprograms for Text_IO for unbounded -strings, avoiding the necessity for an intermediate operation -with ordinary strings. - -@node Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Strings Unbounded Text_IO a-suteio ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8} -@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) - - -@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) - -@geindex Unbounded_Wide_String -@geindex IO support - -@geindex Text_IO -@geindex extensions for unbounded wide strings - -This package provides subprograms for Text_IO for unbounded -wide strings, avoiding the necessity for an intermediate operation -with ordinary wide strings. - -@node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Task_Initialization a-tasini ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa} -@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) - - -@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) - -@geindex Unbounded_Wide_Wide_String -@geindex IO support - -@geindex Text_IO -@geindex extensions for unbounded wide wide strings - -This package provides subprograms for Text_IO for unbounded -wide wide strings, avoiding the necessity for an intermediate operation -with ordinary wide wide strings. - -@node Ada Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id20}@anchor{2fc} -@section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) - - -@geindex Ada.Task_Initialization (a-tasini.ads) - -This package provides a way to set a global initialization handler that -is automatically invoked whenever a task is activated. Handlers are -parameterless procedures. Note that such a handler is only invoked for -those tasks activated after the handler is set. - -@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id21}@anchor{2fe} -@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) - - -@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) - -@geindex C Streams -@geindex Interfacing with `@w{`}Text_IO`@w{`} - -This package provides subprograms that allow interfacing between -C streams and @code{Text_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Wide_Characters Unicode a-wichun ads,Ada Text_IO C_Streams a-tiocst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id22}@anchor{300} -@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) - - -@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) - -@geindex Text_IO resetting standard files - -This procedure is used to reset the status of the standard files used -by Ada.Text_IO. This is useful in a situation (such as a restart in an -embedded application) where the status of the files may change during -execution (for example a standard input file may be redefined to be -interactive). - -@node Ada Wide_Characters Unicode a-wichun ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id23}@anchor{302} -@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) - - -@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) - -@geindex Unicode categorization -@geindex Wide_Character - -This package provides subprograms that allow categorization of -Wide_Character values according to Unicode categories. - -@node Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Characters Unicode a-wichun ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304} -@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) - - -@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) - -@geindex C Streams -@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} - -This package provides subprograms that allow interfacing between -C streams and @code{Wide_Text_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id25}@anchor{306} -@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) - - -@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) - -@geindex Wide_Text_IO resetting standard files - -This procedure is used to reset the status of the standard files used -by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an -embedded application) where the status of the files may change during -execution (for example a standard input file may be redefined to be -interactive). - -@node Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id26}@anchor{308} -@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) - - -@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) - -@geindex Unicode categorization -@geindex Wide_Wide_Character - -This package provides subprograms that allow categorization of -Wide_Wide_Character values according to Unicode categories. - -@node Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id27}@anchor{30a} -@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) - - -@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) - -@geindex C Streams -@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} - -This package provides subprograms that allow interfacing between -C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be -extracted from a file opened on the Ada side, and an Ada file -can be constructed from a stream opened on the C side. - -@node Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,GNAT Altivec g-altive ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id28}@anchor{30c} -@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) - - -@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) - -@geindex Wide_Wide_Text_IO resetting standard files - -This procedure is used to reset the status of the standard files used -by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a -restart in an embedded application) where the status of the files may -change during execution (for example a standard input file may be -redefined to be interactive). - -@node GNAT Altivec g-altive ads,GNAT Altivec Conversions g-altcon ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id29}@anchor{30e} -@section @code{GNAT.Altivec} (@code{g-altive.ads}) - - -@geindex GNAT.Altivec (g-altive.ads) - -@geindex AltiVec - -This is the root package of the GNAT AltiVec binding. It provides -definitions of constants and types common to all the versions of the -binding. - -@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310} -@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) - - -@geindex GNAT.Altivec.Conversions (g-altcon.ads) - -@geindex AltiVec - -This package provides the Vector/View conversion routines. - -@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id31}@anchor{312} -@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) - - -@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) - -@geindex AltiVec - -This package exposes the Ada interface to the AltiVec operations on -vector objects. A soft emulation is included by default in the GNAT -library. The hard binding is provided as a separate package. This unit -is common to both bindings. - -@node GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Vector_Views g-alvevi ads,GNAT Altivec Vector_Operations g-alveop ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id32}@anchor{314} -@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) - - -@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) - -@geindex AltiVec - -This package exposes the various vector types part of the Ada binding -to AltiVec facilities. - -@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316} -@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) - - -@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) - -@geindex AltiVec - -This package provides public ‘View’ data types from/to which private -vector representations can be converted via -GNAT.Altivec.Conversions. This allows convenient access to individual -vector elements and provides a simple way to initialize vector -objects. - -@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id34}@anchor{318} -@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) - - -@geindex GNAT.Array_Split (g-arrspl.ads) - -@geindex Array splitter - -Useful array-manipulation routines: given a set of separators, split -an array wherever the separators appear, and provide direct access -to the resulting slices. - -@node GNAT AWK g-awk ads,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id35}@anchor{31a} -@section @code{GNAT.AWK} (@code{g-awk.ads}) - - -@geindex GNAT.AWK (g-awk.ads) - -@geindex Parsing - -@geindex AWK - -Provides AWK-like parsing functions, with an easy interface for parsing one -or more files containing formatted data. The file is viewed as a database -where each record is a line and a field is a data element in this line. - -@node GNAT Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id36}@anchor{31c} -@section @code{GNAT.Binary_Search} (@code{g-binsea.ads}) - - -@geindex GNAT.Binary_Search (g-binsea.ads) - -@geindex Binary search - -Allow binary search of a sorted array (or of an array-like container; -the generic does not reference the array directly). - -@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id37}@anchor{31e} -@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) - - -@geindex GNAT.Bind_Environment (g-binenv.ads) - -@geindex Bind environment - -Provides access to key=value associations captured at bind time. -These associations can be specified using the @code{-V} binder command -line switch. - -@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id38}@anchor{320} -@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) - - -@geindex GNAT.Branch_Prediction (g-brapre.ads) - -@geindex Branch Prediction - -Provides routines giving hints to the branch predictor of the code generator. - -@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322} -@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) - - -@geindex GNAT.Bounded_Buffers (g-boubuf.ads) - -@geindex Parsing - -@geindex Bounded Buffers - -Provides a concurrent generic bounded buffer abstraction. Instances are -useful directly or as parts of the implementations of other abstractions, -such as mailboxes. - -@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324} -@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) - - -@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) - -@geindex Parsing - -@geindex Mailboxes - -Provides a thread-safe asynchronous intertask mailbox communication facility. - -@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326} -@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) - - -@geindex GNAT.Bubble_Sort (g-bubsor.ads) - -@geindex Sorting - -@geindex Bubble sort - -Provides a general implementation of bubble sort usable for sorting arbitrary -data items. Exchange and comparison procedures are provided by passing -access-to-procedure values. - -@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328} -@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) - - -@geindex GNAT.Bubble_Sort_A (g-busora.ads) - -@geindex Sorting - -@geindex Bubble sort - -Provides a general implementation of bubble sort usable for sorting arbitrary -data items. Move and comparison procedures are provided by passing -access-to-procedure values. This is an older version, retained for -compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. - -@node GNAT Bubble_Sort_G g-busorg ads,GNAT Byte_Order_Mark g-byorma ads,GNAT Bubble_Sort_A g-busora ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a} -@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) - - -@geindex GNAT.Bubble_Sort_G (g-busorg.ads) - -@geindex Sorting - -@geindex Bubble sort - -Similar to @code{Bubble_Sort_A} except that the move and sorting procedures -are provided as generic parameters, this improves efficiency, especially -if the procedures can be inlined, at the expense of duplicating code for -multiple instantiations. - -@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c} -@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) - - -@geindex GNAT.Byte_Order_Mark (g-byorma.ads) - -@geindex UTF-8 representation - -@geindex Wide characte representations - -Provides a routine which given a string, reads the start of the string to -see whether it is one of the standard byte order marks (BOM’s) which signal -the encoding of the string. The routine includes detection of special XML -sequences for various UCS input formats. - -@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e} -@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) - - -@geindex GNAT.Byte_Swapping (g-bytswa.ads) - -@geindex Byte swapping - -@geindex Endianness - -General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. -Machine-specific implementations are available in some cases. - -@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330} -@section @code{GNAT.Calendar} (@code{g-calend.ads}) - - -@geindex GNAT.Calendar (g-calend.ads) - -@geindex Calendar - -Extends the facilities provided by @code{Ada.Calendar} to include handling -of days of the week, an extended @code{Split} and @code{Time_Of} capability. -Also provides conversion of @code{Ada.Calendar.Time} values to and from the -C @code{timeval} format. - -@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332} -@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) - - -@geindex Calendar - -@geindex Time - -@geindex GNAT.Calendar.Time_IO (g-catiio.ads) - -@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334} -@section @code{GNAT.CRC32} (@code{g-crc32.ads}) - - -@geindex GNAT.CRC32 (g-crc32.ads) - -@geindex CRC32 - -@geindex Cyclic Redundancy Check - -This package implements the CRC-32 algorithm. For a full description -of this algorithm see -`Computation of Cyclic Redundancy Checks via Table Look-Up', -@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, -Aug. 1988. Sarwate, D.V. - -@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336} -@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) - - -@geindex GNAT.Case_Util (g-casuti.ads) - -@geindex Casing utilities - -@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) - -A set of simple routines for handling upper and lower casing of strings -without the overhead of the full casing tables -in @code{Ada.Characters.Handling}. - -@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338} -@section @code{GNAT.CGI} (@code{g-cgi.ads}) - - -@geindex GNAT.CGI (g-cgi.ads) - -@geindex CGI (Common Gateway Interface) - -This is a package for interfacing a GNAT program with a Web server via the -Common Gateway Interface (CGI). Basically this package parses the CGI -parameters, which are a set of key/value pairs sent by the Web server. It -builds a table whose index is the key and provides some services to deal -with this table. - -@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a} -@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) - - -@geindex GNAT.CGI.Cookie (g-cgicoo.ads) - -@geindex CGI (Common Gateway Interface) cookie support - -@geindex Cookie support in CGI - -This is a package to interface a GNAT program with a Web server via the -Common Gateway Interface (CGI). It exports services to deal with Web -cookies (piece of information kept in the Web client software). - -@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c} -@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) - - -@geindex GNAT.CGI.Debug (g-cgideb.ads) - -@geindex CGI (Common Gateway Interface) debugging - -This is a package to help debugging CGI (Common Gateway Interface) -programs written in Ada. - -@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@anchor{33e} -@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) - - -@geindex GNAT.Command_Line (g-comlin.ads) - -@geindex Command line - -Provides a high level interface to @code{Ada.Command_Line} facilities, -including the ability to scan for named switches with optional parameters -and expand file names using wildcard notations. - -@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340} -@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) - - -@geindex GNAT.Compiler_Version (g-comver.ads) - -@geindex Compiler Version - -@geindex Version -@geindex of compiler - -Provides a routine for obtaining the version of the compiler used to -compile the program. More accurately this is the version of the binder -used to bind the program (this will normally be the same as the version -of the compiler if a consistent tool set is used to compile all units -of a partition). - -@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342} -@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) - - -@geindex GNAT.Ctrl_C (g-ctrl_c.ads) - -@geindex Interrupt - -Provides a simple interface to handle Ctrl-C keyboard events. - -@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344} -@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) - - -@geindex GNAT.Current_Exception (g-curexc.ads) - -@geindex Current exception - -@geindex Exception retrieval - -Provides access to information on the current exception that has been raised -without the need for using the Ada 95 / Ada 2005 exception choice parameter -specification syntax. -This is particularly useful in simulating typical facilities for -obtaining information about exceptions provided by Ada 83 compilers. - -@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346} -@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) - - -@geindex GNAT.Debug_Pools (g-debpoo.ads) - -@geindex Debugging - -@geindex Debug pools - -@geindex Memory corruption debugging - -Provide a debugging storage pools that helps tracking memory corruption -problems. -See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. - -@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348} -@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) - - -@geindex GNAT.Debug_Utilities (g-debuti.ads) - -@geindex Debugging - -Provides a few useful utilities for debugging purposes, including conversion -to and from string images of address values. Supports both C and Ada formats -for hexadecimal literals. - -@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a} -@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) - - -@geindex GNAT.Decode_String (g-decstr.ads) - -@geindex Decoding strings - -@geindex String decoding - -@geindex Wide character encoding - -@geindex UTF-8 - -@geindex Unicode - -A generic package providing routines for decoding wide character and wide wide -character strings encoded as sequences of 8-bit characters using a specified -encoding method. Includes validation routines, and also routines for stepping -to next or previous encoded character in an encoded string. -Useful in conjunction with Unicode character coding. Note there is a -preinstantiation for UTF-8. See next entry. - -@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c} -@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) - - -@geindex GNAT.Decode_UTF8_String (g-deutst.ads) - -@geindex Decoding strings - -@geindex Decoding UTF-8 strings - -@geindex UTF-8 string decoding - -@geindex Wide character decoding - -@geindex UTF-8 - -@geindex Unicode - -A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. - -@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e} -@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) - - -@geindex GNAT.Directory_Operations (g-dirope.ads) - -@geindex Directory operations - -Provides a set of routines for manipulating directories, including changing -the current directory, making new directories, and scanning the files in a -directory. - -@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350} -@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) - - -@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) - -@geindex Directory operations iteration - -A child unit of GNAT.Directory_Operations providing additional operations -for iterating through directories. - -@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352} -@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) - - -@geindex GNAT.Dynamic_HTables (g-dynhta.ads) - -@geindex Hash tables - -A generic implementation of hash tables that can be used to hash arbitrary -data. Provided in two forms, a simple form with built in hash functions, -and a more complex form in which the hash function is supplied. - -This package provides a facility similar to that of @code{GNAT.HTable}, -except that this package declares a type that can be used to define -dynamic instances of the hash table, while an instantiation of -@code{GNAT.HTable} creates a single instance of the hash table. - -@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354} -@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) - - -@geindex GNAT.Dynamic_Tables (g-dyntab.ads) - -@geindex Table implementation - -@geindex Arrays -@geindex extendable - -A generic package providing a single dimension array abstraction where the -length of the array can be dynamically modified. - -This package provides a facility similar to that of @code{GNAT.Table}, -except that this package declares a type that can be used to define -dynamic instances of the table, while an instantiation of -@code{GNAT.Table} creates a single instance of the table type. - -@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356} -@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) - - -@geindex GNAT.Encode_String (g-encstr.ads) - -@geindex Encoding strings - -@geindex String encoding - -@geindex Wide character encoding - -@geindex UTF-8 - -@geindex Unicode - -A generic package providing routines for encoding wide character and wide -wide character strings as sequences of 8-bit characters using a specified -encoding method. Useful in conjunction with Unicode character coding. -Note there is a preinstantiation for UTF-8. See next entry. - -@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358} -@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) - - -@geindex GNAT.Encode_UTF8_String (g-enutst.ads) - -@geindex Encoding strings - -@geindex Encoding UTF-8 strings - -@geindex UTF-8 string encoding - -@geindex Wide character encoding - -@geindex UTF-8 - -@geindex Unicode - -A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. - -@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a} -@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) - - -@geindex GNAT.Exception_Actions (g-excact.ads) - -@geindex Exception actions - -Provides callbacks when an exception is raised. Callbacks can be registered -for specific exceptions, or when any exception is raised. This -can be used for instance to force a core dump to ease debugging. - -@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c} -@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) - - -@geindex GNAT.Exception_Traces (g-exctra.ads) - -@geindex Exception traces - -@geindex Debugging - -Provides an interface allowing to control automatic output upon exception -occurrences. - -@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e} -@section @code{GNAT.Exceptions} (@code{g-except.ads}) - - -@geindex GNAT.Exceptions (g-except.ads) - -@geindex Exceptions -@geindex Pure - -@geindex Pure packages -@geindex exceptions - -Normally it is not possible to raise an exception with -a message from a subprogram in a pure package, since the -necessary types and subprograms are in @code{Ada.Exceptions} -which is not a pure unit. @code{GNAT.Exceptions} provides a -facility for getting around this limitation for a few -predefined exceptions, and for example allow raising -@code{Constraint_Error} with a message from a pure subprogram. - -@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360} -@section @code{GNAT.Expect} (@code{g-expect.ads}) - - -@geindex GNAT.Expect (g-expect.ads) - -Provides a set of subprograms similar to what is available -with the standard Tcl Expect tool. -It allows you to easily spawn and communicate with an external process. -You can send commands or inputs to the process, and compare the output -with some expected regular expression. Currently @code{GNAT.Expect} -is implemented on all native GNAT ports. -It is not implemented for cross ports, and in particular is not -implemented for VxWorks or LynxOS. - -@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id71}@anchor{362} -@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) - - -@geindex GNAT.Expect.TTY (g-exptty.ads) - -As GNAT.Expect but using pseudo-terminal. -Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT -ports. It is not implemented for cross ports, and -in particular is not implemented for VxWorks or LynxOS. - -@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364} -@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) - - -@geindex GNAT.Float_Control (g-flocon.ads) - -@geindex Floating-Point Processor - -Provides an interface for resetting the floating-point processor into the -mode required for correct semantic operation in Ada. Some third party -library calls may cause this mode to be modified, and the Reset procedure -in this package can be used to reestablish the required mode. - -@node GNAT Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366} -@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) - - -@geindex GNAT.Formatted_String (g-forstr.ads) - -@geindex Formatted String - -Provides support for C/C++ printf() formatted strings. The format is -copied from the printf() routine and should therefore gives identical -output. Some generic routines are provided to be able to use types -derived from Integer, Float or enumerations as values for the -formatted string. - -@node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368} -@section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads}) - - -@geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads) - -@geindex Mathematical functions - -Provides direct access to the underlying implementation of the common -mathematical functions, generally from the system mathematical library. -This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that -the implementation may deviate from the semantics specified for these -functions in the Reference Manual, for example @code{Numerics.Argument_Error} -is not raised. On selected platforms, some of these functions may also -have a vector implementation that can be automatically used by the -compiler when auto-vectorization is enabled. - -@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a} -@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) - - -@geindex GNAT.Heap_Sort (g-heasor.ads) - -@geindex Sorting - -Provides a general implementation of heap sort usable for sorting arbitrary -data items. Exchange and comparison procedures are provided by passing -access-to-procedure values. The algorithm used is a modified heap sort -that performs approximately N*log(N) comparisons in the worst case. - -@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c} -@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) - - -@geindex GNAT.Heap_Sort_A (g-hesora.ads) - -@geindex Sorting - -Provides a general implementation of heap sort usable for sorting arbitrary -data items. Move and comparison procedures are provided by passing -access-to-procedure values. The algorithm used is a modified heap sort -that performs approximately N*log(N) comparisons in the worst case. -This differs from @code{GNAT.Heap_Sort} in having a less convenient -interface, but may be slightly more efficient. - -@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e} -@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) - - -@geindex GNAT.Heap_Sort_G (g-hesorg.ads) - -@geindex Sorting - -Similar to @code{Heap_Sort_A} except that the move and sorting procedures -are provided as generic parameters, this improves efficiency, especially -if the procedures can be inlined, at the expense of duplicating code for -multiple instantiations. - -@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370} -@section @code{GNAT.HTable} (@code{g-htable.ads}) - - -@geindex GNAT.HTable (g-htable.ads) - -@geindex Hash tables - -A generic implementation of hash tables that can be used to hash arbitrary -data. Provides two approaches, one a simple static approach, and the other -allowing arbitrary dynamic hash tables. - -@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372} -@section @code{GNAT.IO} (@code{g-io.ads}) - - -@geindex GNAT.IO (g-io.ads) - -@geindex Simple I/O - -@geindex Input/Output facilities - -A simple preelaborable input-output package that provides a subset of -simple Text_IO functions for reading characters and strings from -Standard_Input, and writing characters, strings and integers to either -Standard_Output or Standard_Error. - -@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374} -@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) - - -@geindex GNAT.IO_Aux (g-io_aux.ads) - -@geindex Text_IO - -@geindex Input/Output facilities - -Provides some auxiliary functions for use with Text_IO, including a test -for whether a file exists, and functions for reading a line of text. - -@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376} -@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) - - -@geindex GNAT.Lock_Files (g-locfil.ads) - -@geindex File locking - -@geindex Locking using files - -Provides a general interface for using files as locks. Can be used for -providing program level synchronization. - -@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378} -@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) - - -@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) - -@geindex Random number generation - -The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses -a modified version of the Blum-Blum-Shub generator. - -@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a} -@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) - - -@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) - -@geindex Random number generation - -The original implementation of @code{Ada.Numerics.Float_Random}. Uses -a modified version of the Blum-Blum-Shub generator. - -@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c} -@section @code{GNAT.MD5} (@code{g-md5.ads}) - - -@geindex GNAT.MD5 (g-md5.ads) - -@geindex Message Digest MD5 - -Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and -the HMAC-MD5 message authentication function as described in RFC 2104 and -FIPS PUB 198. - -@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e} -@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) - - -@geindex GNAT.Memory_Dump (g-memdum.ads) - -@geindex Dump Memory - -Provides a convenient routine for dumping raw memory to either the -standard output or standard error files. Uses GNAT.IO for actual -output. - -@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380} -@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) - - -@geindex GNAT.Most_Recent_Exception (g-moreex.ads) - -@geindex Exception -@geindex obtaining most recent - -Provides access to the most recently raised exception. Can be used for -various logging purposes, including duplicating functionality of some -Ada 83 implementation dependent extensions. - -@node GNAT OS_Lib g-os_lib ads,GNAT Perfect_Hash_Generators g-pehage ads,GNAT Most_Recent_Exception g-moreex ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382} -@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) - - -@geindex GNAT.OS_Lib (g-os_lib.ads) - -@geindex Operating System interface - -@geindex Spawn capability - -Provides a range of target independent operating system interface functions, -including time/date management, file operations, subprocess management, -including a portable spawn procedure, and access to environment variables -and error return codes. - -@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384} -@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) - - -@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) - -@geindex Hash functions - -Provides a generator of static minimal perfect hash functions. No -collisions occur and each item can be retrieved from the table in one -probe (perfect property). The hash table size corresponds to the exact -size of the key set and no larger (minimal property). The key set has to -be know in advance (static property). The hash functions are also order -preserving. If w2 is inserted after w1 in the generator, their -hashcode are in the same order. These hashing functions are very -convenient for use with realtime applications. - -@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386} -@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) - - -@geindex GNAT.Random_Numbers (g-rannum.ads) - -@geindex Random number generation - -Provides random number capabilities which extend those available in the -standard Ada library and are more convenient to use. - -@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25c}@anchor{gnat_rm/the_gnat_library id90}@anchor{387} -@section @code{GNAT.Regexp} (@code{g-regexp.ads}) - - -@geindex GNAT.Regexp (g-regexp.ads) - -@geindex Regular expressions - -@geindex Pattern matching - -A simple implementation of regular expressions, using a subset of regular -expression syntax copied from familiar Unix style utilities. This is the -simplest of the three pattern matching packages provided, and is particularly -suitable for ‘file globbing’ applications. - -@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id91}@anchor{389} -@section @code{GNAT.Registry} (@code{g-regist.ads}) - - -@geindex GNAT.Registry (g-regist.ads) - -@geindex Windows Registry - -This is a high level binding to the Windows registry. It is possible to -do simple things like reading a key value, creating a new key. For full -registry API, but at a lower level of abstraction, refer to the Win32.Winreg -package provided with the Win32Ada binding - -@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{38a}@anchor{gnat_rm/the_gnat_library id92}@anchor{38b} -@section @code{GNAT.Regpat} (@code{g-regpat.ads}) - - -@geindex GNAT.Regpat (g-regpat.ads) - -@geindex Regular expressions - -@geindex Pattern matching - -A complete implementation of Unix-style regular expression matching, copied -from the original V7 style regular expression library written in C by -Henry Spencer (and binary compatible with this C library). - -@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{38c}@anchor{gnat_rm/the_gnat_library id93}@anchor{38d} -@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) - - -@geindex GNAT.Rewrite_Data (g-rewdat.ads) - -@geindex Rewrite data - -A unit to rewrite on-the-fly string occurrences in a stream of -data. The implementation has a very minimal memory footprint as the -full content to be processed is not loaded into memory all at once. This makes -this interface usable for large files or socket streams. - -@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id94}@anchor{38f} -@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) - - -@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) - -@geindex Secondary Stack Info - -Provide the capability to query the high water mark of the current task’s -secondary stack. - -@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id95}@anchor{391} -@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) - - -@geindex GNAT.Semaphores (g-semaph.ads) - -@geindex Semaphores - -Provides classic counting and binary semaphores using protected types. - -@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id96}@anchor{393} -@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) - - -@geindex GNAT.Serial_Communications (g-sercom.ads) - -@geindex Serial_Communications - -Provides a simple interface to send and receive data over a serial -port. This is only supported on GNU/Linux and Windows. - -@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id97}@anchor{395} -@section @code{GNAT.SHA1} (@code{g-sha1.ads}) - - -@geindex GNAT.SHA1 (g-sha1.ads) - -@geindex Secure Hash Algorithm SHA-1 - -Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 -and RFC 3174, and the HMAC-SHA1 message authentication function as described -in RFC 2104 and FIPS PUB 198. - -@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id98}@anchor{397} -@section @code{GNAT.SHA224} (@code{g-sha224.ads}) - - -@geindex GNAT.SHA224 (g-sha224.ads) - -@geindex Secure Hash Algorithm SHA-224 - -Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, -and the HMAC-SHA224 message authentication function as described -in RFC 2104 and FIPS PUB 198. - -@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399} -@section @code{GNAT.SHA256} (@code{g-sha256.ads}) - - -@geindex GNAT.SHA256 (g-sha256.ads) - -@geindex Secure Hash Algorithm SHA-256 - -Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, -and the HMAC-SHA256 message authentication function as described -in RFC 2104 and FIPS PUB 198. - -@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b} -@section @code{GNAT.SHA384} (@code{g-sha384.ads}) - - -@geindex GNAT.SHA384 (g-sha384.ads) - -@geindex Secure Hash Algorithm SHA-384 - -Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, -and the HMAC-SHA384 message authentication function as described -in RFC 2104 and FIPS PUB 198. - -@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d} -@section @code{GNAT.SHA512} (@code{g-sha512.ads}) - - -@geindex GNAT.SHA512 (g-sha512.ads) - -@geindex Secure Hash Algorithm SHA-512 - -Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, -and the HMAC-SHA512 message authentication function as described -in RFC 2104 and FIPS PUB 198. - -@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f} -@section @code{GNAT.Signals} (@code{g-signal.ads}) - - -@geindex GNAT.Signals (g-signal.ads) - -@geindex Signals - -Provides the ability to manipulate the blocked status of signals on supported -targets. - -@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1} -@section @code{GNAT.Sockets} (@code{g-socket.ads}) - - -@geindex GNAT.Sockets (g-socket.ads) - -@geindex Sockets - -A high level and portable interface to develop sockets based applications. -This package is based on the sockets thin binding found in -@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented -on all native GNAT ports and on VxWorks cross prots. It is not implemented for -the LynxOS cross port. - -@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3} -@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) - - -@geindex GNAT.Source_Info (g-souinf.ads) - -@geindex Source Information - -Provides subprograms that give access to source code information known at -compile time, such as the current file name and line number. Also provides -subprograms yielding the date and time of the current compilation (like the -C macros @code{__DATE__} and @code{__TIME__}) - -@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5} -@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) - - -@geindex GNAT.Spelling_Checker (g-speche.ads) - -@geindex Spell checking - -Provides a function for determining whether one string is a plausible -near misspelling of another string. - -@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7} -@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) - - -@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) - -@geindex Spell checking - -Provides a generic function that can be instantiated with a string type for -determining whether one string is a plausible near misspelling of another -string. - -@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9} -@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) - - -@geindex GNAT.Spitbol.Patterns (g-spipat.ads) - -@geindex SPITBOL pattern matching - -@geindex Pattern matching - -A complete implementation of SNOBOL4 style pattern matching. This is the -most elaborate of the pattern matching packages provided. It fully duplicates -the SNOBOL4 dynamic pattern construction and matching capabilities, using the -efficient algorithm developed by Robert Dewar for the SPITBOL system. - -@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab} -@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) - - -@geindex GNAT.Spitbol (g-spitbo.ads) - -@geindex SPITBOL interface - -The top level package of the collection of SPITBOL-style functionality, this -package provides basic SNOBOL4 string manipulation functions, such as -Pad, Reverse, Trim, Substr capability, as well as a generic table function -useful for constructing arbitrary mappings from strings in the style of -the SNOBOL4 TABLE function. - -@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad} -@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) - - -@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) - -@geindex Sets of strings - -@geindex SPITBOL Tables - -A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} -for type @code{Standard.Boolean}, giving an implementation of sets of -string values. - -@node GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol Table_VString g-sptavs ads,GNAT Spitbol Table_Boolean g-sptabo ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af} -@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) - - -@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) - -@geindex Integer maps - -@geindex Maps - -@geindex SPITBOL Tables - -A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} -for type @code{Standard.Integer}, giving an implementation of maps -from string to integer values. - -@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1} -@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) - - -@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) - -@geindex String maps - -@geindex Maps - -@geindex SPITBOL Tables - -A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for -a variable length string type, giving an implementation of general -maps from strings to strings. - -@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3} -@section @code{GNAT.SSE} (@code{g-sse.ads}) - - -@geindex GNAT.SSE (g-sse.ads) - -Root of a set of units aimed at offering Ada bindings to a subset of -the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of -targets. It exposes vector component types together with a general -introduction to the binding contents and use. - -@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5} -@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) - - -@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) - -SSE vector types for use with SSE related intrinsics. - -@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7} -@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) - - -@geindex GNAT.String_Hash (g-strhas.ads) - -@geindex Hash functions - -Provides a generic hash function working on arrays of scalars. Both the scalar -type and the hash result type are parameters. - -@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9} -@section @code{GNAT.Strings} (@code{g-string.ads}) - - -@geindex GNAT.Strings (g-string.ads) - -Common String access types and related subprograms. Basically it -defines a string access and an array of string access types. - -@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb} -@section @code{GNAT.String_Split} (@code{g-strspl.ads}) - - -@geindex GNAT.String_Split (g-strspl.ads) - -@geindex String splitter - -Useful string manipulation routines: given a set of separators, split -a string wherever the separators appear, and provide direct access -to the resulting slices. This package is instantiated from -@code{GNAT.Array_Split}. - -@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd} -@section @code{GNAT.Table} (@code{g-table.ads}) - - -@geindex GNAT.Table (g-table.ads) - -@geindex Table implementation - -@geindex Arrays -@geindex extendable - -A generic package providing a single dimension array abstraction where the -length of the array can be dynamically modified. - -This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, -except that this package declares a single instance of the table type, -while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be -used to define dynamic instances of the table. - -@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf} -@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) - - -@geindex GNAT.Task_Lock (g-tasloc.ads) - -@geindex Task synchronization - -@geindex Task locking - -@geindex Locking - -A very simple facility for locking and unlocking sections of code using a -single global task lock. Appropriate for use in situations where contention -between tasks is very rarely expected. - -@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1} -@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) - - -@geindex GNAT.Time_Stamp (g-timsta.ads) - -@geindex Time stamp - -@geindex Current time - -Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that -represents the current date and time in ISO 8601 format. This is a very simple -routine with minimal code and there are no dependencies on any other unit. - -@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3} -@section @code{GNAT.Threads} (@code{g-thread.ads}) - - -@geindex GNAT.Threads (g-thread.ads) - -@geindex Foreign threads - -@geindex Threads -@geindex foreign - -Provides facilities for dealing with foreign threads which need to be known -by the GNAT run-time system. Consult the documentation of this package for -further details if your program has threads that are created by a non-Ada -environment which then accesses Ada code. - -@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5} -@section @code{GNAT.Traceback} (@code{g-traceb.ads}) - - -@geindex GNAT.Traceback (g-traceb.ads) - -@geindex Trace back facilities - -Provides a facility for obtaining non-symbolic traceback information, useful -in various debugging situations. - -@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7} -@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) - - -@geindex GNAT.Traceback.Symbolic (g-trasym.ads) - -@geindex Trace back facilities - -@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9} -@section @code{GNAT.UTF_32} (@code{g-table.ads}) - - -@geindex GNAT.UTF_32 (g-table.ads) - -@geindex Wide character codes - -This is a package intended to be used in conjunction with the -@code{Wide_Character} type in Ada 95 and the -@code{Wide_Wide_Character} type in Ada 2005 (available -in @code{GNAT} in Ada 2005 mode). This package contains -Unicode categorization routines, as well as lexical -categorization routines corresponding to the Ada 2005 -lexical rules for identifiers and strings, and also a -lower case to upper case fold routine corresponding to -the Ada 2005 rules for identifier equivalence. - -@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb} -@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) - - -@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) - -@geindex Spell checking - -Provides a function for determining whether one wide wide string is a plausible -near misspelling of another wide wide string, where the strings are represented -using the UTF_32_String type defined in System.Wch_Cnv. - -@node GNAT Wide_Spelling_Checker g-wispch ads,GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Spelling_Checker g-u3spch ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd} -@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) - - -@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) - -@geindex Spell checking - -Provides a function for determining whether one wide string is a plausible -near misspelling of another wide string. - -@node GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Spelling_Checker g-wispch ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf} -@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) - - -@geindex GNAT.Wide_String_Split (g-wistsp.ads) - -@geindex Wide_String splitter - -Useful wide string manipulation routines: given a set of separators, split -a wide string wherever the separators appear, and provide direct access -to the resulting slices. This package is instantiated from -@code{GNAT.Array_Split}. - -@node GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Wide_String_Split g-zistsp ads,GNAT Wide_String_Split g-wistsp ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1} -@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) - - -@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) - -@geindex Spell checking - -Provides a function for determining whether one wide wide string is a plausible -near misspelling of another wide wide string. - -@node GNAT Wide_Wide_String_Split g-zistsp ads,Interfaces C Extensions i-cexten ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3} -@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) - - -@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) - -@geindex Wide_Wide_String splitter - -Useful wide wide string manipulation routines: given a set of separators, split -a wide wide string wherever the separators appear, and provide direct access -to the resulting slices. This package is instantiated from -@code{GNAT.Array_Split}. - -@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id129}@anchor{3d4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d5} -@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) - - -@geindex Interfaces.C.Extensions (i-cexten.ads) - -This package contains additional C-related definitions, intended -for use with either manually or automatically generated bindings -to C libraries. - -@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id130}@anchor{3d6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3d7} -@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) - - -@geindex Interfaces.C.Streams (i-cstrea.ads) - -@geindex C streams -@geindex interfacing - -This package is a binding for the most commonly used operations -on C streams. - -@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id131}@anchor{3d8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3d9} -@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) - - -@geindex Interfaces.Packed_Decimal (i-pacdec.ads) - -@geindex IBM Packed Format - -@geindex Packed Decimal - -This package provides a set of routines for conversions to and -from a packed decimal format compatible with that used on IBM -mainframes. - -@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id132}@anchor{3da}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3db} -@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) - - -@geindex Interfaces.VxWorks (i-vxwork.ads) - -@geindex Interfacing to VxWorks - -@geindex VxWorks -@geindex interfacing - -This package provides a limited binding to the VxWorks API. -In particular, it interfaces with the -VxWorks hardware interrupt facilities. - -@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id133}@anchor{3dc}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3dd} -@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) - - -@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) - -@geindex Interfacing to VxWorks - -@geindex VxWorks -@geindex interfacing - -This package provides a way for users to replace the use of -intConnect() with a custom routine for installing interrupt -handlers. - -@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id134}@anchor{3de}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3df} -@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) - - -@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) - -@geindex Interfacing to VxWorks' I/O - -@geindex VxWorks -@geindex I/O interfacing - -@geindex VxWorks -@geindex Get_Immediate - -@geindex Get_Immediate -@geindex VxWorks - -This package provides a binding to the ioctl (IO/Control) -function of VxWorks, defining a set of option values and -function codes. A particular use of this package is -to enable the use of Get_Immediate under VxWorks. - -@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id135}@anchor{3e0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e1} -@section @code{System.Address_Image} (@code{s-addima.ads}) - - -@geindex System.Address_Image (s-addima.ads) - -@geindex Address image - -@geindex Image -@geindex of an address - -This function provides a useful debugging -function that gives an (implementation dependent) -string which identifies an address. - -@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id136}@anchor{3e2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e3} -@section @code{System.Assertions} (@code{s-assert.ads}) - - -@geindex System.Assertions (s-assert.ads) - -@geindex Assertions - -@geindex Assert_Failure -@geindex exception - -This package provides the declaration of the exception raised -by an run-time assertion failure, as well as the routine that -is used internally to raise this assertion. - -@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3e5} -@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) - - -@geindex System.Atomic_Counters (s-atocou.ads) - -This package provides the declaration of an atomic counter type, -together with efficient routines (using hardware -synchronization primitives) for incrementing, decrementing, -and testing of these counters. This package is implemented -on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9, -x86, and x86_64 platforms. - -@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3e7} -@section @code{System.Memory} (@code{s-memory.ads}) - - -@geindex System.Memory (s-memory.ads) - -@geindex Memory allocation - -This package provides the interface to the low level routines used -by the generated code for allocation and freeing storage for the -default storage pool (analogous to the C routines malloc and free). -It also provides a reallocation interface analogous to the C routine -realloc. The body of this unit may be modified to provide alternative -allocation mechanisms for the default pool, and in addition, direct -calls to this unit may be made for low level allocation uses (for -example see the body of @code{GNAT.Tables}). - -@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3e9} -@section @code{System.Multiprocessors} (@code{s-multip.ads}) - - -@geindex System.Multiprocessors (s-multip.ads) - -@geindex Multiprocessor interface - -This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but -in GNAT we also make it available in Ada 95 and Ada 2005 (where it is -technically an implementation-defined addition). - -@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3eb} -@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) - - -@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) - -@geindex Multiprocessor interface - -This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but -in GNAT we also make it available in Ada 95 and Ada 2005 (where it is -technically an implementation-defined addition). - -@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3ed} -@section @code{System.Partition_Interface} (@code{s-parint.ads}) - - -@geindex System.Partition_Interface (s-parint.ads) - -@geindex Partition interfacing functions - -This package provides facilities for partition interfacing. It -is used primarily in a distribution context when using Annex E -with @code{GLADE}. - -@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ef} -@section @code{System.Pool_Global} (@code{s-pooglo.ads}) - - -@geindex System.Pool_Global (s-pooglo.ads) - -@geindex Storage pool -@geindex global - -@geindex Global storage pool - -This package provides a storage pool that is equivalent to the default -storage pool used for access types for which no pool is specifically -declared. It uses malloc/free to allocate/free and does not attempt to -do any automatic reclamation. - -@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f1} -@section @code{System.Pool_Local} (@code{s-pooloc.ads}) - - -@geindex System.Pool_Local (s-pooloc.ads) - -@geindex Storage pool -@geindex local - -@geindex Local storage pool - -This package provides a storage pool that is intended for use with locally -defined access types. It uses malloc/free for allocate/free, and maintains -a list of allocated blocks, so that all storage allocated for the pool can -be freed automatically when the pool is finalized. - -@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f3} -@section @code{System.Restrictions} (@code{s-restri.ads}) - - -@geindex System.Restrictions (s-restri.ads) - -@geindex Run-time restrictions access - -This package provides facilities for accessing at run time -the status of restrictions specified at compile time for -the partition. Information is available both with regard -to actual restrictions specified, and with regard to -compiler determined information on which restrictions -are violated by one or more packages in the partition. - -@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f5} -@section @code{System.Rident} (@code{s-rident.ads}) - - -@geindex System.Rident (s-rident.ads) - -@geindex Restrictions definitions - -This package provides definitions of the restrictions -identifiers supported by GNAT, and also the format of -the restrictions provided in package System.Restrictions. -It is not normally necessary to @code{with} this generic package -since the necessary instantiation is included in -package System.Restrictions. - -@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3f7} -@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) - - -@geindex System.Strings.Stream_Ops (s-ststop.ads) - -@geindex Stream operations - -@geindex String stream operations - -This package provides a set of stream subprograms for standard string types. -It is intended primarily to support implicit use of such subprograms when -stream attributes are applied to string types, but the subprograms in this -package can be used directly by application programs. - -@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3f9} -@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) - - -@geindex System.Unsigned_Types (s-unstyp.ads) - -This package contains definitions of standard unsigned types that -correspond in size to the standard signed types declared in Standard, -and (unlike the types in Interfaces) have corresponding names. It -also contains some related definitions for other specialized types -used by the compiler in connection with packed array types. - -@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3fb} -@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) - - -@geindex System.Wch_Cnv (s-wchcnv.ads) - -@geindex Wide Character -@geindex Representation - -@geindex Wide String -@geindex Conversion - -@geindex Representation of wide characters - -This package provides routines for converting between -wide and wide wide characters and a representation as a value of type -@code{Standard.String}, using a specified wide character -encoding method. It uses definitions in -package @code{System.Wch_Con}. - -@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library -@anchor{gnat_rm/the_gnat_library id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3fd} -@section @code{System.Wch_Con} (@code{s-wchcon.ads}) - - -@geindex System.Wch_Con (s-wchcon.ads) - -This package provides definitions and descriptions of -the various methods used for encoding wide characters -in ordinary strings. These definitions are used by -the package @code{System.Wch_Cnv}. - -@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top -@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3fe}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3ff}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11} -@chapter Interfacing to Other Languages - - -The facilities in Annex B of the Ada Reference Manual are fully -implemented in GNAT, and in addition, a full interface to C++ is -provided. - -@menu -* Interfacing to C:: -* Interfacing to C++:: -* Interfacing to COBOL:: -* Interfacing to Fortran:: -* Interfacing to non-GNAT Ada code:: - -@end menu - -@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages -@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{400}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{401} -@section Interfacing to C - - -Interfacing to C with GNAT can use one of two approaches: - - -@itemize * - -@item -The types in the package @code{Interfaces.C} may be used. - -@item -Standard Ada types may be used directly. This may be less portable to -other compilers, but will work on all GNAT compilers, which guarantee -correspondence between the C and Ada types. -@end itemize - -Pragma @code{Convention C} may be applied to Ada types, but mostly has no -effect, since this is the default. The following table shows the -correspondence between Ada scalar types and the corresponding C types. - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem - -Ada Type - -@tab - -C Type - -@item - -@code{Integer} - -@tab - -@code{int} - -@item - -@code{Short_Integer} - -@tab - -@code{short} - -@item - -@code{Short_Short_Integer} - -@tab - -@code{signed char} - -@item - -@code{Long_Integer} - -@tab - -@code{long} - -@item - -@code{Long_Long_Integer} - -@tab - -@code{long long} - -@item - -@code{Short_Float} - -@tab - -@code{float} - -@item - -@code{Float} - -@tab - -@code{float} - -@item - -@code{Long_Float} - -@tab - -@code{double} - -@item - -@code{Long_Long_Float} - -@tab - -This is the longest floating-point type supported by the hardware. - -@end multitable - - -Additionally, there are the following general correspondences between Ada -and C types: - - -@itemize * - -@item -Ada enumeration types map to C enumeration types directly if pragma -@code{Convention C} is specified, which causes them to have a length of -32 bits, except for boolean types which map to C99 @code{bool} and for -which the length is 8 bits. -Without pragma @code{Convention C}, Ada enumeration types map to -8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, -@code{int}, respectively) depending on the number of values passed. -This is the only case in which pragma @code{Convention C} affects the -representation of an Ada type. - -@item -Ada access types map to C pointers, except for the case of pointers to -unconstrained types in Ada, which have no direct C equivalent. - -@item -Ada arrays map directly to C arrays. - -@item -Ada records map directly to C structures. - -@item -Packed Ada records map to C structures where all members are bit fields -of the length corresponding to the @code{type'Size} value in Ada. -@end itemize - -@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages -@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{402} -@section Interfacing to C++ - - -The interface to C++ makes use of the following pragmas, which are -primarily intended to be constructed automatically using a binding generator -tool, although it is possible to construct them by hand. - -Using these pragmas it is possible to achieve complete -inter-operability between Ada tagged types and C++ class definitions. -See @ref{7,,Implementation Defined Pragmas}, for more details. - - -@table @asis - -@item @code{pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})} - -The argument denotes an entity in the current declarative region that is -declared as a tagged or untagged record type. It indicates that the type -corresponds to an externally declared C++ class type, and is to be laid -out the same way that C++ would lay out the type. - -Note: Pragma @code{CPP_Class} is currently obsolete. It is supported -for backward compatibility but its functionality is available -using pragma @code{Import} with @code{Convention} = @code{CPP}. - -@item @code{pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})} - -This pragma identifies an imported function (imported in the usual way -with pragma @code{Import}) as corresponding to a C++ constructor. -@end table - -A few restrictions are placed on the use of the @code{Access} attribute -in conjunction with subprograms subject to convention @code{CPP}: the -attribute may be used neither on primitive operations of a tagged -record type with convention @code{CPP}, imported or not, nor on -subprograms imported with pragma @code{CPP_Constructor}. - -In addition, C++ exceptions are propagated and can be handled in an -@code{others} choice of an exception handler. The corresponding Ada -occurrence has no message, and the simple name of the exception identity -contains @code{Foreign_Exception}. Finalization and awaiting dependent -tasks works properly when such foreign exceptions are propagated. - -It is also possible to import a C++ exception using the following syntax: - -@example -LOCAL_NAME : exception; -pragma Import (Cpp, - [Entity =>] LOCAL_NAME, - [External_Name =>] static_string_EXPRESSION); -@end example - -The @code{External_Name} is the name of the C++ RTTI symbol. You can then -cover a specific C++ exception in an exception handler. - -@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages -@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{403}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{404} -@section Interfacing to COBOL - - -Interfacing to COBOL is achieved as described in section B.4 of -the Ada Reference Manual. - -@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages -@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{405}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{406} -@section Interfacing to Fortran - - -Interfacing to Fortran is achieved as described in section B.5 of the -Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a -multi-dimensional array causes the array to be stored in column-major -order as required for convenient interface to Fortran. - -@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages -@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{407}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{408} -@section Interfacing to non-GNAT Ada code - - -It is possible to specify the convention @code{Ada} in a pragma -@code{Import} or pragma @code{Export}. However this refers to -the calling conventions used by GNAT, which may or may not be -similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 -compiler to allow interoperation. - -If arguments types are kept simple, and if the foreign compiler generally -follows system calling conventions, then it may be possible to integrate -files compiled by other Ada compilers, provided that the elaboration -issues are adequately addressed (for example by eliminating the -need for any load time elaboration). - -In particular, GNAT running on VMS is designed to -be highly compatible with the DEC Ada 83 compiler, so this is one -case in which it is possible to import foreign units of this type, -provided that the data items passed are restricted to simple scalar -values or simple record types without variants, or simple array -types with fixed bounds. - -@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top -@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{409}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{40a}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12} -@chapter Specialized Needs Annexes - - -Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not -required in all implementations. However, as described in this chapter, -GNAT implements all of these annexes: - - -@table @asis - -@item `Systems Programming (Annex C)' - -The Systems Programming Annex is fully implemented. - -@item `Real-Time Systems (Annex D)' - -The Real-Time Systems Annex is fully implemented. - -@item `Distributed Systems (Annex E)' - -Stub generation is fully implemented in the GNAT compiler. In addition, -a complete compatible PCS is available as part of the GLADE system, -a separate product. When the two -products are used in conjunction, this annex is fully implemented. - -@item `Information Systems (Annex F)' - -The Information Systems annex is fully implemented. - -@item `Numerics (Annex G)' - -The Numerics Annex is fully implemented. - -@item `Safety and Security / High-Integrity Systems (Annex H)' - -The Safety and Security Annex (termed the High-Integrity Systems Annex -in Ada 2005) is fully implemented. -@end table - -@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top -@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{40b}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{40c}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13} -@chapter Implementation of Specific Ada Features - - -This chapter describes the GNAT implementation of several Ada language -facilities. - -@menu -* Machine Code Insertions:: -* GNAT Implementation of Tasking:: -* GNAT Implementation of Shared Passive Packages:: -* Code Generation for Array Aggregates:: -* The Size of Discriminated Records with Default Discriminants:: -* Image Values For Nonscalar Types:: -* Strict Conformance to the Ada Reference Manual:: - -@end menu - -@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{40d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{166} -@section Machine Code Insertions - - -@geindex Machine Code insertions - -Package @code{Machine_Code} provides machine code support as described -in the Ada Reference Manual in two separate forms: - - -@itemize * - -@item -Machine code statements, consisting of qualified expressions that -fit the requirements of RM section 13.8. - -@item -An intrinsic callable procedure, providing an alternative mechanism of -including machine instructions in a subprogram. -@end itemize - -The two features are similar, and both are closely related to the mechanism -provided by the asm instruction in the GNU C compiler. Full understanding -and use of the facilities in this package requires understanding the asm -instruction, see the section on Extended Asm in -@cite{Using_the_GNU_Compiler_Collection_(GCC)}. - -Calls to the function @code{Asm} and the procedure @code{Asm} have identical -semantic restrictions and effects as described below. Both are provided so -that the procedure call can be used as a statement, and the function call -can be used to form a code_statement. - -Consider this C @code{asm} instruction: - -@example -asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); -@end example - -The equivalent can be written for GNAT as: - -@example -Asm ("fsinx %1 %0", - My_Float'Asm_Output ("=f", result), - My_Float'Asm_Input ("f", angle)); -@end example - -The first argument to @code{Asm} is the assembler template, and is -identical to what is used in GNU C. This string must be a static -expression. The second argument is the output operand list. It is -either a single @code{Asm_Output} attribute reference, or a list of such -references enclosed in parentheses (technically an array aggregate of -such references). - -The @code{Asm_Output} attribute denotes a function that takes two -parameters. The first is a string, the second is the name of a variable -of the type designated by the attribute prefix. The first (string) -argument is required to be a static expression and designates the -constraint (see the section on Constraints in -@cite{Using_the_GNU_Compiler_Collection_(GCC)}) -for the parameter; e.g., what kind of register is required. The second -argument is the variable to be written or updated with the -result. The possible values for constraint are the same as those used in -the RTL, and are dependent on the configuration file used to build the -GCC back end. If there are no output operands, then this argument may -either be omitted, or explicitly given as @code{No_Output_Operands}. -No support is provided for GNU C’s symbolic names for output parameters. - -The second argument of @code{my_float'Asm_Output} functions as -though it were an @code{out} parameter, which is a little curious, but -all names have the form of expressions, so there is no syntactic -irregularity, even though normally functions would not be permitted -@code{out} parameters. The third argument is the list of input -operands. It is either a single @code{Asm_Input} attribute reference, or -a list of such references enclosed in parentheses (technically an array -aggregate of such references). - -The @code{Asm_Input} attribute denotes a function that takes two -parameters. The first is a string, the second is an expression of the -type designated by the prefix. The first (string) argument is required -to be a static expression, and is the constraint for the parameter, -(e.g., what kind of register is required). The second argument is the -value to be used as the input argument. The possible values for the -constraint are the same as those used in the RTL, and are dependent on -the configuration file used to built the GCC back end. -No support is provided for GNU C’s symbolic names for input parameters. - -If there are no input operands, this argument may either be omitted, or -explicitly given as @code{No_Input_Operands}. The fourth argument, not -present in the above example, is a list of register names, called the -`clobber' argument. This argument, if given, must be a static string -expression, and is a space or comma separated list of names of registers -that must be considered destroyed as a result of the @code{Asm} call. If -this argument is the null string (the default value), then the code -generator assumes that no additional registers are destroyed. -In addition to registers, the special clobbers @code{memory} and -@code{cc} as described in the GNU C docs are both supported. - -The fifth argument, not present in the above example, called the -`volatile' argument, is by default @code{False}. It can be set to -the literal value @code{True} to indicate to the code generator that all -optimizations with respect to the instruction specified should be -suppressed, and in particular an instruction that has outputs -will still be generated, even if none of the outputs are -used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} -for the full description. -Generally it is strongly advisable to use Volatile for any ASM statement -that is missing either input or output operands or to avoid unwanted -optimizations. A warning is generated if this advice is not followed. - -No support is provided for GNU C’s @code{asm goto} feature. - -The @code{Asm} subprograms may be used in two ways. First the procedure -forms can be used anywhere a procedure call would be valid, and -correspond to what the RM calls ‘intrinsic’ routines. Such calls can -be used to intersperse machine instructions with other Ada statements. -Second, the function forms, which return a dummy value of the limited -private type @code{Asm_Insn}, can be used in code statements, and indeed -this is the only context where such calls are allowed. Code statements -appear as aggregates of the form: - -@example -Asm_Insn'(Asm (...)); -Asm_Insn'(Asm_Volatile (...)); -@end example - -In accordance with RM rules, such code statements are allowed only -within subprograms whose entire body consists of such statements. It is -not permissible to intermix such statements with other Ada statements. - -Typically the form using intrinsic procedure calls is more convenient -and more flexible. The code statement form is provided to meet the RM -suggestion that such a facility should be made available. The following -is the exact syntax of the call to @code{Asm}. As usual, if named notation -is used, the arguments may be given in arbitrary order, following the -normal rules for use of positional and named arguments: - -@example -ASM_CALL ::= Asm ( - [Template =>] static_string_EXPRESSION - [,[Outputs =>] OUTPUT_OPERAND_LIST ] - [,[Inputs =>] INPUT_OPERAND_LIST ] - [,[Clobber =>] static_string_EXPRESSION ] - [,[Volatile =>] static_boolean_EXPRESSION] ) - -OUTPUT_OPERAND_LIST ::= - [PREFIX.]No_Output_Operands -| OUTPUT_OPERAND_ATTRIBUTE -| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) - -OUTPUT_OPERAND_ATTRIBUTE ::= - SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) - -INPUT_OPERAND_LIST ::= - [PREFIX.]No_Input_Operands -| INPUT_OPERAND_ATTRIBUTE -| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) - -INPUT_OPERAND_ATTRIBUTE ::= - SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) -@end example - -The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} -are declared in the package @code{Machine_Code} and must be referenced -according to normal visibility rules. In particular if there is no -@code{use} clause for this package, then appropriate package name -qualification is required. - -@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{40e}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{40f} -@section GNAT Implementation of Tasking - - -This chapter outlines the basic GNAT approach to tasking (in particular, -a multi-layered library for portability) and discusses issues related -to compliance with the Real-Time Systems Annex. - -@menu -* Mapping Ada Tasks onto the Underlying Kernel Threads:: -* Ensuring Compliance with the Real-Time Annex:: -* Support for Locking Policies:: - -@end menu - -@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking -@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{410}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{411} -@subsection Mapping Ada Tasks onto the Underlying Kernel Threads - - -GNAT’s run-time support comprises two layers: - - -@itemize * - -@item -GNARL (GNAT Run-time Layer) - -@item -GNULL (GNAT Low-level Library) -@end itemize - -In GNAT, Ada’s tasking services rely on a platform and OS independent -layer known as GNARL. This code is responsible for implementing the -correct semantics of Ada’s task creation, rendezvous, protected -operations etc. - -GNARL decomposes Ada’s tasking semantics into simpler lower level -operations such as create a thread, set the priority of a thread, -yield, create a lock, lock/unlock, etc. The spec for these low-level -operations constitutes GNULLI, the GNULL Interface. This interface is -directly inspired from the POSIX real-time API. - -If the underlying executive or OS implements the POSIX standard -faithfully, the GNULL Interface maps as is to the services offered by -the underlying kernel. Otherwise, some target dependent glue code maps -the services offered by the underlying kernel to the semantics expected -by GNARL. - -Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the -key point is that each Ada task is mapped on a thread in the underlying -kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. - -In addition Ada task priorities map onto the underlying thread priorities. -Mapping Ada tasks onto the underlying kernel threads has several advantages: - - -@itemize * - -@item -The underlying scheduler is used to schedule the Ada tasks. This -makes Ada tasks as efficient as kernel threads from a scheduling -standpoint. - -@item -Interaction with code written in C containing threads is eased -since at the lowest level Ada tasks and C threads map onto the same -underlying kernel concept. - -@item -When an Ada task is blocked during I/O the remaining Ada tasks are -able to proceed. - -@item -On multiprocessor systems Ada tasks can execute in parallel. -@end itemize - -Some threads libraries offer a mechanism to fork a new process, with the -child process duplicating the threads from the parent. -GNAT does not -support this functionality when the parent contains more than one task. - -@geindex Forking a new process - -@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking -@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{412}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{413} -@subsection Ensuring Compliance with the Real-Time Annex - - -@geindex Real-Time Systems Annex compliance - -Although mapping Ada tasks onto -the underlying threads has significant advantages, it does create some -complications when it comes to respecting the scheduling semantics -specified in the real-time annex (Annex D). - -For instance the Annex D requirement for the @code{FIFO_Within_Priorities} -scheduling policy states: - -@quotation - -`When the active priority of a ready task that is not running -changes, or the setting of its base priority takes effect, the -task is removed from the ready queue for its old active priority -and is added at the tail of the ready queue for its new active -priority, except in the case where the active priority is lowered -due to the loss of inherited priority, in which case the task is -added at the head of the ready queue for its new active priority.' -@end quotation - -While most kernels do put tasks at the end of the priority queue when -a task changes its priority, (which respects the main -FIFO_Within_Priorities requirement), almost none keep a thread at the -beginning of its priority queue when its priority drops from the loss -of inherited priority. - -As a result most vendors have provided incomplete Annex D implementations. - -The GNAT run-time, has a nice cooperative solution to this problem -which ensures that accurate FIFO_Within_Priorities semantics are -respected. - -The principle is as follows. When an Ada task T is about to start -running, it checks whether some other Ada task R with the same -priority as T has been suspended due to the loss of priority -inheritance. If this is the case, T yields and is placed at the end of -its priority queue. When R arrives at the front of the queue it -executes. - -Note that this simple scheme preserves the relative order of the tasks -that were ready to execute in the priority queue where R has been -placed at the end. - -@c Support_for_Locking_Policies - -@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking -@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{414} -@subsection Support for Locking Policies - - -This section specifies which policies specified by pragma Locking_Policy -are supported on which platforms. - -GNAT supports the standard @code{Ceiling_Locking} policy, and the -implementation defined @code{Inheritance_Locking} and -@code{Concurrent_Readers_Locking} policies. - -@code{Ceiling_Locking} is supported on all platforms if the operating system -supports it. In particular, @code{Ceiling_Locking} is not supported on -VxWorks. -@code{Inheritance_Locking} is supported on -Linux, -Darwin (Mac OS X), -LynxOS 178, -and VxWorks. -@code{Concurrent_Readers_Locking} is supported on Linux. - -Notes about @code{Ceiling_Locking} on Linux: -If the process is running as ‘root’, ceiling locking is used. -If the capabilities facility is installed -(“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, -for example), -and the program is linked against that library -(“-largs -lcap”), -and the executable file has the cap_sys_nice capability -(“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), -then ceiling locking is used. -Otherwise, the @code{Ceiling_Locking} policy is ignored. - -@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{416} -@section GNAT Implementation of Shared Passive Packages - - -@geindex Shared passive packages - -GNAT fully implements the -@geindex pragma Shared_Passive -pragma -@code{Shared_Passive} for -the purpose of designating shared passive packages. -This allows the use of passive partitions in the -context described in the Ada Reference Manual; i.e., for communication -between separate partitions of a distributed application using the -features in Annex E. - -@geindex Annex E - -@geindex Distribution Systems Annex - -However, the implementation approach used by GNAT provides for more -extensive usage as follows: - - -@table @asis - -@item `Communication between separate programs' - -This allows separate programs to access the data in passive -partitions, using protected objects for synchronization where -needed. The only requirement is that the two programs have a -common shared file system. It is even possible for programs -running on different machines with different architectures -(e.g., different endianness) to communicate via the data in -a passive partition. - -@item `Persistence between program runs' - -The data in a passive package can persist from one run of a -program to another, so that a later program sees the final -values stored by a previous run of the same program. -@end table - -The implementation approach used is to store the data in files. A -separate stream file is created for each object in the package, and -an access to an object causes the corresponding file to be read or -written. - -@geindex SHARED_MEMORY_DIRECTORY environment variable - -The environment variable @code{SHARED_MEMORY_DIRECTORY} should be -set to the directory to be used for these files. -The files in this directory -have names that correspond to their fully qualified names. For -example, if we have the package - -@example -package X is - pragma Shared_Passive (X); - Y : Integer; - Z : Float; -end X; -@end example - -and the environment variable is set to @code{/stemp/}, then the files created -will have the names: - -@example -/stemp/x.y -/stemp/x.z -@end example - -These files are created when a value is initially written to the object, and -the files are retained until manually deleted. This provides the persistence -semantics. If no file exists, it means that no partition has assigned a value -to the variable; in this case the initial value declared in the package -will be used. This model ensures that there are no issues in synchronizing -the elaboration process, since elaboration of passive packages elaborates the -initial values, but does not create the files. - -The files are written using normal @code{Stream_IO} access. -If you want to be able -to communicate between programs or partitions running on different -architectures, then you should use the XDR versions of the stream attribute -routines, since these are architecture independent. - -If active synchronization is required for access to the variables in the -shared passive package, then as described in the Ada Reference Manual, the -package may contain protected objects used for this purpose. In this case -a lock file (whose name is @code{___lock}, with three underscores) -is created in the shared memory directory. - -@geindex ___lock file (for shared passive packages) - -This is used to provide the required locking -semantics for proper protected object synchronization. - -@node Code Generation for Array Aggregates,The Size of Discriminated Records with Default Discriminants,GNAT Implementation of Shared Passive Packages,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{418} -@section Code Generation for Array Aggregates - - -Aggregates have a rich syntax and allow the user to specify the values of -complex data structures by means of a single construct. As a result, the -code generated for aggregates can be quite complex and involve loops, case -statements and multiple assignments. In the simplest cases, however, the -compiler will recognize aggregates whose components and constraints are -fully static, and in those cases the compiler will generate little or no -executable code. The following is an outline of the code that GNAT generates -for various aggregate constructs. For further details, you will find it -useful to examine the output produced by the -gnatG flag to see the expanded -source that is input to the code generator. You may also want to examine -the assembly code generated at various levels of optimization. - -The code generated for aggregates depends on the context, the component values, -and the type. In the context of an object declaration the code generated is -generally simpler than in the case of an assignment. As a general rule, static -component values and static subtypes also lead to simpler code. - -@menu -* Static constant aggregates with static bounds:: -* Constant aggregates with unconstrained nominal types:: -* Aggregates with static bounds:: -* Aggregates with nonstatic bounds:: -* Aggregates in assignment statements:: - -@end menu - -@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates -@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{41a} -@subsection Static constant aggregates with static bounds - - -For the declarations: - -@example -type One_Dim is array (1..10) of integer; -ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); -@end example - -GNAT generates no executable code: the constant ar0 is placed in static memory. -The same is true for constant aggregates with named associations: - -@example -Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); -Cr3 : constant One_Dim := (others => 7777); -@end example - -The same is true for multidimensional constant arrays such as: - -@example -type two_dim is array (1..3, 1..3) of integer; -Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); -@end example - -The same is true for arrays of one-dimensional arrays: the following are -static: - -@example -type ar1b is array (1..3) of boolean; -type ar_ar is array (1..3) of ar1b; -None : constant ar1b := (others => false); -- fully static -None2 : constant ar_ar := (1..3 => None); -- fully static -@end example - -However, for multidimensional aggregates with named associations, GNAT will -generate assignments and loops, even if all associations are static. The -following two declarations generate a loop for the first dimension, and -individual component assignments for the second dimension: - -@example -Zero1: constant two_dim := (1..3 => (1..3 => 0)); -Zero2: constant two_dim := (others => (others => 0)); -@end example - -@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates -@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{41c} -@subsection Constant aggregates with unconstrained nominal types - - -In such cases the aggregate itself establishes the subtype, so that -associations with @code{others} cannot be used. GNAT determines the -bounds for the actual subtype of the aggregate, and allocates the -aggregate statically as well. No code is generated for the following: - -@example -type One_Unc is array (natural range <>) of integer; -Cr_Unc : constant One_Unc := (12,24,36); -@end example - -@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates -@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{41e} -@subsection Aggregates with static bounds - - -In all previous examples the aggregate was the initial (and immutable) value -of a constant. If the aggregate initializes a variable, then code is generated -for it as a combination of individual assignments and loops over the target -object. The declarations - -@example -Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); -Cr_Var2 : One_Dim := (others > -1); -@end example - -generate the equivalent of - -@example -Cr_Var1 (1) := 2; -Cr_Var1 (2) := 3; -Cr_Var1 (3) := 5; -Cr_Var1 (4) := 11; - -for I in Cr_Var2'range loop - Cr_Var2 (I) := -1; -end loop; -@end example - -@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates -@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{420} -@subsection Aggregates with nonstatic bounds - - -If the bounds of the aggregate are not statically compatible with the bounds -of the nominal subtype of the target, then constraint checks have to be -generated on the bounds. For a multidimensional array, constraint checks may -have to be applied to sub-arrays individually, if they do not have statically -compatible subtypes. - -@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates -@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{422} -@subsection Aggregates in assignment statements - - -In general, aggregate assignment requires the construction of a temporary, -and a copy from the temporary to the target of the assignment. This is because -it is not always possible to convert the assignment into a series of individual -component assignments. For example, consider the simple case: - -@example -A := (A(2), A(1)); -@end example - -This cannot be converted into: - -@example -A(1) := A(2); -A(2) := A(1); -@end example - -So the aggregate has to be built first in a separate location, and then -copied into the target. GNAT recognizes simple cases where this intermediate -step is not required, and the assignments can be performed in place, directly -into the target. The following sufficient criteria are applied: - - -@itemize * - -@item -The bounds of the aggregate are static, and the associations are static. - -@item -The components of the aggregate are static constants, names of -simple variables that are not renamings, or expressions not involving -indexed components whose operands obey these rules. -@end itemize - -If any of these conditions are violated, the aggregate will be built in -a temporary (created either by the front-end or the code generator) and then -that temporary will be copied onto the target. - -@node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{424} -@section The Size of Discriminated Records with Default Discriminants - - -If a discriminated type @code{T} has discriminants with default values, it is -possible to declare an object of this type without providing an explicit -constraint: - -@example -type Size is range 1..100; - -type Rec (D : Size := 15) is record - Name : String (1..D); -end T; - -Word : Rec; -@end example - -Such an object is said to be `unconstrained'. -The discriminant of the object -can be modified by a full assignment to the object, as long as it preserves the -relation between the value of the discriminant, and the value of the components -that depend on it: - -@example -Word := (3, "yes"); - -Word := (5, "maybe"); - -Word := (5, "no"); -- raises Constraint_Error -@end example - -In order to support this behavior efficiently, an unconstrained object is -given the maximum size that any value of the type requires. In the case -above, @code{Word} has storage for the discriminant and for -a @code{String} of length 100. -It is important to note that unconstrained objects do not require dynamic -allocation. It would be an improper implementation to place on the heap those -components whose size depends on discriminants. (This improper implementation -was used by some Ada83 compilers, where the @code{Name} component above -would have -been stored as a pointer to a dynamic string). Following the principle that -dynamic storage management should never be introduced implicitly, -an Ada compiler should reserve the full size for an unconstrained declared -object, and place it on the stack. - -This maximum size approach -has been a source of surprise to some users, who expect the default -values of the discriminants to determine the size reserved for an -unconstrained object: “If the default is 15, why should the object occupy -a larger size?” -The answer, of course, is that the discriminant may be later modified, -and its full range of values must be taken into account. This is why the -declaration: - -@example -type Rec (D : Positive := 15) is record - Name : String (1..D); -end record; - -Too_Large : Rec; -@end example - -is flagged by the compiler with a warning: -an attempt to create @code{Too_Large} will raise @code{Storage_Error}, -because the required size includes @code{Positive'Last} -bytes. As the first example indicates, the proper approach is to declare an -index type of ‘reasonable’ range so that unconstrained objects are not too -large. - -One final wrinkle: if the object is declared to be @code{aliased}, or if it is -created in the heap by means of an allocator, then it is `not' -unconstrained: -it is constrained by the default values of the discriminants, and those values -cannot be modified by full assignment. This is because in the presence of -aliasing all views of the object (which may be manipulated by different tasks, -say) must be consistent, so it is imperative that the object, once created, -remain invariant. - -@node Image Values For Nonscalar Types,Strict Conformance to the Ada Reference Manual,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{426} -@section Image Values For Nonscalar Types - - -Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes -for nonscalar types; earlier Ada versions defined these attributes only -for scalar types. Ada RM 4.10 provides some general guidance regarding -the default implementation of these attributes and the GNAT compiler -follows that guidance. However, beyond that the precise details of the -image text generated in these cases are deliberately not documented and are -subject to change. In particular, users should not rely on formatting details -(such as spaces or line breaking), record field order, image values for access -types, image values for types that have ancestor or subcomponent types -declared in non-Ada2022 code, image values for predefined types, or the -compiler’s choices regarding the implementation permissions described in -Ada RM 4.10. This list is not intended to be exhaustive. If more precise -control of image text is required for some type T, then T’Put_Image should be -explicitly specified. - -@node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features -@anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{428} -@section Strict Conformance to the Ada Reference Manual - - -The dynamic semantics defined by the Ada Reference Manual impose a set of -run-time checks to be generated. By default, the GNAT compiler will insert many -run-time checks into the compiled code, including most of those required by the -Ada Reference Manual. However, there are two checks that are not enabled in -the default mode for efficiency reasons: checks for access before elaboration -on subprogram calls, and stack overflow checking (most operating systems do not -perform this check by default). - -Strict conformance to the Ada Reference Manual can be achieved by adding two -compiler options for dynamic checks for access-before-elaboration on subprogram -calls and generic instantiations (`-gnatE'), and stack overflow checking -(`-fstack-check'). - -Note that the result of a floating point arithmetic operation in overflow and -invalid situations, when the @code{Machine_Overflows} attribute of the result -type is @code{False}, is to generate IEEE NaN and infinite values. This is the -case for machines compliant with the IEEE floating-point standard, but on -machines that are not fully compliant with this standard, such as Alpha, the -`-mieee' compiler flag must be used for achieving IEEE confirming -behavior (although at the cost of a significant performance penalty), so -infinite and NaN values are properly generated. - -@node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top -@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{429}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{42a}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14} -@chapter Implementation of Ada 2012 Features - - -@geindex Ada 2012 implementation status - -@geindex -gnat12 option (gcc) - -@geindex pragma Ada_2012 - -@geindex configuration pragma Ada_2012 - -@geindex Ada_2012 configuration pragma - -This chapter contains a complete list of Ada 2012 features that have been -implemented. -Generally, these features are only -available if the `-gnat12' (Ada 2012 features enabled) option is set, -which is the default behavior, -or if the configuration pragma @code{Ada_2012} is used. - -However, new pragmas, attributes, and restrictions are -unconditionally available, since the Ada 95 standard allows the addition of -new pragmas, attributes, and restrictions (there are exceptions, which are -documented in the individual descriptions), and also certain packages -were made available in earlier versions of Ada. - -An ISO date (YYYY-MM-DD) appears in parentheses on the description line. -This date shows the implementation date of the feature. Any wavefront -subsequent to this date will contain the indicated feature, as will any -subsequent releases. A date of 0000-00-00 means that GNAT has always -implemented the feature, or implemented it as soon as it appeared as a -binding interpretation. - -Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada -standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. -The features are ordered based on the relevant sections of the Ada -Reference Manual (“RM”). When a given AI relates to multiple points -in the RM, the earliest is used. - -A complete description of the AIs may be found in -@indicateurl{http://www.ada-auth.org/ai05-summary.html}. - -@geindex AI-0176 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0176 Quantified expressions (2010-09-29)' - -Both universally and existentially quantified expressions are implemented. -They use the new syntax for iterators proposed in AI05-139-2, as well as -the standard Ada loop syntax. - -RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) -@end itemize - -@geindex AI-0079 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0079 Allow other_format characters in source (2010-07-10)' - -Wide characters in the unicode category `other_format' are now allowed in -source programs between tokens, but not within a token such as an identifier. - -RM References: 2.01 (4/2) 2.02 (7) -@end itemize - -@geindex AI-0091 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0091 Do not allow other_format in identifiers (0000-00-00)' - -Wide characters in the unicode category `other_format' are not permitted -within an identifier, since this can be a security problem. The error -message for this case has been improved to be more specific, but GNAT has -never allowed such characters to appear in identifiers. - -RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2) -@end itemize - -@geindex AI-0100 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0100 Placement of pragmas (2010-07-01)' - -This AI is an earlier version of AI-163. It simplifies the rules -for legal placement of pragmas. In the case of lists that allow pragmas, if -the list may have no elements, then the list may consist solely of pragmas. - -RM References: 2.08 (7) -@end itemize - -@geindex AI-0163 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0163 Pragmas in place of null (2010-07-01)' - -A statement sequence may be composed entirely of pragmas. It is no longer -necessary to add a dummy @code{null} statement to make the sequence legal. - -RM References: 2.08 (7) 2.08 (16) -@end itemize - -@geindex AI-0080 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0080 ‘View of’ not needed if clear from context (0000-00-00)' - -This is an editorial change only, described as non-testable in the AI. - -RM References: 3.01 (7) -@end itemize - -@geindex AI-0183 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0183 Aspect specifications (2010-08-16)' - -Aspect specifications have been fully implemented except for pre and post- -conditions, and type invariants, which have their own separate AI’s. All -forms of declarations listed in the AI are supported. The following is a -list of the aspects supported (with GNAT implementation aspects marked) -@end itemize - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} -@headitem - -Supported Aspect - -@tab - -Source - -@item - -@code{Ada_2005} - -@tab - -– GNAT - -@item - -@code{Ada_2012} - -@tab - -– GNAT - -@item - -@code{Address} - -@tab - -@item - -@code{Alignment} - -@tab - -@item - -@code{Atomic} - -@tab - -@item - -@code{Atomic_Components} - -@tab - -@item - -@code{Bit_Order} - -@tab - -@item - -@code{Component_Size} - -@tab - -@item - -@code{Contract_Cases} - -@tab - -– GNAT - -@item - -@code{Discard_Names} - -@tab - -@item - -@code{External_Tag} - -@tab - -@item - -@code{Favor_Top_Level} - -@tab - -– GNAT - -@item - -@code{Inline} - -@tab - -@item - -@code{Inline_Always} - -@tab - -– GNAT - -@item - -@code{Invariant} - -@tab - -– GNAT - -@item - -@code{Machine_Radix} - -@tab - -@item - -@code{No_Return} - -@tab - -@item - -@code{Object_Size} - -@tab - -– GNAT - -@item - -@code{Pack} - -@tab - -@item - -@code{Persistent_BSS} - -@tab - -– GNAT - -@item - -@code{Post} - -@tab - -@item - -@code{Pre} - -@tab - -@item - -@code{Predicate} - -@tab - -@item - -@code{Preelaborable_Initialization} - -@tab - -@item - -@code{Pure_Function} - -@tab - -– GNAT - -@item - -@code{Remote_Access_Type} - -@tab - -– GNAT - -@item - -@code{Shared} - -@tab - -– GNAT - -@item - -@code{Size} - -@tab - -@item - -@code{Storage_Pool} - -@tab - -@item - -@code{Storage_Size} - -@tab - -@item - -@code{Stream_Size} - -@tab - -@item - -@code{Suppress} - -@tab - -@item - -@code{Suppress_Debug_Info} - -@tab - -– GNAT - -@item - -@code{Test_Case} - -@tab - -– GNAT - -@item - -@code{Thread_Local_Storage} - -@tab - -– GNAT - -@item - -@code{Type_Invariant} - -@tab - -@item - -@code{Unchecked_Union} - -@tab - -@item - -@code{Universal_Aliasing} - -@tab - -– GNAT - -@item - -@code{Unmodified} - -@tab - -– GNAT - -@item - -@code{Unreferenced} - -@tab - -– GNAT - -@item - -@code{Unreferenced_Objects} - -@tab - -– GNAT - -@item - -@code{Unsuppress} - -@tab - -@item - -@code{Value_Size} - -@tab - -– GNAT - -@item - -@code{Volatile} - -@tab - -@item - -@code{Volatile_Components} - -@tab - -@item - -@code{Warnings} - -@tab - -– GNAT - -@end multitable - - -@quotation - -Note that for aspects with an expression, e.g. @code{Size}, the expression is -treated like a default expression (visibility is analyzed at the point of -occurrence of the aspect, but evaluation of the expression occurs at the -freeze point of the entity involved). - -RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) -3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 -(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) -9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) -12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) -13.03.01 (0) -@end quotation - -@geindex AI-0128 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0128 Inequality is a primitive operation (0000-00-00)' - -If an equality operator (“=”) is declared for a type, then the implicitly -declared inequality operator (“/=”) is a primitive operation of the type. -This is the only reasonable interpretation, and is the one always implemented -by GNAT, but the RM was not entirely clear in making this point. - -RM References: 3.02.03 (6) 6.06 (6) -@end itemize - -@geindex AI-0003 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0003 Qualified expressions as names (2010-07-11)' - -In Ada 2012, a qualified expression is considered to be syntactically a name, -meaning that constructs such as @code{A'(F(X)).B} are now legal. This is -useful in disambiguating some cases of overloading. - -RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) -5.04 (7) -@end itemize - -@geindex AI-0120 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0120 Constant instance of protected object (0000-00-00)' - -This is an RM editorial change only. The section that lists objects that are -constant failed to include the current instance of a protected object -within a protected function. This has always been treated as a constant -in GNAT. - -RM References: 3.03 (21) -@end itemize - -@geindex AI-0008 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0008 General access to constrained objects (0000-00-00)' - -The wording in the RM implied that if you have a general access to a -constrained object, it could be used to modify the discriminants. This was -obviously not intended. @code{Constraint_Error} should be raised, and GNAT -has always done so in this situation. - -RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) -@end itemize - -@geindex AI-0093 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0093 Additional rules use immutably limited (0000-00-00)' - -This is an editorial change only, to make more widespread use of the Ada 2012 -‘immutably limited’. - -RM References: 3.03 (23.4/3) -@end itemize - -@geindex AI-0096 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0096 Deriving from formal private types (2010-07-20)' - -In general it is illegal for a type derived from a formal limited type to be -nonlimited. This AI makes an exception to this rule: derivation is legal -if it appears in the private part of the generic, and the formal type is not -tagged. If the type is tagged, the legality check must be applied to the -private part of the package. - -RM References: 3.04 (5.1/2) 6.02 (7) -@end itemize - -@geindex AI-0181 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0181 Soft hyphen is a non-graphic character (2010-07-23)' - -From Ada 2005 on, soft hyphen is considered a non-graphic character, which -means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the -@code{Image} and @code{Value} attributes for the character types. Strictly -speaking this is an inconsistency with Ada 95, but in practice the use of -these attributes is so obscure that it will not cause problems. - -RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) -@end itemize - -@geindex AI-0182 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0182 Additional forms for' @code{Character'Value} `(0000-00-00)' - -This AI allows @code{Character'Value} to accept the string @code{'?'} where -@code{?} is any character including non-graphic control characters. GNAT has -always accepted such strings. It also allows strings such as -@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this -permission and raises @code{Constraint_Error}, as is certainly still -permitted. - -RM References: 3.05 (56/2) -@end itemize - -@geindex AI-0214 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0214 Defaulted discriminants for limited tagged (2010-10-01)' - -Ada 2012 relaxes the restriction that forbids discriminants of tagged types -to have default expressions by allowing them when the type is limited. It -is often useful to define a default value for a discriminant even though -it can’t be changed by assignment. - -RM References: 3.07 (9.1/2) 3.07.02 (3) -@end itemize - -@geindex AI-0102 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0102 Some implicit conversions are illegal (0000-00-00)' - -It is illegal to assign an anonymous access constant to an anonymous access -variable. The RM did not have a clear rule to prevent this, but GNAT has -always generated an error for this usage. - -RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) -@end itemize - -@geindex AI-0158 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0158 Generalizing membership tests (2010-09-16)' - -This AI extends the syntax of membership tests to simplify complex conditions -that can be expressed as membership in a subset of values of any type. It -introduces syntax for a list of expressions that may be used in loop contexts -as well. - -RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) -@end itemize - -@geindex AI-0173 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0173 Testing if tags represent abstract types (2010-07-03)' - -The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked -with the tag of an abstract type, and @code{False} otherwise. - -RM References: 3.09 (7.4/2) 3.09 (12.4/2) -@end itemize - -@geindex AI-0076 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0076 function with controlling result (0000-00-00)' - -This is an editorial change only. The RM defines calls with controlling -results, but uses the term ‘function with controlling result’ without an -explicit definition. - -RM References: 3.09.02 (2/2) -@end itemize - -@geindex AI-0126 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0126 Dispatching with no declared operation (0000-00-00)' - -This AI clarifies dispatching rules, and simply confirms that dispatching -executes the operation of the parent type when there is no explicitly or -implicitly declared operation for the descendant type. This has always been -the case in all versions of GNAT. - -RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) -@end itemize - -@geindex AI-0097 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0097 Treatment of abstract null extension (2010-07-19)' - -The RM as written implied that in some cases it was possible to create an -object of an abstract type, by having an abstract extension inherit a non- -abstract constructor from its parent type. This mistake has been corrected -in GNAT and in the RM, and this construct is now illegal. - -RM References: 3.09.03 (4/2) -@end itemize - -@geindex AI-0203 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0203 Extended return cannot be abstract (0000-00-00)' - -A return_subtype_indication cannot denote an abstract subtype. GNAT has never -permitted such usage. - -RM References: 3.09.03 (8/3) -@end itemize - -@geindex AI-0198 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0198 Inheriting abstract operators (0000-00-00)' - -This AI resolves a conflict between two rules involving inherited abstract -operations and predefined operators. If a derived numeric type inherits -an abstract operator, it overrides the predefined one. This interpretation -was always the one implemented in GNAT. - -RM References: 3.09.03 (4/3) -@end itemize - -@geindex AI-0073 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0073 Functions returning abstract types (2010-07-10)' - -This AI covers a number of issues regarding returning abstract types. In -particular generic functions cannot have abstract result types or access -result types designated an abstract type. There are some other cases which -are detailed in the AI. Note that this binding interpretation has not been -retrofitted to operate before Ada 2012 mode, since it caused a significant -number of regressions. - -RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) -@end itemize - -@geindex AI-0070 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0070 Elaboration of interface types (0000-00-00)' - -This is an editorial change only, there are no testable consequences short of -checking for the absence of generated code for an interface declaration. - -RM References: 3.09.04 (18/2) -@end itemize - -@geindex AI-0208 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0208 Characteristics of incomplete views (0000-00-00)' - -The wording in the Ada 2005 RM concerning characteristics of incomplete views -was incorrect and implied that some programs intended to be legal were now -illegal. GNAT had never considered such programs illegal, so it has always -implemented the intent of this AI. - -RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) -@end itemize - -@geindex AI-0162 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0162 Incomplete type completed by partial view (2010-09-15)' - -Incomplete types are made more useful by allowing them to be completed by -private types and private extensions. - -RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) -@end itemize - -@geindex AI-0098 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0098 Anonymous subprogram access restrictions (0000-00-00)' - -An unintentional omission in the RM implied some inconsistent restrictions on -the use of anonymous access to subprogram values. These restrictions were not -intentional, and have never been enforced by GNAT. - -RM References: 3.10.01 (6) 3.10.01 (9.2/2) -@end itemize - -@geindex AI-0199 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0199 Aggregate with anonymous access components (2010-07-14)' - -A choice list in a record aggregate can include several components of -(distinct) anonymous access types as long as they have matching designated -subtypes. - -RM References: 4.03.01 (16) -@end itemize - -@geindex AI-0220 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0220 Needed components for aggregates (0000-00-00)' - -This AI addresses a wording problem in the RM that appears to permit some -complex cases of aggregates with nonstatic discriminants. GNAT has always -implemented the intended semantics. - -RM References: 4.03.01 (17) -@end itemize - -@geindex AI-0147 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0147 Conditional expressions (2009-03-29)' - -Conditional expressions are permitted. The form of such an expression is: - -@example -(if expr then expr @{elsif expr then expr@} [else expr]) -@end example - -The parentheses can be omitted in contexts where parentheses are present -anyway, such as subprogram arguments and pragma arguments. If the `else' -clause is omitted, `else' `True' is assumed; -thus @code{(if A then B)} is a way to conveniently represent -`(A implies B)' in standard logic. - -RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) -4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) -@end itemize - -@geindex AI-0037 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0037 Out-of-range box associations in aggregate (0000-00-00)' - -This AI confirms that an association of the form @code{Indx => <>} in an -array aggregate must raise @code{Constraint_Error} if @code{Indx} -is out of range. The RM specified a range check on other associations, but -not when the value of the association was defaulted. GNAT has always inserted -a constraint check on the index value. - -RM References: 4.03.03 (29) -@end itemize - -@geindex AI-0123 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0123 Composability of equality (2010-04-13)' - -Equality of untagged record composes, so that the predefined equality for a -composite type that includes a component of some untagged record type -@code{R} uses the equality operation of @code{R} (which may be user-defined -or predefined). This makes the behavior of untagged records identical to that -of tagged types in this respect. - -This change is an incompatibility with previous versions of Ada, but it -corrects a non-uniformity that was often a source of confusion. Analysis of -a large number of industrial programs indicates that in those rare cases -where a composite type had an untagged record component with a user-defined -equality, either there was no use of the composite equality, or else the code -expected the same composability as for tagged types, and thus had a bug that -would be fixed by this change. - -RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) -8.05.04 (8) -@end itemize - -@geindex AI-0088 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0088 The value of exponentiation (0000-00-00)' - -This AI clarifies the equivalence rule given for the dynamic semantics of -exponentiation: the value of the operation can be obtained by repeated -multiplication, but the operation can be implemented otherwise (for example -using the familiar divide-by-two-and-square algorithm, even if this is less -accurate), and does not imply repeated reads of a volatile base. - -RM References: 4.05.06 (11) -@end itemize - -@geindex AI-0188 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0188 Case expressions (2010-01-09)' - -Case expressions are permitted. This allows use of constructs such as: - -@example -X := (case Y is when 1 => 2, when 2 => 3, when others => 31) -@end example - -RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) -@end itemize - -@geindex AI-0104 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0104 Null exclusion and uninitialized allocator (2010-07-15)' - -The assignment @code{Ptr := new not null Some_Ptr;} will raise -@code{Constraint_Error} because the default value of the allocated object is -`null'. This useless construct is illegal in Ada 2012. - -RM References: 4.08 (2) -@end itemize - -@geindex AI-0157 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0157 Allocation/Deallocation from empty pool (2010-07-11)' - -Allocation and Deallocation from an empty storage pool (i.e. allocation or -deallocation of a pointer for which a static storage size clause of zero -has been given) is now illegal and is detected as such. GNAT -previously gave a warning but not an error. - -RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) -@end itemize - -@geindex AI-0179 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0179 Statement not required after label (2010-04-10)' - -It is not necessary to have a statement following a label, so a label -can appear at the end of a statement sequence without the need for putting a -null statement afterwards, but it is not allowable to have only labels and -no real statements in a statement sequence. - -RM References: 5.01 (2) -@end itemize - -@geindex AI-0139-2 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0139-2 Syntactic sugar for iterators (2010-09-29)' - -The new syntax for iterating over arrays and containers is now implemented. -Iteration over containers is for now limited to read-only iterators. Only -default iterators are supported, with the syntax: @code{for Elem of C}. - -RM References: 5.05 -@end itemize - -@geindex AI-0134 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0134 Profiles must match for full conformance (0000-00-00)' - -For full conformance, the profiles of anonymous-access-to-subprogram -parameters must match. GNAT has always enforced this rule. - -RM References: 6.03.01 (18) -@end itemize - -@geindex AI-0207 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0207 Mode conformance and access constant (0000-00-00)' - -This AI confirms that access_to_constant indication must match for mode -conformance. This was implemented in GNAT when the qualifier was originally -introduced in Ada 2005. - -RM References: 6.03.01 (16/2) -@end itemize - -@geindex AI-0046 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0046 Null exclusion match for full conformance (2010-07-17)' - -For full conformance, in the case of access parameters, the null exclusion -must match (either both or neither must have @code{not null}). - -RM References: 6.03.02 (18) -@end itemize - -@geindex AI-0118 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0118 The association of parameter associations (0000-00-00)' - -This AI clarifies the rules for named associations in subprogram calls and -generic instantiations. The rules have been in place since Ada 83. - -RM References: 6.04.01 (2) 12.03 (9) -@end itemize - -@geindex AI-0196 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0196 Null exclusion tests for out parameters (0000-00-00)' - -Null exclusion checks are not made for @code{out} parameters when -evaluating the actual parameters. GNAT has never generated these checks. - -RM References: 6.04.01 (13) -@end itemize - -@geindex AI-0015 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0015 Constant return objects (0000-00-00)' - -The return object declared in an `extended_return_statement' may be -declared constant. This was always intended, and GNAT has always allowed it. - -RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) -6.05 (5.7/2) -@end itemize - -@geindex AI-0032 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0032 Extended return for class-wide functions (0000-00-00)' - -If a function returns a class-wide type, the object of an extended return -statement can be declared with a specific type that is covered by the class- -wide type. This has been implemented in GNAT since the introduction of -extended returns. Note AI-0103 complements this AI by imposing matching -rules for constrained return types. - -RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) -6.05 (8/2) -@end itemize - -@geindex AI-0103 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0103 Static matching for extended return (2010-07-23)' - -If the return subtype of a function is an elementary type or a constrained -type, the subtype indication in an extended return statement must match -statically this return subtype. - -RM References: 6.05 (5.2/2) -@end itemize - -@geindex AI-0058 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0058 Abnormal completion of an extended return (0000-00-00)' - -The RM had some incorrect wording implying wrong treatment of abnormal -completion in an extended return. GNAT has always implemented the intended -correct semantics as described by this AI. - -RM References: 6.05 (22/2) -@end itemize - -@geindex AI-0050 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0050 Raising Constraint_Error early for function call (0000-00-00)' - -The implementation permissions for raising @code{Constraint_Error} early on a function call -when it was clear an exception would be raised were over-permissive and allowed -mishandling of discriminants in some cases. GNAT did -not take advantage of these incorrect permissions in any case. - -RM References: 6.05 (24/2) -@end itemize - -@geindex AI-0125 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0125 Nonoverridable operations of an ancestor (2010-09-28)' - -In Ada 2012, the declaration of a primitive operation of a type extension -or private extension can also override an inherited primitive that is not -visible at the point of this declaration. - -RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) -@end itemize - -@geindex AI-0062 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0062 Null exclusions and deferred constants (0000-00-00)' - -A full constant may have a null exclusion even if its associated deferred -constant does not. GNAT has always allowed this. - -RM References: 7.04 (6/2) 7.04 (7.1/2) -@end itemize - -@geindex AI-0178 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0178 Incomplete views are limited (0000-00-00)' - -This AI clarifies the role of incomplete views and plugs an omission in the -RM. GNAT always correctly restricted the use of incomplete views and types. - -RM References: 7.05 (3/2) 7.05 (6/2) -@end itemize - -@geindex AI-0087 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0087 Actual for formal nonlimited derived type (2010-07-15)' - -The actual for a formal nonlimited derived type cannot be limited. In -particular, a formal derived type that extends a limited interface but which -is not explicitly limited cannot be instantiated with a limited type. - -RM References: 7.05 (5/2) 12.05.01 (5.1/2) -@end itemize - -@geindex AI-0099 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0099 Tag determines whether finalization needed (0000-00-00)' - -This AI clarifies that ‘needs finalization’ is part of dynamic semantics, -and therefore depends on the run-time characteristics of an object (i.e. its -tag) and not on its nominal type. As the AI indicates: “we do not expect -this to affect any implementation’’. - -RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) -@end itemize - -@geindex AI-0064 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0064 Redundant finalization rule (0000-00-00)' - -This is an editorial change only. The intended behavior is already checked -by an existing ACATS test, which GNAT has always executed correctly. - -RM References: 7.06.01 (17.1/1) -@end itemize - -@geindex AI-0026 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0026 Missing rules for Unchecked_Union (2010-07-07)' - -Record representation clauses concerning Unchecked_Union types cannot mention -the discriminant of the type. The type of a component declared in the variant -part of an Unchecked_Union cannot be controlled, have controlled components, -nor have protected or task parts. If an Unchecked_Union type is declared -within the body of a generic unit or its descendants, then the type of a -component declared in the variant part cannot be a formal private type or a -formal private extension declared within the same generic unit. - -RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) -@end itemize - -@geindex AI-0205 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0205 Extended return declares visible name (0000-00-00)' - -This AI corrects a simple omission in the RM. Return objects have always -been visible within an extended return statement. - -RM References: 8.03 (17) -@end itemize - -@geindex AI-0042 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0042 Overriding versus implemented-by (0000-00-00)' - -This AI fixes a wording gap in the RM. An operation of a synchronized -interface can be implemented by a protected or task entry, but the abstract -operation is not being overridden in the usual sense, and it must be stated -separately that this implementation is legal. This has always been the case -in GNAT. - -RM References: 9.01 (9.2/2) 9.04 (11.1/2) -@end itemize - -@geindex AI-0030 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0030 Requeue on synchronized interfaces (2010-07-19)' - -Requeue is permitted to a protected, synchronized or task interface primitive -providing it is known that the overriding operation is an entry. Otherwise -the requeue statement has the same effect as a procedure call. Use of pragma -@code{Implemented} provides a way to impose a static requirement on the -overriding operation by adhering to one of the implementation kinds: entry, -protected procedure or any of the above. - -RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) -9.05.04 (6) 9.05.04 (7) 9.05.04 (12) -@end itemize - -@geindex AI-0201 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0201 Independence of atomic object components (2010-07-22)' - -If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} -attribute, then individual components may not be addressable by independent -tasks. However, if the representation clause has no effect (is confirming), -then independence is not compromised. Furthermore, in GNAT, specification of -other appropriately addressable component sizes (e.g. 16 for 8-bit -characters) also preserves independence. GNAT now gives very clear warnings -both for the declaration of such a type, and for any assignment to its components. - -RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) -@end itemize - -@geindex AI-0009 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0009 Pragma Independent[_Components] (2010-07-23)' - -This AI introduces the new pragmas @code{Independent} and -@code{Independent_Components}, -which control guaranteeing independence of access to objects and components. -The AI also requires independence not unaffected by confirming rep clauses. - -RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) -C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) -@end itemize - -@geindex AI-0072 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0072 Task signalling using ‘Terminated (0000-00-00)' - -This AI clarifies that task signalling for reading @code{'Terminated} only -occurs if the result is True. GNAT semantics has always been consistent with -this notion of task signalling. - -RM References: 9.10 (6.1/1) -@end itemize - -@geindex AI-0108 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0108 Limited incomplete view and discriminants (0000-00-00)' - -This AI confirms that an incomplete type from a limited view does not have -discriminants. This has always been the case in GNAT. - -RM References: 10.01.01 (12.3/2) -@end itemize - -@geindex AI-0129 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0129 Limited views and incomplete types (0000-00-00)' - -This AI clarifies the description of limited views: a limited view of a -package includes only one view of a type that has an incomplete declaration -and a full declaration (there is no possible ambiguity in a client package). -This AI also fixes an omission: a nested package in the private part has no -limited view. GNAT always implemented this correctly. - -RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) -@end itemize - -@geindex AI-0077 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0077 Limited withs and scope of declarations (0000-00-00)' - -This AI clarifies that a declaration does not include a context clause, -and confirms that it is illegal to have a context in which both a limited -and a nonlimited view of a package are accessible. Such double visibility -was always rejected by GNAT. - -RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) -@end itemize - -@geindex AI-0122 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0122 Private with and children of generics (0000-00-00)' - -This AI clarifies the visibility of private children of generic units within -instantiations of a parent. GNAT has always handled this correctly. - -RM References: 10.01.02 (12/2) -@end itemize - -@geindex AI-0040 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0040 Limited with clauses on descendant (0000-00-00)' - -This AI confirms that a limited with clause in a child unit cannot name -an ancestor of the unit. This has always been checked in GNAT. - -RM References: 10.01.02 (20/2) -@end itemize - -@geindex AI-0132 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0132 Placement of library unit pragmas (0000-00-00)' - -This AI fills a gap in the description of library unit pragmas. The pragma -clearly must apply to a library unit, even if it does not carry the name -of the enclosing unit. GNAT has always enforced the required check. - -RM References: 10.01.05 (7) -@end itemize - -@geindex AI-0034 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0034 Categorization of limited views (0000-00-00)' - -The RM makes certain limited with clauses illegal because of categorization -considerations, when the corresponding normal with would be legal. This is -not intended, and GNAT has always implemented the recommended behavior. - -RM References: 10.02.01 (11/1) 10.02.01 (17/2) -@end itemize - -@geindex AI-0035 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0035 Inconsistencies with Pure units (0000-00-00)' - -This AI remedies some inconsistencies in the legality rules for Pure units. -Derived access types are legal in a pure unit (on the assumption that the -rule for a zero storage pool size has been enforced on the ancestor type). -The rules are enforced in generic instances and in subunits. GNAT has always -implemented the recommended behavior. - -RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) -@end itemize - -@geindex AI-0219 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0219 Pure permissions and limited parameters (2010-05-25)' - -This AI refines the rules for the cases with limited parameters which do not -allow the implementations to omit ‘redundant’. GNAT now properly conforms -to the requirements of this binding interpretation. - -RM References: 10.02.01 (18/2) -@end itemize - -@geindex AI-0043 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0043 Rules about raising exceptions (0000-00-00)' - -This AI covers various omissions in the RM regarding the raising of -exceptions. GNAT has always implemented the intended semantics. - -RM References: 11.04.01 (10.1/2) 11 (2) -@end itemize - -@geindex AI-0200 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0200 Mismatches in formal package declarations (0000-00-00)' - -This AI plugs a gap in the RM which appeared to allow some obviously intended -illegal instantiations. GNAT has never allowed these instantiations. - -RM References: 12.07 (16) -@end itemize - -@geindex AI-0112 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0112 Detection of duplicate pragmas (2010-07-24)' - -This AI concerns giving names to various representation aspects, but the -practical effect is simply to make the use of duplicate -@code{Atomic[_Components]}, -@code{Volatile[_Components]}, and -@code{Independent[_Components]} pragmas illegal, and GNAT -now performs this required check. - -RM References: 13.01 (8) -@end itemize - -@geindex AI-0106 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0106 No representation pragmas on generic formals (0000-00-00)' - -The RM appeared to allow representation pragmas on generic formal parameters, -but this was not intended, and GNAT has never permitted this usage. - -RM References: 13.01 (9.1/1) -@end itemize - -@geindex AI-0012 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)' - -It is now illegal to give an inappropriate component size or a pragma -@code{Pack} that attempts to change the component size in the case of atomic -or aliased components. Previously GNAT ignored such an attempt with a -warning. - -RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) -@end itemize - -@geindex AI-0039 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0039 Stream attributes cannot be dynamic (0000-00-00)' - -The RM permitted the use of dynamic expressions (such as @code{ptr.all})` -for stream attributes, but these were never useful and are now illegal. GNAT -has always regarded such expressions as illegal. - -RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) -@end itemize - -@geindex AI-0095 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0095 Address of intrinsic subprograms (0000-00-00)' - -The prefix of @code{'Address} cannot statically denote a subprogram with -convention @code{Intrinsic}. The use of the @code{Address} attribute raises -@code{Program_Error} if the prefix denotes a subprogram with convention -@code{Intrinsic}. - -RM References: 13.03 (11/1) -@end itemize - -@geindex AI-0116 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0116 Alignment of class-wide objects (0000-00-00)' - -This AI requires that the alignment of a class-wide object be no greater -than the alignment of any type in the class. GNAT has always followed this -recommendation. - -RM References: 13.03 (29) 13.11 (16) -@end itemize - -@geindex AI-0146 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0146 Type invariants (2009-09-21)' - -Type invariants may be specified for private types using the aspect notation. -Aspect @code{Type_Invariant} may be specified for any private type, -@code{Type_Invariant'Class} can -only be specified for tagged types, and is inherited by any descendent of the -tagged types. The invariant is a boolean expression that is tested for being -true in the following situations: conversions to the private type, object -declarations for the private type that are default initialized, and -[`in'] `out' -parameters and returned result on return from any primitive operation for -the type that is visible to a client. -GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and -@code{Invariant'Class} for @code{Type_Invariant'Class}. - -RM References: 13.03.03 (00) -@end itemize - -@geindex AI-0078 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)' - -In Ada 2012, compilers are required to support unchecked conversion where the -target alignment is a multiple of the source alignment. GNAT always supported -this case (and indeed all cases of differing alignments, doing copies where -required if the alignment was reduced). - -RM References: 13.09 (7) -@end itemize - -@geindex AI-0195 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0195 Invalid value handling is implementation defined (2010-07-03)' - -The handling of invalid values is now designated to be implementation -defined. This is a documentation change only, requiring Annex M in the GNAT -Reference Manual to document this handling. -In GNAT, checks for invalid values are made -only when necessary to avoid erroneous behavior. Operations like assignments -which cannot cause erroneous behavior ignore the possibility of invalid -values and do not do a check. The date given above applies only to the -documentation change, this behavior has always been implemented by GNAT. - -RM References: 13.09.01 (10) -@end itemize - -@geindex AI-0193 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0193 Alignment of allocators (2010-09-16)' - -This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, -analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead -of size. - -RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) -13.11.01 (2) 13.11.01 (3) -@end itemize - -@geindex AI-0177 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0177 Parameterized expressions (2010-07-10)' - -The new Ada 2012 notion of parameterized expressions is implemented. The form -is: - -@example -function-specification is (expression) -@end example - -This is exactly equivalent to the -corresponding function body that returns the expression, but it can appear -in a package spec. Note that the expression must be parenthesized. - -RM References: 13.11.01 (3/2) -@end itemize - -@geindex AI-0033 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)' - -Neither of these two pragmas may appear within a generic template, because -the generic might be instantiated at other than the library level. - -RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) -@end itemize - -@geindex AI-0161 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)' - -A new restriction @code{No_Default_Stream_Attributes} prevents the use of any -of the default stream attributes for elementary types. If this restriction is -in force, then it is necessary to provide explicit subprograms for any -stream attributes used. - -RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) -@end itemize - -@geindex AI-0194 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0194 Value of Stream_Size attribute (0000-00-00)' - -The @code{Stream_Size} attribute returns the default number of bits in the -stream representation of the given type. -This value is not affected by the presence -of stream subprogram attributes for the type. GNAT has always implemented -this interpretation. - -RM References: 13.13.02 (1.2/2) -@end itemize - -@geindex AI-0109 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0109 Redundant check in S’Class’Input (0000-00-00)' - -This AI is an editorial change only. It removes the need for a tag check -that can never fail. - -RM References: 13.13.02 (34/2) -@end itemize - -@geindex AI-0007 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0007 Stream read and private scalar types (0000-00-00)' - -The RM as written appeared to limit the possibilities of declaring read -attribute procedures for private scalar types. This limitation was not -intended, and has never been enforced by GNAT. - -RM References: 13.13.02 (50/2) 13.13.02 (51/2) -@end itemize - -@geindex AI-0065 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0065 Remote access types and external streaming (0000-00-00)' - -This AI clarifies the fact that all remote access types support external -streaming. This fixes an obvious oversight in the definition of the -language, and GNAT always implemented the intended correct rules. - -RM References: 13.13.02 (52/2) -@end itemize - -@geindex AI-0019 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0019 Freezing of primitives for tagged types (0000-00-00)' - -The RM suggests that primitive subprograms of a specific tagged type are -frozen when the tagged type is frozen. This would be an incompatible change -and is not intended. GNAT has never attempted this kind of freezing and its -behavior is consistent with the recommendation of this AI. - -RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) -@end itemize - -@geindex AI-0017 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0017 Freezing and incomplete types (0000-00-00)' - -So-called ‘Taft-amendment types’ (i.e., types that are completed in package -bodies) are not frozen by the occurrence of bodies in the -enclosing declarative part. GNAT always implemented this properly. - -RM References: 13.14 (3/1) -@end itemize - -@geindex AI-0060 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0060 Extended definition of remote access types (0000-00-00)' - -This AI extends the definition of remote access types to include access -to limited, synchronized, protected or task class-wide interface types. -GNAT already implemented this extension. - -RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) -@end itemize - -@geindex AI-0114 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0114 Classification of letters (0000-00-00)' - -The code points 170 (@code{FEMININE ORDINAL INDICATOR}), -181 (@code{MICRO SIGN}), and -186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered -lower case letters by Unicode. -However, they are not allowed in identifiers, and they -return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. -This behavior is consistent with that defined in Ada 95. - -RM References: A.03.02 (59) A.04.06 (7) -@end itemize - -@geindex AI-0185 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)' - -Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide -classification functions for @code{Wide_Character} and -@code{Wide_Wide_Character}, as well as providing -case folding routines for @code{Wide_[Wide_]Character} and -@code{Wide_[Wide_]String}. - -RM References: A.03.05 (0) A.03.06 (0) -@end itemize - -@geindex AI-0031 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0031 Add From parameter to Find_Token (2010-07-25)' - -A new version of @code{Find_Token} is added to all relevant string packages, -with an extra parameter @code{From}. Instead of starting at the first -character of the string, the search for a matching Token starts at the -character indexed by the value of @code{From}. -These procedures are available in all versions of Ada -but if used in versions earlier than Ada 2012 they will generate a warning -that an Ada 2012 subprogram is being used. - -RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) -A.04.05 (46) -@end itemize - -@geindex AI-0056 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0056 Index on null string returns zero (0000-00-00)' - -The wording in the Ada 2005 RM implied an incompatible handling of the -@code{Index} functions, resulting in raising an exception instead of -returning zero in some situations. -This was not intended and has been corrected. -GNAT always returned zero, and is thus consistent with this AI. - -RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) -@end itemize - -@geindex AI-0137 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0137 String encoding package (2010-03-25)' - -The packages @code{Ada.Strings.UTF_Encoding}, together with its child -packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, -and @code{Wide_Wide_Strings} have been -implemented. These packages (whose documentation can be found in the spec -files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, -@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of -@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} -values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and -UTF-16), as well as conversions between the different UTF encodings. With -the exception of @code{Wide_Wide_Strings}, these packages are available in -Ada 95 and Ada 2005 mode as well as Ada 2012 mode. -The @code{Wide_Wide_Strings} package -is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 -mode since it uses @code{Wide_Wide_Character}). - -RM References: A.04.11 -@end itemize - -@geindex AI-0038 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0038 Minor errors in Text_IO (0000-00-00)' - -These are minor errors in the description on three points. The intent on -all these points has always been clear, and GNAT has always implemented the -correct intended semantics. - -RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24) -@end itemize - -@geindex AI-0044 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0044 Restrictions on container instantiations (0000-00-00)' - -This AI places restrictions on allowed instantiations of generic containers. -These restrictions are not checked by the compiler, so there is nothing to -change in the implementation. This affects only the RM documentation. - -RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2) -@end itemize - -@geindex AI-0127 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0127 Adding Locale Capabilities (2010-09-29)' - -This package provides an interface for identifying the current locale. - -RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 -A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 -@end itemize - -@geindex AI-0002 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0002 Export C with unconstrained arrays (0000-00-00)' - -The compiler is not required to support exporting an Ada subprogram with -convention C if there are parameters or a return type of an unconstrained -array type (such as @code{String}). GNAT allows such declarations but -generates warnings. It is possible, but complicated, to write the -corresponding C code and certainly such code would be specific to GNAT and -non-portable. - -RM References: B.01 (17) B.03 (62) B.03 (71.1/2) -@end itemize - -@geindex AI05-0216 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)' - -It is clearly the intention that @code{No_Task_Hierarchy} is intended to -forbid tasks declared locally within subprograms, or functions returning task -objects, and that is the implementation that GNAT has always provided. -However the language in the RM was not sufficiently clear on this point. -Thus this is a documentation change in the RM only. - -RM References: D.07 (3/3) -@end itemize - -@geindex AI-0211 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)' - -The restriction @code{No_Relative_Delays} forbids any calls to the subprogram -@code{Ada.Real_Time.Timing_Events.Set_Handler}. - -RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) -@end itemize - -@geindex AI-0190 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0190 pragma Default_Storage_Pool (2010-09-15)' - -This AI introduces a new pragma @code{Default_Storage_Pool}, which can be -used to control storage pools globally. -In particular, you can force every access -type that is used for allocation (`new') to have an explicit storage pool, -or you can declare a pool globally to be used for all access types that lack -an explicit one. - -RM References: D.07 (8) -@end itemize - -@geindex AI-0189 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0189 No_Allocators_After_Elaboration (2010-01-23)' - -This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, -which says that no dynamic allocation will occur once elaboration is -completed. -In general this requires a run-time check, which is not required, and which -GNAT does not attempt. But the static cases of allocators in a task body or -in the body of the main program are detected and flagged at compile or bind -time. - -RM References: D.07 (19.1/2) H.04 (23.3/2) -@end itemize - -@geindex AI-0171 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)' - -A new package @code{System.Multiprocessors} is added, together with the -definition of pragma @code{CPU} for controlling task affinity. A new no -dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, -is added to the Ravenscar profile. - -RM References: D.13.01 (4/2) D.16 -@end itemize - -@geindex AI-0210 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0210 Correct Timing_Events metric (0000-00-00)' - -This is a documentation only issue regarding wording of metric requirements, -that does not affect the implementation of the compiler. - -RM References: D.15 (24/2) -@end itemize - -@geindex AI-0206 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0206 Remote types packages and preelaborate (2010-07-24)' - -Remote types packages are now allowed to depend on preelaborated packages. -This was formerly considered illegal. - -RM References: E.02.02 (6) -@end itemize - -@geindex AI-0152 (Ada 2012 feature) - - -@itemize * - -@item -`AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)' - -Restriction @code{No_Anonymous_Allocators} prevents the use of allocators -where the type of the returned value is an anonymous access type. - -RM References: H.04 (8/1) -@end itemize - -@node Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top -@anchor{gnat_rm/security_hardening_features doc}@anchor{42b}@anchor{gnat_rm/security_hardening_features id1}@anchor{42c}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15} -@chapter Security Hardening Features - - -This chapter describes Ada extensions aimed at security hardening that -are provided by GNAT. - -The features in this chapter are currently experimental and subject to -change. - -@c Register Scrubbing: - -@menu -* Register Scrubbing:: -* Stack Scrubbing:: -* Hardened Conditionals:: -* Hardened Booleans:: -* Control Flow Redundancy:: - -@end menu - -@node Register Scrubbing,Stack Scrubbing,,Security Hardening Features -@anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{42d} -@section Register Scrubbing - - -GNAT can generate code to zero-out hardware registers before returning -from a subprogram. - -It can be enabled with the @code{-fzero-call-used-regs=`choice'} -command-line option, to affect all subprograms in a compilation, and -with a @code{Machine_Attribute} pragma, to affect only specific -subprograms. - -@example -procedure Foo; -pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); --- Before returning, Foo scrubs only call-clobbered registers --- that it uses itself. - -function Bar return Integer; -pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); --- Before returning, Bar scrubs all call-clobbered registers. -@end example - -For usage and more details on the command-line option, on the -@code{zero_call_used_regs} attribute, and on their use with other -programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. - -@c Stack Scrubbing: - -@node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features -@anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{42e} -@section Stack Scrubbing - - -GNAT can generate code to zero-out stack frames used by subprograms. - -It can be activated with the @code{Machine_Attribute} pragma, on -specific subprograms and variables, or their types. (This attribute -always applies to a type, even when it is associated with a subprogram -or a variable.) - -@example -function Foo returns Integer; -pragma Machine_Attribute (Foo, "strub"); --- Foo and its callers are modified so as to scrub the stack --- space used by Foo after it returns. Shorthand for: --- pragma Machine_Attribute (Foo, "strub", "at-calls"); - -procedure Bar; -pragma Machine_Attribute (Bar, "strub", "internal"); --- Bar is turned into a wrapper for its original body, --- and they scrub the stack used by the original body. - -Var : Integer; -pragma Machine_Attribute (Var, "strub"); --- Reading from Var in a subprogram enables stack scrubbing --- of the stack space used by the subprogram. Furthermore, if --- Var is declared within a subprogram, this also enables --- scrubbing of the stack space used by that subprogram. -@end example - -Given these declarations, Foo has its type and body modified as -follows: - -@example -function Foo ( : in out System.Address) returns Integer -is - -- ... -begin - <__strub_update> (); -- Updates the stack WaterMark. - -- ... -end; -@end example - -whereas its callers are modified from: - -@example -X := Foo; -@end example - -to: - -@example -declare - : System.Address; -begin - <__strub_enter> (); -- Initialize . - X := Foo (); - <__strub_leave> (); -- Scrubs stack up to . -end; -@end example - -As for Bar, because it is strubbed in internal mode, its callers are -not modified. Its definition is modified roughly as follows: - -@example -procedure Bar is - : System.Address; - procedure Strubbed_Bar ( : in out System.Address) is - begin - <__strub_update> (); -- Updates the stack WaterMark. - -- original Bar body. - end Strubbed_Bar; -begin - <__strub_enter> (); -- Initialize . - Strubbed_Bar (); - <__strub_leave> (); -- Scrubs stack up to . -end Bar; -@end example - -There are also @code{-fstrub=`choice'} command-line options to -control default settings. For usage and more details on the -command-line options, on the @code{strub} attribute, and their use with -other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. - -Note that Ada secondary stacks are not scrubbed. The restriction -@code{No_Secondary_Stack} avoids their use, and thus their accidental -preservation of data that should be scrubbed. - -Attributes @code{Access} and @code{Unconstrained_Access} of variables and -constants with @code{strub} enabled require types with @code{strub} enabled; -there is no way to express an access-to-strub type otherwise. -@code{Unchecked_Access} bypasses this constraint, but the resulting -access type designates a non-strub type. - -@example -VI : aliased Integer; -pragma Machine_Attribute (VI, "strub"); -XsVI : access Integer := VI'Access; -- Error. -UXsVI : access Integer := VI'Unchecked_Access; -- OK, --- UXsVI does *not* enable strub in subprograms that --- dereference it to obtain the UXsVI.all value. - -type Strub_Int is new Integer; -pragma Machine_Attribute (Strub_Int, "strub"); -VSI : aliased Strub_Int; -XsVSI : access Strub_Int := VSI'Access; -- OK, --- VSI and XsVSI.all both enable strub in subprograms that --- read their values. -@end example - -Every access-to-subprogram type, renaming, and overriding and -overridden dispatching operations that may refer to a subprogram with -an attribute-modified interface must be annotated with the same -interface-modifying attribute. Access-to-subprogram types can be -explicitly converted to different strub modes, as long as they are -interface-compatible (i.e., adding or removing @code{at-calls} is not -allowed). For example, a @code{strub}-@code{disabled} subprogram can be -turned @code{callable} through such an explicit conversion: - -@example -type TBar is access procedure; - -type TBar_Callable is access procedure; -pragma Machine_Attribute (TBar_Callable, "strub", "callable"); --- The attribute modifies the procedure type, rather than the --- access type, because of the extra argument after "strub", --- only applicable to subprogram types. - -Bar_Callable_Ptr : constant TBar_Callable - := TBar_Callable (TBar'(Bar'Access)); - -procedure Bar_Callable renames Bar_Callable_Ptr.all; -pragma Machine_Attribute (Bar_Callable, "strub", "callable"); -@end example - -Note that the renaming declaration is expanded to a full subprogram -body, it won’t be just an alias. Only if it is inlined will it be as -efficient as a call by dereferencing the access-to-subprogram constant -Bar_Callable_Ptr. - -@c Hardened Conditionals: - -@node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features -@anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{42f} -@section Hardened Conditionals - - -GNAT can harden conditionals to protect against control-flow attacks. - -This is accomplished by two complementary transformations, each -activated by a separate command-line option. - -The option @code{-fharden-compares} enables hardening of compares -that compute results stored in variables, adding verification that the -reversed compare yields the opposite result, turning: - -@example -B := X = Y; -@end example - -into: - -@example -B := X = Y; -declare - NotB : Boolean := X /= Y; -- Computed independently of B. -begin - if B = NotB then - <__builtin_trap>; - end if; -end; -@end example - -The option @code{-fharden-conditional-branches} enables hardening -of compares that guard conditional branches, adding verification of -the reversed compare to both execution paths, turning: - -@example -if X = Y then - X := Z + 1; -else - Y := Z - 1; -end if; -@end example - -into: - -@example -if X = Y then - if X /= Y then -- Computed independently of X = Y. - <__builtin_trap>; - end if; - X := Z + 1; -else - if X /= Y then -- Computed independently of X = Y. - null; - else - <__builtin_trap>; - end if; - Y := Z - 1; -end if; -@end example - -These transformations are introduced late in the compilation pipeline, -long after boolean expressions are decomposed into separate compares, -each one turned into either a conditional branch or a compare whose -result is stored in a boolean variable or temporary. Compiler -optimizations, if enabled, may also turn conditional branches into -stored compares, and vice-versa, or into operations with implied -conditionals (e.g. MIN and MAX). Conditionals may also be optimized -out entirely, if their value can be determined at compile time, and -occasionally multiple compares can be combined into one. - -It is thus difficult to predict which of these two options will affect -a specific compare operation expressed in source code. Using both -options ensures that every compare that is neither optimized out nor -optimized into implied conditionals will be hardened. - -The addition of reversed compares can be observed by enabling the dump -files of the corresponding passes, through command-line options -@code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr}, -respectively. - -They are separate options, however, because of the significantly -different performance impact of the hardening transformations. - -For usage and more details on the command-line options, see -@cite{Using the GNU Compiler Collection (GCC)}. These options can -be used with other programming languages supported by GCC. - -@c Hardened Booleans: - -@node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features -@anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{430} -@section Hardened Booleans - - -Ada has built-in support for introducing boolean types with -alternative representations, using representation clauses: - -@example -type HBool is new Boolean; -for HBool use (16#5a#, 16#a5#); -for HBool'Size use 8; -@end example - -When validity checking is enabled, the compiler will check that -variables of such types hold values corresponding to the selected -representations. - -There are multiple strategies for where to introduce validity checking -(see @code{-gnatV} options). Their goal is to guard against -various kinds of programming errors, and GNAT strives to omit checks -when program logic rules out an invalid value, and optimizers may -further remove checks found to be redundant. - -For additional hardening, the @code{hardbool} @code{Machine_Attribute} -pragma can be used to annotate boolean types with representation -clauses, so that expressions of such types used as conditions are -checked even when compiling with @code{-gnatVT}: - -@example -pragma Machine_Attribute (HBool, "hardbool"); - -function To_Boolean (X : HBool) returns Boolean is (Boolean (X)); -@end example - -is compiled roughly like: - -@example -function To_Boolean (X : HBool) returns Boolean is -begin - if X not in True | False then - raise Constraint_Error; - elsif X in True then - return True; - else - return False; - end if; -end To_Boolean; -@end example - -Note that @code{-gnatVn} will disable even @code{hardbool} testing. - -Analogous behavior is available as a GCC extension to the C and -Objective C programming languages, through the @code{hardbool} attribute, -with the difference that, instead of raising a Constraint_Error -exception, when a hardened boolean variable is found to hold a value -that stands for neither True nor False, the program traps. For usage -and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}. - -@c Control Flow Redundancy: - -@node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features -@anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{431} -@section Control Flow Redundancy - - -GNAT can guard against unexpected execution flows, such as branching -into the middle of subprograms, as in Return Oriented Programming -exploits. - -In units compiled with @code{-fharden-control-flow-redundancy}, -subprograms are instrumented so that, every time they are called, -basic blocks take note as control flows through them, and, before -returning, subprograms verify that the taken notes are consistent with -the control-flow graph. - -Functions with too many basic blocks, or with multiple return points, -call a run-time function to perform the verification. Other functions -perform the verification inline before returning. - -Optimizing the inlined verification can be quite time consuming, so -the default upper limit for the inline mode is set at 16 blocks. -Command-line option @code{--param hardcfr-max-inline-blocks=} can -override it. - -Even though typically sparse control-flow graphs exhibit run-time -verification time nearly proportional to the block count of a -subprogram, it may become very significant for generated subprograms -with thousands of blocks. Command-line option -@code{--param hardcfr-max-blocks=} can set an upper limit for -instrumentation. - -For each block that is marked as visited, the mechanism checks that at -least one of its predecessors, and at least one of its successors, are -also marked as visited. - -Verification is performed just before returning. Subprogram -executions that complete by raising or propagating an exception bypass -verification-and-return points. A subprogram that can only complete -by raising or propagating an exception may have instrumentation -disabled altogether. - -The instrumentation for hardening with control flow redundancy can be -observed in dump files generated by the command-line option -@code{-fdump-tree-hardcfr}. - -For more details on the control flow redundancy command-line options, -see @cite{Using the GNU Compiler Collection (GCC)}. These options -can be used with other programming languages supported by GCC. - -@node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top -@anchor{gnat_rm/obsolescent_features doc}@anchor{432}@anchor{gnat_rm/obsolescent_features id1}@anchor{433}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} -@chapter Obsolescent Features - - -This chapter describes features that are provided by GNAT, but are -considered obsolescent since there are preferred ways of achieving -the same effect. These features are provided solely for historical -compatibility purposes. - -@menu -* pragma No_Run_Time:: -* pragma Ravenscar:: -* pragma Restricted_Run_Time:: -* pragma Task_Info:: -* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. - -@end menu - -@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features -@anchor{gnat_rm/obsolescent_features id2}@anchor{434}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{435} -@section pragma No_Run_Time - - -The pragma @code{No_Run_Time} is used to achieve an affect similar -to the use of the “Zero Foot Print” configurable run time, but without -requiring a specially configured run time. The result of using this -pragma, which must be used for all units in a partition, is to restrict -the use of any language features requiring run-time support code. The -preferred usage is to use an appropriately configured run-time that -includes just those features that are to be made accessible. - -@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features -@anchor{gnat_rm/obsolescent_features id3}@anchor{436}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{437} -@section pragma Ravenscar - - -The pragma @code{Ravenscar} has exactly the same effect as pragma -@code{Profile (Ravenscar)}. The latter usage is preferred since it -is part of the new Ada 2005 standard. - -@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features -@anchor{gnat_rm/obsolescent_features id4}@anchor{438}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{439} -@section pragma Restricted_Run_Time - - -The pragma @code{Restricted_Run_Time} has exactly the same effect as -pragma @code{Profile (Restricted)}. The latter usage is -preferred since the Ada 2005 pragma @code{Profile} is intended for -this kind of implementation dependent addition. - -@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features -@anchor{gnat_rm/obsolescent_features id5}@anchor{43a}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{43b} -@section pragma Task_Info - - -The functionality provided by pragma @code{Task_Info} is now part of the -Ada language. The @code{CPU} aspect and the package -@code{System.Multiprocessors} offer a less system-dependent way to specify -task affinity or to query the number of processors. - -Syntax - -@example -pragma Task_Info (EXPRESSION); -@end example - -This pragma appears within a task definition (like pragma -@code{Priority}) and applies to the task in which it appears. The -argument must be of type @code{System.Task_Info.Task_Info_Type}. -The @code{Task_Info} pragma provides system dependent control over -aspects of tasking implementation, for example, the ability to map -tasks to specific processors. For details on the facilities available -for the version of GNAT that you are using, see the documentation -in the spec of package System.Task_Info in the runtime -library. - -@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features -@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{43c}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{43d} -@section package System.Task_Info (@code{s-tasinf.ads}) - - -This package provides target dependent functionality that is used -to support the @code{Task_Info} pragma. The predefined Ada package -@code{System.Multiprocessors} and the @code{CPU} aspect now provide a -standard replacement for GNAT’s @code{Task_Info} functionality. - -@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top -@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{43e}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{43f} -@chapter Compatibility and Porting Guide - - -This chapter presents some guidelines for developing portable Ada code, -describes the compatibility issues that may arise between -GNAT and other Ada compilation systems (including those for Ada 83), -and shows how GNAT can expedite porting -applications developed in other Ada environments. - -@menu -* Writing Portable Fixed-Point Declarations:: -* Compatibility with Ada 83:: -* Compatibility between Ada 95 and Ada 2005:: -* Implementation-dependent characteristics:: -* Compatibility with Other Ada Systems:: -* Representation Clauses:: -* Compatibility with HP Ada 83:: - -@end menu - -@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{440}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{441} -@section Writing Portable Fixed-Point Declarations - - -The Ada Reference Manual gives an implementation freedom to choose bounds -that are narrower by @code{Small} from the given bounds. -For example, if we write - -@example -type F1 is delta 1.0 range -128.0 .. +128.0; -@end example - -then the implementation is allowed to choose -128.0 .. +127.0 if it -likes, but is not required to do so. - -This leads to possible portability problems, so let’s have a closer -look at this, and figure out how to avoid these problems. - -First, why does this freedom exist, and why would an implementation -take advantage of it? To answer this, take a closer look at the type -declaration for @code{F1} above. If the compiler uses the given bounds, -it would need 9 bits to hold the largest positive value (and typically -that means 16 bits on all machines). But if the implementation chooses -the +127.0 bound then it can fit values of the type in 8 bits. - -Why not make the user write +127.0 if that’s what is wanted? -The rationale is that if you are thinking of fixed point -as a kind of ‘poor man’s floating-point’, then you don’t want -to be thinking about the scaled integers that are used in its -representation. Let’s take another example: - -@example -type F2 is delta 2.0**(-15) range -1.0 .. +1.0; -@end example - -Looking at this declaration, it seems casually as though -it should fit in 16 bits, but again that extra positive value -+1.0 has the scaled integer equivalent of 2**15 which is one too -big for signed 16 bits. The implementation can treat this as: - -@example -type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); -@end example - -and the Ada language design team felt that this was too annoying -to require. We don’t need to debate this decision at this point, -since it is well established (the rule about narrowing the ranges -dates to Ada 83). - -But the important point is that an implementation is not required -to do this narrowing, so we have a potential portability problem. -We could imagine three types of implementation: - - -@enumerate a - -@item -those that narrow the range automatically if they can figure -out that the narrower range will allow storage in a smaller machine unit, - -@item -those that will narrow only if forced to by a @code{'Size} clause, and - -@item -those that will never narrow. -@end enumerate - -Now if we are language theoreticians, we can imagine a fourth -approach: to narrow all the time, e.g. to treat - -@example -type F3 is delta 1.0 range -10.0 .. +23.0; -@end example - -as though it had been written: - -@example -type F3 is delta 1.0 range -9.0 .. +22.0; -@end example - -But although technically allowed, such a behavior would be hostile and silly, -and no real compiler would do this. All real compilers will fall into one of -the categories (a), (b) or (c) above. - -So, how do you get the compiler to do what you want? The answer is give the -actual bounds you want, and then use a @code{'Small} clause and a -@code{'Size} clause to absolutely pin down what the compiler does. -E.g., for @code{F2} above, we will write: - -@example -My_Small : constant := 2.0**(-15); -My_First : constant := -1.0; -My_Last : constant := +1.0 - My_Small; - -type F2 is delta My_Small range My_First .. My_Last; -@end example - -and then add - -@example -for F2'Small use my_Small; -for F2'Size use 16; -@end example - -In practice all compilers will do the same thing here and will give you -what you want, so the above declarations are fully portable. If you really -want to play language lawyer and guard against ludicrous behavior by the -compiler you could add - -@example -Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); -Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); -@end example - -One or other or both are allowed to be illegal if the compiler is -behaving in a silly manner, but at least the silly compiler will not -get away with silently messing with your (very clear) intentions. - -If you follow this scheme you will be guaranteed that your fixed-point -types will be portable. - -@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{442}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{443} -@section Compatibility with Ada 83 - - -@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) - -Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 -are highly upwards compatible with Ada 83. In -particular, the design intention was that the difficulties associated -with moving from Ada 83 to later versions of the standard should be no greater -than those that occur when moving from one Ada 83 system to another. - -However, there are a number of points at which there are minor -incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains -full details of these issues as they relate to Ada 95, -and should be consulted for a complete treatment. -In practice the -following subsections treat the most likely issues to be encountered. - -@menu -* Legal Ada 83 programs that are illegal in Ada 95:: -* More deterministic semantics:: -* Changed semantics:: -* Other language compatibility issues:: - -@end menu - -@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 -@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{445} -@subsection Legal Ada 83 programs that are illegal in Ada 95 - - -Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in -Ada 95 and later versions of the standard: - - -@itemize * - -@item -`Character literals' - -Some uses of character literals are ambiguous. Since Ada 95 has introduced -@code{Wide_Character} as a new predefined character type, some uses of -character literals that were legal in Ada 83 are illegal in Ada 95. -For example: - -@example -for Char in 'A' .. 'Z' loop ... end loop; -@end example - -The problem is that ‘A’ and ‘Z’ could be from either -@code{Character} or @code{Wide_Character}. The simplest correction -is to make the type explicit; e.g.: - -@example -for Char in Character range 'A' .. 'Z' loop ... end loop; -@end example - -@item -`New reserved words' - -The identifiers @code{abstract}, @code{aliased}, @code{protected}, -@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. -Existing Ada 83 code using any of these identifiers must be edited to -use some alternative name. - -@item -`Freezing rules' - -The rules in Ada 95 are slightly different with regard to the point at -which entities are frozen, and representation pragmas and clauses are -not permitted past the freeze point. This shows up most typically in -the form of an error message complaining that a representation item -appears too late, and the appropriate corrective action is to move -the item nearer to the declaration of the entity to which it refers. - -A particular case is that representation pragmas -cannot be applied to a subprogram body. If necessary, a separate subprogram -declaration must be introduced to which the pragma can be applied. - -@item -`Optional bodies for library packages' - -In Ada 83, a package that did not require a package body was nevertheless -allowed to have one. This lead to certain surprises in compiling large -systems (situations in which the body could be unexpectedly ignored by the -binder). In Ada 95, if a package does not require a body then it is not -permitted to have a body. To fix this problem, simply remove a redundant -body if it is empty, or, if it is non-empty, introduce a dummy declaration -into the spec that makes the body required. One approach is to add a private -part to the package declaration (if necessary), and define a parameterless -procedure called @code{Requires_Body}, which must then be given a dummy -procedure body in the package body, which then becomes required. -Another approach (assuming that this does not introduce elaboration -circularities) is to add an @code{Elaborate_Body} pragma to the package spec, -since one effect of this pragma is to require the presence of a package body. - -@item -`Numeric_Error is the same exception as Constraint_Error' - -In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. -This means that it is illegal to have separate exception handlers for -the two exceptions. The fix is simply to remove the handler for the -@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise -@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). - -@item -`Indefinite subtypes in generics' - -In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) -as the actual for a generic formal private type, but then the instantiation -would be illegal if there were any instances of declarations of variables -of this type in the generic body. In Ada 95, to avoid this clear violation -of the methodological principle known as the ‘contract model’, -the generic declaration explicitly indicates whether -or not such instantiations are permitted. If a generic formal parameter -has explicit unknown discriminants, indicated by using @code{(<>)} after the -subtype name, then it can be instantiated with indefinite types, but no -stand-alone variables can be declared of this type. Any attempt to declare -such a variable will result in an illegality at the time the generic is -declared. If the @code{(<>)} notation is not used, then it is illegal -to instantiate the generic with an indefinite type. -This is the potential incompatibility issue when porting Ada 83 code to Ada 95. -It will show up as a compile time error, and -the fix is usually simply to add the @code{(<>)} to the generic declaration. -@end itemize - -@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 -@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{447} -@subsection More deterministic semantics - - - -@itemize * - -@item -`Conversions' - -Conversions from real types to integer types round away from 0. In Ada 83 -the conversion Integer(2.5) could deliver either 2 or 3 as its value. This -implementation freedom was intended to support unbiased rounding in -statistical applications, but in practice it interfered with portability. -In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 -is required. Numeric code may be affected by this change in semantics. -Note, though, that this issue is no worse than already existed in Ada 83 -when porting code from one vendor to another. - -@item -`Tasking' - -The Real-Time Annex introduces a set of policies that define the behavior of -features that were implementation dependent in Ada 83, such as the order in -which open select branches are executed. -@end itemize - -@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 -@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{449} -@subsection Changed semantics - - -The worst kind of incompatibility is one where a program that is legal in -Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not -possible in Ada 83. Fortunately this is extremely rare, but the one -situation that you should be alert to is the change in the predefined type -@code{Character} from 7-bit ASCII to 8-bit Latin-1. - -@quotation - -@geindex Latin-1 -@end quotation - - -@itemize * - -@item -`Range of type `@w{`}Character`@w{`}' - -The range of @code{Standard.Character} is now the full 256 characters -of Latin-1, whereas in most Ada 83 implementations it was restricted -to 128 characters. Although some of the effects of -this change will be manifest in compile-time rejection of legal -Ada 83 programs it is possible for a working Ada 83 program to have -a different effect in Ada 95, one that was not permitted in Ada 83. -As an example, the expression -@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now -delivers @code{255} as its value. -In general, you should look at the logic of any -character-processing Ada 83 program and see whether it needs to be adapted -to work correctly with Latin-1. Note that the predefined Ada 95 API has a -character handling package that may be relevant if code needs to be adapted -to account for the additional Latin-1 elements. -The desirable fix is to -modify the program to accommodate the full character set, but in some cases -it may be convenient to define a subtype or derived type of Character that -covers only the restricted range. -@end itemize - -@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 -@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{44b} -@subsection Other language compatibility issues - - - -@itemize * - -@item -`-gnat83' switch - -All implementations of GNAT provide a switch that causes GNAT to operate -in Ada 83 mode. In this mode, some but not all compatibility problems -of the type described above are handled automatically. For example, the -new reserved words introduced in Ada 95 and Ada 2005 are treated simply -as identifiers as in Ada 83. However, -in practice, it is usually advisable to make the necessary modifications -to the program to remove the need for using this switch. -See the @code{Compiling Different Versions of Ada} section in -the @cite{GNAT User’s Guide}. - -@item -Support for removed Ada 83 pragmas and attributes - -A number of pragmas and attributes from Ada 83 were removed from Ada 95, -generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 -compilers are allowed, but not required, to implement these missing -elements. In contrast with some other compilers, GNAT implements all -such pragmas and attributes, eliminating this compatibility concern. These -include @code{pragma Interface} and the floating point type attributes -(@code{Emax}, @code{Mantissa}, etc.), among other items. -@end itemize - -@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{44d} -@section Compatibility between Ada 95 and Ada 2005 - - -@geindex Compatibility between Ada 95 and Ada 2005 - -Although Ada 2005 was designed to be upwards compatible with Ada 95, there are -a number of incompatibilities. Several are enumerated below; -for a complete description please see the -@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in -@cite{Rationale for Ada 2005}. - - -@itemize * - -@item -`New reserved words.' - -The words @code{interface}, @code{overriding} and @code{synchronized} are -reserved in Ada 2005. -A pre-Ada 2005 program that uses any of these as an identifier will be -illegal. - -@item -`New declarations in predefined packages.' - -A number of packages in the predefined environment contain new declarations: -@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, -@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, -@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, -@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, -@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. -If an Ada 95 program does a @code{with} and @code{use} of any of these -packages, the new declarations may cause name clashes. - -@item -`Access parameters.' - -A nondispatching subprogram with an access parameter cannot be renamed -as a dispatching operation. This was permitted in Ada 95. - -@item -`Access types, discriminants, and constraints.' - -Rule changes in this area have led to some incompatibilities; for example, -constrained subtypes of some access types are not permitted in Ada 2005. - -@item -`Aggregates for limited types.' - -The allowance of aggregates for limited types in Ada 2005 raises the -possibility of ambiguities in legal Ada 95 programs, since additional types -now need to be considered in expression resolution. - -@item -`Fixed-point multiplication and division.' - -Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which -were legal in Ada 95 and invoked the predefined versions of these operations, -are now ambiguous. -The ambiguity may be resolved either by applying a type conversion to the -expression, or by explicitly invoking the operation from package -@code{Standard}. - -@item -`Return-by-reference types.' - -The Ada 95 return-by-reference mechanism has been removed. Instead, the user -can declare a function returning a value from an anonymous access type. -@end itemize - -@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{44f} -@section Implementation-dependent characteristics - - -Although the Ada language defines the semantics of each construct as -precisely as practical, in some situations (for example for reasons of -efficiency, or where the effect is heavily dependent on the host or target -platform) the implementation is allowed some freedom. In porting Ada 83 -code to GNAT, you need to be aware of whether / how the existing code -exercised such implementation dependencies. Such characteristics fall into -several categories, and GNAT offers specific support in assisting the -transition from certain Ada 83 compilers. - -@menu -* Implementation-defined pragmas:: -* Implementation-defined attributes:: -* Libraries:: -* Elaboration order:: -* Target-specific aspects:: - -@end menu - -@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics -@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{451} -@subsection Implementation-defined pragmas - - -Ada compilers are allowed to supplement the language-defined pragmas, and -these are a potential source of non-portability. All GNAT-defined pragmas -are described in @ref{7,,Implementation Defined Pragmas}, -and these include several that are specifically -intended to correspond to other vendors’ Ada 83 pragmas. -For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. -For compatibility with HP Ada 83, GNAT supplies the pragmas -@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, -@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, -and @code{Volatile}. -Other relevant pragmas include @code{External} and @code{Link_With}. -Some vendor-specific -Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are -recognized, thus -avoiding compiler rejection of units that contain such pragmas; they are not -relevant in a GNAT context and hence are not otherwise implemented. - -@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics -@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{453} -@subsection Implementation-defined attributes - - -Analogous to pragmas, the set of attributes may be extended by an -implementation. All GNAT-defined attributes are described in -@ref{8,,Implementation Defined Attributes}, -and these include several that are specifically intended -to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, -the attribute @code{VADS_Size} may be useful. For compatibility with HP -Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and -@code{Type_Class}. - -@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics -@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{455} -@subsection Libraries - - -Vendors may supply libraries to supplement the standard Ada API. If Ada 83 -code uses vendor-specific libraries then there are several ways to manage -this in Ada 95 and later versions of the standard: - - -@itemize * - -@item -If the source code for the libraries (specs and bodies) are -available, then the libraries can be migrated in the same way as the -application. - -@item -If the source code for the specs but not the bodies are -available, then you can reimplement the bodies. - -@item -Some features introduced by Ada 95 obviate the need for library support. For -example most Ada 83 vendors supplied a package for unsigned integers. The -Ada 95 modular type feature is the preferred way to handle this need, so -instead of migrating or reimplementing the unsigned integer package it may -be preferable to retrofit the application using modular types. -@end itemize - -@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics -@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{457} -@subsection Elaboration order - - -The implementation can choose any elaboration order consistent with the unit -dependency relationship. This freedom means that some orders can result in -Program_Error being raised due to an ‘Access Before Elaboration’: an attempt -to invoke a subprogram before its body has been elaborated, or to instantiate -a generic before the generic body has been elaborated. By default GNAT -attempts to choose a safe order (one that will not encounter access before -elaboration problems) by implicitly inserting @code{Elaborate} or -@code{Elaborate_All} pragmas where -needed. However, this can lead to the creation of elaboration circularities -and a resulting rejection of the program by gnatbind. This issue is -thoroughly described in the `Elaboration Order Handling in GNAT' appendix -in the @cite{GNAT User’s Guide}. -In brief, there are several -ways to deal with this situation: - - -@itemize * - -@item -Modify the program to eliminate the circularities, e.g., by moving -elaboration-time code into explicitly-invoked procedures - -@item -Constrain the elaboration order by including explicit @code{Elaborate_Body} or -@code{Elaborate} pragmas, and then inhibit the generation of implicit -@code{Elaborate_All} -pragmas either globally (as an effect of the `-gnatE' switch) or locally -(by selectively suppressing elaboration checks via pragma -@code{Suppress(Elaboration_Check)} when it is safe to do so). -@end itemize - -@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics -@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{459} -@subsection Target-specific aspects - - -Low-level applications need to deal with machine addresses, data -representations, interfacing with assembler code, and similar issues. If -such an Ada 83 application is being ported to different target hardware (for -example where the byte endianness has changed) then you will need to -carefully examine the program logic; the porting effort will heavily depend -on the robustness of the original design. Moreover, Ada 95 (and thus -Ada 2005 and Ada 2012) are sometimes -incompatible with typical Ada 83 compiler practices regarding implicit -packing, the meaning of the Size attribute, and the size of access values. -GNAT’s approach to these issues is described in @ref{45a,,Representation Clauses}. - -@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{45c} -@section Compatibility with Other Ada Systems - - -If programs avoid the use of implementation dependent and -implementation defined features, as documented in the -@cite{Ada Reference Manual}, there should be a high degree of portability between -GNAT and other Ada systems. The following are specific items which -have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 -compilers, but do not affect porting code to GNAT. -(As of January 2007, GNAT is the only compiler available for Ada 2005; -the following issues may or may not arise for Ada 2005 programs -when other compilers appear.) - - -@itemize * - -@item -`Ada 83 Pragmas and Attributes' - -Ada 95 compilers are allowed, but not required, to implement the missing -Ada 83 pragmas and attributes that are no longer defined in Ada 95. -GNAT implements all such pragmas and attributes, eliminating this as -a compatibility concern, but some other Ada 95 compilers reject these -pragmas and attributes. - -@item -`Specialized Needs Annexes' - -GNAT implements the full set of special needs annexes. At the -current time, it is the only Ada 95 compiler to do so. This means that -programs making use of these features may not be portable to other Ada -95 compilation systems. - -@item -`Representation Clauses' - -Some other Ada 95 compilers implement only the minimal set of -representation clauses required by the Ada 95 reference manual. GNAT goes -far beyond this minimal set, as described in the next section. -@end itemize - -@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{45a} -@section Representation Clauses - - -The Ada 83 reference manual was quite vague in describing both the minimal -required implementation of representation clauses, and also their precise -effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the -minimal set of capabilities required is still quite limited. - -GNAT implements the full required set of capabilities in -Ada 95 and Ada 2005, but also goes much further, and in particular -an effort has been made to be compatible with existing Ada 83 usage to the -greatest extent possible. - -A few cases exist in which Ada 83 compiler behavior is incompatible with -the requirements in Ada 95 (and thus also Ada 2005). These are instances of -intentional or accidental dependence on specific implementation dependent -characteristics of these Ada 83 compilers. The following is a list of -the cases most likely to arise in existing Ada 83 code. - - -@itemize * - -@item -`Implicit Packing' - -Some Ada 83 compilers allowed a Size specification to cause implicit -packing of an array or record. This could cause expensive implicit -conversions for change of representation in the presence of derived -types, and the Ada design intends to avoid this possibility. -Subsequent AI’s were issued to make it clear that such implicit -change of representation in response to a Size clause is inadvisable, -and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) -Reference Manuals as implementation advice that is followed by GNAT. -The problem will show up as an error -message rejecting the size clause. The fix is simply to provide -the explicit pragma @code{Pack}, or for more fine tuned control, provide -a Component_Size clause. - -@item -`Meaning of Size Attribute' - -The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as -the minimal number of bits required to hold values of the type. For example, -on a 32-bit machine, the size of @code{Natural} will typically be 31 and not -32 (since no sign bit is required). Some Ada 83 compilers gave 31, and -some 32 in this situation. This problem will usually show up as a compile -time error, but not always. It is a good idea to check all uses of the -‘Size attribute when porting Ada 83 code. The GNAT specific attribute -Object_Size can provide a useful way of duplicating the behavior of -some Ada 83 compiler systems. - -@item -`Size of Access Types' - -A common assumption in Ada 83 code is that an access type is in fact a pointer, -and that therefore it will be the same size as a System.Address value. This -assumption is true for GNAT in most cases with one exception. For the case of -a pointer to an unconstrained array type (where the bounds may vary from one -value of the access type to another), the default is to use a ‘fat pointer’, -which is represented as two separate pointers, one to the bounds, and one to -the array. This representation has a number of advantages, including improved -efficiency. However, it may cause some difficulties in porting existing Ada 83 -code which makes the assumption that, for example, pointers fit in 32 bits on -a machine with 32-bit addressing. - -To get around this problem, GNAT also permits the use of ‘thin pointers’ for -access types in this case (where the designated type is an unconstrained array -type). These thin pointers are indeed the same size as a System.Address value. -To specify a thin pointer, use a size clause for the type, for example: - -@example -type X is access all String; -for X'Size use Standard'Address_Size; -@end example - -which will cause the type X to be represented using a single pointer. -When using this representation, the bounds are right behind the array. -This representation is slightly less efficient, and does not allow quite -such flexibility in the use of foreign pointers or in using the -Unrestricted_Access attribute to create pointers to non-aliased objects. -But for any standard portable use of the access type it will work in -a functionally correct manner and allow porting of existing code. -Note that another way of forcing a thin pointer representation -is to use a component size clause for the element size in an array, -or a record representation clause for an access field in a record. - -See the documentation of Unrestricted_Access in the GNAT RM for a -full discussion of possible problems using this attribute in conjunction -with thin pointers. -@end itemize - -@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide -@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{45f} -@section Compatibility with HP Ada 83 - - -All the HP Ada 83 pragmas and attributes are recognized, although only a subset -of them can sensibly be implemented. The description of pragmas in -@ref{7,,Implementation Defined Pragmas} indicates whether or not they are -applicable to GNAT. - - -@itemize * - -@item -`Default floating-point representation' - -In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, -it is VMS format. - -@item -`System' - -the package System in GNAT exactly corresponds to the definition in the -Ada 95 reference manual, which means that it excludes many of the -HP Ada 83 extensions. However, a separate package Aux_DEC is provided -that contains the additional definitions, and a special pragma, -Extend_System allows this package to be treated transparently as an -extension of package System. -@end itemize - -@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top -@anchor{share/gnu_free_documentation_license doc}@anchor{460}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{461} -@chapter GNU Free Documentation License - - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -@indicateurl{https://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -`Preamble' - -The purpose of this License is to make a manual, textbook, or other -functional and useful document “free” in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of “copyleft”, which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -`1. APPLICABILITY AND DEFINITIONS' - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The `Document', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as “`you'”. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A “`Modified Version'” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A “`Secondary Section'” is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document’s overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The “`Invariant Sections'” are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The “`Cover Texts'” are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A “`Transparent'” copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not “Transparent” is called `Opaque'. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The “`Title Page'” means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, “Title Page” means -the text near the most prominent appearance of the work’s title, -preceding the beginning of the body of the text. - -The “`publisher'” means any person or entity that distributes -copies of the Document to the public. - -A section “`Entitled XYZ'” means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as “`Acknowledgements'”, -“`Dedications'”, “`Endorsements'”, or “`History'”.) -To “`Preserve the Title'” -of such a section when you modify the Document means that it remains a -section “Entitled XYZ” according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -`2. VERBATIM COPYING' - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -`3. COPYING IN QUANTITY' - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document’s license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -`4. MODIFICATIONS' - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - - -@enumerate A - -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document’s license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled “History”, Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled “History” in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the “History” section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled “Acknowledgements” or “Dedications”, -Preserve the Title of the section, and preserve in the section all -the substance and tone of each of the contributor acknowledgements -and/or dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled “Endorsements”. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled “Endorsements” -or to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version’s license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled “Endorsements”, provided it contains -nothing but endorsements of your Modified Version by various -parties—for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -`5. COMBINING DOCUMENTS' - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled “History” -in the various original documents, forming one section Entitled -“History”; likewise combine any sections Entitled “Acknowledgements”, -and any sections Entitled “Dedications”. You must delete all sections -Entitled “Endorsements”. - -`6. COLLECTIONS OF DOCUMENTS' - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -`7. AGGREGATION WITH INDEPENDENT WORKS' - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an “aggregate” if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation’s users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document’s Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -`8. TRANSLATION' - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled “Acknowledgements”, -“Dedications”, or “History”, the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -`9. TERMINATION' - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -`10. FUTURE REVISIONS OF THIS LICENSE' - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@indicateurl{https://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License “or any later version” applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy’s public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -`11. RELICENSING' - -“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -“Massive Multiauthor Collaboration” (or “MMC”) contained in the -site means any set of copyrightable works thus published on the MMC -site. - -“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -“Incorporate” means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is “eligible for relicensing” if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -`ADDENDUM: How to use this License for your documents' - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@quotation - -Copyright © YEAR YOUR NAME. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled “GNU -Free Documentation License”. -@end quotation - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the “with … Texts.” line with this: - -@quotation - -with the Invariant Sections being LIST THEIR TITLES, with the -Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. -@end quotation - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index,,GNU Free Documentation License,Top -@unnumbered Index - - -@printindex ge - - -@c %**end of body -@bye diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi deleted file mode 100644 index 7b1aaeba9545..000000000000 --- a/gcc/ada/gnat_ugn.texi +++ /dev/null @@ -1,29389 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnat_ugn.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 5.2.3.@* -@end ifinfo -@settitle GNAT User's Guide for Native Platforms -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory GNU Ada Tools -@direntry -* gnat_ugn: (gnat_ugn.info). gnat_ugn -@end direntry - -@c %**end of header - -@copying -@quotation -GNAT User's Guide for Native Platforms , Oct 27, 2022 - -AdaCore - -Copyright @copyright{} 2008-2022, Free Software Foundation -@end quotation - -@end copying - -@titlepage -@title GNAT User's Guide for Native Platforms -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top GNAT User's Guide for Native Platforms -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{gnat_ugn doc}@anchor{0} -`GNAT, The GNU Ada Development Environment' - - -@include gcc-common.texi -GCC version @value{version-GCC}@* -AdaCore - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being -“GNAT User’s Guide for Native Platforms”, -and with no Back-Cover Texts. A copy of the license is -included in the section entitled @ref{1,,GNU Free Documentation License}. - -@menu -* About This Guide:: -* Getting Started with GNAT:: -* The GNAT Compilation Model:: -* Building Executable Programs with GNAT:: -* GNAT Utility Programs:: -* GNAT and Program Execution:: -* Platform-Specific Information:: -* Example of Binder Output File:: -* Elaboration Order Handling in GNAT:: -* Inline Assembler:: -* GNU Free Documentation License:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -About This Guide - -* What This Guide Contains:: -* What You Should Know before Reading This Guide:: -* Related Information:: -* Conventions:: - -Getting Started with GNAT - -* System Requirements:: -* Running GNAT:: -* Running a Simple Ada Program:: -* Running a Program with Multiple Units:: - -The GNAT Compilation Model - -* Source Representation:: -* Foreign Language Representation:: -* File Naming Topics and Utilities:: -* Configuration Pragmas:: -* Generating Object Files:: -* Source Dependencies:: -* The Ada Library Information Files:: -* Binding an Ada Program:: -* GNAT and Libraries:: -* Conditional Compilation:: -* Mixed Language Programming:: -* GNAT and Other Compilation Models:: -* Using GNAT Files with External Tools:: - -Foreign Language Representation - -* Latin-1:: -* Other 8-Bit Codes:: -* Wide_Character Encodings:: -* Wide_Wide_Character Encodings:: - -File Naming Topics and Utilities - -* File Naming Rules:: -* Using Other File Names:: -* Alternative File Naming Schemes:: -* Handling Arbitrary File Naming Conventions with gnatname:: -* File Name Krunching with gnatkr:: -* Renaming Files with gnatchop:: - -Handling Arbitrary File Naming Conventions with gnatname - -* Arbitrary File Naming Conventions:: -* Running gnatname:: -* Switches for gnatname:: -* Examples of gnatname Usage:: - -File Name Krunching with gnatkr - -* About gnatkr:: -* Using gnatkr:: -* Krunching Method:: -* Examples of gnatkr Usage:: - -Renaming Files with gnatchop - -* Handling Files with Multiple Units:: -* Operating gnatchop in Compilation Mode:: -* Command Line for gnatchop:: -* Switches for gnatchop:: -* Examples of gnatchop Usage:: - -Configuration Pragmas - -* Handling of Configuration Pragmas:: -* The Configuration Pragmas Files:: - -GNAT and Libraries - -* Introduction to Libraries in GNAT:: -* General Ada Libraries:: -* Stand-alone Ada Libraries:: -* Rebuilding the GNAT Run-Time Library:: - -General Ada Libraries - -* Building a library:: -* Installing a library:: -* Using a library:: - -Stand-alone Ada Libraries - -* Introduction to Stand-alone Libraries:: -* Building a Stand-alone Library:: -* Creating a Stand-alone Library to be used in a non-Ada context:: -* Restrictions in Stand-alone Libraries:: - -Conditional Compilation - -* Modeling Conditional Compilation in Ada:: -* Preprocessing with gnatprep:: -* Integrated Preprocessing:: - -Modeling Conditional Compilation in Ada - -* Use of Boolean Constants:: -* Debugging - A Special Case:: -* Conditionalizing Declarations:: -* Use of Alternative Implementations:: -* Preprocessing:: - -Preprocessing with gnatprep - -* Preprocessing Symbols:: -* Using gnatprep:: -* Switches for gnatprep:: -* Form of Definitions File:: -* Form of Input Text for gnatprep:: - -Mixed Language Programming - -* Interfacing to C:: -* Calling Conventions:: -* Building Mixed Ada and C++ Programs:: -* Generating Ada Bindings for C and C++ headers:: -* Generating C Headers for Ada Specifications:: - -Building Mixed Ada and C++ Programs - -* Interfacing to C++:: -* Linking a Mixed C++ & Ada Program:: -* A Simple Example:: -* Interfacing with C++ constructors:: -* Interfacing with C++ at the Class Level:: - -Generating Ada Bindings for C and C++ headers - -* Running the Binding Generator:: -* Generating Bindings for C++ Headers:: -* Switches:: - -Generating C Headers for Ada Specifications - -* Running the C Header Generator:: - -GNAT and Other Compilation Models - -* Comparison between GNAT and C/C++ Compilation Models:: -* Comparison between GNAT and Conventional Ada Library Models:: - -Using GNAT Files with External Tools - -* Using Other Utility Programs with GNAT:: -* The External Symbol Naming Scheme of GNAT:: - -Building Executable Programs with GNAT - -* Building with gnatmake:: -* Compiling with gcc:: -* Compiler Switches:: -* Linker Switches:: -* Binding with gnatbind:: -* Linking with gnatlink:: -* Using the GNU make Utility:: - -Building with gnatmake - -* Running gnatmake:: -* Switches for gnatmake:: -* Mode Switches for gnatmake:: -* Notes on the Command Line:: -* How gnatmake Works:: -* Examples of gnatmake Usage:: - -Compiling with gcc - -* Compiling Programs:: -* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. -* Order of Compilation Issues:: -* Examples:: - -Compiler Switches - -* Alphabetical List of All Switches:: -* Output and Error Message Control:: -* Warning Message Control:: -* Debugging and Assertion Control:: -* Validity Checking:: -* Style Checking:: -* Run-Time Checks:: -* Using gcc for Syntax Checking:: -* Using gcc for Semantic Checking:: -* Compiling Different Versions of Ada:: -* Character Set Control:: -* File Naming Control:: -* Subprogram Inlining Control:: -* Auxiliary Output Control:: -* Debugging Control:: -* Exception Handling Control:: -* Units to Sources Mapping Files:: -* Code Generation Control:: - -Binding with gnatbind - -* Running gnatbind:: -* Switches for gnatbind:: -* Command-Line Access:: -* Search Paths for gnatbind:: -* Examples of gnatbind Usage:: - -Switches for gnatbind - -* Consistency-Checking Modes:: -* Binder Error Message Control:: -* Elaboration Control:: -* Output Control:: -* Dynamic Allocation Control:: -* Binding with Non-Ada Main Programs:: -* Binding Programs with No Main Subprogram:: - -Linking with gnatlink - -* Running gnatlink:: -* Switches for gnatlink:: - -Using the GNU make Utility - -* Using gnatmake in a Makefile:: -* Automatically Creating a List of Directories:: -* Generating the Command Line Switches:: -* Overcoming Command Line Length Limits:: - -GNAT Utility Programs - -* The File Cleanup Utility gnatclean:: -* The GNAT Library Browser gnatls:: - -The File Cleanup Utility gnatclean - -* Running gnatclean:: -* Switches for gnatclean:: - -The GNAT Library Browser gnatls - -* Running gnatls:: -* Switches for gnatls:: -* Example of gnatls Usage:: - -GNAT and Program Execution - -* Running and Debugging Ada Programs:: -* Profiling:: -* Improving Performance:: -* Overflow Check Handling in GNAT:: -* Performing Dimensionality Analysis in GNAT:: -* Stack Related Facilities:: -* Memory Management Issues:: - -Running and Debugging Ada Programs - -* The GNAT Debugger GDB:: -* Running GDB:: -* Introduction to GDB Commands:: -* Using Ada Expressions:: -* Calling User-Defined Subprograms:: -* Using the next Command in a Function:: -* Stopping When Ada Exceptions Are Raised:: -* Ada Tasks:: -* Debugging Generic Units:: -* Remote Debugging with gdbserver:: -* GNAT Abnormal Termination or Failure to Terminate:: -* Naming Conventions for GNAT Source Files:: -* Getting Internal Debugging Information:: -* Stack Traceback:: -* Pretty-Printers for the GNAT runtime:: - -Stack Traceback - -* Non-Symbolic Traceback:: -* Symbolic Traceback:: - -Profiling - -* Profiling an Ada Program with gprof:: - -Profiling an Ada Program with gprof - -* Compilation for profiling:: -* Program execution:: -* Running gprof:: -* Interpretation of profiling results:: - -Improving Performance - -* Performance Considerations:: -* Text_IO Suggestions:: -* Reducing Size of Executables with Unused Subprogram/Data Elimination:: - -Performance Considerations - -* Controlling Run-Time Checks:: -* Use of Restrictions:: -* Optimization Levels:: -* Debugging Optimized Code:: -* Inlining of Subprograms:: -* Floating Point Operations:: -* Vectorization of loops:: -* Other Optimization Switches:: -* Optimization and Strict Aliasing:: -* Aliased Variables and Optimization:: -* Atomic Variables and Optimization:: -* Passive Task Optimization:: - -Reducing Size of Executables with Unused Subprogram/Data Elimination - -* About unused subprogram/data elimination:: -* Compilation options:: -* Example of unused subprogram/data elimination:: - -Overflow Check Handling in GNAT - -* Background:: -* Management of Overflows in GNAT:: -* Specifying the Desired Mode:: -* Default Settings:: -* Implementation Notes:: - -Stack Related Facilities - -* Stack Overflow Checking:: -* Static Stack Usage Analysis:: -* Dynamic Stack Usage Analysis:: - -Memory Management Issues - -* Some Useful Memory Pools:: -* The GNAT Debug Pool Facility:: - -Platform-Specific Information - -* Run-Time Libraries:: -* Specifying a Run-Time Library:: -* GNU/Linux Topics:: -* Microsoft Windows Topics:: -* Mac OS Topics:: - -Run-Time Libraries - -* Summary of Run-Time Configurations:: - -Specifying a Run-Time Library - -* Choosing the Scheduling Policy:: - -GNU/Linux Topics - -* Required Packages on GNU/Linux:: -* A GNU/Linux Debug Quirk:: - -Microsoft Windows Topics - -* Using GNAT on Windows:: -* Using a network installation of GNAT:: -* CONSOLE and WINDOWS subsystems:: -* Temporary Files:: -* Disabling Command Line Argument Expansion:: -* Windows Socket Timeouts:: -* Mixed-Language Programming on Windows:: -* Windows Specific Add-Ons:: - -Mixed-Language Programming on Windows - -* Windows Calling Conventions:: -* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. -* Using DLLs with GNAT:: -* Building DLLs with GNAT Project files:: -* Building DLLs with GNAT:: -* Building DLLs with gnatdll:: -* Ada DLLs and Finalization:: -* Creating a Spec for Ada DLLs:: -* GNAT and Windows Resources:: -* Using GNAT DLLs from Microsoft Visual Studio Applications:: -* Debugging a DLL:: -* Setting Stack Size from gnatlink:: -* Setting Heap Size from gnatlink:: - -Windows Calling Conventions - -* C Calling Convention:: -* Stdcall Calling Convention:: -* Win32 Calling Convention:: -* DLL Calling Convention:: - -Using DLLs with GNAT - -* Creating an Ada Spec for the DLL Services:: -* Creating an Import Library:: - -Building DLLs with gnatdll - -* Limitations When Using Ada DLLs from Ada:: -* Exporting Ada Entities:: -* Ada DLLs and Elaboration:: - -Creating a Spec for Ada DLLs - -* Creating the Definition File:: -* Using gnatdll:: - -GNAT and Windows Resources - -* Building Resources:: -* Compiling Resources:: -* Using Resources:: - -Debugging a DLL - -* Program and DLL Both Built with GCC/GNAT:: -* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: - -Windows Specific Add-Ons - -* Win32Ada:: -* wPOSIX:: - -Mac OS Topics - -* Codesigning the Debugger:: - -Elaboration Order Handling in GNAT - -* Elaboration Code:: -* Elaboration Order:: -* Checking the Elaboration Order:: -* Controlling the Elaboration Order in Ada:: -* Controlling the Elaboration Order in GNAT:: -* Mixing Elaboration Models:: -* ABE Diagnostics:: -* SPARK Diagnostics:: -* Elaboration Circularities:: -* Resolving Elaboration Circularities:: -* Elaboration-related Compiler Switches:: -* Summary of Procedures for Elaboration Control:: -* Inspecting the Chosen Elaboration Order:: - -Inline Assembler - -* Basic Assembler Syntax:: -* A Simple Example of Inline Assembler:: -* Output Variables in Inline Assembler:: -* Input Variables in Inline Assembler:: -* Inlining Inline Assembler Code:: -* Other Asm Functionality:: - -Other Asm Functionality - -* The Clobber Parameter:: -* The Volatile Parameter:: - -@end detailmenu -@end menu - -@node About This Guide,Getting Started with GNAT,Top,Top -@anchor{gnat_ugn/about_this_guide doc}@anchor{2}@anchor{gnat_ugn/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_ugn/about_this_guide gnat-user-s-guide-for-native-platforms}@anchor{4}@anchor{gnat_ugn/about_this_guide id1}@anchor{5} -@chapter About This Guide - - - -This guide describes the use of GNAT, -a compiler and software development -toolset for the full Ada programming language. -It documents the features of the compiler and tools, and explains -how to use them to build Ada applications. - -GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be -invoked in Ada 83 compatibility mode. -By default, GNAT assumes Ada 2012, but you can override with a -compiler switch (@ref{6,,Compiling Different Versions of Ada}) -to explicitly specify the language version. -Throughout this manual, references to ‘Ada’ without a year suffix -apply to all Ada versions of the language, starting with Ada 95. - -@menu -* What This Guide Contains:: -* What You Should Know before Reading This Guide:: -* Related Information:: -* Conventions:: - -@end menu - -@node What This Guide Contains,What You Should Know before Reading This Guide,,About This Guide -@anchor{gnat_ugn/about_this_guide what-this-guide-contains}@anchor{7} -@section What This Guide Contains - - -This guide contains the following chapters: - - -@itemize * - -@item -@ref{8,,Getting Started with GNAT} describes how to get started compiling -and running Ada programs with the GNAT Ada programming environment. - -@item -@ref{9,,The GNAT Compilation Model} describes the compilation model used -by GNAT. - -@item -@ref{a,,Building Executable Programs with GNAT} describes how to use the -main GNAT tools to build executable programs, and it also gives examples of -using the GNU make utility with GNAT. - -@item -@ref{b,,GNAT Utility Programs} explains the various utility programs that -are included in the GNAT environment - -@item -@ref{c,,GNAT and Program Execution} covers a number of topics related to -running, debugging, and tuning the performace of programs developed -with GNAT -@end itemize - -Appendices cover several additional topics: - - -@itemize * - -@item -@ref{d,,Platform-Specific Information} describes the different run-time -library implementations and also presents information on how to use -GNAT on several specific platforms - -@item -@ref{e,,Example of Binder Output File} shows the source code for the binder -output file for a sample program. - -@item -@ref{f,,Elaboration Order Handling in GNAT} describes how GNAT helps -you deal with elaboration order issues. - -@item -@ref{10,,Inline Assembler} shows how to use the inline assembly facility -in an Ada program. -@end itemize - -@node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide -@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{11} -@section What You Should Know before Reading This Guide - - -@geindex Ada 95 Language Reference Manual - -@geindex Ada 2005 Language Reference Manual - -This guide assumes a basic familiarity with the Ada 95 language, as -described in the International Standard ANSI/ISO/IEC-8652:1995, January -1995. -Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in -the GNAT documentation package. - -@node Related Information,Conventions,What You Should Know before Reading This Guide,About This Guide -@anchor{gnat_ugn/about_this_guide related-information}@anchor{12} -@section Related Information - - -For further information about Ada and related tools, please refer to the -following documents: - - -@itemize * - -@item -@cite{Ada 95 Reference Manual}, @cite{Ada 2005 Reference Manual}, and -@cite{Ada 2012 Reference Manual}, which contain reference -material for the several revisions of the Ada language standard. - -@item -@cite{GNAT Reference_Manual}, which contains all reference material for the GNAT -implementation of Ada. - -@item -@cite{Using GNAT Studio}, which describes the GNAT Studio -Integrated Development Environment. - -@item -@cite{GNAT Studio Tutorial}, which introduces the -main GNAT Studio features through examples. - -@item -@cite{Debugging with GDB}, -for all details on the use of the GNU source-level debugger. - -@item -@cite{GNU Emacs Manual}, -for full information on the extensible editor and programming -environment Emacs. -@end itemize - -@node Conventions,,Related Information,About This Guide -@anchor{gnat_ugn/about_this_guide conventions}@anchor{13} -@section Conventions - - -@geindex Conventions -@geindex typographical - -@geindex Typographical conventions - -Following are examples of the typographical and graphic conventions used -in this guide: - - -@itemize * - -@item -@code{Functions}, @code{utility program names}, @code{standard names}, -and @code{classes}. - -@item -@code{Option flags} - -@item -@code{File names} - -@item -@code{Variables} - -@item -`Emphasis' - -@item -[optional information or parameters] - -@item -Examples are described by text - -@example -and then shown this way. -@end example - -@item -Commands that are entered by the user are shown as preceded by a prompt string -comprising the @code{$} character followed by a space. - -@item -Full file names are shown with the ‘/’ character -as the directory separator; e.g., @code{parent-dir/subdir/myfile.adb}. -If you are using GNAT on a Windows platform, please note that -the ‘\’ character should be used instead. -@end itemize - -@node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top -@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{14}@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{15} -@chapter Getting Started with GNAT - - -This chapter describes how to use GNAT’s command line interface to build -executable Ada programs. -On most platforms a visually oriented Integrated Development Environment -is also available: GNAT Studio. -GNAT Studio offers a graphical “look and feel”, support for development in -other programming languages, comprehensive browsing features, and -many other capabilities. -For information on GNAT Studio please refer to the -@cite{GNAT Studio documentation}. - -@menu -* System Requirements:: -* Running GNAT:: -* Running a Simple Ada Program:: -* Running a Program with Multiple Units:: - -@end menu - -@node System Requirements,Running GNAT,,Getting Started with GNAT -@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{16}@anchor{gnat_ugn/getting_started_with_gnat system-requirements}@anchor{17} -@section System Requirements - - -Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order -to get the best experience, we recommend using a machine with as many cores -as possible since all individual compilations can run in parallel. -A comfortable setup for a compiler server is a machine with 24 physical cores -or more, with at least 48 GB of memory (2 GB per core). - -For a desktop machine, a minimum of 4 cores is recommended (8 preferred), -with at least 2GB per core (so 8 to 16GB). - -In addition, for running and navigating sources in GNAT Studio smoothly, we -recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code. -In other words, we recommend at least 3 GB for for 500K lines of code and -7.5 GB for 2 million lines of code. - -Note that using local and fast drives will also make a difference in terms of -build and link time. Network drives such as NFS, SMB, or worse, configuration -management filesystems (such as ClearCase dynamic views) should be avoided as -much as possible and will produce very degraded performance (typically 2 to 3 -times slower than on local fast drives). If such slow drives cannot be avoided -for accessing the source code, then you should at least configure your project -file so that the result of the compilation is stored on a drive local to the -machine performing the run. This can be achieved by setting the @code{Object_Dir} -project file attribute. - -@node Running GNAT,Running a Simple Ada Program,System Requirements,Getting Started with GNAT -@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{18}@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{19} -@section Running GNAT - - -Three steps are needed to create an executable file from an Ada source -file: - - -@itemize * - -@item -The source file(s) must be compiled. - -@item -The file(s) must be bound using the GNAT binder. - -@item -All appropriate object files must be linked to produce an executable. -@end itemize - -All three steps are most commonly handled by using the @code{gnatmake} -utility program that, given the name of the main program, automatically -performs the necessary compilation, binding and linking steps. - -@node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT -@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{1a}@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{1b} -@section Running a Simple Ada Program - - -Any text editor may be used to prepare an Ada program. -(If Emacs is used, the optional Ada mode may be helpful in laying out the -program.) -The program text is a normal text file. We will assume in our initial -example that you have used your editor to prepare the following -standard format text file: - -@example -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello is -begin - Put_Line ("Hello WORLD!"); -end Hello; -@end example - -This file should be named @code{hello.adb}. -With the normal default file naming conventions, GNAT requires -that each file -contain a single compilation unit whose file name is the -unit name, -with periods replaced by hyphens; the -extension is @code{ads} for a -spec and @code{adb} for a body. -You can override this default file naming convention by use of the -special pragma @code{Source_File_Name} (for further information please -see @ref{1c,,Using Other File Names}). -Alternatively, if you want to rename your files according to this default -convention, which is probably more convenient if you will be using GNAT -for all your compilations, then the @code{gnatchop} utility -can be used to generate correctly-named source files -(see @ref{1d,,Renaming Files with gnatchop}). - -You can compile the program using the following command (@code{$} is used -as the command prompt in the examples in this document): - -@example -$ gcc -c hello.adb -@end example - -@code{gcc} is the command used to run the compiler. This compiler is -capable of compiling programs in several languages, including Ada and -C. It assumes that you have given it an Ada program if the file extension is -either @code{.ads} or @code{.adb}, and it will then call -the GNAT compiler to compile the specified file. - -The @code{-c} switch is required. It tells @code{gcc} to only do a -compilation. (For C programs, @code{gcc} can also do linking, but this -capability is not used directly for Ada programs, so the @code{-c} -switch must always be present.) - -This compile command generates a file -@code{hello.o}, which is the object -file corresponding to your Ada program. It also generates -an ‘Ada Library Information’ file @code{hello.ali}, -which contains additional information used to check -that an Ada program is consistent. - -To build an executable file, use either @code{gnatmake} or gprbuild with -the name of the main file: these tools are builders that will take care of -all the necessary build steps in the correct order. -In particular, these builders automatically recompile any sources that have -been modified since they were last compiled, or sources that depend -on such modified sources, so that ‘version skew’ is avoided. - -@geindex Version skew (avoided by `@w{`}gnatmake`@w{`}) - -@example -$ gnatmake hello.adb -@end example - -The result is an executable program called @code{hello}, which can be -run by entering: - -@example -$ hello -@end example - -assuming that the current directory is on the search path -for executable programs. - -and, if all has gone well, you will see: - -@example -Hello WORLD! -@end example - -appear in response to this command. - -@node Running a Program with Multiple Units,,Running a Simple Ada Program,Getting Started with GNAT -@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{1e}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{1f} -@section Running a Program with Multiple Units - - -Consider a slightly more complicated example that has three files: a -main program, and the spec and body of a package: - -@example -package Greetings is - procedure Hello; - procedure Goodbye; -end Greetings; - -with Ada.Text_IO; use Ada.Text_IO; -package body Greetings is - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - procedure Goodbye is - begin - Put_Line ("Goodbye WORLD!"); - end Goodbye; -end Greetings; - -with Greetings; -procedure Gmain is -begin - Greetings.Hello; - Greetings.Goodbye; -end Gmain; -@end example - -Following the one-unit-per-file rule, place this program in the -following three separate files: - - -@table @asis - -@item `greetings.ads' - -spec of package @code{Greetings} - -@item `greetings.adb' - -body of package @code{Greetings} - -@item `gmain.adb' - -body of main program -@end table - -Note that there is no required order of compilation when using GNAT. -In particular it is perfectly fine to compile the main program first. -Also, it is not necessary to compile package specs in the case where -there is an accompanying body; you only need to compile the body. If you want -to submit these files to the compiler for semantic checking and not code -generation, then use the @code{-gnatc} switch: - -@example -$ gcc -c greetings.ads -gnatc -@end example - -Although the compilation can be done in separate steps, in practice it is -almost always more convenient to use the @code{gnatmake} or @code{gprbuild} tools: - -@example -$ gnatmake gmain.adb -@end example - -@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit - -@node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top -@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{20}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{21}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9} -@chapter The GNAT Compilation Model - - -@geindex GNAT compilation model - -@geindex Compilation model - -This chapter describes the compilation model used by GNAT. Although -similar to that used by other languages such as C and C++, this model -is substantially different from the traditional Ada compilation models, -which are based on a centralized program library. The chapter covers -the following material: - - -@itemize * - -@item -Topics related to source file makeup and naming - - -@itemize * - -@item -@ref{22,,Source Representation} - -@item -@ref{23,,Foreign Language Representation} - -@item -@ref{24,,File Naming Topics and Utilities} -@end itemize - -@item -@ref{25,,Configuration Pragmas} - -@item -@ref{26,,Generating Object Files} - -@item -@ref{27,,Source Dependencies} - -@item -@ref{28,,The Ada Library Information Files} - -@item -@ref{29,,Binding an Ada Program} - -@item -@ref{2a,,GNAT and Libraries} - -@item -@ref{2b,,Conditional Compilation} - -@item -@ref{2c,,Mixed Language Programming} - -@item -@ref{2d,,GNAT and Other Compilation Models} - -@item -@ref{2e,,Using GNAT Files with External Tools} -@end itemize - -@menu -* Source Representation:: -* Foreign Language Representation:: -* File Naming Topics and Utilities:: -* Configuration Pragmas:: -* Generating Object Files:: -* Source Dependencies:: -* The Ada Library Information Files:: -* Binding an Ada Program:: -* GNAT and Libraries:: -* Conditional Compilation:: -* Mixed Language Programming:: -* GNAT and Other Compilation Models:: -* Using GNAT Files with External Tools:: - -@end menu - -@node Source Representation,Foreign Language Representation,,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{2f}@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{22} -@section Source Representation - - -@geindex Latin-1 - -@geindex VT -@geindex HT -@geindex CR -@geindex LF -@geindex FF - -Ada source programs are represented in standard text files, using -Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar -7-bit ASCII set, plus additional characters used for -representing foreign languages (see @ref{23,,Foreign Language Representation} -for support of non-USA character sets). The format effector characters -are represented using their standard ASCII encodings, as follows: - -@quotation - - -@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} -@item - -Character - -@tab - -Effect - -@tab - -Code - -@item - -@code{VT} - -@tab - -Vertical tab - -@tab - -@code{16#0B#} - -@item - -@code{HT} - -@tab - -Horizontal tab - -@tab - -@code{16#09#} - -@item - -@code{CR} - -@tab - -Carriage return - -@tab - -@code{16#0D#} - -@item - -@code{LF} - -@tab - -Line feed - -@tab - -@code{16#0A#} - -@item - -@code{FF} - -@tab - -Form feed - -@tab - -@code{16#0C#} - -@end multitable - -@end quotation - -Source files are in standard text file format. In addition, GNAT will -recognize a wide variety of stream formats, in which the end of -physical lines is marked by any of the following sequences: -@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful -in accommodating files that are imported from other operating systems. - -@geindex End of source file; Source file@comma{} end - -@geindex SUB (control character) - -The end of a source file is normally represented by the physical end of -file. However, the control character @code{16#1A#} (@code{SUB}) is also -recognized as signalling the end of the source file. Again, this is -provided for compatibility with other operating systems where this -code is used to represent the end of file. - -@geindex spec (definition) -@geindex compilation (definition) - -Each file contains a single Ada compilation unit, including any pragmas -associated with the unit. For example, this means you must place a -package declaration (a package `spec') and the corresponding body in -separate files. An Ada `compilation' (which is a sequence of -compilation units) is represented using a sequence of files. Similarly, -you will place each subunit or child unit in a separate file. - -@node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{23}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{30} -@section Foreign Language Representation - - -GNAT supports the standard character sets defined in Ada as well as -several other non-standard character sets for use in localized versions -of the compiler (@ref{31,,Character Set Control}). - -@menu -* Latin-1:: -* Other 8-Bit Codes:: -* Wide_Character Encodings:: -* Wide_Wide_Character Encodings:: - -@end menu - -@node Latin-1,Other 8-Bit Codes,,Foreign Language Representation -@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33} -@subsection Latin-1 - - -@geindex Latin-1 - -The basic character set is Latin-1. This character set is defined by ISO -standard 8859, part 1. The lower half (character codes @code{16#00#} -… @code{16#7F#)} is identical to standard ASCII coding, but the upper -half is used to represent additional characters. These include extended letters -used by European languages, such as French accents, the vowels with umlauts -used in German, and the extra letter A-ring used in Swedish. - -@geindex Ada.Characters.Latin_1 - -For a complete list of Latin-1 codes and their encodings, see the source -file of library unit @code{Ada.Characters.Latin_1} in file -@code{a-chlat1.ads}. -You may use any of these extended characters freely in character or -string literals. In addition, the extended characters that represent -letters can be used in identifiers. - -@node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation -@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{34}@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{35} -@subsection Other 8-Bit Codes - - -GNAT also supports several other 8-bit coding schemes: - -@geindex Latin-2 - -@geindex ISO 8859-2 - - -@table @asis - -@item `ISO 8859-2 (Latin-2)' - -Latin-2 letters allowed in identifiers, with uppercase and lowercase -equivalence. -@end table - -@geindex Latin-3 - -@geindex ISO 8859-3 - - -@table @asis - -@item `ISO 8859-3 (Latin-3)' - -Latin-3 letters allowed in identifiers, with uppercase and lowercase -equivalence. -@end table - -@geindex Latin-4 - -@geindex ISO 8859-4 - - -@table @asis - -@item `ISO 8859-4 (Latin-4)' - -Latin-4 letters allowed in identifiers, with uppercase and lowercase -equivalence. -@end table - -@geindex ISO 8859-5 - -@geindex Cyrillic - - -@table @asis - -@item `ISO 8859-5 (Cyrillic)' - -ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and -lowercase equivalence. -@end table - -@geindex ISO 8859-15 - -@geindex Latin-9 - - -@table @asis - -@item `ISO 8859-15 (Latin-9)' - -ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and -lowercase equivalence -@end table - -@geindex code page 437 (IBM PC) - - -@table @asis - -@item `IBM PC (code page 437)' - -This code page is the normal default for PCs in the U.S. It corresponds -to the original IBM PC character set. This set has some, but not all, of -the extended Latin-1 letters, but these letters do not have the same -encoding as Latin-1. In this mode, these letters are allowed in -identifiers with uppercase and lowercase equivalence. -@end table - -@geindex code page 850 (IBM PC) - - -@table @asis - -@item `IBM PC (code page 850)' - -This code page is a modification of 437 extended to include all the -Latin-1 letters, but still not with the usual Latin-1 encoding. In this -mode, all these letters are allowed in identifiers with uppercase and -lowercase equivalence. - -@item `Full Upper 8-bit' - -Any character in the range 80-FF allowed in identifiers, and all are -considered distinct. In other words, there are no uppercase and lowercase -equivalences in this range. This is useful in conjunction with -certain encoding schemes used for some foreign character sets (e.g., -the typical method of representing Chinese characters on the PC). - -@item `No Upper-Half' - -No upper-half characters in the range 80-FF are allowed in identifiers. -This gives Ada 83 compatibility for identifier names. -@end table - -For precise data on the encodings permitted, and the uppercase and lowercase -equivalences that are recognized, see the file @code{csets.adb} in -the GNAT compiler sources. You will need to obtain a full source release -of GNAT to obtain this file. - -@node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation -@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{36}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{37} -@subsection Wide_Character Encodings - - -GNAT allows wide character codes to appear in character and string -literals, and also optionally in identifiers, by means of the following -possible encoding schemes: - - -@table @asis - -@item `Hex Coding' - -In this encoding, a wide character is represented by the following five -character sequence: - -@example -ESC a b c d -@end example - -where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal -characters (using uppercase letters) of the wide character code. For -example, ESC A345 is used to represent the wide character with code -@code{16#A345#}. -This scheme is compatible with use of the full Wide_Character set. - -@item `Upper-Half Coding' - -@geindex Upper-Half Coding - -The wide character with encoding @code{16#abcd#} where the upper bit is on -(in other words, ‘a’ is in the range 8-F) is represented as two bytes, -@code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control -character, but is not required to be in the upper half. This method can -be also used for shift-JIS or EUC, where the internal coding matches the -external coding. - -@item `Shift JIS Coding' - -@geindex Shift JIS Coding - -A wide character is represented by a two-character sequence, -@code{16#ab#} and -@code{16#cd#}, with the restrictions described for upper-half encoding as -described above. The internal character code is the corresponding JIS -character according to the standard algorithm for Shift-JIS -conversion. Only characters defined in the JIS code set table can be -used with this encoding method. - -@item `EUC Coding' - -@geindex EUC Coding - -A wide character is represented by a two-character sequence -@code{16#ab#} and -@code{16#cd#}, with both characters being in the upper half. The internal -character code is the corresponding JIS character according to the EUC -encoding algorithm. Only characters defined in the JIS code set table -can be used with this encoding method. - -@item `UTF-8 Coding' - -A wide character is represented using -UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO -10646-1/Am.2. Depending on the character value, the representation -is a one, two, or three byte sequence: - -@example -16#0000#-16#007f#: 2#0xxxxxxx# -16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# -16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# -@end example - -where the @code{xxx} bits correspond to the left-padded bits of the -16-bit character value. Note that all lower half ASCII characters -are represented as ASCII bytes and all upper half characters and -other wide characters are represented as sequences of upper-half -(The full UTF-8 scheme allows for encoding 31-bit characters as -6-byte sequences, and in the following section on wide wide -characters, the use of these sequences is documented). - -@item `Brackets Coding' - -In this encoding, a wide character is represented by the following eight -character sequence: - -@example -[ " a b c d " ] -@end example - -where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal -characters (using uppercase letters) of the wide character code. For -example, [‘A345’] is used to represent the wide character with code -@code{16#A345#}. It is also possible (though not required) to use the -Brackets coding for upper half characters. For example, the code -@code{16#A3#} can be represented as @code{['A3']}. - -This scheme is compatible with use of the full Wide_Character set, -and is also the method used for wide character encoding in some standard -ACATS (Ada Conformity Assessment Test Suite) test suite distributions. -@end table - -@cartouche -@quotation Note -Some of these coding schemes do not permit the full use of the -Ada character set. For example, neither Shift JIS nor EUC allow the -use of the upper half of the Latin-1 set. -@end quotation -@end cartouche - -@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation -@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{38}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{39} -@subsection Wide_Wide_Character Encodings - - -GNAT allows wide wide character codes to appear in character and string -literals, and also optionally in identifiers, by means of the following -possible encoding schemes: - - -@table @asis - -@item `UTF-8 Coding' - -A wide character is represented using -UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO -10646-1/Am.2. Depending on the character value, the representation -of character codes with values greater than 16#FFFF# is a -is a four, five, or six byte sequence: - -@example -16#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx - 10xxxxxx -16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx - 10xxxxxx 10xxxxxx -16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx - 10xxxxxx 10xxxxxx 10xxxxxx -@end example - -where the @code{xxx} bits correspond to the left-padded bits of the -32-bit character value. - -@item `Brackets Coding' - -In this encoding, a wide wide character is represented by the following ten or -twelve byte character sequence: - -@example -[ " a b c d e f " ] -[ " a b c d e f g h " ] -@end example - -where @code{a-h} are the six or eight hexadecimal -characters (using uppercase letters) of the wide wide character code. For -example, [“1F4567”] is used to represent the wide wide character with code -@code{16#001F_4567#}. - -This scheme is compatible with use of the full Wide_Wide_Character set, -and is also the method used for wide wide character encoding in some standard -ACATS (Ada Conformity Assessment Test Suite) test suite distributions. -@end table - -@node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{24}@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{3a} -@section File Naming Topics and Utilities - - -GNAT has a default file naming scheme and also provides the user with -a high degree of control over how the names and extensions of the -source files correspond to the Ada compilation units that they contain. - -@menu -* File Naming Rules:: -* Using Other File Names:: -* Alternative File Naming Schemes:: -* Handling Arbitrary File Naming Conventions with gnatname:: -* File Name Krunching with gnatkr:: -* Renaming Files with gnatchop:: - -@end menu - -@node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{3c} -@subsection File Naming Rules - - -The default file name is determined by the name of the unit that the -file contains. The name is formed by taking the full expanded name of -the unit and replacing the separating dots with hyphens and using -lowercase for all letters. - -An exception arises if the file name generated by the above rules starts -with one of the characters -@code{a}, @code{g}, @code{i}, or @code{s}, and the second character is a -minus. In this case, the character tilde is used in place -of the minus. The reason for this special rule is to avoid clashes with -the standard names for child units of the packages System, Ada, -Interfaces, and GNAT, which use the prefixes -@code{s-}, @code{a-}, @code{i-}, and @code{g-}, -respectively. - -The file extension is @code{.ads} for a spec and -@code{.adb} for a body. The following table shows some -examples of these rules. - -@quotation - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -Source File - -@tab - -Ada Compilation Unit - -@item - -@code{main.ads} - -@tab - -Main (spec) - -@item - -@code{main.adb} - -@tab - -Main (body) - -@item - -@code{arith_functions.ads} - -@tab - -Arith_Functions (package spec) - -@item - -@code{arith_functions.adb} - -@tab - -Arith_Functions (package body) - -@item - -@code{func-spec.ads} - -@tab - -Func.Spec (child package spec) - -@item - -@code{func-spec.adb} - -@tab - -Func.Spec (child package body) - -@item - -@code{main-sub.adb} - -@tab - -Sub (subunit of Main) - -@item - -@code{a~bad.adb} - -@tab - -A.Bad (child package body) - -@end multitable - -@end quotation - -Following these rules can result in excessively long -file names if corresponding -unit names are long (for example, if child units or subunits are -heavily nested). An option is available to shorten such long file names -(called file name ‘krunching’). This may be particularly useful when -programs being developed with GNAT are to be used on operating systems -with limited file name lengths. @ref{3d,,Using gnatkr}. - -Of course, no file shortening algorithm can guarantee uniqueness over -all possible unit names; if file name krunching is used, it is your -responsibility to ensure no name clashes occur. Alternatively you -can specify the exact file names that you want used, as described -in the next section. Finally, if your Ada programs are migrating from a -compiler with a different naming convention, you can use the gnatchop -utility to produce source files that follow the GNAT naming conventions. -(For details see @ref{1d,,Renaming Files with gnatchop}.) - -Note: in the case of Windows or Mac OS operating systems, case is not -significant. So for example on Windows if the canonical name is -@code{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead. -However, case is significant for other operating systems, so for example, -if you want to use other than canonically cased file names on a Unix system, -you need to follow the procedures described in the next section. - -@node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{1c} -@subsection Using Other File Names - - -@geindex File names - -In the previous section, we have described the default rules used by -GNAT to determine the file name in which a given unit resides. It is -often convenient to follow these default rules, and if you follow them, -the compiler knows without being explicitly told where to find all -the files it needs. - -@geindex Source_File_Name pragma - -However, in some cases, particularly when a program is imported from -another Ada compiler environment, it may be more convenient for the -programmer to specify which file names contain which units. GNAT allows -arbitrary file names to be used by means of the Source_File_Name pragma. -The form of this pragma is as shown in the following examples: - -@example -pragma Source_File_Name (My_Utilities.Stacks, - Spec_File_Name => "myutilst_a.ada"); -pragma Source_File_name (My_Utilities.Stacks, - Body_File_Name => "myutilst.ada"); -@end example - -As shown in this example, the first argument for the pragma is the unit -name (in this example a child unit). The second argument has the form -of a named association. The identifier -indicates whether the file name is for a spec or a body; -the file name itself is given by a string literal. - -The source file name pragma is a configuration pragma, which means that -normally it will be placed in the @code{gnat.adc} -file used to hold configuration -pragmas that apply to a complete compilation environment. -For more details on how the @code{gnat.adc} file is created and used -see @ref{3f,,Handling of Configuration Pragmas}. - -@geindex gnat.adc - -GNAT allows completely arbitrary file names to be specified using the -source file name pragma. However, if the file name specified has an -extension other than @code{.ads} or @code{.adb} it is necessary to use -a special syntax when compiling the file. The name in this case must be -preceded by the special sequence @code{-x} followed by a space and the name -of the language, here @code{ada}, as in: - -@example -$ gcc -c -x ada peculiar_file_name.sim -@end example - -@code{gnatmake} handles non-standard file names in the usual manner (the -non-standard file name for the main program is simply used as the -argument to gnatmake). Note that if the extension is also non-standard, -then it must be included in the @code{gnatmake} command, it may not -be omitted. - -@node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{41} -@subsection Alternative File Naming Schemes - - -@geindex File naming schemes -@geindex alternative - -@geindex File names - -The previous section described the use of the @code{Source_File_Name} -pragma to allow arbitrary names to be assigned to individual source files. -However, this approach requires one pragma for each file, and especially in -large systems can result in very long @code{gnat.adc} files, and also create -a maintenance problem. - -@geindex Source_File_Name pragma - -GNAT also provides a facility for specifying systematic file naming schemes -other than the standard default naming scheme previously described. An -alternative scheme for naming is specified by the use of -@code{Source_File_Name} pragmas having the following format: - -@example -pragma Source_File_Name ( - Spec_File_Name => FILE_NAME_PATTERN - [ , Casing => CASING_SPEC] - [ , Dot_Replacement => STRING_LITERAL ] ); - -pragma Source_File_Name ( - Body_File_Name => FILE_NAME_PATTERN - [ , Casing => CASING_SPEC ] - [ , Dot_Replacement => STRING_LITERAL ] ) ; - -pragma Source_File_Name ( - Subunit_File_Name => FILE_NAME_PATTERN - [ , Casing => CASING_SPEC ] - [ , Dot_Replacement => STRING_LITERAL ] ) ; - -FILE_NAME_PATTERN ::= STRING_LITERAL -CASING_SPEC ::= Lowercase | Uppercase | Mixedcase -@end example - -The @code{FILE_NAME_PATTERN} string shows how the file name is constructed. -It contains a single asterisk character, and the unit name is substituted -systematically for this asterisk. The optional parameter -@code{Casing} indicates -whether the unit name is to be all upper-case letters, all lower-case letters, -or mixed-case. If no -@code{Casing} parameter is used, then the default is all -lower-case. - -The optional @code{Dot_Replacement} string is used to replace any periods -that occur in subunit or child unit names. If no @code{Dot_Replacement} -argument is used then separating dots appear unchanged in the resulting -file name. -Although the above syntax indicates that the -@code{Casing} argument must appear -before the @code{Dot_Replacement} argument, but it -is also permissible to write these arguments in the opposite order. - -As indicated, it is possible to specify different naming schemes for -bodies, specs, and subunits. Quite often the rule for subunits is the -same as the rule for bodies, in which case, there is no need to give -a separate @code{Subunit_File_Name} rule, and in this case the -@code{Body_File_name} rule is used for subunits as well. - -The separate rule for subunits can also be used to implement the rather -unusual case of a compilation environment (e.g., a single directory) which -contains a subunit and a child unit with the same unit name. Although -both units cannot appear in the same partition, the Ada Reference Manual -allows (but does not require) the possibility of the two units coexisting -in the same environment. - -The file name translation works in the following steps: - - -@itemize * - -@item -If there is a specific @code{Source_File_Name} pragma for the given unit, -then this is always used, and any general pattern rules are ignored. - -@item -If there is a pattern type @code{Source_File_Name} pragma that applies to -the unit, then the resulting file name will be used if the file exists. If -more than one pattern matches, the latest one will be tried first, and the -first attempt resulting in a reference to a file that exists will be used. - -@item -If no pattern type @code{Source_File_Name} pragma that applies to the unit -for which the corresponding file exists, then the standard GNAT default -naming rules are used. -@end itemize - -As an example of the use of this mechanism, consider a commonly used scheme -in which file names are all lower case, with separating periods copied -unchanged to the resulting file name, and specs end with @code{.1.ada}, and -bodies end with @code{.2.ada}. GNAT will follow this scheme if the following -two pragmas appear: - -@example -pragma Source_File_Name - (Spec_File_Name => ".1.ada"); -pragma Source_File_Name - (Body_File_Name => ".2.ada"); -@end example - -The default GNAT scheme is actually implemented by providing the following -default pragmas internally: - -@example -pragma Source_File_Name - (Spec_File_Name => ".ads", Dot_Replacement => "-"); -pragma Source_File_Name - (Body_File_Name => ".adb", Dot_Replacement => "-"); -@end example - -Our final example implements a scheme typically used with one of the -Ada 83 compilers, where the separator character for subunits was ‘__’ -(two underscores), specs were identified by adding @code{_.ADA}, bodies -by adding @code{.ADA}, and subunits by -adding @code{.SEP}. All file names were -upper case. Child units were not present of course since this was an -Ada 83 compiler, but it seems reasonable to extend this scheme to use -the same double underscore separator for child units. - -@example -pragma Source_File_Name - (Spec_File_Name => "_.ADA", - Dot_Replacement => "__", - Casing = Uppercase); -pragma Source_File_Name - (Body_File_Name => ".ADA", - Dot_Replacement => "__", - Casing = Uppercase); -pragma Source_File_Name - (Subunit_File_Name => ".SEP", - Dot_Replacement => "__", - Casing = Uppercase); -@end example - -@geindex gnatname - -@node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{42}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{43} -@subsection Handling Arbitrary File Naming Conventions with @code{gnatname} - - -@geindex File Naming Conventions - -@menu -* Arbitrary File Naming Conventions:: -* Running gnatname:: -* Switches for gnatname:: -* Examples of gnatname Usage:: - -@end menu - -@node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname -@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{45} -@subsubsection Arbitrary File Naming Conventions - - -The GNAT compiler must be able to know the source file name of a compilation -unit. When using the standard GNAT default file naming conventions -(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler -does not need additional information. - -When the source file names do not follow the standard GNAT default file naming -conventions, the GNAT compiler must be given additional information through -a configuration pragmas file (@ref{25,,Configuration Pragmas}) -or a project file. -When the non-standard file naming conventions are well-defined, -a small number of pragmas @code{Source_File_Name} specifying a naming pattern -(@ref{40,,Alternative File Naming Schemes}) may be sufficient. However, -if the file naming conventions are irregular or arbitrary, a number -of pragma @code{Source_File_Name} for individual compilation units -must be defined. -To help maintain the correspondence between compilation unit names and -source file names within the compiler, -GNAT provides a tool @code{gnatname} to generate the required pragmas for a -set of files. - -@node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname -@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{47} -@subsubsection Running @code{gnatname} - - -The usual form of the @code{gnatname} command is: - -@example -$ gnatname [ switches ] naming_pattern [ naming_patterns ] - [--and [ switches ] naming_pattern [ naming_patterns ]] -@end example - -All of the arguments are optional. If invoked without any argument, -@code{gnatname} will display its usage. - -When used with at least one naming pattern, @code{gnatname} will attempt to -find all the compilation units in files that follow at least one of the -naming patterns. To find these compilation units, -@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all -regular files. - -One or several Naming Patterns may be given as arguments to @code{gnatname}. -Each Naming Pattern is enclosed between double quotes (or single -quotes on Windows). -A Naming Pattern is a regular expression similar to the wildcard patterns -used in file names by the Unix shells or the DOS prompt. - -@code{gnatname} may be called with several sections of directories/patterns. -Sections are separated by the switch @code{--and}. In each section, there must be -at least one pattern. If no directory is specified in a section, the current -directory (or the project directory if @code{-P} is used) is implied. -The options other that the directory switches and the patterns apply globally -even if they are in different sections. - -Examples of Naming Patterns are: - -@example -"*.[12].ada" -"*.ad[sb]*" -"body_*" "spec_*" -@end example - -For a more complete description of the syntax of Naming Patterns, -see the second kind of regular expressions described in @code{g-regexp.ads} -(the ‘Glob’ regular expressions). - -When invoked without the switch @code{-P}, @code{gnatname} will create a -configuration pragmas file @code{gnat.adc} in the current working directory, -with pragmas @code{Source_File_Name} for each file that contains a valid Ada -unit. - -@node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname -@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{48}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{49} -@subsubsection Switches for @code{gnatname} - - -Switches for @code{gnatname} must precede any specified Naming Pattern. - -You may specify any of the following switches to @code{gnatname}: - -@geindex --version (gnatname) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatname) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. - -@item @code{--subdirs=`dir'} - -Real object, library or exec directories are subdirectories of the -specified ones. - -@item @code{--no-backup} - -Do not create a backup copy of an existing project file. - -@item @code{--and} - -Start another section of directories/patterns. -@end table - -@geindex -c (gnatname) - - -@table @asis - -@item @code{-c`filename'} - -Create a configuration pragmas file @code{filename} (instead of the default -@code{gnat.adc}). -There may be zero, one or more space between @code{-c} and -@code{filename}. -@code{filename} may include directory information. @code{filename} must be -writable. There may be only one switch @code{-c}. -When a switch @code{-c} is -specified, no switch @code{-P} may be specified (see below). -@end table - -@geindex -d (gnatname) - - -@table @asis - -@item @code{-d`dir'} - -Look for source files in directory @code{dir}. There may be zero, one or more -spaces between @code{-d} and @code{dir}. -@code{dir} may end with @code{/**}, that is it may be of the form -@code{root_dir/**}. In this case, the directory @code{root_dir} and all of its -subdirectories, recursively, have to be searched for sources. -When a switch @code{-d} -is specified, the current working directory will not be searched for source -files, unless it is explicitly specified with a @code{-d} -or @code{-D} switch. -Several switches @code{-d} may be specified. -If @code{dir} is a relative path, it is relative to the directory of -the configuration pragmas file specified with switch -@code{-c}, -or to the directory of the project file specified with switch -@code{-P} or, -if neither switch @code{-c} -nor switch @code{-P} are specified, it is relative to the -current working directory. The directory -specified with switch @code{-d} must exist and be readable. -@end table - -@geindex -D (gnatname) - - -@table @asis - -@item @code{-D`filename'} - -Look for source files in all directories listed in text file @code{filename}. -There may be zero, one or more spaces between @code{-D} -and @code{filename}. -@code{filename} must be an existing, readable text file. -Each nonempty line in @code{filename} must be a directory. -Specifying switch @code{-D} is equivalent to specifying as many -switches @code{-d} as there are nonempty lines in -@code{file}. - -@item @code{-eL} - -Follow symbolic links when processing project files. - -@geindex -f (gnatname) - -@item @code{-f`pattern'} - -Foreign patterns. Using this switch, it is possible to add sources of languages -other than Ada to the list of sources of a project file. -It is only useful if a -P switch is used. -For example, - -@example -gnatname -Pprj -f"*.c" "*.ada" -@end example - -will look for Ada units in all files with the @code{.ada} extension, -and will add to the list of file for project @code{prj.gpr} the C files -with extension @code{.c}. - -@geindex -h (gnatname) - -@item @code{-h} - -Output usage (help) information. The output is written to @code{stdout}. - -@geindex -P (gnatname) - -@item @code{-P`proj'} - -Create or update project file @code{proj}. There may be zero, one or more space -between @code{-P} and @code{proj}. @code{proj} may include directory -information. @code{proj} must be writable. -There may be only one switch @code{-P}. -When a switch @code{-P} is specified, -no switch @code{-c} may be specified. -On all platforms, except on VMS, when @code{gnatname} is invoked for an -existing project file .gpr, a backup copy of the project file is created -in the project directory with file name .gpr.saved_x. ‘x’ is the first -non negative number that makes this backup copy a new file. - -@geindex -v (gnatname) - -@item @code{-v} - -Verbose mode. Output detailed explanation of behavior to @code{stdout}. -This includes name of the file written, the name of the directories to search -and, for each file in those directories whose name matches at least one of -the Naming Patterns, an indication of whether the file contains a unit, -and if so the name of the unit. -@end table - -@geindex -v -v (gnatname) - - -@table @asis - -@item @code{-v -v} - -Very Verbose mode. In addition to the output produced in verbose mode, -for each file in the searched directories whose name matches none of -the Naming Patterns, an indication is given that there is no match. - -@geindex -x (gnatname) - -@item @code{-x`pattern'} - -Excluded patterns. Using this switch, it is possible to exclude some files -that would match the name patterns. For example, - -@example -gnatname -x "*_nt.ada" "*.ada" -@end example - -will look for Ada units in all files with the @code{.ada} extension, -except those whose names end with @code{_nt.ada}. -@end table - -@node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname -@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{4a}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{4b} -@subsubsection Examples of @code{gnatname} Usage - - -@example -$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" -@end example - -In this example, the directory @code{/home/me} must already exist -and be writable. In addition, the directory -@code{/home/me/sources} (specified by -@code{-d sources}) must exist and be readable. - -Note the optional spaces after @code{-c} and @code{-d}. - -@example -$ gnatname -P/home/me/proj -x "*_nt_body.ada" --dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" -@end example - -Note that several switches @code{-d} may be used, -even in conjunction with one or several switches -@code{-D}. Several Naming Patterns and one excluded pattern -are used in this example. - -@node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{4c}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{4d} -@subsection File Name Krunching with @code{gnatkr} - - -@geindex gnatkr - -This section discusses the method used by the compiler to shorten -the default file names chosen for Ada units so that they do not -exceed the maximum length permitted. It also describes the -@code{gnatkr} utility that can be used to determine the result of -applying this shortening. - -@menu -* About gnatkr:: -* Using gnatkr:: -* Krunching Method:: -* Examples of gnatkr Usage:: - -@end menu - -@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr -@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{4e}@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{4f} -@subsubsection About @code{gnatkr} - - -The default file naming rule in GNAT -is that the file name must be derived from -the unit name. The exact default rule is as follows: - - -@itemize * - -@item -Take the unit name and replace all dots by hyphens. - -@item -If such a replacement occurs in the -second character position of a name, and the first character is -@code{a}, @code{g}, @code{s}, or @code{i}, -then replace the dot by the character -@code{~} (tilde) -instead of a minus. - -The reason for this exception is to avoid clashes -with the standard names for children of System, Ada, Interfaces, -and GNAT, which use the prefixes -@code{s-}, @code{a-}, @code{i-}, and @code{g-}, -respectively. -@end itemize - -The @code{-gnatk`nn'} -switch of the compiler activates a ‘krunching’ -circuit that limits file names to nn characters (where nn is a decimal -integer). - -The @code{gnatkr} utility can be used to determine the krunched name for -a given file, when krunched to a specified maximum length. - -@node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr -@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{50}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{3d} -@subsubsection Using @code{gnatkr} - - -The @code{gnatkr} command has the form: - -@example -$ gnatkr name [ length ] -@end example - -@code{name} is the uncrunched file name, derived from the name of the unit -in the standard manner described in the previous section (i.e., in particular -all dots are replaced by hyphens). The file name may or may not have an -extension (defined as a suffix of the form period followed by arbitrary -characters other than period). If an extension is present then it will -be preserved in the output. For example, when krunching @code{hellofile.ads} -to eight characters, the result will be hellofil.ads. - -Note: for compatibility with previous versions of @code{gnatkr} dots may -appear in the name instead of hyphens, but the last dot will always be -taken as the start of an extension. So if @code{gnatkr} is given an argument -such as @code{Hello.World.adb} it will be treated exactly as if the first -period had been a hyphen, and for example krunching to eight characters -gives the result @code{hellworl.adb}. - -Note that the result is always all lower case. -Characters of the other case are folded as required. - -@code{length} represents the length of the krunched name. The default -when no argument is given is 8 characters. A length of zero stands for -unlimited, in other words do not chop except for system files where the -implied crunching length is always eight characters. - -The output is the krunched name. The output has an extension only if the -original argument was a file name with an extension. - -@node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr -@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52} -@subsubsection Krunching Method - - -The initial file name is determined by the name of the unit that the file -contains. The name is formed by taking the full expanded name of the -unit and replacing the separating dots with hyphens and -using lowercase -for all letters, except that a hyphen in the second character position is -replaced by a tilde if the first character is -@code{a}, @code{i}, @code{g}, or @code{s}. -The extension is @code{.ads} for a -spec and @code{.adb} for a body. -Krunching does not affect the extension, but the file name is shortened to -the specified length by following these rules: - - -@itemize * - -@item -The name is divided into segments separated by hyphens, tildes or -underscores and all hyphens, tildes, and underscores are -eliminated. If this leaves the name short enough, we are done. - -@item -If the name is too long, the longest segment is located (left-most -if there are two of equal length), and shortened by dropping -its last character. This is repeated until the name is short enough. - -As an example, consider the krunching of @code{our-strings-wide_fixed.adb} -to fit the name into 8 characters as required by some operating systems: - -@example -our-strings-wide_fixed 22 -our strings wide fixed 19 -our string wide fixed 18 -our strin wide fixed 17 -our stri wide fixed 16 -our stri wide fixe 15 -our str wide fixe 14 -our str wid fixe 13 -our str wid fix 12 -ou str wid fix 11 -ou st wid fix 10 -ou st wi fix 9 -ou st wi fi 8 -Final file name: oustwifi.adb -@end example - -@item -The file names for all predefined units are always krunched to eight -characters. The krunching of these predefined units uses the following -special prefix replacements: - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} -@item - -Prefix - -@tab - -Replacement - -@item - -@code{ada-} - -@tab - -@code{a-} - -@item - -@code{gnat-} - -@tab - -@code{g-} - -@item - -@code{interfac es-} - -@tab - -@code{i-} - -@item - -@code{system-} - -@tab - -@code{s-} - -@end multitable - - -These system files have a hyphen in the second character position. That -is why normal user files replace such a character with a -tilde, to avoid confusion with system file names. - -As an example of this special rule, consider -@code{ada-strings-wide_fixed.adb}, which gets krunched as follows: - -@example -ada-strings-wide_fixed 22 -a- strings wide fixed 18 -a- string wide fixed 17 -a- strin wide fixed 16 -a- stri wide fixed 15 -a- stri wide fixe 14 -a- str wide fixe 13 -a- str wid fixe 12 -a- str wid fix 11 -a- st wid fix 10 -a- st wi fix 9 -a- st wi fi 8 -Final file name: a-stwifi.adb -@end example -@end itemize - -Of course no file shortening algorithm can guarantee uniqueness over all -possible unit names, and if file name krunching is used then it is your -responsibility to ensure that no name clashes occur. The utility -program @code{gnatkr} is supplied for conveniently determining the -krunched name of a file. - -@node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr -@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{54} -@subsubsection Examples of @code{gnatkr} Usage - - -@example -$ gnatkr very_long_unit_name.ads --> velounna.ads -$ gnatkr grandparent-parent-child.ads --> grparchi.ads -$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads -$ gnatkr grandparent-parent-child --> grparchi -$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads -$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads -@end example - -@node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities -@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{55}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{1d} -@subsection Renaming Files with @code{gnatchop} - - -@geindex gnatchop - -This section discusses how to handle files with multiple units by using -the @code{gnatchop} utility. This utility is also useful in renaming -files to meet the standard GNAT default file naming conventions. - -@menu -* Handling Files with Multiple Units:: -* Operating gnatchop in Compilation Mode:: -* Command Line for gnatchop:: -* Switches for gnatchop:: -* Examples of gnatchop Usage:: - -@end menu - -@node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop -@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{56}@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{57} -@subsubsection Handling Files with Multiple Units - - -The basic compilation model of GNAT requires that a file submitted to the -compiler have only one unit and there be a strict correspondence -between the file name and the unit name. - -If you want to keep your files with multiple units, -perhaps to maintain compatibility with some other Ada compilation system, -you can use @code{gnatname} to generate or update your project files. -Generated or modified project files can be processed by GNAT. - -See @ref{42,,Handling Arbitrary File Naming Conventions with gnatname} -for more details on how to use @cite{gnatname}. - -Alternatively, if you want to permanently restructure a set of ‘foreign’ -files so that they match the GNAT rules, and do the remaining development -using the GNAT structure, you can simply use @code{gnatchop} once, generate the -new set of files and work with them from that point on. - -Note that if your file containing multiple units starts with a byte order -mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop -will each start with a copy of this BOM, meaning that they can be compiled -automatically in UTF-8 mode without needing to specify an explicit encoding. - -@node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop -@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{58}@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{59} -@subsubsection Operating gnatchop in Compilation Mode - - -The basic function of @code{gnatchop} is to take a file with multiple units -and split it into separate files. The boundary between files is reasonably -clear, except for the issue of comments and pragmas. In default mode, the -rule is that any pragmas between units belong to the previous unit, except -that configuration pragmas always belong to the following unit. Any comments -belong to the following unit. These rules -almost always result in the right choice of -the split point without needing to mark it explicitly and most users will -find this default to be what they want. In this default mode it is incorrect to -submit a file containing only configuration pragmas, or one that ends in -configuration pragmas, to @code{gnatchop}. - -However, using a special option to activate ‘compilation mode’, -@code{gnatchop} -can perform another function, which is to provide exactly the semantics -required by the RM for handling of configuration pragmas in a compilation. -In the absence of configuration pragmas (at the main file level), this -option has no effect, but it causes such configuration pragmas to be handled -in a quite different manner. - -First, in compilation mode, if @code{gnatchop} is given a file that consists of -only configuration pragmas, then this file is appended to the -@code{gnat.adc} file in the current directory. This behavior provides -the required behavior described in the RM for the actions to be taken -on submitting such a file to the compiler, namely that these pragmas -should apply to all subsequent compilations in the same compilation -environment. Using GNAT, the current directory, possibly containing a -@code{gnat.adc} file is the representation -of a compilation environment. For more information on the -@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}. - -Second, in compilation mode, if @code{gnatchop} -is given a file that starts with -configuration pragmas, and contains one or more units, then these -configuration pragmas are prepended to each of the chopped files. This -behavior provides the required behavior described in the RM for the -actions to be taken on compiling such a file, namely that the pragmas -apply to all units in the compilation, but not to subsequently compiled -units. - -Finally, if configuration pragmas appear between units, they are appended -to the previous unit. This results in the previous unit being illegal, -since the compiler does not accept configuration pragmas that follow -a unit. This provides the required RM behavior that forbids configuration -pragmas other than those preceding the first compilation unit of a -compilation. - -For most purposes, @code{gnatchop} will be used in default mode. The -compilation mode described above is used only if you need exactly -accurate behavior with respect to compilations, and you have files -that contain multiple units and configuration pragmas. In this -circumstance the use of @code{gnatchop} with the compilation mode -switch provides the required behavior, and is for example the mode -in which GNAT processes the ACVC tests. - -@node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop -@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{5a}@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{5b} -@subsubsection Command Line for @code{gnatchop} - - -The @code{gnatchop} command has the form: - -@example -$ gnatchop switches file_name [file_name ...] - [directory] -@end example - -The only required argument is the file name of the file to be chopped. -There are no restrictions on the form of this file name. The file itself -contains one or more Ada units, in normal GNAT format, concatenated -together. As shown, more than one file may be presented to be chopped. - -When run in default mode, @code{gnatchop} generates one output file in -the current directory for each unit in each of the files. - -@code{directory}, if specified, gives the name of the directory to which -the output files will be written. If it is not specified, all files are -written to the current directory. - -For example, given a -file called @code{hellofiles} containing - -@example -procedure Hello; - -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello is -begin - Put_Line ("Hello"); -end Hello; -@end example - -the command - -@example -$ gnatchop hellofiles -@end example - -generates two files in the current directory, one called -@code{hello.ads} containing the single line that is the procedure spec, -and the other called @code{hello.adb} containing the remaining text. The -original file is not affected. The generated files can be compiled in -the normal manner. - -When gnatchop is invoked on a file that is empty or that contains only empty -lines and/or comments, gnatchop will not fail, but will not produce any -new sources. - -For example, given a -file called @code{toto.txt} containing - -@example --- Just a comment -@end example - -the command - -@example -$ gnatchop toto.txt -@end example - -will not produce any new file and will result in the following warnings: - -@example -toto.txt:1:01: warning: empty file, contains no compilation units -no compilation units found -no source files written -@end example - -@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop -@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{5c}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{5d} -@subsubsection Switches for @code{gnatchop} - - -@code{gnatchop} recognizes the following switches: - -@geindex --version (gnatchop) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatchop) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. -@end table - -@geindex -c (gnatchop) - - -@table @asis - -@item @code{-c} - -Causes @code{gnatchop} to operate in compilation mode, in which -configuration pragmas are handled according to strict RM rules. See -previous section for a full description of this mode. - -@item @code{-gnat`xxx'} - -This passes the given @code{-gnat`xxx'} switch to @code{gnat} which is -used to parse the given file. Not all `xxx' options make sense, -but for example, the use of @code{-gnati2} allows @code{gnatchop} to -process a source file that uses Latin-2 coding for identifiers. - -@item @code{-h} - -Causes @code{gnatchop} to generate a brief help summary to the standard -output file showing usage information. -@end table - -@geindex -k (gnatchop) - - -@table @asis - -@item @code{-k`mm'} - -Limit generated file names to the specified number @code{mm} -of characters. -This is useful if the -resulting set of files is required to be interoperable with systems -which limit the length of file names. -No space is allowed between the @code{-k} and the numeric value. The numeric -value may be omitted in which case a default of @code{-k8}, -suitable for use -with DOS-like file systems, is used. If no @code{-k} switch -is present then -there is no limit on the length of file names. -@end table - -@geindex -p (gnatchop) - - -@table @asis - -@item @code{-p} - -Causes the file modification time stamp of the input file to be -preserved and used for the time stamp of the output file(s). This may be -useful for preserving coherency of time stamps in an environment where -@code{gnatchop} is used as part of a standard build process. -@end table - -@geindex -q (gnatchop) - - -@table @asis - -@item @code{-q} - -Causes output of informational messages indicating the set of generated -files to be suppressed. Warnings and error messages are unaffected. -@end table - -@geindex -r (gnatchop) - -@geindex Source_Reference pragmas - - -@table @asis - -@item @code{-r} - -Generate @code{Source_Reference} pragmas. Use this switch if the output -files are regarded as temporary and development is to be done in terms -of the original unchopped file. This switch causes -@code{Source_Reference} pragmas to be inserted into each of the -generated files to refers back to the original file name and line number. -The result is that all error messages refer back to the original -unchopped file. -In addition, the debugging information placed into the object file (when -the @code{-g} switch of @code{gcc} or @code{gnatmake} is -specified) -also refers back to this original file so that tools like profilers and -debuggers will give information in terms of the original unchopped file. - -If the original file to be chopped itself contains -a @code{Source_Reference} -pragma referencing a third file, then gnatchop respects -this pragma, and the generated @code{Source_Reference} pragmas -in the chopped file refer to the original file, with appropriate -line numbers. This is particularly useful when @code{gnatchop} -is used in conjunction with @code{gnatprep} to compile files that -contain preprocessing statements and multiple units. -@end table - -@geindex -v (gnatchop) - - -@table @asis - -@item @code{-v} - -Causes @code{gnatchop} to operate in verbose mode. The version -number and copyright notice are output, as well as exact copies of -the gnat1 commands spawned to obtain the chop control information. -@end table - -@geindex -w (gnatchop) - - -@table @asis - -@item @code{-w} - -Overwrite existing file names. Normally @code{gnatchop} regards it as a -fatal error if there is already a file with the same name as a -file it would otherwise output, in other words if the files to be -chopped contain duplicated units. This switch bypasses this -check, and causes all but the last instance of such duplicated -units to be skipped. -@end table - -@geindex --GCC= (gnatchop) - - -@table @asis - -@item @code{--GCC=`xxxx'} - -Specify the path of the GNAT parser to be used. When this switch is used, -no attempt is made to add the prefix to the GNAT parser executable. -@end table - -@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop -@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{5e}@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{5f} -@subsubsection Examples of @code{gnatchop} Usage - - -@example -$ gnatchop -w hello_s.ada prerelease/files -@end example - -Chops the source file @code{hello_s.ada}. The output files will be -placed in the directory @code{prerelease/files}, -overwriting any -files with matching names in that directory (no files in the current -directory are modified). - -@example -$ gnatchop archive -@end example - -Chops the source file @code{archive} -into the current directory. One -useful application of @code{gnatchop} is in sending sets of sources -around, for example in email messages. The required sources are simply -concatenated (for example, using a Unix @code{cat} -command), and then -@code{gnatchop} is used at the other end to reconstitute the original -file names. - -@example -$ gnatchop file1 file2 file3 direc -@end example - -Chops all units in files @code{file1}, @code{file2}, @code{file3}, placing -the resulting files in the directory @code{direc}. Note that if any units -occur more than once anywhere within this set of files, an error message -is generated, and no files are written. To override this check, use the -@code{-w} switch, -in which case the last occurrence in the last file will -be the one that is output, and earlier duplicate occurrences for a given -unit will be skipped. - -@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25}@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60} -@section Configuration Pragmas - - -@geindex Configuration pragmas - -@geindex Pragmas -@geindex configuration - -Configuration pragmas include those pragmas described as -such in the Ada Reference Manual, as well as -implementation-dependent pragmas that are configuration pragmas. -See the @code{Implementation_Defined_Pragmas} chapter in the -@cite{GNAT_Reference_Manual} for details on these -additional GNAT-specific configuration pragmas. -Most notably, the pragma @code{Source_File_Name}, which allows -specifying non-default names for source files, is a configuration -pragma. The following is a complete list of configuration pragmas -recognized by GNAT: - -@example -Ada_83 -Ada_95 -Ada_05 -Ada_2005 -Ada_12 -Ada_2012 -Ada_2022 -Aggregate_Individually_Assign -Allow_Integer_Address -Annotate -Assertion_Policy -Assume_No_Invalid_Values -C_Pass_By_Copy -Check_Float_Overflow -Check_Name -Check_Policy -Component_Alignment -Convention_Identifier -Debug_Policy -Default_Scalar_Storage_Order -Default_Storage_Pool -Detect_Blocking -Disable_Atomic_Synchronization -Discard_Names -Elaboration_Checks -Eliminate -Enable_Atomic_Synchronization -Extend_System -Extensions_Allowed -External_Name_Casing -Fast_Math -Favor_Top_Level -Ignore_Pragma -Implicit_Packing -Initialize_Scalars -Interrupt_State -License -Locking_Policy -No_Component_Reordering -No_Heap_Finalization -No_Strict_Aliasing -Normalize_Scalars -Optimize_Alignment -Overflow_Mode -Overriding_Renamings -Partition_Elaboration_Policy -Persistent_BSS -Prefix_Exception_Messages -Priority_Specific_Dispatching -Profile -Profile_Warnings -Queuing_Policy -Rename_Pragma -Restrictions -Restriction_Warnings -Reviewable -Short_Circuit_And_Or -Source_File_Name -Source_File_Name_Project -SPARK_Mode -Style_Checks -Suppress -Suppress_Exception_Locations -Task_Dispatching_Policy -Unevaluated_Use_Of_Old -Unsuppress -Use_VADS_Size -Validity_Checks -Warning_As_Error -Warnings -Wide_Character_Encoding -@end example - -@menu -* Handling of Configuration Pragmas:: -* The Configuration Pragmas Files:: - -@end menu - -@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas -@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{3f}@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{61} -@subsection Handling of Configuration Pragmas - - -Configuration pragmas may either appear at the start of a compilation -unit, or they can appear in a configuration pragma file to apply to -all compilations performed in a given compilation environment. - -GNAT also provides the @code{gnatchop} utility to provide an automatic -way to handle configuration pragmas following the semantics for -compilations (that is, files with multiple units), described in the RM. -See @ref{59,,Operating gnatchop in Compilation Mode} for details. -However, for most purposes, it will be more convenient to edit the -@code{gnat.adc} file that contains configuration pragmas directly, -as described in the following section. - -In the case of @code{Restrictions} pragmas appearing as configuration -pragmas in individual compilation units, the exact handling depends on -the type of restriction. - -Restrictions that require partition-wide consistency (like -@code{No_Tasking}) are -recognized wherever they appear -and can be freely inherited, e.g. from a `with'ed unit to the `with'ing -unit. This makes sense since the binder will in any case insist on seeing -consistent use, so any unit not conforming to any restrictions that are -anywhere in the partition will be rejected, and you might as well find -that out at compile time rather than at bind time. - -For restrictions that do not require partition-wide consistency, e.g. -SPARK or No_Implementation_Attributes, in general the restriction applies -only to the unit in which the pragma appears, and not to any other units. - -The exception is No_Elaboration_Code which always applies to the entire -object file from a compilation, i.e. to the body, spec, and all subunits. -This restriction can be specified in a configuration pragma file, or it -can be on the body and/or the spec (in either case it applies to all the -relevant units). It can appear on a subunit only if it has previously -appeared in the body of spec. - -@node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas -@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{62}@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{63} -@subsection The Configuration Pragmas Files - - -@geindex gnat.adc - -In GNAT a compilation environment is defined by the current -directory at the time that a compile command is given. This current -directory is searched for a file whose name is @code{gnat.adc}. If -this file is present, it is expected to contain one or more -configuration pragmas that will be applied to the current compilation. -However, if the switch @code{-gnatA} is used, @code{gnat.adc} is not -considered. When taken into account, @code{gnat.adc} is added to the -dependencies, so that if @code{gnat.adc} is modified later, an invocation of -@code{gnatmake} will recompile the source. - -Configuration pragmas may be entered into the @code{gnat.adc} file -either by running @code{gnatchop} on a source file that consists only of -configuration pragmas, or more conveniently by direct editing of the -@code{gnat.adc} file, which is a standard format source file. - -Besides @code{gnat.adc}, additional files containing configuration -pragmas may be applied to the current compilation using the switch -@code{-gnatec=`path'} where @code{path} must designate an existing file that -contains only configuration pragmas. These configuration pragmas are -in addition to those found in @code{gnat.adc} (provided @code{gnat.adc} -is present and switch @code{-gnatA} is not used). - -It is allowable to specify several switches @code{-gnatec=}, all of which -will be taken into account. - -Files containing configuration pragmas specified with switches -@code{-gnatec=} are added to the dependencies, unless they are -temporary files. A file is considered temporary if its name ends in -@code{.tmp} or @code{.TMP}. Certain tools follow this naming -convention because they pass information to @code{gcc} via -temporary files that are immediately deleted; it doesn’t make sense to -depend on a file that no longer exists. Such tools include -@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}. - -By default, configuration pragma files are stored by their absolute paths in -ALI files. You can use the @code{-gnateb} switch in order to store them by -their basename instead. - -If you are using project file, a separate mechanism is provided using -project attributes. - -@c --Comment -@c See :ref:`Specifying_Configuration_Pragmas` for more details. - -@node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{26}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{64} -@section Generating Object Files - - -An Ada program consists of a set of source files, and the first step in -compiling the program is to generate the corresponding object files. -These are generated by compiling a subset of these source files. -The files you need to compile are the following: - - -@itemize * - -@item -If a package spec has no body, compile the package spec to produce the -object file for the package. - -@item -If a package has both a spec and a body, compile the body to produce the -object file for the package. The source file for the package spec need -not be compiled in this case because there is only one object file, which -contains the code for both the spec and body of the package. - -@item -For a subprogram, compile the subprogram body to produce the object file -for the subprogram. The spec, if one is present, is as usual in a -separate file, and need not be compiled. -@end itemize - -@geindex Subunits - - -@itemize * - -@item -In the case of subunits, only compile the parent unit. A single object -file is generated for the entire subunit tree, which includes all the -subunits. - -@item -Compile child units independently of their parent units -(though, of course, the spec of all the ancestor unit must be present in order -to compile a child unit). - -@geindex Generics - -@item -Compile generic units in the same manner as any other units. The object -files in this case are small dummy files that contain at most the -flag used for elaboration checking. This is because GNAT always handles generic -instantiation by means of macro expansion. However, it is still necessary to -compile generic units, for dependency checking and elaboration purposes. -@end itemize - -The preceding rules describe the set of files that must be compiled to -generate the object files for a program. Each object file has the same -name as the corresponding source file, except that the extension is -@code{.o} as usual. - -You may wish to compile other files for the purpose of checking their -syntactic and semantic correctness. For example, in the case where a -package has a separate spec and body, you would not normally compile the -spec. However, it is convenient in practice to compile the spec to make -sure it is error-free before compiling clients of this spec, because such -compilations will fail if there is an error in the spec. - -GNAT provides an option for compiling such files purely for the -purposes of checking correctness; such compilations are not required as -part of the process of building a program. To compile a file in this -checking mode, use the @code{-gnatc} switch. - -@node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27} -@section Source Dependencies - - -A given object file clearly depends on the source file which is compiled -to produce it. Here we are using “depends” in the sense of a typical -@code{make} utility; in other words, an object file depends on a source -file if changes to the source file require the object file to be -recompiled. -In addition to this basic dependency, a given object may depend on -additional source files as follows: - - -@itemize * - -@item -If a file being compiled `with's a unit @code{X}, the object file -depends on the file containing the spec of unit @code{X}. This includes -files that are `with'ed implicitly either because they are parents -of `with'ed child units or they are run-time units required by the -language constructs used in a particular unit. - -@item -If a file being compiled instantiates a library level generic unit, the -object file depends on both the spec and body files for this generic -unit. - -@item -If a file being compiled instantiates a generic unit defined within a -package, the object file depends on the body file for the package as -well as the spec file. -@end itemize - -@geindex Inline - -@geindex -gnatn switch - - -@itemize * - -@item -If a file being compiled contains a call to a subprogram for which -pragma @code{Inline} applies and inlining is activated with the -@code{-gnatn} switch, the object file depends on the file containing the -body of this subprogram as well as on the file containing the spec. Note -that for inlining to actually occur as a result of the use of this switch, -it is necessary to compile in optimizing mode. - -@geindex -gnatN switch - -The use of @code{-gnatN} activates inlining optimization -that is performed by the front end of the compiler. This inlining does -not require that the code generation be optimized. Like @code{-gnatn}, -the use of this switch generates additional dependencies. - -When using a gcc-based back end, then the use of -@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. -Historically front end inlining was more extensive than the gcc back end -inlining, but that is no longer the case. - -@item -If an object file @code{O} depends on the proper body of a subunit through -inlining or instantiation, it depends on the parent unit of the subunit. -This means that any modification of the parent unit or one of its subunits -affects the compilation of @code{O}. - -@item -The object file for a parent unit depends on all its subunit body files. - -@item -The previous two rules meant that for purposes of computing dependencies and -recompilation, a body and all its subunits are treated as an indivisible whole. - -These rules are applied transitively: if unit @code{A} `with's -unit @code{B}, whose elaboration calls an inlined procedure in package -@code{C}, the object file for unit @code{A} will depend on the body of -@code{C}, in file @code{c.adb}. - -The set of dependent files described by these rules includes all the -files on which the unit is semantically dependent, as dictated by the -Ada language standard. However, it is a superset of what the -standard describes, because it includes generic, inline, and subunit -dependencies. - -An object file must be recreated by recompiling the corresponding source -file if any of the source files on which it depends are modified. For -example, if the @code{make} utility is used to control compilation, -the rule for an Ada object file must mention all the source files on -which the object file depends, according to the above definition. -The determination of the necessary -recompilations is done automatically when one uses @code{gnatmake}. -@end itemize - -@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{66}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{28} -@section The Ada Library Information Files - - -@geindex Ada Library Information files - -@geindex ALI files - -Each compilation actually generates two output files. The first of these -is the normal object file that has a @code{.o} extension. The second is a -text file containing full dependency information. It has the same -name as the source file, but an @code{.ali} extension. -This file is known as the Ada Library Information (@code{ALI}) file. -The following information is contained in the @code{ALI} file. - - -@itemize * - -@item -Version information (indicates which version of GNAT was used to compile -the unit(s) in question) - -@item -Main program information (including priority and time slice settings, -as well as the wide character encoding used during compilation). - -@item -List of arguments used in the @code{gcc} command for the compilation - -@item -Attributes of the unit, including configuration pragmas used, an indication -of whether the compilation was successful, exception model used etc. - -@item -A list of relevant restrictions applying to the unit (used for consistency) -checking. - -@item -Categorization information (e.g., use of pragma @code{Pure}). - -@item -Information on all `with'ed units, including presence of -@code{Elaborate} or @code{Elaborate_All} pragmas. - -@item -Information from any @code{Linker_Options} pragmas used in the unit - -@item -Information on the use of @code{Body_Version} or @code{Version} -attributes in the unit. - -@item -Dependency information. This is a list of files, together with -time stamp and checksum information. These are files on which -the unit depends in the sense that recompilation is required -if any of these units are modified. - -@item -Cross-reference data. Contains information on all entities referenced -in the unit. Used by some tools to provide cross-reference information. -@end itemize - -For a full detailed description of the format of the @code{ALI} file, -see the source of the body of unit @code{Lib.Writ}, contained in file -@code{lib-writ.adb} in the GNAT compiler sources. - -@node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{29}@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{67} -@section Binding an Ada Program - - -When using languages such as C and C++, once the source files have been -compiled the only remaining step in building an executable program -is linking the object modules together. This means that it is possible to -link an inconsistent version of a program, in which two units have -included different versions of the same header. - -The rules of Ada do not permit such an inconsistent program to be built. -For example, if two clients have different versions of the same package, -it is illegal to build a program containing these two clients. -These rules are enforced by the GNAT binder, which also determines an -elaboration order consistent with the Ada rules. - -The GNAT binder is run after all the object files for a program have -been created. It is given the name of the main program unit, and from -this it determines the set of units required by the program, by reading the -corresponding ALI files. It generates error messages if the program is -inconsistent or if no valid order of elaboration exists. - -If no errors are detected, the binder produces a main program, in Ada by -default, that contains calls to the elaboration procedures of those -compilation unit that require them, followed by -a call to the main program. This Ada program is compiled to generate the -object file for the main program. The name of -the Ada file is @code{b~xxx}.adb` (with the corresponding spec -@code{b~xxx}.ads`) where @code{xxx} is the name of the -main program unit. - -Finally, the linker is used to build the resulting executable program, -using the object from the main program from the bind step as well as the -object files for the Ada units of the program. - -@node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{2a}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{68} -@section GNAT and Libraries - - -@geindex Library building and using - -This section describes how to build and use libraries with GNAT, and also shows -how to recompile the GNAT run-time library. You should be familiar with the -Project Manager facility (see the `GNAT_Project_Manager' chapter of the -`GPRbuild User’s Guide') before reading this chapter. - -@menu -* Introduction to Libraries in GNAT:: -* General Ada Libraries:: -* Stand-alone Ada Libraries:: -* Rebuilding the GNAT Run-Time Library:: - -@end menu - -@node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{6a} -@subsection Introduction to Libraries in GNAT - - -A library is, conceptually, a collection of objects which does not have its -own main thread of execution, but rather provides certain services to the -applications that use it. A library can be either statically linked with the -application, in which case its code is directly included in the application, -or, on platforms that support it, be dynamically linked, in which case -its code is shared by all applications making use of this library. - -GNAT supports both types of libraries. -In the static case, the compiled code can be provided in different ways. The -simplest approach is to provide directly the set of objects resulting from -compilation of the library source files. Alternatively, you can group the -objects into an archive using whatever commands are provided by the operating -system. For the latter case, the objects are grouped into a shared library. - -In the GNAT environment, a library has three types of components: - - -@itemize * - -@item -Source files, - -@item -@code{ALI} files (see @ref{28,,The Ada Library Information Files}), and - -@item -Object files, an archive or a shared library. -@end itemize - -A GNAT library may expose all its source files, which is useful for -documentation purposes. Alternatively, it may expose only the units needed by -an external user to make use of the library. That is to say, the specs -reflecting the library services along with all the units needed to compile -those specs, which can include generic bodies or any body implementing an -inlined routine. In the case of `stand-alone libraries' those exposed -units are called `interface units' (@ref{6b,,Stand-alone Ada Libraries}). - -All compilation units comprising an application, including those in a library, -need to be elaborated in an order partially defined by Ada’s semantics. GNAT -computes the elaboration order from the @code{ALI} files and this is why they -constitute a mandatory part of GNAT libraries. -`Stand-alone libraries' are the exception to this rule because a specific -library elaboration routine is produced independently of the application(s) -using the library. - -@node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries -@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{6d} -@subsection General Ada Libraries - - -@menu -* Building a library:: -* Installing a library:: -* Using a library:: - -@end menu - -@node Building a library,Installing a library,,General Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{6f} -@subsubsection Building a library - - -The easiest way to build a library is to use the Project Manager, -which supports a special type of project called a `Library Project' -(see the `Library Projects' section in the `GNAT Project Manager' -chapter of the `GPRbuild User’s Guide'). - -A project is considered a library project, when two project-level attributes -are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to -control different aspects of library configuration, additional optional -project-level attributes can be specified: - - -@itemize * - -@item - -@table @asis - -@item @code{Library_Kind} - -This attribute controls whether the library is to be static or dynamic -@end table - -@item - -@table @asis - -@item @code{Library_Version} - -This attribute specifies the library version; this value is used -during dynamic linking of shared libraries to determine if the currently -installed versions of the binaries are compatible. -@end table - -@item -@code{Library_Options} - -@item - -@table @asis - -@item @code{Library_GCC} - -These attributes specify additional low-level options to be used during -library generation, and redefine the actual application used to generate -library. -@end table -@end itemize - -The GNAT Project Manager takes full care of the library maintenance task, -including recompilation of the source files for which objects do not exist -or are not up to date, assembly of the library archive, and installation of -the library (i.e., copying associated source, object and @code{ALI} files -to the specified location). - -Here is a simple library project file: - -@example -project My_Lib is - for Source_Dirs use ("src1", "src2"); - for Object_Dir use "obj"; - for Library_Name use "mylib"; - for Library_Dir use "lib"; - for Library_Kind use "dynamic"; -end My_lib; -@end example - -and the compilation command to build and install the library: - -@example -$ gnatmake -Pmy_lib -@end example - -It is not entirely trivial to perform manually all the steps required to -produce a library. We recommend that you use the GNAT Project Manager -for this task. In special cases where this is not desired, the necessary -steps are discussed below. - -There are various possibilities for compiling the units that make up the -library: for example with a Makefile (@ref{70,,Using the GNU make Utility}) or -with a conventional script. For simple libraries, it is also possible to create -a dummy main program which depends upon all the packages that comprise the -interface of the library. This dummy main program can then be given to -@code{gnatmake}, which will ensure that all necessary objects are built. - -After this task is accomplished, you should follow the standard procedure -of the underlying operating system to produce the static or shared library. - -Here is an example of such a dummy program: - -@example -with My_Lib.Service1; -with My_Lib.Service2; -with My_Lib.Service3; -procedure My_Lib_Dummy is -begin - null; -end; -@end example - -Here are the generic commands that will build an archive or a shared library. - -@example -# compiling the library -$ gnatmake -c my_lib_dummy.adb - -# we don't need the dummy object itself -$ rm my_lib_dummy.o my_lib_dummy.ali - -# create an archive with the remaining objects -$ ar rc libmy_lib.a *.o -# some systems may require "ranlib" to be run as well - -# or create a shared library -$ gcc -shared -o libmy_lib.so *.o -# some systems may require the code to have been compiled with -fPIC - -# remove the object files that are now in the library -$ rm *.o - -# Make the ALI files read-only so that gnatmake will not try to -# regenerate the objects that are in the library -$ chmod -w *.ali -@end example - -Please note that the library must have a name of the form @code{lib`xxx'.a} -or @code{lib`xxx'.so} (or @code{lib`xxx'.dll} on Windows) in order to -be accessed by the directive @code{-l`xxx'} at link time. - -@node Installing a library,Using a library,Building a library,General Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{72} -@subsubsection Installing a library - - -@geindex ADA_PROJECT_PATH - -@geindex GPR_PROJECT_PATH - -If you use project files, library installation is part of the library build -process (see the `Installing a Library with Project Files' section of the -`GNAT Project Manager' chapter of the `GPRbuild User’s Guide'). - -When project files are not an option, it is also possible, but not recommended, -to install the library so that the sources needed to use the library are on the -Ada source path and the ALI files & libraries be on the Ada Object path (see -@ref{73,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system -administrator can place general-purpose libraries in the default compiler -paths, by specifying the libraries’ location in the configuration files -@code{ada_source_path} and @code{ada_object_path}. These configuration files -must be located in the GNAT installation tree at the same place as the gcc spec -file. The location of the gcc spec file can be determined as follows: - -@example -$ gcc -v -@end example - -The configuration files mentioned above have a simple format: each line -must contain one unique directory name. -Those names are added to the corresponding path -in their order of appearance in the file. The names can be either absolute -or relative; in the latter case, they are relative to where theses files -are located. - -The files @code{ada_source_path} and @code{ada_object_path} might not be -present in a -GNAT installation, in which case, GNAT will look for its run-time library in -the directories @code{adainclude} (for the sources) and @code{adalib} (for the -objects and @code{ALI} files). When the files exist, the compiler does not -look in @code{adainclude} and @code{adalib}, and thus the -@code{ada_source_path} file -must contain the location for the GNAT run-time sources (which can simply -be @code{adainclude}). In the same way, the @code{ada_object_path} file must -contain the location for the GNAT run-time objects (which can simply -be @code{adalib}). - -You can also specify a new default path to the run-time library at compilation -time with the switch @code{--RTS=rts-path}. You can thus choose / change -the run-time library you want your program to be compiled with. This switch is -recognized by @code{gcc}, @code{gnatmake}, @code{gnatbind}, @code{gnatls}, and all -project aware tools. - -It is possible to install a library before or after the standard GNAT -library, by reordering the lines in the configuration files. In general, a -library must be installed before the GNAT library if it redefines -any part of it. - -@node Using a library,,Installing a library,General Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{74}@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{75} -@subsubsection Using a library - - -Once again, the project facility greatly simplifies the use of -libraries. In this context, using a library is just a matter of adding a -`with' clause in the user project. For instance, to make use of the -library @code{My_Lib} shown in examples in earlier sections, you can -write: - -@example -with "my_lib"; -project My_Proj is - ... -end My_Proj; -@end example - -Even if you have a third-party, non-Ada library, you can still use GNAT’s -Project Manager facility to provide a wrapper for it. For example, the -following project, when `with'ed by your main project, will link with the -third-party library @code{liba.a}: - -@example -project Liba is - for Externally_Built use "true"; - for Source_Files use (); - for Library_Dir use "lib"; - for Library_Name use "a"; - for Library_Kind use "static"; -end Liba; -@end example - -This is an alternative to the use of @code{pragma Linker_Options}. It is -especially interesting in the context of systems with several interdependent -static libraries where finding a proper linker order is not easy and best be -left to the tools having visibility over project dependence information. - -In order to use an Ada library manually, you need to make sure that this -library is on both your source and object path -(see @ref{73,,Search Paths and the Run-Time Library (RTL)} -and @ref{76,,Search Paths for gnatbind}). Furthermore, when the objects are grouped -in an archive or a shared library, you need to specify the desired -library at link time. - -For example, you can use the library @code{mylib} installed in -@code{/dir/my_lib_src} and @code{/dir/my_lib_obj} with the following commands: - -@example -$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\ - -largs -lmy_lib -@end example - -This can be expressed more simply: - -@example -$ gnatmake my_appl -@end example - -when the following conditions are met: - - -@itemize * - -@item -@code{/dir/my_lib_src} has been added by the user to the environment -variable -@geindex ADA_INCLUDE_PATH -@geindex environment variable; ADA_INCLUDE_PATH -@code{ADA_INCLUDE_PATH}, or by the administrator to the file -@code{ada_source_path} - -@item -@code{/dir/my_lib_obj} has been added by the user to the environment -variable -@geindex ADA_OBJECTS_PATH -@geindex environment variable; ADA_OBJECTS_PATH -@code{ADA_OBJECTS_PATH}, or by the administrator to the file -@code{ada_object_path} - -@item -a pragma @code{Linker_Options} has been added to one of the sources. -For example: - -@example -pragma Linker_Options ("-lmy_lib"); -@end example -@end itemize - -Note that you may also load a library dynamically at -run time given its filename, as illustrated in the GNAT @code{plugins} example -in the directory @code{share/examples/gnat/plugins} within the GNAT -install area. - -@node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{6b} -@subsection Stand-alone Ada Libraries - - -@geindex Stand-alone libraries - -@menu -* Introduction to Stand-alone Libraries:: -* Building a Stand-alone Library:: -* Creating a Stand-alone Library to be used in a non-Ada context:: -* Restrictions in Stand-alone Libraries:: - -@end menu - -@node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{79} -@subsubsection Introduction to Stand-alone Libraries - - -A Stand-alone Library (abbreviated ‘SAL’) is a library that contains the -necessary code to -elaborate the Ada units that are included in the library. In contrast with -an ordinary library, which consists of all sources, objects and @code{ALI} -files of the -library, a SAL may specify a restricted subset of compilation units -to serve as a library interface. In this case, the fully -self-sufficient set of files will normally consist of an objects -archive, the sources of interface units’ specs, and the @code{ALI} -files of interface units. -If an interface spec contains a generic unit or an inlined subprogram, -the body’s -source must also be provided; if the units that must be provided in the source -form depend on other units, the source and @code{ALI} files of those must -also be provided. - -The main purpose of a SAL is to minimize the recompilation overhead of client -applications when a new version of the library is installed. Specifically, -if the interface sources have not changed, client applications do not need to -be recompiled. If, furthermore, a SAL is provided in the shared form and its -version, controlled by @code{Library_Version} attribute, is not changed, -then the clients do not need to be relinked. - -SALs also allow the library providers to minimize the amount of library source -text exposed to the clients. Such ‘information hiding’ might be useful or -necessary for various reasons. - -Stand-alone libraries are also well suited to be used in an executable whose -main routine is not written in Ada. - -@node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{7b} -@subsubsection Building a Stand-alone Library - - -GNAT’s Project facility provides a simple way of building and installing -stand-alone libraries; see the `Stand-alone Library Projects' section -in the `GNAT Project Manager' chapter of the `GPRbuild User’s Guide'. -To be a Stand-alone Library Project, in addition to the two attributes -that make a project a Library Project (@code{Library_Name} and -@code{Library_Dir}; see the `Library Projects' section in the -`GNAT Project Manager' chapter of the `GPRbuild User’s Guide'), -the attribute @code{Library_Interface} must be defined. For example: - -@example -for Library_Dir use "lib_dir"; -for Library_Name use "dummy"; -for Library_Interface use ("int1", "int1.child"); -@end example - -Attribute @code{Library_Interface} has a non-empty string list value, -each string in the list designating a unit contained in an immediate source -of the project file. - -When a Stand-alone Library is built, first the binder is invoked to build -a package whose name depends on the library name -(@code{b~dummy.ads/b} in the example above). -This binder-generated package includes initialization and -finalization procedures whose -names depend on the library name (@code{dummyinit} and @code{dummyfinal} -in the example -above). The object corresponding to this package is included in the library. - -You must ensure timely (e.g., prior to any use of interfaces in the SAL) -calling of these procedures if a static SAL is built, or if a shared SAL -is built -with the project-level attribute @code{Library_Auto_Init} set to -@code{"false"}. - -For a Stand-Alone Library, only the @code{ALI} files of the Interface Units -(those that are listed in attribute @code{Library_Interface}) are copied to -the Library Directory. As a consequence, only the Interface Units may be -imported from Ada units outside of the library. If other units are imported, -the binding phase will fail. - -It is also possible to build an encapsulated library where not only -the code to elaborate and finalize the library is embedded but also -ensuring that the library is linked only against static -libraries. So an encapsulated library only depends on system -libraries, all other code, including the GNAT runtime, is embedded. To -build an encapsulated library the attribute -@code{Library_Standalone} must be set to @code{encapsulated}: - -@example -for Library_Dir use "lib_dir"; -for Library_Name use "dummy"; -for Library_Kind use "dynamic"; -for Library_Interface use ("int1", "int1.child"); -for Library_Standalone use "encapsulated"; -@end example - -The default value for this attribute is @code{standard} in which case -a stand-alone library is built. - -The attribute @code{Library_Src_Dir} may be specified for a -Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a -single string value. Its value must be the path (absolute or relative to the -project directory) of an existing directory. This directory cannot be the -object directory or one of the source directories, but it can be the same as -the library directory. The sources of the Interface -Units of the library that are needed by an Ada client of the library will be -copied to the designated directory, called the Interface Copy directory. -These sources include the specs of the Interface Units, but they may also -include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always} -are used, or when there is a generic unit in the spec. Before the sources -are copied to the Interface Copy directory, an attempt is made to delete all -files in the Interface Copy directory. - -Building stand-alone libraries by hand is somewhat tedious, but for those -occasions when it is necessary here are the steps that you need to perform: - - -@itemize * - -@item -Compile all library sources. - -@item -Invoke the binder with the switch @code{-n} (No Ada main program), -with all the @code{ALI} files of the interfaces, and -with the switch @code{-L} to give specific names to the @code{init} -and @code{final} procedures. For example: - -@example -$ gnatbind -n int1.ali int2.ali -Lsal1 -@end example - -@item -Compile the binder generated file: - -@example -$ gcc -c b~int2.adb -@end example - -@item -Link the dynamic library with all the necessary object files, -indicating to the linker the names of the @code{init} (and possibly -@code{final}) procedures for automatic initialization (and finalization). -The built library should be placed in a directory different from -the object directory. - -@item -Copy the @code{ALI} files of the interface to the library directory, -add in this copy an indication that it is an interface to a SAL -(i.e., add a word @code{SL} on the line in the @code{ALI} file that starts -with letter ‘P’) and make the modified copy of the @code{ALI} file -read-only. -@end itemize - -Using SALs is not different from using other libraries -(see @ref{75,,Using a library}). - -@node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{7d} -@subsubsection Creating a Stand-alone Library to be used in a non-Ada context - - -It is easy to adapt the SAL build procedure discussed above for use of a SAL in -a non-Ada context. - -The only extra step required is to ensure that library interface subprograms -are compatible with the main program, by means of @code{pragma Export} -or @code{pragma Convention}. - -Here is an example of simple library interface for use with C main program: - -@example -package My_Package is - - procedure Do_Something; - pragma Export (C, Do_Something, "do_something"); - - procedure Do_Something_Else; - pragma Export (C, Do_Something_Else, "do_something_else"); - -end My_Package; -@end example - -On the foreign language side, you must provide a ‘foreign’ view of the -library interface; remember that it should contain elaboration routines in -addition to interface subprograms. - -The example below shows the content of @code{mylib_interface.h} (note -that there is no rule for the naming of this file, any name can be used) - -@example -/* the library elaboration procedure */ -extern void mylibinit (void); - -/* the library finalization procedure */ -extern void mylibfinal (void); - -/* the interface exported by the library */ -extern void do_something (void); -extern void do_something_else (void); -@end example - -Libraries built as explained above can be used from any program, provided -that the elaboration procedures (named @code{mylibinit} in the previous -example) are called before the library services are used. Any number of -libraries can be used simultaneously, as long as the elaboration -procedure of each library is called. - -Below is an example of a C program that uses the @code{mylib} library. - -@example -#include "mylib_interface.h" - -int -main (void) -@{ - /* First, elaborate the library before using it */ - mylibinit (); - - /* Main program, using the library exported entities */ - do_something (); - do_something_else (); - - /* Library finalization at the end of the program */ - mylibfinal (); - return 0; -@} -@end example - -Note that invoking any library finalization procedure generated by -@code{gnatbind} shuts down the Ada run-time environment. -Consequently, the -finalization of all Ada libraries must be performed at the end of the program. -No call to these libraries or to the Ada run-time library should be made -after the finalization phase. - -Note also that special care must be taken with multi-tasks -applications. The initialization and finalization routines are not -protected against concurrent access. If such requirement is needed it -must be ensured at the application level using a specific operating -system services like a mutex or a critical-section. - -@node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{7f} -@subsubsection Restrictions in Stand-alone Libraries - - -The pragmas listed below should be used with caution inside libraries, -as they can create incompatibilities with other Ada libraries: - - -@itemize * - -@item -pragma @code{Locking_Policy} - -@item -pragma @code{Partition_Elaboration_Policy} - -@item -pragma @code{Queuing_Policy} - -@item -pragma @code{Task_Dispatching_Policy} - -@item -pragma @code{Unreserve_All_Interrupts} -@end itemize - -When using a library that contains such pragmas, the user must make sure -that all libraries use the same pragmas with the same values. Otherwise, -@code{Program_Error} will -be raised during the elaboration of the conflicting -libraries. The usage of these pragmas and its consequences for the user -should therefore be well documented. - -Similarly, the traceback in the exception occurrence mechanism should be -enabled or disabled in a consistent manner across all libraries. -Otherwise, Program_Error will be raised during the elaboration of the -conflicting libraries. - -If the @code{Version} or @code{Body_Version} -attributes are used inside a library, then you need to -perform a @code{gnatbind} step that specifies all @code{ALI} files in all -libraries, so that version identifiers can be properly computed. -In practice these attributes are rarely used, so this is unlikely -to be a consideration. - -@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries -@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{81} -@subsection Rebuilding the GNAT Run-Time Library - - -@geindex GNAT Run-Time Library -@geindex rebuilding - -@geindex Building the GNAT Run-Time Library - -@geindex Rebuilding the GNAT Run-Time Library - -@geindex Run-Time Library -@geindex rebuilding - -It may be useful to recompile the GNAT library in various debugging or -experimentation contexts. A project file called -@code{libada.gpr} is provided to that effect and can be found in -the directory containing the GNAT library. The location of this -directory depends on the way the GNAT environment has been installed and can -be determined by means of the command: - -@example -$ gnatls -v -@end example - -The last entry in the source search path usually contains the -gnat library (the @code{adainclude} directory). This project file contains its -own documentation and in particular the set of instructions needed to rebuild a -new library and to use it. - -Note that rebuilding the GNAT Run-Time is only recommended for temporary -experiments or debugging, and is not supported. - -@geindex Conditional compilation - -@node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{2b}@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{82} -@section Conditional Compilation - - -This section presents some guidelines for modeling conditional compilation in Ada and describes the -gnatprep preprocessor utility. - -@geindex Conditional compilation - -@menu -* Modeling Conditional Compilation in Ada:: -* Preprocessing with gnatprep:: -* Integrated Preprocessing:: - -@end menu - -@node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation -@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{84} -@subsection Modeling Conditional Compilation in Ada - - -It is often necessary to arrange for a single source program -to serve multiple purposes, where it is compiled in different -ways to achieve these different goals. Some examples of the -need for this feature are - - -@itemize * - -@item -Adapting a program to a different hardware environment - -@item -Adapting a program to a different target architecture - -@item -Turning debugging features on and off - -@item -Arranging for a program to compile with different compilers -@end itemize - -In C, or C++, the typical approach would be to use the preprocessor -that is defined as part of the language. The Ada language does not -contain such a feature. This is not an oversight, but rather a very -deliberate design decision, based on the experience that overuse of -the preprocessing features in C and C++ can result in programs that -are extremely difficult to maintain. For example, if we have ten -switches that can be on or off, this means that there are a thousand -separate programs, any one of which might not even be syntactically -correct, and even if syntactically correct, the resulting program -might not work correctly. Testing all combinations can quickly become -impossible. - -Nevertheless, the need to tailor programs certainly exists, and in -this section we will discuss how this can -be achieved using Ada in general, and GNAT in particular. - -@menu -* Use of Boolean Constants:: -* Debugging - A Special Case:: -* Conditionalizing Declarations:: -* Use of Alternative Implementations:: -* Preprocessing:: - -@end menu - -@node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada -@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{86} -@subsubsection Use of Boolean Constants - - -In the case where the difference is simply which code -sequence is executed, the cleanest solution is to use Boolean -constants to control which code is executed. - -@example -FP_Initialize_Required : constant Boolean := True; -... -if FP_Initialize_Required then -... -end if; -@end example - -Not only will the code inside the @code{if} statement not be executed if -the constant Boolean is @code{False}, but it will also be completely -deleted from the program. -However, the code is only deleted after the @code{if} statement -has been checked for syntactic and semantic correctness. -(In contrast, with preprocessors the code is deleted before the -compiler ever gets to see it, so it is not checked until the switch -is turned on.) - -@geindex Preprocessors (contrasted with conditional compilation) - -Typically the Boolean constants will be in a separate package, -something like: - -@example -package Config is - FP_Initialize_Required : constant Boolean := True; - Reset_Available : constant Boolean := False; - ... -end Config; -@end example - -The @code{Config} package exists in multiple forms for the various targets, -with an appropriate script selecting the version of @code{Config} needed. -Then any other unit requiring conditional compilation can do a `with' -of @code{Config} to make the constants visible. - -@node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada -@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{87}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{88} -@subsubsection Debugging - A Special Case - - -A common use of conditional code is to execute statements (for example -dynamic checks, or output of intermediate results) under control of a -debug switch, so that the debugging behavior can be turned on and off. -This can be done using a Boolean constant to control whether the code -is active: - -@example -if Debugging then - Put_Line ("got to the first stage!"); -end if; -@end example - -or - -@example -if Debugging and then Temperature > 999.0 then - raise Temperature_Crazy; -end if; -@end example - -@geindex pragma Assert - -Since this is a common case, there are special features to deal with -this in a convenient manner. For the case of tests, Ada 2005 has added -a pragma @code{Assert} that can be used for such tests. This pragma is modeled -on the @code{Assert} pragma that has always been available in GNAT, so this -feature may be used with GNAT even if you are not using Ada 2005 features. -The use of pragma @code{Assert} is described in the -@cite{GNAT_Reference_Manual}, but as an -example, the last test could be written: - -@example -pragma Assert (Temperature <= 999.0, "Temperature Crazy"); -@end example - -or simply - -@example -pragma Assert (Temperature <= 999.0); -@end example - -In both cases, if assertions are active and the temperature is excessive, -the exception @code{Assert_Failure} will be raised, with the given string in -the first case or a string indicating the location of the pragma in the second -case used as the exception message. - -@geindex pragma Assertion_Policy - -You can turn assertions on and off by using the @code{Assertion_Policy} -pragma. - -@geindex -gnata switch - -This is an Ada 2005 pragma which is implemented in all modes by -GNAT. Alternatively, you can use the @code{-gnata} switch -to enable assertions from the command line, which applies to -all versions of Ada. - -@geindex pragma Debug - -For the example above with the @code{Put_Line}, the GNAT-specific pragma -@code{Debug} can be used: - -@example -pragma Debug (Put_Line ("got to the first stage!")); -@end example - -If debug pragmas are enabled, the argument, which must be of the form of -a procedure call, is executed (in this case, @code{Put_Line} will be called). -Only one call can be present, but of course a special debugging procedure -containing any code you like can be included in the program and then -called in a pragma @code{Debug} argument as needed. - -One advantage of pragma @code{Debug} over the @code{if Debugging then} -construct is that pragma @code{Debug} can appear in declarative contexts, -such as at the very beginning of a procedure, before local declarations have -been elaborated. - -@geindex pragma Debug_Policy - -Debug pragmas are enabled using either the @code{-gnata} switch that also -controls assertions, or with a separate Debug_Policy pragma. - -The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used -in Ada 95 and Ada 83 programs as well), and is analogous to -pragma @code{Assertion_Policy} to control assertions. - -@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas, -and thus they can appear in @code{gnat.adc} if you are not using a -project file, or in the file designated to contain configuration pragmas -in a project file. -They then apply to all subsequent compilations. In practice the use of -the @code{-gnata} switch is often the most convenient method of controlling -the status of these pragmas. - -Note that a pragma is not a statement, so in contexts where a statement -sequence is required, you can’t just write a pragma on its own. You have -to add a @code{null} statement. - -@example -if ... then - ... -- some statements -else - pragma Assert (Num_Cases < 10); - null; -end if; -@end example - -@node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada -@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a} -@subsubsection Conditionalizing Declarations - - -In some cases it may be necessary to conditionalize declarations to meet -different requirements. For example we might want a bit string whose length -is set to meet some hardware message requirement. - -This may be possible using declare blocks controlled -by conditional constants: - -@example -if Small_Machine then - declare - X : Bit_String (1 .. 10); - begin - ... - end; -else - declare - X : Large_Bit_String (1 .. 1000); - begin - ... - end; -end if; -@end example - -Note that in this approach, both declarations are analyzed by the -compiler so this can only be used where both declarations are legal, -even though one of them will not be used. - -Another approach is to define integer constants, e.g., @code{Bits_Per_Word}, -or Boolean constants, e.g., @code{Little_Endian}, and then write declarations -that are parameterized by these constants. For example - -@example -for Rec use - Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; -end record; -@end example - -If @code{Bits_Per_Word} is set to 32, this generates either - -@example -for Rec use - Field1 at 0 range 0 .. 32; -end record; -@end example - -for the big endian case, or - -@example -for Rec use record - Field1 at 0 range 10 .. 32; -end record; -@end example - -for the little endian case. Since a powerful subset of Ada expression -notation is usable for creating static constants, clever use of this -feature can often solve quite difficult problems in conditionalizing -compilation (note incidentally that in Ada 95, the little endian -constant was introduced as @code{System.Default_Bit_Order}, so you do not -need to define this one yourself). - -@node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada -@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{8c} -@subsubsection Use of Alternative Implementations - - -In some cases, none of the approaches described above are adequate. This -can occur for example if the set of declarations required is radically -different for two different configurations. - -In this situation, the official Ada way of dealing with conditionalizing -such code is to write separate units for the different cases. As long as -this does not result in excessive duplication of code, this can be done -without creating maintenance problems. The approach is to share common -code as far as possible, and then isolate the code and declarations -that are different. Subunits are often a convenient method for breaking -out a piece of a unit that is to be conditionalized, with separate files -for different versions of the subunit for different targets, where the -build script selects the right one to give to the compiler. - -@geindex Subunits (and conditional compilation) - -As an example, consider a situation where a new feature in Ada 2005 -allows something to be done in a really nice way. But your code must be able -to compile with an Ada 95 compiler. Conceptually you want to say: - -@example -if Ada_2005 then - ... neat Ada 2005 code -else - ... not quite as neat Ada 95 code -end if; -@end example - -where @code{Ada_2005} is a Boolean constant. - -But this won’t work when @code{Ada_2005} is set to @code{False}, -since the @code{then} clause will be illegal for an Ada 95 compiler. -(Recall that although such unreachable code would eventually be deleted -by the compiler, it still needs to be legal. If it uses features -introduced in Ada 2005, it will be illegal in Ada 95.) - -So instead we write - -@example -procedure Insert is separate; -@end example - -Then we have two files for the subunit @code{Insert}, with the two sets of -code. -If the package containing this is called @code{File_Queries}, then we might -have two files - - -@itemize * - -@item -@code{file_queries-insert-2005.adb} - -@item -@code{file_queries-insert-95.adb} -@end itemize - -and the build script renames the appropriate file to @code{file_queries-insert.adb} and then carries out the compilation. - -This can also be done with project files’ naming schemes. For example: - -@example -for body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; -@end example - -Note also that with project files it is desirable to use a different extension -than @code{ads} / @code{adb} for alternative versions. Otherwise a naming -conflict may arise through another commonly used feature: to declare as part -of the project a set of directories containing all the sources obeying the -default naming scheme. - -The use of alternative units is certainly feasible in all situations, -and for example the Ada part of the GNAT run-time is conditionalized -based on the target architecture using this approach. As a specific example, -consider the implementation of the AST feature in VMS. There is one -spec: @code{s-asthan.ads} which is the same for all architectures, and three -bodies: - - -@itemize * - -@item - -@table @asis - -@item @code{s-asthan.adb} - -used for all non-VMS operating systems -@end table - -@item - -@table @asis - -@item @code{s-asthan-vms-alpha.adb} - -used for VMS on the Alpha -@end table - -@item - -@table @asis - -@item @code{s-asthan-vms-ia64.adb} - -used for VMS on the ia64 -@end table -@end itemize - -The dummy version @code{s-asthan.adb} simply raises exceptions noting that -this operating system feature is not available, and the two remaining -versions interface with the corresponding versions of VMS to provide -VMS-compatible AST handling. The GNAT build script knows the architecture -and operating system, and automatically selects the right version, -renaming it if necessary to @code{s-asthan.adb} before the run-time build. - -Another style for arranging alternative implementations is through Ada’s -access-to-subprogram facility. -In case some functionality is to be conditionally included, -you can declare an access-to-procedure variable @code{Ref} that is initialized -to designate a ‘do nothing’ procedure, and then invoke @code{Ref.all} -when appropriate. -In some library package, set @code{Ref} to @code{Proc'Access} for some -procedure @code{Proc} that performs the relevant processing. -The initialization only occurs if the library package is included in the -program. -The same idea can also be implemented using tagged types and dispatching -calls. - -@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada -@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8e} -@subsubsection Preprocessing - - -@geindex Preprocessing - -Although it is quite possible to conditionalize code without the use of -C-style preprocessing, as described earlier in this section, it is -nevertheless convenient in some cases to use the C approach. Moreover, -older Ada compilers have often provided some preprocessing capability, -so legacy code may depend on this approach, even though it is not -standard. - -To accommodate such use, GNAT provides a preprocessor (modeled to a large -extent on the various preprocessors that have been used -with legacy code on other compilers, to enable easier transition). - -@geindex gnatprep - -The preprocessor may be used in two separate modes. It can be used quite -separately from the compiler, to generate a separate output source file -that is then fed to the compiler as a separate step. This is the -@code{gnatprep} utility, whose use is fully described in -@ref{8f,,Preprocessing with gnatprep}. - -The preprocessing language allows such constructs as - -@example -#if DEBUG or else (PRIORITY > 4) then - sequence of declarations -#else - completely different sequence of declarations -#end if; -@end example - -The values of the symbols @code{DEBUG} and @code{PRIORITY} can be -defined either on the command line or in a separate file. - -The other way of running the preprocessor is even closer to the C style and -often more convenient. In this approach the preprocessing is integrated into -the compilation process. The compiler is given the preprocessor input which -includes @code{#if} lines etc, and then the compiler carries out the -preprocessing internally and processes the resulting output. -For more details on this approach, see @ref{90,,Integrated Preprocessing}. - -@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation -@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{91}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{8f} -@subsection Preprocessing with @code{gnatprep} - - -@geindex gnatprep - -@geindex Preprocessing (gnatprep) - -This section discusses how to use GNAT’s @code{gnatprep} utility for simple -preprocessing. -Although designed for use with GNAT, @code{gnatprep} does not depend on any -special GNAT features. -For further discussion of conditional compilation in general, see -@ref{2b,,Conditional Compilation}. - -@menu -* Preprocessing Symbols:: -* Using gnatprep:: -* Switches for gnatprep:: -* Form of Definitions File:: -* Form of Input Text for gnatprep:: - -@end menu - -@node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep -@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93} -@subsubsection Preprocessing Symbols - - -Preprocessing symbols are defined in `definition files' and referenced in the -sources to be preprocessed. A preprocessing symbol is an identifier, following -normal Ada (case-insensitive) rules for its syntax, with the restriction that -all characters need to be in the ASCII set (no accented letters). - -@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep -@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{95} -@subsubsection Using @code{gnatprep} - - -To call @code{gnatprep} use: - -@example -$ gnatprep [ switches ] infile outfile [ deffile ] -@end example - -where - - -@itemize * - -@item - -@table @asis - -@item `switches' - -is an optional sequence of switches as described in the next section. -@end table - -@item - -@table @asis - -@item `infile' - -is the full name of the input file, which is an Ada source -file containing preprocessor directives. -@end table - -@item - -@table @asis - -@item `outfile' - -is the full name of the output file, which is an Ada source -in standard Ada form. When used with GNAT, this file name will -normally have an @code{ads} or @code{adb} suffix. -@end table - -@item - -@table @asis - -@item @code{deffile} - -is the full name of a text file containing definitions of -preprocessing symbols to be referenced by the preprocessor. This argument is -optional, and can be replaced by the use of the @code{-D} switch. -@end table -@end itemize - -@node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep -@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{97} -@subsubsection Switches for @code{gnatprep} - - -@geindex --version (gnatprep) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatprep) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage and then exit disregarding -all other options. -@end table - -@geindex -b (gnatprep) - - -@table @asis - -@item @code{-b} - -Causes both preprocessor lines and the lines deleted by -preprocessing to be replaced by blank lines in the output source file, -preserving line numbers in the output file. -@end table - -@geindex -c (gnatprep) - - -@table @asis - -@item @code{-c} - -Causes both preprocessor lines and the lines deleted -by preprocessing to be retained in the output source as comments marked -with the special string @code{"--! "}. This option will result in line numbers -being preserved in the output file. -@end table - -@geindex -C (gnatprep) - - -@table @asis - -@item @code{-C} - -Causes comments to be scanned. Normally comments are ignored by gnatprep. -If this option is specified, then comments are scanned and any $symbol -substitutions performed as in program text. This is particularly useful -when structured comments are used (e.g., for programs written in a -pre-2014 version of the SPARK Ada subset). Note that this switch is not -available when doing integrated preprocessing (it would be useless in -this context since comments are ignored by the compiler in any case). -@end table - -@geindex -D (gnatprep) - - -@table @asis - -@item @code{-D`symbol'[=`value']} - -Defines a new preprocessing symbol with the specified value. If no value is given -on the command line, then symbol is considered to be @code{True}. This switch -can be used in place of a definition file. -@end table - -@geindex -r (gnatprep) - - -@table @asis - -@item @code{-r} - -Causes a @code{Source_Reference} pragma to be generated that -references the original input file, so that error messages will use -the file name of this original file. The use of this switch implies -that preprocessor lines are not to be removed from the file, so its -use will force @code{-b} mode if @code{-c} -has not been specified explicitly. - -Note that if the file to be preprocessed contains multiple units, then -it will be necessary to @code{gnatchop} the output file from -@code{gnatprep}. If a @code{Source_Reference} pragma is present -in the preprocessed file, it will be respected by -@code{gnatchop -r} -so that the final chopped files will correctly refer to the original -input source file for @code{gnatprep}. -@end table - -@geindex -s (gnatprep) - - -@table @asis - -@item @code{-s} - -Causes a sorted list of symbol names and values to be -listed on the standard output file. -@end table - -@geindex -T (gnatprep) - - -@table @asis - -@item @code{-T} - -Use LF as line terminators when writing files. By default the line terminator -of the host (LF under unix, CR/LF under Windows) is used. -@end table - -@geindex -u (gnatprep) - - -@table @asis - -@item @code{-u} - -Causes undefined symbols to be treated as having the value FALSE in the context -of a preprocessor test. In the absence of this option, an undefined symbol in -a @code{#if} or @code{#elsif} test will be treated as an error. -@end table - -@geindex -v (gnatprep) - - -@table @asis - -@item @code{-v} - -Verbose mode: generates more output about work done. -@end table - -Note: if neither @code{-b} nor @code{-c} is present, -then preprocessor lines and -deleted lines are completely removed from the output, unless -r is -specified, in which case -b is assumed. - -@node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep -@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{99} -@subsubsection Form of Definitions File - - -The definitions file contains lines of the form: - -@example -symbol := value -@end example - -where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following: - - -@itemize * - -@item -Empty, corresponding to a null substitution, - -@item -A string literal using normal Ada syntax, or - -@item -Any sequence of characters from the set @{letters, digits, period, underline@}. -@end itemize - -Comment lines may also appear in the definitions file, starting with -the usual @code{--}, -and comments may be added to the definitions lines. - -@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep -@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{9b} -@subsubsection Form of Input Text for @code{gnatprep} - - -The input text may contain preprocessor conditional inclusion lines, -as well as general symbol substitution sequences. - -The preprocessor conditional inclusion commands have the form: - -@example -#if [then] - lines -#elsif [then] - lines -#elsif [then] - lines -... -#else - lines -#end if; -@end example - -In this example, is defined by the following grammar: - -@example - ::= - ::= = "" - ::= = - ::= = - ::= > - ::= >= - ::= < - ::= <= - ::= 'Defined - ::= not - ::= and - ::= or - ::= and then - ::= or else - ::= ( ) -@end example - -Note the following restriction: it is not allowed to have “and” or “or” -following “not” in the same expression without parentheses. For example, this -is not allowed: - -@example -not X or Y -@end example - -This can be expressed instead as one of the following forms: - -@example -(not X) or Y -not (X or Y) -@end example - -For the first test ( ::= ) the symbol must have -either the value true or false, that is to say the right-hand of the -symbol definition must be one of the (case-insensitive) literals -@code{True} or @code{False}. If the value is true, then the -corresponding lines are included, and if the value is false, they are -excluded. - -When comparing a symbol to an integer, the integer is any non negative -literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or -2#11#. The symbol value must also be a non negative integer. Integer values -in the range 0 .. 2**31-1 are supported. - -The test ( ::= ’Defined) is true only if -the symbol has been defined in the definition file or by a @code{-D} -switch on the command line. Otherwise, the test is false. - -The equality tests are case insensitive, as are all the preprocessor lines. - -If the symbol referenced is not defined in the symbol definitions file, -then the effect depends on whether or not switch @code{-u} -is specified. If so, then the symbol is treated as if it had the value -false and the test fails. If this switch is not specified, then -it is an error to reference an undefined symbol. It is also an error to -reference a symbol that is defined with a value other than @code{True} -or @code{False}. - -The use of the @code{not} operator inverts the sense of this logical test. -The @code{not} operator cannot be combined with the @code{or} or @code{and} -operators, without parentheses. For example, “if not X or Y then” is not -allowed, but “if (not X) or Y then” and “if not (X or Y) then” are. - -The @code{then} keyword is optional as shown - -The @code{#} must be the first non-blank character on a line, but -otherwise the format is free form. Spaces or tabs may appear between -the @code{#} and the keyword. The keywords and the symbols are case -insensitive as in normal Ada code. Comments may be used on a -preprocessor line, but other than that, no other tokens may appear on a -preprocessor line. Any number of @code{elsif} clauses can be present, -including none at all. The @code{else} is optional, as in Ada. - -The @code{#} marking the start of a preprocessor line must be the first -non-blank character on the line, i.e., it must be preceded only by -spaces or horizontal tabs. - -Symbol substitution outside of preprocessor lines is obtained by using -the sequence: - -@example -$symbol -@end example - -anywhere within a source line, except in a comment or within a -string literal. The identifier -following the @code{$} must match one of the symbols defined in the symbol -definition file, and the result is to substitute the value of the -symbol in place of @code{$symbol} in the output file. - -Note that although the substitution of strings within a string literal -is not possible, it is possible to have a symbol whose defined value is -a string literal. So instead of setting XYZ to @code{hello} and writing: - -@example -Header : String := "$XYZ"; -@end example - -you should set XYZ to @code{"hello"} and write: - -@example -Header : String := $XYZ; -@end example - -and then the substitution will occur as desired. - -@node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation -@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90} -@subsection Integrated Preprocessing - - -As noted above, a file to be preprocessed consists of Ada source code -in which preprocessing lines have been inserted. However, -instead of using @code{gnatprep} to explicitly preprocess a file as a separate -step before compilation, you can carry out the preprocessing implicitly -as part of compilation. Such `integrated preprocessing', which is the common -style with C, is performed when either or both of the following switches -are passed to the compiler: - -@quotation - - -@itemize * - -@item -@code{-gnatep}, which specifies the `preprocessor data file'. -This file dictates how the source files will be preprocessed (e.g., which -symbol definition files apply to which sources). - -@item -@code{-gnateD}, which defines values for preprocessing symbols. -@end itemize -@end quotation - -Integrated preprocessing applies only to Ada source files, it is -not available for configuration pragma files. - -With integrated preprocessing, the output from the preprocessor is not, -by default, written to any external file. Instead it is passed -internally to the compiler. To preserve the result of -preprocessing in a file, either run @code{gnatprep} -in standalone mode or else supply the @code{-gnateG} switch -(described below) to the compiler. - -When using project files: - -@quotation - - -@itemize * - -@item -the builder switch @code{-x} should be used if any Ada source is -compiled with @code{gnatep=}, so that the compiler finds the -`preprocessor data file'. - -@item -the preprocessing data file and the symbol definition files should be -located in the source directories of the project. -@end itemize -@end quotation - -Note that the @code{gnatmake} switch @code{-m} will almost -always trigger recompilation for sources that are preprocessed, -because @code{gnatmake} cannot compute the checksum of the source after -preprocessing. - -The actual preprocessing function is described in detail in -@ref{8f,,Preprocessing with gnatprep}. This section explains the switches -that relate to integrated preprocessing. - -@geindex -gnatep (gcc) - - -@table @asis - -@item @code{-gnatep=`preprocessor_data_file'} - -This switch specifies the file name (without directory -information) of the preprocessor data file. Either place this file -in one of the source directories, or, when using project -files, reference the project file’s directory via the -@code{project_name'Project_Dir} project attribute; e.g: - -@quotation - -@example -project Prj is - package Compiler is - for Switches ("Ada") use - ("-gnatep=" & Prj'Project_Dir & "prep.def"); - end Compiler; -end Prj; -@end example -@end quotation - -A preprocessor data file is a text file that contains `preprocessor -control lines'. A preprocessor control line directs the preprocessing of -either a particular source file, or, analogous to @code{others} in Ada, -all sources not specified elsewhere in the preprocessor data file. -A preprocessor control line -can optionally identify a `definition file' that assigns values to -preprocessor symbols, as well as a list of switches that relate to -preprocessing. -Empty lines and comments (using Ada syntax) are also permitted, with no -semantic effect. - -Here’s an example of a preprocessor data file: - -@quotation - -@example -"toto.adb" "prep.def" -u --- Preprocess toto.adb, using definition file prep.def --- Undefined symbols are treated as False - -* -c -DVERSION=V101 --- Preprocess all other sources without using a definition file --- Suppressed lined are commented --- Symbol VERSION has the value V101 - -"tata.adb" "prep2.def" -s --- Preprocess tata.adb, using definition file prep2.def --- List all symbols with their values -@end example -@end quotation - -A preprocessor control line has the following syntax: - -@quotation - -@example - ::= - [ ] @{ @} - - ::= | '*' - - ::= - - := - - := (See below for list) -@end example -@end quotation - -Thus each preprocessor control line starts with either a literal string or -the character ‘*’: - - -@itemize * - -@item -A literal string is the file name (without directory information) of the source -file that will be input to the preprocessor. - -@item -The character ‘*’ is a wild-card indicator; the additional parameters on the line -indicate the preprocessing for all the sources -that are not specified explicitly on other lines (the order of the lines is not -significant). -@end itemize - -It is an error to have two lines with the same file name or two -lines starting with the character ‘*’. - -After the file name or ‘*’, an optional literal string specifies the name of -the definition file to be used for preprocessing -(@ref{98,,Form of Definitions File}). The definition files are found by the -compiler in one of the source directories. In some cases, when compiling -a source in a directory other than the current directory, if the definition -file is in the current directory, it may be necessary to add the current -directory as a source directory through the @code{-I} switch; otherwise -the compiler would not find the definition file. - -Finally, switches similar to those of @code{gnatprep} may optionally appear: - - -@table @asis - -@item @code{-b} - -Causes both preprocessor lines and the lines deleted by -preprocessing to be replaced by blank lines, preserving the line number. -This switch is always implied; however, if specified after @code{-c} -it cancels the effect of @code{-c}. - -@item @code{-c} - -Causes both preprocessor lines and the lines deleted -by preprocessing to be retained as comments marked -with the special string ‘@cite{–!}’. - -@item @code{-D`symbol'=`new_value'} - -Define or redefine @code{symbol} to have @code{new_value} as its value. -The permitted form for @code{symbol} is either an Ada identifier, or any Ada reserved word -aside from @code{if}, -@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. -The permitted form for @code{new_value} is a literal string, an Ada identifier or any Ada reserved -word. A symbol declared with this switch replaces a symbol with the -same name defined in a definition file. - -@item @code{-s} - -Causes a sorted list of symbol names and values to be -listed on the standard output file. - -@item @code{-u} - -Causes undefined symbols to be treated as having the value @code{FALSE} -in the context -of a preprocessor test. In the absence of this option, an undefined symbol in -a @code{#if} or @code{#elsif} test will be treated as an error. -@end table -@end table - -@geindex -gnateD (gcc) - - -@table @asis - -@item @code{-gnateD`symbol'[=`new_value']} - -Define or redefine @code{symbol} to have @code{new_value} as its value. If no value -is supplied, then the value of @code{symbol} is @code{True}. -The form of @code{symbol} is an identifier, following normal Ada (case-insensitive) -rules for its syntax, and @code{new_value} is either an arbitrary string between double -quotes or any sequence (including an empty sequence) of characters from the -set (letters, digits, period, underline). -Ada reserved words may be used as symbols, with the exceptions of @code{if}, -@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. - -Examples: - -@quotation - -@example --gnateDToto=Tata --gnateDFoo --gnateDFoo=\"Foo-Bar\" -@end example -@end quotation - -A symbol declared with this switch on the command line replaces a -symbol with the same name either in a definition file or specified with a -switch @code{-D} in the preprocessor data file. - -This switch is similar to switch @code{-D} of @code{gnatprep}. - -@item @code{-gnateG} - -When integrated preprocessing is performed on source file @code{filename.extension}, -create or overwrite @code{filename.extension.prep} to contain -the result of the preprocessing. -For example if the source file is @code{foo.adb} then -the output file will be @code{foo.adb.prep}. -@end table - -@node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{9d}@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{2c} -@section Mixed Language Programming - - -@geindex Mixed Language Programming - -This section describes how to develop a mixed-language program, -with a focus on combining Ada with C or C++. - -@menu -* Interfacing to C:: -* Calling Conventions:: -* Building Mixed Ada and C++ Programs:: -* Generating Ada Bindings for C and C++ headers:: -* Generating C Headers for Ada Specifications:: - -@end menu - -@node Interfacing to C,Calling Conventions,,Mixed Language Programming -@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{9f} -@subsection Interfacing to C - - -Interfacing Ada with a foreign language such as C involves using -compiler directives to import and/or export entity definitions in each -language – using @code{extern} statements in C, for instance, and the -@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada. -A full treatment of these topics is provided in Appendix B, section 1 -of the Ada Reference Manual. - -There are two ways to build a program using GNAT that contains some Ada -sources and some foreign language sources, depending on whether or not -the main subprogram is written in Ada. Here is a source example with -the main subprogram in Ada: - -@example -/* file1.c */ -#include - -void print_num (int num) -@{ - printf ("num is %d.\\n", num); - return; -@} -@end example - -@example -/* file2.c */ - -/* num_from_Ada is declared in my_main.adb */ -extern int num_from_Ada; - -int get_num (void) -@{ - return num_from_Ada; -@} -@end example - -@example --- my_main.adb -procedure My_Main is - - -- Declare then export an Integer entity called num_from_Ada - My_Num : Integer := 10; - pragma Export (C, My_Num, "num_from_Ada"); - - -- Declare an Ada function spec for Get_Num, then use - -- C function get_num for the implementation. - function Get_Num return Integer; - pragma Import (C, Get_Num, "get_num"); - - -- Declare an Ada procedure spec for Print_Num, then use - -- C function print_num for the implementation. - procedure Print_Num (Num : Integer); - pragma Import (C, Print_Num, "print_num"); - -begin - Print_Num (Get_Num); -end My_Main; -@end example - -To build this example: - - -@itemize * - -@item -First compile the foreign language files to -generate object files: - -@example -$ gcc -c file1.c -$ gcc -c file2.c -@end example - -@item -Then, compile the Ada units to produce a set of object files and ALI -files: - -@example -$ gnatmake -c my_main.adb -@end example - -@item -Run the Ada binder on the Ada main program: - -@example -$ gnatbind my_main.ali -@end example - -@item -Link the Ada main program, the Ada objects and the other language -objects: - -@example -$ gnatlink my_main.ali file1.o file2.o -@end example -@end itemize - -The last three steps can be grouped in a single command: - -@example -$ gnatmake my_main.adb -largs file1.o file2.o -@end example - -@geindex Binder output file - -If the main program is in a language other than Ada, then you may have -more than one entry point into the Ada subsystem. You must use a special -binder option to generate callable routines that initialize and -finalize the Ada units (@ref{a0,,Binding with Non-Ada Main Programs}). -Calls to the initialization and finalization routines must be inserted -in the main program, or some other appropriate point in the code. The -call to initialize the Ada units must occur before the first Ada -subprogram is called, and the call to finalize the Ada units must occur -after the last Ada subprogram returns. The binder will place the -initialization and finalization subprograms into the -@code{b~xxx.adb} file where they can be accessed by your C -sources. To illustrate, we have the following example: - -@example -/* main.c */ -extern void adainit (void); -extern void adafinal (void); -extern int add (int, int); -extern int sub (int, int); - -int main (int argc, char *argv[]) -@{ - int a = 21, b = 7; - - adainit(); - - /* Should print "21 + 7 = 28" */ - printf ("%d + %d = %d\\n", a, b, add (a, b)); - - /* Should print "21 - 7 = 14" */ - printf ("%d - %d = %d\\n", a, b, sub (a, b)); - - adafinal(); -@} -@end example - -@example --- unit1.ads -package Unit1 is - function Add (A, B : Integer) return Integer; - pragma Export (C, Add, "add"); -end Unit1; -@end example - -@example --- unit1.adb -package body Unit1 is - function Add (A, B : Integer) return Integer is - begin - return A + B; - end Add; -end Unit1; -@end example - -@example --- unit2.ads -package Unit2 is - function Sub (A, B : Integer) return Integer; - pragma Export (C, Sub, "sub"); -end Unit2; -@end example - -@example --- unit2.adb -package body Unit2 is - function Sub (A, B : Integer) return Integer is - begin - return A - B; - end Sub; -end Unit2; -@end example - -The build procedure for this application is similar to the last -example’s: - - -@itemize * - -@item -First, compile the foreign language files to generate object files: - -@example -$ gcc -c main.c -@end example - -@item -Next, compile the Ada units to produce a set of object files and ALI -files: - -@example -$ gnatmake -c unit1.adb -$ gnatmake -c unit2.adb -@end example - -@item -Run the Ada binder on every generated ALI file. Make sure to use the -@code{-n} option to specify a foreign main program: - -@example -$ gnatbind -n unit1.ali unit2.ali -@end example - -@item -Link the Ada main program, the Ada objects and the foreign language -objects. You need only list the last ALI file here: - -@example -$ gnatlink unit2.ali main.o -o exec_file -@end example - -This procedure yields a binary executable called @code{exec_file}. -@end itemize - -Depending on the circumstances (for example when your non-Ada main object -does not provide symbol @code{main}), you may also need to instruct the -GNAT linker not to include the standard startup objects by passing the -@code{-nostartfiles} switch to @code{gnatlink}. - -@node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming -@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2} -@subsection Calling Conventions - - -@geindex Foreign Languages - -@geindex Calling Conventions - -GNAT follows standard calling sequence conventions and will thus interface -to any other language that also follows these conventions. The following -Convention identifiers are recognized by GNAT: - -@geindex Interfacing to Ada - -@geindex Other Ada compilers - -@geindex Convention Ada - - -@table @asis - -@item @code{Ada} - -This indicates that the standard Ada calling sequence will be -used and all Ada data items may be passed without any limitations in the -case where GNAT is used to generate both the caller and callee. It is also -possible to mix GNAT generated code and code generated by another Ada -compiler. In this case, the data types should be restricted to simple -cases, including primitive types. Whether complex data types can be passed -depends on the situation. Probably it is safe to pass simple arrays, such -as arrays of integers or floats. Records may or may not work, depending -on whether both compilers lay them out identically. Complex structures -involving variant records, access parameters, tasks, or protected types, -are unlikely to be able to be passed. - -Note that in the case of GNAT running -on a platform that supports HP Ada 83, a higher degree of compatibility -can be guaranteed, and in particular records are laid out in an identical -manner in the two compilers. Note also that if output from two different -compilers is mixed, the program is responsible for dealing with elaboration -issues. Probably the safest approach is to write the main program in the -version of Ada other than GNAT, so that it takes care of its own elaboration -requirements, and then call the GNAT-generated adainit procedure to ensure -elaboration of the GNAT components. Consult the documentation of the other -Ada compiler for further details on elaboration. - -However, it is not possible to mix the tasking run time of GNAT and -HP Ada 83, All the tasking operations must either be entirely within -GNAT compiled sections of the program, or entirely within HP Ada 83 -compiled sections of the program. -@end table - -@geindex Interfacing to Assembly - -@geindex Convention Assembler - - -@table @asis - -@item @code{Assembler} - -Specifies assembler as the convention. In practice this has the -same effect as convention Ada (but is not equivalent in the sense of being -considered the same convention). -@end table - -@geindex Convention Asm - -@geindex Asm - - -@table @asis - -@item @code{Asm} - -Equivalent to Assembler. - -@geindex Interfacing to COBOL - -@geindex Convention COBOL -@end table - -@geindex COBOL - - -@table @asis - -@item @code{COBOL} - -Data will be passed according to the conventions described -in section B.4 of the Ada Reference Manual. -@end table - -@geindex C - -@geindex Interfacing to C - -@geindex Convention C - - -@table @asis - -@item @code{C} - -Data will be passed according to the conventions described -in section B.3 of the Ada Reference Manual. - -A note on interfacing to a C ‘varargs’ function: - -@quotation - -@geindex C varargs function - -@geindex Interfacing to C varargs function - -@geindex varargs function interfaces - -In C, @code{varargs} allows a function to take a variable number of -arguments. There is no direct equivalent in this to Ada. One -approach that can be used is to create a C wrapper for each -different profile and then interface to this C wrapper. For -example, to print an @code{int} value using @code{printf}, -create a C function @code{printfi} that takes two arguments, a -pointer to a string and an int, and calls @code{printf}. -Then in the Ada program, use pragma @code{Import} to -interface to @code{printfi}. - -It may work on some platforms to directly interface to -a @code{varargs} function by providing a specific Ada profile -for a particular call. However, this does not work on -all platforms, since there is no guarantee that the -calling sequence for a two argument normal C function -is the same as for calling a @code{varargs} C function with -the same two arguments. -@end quotation -@end table - -@geindex Convention Default - -@geindex Default - - -@table @asis - -@item @code{Default} - -Equivalent to C. -@end table - -@geindex Convention External - -@geindex External - - -@table @asis - -@item @code{External} - -Equivalent to C. -@end table - -@geindex C++ - -@geindex Interfacing to C++ - -@geindex Convention C++ - - -@table @asis - -@item @code{C_Plus_Plus} (or @code{CPP}) - -This stands for C++. For most purposes this is identical to C. -See the separate description of the specialized GNAT pragmas relating to -C++ interfacing for further details. -@end table - -@geindex Fortran - -@geindex Interfacing to Fortran - -@geindex Convention Fortran - - -@table @asis - -@item @code{Fortran} - -Data will be passed according to the conventions described -in section B.5 of the Ada Reference Manual. - -@item @code{Intrinsic} - -This applies to an intrinsic operation, as defined in the Ada -Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram, -this means that the body of the subprogram is provided by the compiler itself, -usually by means of an efficient code sequence, and that the user does not -supply an explicit body for it. In an application program, the pragma may -be applied to the following sets of names: - - -@itemize * - -@item -Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_Arithmetic. -The corresponding subprogram declaration must have -two formal parameters. The -first one must be a signed integer type or a modular type with a binary -modulus, and the second parameter must be of type Natural. -The return type must be the same as the type of the first argument. The size -of this type can only be 8, 16, 32, or 64. - -@item -Binary arithmetic operators: ‘+’, ‘-’, ‘*’, ‘/’. -The corresponding operator declaration must have parameters and result type -that have the same root numeric type (for example, all three are long_float -types). This simplifies the definition of operations that use type checking -to perform dimensional checks: -@end itemize - -@example - type Distance is new Long_Float; - type Time is new Long_Float; - type Velocity is new Long_Float; - function "/" (D : Distance; T : Time) - return Velocity; - pragma Import (Intrinsic, "/"); - -This common idiom is often programmed with a generic definition and an -explicit body. The pragma makes it simpler to introduce such declarations. -It incurs no overhead in compilation time or code size, because it is -implemented as a single machine instruction. -@end example - - -@itemize * - -@item -General subprogram entities. This is used to bind an Ada subprogram -declaration to -a compiler builtin by name with back-ends where such interfaces are -available. A typical example is the set of @code{__builtin} functions -exposed by the GCC back-end, as in the following example: - -@example -function builtin_sqrt (F : Float) return Float; -pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); -@end example - -Most of the GCC builtins are accessible this way, and as for other -import conventions (e.g. C), it is the user’s responsibility to ensure -that the Ada subprogram profile matches the underlying builtin -expectations. -@end itemize -@end table - -@geindex Stdcall - -@geindex Convention Stdcall - - -@table @asis - -@item @code{Stdcall} - -This is relevant only to Windows implementations of GNAT, -and specifies that the @code{Stdcall} calling sequence will be used, -as defined by the NT API. Nevertheless, to ease building -cross-platform bindings this convention will be handled as a @code{C} calling -convention on non-Windows platforms. -@end table - -@geindex DLL - -@geindex Convention DLL - - -@table @asis - -@item @code{DLL} - -This is equivalent to @code{Stdcall}. -@end table - -@geindex Win32 - -@geindex Convention Win32 - - -@table @asis - -@item @code{Win32} - -This is equivalent to @code{Stdcall}. -@end table - -@geindex Stubbed - -@geindex Convention Stubbed - - -@table @asis - -@item @code{Stubbed} - -This is a special convention that indicates that the compiler -should provide a stub body that raises @code{Program_Error}. -@end table - -GNAT additionally provides a useful pragma @code{Convention_Identifier} -that can be used to parameterize conventions and allow additional synonyms -to be specified. For example if you have legacy code in which the convention -identifier Fortran77 was used for Fortran, you can use the configuration -pragma: - -@example -pragma Convention_Identifier (Fortran77, Fortran); -@end example - -And from now on the identifier Fortran77 may be used as a convention -identifier (for example in an @code{Import} pragma) with the same -meaning as Fortran. - -@node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming -@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{a4} -@subsection Building Mixed Ada and C++ Programs - - -A programmer inexperienced with mixed-language development may find that -building an application containing both Ada and C++ code can be a -challenge. This section gives a few hints that should make this task easier. - -@menu -* Interfacing to C++:: -* Linking a Mixed C++ & Ada Program:: -* A Simple Example:: -* Interfacing with C++ constructors:: -* Interfacing with C++ at the Class Level:: - -@end menu - -@node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs -@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6} -@subsubsection Interfacing to C++ - - -GNAT supports interfacing with the G++ compiler (or any C++ compiler -generating code that is compatible with the G++ Application Binary -Interface —see @indicateurl{http://itanium-cxx-abi.github.io/cxx-abi/abi.html}). - -Interfacing can be done at 3 levels: simple data, subprograms, and -classes. In the first two cases, GNAT offers a specific @code{Convention C_Plus_Plus} -(or @code{CPP}) that behaves exactly like @code{Convention C}. -Usually, C++ mangles the names of subprograms. To generate proper mangled -names automatically, see @ref{a7,,Generating Ada Bindings for C and C++ headers}). -This problem can also be addressed manually in two ways: - - -@itemize * - -@item -by modifying the C++ code in order to force a C convention using -the @code{extern "C"} syntax. - -@item -by figuring out the mangled name (using e.g. @code{nm}) and using it as the -Link_Name argument of the pragma import. -@end itemize - -Interfacing at the class level can be achieved by using the GNAT specific -pragmas such as @code{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information. - -@node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs -@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{a9} -@subsubsection Linking a Mixed C++ & Ada Program - - -Usually the linker of the C++ development system must be used to link -mixed applications because most C++ systems will resolve elaboration -issues (such as calling constructors on global class instances) -transparently during the link phase. GNAT has been adapted to ease the -use of a foreign linker for the last phase. Three cases can be -considered: - - -@itemize * - -@item -Using GNAT and G++ (GNU C++ compiler) from the same GCC installation: -The C++ linker can simply be called by using the C++ specific driver -called @code{g++}. - -Note that if the C++ code uses inline functions, you will need to -compile your C++ code with the @code{-fkeep-inline-functions} switch in -order to provide an existing function implementation that the Ada code can -link with. - -@example -$ g++ -c -fkeep-inline-functions file1.C -$ g++ -c -fkeep-inline-functions file2.C -$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ -@end example - -@item -Using GNAT and G++ from two different GCC installations: If both -compilers are on the :envvar`PATH`, the previous method may be used. It is -important to note that environment variables such as -@geindex C_INCLUDE_PATH -@geindex environment variable; C_INCLUDE_PATH -@code{C_INCLUDE_PATH}, -@geindex GCC_EXEC_PREFIX -@geindex environment variable; GCC_EXEC_PREFIX -@code{GCC_EXEC_PREFIX}, -@geindex BINUTILS_ROOT -@geindex environment variable; BINUTILS_ROOT -@code{BINUTILS_ROOT}, and -@geindex GCC_ROOT -@geindex environment variable; GCC_ROOT -@code{GCC_ROOT} will affect both compilers -at the same time and may make one of the two compilers operate -improperly if set during invocation of the wrong compiler. It is also -very important that the linker uses the proper @code{libgcc.a} GCC -library – that is, the one from the C++ compiler installation. The -implicit link command as suggested in the @code{gnatmake} command -from the former example can be replaced by an explicit link command with -the full-verbosity option in order to verify which library is used: - -@example -$ gnatbind ada_unit -$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ -@end example - -If there is a problem due to interfering environment variables, it can -be worked around by using an intermediate script. The following example -shows the proper script to use when GNAT has not been installed at its -default location and g++ has been installed at its default location: - -@example -$ cat ./my_script -#!/bin/sh -unset BINUTILS_ROOT -unset GCC_ROOT -c++ $* -$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script -@end example - -@item -Using a non-GNU C++ compiler: The commands previously described can be -used to insure that the C++ linker is used. Nonetheless, you need to add -a few more parameters to the link command line, depending on the exception -mechanism used. - -If the @code{setjmp} / @code{longjmp} exception mechanism is used, only the paths -to the @code{libgcc} libraries are required: - -@example -$ cat ./my_script -#!/bin/sh -CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a -$ gnatlink ada_unit file1.o file2.o --LINK=./my_script -@end example - -where CC is the name of the non-GNU C++ compiler. - -If the “zero cost” exception mechanism is used, and the platform -supports automatic registration of exception tables (e.g., Solaris), -paths to more objects are required: - -@example -$ cat ./my_script -#!/bin/sh -CC gcc -print-file-name=crtbegin.o $* \\ -gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\ -gcc -print-file-name=crtend.o -$ gnatlink ada_unit file1.o file2.o --LINK=./my_script -@end example - -If the “zero cost exception” mechanism is used, and the platform -doesn’t support automatic registration of exception tables (e.g., HP-UX -or AIX), the simple approach described above will not work and -a pre-linking phase using GNAT will be necessary. -@end itemize - -Another alternative is to use the @code{gprbuild} multi-language builder -which has a large knowledge base and knows how to link Ada and C++ code -together automatically in most cases. - -@node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs -@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{ab} -@subsubsection A Simple Example - - -The following example, provided as part of the GNAT examples, shows how -to achieve procedural interfacing between Ada and C++ in both -directions. The C++ class A has two methods. The first method is exported -to Ada by the means of an extern C wrapper function. The second method -calls an Ada subprogram. On the Ada side, the C++ calls are modelled by -a limited record with a layout comparable to the C++ class. The Ada -subprogram, in turn, calls the C++ method. So, starting from the C++ -main program, the process passes back and forth between the two -languages. - -Here are the compilation commands: - -@example -$ gnatmake -c simple_cpp_interface -$ g++ -c cpp_main.C -$ g++ -c ex7.C -$ gnatbind -n simple_cpp_interface -$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o -@end example - -Here are the corresponding sources: - -@example -//cpp_main.C - -#include "ex7.h" - -extern "C" @{ - void adainit (void); - void adafinal (void); - void method1 (A *t); -@} - -void method1 (A *t) -@{ - t->method1 (); -@} - -int main () -@{ - A obj; - adainit (); - obj.method2 (3030); - adafinal (); -@} -@end example - -@example -//ex7.h - -class Origin @{ - public: - int o_value; -@}; -class A : public Origin @{ - public: - void method1 (void); - void method2 (int v); - A(); - int a_value; -@}; -@end example - -@example -//ex7.C - -#include "ex7.h" -#include - -extern "C" @{ void ada_method2 (A *t, int v);@} - -void A::method1 (void) -@{ - a_value = 2020; - printf ("in A::method1, a_value = %d \\n",a_value); -@} - -void A::method2 (int v) -@{ - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \\n",a_value); -@} - -A::A(void) -@{ - a_value = 1010; - printf ("in A::A, a_value = %d \\n",a_value); -@} -@end example - -@example --- simple_cpp_interface.ads -with System; -package Simple_Cpp_Interface is - type A is limited - record - Vptr : System.Address; - O_Value : Integer; - A_Value : Integer; - end record; - pragma Convention (C, A); - - procedure Method1 (This : in out A); - pragma Import (C, Method1); - - procedure Ada_Method2 (This : in out A; V : Integer); - pragma Export (C, Ada_Method2); - -end Simple_Cpp_Interface; -@end example - -@example --- simple_cpp_interface.adb -package body Simple_Cpp_Interface is - - procedure Ada_Method2 (This : in out A; V : Integer) is - begin - Method1 (This); - This.A_Value := V; - end Ada_Method2; - -end Simple_Cpp_Interface; -@end example - -@node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs -@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{ad} -@subsubsection Interfacing with C++ constructors - - -In order to interface with C++ constructors GNAT provides the -@code{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual} -for additional information). -In this section we present some common uses of C++ constructors -in mixed-languages programs in GNAT. - -Let us assume that we need to interface with the following -C++ class: - -@example -class Root @{ -public: - int a_value; - int b_value; - virtual int Get_Value (); - Root(); // Default constructor - Root(int v); // 1st non-default constructor - Root(int v, int w); // 2nd non-default constructor -@}; -@end example - -For this purpose we can write the following package spec (further -information on how to build this spec is available in -@ref{ae,,Interfacing with C++ at the Class Level} and -@ref{a7,,Generating Ada Bindings for C and C++ headers}). - -@example -with Interfaces.C; use Interfaces.C; -package Pkg_Root is - type Root is tagged limited record - A_Value : int; - B_Value : int; - end record; - pragma Import (CPP, Root); - - function Get_Value (Obj : Root) return int; - pragma Import (CPP, Get_Value); - - function Constructor return Root; - pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); - - function Constructor (v : Integer) return Root; - pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); - - function Constructor (v, w : Integer) return Root; - pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); -end Pkg_Root; -@end example - -On the Ada side the constructor is represented by a function (whose -name is arbitrary) that returns the classwide type corresponding to -the imported C++ class. Although the constructor is described as a -function, it is typically a procedure with an extra implicit argument -(the object being initialized) at the implementation level. GNAT -issues the appropriate call, whatever it is, to get the object -properly initialized. - -Constructors can only appear in the following contexts: - - -@itemize * - -@item -On the right side of an initialization of an object of type @code{T}. - -@item -On the right side of an initialization of a record component of type @code{T}. - -@item -In an Ada 2005 limited aggregate. - -@item -In an Ada 2005 nested limited aggregate. - -@item -In an Ada 2005 limited aggregate that initializes an object built in -place by an extended return statement. -@end itemize - -In a declaration of an object whose type is a class imported from C++, -either the default C++ constructor is implicitly called by GNAT, or -else the required C++ constructor must be explicitly called in the -expression that initializes the object. For example: - -@example -Obj1 : Root; -Obj2 : Root := Constructor; -Obj3 : Root := Constructor (v => 10); -Obj4 : Root := Constructor (30, 40); -@end example - -The first two declarations are equivalent: in both cases the default C++ -constructor is invoked (in the former case the call to the constructor is -implicit, and in the latter case the call is explicit in the object -declaration). @code{Obj3} is initialized by the C++ non-default constructor -that takes an integer argument, and @code{Obj4} is initialized by the -non-default C++ constructor that takes two integers. - -Let us derive the imported C++ class in the Ada side. For example: - -@example -type DT is new Root with record - C_Value : Natural := 2009; -end record; -@end example - -In this case the components DT inherited from the C++ side must be -initialized by a C++ constructor, and the additional Ada components -of type DT are initialized by GNAT. The initialization of such an -object is done either by default, or by means of a function returning -an aggregate of type DT, or by means of an extension aggregate. - -@example -Obj5 : DT; -Obj6 : DT := Function_Returning_DT (50); -Obj7 : DT := (Constructor (30,40) with C_Value => 50); -@end example - -The declaration of @code{Obj5} invokes the default constructors: the -C++ default constructor of the parent type takes care of the initialization -of the components inherited from Root, and GNAT takes care of the default -initialization of the additional Ada components of type DT (that is, -@code{C_Value} is initialized to value 2009). The order of invocation of -the constructors is consistent with the order of elaboration required by -Ada and C++. That is, the constructor of the parent type is always called -before the constructor of the derived type. - -Let us now consider a record that has components whose type is imported -from C++. For example: - -@example -type Rec1 is limited record - Data1 : Root := Constructor (10); - Value : Natural := 1000; -end record; - -type Rec2 (D : Integer := 20) is limited record - Rec : Rec1; - Data2 : Root := Constructor (D, 30); -end record; -@end example - -The initialization of an object of type @code{Rec2} will call the -non-default C++ constructors specified for the imported components. -For example: - -@example -Obj8 : Rec2 (40); -@end example - -Using Ada 2005 we can use limited aggregates to initialize an object -invoking C++ constructors that differ from those specified in the type -declarations. For example: - -@example -Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), - others => <>), - others => <>); -@end example - -The above declaration uses an Ada 2005 limited aggregate to -initialize @code{Obj9}, and the C++ constructor that has two integer -arguments is invoked to initialize the @code{Data1} component instead -of the constructor specified in the declaration of type @code{Rec1}. In -Ada 2005 the box in the aggregate indicates that unspecified components -are initialized using the expression (if any) available in the component -declaration. That is, in this case discriminant @code{D} is initialized -to value @code{20}, @code{Value} is initialized to value 1000, and the -non-default C++ constructor that handles two integers takes care of -initializing component @code{Data2} with values @code{20,30}. - -In Ada 2005 we can use the extended return statement to build the Ada -equivalent to C++ non-default constructors. For example: - -@example -function Constructor (V : Integer) return Rec2 is -begin - return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), - others => <>), - others => <>) do - -- Further actions required for construction of - -- objects of type Rec2 - ... - end record; -end Constructor; -@end example - -In this example the extended return statement construct is used to -build in place the returned object whose components are initialized -by means of a limited aggregate. Any further action associated with -the constructor can be placed inside the construct. - -@node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs -@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{af}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{ae} -@subsubsection Interfacing with C++ at the Class Level - - -In this section we demonstrate the GNAT features for interfacing with -C++ by means of an example making use of Ada 2005 abstract interface -types. This example consists of a classification of animals; classes -have been used to model our main classification of animals, and -interfaces provide support for the management of secondary -classifications. We first demonstrate a case in which the types and -constructors are defined on the C++ side and imported from the Ada -side, and latter the reverse case. - -The root of our derivation will be the @code{Animal} class, with a -single private attribute (the @code{Age} of the animal), a constructor, -and two public primitives to set and get the value of this attribute. - -@example -class Animal @{ - public: - virtual void Set_Age (int New_Age); - virtual int Age (); - Animal() @{Age_Count = 0;@}; - private: - int Age_Count; -@}; -@end example - -Abstract interface types are defined in C++ by means of classes with pure -virtual functions and no data members. In our example we will use two -interfaces that provide support for the common management of @code{Carnivore} -and @code{Domestic} animals: - -@example -class Carnivore @{ -public: - virtual int Number_Of_Teeth () = 0; -@}; - -class Domestic @{ -public: - virtual void Set_Owner (char* Name) = 0; -@}; -@end example - -Using these declarations, we can now say that a @code{Dog} is an animal that is -both Carnivore and Domestic, that is: - -@example -class Dog : Animal, Carnivore, Domestic @{ - public: - virtual int Number_Of_Teeth (); - virtual void Set_Owner (char* Name); - - Dog(); // Constructor - private: - int Tooth_Count; - char *Owner; -@}; -@end example - -In the following examples we will assume that the previous declarations are -located in a file named @code{animals.h}. The following package demonstrates -how to import these C++ declarations from the Ada side: - -@example -with Interfaces.C.Strings; use Interfaces.C.Strings; -package Animals is - type Carnivore is limited interface; - pragma Convention (C_Plus_Plus, Carnivore); - function Number_Of_Teeth (X : Carnivore) - return Natural is abstract; - - type Domestic is limited interface; - pragma Convention (C_Plus_Plus, Domestic); - procedure Set_Owner - (X : in out Domestic; - Name : Chars_Ptr) is abstract; - - type Animal is tagged limited record - Age : Natural; - end record; - pragma Import (C_Plus_Plus, Animal); - - procedure Set_Age (X : in out Animal; Age : Integer); - pragma Import (C_Plus_Plus, Set_Age); - - function Age (X : Animal) return Integer; - pragma Import (C_Plus_Plus, Age); - - function New_Animal return Animal; - pragma CPP_Constructor (New_Animal); - pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev"); - - type Dog is new Animal and Carnivore and Domestic with record - Tooth_Count : Natural; - Owner : Chars_Ptr; - end record; - pragma Import (C_Plus_Plus, Dog); - - function Number_Of_Teeth (A : Dog) return Natural; - pragma Import (C_Plus_Plus, Number_Of_Teeth); - - procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); - pragma Import (C_Plus_Plus, Set_Owner); - - function New_Dog return Dog; - pragma CPP_Constructor (New_Dog); - pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); -end Animals; -@end example - -Thanks to the compatibility between GNAT run-time structures and the C++ ABI, -interfacing with these C++ classes is easy. The only requirement is that all -the primitives and components must be declared exactly in the same order in -the two languages. - -Regarding the abstract interfaces, we must indicate to the GNAT compiler by -means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass -the arguments to the called primitives will be the same as for C++. For the -imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus} -to indicate that they have been defined on the C++ side; this is required -because the dispatch table associated with these tagged types will be built -in the C++ side and therefore will not contain the predefined Ada primitives -which Ada would otherwise expect. - -As the reader can see there is no need to indicate the C++ mangled names -associated with each subprogram because it is assumed that all the calls to -these primitives will be dispatching calls. The only exception is the -constructor, which must be registered with the compiler by means of -@code{pragma CPP_Constructor} and needs to provide its associated C++ -mangled name because the Ada compiler generates direct calls to it. - -With the above packages we can now declare objects of type Dog on the Ada side -and dispatch calls to the corresponding subprograms on the C++ side. We can -also extend the tagged type Dog with further fields and primitives, and -override some of its C++ primitives on the Ada side. For example, here we have -a type derivation defined on the Ada side that inherits all the dispatching -primitives of the ancestor from the C++ side. - -@example -with Animals; use Animals; -package Vaccinated_Animals is - type Vaccinated_Dog is new Dog with null record; - function Vaccination_Expired (A : Vaccinated_Dog) return Boolean; -end Vaccinated_Animals; -@end example - -It is important to note that, because of the ABI compatibility, the programmer -does not need to add any further information to indicate either the object -layout or the dispatch table entry associated with each dispatching operation. - -Now let us define all the types and constructors on the Ada side and export -them to C++, using the same hierarchy of our previous example: - -@example -with Interfaces.C.Strings; -use Interfaces.C.Strings; -package Animals is - type Carnivore is limited interface; - pragma Convention (C_Plus_Plus, Carnivore); - function Number_Of_Teeth (X : Carnivore) - return Natural is abstract; - - type Domestic is limited interface; - pragma Convention (C_Plus_Plus, Domestic); - procedure Set_Owner - (X : in out Domestic; - Name : Chars_Ptr) is abstract; - - type Animal is tagged record - Age : Natural; - end record; - pragma Convention (C_Plus_Plus, Animal); - - procedure Set_Age (X : in out Animal; Age : Integer); - pragma Export (C_Plus_Plus, Set_Age); - - function Age (X : Animal) return Integer; - pragma Export (C_Plus_Plus, Age); - - function New_Animal return Animal'Class; - pragma Export (C_Plus_Plus, New_Animal); - - type Dog is new Animal and Carnivore and Domestic with record - Tooth_Count : Natural; - Owner : String (1 .. 30); - end record; - pragma Convention (C_Plus_Plus, Dog); - - function Number_Of_Teeth (A : Dog) return Natural; - pragma Export (C_Plus_Plus, Number_Of_Teeth); - - procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); - pragma Export (C_Plus_Plus, Set_Owner); - - function New_Dog return Dog'Class; - pragma Export (C_Plus_Plus, New_Dog); -end Animals; -@end example - -Compared with our previous example the only differences are the use of -@code{pragma Convention} (instead of @code{pragma Import}), and the use of -@code{pragma Export} to indicate to the GNAT compiler that the primitives will -be available to C++. Thanks to the ABI compatibility, on the C++ side there is -nothing else to be done; as explained above, the only requirement is that all -the primitives and components are declared in exactly the same order. - -For completeness, let us see a brief C++ main program that uses the -declarations available in @code{animals.h} (presented in our first example) to -import and use the declarations from the Ada side, properly initializing and -finalizing the Ada run-time system along the way: - -@example -#include "animals.h" -#include -using namespace std; - -void Check_Carnivore (Carnivore *obj) @{...@} -void Check_Domestic (Domestic *obj) @{...@} -void Check_Animal (Animal *obj) @{...@} -void Check_Dog (Dog *obj) @{...@} - -extern "C" @{ - void adainit (void); - void adafinal (void); - Dog* new_dog (); -@} - -void test () -@{ - Dog *obj = new_dog(); // Ada constructor - Check_Carnivore (obj); // Check secondary DT - Check_Domestic (obj); // Check secondary DT - Check_Animal (obj); // Check primary DT - Check_Dog (obj); // Check primary DT -@} - -int main () -@{ - adainit (); test(); adafinal (); - return 0; -@} -@end example - -@node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming -@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{a7}@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{b0} -@subsection Generating Ada Bindings for C and C++ headers - - -@geindex Binding generation (for C and C++ headers) - -@geindex C headers (binding generation) - -@geindex C++ headers (binding generation) - -GNAT includes a binding generator for C and C++ headers which is -intended to do 95% of the tedious work of generating Ada specs from C -or C++ header files. - -Note that this capability is not intended to generate 100% correct Ada specs, -and will is some cases require manual adjustments, although it can often -be used out of the box in practice. - -Some of the known limitations include: - - -@itemize * - -@item -only very simple character constant macros are translated into Ada -constants. Function macros (macros with arguments) are partially translated -as comments, to be completed manually if needed. - -@item -some extensions (e.g. vector types) are not supported - -@item -pointers to pointers are mapped to System.Address - -@item -identifiers with identical name (except casing) may generate compilation -errors (e.g. @code{shm_get} vs @code{SHM_GET}). -@end itemize - -The code is generated using Ada 2012 syntax, which makes it easier to interface -with other languages. In most cases you can still use the generated binding -even if your code is compiled using earlier versions of Ada (e.g. @code{-gnat95}). - -@menu -* Running the Binding Generator:: -* Generating Bindings for C++ Headers:: -* Switches:: - -@end menu - -@node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers -@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2} -@subsubsection Running the Binding Generator - - -The binding generator is part of the @code{gcc} compiler and can be -invoked via the @code{-fdump-ada-spec} switch, which will generate Ada -spec files for the header files specified on the command line, and all -header files needed by these files transitively. For example: - -@example -$ gcc -c -fdump-ada-spec -C /usr/include/time.h -$ gcc -c *.ads -@end example - -will generate, under GNU/Linux, the following files: @code{time_h.ads}, -@code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which -correspond to the files @code{/usr/include/time.h}, -@code{/usr/include/bits/time.h}, etc…, and then compile these Ada specs. -That is to say, the name of the Ada specs is in keeping with the relative path -under @code{/usr/include/} of the header files. This behavior is specific to -paths ending with @code{/include/}; in all the other cases, the name of the -Ada specs is derived from the simple name of the header files instead. - -The @code{-C} switch tells @code{gcc} to extract comments from headers, -and will attempt to generate corresponding Ada comments. - -If you want to generate a single Ada file and not the transitive closure, you -can use instead the @code{-fdump-ada-spec-slim} switch. - -You can optionally specify a parent unit, of which all generated units will -be children, using @code{-fada-spec-parent=`unit'}. - -The simple @code{gcc}-based command works only for C headers. For C++ headers -you need to use either the @code{g++} command or the combination @code{gcc -x c++}. - -In some cases, the generated bindings will be more complete or more meaningful -when defining some macros, which you can do via the @code{-D} switch. This -is for example the case with @code{Xlib.h} under GNU/Linux: - -@example -$ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h -@end example - -The above will generate more complete bindings than a straight call without -the @code{-DXLIB_ILLEGAL_ACCESS} switch. - -In other cases, it is not possible to parse a header file in a stand-alone -manner, because other include files need to be included first. In this -case, the solution is to create a small header file including the needed -@code{#include} and possible @code{#define} directives. For example, to -generate Ada bindings for @code{readline/readline.h}, you need to first -include @code{stdio.h}, so you can create a file with the following two -lines in e.g. @code{readline1.h}: - -@example -#include -#include -@end example - -and then generate Ada bindings from this file: - -@example -$ gcc -c -fdump-ada-spec readline1.h -@end example - -@node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers -@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b3}@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{b4} -@subsubsection Generating Bindings for C++ Headers - - -Generating bindings for C++ headers is done using the same options, always -with the `g++' compiler. Note that generating Ada spec from C++ headers is a -much more complex job and support for C++ headers is much more limited that -support for C headers. As a result, you will need to modify the resulting -bindings by hand more extensively when using C++ headers. - -In this mode, C++ classes will be mapped to Ada tagged types, constructors -will be mapped using the @code{CPP_Constructor} pragma, and when possible, -multiple inheritance of abstract classes will be mapped to Ada interfaces -(see the `Interfacing to C++' section in the @cite{GNAT Reference Manual} -for additional information on interfacing to C++). - -For example, given the following C++ header file: - -@example -class Carnivore @{ -public: - virtual int Number_Of_Teeth () = 0; -@}; - -class Domestic @{ -public: - virtual void Set_Owner (char* Name) = 0; -@}; - -class Animal @{ -public: - int Age_Count; - virtual void Set_Age (int New_Age); -@}; - -class Dog : Animal, Carnivore, Domestic @{ - public: - int Tooth_Count; - char *Owner; - - virtual int Number_Of_Teeth (); - virtual void Set_Owner (char* Name); - - Dog(); -@}; -@end example - -The corresponding Ada code is generated: - -@example -package Class_Carnivore is - type Carnivore is limited interface; - pragma Import (CPP, Carnivore); - - function Number_Of_Teeth (this : access Carnivore) return int is abstract; -end; -use Class_Carnivore; - -package Class_Domestic is - type Domestic is limited interface; - pragma Import (CPP, Domestic); - - procedure Set_Owner - (this : access Domestic; - Name : Interfaces.C.Strings.chars_ptr) is abstract; -end; -use Class_Domestic; - -package Class_Animal is - type Animal is tagged limited record - Age_Count : aliased int; - end record; - pragma Import (CPP, Animal); - - procedure Set_Age (this : access Animal; New_Age : int); - pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); -end; -use Class_Animal; - -package Class_Dog is - type Dog is new Animal and Carnivore and Domestic with record - Tooth_Count : aliased int; - Owner : Interfaces.C.Strings.chars_ptr; - end record; - pragma Import (CPP, Dog); - - function Number_Of_Teeth (this : access Dog) return int; - pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); - - procedure Set_Owner - (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); - pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); - - function New_Dog return Dog; - pragma CPP_Constructor (New_Dog); - pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); -end; -use Class_Dog; -@end example - -@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers -@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{b6} -@subsubsection Switches - - -@geindex -fdump-ada-spec (gcc) - - -@table @asis - -@item @code{-fdump-ada-spec} - -Generate Ada spec files for the given header files transitively (including -all header files that these headers depend upon). -@end table - -@geindex -fdump-ada-spec-slim (gcc) - - -@table @asis - -@item @code{-fdump-ada-spec-slim} - -Generate Ada spec files for the header files specified on the command line -only. -@end table - -@geindex -fada-spec-parent (gcc) - - -@table @asis - -@item @code{-fada-spec-parent=`unit'} - -Specifies that all files generated by @code{-fdump-ada-spec} are -to be child units of the specified parent unit. -@end table - -@geindex -C (gcc) - - -@table @asis - -@item @code{-C} - -Extract comments from headers and generate Ada comments in the Ada spec files. -@end table - -@node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming -@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8} -@subsection Generating C Headers for Ada Specifications - - -@geindex Binding generation (for Ada specs) - -@geindex C headers (binding generation) - -GNAT includes a C header generator for Ada specifications which supports -Ada types that have a direct mapping to C types. This includes in particular -support for: - - -@itemize * - -@item -Scalar types - -@item -Constrained arrays - -@item -Records (untagged) - -@item -Composition of the above types - -@item -Constant declarations - -@item -Object declarations - -@item -Subprogram declarations -@end itemize - -@menu -* Running the C Header Generator:: - -@end menu - -@node Running the C Header Generator,,,Generating C Headers for Ada Specifications -@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{b9} -@subsubsection Running the C Header Generator - - -The C header generator is part of the GNAT compiler and can be invoked via -the @code{-gnatceg} combination of switches, which will generate a @code{.h} -file corresponding to the given input file (Ada spec or body). Note that -only spec files are processed in any case, so giving a spec or a body file -as input is equivalent. For example: - -@example -$ gcc -c -gnatceg pack1.ads -@end example - -will generate a self-contained file called @code{pack1.h} including -common definitions from the Ada Standard package, followed by the -definitions included in @code{pack1.ads}, as well as all the other units -withed by this file. - -For instance, given the following Ada files: - -@example -package Pack2 is - type Int is range 1 .. 10; -end Pack2; -@end example - -@example -with Pack2; - -package Pack1 is - type Rec is record - Field1, Field2 : Pack2.Int; - end record; - - Global : Rec := (1, 2); - - procedure Proc1 (R : Rec); - procedure Proc2 (R : in out Rec); -end Pack1; -@end example - -The above @code{gcc} command will generate the following @code{pack1.h} file: - -@example -/* Standard definitions skipped */ -#ifndef PACK2_ADS -#define PACK2_ADS -typedef short_short_integer pack2__TintB; -typedef pack2__TintB pack2__int; -#endif /* PACK2_ADS */ - -#ifndef PACK1_ADS -#define PACK1_ADS -typedef struct _pack1__rec @{ - pack2__int field1; - pack2__int field2; -@} pack1__rec; -extern pack1__rec pack1__global; -extern void pack1__proc1(const pack1__rec r); -extern void pack1__proc2(pack1__rec *r); -#endif /* PACK1_ADS */ -@end example - -You can then @code{include} @code{pack1.h} from a C source file and use the types, -call subprograms, reference objects, and constants. - -@node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d}@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{ba} -@section GNAT and Other Compilation Models - - -This section compares the GNAT model with the approaches taken in -other environments, first the C/C++ model and then the mechanism that -has been used in other Ada systems, in particular those traditionally -used for Ada 83. - -@menu -* Comparison between GNAT and C/C++ Compilation Models:: -* Comparison between GNAT and Conventional Ada Library Models:: - -@end menu - -@node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models -@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc} -@subsection Comparison between GNAT and C/C++ Compilation Models - - -The GNAT model of compilation is close to the C and C++ models. You can -think of Ada specs as corresponding to header files in C. As in C, you -don’t need to compile specs; they are compiled when they are used. The -Ada `with' is similar in effect to the @code{#include} of a C -header. - -One notable difference is that, in Ada, you may compile specs separately -to check them for semantic and syntactic accuracy. This is not always -possible with C headers because they are fragments of programs that have -less specific syntactic or semantic rules. - -The other major difference is the requirement for running the binder, -which performs two important functions. First, it checks for -consistency. In C or C++, the only defense against assembling -inconsistent programs lies outside the compiler, in a makefile, for -example. The binder satisfies the Ada requirement that it be impossible -to construct an inconsistent program when the compiler is used in normal -mode. - -@geindex Elaboration order control - -The other important function of the binder is to deal with elaboration -issues. There are also elaboration issues in C++ that are handled -automatically. This automatic handling has the advantage of being -simpler to use, but the C++ programmer has no control over elaboration. -Where @code{gnatbind} might complain there was no valid order of -elaboration, a C++ compiler would simply construct a program that -malfunctioned at run time. - -@node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models -@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{be} -@subsection Comparison between GNAT and Conventional Ada Library Models - - -This section is intended for Ada programmers who have -used an Ada compiler implementing the traditional Ada library -model, as described in the Ada Reference Manual. - -@geindex GNAT library - -In GNAT, there is no ‘library’ in the normal sense. Instead, the set of -source files themselves acts as the library. Compiling Ada programs does -not generate any centralized information, but rather an object file and -a ALI file, which are of interest only to the binder and linker. -In a traditional system, the compiler reads information not only from -the source file being compiled, but also from the centralized library. -This means that the effect of a compilation depends on what has been -previously compiled. In particular: - - -@itemize * - -@item -When a unit is `with'ed, the unit seen by the compiler corresponds -to the version of the unit most recently compiled into the library. - -@item -Inlining is effective only if the necessary body has already been -compiled into the library. - -@item -Compiling a unit may obsolete other units in the library. -@end itemize - -In GNAT, compiling one unit never affects the compilation of any other -units because the compiler reads only source files. Only changes to source -files can affect the results of a compilation. In particular: - - -@itemize * - -@item -When a unit is `with'ed, the unit seen by the compiler corresponds -to the source version of the unit that is currently accessible to the -compiler. - -@geindex Inlining - -@item -Inlining requires the appropriate source files for the package or -subprogram bodies to be available to the compiler. Inlining is always -effective, independent of the order in which units are compiled. - -@item -Compiling a unit never affects any other compilations. The editing of -sources may cause previous compilations to be out of date if they -depended on the source file being modified. -@end itemize - -The most important result of these differences is that order of compilation -is never significant in GNAT. There is no situation in which one is -required to do one compilation before another. What shows up as order of -compilation requirements in the traditional Ada library becomes, in -GNAT, simple source dependencies; in other words, there is only a set -of rules saying what source files must be present when a file is -compiled. - -@node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model -@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{bf}@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{2e} -@section Using GNAT Files with External Tools - - -This section explains how files that are produced by GNAT may be -used with tools designed for other languages. - -@menu -* Using Other Utility Programs with GNAT:: -* The External Symbol Naming Scheme of GNAT:: - -@end menu - -@node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools -@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{c0}@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{c1} -@subsection Using Other Utility Programs with GNAT - - -The object files generated by GNAT are in standard system format and in -particular the debugging information uses this format. This means -programs generated by GNAT can be used with existing utilities that -depend on these formats. - -In general, any utility program that works with C will also often work with -Ada programs generated by GNAT. This includes software utilities such as -gprof (a profiling program), gdb (the FSF debugger), and utilities such -as Purify. - -@node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools -@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{c2}@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{c3} -@subsection The External Symbol Naming Scheme of GNAT - - -In order to interpret the output from GNAT, when using tools that are -originally intended for use with other languages, it is useful to -understand the conventions used to generate link names from the Ada -entity names. - -All link names are in all lowercase letters. With the exception of library -procedure names, the mechanism used is simply to use the full expanded -Ada name with dots replaced by double underscores. For example, suppose -we have the following package spec: - -@example -package QRS is - MN : Integer; -end QRS; -@end example - -@geindex pragma Export - -The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so -the corresponding link name is @code{qrs__mn}. -Of course if a @code{pragma Export} is used this may be overridden: - -@example -package Exports is - Var1 : Integer; - pragma Export (Var1, C, External_Name => "var1_name"); - Var2 : Integer; - pragma Export (Var2, C, Link_Name => "var2_link_name"); -end Exports; -@end example - -In this case, the link name for @code{Var1} is whatever link name the -C compiler would assign for the C function @code{var1_name}. This typically -would be either @code{var1_name} or @code{_var1_name}, depending on operating -system conventions, but other possibilities exist. The link name for -@code{Var2} is @code{var2_link_name}, and this is not operating system -dependent. - -One exception occurs for library level procedures. A potential ambiguity -arises between the required name @code{_main} for the C main program, -and the name we would otherwise assign to an Ada library level procedure -called @code{Main} (which might well not be the main program). - -To avoid this ambiguity, we attach the prefix @code{_ada_} to such -names. So if we have a library level procedure such as: - -@example -procedure Hello (S : String); -@end example - -the external name of this procedure will be @code{_ada_hello}. - -@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit - -@node Building Executable Programs with GNAT,GNAT Utility Programs,The GNAT Compilation Model,Top -@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{c4}@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{c5} -@chapter Building Executable Programs with GNAT - - -This chapter describes first the gnatmake tool -(@ref{c6,,Building with gnatmake}), -which automatically determines the set of sources -needed by an Ada compilation unit and executes the necessary -(re)compilations, binding and linking. -It also explains how to use each tool individually: the -compiler (gcc, see @ref{c7,,Compiling with gcc}), -binder (gnatbind, see @ref{c8,,Binding with gnatbind}), -and linker (gnatlink, see @ref{c9,,Linking with gnatlink}) -to build executable programs. -Finally, this chapter provides examples of -how to make use of the general GNU make mechanism -in a GNAT context (see @ref{70,,Using the GNU make Utility}). - - -@menu -* Building with gnatmake:: -* Compiling with gcc:: -* Compiler Switches:: -* Linker Switches:: -* Binding with gnatbind:: -* Linking with gnatlink:: -* Using the GNU make Utility:: - -@end menu - -@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{ca}@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{c6} -@section Building with @code{gnatmake} - - -@geindex gnatmake - -A typical development cycle when working on an Ada program consists of -the following steps: - - -@enumerate - -@item -Edit some sources to fix bugs; - -@item -Add enhancements; - -@item -Compile all sources affected; - -@item -Rebind and relink; and - -@item -Test. -@end enumerate - -@geindex Dependency rules (compilation) - -The third step in particular can be tricky, because not only do the modified -files have to be compiled, but any files depending on these files must also be -recompiled. The dependency rules in Ada can be quite complex, especially -in the presence of overloading, @code{use} clauses, generics and inlined -subprograms. - -@code{gnatmake} automatically takes care of the third and fourth steps -of this process. It determines which sources need to be compiled, -compiles them, and binds and links the resulting object files. - -Unlike some other Ada make programs, the dependencies are always -accurately recomputed from the new sources. The source based approach of -the GNAT compilation model makes this possible. This means that if -changes to the source program cause corresponding changes in -dependencies, they will always be tracked exactly correctly by -@code{gnatmake}. - -Note that for advanced forms of project structure, we recommend creating -a project file as explained in the `GNAT_Project_Manager' chapter in the -`GPRbuild User’s Guide', and using the -@code{gprbuild} tool which supports building with project files and works similarly -to @code{gnatmake}. - -@menu -* Running gnatmake:: -* Switches for gnatmake:: -* Mode Switches for gnatmake:: -* Notes on the Command Line:: -* How gnatmake Works:: -* Examples of gnatmake Usage:: - -@end menu - -@node Running gnatmake,Switches for gnatmake,,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{cb}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{cc} -@subsection Running @code{gnatmake} - - -The usual form of the @code{gnatmake} command is - -@example -$ gnatmake [] [] [] -@end example - -The only required argument is one @code{file_name}, which specifies -a compilation unit that is a main program. Several @code{file_names} can be -specified: this will result in several executables being built. -If @code{switches} are present, they can be placed before the first -@code{file_name}, between @code{file_names} or after the last @code{file_name}. -If @code{mode_switches} are present, they must always be placed after -the last @code{file_name} and all @code{switches}. - -If you are using standard file extensions (@code{.adb} and -@code{.ads}), then the -extension may be omitted from the @code{file_name} arguments. However, if -you are using non-standard extensions, then it is required that the -extension be given. A relative or absolute directory path can be -specified in a @code{file_name}, in which case, the input source file will -be searched for in the specified directory only. Otherwise, the input -source file will first be searched in the directory where -@code{gnatmake} was invoked and if it is not found, it will be search on -the source path of the compiler as described in -@ref{73,,Search Paths and the Run-Time Library (RTL)}. - -All @code{gnatmake} output (except when you specify @code{-M}) is sent to -@code{stderr}. The output produced by the -@code{-M} switch is sent to @code{stdout}. - -@node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{cd}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{ce} -@subsection Switches for @code{gnatmake} - - -You may specify any of the following switches to @code{gnatmake}: - -@geindex --version (gnatmake) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatmake) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. -@end table - -@geindex -P (gnatmake) - - -@table @asis - -@item @code{-P`project'} - -Build GNAT project file @code{project} using GPRbuild. When this switch is -present, all other command-line switches are treated as GPRbuild switches -and not @code{gnatmake} switches. -@end table - -@c -- Comment: -@c :ref:`gnatmake_and_Project_Files`. - -@geindex --GCC=compiler_name (gnatmake) - - -@table @asis - -@item @code{--GCC=`compiler_name'} - -Program used for compiling. The default is @code{gcc}. You need to use -quotes around @code{compiler_name} if @code{compiler_name} contains -spaces or other separator characters. -As an example @code{--GCC="foo -x -y"} -will instruct @code{gnatmake} to use @code{foo -x -y} as your -compiler. A limitation of this syntax is that the name and path name of -the executable itself must not include any embedded spaces. Note that -switch @code{-c} is always inserted after your command name. Thus in the -above example the compiler command that will be used by @code{gnatmake} -will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are -used, only the last @code{compiler_name} is taken into account. However, -all the additional switches are also taken into account. Thus, -@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to -@code{--GCC="bar -x -y -z -t"}. -@end table - -@geindex --GNATBIND=binder_name (gnatmake) - - -@table @asis - -@item @code{--GNATBIND=`binder_name'} - -Program used for binding. The default is @code{gnatbind}. You need to -use quotes around @code{binder_name} if @code{binder_name} contains spaces -or other separator characters. -As an example @code{--GNATBIND="bar -x -y"} -will instruct @code{gnatmake} to use @code{bar -x -y} as your -binder. Binder switches that are normally appended by @code{gnatmake} -to @code{gnatbind} are now appended to the end of @code{bar -x -y}. -A limitation of this syntax is that the name and path name of the executable -itself must not include any embedded spaces. -@end table - -@geindex --GNATLINK=linker_name (gnatmake) - - -@table @asis - -@item @code{--GNATLINK=`linker_name'} - -Program used for linking. The default is @code{gnatlink}. You need to -use quotes around @code{linker_name} if @code{linker_name} contains spaces -or other separator characters. -As an example @code{--GNATLINK="lan -x -y"} -will instruct @code{gnatmake} to use @code{lan -x -y} as your -linker. Linker switches that are normally appended by @code{gnatmake} to -@code{gnatlink} are now appended to the end of @code{lan -x -y}. -A limitation of this syntax is that the name and path name of the executable -itself must not include any embedded spaces. - -@item @code{--create-map-file} - -When linking an executable, create a map file. The name of the map file -has the same name as the executable with extension “.map”. - -@item @code{--create-map-file=`mapfile'} - -When linking an executable, create a map file with the specified name. -@end table - -@geindex --create-missing-dirs (gnatmake) - - -@table @asis - -@item @code{--create-missing-dirs} - -When using project files (@code{-P`project'}), automatically create -missing object directories, library directories and exec -directories. - -@item @code{--single-compile-per-obj-dir} - -Disallow simultaneous compilations in the same object directory when -project files are used. - -@item @code{--subdirs=`subdir'} - -Actual object directory of each project file is the subdirectory subdir of the -object directory specified or defaulted in the project file. - -@item @code{--unchecked-shared-lib-imports} - -By default, shared library projects are not allowed to import static library -projects. When this switch is used on the command line, this restriction is -relaxed. - -@item @code{--source-info=`source info file'} - -Specify a source info file. This switch is active only when project files -are used. If the source info file is specified as a relative path, then it is -relative to the object directory of the main project. If the source info file -does not exist, then after the Project Manager has successfully parsed and -processed the project files and found the sources, it creates the source info -file. If the source info file already exists and can be read successfully, -then the Project Manager will get all the needed information about the sources -from the source info file and will not look for them. This reduces the time -to process the project files, especially when looking for sources that take a -long time. If the source info file exists but cannot be parsed successfully, -the Project Manager will attempt to recreate it. If the Project Manager fails -to create the source info file, a message is issued, but gnatmake does not -fail. @code{gnatmake} “trusts” the source info file. This means that -if the source files have changed (addition, deletion, moving to a different -source directory), then the source info file need to be deleted and recreated. -@end table - -@geindex -a (gnatmake) - - -@table @asis - -@item @code{-a} - -Consider all files in the make process, even the GNAT internal system -files (for example, the predefined Ada library files), as well as any -locked files. Locked files are files whose ALI file is write-protected. -By default, -@code{gnatmake} does not check these files, -because the assumption is that the GNAT internal files are properly up -to date, and also that any write protected ALI files have been properly -installed. Note that if there is an installation problem, such that one -of these files is not up to date, it will be properly caught by the -binder. -You may have to specify this switch if you are working on GNAT -itself. The switch @code{-a} is also useful -in conjunction with @code{-f} -if you need to recompile an entire application, -including run-time files, using special configuration pragmas, -such as a @code{Normalize_Scalars} pragma. - -By default -@code{gnatmake -a} compiles all GNAT -internal files with -@code{gcc -c -gnatpg} rather than @code{gcc -c}. -@end table - -@geindex -b (gnatmake) - - -@table @asis - -@item @code{-b} - -Bind only. Can be combined with @code{-c} to do -compilation and binding, but no link. -Can be combined with @code{-l} -to do binding and linking. When not combined with -@code{-c} -all the units in the closure of the main program must have been previously -compiled and must be up to date. The root unit specified by @code{file_name} -may be given without extension, with the source extension or, if no GNAT -Project File is specified, with the ALI file extension. -@end table - -@geindex -c (gnatmake) - - -@table @asis - -@item @code{-c} - -Compile only. Do not perform binding, except when @code{-b} -is also specified. Do not perform linking, except if both -@code{-b} and -@code{-l} are also specified. -If the root unit specified by @code{file_name} is not a main unit, this is the -default. Otherwise @code{gnatmake} will attempt binding and linking -unless all objects are up to date and the executable is more recent than -the objects. -@end table - -@geindex -C (gnatmake) - - -@table @asis - -@item @code{-C} - -Use a temporary mapping file. A mapping file is a way to communicate -to the compiler two mappings: from unit names to file names (without -any directory information) and from file names to path names (with -full directory information). A mapping file can make the compiler’s -file searches faster, especially if there are many source directories, -or the sources are read over a slow network connection. If -@code{-P} is used, a mapping file is always used, so -@code{-C} is unnecessary; in this case the mapping file -is initially populated based on the project file. If -@code{-C} is used without -@code{-P}, -the mapping file is initially empty. Each invocation of the compiler -will add any newly accessed sources to the mapping file. -@end table - -@geindex -C= (gnatmake) - - -@table @asis - -@item @code{-C=`file'} - -Use a specific mapping file. The file, specified as a path name (absolute or -relative) by this switch, should already exist, otherwise the switch is -ineffective. The specified mapping file will be communicated to the compiler. -This switch is not compatible with a project file -(-P`file`) or with multiple compiling processes -(-jnnn, when nnn is greater than 1). -@end table - -@geindex -d (gnatmake) - - -@table @asis - -@item @code{-d} - -Display progress for each source, up to date or not, as a single line: - -@example -completed x out of y (zz%) -@end example - -If the file needs to be compiled this is displayed after the invocation of -the compiler. These lines are displayed even in quiet output mode. -@end table - -@geindex -D (gnatmake) - - -@table @asis - -@item @code{-D `dir'} - -Put all object files and ALI file in directory @code{dir}. -If the @code{-D} switch is not used, all object files -and ALI files go in the current working directory. - -This switch cannot be used when using a project file. -@end table - -@geindex -eI (gnatmake) - - -@table @asis - -@item @code{-eI`nnn'} - -Indicates that the main source is a multi-unit source and the rank of the unit -in the source file is nnn. nnn needs to be a positive number and a valid -index in the source. This switch cannot be used when @code{gnatmake} is -invoked for several mains. -@end table - -@geindex -eL (gnatmake) - -@geindex symbolic links - - -@table @asis - -@item @code{-eL} - -Follow all symbolic links when processing project files. -This should be used if your project uses symbolic links for files or -directories, but is not needed in other cases. - -@geindex naming scheme - -This also assumes that no directory matches the naming scheme for files (for -instance that you do not have a directory called “sources.ads” when using the -default GNAT naming scheme). - -When you do not have to use this switch (i.e., by default), gnatmake is able to -save a lot of system calls (several per source file and object file), which -can result in a significant speed up to load and manipulate a project file, -especially when using source files from a remote system. -@end table - -@geindex -eS (gnatmake) - - -@table @asis - -@item @code{-eS} - -Output the commands for the compiler, the binder and the linker -on standard output, -instead of standard error. -@end table - -@geindex -f (gnatmake) - - -@table @asis - -@item @code{-f} - -Force recompilations. Recompile all sources, even though some object -files may be up to date, but don’t recompile predefined or GNAT internal -files or locked files (files with a write-protected ALI file), -unless the @code{-a} switch is also specified. -@end table - -@geindex -F (gnatmake) - - -@table @asis - -@item @code{-F} - -When using project files, if some errors or warnings are detected during -parsing and verbose mode is not in effect (no use of switch --v), then error lines start with the full path name of the project -file, rather than its simple file name. -@end table - -@geindex -g (gnatmake) - - -@table @asis - -@item @code{-g} - -Enable debugging. This switch is simply passed to the compiler and to the -linker. -@end table - -@geindex -i (gnatmake) - - -@table @asis - -@item @code{-i} - -In normal mode, @code{gnatmake} compiles all object files and ALI files -into the current directory. If the @code{-i} switch is used, -then instead object files and ALI files that already exist are overwritten -in place. This means that once a large project is organized into separate -directories in the desired manner, then @code{gnatmake} will automatically -maintain and update this organization. If no ALI files are found on the -Ada object path (see @ref{73,,Search Paths and the Run-Time Library (RTL)}), -the new object and ALI files are created in the -directory containing the source being compiled. If another organization -is desired, where objects and sources are kept in different directories, -a useful technique is to create dummy ALI files in the desired directories. -When detecting such a dummy file, @code{gnatmake} will be forced to -recompile the corresponding source file, and it will be put the resulting -object and ALI files in the directory where it found the dummy file. -@end table - -@geindex -j (gnatmake) - -@geindex Parallel make - - -@table @asis - -@item @code{-j`n'} - -Use @code{n} processes to carry out the (re)compilations. On a multiprocessor -machine compilations will occur in parallel. If @code{n} is 0, then the -maximum number of parallel compilations is the number of core processors -on the platform. In the event of compilation errors, messages from various -compilations might get interspersed (but @code{gnatmake} will give you the -full ordered list of failing compiles at the end). If this is problematic, -rerun the make process with n set to 1 to get a clean list of messages. -@end table - -@geindex -k (gnatmake) - - -@table @asis - -@item @code{-k} - -Keep going. Continue as much as possible after a compilation error. To -ease the programmer’s task in case of compilation errors, the list of -sources for which the compile fails is given when @code{gnatmake} -terminates. - -If @code{gnatmake} is invoked with several @code{file_names} and with this -switch, if there are compilation errors when building an executable, -@code{gnatmake} will not attempt to build the following executables. -@end table - -@geindex -l (gnatmake) - - -@table @asis - -@item @code{-l} - -Link only. Can be combined with @code{-b} to binding -and linking. Linking will not be performed if combined with -@code{-c} -but not with @code{-b}. -When not combined with @code{-b} -all the units in the closure of the main program must have been previously -compiled and must be up to date, and the main program needs to have been bound. -The root unit specified by @code{file_name} -may be given without extension, with the source extension or, if no GNAT -Project File is specified, with the ALI file extension. -@end table - -@geindex -m (gnatmake) - - -@table @asis - -@item @code{-m} - -Specify that the minimum necessary amount of recompilations -be performed. In this mode @code{gnatmake} ignores time -stamp differences when the only -modifications to a source file consist in adding/removing comments, -empty lines, spaces or tabs. This means that if you have changed the -comments in a source file or have simply reformatted it, using this -switch will tell @code{gnatmake} not to recompile files that depend on it -(provided other sources on which these files depend have undergone no -semantic modifications). Note that the debugging information may be -out of date with respect to the sources if the @code{-m} switch causes -a compilation to be switched, so the use of this switch represents a -trade-off between compilation time and accurate debugging information. -@end table - -@geindex Dependencies -@geindex producing list - -@geindex -M (gnatmake) - - -@table @asis - -@item @code{-M} - -Check if all objects are up to date. If they are, output the object -dependences to @code{stdout} in a form that can be directly exploited in -a @code{Makefile}. By default, each source file is prefixed with its -(relative or absolute) directory name. This name is whatever you -specified in the various @code{-aI} -and @code{-I} switches. If you use -@code{gnatmake -M} @code{-q} -(see below), only the source file names, -without relative paths, are output. If you just specify the @code{-M} -switch, dependencies of the GNAT internal system files are omitted. This -is typically what you want. If you also specify -the @code{-a} switch, -dependencies of the GNAT internal files are also listed. Note that -dependencies of the objects in external Ada libraries (see -switch @code{-aL`dir'} in the following list) -are never reported. -@end table - -@geindex -n (gnatmake) - - -@table @asis - -@item @code{-n} - -Don’t compile, bind, or link. Checks if all objects are up to date. -If they are not, the full name of the first file that needs to be -recompiled is printed. -Repeated use of this option, followed by compiling the indicated source -file, will eventually result in recompiling all required units. -@end table - -@geindex -o (gnatmake) - - -@table @asis - -@item @code{-o `exec_name'} - -Output executable name. The name of the final executable program will be -@code{exec_name}. If the @code{-o} switch is omitted the default -name for the executable will be the name of the input file in appropriate form -for an executable file on the host system. - -This switch cannot be used when invoking @code{gnatmake} with several -@code{file_names}. -@end table - -@geindex -p (gnatmake) - - -@table @asis - -@item @code{-p} - -Same as @code{--create-missing-dirs} -@end table - -@geindex -q (gnatmake) - - -@table @asis - -@item @code{-q} - -Quiet. When this flag is not set, the commands carried out by -@code{gnatmake} are displayed. -@end table - -@geindex -s (gnatmake) - - -@table @asis - -@item @code{-s} - -Recompile if compiler switches have changed since last compilation. -All compiler switches but -I and -o are taken into account in the -following way: -orders between different ‘first letter’ switches are ignored, but -orders between same switches are taken into account. For example, -@code{-O -O2} is different than @code{-O2 -O}, but @code{-g -O} -is equivalent to @code{-O -g}. - -This switch is recommended when Integrated Preprocessing is used. -@end table - -@geindex -u (gnatmake) - - -@table @asis - -@item @code{-u} - -Unique. Recompile at most the main files. It implies -c. Combined with --f, it is equivalent to calling the compiler directly. Note that using --u with a project file and no main has a special meaning. -@end table - -@c --Comment -@c (See :ref:`Project_Files_and_Main_Subprograms`.) - -@geindex -U (gnatmake) - - -@table @asis - -@item @code{-U} - -When used without a project file or with one or several mains on the command -line, is equivalent to -u. When used with a project file and no main -on the command line, all sources of all project files are checked and compiled -if not up to date, and libraries are rebuilt, if necessary. -@end table - -@geindex -v (gnatmake) - - -@table @asis - -@item @code{-v} - -Verbose. Display the reason for all recompilations @code{gnatmake} -decides are necessary, with the highest verbosity level. -@end table - -@geindex -vl (gnatmake) - - -@table @asis - -@item @code{-vl} - -Verbosity level Low. Display fewer lines than in verbosity Medium. -@end table - -@geindex -vm (gnatmake) - - -@table @asis - -@item @code{-vm} - -Verbosity level Medium. Potentially display fewer lines than in verbosity High. -@end table - -@geindex -vm (gnatmake) - - -@table @asis - -@item @code{-vh} - -Verbosity level High. Equivalent to -v. - -@item @code{-vP`x'} - -Indicate the verbosity of the parsing of GNAT project files. -See @ref{cf,,Switches Related to Project Files}. -@end table - -@geindex -x (gnatmake) - - -@table @asis - -@item @code{-x} - -Indicate that sources that are not part of any Project File may be compiled. -Normally, when using Project Files, only sources that are part of a Project -File may be compile. When this switch is used, a source outside of all Project -Files may be compiled. The ALI file and the object file will be put in the -object directory of the main Project. The compilation switches used will only -be those specified on the command line. Even when -@code{-x} is used, mains specified on the -command line need to be sources of a project file. - -@item @code{-X`name'=`value'} - -Indicate that external variable @code{name} has the value @code{value}. -The Project Manager will use this value for occurrences of -@code{external(name)} when parsing the project file. -@ref{cf,,Switches Related to Project Files}. -@end table - -@geindex -z (gnatmake) - - -@table @asis - -@item @code{-z} - -No main subprogram. Bind and link the program even if the unit name -given on the command line is a package name. The resulting executable -will execute the elaboration routines of the package and its closure, -then the finalization routines. -@end table - -@subsubheading GCC switches - - -Any uppercase or multi-character switch that is not a @code{gnatmake} switch -is passed to @code{gcc} (e.g., @code{-O}, @code{-gnato,} etc.) - -@subsubheading Source and library search path switches - - -@geindex -aI (gnatmake) - - -@table @asis - -@item @code{-aI`dir'} - -When looking for source files also look in directory @code{dir}. -The order in which source files search is undertaken is -described in @ref{73,,Search Paths and the Run-Time Library (RTL)}. -@end table - -@geindex -aL (gnatmake) - - -@table @asis - -@item @code{-aL`dir'} - -Consider @code{dir} as being an externally provided Ada library. -Instructs @code{gnatmake} to skip compilation units whose @code{.ALI} -files have been located in directory @code{dir}. This allows you to have -missing bodies for the units in @code{dir} and to ignore out of date bodies -for the same units. You still need to specify -the location of the specs for these units by using the switches -@code{-aI`dir'} or @code{-I`dir'}. -Note: this switch is provided for compatibility with previous versions -of @code{gnatmake}. The easier method of causing standard libraries -to be excluded from consideration is to write-protect the corresponding -ALI files. -@end table - -@geindex -aO (gnatmake) - - -@table @asis - -@item @code{-aO`dir'} - -When searching for library and object files, look in directory -@code{dir}. The order in which library files are searched is described in -@ref{76,,Search Paths for gnatbind}. -@end table - -@geindex Search paths -@geindex for gnatmake - -@geindex -A (gnatmake) - - -@table @asis - -@item @code{-A`dir'} - -Equivalent to @code{-aL`dir'} @code{-aI`dir'}. - -@geindex -I (gnatmake) - -@item @code{-I`dir'} - -Equivalent to @code{-aO`dir' -aI`dir'}. -@end table - -@geindex -I- (gnatmake) - -@geindex Source files -@geindex suppressing search - - -@table @asis - -@item @code{-I-} - -Do not look for source files in the directory containing the source -file named in the command line. -Do not look for ALI or object files in the directory -where @code{gnatmake} was invoked. -@end table - -@geindex -L (gnatmake) - -@geindex Linker libraries - - -@table @asis - -@item @code{-L`dir'} - -Add directory @code{dir} to the list of directories in which the linker -will search for libraries. This is equivalent to -@code{-largs} @code{-L`dir'}. -Furthermore, under Windows, the sources pointed to by the libraries path -set in the registry are not searched for. -@end table - -@geindex -nostdinc (gnatmake) - - -@table @asis - -@item @code{-nostdinc} - -Do not look for source files in the system default directory. -@end table - -@geindex -nostdlib (gnatmake) - - -@table @asis - -@item @code{-nostdlib} - -Do not look for library files in the system default directory. -@end table - -@geindex --RTS (gnatmake) - - -@table @asis - -@item @code{--RTS=`rts-path'} - -Specifies the default location of the run-time library. GNAT looks for the -run-time -in the following directories, and stops as soon as a valid run-time is found -(@code{adainclude} or @code{ada_source_path}, and @code{adalib} or -@code{ada_object_path} present): - - -@itemize * - -@item -`/$rts_path' - -@item -`/$rts_path' - -@item -`/rts-$rts_path' - -@item -The selected path is handled like a normal RTS path. -@end itemize -@end table - -@node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{d0}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{d1} -@subsection Mode Switches for @code{gnatmake} - - -The mode switches (referred to as @code{mode_switches}) allow the -inclusion of switches that are to be passed to the compiler itself, the -binder or the linker. The effect of a mode switch is to cause all -subsequent switches up to the end of the switch list, or up to the next -mode switch, to be interpreted as switches to be passed on to the -designated component of GNAT. - -@geindex -cargs (gnatmake) - - -@table @asis - -@item @code{-cargs `switches'} - -Compiler switches. Here @code{switches} is a list of switches -that are valid switches for @code{gcc}. They will be passed on to -all compile steps performed by @code{gnatmake}. -@end table - -@geindex -bargs (gnatmake) - - -@table @asis - -@item @code{-bargs `switches'} - -Binder switches. Here @code{switches} is a list of switches -that are valid switches for @code{gnatbind}. They will be passed on to -all bind steps performed by @code{gnatmake}. -@end table - -@geindex -largs (gnatmake) - - -@table @asis - -@item @code{-largs `switches'} - -Linker switches. Here @code{switches} is a list of switches -that are valid switches for @code{gnatlink}. They will be passed on to -all link steps performed by @code{gnatmake}. -@end table - -@geindex -margs (gnatmake) - - -@table @asis - -@item @code{-margs `switches'} - -Make switches. The switches are directly interpreted by @code{gnatmake}, -regardless of any previous occurrence of @code{-cargs}, @code{-bargs} -or @code{-largs}. -@end table - -@node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{d2}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{d3} -@subsection Notes on the Command Line - - -This section contains some additional useful notes on the operation -of the @code{gnatmake} command. - -@geindex Recompilation (by gnatmake) - - -@itemize * - -@item -If @code{gnatmake} finds no ALI files, it recompiles the main program -and all other units required by the main program. -This means that @code{gnatmake} -can be used for the initial compile, as well as during subsequent steps of -the development cycle. - -@item -If you enter @code{gnatmake foo.adb}, where @code{foo} -is a subunit or body of a generic unit, @code{gnatmake} recompiles -@code{foo.adb} (because it finds no ALI) and stops, issuing a -warning. - -@item -In @code{gnatmake} the switch @code{-I} -is used to specify both source and -library file paths. Use @code{-aI} -instead if you just want to specify -source paths only and @code{-aO} -if you want to specify library paths -only. - -@item -@code{gnatmake} will ignore any files whose ALI file is write-protected. -This may conveniently be used to exclude standard libraries from -consideration and in particular it means that the use of the -@code{-f} switch will not recompile these files -unless @code{-a} is also specified. - -@item -@code{gnatmake} has been designed to make the use of Ada libraries -particularly convenient. Assume you have an Ada library organized -as follows: `obj-dir' contains the objects and ALI files for -of your Ada compilation units, -whereas `include-dir' contains the -specs of these units, but no bodies. Then to compile a unit -stored in @code{main.adb}, which uses this Ada library you would just type: - -@example -$ gnatmake -aI`include-dir` -aL`obj-dir` main -@end example - -@item -Using @code{gnatmake} along with the @code{-m (minimal recompilation)} -switch provides a mechanism for avoiding unnecessary recompilations. Using -this switch, -you can update the comments/format of your -source files without having to recompile everything. Note, however, that -adding or deleting lines in a source files may render its debugging -info obsolete. If the file in question is a spec, the impact is rather -limited, as that debugging info will only be useful during the -elaboration phase of your program. For bodies the impact can be more -significant. In all events, your debugger will warn you if a source file -is more recent than the corresponding object, and alert you to the fact -that the debugging information may be out of date. -@end itemize - -@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{d4}@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{d5} -@subsection How @code{gnatmake} Works - - -Generally @code{gnatmake} automatically performs all necessary -recompilations and you don’t need to worry about how it works. However, -it may be useful to have some basic understanding of the @code{gnatmake} -approach and in particular to understand how it uses the results of -previous compilations without incorrectly depending on them. - -First a definition: an object file is considered `up to date' if the -corresponding ALI file exists and if all the source files listed in the -dependency section of this ALI file have time stamps matching those in -the ALI file. This means that neither the source file itself nor any -files that it depends on have been modified, and hence there is no need -to recompile this file. - -@code{gnatmake} works by first checking if the specified main unit is up -to date. If so, no compilations are required for the main unit. If not, -@code{gnatmake} compiles the main program to build a new ALI file that -reflects the latest sources. Then the ALI file of the main unit is -examined to find all the source files on which the main program depends, -and @code{gnatmake} recursively applies the above procedure on all these -files. - -This process ensures that @code{gnatmake} only trusts the dependencies -in an existing ALI file if they are known to be correct. Otherwise it -always recompiles to determine a new, guaranteed accurate set of -dependencies. As a result the program is compiled ‘upside down’ from what may -be more familiar as the required order of compilation in some other Ada -systems. In particular, clients are compiled before the units on which -they depend. The ability of GNAT to compile in any order is critical in -allowing an order of compilation to be chosen that guarantees that -@code{gnatmake} will recompute a correct set of new dependencies if -necessary. - -When invoking @code{gnatmake} with several @code{file_names}, if a unit is -imported by several of the executables, it will be recompiled at most once. - -Note: when using non-standard naming conventions -(@ref{1c,,Using Other File Names}), changing through a configuration pragmas -file the version of a source and invoking @code{gnatmake} to recompile may -have no effect, if the previous version of the source is still accessible -by @code{gnatmake}. It may be necessary to use the switch --f. - -@node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake -@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{d6}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{d7} -@subsection Examples of @code{gnatmake} Usage - - - -@table @asis - -@item `gnatmake hello.adb' - -Compile all files necessary to bind and link the main program -@code{hello.adb} (containing unit @code{Hello}) and bind and link the -resulting object files to generate an executable file @code{hello}. - -@item `gnatmake main1 main2 main3' - -Compile all files necessary to bind and link the main programs -@code{main1.adb} (containing unit @code{Main1}), @code{main2.adb} -(containing unit @code{Main2}) and @code{main3.adb} -(containing unit @code{Main3}) and bind and link the resulting object files -to generate three executable files @code{main1}, -@code{main2} and @code{main3}. - -@item `gnatmake -q Main_Unit -cargs -O2 -bargs -l' - -Compile all files necessary to bind and link the main program unit -@code{Main_Unit} (from file @code{main_unit.adb}). All compilations will -be done with optimization level 2 and the order of elaboration will be -listed by the binder. @code{gnatmake} will operate in quiet mode, not -displaying commands it is executing. -@end table - -@node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{c7}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{d8} -@section Compiling with @code{gcc} - - -This section discusses how to compile Ada programs using the @code{gcc} -command. It also describes the set of switches -that can be used to control the behavior of the compiler. - -@menu -* Compiling Programs:: -* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. -* Order of Compilation Issues:: -* Examples:: - -@end menu - -@node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc -@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{d9}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{da} -@subsection Compiling Programs - - -The first step in creating an executable program is to compile the units -of the program using the @code{gcc} command. You must compile the -following files: - - -@itemize * - -@item -the body file (@code{.adb}) for a library level subprogram or generic -subprogram - -@item -the spec file (@code{.ads}) for a library level package or generic -package that has no body - -@item -the body file (@code{.adb}) for a library level package -or generic package that has a body -@end itemize - -You need `not' compile the following files - - -@itemize * - -@item -the spec of a library unit which has a body - -@item -subunits -@end itemize - -because they are compiled as part of compiling related units. GNAT -package specs -when the corresponding body is compiled, and subunits when the parent is -compiled. - -@geindex cannot generate code - -If you attempt to compile any of these files, you will get one of the -following error messages (where @code{fff} is the name of the file you -compiled): - -@quotation - -@example -cannot generate code for file `@w{`}fff`@w{`} (package spec) -to check package spec, use -gnatc - -cannot generate code for file `@w{`}fff`@w{`} (missing subunits) -to check parent unit, use -gnatc - -cannot generate code for file `@w{`}fff`@w{`} (subprogram spec) -to check subprogram spec, use -gnatc - -cannot generate code for file `@w{`}fff`@w{`} (subunit) -to check subunit, use -gnatc -@end example -@end quotation - -As indicated by the above error messages, if you want to submit -one of these files to the compiler to check for correct semantics -without generating code, then use the @code{-gnatc} switch. - -The basic command for compiling a file containing an Ada unit is: - -@example -$ gcc -c [switches] -@end example - -where @code{file name} is the name of the Ada file (usually -having an extension @code{.ads} for a spec or @code{.adb} for a body). -You specify the -@code{-c} switch to tell @code{gcc} to compile, but not link, the file. -The result of a successful compilation is an object file, which has the -same name as the source file but an extension of @code{.o} and an Ada -Library Information (ALI) file, which also has the same name as the -source file, but with @code{.ali} as the extension. GNAT creates these -two output files in the current directory, but you may specify a source -file in any directory using an absolute or relative path specification -containing the directory information. - -TESTING: the @code{--foobar`NN'} switch - -@geindex gnat1 - -@code{gcc} is actually a driver program that looks at the extensions of -the file arguments and loads the appropriate compiler. For example, the -GNU C compiler is @code{cc1}, and the Ada compiler is @code{gnat1}. -These programs are in directories known to the driver program (in some -configurations via environment variables you set), but need not be in -your path. The @code{gcc} driver also calls the assembler and any other -utilities needed to complete the generation of the required object -files. - -It is possible to supply several file names on the same @code{gcc} -command. This causes @code{gcc} to call the appropriate compiler for -each file. For example, the following command lists two separate -files to be compiled: - -@example -$ gcc -c x.adb y.adb -@end example - -calls @code{gnat1} (the Ada compiler) twice to compile @code{x.adb} and -@code{y.adb}. -The compiler generates two object files @code{x.o} and @code{y.o} -and the two ALI files @code{x.ali} and @code{y.ali}. - -Any switches apply to all the files listed, see @ref{db,,Compiler Switches} for a -list of available @code{gcc} switches. - -@node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc -@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{73} -@subsection Search Paths and the Run-Time Library (RTL) - - -With the GNAT source-based library system, the compiler must be able to -find source files for units that are needed by the unit being compiled. -Search paths are used to guide this process. - -The compiler compiles one source file whose name must be given -explicitly on the command line. In other words, no searching is done -for this file. To find all other source files that are needed (the most -common being the specs of units), the compiler examines the following -directories, in the following order: - - -@itemize * - -@item -The directory containing the source file of the main unit being compiled -(the file name on the command line). - -@item -Each directory named by an @code{-I} switch given on the @code{gcc} -command line, in the order given. - -@geindex ADA_PRJ_INCLUDE_FILE - -@item -Each of the directories listed in the text file whose name is given -by the -@geindex ADA_PRJ_INCLUDE_FILE -@geindex environment variable; ADA_PRJ_INCLUDE_FILE -@code{ADA_PRJ_INCLUDE_FILE} environment variable. -@geindex ADA_PRJ_INCLUDE_FILE -@geindex environment variable; ADA_PRJ_INCLUDE_FILE -@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the gnat -driver when project files are used. It should not normally be set -by other means. - -@geindex ADA_INCLUDE_PATH - -@item -Each of the directories listed in the value of the -@geindex ADA_INCLUDE_PATH -@geindex environment variable; ADA_INCLUDE_PATH -@code{ADA_INCLUDE_PATH} environment variable. -Construct this value -exactly as the -@geindex PATH -@geindex environment variable; PATH -@code{PATH} environment variable: a list of directory -names separated by colons (semicolons when working with the NT version). - -@item -The content of the @code{ada_source_path} file which is part of the GNAT -installation tree and is used to store standard libraries such as the -GNAT Run Time Library (RTL) source files. -@ref{72,,Installing a library} -@end itemize - -Specifying the switch @code{-I-} -inhibits the use of the directory -containing the source file named in the command line. You can still -have this directory on your search path, but in this case it must be -explicitly requested with a @code{-I} switch. - -Specifying the switch @code{-nostdinc} -inhibits the search of the default location for the GNAT Run Time -Library (RTL) source files. - -The compiler outputs its object files and ALI files in the current -working directory. -Caution: The object file can be redirected with the @code{-o} switch; -however, @code{gcc} and @code{gnat1} have not been coordinated on this -so the @code{ALI} file will not go to the right place. Therefore, you should -avoid using the @code{-o} switch. - -@geindex System.IO - -The packages @code{Ada}, @code{System}, and @code{Interfaces} and their -children make up the GNAT RTL, together with the simple @code{System.IO} -package used in the @code{"Hello World"} example. The sources for these units -are needed by the compiler and are kept together in one directory. Not -all of the bodies are needed, but all of the sources are kept together -anyway. In a normal installation, you need not specify these directory -names when compiling or binding. Either the environment variables or -the built-in defaults cause these files to be found. - -In addition to the language-defined hierarchies (@code{System}, @code{Ada} and -@code{Interfaces}), the GNAT distribution provides a fourth hierarchy, -consisting of child units of @code{GNAT}. This is a collection of generally -useful types, subprograms, etc. See the @cite{GNAT_Reference_Manual} -for further details. - -Besides simplifying access to the RTL, a major use of search paths is -in compiling sources from multiple directories. This can make -development environments much more flexible. - -@node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc -@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{de} -@subsection Order of Compilation Issues - - -If, in our earlier example, there was a spec for the @code{hello} -procedure, it would be contained in the file @code{hello.ads}; yet this -file would not have to be explicitly compiled. This is the result of the -model we chose to implement library management. Some of the consequences -of this model are as follows: - - -@itemize * - -@item -There is no point in compiling specs (except for package -specs with no bodies) because these are compiled as needed by clients. If -you attempt a useless compilation, you will receive an error message. -It is also useless to compile subunits because they are compiled as needed -by the parent. - -@item -There are no order of compilation requirements: performing a -compilation never obsoletes anything. The only way you can obsolete -something and require recompilations is to modify one of the -source files on which it depends. - -@item -There is no library as such, apart from the ALI files -(@ref{28,,The Ada Library Information Files}, for information on the format -of these files). For now we find it convenient to create separate ALI files, -but eventually the information therein may be incorporated into the object -file directly. - -@item -When you compile a unit, the source files for the specs of all units -that it `with's, all its subunits, and the bodies of any generics it -instantiates must be available (reachable by the search-paths mechanism -described above), or you will receive a fatal error message. -@end itemize - -@node Examples,,Order of Compilation Issues,Compiling with gcc -@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{e0} -@subsection Examples - - -The following are some typical Ada compilation command line examples: - -@example -$ gcc -c xyz.adb -@end example - -Compile body in file @code{xyz.adb} with all default options. - -@example -$ gcc -c -O2 -gnata xyz-def.adb -@end example - -Compile the child unit package in file @code{xyz-def.adb} with extensive -optimizations, and pragma @code{Assert}/@cite{Debug} statements -enabled. - -@example -$ gcc -c -gnatc abc-def.adb -@end example - -Compile the subunit in file @code{abc-def.adb} in semantic-checking-only -mode. - -@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{db} -@section Compiler Switches - - -The @code{gcc} command accepts switches that control the -compilation process. These switches are fully described in this section: -first an alphabetical listing of all switches with a brief description, -and then functionally grouped sets of switches with more detailed -information. - -More switches exist for GCC than those documented here, especially -for specific targets. However, their use is not recommended as -they may change code generation in ways that are incompatible with -the Ada run-time library, or can cause inconsistencies between -compilation units. - -@menu -* Alphabetical List of All Switches:: -* Output and Error Message Control:: -* Warning Message Control:: -* Debugging and Assertion Control:: -* Validity Checking:: -* Style Checking:: -* Run-Time Checks:: -* Using gcc for Syntax Checking:: -* Using gcc for Semantic Checking:: -* Compiling Different Versions of Ada:: -* Character Set Control:: -* File Naming Control:: -* Subprogram Inlining Control:: -* Auxiliary Output Control:: -* Debugging Control:: -* Exception Handling Control:: -* Units to Sources Mapping Files:: -* Code Generation Control:: - -@end menu - -@node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{e3} -@subsection Alphabetical List of All Switches - - -@geindex -b (gcc) - - -@table @asis - -@item @code{-b `target'} - -Compile your program to run on @code{target}, which is the name of a -system configuration. You must have a GNAT cross-compiler built if -@code{target} is not the same as your host system. -@end table - -@geindex -B (gcc) - - -@table @asis - -@item @code{-B`dir'} - -Load compiler executables (for example, @code{gnat1}, the Ada compiler) -from @code{dir} instead of the default location. Only use this switch -when multiple versions of the GNAT compiler are available. -See the “Options for Directory Search” section in the -@cite{Using the GNU Compiler Collection (GCC)} manual for further details. -You would normally use the @code{-b} or @code{-V} switch instead. -@end table - -@geindex -c (gcc) - - -@table @asis - -@item @code{-c} - -Compile. Always use this switch when compiling Ada programs. - -Note: for some other languages when using @code{gcc}, notably in -the case of C and C++, it is possible to use -use @code{gcc} without a @code{-c} switch to -compile and link in one step. In the case of GNAT, you -cannot use this approach, because the binder must be run -and @code{gcc} cannot be used to run the GNAT binder. -@end table - -@geindex -fcallgraph-info (gcc) - - -@table @asis - -@item @code{-fcallgraph-info[=su,da]} - -Makes the compiler output callgraph information for the program, on a -per-file basis. The information is generated in the VCG format. It can -be decorated with additional, per-node and/or per-edge information, if a -list of comma-separated markers is additionally specified. When the -@code{su} marker is specified, the callgraph is decorated with stack usage -information; it is equivalent to @code{-fstack-usage}. When the @code{da} -marker is specified, the callgraph is decorated with information about -dynamically allocated objects. -@end table - -@geindex -fdiagnostics-format (gcc) - - -@table @asis - -@item @code{-fdiagnostics-format=json} - -Makes GNAT emit warning and error messages as JSON. Inhibits printing of -text warning and errors messages except if @code{-gnatv} or -@code{-gnatl} are present. Uses absolute file paths when used along -@code{-gnatef}. -@end table - -@geindex -fdump-scos (gcc) - - -@table @asis - -@item @code{-fdump-scos} - -Generates SCO (Source Coverage Obligation) information in the ALI file. -This information is used by advanced coverage tools. See unit @code{SCOs} -in the compiler sources for details in files @code{scos.ads} and -@code{scos.adb}. -@end table - -@geindex -fgnat-encodings (gcc) - - -@table @asis - -@item @code{-fgnat-encodings=[all|gdb|minimal]} - -This switch controls the balance between GNAT encodings and standard DWARF -emitted in the debug information. -@end table - -@geindex -flto (gcc) - - -@table @asis - -@item @code{-flto[=`n']} - -Enables Link Time Optimization. This switch must be used in conjunction -with the @code{-Ox} switches (but not with the @code{-gnatn} switch -since it is a full replacement for the latter) and instructs the compiler -to defer most optimizations until the link stage. The advantage of this -approach is that the compiler can do a whole-program analysis and choose -the best interprocedural optimization strategy based on a complete view -of the program, instead of a fragmentary view with the usual approach. -This can also speed up the compilation of big programs and reduce the -size of the executable, compared with a traditional per-unit compilation -with inlining across units enabled by the @code{-gnatn} switch. -The drawback of this approach is that it may require more memory and that -the debugging information generated by -g with it might be hardly usable. -The switch, as well as the accompanying @code{-Ox} switches, must be -specified both for the compilation and the link phases. -If the @code{n} parameter is specified, the optimization and final code -generation at link time are executed using @code{n} parallel jobs by -means of an installed @code{make} program. -@end table - -@geindex -fno-inline (gcc) - - -@table @asis - -@item @code{-fno-inline} - -Suppresses all inlining, unless requested with pragma @code{Inline_Always}. The -effect is enforced regardless of other optimization or inlining switches. -Note that inlining can also be suppressed on a finer-grained basis with -pragma @code{No_Inline}. -@end table - -@geindex -fno-inline-functions (gcc) - - -@table @asis - -@item @code{-fno-inline-functions} - -Suppresses automatic inlining of subprograms, which is enabled -if @code{-O3} is used. -@end table - -@geindex -fno-inline-small-functions (gcc) - - -@table @asis - -@item @code{-fno-inline-small-functions} - -Suppresses automatic inlining of small subprograms, which is enabled -if @code{-O2} is used. -@end table - -@geindex -fno-inline-functions-called-once (gcc) - - -@table @asis - -@item @code{-fno-inline-functions-called-once} - -Suppresses inlining of subprograms local to the unit and called once -from within it, which is enabled if @code{-O1} is used. -@end table - -@geindex -fno-ivopts (gcc) - - -@table @asis - -@item @code{-fno-ivopts} - -Suppresses high-level loop induction variable optimizations, which are -enabled if @code{-O1} is used. These optimizations are generally -profitable but, for some specific cases of loops with numerous uses -of the iteration variable that follow a common pattern, they may end -up destroying the regularity that could be exploited at a lower level -and thus producing inferior code. -@end table - -@geindex -fno-strict-aliasing (gcc) - - -@table @asis - -@item @code{-fno-strict-aliasing} - -Causes the compiler to avoid assumptions regarding non-aliasing -of objects of different types. See -@ref{e4,,Optimization and Strict Aliasing} for details. -@end table - -@geindex -fno-strict-overflow (gcc) - - -@table @asis - -@item @code{-fno-strict-overflow} - -Causes the compiler to avoid assumptions regarding the rules of signed -integer overflow. These rules specify that signed integer overflow will -result in a Constraint_Error exception at run time and are enforced in -default mode by the compiler, so this switch should not be necessary in -normal operating mode. It might be useful in conjunction with @code{-gnato0} -for very peculiar cases of low-level programming. -@end table - -@geindex -fstack-check (gcc) - - -@table @asis - -@item @code{-fstack-check} - -Activates stack checking. -See @ref{e5,,Stack Overflow Checking} for details. -@end table - -@geindex -fstack-usage (gcc) - - -@table @asis - -@item @code{-fstack-usage} - -Makes the compiler output stack usage information for the program, on a -per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details. -@end table - -@geindex -g (gcc) - - -@table @asis - -@item @code{-g} - -Generate debugging information. This information is stored in the object -file and copied from there to the final executable file by the linker, -where it can be read by the debugger. You must use the -@code{-g} switch if you plan on using the debugger. -@end table - -@geindex -gnat05 (gcc) - - -@table @asis - -@item @code{-gnat05} - -Allow full Ada 2005 features. -@end table - -@geindex -gnat12 (gcc) - - -@table @asis - -@item @code{-gnat12} - -Allow full Ada 2012 features. -@end table - -@geindex -gnat83 (gcc) - -@geindex -gnat2005 (gcc) - - -@table @asis - -@item @code{-gnat2005} - -Allow full Ada 2005 features (same as @code{-gnat05}) -@end table - -@geindex -gnat2012 (gcc) - - -@table @asis - -@item @code{-gnat2012} - -Allow full Ada 2012 features (same as @code{-gnat12}) -@end table - -@geindex -gnat2022 (gcc) - - -@table @asis - -@item @code{-gnat2022} - -Allow full Ada 2022 features - -@item @code{-gnat83} - -Enforce Ada 83 restrictions. -@end table - -@geindex -gnat95 (gcc) - - -@table @asis - -@item @code{-gnat95} - -Enforce Ada 95 restrictions. - -Note: for compatibility with some Ada 95 compilers which support only -the @code{overriding} keyword of Ada 2005, the @code{-gnatd.D} switch can -be used along with @code{-gnat95} to achieve a similar effect with GNAT. - -@code{-gnatd.D} instructs GNAT to consider @code{overriding} as a keyword -and handle its associated semantic checks, even in Ada 95 mode. -@end table - -@geindex -gnata (gcc) - - -@table @asis - -@item @code{-gnata} - -Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be -activated. Note that these pragmas can also be controlled using the -configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}. -It also activates pragmas @code{Check}, @code{Precondition}, and -@code{Postcondition}. Note that these pragmas can also be controlled -using the configuration pragma @code{Check_Policy}. In Ada 2012, it -also activates all assertions defined in the RM as aspects: preconditions, -postconditions, type invariants and (sub)type predicates. In all Ada modes, -corresponding pragmas for type invariants and (sub)type predicates are -also activated. The default is that all these assertions are disabled, -and have no effect, other than being checked for syntactic validity, and -in the case of subtype predicates, constructions such as membership tests -still test predicates even if assertions are turned off. -@end table - -@geindex -gnatA (gcc) - - -@table @asis - -@item @code{-gnatA} - -Avoid processing @code{gnat.adc}. If a @code{gnat.adc} file is present, -it will be ignored. -@end table - -@geindex -gnatb (gcc) - - -@table @asis - -@item @code{-gnatb} - -Generate brief messages to @code{stderr} even if verbose mode set. -@end table - -@geindex -gnatB (gcc) - - -@table @asis - -@item @code{-gnatB} - -Assume no invalid (bad) values except for ‘Valid attribute use -(@ref{e7,,Validity Checking}). -@end table - -@geindex -gnatc (gcc) - - -@table @asis - -@item @code{-gnatc} - -Check syntax and semantics only (no code generation attempted). When the -compiler is invoked by @code{gnatmake}, if the switch @code{-gnatc} is -only given to the compiler (after @code{-cargs} or in package Compiler of -the project file), @code{gnatmake} will fail because it will not find the -object file after compilation. If @code{gnatmake} is called with -@code{-gnatc} as a builder switch (before @code{-cargs} or in package -Builder of the project file) then @code{gnatmake} will not fail because -it will not look for the object files after compilation, and it will not try -to build and link. -@end table - -@geindex -gnatC (gcc) - - -@table @asis - -@item @code{-gnatC} - -Generate CodePeer intermediate format (no code generation attempted). -This switch will generate an intermediate representation suitable for -use by CodePeer (@code{.scil} files). This switch is not compatible with -code generation (it will, among other things, disable some switches such -as -gnatn, and enable others such as -gnata). -@end table - -@geindex -gnatd (gcc) - - -@table @asis - -@item @code{-gnatd} - -Specify debug options for the compiler. The string of characters after -the @code{-gnatd} specifies the specific debug options. The possible -characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore. -See compiler source file @code{debug.adb} for details of the implemented -debug options. Certain debug options are relevant to applications -programmers, and these are documented at appropriate points in this -users guide. -@end table - -@geindex -gnatD[nn] (gcc) - - -@table @asis - -@item @code{-gnatD} - -Create expanded source files for source level debugging. This switch -also suppresses generation of cross-reference information -(see @code{-gnatx}). Note that this switch is not allowed if a previous --gnatR switch has been given, since these two switches are not compatible. -@end table - -@geindex -gnateA (gcc) - - -@table @asis - -@item @code{-gnateA} - -Check that the actual parameters of a subprogram call are not aliases of one -another. To qualify as aliasing, their memory locations must be identical or -overlapping, at least one of the corresponding formal parameters must be of -mode OUT or IN OUT, and at least one of the corresponding formal parameters -must have its parameter passing mechanism not specified. - -@example -type Rec_Typ is record - Data : Integer := 0; -end record; - -function Self (Val : Rec_Typ) return Rec_Typ is -begin - return Val; -end Self; - -procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is -begin - null; -end Detect_Aliasing; - -Obj : Rec_Typ; - -Detect_Aliasing (Obj, Obj); -Detect_Aliasing (Obj, Self (Obj)); -@end example - -In the example above, the first call to @code{Detect_Aliasing} fails with a -@code{Program_Error} at run time because the actuals for @code{Val_1} and -@code{Val_2} denote the same object. The second call executes without raising -an exception because @code{Self(Obj)} produces an anonymous object which does -not share the memory location of @code{Obj}. -@end table - -@geindex -gnateb (gcc) - - -@table @asis - -@item @code{-gnateb} - -Store configuration files by their basename in ALI files. This switch is -used for instance by gprbuild for distributed builds in order to prevent -issues where machine-specific absolute paths could end up being stored in -ALI files. -@end table - -@geindex -gnatec (gcc) - - -@table @asis - -@item @code{-gnatec=`path'} - -Specify a configuration pragma file -(the equal sign is optional) -(@ref{63,,The Configuration Pragmas Files}). -@end table - -@geindex -gnateC (gcc) - - -@table @asis - -@item @code{-gnateC} - -Generate CodePeer messages in a compiler-like format. This switch is only -effective if @code{-gnatcC} is also specified and requires an installation -of CodePeer. -@end table - -@geindex -gnated (gcc) - - -@table @asis - -@item @code{-gnated} - -Disable atomic synchronization -@end table - -@geindex -gnateD (gcc) - - -@table @asis - -@item @code{-gnateDsymbol[=`value']} - -Defines a symbol, associated with @code{value}, for preprocessing. -(@ref{90,,Integrated Preprocessing}). -@end table - -@geindex -gnateE (gcc) - - -@table @asis - -@item @code{-gnateE} - -Generate extra information in exception messages. In particular, display -extra column information and the value and range associated with index and -range check failures, and extra column information for access checks. -In cases where the compiler is able to determine at compile time that -a check will fail, it gives a warning, and the extra information is not -produced at run time. -@end table - -@geindex -gnatef (gcc) - - -@table @asis - -@item @code{-gnatef} - -Display full source path name in brief error messages and absolute paths in -@code{-fdiagnostics-format=json}’s output. -@end table - -@geindex -gnateF (gcc) - - -@table @asis - -@item @code{-gnateF} - -Check for overflow on all floating-point operations, including those -for unconstrained predefined types. See description of pragma -@code{Check_Float_Overflow} in GNAT RM. -@end table - -@geindex -gnateg (gcc) - -@code{-gnateg} -@code{-gnatceg} - -@quotation - -The @code{-gnatc} switch must always be specified before this switch, e.g. -@code{-gnatceg}. Generate a C header from the Ada input file. See -@ref{b7,,Generating C Headers for Ada Specifications} for more -information. -@end quotation - -@geindex -gnateG (gcc) - - -@table @asis - -@item @code{-gnateG} - -Save result of preprocessing in a text file. -@end table - -@geindex -gnatei (gcc) - - -@table @asis - -@item @code{-gnatei`nnn'} - -Set maximum number of instantiations during compilation of a single unit to -@code{nnn}. This may be useful in increasing the default maximum of 8000 for -the rare case when a single unit legitimately exceeds this limit. -@end table - -@geindex -gnateI (gcc) - - -@table @asis - -@item @code{-gnateI`nnn'} - -Indicates that the source is a multi-unit source and that the index of the -unit to compile is @code{nnn}. @code{nnn} needs to be a positive number and need -to be a valid index in the multi-unit source. -@end table - -@geindex -gnatel (gcc) - - -@table @asis - -@item @code{-gnatel} - -This switch can be used with the static elaboration model to issue info -messages showing -where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All} -are generated. This is useful in diagnosing elaboration circularities -caused by these implicit pragmas when using the static elaboration -model. See See the section in this guide on elaboration checking for -further details. These messages are not generated by default, and are -intended only for temporary use when debugging circularity problems. -@end table - -@geindex -gnatel (gcc) - - -@table @asis - -@item @code{-gnateL} - -This switch turns off the info messages about implicit elaboration pragmas. -@end table - -@geindex -gnatem (gcc) - - -@table @asis - -@item @code{-gnatem=`path'} - -Specify a mapping file -(the equal sign is optional) -(@ref{e8,,Units to Sources Mapping Files}). -@end table - -@geindex -gnatep (gcc) - - -@table @asis - -@item @code{-gnatep=`file'} - -Specify a preprocessing data file -(the equal sign is optional) -(@ref{90,,Integrated Preprocessing}). -@end table - -@geindex -gnateP (gcc) - - -@table @asis - -@item @code{-gnateP} - -Turn categorization dependency errors into warnings. -Ada requires that units that WITH one another have compatible categories, for -example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, -these errors become warnings (which can be ignored, or suppressed in the usual -manner). This can be useful in some specialized circumstances such as the -temporary use of special test software. -@end table - -@geindex -gnateS (gcc) - - -@table @asis - -@item @code{-gnateS} - -Synonym of @code{-fdump-scos}, kept for backwards compatibility. -@end table - -@geindex -gnatet=file (gcc) - - -@table @asis - -@item @code{-gnatet=`path'} - -Generate target dependent information. The format of the output file is -described in the section about switch @code{-gnateT}. -@end table - -@geindex -gnateT (gcc) - - -@table @asis - -@item @code{-gnateT=`path'} - -Read target dependent information, such as endianness or sizes and alignments -of base type. If this switch is passed, the default target dependent -information of the compiler is replaced by the one read from the input file. -This is used by tools other than the compiler, e.g. to do -semantic analysis of programs that will run on some other target than -the machine on which the tool is run. - -The following target dependent values should be defined, -where @code{Nat} denotes a natural integer value, @code{Pos} denotes a -positive integer value, and fields marked with a question mark are -boolean fields, where a value of 0 is False, and a value of 1 is True: - -@example -Bits_BE : Nat; -- Bits stored big-endian? -Bits_Per_Unit : Pos; -- Bits in a storage unit -Bits_Per_Word : Pos; -- Bits in a word -Bytes_BE : Nat; -- Bytes stored big-endian? -Char_Size : Pos; -- Standard.Character'Size -Double_Float_Alignment : Nat; -- Alignment of double float -Double_Scalar_Alignment : Nat; -- Alignment of double length scalar -Double_Size : Pos; -- Standard.Long_Float'Size -Float_Size : Pos; -- Standard.Float'Size -Float_Words_BE : Nat; -- Float words stored big-endian? -Int_Size : Pos; -- Standard.Integer'Size -Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size -Long_Long_Long_Size : Pos; -- Standard.Long_Long_Long_Integer'Size -Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size -Long_Size : Pos; -- Standard.Long_Integer'Size -Maximum_Alignment : Pos; -- Maximum permitted alignment -Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field -Pointer_Size : Pos; -- System.Address'Size -Short_Enums : Nat; -- Foreign enums use short size? -Short_Size : Pos; -- Standard.Short_Integer'Size -Strict_Alignment : Nat; -- Strict alignment? -System_Allocator_Alignment : Nat; -- Alignment for malloc calls -Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size -Words_BE : Nat; -- Words stored big-endian? -@end example - -@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of -GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.} - -@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of -GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.} - -@code{Double_Float_Alignment}, if not zero, is the maximum alignment that the -compiler can choose by default for a 64-bit floating-point type or object. - -@code{Double_Scalar_Alignment}, if not zero, is the maximum alignment that the -compiler can choose by default for a 64-bit or larger scalar type or object. - -@code{Maximum_Alignment} is the maximum alignment that the compiler can choose -by default for a type or object, which is also the maximum alignment that can -be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT -/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as -follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.} - -@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is -64 for the majority of GCC targets (but can be different on some targets). - -@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT} -documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.} - -@code{System_Allocator_Alignment} is the guaranteed alignment of data returned -by calls to @code{malloc}. - -The format of the input file is as follows. First come the values of -the variables defined above, with one line per value: - -@example -name value -@end example - -where @code{name} is the name of the parameter, spelled out in full, -and cased as in the above list, and @code{value} is an unsigned decimal -integer. Two or more blanks separates the name from the value. - -All the variables must be present, in alphabetical order (i.e. the -same order as the list above). - -Then there is a blank line to separate the two parts of the file. Then -come the lines showing the floating-point types to be registered, with -one line per registered mode: - -@example -name digs float_rep size alignment -@end example - -where @code{name} is the string name of the type (which can have -single spaces embedded in the name, e.g. long double), @code{digs} is -the number of digits for the floating-point type, @code{float_rep} is -the float representation (I for IEEE-754-Binary, which is -the only one supported at this time), -@code{size} is the size in bits, @code{alignment} is the -alignment in bits. The name is followed by at least two blanks, fields -are separated by at least one blank, and a LF character immediately -follows the alignment field. - -Here is an example of a target parameterization file: - -@example -Bits_BE 0 -Bits_Per_Unit 8 -Bits_Per_Word 64 -Bytes_BE 0 -Char_Size 8 -Double_Float_Alignment 0 -Double_Scalar_Alignment 0 -Double_Size 64 -Float_Size 32 -Float_Words_BE 0 -Int_Size 64 -Long_Double_Size 128 -Long_Long_Long_Size 128 -Long_Long_Size 64 -Long_Size 64 -Maximum_Alignment 16 -Max_Unaligned_Field 64 -Pointer_Size 64 -Short_Size 16 -Strict_Alignment 0 -System_Allocator_Alignment 16 -Wchar_T_Size 32 -Words_BE 0 - -float 15 I 64 64 -double 15 I 64 64 -long double 18 I 80 128 -TF 33 I 128 128 -@end example -@end table - -@geindex -gnateu (gcc) - - -@table @asis - -@item @code{-gnateu} - -Ignore unrecognized validity, warning, and style switches that -appear after this switch is given. This may be useful when -compiling sources developed on a later version of the compiler -with an earlier version. Of course the earlier version must -support this switch. -@end table - -@geindex -gnateV (gcc) - - -@table @asis - -@item @code{-gnateV} - -Check that all actual parameters of a subprogram call are valid according to -the rules of validity checking (@ref{e7,,Validity Checking}). -@end table - -@geindex -gnateY (gcc) - - -@table @asis - -@item @code{-gnateY} - -Ignore all STYLE_CHECKS pragmas. Full legality checks -are still carried out, but the pragmas have no effect -on what style checks are active. This allows all style -checking options to be controlled from the command line. -@end table - -@geindex -gnatE (gcc) - - -@table @asis - -@item @code{-gnatE} - -Dynamic elaboration checking mode enabled. For further details see -@ref{f,,Elaboration Order Handling in GNAT}. -@end table - -@geindex -gnatf (gcc) - - -@table @asis - -@item @code{-gnatf} - -Full errors. Multiple errors per line, all undefined references, do not -attempt to suppress cascaded errors. -@end table - -@geindex -gnatF (gcc) - - -@table @asis - -@item @code{-gnatF} - -Externals names are folded to all uppercase. -@end table - -@geindex -gnatg (gcc) - - -@table @asis - -@item @code{-gnatg} - -Internal GNAT implementation mode. This should not be used for applications -programs, it is intended only for use by the compiler and its run-time -library. For documentation, see the GNAT sources. Note that @code{-gnatg} -implies @code{-gnatw.ge} and @code{-gnatyg} so that all standard -warnings and all standard style options are turned on. All warnings and style -messages are treated as errors. -@end table - -@geindex -gnatG[nn] (gcc) - - -@table @asis - -@item @code{-gnatG=nn} - -List generated expanded code in source form. -@end table - -@geindex -gnath (gcc) - - -@table @asis - -@item @code{-gnath} - -Output usage information. The output is written to @code{stdout}. -@end table - -@geindex -gnatH (gcc) - - -@table @asis - -@item @code{-gnatH} - -Legacy elaboration-checking mode enabled. When this switch is in effect, -the pre-18.x access-before-elaboration model becomes the de facto model. -For further details see @ref{f,,Elaboration Order Handling in GNAT}. -@end table - -@geindex -gnati (gcc) - - -@table @asis - -@item @code{-gnati`c'} - -Identifier character set (@code{c} = 1/2/3/4/5/9/p/8/f/n/w). -For details of the possible selections for @code{c}, -see @ref{31,,Character Set Control}. -@end table - -@geindex -gnatI (gcc) - - -@table @asis - -@item @code{-gnatI} - -Ignore representation clauses. When this switch is used, -representation clauses are treated as comments. This is useful -when initially porting code where you want to ignore rep clause -problems, and also for compiling foreign code (particularly -for use with ASIS). The representation clauses that are ignored -are: enumeration_representation_clause, record_representation_clause, -and attribute_definition_clause for the following attributes: -Address, Alignment, Bit_Order, Component_Size, Machine_Radix, -Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size, -and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored. -Note that this option should be used only for compiling – the -code is likely to malfunction at run time. -@end table - -@geindex -gnatjnn (gcc) - - -@table @asis - -@item @code{-gnatj`nn'} - -Reformat error messages to fit on @code{nn} character lines -@end table - -@geindex -gnatJ (gcc) - - -@table @asis - -@item @code{-gnatJ} - -Permissive elaboration-checking mode enabled. When this switch is in effect, -the post-18.x access-before-elaboration model ignores potential issues with: - - -@itemize - - -@item -Accept statements - -@item -Activations of tasks defined in instances - -@item -Assertion pragmas - -@item -Calls from within an instance to its enclosing context - -@item -Calls through generic formal parameters - -@item -Calls to subprograms defined in instances - -@item -Entry calls - -@item -Indirect calls using ‘Access - -@item -Requeue statements - -@item -Select statements - -@item -Synchronous task suspension -@end itemize - -and does not emit compile-time diagnostics or run-time checks. For further -details see @ref{f,,Elaboration Order Handling in GNAT}. -@end table - -@geindex -gnatk (gcc) - - -@table @asis - -@item @code{-gnatk=`n'} - -Limit file names to @code{n} (1-999) characters (@code{k} = krunch). -@end table - -@geindex -gnatl (gcc) - - -@table @asis - -@item @code{-gnatl} - -Output full source listing with embedded error messages. -@end table - -@geindex -gnatL (gcc) - - -@table @asis - -@item @code{-gnatL} - -Used in conjunction with -gnatG or -gnatD to intersperse original -source lines (as comment lines with line numbers) in the expanded -source output. -@end table - -@geindex -gnatm (gcc) - - -@table @asis - -@item @code{-gnatm=`n'} - -Limit number of detected error or warning messages to @code{n} -where @code{n} is in the range 1..999999. The default setting if -no switch is given is 9999. If the number of warnings reaches this -limit, then a message is output and further warnings are suppressed, -but the compilation is continued. If the number of error messages -reaches this limit, then a message is output and the compilation -is abandoned. The equal sign here is optional. A value of zero -means that no limit applies. -@end table - -@geindex -gnatn (gcc) - - -@table @asis - -@item @code{-gnatn[12]} - -Activate inlining across units for subprograms for which pragma @code{Inline} -is specified. This inlining is performed by the GCC back-end. An optional -digit sets the inlining level: 1 for moderate inlining across units -or 2 for full inlining across units. If no inlining level is specified, -the compiler will pick it based on the optimization level. -@end table - -@geindex -gnatN (gcc) - - -@table @asis - -@item @code{-gnatN} - -Activate front end inlining for subprograms for which -pragma @code{Inline} is specified. This inlining is performed -by the front end and will be visible in the -@code{-gnatG} output. - -When using a gcc-based back end, then the use of -@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. -Historically front end inlining was more extensive than the gcc back end -inlining, but that is no longer the case. -@end table - -@geindex -gnato0 (gcc) - - -@table @asis - -@item @code{-gnato0} - -Suppresses overflow checking. This causes the behavior of the compiler to -match the default for older versions where overflow checking was suppressed -by default. This is equivalent to having -@code{pragma Suppress (Overflow_Check)} in a configuration pragma file. -@end table - -@geindex -gnato?? (gcc) - - -@table @asis - -@item @code{-gnato??} - -Set default mode for handling generation of code to avoid intermediate -arithmetic overflow. Here @code{??} is two digits, a -single digit, or nothing. Each digit is one of the digits @code{1} -through @code{3}: - - -@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -Digit - -@tab - -Interpretation - -@item - -`1' - -@tab - -All intermediate overflows checked against base type (@code{STRICT}) - -@item - -`2' - -@tab - -Minimize intermediate overflows (@code{MINIMIZED}) - -@item - -`3' - -@tab - -Eliminate intermediate overflows (@code{ELIMINATED}) - -@end multitable - - -If only one digit appears, then it applies to all -cases; if two digits are given, then the first applies outside -assertions, pre/postconditions, and type invariants, and the second -applies within assertions, pre/postconditions, and type invariants. - -If no digits follow the @code{-gnato}, then it is equivalent to -@code{-gnato11}, -causing all intermediate overflows to be handled in strict -mode. - -This switch also causes arithmetic overflow checking to be performed -(as though @code{pragma Unsuppress (Overflow_Check)} had been specified). - -The default if no option @code{-gnato} is given is that overflow handling -is in @code{STRICT} mode (computations done using the base type), and that -overflow checking is enabled. - -Note that division by zero is a separate check that is not -controlled by this switch (divide-by-zero checking is on by default). - -See also @ref{e9,,Specifying the Desired Mode}. -@end table - -@geindex -gnatp (gcc) - - -@table @asis - -@item @code{-gnatp} - -Suppress all checks. See @ref{ea,,Run-Time Checks} for details. This switch -has no effect if cancelled by a subsequent @code{-gnat-p} switch. -@end table - -@geindex -gnat-p (gcc) - - -@table @asis - -@item @code{-gnat-p} - -Cancel effect of previous @code{-gnatp} switch. -@end table - -@geindex -gnatq (gcc) - - -@table @asis - -@item @code{-gnatq} - -Don’t quit. Try semantics, even if parse errors. -@end table - -@geindex -gnatQ (gcc) - - -@table @asis - -@item @code{-gnatQ} - -Don’t quit. Generate @code{ALI} and tree files even if illegalities. -Note that code generation is still suppressed in the presence of any -errors, so even with @code{-gnatQ} no object file is generated. -@end table - -@geindex -gnatr (gcc) - - -@table @asis - -@item @code{-gnatr} - -Treat pragma Restrictions as Restriction_Warnings. -@end table - -@geindex -gnatR (gcc) - - -@table @asis - -@item @code{-gnatR[0|1|2|3|4][e][j][m][s]} - -Output representation information for declared types, objects and -subprograms. Note that this switch is not allowed if a previous -@code{-gnatD} switch has been given, since these two switches -are not compatible. -@end table - -@geindex -gnats (gcc) - - -@table @asis - -@item @code{-gnats} - -Syntax check only. -@end table - -@geindex -gnatS (gcc) - - -@table @asis - -@item @code{-gnatS} - -Print package Standard. -@end table - -@geindex -gnatT (gcc) - - -@table @asis - -@item @code{-gnatT`nnn'} - -All compiler tables start at @code{nnn} times usual starting size. -@end table - -@geindex -gnatu (gcc) - - -@table @asis - -@item @code{-gnatu} - -List units for this compilation. -@end table - -@geindex -gnatU (gcc) - - -@table @asis - -@item @code{-gnatU} - -Tag all error messages with the unique string ‘error:’ -@end table - -@geindex -gnatv (gcc) - - -@table @asis - -@item @code{-gnatv} - -Verbose mode. Full error output with source lines to @code{stdout}. -@end table - -@geindex -gnatV (gcc) - - -@table @asis - -@item @code{-gnatV} - -Control level of validity checking (@ref{e7,,Validity Checking}). -@end table - -@geindex -gnatw (gcc) - - -@table @asis - -@item @code{-gnatw`xxx'} - -Warning mode where -@code{xxx} is a string of option letters that denotes -the exact warnings that -are enabled or disabled (@ref{eb,,Warning Message Control}). -@end table - -@geindex -gnatW (gcc) - - -@table @asis - -@item @code{-gnatW`e'} - -Wide character encoding method -(@code{e}=n/h/u/s/e/8). -@end table - -@geindex -gnatx (gcc) - - -@table @asis - -@item @code{-gnatx} - -Suppress generation of cross-reference information. -@end table - -@geindex -gnatX (gcc) - - -@table @asis - -@item @code{-gnatX} - -Enable core GNAT implementation extensions and latest Ada version. -@end table - -@geindex -gnatX0 (gcc) - - -@table @asis - -@item @code{-gnatX0} - -Enable all GNAT implementation extensions and latest Ada version. -@end table - -@geindex -gnaty (gcc) - - -@table @asis - -@item @code{-gnaty} - -Enable built-in style checks (@ref{ec,,Style Checking}). -@end table - -@geindex -gnatz (gcc) - - -@table @asis - -@item @code{-gnatz`m'} - -Distribution stub generation and compilation -(@code{m}=r/c for receiver/caller stubs). -@end table - -@geindex -I (gcc) - - -@table @asis - -@item @code{-I`dir'} - -@geindex RTL - -Direct GNAT to search the @code{dir} directory for source files needed by -the current compilation -(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). -@end table - -@geindex -I- (gcc) - - -@table @asis - -@item @code{-I-} - -@geindex RTL - -Except for the source file named in the command line, do not look for source -files in the directory containing the source file named in the command line -(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). -@end table - -@geindex -o (gcc) - - -@table @asis - -@item @code{-o `file'} - -This switch is used in @code{gcc} to redirect the generated object file -and its associated ALI file. Beware of this switch with GNAT, because it may -cause the object file and ALI file to have different names which in turn -may confuse the binder and the linker. -@end table - -@geindex -nostdinc (gcc) - - -@table @asis - -@item @code{-nostdinc} - -Inhibit the search of the default location for the GNAT Run Time -Library (RTL) source files. -@end table - -@geindex -nostdlib (gcc) - - -@table @asis - -@item @code{-nostdlib} - -Inhibit the search of the default location for the GNAT Run Time -Library (RTL) ALI files. -@end table - -@geindex -O (gcc) - - -@table @asis - -@item @code{-O[`n']} - -@code{n} controls the optimization level: - - -@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -`n' - -@tab - -Effect - -@item - -`0' - -@tab - -No optimization, the default setting if no @code{-O} appears - -@item - -`1' - -@tab - -Normal optimization, the default if you specify @code{-O} without an -operand. A good compromise between code quality and compilation -time. - -@item - -`2' - -@tab - -Extensive optimization, may improve execution time, possibly at -the cost of substantially increased compilation time. - -@item - -`3' - -@tab - -Same as @code{-O2}, and also includes inline expansion for small -subprograms in the same unit. - -@item - -`s' - -@tab - -Optimize space usage - -@end multitable - - -See also @ref{ed,,Optimization Levels}. -@end table - -@geindex -pass-exit-codes (gcc) - - -@table @asis - -@item @code{-pass-exit-codes} - -Catch exit codes from the compiler and use the most meaningful as -exit status. -@end table - -@geindex --RTS (gcc) - - -@table @asis - -@item @code{--RTS=`rts-path'} - -Specifies the default location of the run-time library. Same meaning as the -equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}). -@end table - -@geindex -S (gcc) - - -@table @asis - -@item @code{-S} - -Used in place of @code{-c} to -cause the assembler source file to be -generated, using @code{.s} as the extension, -instead of the object file. -This may be useful if you need to examine the generated assembly code. -@end table - -@geindex -fverbose-asm (gcc) - - -@table @asis - -@item @code{-fverbose-asm} - -Used in conjunction with @code{-S} -to cause the generated assembly code file to be annotated with variable -names, making it significantly easier to follow. -@end table - -@geindex -v (gcc) - - -@table @asis - -@item @code{-v} - -Show commands generated by the @code{gcc} driver. Normally used only for -debugging purposes or if you need to be sure what version of the -compiler you are executing. -@end table - -@geindex -V (gcc) - - -@table @asis - -@item @code{-V `ver'} - -Execute @code{ver} version of the compiler. This is the @code{gcc} -version, not the GNAT version. -@end table - -@geindex -w (gcc) - - -@table @asis - -@item @code{-w} - -Turn off warnings generated by the back end of the compiler. Use of -this switch also causes the default for front end warnings to be set -to suppress (as though @code{-gnatws} had appeared at the start of -the options). -@end table - -@geindex Combining GNAT switches - -You may combine a sequence of GNAT switches into a single switch. For -example, the combined switch - -@quotation - -@example --gnatofi3 -@end example -@end quotation - -is equivalent to specifying the following sequence of switches: - -@quotation - -@example --gnato -gnatf -gnati3 -@end example -@end quotation - -The following restrictions apply to the combination of switches -in this manner: - - -@itemize * - -@item -The switch @code{-gnatc} if combined with other switches must come -first in the string. - -@item -The switch @code{-gnats} if combined with other switches must come -first in the string. - -@item -The switches -@code{-gnatzc} and @code{-gnatzr} may not be combined with any other -switches, and only one of them may appear in the command line. - -@item -The switch @code{-gnat-p} may not be combined with any other switch. - -@item -Once a ‘y’ appears in the string (that is a use of the @code{-gnaty} -switch), then all further characters in the switch are interpreted -as style modifiers (see description of @code{-gnaty}). - -@item -Once a ‘d’ appears in the string (that is a use of the @code{-gnatd} -switch), then all further characters in the switch are interpreted -as debug flags (see description of @code{-gnatd}). - -@item -Once a ‘w’ appears in the string (that is a use of the @code{-gnatw} -switch), then all further characters in the switch are interpreted -as warning mode modifiers (see description of @code{-gnatw}). - -@item -Once a ‘V’ appears in the string (that is a use of the @code{-gnatV} -switch), then all further characters in the switch are interpreted -as validity checking options (@ref{e7,,Validity Checking}). - -@item -Option ‘em’, ‘ec’, ‘ep’, ‘l=’ and ‘R’ must be the last options in -a combined list of options. -@end itemize - -@node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{ef} -@subsection Output and Error Message Control - - -@geindex stderr - -The standard default format for error messages is called ‘brief format’. -Brief format messages are written to @code{stderr} (the standard error -file) and have the following form: - -@example -e.adb:3:04: Incorrect spelling of keyword "function" -e.adb:4:20: ";" should be "is" -@end example - -The first integer after the file name is the line number in the file, -and the second integer is the column number within the line. -@code{GNAT Studio} can parse the error messages -and point to the referenced character. -The following switches provide control over the error message -format: - -@geindex -gnatv (gcc) - - -@table @asis - -@item @code{-gnatv} - -The @code{v} stands for verbose. -The effect of this setting is to write long-format error -messages to @code{stdout} (the standard output file). -The same program compiled with the -@code{-gnatv} switch would generate: - -@example -3. funcion X (Q : Integer) - | ->>> Incorrect spelling of keyword "function" -4. return Integer; - | ->>> ";" should be "is" -@end example - -The vertical bar indicates the location of the error, and the @code{>>>} -prefix can be used to search for error messages. When this switch is -used the only source lines output are those with errors. -@end table - -@geindex -gnatl (gcc) - - -@table @asis - -@item @code{-gnatl} - -The @code{l} stands for list. -This switch causes a full listing of -the file to be generated. In the case where a body is -compiled, the corresponding spec is also listed, along -with any subunits. Typical output from compiling a package -body @code{p.adb} might look like: - -@example -Compiling: p.adb - - 1. package body p is - 2. procedure a; - 3. procedure a is separate; - 4. begin - 5. null - | - >>> missing ";" - - 6. end; - -Compiling: p.ads - - 1. package p is - 2. pragma Elaborate_Body - | - >>> missing ";" - - 3. end p; - -Compiling: p-a.adb - - 1. separate p - | - >>> missing "(" - - 2. procedure a is - 3. begin - 4. null - | - >>> missing ";" - - 5. end; -@end example - -When you specify the @code{-gnatv} or @code{-gnatl} switches and -standard output is redirected, a brief summary is written to -@code{stderr} (standard error) giving the number of error messages and -warning messages generated. -@end table - -@geindex -gnatl=fname (gcc) - - -@table @asis - -@item @code{-gnatl=`fname'} - -This has the same effect as @code{-gnatl} except that the output is -written to a file instead of to standard output. If the given name -@code{fname} does not start with a period, then it is the full name -of the file to be written. If @code{fname} is an extension, it is -appended to the name of the file being compiled. For example, if -file @code{xyz.adb} is compiled with @code{-gnatl=.lst}, -then the output is written to file xyz.adb.lst. -@end table - -@geindex -gnatU (gcc) - - -@table @asis - -@item @code{-gnatU} - -This switch forces all error messages to be preceded by the unique -string ‘error:’. This means that error messages take a few more -characters in space, but allows easy searching for and identification -of error messages. -@end table - -@geindex -gnatb (gcc) - - -@table @asis - -@item @code{-gnatb} - -The @code{b} stands for brief. -This switch causes GNAT to generate the -brief format error messages to @code{stderr} (the standard error -file) as well as the verbose -format message or full listing (which as usual is written to -@code{stdout}, the standard output file). -@end table - -@geindex -gnatm (gcc) - - -@table @asis - -@item @code{-gnatm=`n'} - -The @code{m} stands for maximum. -@code{n} is a decimal integer in the -range of 1 to 999999 and limits the number of error or warning -messages to be generated. For example, using -@code{-gnatm2} might yield - -@example -e.adb:3:04: Incorrect spelling of keyword "function" -e.adb:5:35: missing ".." -fatal error: maximum number of errors detected -compilation abandoned -@end example - -The default setting if -no switch is given is 9999. If the number of warnings reaches this -limit, then a message is output and further warnings are suppressed, -but the compilation is continued. If the number of error messages -reaches this limit, then a message is output and the compilation -is abandoned. A value of zero means that no limit applies. - -Note that the equal sign is optional, so the switches -@code{-gnatm2} and @code{-gnatm=2} are equivalent. -@end table - -@geindex -gnatf (gcc) - - -@table @asis - -@item @code{-gnatf} - -@geindex Error messages -@geindex suppressing - -The @code{f} stands for full. -Normally, the compiler suppresses error messages that are likely to be -redundant. This switch causes all error -messages to be generated. In particular, in the case of -references to undefined variables. If a given variable is referenced -several times, the normal format of messages is - -@example -e.adb:7:07: "V" is undefined (more references follow) -@end example - -where the parenthetical comment warns that there are additional -references to the variable @code{V}. Compiling the same program with the -@code{-gnatf} switch yields - -@example -e.adb:7:07: "V" is undefined -e.adb:8:07: "V" is undefined -e.adb:8:12: "V" is undefined -e.adb:8:16: "V" is undefined -e.adb:9:07: "V" is undefined -e.adb:9:12: "V" is undefined -@end example - -The @code{-gnatf} switch also generates additional information for -some error messages. Some examples are: - - -@itemize * - -@item -Details on possibly non-portable unchecked conversion - -@item -List possible interpretations for ambiguous calls - -@item -Additional details on incorrect parameters -@end itemize -@end table - -@geindex -gnatjnn (gcc) - - -@table @asis - -@item @code{-gnatjnn} - -In normal operation mode (or if @code{-gnatj0} is used), then error messages -with continuation lines are treated as though the continuation lines were -separate messages (and so a warning with two continuation lines counts as -three warnings, and is listed as three separate messages). - -If the @code{-gnatjnn} switch is used with a positive value for nn, then -messages are output in a different manner. A message and all its continuation -lines are treated as a unit, and count as only one warning or message in the -statistics totals. Furthermore, the message is reformatted so that no line -is longer than nn characters. -@end table - -@geindex -gnatq (gcc) - - -@table @asis - -@item @code{-gnatq} - -The @code{q} stands for quit (really ‘don’t quit’). -In normal operation mode, the compiler first parses the program and -determines if there are any syntax errors. If there are, appropriate -error messages are generated and compilation is immediately terminated. -This switch tells -GNAT to continue with semantic analysis even if syntax errors have been -found. This may enable the detection of more errors in a single run. On -the other hand, the semantic analyzer is more likely to encounter some -internal fatal error when given a syntactically invalid tree. -@end table - -@geindex -gnatQ (gcc) - - -@table @asis - -@item @code{-gnatQ} - -In normal operation mode, the @code{ALI} file is not generated if any -illegalities are detected in the program. The use of @code{-gnatQ} forces -generation of the @code{ALI} file. This file is marked as being in -error, so it cannot be used for binding purposes, but it does contain -reasonably complete cross-reference information, and thus may be useful -for use by tools (e.g., semantic browsing tools or integrated development -environments) that are driven from the @code{ALI} file. This switch -implies @code{-gnatq}, since the semantic phase must be run to get a -meaningful ALI file. - -When @code{-gnatQ} is used and the generated @code{ALI} file is marked as -being in error, @code{gnatmake} will attempt to recompile the source when it -finds such an @code{ALI} file, including with switch @code{-gnatc}. - -Note that @code{-gnatQ} has no effect if @code{-gnats} is specified, -since ALI files are never generated if @code{-gnats} is set. -@end table - -@node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{eb} -@subsection Warning Message Control - - -@geindex Warning messages - -In addition to error messages, which correspond to illegalities as defined -in the Ada Reference Manual, the compiler detects two kinds of warning -situations. - -First, the compiler considers some constructs suspicious and generates a -warning message to alert you to a possible error. Second, if the -compiler detects a situation that is sure to raise an exception at -run time, it generates a warning message. The following shows an example -of warning messages: - -@example -e.adb:4:24: warning: creation of object may raise Storage_Error -e.adb:10:17: warning: static value out of range -e.adb:10:17: warning: "Constraint_Error" will be raised at run time -@end example - -GNAT considers a large number of situations as appropriate -for the generation of warning messages. As always, warnings are not -definite indications of errors. For example, if you do an out-of-range -assignment with the deliberate intention of raising a -@code{Constraint_Error} exception, then the warning that may be -issued does not indicate an error. Some of the situations for which GNAT -issues warnings (at least some of the time) are given in the following -list. This list is not complete, and new warnings are often added to -subsequent versions of GNAT. The list is intended to give a general idea -of the kinds of warnings that are generated. - - -@itemize * - -@item -Possible infinitely recursive calls - -@item -Out-of-range values being assigned - -@item -Possible order of elaboration problems - -@item -Size not a multiple of alignment for a record type - -@item -Assertions (pragma Assert) that are sure to fail - -@item -Unreachable code - -@item -Address clauses with possibly unaligned values, or where an attempt is -made to overlay a smaller variable with a larger one. - -@item -Fixed-point type declarations with a null range - -@item -Direct_IO or Sequential_IO instantiated with a type that has access values - -@item -Variables that are never assigned a value - -@item -Variables that are referenced before being initialized - -@item -Task entries with no corresponding @code{accept} statement - -@item -Duplicate accepts for the same task entry in a @code{select} - -@item -Objects that take too much storage - -@item -Unchecked conversion between types of differing sizes - -@item -Missing @code{return} statement along some execution path in a function - -@item -Incorrect (unrecognized) pragmas - -@item -Incorrect external names - -@item -Allocation from empty storage pool - -@item -Potentially blocking operation in protected type - -@item -Suspicious parenthesization of expressions - -@item -Mismatching bounds in an aggregate - -@item -Attempt to return local value by reference - -@item -Premature instantiation of a generic body - -@item -Attempt to pack aliased components - -@item -Out of bounds array subscripts - -@item -Wrong length on string assignment - -@item -Violations of style rules if style checking is enabled - -@item -Unused `with' clauses - -@item -@code{Bit_Order} usage that does not have any effect - -@item -@code{Standard.Duration} used to resolve universal fixed expression - -@item -Dereference of possibly null value - -@item -Declaration that is likely to cause storage error - -@item -Internal GNAT unit `with'ed by application unit - -@item -Values known to be out of range at compile time - -@item -Unreferenced or unmodified variables. Note that a special -exemption applies to variables which contain any of the substrings -@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables -are considered likely to be intentionally used in a situation where -otherwise a warning would be given, so warnings of this kind are -always suppressed for such variables. - -@item -Address overlays that could clobber memory - -@item -Unexpected initialization when address clause present - -@item -Bad alignment for address clause - -@item -Useless type conversions - -@item -Redundant assignment statements and other redundant constructs - -@item -Useless exception handlers - -@item -Accidental hiding of name by child unit - -@item -Access before elaboration detected at compile time - -@item -A range in a @code{for} loop that is known to be null or might be null -@end itemize - -The following section lists compiler switches that are available -to control the handling of warning messages. It is also possible -to exercise much finer control over what warnings are issued and -suppressed using the GNAT pragma Warnings (see the description -of the pragma in the @cite{GNAT_Reference_manual}). - -@geindex -gnatwa (gcc) - - -@table @asis - -@item @code{-gnatwa} - -`Activate most optional warnings.' - -This switch activates most optional warning messages. See the remaining list -in this section for details on optional warning messages that can be -individually controlled. The warnings that are not turned on by this -switch are: - - -@itemize * - -@item -@code{-gnatwd} (implicit dereferencing) - -@item -@code{-gnatw.d} (tag warnings with -gnatw switch) - -@item -@code{-gnatwh} (hiding) - -@item -@code{-gnatw.h} (holes in record layouts) - -@item -@code{-gnatw.j} (late primitives of tagged types) - -@item -@code{-gnatw.k} (redefinition of names in standard) - -@item -@code{-gnatwl} (elaboration warnings) - -@item -@code{-gnatw.l} (inherited aspects) - -@item -@code{-gnatw.n} (atomic synchronization) - -@item -@code{-gnatwo} (address clause overlay) - -@item -@code{-gnatw.o} (values set by out parameters ignored) - -@item -@code{-gnatw.q} (questionable layout of record types) - -@item -@code{-gnatw_q} (ignored equality) - -@item -@code{-gnatw_r} (out-of-order record representation clauses) - -@item -@code{-gnatw.s} (overridden size clause) - -@item -@code{-gnatwt} (tracking of deleted conditional code) - -@item -@code{-gnatw.u} (unordered enumeration) - -@item -@code{-gnatw.w} (use of Warnings Off) - -@item -@code{-gnatw.y} (reasons for package needing body) -@end itemize - -All other optional warnings are turned on. -@end table - -@geindex -gnatwA (gcc) - - -@table @asis - -@item @code{-gnatwA} - -`Suppress all optional errors.' - -This switch suppresses all optional warning messages, see remaining list -in this section for details on optional warning messages that can be -individually controlled. Note that unlike switch @code{-gnatws}, the -use of switch @code{-gnatwA} does not suppress warnings that are -normally given unconditionally and cannot be individually controlled -(for example, the warning about a missing exit path in a function). -Also, again unlike switch @code{-gnatws}, warnings suppressed by -the use of switch @code{-gnatwA} can be individually turned back -on. For example the use of switch @code{-gnatwA} followed by -switch @code{-gnatwd} will suppress all optional warnings except -the warnings for implicit dereferencing. -@end table - -@geindex -gnatw.a (gcc) - - -@table @asis - -@item @code{-gnatw.a} - -`Activate warnings on failing assertions.' - -@geindex Assert failures - -This switch activates warnings for assertions where the compiler can tell at -compile time that the assertion will fail. Note that this warning is given -even if assertions are disabled. The default is that such warnings are -generated. -@end table - -@geindex -gnatw.A (gcc) - - -@table @asis - -@item @code{-gnatw.A} - -`Suppress warnings on failing assertions.' - -@geindex Assert failures - -This switch suppresses warnings for assertions where the compiler can tell at -compile time that the assertion will fail. -@end table - -@geindex -gnatw_a - - -@table @asis - -@item @code{-gnatw_a} - -`Activate warnings on anonymous allocators.' - -@geindex Anonymous allocators - -This switch activates warnings for allocators of anonymous access types, -which can involve run-time accessibility checks and lead to unexpected -accessibility violations. For more details on the rules involved, see -RM 3.10.2 (14). -@end table - -@geindex -gnatw_A - - -@table @asis - -@item @code{-gnatw_A} - -`Supress warnings on anonymous allocators.' - -@geindex Anonymous allocators - -This switch suppresses warnings for anonymous access type allocators. -@end table - -@geindex -gnatwb (gcc) - - -@table @asis - -@item @code{-gnatwb} - -`Activate warnings on bad fixed values.' - -@geindex Bad fixed values - -@geindex Fixed-point Small value - -@geindex Small value - -This switch activates warnings for static fixed-point expressions whose -value is not an exact multiple of Small. Such values are implementation -dependent, since an implementation is free to choose either of the multiples -that surround the value. GNAT always chooses the closer one, but this is not -required behavior, and it is better to specify a value that is an exact -multiple, ensuring predictable execution. The default is that such warnings -are not generated. -@end table - -@geindex -gnatwB (gcc) - - -@table @asis - -@item @code{-gnatwB} - -`Suppress warnings on bad fixed values.' - -This switch suppresses warnings for static fixed-point expressions whose -value is not an exact multiple of Small. -@end table - -@geindex -gnatw.b (gcc) - - -@table @asis - -@item @code{-gnatw.b} - -`Activate warnings on biased representation.' - -@geindex Biased representation - -This switch activates warnings when a size clause, value size clause, component -clause, or component size clause forces the use of biased representation for an -integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 -to represent 10/11). The default is that such warnings are generated. -@end table - -@geindex -gnatwB (gcc) - - -@table @asis - -@item @code{-gnatw.B} - -`Suppress warnings on biased representation.' - -This switch suppresses warnings for representation clauses that force the use -of biased representation. -@end table - -@geindex -gnatwc (gcc) - - -@table @asis - -@item @code{-gnatwc} - -`Activate warnings on conditionals.' - -@geindex Conditionals -@geindex constant - -This switch activates warnings for conditional expressions used in -tests that are known to be True or False at compile time. The default -is that such warnings are not generated. -Note that this warning does -not get issued for the use of boolean constants whose -values are known at compile time, since this is a standard technique -for conditional compilation in Ada, and this would generate too many -false positive warnings. - -This warning option also activates a special test for comparisons using -the operators ‘>=’ and’ <=’. -If the compiler can tell that only the equality condition is possible, -then it will warn that the ‘>’ or ‘<’ part of the test -is useless and that the operator could be replaced by ‘=’. -An example would be comparing a @code{Natural} variable <= 0. - -This warning option also generates warnings if -one or both tests is optimized away in a membership test for integer -values if the result can be determined at compile time. Range tests on -enumeration types are not included, since it is common for such tests -to include an end point. - -This warning can also be turned on using @code{-gnatwa}. -@end table - -@geindex -gnatwC (gcc) - - -@table @asis - -@item @code{-gnatwC} - -`Suppress warnings on conditionals.' - -This switch suppresses warnings for conditional expressions used in -tests that are known to be True or False at compile time. -@end table - -@geindex -gnatw.c (gcc) - - -@table @asis - -@item @code{-gnatw.c} - -`Activate warnings on missing component clauses.' - -@geindex Component clause -@geindex missing - -This switch activates warnings for record components where a record -representation clause is present and has component clauses for the -majority, but not all, of the components. A warning is given for each -component for which no component clause is present. -@end table - -@geindex -gnatw.C (gcc) - - -@table @asis - -@item @code{-gnatw.C} - -`Suppress warnings on missing component clauses.' - -This switch suppresses warnings for record components that are -missing a component clause in the situation described above. -@end table - -@geindex -gnatw_c (gcc) - - -@table @asis - -@item @code{-gnatw_c} - -`Activate warnings on unknown condition in Compile_Time_Warning.' - -@geindex Compile_Time_Warning - -@geindex Compile_Time_Error - -This switch activates warnings on a pragma Compile_Time_Warning -or Compile_Time_Error whose condition has a value that is not -known at compile time. -The default is that such warnings are generated. -@end table - -@geindex -gnatw_C (gcc) - - -@table @asis - -@item @code{-gnatw_C} - -`Suppress warnings on unknown condition in Compile_Time_Warning.' - -This switch supresses warnings on a pragma Compile_Time_Warning -or Compile_Time_Error whose condition has a value that is not -known at compile time. -@end table - -@geindex -gnatwd (gcc) - - -@table @asis - -@item @code{-gnatwd} - -`Activate warnings on implicit dereferencing.' - -If this switch is set, then the use of a prefix of an access type -in an indexed component, slice, or selected component without an -explicit @code{.all} will generate a warning. With this warning -enabled, access checks occur only at points where an explicit -@code{.all} appears in the source code (assuming no warnings are -generated as a result of this switch). The default is that such -warnings are not generated. -@end table - -@geindex -gnatwD (gcc) - - -@table @asis - -@item @code{-gnatwD} - -`Suppress warnings on implicit dereferencing.' - -@geindex Implicit dereferencing - -@geindex Dereferencing -@geindex implicit - -This switch suppresses warnings for implicit dereferences in -indexed components, slices, and selected components. -@end table - -@geindex -gnatw.d (gcc) - - -@table @asis - -@item @code{-gnatw.d} - -`Activate tagging of warning and info messages.' - -If this switch is set, then warning messages are tagged, with one of the -following strings: - -@quotation - - -@itemize - - -@item -`[-gnatw?]' -Used to tag warnings controlled by the switch @code{-gnatwx} where x -is a letter a-z. - -@item -`[-gnatw.?]' -Used to tag warnings controlled by the switch @code{-gnatw.x} where x -is a letter a-z. - -@item -`[-gnatel]' -Used to tag elaboration information (info) messages generated when the -static model of elaboration is used and the @code{-gnatel} switch is set. - -@item -`[restriction warning]' -Used to tag warning messages for restriction violations, activated by use -of the pragma @code{Restriction_Warnings}. - -@item -`[warning-as-error]' -Used to tag warning messages that have been converted to error messages by -use of the pragma Warning_As_Error. Note that such warnings are prefixed by -the string “error: “ rather than “warning: “. - -@item -`[enabled by default]' -Used to tag all other warnings that are always given by default, unless -warnings are completely suppressed using pragma `Warnings(Off)' or -the switch @code{-gnatws}. -@end itemize -@end quotation -@end table - -@geindex -gnatw.d (gcc) - - -@table @asis - -@item @code{-gnatw.D} - -`Deactivate tagging of warning and info messages messages.' - -If this switch is set, then warning messages return to the default -mode in which warnings and info messages are not tagged as described above for -@code{-gnatw.d}. -@end table - -@geindex -gnatwe (gcc) - -@geindex Warnings -@geindex treat as error - - -@table @asis - -@item @code{-gnatwe} - -`Treat warnings and style checks as errors.' - -This switch causes warning messages and style check messages to be -treated as errors. -The warning string still appears, but the warning messages are counted -as errors, and prevent the generation of an object file. Note that this -is the only -gnatw switch that affects the handling of style check messages. -Note also that this switch has no effect on info (information) messages, which -are not treated as errors if this switch is present. -@end table - -@geindex -gnatw.e (gcc) - - -@table @asis - -@item @code{-gnatw.e} - -`Activate every optional warning.' - -@geindex Warnings -@geindex activate every optional warning - -This switch activates all optional warnings, including those which -are not activated by @code{-gnatwa}. The use of this switch is not -recommended for normal use. If you turn this switch on, it is almost -certain that you will get large numbers of useless warnings. The -warnings that are excluded from @code{-gnatwa} are typically highly -specialized warnings that are suitable for use only in code that has -been specifically designed according to specialized coding rules. -@end table - -@geindex -gnatwE (gcc) - -@geindex Warnings -@geindex treat as error - - -@table @asis - -@item @code{-gnatwE} - -`Treat all run-time exception warnings as errors.' - -This switch causes warning messages regarding errors that will be raised -during run-time execution to be treated as errors. -@end table - -@geindex -gnatwf (gcc) - - -@table @asis - -@item @code{-gnatwf} - -`Activate warnings on unreferenced formals.' - -@geindex Formals -@geindex unreferenced - -This switch causes a warning to be generated if a formal parameter -is not referenced in the body of the subprogram. This warning can -also be turned on using @code{-gnatwu}. The -default is that these warnings are not generated. -@end table - -@geindex -gnatwF (gcc) - - -@table @asis - -@item @code{-gnatwF} - -`Suppress warnings on unreferenced formals.' - -This switch suppresses warnings for unreferenced formal -parameters. Note that the -combination @code{-gnatwu} followed by @code{-gnatwF} has the -effect of warning on unreferenced entities other than subprogram -formals. -@end table - -@geindex -gnatwg (gcc) - - -@table @asis - -@item @code{-gnatwg} - -`Activate warnings on unrecognized pragmas.' - -@geindex Pragmas -@geindex unrecognized - -This switch causes a warning to be generated if an unrecognized -pragma is encountered. Apart from issuing this warning, the -pragma is ignored and has no effect. The default -is that such warnings are issued (satisfying the Ada Reference -Manual requirement that such warnings appear). -@end table - -@geindex -gnatwG (gcc) - - -@table @asis - -@item @code{-gnatwG} - -`Suppress warnings on unrecognized pragmas.' - -This switch suppresses warnings for unrecognized pragmas. -@end table - -@geindex -gnatw.g (gcc) - - -@table @asis - -@item @code{-gnatw.g} - -`Warnings used for GNAT sources.' - -This switch sets the warning categories that are used by the standard -GNAT style. Currently this is equivalent to -@code{-gnatwAao.q.s.CI.V.X.Z} -but more warnings may be added in the future without advanced notice. -@end table - -@geindex -gnatwh (gcc) - - -@table @asis - -@item @code{-gnatwh} - -`Activate warnings on hiding.' - -@geindex Hiding of Declarations - -This switch activates warnings on hiding declarations that are considered -potentially confusing. Not all cases of hiding cause warnings; for example an -overriding declaration hides an implicit declaration, which is just normal -code. The default is that warnings on hiding are not generated. -@end table - -@geindex -gnatwH (gcc) - - -@table @asis - -@item @code{-gnatwH} - -`Suppress warnings on hiding.' - -This switch suppresses warnings on hiding declarations. -@end table - -@geindex -gnatw.h (gcc) - - -@table @asis - -@item @code{-gnatw.h} - -`Activate warnings on holes/gaps in records.' - -@geindex Record Representation (gaps) - -This switch activates warnings on component clauses in record -representation clauses that leave holes (gaps) in the record layout. -If this warning option is active, then record representation clauses -should specify a contiguous layout, adding unused fill fields if needed. -@end table - -@geindex -gnatw.H (gcc) - - -@table @asis - -@item @code{-gnatw.H} - -`Suppress warnings on holes/gaps in records.' - -This switch suppresses warnings on component clauses in record -representation clauses that leave holes (haps) in the record layout. -@end table - -@geindex -gnatwi (gcc) - - -@table @asis - -@item @code{-gnatwi} - -`Activate warnings on implementation units.' - -This switch activates warnings for a `with' of an internal GNAT -implementation unit, defined as any unit from the @code{Ada}, -@code{Interfaces}, @code{GNAT}, -or @code{System} -hierarchies that is not -documented in either the Ada Reference Manual or the GNAT -Programmer’s Reference Manual. Such units are intended only -for internal implementation purposes and should not be `with'ed -by user programs. The default is that such warnings are generated -@end table - -@geindex -gnatwI (gcc) - - -@table @asis - -@item @code{-gnatwI} - -`Disable warnings on implementation units.' - -This switch disables warnings for a `with' of an internal GNAT -implementation unit. -@end table - -@geindex -gnatw.i (gcc) - - -@table @asis - -@item @code{-gnatw.i} - -`Activate warnings on overlapping actuals.' - -This switch enables a warning on statically detectable overlapping actuals in -a subprogram call, when one of the actuals is an in-out parameter, and the -types of the actuals are not by-copy types. This warning is off by default. -@end table - -@geindex -gnatw.I (gcc) - - -@table @asis - -@item @code{-gnatw.I} - -`Disable warnings on overlapping actuals.' - -This switch disables warnings on overlapping actuals in a call. -@end table - -@geindex -gnatwj (gcc) - - -@table @asis - -@item @code{-gnatwj} - -`Activate warnings on obsolescent features (Annex J).' - -@geindex Features -@geindex obsolescent - -@geindex Obsolescent features - -If this warning option is activated, then warnings are generated for -calls to subprograms marked with @code{pragma Obsolescent} and -for use of features in Annex J of the Ada Reference Manual. In the -case of Annex J, not all features are flagged. In particular, uses of package -@code{ASCII} are not flagged, since these are very common and -would generate many annoying positive warnings. The default is that -such warnings are not generated. - -In addition to the above cases, warnings are also generated for -GNAT features that have been provided in past versions but which -have been superseded (typically by features in the new Ada standard). -For example, @code{pragma Ravenscar} will be flagged since its -function is replaced by @code{pragma Profile(Ravenscar)}, and -@code{pragma Interface_Name} will be flagged since its function -is replaced by @code{pragma Import}. - -Note that this warning option functions differently from the -restriction @code{No_Obsolescent_Features} in two respects. -First, the restriction applies only to annex J features. -Second, the restriction does flag uses of package @code{ASCII}. -@end table - -@geindex -gnatwJ (gcc) - - -@table @asis - -@item @code{-gnatwJ} - -`Suppress warnings on obsolescent features (Annex J).' - -This switch disables warnings on use of obsolescent features. -@end table - -@geindex -gnatw.j (gcc) - - -@table @asis - -@item @code{-gnatw.j} - -`Activate warnings on late declarations of tagged type primitives.' - -This switch activates warnings on visible primitives added to a -tagged type after deriving a private extension from it. -@end table - -@geindex -gnatw.J (gcc) - - -@table @asis - -@item @code{-gnatw.J} - -`Suppress warnings on late declarations of tagged type primitives.' - -This switch suppresses warnings on visible primitives added to a -tagged type after deriving a private extension from it. -@end table - -@geindex -gnatwk (gcc) - - -@table @asis - -@item @code{-gnatwk} - -`Activate warnings on variables that could be constants.' - -This switch activates warnings for variables that are initialized but -never modified, and then could be declared constants. The default is that -such warnings are not given. -@end table - -@geindex -gnatwK (gcc) - - -@table @asis - -@item @code{-gnatwK} - -`Suppress warnings on variables that could be constants.' - -This switch disables warnings on variables that could be declared constants. -@end table - -@geindex -gnatw.k (gcc) - - -@table @asis - -@item @code{-gnatw.k} - -`Activate warnings on redefinition of names in standard.' - -This switch activates warnings for declarations that declare a name that -is defined in package Standard. Such declarations can be confusing, -especially since the names in package Standard continue to be directly -visible, meaning that use visibiliy on such redeclared names does not -work as expected. Names of discriminants and components in records are -not included in this check. -@end table - -@geindex -gnatwK (gcc) - - -@table @asis - -@item @code{-gnatw.K} - -`Suppress warnings on redefinition of names in standard.' - -This switch disables warnings for declarations that declare a name that -is defined in package Standard. -@end table - -@geindex -gnatwl (gcc) - - -@table @asis - -@item @code{-gnatwl} - -`Activate warnings for elaboration pragmas.' - -@geindex Elaboration -@geindex warnings - -This switch activates warnings for possible elaboration problems, -including suspicious use -of @code{Elaborate} pragmas, when using the static elaboration model, and -possible situations that may raise @code{Program_Error} when using the -dynamic elaboration model. -See the section in this guide on elaboration checking for further details. -The default is that such warnings -are not generated. -@end table - -@geindex -gnatwL (gcc) - - -@table @asis - -@item @code{-gnatwL} - -`Suppress warnings for elaboration pragmas.' - -This switch suppresses warnings for possible elaboration problems. -@end table - -@geindex -gnatw.l (gcc) - - -@table @asis - -@item @code{-gnatw.l} - -`List inherited aspects.' - -This switch causes the compiler to list inherited invariants, -preconditions, and postconditions from Type_Invariant’Class, Invariant’Class, -Pre’Class, and Post’Class aspects. Also list inherited subtype predicates. -@end table - -@geindex -gnatw.L (gcc) - - -@table @asis - -@item @code{-gnatw.L} - -`Suppress listing of inherited aspects.' - -This switch suppresses listing of inherited aspects. -@end table - -@geindex -gnatwm (gcc) - - -@table @asis - -@item @code{-gnatwm} - -`Activate warnings on modified but unreferenced variables.' - -This switch activates warnings for variables that are assigned (using -an initialization value or with one or more assignment statements) but -whose value is never read. The warning is suppressed for volatile -variables and also for variables that are renamings of other variables -or for which an address clause is given. -The default is that these warnings are not given. -@end table - -@geindex -gnatwM (gcc) - - -@table @asis - -@item @code{-gnatwM} - -`Disable warnings on modified but unreferenced variables.' - -This switch disables warnings for variables that are assigned or -initialized, but never read. -@end table - -@geindex -gnatw.m (gcc) - - -@table @asis - -@item @code{-gnatw.m} - -`Activate warnings on suspicious modulus values.' - -This switch activates warnings for modulus values that seem suspicious. -The cases caught are where the size is the same as the modulus (e.g. -a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 -with no size clause. The guess in both cases is that 2**x was intended -rather than x. In addition expressions of the form 2*x for small x -generate a warning (the almost certainly accurate guess being that -2**x was intended). This switch also activates warnings for negative -literal values of a modular type, which are interpreted as large positive -integers after wrap-around. The default is that these warnings are given. -@end table - -@geindex -gnatw.M (gcc) - - -@table @asis - -@item @code{-gnatw.M} - -`Disable warnings on suspicious modulus values.' - -This switch disables warnings for suspicious modulus values. -@end table - -@geindex -gnatwn (gcc) - - -@table @asis - -@item @code{-gnatwn} - -`Set normal warnings mode.' - -This switch sets normal warning mode, in which enabled warnings are -issued and treated as warnings rather than errors. This is the default -mode. the switch @code{-gnatwn} can be used to cancel the effect of -an explicit @code{-gnatws} or -@code{-gnatwe}. It also cancels the effect of the -implicit @code{-gnatwe} that is activated by the -use of @code{-gnatg}. -@end table - -@geindex -gnatw.n (gcc) - -@geindex Atomic Synchronization -@geindex warnings - - -@table @asis - -@item @code{-gnatw.n} - -`Activate warnings on atomic synchronization.' - -This switch actives warnings when an access to an atomic variable -requires the generation of atomic synchronization code. These -warnings are off by default. -@end table - -@geindex -gnatw.N (gcc) - - -@table @asis - -@item @code{-gnatw.N} - -`Suppress warnings on atomic synchronization.' - -@geindex Atomic Synchronization -@geindex warnings - -This switch suppresses warnings when an access to an atomic variable -requires the generation of atomic synchronization code. -@end table - -@geindex -gnatwo (gcc) - -@geindex Address Clauses -@geindex warnings - - -@table @asis - -@item @code{-gnatwo} - -`Activate warnings on address clause overlays.' - -This switch activates warnings for possibly unintended initialization -effects of defining address clauses that cause one variable to overlap -another. The default is that such warnings are generated. -@end table - -@geindex -gnatwO (gcc) - - -@table @asis - -@item @code{-gnatwO} - -`Suppress warnings on address clause overlays.' - -This switch suppresses warnings on possibly unintended initialization -effects of defining address clauses that cause one variable to overlap -another. -@end table - -@geindex -gnatw.o (gcc) - - -@table @asis - -@item @code{-gnatw.o} - -`Activate warnings on modified but unreferenced out parameters.' - -This switch activates warnings for variables that are modified by using -them as actuals for a call to a procedure with an out mode formal, where -the resulting assigned value is never read. It is applicable in the case -where there is more than one out mode formal. If there is only one out -mode formal, the warning is issued by default (controlled by -gnatwu). -The warning is suppressed for volatile -variables and also for variables that are renamings of other variables -or for which an address clause is given. -The default is that these warnings are not given. -@end table - -@geindex -gnatw.O (gcc) - - -@table @asis - -@item @code{-gnatw.O} - -`Disable warnings on modified but unreferenced out parameters.' - -This switch suppresses warnings for variables that are modified by using -them as actuals for a call to a procedure with an out mode formal, where -the resulting assigned value is never read. -@end table - -@geindex -gnatwp (gcc) - -@geindex Inlining -@geindex warnings - - -@table @asis - -@item @code{-gnatwp} - -`Activate warnings on ineffective pragma Inlines.' - -This switch activates warnings for failure of front end inlining -(activated by @code{-gnatN}) to inline a particular call. There are -many reasons for not being able to inline a call, including most -commonly that the call is too complex to inline. The default is -that such warnings are not given. -Warnings on ineffective inlining by the gcc back-end can be activated -separately, using the gcc switch -Winline. -@end table - -@geindex -gnatwP (gcc) - - -@table @asis - -@item @code{-gnatwP} - -`Suppress warnings on ineffective pragma Inlines.' - -This switch suppresses warnings on ineffective pragma Inlines. If the -inlining mechanism cannot inline a call, it will simply ignore the -request silently. -@end table - -@geindex -gnatw.p (gcc) - -@geindex Parameter order -@geindex warnings - - -@table @asis - -@item @code{-gnatw.p} - -`Activate warnings on parameter ordering.' - -This switch activates warnings for cases of suspicious parameter -ordering when the list of arguments are all simple identifiers that -match the names of the formals, but are in a different order. The -warning is suppressed if any use of named parameter notation is used, -so this is the appropriate way to suppress a false positive (and -serves to emphasize that the “misordering” is deliberate). The -default is that such warnings are not given. -@end table - -@geindex -gnatw.P (gcc) - - -@table @asis - -@item @code{-gnatw.P} - -`Suppress warnings on parameter ordering.' - -This switch suppresses warnings on cases of suspicious parameter -ordering. -@end table - -@geindex -gnatw_p (gcc) - - -@table @asis - -@item @code{-gnatw_p} - -`Activate warnings for pedantic checks.' - -This switch activates warnings for the failure of certain pedantic checks. -The only case currently supported is a check that the subtype_marks given -for corresponding formal parameter and function results in a subprogram -declaration and its body denote the same subtype declaration. The default -is that such warnings are not given. -@end table - -@geindex -gnatw_P (gcc) - - -@table @asis - -@item @code{-gnatw_P} - -`Suppress warnings for pedantic checks.' - -This switch suppresses warnings on violations of pedantic checks. -@end table - -@geindex -gnatwq (gcc) - -@geindex Parentheses -@geindex warnings - - -@table @asis - -@item @code{-gnatwq} - -`Activate warnings on questionable missing parentheses.' - -This switch activates warnings for cases where parentheses are not used and -the result is potential ambiguity from a readers point of view. For example -(not a > b) when a and b are modular means ((not a) > b) and very likely the -programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and -quite likely ((-x) mod 5) was intended. In such situations it seems best to -follow the rule of always parenthesizing to make the association clear, and -this warning switch warns if such parentheses are not present. The default -is that these warnings are given. -@end table - -@geindex -gnatwQ (gcc) - - -@table @asis - -@item @code{-gnatwQ} - -`Suppress warnings on questionable missing parentheses.' - -This switch suppresses warnings for cases where the association is not -clear and the use of parentheses is preferred. -@end table - -@geindex -gnatw.q (gcc) - -@geindex Layout -@geindex warnings - - -@table @asis - -@item @code{-gnatw.q} - -`Activate warnings on questionable layout of record types.' - -This switch activates warnings for cases where the default layout of -a record type, that is to say the layout of its components in textual -order of the source code, would very likely cause inefficiencies in -the code generated by the compiler, both in terms of space and speed -during execution. One warning is issued for each problematic component -without representation clause in the nonvariant part and then in each -variant recursively, if any. - -The purpose of these warnings is neither to prescribe an optimal layout -nor to force the use of representation clauses, but rather to get rid of -the most blatant inefficiencies in the layout. Therefore, the default -layout is matched against the following synthetic ordered layout and -the deviations are flagged on a component-by-component basis: - - -@itemize * - -@item -first all components or groups of components whose length is fixed -and a multiple of the storage unit, - -@item -then the remaining components whose length is fixed and not a multiple -of the storage unit, - -@item -then the remaining components whose length doesn’t depend on discriminants -(that is to say, with variable but uniform length for all objects), - -@item -then all components whose length depends on discriminants, - -@item -finally the variant part (if any), -@end itemize - -for the nonvariant part and for each variant recursively, if any. - -The exact wording of the warning depends on whether the compiler is allowed -to reorder the components in the record type or precluded from doing it by -means of pragma @code{No_Component_Reordering}. - -The default is that these warnings are not given. -@end table - -@geindex -gnatw.Q (gcc) - - -@table @asis - -@item @code{-gnatw.Q} - -`Suppress warnings on questionable layout of record types.' - -This switch suppresses warnings for cases where the default layout of -a record type would very likely cause inefficiencies. -@end table - -@geindex -gnatw_q (gcc) - - -@table @asis - -@item @code{-gnatw_q} - -`Activate warnings for ignored equality operators.' - -This switch activates warnings for a user-defined “=” function that does -not compose (i.e. is ignored for a predefined “=” for a composite type -containing a component whose type has the user-defined “=” as -primitive). Note that the user-defined “=” must be a primitive operator -in order to trigger the warning. - -The default is that these warnings are not given. -@end table - -@geindex -gnatw_Q (gcc) - - -@table @asis - -@item @code{-gnatw_Q} - -`Suppress warnings for ignored equality operators.' -@end table - -@geindex -gnatwr (gcc) - - -@table @asis - -@item @code{-gnatwr} - -`Activate warnings on redundant constructs.' - -This switch activates warnings for redundant constructs. The following -is the current list of constructs regarded as redundant: - - -@itemize * - -@item -Assignment of an item to itself. - -@item -Type conversion that converts an expression to its own type. - -@item -Use of the attribute @code{Base} where @code{typ'Base} is the same -as @code{typ}. - -@item -Use of pragma @code{Pack} when all components are placed by a record -representation clause. - -@item -Exception handler containing only a reraise statement (raise with no -operand) which has no effect. - -@item -Use of the operator abs on an operand that is known at compile time -to be non-negative - -@item -Comparison of an object or (unary or binary) operation of boolean type to -an explicit True value. - -@item -Import of parent package. -@end itemize - -The default is that warnings for redundant constructs are not given. -@end table - -@geindex -gnatwR (gcc) - - -@table @asis - -@item @code{-gnatwR} - -`Suppress warnings on redundant constructs.' - -This switch suppresses warnings for redundant constructs. -@end table - -@geindex -gnatw.r (gcc) - - -@table @asis - -@item @code{-gnatw.r} - -`Activate warnings for object renaming function.' - -This switch activates warnings for an object renaming that renames a -function call, which is equivalent to a constant declaration (as -opposed to renaming the function itself). The default is that these -warnings are given. -@end table - -@geindex -gnatw.R (gcc) - - -@table @asis - -@item @code{-gnatw.R} - -`Suppress warnings for object renaming function.' - -This switch suppresses warnings for object renaming function. -@end table - -@geindex -gnatw_r (gcc) - - -@table @asis - -@item @code{-gnatw_r} - -`Activate warnings for out-of-order record representation clauses.' - -This switch activates warnings for record representation clauses, -if the order of component declarations, component clauses, -and bit-level layout do not all agree. -The default is that these warnings are not given. -@end table - -@geindex -gnatw_R (gcc) - - -@table @asis - -@item @code{-gnatw_R} - -`Suppress warnings for out-of-order record representation clauses.' -@end table - -@geindex -gnatws (gcc) - - -@table @asis - -@item @code{-gnatws} - -`Suppress all warnings.' - -This switch completely suppresses the -output of all warning messages from the GNAT front end, including -both warnings that can be controlled by switches described in this -section, and those that are normally given unconditionally. The -effect of this suppress action can only be cancelled by a subsequent -use of the switch @code{-gnatwn}. - -Note that switch @code{-gnatws} does not suppress -warnings from the @code{gcc} back end. -To suppress these back end warnings as well, use the switch @code{-w} -in addition to @code{-gnatws}. Also this switch has no effect on the -handling of style check messages. -@end table - -@geindex -gnatw.s (gcc) - -@geindex Record Representation (component sizes) - - -@table @asis - -@item @code{-gnatw.s} - -`Activate warnings on overridden size clauses.' - -This switch activates warnings on component clauses in record -representation clauses where the length given overrides that -specified by an explicit size clause for the component type. A -warning is similarly given in the array case if a specified -component size overrides an explicit size clause for the array -component type. -@end table - -@geindex -gnatw.S (gcc) - - -@table @asis - -@item @code{-gnatw.S} - -`Suppress warnings on overridden size clauses.' - -This switch suppresses warnings on component clauses in record -representation clauses that override size clauses, and similar -warnings when an array component size overrides a size clause. -@end table - -@geindex -gnatwt (gcc) - -@geindex Deactivated code -@geindex warnings - -@geindex Deleted code -@geindex warnings - - -@table @asis - -@item @code{-gnatwt} - -`Activate warnings for tracking of deleted conditional code.' - -This switch activates warnings for tracking of code in conditionals (IF and -CASE statements) that is detected to be dead code which cannot be executed, and -which is removed by the front end. This warning is off by default. This may be -useful for detecting deactivated code in certified applications. -@end table - -@geindex -gnatwT (gcc) - - -@table @asis - -@item @code{-gnatwT} - -`Suppress warnings for tracking of deleted conditional code.' - -This switch suppresses warnings for tracking of deleted conditional code. -@end table - -@geindex -gnatw.t (gcc) - - -@table @asis - -@item @code{-gnatw.t} - -`Activate warnings on suspicious contracts.' - -This switch activates warnings on suspicious contracts. This includes -warnings on suspicious postconditions (whether a pragma @code{Postcondition} or a -@code{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect -@code{Contract_Cases}). A function postcondition or contract case is suspicious -when no postcondition or contract case for this function mentions the result -of the function. A procedure postcondition or contract case is suspicious -when it only refers to the pre-state of the procedure, because in that case -it should rather be expressed as a precondition. This switch also controls -warnings on suspicious cases of expressions typically found in contracts like -quantified expressions and uses of Update attribute. The default is that such -warnings are generated. -@end table - -@geindex -gnatw.T (gcc) - - -@table @asis - -@item @code{-gnatw.T} - -`Suppress warnings on suspicious contracts.' - -This switch suppresses warnings on suspicious contracts. -@end table - -@geindex -gnatwu (gcc) - - -@table @asis - -@item @code{-gnatwu} - -`Activate warnings on unused entities.' - -This switch activates warnings to be generated for entities that -are declared but not referenced, and for units that are `with'ed -and not -referenced. In the case of packages, a warning is also generated if -no entities in the package are referenced. This means that if a with’ed -package is referenced but the only references are in @code{use} -clauses or @code{renames} -declarations, a warning is still generated. A warning is also generated -for a generic package that is `with'ed but never instantiated. -In the case where a package or subprogram body is compiled, and there -is a `with' on the corresponding spec -that is only referenced in the body, -a warning is also generated, noting that the -`with' can be moved to the body. The default is that -such warnings are not generated. -This switch also activates warnings on unreferenced formals -(it includes the effect of @code{-gnatwf}). -@end table - -@geindex -gnatwU (gcc) - - -@table @asis - -@item @code{-gnatwU} - -`Suppress warnings on unused entities.' - -This switch suppresses warnings for unused entities and packages. -It also turns off warnings on unreferenced formals (and thus includes -the effect of @code{-gnatwF}). -@end table - -@geindex -gnatw.u (gcc) - - -@table @asis - -@item @code{-gnatw.u} - -`Activate warnings on unordered enumeration types.' - -This switch causes enumeration types to be considered as conceptually -unordered, unless an explicit pragma @code{Ordered} is given for the type. -The effect is to generate warnings in clients that use explicit comparisons -or subranges, since these constructs both treat objects of the type as -ordered. (A `client' is defined as a unit that is other than the unit in -which the type is declared, or its body or subunits.) Please refer to -the description of pragma @code{Ordered} in the -@cite{GNAT Reference Manual} for further details. -The default is that such warnings are not generated. -@end table - -@geindex -gnatw.U (gcc) - - -@table @asis - -@item @code{-gnatw.U} - -`Deactivate warnings on unordered enumeration types.' - -This switch causes all enumeration types to be considered as ordered, so -that no warnings are given for comparisons or subranges for any type. -@end table - -@geindex -gnatwv (gcc) - -@geindex Unassigned variable warnings - - -@table @asis - -@item @code{-gnatwv} - -`Activate warnings on unassigned variables.' - -This switch activates warnings for access to variables which -may not be properly initialized. The default is that -such warnings are generated. This switch will also be emitted when -initializing an array or record object via the following aggregate: - -@example -Array_Or_Record : XXX := (others => <>); -@end example - -unless the relevant type fully initializes all components. -@end table - -@geindex -gnatwV (gcc) - - -@table @asis - -@item @code{-gnatwV} - -`Suppress warnings on unassigned variables.' - -This switch suppresses warnings for access to variables which -may not be properly initialized. -@end table - -@geindex -gnatw.v (gcc) - -@geindex bit order warnings - - -@table @asis - -@item @code{-gnatw.v} - -`Activate info messages for non-default bit order.' - -This switch activates messages (labeled “info”, they are not warnings, -just informational messages) about the effects of non-default bit-order -on records to which a component clause is applied. The effect of specifying -non-default bit ordering is a bit subtle (and changed with Ada 2005), so -these messages, which are given by default, are useful in understanding the -exact consequences of using this feature. -@end table - -@geindex -gnatw.V (gcc) - - -@table @asis - -@item @code{-gnatw.V} - -`Suppress info messages for non-default bit order.' - -This switch suppresses information messages for the effects of specifying -non-default bit order on record components with component clauses. -@end table - -@geindex -gnatww (gcc) - -@geindex String indexing warnings - - -@table @asis - -@item @code{-gnatww} - -`Activate warnings on wrong low bound assumption.' - -This switch activates warnings for indexing an unconstrained string parameter -with a literal or S’Length. This is a case where the code is assuming that the -low bound is one, which is in general not true (for example when a slice is -passed). The default is that such warnings are generated. -@end table - -@geindex -gnatwW (gcc) - - -@table @asis - -@item @code{-gnatwW} - -`Suppress warnings on wrong low bound assumption.' - -This switch suppresses warnings for indexing an unconstrained string parameter -with a literal or S’Length. Note that this warning can also be suppressed -in a particular case by adding an assertion that the lower bound is 1, -as shown in the following example: - -@example -procedure K (S : String) is - pragma Assert (S'First = 1); - ... -@end example -@end table - -@geindex -gnatw.w (gcc) - -@geindex Warnings Off control - - -@table @asis - -@item @code{-gnatw.w} - -`Activate warnings on Warnings Off pragmas.' - -This switch activates warnings for use of @code{pragma Warnings (Off, entity)} -where either the pragma is entirely useless (because it suppresses no -warnings), or it could be replaced by @code{pragma Unreferenced} or -@code{pragma Unmodified}. -Also activates warnings for the case of -Warnings (Off, String), where either there is no matching -Warnings (On, String), or the Warnings (Off) did not suppress any warning. -The default is that these warnings are not given. -@end table - -@geindex -gnatw.W (gcc) - - -@table @asis - -@item @code{-gnatw.W} - -`Suppress warnings on unnecessary Warnings Off pragmas.' - -This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}. -@end table - -@geindex -gnatwx (gcc) - -@geindex Export/Import pragma warnings - - -@table @asis - -@item @code{-gnatwx} - -`Activate warnings on Export/Import pragmas.' - -This switch activates warnings on Export/Import pragmas when -the compiler detects a possible conflict between the Ada and -foreign language calling sequences. For example, the use of -default parameters in a convention C procedure is dubious -because the C compiler cannot supply the proper default, so -a warning is issued. The default is that such warnings are -generated. -@end table - -@geindex -gnatwX (gcc) - - -@table @asis - -@item @code{-gnatwX} - -`Suppress warnings on Export/Import pragmas.' - -This switch suppresses warnings on Export/Import pragmas. -The sense of this is that you are telling the compiler that -you know what you are doing in writing the pragma, and it -should not complain at you. -@end table - -@geindex -gnatwm (gcc) - - -@table @asis - -@item @code{-gnatw.x} - -`Activate warnings for No_Exception_Propagation mode.' - -This switch activates warnings for exception usage when pragma Restrictions -(No_Exception_Propagation) is in effect. Warnings are given for implicit or -explicit exception raises which are not covered by a local handler, and for -exception handlers which do not cover a local raise. The default is that -these warnings are given for units that contain exception handlers. - -@item @code{-gnatw.X} - -`Disable warnings for No_Exception_Propagation mode.' - -This switch disables warnings for exception usage when pragma Restrictions -(No_Exception_Propagation) is in effect. -@end table - -@geindex -gnatwy (gcc) - -@geindex Ada compatibility issues warnings - - -@table @asis - -@item @code{-gnatwy} - -`Activate warnings for Ada compatibility issues.' - -For the most part, newer versions of Ada are upwards compatible -with older versions. For example, Ada 2005 programs will almost -always work when compiled as Ada 2012. -However there are some exceptions (for example the fact that -@code{some} is now a reserved word in Ada 2012). This -switch activates several warnings to help in identifying -and correcting such incompatibilities. The default is that -these warnings are generated. Note that at one point Ada 2005 -was called Ada 0Y, hence the choice of character. -@end table - -@geindex -gnatwY (gcc) - -@geindex Ada compatibility issues warnings - - -@table @asis - -@item @code{-gnatwY} - -`Disable warnings for Ada compatibility issues.' - -This switch suppresses the warnings intended to help in identifying -incompatibilities between Ada language versions. -@end table - -@geindex -gnatw.y (gcc) - -@geindex Package spec needing body - - -@table @asis - -@item @code{-gnatw.y} - -`Activate information messages for why package spec needs body.' - -There are a number of cases in which a package spec needs a body. -For example, the use of pragma Elaborate_Body, or the declaration -of a procedure specification requiring a completion. This switch -causes information messages to be output showing why a package -specification requires a body. This can be useful in the case of -a large package specification which is unexpectedly requiring a -body. The default is that such information messages are not output. -@end table - -@geindex -gnatw.Y (gcc) - -@geindex No information messages for why package spec needs body - - -@table @asis - -@item @code{-gnatw.Y} - -`Disable information messages for why package spec needs body.' - -This switch suppresses the output of information messages showing why -a package specification needs a body. -@end table - -@geindex -gnatwz (gcc) - -@geindex Unchecked_Conversion warnings - - -@table @asis - -@item @code{-gnatwz} - -`Activate warnings on unchecked conversions.' - -This switch activates warnings for unchecked conversions -where the types are known at compile time to have different -sizes. The default is that such warnings are generated. Warnings are also -generated for subprogram pointers with different conventions. -@end table - -@geindex -gnatwZ (gcc) - - -@table @asis - -@item @code{-gnatwZ} - -`Suppress warnings on unchecked conversions.' - -This switch suppresses warnings for unchecked conversions -where the types are known at compile time to have different -sizes or conventions. -@end table - -@geindex -gnatw.z (gcc) - -@geindex Size/Alignment warnings - - -@table @asis - -@item @code{-gnatw.z} - -`Activate warnings for size not a multiple of alignment.' - -This switch activates warnings for cases of array and record types -with specified @code{Size} and @code{Alignment} attributes where the -size is not a multiple of the alignment, resulting in an object -size that is greater than the specified size. The default -is that such warnings are generated. -@end table - -@geindex -gnatw.Z (gcc) - -@geindex Size/Alignment warnings - - -@table @asis - -@item @code{-gnatw.Z} - -`Suppress warnings for size not a multiple of alignment.' - -This switch suppresses warnings for cases of array and record types -with specified @code{Size} and @code{Alignment} attributes where the -size is not a multiple of the alignment, resulting in an object -size that is greater than the specified size. The warning can also -be suppressed by giving an explicit @code{Object_Size} value. -@end table - -@geindex -Wunused (gcc) - - -@table @asis - -@item @code{-Wunused} - -The warnings controlled by the @code{-gnatw} switch are generated by -the front end of the compiler. The GCC back end can provide -additional warnings and they are controlled by the @code{-W} switch. -For example, @code{-Wunused} activates back end -warnings for entities that are declared but not referenced. -@end table - -@geindex -Wuninitialized (gcc) - - -@table @asis - -@item @code{-Wuninitialized} - -Similarly, @code{-Wuninitialized} activates -the back end warning for uninitialized variables. This switch must be -used in conjunction with an optimization level greater than zero. -@end table - -@geindex -Wstack-usage (gcc) - - -@table @asis - -@item @code{-Wstack-usage=`len'} - -Warn if the stack usage of a subprogram might be larger than @code{len} bytes. -See @ref{e6,,Static Stack Usage Analysis} for details. -@end table - -@geindex -Wall (gcc) - - -@table @asis - -@item @code{-Wall} - -This switch enables most warnings from the GCC back end. -The code generator detects a number of warning situations that are missed -by the GNAT front end, and this switch can be used to activate them. -The use of this switch also sets the default front-end warning mode to -@code{-gnatwa}, that is, most front-end warnings are activated as well. -@end table - -@geindex -w (gcc) - - -@table @asis - -@item @code{-w} - -Conversely, this switch suppresses warnings from the GCC back end. -The use of this switch also sets the default front-end warning mode to -@code{-gnatws}, that is, front-end warnings are suppressed as well. -@end table - -@geindex -Werror (gcc) - - -@table @asis - -@item @code{-Werror} - -This switch causes warnings from the GCC back end to be treated as -errors. The warning string still appears, but the warning messages are -counted as errors, and prevent the generation of an object file. -The use of this switch also sets the default front-end warning mode to -@code{-gnatwe}, that is, front-end warning messages and style check -messages are treated as errors as well. -@end table - -A string of warning parameters can be used in the same parameter. For example: - -@example --gnatwaGe -@end example - -will turn on all optional warnings except for unrecognized pragma warnings, -and also specify that warnings should be treated as errors. - -When no switch @code{-gnatw} is used, this is equivalent to: - -@quotation - - -@itemize * - -@item -@code{-gnatw.a} - -@item -@code{-gnatwB} - -@item -@code{-gnatw.b} - -@item -@code{-gnatwC} - -@item -@code{-gnatw.C} - -@item -@code{-gnatwD} - -@item -@code{-gnatw.D} - -@item -@code{-gnatwF} - -@item -@code{-gnatw.F} - -@item -@code{-gnatwg} - -@item -@code{-gnatwH} - -@item -@code{-gnatw.H} - -@item -@code{-gnatwi} - -@item -@code{-gnatwJ} - -@item -@code{-gnatw.J} - -@item -@code{-gnatwK} - -@item -@code{-gnatw.K} - -@item -@code{-gnatwL} - -@item -@code{-gnatw.L} - -@item -@code{-gnatwM} - -@item -@code{-gnatw.m} - -@item -@code{-gnatwn} - -@item -@code{-gnatw.N} - -@item -@code{-gnatwo} - -@item -@code{-gnatw.O} - -@item -@code{-gnatwP} - -@item -@code{-gnatw.P} - -@item -@code{-gnatwq} - -@item -@code{-gnatw.Q} - -@item -@code{-gnatwR} - -@item -@code{-gnatw.R} - -@item -@code{-gnatw.S} - -@item -@code{-gnatwT} - -@item -@code{-gnatw.t} - -@item -@code{-gnatwU} - -@item -@code{-gnatw.U} - -@item -@code{-gnatwv} - -@item -@code{-gnatw.v} - -@item -@code{-gnatww} - -@item -@code{-gnatw.W} - -@item -@code{-gnatwx} - -@item -@code{-gnatw.X} - -@item -@code{-gnatwy} - -@item -@code{-gnatw.Y} - -@item -@code{-gnatwz} - -@item -@code{-gnatw.z} -@end itemize -@end quotation - -@node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{f2} -@subsection Debugging and Assertion Control - - -@geindex -gnata (gcc) - - -@table @asis - -@item @code{-gnata} - -@geindex Assert - -@geindex Debug - -@geindex Assertions - -@geindex Precondition - -@geindex Postcondition - -@geindex Type invariants - -@geindex Subtype predicates - -The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma: - -@example -pragma Assertion_Policy (Check); -@end example - -Which is a shorthand for: - -@example -pragma Assertion_Policy --- Ada RM assertion pragmas - (Assert => Check, - Static_Predicate => Check, - Dynamic_Predicate => Check, - Pre => Check, - Pre'Class => Check, - Post => Check, - Post'Class => Check, - Type_Invariant => Check, - Type_Invariant'Class => Check, - Default_Initial_Condition => Check, --- GNAT specific assertion pragmas - Assert_And_Cut => Check, - Assume => Check, - Contract_Cases => Check, - Debug => Check, - Ghost => Check, - Initial_Condition => Check, - Loop_Invariant => Check, - Loop_Variant => Check, - Postcondition => Check, - Precondition => Check, - Predicate => Check, - Refined_Post => Check, - Subprogram_Variant => Check); -@end example - -The pragmas @code{Assert} and @code{Debug} normally have no effect and -are ignored. This switch, where @code{a} stands for ‘assert’, causes -pragmas @code{Assert} and @code{Debug} to be activated. This switch also -causes preconditions, postconditions, subtype predicates, and -type invariants to be activated. - -The pragmas have the form: - -@example -pragma Assert ( [, ]) -pragma Debug () -pragma Type_Invariant (, ) -pragma Predicate (, ) -pragma Precondition (, ) -pragma Postcondition (, ) -@end example - -The aspects have the form: - -@example -with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate] - => ; -@end example - -The @code{Assert} pragma causes @code{Boolean-expression} to be tested. -If the result is @code{True}, the pragma has no effect (other than -possible side effects from evaluating the expression). If the result is -@code{False}, the exception @code{Assert_Failure} declared in the package -@code{System.Assertions} is raised (passing @code{static-string-expression}, if -present, as the message associated with the exception). If no string -expression is given, the default is a string containing the file name and -line number of the pragma. - -The @code{Debug} pragma causes @code{procedure} to be called. Note that -@code{pragma Debug} may appear within a declaration sequence, allowing -debugging procedures to be called between declarations. - -For the aspect specification, the @code{Boolean-expression} is evaluated. -If the result is @code{True}, the aspect has no effect. If the result -is @code{False}, the exception @code{Assert_Failure} is raised. -@end table - -@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{f3}@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{e7} -@subsection Validity Checking - - -@geindex Validity Checking - -The Ada Reference Manual defines the concept of invalid values (see -RM 13.9.1). The primary source of invalid values is uninitialized -variables. A scalar variable that is left uninitialized may contain -an invalid value; the concept of invalid does not apply to access or -composite types. - -It is an error to read an invalid value, but the RM does not require -run-time checks to detect such errors, except for some minimal -checking to prevent erroneous execution (i.e. unpredictable -behavior). This corresponds to the @code{-gnatVd} switch below, -which is the default. For example, by default, if the expression of a -case statement is invalid, it will raise Constraint_Error rather than -causing a wild jump, and if an array index on the left-hand side of an -assignment is invalid, it will raise Constraint_Error rather than -overwriting an arbitrary memory location. - -The @code{-gnatVa} may be used to enable additional validity checks, -which are not required by the RM. These checks are often very -expensive (which is why the RM does not require them). These checks -are useful in tracking down uninitialized variables, but they are -not usually recommended for production builds, and in particular -we do not recommend using these extra validity checking options in -combination with optimization, since this can confuse the optimizer. -If performance is a consideration, leading to the need to optimize, -then the validity checking options should not be used. - -The other @code{-gnatV`x'} switches below allow finer-grained -control; you can enable whichever validity checks you desire. However, -for most debugging purposes, @code{-gnatVa} is sufficient, and the -default @code{-gnatVd} (i.e. standard Ada behavior) is usually -sufficient for non-debugging use. - -The @code{-gnatB} switch tells the compiler to assume that all -values are valid (that is, within their declared subtype range) -except in the context of a use of the Valid attribute. This means -the compiler can generate more efficient code, since the range -of values is better known at compile time. However, an uninitialized -variable can cause wild jumps and memory corruption in this mode. - -The @code{-gnatV`x'} switch allows control over the validity -checking mode as described below. -The @code{x} argument is a string of letters that -indicate validity checks that are performed or not performed in addition -to the default checks required by Ada as described above. - -@geindex -gnatVa (gcc) - - -@table @asis - -@item @code{-gnatVa} - -`All validity checks.' - -All validity checks are turned on. -That is, @code{-gnatVa} is -equivalent to @code{gnatVcdefimoprst}. -@end table - -@geindex -gnatVc (gcc) - - -@table @asis - -@item @code{-gnatVc} - -`Validity checks for copies.' - -The right-hand side of assignments, and the (explicit) initializing values -of object declarations are validity checked. -@end table - -@geindex -gnatVd (gcc) - - -@table @asis - -@item @code{-gnatVd} - -`Default (RM) validity checks.' - -Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these -(and only these) validity checks are enabled by default. -For case statements (and case expressions) that lack a “when others =>” -choice, a check is made that the value of the selector expression -belongs to its nominal subtype. If it does not, Constraint_Error is raised. -For assignments to array components (and for indexed components in some -other contexts), a check is made that each index expression belongs to the -corresponding index subtype. If it does not, Constraint_Error is raised. -Both these validity checks may be turned off using switch @code{-gnatVD}. -They are turned on by default. If @code{-gnatVD} is specified, a subsequent -switch @code{-gnatVd} will leave the checks turned on. -Switch @code{-gnatVD} should be used only if you are sure that all such -expressions have valid values. If you use this switch and invalid values -are present, then the program is erroneous, and wild jumps or memory -overwriting may occur. -@end table - -@geindex -gnatVe (gcc) - - -@table @asis - -@item @code{-gnatVe} - -`Validity checks for scalar components.' - -In the absence of this switch, assignments to scalar components of -enclosing record or array objects are not validity checked, even if -validity checks for assignments generally (@code{-gnatVc}) are turned on. -Specifying this switch enables such checks. -This switch has no effect if the @code{-gnatVc} switch is not specified. -@end table - -@geindex -gnatVf (gcc) - - -@table @asis - -@item @code{-gnatVf} - -`Validity checks for floating-point values.' - -Specifying this switch enables validity checking for floating-point -values in the same contexts where validity checking is enabled for -other scalar values. -In the absence of this switch, validity checking is not performed for -floating-point values. This takes precedence over other statements about -performing validity checking for scalar objects in various scenarios. -One way to look at it is that if this switch is not set, then whenever -any of the other rules in this section use the word “scalar” they -really mean “scalar and not floating-point”. -If @code{-gnatVf} is specified, then validity checking also applies -for floating-point values, and NaNs and infinities are considered invalid, -as well as out-of-range values for constrained types. The exact contexts -in which floating-point values are checked depends on the setting of other -options. For example, @code{-gnatVif} or @code{-gnatVfi} -(the order does not matter) specifies that floating-point parameters of mode -@code{in} should be validity checked. -@end table - -@geindex -gnatVi (gcc) - - -@table @asis - -@item @code{-gnatVi} - -`Validity checks for `@w{`}in`@w{`} mode parameters.' - -Arguments for parameters of mode @code{in} are validity checked in function -and procedure calls at the point of call. -@end table - -@geindex -gnatVm (gcc) - - -@table @asis - -@item @code{-gnatVm} - -`Validity checks for `@w{`}in out`@w{`} mode parameters.' - -Arguments for parameters of mode @code{in out} are validity checked in -procedure calls at the point of call. The @code{'m'} here stands for -modify, since this concerns parameters that can be modified by the call. -Note that there is no specific option to test @code{out} parameters, -but any reference within the subprogram will be tested in the usual -manner, and if an invalid value is copied back, any reference to it -will be subject to validity checking. -@end table - -@geindex -gnatVn (gcc) - - -@table @asis - -@item @code{-gnatVn} - -`No validity checks.' - -This switch turns off all validity checking, including the default checking -for case statements and left hand side subscripts. Note that the use of -the switch @code{-gnatp} suppresses all run-time checks, including -validity checks, and thus implies @code{-gnatVn}. When this switch -is used, it cancels any other @code{-gnatV} previously issued. -@end table - -@geindex -gnatVo (gcc) - - -@table @asis - -@item @code{-gnatVo} - -`Validity checks for operator and attribute operands.' - -Scalar arguments for predefined operators and for attributes are -validity checked. -This includes all operators in package @code{Standard}, -the shift operators defined as intrinsic in package @code{Interfaces} -and operands for attributes such as @code{Pos}. Checks are also made -on individual component values for composite comparisons, and on the -expressions in type conversions and qualified expressions. Checks are -also made on explicit ranges using @code{..} (e.g., slices, loops etc). -@end table - -@geindex -gnatVp (gcc) - - -@table @asis - -@item @code{-gnatVp} - -`Validity checks for parameters.' - -This controls the treatment of formal parameters within a subprogram (as -opposed to @code{-gnatVi} and @code{-gnatVm}, which control validity -testing of actual parameters of a call). If either of these call options is -specified, then normally an assumption is made within a subprogram that -the validity of any incoming formal parameters of the corresponding mode(s) -has already been checked at the point of call and does not need rechecking. -If @code{-gnatVp} is set, then this assumption is not made and so their -validity may be checked (or rechecked) within the subprogram. If neither of -the two call-related options is specified, then this switch has no effect. -@end table - -@geindex -gnatVr (gcc) - - -@table @asis - -@item @code{-gnatVr} - -`Validity checks for function returns.' - -The expression in simple @code{return} statements in functions is validity -checked. -@end table - -@geindex -gnatVs (gcc) - - -@table @asis - -@item @code{-gnatVs} - -`Validity checks for subscripts.' - -All subscript expressions are checked for validity, whatever context -they occur in (in default mode some subscripts are not validity checked; -for example, validity checking may be omitted in some cases involving -a read of a component of an array). -@end table - -@geindex -gnatVt (gcc) - - -@table @asis - -@item @code{-gnatVt} - -`Validity checks for tests.' - -Expressions used as conditions in @code{if}, @code{while} or @code{exit} -statements are checked, as well as guard expressions in entry calls. -@end table - -The @code{-gnatV} switch may be followed by a string of letters -to turn on a series of validity checking options. -For example, @code{-gnatVcr} -specifies that in addition to the default validity checking, copies and -function return expressions are to be validity checked. -In order to make it easier to specify the desired combination of effects, -the upper case letters @code{CDFIMORST} may -be used to turn off the corresponding lower case option. -Thus @code{-gnatVaM} turns on all validity checking options except for -checking of @code{in out} parameters. - -The specification of additional validity checking generates extra code (and -in the case of @code{-gnatVa} the code expansion can be substantial). -However, these additional checks can be very useful in detecting -uninitialized variables, incorrect use of unchecked conversion, and other -errors leading to invalid values. The use of pragma @code{Initialize_Scalars} -is useful in conjunction with the extra validity checking, since this -ensures that wherever possible uninitialized variables have invalid values. - -See also the pragma @code{Validity_Checks} which allows modification of -the validity checking mode at the program source level, and also allows for -temporary disabling of validity checks. - -@node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{ec} -@subsection Style Checking - - -@geindex Style checking - -@geindex -gnaty (gcc) - -The @code{-gnatyx} switch causes the compiler to -enforce specified style rules. A limited set of style rules has been used -in writing the GNAT sources themselves. This switch allows user programs -to activate all or some of these checks. If the source program fails a -specified style check, an appropriate message is given, preceded by -the character sequence ‘(style)’. This message does not prevent -successful compilation (unless the @code{-gnatwe} switch is used). - -Note that this is by no means intended to be a general facility for -checking arbitrary coding standards. It is simply an embedding of the -style rules we have chosen for the GNAT sources. If you are starting -a project which does not have established style standards, you may -find it useful to adopt the entire set of GNAT coding standards, or -some subset of them. - - -The string @code{x} is a sequence of letters or digits -indicating the particular style -checks to be performed. The following checks are defined: - -@geindex -gnaty[0-9] (gcc) - - -@table @asis - -@item @code{-gnaty0} - -`Specify indentation level.' - -If a digit from 1-9 appears -in the string after @code{-gnaty} -then proper indentation is checked, with the digit indicating the -indentation level required. A value of zero turns off this style check. -The rule checks that the following constructs start on a column that is -a multiple of the alignment level: - - -@itemize * - -@item -beginnings of declarations (except record component declarations) -and statements; - -@item -beginnings of the structural components of compound statements; - -@item -@code{end} keyword that completes the declaration of a program unit declaration -or body or that completes a compound statement. -@end itemize - -Full line comments must be -aligned with the @code{--} starting on a column that is a multiple of -the alignment level, or they may be aligned the same way as the following -non-blank line (this is useful when full line comments appear in the middle -of a statement, or they may be aligned with the source line on the previous -non-blank line. -@end table - -@geindex -gnatya (gcc) - - -@table @asis - -@item @code{-gnatya} - -`Check attribute casing.' - -Attribute names, including the case of keywords such as @code{digits} -used as attributes names, must be written in mixed case, that is, the -initial letter and any letter following an underscore must be uppercase. -All other letters must be lowercase. -@end table - -@geindex -gnatyA (gcc) - - -@table @asis - -@item @code{-gnatyA} - -`Use of array index numbers in array attributes.' - -When using the array attributes First, Last, Range, -or Length, the index number must be omitted for one-dimensional arrays -and is required for multi-dimensional arrays. -@end table - -@geindex -gnatyb (gcc) - - -@table @asis - -@item @code{-gnatyb} - -`Blanks not allowed at statement end.' - -Trailing blanks are not allowed at the end of statements. The purpose of this -rule, together with h (no horizontal tabs), is to enforce a canonical format -for the use of blanks to separate source tokens. -@end table - -@geindex -gnatyB (gcc) - - -@table @asis - -@item @code{-gnatyB} - -`Check Boolean operators.' - -The use of AND/OR operators is not permitted except in the cases of modular -operands, array operands, and simple stand-alone boolean variables or -boolean constants. In all other cases @code{and then}/@cite{or else} are -required. -@end table - -@geindex -gnatyc (gcc) - - -@table @asis - -@item @code{-gnatyc} - -`Check comments, double space.' - -Comments must meet the following set of rules: - - -@itemize * - -@item -The @code{--} that starts the column must either start in column one, -or else at least one blank must precede this sequence. - -@item -Comments that follow other tokens on a line must have at least one blank -following the @code{--} at the start of the comment. - -@item -Full line comments must have at least two blanks following the -@code{--} that starts the comment, with the following exceptions. - -@item -A line consisting only of the @code{--} characters, possibly preceded -by blanks is permitted. - -@item -A comment starting with @code{--x} where @code{x} is a special character -is permitted. -This allows proper processing of the output from specialized tools -such as @code{gnatprep} (where @code{--!} is used) and in earlier versions of the SPARK -annotation -language (where @code{--#} is used). For the purposes of this rule, a -special character is defined as being in one of the ASCII ranges -@code{16#21#...16#2F#} or @code{16#3A#...16#3F#}. -Note that this usage is not permitted -in GNAT implementation units (i.e., when @code{-gnatg} is used). - -@item -A line consisting entirely of minus signs, possibly preceded by blanks, is -permitted. This allows the construction of box comments where lines of minus -signs are used to form the top and bottom of the box. - -@item -A comment that starts and ends with @code{--} is permitted as long as at -least one blank follows the initial @code{--}. Together with the preceding -rule, this allows the construction of box comments, as shown in the following -example: - -@example ---------------------------- --- This is a box comment -- --- with two text lines. -- ---------------------------- -@end example -@end itemize -@end table - -@geindex -gnatyC (gcc) - - -@table @asis - -@item @code{-gnatyC} - -`Check comments, single space.' - -This is identical to @code{c} except that only one space -is required following the @code{--} of a comment instead of two. -@end table - -@geindex -gnatyd (gcc) - - -@table @asis - -@item @code{-gnatyd} - -`Check no DOS line terminators present.' - -All lines must be terminated by a single ASCII.LF -character (in particular the DOS line terminator sequence CR/LF is not -allowed). -@end table - -@geindex -gnatyD (gcc) - - -@table @asis - -@item @code{-gnatyD} - -`Check declared identifiers in mixed case.' - -Declared identifiers must be in mixed case, as in -This_Is_An_Identifier. Use -gnatyr in addition to ensure -that references match declarations. -@end table - -@geindex -gnatye (gcc) - - -@table @asis - -@item @code{-gnatye} - -`Check end/exit labels.' - -Optional labels on @code{end} statements ending subprograms and on -@code{exit} statements exiting named loops, are required to be present. -@end table - -@geindex -gnatyf (gcc) - - -@table @asis - -@item @code{-gnatyf} - -`No form feeds or vertical tabs.' - -Neither form feeds nor vertical tab characters are permitted -in the source text. -@end table - -@geindex -gnatyg (gcc) - - -@table @asis - -@item @code{-gnatyg} - -`GNAT style mode.' - -The set of style check switches is set to match that used by the GNAT sources. -This may be useful when developing code that is eventually intended to be -incorporated into GNAT. Currently this is equivalent to @code{-gnatyydISux}) -but additional style switches may be added to this set in the future without -advance notice. -@end table - -@geindex -gnatyh (gcc) - - -@table @asis - -@item @code{-gnatyh} - -`No horizontal tabs.' - -Horizontal tab characters are not permitted in the source text. -Together with the b (no blanks at end of line) check, this -enforces a canonical form for the use of blanks to separate -source tokens. -@end table - -@geindex -gnatyi (gcc) - - -@table @asis - -@item @code{-gnatyi} - -`Check if-then layout.' - -The keyword @code{then} must appear either on the same -line as corresponding @code{if}, or on a line on its own, lined -up under the @code{if}. -@end table - -@geindex -gnatyI (gcc) - - -@table @asis - -@item @code{-gnatyI} - -`check mode IN keywords.' - -Mode @code{in} (the default mode) is not -allowed to be given explicitly. @code{in out} is fine, -but not @code{in} on its own. -@end table - -@geindex -gnatyk (gcc) - - -@table @asis - -@item @code{-gnatyk} - -`Check keyword casing.' - -All keywords must be in lower case (with the exception of keywords -such as @code{digits} used as attribute names to which this check -does not apply). A single error is reported for each line breaking -this rule even if multiple casing issues exist on a same line. -@end table - -@geindex -gnatyl (gcc) - - -@table @asis - -@item @code{-gnatyl} - -`Check layout.' - -Layout of statement and declaration constructs must follow the -recommendations in the Ada Reference Manual, as indicated by the -form of the syntax rules. For example an @code{else} keyword must -be lined up with the corresponding @code{if} keyword. - -There are two respects in which the style rule enforced by this check -option are more liberal than those in the Ada Reference Manual. First -in the case of record declarations, it is permissible to put the -@code{record} keyword on the same line as the @code{type} keyword, and -then the @code{end} in @code{end record} must line up under @code{type}. -This is also permitted when the type declaration is split on two lines. -For example, any of the following three layouts is acceptable: - -@example -type q is record - a : integer; - b : integer; -end record; - -type q is - record - a : integer; - b : integer; - end record; - -type q is - record - a : integer; - b : integer; -end record; -@end example - -Second, in the case of a block statement, a permitted alternative -is to put the block label on the same line as the @code{declare} or -@code{begin} keyword, and then line the @code{end} keyword up under -the block label. For example both the following are permitted: - -@example -Block : declare - A : Integer := 3; -begin - Proc (A, A); -end Block; - -Block : - declare - A : Integer := 3; - begin - Proc (A, A); - end Block; -@end example - -The same alternative format is allowed for loops. For example, both of -the following are permitted: - -@example -Clear : while J < 10 loop - A (J) := 0; -end loop Clear; - -Clear : - while J < 10 loop - A (J) := 0; - end loop Clear; -@end example -@end table - -@geindex -gnatyLnnn (gcc) - - -@table @asis - -@item @code{-gnatyL} - -`Set maximum nesting level.' - -The maximum level of nesting of constructs (including subprograms, loops, -blocks, packages, and conditionals) may not exceed the given value -`nnn'. A value of zero disconnects this style check. -@end table - -@geindex -gnatym (gcc) - - -@table @asis - -@item @code{-gnatym} - -`Check maximum line length.' - -The length of source lines must not exceed 79 characters, including -any trailing blanks. The value of 79 allows convenient display on an -80 character wide device or window, allowing for possible special -treatment of 80 character lines. Note that this count is of -characters in the source text. This means that a tab character counts -as one character in this count and a wide character sequence counts as -a single character (however many bytes are needed in the encoding). -@end table - -@geindex -gnatyMnnn (gcc) - - -@table @asis - -@item @code{-gnatyM} - -`Set maximum line length.' - -The length of lines must not exceed the -given value `nnn'. The maximum value that can be specified is 32767. -If neither style option for setting the line length is used, then the -default is 255. This also controls the maximum length of lexical elements, -where the only restriction is that they must fit on a single line. -@end table - -@geindex -gnatyn (gcc) - - -@table @asis - -@item @code{-gnatyn} - -`Check casing of entities in Standard.' - -Any identifier from Standard must be cased -to match the presentation in the Ada Reference Manual (for example, -@code{Integer} and @code{ASCII.NUL}). -@end table - -@geindex -gnatyN (gcc) - - -@table @asis - -@item @code{-gnatyN} - -`Turn off all style checks.' - -All style check options are turned off. -@end table - -@geindex -gnatyo (gcc) - - -@table @asis - -@item @code{-gnatyo} - -`Check order of subprogram bodies.' - -All subprogram bodies in a given scope -(e.g., a package body) must be in alphabetical order. The ordering -rule uses normal Ada rules for comparing strings, ignoring casing -of letters, except that if there is a trailing numeric suffix, then -the value of this suffix is used in the ordering (e.g., Junk2 comes -before Junk10). -@end table - -@geindex -gnatyO (gcc) - - -@table @asis - -@item @code{-gnatyO} - -`Check that overriding subprograms are explicitly marked as such.' - -This applies to all subprograms of a derived type that override a primitive -operation of the type, for both tagged and untagged types. In particular, -the declaration of a primitive operation of a type extension that overrides -an inherited operation must carry an overriding indicator. Another case is -the declaration of a function that overrides a predefined operator (such -as an equality operator). -@end table - -@geindex -gnatyp (gcc) - - -@table @asis - -@item @code{-gnatyp} - -`Check pragma casing.' - -Pragma names must be written in mixed case, that is, the -initial letter and any letter following an underscore must be uppercase. -All other letters must be lowercase. An exception is that SPARK_Mode is -allowed as an alternative for Spark_Mode. -@end table - -@geindex -gnatyr (gcc) - - -@table @asis - -@item @code{-gnatyr} - -`Check references.' - -All identifier references must be cased in the same way as the -corresponding declaration. No specific casing style is imposed on -identifiers. The only requirement is for consistency of references -with declarations. -@end table - -@geindex -gnatys (gcc) - - -@table @asis - -@item @code{-gnatys} - -`Check separate specs.' - -Separate declarations (‘specs’) are required for subprograms (a -body is not allowed to serve as its own declaration). The only -exception is that parameterless library level procedures are -not required to have a separate declaration. This exception covers -the most frequent form of main program procedures. -@end table - -@geindex -gnatyS (gcc) - - -@table @asis - -@item @code{-gnatyS} - -`Check no statements after then/else.' - -No statements are allowed -on the same line as a @code{then} or @code{else} keyword following the -keyword in an @code{if} statement. @code{or else} and @code{and then} are not -affected, and a special exception allows a pragma to appear after @code{else}. -@end table - -@geindex -gnatyt (gcc) - - -@table @asis - -@item @code{-gnatyt} - -`Check token spacing.' - -The following token spacing rules are enforced: - - -@itemize * - -@item -The keywords @code{abs} and @code{not} must be followed by a space. - -@item -The token @code{=>} must be surrounded by spaces. - -@item -The token @code{<>} must be preceded by a space or a left parenthesis. - -@item -Binary operators other than @code{**} must be surrounded by spaces. -There is no restriction on the layout of the @code{**} binary operator. - -@item -Colon must be surrounded by spaces. - -@item -Colon-equal (assignment, initialization) must be surrounded by spaces. - -@item -Comma must be the first non-blank character on the line, or be -immediately preceded by a non-blank character, and must be followed -by a space. - -@item -If the token preceding a left parenthesis ends with a letter or digit, then -a space must separate the two tokens. - -@item -If the token following a right parenthesis starts with a letter or digit, then -a space must separate the two tokens. - -@item -A right parenthesis must either be the first non-blank character on -a line, or it must be preceded by a non-blank character. - -@item -A semicolon must not be preceded by a space, and must not be followed by -a non-blank character. - -@item -A unary plus or minus may not be followed by a space. - -@item -A vertical bar must be surrounded by spaces. -@end itemize - -Exactly one blank (and no other white space) must appear between -a @code{not} token and a following @code{in} token. -@end table - -@geindex -gnatyu (gcc) - - -@table @asis - -@item @code{-gnatyu} - -`Check unnecessary blank lines.' - -Unnecessary blank lines are not allowed. A blank line is considered -unnecessary if it appears at the end of the file, or if more than -one blank line occurs in sequence. -@end table - -@geindex -gnatyx (gcc) - - -@table @asis - -@item @code{-gnatyx} - -`Check extra parentheses.' - -Unnecessary extra level of parentheses (C-style) are not allowed -around conditions in @code{if} statements, @code{while} statements and -@code{exit} statements. -@end table - -@geindex -gnatyy (gcc) - - -@table @asis - -@item @code{-gnatyy} - -`Set all standard style check options.' - -This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking -options enabled with the exception of @code{-gnatyB}, @code{-gnatyd}, -@code{-gnatyI}, @code{-gnatyLnnn}, @code{-gnatyo}, @code{-gnatyO}, -@code{-gnatyS}, @code{-gnatyu}, and @code{-gnatyx}. -@end table - -@geindex -gnaty- (gcc) - - -@table @asis - -@item @code{-gnaty-} - -`Remove style check options.' - -This causes any subsequent options in the string to act as canceling the -corresponding style check option. To cancel maximum nesting level control, -use the @code{L} parameter without any integer value after that, because any -digit following `-' in the parameter string of the @code{-gnaty} -option will be treated as canceling the indentation check. The same is true -for the @code{M} parameter. @code{y} and @code{N} parameters are not -allowed after `-'. -@end table - -@geindex -gnaty+ (gcc) - - -@table @asis - -@item @code{-gnaty+} - -`Enable style check options.' - -This causes any subsequent options in the string to enable the corresponding -style check option. That is, it cancels the effect of a previous -, -if any. -@end table - -@c end of switch description (leave this comment to ease automatic parsing for - -@c GNAT Studio) - -In the above rules, appearing in column one is always permitted, that is, -counts as meeting either a requirement for a required preceding space, -or as meeting a requirement for no preceding space. - -Appearing at the end of a line is also always permitted, that is, counts -as meeting either a requirement for a following space, or as meeting -a requirement for no following space. - -If any of these style rules is violated, a message is generated giving -details on the violation. The initial characters of such messages are -always ‘@cite{(style)}’. Note that these messages are treated as warning -messages, so they normally do not prevent the generation of an object -file. The @code{-gnatwe} switch can be used to treat warning messages, -including style messages, as fatal errors. - -The switch @code{-gnaty} on its own (that is not -followed by any letters or digits) is equivalent -to the use of @code{-gnatyy} as described above, that is all -built-in standard style check options are enabled. - -The switch @code{-gnatyN} clears any previously set style checks. - -@node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{f5}@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{ea} -@subsection Run-Time Checks - - -@geindex Division by zero - -@geindex Access before elaboration - -@geindex Checks -@geindex division by zero - -@geindex Checks -@geindex access before elaboration - -@geindex Checks -@geindex stack overflow checking - -By default, the following checks are suppressed: stack overflow -checks, and checks for access before elaboration on subprogram -calls. All other checks, including overflow checks, range checks and -array bounds checks, are turned on by default. The following @code{gcc} -switches refine this default behavior. - -@geindex -gnatp (gcc) - - -@table @asis - -@item @code{-gnatp} - -@geindex Suppressing checks - -@geindex Checks -@geindex suppressing - -This switch causes the unit to be compiled -as though @code{pragma Suppress (All_checks)} -had been present in the source. Validity checks are also eliminated (in -other words @code{-gnatp} also implies @code{-gnatVn}. -Use this switch to improve the performance -of the code at the expense of safety in the presence of invalid data or -program bugs. - -Note that when checks are suppressed, the compiler is allowed, but not -required, to omit the checking code. If the run-time cost of the -checking code is zero or near-zero, the compiler will generate it even -if checks are suppressed. In particular, if the compiler can prove -that a certain check will necessarily fail, it will generate code to -do an unconditional ‘raise’, even if checks are suppressed. The -compiler warns in this case. Another case in which checks may not be -eliminated is when they are embedded in certain run-time routines such -as math library routines. - -Of course, run-time checks are omitted whenever the compiler can prove -that they will not fail, whether or not checks are suppressed. - -Note that if you suppress a check that would have failed, program -execution is erroneous, which means the behavior is totally -unpredictable. The program might crash, or print wrong answers, or -do anything else. It might even do exactly what you wanted it to do -(and then it might start failing mysteriously next week or next -year). The compiler will generate code based on the assumption that -the condition being checked is true, which can result in erroneous -execution if that assumption is wrong. - -The checks subject to suppression include all the checks defined by the Ada -standard, the additional implementation defined checks @code{Alignment_Check}, -@code{Duplicated_Tag_Check}, @code{Predicate_Check}, @code{Container_Checks}, @code{Tampering_Check}, -and @code{Validity_Check}, as well as any checks introduced using @code{pragma Check_Name}. -Note that @code{Atomic_Synchronization} is not automatically suppressed by use of this option. - -If the code depends on certain checks being active, you can use -pragma @code{Unsuppress} either as a configuration pragma or as -a local pragma to make sure that a specified check is performed -even if @code{gnatp} is specified. - -The @code{-gnatp} switch has no effect if a subsequent -@code{-gnat-p} switch appears. -@end table - -@geindex -gnat-p (gcc) - -@geindex Suppressing checks - -@geindex Checks -@geindex suppressing - -@geindex Suppress - - -@table @asis - -@item @code{-gnat-p} - -This switch cancels the effect of a previous @code{gnatp} switch. -@end table - -@geindex -gnato?? (gcc) - -@geindex Overflow checks - -@geindex Overflow mode - -@geindex Check -@geindex overflow - - -@table @asis - -@item @code{-gnato??} - -This switch controls the mode used for computing intermediate -arithmetic integer operations, and also enables overflow checking. -For a full description of overflow mode and checking control, see -the ‘Overflow Check Handling in GNAT’ appendix in this -User’s Guide. - -Overflow checks are always enabled by this switch. The argument -controls the mode, using the codes - - -@table @asis - -@item `1 = STRICT' - -In STRICT mode, intermediate operations are always done using the -base type, and overflow checking ensures that the result is within -the base type range. - -@item `2 = MINIMIZED' - -In MINIMIZED mode, overflows in intermediate operations are avoided -where possible by using a larger integer type for the computation -(typically @code{Long_Long_Integer}). Overflow checking ensures that -the result fits in this larger integer type. - -@item `3 = ELIMINATED' - -In ELIMINATED mode, overflows in intermediate operations are avoided -by using multi-precision arithmetic. In this case, overflow checking -has no effect on intermediate operations (since overflow is impossible). -@end table - -If two digits are present after @code{-gnato} then the first digit -sets the mode for expressions outside assertions, and the second digit -sets the mode for expressions within assertions. Here assertions is used -in the technical sense (which includes for example precondition and -postcondition expressions). - -If one digit is present, the corresponding mode is applicable to both -expressions within and outside assertion expressions. - -If no digits are present, the default is to enable overflow checks -and set STRICT mode for both kinds of expressions. This is compatible -with the use of @code{-gnato} in previous versions of GNAT. - -@geindex Machine_Overflows - -Note that the @code{-gnato??} switch does not affect the code generated -for any floating-point operations; it applies only to integer semantics. -For floating-point, GNAT has the @code{Machine_Overflows} -attribute set to @code{False} and the normal mode of operation is to -generate IEEE NaN and infinite values on overflow or invalid operations -(such as dividing 0.0 by 0.0). - -The reason that we distinguish overflow checking from other kinds of -range constraint checking is that a failure of an overflow check, unlike -for example the failure of a range check, can result in an incorrect -value, but cannot cause random memory destruction (like an out of range -subscript), or a wild jump (from an out of range case value). Overflow -checking is also quite expensive in time and space, since in general it -requires the use of double length arithmetic. - -Note again that the default is @code{-gnato11} (equivalent to @code{-gnato1}), -so overflow checking is performed in STRICT mode by default. -@end table - -@geindex -gnatE (gcc) - -@geindex Elaboration checks - -@geindex Check -@geindex elaboration - - -@table @asis - -@item @code{-gnatE} - -Enables dynamic checks for access-before-elaboration -on subprogram calls and generic instantiations. -Note that @code{-gnatE} is not necessary for safety, because in the -default mode, GNAT ensures statically that the checks would not fail. -For full details of the effect and use of this switch, -@ref{c7,,Compiling with gcc}. -@end table - -@geindex -fstack-check (gcc) - -@geindex Stack Overflow Checking - -@geindex Checks -@geindex stack overflow checking - - -@table @asis - -@item @code{-fstack-check} - -Activates stack overflow checking. For full details of the effect and use of -this switch see @ref{e5,,Stack Overflow Checking}. -@end table - -@geindex Unsuppress - -The setting of these switches only controls the default setting of the -checks. You may modify them using either @code{Suppress} (to remove -checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in -the program source. - -@node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{f7} -@subsection Using @code{gcc} for Syntax Checking - - -@geindex -gnats (gcc) - - -@table @asis - -@item @code{-gnats} - -The @code{s} stands for ‘syntax’. - -Run GNAT in syntax checking only mode. For -example, the command - -@example -$ gcc -c -gnats x.adb -@end example - -compiles file @code{x.adb} in syntax-check-only mode. You can check a -series of files in a single command -, and can use wildcards to specify such a group of files. -Note that you must specify the @code{-c} (compile -only) flag in addition to the @code{-gnats} flag. - -You may use other switches in conjunction with @code{-gnats}. In -particular, @code{-gnatl} and @code{-gnatv} are useful to control the -format of any generated error messages. - -When the source file is empty or contains only empty lines and/or comments, -the output is a warning: - -@example -$ gcc -c -gnats -x ada toto.txt -toto.txt:1:01: warning: empty file, contains no compilation units -$ -@end example - -Otherwise, the output is simply the error messages, if any. No object file or -ALI file is generated by a syntax-only compilation. Also, no units other -than the one specified are accessed. For example, if a unit @code{X} -`with's a unit @code{Y}, compiling unit @code{X} in syntax -check only mode does not access the source file containing unit -@code{Y}. - -@geindex Multiple units -@geindex syntax checking - -Normally, GNAT allows only a single unit in a source file. However, this -restriction does not apply in syntax-check-only mode, and it is possible -to check a file containing multiple compilation units concatenated -together. This is primarily used by the @code{gnatchop} utility -(@ref{1d,,Renaming Files with gnatchop}). -@end table - -@node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{f9} -@subsection Using @code{gcc} for Semantic Checking - - -@geindex -gnatc (gcc) - - -@table @asis - -@item @code{-gnatc} - -The @code{c} stands for ‘check’. -Causes the compiler to operate in semantic check mode, -with full checking for all illegalities specified in the -Ada Reference Manual, but without generation of any object code -(no object file is generated). - -Because dependent files must be accessed, you must follow the GNAT -semantic restrictions on file structuring to operate in this mode: - - -@itemize * - -@item -The needed source files must be accessible -(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). - -@item -Each file must contain only one compilation unit. - -@item -The file name and unit name must match (@ref{3b,,File Naming Rules}). -@end itemize - -The output consists of error messages as appropriate. No object file is -generated. An @code{ALI} file is generated for use in the context of -cross-reference tools, but this file is marked as not being suitable -for binding (since no object file is generated). -The checking corresponds exactly to the notion of -legality in the Ada Reference Manual. - -Any unit can be compiled in semantics-checking-only mode, including -units that would not normally be compiled (subunits, -and specifications where a separate body is present). -@end table - -@node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{fa} -@subsection Compiling Different Versions of Ada - - -The switches described in this section allow you to explicitly specify -the version of the Ada language that your programs are written in. -The default mode is Ada 2012, -but you can also specify Ada 95, Ada 2005 mode, or -indicate Ada 83 compatibility mode. - -@geindex Compatibility with Ada 83 - -@geindex -gnat83 (gcc) - -@geindex ACVC -@geindex Ada 83 tests - -@geindex Ada 83 mode - - -@table @asis - -@item @code{-gnat83} (Ada 83 Compatibility Mode) - -Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch -specifies that the program is to be compiled in Ada 83 mode. With -@code{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83 -semantics where this can be done easily. -It is not possible to guarantee this switch does a perfect -job; some subtle tests, such as are -found in earlier ACVC tests (and that have been removed from the ACATS suite -for Ada 95), might not compile correctly. -Nevertheless, this switch may be useful in some circumstances, for example -where, due to contractual reasons, existing code needs to be maintained -using only Ada 83 features. - -With few exceptions (most notably the need to use @code{<>} on -unconstrained -@geindex Generic formal parameters -generic formal parameters, -the use of the new Ada 95 / Ada 2005 -reserved words, and the use of packages -with optional bodies), it is not necessary to specify the -@code{-gnat83} switch when compiling Ada 83 programs, because, with rare -exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus -a correct Ada 83 program is usually also a correct program -in these later versions of the language standard. For further information -please refer to the `Compatibility and Porting Guide' chapter in the -@cite{GNAT Reference Manual}. -@end table - -@geindex -gnat95 (gcc) - -@geindex Ada 95 mode - - -@table @asis - -@item @code{-gnat95} (Ada 95 mode) - -This switch directs the compiler to implement the Ada 95 version of the -language. -Since Ada 95 is almost completely upwards -compatible with Ada 83, Ada 83 programs may generally be compiled using -this switch (see the description of the @code{-gnat83} switch for further -information about Ada 83 mode). -If an Ada 2005 program is compiled in Ada 95 mode, -uses of the new Ada 2005 features will cause error -messages or warnings. - -This switch also can be used to cancel the effect of a previous -@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012} -switch earlier in the command line. -@end table - -@geindex -gnat05 (gcc) - -@geindex -gnat2005 (gcc) - -@geindex Ada 2005 mode - - -@table @asis - -@item @code{-gnat05} or @code{-gnat2005} (Ada 2005 mode) - -This switch directs the compiler to implement the Ada 2005 version of the -language, as documented in the official Ada standards document. -Since Ada 2005 is almost completely upwards -compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs -may generally be compiled using this switch (see the description of the -@code{-gnat83} and @code{-gnat95} switches for further -information). -@end table - -@geindex -gnat12 (gcc) - -@geindex -gnat2012 (gcc) - -@geindex Ada 2012 mode - - -@table @asis - -@item @code{-gnat12} or @code{-gnat2012} (Ada 2012 mode) - -This switch directs the compiler to implement the Ada 2012 version of the -language (also the default). -Since Ada 2012 is almost completely upwards -compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), -Ada 83 and Ada 95 programs -may generally be compiled using this switch (see the description of the -@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches -for further information). -@end table - -@geindex -gnat2022 (gcc) - -@geindex Ada 2022 mode - - -@table @asis - -@item @code{-gnat2022} (Ada 2022 mode) - -This switch directs the compiler to implement the Ada 2022 version of the -language. -@end table - -@geindex -gnatX0 (gcc) - -@geindex Ada language extensions - -@geindex GNAT extensions - - -@table @asis - -@item @code{-gnatX0} (Enable GNAT Extensions) - -This switch directs the compiler to implement the latest version of the -language (currently Ada 2022) and also to enable certain GNAT implementation -extensions that are not part of any Ada standard. For a full list of these -extensions, see the GNAT reference manual, @code{Pragma Extensions_Allowed}. -@end table - -@geindex -gnatX (gcc) - -@geindex Ada language extensions - -@geindex GNAT extensions - - -@table @asis - -@item @code{-gnatX} (Enable core GNAT Extensions) - -This switch is similar to -gnatX0 except that only some, not all, of the -GNAT-defined language extensions are enabled. For a list of the -extensions enabled by this switch, see the GNAT reference manual -@code{Pragma Extensions_Allowed} and the description of that pragma’s -“On” (as opposed to “All”) argument. -@end table - -@node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{31}@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{fb} -@subsection Character Set Control - - -@geindex -gnati (gcc) - - -@table @asis - -@item @code{-gnati`c'} - -Normally GNAT recognizes the Latin-1 character set in source program -identifiers, as described in the Ada Reference Manual. -This switch causes -GNAT to recognize alternate character sets in identifiers. @code{c} is a -single character indicating the character set, as follows: - - -@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -`1' - -@tab - -ISO 8859-1 (Latin-1) identifiers - -@item - -`2' - -@tab - -ISO 8859-2 (Latin-2) letters allowed in identifiers - -@item - -`3' - -@tab - -ISO 8859-3 (Latin-3) letters allowed in identifiers - -@item - -`4' - -@tab - -ISO 8859-4 (Latin-4) letters allowed in identifiers - -@item - -`5' - -@tab - -ISO 8859-5 (Cyrillic) letters allowed in identifiers - -@item - -`9' - -@tab - -ISO 8859-15 (Latin-9) letters allowed in identifiers - -@item - -`p' - -@tab - -IBM PC letters (code page 437) allowed in identifiers - -@item - -`8' - -@tab - -IBM PC letters (code page 850) allowed in identifiers - -@item - -`f' - -@tab - -Full upper-half codes allowed in identifiers - -@item - -`n' - -@tab - -No upper-half codes allowed in identifiers - -@item - -`w' - -@tab - -Wide-character codes (that is, codes greater than 255) -allowed in identifiers - -@end multitable - - -See @ref{23,,Foreign Language Representation} for full details on the -implementation of these character sets. -@end table - -@geindex -gnatW (gcc) - - -@table @asis - -@item @code{-gnatW`e'} - -Specify the method of encoding for wide characters. -@code{e} is one of the following: - - -@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -`h' - -@tab - -Hex encoding (brackets coding also recognized) - -@item - -`u' - -@tab - -Upper half encoding (brackets encoding also recognized) - -@item - -`s' - -@tab - -Shift/JIS encoding (brackets encoding also recognized) - -@item - -`e' - -@tab - -EUC encoding (brackets encoding also recognized) - -@item - -`8' - -@tab - -UTF-8 encoding (brackets encoding also recognized) - -@item - -`b' - -@tab - -Brackets encoding only (default value) - -@end multitable - - -For full details on these encoding -methods see @ref{37,,Wide_Character Encodings}. -Note that brackets coding is always accepted, even if one of the other -options is specified, so for example @code{-gnatW8} specifies that both -brackets and UTF-8 encodings will be recognized. The units that are -with’ed directly or indirectly will be scanned using the specified -representation scheme, and so if one of the non-brackets scheme is -used, it must be used consistently throughout the program. However, -since brackets encoding is always recognized, it may be conveniently -used in standard libraries, allowing these libraries to be used with -any of the available coding schemes. - -Note that brackets encoding only applies to program text. Within comments, -brackets are considered to be normal graphic characters, and bracket sequences -are never recognized as wide characters. - -If no @code{-gnatW?} parameter is present, then the default -representation is normally Brackets encoding only. However, if the -first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard -byte order mark or BOM for UTF-8), then these three characters are -skipped and the default representation for the file is set to UTF-8. - -Note that the wide character representation that is specified (explicitly -or by default) for the main program also acts as the default encoding used -for Wide_Text_IO files if not specifically overridden by a WCEM form -parameter. -@end table - -When no @code{-gnatW?} is specified, then characters (other than wide -characters represented using brackets notation) are treated as 8-bit -Latin-1 codes. The codes recognized are the Latin-1 graphic characters, -and ASCII format effectors (CR, LF, HT, VT). Other lower half control -characters in the range 16#00#..16#1F# are not accepted in program text -or in comments. Upper half control characters (16#80#..16#9F#) are rejected -in program text, but allowed and ignored in comments. Note in particular -that the Next Line (NEL) character whose encoding is 16#85# is not recognized -as an end of line in this default mode. If your source program contains -instances of the NEL character used as a line terminator, -you must use UTF-8 encoding for the whole -source program. In default mode, all lines must be ended by a standard -end of line sequence (CR, CR/LF, or LF). - -Note that the convention of simply accepting all upper half characters in -comments means that programs that use standard ASCII for program text, but -UTF-8 encoding for comments are accepted in default mode, providing that the -comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. -This is a common mode for many programs with foreign language comments. - -@node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{fc}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{fd} -@subsection File Naming Control - - -@geindex -gnatk (gcc) - - -@table @asis - -@item @code{-gnatk`n'} - -Activates file name ‘krunching’. @code{n}, a decimal integer in the range -1-999, indicates the maximum allowable length of a file name (not -including the @code{.ads} or @code{.adb} extension). The default is not -to enable file name krunching. - -For the source file naming rules, @ref{3b,,File Naming Rules}. -@end table - -@node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{ff} -@subsection Subprogram Inlining Control - - -@geindex -gnatn (gcc) - - -@table @asis - -@item @code{-gnatn[12]} - -The @code{n} here is intended to suggest the first syllable of the word ‘inline’. -GNAT recognizes and processes @code{Inline} pragmas. However, for inlining to -actually occur, optimization must be enabled and, by default, inlining of -subprograms across units is not performed. If you want to additionally -enable inlining of subprograms specified by pragma @code{Inline} across units, -you must also specify this switch. - -In the absence of this switch, GNAT does not attempt inlining across units -and does not access the bodies of subprograms for which @code{pragma Inline} is -specified if they are not in the current unit. - -You can optionally specify the inlining level: 1 for moderate inlining across -units, which is a good compromise between compilation times and performances -at run time, or 2 for full inlining across units, which may bring about -longer compilation times. If no inlining level is specified, the compiler will -pick it based on the optimization level: 1 for @code{-O1}, @code{-O2} or -@code{-Os} and 2 for @code{-O3}. - -If you specify this switch the compiler will access these bodies, -creating an extra source dependency for the resulting object file, and -where possible, the call will be inlined. -For further details on when inlining is possible -see @ref{100,,Inlining of Subprograms}. -@end table - -@geindex -gnatN (gcc) - - -@table @asis - -@item @code{-gnatN} - -This switch activates front-end inlining which also -generates additional dependencies. - -When using a gcc-based back end, then the use of -@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred. -Historically front end inlining was more extensive than the gcc back end -inlining, but that is no longer the case. -@end table - -@node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{102} -@subsection Auxiliary Output Control - - -@geindex -gnatu (gcc) - - -@table @asis - -@item @code{-gnatu} - -Print a list of units required by this compilation on @code{stdout}. -The listing includes all units on which the unit being compiled depends -either directly or indirectly. -@end table - -@geindex -pass-exit-codes (gcc) - - -@table @asis - -@item @code{-pass-exit-codes} - -If this switch is not used, the exit code returned by @code{gcc} when -compiling multiple files indicates whether all source files have -been successfully used to generate object files or not. - -When @code{-pass-exit-codes} is used, @code{gcc} exits with an extended -exit status and allows an integrated development environment to better -react to a compilation failure. Those exit status are: - - -@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -`5' - -@tab - -There was an error in at least one source file. - -@item - -`3' - -@tab - -At least one source file did not generate an object file. - -@item - -`2' - -@tab - -The compiler died unexpectedly (internal error for example). - -@item - -`0' - -@tab - -An object file has been generated for every source file. - -@end multitable - -@end table - -@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{104} -@subsection Debugging Control - - -@quotation - -@geindex Debugging options -@end quotation - -@geindex -gnatd (gcc) - - -@table @asis - -@item @code{-gnatd`x'} - -Activate internal debugging switches. @code{x} is a letter or digit, or -string of letters or digits, which specifies the type of debugging -outputs desired. Normally these are used only for internal development -or system debugging purposes. You can find full documentation for these -switches in the body of the @code{Debug} unit in the compiler source -file @code{debug.adb}. -@end table - -@geindex -gnatG (gcc) - - -@table @asis - -@item @code{-gnatG[=`nn']} - -This switch causes the compiler to generate auxiliary output containing -a pseudo-source listing of the generated expanded code. Like most Ada -compilers, GNAT works by first transforming the high level Ada code into -lower level constructs. For example, tasking operations are transformed -into calls to the tasking run-time routines. A unique capability of GNAT -is to list this expanded code in a form very close to normal Ada source. -This is very useful in understanding the implications of various Ada -usage on the efficiency of the generated code. There are many cases in -Ada (e.g., the use of controlled types), where simple Ada statements can -generate a lot of run-time code. By using @code{-gnatG} you can identify -these cases, and consider whether it may be desirable to modify the coding -approach to improve efficiency. - -The optional parameter @code{nn} if present after -gnatG specifies an -alternative maximum line length that overrides the normal default of 72. -This value is in the range 40-999999, values less than 40 being silently -reset to 40. The equal sign is optional. - -The format of the output is very similar to standard Ada source, and is -easily understood by an Ada programmer. The following special syntactic -additions correspond to low level features used in the generated code that -do not have any exact analogies in pure Ada source form. The following -is a partial list of these special constructions. See the spec -of package @code{Sprint} in file @code{sprint.ads} for a full list. - -@geindex -gnatL (gcc) - -If the switch @code{-gnatL} is used in conjunction with -@code{-gnatG}, then the original source lines are interspersed -in the expanded source (as comment lines with the original line number). - - -@table @asis - -@item @code{new @var{xxx} [storage_pool = @var{yyy}]} - -Shows the storage pool being used for an allocator. - -@item @code{at end @var{procedure-name};} - -Shows the finalization (cleanup) procedure for a scope. - -@item @code{(if @var{expr} then @var{expr} else @var{expr})} - -Conditional expression equivalent to the @code{x?y:z} construction in C. - -@item @code{@var{target}^(@var{source})} - -A conversion with floating-point truncation instead of rounding. - -@item @code{@var{target}?(@var{source})} - -A conversion that bypasses normal Ada semantic checking. In particular -enumeration types and fixed-point types are treated simply as integers. - -@item @code{@var{target}?^(@var{source})} - -Combines the above two cases. -@end table - -@code{@var{x} #/ @var{y}} - -@code{@var{x} #mod @var{y}} - -@code{@var{x} # @var{y}} - - -@table @asis - -@item @code{@var{x} #rem @var{y}} - -A division or multiplication of fixed-point values which are treated as -integers without any kind of scaling. - -@item @code{free @var{expr} [storage_pool = @var{xxx}]} - -Shows the storage pool associated with a @code{free} statement. - -@item @code{[subtype or type declaration]} - -Used to list an equivalent declaration for an internally generated -type that is referenced elsewhere in the listing. - -@item @code{freeze @var{type-name} [@var{actions}]} - -Shows the point at which @code{type-name} is frozen, with possible -associated actions to be performed at the freeze point. - -@item @code{reference @var{itype}} - -Reference (and hence definition) to internal type @code{itype}. - -@item @code{@var{function-name}! (@var{arg}, @var{arg}, @var{arg})} - -Intrinsic function call. - -@item @code{@var{label-name} : label} - -Declaration of label @code{labelname}. - -@item @code{#$ @var{subprogram-name}} - -An implicit call to a run-time support routine -(to meet the requirement of H.3.1(9) in a -convenient manner). - -@item @code{@var{expr} && @var{expr} && @var{expr} ... && @var{expr}} - -A multiple concatenation (same effect as @code{expr} & @code{expr} & -@code{expr}, but handled more efficiently). - -@item @code{[constraint_error]} - -Raise the @code{Constraint_Error} exception. - -@item @code{@var{expression}'reference} - -A pointer to the result of evaluating @{expression@}. - -@item @code{@var{target-type}!(@var{source-expression})} - -An unchecked conversion of @code{source-expression} to @code{target-type}. - -@item @code{[@var{numerator}/@var{denominator}]} - -Used to represent internal real literals (that) have no exact -representation in base 2-16 (for example, the result of compile time -evaluation of the expression 1.0/27.0). -@end table -@end table - -@geindex -gnatD (gcc) - - -@table @asis - -@item @code{-gnatD[=nn]} - -When used in conjunction with @code{-gnatG}, this switch causes -the expanded source, as described above for -@code{-gnatG} to be written to files with names -@code{xxx.dg}, where @code{xxx} is the normal file name, -instead of to the standard output file. For -example, if the source file name is @code{hello.adb}, then a file -@code{hello.adb.dg} will be written. The debugging -information generated by the @code{gcc} @code{-g} switch -will refer to the generated @code{xxx.dg} file. This allows -you to do source level debugging using the generated code which is -sometimes useful for complex code, for example to find out exactly -which part of a complex construction raised an exception. This switch -also suppresses generation of cross-reference information (see -@code{-gnatx}) since otherwise the cross-reference information -would refer to the @code{.dg} file, which would cause -confusion since this is not the original source file. - -Note that @code{-gnatD} actually implies @code{-gnatG} -automatically, so it is not necessary to give both options. -In other words @code{-gnatD} is equivalent to @code{-gnatDG}). - -@geindex -gnatL (gcc) - -If the switch @code{-gnatL} is used in conjunction with -@code{-gnatDG}, then the original source lines are interspersed -in the expanded source (as comment lines with the original line number). - -The optional parameter @code{nn} if present after -gnatD specifies an -alternative maximum line length that overrides the normal default of 72. -This value is in the range 40-999999, values less than 40 being silently -reset to 40. The equal sign is optional. -@end table - -@geindex -gnatr (gcc) - -@geindex pragma Restrictions - - -@table @asis - -@item @code{-gnatr} - -This switch causes pragma Restrictions to be treated as Restriction_Warnings -so that violation of restrictions causes warnings rather than illegalities. -This is useful during the development process when new restrictions are added -or investigated. The switch also causes pragma Profile to be treated as -Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set -restriction warnings rather than restrictions. -@end table - -@geindex -gnatR (gcc) - - -@table @asis - -@item @code{-gnatR[0|1|2|3|4][e][j][m][s]} - -This switch controls output from the compiler of a listing showing -representation information for declared types, objects and subprograms. -For @code{-gnatR0}, no information is output (equivalent to omitting -the @code{-gnatR} switch). For @code{-gnatR1} (which is the default, -so @code{-gnatR} with no parameter has the same effect), size and -alignment information is listed for declared array and record types. - -For @code{-gnatR2}, size and alignment information is listed for all -declared types and objects. The @code{Linker_Section} is also listed for any -entity for which the @code{Linker_Section} is set explicitly or implicitly (the -latter case occurs for objects of a type for which a @code{Linker_Section} -is set). - -For @code{-gnatR3}, symbolic expressions for values that are computed -at run time for records are included. These symbolic expressions have -a mostly obvious format with #n being used to represent the value of the -n’th discriminant. See source files @code{repinfo.ads/adb} in the -GNAT sources for full details on the format of @code{-gnatR3} output. - -For @code{-gnatR4}, information for relevant compiler-generated types -is also listed, i.e. when they are structurally part of other declared -types and objects. - -If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then -extended representation information for record sub-components of records -is included. - -If the switch is followed by an @code{m} (e.g. @code{-gnatRm}), then -subprogram conventions and parameter passing mechanisms for all the -subprograms are included. - -If the switch is followed by a @code{j} (e.g., @code{-gnatRj}), then -the output is in the JSON data interchange format specified by the -ECMA-404 standard. The semantic description of this JSON output is -available in the specification of the Repinfo unit present in the -compiler sources. - -If the switch is followed by an @code{s} (e.g., @code{-gnatR3s}), then -the output is to a file with the name @code{file.rep} where @code{file} is -the name of the corresponding source file, except if @code{j} is also -specified, in which case the file name is @code{file.json}. - -Note that it is possible for record components to have zero size. In -this case, the component clause uses an obvious extension of permitted -Ada syntax, for example @code{at 0 range 0 .. -1}. -@end table - -@geindex -gnatS (gcc) - - -@table @asis - -@item @code{-gnatS} - -The use of the switch @code{-gnatS} for an -Ada compilation will cause the compiler to output a -representation of package Standard in a form very -close to standard Ada. It is not quite possible to -do this entirely in standard Ada (since new -numeric base types cannot be created in standard -Ada), but the output is easily -readable to any Ada programmer, and is useful to -determine the characteristics of target dependent -types in package Standard. -@end table - -@geindex -gnatx (gcc) - - -@table @asis - -@item @code{-gnatx} - -Normally the compiler generates full cross-referencing information in -the @code{ALI} file. This information is used by a number of tools. -The @code{-gnatx} switch suppresses this information. This saves some space -and may slightly speed up compilation, but means that tools depending -on this information cannot be used. -@end table - -@geindex -fgnat-encodings (gcc) - - -@table @asis - -@item @code{-fgnat-encodings=[all|gdb|minimal]} - -This switch controls the balance between GNAT encodings and standard DWARF -emitted in the debug information. - -Historically, old debug formats like stabs were not powerful enough to -express some Ada types (for instance, variant records or fixed-point types). -To work around this, GNAT introduced proprietary encodings that embed the -missing information (“GNAT encodings”). - -Recent versions of the DWARF debug information format are now able to -correctly describe most of these Ada constructs (“standard DWARF”). As -third-party tools started to use this format, GNAT has been enhanced to -generate it. However, most tools (including GDB) are still relying on GNAT -encodings. - -To support all tools, GNAT needs to be versatile about the balance between -generation of GNAT encodings and standard DWARF. This is what -@code{-fgnat-encodings} is about. - - -@itemize * - -@item -@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as -possible so it does not conflict with GNAT encodings. - -@item -@code{=gdb}: Emit as much standard DWARF as possible as long as the current -GDB handles it. Emit GNAT encodings for the rest. - -@item -@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT -encodings for the rest. -@end itemize -@end table - -@node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{106} -@subsection Exception Handling Control - - -GNAT uses two methods for handling exceptions at run time. The -@code{setjmp/longjmp} method saves the context when entering -a frame with an exception handler. Then when an exception is -raised, the context can be restored immediately, without the -need for tracing stack frames. This method provides very fast -exception propagation, but introduces significant overhead for -the use of exception handlers, even if no exception is raised. - -The other approach is called ‘zero cost’ exception handling. -With this method, the compiler builds static tables to describe -the exception ranges. No dynamic code is required when entering -a frame containing an exception handler. When an exception is -raised, the tables are used to control a back trace of the -subprogram invocation stack to locate the required exception -handler. This method has considerably poorer performance for -the propagation of exceptions, but there is no overhead for -exception handlers if no exception is raised. Note that in this -mode and in the context of mixed Ada and C/C++ programming, -to propagate an exception through a C/C++ code, the C/C++ code -must be compiled with the @code{-funwind-tables} GCC’s -option. - -The following switches may be used to control which of the -two exception handling methods is used. - -@geindex --RTS=sjlj (gnatmake) - - -@table @asis - -@item @code{--RTS=sjlj} - -This switch causes the setjmp/longjmp run-time (when available) to be used -for exception handling. If the default -mechanism for the target is zero cost exceptions, then -this switch can be used to modify this default, and must be -used for all units in the partition. -This option is rarely used. One case in which it may be -advantageous is if you have an application where exception -raising is common and the overall performance of the -application is improved by favoring exception propagation. -@end table - -@geindex --RTS=zcx (gnatmake) - -@geindex Zero Cost Exceptions - - -@table @asis - -@item @code{--RTS=zcx} - -This switch causes the zero cost approach to be used -for exception handling. If this is the default mechanism for the -target (see below), then this switch is unneeded. If the default -mechanism for the target is setjmp/longjmp exceptions, then -this switch can be used to modify this default, and must be -used for all units in the partition. -This option can only be used if the zero cost approach -is available for the target in use, otherwise it will generate an error. -@end table - -The same option @code{--RTS} must be used both for @code{gcc} -and @code{gnatbind}. Passing this option to @code{gnatmake} -(@ref{ce,,Switches for gnatmake}) will ensure the required consistency -through the compilation and binding steps. - -@node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{e8} -@subsection Units to Sources Mapping Files - - -@geindex -gnatem (gcc) - - -@table @asis - -@item @code{-gnatem=`path'} - -A mapping file is a way to communicate to the compiler two mappings: -from unit names to file names (without any directory information) and from -file names to path names (with full directory information). These mappings -are used by the compiler to short-circuit the path search. - -The use of mapping files is not required for correct operation of the -compiler, but mapping files can improve efficiency, particularly when -sources are read over a slow network connection. In normal operation, -you need not be concerned with the format or use of mapping files, -and the @code{-gnatem} switch is not a switch that you would use -explicitly. It is intended primarily for use by automatic tools such as -@code{gnatmake} running under the project file facility. The -description here of the format of mapping files is provided -for completeness and for possible use by other tools. - -A mapping file is a sequence of sets of three lines. In each set, the -first line is the unit name, in lower case, with @code{%s} appended -for specs and @code{%b} appended for bodies; the second line is the -file name; and the third line is the path name. - -Example: - -@example -main%b -main.2.ada -/gnat/project1/sources/main.2.ada -@end example - -When the switch @code{-gnatem} is specified, the compiler will -create in memory the two mappings from the specified file. If there is -any problem (nonexistent file, truncated file or duplicate entries), -no mapping will be created. - -Several @code{-gnatem} switches may be specified; however, only the -last one on the command line will be taken into account. - -When using a project file, @code{gnatmake} creates a temporary -mapping file and communicates it to the compiler using this switch. -@end table - -@node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches -@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{109} -@subsection Code Generation Control - - -The GCC technology provides a wide range of target dependent -@code{-m} switches for controlling -details of code generation with respect to different versions of -architectures. This includes variations in instruction sets (e.g., -different members of the power pc family), and different requirements -for optimal arrangement of instructions (e.g., different members of -the x86 family). The list of available @code{-m} switches may be -found in the GCC documentation. - -Use of these @code{-m} switches may in some cases result in improved -code performance. - -The GNAT technology is tested and qualified without any -@code{-m} switches, -so generally the most reliable approach is to avoid the use of these -switches. However, we generally expect most of these switches to work -successfully with GNAT, and many customers have reported successful -use of these options. - -Our general advice is to avoid the use of @code{-m} switches unless -special needs lead to requirements in this area. In particular, -there is no point in using @code{-m} switches to improve performance -unless you actually see a performance improvement. - -@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{10b} -@section Linker Switches - - -Linker switches can be specified after @code{-largs} builder switch. - -@geindex -fuse-ld=name - - -@table @asis - -@item @code{-fuse-ld=`name'} - -Linker to be used. The default is @code{bfd} for @code{ld.bfd}; @code{gold} -(for @code{ld.gold}) and @code{mold} (for @code{ld.mold}) are more -recent and faster alternatives, but only available on GNU/Linux -platforms. - -@end table - -@node Binding with gnatbind,Linking with gnatlink,Linker Switches,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c} -@section Binding with @code{gnatbind} - - -@geindex gnatbind - -This chapter describes the GNAT binder, @code{gnatbind}, which is used -to bind compiled GNAT objects. - -The @code{gnatbind} program performs four separate functions: - - -@itemize * - -@item -Checks that a program is consistent, in accordance with the rules in -Chapter 10 of the Ada Reference Manual. In particular, error -messages are generated if a program uses inconsistent versions of a -given unit. - -@item -Checks that an acceptable order of elaboration exists for the program -and issues an error message if it cannot find an order of elaboration -that satisfies the rules in Chapter 10 of the Ada Language Manual. - -@item -Generates a main program incorporating the given elaboration order. -This program is a small Ada package (body and spec) that -must be subsequently compiled -using the GNAT compiler. The necessary compilation step is usually -performed automatically by @code{gnatlink}. The two most important -functions of this program -are to call the elaboration routines of units in an appropriate order -and to call the main program. - -@item -Determines the set of object files required by the given main program. -This information is output in the forms of comments in the generated program, -to be read by the @code{gnatlink} utility used to link the Ada application. -@end itemize - -@menu -* Running gnatbind:: -* Switches for gnatbind:: -* Command-Line Access:: -* Search Paths for gnatbind:: -* Examples of gnatbind Usage:: - -@end menu - -@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{10e} -@subsection Running @code{gnatbind} - - -The form of the @code{gnatbind} command is - -@example -$ gnatbind [ switches ] mainprog[.ali] [ switches ] -@end example - -where @code{mainprog.adb} is the Ada file containing the main program -unit body. @code{gnatbind} constructs an Ada -package in two files whose names are -@code{b~mainprog.ads}, and @code{b~mainprog.adb}. -For example, if given the -parameter @code{hello.ali}, for a main program contained in file -@code{hello.adb}, the binder output files would be @code{b~hello.ads} -and @code{b~hello.adb}. - -When doing consistency checking, the binder takes into consideration -any source files it can locate. For example, if the binder determines -that the given main program requires the package @code{Pack}, whose -@code{.ALI} -file is @code{pack.ali} and whose corresponding source spec file is -@code{pack.ads}, it attempts to locate the source file @code{pack.ads} -(using the same search path conventions as previously described for the -@code{gcc} command). If it can locate this source file, it checks that -the time stamps -or source checksums of the source and its references to in @code{ALI} files -match. In other words, any @code{ALI} files that mentions this spec must have -resulted from compiling this version of the source file (or in the case -where the source checksums match, a version close enough that the -difference does not matter). - -@geindex Source files -@geindex use by binder - -The effect of this consistency checking, which includes source files, is -that the binder ensures that the program is consistent with the latest -version of the source files that can be located at bind time. Editing a -source file without compiling files that depend on the source file cause -error messages to be generated by the binder. - -For example, suppose you have a main program @code{hello.adb} and a -package @code{P}, from file @code{p.ads} and you perform the following -steps: - - -@itemize * - -@item -Enter @code{gcc -c hello.adb} to compile the main program. - -@item -Enter @code{gcc -c p.ads} to compile package @code{P}. - -@item -Edit file @code{p.ads}. - -@item -Enter @code{gnatbind hello}. -@end itemize - -At this point, the file @code{p.ali} contains an out-of-date time stamp -because the file @code{p.ads} has been edited. The attempt at binding -fails, and the binder generates the following error messages: - -@example -error: "hello.adb" must be recompiled ("p.ads" has been modified) -error: "p.ads" has been modified and must be recompiled -@end example - -Now both files must be recompiled as indicated, and then the bind can -succeed, generating a main program. You need not normally be concerned -with the contents of this file, but for reference purposes a sample -binder output file is given in @ref{e,,Example of Binder Output File}. - -In most normal usage, the default mode of @code{gnatbind} which is to -generate the main package in Ada, as described in the previous section. -In particular, this means that any Ada programmer can read and understand -the generated main program. It can also be debugged just like any other -Ada code provided the @code{-g} switch is used for -@code{gnatbind} and @code{gnatlink}. - -@node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{110} -@subsection Switches for @code{gnatbind} - - -The following switches are available with @code{gnatbind}; details will -be presented in subsequent sections. - -@geindex --version (gnatbind) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatbind) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. -@end table - -@geindex -a (gnatbind) - - -@table @asis - -@item @code{-a} - -Indicates that, if supported by the platform, the adainit procedure should -be treated as an initialisation routine by the linker (a constructor). This -is intended to be used by the Project Manager to automatically initialize -shared Stand-Alone Libraries. -@end table - -@geindex -aO (gnatbind) - - -@table @asis - -@item @code{-aO} - -Specify directory to be searched for ALI files. -@end table - -@geindex -aI (gnatbind) - - -@table @asis - -@item @code{-aI} - -Specify directory to be searched for source file. -@end table - -@geindex -A (gnatbind) - - -@table @asis - -@item @code{-A[=`filename']} - -Output ALI list (to standard output or to the named file). -@end table - -@geindex -b (gnatbind) - - -@table @asis - -@item @code{-b} - -Generate brief messages to @code{stderr} even if verbose mode set. -@end table - -@geindex -c (gnatbind) - - -@table @asis - -@item @code{-c} - -Check only, no generation of binder output file. -@end table - -@geindex -dnn[k|m] (gnatbind) - - -@table @asis - -@item @code{-d`nn'[k|m]} - -This switch can be used to change the default task stack size value -to a specified size @code{nn}, which is expressed in bytes by default, or -in kilobytes when suffixed with @code{k} or in megabytes when suffixed -with @code{m}. -In the absence of a @code{[k|m]} suffix, this switch is equivalent, -in effect, to completing all task specs with - -@example -pragma Storage_Size (nn); -@end example - -When they do not already have such a pragma. -@end table - -@geindex -D (gnatbind) - - -@table @asis - -@item @code{-D`nn'[k|m]} - -Set the default secondary stack size to @code{nn}. The suffix indicates whether -the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes -(@code{m} suffix). - -The secondary stack holds objects of unconstrained types that are returned by -functions, for example unconstrained Strings. The size of the secondary stack -can be dynamic or fixed depending on the target. - -For most targets, the secondary stack grows on demand and is implemented as -a chain of blocks in the heap. In this case, the default secondary stack size -determines the initial size of the secondary stack for each task and the -smallest amount the secondary stack can grow by. - -For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is -fixed. This switch can be used to change the default size of these stacks. -The default secondary stack size can be overridden on a per-task basis if -individual tasks have different secondary stack requirements. This is -achieved through the Secondary_Stack_Size aspect that takes the size of the -secondary stack in bytes. -@end table - -@geindex -e (gnatbind) - - -@table @asis - -@item @code{-e} - -Output complete list of elaboration-order dependencies. -@end table - -@geindex -Ea (gnatbind) - - -@table @asis - -@item @code{-Ea} - -Store tracebacks in exception occurrences when the target supports it. -The “a” is for “address”; tracebacks will contain hexadecimal addresses, -unless symbolic tracebacks are enabled. - -See also the packages @code{GNAT.Traceback} and -@code{GNAT.Traceback.Symbolic} for more information. -Note that on x86 ports, you must not use @code{-fomit-frame-pointer} -@code{gcc} option. -@end table - -@geindex -Es (gnatbind) - - -@table @asis - -@item @code{-Es} - -Store tracebacks in exception occurrences when the target supports it. -The “s” is for “symbolic”; symbolic tracebacks are enabled. -@end table - -@geindex -E (gnatbind) - - -@table @asis - -@item @code{-E} - -Currently the same as @code{-Ea}. -@end table - -@geindex -f (gnatbind) - - -@table @asis - -@item @code{-f`elab-order'} - -Force elaboration order. For further details see @ref{111,,Elaboration Control} -and @ref{f,,Elaboration Order Handling in GNAT}. -@end table - -@geindex -F (gnatbind) - - -@table @asis - -@item @code{-F} - -Force the checks of elaboration flags. @code{gnatbind} does not normally -generate checks of elaboration flags for the main executable, except when -a Stand-Alone Library is used. However, there are cases when this cannot be -detected by gnatbind. An example is importing an interface of a Stand-Alone -Library through a pragma Import and only specifying through a linker switch -this Stand-Alone Library. This switch is used to guarantee that elaboration -flag checks are generated. -@end table - -@geindex -h (gnatbind) - - -@table @asis - -@item @code{-h} - -Output usage (help) information. -@end table - -@geindex -H (gnatbind) - - -@table @asis - -@item @code{-H} - -Legacy elaboration order model enabled. For further details see -@ref{f,,Elaboration Order Handling in GNAT}. -@end table - -@geindex -H32 (gnatbind) - - -@table @asis - -@item @code{-H32} - -Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types). -For further details see @ref{112,,Dynamic Allocation Control}. -@end table - -@geindex -H64 (gnatbind) - -@geindex __gnat_malloc - - -@table @asis - -@item @code{-H64} - -Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types). -For further details see @ref{112,,Dynamic Allocation Control}. - -@geindex -I (gnatbind) - -@item @code{-I} - -Specify directory to be searched for source and ALI files. - -@geindex -I- (gnatbind) - -@item @code{-I-} - -Do not look for sources in the current directory where @code{gnatbind} was -invoked, and do not look for ALI files in the directory containing the -ALI file named in the @code{gnatbind} command line. - -@geindex -k (gnatbind) - -@item @code{-k} - -Disable checking of elaboration flags. When using @code{-n} -either explicitly or implicitly, @code{-F} is also implied, -unless @code{-k} is used. This switch should be used with care -and you should ensure manually that elaboration routines are not called -twice unintentionally. - -@geindex -K (gnatbind) - -@item @code{-K} - -Give list of linker options specified for link. - -@geindex -l (gnatbind) - -@item @code{-l} - -Output chosen elaboration order. - -@geindex -L (gnatbind) - -@item @code{-L`xxx'} - -Bind the units for library building. In this case the @code{adainit} and -@code{adafinal} procedures (@ref{a0,,Binding with Non-Ada Main Programs}) -are renamed to @code{@var{xxx}init} and -@code{@var{xxx}final}. -Implies -n. -(@ref{2a,,GNAT and Libraries}, for more details.) - -@geindex -M (gnatbind) - -@item @code{-M`xyz'} - -Rename generated main program from main to xyz. This option is -supported on cross environments only. - -@geindex -m (gnatbind) - -@item @code{-m`n'} - -Limit number of detected errors or warnings to @code{n}, where @code{n} is -in the range 1..999999. The default value if no switch is -given is 9999. If the number of warnings reaches this limit, then a -message is output and further warnings are suppressed, the bind -continues in this case. If the number of errors reaches this -limit, then a message is output and the bind is abandoned. -A value of zero means that no limit is enforced. The equal -sign is optional. - -@geindex -minimal (gnatbind) - -@item @code{-minimal} - -Generate a binder file suitable for space-constrained applications. When -active, binder-generated objects not required for program operation are no -longer generated. `Warning:' this option comes with the following -limitations: - - -@itemize * - -@item -Starting the program’s execution in the debugger will cause it to -stop at the start of the @code{main} function instead of the main subprogram. -This can be worked around by manually inserting a breakpoint on that -subprogram and resuming the program’s execution until reaching that breakpoint. - -@item -Programs using GNAT.Compiler_Version will not link. -@end itemize - -@geindex -n (gnatbind) - -@item @code{-n} - -No main program. - -@geindex -nostdinc (gnatbind) - -@item @code{-nostdinc} - -Do not look for sources in the system default directory. - -@geindex -nostdlib (gnatbind) - -@item @code{-nostdlib} - -Do not look for library files in the system default directory. - -@geindex --RTS (gnatbind) - -@item @code{--RTS=`rts-path'} - -Specifies the default location of the run-time library. Same meaning as the -equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}). - -@geindex -o (gnatbind) - -@item @code{-o `file'} - -Name the output file @code{file} (default is @code{b~`xxx}.adb`). -Note that if this option is used, then linking must be done manually, -gnatlink cannot be used. - -@geindex -O (gnatbind) - -@item @code{-O[=`filename']} - -Output object list (to standard output or to the named file). - -@geindex -p (gnatbind) - -@item @code{-p} - -Pessimistic (worst-case) elaboration order. - -@geindex -P (gnatbind) - -@item @code{-P} - -Generate binder file suitable for CodePeer. - -@geindex -R (gnatbind) - -@item @code{-R} - -Output closure source list, which includes all non-run-time units that are -included in the bind. - -@geindex -Ra (gnatbind) - -@item @code{-Ra} - -Like @code{-R} but the list includes run-time units. - -@geindex -s (gnatbind) - -@item @code{-s} - -Require all source files to be present. - -@geindex -S (gnatbind) - -@item @code{-S`xxx'} - -Specifies the value to be used when detecting uninitialized scalar -objects with pragma Initialize_Scalars. -The @code{xxx} string specified with the switch is one of: - - -@itemize * - -@item -@code{in} for an invalid value. - -If zero is invalid for the discrete type in question, -then the scalar value is set to all zero bits. -For signed discrete types, the largest possible negative value of -the underlying scalar is set (i.e. a one bit followed by all zero bits). -For unsigned discrete types, the underlying scalar value is set to all -one bits. For floating-point types, a NaN value is set -(see body of package System.Scalar_Values for exact values). - -@item -@code{lo} for low value. - -If zero is invalid for the discrete type in question, -then the scalar value is set to all zero bits. -For signed discrete types, the largest possible negative value of -the underlying scalar is set (i.e. a one bit followed by all zero bits). -For unsigned discrete types, the underlying scalar value is set to all -zero bits. For floating-point, a small value is set -(see body of package System.Scalar_Values for exact values). - -@item -@code{hi} for high value. - -If zero is invalid for the discrete type in question, -then the scalar value is set to all one bits. -For signed discrete types, the largest possible positive value of -the underlying scalar is set (i.e. a zero bit followed by all one bits). -For unsigned discrete types, the underlying scalar value is set to all -one bits. For floating-point, a large value is set -(see body of package System.Scalar_Values for exact values). - -@item -@code{xx} for hex value (two hex digits). - -The underlying scalar is set to a value consisting of repeated bytes, whose -value corresponds to the given value. For example if @code{BF} is given, -then a 32-bit scalar value will be set to the bit patterm @code{16#BFBFBFBF#}. -@end itemize - -@geindex GNAT_INIT_SCALARS - -In addition, you can specify @code{-Sev} to indicate that the value is -to be set at run time. In this case, the program will look for an environment -variable of the form @code{GNAT_INIT_SCALARS=@var{yy}}, where @code{yy} is one -of @code{in/lo/hi/@var{xx}} with the same meanings as above. -If no environment variable is found, or if it does not have a valid value, -then the default is @code{in} (invalid values). -@end table - -@geindex -static (gnatbind) - - -@table @asis - -@item @code{-static} - -Link against a static GNAT run-time. - -@geindex -shared (gnatbind) - -@item @code{-shared} - -Link against a shared GNAT run-time when available. - -@geindex -t (gnatbind) - -@item @code{-t} - -Tolerate time stamp and other consistency errors. - -@geindex -T (gnatbind) - -@item @code{-T`n'} - -Set the time slice value to @code{n} milliseconds. If the system supports -the specification of a specific time slice value, then the indicated value -is used. If the system does not support specific time slice values, but -does support some general notion of round-robin scheduling, then any -nonzero value will activate round-robin scheduling. - -A value of zero is treated specially. It turns off time -slicing, and in addition, indicates to the tasking run-time that the -semantics should match as closely as possible the Annex D -requirements of the Ada RM, and in particular sets the default -scheduling policy to @code{FIFO_Within_Priorities}. - -@geindex -u (gnatbind) - -@item @code{-u`n'} - -Enable dynamic stack usage, with @code{n} results stored and displayed -at program termination. A result is generated when a task -terminates. Results that can’t be stored are displayed on the fly, at -task termination. This option is currently not supported on Itanium -platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.) - -@geindex -v (gnatbind) - -@item @code{-v} - -Verbose mode. Write error messages, header, summary output to -@code{stdout}. - -@geindex -V (gnatbind) - -@item @code{-V`key'=`value'} - -Store the given association of @code{key} to @code{value} in the bind environment. -Values stored this way can be retrieved at run time using -@code{GNAT.Bind_Environment}. - -@geindex -w (gnatbind) - -@item @code{-w`x'} - -Warning mode; @code{x} = s/e for suppress/treat as error. - -@geindex -Wx (gnatbind) - -@item @code{-Wx`e'} - -Override default wide character encoding for standard Text_IO files. - -@geindex -x (gnatbind) - -@item @code{-x} - -Exclude source files (check object consistency only). - -@geindex -xdr (gnatbind) - -@item @code{-xdr} - -Use the target-independent XDR protocol for stream oriented attributes -instead of the default implementation which is based on direct binary -representations and is therefore target-and endianness-dependent. -However it does not support 128-bit integer types and the exception -@code{Ada.IO_Exceptions.Device_Error} is raised if any attempt is made -at streaming 128-bit integer types with it. - -@geindex -Xnnn (gnatbind) - -@item @code{-X`nnn'} - -Set default exit status value, normally 0 for POSIX compliance. - -@geindex -y (gnatbind) - -@item @code{-y} - -Enable leap seconds support in @code{Ada.Calendar} and its children. - -@geindex -z (gnatbind) - -@item @code{-z} - -No main subprogram. -@end table - -You may obtain this listing of switches by running @code{gnatbind} with -no arguments. - -@menu -* Consistency-Checking Modes:: -* Binder Error Message Control:: -* Elaboration Control:: -* Output Control:: -* Dynamic Allocation Control:: -* Binding with Non-Ada Main Programs:: -* Binding Programs with No Main Subprogram:: - -@end menu - -@node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{115} -@subsubsection Consistency-Checking Modes - - -As described earlier, by default @code{gnatbind} checks -that object files are consistent with one another and are consistent -with any source files it can locate. The following switches control binder -access to sources. - -@quotation - -@geindex -s (gnatbind) -@end quotation - - -@table @asis - -@item @code{-s} - -Require source files to be present. In this mode, the binder must be -able to locate all source files that are referenced, in order to check -their consistency. In normal mode, if a source file cannot be located it -is simply ignored. If you specify this switch, a missing source -file is an error. - -@geindex -Wx (gnatbind) - -@item @code{-Wx`e'} - -Override default wide character encoding for standard Text_IO files. -Normally the default wide character encoding method used for standard -[Wide_[Wide_]]Text_IO files is taken from the encoding specified for -the main source input (see description of switch -@code{-gnatWx} for the compiler). The -use of this switch for the binder (which has the same set of -possible arguments) overrides this default as specified. - -@geindex -x (gnatbind) - -@item @code{-x} - -Exclude source files. In this mode, the binder only checks that ALI -files are consistent with one another. Source files are not accessed. -The binder runs faster in this mode, and there is still a guarantee that -the resulting program is self-consistent. -If a source file has been edited since it was last compiled, and you -specify this switch, the binder will not detect that the object -file is out of date with respect to the source file. Note that this is the -mode that is automatically used by @code{gnatmake} because in this -case the checking against sources has already been performed by -@code{gnatmake} in the course of compilation (i.e., before binding). -@end table - -@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{117} -@subsubsection Binder Error Message Control - - -The following switches provide control over the generation of error -messages from the binder: - -@quotation - -@geindex -v (gnatbind) -@end quotation - - -@table @asis - -@item @code{-v} - -Verbose mode. In the normal mode, brief error messages are generated to -@code{stderr}. If this switch is present, a header is written -to @code{stdout} and any error messages are directed to @code{stdout}. -All that is written to @code{stderr} is a brief summary message. - -@geindex -b (gnatbind) - -@item @code{-b} - -Generate brief error messages to @code{stderr} even if verbose mode is -specified. This is relevant only when used with the -@code{-v} switch. - -@geindex -m (gnatbind) - -@item @code{-m`n'} - -Limits the number of error messages to @code{n}, a decimal integer in the -range 1-999. The binder terminates immediately if this limit is reached. - -@geindex -M (gnatbind) - -@item @code{-M`xxx'} - -Renames the generated main program from @code{main} to @code{xxx}. -This is useful in the case of some cross-building environments, where -the actual main program is separate from the one generated -by @code{gnatbind}. - -@geindex -ws (gnatbind) - -@geindex Warnings - -@item @code{-ws} - -Suppress all warning messages. - -@geindex -we (gnatbind) - -@item @code{-we} - -Treat any warning messages as fatal errors. - -@geindex -t (gnatbind) - -@geindex Time stamp checks -@geindex in binder - -@geindex Binder consistency checks - -@geindex Consistency checks -@geindex in binder - -@item @code{-t} - -The binder performs a number of consistency checks including: - - -@itemize * - -@item -Check that time stamps of a given source unit are consistent - -@item -Check that checksums of a given source unit are consistent - -@item -Check that consistent versions of @code{GNAT} were used for compilation - -@item -Check consistency of configuration pragmas as required -@end itemize - -Normally failure of such checks, in accordance with the consistency -requirements of the Ada Reference Manual, causes error messages to be -generated which abort the binder and prevent the output of a binder -file and subsequent link to obtain an executable. - -The @code{-t} switch converts these error messages -into warnings, so that -binding and linking can continue to completion even in the presence of such -errors. The result may be a failed link (due to missing symbols), or a -non-functional executable which has undefined semantics. - -@cartouche -@quotation Note -This means that @code{-t} should be used only in unusual situations, -with extreme care. -@end quotation -@end cartouche -@end table - -@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{111}@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{118} -@subsubsection Elaboration Control - - -The following switches provide additional control over the elaboration -order. For further details see @ref{f,,Elaboration Order Handling in GNAT}. - -@geindex -f (gnatbind) - - -@table @asis - -@item @code{-f`elab-order'} - -Force elaboration order. - -@code{elab-order} should be the name of a “forced elaboration order file”, that -is, a text file containing library item names, one per line. A name of the -form “some.unit%s” or “some.unit (spec)” denotes the spec of Some.Unit. A -name of the form “some.unit%b” or “some.unit (body)” denotes the body of -Some.Unit. Each pair of lines is taken to mean that there is an elaboration -dependence of the second line on the first. For example, if the file -contains: - -@example -this (spec) -this (body) -that (spec) -that (body) -@end example - -then the spec of This will be elaborated before the body of This, and the -body of This will be elaborated before the spec of That, and the spec of That -will be elaborated before the body of That. The first and last of these three -dependences are already required by Ada rules, so this file is really just -forcing the body of This to be elaborated before the spec of That. - -The given order must be consistent with Ada rules, or else @code{gnatbind} will -give elaboration cycle errors. For example, if you say x (body) should be -elaborated before x (spec), there will be a cycle, because Ada rules require -x (spec) to be elaborated before x (body); you can’t have the spec and body -both elaborated before each other. - -If you later add “with That;” to the body of This, there will be a cycle, in -which case you should erase either “this (body)” or “that (spec)” from the -above forced elaboration order file. - -Blank lines and Ada-style comments are ignored. Unit names that do not exist -in the program are ignored. Units in the GNAT predefined library are also -ignored. -@end table - -@geindex -p (gnatbind) - - -@table @asis - -@item @code{-p} - -Pessimistic elaboration order - -This switch is only applicable to the pre-20.x legacy elaboration models. -The post-20.x elaboration model uses a more informed approach of ordering -the units. - -Normally the binder attempts to choose an elaboration order that is likely to -minimize the likelihood of an elaboration order error resulting in raising a -@code{Program_Error} exception. This switch reverses the action of the binder, -and requests that it deliberately choose an order that is likely to maximize -the likelihood of an elaboration error. This is useful in ensuring -portability and avoiding dependence on accidental fortuitous elaboration -ordering. - -Normally it only makes sense to use the @code{-p} switch if dynamic -elaboration checking is used (@code{-gnatE} switch used for compilation). -This is because in the default static elaboration mode, all necessary -@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted. -These implicit pragmas are still respected by the binder in @code{-p} -mode, so a safe elaboration order is assured. - -Note that @code{-p} is not intended for production use; it is more for -debugging/experimental use. -@end table - -@node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{11a} -@subsubsection Output Control - - -The following switches allow additional control over the output -generated by the binder. - -@quotation - -@geindex -c (gnatbind) -@end quotation - - -@table @asis - -@item @code{-c} - -Check only. Do not generate the binder output file. In this mode the -binder performs all error checks but does not generate an output file. - -@geindex -e (gnatbind) - -@item @code{-e} - -Output complete list of elaboration-order dependencies, showing the -reason for each dependency. This output can be rather extensive but may -be useful in diagnosing problems with elaboration order. The output is -written to @code{stdout}. - -@geindex -h (gnatbind) - -@item @code{-h} - -Output usage information. The output is written to @code{stdout}. - -@geindex -K (gnatbind) - -@item @code{-K} - -Output linker options to @code{stdout}. Includes library search paths, -contents of pragmas Ident and Linker_Options, and libraries added -by @code{gnatbind}. - -@geindex -l (gnatbind) - -@item @code{-l} - -Output chosen elaboration order. The output is written to @code{stdout}. - -@geindex -O (gnatbind) - -@item @code{-O} - -Output full names of all the object files that must be linked to provide -the Ada component of the program. The output is written to @code{stdout}. -This list includes the files explicitly supplied and referenced by the user -as well as implicitly referenced run-time unit files. The latter are -omitted if the corresponding units reside in shared libraries. The -directory names for the run-time units depend on the system configuration. - -@geindex -o (gnatbind) - -@item @code{-o `file'} - -Set name of output file to @code{file} instead of the normal -@code{b~`mainprog}.adb` default. Note that @code{file} denote the Ada -binder generated body filename. -Note that if this option is used, then linking must be done manually. -It is not possible to use gnatlink in this case, since it cannot locate -the binder file. - -@geindex -r (gnatbind) - -@item @code{-r} - -Generate list of @code{pragma Restrictions} that could be applied to -the current unit. This is useful for code audit purposes, and also may -be used to improve code generation in some cases. -@end table - -@node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{11b} -@subsubsection Dynamic Allocation Control - - -The heap control switches – @code{-H32} and @code{-H64} – -determine whether dynamic allocation uses 32-bit or 64-bit memory. -They only affect compiler-generated allocations via @code{__gnat_malloc}; -explicit calls to @code{malloc} and related functions from the C -run-time library are unaffected. - - -@table @asis - -@item @code{-H32} - -Allocate memory on 32-bit heap - -@item @code{-H64} - -Allocate memory on 64-bit heap. This is the default -unless explicitly overridden by a @code{'Size} clause on the access type. -@end table - -These switches are only effective on VMS platforms. - -@node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{a0}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{11c} -@subsubsection Binding with Non-Ada Main Programs - - -The description so far has assumed that the main -program is in Ada, and that the task of the binder is to generate a -corresponding function @code{main} that invokes this Ada main -program. GNAT also supports the building of executable programs where -the main program is not in Ada, but some of the called routines are -written in Ada and compiled using GNAT (@ref{2c,,Mixed Language Programming}). -The following switch is used in this situation: - -@quotation - -@geindex -n (gnatbind) -@end quotation - - -@table @asis - -@item @code{-n} - -No main program. The main program is not in Ada. -@end table - -In this case, most of the functions of the binder are still required, -but instead of generating a main program, the binder generates a file -containing the following callable routines: - -@quotation - -@geindex adainit - - -@table @asis - -@item @code{adainit} - -You must call this routine to initialize the Ada part of the program by -calling the necessary elaboration routines. A call to @code{adainit} is -required before the first call to an Ada subprogram. - -Note that it is assumed that the basic execution environment must be setup -to be appropriate for Ada execution at the point where the first Ada -subprogram is called. In particular, if the Ada code will do any -floating-point operations, then the FPU must be setup in an appropriate -manner. For the case of the x86, for example, full precision mode is -required. The procedure GNAT.Float_Control.Reset may be used to ensure -that the FPU is in the right state. -@end table - -@geindex adafinal - - -@table @asis - -@item @code{adafinal} - -You must call this routine to perform any library-level finalization -required by the Ada subprograms. A call to @code{adafinal} is required -after the last call to an Ada subprogram, and before the program -terminates. -@end table -@end quotation - -@geindex -n (gnatbind) - -@geindex Binder -@geindex multiple input files - -If the @code{-n} switch -is given, more than one ALI file may appear on -the command line for @code{gnatbind}. The normal @code{closure} -calculation is performed for each of the specified units. Calculating -the closure means finding out the set of units involved by tracing -`with' references. The reason it is necessary to be able to -specify more than one ALI file is that a given program may invoke two or -more quite separate groups of Ada units. - -The binder takes the name of its output file from the last specified ALI -file, unless overridden by the use of the @code{-o file}. - -@geindex -o (gnatbind) - -The output is an Ada unit in source form that can be compiled with GNAT. -This compilation occurs automatically as part of the @code{gnatlink} -processing. - -Currently the GNAT run-time requires a FPU using 80 bits mode -precision. Under targets where this is not the default it is required to -call GNAT.Float_Control.Reset before using floating point numbers (this -include float computation, float input and output) in the Ada code. A -side effect is that this could be the wrong mode for the foreign code -where floating point computation could be broken after this call. - -@node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{11d}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{11e} -@subsubsection Binding Programs with No Main Subprogram - - -It is possible to have an Ada program which does not have a main -subprogram. This program will call the elaboration routines of all the -packages, then the finalization routines. - -The following switch is used to bind programs organized in this manner: - -@quotation - -@geindex -z (gnatbind) -@end quotation - - -@table @asis - -@item @code{-z} - -Normally the binder checks that the unit name given on the command line -corresponds to a suitable main subprogram. When this switch is used, -a list of ALI files can be given, and the execution of the program -consists of elaboration of these units in an appropriate order. Note -that the default wide character encoding method for standard Text_IO -files is always set to Brackets if this switch is set (you can use -the binder switch -@code{-Wx} to override this default). -@end table - -@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{120} -@subsection Command-Line Access - - -The package @code{Ada.Command_Line} provides access to the command-line -arguments and program name. In order for this interface to operate -correctly, the two variables - -@example -int gnat_argc; -char **gnat_argv; -@end example - -@geindex gnat_argv - -@geindex gnat_argc - -are declared in one of the GNAT library routines. These variables must -be set from the actual @code{argc} and @code{argv} values passed to the -main program. With no `n' present, @code{gnatbind} -generates the C main program to automatically set these variables. -If the `n' switch is used, there is no automatic way to -set these variables. If they are not set, the procedures in -@code{Ada.Command_Line} will not be available, and any attempt to use -them will raise @code{Constraint_Error}. If command line access is -required, your main program must set @code{gnat_argc} and -@code{gnat_argv} from the @code{argc} and @code{argv} values passed to -it. - -@node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{121}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{76} -@subsection Search Paths for @code{gnatbind} - - -The binder takes the name of an ALI file as its argument and needs to -locate source files as well as other ALI files to verify object consistency. - -For source files, it follows exactly the same search rules as @code{gcc} -(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the -directories searched are: - - -@itemize * - -@item -The directory containing the ALI file named in the command line, unless -the switch @code{-I-} is specified. - -@item -All directories specified by @code{-I} -switches on the @code{gnatbind} -command line, in the order given. - -@geindex ADA_PRJ_OBJECTS_FILE - -@item -Each of the directories listed in the text file whose name is given -by the -@geindex ADA_PRJ_OBJECTS_FILE -@geindex environment variable; ADA_PRJ_OBJECTS_FILE -@code{ADA_PRJ_OBJECTS_FILE} environment variable. - -@geindex ADA_PRJ_OBJECTS_FILE -@geindex environment variable; ADA_PRJ_OBJECTS_FILE -@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the gnat -driver when project files are used. It should not normally be set -by other means. - -@geindex ADA_OBJECTS_PATH - -@item -Each of the directories listed in the value of the -@geindex ADA_OBJECTS_PATH -@geindex environment variable; ADA_OBJECTS_PATH -@code{ADA_OBJECTS_PATH} environment variable. -Construct this value -exactly as the -@geindex PATH -@geindex environment variable; PATH -@code{PATH} environment variable: a list of directory -names separated by colons (semicolons when working with the NT version -of GNAT). - -@item -The content of the @code{ada_object_path} file which is part of the GNAT -installation tree and is used to store standard libraries such as the -GNAT Run-Time Library (RTL) unless the switch @code{-nostdlib} is -specified. See @ref{72,,Installing a library} -@end itemize - -@geindex -I (gnatbind) - -@geindex -aI (gnatbind) - -@geindex -aO (gnatbind) - -In the binder the switch @code{-I} -is used to specify both source and -library file paths. Use @code{-aI} -instead if you want to specify -source paths only, and @code{-aO} -if you want to specify library paths -only. This means that for the binder -@code{-I`dir'} is equivalent to -@code{-aI`dir'} -@code{-aO``dir'}. -The binder generates the bind file (a C language source file) in the -current working directory. - -@geindex Ada - -@geindex System - -@geindex Interfaces - -@geindex GNAT - -The packages @code{Ada}, @code{System}, and @code{Interfaces} and their -children make up the GNAT Run-Time Library, together with the package -GNAT and its children, which contain a set of useful additional -library functions provided by GNAT. The sources for these units are -needed by the compiler and are kept together in one directory. The ALI -files and object files generated by compiling the RTL are needed by the -binder and the linker and are kept together in one directory, typically -different from the directory containing the sources. In a normal -installation, you need not specify these directory names when compiling -or binding. Either the environment variables or the built-in defaults -cause these files to be found. - -Besides simplifying access to the RTL, a major use of search paths is -in compiling sources from multiple directories. This can make -development environments much more flexible. - -@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind -@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{123} -@subsection Examples of @code{gnatbind} Usage - - -Here are some examples of @code{gnatbind} invocations: - -@quotation - -@example -gnatbind hello -@end example - -The main program @code{Hello} (source program in @code{hello.adb}) is -bound using the standard switch settings. The generated main program is -@code{b~hello.adb}. This is the normal, default use of the binder. - -@example -gnatbind hello -o mainprog.adb -@end example - -The main program @code{Hello} (source program in @code{hello.adb}) is -bound using the standard switch settings. The generated main program is -@code{mainprog.adb} with the associated spec in -@code{mainprog.ads}. Note that you must specify the body here not the -spec. Note that if this option is used, then linking must be done manually, -since gnatlink will not be able to find the generated file. -@end quotation - -@node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{124}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{c9} -@section Linking with @code{gnatlink} - - -@geindex gnatlink - -This chapter discusses @code{gnatlink}, a tool that links -an Ada program and builds an executable file. This utility -invokes the system linker (via the @code{gcc} command) -with a correct list of object files and library references. -@code{gnatlink} automatically determines the list of files and -references for the Ada part of a program. It uses the binder file -generated by the @code{gnatbind} to determine this list. - -@menu -* Running gnatlink:: -* Switches for gnatlink:: - -@end menu - -@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink -@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{126} -@subsection Running @code{gnatlink} - - -The form of the @code{gnatlink} command is - -@example -$ gnatlink [ switches ] mainprog [.ali] - [ non-Ada objects ] [ linker options ] -@end example - -The arguments of @code{gnatlink} (switches, main @code{ALI} file, -non-Ada objects -or linker options) may be in any order, provided that no non-Ada object may -be mistaken for a main @code{ALI} file. -Any file name @code{F} without the @code{.ali} -extension will be taken as the main @code{ALI} file if a file exists -whose name is the concatenation of @code{F} and @code{.ali}. - -@code{mainprog.ali} references the ALI file of the main program. -The @code{.ali} extension of this file can be omitted. From this -reference, @code{gnatlink} locates the corresponding binder file -@code{b~mainprog.adb} and, using the information in this file along -with the list of non-Ada objects and linker options, constructs a -linker command file to create the executable. - -The arguments other than the @code{gnatlink} switches and the main -@code{ALI} file are passed to the linker uninterpreted. -They typically include the names of -object files for units written in other languages than Ada and any library -references required to resolve references in any of these foreign language -units, or in @code{Import} pragmas in any Ada units. - -@code{linker options} is an optional list of linker specific -switches. -The default linker called by gnatlink is @code{gcc} which in -turn calls the appropriate system linker. - -One useful option for the linker is @code{-s}: it reduces the size of the -executable by removing all symbol table and relocation information from the -executable. - -Standard options for the linker such as @code{-lmy_lib} or -@code{-Ldir} can be added as is. -For options that are not recognized by -@code{gcc} as linker options, use the @code{gcc} switches -@code{-Xlinker} or @code{-Wl,}. - -Refer to the GCC documentation for -details. - -Here is an example showing how to generate a linker map: - -@example -$ gnatlink my_prog -Wl,-Map,MAPFILE -@end example - -Using @code{linker options} it is possible to set the program stack and -heap size. -See @ref{127,,Setting Stack Size from gnatlink} and -@ref{128,,Setting Heap Size from gnatlink}. - -@code{gnatlink} determines the list of objects required by the Ada -program and prepends them to the list of objects passed to the linker. -@code{gnatlink} also gathers any arguments set by the use of -@code{pragma Linker_Options} and adds them to the list of arguments -presented to the linker. - -@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink -@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{129}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{12a} -@subsection Switches for @code{gnatlink} - - -The following switches are available with the @code{gnatlink} utility: - -@geindex --version (gnatlink) - - -@table @asis - -@item @code{--version} - -Display Copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatlink) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. -@end table - -@geindex Command line length - -@geindex -f (gnatlink) - - -@table @asis - -@item @code{-f} - -On some targets, the command line length is limited, and @code{gnatlink} -will generate a separate file for the linker if the list of object files -is too long. -The @code{-f} switch forces this file -to be generated even if -the limit is not exceeded. This is useful in some cases to deal with -special situations where the command line length is exceeded. -@end table - -@geindex Debugging information -@geindex including - -@geindex -g (gnatlink) - - -@table @asis - -@item @code{-g} - -The option to include debugging information causes the Ada bind file (in -other words, @code{b~mainprog.adb}) to be compiled with @code{-g}. -In addition, the binder does not delete the @code{b~mainprog.adb}, -@code{b~mainprog.o} and @code{b~mainprog.ali} files. -Without @code{-g}, the binder removes these files by default. -@end table - -@geindex -n (gnatlink) - - -@table @asis - -@item @code{-n} - -Do not compile the file generated by the binder. This may be used when -a link is rerun with different options, but there is no need to recompile -the binder file. -@end table - -@geindex -v (gnatlink) - - -@table @asis - -@item @code{-v} - -Verbose mode. Causes additional information to be output, including a full -list of the included object files. -This switch option is most useful when you want -to see what set of object files are being used in the link step. -@end table - -@geindex -v -v (gnatlink) - - -@table @asis - -@item @code{-v -v} - -Very verbose mode. Requests that the compiler operate in verbose mode when -it compiles the binder file, and that the system linker run in verbose mode. -@end table - -@geindex -o (gnatlink) - - -@table @asis - -@item @code{-o `exec-name'} - -@code{exec-name} specifies an alternate name for the generated -executable program. If this switch is omitted, the executable has the same -name as the main unit. For example, @code{gnatlink try.ali} creates -an executable called @code{try}. -@end table - -@geindex -B (gnatlink) - - -@table @asis - -@item @code{-B`dir'} - -Load compiler executables (for example, @code{gnat1}, the Ada compiler) -from @code{dir} instead of the default location. Only use this switch -when multiple versions of the GNAT compiler are available. -See the @code{Directory Options} section in @cite{The_GNU_Compiler_Collection} -for further details. You would normally use the @code{-b} or -@code{-V} switch instead. -@end table - -@geindex -M (gnatlink) - - -@table @asis - -@item @code{-M} - -When linking an executable, create a map file. The name of the map file -has the same name as the executable with extension “.map”. -@end table - -@geindex -M= (gnatlink) - - -@table @asis - -@item @code{-M=`mapfile'} - -When linking an executable, create a map file. The name of the map file is -@code{mapfile}. -@end table - -@geindex --GCC=compiler_name (gnatlink) - - -@table @asis - -@item @code{--GCC=`compiler_name'} - -Program used for compiling the binder file. The default is -@code{gcc}. You need to use quotes around @code{compiler_name} if -@code{compiler_name} contains spaces or other separator characters. -As an example @code{--GCC="foo -x -y"} will instruct @code{gnatlink} to -use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always -inserted after your command name. Thus in the above example the compiler -command that will be used by @code{gnatlink} will be @code{foo -c -x -y}. -A limitation of this syntax is that the name and path name of the executable -itself must not include any embedded spaces. If the compiler executable is -different from the default one (gcc or -gcc), then the back-end -switches in the ALI file are not used to compile the binder generated source. -For example, this is the case with @code{--GCC="foo -x -y"}. But the back end -switches will be used for @code{--GCC="gcc -gnatv"}. If several -@code{--GCC=compiler_name} are used, only the last @code{compiler_name} -is taken into account. However, all the additional switches are also taken -into account. Thus, -@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to -@code{--GCC="bar -x -y -z -t"}. -@end table - -@geindex --LINK= (gnatlink) - - -@table @asis - -@item @code{--LINK=`name'} - -@code{name} is the name of the linker to be invoked. This is especially -useful in mixed language programs since languages such as C++ require -their own linker to be used. When this switch is omitted, the default -name for the linker is @code{gcc}. When this switch is used, the -specified linker is called instead of @code{gcc} with exactly the same -parameters that would have been passed to @code{gcc} so if the desired -linker requires different parameters it is necessary to use a wrapper -script that massages the parameters before invoking the real linker. It -may be useful to control the exact invocation by using the verbose -switch. -@end table - -@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT -@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{12b}@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{70} -@section Using the GNU @code{make} Utility - - -@geindex make (GNU) -@geindex GNU make - -This chapter offers some examples of makefiles that solve specific -problems. It does not explain how to write a makefile, nor does it try to replace the -@code{gnatmake} utility (@ref{c6,,Building with gnatmake}). - -All the examples in this section are specific to the GNU version of -make. Although @code{make} is a standard utility, and the basic language -is the same, these examples use some advanced features found only in -@code{GNU make}. - -@menu -* Using gnatmake in a Makefile:: -* Automatically Creating a List of Directories:: -* Generating the Command Line Switches:: -* Overcoming Command Line Length Limits:: - -@end menu - -@node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility -@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{12d} -@subsection Using gnatmake in a Makefile - - -@c index makefile (GNU make) - -Complex project organizations can be handled in a very powerful way by -using GNU make combined with gnatmake. For instance, here is a Makefile -which allows you to build each subsystem of a big project into a separate -shared library. Such a makefile allows you to significantly reduce the link -time of very big applications while maintaining full coherence at -each step of the build process. - -The list of dependencies are handled automatically by -@code{gnatmake}. The Makefile is simply used to call gnatmake in each of -the appropriate directories. - -Note that you should also read the example on how to automatically -create the list of directories -(@ref{12e,,Automatically Creating a List of Directories}) -which might help you in case your project has a lot of subdirectories. - -@example -## This Makefile is intended to be used with the following directory -## configuration: -## - The sources are split into a series of csc (computer software components) -## Each of these csc is put in its own directory. -## Their name are referenced by the directory names. -## They will be compiled into shared library (although this would also work -## with static libraries) -## - The main program (and possibly other packages that do not belong to any -## csc) is put in the top level directory (where the Makefile is). -## toplevel_dir __ first_csc (sources) __ lib (will contain the library) -## \\_ second_csc (sources) __ lib (will contain the library) -## \\_ ... -## Although this Makefile is build for shared library, it is easy to modify -## to build partial link objects instead (modify the lines with -shared and -## gnatlink below) -## -## With this makefile, you can change any file in the system or add any new -## file, and everything will be recompiled correctly (only the relevant shared -## objects will be recompiled, and the main program will be re-linked). - -# The list of computer software component for your project. This might be -# generated automatically. -CSC_LIST=aa bb cc - -# Name of the main program (no extension) -MAIN=main - -# If we need to build objects with -fPIC, uncomment the following line -#NEED_FPIC=-fPIC - -# The following variable should give the directory containing libgnat.so -# You can get this directory through 'gnatls -v'. This is usually the last -# directory in the Object_Path. -GLIB=... - -# The directories for the libraries -# (This macro expands the list of CSC to the list of shared libraries, you -# could simply use the expanded form: -# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so -LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@} - -$@{MAIN@}: objects $@{LIB_DIR@} - gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared - gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@} - -objects:: - # recompile the sources - gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@} - -# Note: In a future version of GNAT, the following commands will be simplified -# by a new tool, gnatmlib -$@{LIB_DIR@}: - mkdir -p $@{dir $@@ @} - cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat - cd $@{dir $@@ @} && cp -f ../*.ali . - -# The dependencies for the modules -# Note that we have to force the expansion of *.o, since in some cases -# make won't be able to do it itself. -aa/lib/libaa.so: $@{wildcard aa/*.o@} -bb/lib/libbb.so: $@{wildcard bb/*.o@} -cc/lib/libcc.so: $@{wildcard cc/*.o@} - -# Make sure all of the shared libraries are in the path before starting the -# program -run:: - LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@} - -clean:: - $@{RM@} -rf $@{CSC_LIST:%=%/lib@} - $@{RM@} $@{CSC_LIST:%=%/*.ali@} - $@{RM@} $@{CSC_LIST:%=%/*.o@} - $@{RM@} *.o *.ali $@{MAIN@} -@end example - -@node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility -@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{12e}@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{12f} -@subsection Automatically Creating a List of Directories - - -In most makefiles, you will have to specify a list of directories, and -store it in a variable. For small projects, it is often easier to -specify each of them by hand, since you then have full control over what -is the proper order for these directories, which ones should be -included. - -However, in larger projects, which might involve hundreds of -subdirectories, it might be more convenient to generate this list -automatically. - -The example below presents two methods. The first one, although less -general, gives you more control over the list. It involves wildcard -characters, that are automatically expanded by @code{make}. Its -shortcoming is that you need to explicitly specify some of the -organization of your project, such as for instance the directory tree -depth, whether some directories are found in a separate tree, etc. - -The second method is the most general one. It requires an external -program, called @code{find}, which is standard on all Unix systems. All -the directories found under a given root directory will be added to the -list. - -@example -# The examples below are based on the following directory hierarchy: -# All the directories can contain any number of files -# ROOT_DIRECTORY -> a -> aa -> aaa -# -> ab -# -> ac -# -> b -> ba -> baa -# -> bb -# -> bc -# This Makefile creates a variable called DIRS, that can be reused any time -# you need this list (see the other examples in this section) - -# The root of your project's directory hierarchy -ROOT_DIRECTORY=. - -#### -# First method: specify explicitly the list of directories -# This allows you to specify any subset of all the directories you need. -#### - -DIRS := a/aa/ a/ab/ b/ba/ - -#### -# Second method: use wildcards -# Note that the argument(s) to wildcard below should end with a '/'. -# Since wildcards also return file names, we have to filter them out -# to avoid duplicate directory names. -# We thus use make's `@w{`}dir`@w{`} and `@w{`}sort`@w{`} functions. -# It sets DIRs to the following value (note that the directories aaa and baa -# are not given, unless you change the arguments to wildcard). -# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ -#### - -DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/ - $@{ROOT_DIRECTORY@}/*/*/@}@}@} - -#### -# Third method: use an external program -# This command is much faster if run on local disks, avoiding NFS slowdowns. -# This is the most complete command: it sets DIRs to the following value: -# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc -#### - -DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@} -@end example - -@node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility -@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{130}@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{131} -@subsection Generating the Command Line Switches - - -Once you have created the list of directories as explained in the -previous section (@ref{12e,,Automatically Creating a List of Directories}), -you can easily generate the command line arguments to pass to gnatmake. - -For the sake of completeness, this example assumes that the source path -is not the same as the object path, and that you have two separate lists -of directories. - -@example -# see "Automatically creating a list of directories" to create -# these variables -SOURCE_DIRS= -OBJECT_DIRS= - -GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@} -GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@} - -all: - gnatmake $@{GNATMAKE_SWITCHES@} main_unit -@end example - -@node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility -@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{133} -@subsection Overcoming Command Line Length Limits - - -One problem that might be encountered on big projects is that many -operating systems limit the length of the command line. It is thus hard to give -gnatmake the list of source and object directories. - -This example shows how you can set up environment variables, which will -make @code{gnatmake} behave exactly as if the directories had been -specified on the command line, but have a much higher length limit (or -even none on most systems). - -It assumes that you have created a list of directories in your Makefile, -using one of the methods presented in -@ref{12e,,Automatically Creating a List of Directories}. -For the sake of completeness, we assume that the object -path (where the ALI files are found) is different from the sources patch. - -Note a small trick in the Makefile below: for efficiency reasons, we -create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are -expanded immediately by @code{make}. This way we overcome the standard -make behavior which is to expand the variables only when they are -actually used. - -On Windows, if you are using the standard Windows command shell, you must -replace colons with semicolons in the assignments to these variables. - -@example -# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH. -# This is the same thing as putting the -I arguments on the command line. -# (the equivalent of using -aI on the command line would be to define -# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH). -# You can of course have different values for these variables. -# -# Note also that we need to keep the previous values of these variables, since -# they might have been set before running 'make' to specify where the GNAT -# library is installed. - -# see "Automatically creating a list of directories" to create these -# variables -SOURCE_DIRS= -OBJECT_DIRS= - -empty:= -space:=$@{empty@} $@{empty@} -SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@} -OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@} -ADA_INCLUDE_PATH += $@{SOURCE_LIST@} -ADA_OBJECTS_PATH += $@{OBJECT_LIST@} -export ADA_INCLUDE_PATH -export ADA_OBJECTS_PATH - -all: - gnatmake main_unit -@end example - -@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top -@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{134}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{135} -@chapter GNAT Utility Programs - - -This chapter describes a number of utility programs: - - - -@itemize * - -@item -@ref{136,,The File Cleanup Utility gnatclean} - -@item -@ref{137,,The GNAT Library Browser gnatls} -@end itemize - -Other GNAT utilities are described elsewhere in this manual: - - -@itemize * - -@item -@ref{42,,Handling Arbitrary File Naming Conventions with gnatname} - -@item -@ref{4c,,File Name Krunching with gnatkr} - -@item -@ref{1d,,Renaming Files with gnatchop} - -@item -@ref{8f,,Preprocessing with gnatprep} -@end itemize - -@menu -* The File Cleanup Utility gnatclean:: -* The GNAT Library Browser gnatls:: - -@end menu - -@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs -@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} - - -@geindex File cleanup tool - -@geindex gnatclean - -@code{gnatclean} is a tool that allows the deletion of files produced by the -compiler, binder and linker, including ALI files, object files, tree files, -expanded source files, library files, interface copy source files, binder -generated files and executable files. - -@menu -* Running gnatclean:: -* Switches for gnatclean:: - -@end menu - -@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean -@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{13a} -@subsection Running @code{gnatclean} - - -The @code{gnatclean} command has the form: - -@quotation - -@example -$ gnatclean switches names -@end example -@end quotation - -where @code{names} is a list of source file names. Suffixes @code{.ads} and -@code{adb} may be omitted. If a project file is specified using switch -@code{-P}, then @code{names} may be completely omitted. - -In normal mode, @code{gnatclean} delete the files produced by the compiler and, -if switch @code{-c} is not specified, by the binder and -the linker. In informative-only mode, specified by switch -@code{-n}, the list of files that would have been deleted in -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{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c} -@subsection Switches for @code{gnatclean} - - -@code{gnatclean} recognizes the following switches: - -@geindex --version (gnatclean) - - -@table @asis - -@item @code{--version} - -Display copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatclean) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. - -@item @code{--subdirs=`subdir'} - -Actual object directory of each project file is the subdirectory subdir of the -object directory specified or defaulted in the project file. - -@item @code{--unchecked-shared-lib-imports} - -By default, shared library projects are not allowed to import static library -projects. When this switch is used on the command line, this restriction is -relaxed. -@end table - -@geindex -c (gnatclean) - - -@table @asis - -@item @code{-c} - -Only attempt to delete the files produced by the compiler, not those produced -by the binder or the linker. The files that are not to be deleted are library -files, interface copy files, binder generated files and executable files. -@end table - -@geindex -D (gnatclean) - - -@table @asis - -@item @code{-D `dir'} - -Indicate that ALI and object files should normally be found in directory @code{dir}. -@end table - -@geindex -F (gnatclean) - - -@table @asis - -@item @code{-F} - -When using project files, if some errors or warnings are detected during -parsing and verbose mode is not in effect (no use of switch --v), then error lines start with the full path name of the project -file, rather than its simple file name. -@end table - -@geindex -h (gnatclean) - - -@table @asis - -@item @code{-h} - -Output a message explaining the usage of @code{gnatclean}. -@end table - -@geindex -n (gnatclean) - - -@table @asis - -@item @code{-n} - -Informative-only mode. Do not delete any files. Output the list of the files -that would have been deleted if this switch was not specified. -@end table - -@geindex -P (gnatclean) - - -@table @asis - -@item @code{-P`project'} - -Use project file @code{project}. Only one such switch can be used. -When cleaning a project file, the files produced by the compilation of the -immediate sources or inherited sources of the project files are to be -deleted. This is not depending on the presence or not of executable names -on the command line. -@end table - -@geindex -q (gnatclean) - - -@table @asis - -@item @code{-q} - -Quiet output. If there are no errors, do not output anything, except in -verbose mode (switch -v) or in informative-only mode -(switch -n). -@end table - -@geindex -r (gnatclean) - - -@table @asis - -@item @code{-r} - -When a project file is specified (using switch -P), -clean all imported and extended project files, recursively. If this switch -is not specified, only the files related to the main project file are to be -deleted. This switch has no effect if no project file is specified. -@end table - -@geindex -v (gnatclean) - - -@table @asis - -@item @code{-v} - -Verbose mode. -@end table - -@geindex -vP (gnatclean) - - -@table @asis - -@item @code{-vP`x'} - -Indicates the verbosity of the parsing of GNAT project files. -@ref{cf,,Switches Related to Project Files}. -@end table - -@geindex -X (gnatclean) - - -@table @asis - -@item @code{-X`name'=`value'} - -Indicates that external variable @code{name} has the value @code{value}. -The Project Manager will use this value for occurrences of -@code{external(name)} when parsing the project file. -See @ref{cf,,Switches Related to Project Files}. -@end table - -@geindex -aO (gnatclean) - - -@table @asis - -@item @code{-aO`dir'} - -When searching for ALI and object files, look in directory @code{dir}. -@end table - -@geindex -I (gnatclean) - - -@table @asis - -@item @code{-I`dir'} - -Equivalent to @code{-aO`dir'}. -@end table - -@geindex -I- (gnatclean) - -@geindex Source files -@geindex suppressing search - - -@table @asis - -@item @code{-I-} - -Do not look for ALI or object files in the directory -where @code{gnatclean} was invoked. -@end table - -@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs -@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d}@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137} -@section The GNAT Library Browser @code{gnatls} - - -@geindex Library browser - -@geindex gnatls - -@code{gnatls} is a tool that outputs information about compiled -units. It gives the relationship between objects, unit names and source -files. It can also be used to check the source dependencies of a unit -as well as various characteristics. - -@menu -* Running gnatls:: -* Switches for gnatls:: -* Example of gnatls Usage:: - -@end menu - -@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls -@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f} -@subsection Running @code{gnatls} - - -The @code{gnatls} command has the form - -@quotation - -@example -$ gnatls switches object_or_ali_file -@end example -@end quotation - -The main argument is the list of object or @code{ali} files -(see @ref{28,,The Ada Library Information Files}) -for which information is requested. - -In normal mode, without additional option, @code{gnatls} produces a -four-column listing. Each line represents information for a specific -object. The first column gives the full path of the object, the second -column gives the name of the principal unit in this object, the third -column gives the status of the source and the fourth column gives the -full path of the source representing this unit. -Here is a simple example of use: - -@quotation - -@example -$ gnatls *.o -./demo1.o demo1 DIF demo1.adb -./demo2.o demo2 OK demo2.adb -./hello.o h1 OK hello.adb -./instr-child.o instr.child MOK instr-child.adb -./instr.o instr OK instr.adb -./tef.o tef DIF tef.adb -./text_io_example.o text_io_example OK text_io_example.adb -./tgef.o tgef DIF tgef.adb -@end example -@end quotation - -The first line can be interpreted as follows: the main unit which is -contained in -object file @code{demo1.o} is demo1, whose main source is in -@code{demo1.adb}. Furthermore, the version of the source used for the -compilation of demo1 has been modified (DIF). Each source file has a status -qualifier which can be: - - -@table @asis - -@item `OK (unchanged)' - -The version of the source file used for the compilation of the -specified unit corresponds exactly to the actual source file. - -@item `MOK (slightly modified)' - -The version of the source file used for the compilation of the -specified unit differs from the actual source file but not enough to -require recompilation. If you use gnatmake with the option -@code{-m} (minimal recompilation), a file marked -MOK will not be recompiled. - -@item `DIF (modified)' - -No version of the source found on the path corresponds to the source -used to build this object. - -@item `??? (file not found)' - -No source file was found for this unit. - -@item `HID (hidden, unchanged version not first on PATH)' - -The version of the source that corresponds exactly to the source used -for compilation has been found on the path but it is hidden by another -version of the same source that has been modified. -@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{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141} -@subsection Switches for @code{gnatls} - - -@code{gnatls} recognizes the following switches: - -@geindex --version (gnatls) - - -@table @asis - -@item @code{--version} - -Display copyright and version, then exit disregarding all other options. -@end table - -@geindex --help (gnatls) - - -@table @asis - -@item @code{--help} - -If @code{--version} was not used, display usage, then exit disregarding -all other options. -@end table - -@geindex -a (gnatls) - - -@table @asis - -@item @code{-a} - -Consider all units, including those of the predefined Ada library. -Especially useful with @code{-d}. -@end table - -@geindex -d (gnatls) - - -@table @asis - -@item @code{-d} - -List sources from which specified units depend on. -@end table - -@geindex -h (gnatls) - - -@table @asis - -@item @code{-h} - -Output the list of options. -@end table - -@geindex -o (gnatls) - - -@table @asis - -@item @code{-o} - -Only output information about object files. -@end table - -@geindex -s (gnatls) - - -@table @asis - -@item @code{-s} - -Only output information about source files. -@end table - -@geindex -u (gnatls) - - -@table @asis - -@item @code{-u} - -Only output information about compilation units. -@end table - -@geindex -files (gnatls) - - -@table @asis - -@item @code{-files=`file'} - -Take as arguments the files listed in text file @code{file}. -Text file @code{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. -@end table - -@geindex -aO (gnatls) - -@geindex -aI (gnatls) - -@geindex -I (gnatls) - -@geindex -I- (gnatls) - - -@table @asis - -@item @code{-aO`dir'}, @code{-aI`dir'}, @code{-I`dir'}, @code{-I-}, @code{-nostdinc} - -Source path manipulation. Same meaning as the equivalent @code{gnatmake} -flags (@ref{ce,,Switches for gnatmake}). -@end table - -@geindex -aP (gnatls) - - -@table @asis - -@item @code{-aP`dir'} - -Add @code{dir} at the beginning of the project search dir. -@end table - -@geindex --RTS (gnatls) - - -@table @asis - -@item @code{--RTS=`rts-path'} - -Specifies the default location of the runtime library. Same meaning as the -equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}). -@end table - -@geindex -v (gnatls) - - -@table @asis - -@item @code{-v} - -Verbose mode. Output the complete source, object and project paths. Do not use -the default column layout but instead use long format giving as much as -information possible on each requested units, including special -characteristics such as: - - -@itemize * - -@item -`Preelaborable': The unit is preelaborable in the Ada sense. - -@item -`No_Elab_Code': No elaboration code has been produced by the compiler for this unit. - -@item -`Pure': The unit is pure in the Ada sense. - -@item -`Elaborate_Body': The unit contains a pragma Elaborate_Body. - -@item -`Remote_Types': The unit contains a pragma Remote_Types. - -@item -`Shared_Passive': The unit contains a pragma Shared_Passive. - -@item -`Predefined': This unit is part of the predefined environment and cannot be modified -by the user. - -@item -`Remote_Call_Interface': The unit contains a pragma Remote_Call_Interface. -@end itemize -@end table - -@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls -@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{143} -@subsection Example of @code{gnatls} Usage - - -Example of using the verbose switch. Note how the source and -object paths are affected by the -I switch. - -@quotation - -@example -$ gnatls -v -I.. demo1.o - -GNATLS 5.03w (20041123-34) -Copyright 1997-2004 Free Software Foundation, Inc. - -Source Search Path: - - ../ - /home/comar/local/adainclude/ - -Object Search Path: - - ../ - /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ - -Project Search Path: - - /home/comar/local/lib/gnat/ - -./demo1.o - Unit => - Name => demo1 - Kind => subprogram body - Flags => No_Elab_Code - Source => demo1.adb modified -@end example -@end quotation - -The following is an example of use of the dependency list. -Note the use of the -s switch -which gives a straight list of source files. This can be useful for -building specialized scripts. - -@quotation - -@example -$ gnatls -d demo2.o -./demo2.o demo2 OK demo2.adb - OK gen_list.ads - OK gen_list.adb - OK instr.ads - OK instr-child.ads - -$ gnatls -d -s -a demo1.o -demo1.adb -/home/comar/local/adainclude/ada.ads -/home/comar/local/adainclude/a-finali.ads -/home/comar/local/adainclude/a-filico.ads -/home/comar/local/adainclude/a-stream.ads -/home/comar/local/adainclude/a-tags.ads -gen_list.ads -gen_list.adb -/home/comar/local/adainclude/gnat.ads -/home/comar/local/adainclude/g-io.ads -instr.ads -/home/comar/local/adainclude/system.ads -/home/comar/local/adainclude/s-exctab.ads -/home/comar/local/adainclude/s-finimp.ads -/home/comar/local/adainclude/s-finroo.ads -/home/comar/local/adainclude/s-secsta.ads -/home/comar/local/adainclude/s-stalib.ads -/home/comar/local/adainclude/s-stoele.ads -/home/comar/local/adainclude/s-stratt.ads -/home/comar/local/adainclude/s-tasoli.ads -/home/comar/local/adainclude/s-unstyp.ads -/home/comar/local/adainclude/unchconv.ads -@end example -@end quotation - - - - - - -@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 doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145} -@chapter GNAT and Program Execution - - -This chapter covers several topics: - - -@itemize * - -@item -@ref{146,,Running and Debugging Ada Programs} - -@item -@ref{147,,Profiling} - -@item -@ref{148,,Improving Performance} - -@item -@ref{149,,Overflow Check Handling in GNAT} - -@item -@ref{14a,,Performing Dimensionality Analysis in GNAT} - -@item -@ref{14b,,Stack Related Facilities} - -@item -@ref{14c,,Memory Management Issues} -@end itemize - -@menu -* Running and Debugging Ada Programs:: -* Profiling:: -* Improving Performance:: -* Overflow Check Handling in GNAT:: -* Performing Dimensionality Analysis in GNAT:: -* Stack Related Facilities:: -* Memory Management Issues:: - -@end menu - -@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution -@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 - - -@geindex Debugging - -This section discusses how to debug Ada programs. - -An incorrect Ada program may be handled in three ways by the GNAT compiler: - - -@itemize * - -@item -The illegality may be a violation of the static semantics of Ada. In -that case GNAT diagnoses the constructs in the program that are illegal. -It is then a straightforward matter for the user to modify those parts of -the program. - -@item -The illegality may be a violation of the dynamic semantics of Ada. In -that case the program compiles and executes, but may generate incorrect -results, or may terminate abnormally with some exception. - -@item -When presented with a program that contains convoluted errors, GNAT -itself may terminate abnormally without providing full diagnostics on -the incorrect user program. -@end itemize - -@geindex Debugger - -@geindex gdb - -@menu -* The GNAT Debugger GDB:: -* Running GDB:: -* Introduction to GDB Commands:: -* Using Ada Expressions:: -* Calling User-Defined Subprograms:: -* Using the next Command in a Function:: -* Stopping When Ada Exceptions Are Raised:: -* Ada Tasks:: -* Debugging Generic Units:: -* Remote Debugging with gdbserver:: -* GNAT Abnormal Termination or Failure to Terminate:: -* Naming Conventions for GNAT Source Files:: -* Getting Internal Debugging Information:: -* Stack Traceback:: -* Pretty-Printers for the GNAT runtime:: - -@end menu - -@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs -@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14f} -@subsection The GNAT Debugger GDB - - -@code{GDB} is a general purpose, platform-independent debugger that -can be used to debug mixed-language programs compiled with @code{gcc}, -and in particular is capable of debugging Ada programs compiled with -GNAT. The latest versions of @code{GDB} are Ada-aware and can handle -complex Ada data structures. - -See @cite{Debugging with GDB}, -for full details on the usage of @code{GDB}, including a section on -its usage on programs. This manual should be consulted for full -details. The section that follows is a brief introduction to the -philosophy and use of @code{GDB}. - -When GNAT programs are compiled, the compiler optionally writes debugging -information into the generated object file, including information on -line numbers, and on declared types and variables. This information is -separate from the generated code. It makes the object files considerably -larger, but it does not add to the size of the actual executable that -will be loaded into memory, and has no impact on run-time performance. The -generation of debug information is triggered by the use of the -@code{-g} switch in the @code{gcc} or @code{gnatmake} command -used to carry out the compilations. It is important to emphasize that -the use of these options does not change the generated code. - -The debugging information is written in standard system formats that -are used by many tools, including debuggers and profilers. The format -of the information is typically designed to describe C types and -semantics, but GNAT implements a translation scheme which allows full -details about Ada types and variables to be encoded into these -standard C formats. Details of this encoding scheme may be found in -the file exp_dbug.ads in the GNAT source distribution. However, the -details of this encoding are, in general, of no interest to a user, -since @code{GDB} automatically performs the necessary decoding. - -When a program is bound and linked, the debugging information is -collected from the object files, and stored in the executable image of -the program. Again, this process significantly increases the size of -the generated executable file, but it does not increase the size of -the executable program itself. Furthermore, if this program is run in -the normal manner, it runs exactly as if the debug information were -not present, and takes no more actual memory. - -However, if the program is run under control of @code{GDB}, the -debugger is activated. The image of the program is loaded, at which -point it is ready to run. If a run command is given, then the program -will run exactly as it would have if @code{GDB} were not present. This -is a crucial part of the @code{GDB} design philosophy. @code{GDB} is -entirely non-intrusive until a breakpoint is encountered. If no -breakpoint is ever hit, the program will run exactly as it would if no -debugger were present. When a breakpoint is hit, @code{GDB} accesses -the debugging information and can respond to user commands to inspect -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{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151} -@subsection Running GDB - - -This section describes how to initiate the debugger. - -The debugger can be launched from a @code{GNAT Studio} menu or -directly from the command line. The description below covers the latter use. -All the commands shown can be used in the @code{GNAT Studio} debug console window, -but there are usually more GUI-based ways to achieve the same effect. - -The command to run @code{GDB} is - -@quotation - -@example -$ gdb program -@end example -@end quotation - -where @code{program} is the name of the executable file. This -activates the debugger and results in a prompt for debugger commands. -The simplest command is simply @code{run}, which causes the program to run -exactly as if the debugger were not present. The following section -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 id5}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{153} -@subsection Introduction to GDB Commands - - -@code{GDB} contains a large repertoire of commands. -See @cite{Debugging with GDB} for extensive documentation on the use -of these commands, together with examples of their use. Furthermore, -the command `help' invoked from within GDB activates a simple help -facility which summarizes the available commands and their options. -In this section we summarize a few of the most commonly -used commands to give an idea of what @code{GDB} is about. You should create -a simple program with debugging information and experiment with the use of -these @code{GDB} commands on the program as you read through the -following section. - - -@itemize * - -@item - -@table @asis - -@item @code{set args @var{arguments}} - -The `arguments' list above is a list of arguments to be passed to -the program on a subsequent run command, just as though the arguments -had been entered on a normal invocation of the program. The @code{set args} -command is not needed if the program does not require arguments. -@end table - -@item - -@table @asis - -@item @code{run} - -The @code{run} command causes execution of the program to start from -the beginning. If the program is already running, that is to say if -you are currently positioned at a breakpoint, then a prompt will ask -for confirmation that you want to abandon the current execution and -restart. -@end table - -@item - -@table @asis - -@item @code{breakpoint @var{location}} - -The breakpoint command sets a breakpoint, that is to say a point at which -execution will halt and @code{GDB} will await further -commands. `location' is -either a line number within a file, given in the format @code{file:linenumber}, -or it is the name of a subprogram. If you request that a breakpoint be set on -a subprogram that is overloaded, a prompt will ask you to specify on which of -those subprograms you want to breakpoint. You can also -specify that all of them should be breakpointed. If the program is run -and execution encounters the breakpoint, then the program -stops and @code{GDB} signals that the breakpoint was encountered by -printing the line of code before which the program is halted. -@end table - -@item - -@table @asis - -@item @code{catch exception @var{name}} - -This command causes the program execution to stop whenever exception -@code{name} is raised. If @code{name} is omitted, then the execution is -suspended when any exception is raised. -@end table - -@item - -@table @asis - -@item @code{print @var{expression}} - -This will print the value of the given expression. Most simple -Ada expression formats are properly handled by @code{GDB}, so the expression -can contain function calls, variables, operators, and attribute references. -@end table - -@item - -@table @asis - -@item @code{continue} - -Continues execution following a breakpoint, until the next breakpoint or the -termination of the program. -@end table - -@item - -@table @asis - -@item @code{step} - -Executes a single line after a breakpoint. If the next statement -is a subprogram call, execution continues into (the first statement of) -the called subprogram. -@end table - -@item - -@table @asis - -@item @code{next} - -Executes a single line. If this line is a subprogram call, executes and -returns from the call. -@end table - -@item - -@table @asis - -@item @code{list} - -Lists a few lines around the current source location. In practice, it -is usually more convenient to have a separate edit window open with the -relevant source file displayed. Successive applications of this command -print subsequent lines. The command can be given an argument which is a -line number, in which case it displays a few lines around the specified one. -@end table - -@item - -@table @asis - -@item @code{backtrace} - -Displays a backtrace of the call chain. This command is typically -used after a breakpoint has occurred, to examine the sequence of calls that -leads to the current breakpoint. The display includes one line for each -activation record (frame) corresponding to an active subprogram. -@end table - -@item - -@table @asis - -@item @code{up} - -At a breakpoint, @code{GDB} can display the values of variables local -to the current frame. The command @code{up} can be used to -examine the contents of other active frames, by moving the focus up -the stack, that is to say from callee to caller, one frame at a time. -@end table - -@item - -@table @asis - -@item @code{down} - -Moves the focus of @code{GDB} down from the frame currently being -examined to the frame of its callee (the reverse of the previous command), -@end table - -@item - -@table @asis - -@item @code{frame @var{n}} - -Inspect the frame with the given number. The value 0 denotes the frame -of the current breakpoint, that is to say the top of the call stack. -@end table - -@item - -@table @asis - -@item @code{kill} - -Kills the child process in which the program is running under GDB. -This may be useful for several purposes: - - -@itemize * - -@item -It allows you to recompile and relink your program, since on many systems -you cannot regenerate an executable file while it is running in a process. - -@item -You can run your program outside the debugger, on systems that do not -permit executing a program outside GDB while breakpoints are set -within GDB. - -@item -It allows you to debug a core dump rather than a running process. -@end itemize -@end table -@end itemize - -The above list is a very short introduction to the commands that -@code{GDB} provides. Important additional capabilities, including conditional -breakpoints, the ability to execute command sequences on a breakpoint, -the ability to debug at the machine instruction level and many other -features are described in detail in @cite{Debugging with GDB}. -Note that most commands can be abbreviated -(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{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155} -@subsection Using Ada Expressions - - -@geindex Ada expressions (in gdb) - -@code{GDB} supports a fairly large subset of Ada expression syntax, with some -extensions. The philosophy behind the design of this subset is - -@quotation - - -@itemize * - -@item -That @code{GDB} should provide basic literals and access to operations for -arithmetic, dereferencing, field selection, indexing, and subprogram calls, -leaving more sophisticated computations to subprograms written into the -program (which therefore may be called from @code{GDB}). - -@item -That type safety and strict adherence to Ada language restrictions -are not particularly relevant in a debugging context. - -@item -That brevity is important to the @code{GDB} user. -@end itemize -@end quotation - -Thus, for brevity, the debugger acts as if there were -implicit @code{with} and @code{use} clauses in effect for all user-written -packages, thus making it unnecessary to fully qualify most names with -their packages, regardless of context. Where this causes ambiguity, -@code{GDB} asks the user’s intent. - -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 calling-user-defined-subprograms}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{157} -@subsection Calling User-Defined Subprograms - - -An important capability of @code{GDB} is the ability to call user-defined -subprograms while debugging. This is achieved simply by entering -a subprogram call statement in the form: - -@quotation - -@example -call subprogram-name (parameters) -@end example -@end quotation - -The keyword @code{call} can be omitted in the normal case where the -@code{subprogram-name} does not coincide with any of the predefined -@code{GDB} commands. - -The effect is to invoke the given subprogram, passing it the -list of parameters that is supplied. The parameters can be expressions and -can include variables from the program being debugged. The -subprogram must be defined -at the library level within your program, and @code{GDB} will call the -subprogram within the environment of your program execution (which -means that the subprogram is free to access or even modify variables -within your program). - -The most important use of this facility is in allowing the inclusion of -debugging routines that are tailored to particular data structures -in your program. Such debugging routines can be written to provide a suitably -high-level description of an abstract type, rather than a low-level dump -of its physical layout. After all, the standard -@code{GDB print} command only knows the physical layout of your -types, not their abstract meaning. Debugging routines can provide information -at the desired semantic level and are thus enormously useful. - -For example, when debugging GNAT itself, it is crucial to have access to -the contents of the tree nodes used to represent the program internally. -But tree nodes are represented simply by an integer value (which in turn -is an index into a table of nodes). -Using the @code{print} command on a tree node would simply print this integer -value, which is not very useful. But the PN routine (defined in file -treepr.adb in the GNAT sources) takes a tree node as input, and displays -a useful high level representation of the tree node, which includes the -syntactic category of the node, its position in the source, the integers -that denote descendant nodes and parent node, as well as varied -semantic information. To study this example in more detail, you might want to -look at the body of the PN procedure in the stated file. - -Another useful application of this capability is to deal with situations of -complex data which are not handled suitably by GDB. For example, if you specify -Convention Fortran for a multi-dimensional array, GDB does not know that -the ordering of array elements has been switched and will not properly -address the array elements. In such a case, instead of trying to print the -elements directly from GDB, you can write a callable procedure that prints -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 id8}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{159} -@subsection Using the `next' Command in a Function - - -When you use the @code{next} command in a function, the current source -location will advance to the next statement as usual. A special case -arises in the case of a @code{return} statement. - -Part of the code for a return statement is the ‘epilogue’ of the function. -This is the code that returns to the caller. There is only one copy of -this epilogue code, and it is typically associated with the last return -statement in the function if there is more than one return. In some -implementations, this epilogue is associated with the first statement -of the function. - -The result is that if you use the @code{next} command from a return -statement that is not the last return statement of the function you -may see a strange apparent jump to the last return statement or to -the start of the function. You should simply ignore this odd jump. -The value returned is always that from the first return statement -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 id9}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15b} -@subsection Stopping When Ada Exceptions Are Raised - - -@geindex Exceptions (in gdb) - -You can set catchpoints that stop the program execution when your program -raises selected exceptions. - - -@itemize * - -@item - -@table @asis - -@item @code{catch exception} - -Set a catchpoint that stops execution whenever (any task in the) program -raises any exception. -@end table - -@item - -@table @asis - -@item @code{catch exception @var{name}} - -Set a catchpoint that stops execution whenever (any task in the) program -raises the exception `name'. -@end table - -@item - -@table @asis - -@item @code{catch exception unhandled} - -Set a catchpoint that stops executing whenever (any task in the) program -raises an exception for which there is no handler. -@end table - -@item - -@table @asis - -@item @code{info exceptions}, @code{info exceptions @var{regexp}} - -The @code{info exceptions} command permits the user to examine all defined -exceptions within Ada programs. With a regular expression, `regexp', as -argument, prints out only those exceptions whose name matches `regexp'. -@end table -@end itemize - -@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{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d} -@subsection Ada Tasks - - -@code{GDB} allows the following task-related commands: - - -@itemize * - -@item - -@table @asis - -@item @code{info tasks} - -This command shows a list of current Ada tasks, as in the following example: - -@example -(gdb) info tasks - ID TID P-ID Thread Pri State Name - 1 8088000 0 807e000 15 Child Activation Wait main_task - 2 80a4000 1 80ae000 15 Accept/Select Wait b - 3 809a800 1 80a4800 15 Child Activation Wait a -* 4 80ae800 3 80b8000 15 Running c -@end example - -In this listing, the asterisk before the first task indicates it to be the -currently running task. The first column lists the task ID that is used -to refer to tasks in the following commands. -@end table -@end itemize - -@geindex Breakpoints and tasks - - -@itemize * - -@item -@code{break} `linespec' @code{task} `taskid', @code{break} `linespec' @code{task} `taskid' @code{if} … - -@quotation - -These commands are like the @code{break ... thread ...}. -`linespec' specifies source lines. - -Use the qualifier @code{task @var{taskid}} with a breakpoint command -to specify that you only want @code{GDB} to stop the program when a -particular Ada task reaches this breakpoint. `taskid' is one of the -numeric task identifiers assigned by @code{GDB}, shown in the first -column of the @code{info tasks} display. - -If you do not specify @code{task @var{taskid}} when you set a -breakpoint, the breakpoint applies to `all' tasks of your -program. - -You can use the @code{task} qualifier on conditional breakpoints as -well; in this case, place @code{task @var{taskid}} before the -breakpoint condition (before the @code{if}). -@end quotation -@end itemize - -@geindex Task switching (in gdb) - - -@itemize * - -@item -@code{task @var{taskno}} - -@quotation - -This command allows switching to the task referred by `taskno'. In -particular, this allows browsing of the backtrace of the specified -task. It is advisable to switch back to the original task before -continuing execution otherwise the scheduling of the program may be -perturbed. -@end quotation -@end itemize - -For more detailed information on the tasking support, -see @cite{Debugging with GDB}. - -@geindex Debugging Generic Units - -@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{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f} -@subsection Debugging Generic Units - - -GNAT always uses code expansion for generic instantiation. This means that -each time an instantiation occurs, a complete copy of the original code is -made, with appropriate substitutions of formals by actuals. - -It is not possible to refer to the original generic entities in -@code{GDB}, but it is always possible to debug a particular instance of -a generic, by using the appropriate expanded names. For example, if we have - -@quotation - -@example -procedure g is - - generic package k is - procedure kp (v1 : in out integer); - end k; - - package body k is - procedure kp (v1 : in out integer) is - begin - v1 := v1 + 1; - end kp; - end k; - - package k1 is new k; - package k2 is new k; - - var : integer := 1; - -begin - k1.kp (var); - k2.kp (var); - k1.kp (var); - k2.kp (var); -end; -@end example -@end quotation - -Then to break on a call to procedure kp in the k2 instance, simply -use the command: - -@quotation - -@example -(gdb) break g.k2.kp -@end example -@end quotation - -When the breakpoint occurs, you can step through the code of the -instance in the normal manner and examine the values of local variables, as for -other 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 id12}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{161} -@subsection Remote Debugging with gdbserver - - -On platforms where gdbserver is supported, it is possible to use this tool -to debug your application remotely. This can be useful in situations -where the program needs to be run on a target host that is different -from the host used for development, particularly when the target has -a limited amount of resources (either CPU and/or memory). - -To do so, start your program using gdbserver on the target machine. -gdbserver then automatically suspends the execution of your program -at its entry point, waiting for a debugger to connect to it. The -following commands starts an application and tells gdbserver to -wait for a connection with the debugger on localhost port 4444. - -@quotation - -@example -$ gdbserver localhost:4444 program -Process program created; pid = 5685 -Listening on port 4444 -@end example -@end quotation - -Once gdbserver has started listening, we can tell the debugger to establish -a connection with this gdbserver, and then start the same debugging session -as if the program was being debugged on the same host, directly under -the control of GDB. - -@quotation - -@example -$ gdb program -(gdb) target remote targethost:4444 -Remote debugging using targethost:4444 -0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. -(gdb) b foo.adb:3 -Breakpoint 1 at 0x401f0c: file foo.adb, line 3. -(gdb) continue -Continuing. - -Breakpoint 1, foo () at foo.adb:4 -4 end foo; -@end example -@end quotation - -It is also possible to use gdbserver to attach to an already running -program, in which case the execution of that program is simply suspended -until the connection between the debugger and gdbserver is established. - -For more information on how to use gdbserver, see the `Using the gdbserver Program' -section in @cite{Debugging with GDB}. -GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux. - -@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{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163} -@subsection GNAT Abnormal Termination or Failure to Terminate - - -When presented with programs that contain serious errors in syntax -or semantics, -GNAT may on rare occasions experience problems in operation, such -as aborting with a -segmentation fault or illegal memory access, raising an internal -exception, terminating abnormally, or failing to terminate at all. -In such cases, you can activate -various features of GNAT that can help you pinpoint the construct in your -program that is the likely source of the problem. - -The following strategies are presented in increasing order of -difficulty, corresponding to your experience in using GNAT and your -familiarity with compiler internals. - - -@itemize * - -@item -Run @code{gcc} with the @code{-gnatf}. This first -switch causes all errors on a given line to be reported. In its absence, -only the first error on a line is displayed. - -The @code{-gnatdO} switch causes errors to be displayed as soon as they -are encountered, rather than after compilation is terminated. If GNAT -terminates prematurely or goes into an infinite loop, the last error -message displayed may help to pinpoint the culprit. - -@item -Run @code{gcc} with the @code{-v} (verbose) switch. In this -mode, @code{gcc} produces ongoing information about the progress of the -compilation and provides the name of each procedure as code is -generated. This switch allows you to find which Ada procedure was being -compiled when it encountered a code generation problem. -@end itemize - -@geindex -gnatdc switch - - -@itemize * - -@item -Run @code{gcc} with the @code{-gnatdc} switch. This is a GNAT specific -switch that does for the front-end what @code{-v} does -for the back end. The system prints the name of each unit, -either a compilation unit or nested unit, as it is being analyzed. - -@item -Finally, you can start -@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{14f,,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 -which the execution stopped, and @code{input_file name} indicates the name of -the source file. -@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 id14}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{165} -@subsection Naming Conventions for GNAT Source Files - - -In order to examine the workings of the GNAT system, the following -brief description of its organization may be helpful: - - -@itemize * - -@item -Files with prefix @code{sc} contain the lexical scanner. - -@item -All files prefixed with @code{par} are components of the parser. The -numbers correspond to chapters of the Ada Reference Manual. For example, -parsing of select statements can be found in @code{par-ch9.adb}. - -@item -All files prefixed with @code{sem} perform semantic analysis. The -numbers correspond to chapters of the Ada standard. For example, all -issues involving context clauses can be found in @code{sem_ch10.adb}. In -addition, some features of the language require sufficient special processing -to justify their own semantic files: sem_aggr for aggregates, sem_disp for -dynamic dispatching, etc. - -@item -All files prefixed with @code{exp} perform normalization and -expansion of the intermediate representation (abstract syntax tree, or AST). -these files use the same numbering scheme as the parser and semantics files. -For example, the construction of record initialization procedures is done in -@code{exp_ch3.adb}. - -@item -The files prefixed with @code{bind} implement the binder, which -verifies the consistency of the compilation, determines an order of -elaboration, and generates the bind file. - -@item -The files @code{atree.ads} and @code{atree.adb} detail the low-level -data structures used by the front-end. - -@item -The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of -the abstract syntax tree as produced by the parser. - -@item -The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of -all entities, computed during semantic analysis. - -@item -Library management issues are dealt with in files with prefix -@code{lib}. - -@geindex Annex A (in Ada Reference Manual) - -@item -Ada files with the prefix @code{a-} are children of @code{Ada}, as -defined in Annex A. - -@geindex Annex B (in Ada reference Manual) - -@item -Files with prefix @code{i-} are children of @code{Interfaces}, as -defined in Annex B. - -@geindex System (package in Ada Reference Manual) - -@item -Files with prefix @code{s-} are children of @code{System}. This includes -both language-defined children and GNAT run-time routines. - -@geindex GNAT (package) - -@item -Files with prefix @code{g-} are children of @code{GNAT}. These are useful -general-purpose packages, fully documented in their specs. All -the other @code{.c} files are modifications of common @code{gcc} 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 getting-internal-debugging-information}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{167} -@subsection Getting Internal Debugging Information - - -Most compilers have internal debugging switches and modes. GNAT -does also, except GNAT internal debugging switches and modes are not -secret. A summary and full description of all the compiler and binder -debug flags are in the file @code{debug.adb}. You must obtain the -sources of the compiler to see the full detailed effects of these flags. - -The switches that print the source of the program (reconstructed from -the internal tree) are of general interest for user programs, as are the -options to print -the full internal tree, and the entity table (the symbol table -information). The reconstructed source provides a readable version of the -program after the front-end has completed analysis and expansion, -and is useful when studying the performance of specific constructs. -For example, constraint checks are indicated, complex aggregates -are replaced with loops and assignments, and tasking primitives -are replaced with run-time calls. - -@geindex traceback - -@geindex stack traceback - -@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 id16}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{169} -@subsection Stack Traceback - - -Traceback is a mechanism to display the sequence of subprogram calls that -leads to a specified execution point in a program. Often (but not always) -the execution point is an instruction at which an exception has been raised. -This mechanism is also known as `stack unwinding' because it obtains -its information by scanning the run-time stack and recovering the activation -records of all active subprograms. Stack unwinding is one of the most -important tools for program debugging. - -The first entry stored in traceback corresponds to the deepest calling level, -that is to say the subprogram currently executing the instruction -from which we want to obtain the traceback. - -Note that there is no runtime performance penalty when stack traceback -is enabled, and no exception is raised during program execution. - -@geindex traceback -@geindex non-symbolic - -@menu -* Non-Symbolic Traceback:: -* Symbolic Traceback:: - -@end menu - -@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback -@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16b} -@subsubsection Non-Symbolic Traceback - - -Note: this feature is not supported on all platforms. See -@code{GNAT.Traceback} spec in @code{g-traceb.ads} -for a complete list of supported platforms. - -@subsubheading Tracebacks From an Unhandled Exception - - -A runtime non-symbolic traceback is a list of addresses of call instructions. -To enable this feature you must use the @code{-E} @code{gnatbind} option. With -this option a stack traceback is stored as part of exception information. - -You can translate this information using the @code{addr2line} tool, provided that -the program is compiled with debugging options (see @ref{db,,Compiler Switches}) -and linked at a fixed position with @code{-no-pie}. - -Here is a simple example with @code{gnatmake}: - -@quotation - -@example -procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - -begin - P2; -end STB; -@end example - -@example -$ gnatmake stb -g -bargs -E -largs -no-pie -$ stb - -Execution of stb terminated by unhandled exception -raised CONSTRAINT_ERROR : stb.adb:5 explicit raise -Load address: 0x400000 -Call stack traceback locations: -0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 -@end example -@end quotation - -As we see the traceback lists a sequence of addresses for the unhandled -exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to -guess that this exception come from procedure P1. To translate these -addresses into the source lines where the calls appear, the @code{addr2line} -tool needs to be invoked like this: - -@quotation - -@example -$ addr2line -e stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 - 0x4011f1 0x77e892a4 - -d:/stb/stb.adb:5 -d:/stb/stb.adb:10 -d:/stb/stb.adb:14 -d:/stb/b~stb.adb:197 -crtexe.c:? -crtexe.c:? -??:0 -@end example -@end quotation - -The @code{addr2line} tool has several other useful options: - -@quotation - - -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -@code{-a --addresses} - -@tab - -to show the addresses alongside the line numbers - -@item - -@code{-f --functions} - -@tab - -to get the function name corresponding to a location - -@item - -@code{-p --pretty-print} - -@tab - -to print all the information on a single line - -@item - -@code{--demangle=gnat} - -@tab - -to use the GNAT decoding mode for the function names - -@end multitable - - -@example -$ addr2line -e stb -a -f -p --demangle=gnat 0x401373 0x40138b - 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - -0x00401373: stb.p1 at d:/stb/stb.adb:5 -0x0040138B: stb.p2 at d:/stb/stb.adb:10 -0x0040139C: stb at d:/stb/stb.adb:14 -0x00401335: main at d:/stb/b~stb.adb:197 -0x004011c4: ?? at crtexe.c:? -0x004011f1: ?? at crtexe.c:? -0x77e892a4: ?? ??:0 -@end example -@end quotation - -From this traceback we can see that the exception was raised in @code{stb.adb} -at line 5, which was reached from a procedure call in @code{stb.adb} at line -10, and so on. The @code{b~std.adb} is the binder file, which contains the -call to the main program. @ref{10e,,Running gnatbind}. The remaining entries are -assorted runtime routines and the output will vary from platform to platform. - -It is also possible to use @code{GDB} with these traceback addresses to debug -the program. For example, we can break at a given code location, as reported -in the stack traceback: - -@example -$ gdb -nw stb - -(gdb) break *0x401373 -Breakpoint 1 at 0x401373: file stb.adb, line 5. -@end example - -It is important to note that the stack traceback addresses do not change when -debug information is included. This is particularly useful because it makes it -possible to release software without debug information (to minimize object -size), get a field report that includes a stack traceback whenever an internal -bug occurs, and then be able to retrieve the sequence of calls with the same -program compiled with debug information. - -However the @code{addr2line} tool does not work with Position-Independent Code -(PIC), the historical example being Windows DLLs, which nowadays encompasses -Position-Independent Executables (PIE) on recent Windows versions. - -In order to translate addresses into the source lines with Position-Independent -Executables on recent Windows versions, in other words without using the switch -@code{-no-pie} during linking, you need to use the @code{gnatsymbolize} tool -with @code{--load} instead of the @code{addr2line} tool. The main difference -is that you need to copy the Load Address output in the traceback ahead of the -sequence of addresses. And the default mode of @code{gnatsymbolize} is equivalent -to that of @code{addr2line} with the above switches, so none of them is needed: - -@example -$ gnatmake stb -g -bargs -E -$ stb - -Execution of stb terminated by unhandled exception -raised CONSTRAINT_ERROR : stb.adb:5 explicit raise -Load address: 0x400000 -Call stack traceback locations: -0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - -$ gnatsymbolize --load stb 0x400000 0x401373 0x40138b 0x40139c 0x401335 - 0x4011c4 0x4011f1 0x77e892a4 - -0x00401373 Stb.P1 at stb.adb:5 -0x0040138B Stb.P2 at stb.adb:10 -0x0040139C Stb at stb.adb:14 -0x00401335 Main at b~stb.adb:197 -0x004011c4 __tmainCRTStartup at ??? -0x004011f1 mainCRTStartup at ??? -0x77e892a4 ??? at ??? -@end example - -@subsubheading Tracebacks From Exception Occurrences - - -Non-symbolic tracebacks are obtained by using the @code{-E} binder argument. -The stack traceback is attached to the exception information string, and can -be retrieved in an exception handler within the Ada program, by means of the -Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example: - -@quotation - -@example -with Ada.Text_IO; -with Ada.Exceptions; - -procedure STB is - - use Ada; - use Ada.Exceptions; - - procedure P1 is - K : Positive := 1; - begin - K := K - 1; - exception - when E : others => - Text_IO.Put_Line (Exception_Information (E)); - end P1; - - procedure P2 is - begin - P1; - end P2; - -begin - P2; -end STB; -@end example -@end quotation - -This program will output: - -@quotation - -@example -$ stb - -raised CONSTRAINT_ERROR : stb.adb:12 range check failed -Load address: 0x400000 -Call stack traceback locations: -0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 -@end example -@end quotation - -@subsubheading Tracebacks From Anywhere in a Program - - -It is also possible to retrieve a stack traceback from anywhere in a program. -For this you need to use the @code{GNAT.Traceback} API. This package includes a -procedure called @code{Call_Chain} that computes a complete stack traceback, as -well as useful display procedures described below. It is not necessary to use -the @code{-E} @code{gnatbind} option in this case, because the stack traceback -mechanism is invoked explicitly. - -In the following example we compute a traceback at a specific location in the -program, and we display it using @code{GNAT.Debug_Utilities.Image} to convert -addresses to strings: - -@quotation - -@example -with Ada.Text_IO; -with GNAT.Traceback; -with GNAT.Debug_Utilities; - -procedure STB is - - use Ada; - use GNAT; - use GNAT.Traceback; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - - Text_IO.Put ("In STB.P1 : "); - - for K in 1 .. Len loop - Text_IO.Put (Debug_Utilities.Image (TB (K))); - Text_IO.Put (' '); - end loop; - - Text_IO.New_Line; - end P1; - - procedure P2 is - begin - P1; - end P2; - -begin - P2; -end STB; -@end example - -@example -$ gnatmake stb -g -$ stb - -In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# -16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# -@end example -@end quotation - -You can then get further information by invoking the @code{addr2line} tool or -the @code{gnatsymbolize} tool as described earlier (note that the hexadecimal -addresses need to be specified in C format, with a leading ‘0x’). - -@geindex traceback -@geindex symbolic - -@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback -@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d} -@subsubsection Symbolic Traceback - - -A symbolic traceback is a stack traceback in which procedure names are -associated with each code location. - -Note that this feature is not supported on all platforms. See -@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete -list of currently supported platforms. - -Note that the symbolic traceback requires that the program be compiled -with debug information. If it is not compiled with debug information -only the non-symbolic information will be valid. - -@subsubheading Tracebacks From Exception Occurrences - - -Here is an example: - -@quotation - -@example -with Ada.Text_IO; -with GNAT.Traceback.Symbolic; - -procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - procedure P3 is - begin - P2; - end P3; - -begin - P3; -exception - when E : others => - Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); -end STB; -@end example - -@example -$ gnatmake -g .\stb -bargs -E -$ stb - -0040149F in stb.p1 at stb.adb:8 -004014B7 in stb.p2 at stb.adb:13 -004014CF in stb.p3 at stb.adb:18 -004015DD in ada.stb at stb.adb:22 -00401461 in main at b~stb.adb:168 -004011C4 in __mingw_CRTStartup at crt1.c:200 -004011F1 in mainCRTStartup at crt1.c:222 -77E892A4 in ?? at ??:0 -@end example -@end quotation - -In the above example the @code{.\} syntax in the @code{gnatmake} command -is currently required by @code{addr2line} for files that are in -the current working directory. -Moreover, the exact sequence of linker options may vary from platform -to platform. -The above @code{-largs} section is for Windows platforms. By contrast, -under Unix there is no need for the @code{-largs} section. -Differences across platforms are due to details of linker implementation. - -@subsubheading Tracebacks From Anywhere in a Program - - -It is possible to get a symbolic stack traceback -from anywhere in a program, just as for non-symbolic tracebacks. -The first step is to obtain a non-symbolic -traceback, and then call @code{Symbolic_Traceback} to compute the symbolic -information. Here is an example: - -@quotation - -@example -with Ada.Text_IO; -with GNAT.Traceback; -with GNAT.Traceback.Symbolic; - -procedure STB is - - use Ada; - use GNAT.Traceback; - use GNAT.Traceback.Symbolic; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); - end P1; - - procedure P2 is - begin - P1; - end P2; - -begin - P2; -end STB; -@end example -@end quotation - -@subsubheading Automatic Symbolic Tracebacks - - -Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as -in @code{gprbuild -g ... -bargs -Es}). -This will cause the Exception_Information to contain a symbolic traceback, -which will also be printed if an unhandled exception terminates the -program. - -@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs -@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 - - -As discussed in @cite{Calling User-Defined Subprograms}, GDB’s -@code{print} command only knows about the physical layout of program data -structures and therefore normally displays only low-level dumps, which -are often hard to understand. - -An example of this is when trying to display the contents of an Ada -standard container, such as @code{Ada.Containers.Ordered_Maps.Map}: - -@quotation - -@example -with Ada.Containers.Ordered_Maps; - -procedure PP is - package Int_To_Nat is - new Ada.Containers.Ordered_Maps (Integer, Natural); - - Map : Int_To_Nat.Map; -begin - Map.Insert (1, 10); - Map.Insert (2, 20); - Map.Insert (3, 30); - - Map.Clear; -- BREAK HERE -end PP; -@end example -@end quotation - -When this program is built with debugging information and run under -GDB up to the @code{Map.Clear} statement, trying to print @code{Map} will -yield information that is only relevant to the developers of our standard -containers: - -@quotation - -@example -(gdb) print map -$1 = ( - tree => ( - first => 0x64e010, - last => 0x64e070, - root => 0x64e040, - length => 3, - tc => ( - busy => 0, - lock => 0 - ) - ) -) -@end example -@end quotation - -Fortunately, GDB has a feature called pretty-printers@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction}, -which allows customizing how GDB displays data structures. The GDB -shipped with GNAT embeds such pretty-printers for the most common -containers in the standard library. To enable them, either run the -following command manually under GDB or add it to your @code{.gdbinit} file: - -@quotation - -@example -python import gnatdbg; gnatdbg.setup() -@end example -@end quotation - -Once this is done, GDB’s @code{print} command will automatically use -these pretty-printers when appropriate. Using the previous example: - -@quotation - -@example -(gdb) print map -$1 = pp.int_to_nat.map of length 3 = @{ - [1] = 10, - [2] = 20, - [3] = 30 -@} -@end example -@end quotation - -Pretty-printers are invoked each time GDB tries to display a value, -including when displaying the arguments of a called subprogram (in -GDB’s @code{backtrace} command) or when printing the value returned by a -function (in GDB’s @code{finish} command). - -To display a value without involving pretty-printers, @code{print} can be -invoked with its @code{/r} option: - -@quotation - -@example -(gdb) print/r map -$1 = ( - tree => (... -@end example -@end quotation - -Finer control of pretty-printers is also possible: see GDB's online documentation@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands} -for more information. - -@geindex Profiling - -@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution -@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170}@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147} -@section Profiling - - -This section describes how to use the @code{gprof} profiler tool on Ada programs. - -@geindex gprof - -@geindex Profiling - -@menu -* Profiling an Ada Program with gprof:: - -@end menu - -@node Profiling an Ada Program with gprof,,,Profiling -@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 - - -This section is not meant to be an exhaustive documentation of @code{gprof}. -Full documentation for it can be found in the @cite{GNU Profiler User’s Guide} -documentation that is part of this GNAT distribution. - -Profiling a program helps determine the parts of a program that are executed -most often, and are therefore the most time-consuming. - -@code{gprof} is the standard GNU profiling tool; it has been enhanced to -better handle Ada programs and multitasking. -It is currently supported on the following platforms - - -@itemize * - -@item -Linux x86/x86_64 - -@item -Windows x86/x86_64 (without PIE support) -@end itemize - -In order to profile a program using @code{gprof}, several steps are needed: - - -@enumerate - -@item -Instrument the code, which requires a full recompilation of the project with the -proper switches. - -@item -Execute the program under the analysis conditions, i.e. with the desired -input. - -@item -Analyze the results using the @code{gprof} tool. -@end enumerate - -The following sections detail the different steps, and indicate how -to interpret the results. - -@menu -* Compilation for profiling:: -* Program execution:: -* Running gprof:: -* Interpretation of profiling results:: - -@end menu - -@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof -@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{174} -@subsubsection Compilation for profiling - - -@geindex -pg (gcc) -@geindex for profiling - -@geindex -pg (gnatlink) -@geindex for profiling - -In order to profile a program the first step is to tell the compiler -to generate the necessary profiling information. The compiler switch to be used -is @code{-pg}, which must be added to other compilation switches. This -switch needs to be specified both during compilation and link stages, and can -be specified once when using gnatmake: - -@quotation - -@example -$ gnatmake -f -pg -P my_project -@end example -@end quotation - -Note that only the objects that were compiled with the @code{-pg} switch will -be profiled; if you need to profile your whole project, use the @code{-f} -gnatmake switch to force full recompilation. - -Note that on Windows, gprof does not support PIE. The @code{-no-pie} switch -should be added to the linker flags to disable this feature. - -@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof -@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{176} -@subsubsection Program execution - - -Once the program has been compiled for profiling, you can run it as usual. - -The only constraint imposed by profiling is that the program must terminate -normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be -properly analyzed. - -Once the program completes execution, a data file called @code{gmon.out} is -generated in the directory where the program was launched from. If this file -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 id24}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{178} -@subsubsection Running gprof - - -The @code{gprof} tool is called as follow: - -@quotation - -@example -$ gprof my_prog gmon.out -@end example -@end quotation - -or simply: - -@quotation - -@example -$ gprof my_prog -@end example -@end quotation - -The complete form of the gprof command line is the following: - -@quotation - -@example -$ gprof [switches] [executable [data-file]] -@end example -@end quotation - -@code{gprof} supports numerous switches. The order of these -switch does not matter. The full list of options can be found in -the GNU Profiler User’s Guide documentation that comes with this documentation. - -The following is the subset of those switches that is most relevant: - -@geindex --demangle (gprof) - - -@table @asis - -@item @code{--demangle[=@var{style}]}, @code{--no-demangle} - -These options control whether symbol names should be demangled when -printing output. The default is to demangle C++ symbols. The -@code{--no-demangle} option may be used to turn off demangling. Different -compilers have different mangling styles. The optional demangling style -argument can be used to choose an appropriate demangling style for your -compiler, in particular Ada symbols generated by GNAT can be demangled using -@code{--demangle=gnat}. -@end table - -@geindex -e (gprof) - - -@table @asis - -@item @code{-e @var{function_name}} - -The @code{-e @var{function}} option tells @code{gprof} not to print -information about the function @code{function_name} (and its -children…) in the call graph. The function will still be listed -as a child of any functions that call it, but its index number will be -shown as @code{[not printed]}. More than one @code{-e} option may be -given; only one @code{function_name} may be indicated with each @code{-e} -option. -@end table - -@geindex -E (gprof) - - -@table @asis - -@item @code{-E @var{function_name}} - -The @code{-E @var{function}} option works like the @code{-e} option, but -execution time spent in the function (and children who were not called from -anywhere else), will not be used to compute the percentages-of-time for -the call graph. More than one @code{-E} option may be given; only one -@code{function_name} may be indicated with each @code{-E`} option. -@end table - -@geindex -f (gprof) - - -@table @asis - -@item @code{-f @var{function_name}} - -The @code{-f @var{function}} option causes @code{gprof} to limit the -call graph to the function @code{function_name} and its children (and -their children…). More than one @code{-f} option may be given; -only one @code{function_name} may be indicated with each @code{-f} -option. -@end table - -@geindex -F (gprof) - - -@table @asis - -@item @code{-F @var{function_name}} - -The @code{-F @var{function}} option works like the @code{-f} option, but -only time spent in the function and its children (and their -children…) will be used to determine total-time and -percentages-of-time for the call graph. More than one @code{-F} option -may be given; only one @code{function_name} may be indicated with each -@code{-F} option. The @code{-F} option overrides the @code{-E} option. -@end table - -@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof -@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 - - -The results of the profiling analysis are represented by two arrays: the -‘flat profile’ and the ‘call graph’. Full documentation of those outputs -can be found in the GNU Profiler User’s Guide. - -The flat profile shows the time spent in each function of the program, and how -many time it has been called. This allows you to locate easily the most -time-consuming functions. - -The call graph shows, for each subprogram, the subprograms that call it, -and the subprograms that it calls. It also provides an estimate of the time -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 id26}@anchor{148}@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b} -@section Improving Performance - - -@geindex Improving performance - -This section presents several topics related to program performance. -It first describes some of the tradeoffs that need to be considered -and some of the techniques for making your program run faster. - -It then documents the unused subprogram/data elimination feature, -which can reduce the size of program executables. - -@menu -* Performance Considerations:: -* Text_IO Suggestions:: -* Reducing Size of Executables with Unused Subprogram/Data Elimination:: - -@end menu - -@node Performance Considerations,Text_IO Suggestions,,Improving Performance -@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17d} -@subsection Performance Considerations - - -The GNAT system provides a number of options that allow a trade-off -between - - -@itemize * - -@item -performance of the generated code - -@item -speed of compilation - -@item -minimization of dependences and recompilation - -@item -the degree of run-time checking. -@end itemize - -The defaults (if no options are selected) aim at improving the speed -of compilation and minimizing dependences, at the expense of performance -of the generated code: - - -@itemize * - -@item -no optimization - -@item -no inlining of subprogram calls - -@item -all run-time checks enabled except overflow and elaboration checks -@end itemize - -These options are suitable for most program development purposes. This -section describes how you can modify these choices, and also provides -some guidelines on debugging optimized code. - -@menu -* Controlling Run-Time Checks:: -* Use of Restrictions:: -* Optimization Levels:: -* Debugging Optimized Code:: -* Inlining of Subprograms:: -* Floating Point Operations:: -* Vectorization of loops:: -* Other Optimization Switches:: -* Optimization and Strict Aliasing:: -* Aliased Variables and Optimization:: -* Atomic Variables and Optimization:: -* Passive Task Optimization:: - -@end menu - -@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations -@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17f} -@subsubsection Controlling Run-Time Checks - - -By default, GNAT generates all run-time checks, except stack overflow -checks, and checks for access before elaboration on subprogram -calls. The latter are not required in default mode, because all -necessary checking is done at compile time. - -@geindex -gnatp (gcc) - -@geindex -gnato (gcc) - -The gnat switch, @code{-gnatp} allows this default to be modified. See -@ref{ea,,Run-Time Checks}. - -Our experience is that the default is suitable for most development -purposes. - -Elaboration checks are off by default, and also not needed by default, since -GNAT uses a static elaboration analysis approach that avoids the need for -run-time checking. This manual contains a full chapter discussing the issue -of elaboration checks, and if the default is not satisfactory for your use, -you should read this chapter. - -For validity checks, the minimal checks required by the Ada Reference -Manual (for case statements and assignments to array elements) are on -by default. These can be suppressed by use of the @code{-gnatVn} switch. -Note that in Ada 83, there were no validity checks, so if the Ada 83 mode -is acceptable (or when comparing GNAT performance with an Ada 83 compiler), -it may be reasonable to routinely use @code{-gnatVn}. Validity checks -are also suppressed entirely if @code{-gnatp} is used. - -@geindex Overflow checks - -@geindex Checks -@geindex overflow - -@geindex Suppress - -@geindex Unsuppress - -@geindex pragma Suppress - -@geindex pragma Unsuppress - -Note that the setting of the switches controls the default setting of -the checks. They may be modified using either @code{pragma Suppress} (to -remove checks) or @code{pragma Unsuppress} (to add back suppressed -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{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181} -@subsubsection Use of Restrictions - - -The use of pragma Restrictions allows you to control which features are -permitted in your program. Apart from the obvious point that if you avoid -relatively expensive features like finalization (enforceable by the use -of pragma Restrictions (No_Finalization)), the use of this pragma does not -affect the generated code in most cases. - -One notable exception to this rule is that the possibility of task abort -results in some distributed overhead, particularly if finalization or -exception handlers are used. The reason is that certain sections of code -have to be marked as non-abortable. - -If you use neither the @code{abort} statement, nor asynchronous transfer -of control (@code{select ... then abort}), then this distributed overhead -is removed, which may have a general positive effect in improving -overall performance. Especially code involving frequent use of tasking -constructs and controlled types will show much improved performance. -The relevant restrictions pragmas are - -@quotation - -@example -pragma Restrictions (No_Abort_Statements); -pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); -@end example -@end quotation - -It is recommended that these restriction pragmas be used if possible. Note -that this also means that you can write code without worrying about the -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{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed} -@subsubsection Optimization Levels - - -@geindex -O (gcc) - -Without any optimization option, -the compiler’s goal is to reduce the cost of -compilation and to make debugging produce the expected results. -Statements are independent: if you stop the program with a breakpoint between -statements, you can then assign a new value to any variable or change -the program counter to any other statement in the subprogram and get exactly -the results you would expect from the source code. - -Turning on optimization makes the compiler attempt to improve the -performance and/or code size at the expense of compilation time and -possibly the ability to debug the program. - -If you use multiple --O options, with or without level numbers, -the last such option is the one that is effective. - -The default is optimization off. This results in the fastest compile -times, but GNAT makes absolutely no attempt to optimize, and the -generated programs are considerably larger and slower than when -optimization is enabled. You can use the -@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1} -@code{-O2}, @code{-O3}, and @code{-Os}) -to @code{gcc} to control the optimization level: - - -@itemize * - -@item - -@table @asis - -@item @code{-O0} - -No optimization (the default); -generates unoptimized code but has -the fastest compilation time. - -Note that many other compilers do substantial optimization even -if ‘no optimization’ is specified. With gcc, it is very unusual -to use @code{-O0} for production if execution time is of any concern, -since @code{-O0} means (almost) no optimization. This difference -between gcc and other compilers should be kept in mind when -doing performance comparisons. -@end table - -@item - -@table @asis - -@item @code{-O1} - -Moderate optimization; -optimizes reasonably well but does not -degrade compilation time significantly. -@end table - -@item - -@table @asis - -@item @code{-O2} - -Full optimization; -generates highly optimized code and has -the slowest compilation time. -@end table - -@item - -@table @asis - -@item @code{-O3} - -Full optimization as in @code{-O2}; -also uses more aggressive automatic inlining of subprograms within a unit -(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops. -@end table - -@item - -@table @asis - -@item @code{-Os} - -Optimize space usage (code and data) of resulting program. -@end table -@end itemize - -Higher optimization levels perform more global transformations on the -program and apply more expensive analysis algorithms in order to generate -faster and more compact code. The price in compilation time, and the -resulting improvement in execution time, -both depend on the particular application and the hardware environment. -You should experiment to find the best level for your application. - -Since the precise set of optimizations done at each level will vary from -release to release (and sometime from target to target), it is best to think -of the optimization settings in general terms. -See the `Options That Control Optimization' section in -@cite{Using the GNU Compiler Collection (GCC)} -for details about -the @code{-O} settings and a number of @code{-f} options that -individually enable or disable specific optimizations. - -Unlike some other compilation systems, @code{gcc} has -been tested extensively at all optimization levels. There are some bugs -which appear only with optimization turned on, but there have also been -bugs which show up only in `unoptimized' code. Selecting a lower -level of optimization does not improve the reliability of the code -generator, which in practice is highly reliable at all optimization -levels. - -Note regarding the use of @code{-O3}: The use of this optimization level -ought not to be automatically preferred over that of level @code{-O2}, -since it often results in larger executables which may run more slowly. -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{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184} -@subsubsection Debugging Optimized Code - - -@geindex Debugging optimized code - -@geindex Optimization and debugging - -Although it is possible to do a reasonable amount of debugging at -nonzero optimization levels, -the higher the level the more likely that -source-level constructs will have been eliminated by optimization. -For example, if a loop is strength-reduced, the loop -control variable may be completely eliminated and thus cannot be -displayed in the debugger. -This can only happen at @code{-O2} or @code{-O3}. -Explicit temporary variables that you code might be eliminated at -level @code{-O1} or higher. - -@geindex -g (gcc) - -The use of the @code{-g} switch, -which is needed for source-level debugging, -affects the size of the program executable on disk, -and indeed the debugging information can be quite large. -However, it has no effect on the generated code (and thus does not -degrade performance) - -Since the compiler generates debugging tables for a compilation unit before -it performs optimizations, the optimizing transformations may invalidate some -of the debugging data. You therefore need to anticipate certain -anomalous situations that may arise while debugging optimized code. -These are the most common cases: - - -@itemize * - -@item -`The ‘hopping Program Counter’:' Repeated @code{step} or @code{next} -commands show -the PC bouncing back and forth in the code. This may result from any of -the following optimizations: - - -@itemize - - -@item -`Common subexpression elimination:' using a single instance of code for a -quantity that the source computes several times. As a result you -may not be able to stop on what looks like a statement. - -@item -`Invariant code motion:' moving an expression that does not change within a -loop, to the beginning of the loop. - -@item -`Instruction scheduling:' moving instructions so as to -overlap loads and stores (typically) with other code, or in -general to move computations of values closer to their uses. Often -this causes you to pass an assignment statement without the assignment -happening and then later bounce back to the statement when the -value is actually needed. Placing a breakpoint on a line of code -and then stepping over it may, therefore, not always cause all the -expected side-effects. -@end itemize - -@item -`The ‘big leap’:' More commonly known as `cross-jumping', in which -two identical pieces of code are merged and the program counter suddenly -jumps to a statement that is not supposed to be executed, simply because -it (and the code following) translates to the same thing as the code -that `was' supposed to be executed. This effect is typically seen in -sequences that end in a jump, such as a @code{goto}, a @code{return}, or -a @code{break} in a C @code{switch} statement. - -@item -`The ‘roving variable’:' The symptom is an unexpected value in a variable. -There are various reasons for this effect: - - -@itemize - - -@item -In a subprogram prologue, a parameter may not yet have been moved to its -‘home’. - -@item -A variable may be dead, and its register re-used. This is -probably the most common cause. - -@item -As mentioned above, the assignment of a value to a variable may -have been moved. - -@item -A variable may be eliminated entirely by value propagation or -other means. In this case, GCC may incorrectly generate debugging -information for the variable -@end itemize - -In general, when an unexpected value appears for a local variable or parameter -you should first ascertain if that value was actually computed by -your program, as opposed to being incorrectly reported by the debugger. -Record fields or -array elements in an object designated by an access value -are generally less of a problem, once you have ascertained that the access -value is sensible. -Typically, this means checking variables in the preceding code and in the -calling subprogram to verify that the value observed is explainable from other -values (one must apply the procedure recursively to those -other values); or re-running the code and stopping a little earlier -(perhaps before the call) and stepping to better see how the variable obtained -the value in question; or continuing to step `from' the point of the -strange value to see if code motion had simply moved the variable’s -assignments later. -@end itemize - -In light of such anomalies, a recommended technique is to use @code{-O0} -early in the software development cycle, when extensive debugging capabilities -are most needed, and then move to @code{-O1} and later @code{-O2} as -the debugger becomes less critical. -Whether to use the @code{-g} switch in the release version is -a release management issue. -Note that if you use @code{-g} you can then use the @code{strip} program -on the resulting executable, -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{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100} -@subsubsection Inlining of Subprograms - - -A call to a subprogram in the current unit is inlined if all the -following conditions are met: - - -@itemize * - -@item -The optimization level is at least @code{-O1}. - -@item -The called subprogram is suitable for inlining: It must be small enough -and not contain something that @code{gcc} cannot support in inlined -subprograms. - -@geindex pragma Inline - -@geindex Inline - -@item -Any one of the following applies: @code{pragma Inline} is applied to the -subprogram; the subprogram is local to the unit and called once from -within it; the subprogram is small and optimization level @code{-O2} is -specified; optimization level @code{-O3} is specified. -@end itemize - -Calls to subprograms in `with'ed units are normally not inlined. -To achieve actual inlining (that is, replacement of the call by the code -in the body of the subprogram), the following conditions must all be true: - - -@itemize * - -@item -The optimization level is at least @code{-O1}. - -@item -The called subprogram is suitable for inlining: It must be small enough -and not contain something that @code{gcc} cannot support in inlined -subprograms. - -@item -There is a @code{pragma Inline} for the subprogram. - -@item -The @code{-gnatn} switch is used on the command line. -@end itemize - -Even if all these conditions are met, it may not be possible for -the compiler to inline the call, due to the length of the body, -or features in the body that make it impossible for the compiler -to do the inlining. - -Note that specifying the @code{-gnatn} switch causes additional -compilation dependencies. Consider the following: - -@quotation - -@example -package R is - procedure Q; - pragma Inline (Q); -end R; -package body R is - ... -end R; - -with R; -procedure Main is -begin - ... - R.Q; -end Main; -@end example -@end quotation - -With the default behavior (no @code{-gnatn} switch specified), the -compilation of the @code{Main} procedure depends only on its own source, -@code{main.adb}, and the spec of the package in file @code{r.ads}. This -means that editing the body of @code{R} does not require recompiling -@code{Main}. - -On the other hand, the call @code{R.Q} is not inlined under these -circumstances. If the @code{-gnatn} switch is present when @code{Main} -is compiled, the call will be inlined if the body of @code{Q} is small -enough, but now @code{Main} depends on the body of @code{R} in -@code{r.adb} as well as on the spec. This means that if this body is edited, -the main program must be recompiled. Note that this extra dependency -occurs whether or not the call is in fact inlined by @code{gcc}. - -The use of front end inlining with @code{-gnatN} generates similar -additional dependencies. - -@geindex -fno-inline (gcc) - -Note: The @code{-fno-inline} switch overrides all other conditions and ensures that -no inlining occurs, unless requested with pragma Inline_Always for @code{gcc} -back-ends. The extra dependences resulting from @code{-gnatn} will still be active, -even if this switch is used to suppress the resulting inlining actions. - -@geindex -fno-inline-functions (gcc) - -Note: The @code{-fno-inline-functions} switch can be used to prevent -automatic inlining of subprograms if @code{-O3} is used. - -@geindex -fno-inline-small-functions (gcc) - -Note: The @code{-fno-inline-small-functions} switch can be used to prevent -automatic inlining of small subprograms if @code{-O2} is used. - -@geindex -fno-inline-functions-called-once (gcc) - -Note: The @code{-fno-inline-functions-called-once} switch -can be used to prevent inlining of subprograms local to the unit -and called once from within it if @code{-O1} is used. - -Note regarding the use of @code{-O3}: @code{-gnatn} is made up of two -sub-switches @code{-gnatn1} and @code{-gnatn2} that can be directly -specified in lieu of it, @code{-gnatn} being translated into one of them -based on the optimization level. With @code{-O2} or below, @code{-gnatn} -is equivalent to @code{-gnatn1} which activates pragma @code{Inline} with -moderate inlining across modules. With @code{-O3}, @code{-gnatn} is -equivalent to @code{-gnatn2} which activates pragma @code{Inline} with -full inlining across modules. If you have used pragma @code{Inline} in -appropriate cases, then it is usually much better to use @code{-O2} -and @code{-gnatn} and avoid the use of @code{-O3} which has the additional -effect of inlining subprograms you did not think should be inlined. We have -found that the use of @code{-O3} may slow down the compilation and increase -the code size by performing excessive inlining, leading to increased -instruction cache pressure from the increased code size and thus minor -performance improvements. So the bottom line here is that you should not -automatically assume that @code{-O3} is better than @code{-O2}, and -indeed you should use @code{-O3} only if tests show that it actually -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{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187} -@subsubsection Floating Point Operations - - -@geindex Floating-Point Operations - -On almost all targets, GNAT maps Float and Long_Float to the 32-bit and -64-bit standard IEEE floating-point representations, and operations will -use standard IEEE arithmetic as provided by the processor. On most, but -not all, architectures, the attribute Machine_Overflows is False for these -types, meaning that the semantics of overflow is implementation-defined. -In the case of GNAT, these semantics correspond to the normal IEEE -treatment of infinities and NaN (not a number) values. For example, -1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By -avoiding explicit overflow checks, the performance is greatly improved -on many targets. However, if required, floating-point overflow can be -enabled by the use of the pragma Check_Float_Overflow. - -Another consideration that applies specifically to x86 32-bit -architectures is which form of floating-point arithmetic is used. -By default the operations use the old style x86 floating-point, -which implements an 80-bit extended precision form (on these -architectures the type Long_Long_Float corresponds to that form). -In addition, generation of efficient code in this mode means that -the extended precision form will be used for intermediate results. -This may be helpful in improving the final precision of a complex -expression. However it means that the results obtained on the x86 -will be different from those on other architectures, and for some -algorithms, the extra intermediate precision can be detrimental. - -In addition to this old-style floating-point, all modern x86 chips -implement an alternative floating-point operation model referred -to as SSE2. In this model there is no extended form, and furthermore -execution performance is significantly enhanced. To force GNAT to use -this more modern form, use both of the switches: - -@quotation - --msse2 -mfpmath=sse -@end quotation - -A unit compiled with these switches will automatically use the more -efficient SSE2 instruction set for Float and Long_Float operations. -Note that the ABI has the same form for both floating-point models, -so it is permissible to mix units compiled with and without these -switches. - -@node Vectorization of loops,Other Optimization Switches,Floating Point Operations,Performance Considerations -@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 - - -@geindex Optimization Switches - -You can take advantage of the auto-vectorizer present in the @code{gcc} -back end to vectorize loops with GNAT. The corresponding command line switch -is @code{-ftree-vectorize} but, as it is enabled by default at @code{-O3} -and other aggressive optimizations helpful for vectorization also are enabled -by default at this level, using @code{-O3} directly is recommended. - -You also need to make sure that the target architecture features a supported -SIMD instruction set. For example, for the x86 architecture, you should at -least specify @code{-msse2} to get significant vectorization (but you don’t -need to specify it for x86-64 as it is part of the base 64-bit architecture). -Similarly, for the PowerPC architecture, you should specify @code{-maltivec}. - -The preferred loop form for vectorization is the @code{for} iteration scheme. -Loops with a @code{while} iteration scheme can also be vectorized if they are -very simple, but the vectorizer will quickly give up otherwise. With either -iteration scheme, the flow of control must be straight, in particular no -@code{exit} statement may appear in the loop body. The loop may however -contain a single nested loop, if it can be vectorized when considered alone: - -@quotation - -@example -A : array (1..4, 1..4) of Long_Float; -S : array (1..4) of Long_Float; - -procedure Sum is -begin - for I in A'Range(1) loop - for J in A'Range(2) loop - S (I) := S (I) + A (I, J); - end loop; - end loop; -end Sum; -@end example -@end quotation - -The vectorizable operations depend on the targeted SIMD instruction set, but -the adding and some of the multiplying operators are generally supported, as -well as the logical operators for modular types. Note that compiling -with @code{-gnatp} might well reveal cases where some checks do thwart -vectorization. - -Type conversions may also prevent vectorization if they involve semantics that -are not directly supported by the code generator or the SIMD instruction set. -A typical example is direct conversion from floating-point to integer types. -The solution in this case is to use the following idiom: - -@quotation - -@example -Integer (S'Truncation (F)) -@end example -@end quotation - -if @code{S} is the subtype of floating-point object @code{F}. - -In most cases, the vectorizable loops are loops that iterate over arrays. -All kinds of array types are supported, i.e. constrained array types with -static bounds: - -@quotation - -@example -type Array_Type is array (1 .. 4) of Long_Float; -@end example -@end quotation - -constrained array types with dynamic bounds: - -@quotation - -@example -type Array_Type is array (1 .. Q.N) of Long_Float; - -type Array_Type is array (Q.K .. 4) of Long_Float; - -type Array_Type is array (Q.K .. Q.N) of Long_Float; -@end example -@end quotation - -or unconstrained array types: - -@quotation - -@example -type Array_Type is array (Positive range <>) of Long_Float; -@end example -@end quotation - -The quality of the generated code decreases when the dynamic aspect of the -array type increases, the worst code being generated for unconstrained array -types. This is so because, the less information the compiler has about the -bounds of the array, the more fallback code it needs to generate in order to -fix things up at run time. - -It is possible to specify that a given loop should be subject to vectorization -preferably to other optimizations by means of pragma @code{Loop_Optimize}: - -@quotation - -@example -pragma Loop_Optimize (Vector); -@end example -@end quotation - -placed immediately within the loop will convey the appropriate hint to the -compiler for this loop. - -It is also possible to help the compiler generate better vectorized code -for a given loop by asserting that there are no loop-carried dependencies -in the loop. Consider for example the procedure: - -@quotation - -@example -type Arr is array (1 .. 4) of Long_Float; - -procedure Add (X, Y : not null access Arr; R : not null access Arr) is -begin - for I in Arr'Range loop - R(I) := X(I) + Y(I); - end loop; -end; -@end example -@end quotation - -By default, the compiler cannot unconditionally vectorize the loop because -assigning to a component of the array designated by R in one iteration could -change the value read from the components of the array designated by X or Y -in a later iteration. As a result, the compiler will generate two versions -of the loop in the object code, one vectorized and the other not vectorized, -as well as a test to select the appropriate version at run time. This can -be overcome by another hint: - -@quotation - -@example -pragma Loop_Optimize (Ivdep); -@end example -@end quotation - -placed immediately within the loop will tell the compiler that it can safely -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 id35}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18b} -@subsubsection Other Optimization Switches - - -@geindex Optimization Switches - -Since GNAT uses the @code{gcc} back end, all the specialized -@code{gcc} optimization switches are potentially usable. These switches -have not been extensively tested with GNAT but can generally be expected -to work. Examples of switches in this category are @code{-funroll-loops} -and the various target-specific @code{-m} options (in particular, it has -been observed that @code{-march=xxx} can significantly improve performance -on appropriate machines). For full details of these switches, see -the `Submodel Options' section in the `Hardware Models and Configurations' -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 id36}@anchor{18c}@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4} -@subsubsection Optimization and Strict Aliasing - - -@geindex Aliasing - -@geindex Strict Aliasing - -@geindex No_Strict_Aliasing - -The strong typing capabilities of Ada allow an optimizer to generate -efficient code in situations where other languages would be forced to -make worst case assumptions preventing such optimizations. Consider -the following example: - -@quotation - -@example -procedure R is - type Int1 is new Integer; - type Int2 is new Integer; - type Int1A is access Int1; - type Int2A is access Int2; - Int1V : Int1A; - Int2V : Int2A; - ... - -begin - ... - for J in Data'Range loop - if Data (J) = Int1V.all then - Int2V.all := Int2V.all + 1; - end if; - end loop; - ... -end R; -@end example -@end quotation - -In this example, since the variable @code{Int1V} can only access objects -of type @code{Int1}, and @code{Int2V} can only access objects of type -@code{Int2}, there is no possibility that the assignment to -@code{Int2V.all} affects the value of @code{Int1V.all}. This means that -the compiler optimizer can “know” that the value @code{Int1V.all} is constant -for all iterations of the loop and avoid the extra memory reference -required to dereference it each time through the loop. - -This kind of optimization, called strict aliasing analysis, is -triggered by specifying an optimization level of @code{-O2} or -higher or @code{-Os} and allows GNAT to generate more efficient code -when access values are involved. - -However, although this optimization is always correct in terms of -the formal semantics of the Ada Reference Manual, difficulties can -arise if features like @code{Unchecked_Conversion} are used to break -the typing system. Consider the following complete program example: - -@quotation - -@example -package p1 is - type int1 is new integer; - type int2 is new integer; - type a1 is access int1; - type a2 is access int2; -end p1; - -with p1; use p1; -package p2 is - function to_a2 (Input : a1) return a2; -end p2; - -with Ada.Unchecked_Conversion; -package body p2 is - function to_a2 (Input : a1) return a2 is - function to_a2u is - new Ada.Unchecked_Conversion (a1, a2); - begin - return to_a2u (Input); - end to_a2; -end p2; - -with p2; use p2; -with p1; use p1; -with Text_IO; use Text_IO; -procedure m is - v1 : a1 := new int1; - v2 : a2 := to_a2 (v1); -begin - v1.all := 1; - v2.all := 0; - put_line (int1'image (v1.all)); -end; -@end example -@end quotation - -This program prints out 0 in @code{-O0} or @code{-O1} -mode, but it prints out 1 in @code{-O2} mode. That’s -because in strict aliasing mode, the compiler can and -does assume that the assignment to @code{v2.all} could not -affect the value of @code{v1.all}, since different types -are involved. - -This behavior is not a case of non-conformance with the standard, since -the Ada RM specifies that an unchecked conversion where the resulting -bit pattern is not a correct value of the target type can result in an -abnormal value and attempting to reference an abnormal value makes the -execution of a program erroneous. That’s the case here since the result -does not point to an object of type @code{int2}. This means that the -effect is entirely unpredictable. - -However, although that explanation may satisfy a language -lawyer, in practice an applications programmer expects an -unchecked conversion involving pointers to create true -aliases and the behavior of printing 1 seems plain wrong. -In this case, the strict aliasing optimization is unwelcome. - -Indeed the compiler recognizes this possibility, and the -unchecked conversion generates a warning: - -@quotation - -@example -p2.adb:5:07: warning: possible aliasing problem with type "a2" -p2.adb:5:07: warning: use -fno-strict-aliasing switch for references -p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" -@end example -@end quotation - -Unfortunately the problem is recognized when compiling the body of -package @code{p2}, but the actual “bad” code is generated while -compiling the body of @code{m} and this latter compilation does not see -the suspicious @code{Unchecked_Conversion}. - -As implied by the warning message, there are approaches you can use to -avoid the unwanted strict aliasing optimization in a case like this. - -One possibility is to simply avoid the use of @code{-O2}, but -that is a bit drastic, since it throws away a number of useful -optimizations that do not involve strict aliasing assumptions. - -A less drastic approach is to compile the program using the -option @code{-fno-strict-aliasing}. Actually it is only the -unit containing the dereferencing of the suspicious pointer -that needs to be compiled. So in this case, if we compile -unit @code{m} with this switch, then we get the expected -value of zero printed. Analyzing which units might need -the switch can be painful, so a more reasonable approach -is to compile the entire program with options @code{-O2} -and @code{-fno-strict-aliasing}. If the performance is -satisfactory with this combination of options, then the -advantage is that the entire issue of possible “wrong” -optimization due to strict aliasing is avoided. - -To avoid the use of compiler switches, the configuration -pragma @code{No_Strict_Aliasing} with no parameters may be -used to specify that for all access types, the strict -aliasing optimization should be suppressed. - -However, these approaches are still overkill, in that they causes -all manipulations of all access values to be deoptimized. A more -refined approach is to concentrate attention on the specific -access type identified as problematic. - -First, if a careful analysis of uses of the pointer shows -that there are no possible problematic references, then -the warning can be suppressed by bracketing the -instantiation of @code{Unchecked_Conversion} to turn -the warning off: - -@quotation - -@example -pragma Warnings (Off); -function to_a2u is - new Ada.Unchecked_Conversion (a1, a2); -pragma Warnings (On); -@end example -@end quotation - -Of course that approach is not appropriate for this particular -example, since indeed there is a problematic reference. In this -case we can take one of two other approaches. - -The first possibility is to move the instantiation of unchecked -conversion to the unit in which the type is declared. In -this example, we would move the instantiation of -@code{Unchecked_Conversion} from the body of package -@code{p2} to the spec of package @code{p1}. Now the -warning disappears. That’s because any use of the -access type knows there is a suspicious unchecked -conversion, and the strict aliasing optimization -is automatically suppressed for the type. - -If it is not practical to move the unchecked conversion to the same unit -in which the destination access type is declared (perhaps because the -source type is not visible in that unit), you may use pragma -@code{No_Strict_Aliasing} for the type. This pragma must occur in the -same declarative sequence as the declaration of the access type: - -@quotation - -@example -type a2 is access int2; -pragma No_Strict_Aliasing (a2); -@end example -@end quotation - -Here again, the compiler now knows that the strict aliasing optimization -should be suppressed for any reference to type @code{a2} and the -expected behavior is obtained. - -Finally, note that although the compiler can generate warnings for -simple cases of unchecked conversions, there are tricker and more -indirect ways of creating type incorrect aliases which the compiler -cannot detect. Examples are the use of address overlays and unchecked -conversions involving composite types containing access types as -components. In such cases, no warnings are generated, but there can -still be aliasing problems. One safe coding practice is to forbid the -use of address clauses for type overlaying, and to allow unchecked -conversion only for primitive types. This is not really a significant -restriction since any possible desired effect can be achieved by -unchecked conversion of access values. - -The aliasing analysis done in strict aliasing mode can certainly -have significant benefits. We have seen cases of large scale -application code where the time is increased by up to 5% by turning -this optimization off. If you have code that includes significant -usage of unchecked conversion, you might want to just stick with -@code{-O1} and avoid the entire issue. If you get adequate -performance at this level of optimization level, that’s probably -the safest approach. If tests show that you really need higher -levels of optimization, then you can experiment with @code{-O2} -and @code{-O2 -fno-strict-aliasing} to see how much effect this -has on size and speed of the code. If you really need to use -@code{-O2} with strict aliasing in effect, then you should -review any uses of unchecked conversion of access types, -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 aliased-variables-and-optimization}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18e} -@subsubsection Aliased Variables and Optimization - - -@geindex Aliasing - -There are scenarios in which programs may -use low level techniques to modify variables -that otherwise might be considered to be unassigned. For example, -a variable can be passed to a procedure by reference, which takes -the address of the parameter and uses the address to modify the -variable’s value, even though it is passed as an IN parameter. -Consider the following example: - -@quotation - -@example -procedure P is - Max_Length : constant Natural := 16; - type Char_Ptr is access all Character; - - procedure Get_String(Buffer: Char_Ptr; Size : Integer); - pragma Import (C, Get_String, "get_string"); - - Name : aliased String (1 .. Max_Length) := (others => ' '); - Temp : Char_Ptr; - - function Addr (S : String) return Char_Ptr is - function To_Char_Ptr is - new Ada.Unchecked_Conversion (System.Address, Char_Ptr); - begin - return To_Char_Ptr (S (S'First)'Address); - end; - -begin - Temp := Addr (Name); - Get_String (Temp, Max_Length); -end; -@end example -@end quotation - -where Get_String is a C function that uses the address in Temp to -modify the variable @code{Name}. This code is dubious, and arguably -erroneous, and the compiler would be entitled to assume that -@code{Name} is never modified, and generate code accordingly. - -However, in practice, this would cause some existing code that -seems to work with no optimization to start failing at high -levels of optimization. - -What the compiler does for such cases is to assume that marking -a variable as aliased indicates that some “funny business” may -be going on. The optimizer recognizes the aliased keyword and -inhibits optimizations that assume the value cannot be assigned. -This means that the above example will in fact “work” reliably, -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{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190} -@subsubsection Atomic Variables and Optimization - - -@geindex Atomic - -There are two considerations with regard to performance when -atomic variables are used. - -First, the RM only guarantees that access to atomic variables -be atomic, it has nothing to say about how this is achieved, -though there is a strong implication that this should not be -achieved by explicit locking code. Indeed GNAT will never -generate any locking code for atomic variable access (it will -simply reject any attempt to make a variable or type atomic -if the atomic access cannot be achieved without such locking code). - -That being said, it is important to understand that you cannot -assume that the entire variable will always be accessed. Consider -this example: - -@quotation - -@example -type R is record - A,B,C,D : Character; -end record; -for R'Size use 32; -for R'Alignment use 4; - -RV : R; -pragma Atomic (RV); -X : Character; -... -X := RV.B; -@end example -@end quotation - -You cannot assume that the reference to @code{RV.B} -will read the entire 32-bit -variable with a single load instruction. It is perfectly legitimate if -the hardware allows it to do a byte read of just the B field. This read -is still atomic, which is all the RM requires. GNAT can and does take -advantage of this, depending on the architecture and optimization level. -Any assumption to the contrary is non-portable and risky. Even if you -examine the assembly language and see a full 32-bit load, this might -change in a future version of the compiler. - -If your application requires that all accesses to @code{RV} in this -example be full 32-bit loads, you need to make a copy for the access -as in: - -@quotation - -@example -declare - RV_Copy : constant R := RV; -begin - X := RV_Copy.B; -end; -@end example -@end quotation - -Now the reference to RV must read the whole variable. -Actually one can imagine some compiler which figures -out that the whole copy is not required (because only -the B field is actually accessed), but GNAT -certainly won’t do that, and we don’t know of any -compiler that would not handle this right, and the -above code will in practice work portably across -all architectures (that permit the Atomic declaration). - -The second issue with atomic variables has to do with -the possible requirement of generating synchronization -code. For more details on this, consult the sections on -the pragmas Enable/Disable_Atomic_Synchronization in the -GNAT Reference Manual. If performance is critical, and -such synchronization code is not required, it may be -useful to disable it. - -@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations -@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{192} -@subsubsection Passive Task Optimization - - -@geindex Passive Task - -A passive task is one which is sufficiently simple that -in theory a compiler could recognize it an implement it -efficiently without creating a new thread. The original design -of Ada 83 had in mind this kind of passive task optimization, but -only a few Ada 83 compilers attempted it. The problem was that -it was difficult to determine the exact conditions under which -the optimization was possible. The result is a very fragile -optimization where a very minor change in the program can -suddenly silently make a task non-optimizable. - -With the revisiting of this issue in Ada 95, there was general -agreement that this approach was fundamentally flawed, and the -notion of protected types was introduced. When using protected -types, the restrictions are well defined, and you KNOW that the -operations will be optimized, and furthermore this optimized -performance is fully portable. - -Although it would theoretically be possible for GNAT to attempt to -do this optimization, but it really doesn’t make sense in the -context of Ada 95, and none of the Ada 95 compilers implement -this optimization as far as we know. In particular GNAT never -attempts to perform this optimization. - -In any new Ada 95 code that is written, you should always -use protected types in place of tasks that might be able to -be optimized in this manner. -Of course this does not help if you have legacy Ada 83 code -that depends on this optimization, but it is unusual to encounter -a case where the performance gains from this optimization -are significant. - -Your program should work correctly without this optimization. If -you have performance problems, then the most practical -approach is to figure out exactly where these performance problems -arise, and update those particular tasks to be protected types. Note -that typically clients of the tasks who call entries, will not have -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 id40}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{194} -@subsection @code{Text_IO} Suggestions - - -@geindex Text_IO and performance - -The @code{Ada.Text_IO} package has fairly high overheads due in part to -the requirement of maintaining page and line counts. If performance -is critical, a recommendation is to use @code{Stream_IO} instead of -@code{Text_IO} for volume output, since this package has less overhead. - -If @code{Text_IO} must be used, note that by default output to the standard -output and standard error files is unbuffered (this provides better -behavior when output statements are used for debugging, or if the -progress of a program is observed by tracking the output, e.g. by -using the Unix `tail -f' command to watch redirected output). - -If you are generating large volumes of output with @code{Text_IO} and -performance is an important factor, use a designated file instead -of the standard output file, or change the standard output file to -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{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 - - -@geindex Uunused subprogram/data elimination - -This section describes how you can eliminate unused subprograms and data from -your executable just by setting options at compilation time. - -@menu -* About unused subprogram/data elimination:: -* Compilation options:: -* Example of 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 about-unused-subprogram-data-elimination}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{198} -@subsubsection About unused subprogram/data elimination - - -By default, an executable contains all code and data of its composing objects -(directly linked or coming from statically linked libraries), even data or code -never used by this executable. - -This feature will allow you to eliminate such unused code from your -executable, making it smaller (in disk and in memory). - -This functionality is available on all Linux platforms except for the IA-64 -architecture and on all cross platforms using the ELF binary file format. -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 compilation-options}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{19a} -@subsubsection Compilation options - - -The operation of eliminating the unused code and data from the final executable -is directly performed by the linker. - -@geindex -ffunction-sections (gcc) - -@geindex -fdata-sections (gcc) - -In order to do this, it has to work with objects compiled with the -following options: -@code{-ffunction-sections} @code{-fdata-sections}. - -These options are usable with C and Ada files. -They will place respectively each -function or data in a separate section in the resulting object file. - -Once the objects and static libraries are created with these options, the -linker can perform the dead code elimination. You can do this by setting -the @code{-Wl,--gc-sections} option to gcc command or in the -@code{-largs} section of @code{gnatmake}. This will perform a -garbage collection of code and data never referenced. - -If the linker performs a partial link (@code{-r} linker option), then you -will need to provide the entry point using the @code{-e} / @code{--entry} -linker option. - -Note that objects compiled without the @code{-ffunction-sections} and -@code{-fdata-sections} options can still be linked with the executable. -However, no dead code elimination will be performed on those objects (they will -be linked as is). - -The GNAT static library is now compiled with -ffunction-sections and --fdata-sections on some platforms. This allows you to eliminate the unused code -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{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c} -@subsubsection Example of unused subprogram/data elimination - - -Here is a simple example: - -@quotation - -@example -with Aux; - -procedure Test is -begin - Aux.Used (10); -end Test; - -package Aux is - Used_Data : Integer; - Unused_Data : Integer; - - procedure Used (Data : Integer); - procedure Unused (Data : Integer); -end Aux; - -package body Aux is - procedure Used (Data : Integer) is - begin - Used_Data := Data; - end Used; - - procedure Unused (Data : Integer) is - begin - Unused_Data := Data; - end Unused; -end Aux; -@end example -@end quotation - -@code{Unused} and @code{Unused_Data} are never referenced in this code -excerpt, and hence they may be safely removed from the final executable. - -@quotation - -@example -$ gnatmake test - -$ nm test | grep used -020015f0 T aux__unused -02005d88 B aux__unused_data -020015cc T aux__used -02005d84 B aux__used_data - -$ gnatmake test -cargs -fdata-sections -ffunction-sections \\ - -largs -Wl,--gc-sections - -$ nm test | grep used -02005350 T aux__used -0201ffe0 B aux__used_data -@end example -@end quotation - -It can be observed that the procedure @code{Unused} and the object -@code{Unused_Data} are removed by the linker when using the -appropriate options. - -@geindex Overflow checks - -@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{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d} -@section Overflow Check Handling in GNAT - - -This section explains how to control the handling of overflow checks. - -@menu -* Background:: -* Management of Overflows in GNAT:: -* Specifying the Desired Mode:: -* Default Settings:: -* Implementation Notes:: - -@end menu - -@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT -@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19f} -@subsection Background - - -Overflow checks are checks that the compiler may make to ensure -that intermediate results are not out of range. For example: - -@quotation - -@example -A : Integer; -... -A := A + 1; -@end example -@end quotation - -If @code{A} has the value @code{Integer'Last}, then the addition may cause -overflow since the result is out of range of the type @code{Integer}. -In this case @code{Constraint_Error} will be raised if checks are -enabled. - -A trickier situation arises in examples like the following: - -@quotation - -@example -A, C : Integer; -... -A := (A + 1) + C; -@end example -@end quotation - -where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}. -Now the final result of the expression on the right hand side is -@code{Integer'Last} which is in range, but the question arises whether the -intermediate addition of @code{(A + 1)} raises an overflow error. - -The (perhaps surprising) answer is that the Ada language -definition does not answer this question. Instead it leaves -it up to the implementation to do one of two things if overflow -checks are enabled. - - -@itemize * - -@item -raise an exception (@code{Constraint_Error}), or - -@item -yield the correct mathematical result which is then used in -subsequent operations. -@end itemize - -If the compiler chooses the first approach, then the assignment of this -example will indeed raise @code{Constraint_Error} if overflow checking is -enabled, or result in erroneous execution if overflow checks are suppressed. - -But if the compiler -chooses the second approach, then it can perform both additions yielding -the correct mathematical result, which is in range, so no exception -will be raised, and the right result is obtained, regardless of whether -overflow checks are suppressed. - -Note that in the first example an -exception will be raised in either case, since if the compiler -gives the correct mathematical result for the addition, it will -be out of range of the target type of the assignment, and thus -fails the range check. - -This lack of specified behavior in the handling of overflow for -intermediate results is a source of non-portability, and can thus -be problematic when programs are ported. Most typically this arises -in a situation where the original compiler did not raise an exception, -and then the application is moved to a compiler where the check is -performed on the intermediate result and an unexpected exception is -raised. - -Furthermore, when using Ada 2012’s preconditions and other -assertion forms, another issue arises. Consider: - -@quotation - -@example -procedure P (A, B : Integer) with - Pre => A + B <= Integer'Last; -@end example -@end quotation - -One often wants to regard arithmetic in a context like this from -a mathematical point of view. So for example, if the two actual parameters -for a call to @code{P} are both @code{Integer'Last}, then -the precondition should be regarded as False. If we are executing -in a mode with run-time checks enabled for preconditions, then we would -like this precondition to fail, rather than raising an exception -because of the intermediate overflow. - -However, the language definition leaves the specification of -whether the above condition fails (raising @code{Assert_Error}) or -causes an intermediate overflow (raising @code{Constraint_Error}) -up to the implementation. - -The situation is worse in a case such as the following: - -@quotation - -@example -procedure Q (A, B, C : Integer) with - Pre => A + B + C <= Integer'Last; -@end example -@end quotation - -Consider the call - -@quotation - -@example -Q (A => Integer'Last, B => 1, C => -1); -@end example -@end quotation - -From a mathematical point of view the precondition -is True, but at run time we may (but are not guaranteed to) get an -exception raised because of the intermediate overflow (and we really -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{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1} -@subsection Management of Overflows in GNAT - - -To deal with the portability issue, and with the problem of -mathematical versus run-time interpretation of the expressions in -assertions, GNAT provides comprehensive control over the handling -of intermediate overflow. GNAT can operate in three modes, and -furthermore, permits separate selection of operating modes for -the expressions within assertions (here the term ‘assertions’ -is used in the technical sense, which includes preconditions and so forth) -and for expressions appearing outside assertions. - -The three modes are: - - -@itemize * - -@item -`Use base type for intermediate operations' (@code{STRICT}) - -In this mode, all intermediate results for predefined arithmetic -operators are computed using the base type, and the result must -be in range of the base type. If this is not the -case then either an exception is raised (if overflow checks are -enabled) or the execution is erroneous (if overflow checks are suppressed). -This is the normal default mode. - -@item -`Most intermediate overflows avoided' (@code{MINIMIZED}) - -In this mode, the compiler attempts to avoid intermediate overflows by -using a larger integer type, typically @code{Long_Long_Integer}, -as the type in which arithmetic is -performed for predefined arithmetic operators. This may be slightly more -expensive at -run time (compared to suppressing intermediate overflow checks), though -the cost is negligible on modern 64-bit machines. For the examples given -earlier, no intermediate overflows would have resulted in exceptions, -since the intermediate results are all in the range of -@code{Long_Long_Integer} (typically 64-bits on nearly all implementations -of GNAT). In addition, if checks are enabled, this reduces the number of -checks that must be made, so this choice may actually result in an -improvement in space and time behavior. - -However, there are cases where @code{Long_Long_Integer} is not large -enough, consider the following example: - -@quotation - -@example -procedure R (A, B, C, D : Integer) with - Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; -@end example -@end quotation - -where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}. -Now the intermediate results are -out of the range of @code{Long_Long_Integer} even though the final result -is in range and the precondition is True (from a mathematical point -of view). In such a case, operating in this mode, an overflow occurs -for the intermediate computation (which is why this mode -says `most' intermediate overflows are avoided). In this case, -an exception is raised if overflow checks are enabled, and the -execution is erroneous if overflow checks are suppressed. - -@item -`All intermediate overflows avoided' (@code{ELIMINATED}) - -In this mode, the compiler avoids all intermediate overflows -by using arbitrary precision arithmetic as required. In this -mode, the above example with @code{A**2 * B**2} would -not cause intermediate overflow, because the intermediate result -would be evaluated using sufficient precision, and the result -of evaluating the precondition would be True. - -This mode has the advantage of avoiding any intermediate -overflows, but at the expense of significant run-time overhead, -including the use of a library (included automatically in this -mode) for multiple-precision arithmetic. - -This mode provides cleaner semantics for assertions, since now -the run-time behavior emulates true arithmetic behavior for the -predefined arithmetic operators, meaning that there is never a -conflict between the mathematical view of the assertion, and its -run-time behavior. - -Note that in this mode, the behavior is unaffected by whether or -not overflow checks are suppressed, since overflow does not occur. -It is possible for gigantic intermediate expressions to raise -@code{Storage_Error} as a result of attempting to compute the -results of such expressions (e.g. @code{Integer'Last ** Integer'Last}) -but overflow is impossible. -@end itemize - -Note that these modes apply only to the evaluation of predefined -arithmetic, membership, and comparison operators for signed integer -arithmetic. - -For fixed-point arithmetic, checks can be suppressed. But if checks -are enabled -then fixed-point values are always checked for overflow against the -base type for intermediate expressions (that is such checks always -operate in the equivalent of @code{STRICT} mode). - -For floating-point, on nearly all architectures, @code{Machine_Overflows} -is False, and IEEE infinities are generated, so overflow exceptions -are never raised. If you want to avoid infinities, and check that -final results of expressions are in range, then you can declare a -constrained floating-point type, and range checks will be carried -out in the normal manner (with infinite values always failing all -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 id48}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9} -@subsection Specifying the Desired Mode - - -@geindex pragma Overflow_Mode - -The desired mode of for handling intermediate overflow can be specified using -either the @code{Overflow_Mode} pragma or an equivalent compiler switch. -The pragma has the form - -@quotation - -@example -pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); -@end example -@end quotation - -where @code{MODE} is one of - - -@itemize * - -@item -@code{STRICT}: intermediate overflows checked (using base type) - -@item -@code{MINIMIZED}: minimize intermediate overflows - -@item -@code{ELIMINATED}: eliminate intermediate overflows -@end itemize - -The case is ignored, so @code{MINIMIZED}, @code{Minimized} and -@code{minimized} all have the same effect. - -If only the @code{General} parameter is present, then the given @code{MODE} applies -to expressions both within and outside assertions. If both arguments -are present, then @code{General} applies to expressions outside assertions, -and @code{Assertions} applies to expressions within assertions. For example: - -@quotation - -@example -pragma Overflow_Mode - (General => Minimized, Assertions => Eliminated); -@end example -@end quotation - -specifies that general expressions outside assertions be evaluated -in ‘minimize intermediate overflows’ mode, and expressions within -assertions be evaluated in ‘eliminate intermediate overflows’ mode. -This is often a reasonable choice, avoiding excessive overhead -outside assertions, but assuring a high degree of portability -when importing code from another compiler, while incurring -the extra overhead for assertion expressions to ensure that -the behavior at run time matches the expected mathematical -behavior. - -The @code{Overflow_Mode} pragma has the same scoping and placement -rules as pragma @code{Suppress}, so it can occur either as a -configuration pragma, specifying a default for the whole -program, or in a declarative scope, where it applies to the -remaining declarations and statements in that scope. - -Note that pragma @code{Overflow_Mode} does not affect whether -overflow checks are enabled or suppressed. It only controls the -method used to compute intermediate values. To control whether -overflow checking is enabled or suppressed, use pragma @code{Suppress} -or @code{Unsuppress} in the usual manner. - -@geindex -gnato? (gcc) - -@geindex -gnato?? (gcc) - -Additionally, a compiler switch @code{-gnato?} or @code{-gnato??} -can be used to control the checking mode default (which can be subsequently -overridden using pragmas). - -Here @code{?} is one of the digits @code{1} through @code{3}: - -@quotation - - -@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -@code{1} - -@tab - -use base type for intermediate operations (@code{STRICT}) - -@item - -@code{2} - -@tab - -minimize intermediate overflows (@code{MINIMIZED}) - -@item - -@code{3} - -@tab - -eliminate intermediate overflows (@code{ELIMINATED}) - -@end multitable - -@end quotation - -As with the pragma, if only one digit appears then it applies to all -cases; if two digits are given, then the first applies outside -assertions, and the second within assertions. Thus the equivalent -of the example pragma above would be -@code{-gnato23}. - -If no digits follow the @code{-gnato}, then it is equivalent to -@code{-gnato11}, -causing all intermediate operations to be computed using the base -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 default-settings}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a4} -@subsection Default Settings - - -The default mode for overflow checks is - -@quotation - -@example -General => Strict -@end example -@end quotation - -which causes all computations both inside and outside assertions to use -the base type. - -This retains compatibility with previous versions of -GNAT which suppressed overflow checks by default and always -used the base type for computation of intermediate results. - -@c Sphinx allows no emphasis within :index: role. As a workaround we -@c point the index to "switch" and use emphasis for "-gnato". - -The -@geindex -gnato (gcc) -switch @code{-gnato} (with no digits following) -is equivalent to - -@quotation - -@example -General => Strict -@end example -@end quotation - -which causes overflow checking of all intermediate overflows -both inside and outside assertions against the base type. - -The pragma @code{Suppress (Overflow_Check)} disables overflow -checking, but it has no effect on the method used for computing -intermediate results. - -The pragma @code{Unsuppress (Overflow_Check)} enables overflow -checking, but it has no effect on the method used for computing -intermediate results. - -@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT -@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a6} -@subsection Implementation Notes - - -In practice on typical 64-bit machines, the @code{MINIMIZED} mode is -reasonably efficient, and can be generally used. It also helps -to ensure compatibility with code imported from some other -compiler to GNAT. - -Setting all intermediate overflows checking (@code{CHECKED} mode) -makes sense if you want to -make sure that your code is compatible with any other possible -Ada implementation. This may be useful in ensuring portability -for code that is to be exported to some other compiler than GNAT. - -The Ada standard allows the reassociation of expressions at -the same precedence level if no parentheses are present. For -example, @code{A+B+C} parses as though it were @code{(A+B)+C}, but -the compiler can reintepret this as @code{A+(B+C)}, possibly -introducing or eliminating an overflow exception. The GNAT -compiler never takes advantage of this freedom, and the -expression @code{A+B+C} will be evaluated as @code{(A+B)+C}. -If you need the other order, you can write the parentheses -explicitly @code{A+(B+C)} and GNAT will respect this order. - -The use of @code{ELIMINATED} mode will cause the compiler to -automatically include an appropriate arbitrary precision -integer arithmetic package. The compiler will make calls -to this package, though only in cases where it cannot be -sure that @code{Long_Long_Integer} is sufficient to guard against -intermediate overflows. This package does not use dynamic -allocation, but it does use the secondary stack, so an -appropriate secondary stack package must be present (this -is always true for standard full Ada, but may require -specific steps for restricted run times such as ZFP). - -Although @code{ELIMINATED} mode causes expressions to use arbitrary -precision arithmetic, avoiding overflow, the final result -must be in an appropriate range. This is true even if the -final result is of type @code{[Long_[Long_]]Integer'Base}, which -still has the same bounds as its associated constrained -type at run-time. - -Currently, the @code{ELIMINATED} mode is only available on target -platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT -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 id51}@anchor{14a}@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7} -@section Performing Dimensionality Analysis in GNAT - - -@geindex Dimensionality analysis - -The GNAT compiler supports dimensionality checking. The user can -specify physical units for objects, and the compiler will verify that uses -of these objects are compatible with their dimensions, in a fashion that is -familiar to engineering practice. The dimensions of algebraic expressions -(including powers with static exponents) are computed from their constituents. - -@geindex Dimension_System aspect - -@geindex Dimension aspect - -This feature depends on Ada 2012 aspect specifications, and is available from -version 7.0.1 of GNAT onwards. -The GNAT-specific aspect @code{Dimension_System} -allows you to define a system of units; the aspect @code{Dimension} -then allows the user to declare dimensioned quantities within a given system. -(These aspects are described in the `Implementation Defined Aspects' -chapter of the `GNAT Reference Manual'). - -The major advantage of this model is that it does not require the declaration of -multiple operators for all possible combinations of types: it is only necessary -to use the proper subtypes in object declarations. - -@geindex System.Dim.Mks package (GNAT library) - -@geindex MKS_Type type - -The simplest way to impose dimensionality checking on a computation is to make -use of one of the instantiations of the package @code{System.Dim.Generic_Mks}, which -are part of the GNAT library. This generic package defines a floating-point -type @code{MKS_Type}, for which a sequence of dimension names are specified, -together with their conventional abbreviations. The following should be read -together with the full specification of the package, in file -@code{s-digemk.ads}. - -@quotation - -@geindex s-digemk.ads file - -@example -type Mks_Type is new Float_Type - with - Dimension_System => ( - (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), - (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), - (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), - (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), - (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), - (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), - (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); -@end example -@end quotation - -The package then defines a series of subtypes that correspond to these -conventional units. For example: - -@quotation - -@example -subtype Length is Mks_Type - with - Dimension => (Symbol => 'm', Meter => 1, others => 0); -@end example -@end quotation - -and similarly for @code{Mass}, @code{Time}, @code{Electric_Current}, -@code{Thermodynamic_Temperature}, @code{Amount_Of_Substance}, and -@code{Luminous_Intensity} (the standard set of units of the SI system). - -The package also defines conventional names for values of each unit, for -example: - -@quotation - -@example -m : constant Length := 1.0; -kg : constant Mass := 1.0; -s : constant Time := 1.0; -A : constant Electric_Current := 1.0; -@end example -@end quotation - -as well as useful multiples of these units: - -@quotation - -@example - cm : constant Length := 1.0E-02; - g : constant Mass := 1.0E-03; - min : constant Time := 60.0; - day : constant Time := 60.0 * 24.0 * min; -... -@end example -@end quotation - -There are three instantiations of @code{System.Dim.Generic_Mks} defined in the -GNAT library: - - -@itemize * - -@item -@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}. - -@item -@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}. - -@item -@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}. -@end itemize - -Using one of these packages, you can then define a derived unit by providing -the aspect that specifies its dimensions within the MKS system, as well as the -string to be used for output of a value of that unit: - -@quotation - -@example -subtype Acceleration is Mks_Type - with Dimension => ("m/sec^2", - Meter => 1, - Second => -2, - others => 0); -@end example -@end quotation - -Here is a complete example of use: - -@quotation - -@example -with System.Dim.MKS; use System.Dim.Mks; -with System.Dim.Mks_IO; use System.Dim.Mks_IO; -with Text_IO; use Text_IO; -procedure Free_Fall is - subtype Acceleration is Mks_Type - with Dimension => ("m/sec^2", 1, 0, -2, others => 0); - G : constant acceleration := 9.81 * m / (s ** 2); - T : Time := 10.0*s; - Distance : Length; - -begin - Put ("Gravitational constant: "); - Put (G, Aft => 2, Exp => 0); Put_Line (""); - Distance := 0.5 * G * T ** 2; - Put ("distance travelled in 10 seconds of free fall "); - Put (Distance, Aft => 2, Exp => 0); - Put_Line (""); -end Free_Fall; -@end example -@end quotation - -Execution of this program yields: - -@quotation - -@example -Gravitational constant: 9.81 m/sec^2 -distance travelled in 10 seconds of free fall 490.50 m -@end example -@end quotation - -However, incorrect assignments such as: - -@quotation - -@example -Distance := 5.0; -Distance := 5.0 * kg; -@end example -@end quotation - -are rejected with the following diagnoses: - -@quotation - -@example -Distance := 5.0; - >>> dimensions mismatch in assignment - >>> left-hand side has dimension [L] - >>> right-hand side is dimensionless - -Distance := 5.0 * kg: - >>> dimensions mismatch in assignment - >>> left-hand side has dimension [L] - >>> right-hand side has dimension [M] -@end example -@end quotation - -The dimensions of an expression are properly displayed, even if there is -no explicit subtype for it. If we add to the program: - -@quotation - -@example -Put ("Final velocity: "); -Put (G * T, Aft =>2, Exp =>0); -Put_Line (""); -@end example -@end quotation - -then the output includes: - -@quotation - -@example -Final velocity: 98.10 m.s**(-1) -@end example - -@geindex Dimensionable type - -@geindex Dimensioned subtype -@end quotation - -The type @code{Mks_Type} is said to be a `dimensionable type' since it has a -@code{Dimension_System} aspect, and the subtypes @code{Length}, @code{Mass}, etc., -are said to be `dimensioned subtypes' since each one has a @code{Dimension} -aspect. - -@quotation - -@geindex Dimension Vector (for a dimensioned subtype) - -@geindex Dimension aspect - -@geindex Dimension_System aspect -@end quotation - -The @code{Dimension} aspect of a dimensioned subtype @code{S} defines a mapping -from the base type’s Unit_Names to integer (or, more generally, rational) -values. This mapping is the `dimension vector' (also referred to as the -`dimensionality') for that subtype, denoted by @code{DV(S)}, and thus for each -object of that subtype. Intuitively, the value specified for each -@code{Unit_Name} is the exponent associated with that unit; a zero value -means that the unit is not used. For example: - -@quotation - -@example -declare - Acc : Acceleration; - ... -begin - ... -end; -@end example -@end quotation - -Here @code{DV(Acc)} = @code{DV(Acceleration)} = -@code{(Meter=>1, Kilogram=>0, Second=>-2, Ampere=>0, Kelvin=>0, Mole=>0, Candela=>0)}. -Symbolically, we can express this as @code{Meter / Second**2}. - -The dimension vector of an arithmetic expression is synthesized from the -dimension vectors of its components, with compile-time dimensionality checks -that help prevent mismatches such as using an @code{Acceleration} where a -@code{Length} is required. - -The dimension vector of the result of an arithmetic expression `expr', or -@code{DV(@var{expr})}, is defined as follows, assuming conventional -mathematical definitions for the vector operations that are used: - - -@itemize * - -@item -If `expr' is of the type `universal_real', or is not of a dimensioned subtype, -then `expr' is dimensionless; @code{DV(@var{expr})} is the empty vector. - -@item -@code{DV(@var{op expr})}, where `op' is a unary operator, is @code{DV(@var{expr})} - -@item -@code{DV(@var{expr1 op expr2})} where `op' is “+” or “-” is @code{DV(@var{expr1})} -provided that @code{DV(@var{expr1})} = @code{DV(@var{expr2})}. -If this condition is not met then the construct is illegal. - -@item -@code{DV(@var{expr1} * @var{expr2})} is @code{DV(@var{expr1})} + @code{DV(@var{expr2})}, -and @code{DV(@var{expr1} / @var{expr2})} = @code{DV(@var{expr1})} - @code{DV(@var{expr2})}. -In this context if one of the `expr's is dimensionless then its empty -dimension vector is treated as @code{(others => 0)}. - -@item -@code{DV(@var{expr} ** @var{power})} is `power' * @code{DV(@var{expr})}, -provided that `power' is a static rational value. If this condition is not -met then the construct is illegal. -@end itemize - -Note that, by the above rules, it is illegal to use binary “+” or “-” to -combine a dimensioned and dimensionless value. Thus an expression such as -@code{acc-10.0} is illegal, where @code{acc} is an object of subtype -@code{Acceleration}. - -The dimensionality checks for relationals use the same rules as -for “+” and “-”, except when comparing to a literal; thus - -@quotation - -@example -acc > len -@end example -@end quotation - -is equivalent to - -@quotation - -@example -acc-len > 0.0 -@end example -@end quotation - -and is thus illegal, but - -@quotation - -@example -acc > 10.0 -@end example -@end quotation - -is accepted with a warning. Analogously a conditional expression requires the -same dimension vector for each branch (with no exception for literals). - -The dimension vector of a type conversion @code{T(@var{expr})} is defined -as follows, based on the nature of @code{T}: - - -@itemize * - -@item -If @code{T} is a dimensioned subtype then @code{DV(T(@var{expr}))} is @code{DV(T)} -provided that either `expr' is dimensionless or -@code{DV(T)} = @code{DV(@var{expr})}. The conversion is illegal -if `expr' is dimensioned and @code{DV(@var{expr})} /= @code{DV(T)}. -Note that vector equality does not require that the corresponding -Unit_Names be the same. - -As a consequence of the above rule, it is possible to convert between -different dimension systems that follow the same international system -of units, with the seven physical components given in the standard order -(length, mass, time, etc.). Thus a length in meters can be converted to -a length in inches (with a suitable conversion factor) but cannot be -converted, for example, to a mass in pounds. - -@item -If @code{T} is the base type for `expr' (and the dimensionless root type of -the dimension system), then @code{DV(T(@var{expr}))} is @code{DV(expr)}. -Thus, if `expr' is of a dimensioned subtype of @code{T}, the conversion may -be regarded as a “view conversion” that preserves dimensionality. - -This rule makes it possible to write generic code that can be instantiated -with compatible dimensioned subtypes. The generic unit will contain -conversions that will consequently be present in instantiations, but -conversions to the base type will preserve dimensionality and make it -possible to write generic code that is correct with respect to -dimensionality. - -@item -Otherwise (i.e., @code{T} is neither a dimensioned subtype nor a dimensionable -base type), @code{DV(T(@var{expr}))} is the empty vector. Thus a dimensioned -value can be explicitly converted to a non-dimensioned subtype, which -of course then escapes dimensionality analysis. -@end itemize - -The dimension vector for a type qualification @code{T'(@var{expr})} is the same -as for the type conversion @code{T(@var{expr})}. - -An assignment statement - -@quotation - -@example -Source := Target; -@end example -@end quotation - -requires @code{DV(Source)} = @code{DV(Target)}, and analogously for parameter -passing (the dimension vector for the actual parameter must be equal to the -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 id52}@anchor{14b}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8} -@section Stack Related Facilities - - -This section describes some useful tools associated with stack -checking and analysis. In -particular, it deals with dynamic and static stack usage measurements. - -@menu -* Stack Overflow Checking:: -* Static Stack Usage Analysis:: -* Dynamic Stack Usage Analysis:: - -@end menu - -@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities -@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 - - -@geindex Stack Overflow Checking - -@geindex -fstack-check (gcc) - -For most operating systems, @code{gcc} does not perform stack overflow -checking by default. This means that if the main environment task or -some other task exceeds the available stack space, then unpredictable -behavior will occur. Most native systems offer some level of protection by -adding a guard page at the end of each task stack. This mechanism is usually -not enough for dealing properly with stack overflow situations because -a large local variable could “jump” above the guard page. -Furthermore, when the -guard page is hit, there may not be any space left on the stack for executing -the exception propagation code. Enabling stack checking avoids -such situations. - -To activate stack checking, compile all units with the @code{gcc} option -@code{-fstack-check}. For example: - -@quotation - -@example -$ gcc -c -fstack-check package1.adb -@end example -@end quotation - -Units compiled with this option will generate extra instructions to check -that any use of the stack (for procedure calls or for declaring local -variables in declare blocks) does not exceed the available stack space. -If the space is exceeded, then a @code{Storage_Error} exception is raised. - -For declared tasks, the default stack size is defined by the GNAT runtime, -whose size may be modified at bind time through the @code{-d} bind switch -(@ref{110,,Switches for gnatbind}). Task specific stack sizes may be set using the -@code{Storage_Size} pragma. - -For the environment task, the stack size is determined by the operating system. -Consequently, to modify the size of the environment task please refer to your -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{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6} -@subsection Static Stack Usage Analysis - - -@geindex Static Stack Usage Analysis - -@geindex -fstack-usage - -A unit compiled with @code{-fstack-usage} will generate an extra file -that specifies -the maximum amount of stack used, on a per-function basis. -The file has the same -basename as the target object file with a @code{.su} extension. -Each line of this file is made up of three fields: - - -@itemize * - -@item -The name of the function. - -@item -A number of bytes. - -@item -One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. -@end itemize - -The second field corresponds to the size of the known part of the function -frame. - -The qualifier @code{static} means that the function frame size -is purely static. -It usually means that all local variables have a static size. -In this case, the second field is a reliable measure of the function stack -utilization. - -The qualifier @code{dynamic} means that the function frame size is not static. -It happens mainly when some local variables have a dynamic size. When this -qualifier appears alone, the second field is not a reliable measure -of the function stack analysis. When it is qualified with @code{bounded}, it -means that the second field is a reliable maximum of the function stack -utilization. - -A unit compiled with @code{-Wstack-usage} will issue a warning for each -subprogram whose stack usage might be larger than the specified amount of -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 dynamic-stack-usage-analysis}@anchor{113}@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab} -@subsection Dynamic Stack Usage Analysis - - -It is possible to measure the maximum amount of stack used by a task, by -adding a switch to @code{gnatbind}, as: - -@quotation - -@example -$ gnatbind -u0 file -@end example -@end quotation - -With this option, at each task termination, its stack usage is output on -@code{stderr}. -Note that this switch is not compatible with tools like -Valgrind and DrMemory; they will report errors. - -It is not always convenient to output the stack usage when the program -is still running. Hence, it is possible to delay this output until program -termination. for a given number of tasks specified as the argument of the -@code{-u} option. For instance: - -@quotation - -@example -$ gnatbind -u100 file -@end example -@end quotation - -will buffer the stack usage information of the first 100 tasks to terminate and -output this info at program termination. Results are displayed in four -columns: - -@quotation - -@example -Index | Task Name | Stack Size | Stack Usage -@end example -@end quotation - -where: - - -@itemize * - -@item -`Index' is a number associated with each task. - -@item -`Task Name' is the name of the task analyzed. - -@item -`Stack Size' is the maximum size for the stack. - -@item -`Stack Usage' is the measure done by the stack analyzer. -In order to prevent overflow, the stack -is not entirely analyzed, and it’s not possible to know exactly how -much has actually been used. -@end itemize - -By default the environment task stack, the stack that contains the main unit, -is not processed. To enable processing of the environment task stack, the -environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of -the environment task stack. This amount is given in kilobytes. For example: - -@quotation - -@example -$ set GNAT_STACK_LIMIT 1600 -@end example -@end quotation - -would specify to the analyzer that the environment task stack has a limit -of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis. - -The package @code{GNAT.Task_Stack_Usage} provides facilities to get -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{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac} -@section Memory Management Issues - - -This section describes some useful memory pools provided in the GNAT library -and in particular the GNAT Debug Pool facility, which can be used to detect -incorrect uses of access values (including ‘dangling references’). - - -@menu -* Some Useful Memory Pools:: -* The GNAT Debug Pool Facility:: - -@end menu - -@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues -@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 - - -@geindex Memory Pool - -@geindex storage -@geindex pool - -The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool -storage pool. Allocations use the standard system call @code{malloc} while -deallocations use the standard system call @code{free}. No reclamation is -performed when the pool goes out of scope. For performance reasons, the -standard default Ada allocators/deallocators do not use any explicit storage -pools but if they did, they could use this storage pool without any change in -behavior. That is why this storage pool is used when the user -manages to make the default implicit allocator explicit as in this example: - -@quotation - -@example -type T1 is access Something; - -- no Storage pool is defined for T2 - -type T2 is access Something_Else; -for T2'Storage_Pool use T1'Storage_Pool; --- the above is equivalent to -for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; -@end example -@end quotation - -The @code{System.Pool_Local} package offers the @code{Unbounded_Reclaim_Pool} storage -pool. The allocation strategy is similar to @code{Pool_Local} -except that the all -storage allocated with this pool is reclaimed when the pool object goes out of -scope. This pool provides a explicit mechanism similar to the implicit one -provided by several Ada 83 compilers for allocations performed through a local -access type and whose purpose was to reclaim memory when exiting the -scope of a given local access. As an example, the following program does not -leak memory even though it does not perform explicit deallocation: - -@quotation - -@example -with System.Pool_Local; -procedure Pooloc1 is - procedure Internal is - type A is access Integer; - X : System.Pool_Local.Unbounded_Reclaim_Pool; - for A'Storage_Pool use X; - v : A; - begin - for I in 1 .. 50 loop - v := new Integer; - end loop; - end Internal; -begin - for I in 1 .. 100 loop - Internal; - end loop; -end Pooloc1; -@end example -@end quotation - -The @code{System.Pool_Size} package implements the @code{Stack_Bounded_Pool} used when -@code{Storage_Size} is specified for an access type. -The whole storage for the pool is -allocated at once, usually on the stack at the point where the access type is -elaborated. It is automatically reclaimed when exiting the scope where the -access type is defined. This package is not intended to be used directly by the -user and it is implicitly used for each such declaration: - -@quotation - -@example -type T1 is access Something; -for T1'Storage_Size use 10_000; -@end example -@end quotation - -@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues -@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 - - -@geindex Debug Pool - -@geindex storage -@geindex pool -@geindex memory corruption - -The use of unchecked deallocation and unchecked conversion can easily -lead to incorrect memory references. The problems generated by such -references are usually difficult to tackle because the symptoms can be -very remote from the origin of the problem. In such cases, it is -very helpful to detect the problem as early as possible. This is the -purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}. - -In order to use the GNAT specific debugging pool, the user must -associate a debug pool object with each of the access types that may be -related to suspected memory problems. See Ada Reference Manual 13.11. - -@quotation - -@example -type Ptr is access Some_Type; -Pool : GNAT.Debug_Pools.Debug_Pool; -for Ptr'Storage_Pool use Pool; -@end example -@end quotation - -@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of -pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools, -allow the user to redefine allocation and deallocation strategies. They -also provide a checkpoint for each dereference, through the use of -the primitive operation @code{Dereference} which is implicitly called at -each dereference of an access value. - -Once an access type has been associated with a debug pool, operations on -values of the type may raise four distinct exceptions, -which correspond to four potential kinds of memory corruption: - - -@itemize * - -@item -@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} - -@item -@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage} - -@item -@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} - -@item -@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage} -@end itemize - -For types associated with a Debug_Pool, dynamic allocation is performed using -the standard GNAT allocation routine. References to all allocated chunks of -memory are kept in an internal dictionary. Several deallocation strategies are -provided, whereupon the user can choose to release the memory to the system, -keep it allocated for further invalid access checks, or fill it with an easily -recognizable pattern for debug sessions. The memory pattern is the old IBM -hexadecimal convention: @code{16#DEADBEEF#}. - -See the documentation in the file g-debpoo.ads for more information on the -various strategies. - -Upon each dereference, a check is made that the access value denotes a -properly allocated memory location. Here is a complete example of use of -@code{Debug_Pools}, that includes typical instances of memory corruption: - -@quotation - -@example -with GNAT.IO; use GNAT.IO; -with Ada.Unchecked_Deallocation; -with Ada.Unchecked_Conversion; -with GNAT.Debug_Pools; -with System.Storage_Elements; -with Ada.Exceptions; use Ada.Exceptions; -procedure Debug_Pool_Test is - - type T is access Integer; - type U is access all T; - - P : GNAT.Debug_Pools.Debug_Pool; - for T'Storage_Pool use P; - - procedure Free is new Ada.Unchecked_Deallocation (Integer, T); - function UC is new Ada.Unchecked_Conversion (U, T); - A, B : aliased T; - - procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); - -begin - Info (P); - A := new Integer; - B := new Integer; - B := A; - Info (P); - Free (A); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - B := UC(A'Access); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - Info (P); -end Debug_Pool_Test; -@end example -@end quotation - -The debug pool mechanism provides the following precise diagnostics on the -execution of this erroneous program: - -@quotation - -@example -Debug Pool info: - Total allocated bytes : 0 - Total deallocated bytes : 0 - Current Water Mark: 0 - High Water Mark: 0 - -Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 0 - Current Water Mark: 8 - High Water Mark: 8 - -raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE -raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE -raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE -raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE -Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 4 - Current Water Mark: 4 - High Water Mark: 8 -@end example -@end quotation - - -@c -- Non-breaking space in running text -@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 doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d} -@chapter Platform-Specific Information - - -This appendix contains information relating to the implementation -of run-time libraries on various platforms and also covers -topics related to the GNAT implementation on Windows and Mac OS. - -@menu -* Run-Time Libraries:: -* Specifying a Run-Time Library:: -* GNU/Linux Topics:: -* Microsoft Windows Topics:: -* Mac OS Topics:: - -@end menu - -@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information -@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4} -@section Run-Time Libraries - - -@geindex Tasking and threads libraries - -@geindex Threads libraries and tasking - -@geindex Run-time libraries (platform-specific information) - -The GNAT run-time implementation may vary with respect to both the -underlying threads library and the exception-handling scheme. -For threads support, the default run-time will bind to the thread -package of the underlying operating system. - -For exception handling, either or both of two models are supplied: - -@quotation - -@geindex Zero-Cost Exceptions - -@geindex ZCX (Zero-Cost Exceptions) -@end quotation - - -@itemize * - -@item -`Zero-Cost Exceptions' (“ZCX”), -which uses binder-generated tables that -are interrogated at run time to locate a handler. - -@geindex setjmp/longjmp Exception Model - -@geindex SJLJ (setjmp/longjmp Exception Model) - -@item -`setjmp / longjmp' (‘SJLJ’), -which uses dynamically-set data to establish -the set of handlers -@end itemize - -Most programs should experience a substantial speed improvement by -being compiled with a ZCX run-time. -This is especially true for -tasking applications or applications with many exception handlers. -Note however that the ZCX run-time does not support asynchronous abort -of tasks (@code{abort} and @code{select-then-abort} constructs) and will instead -implement abort by polling points in the runtime. You can also add additional -polling points explicitly if needed in your application via @code{pragma -Abort_Defer}. - -This section summarizes which combinations of threads and exception support -are supplied on various GNAT platforms. - -@menu -* Summary of Run-Time Configurations:: - -@end menu - -@node Summary of Run-Time Configurations,,,Run-Time Libraries -@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b6} -@subsection Summary of Run-Time Configurations - - - -@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} -@headitem - -Platform - -@tab - -Run-Time - -@tab - -Tasking - -@tab - -Exceptions - -@item - -GNU/Linux - -@tab - -rts-native -(default) - -@tab - -pthread library - -@tab - -ZCX - -@item - -rts-sjlj - -@tab - -pthread library - -@tab - -SJLJ - -@item - -Windows - -@tab - -rts-native -(default) - -@tab - -native Win32 threads - -@tab - -ZCX - -@item - -rts-sjlj - -@tab - -native Win32 threads - -@tab - -SJLJ - -@item - -Mac OS - -@tab - -rts-native - -@tab - -pthread library - -@tab - -ZCX - -@end multitable - - -@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information -@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b8} -@section Specifying a Run-Time Library - - -The @code{adainclude} subdirectory containing the sources of the GNAT -run-time library, and the @code{adalib} subdirectory containing the -@code{ALI} files and the static and/or shared GNAT library, are located -in the gcc target-dependent area: - -@quotation - -@example -target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/ -@end example -@end quotation - -As indicated above, on some platforms several run-time libraries are supplied. -These libraries are installed in the target dependent area and -contain a complete source and binary subdirectory. The detailed description -below explains the differences between the different libraries in terms of -their thread support. - -The default run-time library (when GNAT is installed) is `rts-native'. -This default run-time is selected by the means of soft links. -For example on x86-linux: - -@c -- -@c -- $(target-dir) -@c -- | -@c -- +--- adainclude----------+ -@c -- | | -@c -- +--- adalib-----------+ | -@c -- | | | -@c -- +--- rts-native | | -@c -- | | | | -@c -- | +--- adainclude <---+ -@c -- | | | -@c -- | +--- adalib <----+ -@c -- | -@c -- +--- rts-sjlj -@c -- | -@c -- +--- adainclude -@c -- | -@c -- +--- adalib - - -@example - $(target-dir) - __/ / \ \___ - _______/ / \ \_________________ - / / \ \ - / / \ \ -ADAINCLUDE ADALIB rts-native rts-sjlj - : : / \ / \ - : : / \ / \ - : : / \ / \ - : : / \ / \ - +-------------> adainclude adalib adainclude adalib - : ^ - : : - +---------------------+ - - Run-Time Library Directory Structure - (Upper-case names and dotted/dashed arrows represent soft links) -@end example - -If the `rts-sjlj' library is to be selected on a permanent basis, -these soft links can be modified with the following commands: - -@quotation - -@example -$ cd $target -$ rm -f adainclude adalib -$ ln -s rts-sjlj/adainclude adainclude -$ ln -s rts-sjlj/adalib adalib -@end example -@end quotation - -Alternatively, you can specify @code{rts-sjlj/adainclude} in the file -@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in -@code{$target/ada_object_path}. - -@geindex --RTS option - -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{1b9} -@geindex SCHED_FIFO scheduling policy - -@geindex SCHED_RR scheduling policy - -@geindex SCHED_OTHER scheduling policy - -@menu -* Choosing the Scheduling Policy:: - -@end menu - -@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library -@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba} -@subsection Choosing the Scheduling Policy - - -When using a POSIX threads implementation, you have a choice of several -scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}. - -Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO} -or @code{SCHED_RR} requires special (e.g., root) privileges. - -@geindex pragma Time_Slice - -@geindex -T0 option - -@geindex pragma Task_Dispatching_Policy - -By default, GNAT uses the @code{SCHED_OTHER} policy. To specify -@code{SCHED_FIFO}, -you can use one of the following: - - -@itemize * - -@item -@code{pragma Time_Slice (0.0)} - -@item -the corresponding binder option @code{-T0} - -@item -@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} -@end itemize - -To specify @code{SCHED_RR}, -you should use @code{pragma Time_Slice} with a -value greater than 0.0, or else use the corresponding @code{-T} -binder option. - -To make sure a program is running as root, you can put something like -this in a library package body in your application: - -@quotation - -@example -function geteuid return Integer; -pragma Import (C, geteuid, "geteuid"); -Ignore : constant Boolean := - (if geteuid = 0 then True else raise Program_Error with "must be root"); -@end example -@end quotation - -It gets the effective user id, and if it’s not 0 (i.e. root), it raises -Program_Error. Note that if you re running the code in a container, this may -not be sufficient, as you may have sufficient priviledge on the container, -but not on the host machine running the container, so check that you also -have sufficient priviledge for running the container image. - -@geindex Linux - -@geindex GNU/Linux - -@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information -@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bc} -@section GNU/Linux Topics - - -This section describes topics that are specific to GNU/Linux platforms. - -@menu -* Required Packages on GNU/Linux:: -* A GNU/Linux Debug Quirk:: - -@end menu - -@node Required Packages on GNU/Linux,A GNU/Linux Debug Quirk,,GNU/Linux Topics -@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 - - -GNAT requires the C library developer’s package to be installed. -The name of of that package depends on your GNU/Linux distribution: - - -@itemize * - -@item -RedHat, SUSE: @code{glibc-devel}; - -@item -Debian, Ubuntu: @code{libc6-dev} (normally installed by default). -@end itemize - -If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux, -you’ll need the 32-bit version of the following packages: - - -@itemize * - -@item -RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686} - -@item -SUSE: @code{glibc-locale-base-32bit} - -@item -Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5} -@end itemize - -Other GNU/Linux distributions might be choosing a different name -for those packages. - -@node A GNU/Linux Debug Quirk,,Required Packages on GNU/Linux,GNU/Linux Topics -@anchor{gnat_ugn/platform_specific_information a-gnu-linux-debug-quirk}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0} -@subsection A GNU/Linux Debug Quirk - - -On SuSE 15, some kernels have a defect causing issues when debugging -programs using threads or Ada tasks. Due to the lack of documentation -found regarding this kernel issue, we can only provide limited -information about which kernels are impacted: kernel version 5.3.18 is -known to be impacted, and kernels in the 5.14 range or newer are -believed to fix this problem. - -The bug affects the debugging of 32-bit processes on a 64-bit system. -Symptoms can vary: Unexpected @code{SIGABRT} signals being received by -the program, “The futex facility returned an unexpected error code” -error message, and inferior programs hanging indefinitely range among -the symptoms most commonly observed. - -@geindex Windows - -@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information -@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1c2} -@section Microsoft Windows Topics - - -This section describes topics that are specific to the Microsoft Windows -platforms. - - -@menu -* Using GNAT on Windows:: -* Using a network installation of GNAT:: -* CONSOLE and WINDOWS subsystems:: -* Temporary Files:: -* Disabling Command Line Argument Expansion:: -* Windows Socket Timeouts:: -* Mixed-Language Programming on Windows:: -* Windows Specific Add-Ons:: - -@end menu - -@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics -@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c4} -@subsection Using GNAT on Windows - - -One of the strengths of the GNAT technology is that its tool set -(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the -@code{gdb} debugger, etc.) is used in the same way regardless of the -platform. - -On Windows this tool set is complemented by a number of Microsoft-specific -tools that have been provided to facilitate interoperability with Windows -when this is required. With these tools: - - -@itemize * - -@item -You can build applications using the @code{CONSOLE} or @code{WINDOWS} -subsystems. - -@item -You can use any Dynamically Linked Library (DLL) in your Ada code (both -relocatable and non-relocatable DLLs are supported). - -@item -You can build Ada DLLs for use in other applications. These applications -can be written in a language other than Ada (e.g., C, C++, etc). Again both -relocatable and non-relocatable Ada DLLs are supported. - -@item -You can include Windows resources in your Ada application. - -@item -You can use or create COM/DCOM objects. -@end itemize - -Immediately below are listed all known general GNAT-for-Windows restrictions. -Other restrictions about specific features like Windows Resources and DLLs -are listed in separate sections below. - - -@itemize * - -@item -It is not possible to use @code{GetLastError} and @code{SetLastError} -when tasking, protected records, or exceptions are used. In these -cases, in order to implement Ada semantics, the GNAT run-time system -calls certain Win32 routines that set the last error variable to 0 upon -success. It should be possible to use @code{GetLastError} and -@code{SetLastError} when tasking, protected record, and exception -features are not used, but it is not guaranteed to work. - -@item -It is not possible to link against Microsoft C++ libraries except for -import libraries. Interfacing must be done by the mean of DLLs. - -@item -It is possible to link against Microsoft C libraries. Yet the preferred -solution is to use C/C++ compiler that comes with GNAT, since it -doesn’t require having two different development environments and makes the -inter-language debugging experience smoother. - -@item -When the compilation environment is located on FAT32 drives, users may -experience recompilations of the source files that have not changed if -Daylight Saving Time (DST) state has changed since the last time files -were compiled. NTFS drives do not have this problem. - -@item -No components of the GNAT toolset use any entries in the Windows -registry. The only entries that can be created are file associations and -PATH settings, provided the user has chosen to create them at installation -time, as well as some minimal book-keeping information needed to correctly -uninstall or integrate different GNAT products. -@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 id11}@anchor{1c5}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c6} -@subsection Using a network installation of GNAT - - -Make sure the system on which GNAT is installed is accessible from the -current machine, i.e., the install location is shared over the network. -Shared resources are accessed on Windows by means of UNC paths, which -have the format @code{\\\\server\\sharename\\path} - -In order to use such a network installation, simply add the UNC path of the -@code{bin} directory of your GNAT installation in front of your PATH. For -example, if GNAT is installed in @code{\GNAT} directory of a share location -called @code{c-drive} on a machine @code{LOKI}, the following command will -make it available: - -@quotation - -@example -$ path \\loki\c-drive\gnat\bin;%path%` -@end example -@end quotation - -Be aware that every compilation using the network installation results in the -transfer of large amounts of data across the network and will likely cause -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 console-and-windows-subsystems}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c8} -@subsection CONSOLE and WINDOWS subsystems - - -@geindex CONSOLE Subsystem - -@geindex WINDOWS Subsystem - -@geindex -mwindows - -There are two main subsystems under Windows. The @code{CONSOLE} subsystem -(which is the default subsystem) will always create a console when -launching the application. This is not something desirable when the -application has a Windows GUI. To get rid of this console the -application must be using the @code{WINDOWS} subsystem. To do so -the @code{-mwindows} linker option must be specified. - -@quotation - -@example -$ gnatmake winprog -largs -mwindows -@end example -@end quotation - -@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics -@anchor{gnat_ugn/platform_specific_information id13}@anchor{1c9}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1ca} -@subsection Temporary Files - - -@geindex Temporary files - -It is possible to control where temporary files gets created by setting -the -@geindex TMP -@geindex environment variable; TMP -@code{TMP} environment variable. The file will be created: - - -@itemize * - -@item -Under the directory pointed to by the -@geindex TMP -@geindex environment variable; TMP -@code{TMP} environment variable if -this directory exists. - -@item -Under @code{c:\temp}, if the -@geindex TMP -@geindex environment variable; TMP -@code{TMP} environment variable is not -set (or not pointing to a directory) and if this directory exists. - -@item -Under the current working directory otherwise. -@end itemize - -This allows you to determine exactly where the temporary -file will be created. This is particularly useful in networked -environments where you may not have write access to some -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{1cb} -@subsection Disabling Command Line Argument Expansion - - -@geindex Command Line Argument Expansion - -By default, an executable compiled for the Windows platform will do -the following postprocessing on the arguments passed on the command -line: - - -@itemize * - -@item -If the argument contains the characters @code{*} and/or @code{?}, then -file expansion will be attempted. For example, if the current directory -contains @code{a.txt} and @code{b.txt}, then when calling: - -@example -$ my_ada_program *.txt -@end example - -The following arguments will effectively be passed to the main program -(for example when using @code{Ada.Command_Line.Argument}): - -@example -Ada.Command_Line.Argument (1) -> "a.txt" -Ada.Command_Line.Argument (2) -> "b.txt" -@end example - -@item -Filename expansion can be disabled for a given argument by using single -quotes. Thus, calling: - -@example -$ my_ada_program '*.txt' -@end example - -will result in: - -@example -Ada.Command_Line.Argument (1) -> "*.txt" -@end example -@end itemize - -Note that if the program is launched from a shell such as Cygwin Bash -then quote removal might be performed by the shell. - -In some contexts it might be useful to disable this feature (for example if -the program performs its own argument expansion). In order to do this, a C -symbol needs to be defined and set to @code{0}. You can do this by -adding the following code fragment in one of your Ada units: - -@example -Do_Argv_Expansion : Integer := 0; -pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion"); -@end example - -The results of previous examples will be respectively: - -@example -Ada.Command_Line.Argument (1) -> "*.txt" -@end example - -and: - -@example -Ada.Command_Line.Argument (1) -> "'*.txt'" -@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{1cc} -@subsection Windows Socket Timeouts - - -Microsoft Windows desktops older than @code{8.0} and Microsoft Windows Servers -older than @code{2019} set a socket timeout 500 milliseconds longer than the value -set by setsockopt with @code{SO_RCVTIMEO} and @code{SO_SNDTIMEO} options. The GNAT -runtime makes a correction for the difference in the corresponding Windows -versions. For Windows Server starting with version @code{2019}, the user must -provide a manifest file for the GNAT runtime to be able to recognize that -the Windows version does not need the timeout correction. The manifest file -should be located in the same directory as the executable file, and its file -name must match the executable name suffixed by @code{.manifest}. For example, -if the executable name is @code{sock_wto.exe}, then the manifest file name -has to be @code{sock_wto.exe.manifest}. The manifest file must contain at -least the following data: - -@example - - - - - - - - - - - - - - - - - -@end example - -Without the manifest file, the socket timeout is going to be overcorrected on -these Windows Server versions and the actual time is going to be 500 -milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option. -Note that on Microsoft Windows versions where correction is necessary, there -is no way to set a socket timeout shorter than 500 ms. If a socket timeout -shorter than 500 ms is needed on these Windows versions, a call to -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 id14}@anchor{1cd}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1ce} -@subsection Mixed-Language Programming on Windows - - -Developing pure Ada applications on Windows is no different than on -other GNAT-supported platforms. However, when developing or porting an -application that contains a mix of Ada and C/C++, the choice of your -Windows C/C++ development environment conditions your overall -interoperability strategy. - -If you use @code{gcc} or Microsoft C to compile the non-Ada part of -your application, there are no Windows-specific restrictions that -affect the overall interoperability with your Ada code. If you do want -to use the Microsoft tools for your C++ code, you have two choices: - - -@itemize * - -@item -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{1cf,,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{1d0,,Building DLLs with GNAT Project files}) and use the Microsoft -or whatever environment to build your executable. -@end itemize - -In addition to the description about C main in -@ref{2c,,Mixed Language Programming} section, if the C main uses a -stand-alone library it is required on x86-windows to -setup the SEH context. For this the C main must looks like this: - -@quotation - -@example -/* main.c */ -extern void adainit (void); -extern void adafinal (void); -extern void __gnat_initialize(void*); -extern void call_to_ada (void); - -int main (int argc, char *argv[]) -@{ - int SEH [2]; - - /* Initialize the SEH context */ - __gnat_initialize (&SEH); - - adainit(); - - /* Then call Ada services in the stand-alone library */ - - call_to_ada(); - - adafinal(); -@} -@end example -@end quotation - -Note that this is not needed on x86_64-windows where the Windows -native SEH support is used. - -@menu -* Windows Calling Conventions:: -* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. -* Using DLLs with GNAT:: -* Building DLLs with GNAT Project files:: -* Building DLLs with GNAT:: -* Building DLLs with gnatdll:: -* Ada DLLs and Finalization:: -* Creating a Spec for Ada DLLs:: -* GNAT and Windows Resources:: -* Using GNAT DLLs from Microsoft Visual Studio Applications:: -* Debugging a DLL:: -* Setting Stack Size from gnatlink:: -* Setting Heap Size from gnatlink:: - -@end menu - -@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows -@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1d2} -@subsubsection Windows Calling Conventions - - -@geindex Stdcall - -@geindex APIENTRY - -This section pertain only to Win32. On Win64 there is a single native -calling convention. All convention specifiers are ignored on this -platform. - -When a subprogram @code{F} (caller) calls a subprogram @code{G} -(callee), there are several ways to push @code{G}‘s parameters on the -stack and there are several possible scenarios to clean up the stack -upon @code{G}‘s return. A calling convention is an agreed upon software -protocol whereby the responsibilities between the caller (@code{F}) and -the callee (@code{G}) are clearly defined. Several calling conventions -are available for Windows: - - -@itemize * - -@item -@code{C} (Microsoft defined) - -@item -@code{Stdcall} (Microsoft defined) - -@item -@code{Win32} (GNAT specific) - -@item -@code{DLL} (GNAT specific) -@end itemize - -@menu -* C Calling Convention:: -* Stdcall Calling Convention:: -* Win32 Calling Convention:: -* DLL Calling Convention:: - -@end menu - -@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions -@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4} -@subsubsection @code{C} Calling Convention - - -This is the default calling convention used when interfacing to C/C++ -routines compiled with either @code{gcc} or Microsoft Visual C++. - -In the @code{C} calling convention subprogram parameters are pushed on the -stack by the caller from right to left. The caller itself is in charge of -cleaning up the stack after the call. In addition, the name of a routine -with @code{C} calling convention is mangled by adding a leading underscore. - -The name to use on the Ada side when importing (or exporting) a routine -with @code{C} calling convention is the name of the routine. For -instance the C function: - -@quotation - -@example -int get_val (long); -@end example -@end quotation - -should be imported from Ada as follows: - -@quotation - -@example -function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; -pragma Import (C, Get_Val, External_Name => "get_val"); -@end example -@end quotation - -Note that in this particular case the @code{External_Name} parameter could -have been omitted since, when missing, this parameter is taken to be the -name of the Ada entity in lower case. When the @code{Link_Name} parameter -is missing, as in the above example, this parameter is set to be the -@code{External_Name} with a leading underscore. - -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{1d5,,Stdcall Calling Convention}). - -@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions -@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d5} -@subsubsection @code{Stdcall} Calling Convention - - -This convention, which was the calling convention used for Pascal -programs, is used by Microsoft for all the routines in the Win32 API for -efficiency reasons. It must be used to import any routine for which this -convention was specified. - -In the @code{Stdcall} calling convention subprogram parameters are pushed -on the stack by the caller from right to left. The callee (and not the -caller) is in charge of cleaning the stack on routine exit. In addition, -the name of a routine with @code{Stdcall} calling convention is mangled by -adding a leading underscore (as for the @code{C} calling convention) and a -trailing @code{@@@var{nn}}, where @code{nn} is the overall size (in -bytes) of the parameters passed to the routine. - -The name to use on the Ada side when importing a C routine with a -@code{Stdcall} calling convention is the name of the C routine. The leading -underscore and trailing @code{@@@var{nn}} are added automatically by -the compiler. For instance the Win32 function: - -@quotation - -@example -APIENTRY int get_val (long); -@end example -@end quotation - -should be imported from Ada as follows: - -@quotation - -@example -function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; -pragma Import (Stdcall, Get_Val); --- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4" -@end example -@end quotation - -As for the @code{C} calling convention, when the @code{External_Name} -parameter is missing, it is taken to be the name of the Ada entity in lower -case. If instead of writing the above import pragma you write: - -@quotation - -@example -function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; -pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); -@end example -@end quotation - -then the imported routine is @code{_retrieve_val@@4}. However, if instead -of specifying the @code{External_Name} parameter you specify the -@code{Link_Name} as in the following example: - -@quotation - -@example -function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; -pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); -@end example -@end quotation - -then the imported routine is @code{retrieve_val}, that is, there is no -decoration at all. No leading underscore and no Stdcall suffix -@code{@@@var{nn}}. - -This is especially important as in some special cases a DLL’s entry -point name lacks a trailing @code{@@@var{nn}} while the exported -name generated for a call has it. - -It is also possible to import variables defined in a DLL by using an -import pragma for a variable. As an example, if a DLL contains a -variable defined as: - -@quotation - -@example -int my_var; -@end example -@end quotation - -then, to access this variable from Ada you should write: - -@quotation - -@example -My_Var : Interfaces.C.int; -pragma Import (Stdcall, My_Var); -@end example -@end quotation - -Note that to ease building cross-platform bindings this 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 id18}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d8} -@subsubsection @code{Win32} Calling Convention - - -This convention, which is GNAT-specific is fully equivalent to the -@code{Stdcall} calling convention described above. - -@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions -@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information id19}@anchor{1da} -@subsubsection @code{DLL} Calling Convention - - -This convention, which is GNAT-specific is fully equivalent to the -@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 id20}@anchor{1db}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1dc} -@subsubsection Introduction to Dynamic Link Libraries (DLLs) - - -@geindex DLL - -A Dynamically Linked Library (DLL) is a library that can be shared by -several applications running under Windows. A DLL can contain any number of -routines and variables. - -One advantage of DLLs is that you can change and enhance them without -forcing all the applications that depend on them to be relinked or -recompiled. However, you should be aware than all calls to DLL routines are -slower since, as you will understand below, such calls are indirect. - -To illustrate the remainder of this section, suppose that an application -wants to use the services of a DLL @code{API.dll}. To use the services -provided by @code{API.dll} you must statically link against the DLL or -an import library which contains a jump table with an entry for each -routine and variable exported by the DLL. In the Microsoft world this -import library is called @code{API.lib}. When using GNAT this import -library is called either @code{libAPI.dll.a}, @code{libapi.dll.a}, -@code{libAPI.a} or @code{libapi.a} (names are case insensitive). - -After you have linked your application with the DLL or the import library -and you run your application, here is what happens: - - -@itemize * - -@item -Your application is loaded into memory. - -@item -The DLL @code{API.dll} is mapped into the address space of your -application. This means that: - - -@itemize - - -@item -The DLL will use the stack of the calling thread. - -@item -The DLL will use the virtual address space of the calling process. - -@item -The DLL will allocate memory from the virtual address space of the calling -process. - -@item -Handles (pointers) can be safely exchanged between routines in the DLL -routines and routines in the application using the DLL. -@end itemize - -@item -The entries in the jump table (from the import library @code{libAPI.dll.a} -or @code{API.lib} or automatically created when linking against a DLL) -which is part of your application are initialized with the addresses -of the routines and variables in @code{API.dll}. - -@item -If present in @code{API.dll}, routines @code{DllMain} or -@code{DllMainCRTStartup} are invoked. These routines typically contain -the initialization code needed for the well-being of the routines and -variables exported by the DLL. -@end itemize - -There is an additional point which is worth mentioning. In the Windows -world there are two kind of DLLs: relocatable and non-relocatable -DLLs. Non-relocatable DLLs can only be loaded at a very specific address -in the target application address space. If the addresses of two -non-relocatable DLLs overlap and these happen to be used by the same -application, a conflict will occur and the application will run -incorrectly. Hence, when possible, it is always preferable to use and -build relocatable DLLs. Both relocatable and non-relocatable DLLs are -supported by GNAT. Note that the @code{-s} linker option (see GNU Linker -User’s Guide) removes the debugging symbols from the DLL but the DLL can -still be relocated. - -As a side note, an interesting difference between Microsoft DLLs and -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{1dd,,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 id21}@anchor{1de}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cf} -@subsubsection Using DLLs with GNAT - - -To use the services of a DLL, say @code{API.dll}, in your Ada application -you must have: - - -@itemize * - -@item -The Ada spec for the routines and/or variables you want to access in -@code{API.dll}. If not available this Ada spec must be built from the C/C++ -header files provided with the DLL. - -@item -The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously -mentioned an import library is a statically linked library containing the -import table which will be filled at load time to point to the actual -@code{API.dll} routines. Sometimes you don’t have an import library for the -DLL you want to use. The following sections will explain how to build -one. Note that this is optional. - -@item -The actual DLL, @code{API.dll}. -@end itemize - -Once you have all the above, to compile an Ada application that uses the -services of @code{API.dll} and whose main subprogram is @code{My_Ada_App}, -you simply issue the command - -@quotation - -@example -$ gnatmake my_ada_app -largs -lAPI -@end example -@end quotation - -The argument @code{-largs -lAPI} at the end of the @code{gnatmake} command -tells the GNAT linker to look for an import library. The linker will -look for a library name in this specific order: - - -@itemize * - -@item -@code{libAPI.dll.a} - -@item -@code{API.dll.a} - -@item -@code{libAPI.a} - -@item -@code{API.lib} - -@item -@code{libAPI.dll} - -@item -@code{API.dll} -@end itemize - -The first three are the GNU style import libraries. The third is the -Microsoft style import libraries. The last two are the actual DLL names. - -Note that if the Ada package spec for @code{API.dll} contains the -following pragma - -@quotation - -@example -pragma Linker_Options ("-lAPI"); -@end example -@end quotation - -you do not have to add @code{-largs -lAPI} at the end of the -@code{gnatmake} command. - -If any one of the items above is missing you will have to create it -yourself. The following sections explain how to do so using as an -example a fictitious DLL called @code{API.dll}. - -@menu -* Creating an Ada Spec for the DLL Services:: -* Creating an Import Library:: - -@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 creating-an-ada-spec-for-the-dll-services}@anchor{1df}@anchor{gnat_ugn/platform_specific_information id22}@anchor{1e0} -@subsubsection Creating an Ada Spec for the DLL Services - - -A DLL typically comes with a C/C++ header file which provides the -definitions of the routines and variables exported by the DLL. The Ada -equivalent of this header file is a package spec that contains definitions -for the imported entities. If the DLL you intend to use does not come with -an Ada spec you have to generate one such spec yourself. For example if -the header file of @code{API.dll} is a file @code{api.h} containing the -following two definitions: - -@quotation - -@example -int some_var; -int get (char *); -@end example -@end quotation - -then the equivalent Ada spec could be: - -@quotation - -@example -with Interfaces.C.Strings; -package API is - use Interfaces; - - Some_Var : C.int; - function Get (Str : C.Strings.Chars_Ptr) return C.int; - -private - pragma Import (C, Get); - pragma Import (DLL, Some_Var); -end API; -@end example -@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 creating-an-import-library}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e2} -@subsubsection Creating an Import Library - - -@geindex Import library - -If a Microsoft-style import library @code{API.lib} or a GNAT-style -import library @code{libAPI.dll.a} or @code{libAPI.a} is available -with @code{API.dll} you can skip this section. You can also skip this -section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools -as in this case it is possible to link directly against the -DLL. Otherwise read on. - -@geindex Definition file -@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1dd} -@subsubheading The Definition File - - -As previously mentioned, and unlike Unix systems, the list of symbols -that are exported from a DLL must be provided explicitly in Windows. -The main goal of a definition file is precisely that: list the symbols -exported by a DLL. A definition file (usually a file with a @code{.def} -suffix) has the following structure: - -@quotation - -@example -[LIBRARY `@w{`}name`@w{`}] -[DESCRIPTION `@w{`}string`@w{`}] -EXPORTS - `@w{`}symbol1`@w{`} - `@w{`}symbol2`@w{`} - ... -@end example -@end quotation - - -@table @asis - -@item `LIBRARY name' - -This section, which is optional, gives the name of the DLL. - -@item `DESCRIPTION string' - -This section, which is optional, gives a description string that will be -embedded in the import library. - -@item `EXPORTS' - -This section gives the list of exported symbols (procedures, functions or -variables). For instance in the case of @code{API.dll} the @code{EXPORTS} -section of @code{API.def} looks like: - -@example -EXPORTS - some_var - get -@end example -@end table - -Note that you must specify the correct suffix (@code{@@@var{nn}}) -(see @ref{1d2,,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{1e3} -@subsubheading Creating a Definition File Automatically - - -You can automatically create the definition file @code{API.def} -(see @ref{1dd,,The Definition File}) from a DLL. -For that use the @code{dlltool} program as follows: - -@quotation - -@example -$ dlltool API.dll -z API.def --export-all-symbols -@end example - -Note that if some routines in the DLL have the @code{Stdcall} convention -(@ref{1d2,,Windows Calling Conventions}) with stripped @code{@@@var{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. - -Here are some hints to find the right @code{@@@var{nn}} suffix. - - -@itemize - - -@item -If you have the Microsoft import library (.lib), it is possible to get -the right symbols by using Microsoft @code{dumpbin} tool (see the -corresponding Microsoft documentation for further details). - -@example -$ dumpbin /exports api.lib -@end example - -@item -If you have a message about a missing symbol at link time the compiler -tells you what symbol is expected. You just have to go back to the -definition file and add the right suffix. -@end itemize -@end quotation -@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e4} -@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{1e5,,Using gnatdll}) as follows: - -@quotation - -@example -$ gnatdll -e API.def -d API.dll -@end example - -@code{gnatdll} takes as input a definition file @code{API.def} and the -name of the DLL containing the services listed in the definition file -@code{API.dll}. The name of the static import library generated is -computed from the name of the definition file as follows: if the -definition file name is @code{xyz.def}, the import library name will -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{1e5,,Using gnatdll} for more information about @code{gnatdll}). -@end quotation -@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e6} -@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{1ce,,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 -Microsoft’s @code{lib} utility: - -@quotation - -@example -$ lib -machine:IX86 -def:API.def -out:API.lib -@end example - -If you use the above command the definition file @code{API.def} must -contain a line giving the name of the DLL: - -@example -LIBRARY "API" -@end example - -See the Microsoft documentation for further details about the usage of -@code{lib}. -@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 building-dlls-with-gnat-project-files}@anchor{1d0}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7} -@subsubsection Building DLLs with GNAT Project files - - -@geindex DLLs -@geindex building - -There is nothing specific to Windows in the build process. -See the `Library Projects' section in the `GNAT Project Manager' -chapter of the `GPRbuild User’s Guide'. - -Due to a system limitation, it is not possible under Windows to create threads -when inside the @code{DllMain} routine which is used for auto-initialization -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{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9} -@subsubsection Building DLLs with GNAT - - -@geindex DLLs -@geindex building - -This section explain how to build DLLs using the GNAT built-in DLL -support. With the following procedure it is straight forward to build -and use DLLs with GNAT. - - -@itemize * - -@item -Building object files. -The first step is to build all objects files that are to be included -into the DLL. This is done by using the standard @code{gnatmake} tool. - -@item -Building the DLL. -To build the DLL you must use the @code{gcc} @code{-shared} and -@code{-shared-libgcc} options. It is quite simple to use this method: - -@example -$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ... -@end example - -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{1dd,,The Definition File}). -For example: - -@example -$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ... -@end example - -If you use a definition file you must export the elaboration procedures -for every package that required one. Elaboration procedures are named -using the package name followed by “_E”. - -@item -Preparing DLL to be used. -For the DLL to be used by client programs the bodies must be hidden -from it and the .ali set with read-only attribute. This is very important -otherwise GNAT will recompile all packages and will not actually use -the code in the DLL. For example: - -@example -$ mkdir apilib -$ copy *.ads *.ali api.dll apilib -$ attrib +R apilib\\*.ali -@end example -@end itemize - -At this point it is possible to use the DLL by directly linking -against it. Note that you must use the GNAT shared runtime when using -GNAT shared libraries. This is achieved by using the @code{-shared} binder -option. - -@quotation - -@example -$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI -@end 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{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1eb} -@subsubsection Building DLLs with gnatdll - - -@geindex DLLs -@geindex building - -Note that it is preferred to use GNAT Project files -(@ref{1d0,,Building DLLs with GNAT Project files}) or the built-in GNAT -DLL support (@ref{1e8,,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 -remainder of this section. - -The steps required to build an Ada DLL that is to be used by Ada as well as -non-Ada applications are as follows: - - -@itemize * - -@item -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{1ec,,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{1ed,,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{1ee,,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 spec for the services exported by the Ada DLL in each -of the programming languages to which you plan to make the DLL available. - -@item -You must provide a definition file listing the exported entities -(@ref{1dd,,The Definition File}). - -@item -Finally you must use @code{gnatdll} to produce the DLL and the import -library (@ref{1e5,,Using gnatdll}). -@end itemize - -Note that a relocatable DLL stripped using the @code{strip} -binutils tool will not be relocatable anymore. To build a DLL without -debug information pass @code{-largs -s} to @code{gnatdll}. This -restriction does not apply to a DLL built using a Library Project. -See the `Library Projects' section in the `GNAT Project Manager' -chapter of the `GPRbuild User’s Guide'. - -@c Limitations_When_Using_Ada_DLLs_from Ada: - -@menu -* Limitations When Using Ada DLLs from Ada:: -* Exporting Ada Entities:: -* Ada DLLs and Elaboration:: - -@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{1ef} -@subsubsection Limitations When Using Ada DLLs from Ada - - -When using Ada DLLs from Ada applications there is a limitation users -should be aware of. Because on Windows the GNAT run-time is not in a DLL of -its own, each Ada DLL includes a part of the GNAT run-time. Specifically, -each Ada DLL includes the services of the GNAT run-time that are necessary -to the Ada code inside the DLL. As a result, when an Ada program uses an -Ada DLL there are two independent GNAT run-times: one in the Ada DLL and -one in the main program. - -It is therefore not possible to exchange GNAT run-time objects between the -Ada DLL and the main Ada program. Example of GNAT run-time objects are file -handles (e.g., @code{Text_IO.File_Type}), tasks types, protected objects -types, etc. - -It is completely safe to exchange plain elementary, array or record types, -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{1ec}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0} -@subsubsection Exporting Ada Entities - - -@geindex Export table - -Building a DLL is a way to encapsulate a set of services usable from any -application. As a result, the Ada entities exported by a DLL should be -exported with the @code{C} or @code{Stdcall} calling conventions to avoid -any Ada name mangling. As an example here is an Ada package -@code{API}, spec and body, exporting two procedures, a function, and a -variable: - -@quotation - -@example -with Interfaces.C; use Interfaces; -package API is - Count : C.int := 0; - function Factorial (Val : C.int) return C.int; - - procedure Initialize_API; - procedure Finalize_API; - -- Initialization & Finalization routines. More in the next section. -private - pragma Export (C, Initialize_API); - pragma Export (C, Finalize_API); - pragma Export (C, Count); - pragma Export (C, Factorial); -end API; -@end example - -@example -package body API is - function Factorial (Val : C.int) return C.int is - Fact : C.int := 1; - begin - Count := Count + 1; - for K in 1 .. Val loop - Fact := Fact * K; - end loop; - return Fact; - end Factorial; - - procedure Initialize_API is - procedure Adainit; - pragma Import (C, Adainit); - begin - Adainit; - end Initialize_API; - - procedure Finalize_API is - procedure Adafinal; - pragma Import (C, Adafinal); - begin - Adafinal; - end Finalize_API; -end API; -@end example -@end quotation - -If the Ada DLL you are building will only be used by Ada applications -you do not have to export Ada entities with a @code{C} or @code{Stdcall} -convention. As an example, the previous package could be written as -follows: - -@quotation - -@example -package API is - Count : Integer := 0; - function Factorial (Val : Integer) return Integer; - - procedure Initialize_API; - procedure Finalize_API; - -- Initialization and Finalization routines. -end API; -@end example - -@example -package body API is - function Factorial (Val : Integer) return Integer is - Fact : Integer := 1; - begin - Count := Count + 1; - for K in 1 .. Val loop - Fact := Fact * K; - end loop; - return Fact; - end Factorial; - - ... - -- The remainder of this package body is unchanged. -end API; -@end example -@end quotation - -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{1f1,,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{1ed}@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f2} -@subsubsection Ada DLLs and Elaboration - - -@geindex DLLs and elaboration - -The DLL that you are building contains your Ada code as well as all the -routines in the Ada library that are needed by it. The first thing a -user of your DLL must do is elaborate the Ada code -(@ref{f,,Elaboration Order Handling in GNAT}). - -To achieve this you must export an initialization routine -(@code{Initialize_API} in the previous example), which must be invoked -before using any of the DLL services. This elaboration routine must call -the Ada elaboration routine @code{adainit} generated by the GNAT binder -(@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{1e5,,Using gnatdll}). - -When a DLL is loaded, Windows systematically invokes a routine called -@code{DllMain}. It would therefore be possible to call @code{adainit} -directly from @code{DllMain} without having to provide an explicit -initialization routine. Unfortunately, it is not possible to call -@code{adainit} from the @code{DllMain} if your program has library level -tasks because access to the @code{DllMain} entry point is serialized by -the system (that is, only a single thread can execute ‘through’ it at a -time), which means that the GNAT run-time will deadlock waiting for the -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 ada-dlls-and-finalization}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f3} -@subsubsection Ada DLLs and Finalization - - -@geindex DLLs and finalization - -When the services of an Ada DLL are no longer needed, the client code should -invoke the DLL finalization routine, if available. The DLL finalization -routine is in charge of releasing all resources acquired by the DLL. In the -case of the Ada code contained in the DLL, this is achieved by calling -routine @code{adafinal} generated by the GNAT binder -(@ref{a0,,Binding with Non-Ada Main Programs}). -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{1e5,,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 creating-a-spec-for-ada-dlls}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f5} -@subsubsection Creating a Spec for Ada DLLs - - -To use the services exported by the Ada DLL from another programming -language (e.g., C), you have to translate the specs of the exported Ada -entities in that language. For instance in the case of @code{API.dll}, -the corresponding C header file could look like: - -@quotation - -@example -extern int *_imp__count; -#define count (*_imp__count) -int factorial (int); -@end example -@end quotation - -It is important to understand that when building an Ada DLL to be used by -other Ada applications, you need two different specs for the packages -contained in the DLL: one for building the DLL and the other for using -the DLL. This is because the @code{DLL} calling convention is needed to -use a variable defined in a DLL, but when building the DLL, the variable -must have either the @code{Ada} or @code{C} calling convention. As an -example consider a DLL comprising the following package @code{API}: - -@quotation - -@example -package API is - Count : Integer := 0; - ... - -- Remainder of the package omitted. -end API; -@end example -@end quotation - -After producing a DLL containing package @code{API}, the spec that -must be used to import @code{API.Count} from Ada code outside of the -DLL is: - -@quotation - -@example -package API is - Count : Integer; - pragma Import (DLL, Count); -end API; -@end example -@end quotation - -@menu -* Creating the Definition File:: -* Using gnatdll:: - -@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{1f1}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f6} -@subsubsection Creating the Definition File - - -The definition file is the last file needed to build the DLL. It lists -the exported symbols. As an example, the definition file for a DLL -containing only package @code{API} (where all the entities are exported -with a @code{C} calling convention) is: - -@quotation - -@example -EXPORTS - count - factorial - finalize_api - initialize_api -@end example -@end quotation - -If the @code{C} calling convention is missing from package @code{API}, -then the definition file contains the mangled Ada names of the above -entities, which in this case are: - -@quotation - -@example -EXPORTS - api__count - api__factorial - api__finalize_api - api__initialize_api -@end example -@end quotation - -@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs -@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e5} -@subsubsection Using @code{gnatdll} - - -@geindex gnatdll - -@code{gnatdll} is a tool to automate the DLL build process once all the Ada -and non-Ada sources that make up your DLL have been compiled. -@code{gnatdll} is actually in charge of two distinct tasks: build the -static import library for the DLL and the actual DLL. The form of the -@code{gnatdll} command is - -@quotation - -@example -$ gnatdll [ switches ] list-of-files [ -largs opts ] -@end example -@end quotation - -where @code{list-of-files} is a list of ALI and object files. The object -file list must be the exact list of objects corresponding to the non-Ada -sources whose services are to be included in the DLL. The ALI file list -must be the exact list of ALI files for the corresponding Ada sources -whose services are to be included in the DLL. If @code{list-of-files} is -missing, only the static import library is generated. - -You may specify any of the following switches to @code{gnatdll}: - -@quotation - -@geindex -a (gnatdll) -@end quotation - - -@table @asis - -@item @code{-a[`address']} - -Build a non-relocatable DLL at @code{address}. If @code{address} is not -specified the default address @code{0x11000000} will be used. By default, -when this switch is missing, @code{gnatdll} builds relocatable DLL. We -advise the reader to build relocatable DLL. - -@geindex -b (gnatdll) - -@item @code{-b `address'} - -Set the relocatable DLL base address. By default the address is -@code{0x11000000}. - -@geindex -bargs (gnatdll) - -@item @code{-bargs `opts'} - -Binder options. Pass @code{opts} to the binder. - -@geindex -d (gnatdll) - -@item @code{-d `dllfile'} - -@code{dllfile} is the name of the DLL. This switch must be present for -@code{gnatdll} to do anything. The name of the generated import library is -obtained algorithmically from @code{dllfile} as shown in the following -example: if @code{dllfile} is @code{xyz.dll}, the import library name is -@code{libxyz.dll.a}. The name of the definition file to use (if not specified -by option @code{-e}) is obtained algorithmically from @code{dllfile} -as shown in the following example: -if @code{dllfile} is @code{xyz.dll}, the definition -file used is @code{xyz.def}. - -@geindex -e (gnatdll) - -@item @code{-e `deffile'} - -@code{deffile} is the name of the definition file. - -@geindex -g (gnatdll) - -@item @code{-g} - -Generate debugging information. This information is stored in the object -file and copied from there to the final DLL file by the linker, -where it can be read by the debugger. You must use the -@code{-g} switch if you plan on using the debugger or the symbolic -stack traceback. - -@geindex -h (gnatdll) - -@item @code{-h} - -Help mode. Displays @code{gnatdll} switch usage information. - -@geindex -I (gnatdll) - -@item @code{-I`dir'} - -Direct @code{gnatdll} to search the @code{dir} directory for source and -object files needed to build the DLL. -(@ref{73,,Search Paths and the Run-Time Library (RTL)}). - -@geindex -k (gnatdll) - -@item @code{-k} - -Removes the @code{@@@var{nn}} suffix from the import library’s exported -names, but keeps them for the link names. You must specify this -option if you want to use a @code{Stdcall} function in a DLL for which -the @code{@@@var{nn}} suffix has been removed. This is the case for most -of the Windows NT DLL for example. This option has no effect when -@code{-n} option is specified. - -@geindex -l (gnatdll) - -@item @code{-l `file'} - -The list of ALI and object files used to build the DLL are listed in -@code{file}, instead of being given in the command line. Each line in -@code{file} contains the name of an ALI or object file. - -@geindex -n (gnatdll) - -@item @code{-n} - -No Import. Do not create the import library. - -@geindex -q (gnatdll) - -@item @code{-q} - -Quiet mode. Do not display unnecessary messages. - -@geindex -v (gnatdll) - -@item @code{-v} - -Verbose mode. Display extra information. - -@geindex -largs (gnatdll) - -@item @code{-largs `opts'} - -Linker options. Pass @code{opts} to the linker. -@end table - -@subsubheading @code{gnatdll} Example - - -As an example the command to build a relocatable DLL from @code{api.adb} -once @code{api.adb} has been compiled and @code{api.def} created is - -@quotation - -@example -$ gnatdll -d api.dll api.ali -@end example -@end quotation - -The above command creates two files: @code{libapi.dll.a} (the import -library) and @code{api.dll} (the actual DLL). If you want to create -only the DLL, just type: - -@quotation - -@example -$ gnatdll -d api.dll -n api.ali -@end example -@end quotation - -Alternatively if you want to create just the import library, type: - -@quotation - -@example -$ gnatdll -d api.dll -@end example -@end quotation - -@subsubheading @code{gnatdll} behind the Scenes - - -This section details the steps involved in creating a DLL. @code{gnatdll} -does these steps for you. Unless you are interested in understanding what -goes on behind the scenes, you should skip this section. - -We use the previous example of a DLL containing the Ada package @code{API}, -to illustrate the steps necessary to build a DLL. The starting point is a -set of objects that will make up the DLL and the corresponding ALI -files. In the case of this example this means that @code{api.o} and -@code{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does -the following: - - -@itemize * - -@item -@code{gnatdll} builds the base file (@code{api.base}). A base file gives -the information necessary to generate relocation information for the -DLL. - -@example -$ gnatbind -n api -$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base -@end example - -In addition to the base file, the @code{gnatlink} command generates an -output file @code{api.jnk} which can be discarded. The @code{-mdll} switch -asks @code{gnatlink} to generate the routines @code{DllMain} and -@code{DllMainCRTStartup} that are called by the Windows loader when the DLL -is loaded into memory. - -@item -@code{gnatdll} uses @code{dlltool} (see @ref{1f8,,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. - -@example -$ dlltool --dllname api.dll --def api.def --base-file api.base \\ - --output-exp api.exp -@end example - -@item -@code{gnatdll} builds the base file using the new export table. Note that -@code{gnatbind} must be called once again since the binder generated file -has been deleted during the previous call to @code{gnatlink}. - -@example -$ gnatbind -n api -$ gnatlink api -o api.jnk api.exp -mdll - -Wl,--base-file,api.base -@end example - -@item -@code{gnatdll} builds the new export table using the new base file and -generates the DLL import library @code{libAPI.dll.a}. - -@example -$ dlltool --dllname api.dll --def api.def --base-file api.base \\ - --output-exp api.exp --output-lib libAPI.a -@end example - -@item -Finally @code{gnatdll} builds the relocatable DLL using the final export -table. - -@example -$ gnatbind -n api -$ gnatlink api api.exp -o api.dll -mdll -@end example -@end itemize -@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f8} -@subsubheading Using @code{dlltool} - - -@code{dlltool} is the low-level tool used by @code{gnatdll} to build -DLLs and static import libraries. This section summarizes the most -common @code{dlltool} switches. The form of the @code{dlltool} command -is - -@quotation - -@example -$ dlltool [`switches`] -@end example -@end quotation - -@code{dlltool} switches include: - -@geindex --base-file (dlltool) - - -@table @asis - -@item @code{--base-file `basefile'} - -Read the base file @code{basefile} generated by the linker. This switch -is used to create a relocatable DLL. -@end table - -@geindex --def (dlltool) - - -@table @asis - -@item @code{--def `deffile'} - -Read the definition file. -@end table - -@geindex --dllname (dlltool) - - -@table @asis - -@item @code{--dllname `name'} - -Gives the name of the DLL. This switch is used to embed the name of the -DLL in the static import library generated by @code{dlltool} with switch -@code{--output-lib}. -@end table - -@geindex -k (dlltool) - - -@table @asis - -@item @code{-k} - -Kill @code{@@@var{nn}} from exported names -(@ref{1d2,,Windows Calling Conventions} -for a discussion about @code{Stdcall}-style symbols). -@end table - -@geindex --help (dlltool) - - -@table @asis - -@item @code{--help} - -Prints the @code{dlltool} switches with a concise description. -@end table - -@geindex --output-exp (dlltool) - - -@table @asis - -@item @code{--output-exp `exportfile'} - -Generate an export file @code{exportfile}. The export file contains the -export table (list of symbols in the DLL) and is used to create the DLL. -@end table - -@geindex --output-lib (dlltool) - - -@table @asis - -@item @code{--output-lib `libfile'} - -Generate a static import library @code{libfile}. -@end table - -@geindex -v (dlltool) - - -@table @asis - -@item @code{-v} - -Verbose mode. -@end table - -@geindex --as (dlltool) - - -@table @asis - -@item @code{--as `assembler-name'} - -Use @code{assembler-name} as the assembler. The default is @code{as}. -@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{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa} -@subsubsection GNAT and Windows Resources - - -@geindex Resources -@geindex windows - -Resources are an easy way to add Windows specific objects to your -application. The objects that can be added as resources include: - - -@itemize * - -@item -menus - -@item -accelerators - -@item -dialog boxes - -@item -string tables - -@item -bitmaps - -@item -cursors - -@item -icons - -@item -fonts - -@item -version information -@end itemize - -For example, a version information resource can be defined as follow and -embedded into an executable or DLL: - -A version information resource can be used to embed information into an -executable or a DLL. These information can be viewed using the file properties -from the Windows Explorer. Here is an example of a version information -resource: - -@quotation - -@example -1 VERSIONINFO -FILEVERSION 1,0,0,0 -PRODUCTVERSION 1,0,0,0 -BEGIN - BLOCK "StringFileInfo" - BEGIN - BLOCK "080904E4" - BEGIN - VALUE "CompanyName", "My Company Name" - VALUE "FileDescription", "My application" - VALUE "FileVersion", "1.0" - VALUE "InternalName", "my_app" - VALUE "LegalCopyright", "My Name" - VALUE "OriginalFilename", "my_app.exe" - VALUE "ProductName", "My App" - VALUE "ProductVersion", "1.0" - END - END - - BLOCK "VarFileInfo" - BEGIN - VALUE "Translation", 0x809, 1252 - END -END -@end example -@end quotation - -The value @code{0809} (langID) is for the U.K English language and -@code{04E4} (charsetID), which is equal to @code{1252} decimal, for -multilingual. - -This section explains how to build, compile and use resources. Note that this -section does not cover all resource objects, for a complete description see -the corresponding Microsoft documentation. - -@menu -* Building Resources:: -* Compiling Resources:: -* Using Resources:: - -@end menu - -@node Building Resources,Compiling Resources,,GNAT and Windows Resources -@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc} -@subsubsection Building Resources - - -@geindex Resources -@geindex building - -A resource file is an ASCII file. By convention resource files have an -@code{.rc} extension. -The easiest way to build a resource file is to use Microsoft tools -such as @code{imagedit.exe} to build bitmaps, icons and cursors and -@code{dlgedit.exe} to build dialogs. -It is always possible to build an @code{.rc} file yourself by writing a -resource script. - -It is not our objective to explain how to write a resource file. A -complete description of the resource script language can be found in the -Microsoft documentation. - -@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources -@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe} -@subsubsection Compiling Resources - - -@geindex rc - -@geindex windres - -@geindex Resources -@geindex compiling - -This section describes how to build a GNAT-compatible (COFF) object file -containing the resources. This is done using the Resource Compiler -@code{windres} as follows: - -@quotation - -@example -$ windres -i myres.rc -o myres.o -@end example -@end quotation - -By default @code{windres} will run @code{gcc} to preprocess the @code{.rc} -file. You can specify an alternate preprocessor (usually named -@code{cpp.exe}) using the @code{windres} @code{--preprocessor} -parameter. A list of all possible options may be obtained by entering -the command @code{windres} @code{--help}. - -It is also possible to use the Microsoft resource compiler @code{rc.exe} -to produce a @code{.res} file (binary resource file). See the -corresponding Microsoft documentation for further details. In this case -you need to use @code{windres} to translate the @code{.res} file to a -GNAT-compatible object file as follows: - -@quotation - -@example -$ windres -i myres.res -o myres.o -@end example -@end quotation - -@node Using Resources,,Compiling Resources,GNAT and Windows Resources -@anchor{gnat_ugn/platform_specific_information id36}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{200} -@subsubsection Using Resources - - -@geindex Resources -@geindex using - -To include the resource file in your program just add the -GNAT-compatible object file for the resource(s) to the linker -arguments. With @code{gnatmake} this is done by using the @code{-largs} -option: - -@quotation - -@example -$ gnatmake myprog -largs myres.o -@end example -@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{201}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{202} -@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications - - -@geindex Microsoft Visual Studio -@geindex use with GNAT DLLs - -This section describes a common case of mixed GNAT/Microsoft Visual Studio -application development, where the main program is developed using MSVS, and -is linked with a DLL developed using GNAT. Such a mixed application should -be developed following the general guidelines outlined above; below is the -cookbook-style sequence of steps to follow: - - -@enumerate - -@item -First develop and build the GNAT shared library using a library project -(let’s assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}): -@end enumerate - -@quotation - -@example -$ gprbuild -p mylib.gpr -@end example -@end quotation - - -@enumerate 2 - -@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{1e3,,Creating Definition File Automatically}): -@end enumerate - -@quotation - -@example -$ dlltool libmylib.dll -z libmylib.def --export-all-symbols -@end example -@end quotation - - -@enumerate 3 - -@item -Make sure that MSVS command-line tools are accessible on the path. - -@item -Create the Microsoft-style import library (see @ref{1e6,,MSVS-Style Import Library}): -@end enumerate - -@quotation - -@example -$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib -@end example -@end quotation - -If you are using a 64-bit toolchain, the above becomes… - -@quotation - -@example -$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib -@end example -@end quotation - - -@enumerate 5 - -@item -Build the C main -@end enumerate - -@quotation - -@example -$ cl /O2 /MD main.c libmylib.lib -@end example -@end quotation - - -@enumerate 6 - -@item -Before running the executable, make sure you have set the PATH to the DLL, -or copy the DLL into into the directory containing the .exe. -@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 debugging-a-dll}@anchor{203}@anchor{gnat_ugn/platform_specific_information id37}@anchor{204} -@subsubsection Debugging a DLL - - -@geindex DLL debugging - -Debugging a DLL is similar to debugging a standard program. But -we have to deal with two different executable parts: the DLL and the -program that uses it. We have the following four possibilities: - - -@itemize * - -@item -The program and the DLL are built with GCC/GNAT. - -@item -The program is built with foreign tools and the DLL is built with -GCC/GNAT. - -@item -The program is built with GCC/GNAT and the DLL is built with -foreign tools. -@end itemize - -In this section we address only cases one and two above. -There is no point in trying to debug -a DLL with GNU/GDB, if there is no GDB-compatible debugging -information in it. To do so you must use a debugger compatible with the -tools suite used to build the DLL. - -@menu -* Program and DLL Both Built with GCC/GNAT:: -* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: - -@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 id38}@anchor{205}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{206} -@subsubsection Program and DLL Both Built with GCC/GNAT - - -This is the simplest case. Both the DLL and the program have @code{GDB} -compatible debugging information. It is then possible to break anywhere in -the process. Let’s suppose here that the main procedure is named -@code{ada_main} and that in the DLL there is an entry point named -@code{ada_dll}. - -The DLL (@ref{1dc,,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: - - -@itemize * - -@item -Launch @code{GDB} on the main program. - -@example -$ gdb -nw ada_main -@end example - -@item -Start the program and stop at the beginning of the main procedure - -@example -(gdb) start -@end example - -This step is required to be able to set a breakpoint inside the DLL. As long -as the program is not run, the DLL is not loaded. This has the -consequence that the DLL debugging information is also not loaded, so it is not -possible to set a breakpoint in the DLL. - -@item -Set a breakpoint inside the DLL - -@example -(gdb) break ada_dll -(gdb) cont -@end example -@end itemize - -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{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 id39}@anchor{207}@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{208} -@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT - - -In this case things are slightly more complex because it is not possible to -start the main program and then break at the beginning to load the DLL and the -associated DLL debugging information. It is not possible to break at the -beginning of the program because there is no @code{GDB} debugging information, -and therefore there is no direct way of getting initial control. This -section addresses this issue by describing some methods that can be used -to break somewhere in the DLL to debug it. - -First suppose that the main procedure is named @code{main} (this is for -example some C code built with Microsoft Visual C) and that there is a -DLL named @code{test.dll} containing an Ada entry point named -@code{ada_dll}. - -The DLL (see @ref{1dc,,Introduction to Dynamic Link Libraries (DLLs)}) must have -been built with debugging information (see the GNAT @code{-g} option). - -@subsubheading Debugging the DLL Directly - - - -@itemize * - -@item -Find out the executable starting address - -@example -$ objdump --file-header main.exe -@end example - -The starting address is reported on the last line. For example: - -@example -main.exe: file format pei-i386 -architecture: i386, flags 0x0000010a: -EXEC_P, HAS_DEBUG, D_PAGED -start address 0x00401010 -@end example - -@item -Launch the debugger on the executable. - -@example -$ gdb main.exe -@end example - -@item -Set a breakpoint at the starting address, and launch the program. - -@example -$ (gdb) break *0x00401010 -$ (gdb) run -@end example - -The program will stop at the given address. - -@item -Set a breakpoint on a DLL subroutine. - -@example -(gdb) break ada_dll.adb:45 -@end example - -Or if you want to break using a symbol on the DLL, you need first to -select the Ada language (language used by the DLL). - -@example -(gdb) set language ada -(gdb) break ada_dll -@end example - -@item -Continue the program. - -@example -(gdb) cont -@end example - -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{14d,,Running and Debugging Ada Programs}). -@end itemize - -It is also possible to debug the DLL by attaching to a running process. - -@subsubheading Attaching to a Running Process - - -@geindex DLL debugging -@geindex attach to process - -With @code{GDB} it is always possible to debug a running process by -attaching to it. It is possible to debug a DLL this way. The limitation -of this approach is that the DLL must run long enough to perform the -attach operation. It may be useful for instance to insert a time wasting -loop in the code of the DLL to meet this criterion. - - -@itemize * - -@item -Launch the main program @code{main.exe}. - -@example -$ main -@end example - -@item -Use the Windows `Task Manager' to find the process ID. Let’s say -that the process PID for @code{main.exe} is 208. - -@item -Launch gdb. - -@example -$ gdb -@end example - -@item -Attach to the running process to be debugged. - -@example -(gdb) attach 208 -@end example - -@item -Load the process debugging information. - -@example -(gdb) symbol-file main.exe -@end example - -@item -Break somewhere in the DLL. - -@example -(gdb) break ada_dll -@end example - -@item -Continue process execution. - -@example -(gdb) cont -@end example -@end itemize - -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{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 id40}@anchor{209}@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127} -@subsubsection Setting Stack Size from @code{gnatlink} - - -It is possible to specify the program stack size at link time. On modern -versions of Windows, starting with XP, this is mostly useful to set the size of -the main stack (environment task). The other task stacks are set with pragma -Storage_Size or with the `gnatbind -d' command. - -Since older versions of Windows (2000, NT4, etc.) do not allow setting the -reserve size of individual tasks, the link-time stack size applies to all -tasks, and pragma Storage_Size has no effect. -In particular, Stack Overflow checks are made against this -link-time specified size. - -This setting can be done with @code{gnatlink} using either of the following: - - -@itemize * - -@item -@code{-Xlinker} linker option - -@example -$ gnatlink hello -Xlinker --stack=0x10000,0x1000 -@end example - -This sets the stack reserve size to 0x10000 bytes and the stack commit -size to 0x1000 bytes. - -@item -@code{-Wl} linker option - -@example -$ gnatlink hello -Wl,--stack=0x1000000 -@end example - -This sets the stack reserve size to 0x1000000 bytes. Note that with -@code{-Wl} option it is not possible to set the stack commit size -because the comma is a separator for this option. -@end itemize - -@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows -@anchor{gnat_ugn/platform_specific_information id41}@anchor{20a}@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128} -@subsubsection Setting Heap Size from @code{gnatlink} - - -Under Windows systems, it is possible to specify the program heap size from -@code{gnatlink} using either of the following: - - -@itemize * - -@item -@code{-Xlinker} linker option - -@example -$ gnatlink hello -Xlinker --heap=0x10000,0x1000 -@end example - -This sets the heap reserve size to 0x10000 bytes and the heap commit -size to 0x1000 bytes. - -@item -@code{-Wl} linker option - -@example -$ gnatlink hello -Wl,--heap=0x1000000 -@end example - -This sets the heap reserve size to 0x1000000 bytes. Note that with -@code{-Wl} option it is not possible to set the heap commit size -because the comma is a separator for this option. -@end itemize - -@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics -@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{20b}@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{20c} -@subsection Windows Specific Add-Ons - - -This section describes the Windows specific add-ons. - -@menu -* Win32Ada:: -* wPOSIX:: - -@end menu - -@node Win32Ada,wPOSIX,,Windows Specific Add-Ons -@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20e} -@subsubsection Win32Ada - - -Win32Ada is a binding for the Microsoft Win32 API. This binding can be -easily installed from the provided installer. To use the Win32Ada -binding you need to use a project file, and adding a single with_clause -will give you full access to the Win32Ada binding sources and ensure -that the proper libraries are passed to the linker. - -@quotation - -@example -with "win32ada"; -project P is - for Sources use ...; -end P; -@end example -@end quotation - -To build the application you just need to call gprbuild for the -application’s project, here p.gpr: - -@quotation - -@example -gprbuild p.gpr -@end example -@end quotation - -@node wPOSIX,,Win32Ada,Windows Specific Add-Ons -@anchor{gnat_ugn/platform_specific_information id43}@anchor{20f}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{210} -@subsubsection wPOSIX - - -wPOSIX is a minimal POSIX binding whose goal is to help with building -cross-platforms applications. This binding is not complete though, as -the Win32 API does not provide the necessary support for all POSIX APIs. - -To use the wPOSIX binding you need to use a project file, and adding -a single with_clause will give you full access to the wPOSIX binding -sources and ensure that the proper libraries are passed to the linker. - -@quotation - -@example -with "wposix"; -project P is - for Sources use ...; -end P; -@end example -@end quotation - -To build the application you just need to call gprbuild for the -application’s project, here p.gpr: - -@quotation - -@example -gprbuild p.gpr -@end example -@end quotation - -@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information -@anchor{gnat_ugn/platform_specific_information id44}@anchor{211}@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{212} -@section Mac OS Topics - - -@geindex OS X - -This section describes topics that are specific to Apple’s OS X -platform. - -@menu -* Codesigning the Debugger:: - -@end menu - -@node Codesigning the Debugger,,,Mac OS Topics -@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{213} -@subsection Codesigning the Debugger - - -The Darwin Kernel requires the debugger to have special permissions -before it is allowed to control other processes. These permissions -are granted by codesigning the GDB executable. Without these -permissions, the debugger will report error messages such as: - -@example -Starting program: /x/y/foo -Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5). -(please check gdb is codesigned - see taskgated(8)) -@end example - -Codesigning requires a certificate. The following procedure explains -how to create one: - - -@itemize * - -@item -Start the Keychain Access application (in -/Applications/Utilities/Keychain Access.app) - -@item -Select the Keychain Access -> Certificate Assistant -> -Create a Certificate… menu - -@item -Then: - - -@itemize * - -@item -Choose a name for the new certificate (this procedure will use -“gdb-cert” as an example) - -@item -Set “Identity Type” to “Self Signed Root” - -@item -Set “Certificate Type” to “Code Signing” - -@item -Activate the “Let me override defaults” option -@end itemize - -@item -Click several times on “Continue” until the “Specify a Location -For The Certificate” screen appears, then set “Keychain” to “System” - -@item -Click on “Continue” until the certificate is created - -@item -Finally, in the view, double-click on the new certificate, -and set “When using this certificate” to “Always Trust” - -@item -Exit the Keychain Access application and restart the computer -(this is unfortunately required) -@end itemize - -Once a certificate has been created, the debugger can be codesigned -as follow. In a Terminal, run the following command: - -@quotation - -@example -$ codesign -f -s "gdb-cert" /bin/gdb -@end example -@end quotation - -where “gdb-cert” should be replaced by the actual certificate -name chosen above, and should be replaced by -the location where you installed GNAT. Also, be sure that users are -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 doc}@anchor{214}@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{215} -@chapter Example of Binder Output File - - -@geindex Binder output (example) - -This Appendix displays the source code for the output file -generated by `gnatbind' for a simple ‘Hello World’ program. -Comments have been added for clarification purposes. - -@example --- The package is called Ada_Main unless this name is actually used --- as a unit name in the partition, in which case some other unique --- name is used. - -pragma Ada_95; -with System; -package ada_main is - pragma Warnings (Off); - - -- The main program saves the parameters (argument count, - -- argument values, environment pointer) in global variables - -- for later access by other units including - -- Ada.Command_Line. - - gnat_argc : Integer; - gnat_argv : System.Address; - gnat_envp : System.Address; - - -- The actual variables are stored in a library routine. This - -- is useful for some shared library situations, where there - -- are problems if variables are not in the library. - - pragma Import (C, gnat_argc); - pragma Import (C, gnat_argv); - pragma Import (C, gnat_envp); - - -- The exit status is similarly an external location - - gnat_exit_status : Integer; - pragma Import (C, gnat_exit_status); - - GNAT_Version : constant String := - "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL; - pragma Export (C, GNAT_Version, "__gnat_version"); - - Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL; - pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name"); - - -- This is the generated adainit routine that performs - -- initialization at the start of execution. In the case - -- where Ada is the main program, this main program makes - -- a call to adainit at program startup. - - procedure adainit; - pragma Export (C, adainit, "adainit"); - - -- This is the generated adafinal routine that performs - -- finalization at the end of execution. In the case where - -- Ada is the main program, this main program makes a call - -- to adafinal at program termination. - - procedure adafinal; - pragma Export (C, adafinal, "adafinal"); - - -- This routine is called at the start of execution. It is - -- a dummy routine that is used by the debugger to breakpoint - -- at the start of execution. - - -- This is the actual generated main program (it would be - -- suppressed if the no main program switch were used). As - -- required by standard system conventions, this program has - -- the external name main. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer; - pragma Export (C, main, "main"); - - -- The following set of constants give the version - -- identification values for every unit in the bound - -- partition. This identification is computed from all - -- dependent semantic units, and corresponds to the - -- string that would be returned by use of the - -- Body_Version or Version attributes. - - -- The following Export pragmas export the version numbers - -- with symbolic names ending in B (for body) or S - -- (for spec) so that they can be located in a link. The - -- information provided here is sufficient to track down - -- the exact versions of units used in a given build. - - type Version_32 is mod 2 ** 32; - u00001 : constant Version_32 := 16#8ad6e54a#; - pragma Export (C, u00001, "helloB"); - u00002 : constant Version_32 := 16#fbff4c67#; - pragma Export (C, u00002, "system__standard_libraryB"); - u00003 : constant Version_32 := 16#1ec6fd90#; - pragma Export (C, u00003, "system__standard_libraryS"); - u00004 : constant Version_32 := 16#3ffc8e18#; - pragma Export (C, u00004, "adaS"); - u00005 : constant Version_32 := 16#28f088c2#; - pragma Export (C, u00005, "ada__text_ioB"); - u00006 : constant Version_32 := 16#f372c8ac#; - pragma Export (C, u00006, "ada__text_ioS"); - u00007 : constant Version_32 := 16#2c143749#; - pragma Export (C, u00007, "ada__exceptionsB"); - u00008 : constant Version_32 := 16#f4f0cce8#; - pragma Export (C, u00008, "ada__exceptionsS"); - u00009 : constant Version_32 := 16#a46739c0#; - pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB"); - u00010 : constant Version_32 := 16#3aac8c92#; - pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS"); - u00011 : constant Version_32 := 16#1d274481#; - pragma Export (C, u00011, "systemS"); - u00012 : constant Version_32 := 16#a207fefe#; - pragma Export (C, u00012, "system__soft_linksB"); - u00013 : constant Version_32 := 16#467d9556#; - pragma Export (C, u00013, "system__soft_linksS"); - u00014 : constant Version_32 := 16#b01dad17#; - pragma Export (C, u00014, "system__parametersB"); - u00015 : constant Version_32 := 16#630d49fe#; - pragma Export (C, u00015, "system__parametersS"); - u00016 : constant Version_32 := 16#b19b6653#; - pragma Export (C, u00016, "system__secondary_stackB"); - u00017 : constant Version_32 := 16#b6468be8#; - pragma Export (C, u00017, "system__secondary_stackS"); - u00018 : constant Version_32 := 16#39a03df9#; - pragma Export (C, u00018, "system__storage_elementsB"); - u00019 : constant Version_32 := 16#30e40e85#; - pragma Export (C, u00019, "system__storage_elementsS"); - u00020 : constant Version_32 := 16#41837d1e#; - pragma Export (C, u00020, "system__stack_checkingB"); - u00021 : constant Version_32 := 16#93982f69#; - pragma Export (C, u00021, "system__stack_checkingS"); - u00022 : constant Version_32 := 16#393398c1#; - pragma Export (C, u00022, "system__exception_tableB"); - u00023 : constant Version_32 := 16#b33e2294#; - pragma Export (C, u00023, "system__exception_tableS"); - u00024 : constant Version_32 := 16#ce4af020#; - pragma Export (C, u00024, "system__exceptionsB"); - u00025 : constant Version_32 := 16#75442977#; - pragma Export (C, u00025, "system__exceptionsS"); - u00026 : constant Version_32 := 16#37d758f1#; - pragma Export (C, u00026, "system__exceptions__machineS"); - u00027 : constant Version_32 := 16#b895431d#; - pragma Export (C, u00027, "system__exceptions_debugB"); - u00028 : constant Version_32 := 16#aec55d3f#; - pragma Export (C, u00028, "system__exceptions_debugS"); - u00029 : constant Version_32 := 16#570325c8#; - pragma Export (C, u00029, "system__img_intB"); - u00030 : constant Version_32 := 16#1ffca443#; - pragma Export (C, u00030, "system__img_intS"); - u00031 : constant Version_32 := 16#b98c3e16#; - pragma Export (C, u00031, "system__tracebackB"); - u00032 : constant Version_32 := 16#831a9d5a#; - pragma Export (C, u00032, "system__tracebackS"); - u00033 : constant Version_32 := 16#9ed49525#; - pragma Export (C, u00033, "system__traceback_entriesB"); - u00034 : constant Version_32 := 16#1d7cb2f1#; - pragma Export (C, u00034, "system__traceback_entriesS"); - u00035 : constant Version_32 := 16#8c33a517#; - pragma Export (C, u00035, "system__wch_conB"); - u00036 : constant Version_32 := 16#065a6653#; - pragma Export (C, u00036, "system__wch_conS"); - u00037 : constant Version_32 := 16#9721e840#; - pragma Export (C, u00037, "system__wch_stwB"); - u00038 : constant Version_32 := 16#2b4b4a52#; - pragma Export (C, u00038, "system__wch_stwS"); - u00039 : constant Version_32 := 16#92b797cb#; - pragma Export (C, u00039, "system__wch_cnvB"); - u00040 : constant Version_32 := 16#09eddca0#; - pragma Export (C, u00040, "system__wch_cnvS"); - u00041 : constant Version_32 := 16#6033a23f#; - pragma Export (C, u00041, "interfacesS"); - u00042 : constant Version_32 := 16#ece6fdb6#; - pragma Export (C, u00042, "system__wch_jisB"); - u00043 : constant Version_32 := 16#899dc581#; - pragma Export (C, u00043, "system__wch_jisS"); - u00044 : constant Version_32 := 16#10558b11#; - pragma Export (C, u00044, "ada__streamsB"); - u00045 : constant Version_32 := 16#2e6701ab#; - pragma Export (C, u00045, "ada__streamsS"); - u00046 : constant Version_32 := 16#db5c917c#; - pragma Export (C, u00046, "ada__io_exceptionsS"); - u00047 : constant Version_32 := 16#12c8cd7d#; - pragma Export (C, u00047, "ada__tagsB"); - u00048 : constant Version_32 := 16#ce72c228#; - pragma Export (C, u00048, "ada__tagsS"); - u00049 : constant Version_32 := 16#c3335bfd#; - pragma Export (C, u00049, "system__htableB"); - u00050 : constant Version_32 := 16#99e5f76b#; - pragma Export (C, u00050, "system__htableS"); - u00051 : constant Version_32 := 16#089f5cd0#; - pragma Export (C, u00051, "system__string_hashB"); - u00052 : constant Version_32 := 16#3bbb9c15#; - pragma Export (C, u00052, "system__string_hashS"); - u00053 : constant Version_32 := 16#807fe041#; - pragma Export (C, u00053, "system__unsigned_typesS"); - u00054 : constant Version_32 := 16#d27be59e#; - pragma Export (C, u00054, "system__val_lluB"); - u00055 : constant Version_32 := 16#fa8db733#; - pragma Export (C, u00055, "system__val_lluS"); - u00056 : constant Version_32 := 16#27b600b2#; - pragma Export (C, u00056, "system__val_utilB"); - u00057 : constant Version_32 := 16#b187f27f#; - pragma Export (C, u00057, "system__val_utilS"); - u00058 : constant Version_32 := 16#d1060688#; - pragma Export (C, u00058, "system__case_utilB"); - u00059 : constant Version_32 := 16#392e2d56#; - pragma Export (C, u00059, "system__case_utilS"); - u00060 : constant Version_32 := 16#84a27f0d#; - pragma Export (C, u00060, "interfaces__c_streamsB"); - u00061 : constant Version_32 := 16#8bb5f2c0#; - pragma Export (C, u00061, "interfaces__c_streamsS"); - u00062 : constant Version_32 := 16#6db6928f#; - pragma Export (C, u00062, "system__crtlS"); - u00063 : constant Version_32 := 16#4e6a342b#; - pragma Export (C, u00063, "system__file_ioB"); - u00064 : constant Version_32 := 16#ba56a5e4#; - pragma Export (C, u00064, "system__file_ioS"); - u00065 : constant Version_32 := 16#b7ab275c#; - pragma Export (C, u00065, "ada__finalizationB"); - u00066 : constant Version_32 := 16#19f764ca#; - pragma Export (C, u00066, "ada__finalizationS"); - u00067 : constant Version_32 := 16#95817ed8#; - pragma Export (C, u00067, "system__finalization_rootB"); - u00068 : constant Version_32 := 16#52d53711#; - pragma Export (C, u00068, "system__finalization_rootS"); - u00069 : constant Version_32 := 16#769e25e6#; - pragma Export (C, u00069, "interfaces__cB"); - u00070 : constant Version_32 := 16#4a38bedb#; - pragma Export (C, u00070, "interfaces__cS"); - u00071 : constant Version_32 := 16#07e6ee66#; - pragma Export (C, u00071, "system__os_libB"); - u00072 : constant Version_32 := 16#d7b69782#; - pragma Export (C, u00072, "system__os_libS"); - u00073 : constant Version_32 := 16#1a817b8e#; - pragma Export (C, u00073, "system__stringsB"); - u00074 : constant Version_32 := 16#639855e7#; - pragma Export (C, u00074, "system__stringsS"); - u00075 : constant Version_32 := 16#e0b8de29#; - pragma Export (C, u00075, "system__file_control_blockS"); - u00076 : constant Version_32 := 16#b5b2aca1#; - pragma Export (C, u00076, "system__finalization_mastersB"); - u00077 : constant Version_32 := 16#69316dc1#; - pragma Export (C, u00077, "system__finalization_mastersS"); - u00078 : constant Version_32 := 16#57a37a42#; - pragma Export (C, u00078, "system__address_imageB"); - u00079 : constant Version_32 := 16#bccbd9bb#; - pragma Export (C, u00079, "system__address_imageS"); - u00080 : constant Version_32 := 16#7268f812#; - pragma Export (C, u00080, "system__img_boolB"); - u00081 : constant Version_32 := 16#e8fe356a#; - pragma Export (C, u00081, "system__img_boolS"); - u00082 : constant Version_32 := 16#d7aac20c#; - pragma Export (C, u00082, "system__ioB"); - u00083 : constant Version_32 := 16#8365b3ce#; - pragma Export (C, u00083, "system__ioS"); - u00084 : constant Version_32 := 16#6d4d969a#; - pragma Export (C, u00084, "system__storage_poolsB"); - u00085 : constant Version_32 := 16#e87cc305#; - pragma Export (C, u00085, "system__storage_poolsS"); - u00086 : constant Version_32 := 16#e34550ca#; - pragma Export (C, u00086, "system__pool_globalB"); - u00087 : constant Version_32 := 16#c88d2d16#; - pragma Export (C, u00087, "system__pool_globalS"); - u00088 : constant Version_32 := 16#9d39c675#; - pragma Export (C, u00088, "system__memoryB"); - u00089 : constant Version_32 := 16#445a22b5#; - pragma Export (C, u00089, "system__memoryS"); - u00090 : constant Version_32 := 16#6a859064#; - pragma Export (C, u00090, "system__storage_pools__subpoolsB"); - u00091 : constant Version_32 := 16#e3b008dc#; - pragma Export (C, u00091, "system__storage_pools__subpoolsS"); - u00092 : constant Version_32 := 16#63f11652#; - pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB"); - u00093 : constant Version_32 := 16#fe2f4b3a#; - pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS"); - - -- BEGIN ELABORATION ORDER - -- ada%s - -- interfaces%s - -- system%s - -- system.case_util%s - -- system.case_util%b - -- system.htable%s - -- system.img_bool%s - -- system.img_bool%b - -- system.img_int%s - -- system.img_int%b - -- system.io%s - -- system.io%b - -- system.parameters%s - -- system.parameters%b - -- system.crtl%s - -- interfaces.c_streams%s - -- interfaces.c_streams%b - -- system.standard_library%s - -- system.exceptions_debug%s - -- system.exceptions_debug%b - -- system.storage_elements%s - -- system.storage_elements%b - -- system.stack_checking%s - -- system.stack_checking%b - -- system.string_hash%s - -- system.string_hash%b - -- system.htable%b - -- system.strings%s - -- system.strings%b - -- system.os_lib%s - -- system.traceback_entries%s - -- system.traceback_entries%b - -- ada.exceptions%s - -- system.soft_links%s - -- system.unsigned_types%s - -- system.val_llu%s - -- system.val_util%s - -- system.val_util%b - -- system.val_llu%b - -- system.wch_con%s - -- system.wch_con%b - -- system.wch_cnv%s - -- system.wch_jis%s - -- system.wch_jis%b - -- system.wch_cnv%b - -- system.wch_stw%s - -- system.wch_stw%b - -- ada.exceptions.last_chance_handler%s - -- ada.exceptions.last_chance_handler%b - -- system.address_image%s - -- system.exception_table%s - -- system.exception_table%b - -- ada.io_exceptions%s - -- ada.tags%s - -- ada.streams%s - -- ada.streams%b - -- interfaces.c%s - -- system.exceptions%s - -- system.exceptions%b - -- system.exceptions.machine%s - -- system.finalization_root%s - -- system.finalization_root%b - -- ada.finalization%s - -- ada.finalization%b - -- system.storage_pools%s - -- system.storage_pools%b - -- system.finalization_masters%s - -- system.storage_pools.subpools%s - -- system.storage_pools.subpools.finalization%s - -- system.storage_pools.subpools.finalization%b - -- system.memory%s - -- system.memory%b - -- system.standard_library%b - -- system.pool_global%s - -- system.pool_global%b - -- system.file_control_block%s - -- system.file_io%s - -- system.secondary_stack%s - -- system.file_io%b - -- system.storage_pools.subpools%b - -- system.finalization_masters%b - -- interfaces.c%b - -- ada.tags%b - -- system.soft_links%b - -- system.os_lib%b - -- system.secondary_stack%b - -- system.address_image%b - -- system.traceback%s - -- ada.exceptions%b - -- system.traceback%b - -- ada.text_io%s - -- ada.text_io%b - -- hello%b - -- END ELABORATION ORDER - -end ada_main; -@end example - -@example -pragma Ada_95; --- The following source file name pragmas allow the generated file --- names to be unique for different main programs. They are needed --- since the package name will always be Ada_Main. - -pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); -pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); - -pragma Suppress (Overflow_Check); -with Ada.Exceptions; - --- Generated package body for Ada_Main starts here - -package body ada_main is - pragma Warnings (Off); - - -- These values are reference counter associated to units which have - -- been elaborated. It is also used to avoid elaborating the - -- same unit twice. - - E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E"); - E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E"); - E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E"); - E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E"); - E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E"); - E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E"); - E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E"); - E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E"); - E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E"); - E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E"); - E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E"); - E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E"); - E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E"); - E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E"); - E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E"); - E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E"); - E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E"); - E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E"); - - Local_Priority_Specific_Dispatching : constant String := ""; - Local_Interrupt_States : constant String := ""; - - Is_Elaborated : Boolean := False; - - procedure finalize_library is - begin - E06 := E06 - 1; - declare - procedure F1; - pragma Import (Ada, F1, "ada__text_io__finalize_spec"); - begin - F1; - end; - E77 := E77 - 1; - E91 := E91 - 1; - declare - procedure F2; - pragma Import (Ada, F2, "system__file_io__finalize_body"); - begin - E64 := E64 - 1; - F2; - end; - declare - procedure F3; - pragma Import (Ada, F3, "system__file_control_block__finalize_spec"); - begin - E75 := E75 - 1; - F3; - end; - E87 := E87 - 1; - declare - procedure F4; - pragma Import (Ada, F4, "system__pool_global__finalize_spec"); - begin - F4; - end; - declare - procedure F5; - pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec"); - begin - F5; - end; - declare - procedure F6; - pragma Import (Ada, F6, "system__finalization_masters__finalize_spec"); - begin - F6; - end; - declare - procedure Reraise_Library_Exception_If_Any; - pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any"); - begin - Reraise_Library_Exception_If_Any; - end; - end finalize_library; - - ------------- - -- adainit -- - ------------- - - procedure adainit is - - Main_Priority : Integer; - pragma Import (C, Main_Priority, "__gl_main_priority"); - Time_Slice_Value : Integer; - pragma Import (C, Time_Slice_Value, "__gl_time_slice_val"); - WC_Encoding : Character; - pragma Import (C, WC_Encoding, "__gl_wc_encoding"); - Locking_Policy : Character; - pragma Import (C, Locking_Policy, "__gl_locking_policy"); - Queuing_Policy : Character; - pragma Import (C, Queuing_Policy, "__gl_queuing_policy"); - Task_Dispatching_Policy : Character; - pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy"); - Priority_Specific_Dispatching : System.Address; - pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching"); - Num_Specific_Dispatching : Integer; - pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching"); - Main_CPU : Integer; - pragma Import (C, Main_CPU, "__gl_main_cpu"); - Interrupt_States : System.Address; - pragma Import (C, Interrupt_States, "__gl_interrupt_states"); - Num_Interrupt_States : Integer; - pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states"); - Unreserve_All_Interrupts : Integer; - pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts"); - Detect_Blocking : Integer; - pragma Import (C, Detect_Blocking, "__gl_detect_blocking"); - Default_Stack_Size : Integer; - pragma Import (C, Default_Stack_Size, "__gl_default_stack_size"); - Leap_Seconds_Support : Integer; - pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support"); - - procedure Runtime_Initialize; - pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize"); - - Finalize_Library_Objects : No_Param_Proc; - pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects"); - - -- Start of processing for adainit - - begin - - -- Record various information for this partition. The values - -- are derived by the binder from information stored in the ali - -- files by the compiler. - - if Is_Elaborated then - return; - end if; - Is_Elaborated := True; - Main_Priority := -1; - Time_Slice_Value := -1; - WC_Encoding := 'b'; - Locking_Policy := ' '; - Queuing_Policy := ' '; - Task_Dispatching_Policy := ' '; - Priority_Specific_Dispatching := - Local_Priority_Specific_Dispatching'Address; - Num_Specific_Dispatching := 0; - Main_CPU := -1; - Interrupt_States := Local_Interrupt_States'Address; - Num_Interrupt_States := 0; - Unreserve_All_Interrupts := 0; - Detect_Blocking := 0; - Default_Stack_Size := -1; - Leap_Seconds_Support := 0; - - Runtime_Initialize; - - Finalize_Library_Objects := finalize_library'access; - - -- Now we have the elaboration calls for all units in the partition. - -- The Elab_Spec and Elab_Body attributes generate references to the - -- implicit elaboration procedures generated by the compiler for - -- each unit that requires elaboration. Increment a counter of - -- reference for each unit. - - System.Soft_Links'Elab_Spec; - System.Exception_Table'Elab_Body; - E23 := E23 + 1; - Ada.Io_Exceptions'Elab_Spec; - E46 := E46 + 1; - Ada.Tags'Elab_Spec; - Ada.Streams'Elab_Spec; - E45 := E45 + 1; - Interfaces.C'Elab_Spec; - System.Exceptions'Elab_Spec; - E25 := E25 + 1; - System.Finalization_Root'Elab_Spec; - E68 := E68 + 1; - Ada.Finalization'Elab_Spec; - E66 := E66 + 1; - System.Storage_Pools'Elab_Spec; - E85 := E85 + 1; - System.Finalization_Masters'Elab_Spec; - System.Storage_Pools.Subpools'Elab_Spec; - System.Pool_Global'Elab_Spec; - E87 := E87 + 1; - System.File_Control_Block'Elab_Spec; - E75 := E75 + 1; - System.File_Io'Elab_Body; - E64 := E64 + 1; - E91 := E91 + 1; - System.Finalization_Masters'Elab_Body; - E77 := E77 + 1; - E70 := E70 + 1; - Ada.Tags'Elab_Body; - E48 := E48 + 1; - System.Soft_Links'Elab_Body; - E13 := E13 + 1; - System.Os_Lib'Elab_Body; - E72 := E72 + 1; - System.Secondary_Stack'Elab_Body; - E17 := E17 + 1; - Ada.Text_Io'Elab_Spec; - Ada.Text_Io'Elab_Body; - E06 := E06 + 1; - end adainit; - - -------------- - -- adafinal -- - -------------- - - procedure adafinal is - procedure s_stalib_adafinal; - pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal"); - - procedure Runtime_Finalize; - pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize"); - - begin - if not Is_Elaborated then - return; - end if; - Is_Elaborated := False; - Runtime_Finalize; - s_stalib_adafinal; - end adafinal; - - -- We get to the main program of the partition by using - -- pragma Import because if we try to with the unit and - -- call it Ada style, then not only do we waste time - -- recompiling it, but also, we don't really know the right - -- switches (e.g.@@: identifier character set) to be used - -- to compile it. - - procedure Ada_Main_Program; - pragma Import (Ada, Ada_Main_Program, "_ada_hello"); - - ---------- - -- main -- - ---------- - - -- main is actually a function, as in the ANSI C standard, - -- defined to return the exit status. The three parameters - -- are the argument count, argument values and environment - -- pointer. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer - is - -- The initialize routine performs low level system - -- initialization using a standard library routine which - -- sets up signal handling and performs any other - -- required setup. The routine can be found in file - -- a-init.c. - - procedure initialize; - pragma Import (C, initialize, "__gnat_initialize"); - - -- The finalize routine performs low level system - -- finalization using a standard library routine. The - -- routine is found in file a-final.c and in the standard - -- distribution is a dummy routine that does nothing, so - -- really this is a hook for special user finalization. - - procedure finalize; - pragma Import (C, finalize, "__gnat_finalize"); - - -- The following is to initialize the SEH exceptions - - SEH : aliased array (1 .. 2) of Integer; - - Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address; - pragma Volatile (Ensure_Reference); - - -- Start of processing for main - - begin - -- Save global variables - - gnat_argc := argc; - gnat_argv := argv; - gnat_envp := envp; - - -- Call low level system initialization - - Initialize (SEH'Address); - - -- Call our generated Ada initialization routine - - adainit; - - -- Now we call the main program of the partition - - Ada_Main_Program; - - -- Perform Ada finalization - - adafinal; - - -- Perform low level system finalization - - Finalize; - - -- Return the proper exit status - return (gnat_exit_status); - end; - --- This section is entirely comments, so it has no effect on the --- compilation of the Ada_Main package. It provides the list of --- object files and linker options, as well as some standard --- libraries needed for the link. The gnatlink utility parses --- this b~hello.adb file to read these comment lines to generate --- the appropriate command line arguments for the call to the --- system linker. The BEGIN/END lines are used for sentinels for --- this parsing operation. - --- The exact file names will of course depend on the environment, --- host/target and location of files on the host system. - --- BEGIN Object file/option list - -- ./hello.o - -- -L./ - -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ - -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a --- END Object file/option list - -end ada_main; -@end example - -The Ada code in the above example is exactly what is generated by the -binder. We have added comments to more clearly indicate the function -of each part of the generated @code{Ada_Main} package. - -The code is standard Ada in all respects, and can be processed by any -tools that handle Ada. In particular, it is possible to use the debugger -in Ada mode to debug the generated @code{Ada_Main} package. For example, -suppose that for reasons that you do not understand, your program is crashing -during elaboration of the body of @code{Ada.Text_IO}. To locate this bug, -you can place a breakpoint on the call: - -@quotation - -@example -Ada.Text_Io'Elab_Body; -@end example -@end quotation - -and trace the elaboration routine for this package to find out where -the problem might be (more usually of course you would be debugging -elaboration code in your own application). - -@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 doc}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{217} -@chapter Elaboration Order Handling in GNAT - - -@geindex Order of elaboration - -@geindex Elaboration control - -This appendix describes the handling of elaboration code in Ada and GNAT, and -discusses how the order of elaboration of program units can be controlled in -GNAT, either automatically or with explicit programming features. - -@menu -* Elaboration Code:: -* Elaboration Order:: -* Checking the Elaboration Order:: -* Controlling the Elaboration Order in Ada:: -* Controlling the Elaboration Order in GNAT:: -* Mixing Elaboration Models:: -* ABE Diagnostics:: -* SPARK Diagnostics:: -* Elaboration Circularities:: -* Resolving Elaboration Circularities:: -* Elaboration-related Compiler Switches:: -* Summary of Procedures for Elaboration Control:: -* Inspecting the Chosen Elaboration Order:: - -@end menu - -@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT -@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{219} -@section Elaboration Code - - -Ada defines the term `execution' as the process by which a construct achieves -its run-time effect. This process is also referred to as `elaboration' for -declarations and `evaluation' for expressions. - -The execution model in Ada allows for certain sections of an Ada program to be -executed prior to execution of the program itself, primarily with the intent of -initializing data. These sections are referred to as `elaboration code'. -Elaboration code is executed as follows: - - -@itemize * - -@item -All partitions of an Ada program are executed in parallel with one another, -possibly in a separate address space, and possibly on a separate computer. - -@item -The execution of a partition involves running the environment task for that -partition. - -@item -The environment task executes all elaboration code (if available) for all -units within that partition. This code is said to be executed at -`elaboration time'. - -@item -The environment task executes the Ada program (if available) for that -partition. -@end itemize - -In addition to the Ada terminology, this appendix defines the following terms: - - -@itemize * - -@item -`Invocation' - -The act of calling a subprogram, instantiating a generic, or activating a -task. - -@item -`Scenario' - -A construct that is elaborated or invoked by elaboration code is referred to -as an `elaboration scenario' or simply a `scenario'. GNAT recognizes the -following scenarios: - - -@itemize - - -@item -@code{'Access} of entries, operators, and subprograms - -@item -Activation of tasks - -@item -Calls to entries, operators, and subprograms - -@item -Instantiations of generic templates -@end itemize - -@item -`Target' - -A construct elaborated by a scenario is referred to as `elaboration target' -or simply `target'. GNAT recognizes the following targets: - - -@itemize - - -@item -For @code{'Access} of entries, operators, and subprograms, the target is the -entry, operator, or subprogram being aliased. - -@item -For activation of tasks, the target is the task body - -@item -For calls to entries, operators, and subprograms, the target is the entry, -operator, or subprogram being invoked. - -@item -For instantiations of generic templates, the target is the generic template -being instantiated. -@end itemize -@end itemize - -Elaboration code may appear in two distinct contexts: - - -@itemize * - -@item -`Library level' - -A scenario appears at the library level when it is encapsulated by a package -[body] compilation unit, ignoring any other package [body] declarations in -between. - -@example -with Server; -package Client is - procedure Proc; - - package Nested is - Val : ... := Server.Func; - end Nested; -end Client; -@end example - -In the example above, the call to @code{Server.Func} is an elaboration scenario -because it appears at the library level of package @code{Client}. Note that the -declaration of package @code{Nested} is ignored according to the definition -given above. As a result, the call to @code{Server.Func} will be invoked when -the spec of unit @code{Client} is elaborated. - -@item -`Package body statements' - -A scenario appears within the statement sequence of a package body when it is -bounded by the region starting from the @code{begin} keyword of the package body -and ending at the @code{end} keyword of the package body. - -@example -package body Client is - procedure Proc is - begin - ... - end Proc; -begin - Proc; -end Client; -@end example - -In the example above, the call to @code{Proc} is an elaboration scenario because -it appears within the statement sequence of package body @code{Client}. As a -result, the call to @code{Proc} will be invoked when the body of @code{Client} is -elaborated. -@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{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{21b} -@section Elaboration Order - - -The sequence by which the elaboration code of all units within a partition is -executed is referred to as `elaboration order'. - -Within a single unit, elaboration code is executed in sequential order. - -@quotation - -@example -package body Client is - Result : ... := Server.Func; - - procedure Proc is - package Inst is new Server.Gen; - begin - Inst.Eval (Result); - end Proc; -begin - Proc; -end Client; -@end example -@end quotation - -In the example above, the elaboration order within package body @code{Client} is -as follows: - - -@enumerate - -@item -The object declaration of @code{Result} is elaborated. - - -@itemize * - -@item -Function @code{Server.Func} is invoked. -@end itemize - -@item -The subprogram body of @code{Proc} is elaborated. - -@item -Procedure @code{Proc} is invoked. - - -@itemize * - -@item -Generic unit @code{Server.Gen} is instantiated as @code{Inst}. - -@item -Instance @code{Inst} is elaborated. - -@item -Procedure @code{Inst.Eval} is invoked. -@end itemize -@end enumerate - -The elaboration order of all units within a partition depends on the following -factors: - - -@itemize * - -@item -`with'ed units - -@item -parent units - -@item -purity of units - -@item -preelaborability of units - -@item -presence of elaboration-control pragmas - -@item -invocations performed in elaboration code -@end itemize - -A program may have several elaboration orders depending on its structure. - -@quotation - -@example -package Server is - function Func (Index : Integer) return Integer; -end Server; -@end example - -@example -package body Server is - Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5); - - function Func (Index : Integer) return Integer is - begin - return Results (Index); - end Func; -end Server; -@end example - -@example -with Server; -package Client is - Val : constant Integer := Server.Func (3); -end Client; -@end example - -@example -with Client; -procedure Main is begin null; end Main; -@end example -@end quotation - -The following elaboration order exhibits a fundamental problem referred to as -`access-before-elaboration' or simply `ABE'. - -@quotation - -@example -spec of Server -spec of Client -body of Server -body of Main -@end example -@end quotation - -The elaboration of @code{Server}’s spec materializes function @code{Func}, making it -callable. The elaboration of @code{Client}’s spec elaborates the declaration of -@code{Val}. This invokes function @code{Server.Func}, however the body of -@code{Server.Func} has not been elaborated yet because @code{Server}’s body comes -after @code{Client}’s spec in the elaboration order. As a result, the value of -constant @code{Val} is now undefined. - -Without any guarantees from the language, an undetected ABE problem may hinder -proper initialization of data, which in turn may lead to undefined behavior at -run time. To prevent such ABE problems, Ada employs dynamic checks in the same -vein as index or null exclusion checks. A failed ABE check raises exception -@code{Program_Error}. - -The following elaboration order avoids the ABE problem and the program can be -successfully elaborated. - -@quotation - -@example -spec of Server -body of Server -spec of Client -body of Main -@end example -@end quotation - -Ada states that a total elaboration order must exist, but it does not define -what this order is. A compiler is thus tasked with choosing a suitable -elaboration order which satisfies the dependencies imposed by `with' clauses, -unit categorization, elaboration-control pragmas, and invocations performed in -elaboration code. Ideally an order that avoids ABE problems should be chosen, -however a compiler may not always find such an order due to complications with -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 checking-the-elaboration-order}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21d} -@section Checking the Elaboration Order - - -To avoid placing the entire elaboration-order burden on the programmer, Ada -provides three lines of defense: - - -@itemize * - -@item -`Static semantics' - -Static semantic rules restrict the possible choice of elaboration order. For -instance, if unit Client `with's unit Server, then the spec of Server is -always elaborated prior to Client. The same principle applies to child units -- the spec of a parent unit is always elaborated prior to the child unit. - -@item -`Dynamic semantics' - -Dynamic checks are performed at run time, to ensure that a target is -elaborated prior to a scenario that invokes it, thus avoiding ABE problems. -A failed run-time check raises exception @code{Program_Error}. The following -restrictions apply: - - -@itemize - - -@item -`Restrictions on calls' - -An entry, operator, or subprogram can be called from elaboration code only -when the corresponding body has been elaborated. - -@item -`Restrictions on instantiations' - -A generic unit can be instantiated by elaboration code only when the -corresponding body has been elaborated. - -@item -`Restrictions on task activation' - -A task can be activated by elaboration code only when the body of the -associated task type has been elaborated. -@end itemize - -The restrictions above can be summarized by the following rule: - -`If a target has a body, then this body must be elaborated prior to the -scenario that invokes the target.' - -@item -`Elaboration control' - -Pragmas are provided for the programmer to specify the desired 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{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21f} -@section Controlling the Elaboration Order in Ada - - -Ada provides several idioms and pragmas to aid the programmer with specifying -the desired elaboration order and avoiding ABE problems altogether. - - -@itemize * - -@item -`Packages without a body' - -A library package which does not require a completing body does not suffer -from ABE problems. - -@example -package Pack is - generic - type Element is private; - package Containers is - type Element_Array is array (1 .. 10) of Element; - end Containers; -end Pack; -@end example - -In the example above, package @code{Pack} does not require a body because it -does not contain any constructs which require completion in a body. As a -result, generic @code{Pack.Containers} can be instantiated without encountering -any ABE problems. -@end itemize - -@geindex pragma Pure - - -@itemize * - -@item -`pragma Pure' - -Pragma @code{Pure} places sufficient restrictions on a unit to guarantee that no -scenario within the unit can result in an ABE problem. -@end itemize - -@geindex pragma Preelaborate - - -@itemize * - -@item -`pragma Preelaborate' - -Pragma @code{Preelaborate} is slightly less restrictive than pragma @code{Pure}, -but still strong enough to prevent ABE problems within a unit. -@end itemize - -@geindex pragma Elaborate_Body - - -@itemize * - -@item -`pragma Elaborate_Body' - -Pragma @code{Elaborate_Body} requires that the body of a unit is elaborated -immediately after its spec. This restriction guarantees that no client -scenario can invoke a server target before the target body has been -elaborated because the spec and body are effectively “glued” together. - -@example -package Server is - pragma Elaborate_Body; - - function Func return Integer; -end Server; -@end example - -@example -package body Server is - function Func return Integer is - begin - ... - end Func; -end Server; -@end example - -@example -with Server; -package Client is - Val : constant Integer := Server.Func; -end Client; -@end example - -In the example above, pragma @code{Elaborate_Body} guarantees the following -elaboration order: - -@example -spec of Server -body of Server -spec of Client -@end example - -because the spec of @code{Server} must be elaborated prior to @code{Client} by -virtue of the `with' clause, and in addition the body of @code{Server} must be -elaborated immediately after the spec of @code{Server}. - -Removing pragma @code{Elaborate_Body} could result in the following incorrect -elaboration order: - -@example -spec of Server -spec of Client -body of Server -@end example - -where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} has -not been elaborated yet. -@end itemize - -The pragmas outlined above allow a server unit to guarantee safe elaboration -use by client units. Thus it is a good rule to mark units as @code{Pure} or -@code{Preelaborate}, and if this is not possible, mark them as @code{Elaborate_Body}. - -There are however situations where @code{Pure}, @code{Preelaborate}, and -@code{Elaborate_Body} are not applicable. Ada provides another set of pragmas for -use by client units to help ensure the elaboration safety of server units they -depend on. - -@geindex pragma Elaborate (Unit) - - -@itemize * - -@item -`pragma Elaborate (Unit)' - -Pragma @code{Elaborate} can be placed in the context clauses of a unit, after a -`with' clause. It guarantees that both the spec and body of its argument will -be elaborated prior to the unit with the pragma. Note that other unrelated -units may be elaborated in between the spec and the body. - -@example -package Server is - function Func return Integer; -end Server; -@end example - -@example -package body Server is - function Func return Integer is - begin - ... - end Func; -end Server; -@end example - -@example -with Server; -pragma Elaborate (Server); -package Client is - Val : constant Integer := Server.Func; -end Client; -@end example - -In the example above, pragma @code{Elaborate} guarantees the following -elaboration order: - -@example -spec of Server -body of Server -spec of Client -@end example - -Removing pragma @code{Elaborate} could result in the following incorrect -elaboration order: - -@example -spec of Server -spec of Client -body of Server -@end example - -where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} -has not been elaborated yet. -@end itemize - -@geindex pragma Elaborate_All (Unit) - - -@itemize * - -@item -`pragma Elaborate_All (Unit)' - -Pragma @code{Elaborate_All} is placed in the context clauses of a unit, after -a `with' clause. It guarantees that both the spec and body of its argument -will be elaborated prior to the unit with the pragma, as well as all units -`with'ed by the spec and body of the argument, recursively. Note that other -unrelated units may be elaborated in between the spec and the body. - -@example -package Math is - function Factorial (Val : Natural) return Natural; -end Math; -@end example - -@example -package body Math is - function Factorial (Val : Natural) return Natural is - begin - ...; - end Factorial; -end Math; -@end example - -@example -package Computer is - type Operation_Kind is (None, Op_Factorial); - - function Compute - (Val : Natural; - Op : Operation_Kind) return Natural; -end Computer; -@end example - -@example -with Math; -package body Computer is - function Compute - (Val : Natural; - Op : Operation_Kind) return Natural - is - if Op = Op_Factorial then - return Math.Factorial (Val); - end if; - - return 0; - end Compute; -end Computer; -@end example - -@example -with Computer; -pragma Elaborate_All (Computer); -package Client is - Val : constant Natural := - Computer.Compute (123, Computer.Op_Factorial); -end Client; -@end example - -In the example above, pragma @code{Elaborate_All} can result in the following -elaboration order: - -@example -spec of Math -body of Math -spec of Computer -body of Computer -spec of Client -@end example - -Note that there are several allowable suborders for the specs and bodies of -@code{Math} and @code{Computer}, but the point is that these specs and bodies will -be elaborated prior to @code{Client}. - -Removing pragma @code{Elaborate_All} could result in the following incorrect -elaboration order: - -@example -spec of Math -spec of Computer -body of Computer -spec of Client -body of Math -@end example - -where @code{Client} invokes @code{Computer.Compute}, which in turn invokes -@code{Math.Factorial}, but the body of @code{Math.Factorial} has not been -elaborated yet. -@end itemize - -All pragmas shown above can be summarized by the following rule: - -`If a client unit elaborates a server target directly or indirectly, then if -the server unit requires a body and does not have pragma Pure, Preelaborate, -or Elaborate_Body, then the client unit should have pragma Elaborate or -Elaborate_All for the server unit.' - -If the rule outlined above is not followed, then a program may fall in one of -the following states: - - -@itemize * - -@item -`No elaboration order exists' - -In this case a compiler must diagnose the situation, and refuse to build an -executable program. - -@item -`One or more incorrect elaboration orders exist' - -In this case a compiler can build an executable program, but -@code{Program_Error} will be raised when the program is run. - -@item -`Several elaboration orders exist, some correct, some incorrect' - -In this case the programmer has not controlled the elaboration order. As a -result, a compiler may or may not pick one of the correct orders, and the -program may or may not raise @code{Program_Error} when it is run. This is the -worst possible state because the program may fail on another compiler, or -even another version of the same compiler. - -@item -`One or more correct orders exist' - -In this case a compiler can build an executable program, and the program is -run successfully. This state may be guaranteed by following the outlined -rules, or may be the result of good program architecture. -@end itemize - -Note that one additional advantage of using @code{Elaborate} and @code{Elaborate_All} -is that the program continues to stay in the last state (one or more correct -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 controlling-the-elaboration-order-in-gnat}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{221} -@section Controlling the Elaboration Order in GNAT - - -In addition to Ada semantics and rules synthesized from them, GNAT offers -three elaboration models to aid the programmer with specifying the correct -elaboration order and to diagnose elaboration problems. - -@geindex Dynamic elaboration model - - -@itemize * - -@item -`Dynamic elaboration model' - -This is the most permissive of the three elaboration models and emulates the -behavior specified by the Ada Reference Manual. When the dynamic model is in -effect, GNAT makes the following assumptions: - - -@itemize - - -@item -All code within all units in a partition is considered to be elaboration -code. - -@item -Some of the invocations in elaboration code may not take place at run time -due to conditional execution. -@end itemize - -GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios -that invoke internal targets. In addition, GNAT generates run-time checks for -all external targets and for all scenarios that may exhibit ABE problems. - -The elaboration order is obtained by honoring all `with' clauses, purity and -preelaborability of units, and elaboration-control pragmas. The dynamic model -attempts to take all invocations in elaboration code into account. If an -invocation leads to a circularity, GNAT ignores the invocation based on the -assumptions stated above. An order obtained using the dynamic model may fail -an ABE check at run time when GNAT ignored an invocation. - -The dynamic model is enabled with compiler switch @code{-gnatE}. -@end itemize - -@geindex Static elaboration model - - -@itemize * - -@item -`Static elaboration model' - -This is the middle ground of the three models. When the static model is in -effect, GNAT makes the following assumptions: - - -@itemize - - -@item -Only code at the library level and in package body statements within all -units in a partition is considered to be elaboration code. - -@item -All invocations in elaboration will take place at run time, regardless of -conditional execution. -@end itemize - -GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios -that invoke internal targets. In addition, GNAT generates run-time checks for -all external targets and for all scenarios that may exhibit ABE problems. - -The elaboration order is obtained by honoring all `with' clauses, purity and -preelaborability of units, presence of elaboration-control pragmas, and all -invocations in elaboration code. An order obtained using the static model is -guaranteed to be ABE problem-free, excluding dispatching calls and -access-to-subprogram types. - -The static model is the default model in GNAT. -@end itemize - -@geindex SPARK elaboration model - - -@itemize * - -@item -`SPARK elaboration model' - -This is the most conservative of the three models and enforces the SPARK -rules of elaboration as defined in the SPARK Reference Manual, section 7.7. -The SPARK model is in effect only when a scenario and a target reside in a -region subject to @code{SPARK_Mode On}, otherwise the dynamic or static model -is in effect. - -The SPARK model is enabled with compiler switch @code{-gnatd.v}. -@end itemize - -@geindex Legacy elaboration models - - -@itemize * - -@item -`Legacy elaboration models' - -In addition to the three elaboration models outlined above, GNAT provides the -following legacy models: - - -@itemize - - -@item -@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT. -This model is enabled with compiler switch @code{-gnatH}. - -@item -@cite{Legacy elaboration-order model} available in pre-20.x versions of GNAT. -This model is enabled with binder switch @code{-H}. -@end itemize -@end itemize - -@geindex Relaxed elaboration mode - -The dynamic, legacy, and static models can be relaxed using compiler switch -@code{-gnatJ}, making them more permissive. Note that in this mode, 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 id7}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{223} -@section Mixing Elaboration Models - - -It is possible to mix units compiled with a different elaboration model, -however the following rules must be observed: - - -@itemize * - -@item -A client unit compiled with the dynamic model can only `with' a server unit -that meets at least one of the following criteria: - - -@itemize - - -@item -The server unit is compiled with the dynamic model. - -@item -The server unit is a GNAT implementation unit from the @code{Ada}, @code{GNAT}, -@code{Interfaces}, or @code{System} hierarchies. - -@item -The server unit has pragma @code{Pure} or @code{Preelaborate}. - -@item -The client unit has an explicit @code{Elaborate_All} pragma for the server -unit. -@end itemize -@end itemize - -These rules ensure that elaboration checks are not omitted. If the rules are -violated, the binder emits a warning: - -@quotation - -@example -warning: "x.ads" has dynamic elaboration checks and with's -warning: "y.ads" which has static elaboration checks -@end example -@end quotation - -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{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{225} -@section ABE Diagnostics - - -GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios -that invoke internal targets, regardless of whether the dynamic, SPARK, or -static model is in effect. - -Note that GNAT emits warnings rather than hard errors whenever it encounters an -elaboration problem. This is because the elaboration model in effect may be too -conservative, or a particular scenario may not be invoked due conditional -execution. The warnings can be suppressed selectively with @code{pragma Warnings -(Off)} or globally with compiler switch @code{-gnatwL}. - -A `guaranteed ABE' arises when the body of a target is not elaborated early -enough, and causes `all' scenarios that directly invoke the target to fail. - -@quotation - -@example -package body Guaranteed_ABE is - function ABE return Integer; - - Val : constant Integer := ABE; - - function ABE return Integer is - begin - ... - end ABE; -end Guaranteed_ABE; -@end example -@end quotation - -In the example above, the elaboration of @code{Guaranteed_ABE}’s body elaborates -the declaration of @code{Val}. This invokes function @code{ABE}, however the body of -@code{ABE} has not been elaborated yet. GNAT emits the following diagnostic: - -@quotation - -@example -4. Val : constant Integer := ABE; - | - >>> warning: cannot call "ABE" before body seen - >>> warning: Program_Error will be raised at run time -@end example -@end quotation - -A `conditional ABE' arises when the body of a target is not elaborated early -enough, and causes `some' scenarios that directly invoke the target to fail. - -@quotation - -@example - 1. package body Conditional_ABE is - 2. procedure Force_Body is null; - 3. - 4. generic - 5. with function Func return Integer; - 6. package Gen is - 7. Val : constant Integer := Func; - 8. end Gen; - 9. -10. function ABE return Integer; -11. -12. function Cause_ABE return Boolean is -13. package Inst is new Gen (ABE); -14. begin -15. ... -16. end Cause_ABE; -17. -18. Val : constant Boolean := Cause_ABE; -19. -20. function ABE return Integer is -21. begin -22. ... -23. end ABE; -24. -25. Safe : constant Boolean := Cause_ABE; -26. end Conditional_ABE; -@end example -@end quotation - -In the example above, the elaboration of package body @code{Conditional_ABE} -elaborates the declaration of @code{Val}. This invokes function @code{Cause_ABE}, -which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of -@code{Inst} invokes function @code{ABE}, however the body of @code{ABE} has not been -elaborated yet. GNAT emits the following diagnostic: - -@quotation - -@example -13. package Inst is new Gen (ABE); - | - >>> warning: in instantiation at line 7 - >>> warning: cannot call "ABE" before body seen - >>> warning: Program_Error may be raised at run time - >>> warning: body of unit "Conditional_ABE" elaborated - >>> warning: function "Cause_ABE" called at line 18 - >>> warning: function "ABE" called at line 7, instance at line 13 -@end example -@end quotation - -Note that the same ABE problem does not occur with the elaboration of -declaration @code{Safe} because the body of function @code{ABE} has already been -elaborated at that point. - -@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT -@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{227} -@section SPARK Diagnostics - - -GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference -Manual section 7.7 when compiler switch @code{-gnatd.v} is in effect. Note -that GNAT emits hard errors whenever it encounters a violation of the SPARK -rules. - -@quotation - -@example -1. with Server; -2. package body SPARK_Diagnostics with SPARK_Mode is -3. Val : constant Integer := Server.Func; - | - >>> call to "Func" during elaboration in SPARK - >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server" - >>> body of unit "SPARK_Model" elaborated - >>> function "Func" called at line 3 - -4. end SPARK_Diagnostics; -@end example -@end quotation - -@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT -@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{229} -@section Elaboration Circularities - - -An `elaboration circularity' occurs whenever the elaboration of a set of -units enters a deadlocked state, where each unit is waiting for another unit -to be elaborated. This situation may be the result of improper use of `with' -clauses, elaboration-control pragmas, or invocations in elaboration code. - -The following example exhibits an elaboration circularity. - -@quotation - -@example -with B; pragma Elaborate (B); -package A is -end A; -@end example - -@example -package B is - procedure Force_Body; -end B; -@end example - -@example -with C; -package body B is - procedure Force_Body is null; - - Elab : constant Integer := C.Func; -end B; -@end example - -@example -package C is - function Func return Integer; -end C; -@end example - -@example -with A; -package body C is - function Func return Integer is - begin - ... - end Func; -end C; -@end example -@end quotation - -The binder emits the following diagnostic: - -@quotation - -@example -error: Elaboration circularity detected -info: -info: Reason: -info: -info: unit "a (spec)" depends on its own elaboration -info: -info: Circularity: -info: -info: unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)" -info: unit "b (body)" is in the closure of pragma Elaborate -info: unit "b (body)" invokes a construct of unit "c (body)" at elaboration time -info: unit "c (body)" has with clause for unit "a (spec)" -info: -info: Suggestions: -info: -info: remove pragma Elaborate for unit "b (body)" in unit "a (spec)" -info: use the dynamic elaboration model (compiler switch -gnatE) -@end example -@end quotation - -The diagnostic consist of the following sections: - - -@itemize * - -@item -Reason - -This section provides a short explanation describing why the set of units -could not be ordered. - -@item -Circularity - -This section enumerates the units comprising the deadlocked set, along with -their interdependencies. - -@item -Suggestions - -This section enumerates various tactics for eliminating the circularity. -@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{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{22b} -@section Resolving Elaboration Circularities - - -The most desirable option from the point of view of long-term maintenance is to -rearrange the program so that the elaboration problems are avoided. One useful -technique is to place the elaboration code into separate child packages. -Another is to move some of the initialization code to explicitly invoked -subprograms, where the program controls the order of initialization explicitly. -Although this is the most desirable option, it may be impractical and involve -too much modification, especially in the case of complex legacy code. - -When faced with an elaboration circularity, the programmer should also consider -the tactics given in the suggestions section of the circularity diagnostic. -Depending on the units involved in the circularity, their `with' clauses, -purity, preelaborability, presence of elaboration-control pragmas and -invocations at elaboration time, the binder may suggest one or more of the -following tactics to eliminate the circularity: - - -@itemize * - -@item -Pragma Elaborate elimination - -@example -remove pragma Elaborate for unit "..." in unit "..." -@end example - -This tactic is suggested when the binder has determined that pragma -@code{Elaborate}: - - -@itemize - - -@item -Prevents a set of units from being elaborated. - -@item -The removal of the pragma will not eliminate the semantic effects of the -pragma. In other words, the argument of the pragma will still be elaborated -prior to the unit containing the pragma. - -@item -The removal of the pragma will enable the successful ordering of the units. -@end itemize - -The programmer should remove the pragma as advised, and rebuild the program. - -@item -Pragma Elaborate_All elimination - -@example -remove pragma Elaborate_All for unit "..." in unit "..." -@end example - -This tactic is suggested when the binder has determined that pragma -@code{Elaborate_All}: - - -@itemize - - -@item -Prevents a set of units from being elaborated. - -@item -The removal of the pragma will not eliminate the semantic effects of the -pragma. In other words, the argument of the pragma along with its `with' -closure will still be elaborated prior to the unit containing the pragma. - -@item -The removal of the pragma will enable the successful ordering of the units. -@end itemize - -The programmer should remove the pragma as advised, and rebuild the program. - -@item -Pragma Elaborate_All downgrade - -@example -change pragma Elaborate_All for unit "..." to Elaborate in unit "..." -@end example - -This tactic is always suggested with the pragma @code{Elaborate_All} elimination -tactic. It offers a different alternative of guaranteeing that the argument -of the pragma will still be elaborated prior to the unit containing the -pragma. - -The programmer should update the pragma as advised, and rebuild the program. - -@item -Pragma Elaborate_Body elimination - -@example -remove pragma Elaborate_Body in unit "..." -@end example - -This tactic is suggested when the binder has determined that pragma -@code{Elaborate_Body}: - - -@itemize - - -@item -Prevents a set of units from being elaborated. - -@item -The removal of the pragma will enable the successful ordering of the units. -@end itemize - -Note that the binder cannot determine whether the pragma is required for -other purposes, such as guaranteeing the initialization of a variable -declared in the spec by elaboration code in the body. - -The programmer should remove the pragma as advised, and rebuild the program. - -@item -Use of pragma Restrictions - -@example -use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code) -@end example - -This tactic is suggested when the binder has determined that a task -activation at elaboration time: - - -@itemize - - -@item -Prevents a set of units from being elaborated. -@end itemize - -Note that the binder cannot determine with certainty whether the task will -block at elaboration time. - -The programmer should create a configuration file, place the pragma within, -update the general compilation arguments, and rebuild the program. - -@item -Use of dynamic elaboration model - -@example -use the dynamic elaboration model (compiler switch -gnatE) -@end example - -This tactic is suggested when the binder has determined that an invocation at -elaboration time: - - -@itemize - - -@item -Prevents a set of units from being elaborated. - -@item -The use of the dynamic model will enable the successful ordering of the -units. -@end itemize - -The programmer has two options: - - -@itemize - - -@item -Determine the units involved in the invocation using the detailed -invocation information, and add compiler switch @code{-gnatE} to the -compilation arguments of selected files only. This approach will yield -safer elaboration orders compared to the other option because it will -minimize the opportunities presented to the dynamic model for ignoring -invocations. - -@item -Add compiler switch @code{-gnatE} to the general compilation arguments. -@end itemize - -@item -Use of detailed invocation information - -@example -use detailed invocation information (compiler switch -gnatd_F) -@end example - -This tactic is always suggested with the use of the dynamic model tactic. It -causes the circularity section of the circularity diagnostic to describe the -flow of elaboration code from a unit to a unit, enumerating all such paths in -the process. - -The programmer should analyze this information to determine which units -should be compiled with the dynamic model. - -@item -Forced-dependency elimination - -@example -remove the dependency of unit "..." on unit "..." from the argument of switch -f -@end example - -This tactic is suggested when the binder has determined that a dependency -present in the forced-elaboration-order file indicated by binder switch -@code{-f}: - - -@itemize - - -@item -Prevents a set of units from being elaborated. - -@item -The removal of the dependency will enable the successful ordering of the -units. -@end itemize - -The programmer should edit the forced-elaboration-order file, remove the -dependency, and rebind the program. - -@item -All forced-dependency elimination - -@example -remove switch -f -@end example - -This tactic is suggested in case editing the forced-elaboration-order file is -not an option. - -The programmer should remove binder switch @code{-f} from the binder -arguments, and rebind. - -@item -Multiple-circularities diagnostic - -@example -diagnose all circularities (binder switch -d_C) -@end example - -By default, the binder will diagnose only the highest-precedence circularity. -If the program contains multiple circularities, the binder will suggest the -use of binder switch @code{-d_C} in order to obtain the diagnostics of all -circularities. - -The programmer should add binder switch @code{-d_C} to the binder -arguments, and rebind. -@end itemize - -If none of the tactics suggested by the binder eliminate the elaboration -circularity, the programmer should consider using one of the legacy elaboration -models, in the following order: - - -@itemize * - -@item -Use the pre-20.x legacy elaboration-order model, with binder switch -@code{-H}. - -@item -Use both pre-18.x and pre-20.x legacy elaboration models, with compiler -switch @code{-gnatH} and binder switch @code{-H}. - -@item -Use the relaxed static-elaboration model, with compiler switches -@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}. - -@item -Use the relaxed dynamic-elaboration model, with compiler switches -@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch -@code{-H}. -@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 elaboration-related-compiler-switches}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22d} -@section Elaboration-related Compiler Switches - - -GNAT has several switches that affect the elaboration model and consequently -the elaboration order chosen by the binder. - -@geindex -gnatE (gnat) - - -@table @asis - -@item @code{-gnatE} - -Dynamic elaboration checking mode enabled - -When this switch is in effect, GNAT activates the dynamic model. -@end table - -@geindex -gnatel (gnat) - - -@table @asis - -@item @code{-gnatel} - -Turn on info messages on generated Elaborate[_All] pragmas - -This switch is only applicable to the pre-20.x legacy elaboration models. -The post-20.x elaboration model no longer relies on implicitly generated -@code{Elaborate} and @code{Elaborate_All} pragmas to order units. - -When this switch is in effect, GNAT will emit the following supplementary -information depending on the elaboration model in effect. - - -@itemize - - -@item -`Dynamic model' - -GNAT will indicate missing @code{Elaborate} and @code{Elaborate_All} pragmas for -all library-level scenarios within the partition. - -@item -`Static model' - -GNAT will indicate all scenarios invoked during elaboration. In addition, -it will provide detailed traceback when an implicit @code{Elaborate} or -@code{Elaborate_All} pragma is generated. - -@item -`SPARK model' - -GNAT will indicate how an elaboration requirement is met by the context of -a unit. This diagnostic requires compiler switch @code{-gnatd.v}. - -@example -1. with Server; pragma Elaborate_All (Server); -2. package Client with SPARK_Mode is -3. Val : constant Integer := Server.Func; - | - >>> info: call to "Func" during elaboration in SPARK - >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1 - -4. end Client; -@end example -@end itemize -@end table - -@geindex -gnatH (gnat) - - -@table @asis - -@item @code{-gnatH} - -Legacy elaboration checking mode enabled - -When this switch is in effect, GNAT will utilize the pre-18.x elaboration -model. -@end table - -@geindex -gnatJ (gnat) - - -@table @asis - -@item @code{-gnatJ} - -Relaxed elaboration checking mode enabled - -When this switch is in effect, GNAT will not process certain scenarios, -resulting in a more permissive elaboration model. Note that this may -eliminate some diagnostics and run-time checks. -@end table - -@geindex -gnatw.f (gnat) - - -@table @asis - -@item @code{-gnatw.f} - -Turn on warnings for suspicious Subp’Access - -When this switch is in effect, GNAT will treat @code{'Access} of an entry, -operator, or subprogram as a potential call to the target and issue warnings: - -@example - 1. package body Attribute_Call is - 2. function Func return Integer; - 3. type Func_Ptr is access function return Integer; - 4. - 5. Ptr : constant Func_Ptr := Func'Access; - | - >>> warning: "Access" attribute of "Func" before body seen - >>> warning: possible Program_Error on later references - >>> warning: body of unit "Attribute_Call" elaborated - >>> warning: "Access" of "Func" taken at line 5 - - 6. - 7. function Func return Integer is - 8. begin - 9. ... -10. end Func; -11. end Attribute_Call; -@end example - -In the example above, the elaboration of declaration @code{Ptr} is assigned -@code{Func'Access} before the body of @code{Func} has been elaborated. -@end table - -@geindex -gnatwl (gnat) - - -@table @asis - -@item @code{-gnatwl} - -Turn on warnings for elaboration problems - -When this switch is in effect, GNAT emits diagnostics in the form of warnings -concerning various elaboration problems. The warnings are enabled by default. -The switch is provided in case all warnings are suppressed, but elaboration -warnings are still desired. - -@item @code{-gnatwL} - -Turn off warnings for elaboration problems - -When this switch is in effect, GNAT no longer emits any diagnostics in the -form of warnings. Selective suppression of elaboration problems is possible -using @code{pragma Warnings (Off)}. - -@example - 1. package body Selective_Suppression is - 2. function ABE return Integer; - 3. - 4. Val_1 : constant Integer := ABE; - | - >>> warning: cannot call "ABE" before body seen - >>> warning: Program_Error will be raised at run time - - 5. - 6. pragma Warnings (Off); - 7. Val_2 : constant Integer := ABE; - 8. pragma Warnings (On); - 9. -10. function ABE return Integer is -11. begin -12. ... -13. end ABE; -14. end Selective_Suppression; -@end example - -Note that suppressing elaboration warnings does not eliminate run-time -checks. The example above will still fail at run time with an ABE. -@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{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22f} -@section Summary of Procedures for Elaboration Control - - -A programmer should first compile the program with the default options, using -none of the binder or compiler switches. If the binder succeeds in finding an -elaboration order, then apart from possible cases involving dispatching calls -and access-to-subprogram types, the program is free of elaboration errors. - -If it is important for the program to be portable to compilers other than GNAT, -then the programmer should use compiler switch @code{-gnatel} and consider -the messages about missing or implicitly created @code{Elaborate} and -@code{Elaborate_All} pragmas. - -If the binder reports an elaboration circularity, the programmer has several -options: - - -@itemize * - -@item -Ensure that elaboration warnings are enabled. This will allow the static -model to output trace information of elaboration issues. The trace -information could shed light on previously unforeseen dependencies, as well -as their origins. Elaboration warnings are enabled with compiler switch -@code{-gnatwl}. - -@item -Cosider the tactics given in the suggestions section of the circularity -diagnostic. - -@item -If none of the steps outlined above resolve the circularity, use a more -permissive elaboration model, in the following order: - - -@itemize - - -@item -Use the pre-20.x legacy elaboration-order model, with binder switch -@code{-H}. - -@item -Use both pre-18.x and pre-20.x legacy elaboration models, with compiler -switch @code{-gnatH} and binder switch @code{-H}. - -@item -Use the relaxed static elaboration model, with compiler switches -@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}. - -@item -Use the relaxed dynamic elaboration model, with compiler switches -@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch -@code{-H}. -@end itemize -@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{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{231} -@section Inspecting the Chosen Elaboration Order - - -To see the elaboration order chosen by the binder, inspect the contents of file -@cite{b~xxx.adb}. On certain targets, this file appears as @cite{b_xxx.adb}. The -elaboration order appears as a sequence of calls to @code{Elab_Body} and -@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a -particular unit is elaborated. For example: - -@quotation - -@example -System.Soft_Links'Elab_Body; -E14 := True; -System.Secondary_Stack'Elab_Body; -E18 := True; -System.Exception_Table'Elab_Body; -E24 := True; -Ada.Io_Exceptions'Elab_Spec; -E67 := True; -Ada.Tags'Elab_Spec; -Ada.Streams'Elab_Spec; -E43 := True; -Interfaces.C'Elab_Spec; -E69 := True; -System.Finalization_Root'Elab_Spec; -E60 := True; -System.Os_Lib'Elab_Body; -E71 := True; -System.Finalization_Implementation'Elab_Spec; -System.Finalization_Implementation'Elab_Body; -E62 := True; -Ada.Finalization'Elab_Spec; -E58 := True; -Ada.Finalization.List_Controller'Elab_Spec; -E76 := True; -System.File_Control_Block'Elab_Spec; -E74 := True; -System.File_Io'Elab_Body; -E56 := True; -Ada.Tags'Elab_Body; -E45 := True; -Ada.Text_Io'Elab_Spec; -Ada.Text_Io'Elab_Body; -E07 := True; -@end example -@end quotation - -Note also binder switch @code{-l}, which outputs the chosen elaboration -order and provides a more readable form of the above: - -@quotation - -@example -ada (spec) -interfaces (spec) -system (spec) -system.case_util (spec) -system.case_util (body) -system.concat_2 (spec) -system.concat_2 (body) -system.concat_3 (spec) -system.concat_3 (body) -system.htable (spec) -system.parameters (spec) -system.parameters (body) -system.crtl (spec) -interfaces.c_streams (spec) -interfaces.c_streams (body) -system.restrictions (spec) -system.restrictions (body) -system.standard_library (spec) -system.exceptions (spec) -system.exceptions (body) -system.storage_elements (spec) -system.storage_elements (body) -system.secondary_stack (spec) -system.stack_checking (spec) -system.stack_checking (body) -system.string_hash (spec) -system.string_hash (body) -system.htable (body) -system.strings (spec) -system.strings (body) -system.traceback (spec) -system.traceback (body) -system.traceback_entries (spec) -system.traceback_entries (body) -ada.exceptions (spec) -ada.exceptions.last_chance_handler (spec) -system.soft_links (spec) -system.soft_links (body) -ada.exceptions.last_chance_handler (body) -system.secondary_stack (body) -system.exception_table (spec) -system.exception_table (body) -ada.io_exceptions (spec) -ada.tags (spec) -ada.streams (spec) -interfaces.c (spec) -interfaces.c (body) -system.finalization_root (spec) -system.finalization_root (body) -system.memory (spec) -system.memory (body) -system.standard_library (body) -system.os_lib (spec) -system.os_lib (body) -system.unsigned_types (spec) -system.stream_attributes (spec) -system.stream_attributes (body) -system.finalization_implementation (spec) -system.finalization_implementation (body) -ada.finalization (spec) -ada.finalization (body) -ada.finalization.list_controller (spec) -ada.finalization.list_controller (body) -system.file_control_block (spec) -system.file_io (spec) -system.file_io (body) -system.val_uns (spec) -system.val_util (spec) -system.val_util (body) -system.val_uns (body) -system.wch_con (spec) -system.wch_con (body) -system.wch_cnv (spec) -system.wch_jis (spec) -system.wch_jis (body) -system.wch_cnv (body) -system.wch_stw (spec) -system.wch_stw (body) -ada.tags (body) -ada.exceptions (body) -ada.text_io (spec) -ada.text_io (body) -text_io (spec) -gdbstr (body) -@end example -@end quotation - -@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top -@anchor{gnat_ugn/inline_assembler doc}@anchor{232}@anchor{gnat_ugn/inline_assembler id1}@anchor{233}@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10} -@chapter Inline Assembler - - -@geindex Inline Assembler - -If you need to write low-level software that interacts directly -with the hardware, Ada provides two ways to incorporate assembly -language code into your program. First, you can import and invoke -external routines written in assembly language, an Ada feature fully -supported by GNAT. However, for small sections of code it may be simpler -or more efficient to include assembly language statements directly -in your Ada source program, using the facilities of the implementation-defined -package @code{System.Machine_Code}, which incorporates the gcc -Inline Assembler. The Inline Assembler approach offers a number of advantages, -including the following: - - -@itemize * - -@item -No need to use non-Ada tools - -@item -Consistent interface over different targets - -@item -Automatic usage of the proper calling conventions - -@item -Access to Ada constants and variables - -@item -Definition of intrinsic routines - -@item -Possibility of inlining a subprogram comprising assembler code - -@item -Code optimizer can take Inline Assembler code into account -@end itemize - -This appendix presents a series of examples to show you how to use -the Inline Assembler. Although it focuses on the Intel x86, -the general approach applies also to other processors. -It is assumed that you are familiar with Ada -and with assembly language programming. - -@menu -* Basic Assembler Syntax:: -* A Simple Example of Inline Assembler:: -* Output Variables in Inline Assembler:: -* Input Variables in Inline Assembler:: -* Inlining Inline Assembler Code:: -* Other Asm Functionality:: - -@end menu - -@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler -@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{234}@anchor{gnat_ugn/inline_assembler id2}@anchor{235} -@section Basic Assembler Syntax - - -The assembler used by GNAT and gcc is based not on the Intel assembly -language, but rather on a language that descends from the AT&T Unix -assembler @code{as} (and which is often referred to as ‘AT&T syntax’). -The following table summarizes the main features of @code{as} syntax -and points out the differences from the Intel conventions. -See the gcc @code{as} and @code{gas} (an @code{as} macro -pre-processor) documentation for further information. - - -@display -`Register names'@w{ } -@display -gcc / @code{as}: Prefix with ‘%’; for example @code{%eax}@w{ } -Intel: No extra punctuation; for example @code{eax}@w{ } -@end display -@end display - - - - -@display -`Immediate operand'@w{ } -@display -gcc / @code{as}: Prefix with ‘$’; for example @code{$4}@w{ } -Intel: No extra punctuation; for example @code{4}@w{ } -@end display -@end display - - - - -@display -`Address'@w{ } -@display -gcc / @code{as}: Prefix with ‘$’; for example @code{$loc}@w{ } -Intel: No extra punctuation; for example @code{loc}@w{ } -@end display -@end display - - - - -@display -`Memory contents'@w{ } -@display -gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ } -Intel: Square brackets; for example @code{[loc]}@w{ } -@end display -@end display - - - - -@display -`Register contents'@w{ } -@display -gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ } -Intel: Square brackets; for example @code{[eax]}@w{ } -@end display -@end display - - - - -@display -`Hexadecimal numbers'@w{ } -@display -gcc / @code{as}: Leading ‘0x’ (C language syntax); for example @code{0xA0}@w{ } -Intel: Trailing ‘h’; for example @code{A0h}@w{ } -@end display -@end display - - - - -@display -`Operand size'@w{ } -@display -gcc / @code{as}: Explicit in op code; for example @code{movw} to move a 16-bit word@w{ } -Intel: Implicit, deduced by assembler; for example @code{mov}@w{ } -@end display -@end display - - - - -@display -`Instruction repetition'@w{ } -@display -gcc / @code{as}: Split into two lines; for example@w{ } -@display -@code{rep}@w{ } -@code{stosl}@w{ } -@end display -Intel: Keep on one line; for example @code{rep stosl}@w{ } -@end display -@end display - - - - -@display -`Order of operands'@w{ } -@display -gcc / @code{as}: Source first; for example @code{movw $4, %eax}@w{ } -Intel: Destination first; for example @code{mov eax, 4}@w{ } -@end display -@end display - - - -@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{236}@anchor{gnat_ugn/inline_assembler id3}@anchor{237} -@section A Simple Example of Inline Assembler - - -The following example will generate a single assembly language statement, -@code{nop}, which does nothing. Despite its lack of run-time effect, -the example will be useful in illustrating the basics of -the Inline Assembler facility. - -@quotation - -@example -with System.Machine_Code; use System.Machine_Code; -procedure Nothing is -begin - Asm ("nop"); -end Nothing; -@end example -@end quotation - -@code{Asm} is a procedure declared in package @code{System.Machine_Code}; -here it takes one parameter, a `template string' that must be a static -expression and that will form the generated instruction. -@code{Asm} may be regarded as a compile-time procedure that parses -the template string and additional parameters (none here), -from which it generates a sequence of assembly language instructions. - -The examples in this chapter will illustrate several of the forms -for invoking @code{Asm}; a complete specification of the syntax -is found in the @code{Machine_Code_Insertions} section of the -@cite{GNAT Reference Manual}. - -Under the standard GNAT conventions, the @code{Nothing} procedure -should be in a file named @code{nothing.adb}. -You can build the executable in the usual way: - -@quotation - -@example -$ gnatmake nothing -@end example -@end quotation - -However, the interesting aspect of this example is not its run-time behavior -but rather the generated assembly code. -To see this output, invoke the compiler as follows: - -@quotation - -@example -$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb -@end example -@end quotation - -where the options are: - - -@itemize * - -@item - -@table @asis - -@item @code{-c} - -compile only (no bind or link) -@end table - -@item - -@table @asis - -@item @code{-S} - -generate assembler listing -@end table - -@item - -@table @asis - -@item @code{-fomit-frame-pointer} - -do not set up separate stack frames -@end table - -@item - -@table @asis - -@item @code{-gnatp} - -do not add runtime checks -@end table -@end itemize - -This gives a human-readable assembler version of the code. The resulting -file will have the same name as the Ada source file, but with a @code{.s} -extension. In our example, the file @code{nothing.s} has the following -contents: - -@quotation - -@example -.file "nothing.adb" -gcc2_compiled.: -___gnu_compiled_ada: -.text - .align 4 -.globl __ada_nothing -__ada_nothing: -#APP - nop -#NO_APP - jmp L1 - .align 2,0x90 -L1: - ret -@end example -@end quotation - -The assembly code you included is clearly indicated by -the compiler, between the @code{#APP} and @code{#NO_APP} -delimiters. The character before the ‘APP’ and ‘NOAPP’ -can differ on different targets. For example, GNU/Linux uses ‘#APP’ while -on NT you will see ‘/APP’. - -If you make a mistake in your assembler code (such as using the -wrong size modifier, or using a wrong operand for the instruction) GNAT -will report this error in a temporary file, which will be deleted when -the compilation is finished. Generating an assembler file will help -in such cases, since you can assemble this file separately using the -@code{as} assembler that comes with gcc. - -Assembling the file using the command - -@quotation - -@example -$ as nothing.s -@end example -@end quotation - -will give you error messages whose lines correspond to the assembler -input file, so you can easily find and correct any mistakes you made. -If there are no errors, @code{as} will generate an object file -@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{238}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{239} -@section Output Variables in Inline Assembler - - -The examples in this section, showing how to access the processor flags, -illustrate how to specify the destination operands for assembly language -statements. - -@quotation - -@example -with Interfaces; use Interfaces; -with Ada.Text_IO; use Ada.Text_IO; -with System.Machine_Code; use System.Machine_Code; -procedure Get_Flags is - Flags : Unsigned_32; - use ASCII; -begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); -end Get_Flags; -@end example -@end quotation - -In order to have a nicely aligned assembly listing, we have separated -multiple assembler statements in the Asm template string with linefeed -(ASCII.LF) and horizontal tab (ASCII.HT) characters. -The resulting section of the assembly output file is: - -@quotation - -@example -#APP - pushfl - popl %eax - movl %eax, -40(%ebp) -#NO_APP -@end example -@end quotation - -It would have been legal to write the Asm invocation as: - -@quotation - -@example -Asm ("pushfl popl %%eax movl %%eax, %0") -@end example -@end quotation - -but in the generated assembler file, this would come out as: - -@quotation - -@example -#APP - pushfl popl %eax movl %eax, -40(%ebp) -#NO_APP -@end example -@end quotation - -which is not so convenient for the human reader. - -We use Ada comments -at the end of each line to explain what the assembler instructions -actually do. This is a useful convention. - -When writing Inline Assembler instructions, you need to precede each register -and variable name with a percent sign. Since the assembler already requires -a percent sign at the beginning of a register name, you need two consecutive -percent signs for such names in the Asm template string, thus @code{%%eax}. -In the generated assembly code, one of the percent signs will be stripped off. - -Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output -variables: operands you later define using @code{Input} or @code{Output} -parameters to @code{Asm}. -An output variable is illustrated in -the third statement in the Asm template string: - -@quotation - -@example -movl %%eax, %0 -@end example -@end quotation - -The intent is to store the contents of the eax register in a variable that can -be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not -necessarily work, since the compiler might optimize by using a register -to hold Flags, and the expansion of the @code{movl} instruction would not be -aware of this optimization. The solution is not to store the result directly -but rather to advise the compiler to choose the correct operand form; -that is the purpose of the @code{%0} output variable. - -Information about the output variable is supplied in the @code{Outputs} -parameter to @code{Asm}: - -@quotation - -@example -Outputs => Unsigned_32'Asm_Output ("=g", Flags)); -@end example -@end quotation - -The output is defined by the @code{Asm_Output} attribute of the target type; -the general format is - -@quotation - -@example -Type'Asm_Output (constraint_string, variable_name) -@end example -@end quotation - -The constraint string directs the compiler how -to store/access the associated variable. In the example - -@quotation - -@example -Unsigned_32'Asm_Output ("=m", Flags); -@end example -@end quotation - -the @code{"m"} (memory) constraint tells the compiler that the variable -@code{Flags} should be stored in a memory variable, thus preventing -the optimizer from keeping it in a register. In contrast, - -@quotation - -@example -Unsigned_32'Asm_Output ("=r", Flags); -@end example -@end quotation - -uses the @code{"r"} (register) constraint, telling the compiler to -store the variable in a register. - -If the constraint is preceded by the equal character ‘=’, it tells -the compiler that the variable will be used to store data into it. - -In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint, -allowing the optimizer to choose whatever it deems best. - -There are a fairly large number of constraints, but the ones that are -most useful (for the Intel x86 processor) are the following: - -@quotation - - -@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@item - -`=' - -@tab - -output constraint - -@item - -`g' - -@tab - -global (i.e., can be stored anywhere) - -@item - -`m' - -@tab - -in memory - -@item - -`I' - -@tab - -a constant - -@item - -`a' - -@tab - -use eax - -@item - -`b' - -@tab - -use ebx - -@item - -`c' - -@tab - -use ecx - -@item - -`d' - -@tab - -use edx - -@item - -`S' - -@tab - -use esi - -@item - -`D' - -@tab - -use edi - -@item - -`r' - -@tab - -use one of eax, ebx, ecx or edx - -@item - -`q' - -@tab - -use one of eax, ebx, ecx, edx, esi or edi - -@end multitable - -@end quotation - -The full set of constraints is described in the gcc and @code{as} -documentation; note that it is possible to combine certain constraints -in one constraint string. - -You specify the association of an output variable with an assembler operand -through the @code{%@var{n}} notation, where `n' is a non-negative -integer. Thus in - -@quotation - -@example -Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); -@end example -@end quotation - -@code{%0} will be replaced in the expanded code by the appropriate operand, -whatever -the compiler decided for the @code{Flags} variable. - -In general, you may have any number of output variables: - - -@itemize * - -@item -Count the operands starting at 0; thus @code{%0}, @code{%1}, etc. - -@item -Specify the @code{Outputs} parameter as a parenthesized comma-separated list -of @code{Asm_Output} attributes -@end itemize - -For example: - -@quotation - -@example -Asm ("movl %%eax, %0" & LF & HT & - "movl %%ebx, %1" & LF & HT & - "movl %%ecx, %2", - Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A - Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B - Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C -@end example -@end quotation - -where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables -in the Ada program. - -As a variation on the @code{Get_Flags} example, we can use the constraints -string to direct the compiler to store the eax register into the @code{Flags} -variable, instead of including the store instruction explicitly in the -@code{Asm} template string: - -@quotation - -@example -with Interfaces; use Interfaces; -with Ada.Text_IO; use Ada.Text_IO; -with System.Machine_Code; use System.Machine_Code; -procedure Get_Flags_2 is - Flags : Unsigned_32; - use ASCII; -begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax", -- save flags in eax - Outputs => Unsigned_32'Asm_Output ("=a", Flags)); - Put_Line ("Flags register:" & Flags'Img); -end Get_Flags_2; -@end example -@end quotation - -The @code{"a"} constraint tells the compiler that the @code{Flags} -variable will come from the eax register. Here is the resulting code: - -@quotation - -@example -#APP - pushfl - popl %eax -#NO_APP - movl %eax,-40(%ebp) -@end example -@end quotation - -The compiler generated the store of eax into Flags after -expanding the assembler code. - -Actually, there was no need to pop the flags into the eax register; -more simply, we could just pop the flags directly into the program variable: - -@quotation - -@example -with Interfaces; use Interfaces; -with Ada.Text_IO; use Ada.Text_IO; -with System.Machine_Code; use System.Machine_Code; -procedure Get_Flags_3 is - Flags : Unsigned_32; - use ASCII; -begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "pop %0", -- save flags in Flags - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); -end Get_Flags_3; -@end example -@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{23a}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{23b} -@section Input Variables in Inline Assembler - - -The example in this section illustrates how to specify the source operands -for assembly language statements. -The program simply increments its input value by 1: - -@quotation - -@example -with Interfaces; use Interfaces; -with Ada.Text_IO; use Ada.Text_IO; -with System.Machine_Code; use System.Machine_Code; -procedure Increment is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Outputs => Unsigned_32'Asm_Output ("=a", Result), - Inputs => Unsigned_32'Asm_Input ("a", Value)); - return Result; - end Incr; - - Value : Unsigned_32; - -begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Incr (Value); - Put_Line ("Value after is" & Value'Img); -end Increment; -@end example -@end quotation - -The @code{Outputs} parameter to @code{Asm} specifies -that the result will be in the eax register and that it is to be stored -in the @code{Result} variable. - -The @code{Inputs} parameter looks much like the @code{Outputs} parameter, -but with an @code{Asm_Input} attribute. -The @code{"="} constraint, indicating an output value, is not present. - -You can have multiple input variables, in the same way that you can have more -than one output variable. - -The parameter count (%0, %1) etc, still starts at the first output statement, -and continues with the input statements. - -Just as the @code{Outputs} parameter causes the register to be stored into the -target variable after execution of the assembler statements, so does the -@code{Inputs} parameter cause its variable to be loaded into the register -before execution of the assembler statements. - -Thus the effect of the @code{Asm} invocation is: - - -@itemize * - -@item -load the 32-bit value of @code{Value} into eax - -@item -execute the @code{incl %eax} instruction - -@item -store the contents of eax into the @code{Result} variable -@end itemize - -The resulting assembler file (with @code{-O2} optimization) contains: - -@quotation - -@example -_increment__incr.1: - subl $4,%esp - movl 8(%esp),%eax -#APP - incl %eax -#NO_APP - movl %eax,%edx - movl %ecx,(%esp) - addl $4,%esp - ret -@end example -@end quotation - -@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler -@anchor{gnat_ugn/inline_assembler id6}@anchor{23c}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23d} -@section Inlining Inline Assembler Code - - -For a short subprogram such as the @code{Incr} function in the previous -section, the overhead of the call and return (creating / deleting the stack -frame) can be significant, compared to the amount of code in the subprogram -body. A solution is to apply Ada’s @code{Inline} pragma to the subprogram, -which directs the compiler to expand invocations of the subprogram at the -point(s) of call, instead of setting up a stack frame for out-of-line calls. -Here is the resulting program: - -@quotation - -@example -with Interfaces; use Interfaces; -with Ada.Text_IO; use Ada.Text_IO; -with System.Machine_Code; use System.Machine_Code; -procedure Increment_2 is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Outputs => Unsigned_32'Asm_Output ("=a", Result), - Inputs => Unsigned_32'Asm_Input ("a", Value)); - return Result; - end Incr; - pragma Inline (Increment); - - Value : Unsigned_32; - -begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Increment (Value); - Put_Line ("Value after is" & Value'Img); -end Increment_2; -@end example -@end quotation - -Compile the program with both optimization (@code{-O2}) and inlining -(@code{-gnatn}) enabled. - -The @code{Incr} function is still compiled as usual, but at the -point in @code{Increment} where our function used to be called: - -@quotation - -@example -pushl %edi -call _increment__incr.1 -@end example -@end quotation - -the code for the function body directly appears: - -@quotation - -@example -movl %esi,%eax -#APP - incl %eax -#NO_APP - movl %eax,%edx -@end example -@end quotation - -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 id7}@anchor{23e}@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23f} -@section Other @code{Asm} Functionality - - -This section describes two important parameters to the @code{Asm} -procedure: @code{Clobber}, which identifies register usage; -and @code{Volatile}, which inhibits unwanted optimizations. - -@menu -* The Clobber Parameter:: -* The Volatile Parameter:: - -@end menu - -@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality -@anchor{gnat_ugn/inline_assembler id8}@anchor{240}@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{241} -@subsection The @code{Clobber} Parameter - - -One of the dangers of intermixing assembly language and a compiled language -such as Ada is that the compiler needs to be aware of which registers are -being used by the assembly code. In some cases, such as the earlier examples, -the constraint string is sufficient to indicate register usage (e.g., -@code{"a"} for -the eax register). But more generally, the compiler needs an explicit -identification of the registers that are used by the Inline Assembly -statements. - -Using a register that the compiler doesn’t know about -could be a side effect of an instruction (like @code{mull} -storing its result in both eax and edx). -It can also arise from explicit register usage in your -assembly code; for example: - -@quotation - -@example -Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Inputs => Unsigned_32'Asm_Input ("g", Var_In)); -@end example -@end quotation - -where the compiler (since it does not analyze the @code{Asm} template string) -does not know you are using the ebx register. - -In such cases you need to supply the @code{Clobber} parameter to @code{Asm}, -to identify the registers that will be used by your assembly code: - -@quotation - -@example -Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Clobber => "ebx"); -@end example -@end quotation - -The Clobber parameter is a static string expression specifying the -register(s) you are using. Note that register names are `not' prefixed -by a percent sign. Also, if more than one register is used then their names -are separated by commas; e.g., @code{"eax, ebx"} - -The @code{Clobber} parameter has several additional uses: - - -@itemize * - -@item -Use ‘register’ name @code{cc} to indicate that flags might have changed - -@item -Use ‘register’ name @code{memory} if you changed a memory location -@end itemize - -@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality -@anchor{gnat_ugn/inline_assembler id9}@anchor{242}@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{243} -@subsection The @code{Volatile} Parameter - - -@geindex Volatile parameter - -Compiler optimizations in the presence of Inline Assembler may sometimes have -unwanted effects. For example, when an @code{Asm} invocation with an input -variable is inside a loop, the compiler might move the loading of the input -variable outside the loop, regarding it as a one-time initialization. - -If this effect is not desired, you can disable such optimizations by setting -the @code{Volatile} parameter to @code{True}; for example: - -@quotation - -@example -Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Clobber => "ebx", - Volatile => True); -@end example -@end quotation - -By default, @code{Volatile} is set to @code{False} unless there is no -@code{Outputs} parameter. - -Although setting @code{Volatile} to @code{True} prevents unwanted -optimizations, it will also disable other optimizations that might be -important for efficiency. In general, you should set @code{Volatile} -to @code{True} only if the compiler’s optimizations have created -problems. - -@node GNU Free Documentation License,Index,Inline Assembler,Top -@anchor{share/gnu_free_documentation_license doc}@anchor{244}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{245} -@chapter GNU Free Documentation License - - -Version 1.3, 3 November 2008 - -Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc -@indicateurl{https://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -`Preamble' - -The purpose of this License is to make a manual, textbook, or other -functional and useful document “free” in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of “copyleft”, which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -`1. APPLICABILITY AND DEFINITIONS' - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The `Document', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as “`you'”. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A “`Modified Version'” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A “`Secondary Section'” is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document’s overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (Thus, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The “`Invariant Sections'” are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The “`Cover Texts'” are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A “`Transparent'” copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not “Transparent” is called `Opaque'. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML, PostScript or PDF designed for human modification. Examples of -transparent image formats include PNG, XCF and JPG. Opaque formats -include proprietary formats that can be read and edited only by -proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML, PostScript or PDF produced by some word -processors for output purposes only. - -The “`Title Page'” means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, “Title Page” means -the text near the most prominent appearance of the work’s title, -preceding the beginning of the body of the text. - -The “`publisher'” means any person or entity that distributes -copies of the Document to the public. - -A section “`Entitled XYZ'” means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as “`Acknowledgements'”, -“`Dedications'”, “`Endorsements'”, or “`History'”.) -To “`Preserve the Title'” -of such a section when you modify the Document means that it remains a -section “Entitled XYZ” according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -`2. VERBATIM COPYING' - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -`3. COPYING IN QUANTITY' - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document’s license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -`4. MODIFICATIONS' - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - - -@enumerate A - -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document’s license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled “History”, Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled “History” in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the “History” section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled “Acknowledgements” or “Dedications”, -Preserve the Title of the section, and preserve in the section all -the substance and tone of each of the contributor acknowledgements -and/or dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled “Endorsements”. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled “Endorsements” -or to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version’s license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled “Endorsements”, provided it contains -nothing but endorsements of your Modified Version by various -parties—for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -`5. COMBINING DOCUMENTS' - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled “History” -in the various original documents, forming one section Entitled -“History”; likewise combine any sections Entitled “Acknowledgements”, -and any sections Entitled “Dedications”. You must delete all sections -Entitled “Endorsements”. - -`6. COLLECTIONS OF DOCUMENTS' - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -`7. AGGREGATION WITH INDEPENDENT WORKS' - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an “aggregate” if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation’s users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document’s Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -`8. TRANSLATION' - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled “Acknowledgements”, -“Dedications”, or “History”, the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -`9. TERMINATION' - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -`10. FUTURE REVISIONS OF THIS LICENSE' - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@indicateurl{https://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License “or any later version” applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy’s public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -`11. RELICENSING' - -“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -“Massive Multiauthor Collaboration” (or “MMC”) contained in the -site means any set of copyrightable works thus published on the MMC -site. - -“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -“Incorporate” means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is “eligible for relicensing” if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -`ADDENDUM: How to use this License for your documents' - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@quotation - -Copyright © YEAR YOUR NAME. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled “GNU -Free Documentation License”. -@end quotation - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the “with … Texts.” line with this: - -@quotation - -with the Invariant Sections being LIST THEIR TITLES, with the -Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. -@end quotation - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index,,GNU Free Documentation License,Top -@unnumbered Index - - -@printindex ge - -@anchor{cf}@w{ } -@anchor{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{ } - -@c %**end of body -@bye