diff options
Diffstat (limited to 'old_ada/doc')
| -rw-r--r-- | old_ada/doc/ada-mode.html | 2288 | ||||
| -rw-r--r-- | old_ada/doc/ada-mode.info | 1983 | ||||
| -rw-r--r-- | old_ada/doc/ada-mode.pdf | bin | 0 -> 303898 bytes | |||
| -rw-r--r-- | old_ada/doc/ada-mode.texi | 1526 | ||||
| -rwxr-xr-x | old_ada/doc/build.sh | 3 | ||||
| -rwxr-xr-x | old_ada/doc/clean.sh | 2 | ||||
| -rw-r--r-- | old_ada/doc/doclicense.texi | 505 | ||||
| -rw-r--r-- | old_ada/doc/docstyle.texi | 19 |
8 files changed, 6326 insertions, 0 deletions
diff --git a/old_ada/doc/ada-mode.html b/old_ada/doc/ada-mode.html new file mode 100644 index 0000000..6788acb --- /dev/null +++ b/old_ada/doc/ada-mode.html @@ -0,0 +1,2288 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- Copyright (C) 1999-2019 Free Software Foundation, Inc. + +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 "A GNU Manual", +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled "GNU Free Documentation License". + +(a) The FSF's Back-Cover Text is: "You have the freedom to copy and +modify this GNU manual." --> +<title>Ada Mode</title> + +<meta name="description" content="Ada Mode"> +<meta name="keywords" content="Ada Mode"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="texi2any"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="#Top" rel="start" title="Top"> +<link href="#Index" rel="index" title="Index"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="#Overview" rel="next" title="Overview"> +<style type="text/css"> +<!-- +a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +span:hover a.copiable-anchor {visibility: visible} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> +<h1 class="settitle" align="center">Ada Mode</h1> + + + + + +<div class="top" id="Top"> +<div class="header"> +<p> +Next: <a href="#Overview" accesskey="n" rel="next">Overview</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Ada-Mode"></span><h1 class="top">Ada Mode</h1> + +<p>Copyright © 1999–2019 Free Software Foundation, Inc. +</p> +<blockquote> +<p>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 “A GNU Manual”, +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled “GNU Free Documentation License”. +</p> +<p>(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and +modify this GNU manual.” +</p></blockquote> + + + +<div class="Contents_element" id="SEC_Contents"> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a id="toc-Overview-1" href="#Overview">1 Overview</a></li> + <li><a id="toc-Installation-1" href="#Installation">2 Installation</a></li> + <li><a id="toc-Customizing-Ada-mode" href="#Customization">3 Customizing Ada mode</a> + <ul class="no-bullet"> + <li><a id="toc-Non_002dstandard-file-names-1" href="#Non_002dstandard-file-names">3.1 Non-standard file names</a></li> + <li><a id="toc-Other-compiler-1" href="#Other-compiler">3.2 Other compiler</a></li> + <li><a id="toc-Other-customization-1" href="#Other-customization">3.3 Other customization</a></li> + </ul></li> + <li><a id="toc-Compiling-Executing-1" href="#Compiling-Executing">4 Compiling Executing</a> + <ul class="no-bullet"> + <li><a id="toc-Compile-commands-1" href="#Compile-commands">4.1 Compile commands</a></li> + <li><a id="toc-Compiler-errors-1" href="#Compiler-errors">4.2 Compiler errors</a></li> + </ul></li> + <li><a id="toc-Project-files-1" href="#Project-files">5 Project files</a> + <ul class="no-bullet"> + <li><a id="toc-Project-File-Overview-1" href="#Project-File-Overview">5.1 Project File Overview</a></li> + <li><a id="toc-GUI-Editor-1" href="#GUI-Editor">5.2 GUI Editor</a></li> + <li><a id="toc-Project-file-variables-1" href="#Project-file-variables">5.3 Project file variables</a></li> + </ul></li> + <li><a id="toc-Compiling-Examples-1" href="#Compiling-Examples">6 Compiling Examples</a> + <ul class="no-bullet"> + <li><a id="toc-No-project-files-1" href="#No-project-files">6.1 No project files</a></li> + <li><a id="toc-Set-compiler-options-1" href="#Set-compiler-options">6.2 Set compiler options</a></li> + <li><a id="toc-Set-source-search-path-1" href="#Set-source-search-path">6.3 Set source search path</a></li> + <li><a id="toc-Use-GNAT-project-file-1" href="#Use-GNAT-project-file">6.4 Use GNAT project file</a></li> + <li><a id="toc-Use-multiple-GNAT-project-files-1" href="#Use-multiple-GNAT-project-files">6.5 Use multiple GNAT project files</a></li> + </ul></li> + <li><a id="toc-Moving-Through-Ada-Code-1" href="#Moving-Through-Ada-Code">7 Moving Through Ada Code</a></li> + <li><a id="toc-Identifier-completion-1" href="#Identifier-completion">8 Identifier completion</a></li> + <li><a id="toc-Automatic-Smart-Indentation-1" href="#Automatic-Smart-Indentation">9 Automatic Smart Indentation</a></li> + <li><a id="toc-Formatting-Parameter-Lists-1" href="#Formatting-Parameter-Lists">10 Formatting Parameter Lists</a></li> + <li><a id="toc-Automatic-Casing-1" href="#Automatic-Casing">11 Automatic Casing</a></li> + <li><a id="toc-Statement-Templates-1" href="#Statement-Templates">12 Statement Templates</a></li> + <li><a id="toc-Comment-Handling-1" href="#Comment-Handling">13 Comment Handling</a></li> + <li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a></li> + <li><a id="toc-Index-1" href="#Index" rel="index">Index</a></li> +</ul> +</div> +</div> +<hr> +<div class="chapter" id="Overview"> +<div class="header"> +<p> +Next: <a href="#Installation" accesskey="n" rel="next">Installation</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Ada Mode</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Overview-1"></span><h2 class="chapter">1 Overview</h2> + +<p>The Emacs mode for programming in Ada helps the user in understanding +existing code and facilitates writing new code. +</p> +<p>When the GNU Ada compiler GNAT is used, the cross-reference +information output by the compiler is used to provide powerful code +navigation (jump to definition, find all uses, etc.). +</p> +<p>When you open a file with a file extension of <samp>.ads</samp> or +<samp>.adb</samp>, Emacs will automatically load and activate Ada mode. +</p> +<p>Ada mode works without any customization, if you are using the GNAT +compiler (<a href="https://libre2.adacore.com/">https://libre2.adacore.com/</a>) and the GNAT default +naming convention. +</p> +<p>You must customize a few things if you are using a different compiler +or file naming convention; See <a href="#Other-compiler">Other compiler</a>, See <a href="#Non_002dstandard-file-names">Non-standard file names</a>. +</p> +<p>In addition, you may want to customize the indentation, +capitalization, and other things; See <a href="#Other-customization">Other customization</a>. +</p> +<p>Finally, for large Ada projects, you will want to set up an Emacs +Ada mode project file for each project; See <a href="#Project-files">Project files</a>. Note +that these are different from the GNAT project files used by gnatmake +and other GNAT commands. +</p> +<p>See the Emacs info manual, section ’Running Debuggers Under Emacs’, +for general information on debugging. +</p> +<hr> +</div> +<div class="chapter" id="Installation"> +<div class="header"> +<p> +Next: <a href="#Customization" accesskey="n" rel="next">Customizing Ada mode</a>, Previous: <a href="#Overview" accesskey="p" rel="prev">Overview</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Installation-1"></span><h2 class="chapter">2 Installation</h2> + +<p>Ada mode is part of the standard Emacs distribution; if you use that, +no files need to be installed. +</p> +<p>Ada mode is also available as a separate distribution, from the Emacs +Ada mode website +<a href="http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html">http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html</a>. The +separate distribution may be more recent. +</p> +<p>For installing the separate distribution, see the <samp>README</samp> file +in the distribution. +</p> +<p>To see what version of Ada mode you have installed, do <kbd>M-x +ada-mode-version</kbd>. +</p> +<p>The following files are provided with the Ada mode distribution: +</p> +<ul> +<li> <samp>ada-mode.el</samp>: The main file for Ada mode, providing indentation, +formatting of parameter lists, moving through code, comment handling +and automatic casing. + +</li><li> <samp>ada-prj.el</samp>: GUI editing of Ada mode project files, using Emacs +widgets. + +</li><li> <samp>ada-stmt.el</samp>: Ada statement templates. + +</li><li> <samp>ada-xref.el</samp>: GNAT cross-references, completion of identifiers, +and compilation. Also provides project files (which are not +GNAT-specific). + +</li></ul> + +<hr> +</div> +<div class="chapter" id="Customization"> +<div class="header"> +<p> +Next: <a href="#Compiling-Executing" accesskey="n" rel="next">Compiling Executing</a>, Previous: <a href="#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Customizing-Ada-mode"></span><h2 class="chapter">3 Customizing Ada mode</h2> + +<p>Here we assume you are familiar with setting variables in Emacs, +either thru ’customize’ or in elisp (in your <samp>.emacs</samp> file). For +a basic introduction to customize, elisp, and Emacs in general, see +the tutorial in +<cite>The GNU Emacs Manual</cite>. +</p> +<p>These global Emacs settings are strongly recommended (put them in your +.emacs): +</p> +<div class="example"> +<pre class="example">(global-font-lock-mode t) +(transient-mark-mode t) +</pre></div> + +<p>‘<samp>(global-font-lock-mode t)</samp>’ turns on syntax +highlighting for all buffers (it is off by default because it may be +too slow for some machines). +</p> +<p>‘<samp>(transient-mark-mode t)</samp>’ highlights selected text. +</p> +<p>See the Emacs help for each of these variables for more information. +</p> + +<ul class="section-toc"> +<li><a href="#Non_002dstandard-file-names" accesskey="1">Non-standard file names</a></li> +<li><a href="#Other-compiler" accesskey="2">Other compiler</a></li> +<li><a href="#Other-customization" accesskey="3">Other customization</a></li> +</ul> +<hr> +<div class="section" id="Non_002dstandard-file-names"> +<div class="header"> +<p> +Next: <a href="#Other-compiler" accesskey="n" rel="next">Other compiler</a>, Up: <a href="#Customization" accesskey="u" rel="up">Customizing Ada mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Non_002dstandard-file-names-1"></span><h3 class="section">3.1 Non-standard file names</h3> + +<p>By default, Ada mode is configured to use the GNAT file naming +convention, where file names are a simple modification of the Ada +names, and the extension for specs and bodies are +‘<samp>.ads</samp>’ and ‘<samp>.adb</samp>’, respectively. +</p> +<p>Ada mode uses the file extensions to allow moving from a package body +to the corresponding spec and back. +</p> +<p>Ada mode supports a list of alternative file extensions for specs and bodies. +</p> +<p>For instance, if your spec and bodies files are called +<samp><var>unit</var>_s.ada</samp> and <samp><var>unit</var>_b.ada</samp>, respectively, you +can add the following to your <samp>.emacs</samp> file: +</p> +<div class="example"> +<pre class="example">(ada-add-extensions "_s.ada" "_b.ada") +</pre></div> + +<p>You can define additional extensions: +</p> +<div class="example"> +<pre class="example">(ada-add-extensions ".ads" "_b.ada") +(ada-add-extensions ".ads" ".body") +</pre></div> + +<p>This means that whenever Ada mode looks for the body for a file +whose extension is <samp>.ads</samp>, it will take the first available file +that ends with either <samp>.adb</samp>, <samp>_b.ada</samp> or +<samp>.body</samp>. +</p> +<p>Similarly, if Ada mode is looking for a spec, it will look for +<samp>.ads</samp> or <samp>_s.ada</samp>. +</p> +<p>If the filename is not derived from the Ada name following the GNAT +convention, things are a little more complicated. You then need to +rewrite the function <code>ada-make-filename-from-adaname</code>. Doing that +is beyond the scope of this manual; see the current definitions in +<samp>ada-mode.el</samp> and <samp>ada-xref.el</samp> for examples. +</p> +<hr> +</div> +<div class="section" id="Other-compiler"> +<div class="header"> +<p> +Next: <a href="#Other-customization" accesskey="n" rel="next">Other customization</a>, Previous: <a href="#Non_002dstandard-file-names" accesskey="p" rel="prev">Non-standard file names</a>, Up: <a href="#Customization" accesskey="u" rel="up">Customizing Ada mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Other-compiler-1"></span><h3 class="section">3.2 Other compiler</h3> + +<p>By default, Ada mode is configured to use the GNU Ada compiler GNAT. +</p> +<p>To use a different Ada compiler, you must specify the command lines +used to run that compiler, either in lisp variables or in Emacs +Ada mode project files. See <a href="#Project-file-variables">Project file variables</a> for the list +of project variables, and the corresponding lisp variables. +</p> +<hr> +</div> +<div class="section" id="Other-customization"> +<div class="header"> +<p> +Previous: <a href="#Other-compiler" accesskey="p" rel="prev">Other compiler</a>, Up: <a href="#Customization" accesskey="u" rel="up">Customizing Ada mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Other-customization-1"></span><h3 class="section">3.3 Other customization</h3> + +<p>All user-settable Ada mode variables can be set via the menu +‘<samp>Ada | Customize</samp>’. Click on the ‘<samp>Help</samp>’ button there for help +on using customize. +</p> +<p>To modify a specific variable, you can directly call the function +<code>customize-variable</code>; just type <kbd>M-x customize-variable +<span class="key">RET</span> <var>variable-name</var> <span class="key">RET</span></kbd>). +</p> +<p>Alternately, you can specify variable settings in the Emacs +configuration file, <samp>.emacs</samp>. This file is coded in Emacs lisp, +and the syntax to set a variable is the following: +</p><div class="example"> +<pre class="example">(setq variable-name value) +</pre></div> + +<hr> +</div> +</div> +<div class="chapter" id="Compiling-Executing"> +<div class="header"> +<p> +Next: <a href="#Project-files" accesskey="n" rel="next">Project files</a>, Previous: <a href="#Customization" accesskey="p" rel="prev">Customizing Ada mode</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compiling-Executing-1"></span><h2 class="chapter">4 Compiling Executing</h2> + +<p>Ada projects can be compiled, linked, and executed using commands on +the Ada menu. All of these commands can be customized via a project +file (see <a href="#Project-files">Project files</a>), but the defaults are sufficient for using +the GNAT compiler for simple projects (single files, or several files +in a single directory). +</p> +<p>Even when no project file is used, the GUI project editor (menu +‘<samp>Ada | Project | Edit</samp>’) shows the settings of the various project +file variables referenced here. +</p> + +<ul class="section-toc"> +<li><a href="#Compile-commands" accesskey="1">Compile commands</a></li> +<li><a href="#Compiler-errors" accesskey="2">Compiler errors</a></li> +</ul> +<hr> +<div class="section" id="Compile-commands"> +<div class="header"> +<p> +Next: <a href="#Compiler-errors" accesskey="n" rel="next">Compiler errors</a>, Up: <a href="#Compiling-Executing" accesskey="u" rel="up">Compiling Executing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compile-commands-1"></span><h3 class="section">4.1 Compile commands</h3> + +<p>Here are the commands for building and using an Ada project, as +listed in the Ada menu. +</p> +<p>In multi-file projects, there must be one file that is the main +program. That is given by the <code>main</code> project file variable; +it defaults to the current file if not yet set, but is also set by the +“set main and build” command. +</p> +<dl compact="compact"> +<dt><span><code>Check file</code></span></dt> +<dd><p>Compiles the current file in syntax check mode, by running +<code>check_cmd</code> defined in the current project file. This typically +runs faster than full compile mode, speeding up finding and fixing +compilation errors. +</p> +<p>This sets <code>main</code> only if it has not been set yet. +</p> +</dd> +<dt><span><code>Compile file</code></span></dt> +<dd><p>Compiles the current file, by running <code>comp_cmd</code> from the current +project file. +</p> +<p>This does not set <code>main</code>. +</p> +</dd> +<dt><span><code>Set main and Build</code></span></dt> +<dd><p>Sets <code>main</code> to the current file, then executes the Build +command. +</p> +</dd> +<dt><span><code>Show main</code></span></dt> +<dd><p>Display <code>main</code> in the message buffer. +</p> +</dd> +<dt><span><code>Build</code></span></dt> +<dd><p>Compiles all obsolete units of the current <code>main</code>, and links +<code>main</code>, by running <code>make_cmd</code> from the current project. +</p> +<p>This sets <code>main</code> only if it has not been set yet. +</p> +</dd> +<dt><span><code>Run</code></span></dt> +<dd><p>Executes the main program in a shell, displayed in a separate Emacs +buffer. This runs <code>run_cmd</code> from the current project. The +execution buffer allows for interactive input/output. +</p> +<p>To modify the run command, in particular to provide or change the +command line arguments, type <kbd>C-u</kbd> before invoking the command. +</p> +<p>This command is not available for a cross-compilation toolchain. +</p> +</dd> +</dl> +<p>It is important when using these commands to understand how +<code>main</code> is used and changed. +</p> +<p>Build runs ’gnatmake’ on the main unit. During a typical edit/compile +session, this is the only command you need to invoke, which is why it +is bound to <kbd>C-c C-c</kbd>. It will compile all files needed by the +main unit, and display compilation errors in any of them. +</p> +<p>Note that Build can be invoked from any Ada buffer; typically you will +be fixing errors in files other than the main, but you don’t have to +switch back to the main to invoke the compiler again. +</p> +<p>Novices and students typically work on single-file Ada projects. In +this case, <kbd>C-c C-m</kbd> will normally be the only command needed; it +will build the current file, rather than the last-built main. +</p> +<p>There are three ways to change <code>main</code>: +</p> +<ol> +<li> Invoke ‘<samp>Ada | Set main and Build</samp>’, which sets <code>main</code> to +the current file. + +</li><li> Invoke ‘<samp>Ada | Project | Edit</samp>’, edit <code>main</code> and +<code>main</code>, and click ‘<samp>[save]</samp>’ + +</li><li> Invoke ‘<samp>Ada | Project | Load</samp>’, and load a project file that specifies <code>main</code> + +</li></ol> + +<hr> +</div> +<div class="section" id="Compiler-errors"> +<div class="header"> +<p> +Previous: <a href="#Compile-commands" accesskey="p" rel="prev">Compile commands</a>, Up: <a href="#Compiling-Executing" accesskey="u" rel="up">Compiling Executing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compiler-errors-1"></span><h3 class="section">4.2 Compiler errors</h3> + +<p>The <code>Check file</code>, <code>Compile file</code>, and <code>Build</code> commands +all place compilation errors in a separate buffer named +<samp>*compilation*</samp>. +</p> +<p>Each line in this buffer will become active: you can simply click on +it with the middle button of the mouse, or move point to it and press +<tt class="key">RET</tt>. Emacs will then display the relevant source file and put +point on the line and column where the error was found. +</p> +<p>You can also press the <kbd>C-x `</kbd> key (<code>next-error</code>), and Emacs +will jump to the first error. If you press that key again, it will +move you to the second error, and so on. +</p> +<p>Some error messages might also include references to other files. These +references are also clickable in the same way, or put point after the +line number and press <tt class="key">RET</tt>. +</p> +<hr> +</div> +</div> +<div class="chapter" id="Project-files"> +<div class="header"> +<p> +Next: <a href="#Compiling-Examples" accesskey="n" rel="next">Compiling Examples</a>, Previous: <a href="#Compiling-Executing" accesskey="p" rel="prev">Compiling Executing</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Project-files-1"></span><h2 class="chapter">5 Project files</h2> + +<p>An Emacs Ada mode project file specifies what directories hold sources +for your project, and allows you to customize the compilation commands +and other things on a per-project basis. +</p> +<p>Note that Ada mode project files <samp>*.adp</samp> are different than GNAT +compiler project files <samp>*.gpr</samp>. However, Emacs Ada mode can use a +GNAT project file to specify the project directories. If no +other customization is needed, a GNAT project file can be used without +an Emacs Ada mode project file. +</p> + +<ul class="section-toc"> +<li><a href="#Project-File-Overview" accesskey="1">Project File Overview</a></li> +<li><a href="#GUI-Editor" accesskey="2">GUI Editor</a></li> +<li><a href="#Project-file-variables" accesskey="3">Project file variables</a></li> +</ul> +<hr> +<div class="section" id="Project-File-Overview"> +<div class="header"> +<p> +Next: <a href="#GUI-Editor" accesskey="n" rel="next">GUI Editor</a>, Up: <a href="#Project-files" accesskey="u" rel="up">Project files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Project-File-Overview-1"></span><h3 class="section">5.1 Project File Overview</h3> + +<p>Project files have a simple syntax; they may be edited directly. Each +line specifies a project variable name and its value, separated by “=”: +</p><div class="example"> +<pre class="example">src_dir=/Projects/my_project/src_1 +src_dir=/Projects/my_project/src_2 +</pre></div> + +<p>Some variables (like <code>src_dir</code>) are lists; multiple occurrences +are concatenated. +</p> +<p>There must be no space between the variable name and “=”, and no +trailing spaces. +</p> +<p>Alternately, a GUI editor for project files is available (see <a href="#GUI-Editor">GUI Editor</a>). It uses Emacs widgets, similar to Emacs customize. +</p> +<p>The GUI editor also provides a convenient way to view current project +settings, if they have been modified using menu commands rather than +by editing the project file. +</p> +<p>After the first Ada mode build command is invoked, there is always a +current project file, given by the lisp variable +<code>ada-prj-default-project-file</code>. Currently, the only way to show +the current project file is to invoke the GUI editor. +</p> +<p>To find the project file the first time, Ada mode uses the following +search algorithm: +</p> +<ul> +<li> If <code>ada-prj-default-project-file</code> is set, use that. + +</li><li> Otherwise, search for a file in the current directory with +the same base name as the Ada file, but extension given by +<code>ada-prj-file-extension</code> (default <code>".adp"</code>). + +</li><li> If not found, search for <samp>*.adp</samp> in the current directory; if +several are found, prompt the user to select one. + +</li><li> If none are found, use <samp>default.adp</samp> in the current directory (even +if it does not exist). + +</li></ul> + +<p>This algorithm always sets <code>ada-prj-default-project-file</code>, even +when the file does not actually exist. +</p> +<p>To change the project file before or after the first one is found, +invoke ‘<samp>Ada | Project | Load ...</samp>’. +</p> +<p>Or, in lisp, evaluate <code>(ada-set-default-project-file "/path/file.adp")</code>. +This sets <code>ada-prj-default-project-file</code>, and reads the project file. +</p> +<p>You can also specify a GNAT project file to ‘<samp>Ada | Project | Load +...</samp>’ or <code>ada-set-default-project-file</code>. Emacs Ada mode checks the +file extension; if it is <code>.gpr</code>, the file is treated as a GNAT +project file. Any other extension is treated as an Emacs Ada mode +project file. +</p> +<hr> +</div> +<div class="section" id="GUI-Editor"> +<div class="header"> +<p> +Next: <a href="#Project-file-variables" accesskey="n" rel="next">Project file variables</a>, Previous: <a href="#Project-File-Overview" accesskey="p" rel="prev">Project File Overview</a>, Up: <a href="#Project-files" accesskey="u" rel="up">Project files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="GUI-Editor-1"></span><h3 class="section">5.2 GUI Editor</h3> + +<p>The project file editor is invoked with the menu ‘<samp>Ada | Projects +| Edit</samp>’. +</p> +<p>Once in the buffer for editing the project file, you can save your +modification using the ‘<samp>[save]</samp>’ button at the bottom of the +buffer, or the <kbd>C-x C-s</kbd> binding. To cancel your modifications, +kill the buffer or click on the ‘<samp>[cancel]</samp>’ button. +</p> +<hr> +</div> +<div class="section" id="Project-file-variables"> +<div class="header"> +<p> +Previous: <a href="#GUI-Editor" accesskey="p" rel="prev">GUI Editor</a>, Up: <a href="#Project-files" accesskey="u" rel="up">Project files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Project-file-variables-1"></span><h3 class="section">5.3 Project file variables</h3> + +<p>The following variables can be defined in a project file; some can +also be defined in lisp variables. +</p> +<p>To set a project variable that is a list, specify each element of the +list on a separate line in the project file. +</p> +<p>Any project variable can be referenced in other project variables, +using a shell-like notation. For instance, if the variable +<code>comp_cmd</code> contains <code>${comp_opt}</code>, the value of the +<code>comp_opt</code> variable will be substituted when <code>comp_cmd</code> is +used. +</p> +<p>In addition, process environment variables can be referenced using the +same syntax, or the normal <code>$var</code> syntax. +</p> +<p>Most project variables have defaults that can be changed by setting +lisp variables; the table below identifies the lisp variable for each +project variable. Lisp variables corresponding to project variables +that are lists are lisp lists. +</p> +<p>In general, project variables are evaluated when referenced in +Emacs Ada mode commands. Relative file paths are expanded to +absolute relative to <code>${build_dir}</code>. +</p> +<p>Here is the list of variables. In the default values, the current +directory <code>"."</code> is the project file directory. +</p> +<dl compact="compact"> +<dt><span><code>ada_project_path_sep</code> [default: <code>":" or ";"</code>]</span></dt> +<dd><p>Path separator for <code>ADA_PROJECT_PATH</code>. It defaults to the correct +value for a native implementation of GNAT for the current operating +system. The user must override this when using Windows native GNAT +with Cygwin Emacs, and perhaps in other cases. +</p> +<p>Lisp variable: <code>ada-prj-ada-project-path-sep</code>. +</p> +</dd> +<dt><span><code>ada_project_path</code> [default: <code>""</code>]</span></dt> +<dd><p>A list of directories to search for GNAT project files. +</p> +<p>If set, the <code>ADA_PROJECT_PATH</code> process environment variable is +set to this value in the Emacs process when the Emacs Ada mode project +is selected via menu ‘<samp>Ada | Project | Load</samp>’. +</p> +<p>For <code>ada_project_path</code>, relative file paths are expanded to +absolute when the Emacs Ada project file is read, rather than when the +project file is selected. +</p> +<p>For example if the project file is in the directory +<samp>/home/myproject</samp>, the environment variable <code>GDS_ROOT</code> is +set to <code>/home/shared</code>, and the project file contains: +</p><div class="example"> +<pre class="example">ada_project_path_sep=: +ada_project_path=$GDS_ROOT/makerules +ada_project_path=../opentoken +</pre></div> +<p>then as a result the environment variable <code>ADA_PROJECT_PATH</code> will +be set to <code>"/home/shared/makerules:/home/opentoken/"</code>. +</p> +<p>The default value is not the current value of this environment +variable, because that will typically have been set by another +project, and will therefore be incorrect for this project. +</p> +<p>If you have the environment variable set correctly for all of your +projects, you do not need to set this project variable. +</p> +</dd> +<dt><span><code>bind_opt</code> [default: <code>""</code>]</span></dt> +<dd><p>Holds user binder options; used in the default build commands. +</p> +<p>Lisp variable: <code>ada-prj-default-bind-opt</code>. +</p> +</dd> +<dt><span><code>build_dir</code> [default: <code>"."</code>]</span></dt> +<dd><p>The compile commands will be issued in this directory. +</p> +</dd> +<dt><span><code>casing</code> [default: <code>("~/.emacs_case_exceptions")</code>]</span></dt> +<dd><p>List of files containing casing exceptions. See the help on +<code>ada-case-exception-file</code> for more info. +</p> +<p>Lisp variable: <code>ada-case-exception-file</code>. +</p> +</dd> +<dt><span><code>check_cmd</code> [default: <code>"${cross_prefix}gnatmake -u -c -gnatc ${gnatmake_opt} ${full_current} -cargs ${comp_opt}"</code>]</span></dt> +<dd><p>Command used to syntax check a single file. +The name of the file is substituted for <code>full_current</code>. +</p> +<p>Lisp variable: <code>ada-prj-default-check-cmd</code> +</p> +</dd> +<dt><span><code>comp_cmd</code> [default: <code>"${cross_prefix}gnatmake -u -c ${gnatmake_opt} ${full_current} -cargs ${comp_opt}"</code>]</span></dt> +<dd><p>Command used to compile a single file. +The name of the file is substituted for <code>full_current</code>. +</p> +<p>Lisp variable: <code>ada-prj-default-comp-cmd</code>. +</p> +</dd> +<dt><span><code>comp_opt</code> [default: <code>"-gnatq -gnatQ"</code>]</span></dt> +<dd><p>Holds user compiler options; used in the default compile commands. The +default value tells gnatmake to generate library files for +cross-referencing even when there are errors. +</p> +<p>If source code for the project is in multiple directories, the +appropriate compiler options must be added here. <a href="#Set-source-search-path">Set source search path</a> for examples of this. Alternately, GNAT project files may +be used; <a href="#Use-GNAT-project-file">Use GNAT project file</a>. +</p> +<p>Lisp variable: <code>ada-prj-default-comp-opt</code>. +</p> +</dd> +<dt><span><code>cross_prefix</code> [default: <code>""</code>]</span></dt> +<dd><p>Name of target machine in a cross-compilation environment. Used in +default compile and build commands. +</p> +</dd> +<dt><span><code>debug_cmd</code> [default: <code>"${cross_prefix}gdb ${main}"</code>]</span></dt> +<dd><p>Command used to debug the application +</p> +<p>Lisp variable: <code>ada-prj-default-debugger</code>. +</p> +</dd> +<dt><span><code>debug_post_cmd</code> [default: <code>""</code>]</span></dt> +<dd><p>Command executed after <code>debug_cmd</code>. +</p> +</dd> +<dt><span><code>debug_pre_cmd</code> [default: <code>"cd ${build_dir}"</code>]</span></dt> +<dd><p>Command executed before <code>debug_cmd</code>. +</p> +</dd> +<dt><span><code>gnatfind_opt</code> [default: <code>"-rf"</code>]</span></dt> +<dd><p>Holds user gnatfind options; used in the default find commands. +</p> +<p>Lisp variable: <code>ada-prj-gnatfind-switches</code>. +</p> +</dd> +<dt><span><code>gnatmake_opt</code> [default: <code>"-g"</code>]</span></dt> +<dd><p>Holds user gnatmake options; used in the default build commands. +</p> +<p>Lisp variable: <code>ada-prj-default-gnatmake-opt</code>. +</p> +</dd> +<dt><span><code>gpr_file</code> [default: <code>""</code>]</span></dt> +<dd><p>Specify GNAT project file. +</p> +<p>If set, the source and object directories specified in the GNAT +project file are appended to <code>src_dir</code> and <code>obj_dir</code>. This +allows specifying Ada source directories with a GNAT project file, and +other source directories with the Emacs project file. +</p> +<p>In addition, <code>-P{gpr_file}</code> is added to the project variable +<code>gnatmake_opt</code> whenever it is referenced. With the default +project variables, this passes the project file to all gnatmake +commands. +</p> +<p>Lisp variable: <code>ada-prj-default-gpr-file</code>. +</p> + +</dd> +<dt><span><code>link_opt</code> [default: <code>""</code>]</span></dt> +<dd><p>Holds user linker options; used in the default build commands. +</p> +<p>Lisp variable: <code>ada-prj-default-link-opt</code>. +</p> +</dd> +<dt><span><code>main</code> [default: current file]</span></dt> +<dd><p>Specifies the name of the executable file for the project; used in the +default build commands. +</p> +</dd> +<dt><span><code>make_cmd</code> [default: <code>"${cross_prefix}gnatmake -o ${main} ${main} ${gnatmake_opt} -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"</code>]</span></dt> +<dd><p>Command used to build the application. +</p> +<p>Lisp variable: <code>ada-prj-default-make-cmd</code>. +</p> +</dd> +<dt><span><code>obj_dir</code> [default: <code>"."</code>]</span></dt> +<dd><p>A list of directories to search for library files. Ada mode searches +this list for the ‘<samp>.ali</samp>’ files generated by GNAT that contain +cross-reference information. +</p> +<p>The compiler commands must place the ‘<samp>.ali</samp>’ files in one of these +directories; the default commands do that. +</p> +</dd> +<dt><span><code>remote_machine</code> [default: <code>""</code>]</span></dt> +<dd><p>Name of the machine to log into before issuing the compile and build +commands. If this variable is empty, the command will be run on the +local machine. +</p> +</dd> +<dt><span><code>run_cmd</code> [default: <code>"./${main}"</code>]</span></dt> +<dd><p>Command used to run the application. +</p> +</dd> +<dt><span><code>src_dir</code> [default: <code>"."</code>]</span></dt> +<dd><p>A list of directories to search for source files, both for compile +commands and source navigation. +</p> +</dd> +</dl> + +<hr> +</div> +</div> +<div class="chapter" id="Compiling-Examples"> +<div class="header"> +<p> +Next: <a href="#Moving-Through-Ada-Code" accesskey="n" rel="next">Moving Through Ada Code</a>, Previous: <a href="#Project-files" accesskey="p" rel="prev">Project files</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compiling-Examples-1"></span><h2 class="chapter">6 Compiling Examples</h2> + +<p>We present several small projects, and walk thru the process of +compiling, linking, and running them. +</p> +<p>The first example illustrates more Ada mode features than the others; +you should work thru that example before doing the others. +</p> +<p>All of these examples assume you are using GNAT. +</p> +<p>The source for these examples is available on the Emacs Ada mode +website mentioned in See <a href="#Installation">Installation</a>. +</p> + +<ul class="section-toc"> +<li><a href="#No-project-files" accesskey="1">No project files</a></li> +<li><a href="#Set-compiler-options" accesskey="2">Set compiler options</a></li> +<li><a href="#Set-source-search-path" accesskey="3">Set source search path</a></li> +<li><a href="#Use-GNAT-project-file" accesskey="4">Use GNAT project file</a></li> +<li><a href="#Use-multiple-GNAT-project-files" accesskey="5">Use multiple GNAT project files</a></li> +</ul> +<hr> +<div class="section" id="No-project-files"> +<div class="header"> +<p> +Next: <a href="#Set-compiler-options" accesskey="n" rel="next">Set compiler options</a>, Up: <a href="#Compiling-Examples" accesskey="u" rel="up">Compiling Examples</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="No-project-files-1"></span><h3 class="section">6.1 No project files</h3> +<p>This example uses no project files. +</p> +<p>First, create a directory <samp>Example_1</samp>, containing: +</p> +<p><samp>hello.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +</pre></div> + +<p>Yes, this is missing “use Ada.Text_IO;” - we want to demonstrate +compiler error handling. +</p> +<p><samp>hello_2.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Hello_Pkg; +procedure Hello_2 +is begin + Hello_Pkg.Say_Hello; +end Hello_2; +</pre></div> + +<p>This file has no errors. +</p> +<p><samp>hello_pkg.ads</samp>: +</p> +<div class="example"> +<pre class="example">package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +</pre></div> + +<p>This file has no errors. +</p> +<p><samp>hello_pkg.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +</pre></div> + +<p>Yes, this is missing the keyword <code>body</code>; another compiler error +example. +</p> +<p>In buffer <samp>hello.adb</samp>, invoke ‘<samp>Ada | Check file</samp>’. You should +get a <samp>*compilation*</samp> buffer containing something like (the +directory paths will be different): +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_1/ +gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ +gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +gnatmake: "c:/Examples/Example_1/hello.adb" compilation error +</pre></div> + +<p>If you have enabled font-lock, the lines with actual errors (starting +with <samp>hello.adb</samp>) are highlighted, with the file name in red. +</p> +<p>Now type <kbd>C-x `</kbd> (on a PC keyboard, <tt class="key">`</tt> is next to <tt class="key">1</tt>). +Or you can click the middle mouse button on the first error line. The +compilation buffer scrolls to put the first error on the top line, and +point is put at the place of the error in the <samp>hello.adb</samp> buffer. +</p> +<p>To fix the error, change the line to be +</p> +<div class="example"> +<pre class="example"> Ada.Text_IO.Put_Line ("hello from hello.adb"); +</pre></div> + +<p>Now invoke ‘<samp>Ada | Show main</samp>’; this displays ‘<samp>Ada mode main: hello</samp>’. +</p> +<p>Now (in buffer <samp>hello.adb</samp>), invoke ‘<samp>Ada | Build</samp>’. You are +prompted to save the file (if you haven’t already). Then the +compilation buffer is displayed again, containing: +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_1/ +gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello.adb +gnatbind -x hello.ali +gnatlink hello.ali -o hello.exe -g +</pre></div> + +<p>The compilation has succeeded without errors; <samp>hello.exe</samp> now +exists in the same directory as <samp>hello.adb</samp>. +</p> +<p>Now invoke ‘<samp>Ada | Run</samp>’. A <samp>*run*</samp> buffer is displayed, +containing +</p> +<div class="example"> +<pre class="example">Hello from hello.adb + +Process run finished +</pre></div> + +<p>That completes the first part of this example. +</p> +<p>Now we will compile a multi-file project. Open the file +<samp>hello_2.adb</samp>, and invoke ‘<samp>Ada | Set main and Build</samp>’. This +finds an error in <samp>hello_pkg.adb</samp>: +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_1/ +gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "hello_pkg.adb" compilation error +</pre></div> + +<p>This demonstrates that gnatmake finds the files needed by the main +program. However, it cannot find files in a different directory, +unless you use an Emacs Ada mode project file to specify the other directories; +See <a href="#Set-source-search-path">Set source search path</a>, or a GNAT project file; <a href="#Use-GNAT-project-file">Use GNAT project file</a>. +</p> +<p>Invoke ‘<samp>Ada | Show main</samp>’; this displays <samp>Ada mode main: hello_2</samp>. +</p> +<p>Move to the error with <kbd>C-x `</kbd>, and fix the error by adding <code>body</code>: +</p> +<div class="example"> +<pre class="example">package body Hello_Pkg is +</pre></div> + +<p>Now, while still in <samp>hello_pkg.adb</samp>, invoke ‘<samp>Ada | Build</samp>’. +gnatmake successfully builds <samp>hello_2</samp>. This demonstrates that +Emacs has remembered the main file, in the project variable +<code>main</code>, and used it for the Build command. +</p> +<p>Finally, again while in <samp>hello_pkg.adb</samp>, invoke ‘<samp>Ada | Run</samp>’. +The <samp>*run*</samp> buffer displays <code>Hello from hello_pkg.adb</code>. +</p> +<p>One final point. If you switch back to buffer <samp>hello.adb</samp>, and +invoke ‘<samp>Ada | Run</samp>’, <samp>hello_2.exe</samp> will be run. That is +because <code>main</code> is still set to <code>hello_2</code>, as you can +see when you invoke ‘<samp>Ada | Project | Edit</samp>’. +</p> +<p>There are three ways to change <code>main</code>: +</p> +<ol> +<li> Invoke ‘<samp>Ada | Set main and Build</samp>’, which sets <code>main</code> to +the current file. + +</li><li> Invoke ‘<samp>Ada | Project | Edit</samp>’, edit <code>main</code>, and click ‘<samp>[save]</samp>’ + +</li><li> Invoke ‘<samp>Ada | Project | Load</samp>’, and load a project file that specifies <code>main</code> + +</li></ol> + +<hr> +</div> +<div class="section" id="Set-compiler-options"> +<div class="header"> +<p> +Next: <a href="#Set-source-search-path" accesskey="n" rel="next">Set source search path</a>, Previous: <a href="#No-project-files" accesskey="p" rel="prev">No project files</a>, Up: <a href="#Compiling-Examples" accesskey="u" rel="up">Compiling Examples</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Set-compiler-options-1"></span><h3 class="section">6.2 Set compiler options</h3> + +<p>This example illustrates using an Emacs Ada mode project file to set a +compiler option. +</p> +<p>If you have files from <samp>Example_1</samp> open in Emacs, you should +close them so you don’t get confused. Use menu ‘<samp>File | Close +(current buffer)</samp>’. +</p> +<p>In directory <samp>Example_2</samp>, create these files: +</p> +<p><samp>hello.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +</pre></div> + +<p>This is the same as <samp>hello.adb</samp> from <samp>Example_1</samp>. It has two +errors; missing “use Ada.Text_IO;”, and no space between +<code>Put_Line</code> and its argument list. +</p> +<p><samp>hello.adp</samp>: +</p> +<div class="example"> +<pre class="example">comp_opt=-gnatyt +</pre></div> + +<p>This tells the GNAT compiler to check for token spacing; in +particular, there must be a space preceding a parenthesis. +</p> +<p>In buffer <samp>hello.adb</samp>, invoke ‘<samp>Ada | Project | Load...</samp>’, and +select <samp>Example_2/hello.adp</samp>. +</p> +<p>Then, again in buffer <samp>hello.adb</samp>, invoke ‘<samp>Ada | Set main and +Build</samp>’. You should get a <samp>*compilation*</samp> buffer containing +something like (the directory paths will be different): +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_2/ +gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs +gcc -c -g -gnatyt hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +hello.adb:4:12: (style) space required +gnatmake: "hello.adb" compilation error +</pre></div> + +<p>Compare this to the compiler output in <a href="#No-project-files">No project files</a>; the +gnatmake option <code>-cargs -gnatq -gnatQ</code> has been replaced by +<code>-cargs -gnaty</code>, and an additional error is reported in +<samp>hello.adb</samp> on line 4. This shows that <samp>hello.adp</samp> is being +used to set the compiler options. +</p> +<p>Fixing the error, linking and running the code proceed as in <a href="#No-project-files">No project files</a>. +</p> +<hr> +</div> +<div class="section" id="Set-source-search-path"> +<div class="header"> +<p> +Next: <a href="#Use-GNAT-project-file" accesskey="n" rel="next">Use GNAT project file</a>, Previous: <a href="#Set-compiler-options" accesskey="p" rel="prev">Set compiler options</a>, Up: <a href="#Compiling-Examples" accesskey="u" rel="up">Compiling Examples</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Set-source-search-path-1"></span><h3 class="section">6.3 Set source search path</h3> + +<p>In this example, we show how to deal with files in more than one +directory. We start with the same code as in <a href="#No-project-files">No project files</a>; +create those files (with the errors present) +</p> +<p>Create the directory <samp>Example_3</samp>, containing: +</p> +<p><samp>hello_pkg.ads</samp>: +</p> +<div class="example"> +<pre class="example">package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +</pre></div> + +<p><samp>hello_pkg.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +</pre></div> + +<p>These are the same files from example 1; <samp>hello_pkg.adb</samp> has an +error on line 2. +</p> +<p>In addition, create a directory <samp>Example_3/Other</samp>, containing these files: +</p> +<p><samp>Other/hello_3.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_3 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_3"); +end Hello_3; +</pre></div> + +<p>There are no errors in this file. +</p> +<p><samp>Other/other.adp</samp>: +</p> +<div class="example"> +<pre class="example">src_dir=.. +comp_opt=-I.. +</pre></div> + +<p>Note that there must be no trailing spaces. +</p> +<p>In buffer <samp>hello_3.adb</samp>, invoke ‘<samp>Ada | Project | Load...</samp>’, and +select <samp>Example_3/Other/other.adp</samp>. +</p> +<p>Then, again in <samp>hello_3.adb</samp>, invoke ‘<samp>Ada | Set main and +Build</samp>’. You should get a <samp>*compilation*</samp> buffer containing +something like (the directory paths will be different): +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_3/Other/ +gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs +gcc -c -g -I.. hello_3.adb +gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error +</pre></div> + +<p>Compare the <code>-cargs</code> option to the compiler output in <a href="#Set-compiler-options">Set compiler options</a>; this shows that <samp>other.adp</samp> is being used to +set the compiler options. +</p> +<p>Move to the error with <kbd>C-x `</kbd>. Ada mode searches the list of +directories given by <code>src_dir</code> for the file mentioned in the +compiler error message. +</p> +<p>Fixing the error, linking and running the code proceed as in <a href="#No-project-files">No project files</a>. +</p> +<hr> +</div> +<div class="section" id="Use-GNAT-project-file"> +<div class="header"> +<p> +Next: <a href="#Use-multiple-GNAT-project-files" accesskey="n" rel="next">Use multiple GNAT project files</a>, Previous: <a href="#Set-source-search-path" accesskey="p" rel="prev">Set source search path</a>, Up: <a href="#Compiling-Examples" accesskey="u" rel="up">Compiling Examples</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Use-GNAT-project-file-1"></span><h3 class="section">6.4 Use GNAT project file</h3> + +<p>In this example, we show how to use a GNAT project file, with no Ada +mode project file. +</p> +<p>Create the directory <samp>Example_4</samp>, containing: +</p> +<p><samp>hello_pkg.ads</samp>: +</p> +<div class="example"> +<pre class="example">package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +</pre></div> + +<p><samp>hello_pkg.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +</pre></div> + +<p>These are the same files from example 1; <samp>hello_pkg.adb</samp> has an +error on line 2. +</p> +<p>In addition, create a directory <samp>Example_4/Gnat_Project</samp>, +containing these files: +</p> +<p><samp>Gnat_Project/hello_4.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_4 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_4"); +end Hello_4; +</pre></div> + +<p>There are no errors in this file. +</p> +<p><samp>Gnat_Project/hello_4.gpr</samp>: +</p> +<div class="example"> +<pre class="example">Project Hello_4 is + for Source_Dirs use (".", ".."); +end Hello_4; +</pre></div> + +<p>In buffer <samp>hello_4.adb</samp>, invoke ‘<samp>Ada | Project | Load...</samp>’, and +select <samp>Example_4/Gnat_Project/hello_4.gpr</samp>. +</p> +<p>Then, again in <samp>hello_4.adb</samp>, invoke ‘<samp>Ada | Set main and +Build</samp>’. You should get a <samp>*compilation*</samp> buffer containing +something like (the directory paths will be different): +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_4/Gnat_Project/ +gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error +</pre></div> + +<p>Compare the <code>gcc</code> options to the compiler output in <a href="#Set-compiler-options">Set compiler options</a>; this shows that <samp>hello_4.gpr</samp> is being used to +set the compiler options. +</p> +<p>Fixing the error, linking and running the code proceed as in <a href="#No-project-files">No project files</a>. +</p> +<hr> +</div> +<div class="section" id="Use-multiple-GNAT-project-files"> +<div class="header"> +<p> +Previous: <a href="#Use-GNAT-project-file" accesskey="p" rel="prev">Use GNAT project file</a>, Up: <a href="#Compiling-Examples" accesskey="u" rel="up">Compiling Examples</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Use-multiple-GNAT-project-files-1"></span><h3 class="section">6.5 Use multiple GNAT project files</h3> + +<p>In this example, we show how to use multiple GNAT project files, +specifying the GNAT project search path in an Ada mode project file. +</p> +<p>Create the directory <samp>Example_4</samp> as specified in <a href="#Use-GNAT-project-file">Use GNAT project file</a>. +</p> +<p>Create the directory <samp>Example_5</samp>, containing: +</p> +<p><samp>hello_5.adb</samp>: +</p> +<div class="example"> +<pre class="example">with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_5 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_5"); +end Hello_5; +</pre></div> + +<p>There are no errors in this file. +</p> +<p><samp>hello_5.adp</samp>: +</p> +<div class="example"> +<pre class="example">ada_project_path=../Example_4/Gnat_Project +gpr_file=hello_5.gpr +</pre></div> + +<p><samp>hello_5.gpr</samp>: +</p> +<div class="example"> +<pre class="example">with "hello_4"; +Project Hello_5 is + for Source_Dirs use ("."); + package Compiler is + for Default_Switches ("Ada") use ("-g", "-gnatyt"); + end Compiler; +end Hello_5; +</pre></div> + +<p>In buffer <samp>hello_5.adb</samp>, invoke ‘<samp>Ada | Project | Load...</samp>’, and +select <samp>Example_5/hello_5.adp</samp>. +</p> +<p>Then, again in <samp>hello_5.adb</samp>, invoke ‘<samp>Ada | Set main and +Build</samp>’. You should get a <samp>*compilation*</samp> buffer containing +something like (the directory paths will be different): +</p> +<div class="example"> +<pre class="example">cd c:/Examples/Example_5/ +gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb +gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error +</pre></div> + +<p>Now type <kbd>C-x `</kbd>. <samp>Example_4/hello_pkg.adb</samp> is shown, +demonstrating that <samp>hello_5.gpr</samp> and <samp>hello_4.gpr</samp> are being +used to set the compilation search path. +</p> +<hr> +</div> +</div> +<div class="chapter" id="Moving-Through-Ada-Code"> +<div class="header"> +<p> +Next: <a href="#Identifier-completion" accesskey="n" rel="next">Identifier completion</a>, Previous: <a href="#Compiling-Examples" accesskey="p" rel="prev">Compiling Examples</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Moving-Through-Ada-Code-1"></span><h2 class="chapter">7 Moving Through Ada Code</h2> + +<p>There are several easy to use commands to navigate through Ada code. All +these functions are available through the Ada menu, and you can also +use the following key bindings or the command names. Some of these +menu entries are available only if the GNAT compiler is used, since +the implementation relies on the GNAT cross-referencing information. +</p> +<dl compact="compact"> +<dt id='index-ada_002dnext_002dprocedure'><span><kbd>M-C-e</kbd><a href='#index-ada_002dnext_002dprocedure' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to the next function/procedure/task, which ever comes next +(<code>ada-next-procedure</code>). +</p></dd> +<dt id='index-ada_002dprevious_002dprocedure'><span><kbd>M-C-a</kbd><a href='#index-ada_002dprevious_002dprocedure' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to previous function/procedure/task +(<code>ada-previous-procedure</code>). +</p></dd> +<dt id='index-ada_002dnext_002dpackage'><span><kbd>M-x ada-next-package</kbd><a href='#index-ada_002dnext_002dpackage' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to next package. +</p></dd> +<dt id='index-ada_002dprevious_002dpackage'><span><kbd>M-x ada-previous-package</kbd><a href='#index-ada_002dprevious_002dpackage' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to previous package. +</p></dd> +<dt id='index-ada_002dmove_002dto_002dstart'><span><kbd>C-c C-a</kbd><a href='#index-ada_002dmove_002dto_002dstart' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to matching start of <code>end</code> (<code>ada-move-to-start</code>). If +point is at the end of a subprogram, this command jumps to the +corresponding <code>begin</code> if the user option +<code>ada-move-to-declaration</code> is <code>nil</code> (default), otherwise it jumps to +the subprogram declaration. +</p></dd> +<dt id='index-ada_002dmove_002dto_002dend'><span><kbd>C-c C-e</kbd><a href='#index-ada_002dmove_002dto_002dend' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move point to end of current block (<code>ada-move-to-end</code>). +</p></dd> +<dt><span><kbd>C-c o</kbd></span></dt> +<dd><p>Switch between corresponding spec and body file +(<code>ff-find-other-file</code>). If point is in a subprogram, position +point on the corresponding declaration or body in the other file. +</p></dd> +<dt id='index-ada_002dgoto_002ddeclaration'><span><kbd>C-c c-d</kbd><a href='#index-ada_002dgoto_002ddeclaration' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move from any reference to its declaration, for from a declaration to +its body (for procedures, tasks, private and incomplete types). +</p></dd> +<dt id='index-ada_002dfind_002dreferences'><span><kbd>C-c C-r</kbd><a href='#index-ada_002dfind_002dreferences' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Runs the <samp>gnatfind</samp> command to search for all references to the +identifier surrounding point (<code>ada-find-references</code>). Use +<kbd>C-x `</kbd> (<code>next-error</code>) to visit each reference (as for +compilation errors). +</p></dd> +</dl> + +<p>If the <code>ada-xref-create-ali</code> variable is non-<code>nil</code>, Emacs +will try to run GNAT for you whenever cross-reference information is +needed, and is older than the current source file. +</p> +<hr> +</div> +<div class="chapter" id="Identifier-completion"> +<div class="header"> +<p> +Next: <a href="#Automatic-Smart-Indentation" accesskey="n" rel="next">Automatic Smart Indentation</a>, Previous: <a href="#Moving-Through-Ada-Code" accesskey="p" rel="prev">Moving Through Ada Code</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Identifier-completion-1"></span><h2 class="chapter">8 Identifier completion</h2> + +<p>Emacs and Ada mode provide two general ways for the completion of +identifiers. This is an easy way to type faster: you just have to type +the first few letters of an identifiers, and then loop through all the +possible completions. +</p> +<p>The first method is general for Emacs. It works by parsing all open +files for possible completions. +</p> +<p>For instance, if the words ‘<samp>my_identifier</samp>’, ‘<samp>my_subprogram</samp>’ +are the only words starting with ‘<samp>my</samp>’ in any of the opened files, +then you will have this scenario: +</p> +<div class="example"> +<pre class="example">You type: my<kbd>M-/</kbd> +Emacs inserts: ‘<samp>my_identifier</samp>’ +If you press <kbd>M-/</kbd> once again, Emacs replaces ‘<samp>my_identifier</samp>’ with +‘<samp>my_subprogram</samp>’. +Pressing <kbd>M-/</kbd> once more will bring you back to ‘<samp>my_identifier</samp>’. +</pre></div> + +<p>This is a very fast way to do completion, and the casing of words will +also be respected. +</p> +<p>The second method (<kbd>C-<span class="key">TAB</span></kbd>) is specific to Ada mode and the GNAT +compiler. Emacs will search the cross-information for possible +completions. +</p> +<p>The main advantage is that this completion is more accurate: only +existing identifier will be suggested. +</p> +<p>On the other hand, this completion is a little bit slower and requires +that you have compiled your file at least once since you created that +identifier. +</p> +<dl compact="compact"> +<dt id='index-ada_002dcomplete_002didentifier'><span><kbd>C-<span class="key">TAB</span></kbd><a href='#index-ada_002dcomplete_002didentifier' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Complete current identifier using cross-reference information. +</p></dd> +<dt><span><kbd>M-/</kbd></span></dt> +<dd><p>Complete identifier using buffer information (not Ada-specific). +</p></dd> +</dl> + +<hr> +</div> +<div class="chapter" id="Automatic-Smart-Indentation"> +<div class="header"> +<p> +Next: <a href="#Formatting-Parameter-Lists" accesskey="n" rel="next">Formatting Parameter Lists</a>, Previous: <a href="#Identifier-completion" accesskey="p" rel="prev">Identifier completion</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Automatic-Smart-Indentation-1"></span><h2 class="chapter">9 Automatic Smart Indentation</h2> + +<p>Ada mode comes with a full set of rules for automatic indentation. You +can also configure the indentation, via the following variables: +</p> +<dl compact="compact"> +<dt><span><code>ada-broken-indent</code> (default value: 2)</span></dt> +<dd><p>Number of columns to indent the continuation of a broken line. +</p> +</dd> +<dt><span><code>ada-indent</code> (default value: 3)</span></dt> +<dd><p>Number of columns for default indentation. +</p> +</dd> +<dt><span><code>ada-indent-record-rel-type</code> (default value: 3)</span></dt> +<dd><p>Indentation for <code>record</code> relative to <code>type</code> or <code>use</code>. +</p> +</dd> +<dt><span><code>ada-indent-return</code> (default value: 0)</span></dt> +<dd><p>Indentation for <code>return</code> relative to <code>function</code> (if +<code>ada-indent-return</code> is greater than 0), or the open parenthesis +(if <code>ada-indent-return</code> is negative or 0). Note that in the second +case, when there is no open parenthesis, the indentation is done +relative to <code>function</code> with the value of <code>ada-broken-indent</code>. +</p> +</dd> +<dt><span><code>ada-label-indent</code> (default value: -4)</span></dt> +<dd><p>Number of columns to indent a label. +</p> +</dd> +<dt><span><code>ada-stmt-end-indent</code> (default value: 0)</span></dt> +<dd><p>Number of columns to indent a statement <code>end</code> keyword on a separate line. +</p> +</dd> +<dt><span><code>ada-when-indent</code> (default value: 3)</span></dt> +<dd><p>Indentation for <code>when</code> relative to <code>exception</code> or <code>case</code>. +</p> +</dd> +<dt><span><code>ada-indent-is-separate</code> (default value: t)</span></dt> +<dd><p>Non-<code>nil</code> means indent <code>is separate</code> or <code>is abstract</code> if on a single line. +</p> +</dd> +<dt><span><code>ada-indent-to-open-paren</code> (default value: t)</span></dt> +<dd><p>Non-<code>nil</code> means indent according to the innermost open parenthesis. +</p> +</dd> +<dt><span><code>ada-indent-after-return</code> (default value: t)</span></dt> +<dd><p>Non-<code>nil</code> means that the current line will also be re-indented +before inserting a newline, when you press <tt class="key">RET</tt>. +</p></dd> +</dl> + +<p>Most of the time, the indentation will be automatic, i.e., when you +press <tt class="key">RET</tt>, the cursor will move to the correct column on the +next line. +</p> +<p>You can also indent single lines, or the current region, with <tt class="key">TAB</tt>. +</p> +<p>Another mode of indentation exists that helps you to set up your +indentation scheme. If you press <kbd>C-c <span class="key">TAB</span></kbd>, Ada mode will do +the following: +</p> +<ul> +<li> Reindent the current line, as <tt class="key">TAB</tt> would do. +</li><li> Temporarily move the cursor to a reference line, i.e., the line that +was used to calculate the current indentation. +</li><li> Display in the message window the name of the variable that provided +the offset for the indentation. +</li></ul> + +<p>The exact indentation of the current line is the same as the one for the +reference line, plus an offset given by the variable. +</p> +<dl compact="compact"> +<dt><span><kbd><span class="key">TAB</span></kbd></span></dt> +<dd><p>Indent the current line or the current region. +</p></dd> +<dt><span><kbd>C-M-\</kbd></span></dt> +<dd><p>Indent lines in the current region. +</p></dd> +<dt><span><kbd>C-c <span class="key">TAB</span></kbd></span></dt> +<dd><p>Indent the current line and display the name of the variable used for +indentation. +</p></dd> +</dl> + +<hr> +</div> +<div class="chapter" id="Formatting-Parameter-Lists"> +<div class="header"> +<p> +Next: <a href="#Automatic-Casing" accesskey="n" rel="next">Automatic Casing</a>, Previous: <a href="#Automatic-Smart-Indentation" accesskey="p" rel="prev">Automatic Smart Indentation</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Formatting-Parameter-Lists-1"></span><h2 class="chapter">10 Formatting Parameter Lists</h2> + +<dl compact="compact"> +<dt id='index-ada_002dformat_002dparamlist'><span><kbd>C-c C-f</kbd><a href='#index-ada_002dformat_002dparamlist' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Format the parameter list (<code>ada-format-paramlist</code>). +</p></dd> +</dl> + +<p>This aligns the declarations on the colon (‘<samp>:</samp>’) separating +argument names and argument types, and aligns the <code>in</code>, +<code>out</code> and <code>in out</code> keywords. +</p> +<hr> +</div> +<div class="chapter" id="Automatic-Casing"> +<div class="header"> +<p> +Next: <a href="#Statement-Templates" accesskey="n" rel="next">Statement Templates</a>, Previous: <a href="#Formatting-Parameter-Lists" accesskey="p" rel="prev">Formatting Parameter Lists</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Automatic-Casing-1"></span><h2 class="chapter">11 Automatic Casing</h2> + +<p>Casing of identifiers, attributes and keywords is automatically +performed while typing when the variable <code>ada-auto-case</code> is set. +Every time you press a word separator, the previous word is +automatically cased. +</p> +<p>You can customize the automatic casing differently for keywords, +attributes and identifiers. The relevant variables are the following: +<code>ada-case-keyword</code>, <code>ada-case-attribute</code> and +<code>ada-case-identifier</code>. +</p> +<p>All these variables can have one of the following values: +</p> +<dl compact="compact"> +<dt><span><code>downcase-word</code></span></dt> +<dd><p>The word will be lowercase. For instance <code>My_vARIable</code> is +converted to <code>my_variable</code>. +</p> +</dd> +<dt><span><code>upcase-word</code></span></dt> +<dd><p>The word will be uppercase. For instance <code>My_vARIable</code> is +converted to <code>MY_VARIABLE</code>. +</p> +</dd> +<dt><span><code>ada-capitalize-word</code></span></dt> +<dd><p>The first letter and each letter following an underscore (‘<samp>_</samp>’) +are uppercase, others are lowercase. For instance <code>My_vARIable</code> +is converted to <code>My_Variable</code>. +</p> +</dd> +<dt><span><code>ada-loose-case-word</code></span></dt> +<dd><p>Characters after an underscore ‘<samp>_</samp>’ character are uppercase, +others are not modified. For instance <code>My_vARIable</code> is converted +to <code>My_VARIable</code>. +</p></dd> +</dl> + +<p>Ada mode allows you to define exceptions to these rules, in a file +specified by the variable <code>ada-case-exception-file</code> +(default <samp>~/.emacs_case_exceptions</samp>). Each line in this file +specifies the casing of one word or word fragment. Comments may be +included, separated from the word by a space. +</p> +<p>If the word starts with an asterisk (‘<samp>*</samp>’), it defines the casing +as a word fragment (or “substring”); part of a word between two +underscores or word boundary. +</p> +<p>For example: +</p> +<div class="example"> +<pre class="example">DOD Department of Defense +*IO +GNAT The GNAT compiler from Ada Core Technologies +</pre></div> + +<p>The word fragment <code>*IO</code> applies to any word containing “_io”; +<code>Text_IO</code>, <code>Hardware_IO</code>, etc. +</p> +<span id="index-ada_002dcreate_002dcase_002dexception"></span> +<p>There are two ways to add new items to this file: you can simply edit +it as you would edit any text file. Or you can position point on the +word you want to add, and select menu ‘<samp>Ada | Edit | Create Case +Exception</samp>’, or press <kbd>C-c C-y</kbd> (<code>ada-create-case-exception</code>). +The word will automatically be added to the current list of exceptions +and to the file. +</p> +<p>To define a word fragment case exception, select the word fragment, +then select menu ‘<samp>Ada | Edit | Create Case Exception Substring</samp>’. +</p> +<p>It is sometimes useful to have multiple exception files around (for +instance, one could be the standard Ada acronyms, the second some +company specific exceptions, and the last one some project specific +exceptions). If you set up the variable <code>ada-case-exception-file</code> +as a list of files, each of them will be parsed and used in your emacs +session. However, when you save a new exception through the menu, as +described above, the new exception will be added to the first file in +the list. +</p> +<dl compact="compact"> +<dt id='index-ada_002dadjust_002dcase_002dbuffer'><span><kbd>C-c C-b</kbd><a href='#index-ada_002dadjust_002dcase_002dbuffer' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Adjust case in the whole buffer (<code>ada-adjust-case-buffer</code>). +</p></dd> +<dt><span><kbd>C-c C-y</kbd></span></dt> +<dd><p>Create a new entry in the exception dictionary, with the word under +the cursor (<code>ada-create-case-exception</code>) +</p></dd> +<dt id='index-ada_002dcase_002dread_002dexceptions'><span><kbd>C-c C-t</kbd><a href='#index-ada_002dcase_002dread_002dexceptions' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Rereads the exception dictionary from the file +<code>ada-case-exception-file</code> (<code>ada-case-read-exceptions</code>). +</p></dd> +</dl> + +<hr> +</div> +<div class="chapter" id="Statement-Templates"> +<div class="header"> +<p> +Next: <a href="#Comment-Handling" accesskey="n" rel="next">Comment Handling</a>, Previous: <a href="#Automatic-Casing" accesskey="p" rel="prev">Automatic Casing</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Statement-Templates-1"></span><h2 class="chapter">12 Statement Templates</h2> + +<p>Templates are defined for most Ada statements, using the Emacs +“skeleton” package. They can be inserted in the buffer using the +following commands: +</p> +<dl compact="compact"> +<dt id='index-ada_002dexception_002dblock'><span><kbd>C-c t b</kbd><a href='#index-ada_002dexception_002dblock' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>exception Block (<code>ada-exception-block</code>). +</p></dd> +<dt id='index-ada_002dcase'><span><kbd>C-c t c</kbd><a href='#index-ada_002dcase' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>case (<code>ada-case</code>). +</p></dd> +<dt id='index-ada_002ddeclare_002dblock'><span><kbd>C-c t d</kbd><a href='#index-ada_002ddeclare_002dblock' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>declare Block (<code>ada-declare-block</code>). +</p></dd> +<dt id='index-ada_002delse'><span><kbd>C-c t e</kbd><a href='#index-ada_002delse' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>else (<code>ada-else</code>). +</p></dd> +<dt id='index-ada_002dfor_002dloop'><span><kbd>C-c t f</kbd><a href='#index-ada_002dfor_002dloop' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>for Loop (<code>ada-for-loop</code>). +</p></dd> +<dt id='index-ada_002dheader'><span><kbd>C-c t h</kbd><a href='#index-ada_002dheader' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Header (<code>ada-header</code>). +</p></dd> +<dt id='index-ada_002dif'><span><kbd>C-c t i</kbd><a href='#index-ada_002dif' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>if (<code>ada-if</code>). +</p></dd> +<dt id='index-ada_002dpackage_002dbody'><span><kbd>C-c t k</kbd><a href='#index-ada_002dpackage_002dbody' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>package Body (<code>ada-package-body</code>). +</p></dd> +<dt id='index-ada_002dloop'><span><kbd>C-c t l</kbd><a href='#index-ada_002dloop' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>loop (<code>ada-loop</code>). +</p></dd> +<dt id='index-ada_002dsubprogram_002dbody'><span><kbd>C-c p</kbd><a href='#index-ada_002dsubprogram_002dbody' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>subprogram body (<code>ada-subprogram-body</code>). +</p></dd> +<dt id='index-ada_002dtask_002dbody'><span><kbd>C-c t t</kbd><a href='#index-ada_002dtask_002dbody' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>task Body (<code>ada-task-body</code>). +</p></dd> +<dt id='index-ada_002dwhile'><span><kbd>C-c t w</kbd><a href='#index-ada_002dwhile' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>while Loop (<code>ada-while</code>). +</p></dd> +<dt id='index-ada_002duse'><span><kbd>C-c t u</kbd><a href='#index-ada_002duse' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>use (<code>ada-use</code>). +</p></dd> +<dt id='index-ada_002dexit'><span><kbd>C-c t x</kbd><a href='#index-ada_002dexit' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>exit (<code>ada-exit</code>). +</p></dd> +<dt id='index-ada_002darray'><span><kbd>C-c t C-a</kbd><a href='#index-ada_002darray' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>array (<code>ada-array</code>). +</p></dd> +<dt id='index-ada_002delsif'><span><kbd>C-c t C-e</kbd><a href='#index-ada_002delsif' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>elsif (<code>ada-elsif</code>). +</p></dd> +<dt id='index-ada_002dfunction_002dspec'><span><kbd>C-c t C-f</kbd><a href='#index-ada_002dfunction_002dspec' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>function Spec (<code>ada-function-spec</code>). +</p></dd> +<dt id='index-ada_002dpackage_002dspec'><span><kbd>C-c t C-k</kbd><a href='#index-ada_002dpackage_002dspec' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>package Spec (<code>ada-package-spec</code>). +</p></dd> +<dt id='index-ada_002dprocedure_002dspec'><span><kbd>C-c t C-p</kbd><a href='#index-ada_002dprocedure_002dspec' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>procedure Spec (<code>ada-package-spec</code>. +</p></dd> +<dt id='index-ada_002drecord'><span><kbd>C-c t C-r</kbd><a href='#index-ada_002drecord' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>record (<code>ada-record</code>). +</p></dd> +<dt id='index-ada_002dsubtype'><span><kbd>C-c t C-s</kbd><a href='#index-ada_002dsubtype' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>subtype (<code>ada-subtype</code>). +</p></dd> +<dt id='index-ada_002dtask_002dspec'><span><kbd>C-c t C-t</kbd><a href='#index-ada_002dtask_002dspec' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>task Spec (<code>ada-task-spec</code>). +</p></dd> +<dt id='index-ada_002dwith'><span><kbd>C-c t C-u</kbd><a href='#index-ada_002dwith' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>with (<code>ada-with</code>). +</p></dd> +<dt id='index-ada_002dprivate'><span><kbd>C-c t C-v</kbd><a href='#index-ada_002dprivate' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>private (<code>ada-private</code>). +</p></dd> +<dt id='index-ada_002dwhen'><span><kbd>C-c t C-w</kbd><a href='#index-ada_002dwhen' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>when (<code>ada-when</code>). +</p></dd> +<dt id='index-ada_002dexception'><span><kbd>C-c t C-x</kbd><a href='#index-ada_002dexception' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>exception (<code>ada-exception</code>). +</p></dd> +<dt id='index-ada_002dtype'><span><kbd>C-c t C-y</kbd><a href='#index-ada_002dtype' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>type (<code>ada-type</code>). +</p></dd> +</dl> + +<hr> +</div> +<div class="chapter" id="Comment-Handling"> +<div class="header"> +<p> +Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Statement-Templates" accesskey="p" rel="prev">Statement Templates</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Comment-Handling-1"></span><h2 class="chapter">13 Comment Handling</h2> + +<p>By default, comment lines get indented like Ada code. There are a few +additional functions to handle comments: +</p> +<dl compact="compact"> +<dt><span><kbd>M-;</kbd></span></dt> +<dd><p>Start a comment in default column. +</p></dd> +<dt><span><kbd>M-j</kbd></span></dt> +<dd><p>Continue comment on next line. +</p></dd> +<dt><span><kbd>C-c ;</kbd></span></dt> +<dd><p>Comment the selected region (add ‘<samp>--</samp>’ at the beginning of lines). +</p></dd> +<dt><span><kbd>C-c :</kbd></span></dt> +<dd><p>Uncomment the selected region +</p></dd> +<dt><span><kbd>M-q</kbd></span></dt> +<dd><p>autofill the current comment. +</p></dd> +</dl> + +<hr> +</div> +<div class="appendix" id="GNU-Free-Documentation-License"> +<div class="header"> +<p> +Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Comment-Handling" accesskey="p" rel="prev">Comment Handling</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="GNU-Free-Documentation-License-1"></span><h2 class="appendix">Appendix A GNU Free Documentation License</h2> +<div align="center">Version 1.3, 3 November 2008 +</div> + +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="https://fsf.org/">https://fsf.org/</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol start="0"> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> 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. +</p> +<p>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. +</p> +<p>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. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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”. +</p> +<p>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. +</p> +<p>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. +</p> +<p>The “publisher” means any person or entity that distributes copies +of the Document to the public. +</p> +<p>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. +</p> +<p>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. +</p> +</li><li> VERBATIM COPYING + +<p>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. +</p> +<p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +</li><li> MODIFICATIONS + +<p>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: +</p> +<ol type="A" start="1"> +<li> 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. + +</li><li> 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. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> 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. + +</li><li> Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> 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. + +</li><li> 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. + +</li><li> 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. + +</li><li> 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. + +</li><li> Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +</li><li> COMBINING DOCUMENTS + +<p>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. +</p> +<p>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. +</p> +<p>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.” +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>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. +</p> +<p>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. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>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. +</p> +<p>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. +</p> +</li><li> TRANSLATION + +<p>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. +</p> +<p>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. +</p> +</li><li> TERMINATION + +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>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 +<a href="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</a>. +</p> +<p>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. +</p> +</li><li> RELICENSING + +<p>“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. +</p> +<p>“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. +</p> +<p>“Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +</p> +<p>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. +</p> +<p>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. +</p> +</li></ol> + +<span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="heading">ADDENDUM: How to use this License for your documents</h3> + +<p>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: +</p> +<div class="example"> +<pre class="example"> Copyright (C) <var>year</var> <var>your name</var>. + 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''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +</p> +<div class="example"> +<pre class="example"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>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. +</p> + +<hr> +</div> +<div class="unnumbered" id="Index"> +<div class="header"> +<p> +Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="prev">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Ada Mode</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Index-1"></span><h2 class="unnumbered">Index</h2> + +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_fn_letter-A"><b>A</b></a> + +</td></tr></table> +<table class="index-fn" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Index_fn_letter-A">A</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dadjust_002dcase_002dbuffer"><code>ada-adjust-case-buffer</code></a>:</td><td> </td><td valign="top"><a href="#Automatic-Casing">Automatic Casing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002darray"><code>ada-array</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dcase"><code>ada-case</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dcase_002dread_002dexceptions"><code>ada-case-read-exceptions</code></a>:</td><td> </td><td valign="top"><a href="#Automatic-Casing">Automatic Casing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dcomplete_002didentifier"><code>ada-complete-identifier</code></a>:</td><td> </td><td valign="top"><a href="#Identifier-completion">Identifier completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dcreate_002dcase_002dexception"><code>ada-create-case-exception</code></a>:</td><td> </td><td valign="top"><a href="#Automatic-Casing">Automatic Casing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002ddeclare_002dblock"><code>ada-declare-block</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002delse"><code>ada-else</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002delsif"><code>ada-elsif</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dexception"><code>ada-exception</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dexception_002dblock"><code>ada-exception-block</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dexit"><code>ada-exit</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dfind_002dreferences"><code>ada-find-references</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dfor_002dloop"><code>ada-for-loop</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dformat_002dparamlist"><code>ada-format-paramlist</code></a>:</td><td> </td><td valign="top"><a href="#Formatting-Parameter-Lists">Formatting Parameter Lists</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dfunction_002dspec"><code>ada-function-spec</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dgoto_002ddeclaration"><code>ada-goto-declaration</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dheader"><code>ada-header</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dif"><code>ada-if</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dloop"><code>ada-loop</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dmove_002dto_002dend"><code>ada-move-to-end</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dmove_002dto_002dstart"><code>ada-move-to-start</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dnext_002dpackage"><code>ada-next-package</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dnext_002dprocedure"><code>ada-next-procedure</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dpackage_002dbody"><code>ada-package-body</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dpackage_002dspec"><code>ada-package-spec</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dprevious_002dpackage"><code>ada-previous-package</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dprevious_002dprocedure"><code>ada-previous-procedure</code></a>:</td><td> </td><td valign="top"><a href="#Moving-Through-Ada-Code">Moving Through Ada Code</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dprivate"><code>ada-private</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dprocedure_002dspec"><code>ada-procedure-spec</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002drecord"><code>ada-record</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dsubprogram_002dbody"><code>ada-subprogram-body</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dsubtype"><code>ada-subtype</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dtask_002dbody"><code>ada-task-body</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dtask_002dspec"><code>ada-task-spec</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dtype"><code>ada-type</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002duse"><code>ada-use</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dwhen"><code>ada-when</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dwhile"><code>ada-while</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ada_002dwith"><code>ada-with</code></a>:</td><td> </td><td valign="top"><a href="#Statement-Templates">Statement Templates</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_fn_letter-A"><b>A</b></a> + +</td></tr></table> + +</div> +</div> + + + +</body> +</html> diff --git a/old_ada/doc/ada-mode.info b/old_ada/doc/ada-mode.info new file mode 100644 index 0000000..e29172d --- /dev/null +++ b/old_ada/doc/ada-mode.info @@ -0,0 +1,1983 @@ +This is ada-mode.info, produced by texi2any version 6.8 from +ada-mode.texi. + +Copyright © 1999–2019 Free Software Foundation, Inc. + + 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 “A GNU Manual”, and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + “GNU Free Documentation License”. + + (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and + modify this GNU manual.” +INFO-DIR-SECTION Emacs editing modes +START-INFO-DIR-ENTRY +* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. +END-INFO-DIR-ENTRY + + +File: ada-mode.info, Node: Top, Next: Overview, Up: (dir) + +Ada Mode +******** + +Copyright © 1999–2019 Free Software Foundation, Inc. + + 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 “A GNU Manual”, and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + “GNU Free Documentation License”. + + (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and + modify this GNU manual.” + +* Menu: + +* Overview:: +* Installation:: Installing Ada mode on your system +* Customization:: Setting up Ada mode to your taste +* Compiling Executing:: Working with your application within Emacs +* Project files:: Describing the organization of your project +* Compiling Examples:: A small tutorial +* Moving Through Ada Code:: Moving easily through Ada sources +* Identifier completion:: Finishing words automatically +* Automatic Smart Indentation:: Indenting your code automatically as you type +* Formatting Parameter Lists:: Formatting subprograms’ parameter lists + automatically +* Automatic Casing:: Adjusting the case of words automatically +* Statement Templates:: Inserting code templates +* Comment Handling:: Reformatting comments easily +* GNU Free Documentation License:: The license for this documentation. +* Index:: + + +File: ada-mode.info, Node: Overview, Next: Installation, Prev: Top, Up: Top + +1 Overview +********** + +The Emacs mode for programming in Ada helps the user in understanding +existing code and facilitates writing new code. + + When the GNU Ada compiler GNAT is used, the cross-reference +information output by the compiler is used to provide powerful code +navigation (jump to definition, find all uses, etc.). + + When you open a file with a file extension of ‘.ads’ or ‘.adb’, Emacs +will automatically load and activate Ada mode. + + Ada mode works without any customization, if you are using the GNAT +compiler (<https://libre2.adacore.com/>) and the GNAT default naming +convention. + + You must customize a few things if you are using a different compiler +or file naming convention; *Note Other compiler::, *Note Non-standard +file names::. + + In addition, you may want to customize the indentation, +capitalization, and other things; *Note Other customization::. + + Finally, for large Ada projects, you will want to set up an Emacs Ada +mode project file for each project; *Note Project files::. Note that +these are different from the GNAT project files used by gnatmake and +other GNAT commands. + + See the Emacs info manual, section ’Running Debuggers Under Emacs’, +for general information on debugging. + + +File: ada-mode.info, Node: Installation, Next: Customization, Prev: Overview, Up: Top + +2 Installation +************** + +Ada mode is part of the standard Emacs distribution; if you use that, no +files need to be installed. + + Ada mode is also available as a separate distribution, from the Emacs +Ada mode website +<http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html>. The +separate distribution may be more recent. + + For installing the separate distribution, see the ‘README’ file in +the distribution. + + To see what version of Ada mode you have installed, do ‘M-x +ada-mode-version’. + + The following files are provided with the Ada mode distribution: + + • ‘ada-mode.el’: The main file for Ada mode, providing indentation, + formatting of parameter lists, moving through code, comment + handling and automatic casing. + + • ‘ada-prj.el’: GUI editing of Ada mode project files, using Emacs + widgets. + + • ‘ada-stmt.el’: Ada statement templates. + + • ‘ada-xref.el’: GNAT cross-references, completion of identifiers, + and compilation. Also provides project files (which are not + GNAT-specific). + + +File: ada-mode.info, Node: Customization, Next: Compiling Executing, Prev: Installation, Up: Top + +3 Customizing Ada mode +********************** + +Here we assume you are familiar with setting variables in Emacs, either +thru ’customize’ or in elisp (in your ‘.emacs’ file). For a basic +introduction to customize, elisp, and Emacs in general, see the tutorial +in *note The GNU Emacs Manual: (emacs)Top. + + These global Emacs settings are strongly recommended (put them in +your .emacs): + + (global-font-lock-mode t) + (transient-mark-mode t) + + ‘(global-font-lock-mode t)’ turns on syntax highlighting for all +buffers (it is off by default because it may be too slow for some +machines). + + ‘(transient-mark-mode t)’ highlights selected text. + + See the Emacs help for each of these variables for more information. + +* Menu: + +* Non-standard file names:: +* Other compiler:: +* Other customization:: + + +File: ada-mode.info, Node: Non-standard file names, Next: Other compiler, Up: Customization + +3.1 Non-standard file names +=========================== + +By default, Ada mode is configured to use the GNAT file naming +convention, where file names are a simple modification of the Ada names, +and the extension for specs and bodies are ‘.ads’ and ‘.adb’, +respectively. + + Ada mode uses the file extensions to allow moving from a package body +to the corresponding spec and back. + + Ada mode supports a list of alternative file extensions for specs and +bodies. + + For instance, if your spec and bodies files are called ‘UNIT_s.ada’ +and ‘UNIT_b.ada’, respectively, you can add the following to your +‘.emacs’ file: + + (ada-add-extensions "_s.ada" "_b.ada") + + You can define additional extensions: + + (ada-add-extensions ".ads" "_b.ada") + (ada-add-extensions ".ads" ".body") + + This means that whenever Ada mode looks for the body for a file whose +extension is ‘.ads’, it will take the first available file that ends +with either ‘.adb’, ‘_b.ada’ or ‘.body’. + + Similarly, if Ada mode is looking for a spec, it will look for ‘.ads’ +or ‘_s.ada’. + + If the filename is not derived from the Ada name following the GNAT +convention, things are a little more complicated. You then need to +rewrite the function ‘ada-make-filename-from-adaname’. Doing that is +beyond the scope of this manual; see the current definitions in +‘ada-mode.el’ and ‘ada-xref.el’ for examples. + + +File: ada-mode.info, Node: Other compiler, Next: Other customization, Prev: Non-standard file names, Up: Customization + +3.2 Other compiler +================== + +By default, Ada mode is configured to use the GNU Ada compiler GNAT. + + To use a different Ada compiler, you must specify the command lines +used to run that compiler, either in lisp variables or in Emacs Ada mode +project files. See *note Project file variables:: for the list of +project variables, and the corresponding lisp variables. + + +File: ada-mode.info, Node: Other customization, Prev: Other compiler, Up: Customization + +3.3 Other customization +======================= + +All user-settable Ada mode variables can be set via the menu ‘Ada | +Customize’. Click on the ‘Help’ button there for help on using +customize. + + To modify a specific variable, you can directly call the function +‘customize-variable’; just type ‘M-x customize-variable <RET> +VARIABLE-NAME <RET>’). + + Alternately, you can specify variable settings in the Emacs +configuration file, ‘.emacs’. This file is coded in Emacs lisp, and the +syntax to set a variable is the following: + (setq variable-name value) + + +File: ada-mode.info, Node: Compiling Executing, Next: Project files, Prev: Customization, Up: Top + +4 Compiling Executing +********************* + +Ada projects can be compiled, linked, and executed using commands on the +Ada menu. All of these commands can be customized via a project file +(*note Project files::), but the defaults are sufficient for using the +GNAT compiler for simple projects (single files, or several files in a +single directory). + + Even when no project file is used, the GUI project editor (menu ‘Ada +| Project | Edit’) shows the settings of the various project file +variables referenced here. + +* Menu: + +* Compile commands:: +* Compiler errors:: + + +File: ada-mode.info, Node: Compile commands, Next: Compiler errors, Up: Compiling Executing + +4.1 Compile commands +==================== + +Here are the commands for building and using an Ada project, as listed +in the Ada menu. + + In multi-file projects, there must be one file that is the main +program. That is given by the ‘main’ project file variable; it defaults +to the current file if not yet set, but is also set by the “set main and +build” command. + +‘Check file’ + Compiles the current file in syntax check mode, by running + ‘check_cmd’ defined in the current project file. This typically + runs faster than full compile mode, speeding up finding and fixing + compilation errors. + + This sets ‘main’ only if it has not been set yet. + +‘Compile file’ + Compiles the current file, by running ‘comp_cmd’ from the current + project file. + + This does not set ‘main’. + +‘Set main and Build’ + Sets ‘main’ to the current file, then executes the Build command. + +‘Show main’ + Display ‘main’ in the message buffer. + +‘Build’ + Compiles all obsolete units of the current ‘main’, and links + ‘main’, by running ‘make_cmd’ from the current project. + + This sets ‘main’ only if it has not been set yet. + +‘Run’ + Executes the main program in a shell, displayed in a separate Emacs + buffer. This runs ‘run_cmd’ from the current project. The + execution buffer allows for interactive input/output. + + To modify the run command, in particular to provide or change the + command line arguments, type ‘C-u’ before invoking the command. + + This command is not available for a cross-compilation toolchain. + + It is important when using these commands to understand how ‘main’ is +used and changed. + + Build runs ’gnatmake’ on the main unit. During a typical +edit/compile session, this is the only command you need to invoke, which +is why it is bound to ‘C-c C-c’. It will compile all files needed by +the main unit, and display compilation errors in any of them. + + Note that Build can be invoked from any Ada buffer; typically you +will be fixing errors in files other than the main, but you don’t have +to switch back to the main to invoke the compiler again. + + Novices and students typically work on single-file Ada projects. In +this case, ‘C-c C-m’ will normally be the only command needed; it will +build the current file, rather than the last-built main. + + There are three ways to change ‘main’: + + 1. Invoke ‘Ada | Set main and Build’, which sets ‘main’ to the current + file. + + 2. Invoke ‘Ada | Project | Edit’, edit ‘main’ and ‘main’, and click + ‘[save]’ + + 3. Invoke ‘Ada | Project | Load’, and load a project file that + specifies ‘main’ + + +File: ada-mode.info, Node: Compiler errors, Prev: Compile commands, Up: Compiling Executing + +4.2 Compiler errors +=================== + +The ‘Check file’, ‘Compile file’, and ‘Build’ commands all place +compilation errors in a separate buffer named ‘*compilation*’. + + Each line in this buffer will become active: you can simply click on +it with the middle button of the mouse, or move point to it and press +<RET>. Emacs will then display the relevant source file and put point +on the line and column where the error was found. + + You can also press the ‘C-x `’ key (‘next-error’), and Emacs will +jump to the first error. If you press that key again, it will move you +to the second error, and so on. + + Some error messages might also include references to other files. +These references are also clickable in the same way, or put point after +the line number and press <RET>. + + +File: ada-mode.info, Node: Project files, Next: Compiling Examples, Prev: Compiling Executing, Up: Top + +5 Project files +*************** + +An Emacs Ada mode project file specifies what directories hold sources +for your project, and allows you to customize the compilation commands +and other things on a per-project basis. + + Note that Ada mode project files ‘*.adp’ are different than GNAT +compiler project files ‘*.gpr’. However, Emacs Ada mode can use a GNAT +project file to specify the project directories. If no other +customization is needed, a GNAT project file can be used without an +Emacs Ada mode project file. + +* Menu: + +* Project File Overview:: +* GUI Editor:: +* Project file variables:: + + +File: ada-mode.info, Node: Project File Overview, Next: GUI Editor, Up: Project files + +5.1 Project File Overview +========================= + +Project files have a simple syntax; they may be edited directly. Each +line specifies a project variable name and its value, separated by “=”: + src_dir=/Projects/my_project/src_1 + src_dir=/Projects/my_project/src_2 + + Some variables (like ‘src_dir’) are lists; multiple occurrences are +concatenated. + + There must be no space between the variable name and “=”, and no +trailing spaces. + + Alternately, a GUI editor for project files is available (*note GUI +Editor::). It uses Emacs widgets, similar to Emacs customize. + + The GUI editor also provides a convenient way to view current project +settings, if they have been modified using menu commands rather than by +editing the project file. + + After the first Ada mode build command is invoked, there is always a +current project file, given by the lisp variable +‘ada-prj-default-project-file’. Currently, the only way to show the +current project file is to invoke the GUI editor. + + To find the project file the first time, Ada mode uses the following +search algorithm: + + • If ‘ada-prj-default-project-file’ is set, use that. + + • Otherwise, search for a file in the current directory with the same + base name as the Ada file, but extension given by + ‘ada-prj-file-extension’ (default ‘".adp"’). + + • If not found, search for ‘*.adp’ in the current directory; if + several are found, prompt the user to select one. + + • If none are found, use ‘default.adp’ in the current directory (even + if it does not exist). + + This algorithm always sets ‘ada-prj-default-project-file’, even when +the file does not actually exist. + + To change the project file before or after the first one is found, +invoke ‘Ada | Project | Load ...’. + + Or, in lisp, evaluate ‘(ada-set-default-project-file +"/path/file.adp")’. This sets ‘ada-prj-default-project-file’, and reads +the project file. + + You can also specify a GNAT project file to ‘Ada | Project | Load +...’ or ‘ada-set-default-project-file’. Emacs Ada mode checks the file +extension; if it is ‘.gpr’, the file is treated as a GNAT project file. +Any other extension is treated as an Emacs Ada mode project file. + + +File: ada-mode.info, Node: GUI Editor, Next: Project file variables, Prev: Project File Overview, Up: Project files + +5.2 GUI Editor +============== + +The project file editor is invoked with the menu ‘Ada | Projects | +Edit’. + + Once in the buffer for editing the project file, you can save your +modification using the ‘[save]’ button at the bottom of the buffer, or +the ‘C-x C-s’ binding. To cancel your modifications, kill the buffer or +click on the ‘[cancel]’ button. + + +File: ada-mode.info, Node: Project file variables, Prev: GUI Editor, Up: Project files + +5.3 Project file variables +========================== + +The following variables can be defined in a project file; some can also +be defined in lisp variables. + + To set a project variable that is a list, specify each element of the +list on a separate line in the project file. + + Any project variable can be referenced in other project variables, +using a shell-like notation. For instance, if the variable ‘comp_cmd’ +contains ‘${comp_opt}’, the value of the ‘comp_opt’ variable will be +substituted when ‘comp_cmd’ is used. + + In addition, process environment variables can be referenced using +the same syntax, or the normal ‘$var’ syntax. + + Most project variables have defaults that can be changed by setting +lisp variables; the table below identifies the lisp variable for each +project variable. Lisp variables corresponding to project variables +that are lists are lisp lists. + + In general, project variables are evaluated when referenced in Emacs +Ada mode commands. Relative file paths are expanded to absolute +relative to ‘${build_dir}’. + + Here is the list of variables. In the default values, the current +directory ‘"."’ is the project file directory. + +‘ada_project_path_sep’ [default: ‘":" or ";"’] + Path separator for ‘ADA_PROJECT_PATH’. It defaults to the correct + value for a native implementation of GNAT for the current operating + system. The user must override this when using Windows native GNAT + with Cygwin Emacs, and perhaps in other cases. + + Lisp variable: ‘ada-prj-ada-project-path-sep’. + +‘ada_project_path’ [default: ‘""’] + A list of directories to search for GNAT project files. + + If set, the ‘ADA_PROJECT_PATH’ process environment variable is set + to this value in the Emacs process when the Emacs Ada mode project + is selected via menu ‘Ada | Project | Load’. + + For ‘ada_project_path’, relative file paths are expanded to + absolute when the Emacs Ada project file is read, rather than when + the project file is selected. + + For example if the project file is in the directory + ‘/home/myproject’, the environment variable ‘GDS_ROOT’ is set to + ‘/home/shared’, and the project file contains: + ada_project_path_sep=: + ada_project_path=$GDS_ROOT/makerules + ada_project_path=../opentoken + then as a result the environment variable ‘ADA_PROJECT_PATH’ will + be set to ‘"/home/shared/makerules:/home/opentoken/"’. + + The default value is not the current value of this environment + variable, because that will typically have been set by another + project, and will therefore be incorrect for this project. + + If you have the environment variable set correctly for all of your + projects, you do not need to set this project variable. + +‘bind_opt’ [default: ‘""’] + Holds user binder options; used in the default build commands. + + Lisp variable: ‘ada-prj-default-bind-opt’. + +‘build_dir’ [default: ‘"."’] + The compile commands will be issued in this directory. + +‘casing’ [default: ‘("~/.emacs_case_exceptions")’] + List of files containing casing exceptions. See the help on + ‘ada-case-exception-file’ for more info. + + Lisp variable: ‘ada-case-exception-file’. + +‘check_cmd’ [default: ‘"${cross_prefix}gnatmake -u -c -gnatc ${gnatmake_opt} ${full_current} -cargs ${comp_opt}"’] + Command used to syntax check a single file. The name of the file + is substituted for ‘full_current’. + + Lisp variable: ‘ada-prj-default-check-cmd’ + +‘comp_cmd’ [default: ‘"${cross_prefix}gnatmake -u -c ${gnatmake_opt} ${full_current} -cargs ${comp_opt}"’] + Command used to compile a single file. The name of the file is + substituted for ‘full_current’. + + Lisp variable: ‘ada-prj-default-comp-cmd’. + +‘comp_opt’ [default: ‘"-gnatq -gnatQ"’] + Holds user compiler options; used in the default compile commands. + The default value tells gnatmake to generate library files for + cross-referencing even when there are errors. + + If source code for the project is in multiple directories, the + appropriate compiler options must be added here. *note Set source + search path:: for examples of this. Alternately, GNAT project + files may be used; *note Use GNAT project file::. + + Lisp variable: ‘ada-prj-default-comp-opt’. + +‘cross_prefix’ [default: ‘""’] + Name of target machine in a cross-compilation environment. Used in + default compile and build commands. + +‘debug_cmd’ [default: ‘"${cross_prefix}gdb ${main}"’] + Command used to debug the application + + Lisp variable: ‘ada-prj-default-debugger’. + +‘debug_post_cmd’ [default: ‘""’] + Command executed after ‘debug_cmd’. + +‘debug_pre_cmd’ [default: ‘"cd ${build_dir}"’] + Command executed before ‘debug_cmd’. + +‘gnatfind_opt’ [default: ‘"-rf"’] + Holds user gnatfind options; used in the default find commands. + + Lisp variable: ‘ada-prj-gnatfind-switches’. + +‘gnatmake_opt’ [default: ‘"-g"’] + Holds user gnatmake options; used in the default build commands. + + Lisp variable: ‘ada-prj-default-gnatmake-opt’. + +‘gpr_file’ [default: ‘""’] + Specify GNAT project file. + + If set, the source and object directories specified in the GNAT + project file are appended to ‘src_dir’ and ‘obj_dir’. This allows + specifying Ada source directories with a GNAT project file, and + other source directories with the Emacs project file. + + In addition, ‘-P{gpr_file}’ is added to the project variable + ‘gnatmake_opt’ whenever it is referenced. With the default project + variables, this passes the project file to all gnatmake commands. + + Lisp variable: ‘ada-prj-default-gpr-file’. + +‘link_opt’ [default: ‘""’] + Holds user linker options; used in the default build commands. + + Lisp variable: ‘ada-prj-default-link-opt’. + +‘main’ [default: current file] + Specifies the name of the executable file for the project; used in + the default build commands. + +‘make_cmd’ [default: ‘"${cross_prefix}gnatmake -o ${main} ${main} ${gnatmake_opt} -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"’] + Command used to build the application. + + Lisp variable: ‘ada-prj-default-make-cmd’. + +‘obj_dir’ [default: ‘"."’] + A list of directories to search for library files. Ada mode + searches this list for the ‘.ali’ files generated by GNAT that + contain cross-reference information. + + The compiler commands must place the ‘.ali’ files in one of these + directories; the default commands do that. + +‘remote_machine’ [default: ‘""’] + Name of the machine to log into before issuing the compile and + build commands. If this variable is empty, the command will be run + on the local machine. + +‘run_cmd’ [default: ‘"./${main}"’] + Command used to run the application. + +‘src_dir’ [default: ‘"."’] + A list of directories to search for source files, both for compile + commands and source navigation. + + +File: ada-mode.info, Node: Compiling Examples, Next: Moving Through Ada Code, Prev: Project files, Up: Top + +6 Compiling Examples +******************** + +We present several small projects, and walk thru the process of +compiling, linking, and running them. + + The first example illustrates more Ada mode features than the others; +you should work thru that example before doing the others. + + All of these examples assume you are using GNAT. + + The source for these examples is available on the Emacs Ada mode +website mentioned in *Note Installation::. + +* Menu: + +* No project files:: Just menus +* Set compiler options:: A basic Ada mode project file +* Set source search path:: Source in multiple directories +* Use GNAT project file:: +* Use multiple GNAT project files:: + + +File: ada-mode.info, Node: No project files, Next: Set compiler options, Up: Compiling Examples + +6.1 No project files +==================== + +This example uses no project files. + + First, create a directory ‘Example_1’, containing: + + ‘hello.adb’: + + with Ada.Text_IO; + procedure Hello + is begin + Put_Line("Hello from hello.adb"); + end Hello; + + Yes, this is missing “use Ada.Text_IO;” - we want to demonstrate +compiler error handling. + + ‘hello_2.adb’: + + with Hello_Pkg; + procedure Hello_2 + is begin + Hello_Pkg.Say_Hello; + end Hello_2; + + This file has no errors. + + ‘hello_pkg.ads’: + + package Hello_Pkg is + procedure Say_Hello; + end Hello_Pkg; + + This file has no errors. + + ‘hello_pkg.adb’: + + with Ada.Text_IO; + package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; + end Hello_Pkg; + + Yes, this is missing the keyword ‘body’; another compiler error +example. + + In buffer ‘hello.adb’, invoke ‘Ada | Check file’. You should get a +‘*compilation*’ buffer containing something like (the directory paths +will be different): + + cd c:/Examples/Example_1/ + gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ + gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb + hello.adb:4:04: "Put_Line" is not visible + hello.adb:4:04: non-visible declaration at a-textio.ads:264 + hello.adb:4:04: non-visible declaration at a-textio.ads:260 + gnatmake: "c:/Examples/Example_1/hello.adb" compilation error + + If you have enabled font-lock, the lines with actual errors (starting +with ‘hello.adb’) are highlighted, with the file name in red. + + Now type ‘C-x `’ (on a PC keyboard, <`> is next to <1>). Or you can +click the middle mouse button on the first error line. The compilation +buffer scrolls to put the first error on the top line, and point is put +at the place of the error in the ‘hello.adb’ buffer. + + To fix the error, change the line to be + + Ada.Text_IO.Put_Line ("hello from hello.adb"); + + Now invoke ‘Ada | Show main’; this displays ‘Ada mode main: hello’. + + Now (in buffer ‘hello.adb’), invoke ‘Ada | Build’. You are prompted +to save the file (if you haven’t already). Then the compilation buffer +is displayed again, containing: + + cd c:/Examples/Example_1/ + gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs + gcc -c -g -gnatq -gnatQ hello.adb + gnatbind -x hello.ali + gnatlink hello.ali -o hello.exe -g + + The compilation has succeeded without errors; ‘hello.exe’ now exists +in the same directory as ‘hello.adb’. + + Now invoke ‘Ada | Run’. A ‘*run*’ buffer is displayed, containing + + Hello from hello.adb + + Process run finished + + That completes the first part of this example. + + Now we will compile a multi-file project. Open the file +‘hello_2.adb’, and invoke ‘Ada | Set main and Build’. This finds an +error in ‘hello_pkg.adb’: + + cd c:/Examples/Example_1/ + gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs + gcc -c -g -gnatq -gnatQ hello_pkg.adb + hello_pkg.adb:2:08: keyword "body" expected here [see file name] + gnatmake: "hello_pkg.adb" compilation error + + This demonstrates that gnatmake finds the files needed by the main +program. However, it cannot find files in a different directory, unless +you use an Emacs Ada mode project file to specify the other directories; +*Note Set source search path::, or a GNAT project file; *note Use GNAT +project file::. + + Invoke ‘Ada | Show main’; this displays ‘Ada mode main: hello_2’. + + Move to the error with ‘C-x `’, and fix the error by adding ‘body’: + + package body Hello_Pkg is + + Now, while still in ‘hello_pkg.adb’, invoke ‘Ada | Build’. gnatmake +successfully builds ‘hello_2’. This demonstrates that Emacs has +remembered the main file, in the project variable ‘main’, and used it +for the Build command. + + Finally, again while in ‘hello_pkg.adb’, invoke ‘Ada | Run’. The +‘*run*’ buffer displays ‘Hello from hello_pkg.adb’. + + One final point. If you switch back to buffer ‘hello.adb’, and +invoke ‘Ada | Run’, ‘hello_2.exe’ will be run. That is because ‘main’ +is still set to ‘hello_2’, as you can see when you invoke ‘Ada | Project +| Edit’. + + There are three ways to change ‘main’: + + 1. Invoke ‘Ada | Set main and Build’, which sets ‘main’ to the current + file. + + 2. Invoke ‘Ada | Project | Edit’, edit ‘main’, and click ‘[save]’ + + 3. Invoke ‘Ada | Project | Load’, and load a project file that + specifies ‘main’ + + +File: ada-mode.info, Node: Set compiler options, Next: Set source search path, Prev: No project files, Up: Compiling Examples + +6.2 Set compiler options +======================== + +This example illustrates using an Emacs Ada mode project file to set a +compiler option. + + If you have files from ‘Example_1’ open in Emacs, you should close +them so you don’t get confused. Use menu ‘File | Close (current +buffer)’. + + In directory ‘Example_2’, create these files: + + ‘hello.adb’: + + with Ada.Text_IO; + procedure Hello + is begin + Put_Line("Hello from hello.adb"); + end Hello; + + This is the same as ‘hello.adb’ from ‘Example_1’. It has two errors; +missing “use Ada.Text_IO;”, and no space between ‘Put_Line’ and its +argument list. + + ‘hello.adp’: + + comp_opt=-gnatyt + + This tells the GNAT compiler to check for token spacing; in +particular, there must be a space preceding a parenthesis. + + In buffer ‘hello.adb’, invoke ‘Ada | Project | Load...’, and select +‘Example_2/hello.adp’. + + Then, again in buffer ‘hello.adb’, invoke ‘Ada | Set main and Build’. +You should get a ‘*compilation*’ buffer containing something like (the +directory paths will be different): + + cd c:/Examples/Example_2/ + gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs + gcc -c -g -gnatyt hello.adb + hello.adb:4:04: "Put_Line" is not visible + hello.adb:4:04: non-visible declaration at a-textio.ads:264 + hello.adb:4:04: non-visible declaration at a-textio.ads:260 + hello.adb:4:12: (style) space required + gnatmake: "hello.adb" compilation error + + Compare this to the compiler output in *note No project files::; the +gnatmake option ‘-cargs -gnatq -gnatQ’ has been replaced by ‘-cargs +-gnaty’, and an additional error is reported in ‘hello.adb’ on line 4. +This shows that ‘hello.adp’ is being used to set the compiler options. + + Fixing the error, linking and running the code proceed as in *note No +project files::. + + +File: ada-mode.info, Node: Set source search path, Next: Use GNAT project file, Prev: Set compiler options, Up: Compiling Examples + +6.3 Set source search path +========================== + +In this example, we show how to deal with files in more than one +directory. We start with the same code as in *note No project files::; +create those files (with the errors present) + + Create the directory ‘Example_3’, containing: + + ‘hello_pkg.ads’: + + package Hello_Pkg is + procedure Say_Hello; + end Hello_Pkg; + + ‘hello_pkg.adb’: + + with Ada.Text_IO; + package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; + end Hello_Pkg; + + These are the same files from example 1; ‘hello_pkg.adb’ has an error +on line 2. + + In addition, create a directory ‘Example_3/Other’, containing these +files: + + ‘Other/hello_3.adb’: + + with Hello_Pkg; + with Ada.Text_IO; use Ada.Text_IO; + procedure Hello_3 + is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_3"); + end Hello_3; + + There are no errors in this file. + + ‘Other/other.adp’: + + src_dir=.. + comp_opt=-I.. + + Note that there must be no trailing spaces. + + In buffer ‘hello_3.adb’, invoke ‘Ada | Project | Load...’, and select +‘Example_3/Other/other.adp’. + + Then, again in ‘hello_3.adb’, invoke ‘Ada | Set main and Build’. You +should get a ‘*compilation*’ buffer containing something like (the +directory paths will be different): + + cd c:/Examples/Example_3/Other/ + gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs + gcc -c -g -I.. hello_3.adb + gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb + hello_pkg.adb:2:08: keyword "body" expected here [see file name] + gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error + + Compare the ‘-cargs’ option to the compiler output in *note Set +compiler options::; this shows that ‘other.adp’ is being used to set the +compiler options. + + Move to the error with ‘C-x `’. Ada mode searches the list of +directories given by ‘src_dir’ for the file mentioned in the compiler +error message. + + Fixing the error, linking and running the code proceed as in *note No +project files::. + + +File: ada-mode.info, Node: Use GNAT project file, Next: Use multiple GNAT project files, Prev: Set source search path, Up: Compiling Examples + +6.4 Use GNAT project file +========================= + +In this example, we show how to use a GNAT project file, with no Ada +mode project file. + + Create the directory ‘Example_4’, containing: + + ‘hello_pkg.ads’: + + package Hello_Pkg is + procedure Say_Hello; + end Hello_Pkg; + + ‘hello_pkg.adb’: + + with Ada.Text_IO; + package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; + end Hello_Pkg; + + These are the same files from example 1; ‘hello_pkg.adb’ has an error +on line 2. + + In addition, create a directory ‘Example_4/Gnat_Project’, containing +these files: + + ‘Gnat_Project/hello_4.adb’: + + with Hello_Pkg; + with Ada.Text_IO; use Ada.Text_IO; + procedure Hello_4 + is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_4"); + end Hello_4; + + There are no errors in this file. + + ‘Gnat_Project/hello_4.gpr’: + + Project Hello_4 is + for Source_Dirs use (".", ".."); + end Hello_4; + + In buffer ‘hello_4.adb’, invoke ‘Ada | Project | Load...’, and select +‘Example_4/Gnat_Project/hello_4.gpr’. + + Then, again in ‘hello_4.adb’, invoke ‘Ada | Set main and Build’. You +should get a ‘*compilation*’ buffer containing something like (the +directory paths will be different): + + cd c:/Examples/Example_4/Gnat_Project/ + gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs + gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb + gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb + hello_pkg.adb:2:08: keyword "body" expected here [see file name] + gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error + + Compare the ‘gcc’ options to the compiler output in *note Set +compiler options::; this shows that ‘hello_4.gpr’ is being used to set +the compiler options. + + Fixing the error, linking and running the code proceed as in *note No +project files::. + + +File: ada-mode.info, Node: Use multiple GNAT project files, Prev: Use GNAT project file, Up: Compiling Examples + +6.5 Use multiple GNAT project files +=================================== + +In this example, we show how to use multiple GNAT project files, +specifying the GNAT project search path in an Ada mode project file. + + Create the directory ‘Example_4’ as specified in *note Use GNAT +project file::. + + Create the directory ‘Example_5’, containing: + + ‘hello_5.adb’: + + with Hello_Pkg; + with Ada.Text_IO; use Ada.Text_IO; + procedure Hello_5 + is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_5"); + end Hello_5; + + There are no errors in this file. + + ‘hello_5.adp’: + + ada_project_path=../Example_4/Gnat_Project + gpr_file=hello_5.gpr + + ‘hello_5.gpr’: + + with "hello_4"; + Project Hello_5 is + for Source_Dirs use ("."); + package Compiler is + for Default_Switches ("Ada") use ("-g", "-gnatyt"); + end Compiler; + end Hello_5; + + In buffer ‘hello_5.adb’, invoke ‘Ada | Project | Load...’, and select +‘Example_5/hello_5.adp’. + + Then, again in ‘hello_5.adb’, invoke ‘Ada | Set main and Build’. You +should get a ‘*compilation*’ buffer containing something like (the +directory paths will be different): + + cd c:/Examples/Example_5/ + gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs + gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb + gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb + hello_pkg.adb:2:08: keyword "body" expected here [see file name] + gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error + + Now type ‘C-x `’. ‘Example_4/hello_pkg.adb’ is shown, demonstrating +that ‘hello_5.gpr’ and ‘hello_4.gpr’ are being used to set the +compilation search path. + + +File: ada-mode.info, Node: Moving Through Ada Code, Next: Identifier completion, Prev: Compiling Examples, Up: Top + +7 Moving Through Ada Code +************************* + +There are several easy to use commands to navigate through Ada code. +All these functions are available through the Ada menu, and you can also +use the following key bindings or the command names. Some of these menu +entries are available only if the GNAT compiler is used, since the +implementation relies on the GNAT cross-referencing information. + +‘M-C-e’ + Move to the next function/procedure/task, which ever comes next + (‘ada-next-procedure’). +‘M-C-a’ + Move to previous function/procedure/task + (‘ada-previous-procedure’). +‘M-x ada-next-package’ + Move to next package. +‘M-x ada-previous-package’ + Move to previous package. +‘C-c C-a’ + Move to matching start of ‘end’ (‘ada-move-to-start’). If point is + at the end of a subprogram, this command jumps to the corresponding + ‘begin’ if the user option ‘ada-move-to-declaration’ is ‘nil’ + (default), otherwise it jumps to the subprogram declaration. +‘C-c C-e’ + Move point to end of current block (‘ada-move-to-end’). +‘C-c o’ + Switch between corresponding spec and body file + (‘ff-find-other-file’). If point is in a subprogram, position + point on the corresponding declaration or body in the other file. +‘C-c c-d’ + Move from any reference to its declaration, for from a declaration + to its body (for procedures, tasks, private and incomplete types). +‘C-c C-r’ + Runs the ‘gnatfind’ command to search for all references to the + identifier surrounding point (‘ada-find-references’). Use ‘C-x `’ + (‘next-error’) to visit each reference (as for compilation errors). + + If the ‘ada-xref-create-ali’ variable is non-‘nil’, Emacs will try to +run GNAT for you whenever cross-reference information is needed, and is +older than the current source file. + + +File: ada-mode.info, Node: Identifier completion, Next: Automatic Smart Indentation, Prev: Moving Through Ada Code, Up: Top + +8 Identifier completion +*********************** + +Emacs and Ada mode provide two general ways for the completion of +identifiers. This is an easy way to type faster: you just have to type +the first few letters of an identifiers, and then loop through all the +possible completions. + + The first method is general for Emacs. It works by parsing all open +files for possible completions. + + For instance, if the words ‘my_identifier’, ‘my_subprogram’ are the +only words starting with ‘my’ in any of the opened files, then you will +have this scenario: + + You type: myM-/ + Emacs inserts: ‘my_identifier’ + If you press M-/ once again, Emacs replaces ‘my_identifier’ with + ‘my_subprogram’. + Pressing M-/ once more will bring you back to ‘my_identifier’. + + This is a very fast way to do completion, and the casing of words +will also be respected. + + The second method (‘C-<TAB>’) is specific to Ada mode and the GNAT +compiler. Emacs will search the cross-information for possible +completions. + + The main advantage is that this completion is more accurate: only +existing identifier will be suggested. + + On the other hand, this completion is a little bit slower and +requires that you have compiled your file at least once since you +created that identifier. + +‘C-<TAB>’ + Complete current identifier using cross-reference information. +‘M-/’ + Complete identifier using buffer information (not Ada-specific). + + +File: ada-mode.info, Node: Automatic Smart Indentation, Next: Formatting Parameter Lists, Prev: Identifier completion, Up: Top + +9 Automatic Smart Indentation +***************************** + +Ada mode comes with a full set of rules for automatic indentation. You +can also configure the indentation, via the following variables: + +‘ada-broken-indent’ (default value: 2) + Number of columns to indent the continuation of a broken line. + +‘ada-indent’ (default value: 3) + Number of columns for default indentation. + +‘ada-indent-record-rel-type’ (default value: 3) + Indentation for ‘record’ relative to ‘type’ or ‘use’. + +‘ada-indent-return’ (default value: 0) + Indentation for ‘return’ relative to ‘function’ (if + ‘ada-indent-return’ is greater than 0), or the open parenthesis (if + ‘ada-indent-return’ is negative or 0). Note that in the second + case, when there is no open parenthesis, the indentation is done + relative to ‘function’ with the value of ‘ada-broken-indent’. + +‘ada-label-indent’ (default value: -4) + Number of columns to indent a label. + +‘ada-stmt-end-indent’ (default value: 0) + Number of columns to indent a statement ‘end’ keyword on a separate + line. + +‘ada-when-indent’ (default value: 3) + Indentation for ‘when’ relative to ‘exception’ or ‘case’. + +‘ada-indent-is-separate’ (default value: t) + Non-‘nil’ means indent ‘is separate’ or ‘is abstract’ if on a + single line. + +‘ada-indent-to-open-paren’ (default value: t) + Non-‘nil’ means indent according to the innermost open parenthesis. + +‘ada-indent-after-return’ (default value: t) + Non-‘nil’ means that the current line will also be re-indented + before inserting a newline, when you press <RET>. + + Most of the time, the indentation will be automatic, i.e., when you +press <RET>, the cursor will move to the correct column on the next +line. + + You can also indent single lines, or the current region, with <TAB>. + + Another mode of indentation exists that helps you to set up your +indentation scheme. If you press ‘C-c <TAB>’, Ada mode will do the +following: + + • Reindent the current line, as <TAB> would do. + • Temporarily move the cursor to a reference line, i.e., the line + that was used to calculate the current indentation. + • Display in the message window the name of the variable that + provided the offset for the indentation. + + The exact indentation of the current line is the same as the one for +the reference line, plus an offset given by the variable. + +‘<TAB>’ + Indent the current line or the current region. +‘C-M-\’ + Indent lines in the current region. +‘C-c <TAB>’ + Indent the current line and display the name of the variable used + for indentation. + + +File: ada-mode.info, Node: Formatting Parameter Lists, Next: Automatic Casing, Prev: Automatic Smart Indentation, Up: Top + +10 Formatting Parameter Lists +***************************** + +‘C-c C-f’ + Format the parameter list (‘ada-format-paramlist’). + + This aligns the declarations on the colon (‘:’) separating argument +names and argument types, and aligns the ‘in’, ‘out’ and ‘in out’ +keywords. + + +File: ada-mode.info, Node: Automatic Casing, Next: Statement Templates, Prev: Formatting Parameter Lists, Up: Top + +11 Automatic Casing +******************* + +Casing of identifiers, attributes and keywords is automatically +performed while typing when the variable ‘ada-auto-case’ is set. Every +time you press a word separator, the previous word is automatically +cased. + + You can customize the automatic casing differently for keywords, +attributes and identifiers. The relevant variables are the following: +‘ada-case-keyword’, ‘ada-case-attribute’ and ‘ada-case-identifier’. + + All these variables can have one of the following values: + +‘downcase-word’ + The word will be lowercase. For instance ‘My_vARIable’ is + converted to ‘my_variable’. + +‘upcase-word’ + The word will be uppercase. For instance ‘My_vARIable’ is + converted to ‘MY_VARIABLE’. + +‘ada-capitalize-word’ + The first letter and each letter following an underscore (‘_’) are + uppercase, others are lowercase. For instance ‘My_vARIable’ is + converted to ‘My_Variable’. + +‘ada-loose-case-word’ + Characters after an underscore ‘_’ character are uppercase, others + are not modified. For instance ‘My_vARIable’ is converted to + ‘My_VARIable’. + + Ada mode allows you to define exceptions to these rules, in a file +specified by the variable ‘ada-case-exception-file’ (default +‘~/.emacs_case_exceptions’). Each line in this file specifies the +casing of one word or word fragment. Comments may be included, +separated from the word by a space. + + If the word starts with an asterisk (‘*’), it defines the casing as a +word fragment (or “substring”); part of a word between two underscores +or word boundary. + + For example: + + DOD Department of Defense + *IO + GNAT The GNAT compiler from Ada Core Technologies + + The word fragment ‘*IO’ applies to any word containing “_io”; +‘Text_IO’, ‘Hardware_IO’, etc. + + There are two ways to add new items to this file: you can simply edit +it as you would edit any text file. Or you can position point on the +word you want to add, and select menu ‘Ada | Edit | Create Case +Exception’, or press ‘C-c C-y’ (‘ada-create-case-exception’). The word +will automatically be added to the current list of exceptions and to the +file. + + To define a word fragment case exception, select the word fragment, +then select menu ‘Ada | Edit | Create Case Exception Substring’. + + It is sometimes useful to have multiple exception files around (for +instance, one could be the standard Ada acronyms, the second some +company specific exceptions, and the last one some project specific +exceptions). If you set up the variable ‘ada-case-exception-file’ as a +list of files, each of them will be parsed and used in your emacs +session. However, when you save a new exception through the menu, as +described above, the new exception will be added to the first file in +the list. + +‘C-c C-b’ + Adjust case in the whole buffer (‘ada-adjust-case-buffer’). +‘C-c C-y’ + Create a new entry in the exception dictionary, with the word under + the cursor (‘ada-create-case-exception’) +‘C-c C-t’ + Rereads the exception dictionary from the file + ‘ada-case-exception-file’ (‘ada-case-read-exceptions’). + + +File: ada-mode.info, Node: Statement Templates, Next: Comment Handling, Prev: Automatic Casing, Up: Top + +12 Statement Templates +********************** + +Templates are defined for most Ada statements, using the Emacs +“skeleton” package. They can be inserted in the buffer using the +following commands: + +‘C-c t b’ + exception Block (‘ada-exception-block’). +‘C-c t c’ + case (‘ada-case’). +‘C-c t d’ + declare Block (‘ada-declare-block’). +‘C-c t e’ + else (‘ada-else’). +‘C-c t f’ + for Loop (‘ada-for-loop’). +‘C-c t h’ + Header (‘ada-header’). +‘C-c t i’ + if (‘ada-if’). +‘C-c t k’ + package Body (‘ada-package-body’). +‘C-c t l’ + loop (‘ada-loop’). +‘C-c p’ + subprogram body (‘ada-subprogram-body’). +‘C-c t t’ + task Body (‘ada-task-body’). +‘C-c t w’ + while Loop (‘ada-while’). +‘C-c t u’ + use (‘ada-use’). +‘C-c t x’ + exit (‘ada-exit’). +‘C-c t C-a’ + array (‘ada-array’). +‘C-c t C-e’ + elsif (‘ada-elsif’). +‘C-c t C-f’ + function Spec (‘ada-function-spec’). +‘C-c t C-k’ + package Spec (‘ada-package-spec’). +‘C-c t C-p’ + procedure Spec (‘ada-package-spec’. +‘C-c t C-r’ + record (‘ada-record’). +‘C-c t C-s’ + subtype (‘ada-subtype’). +‘C-c t C-t’ + task Spec (‘ada-task-spec’). +‘C-c t C-u’ + with (‘ada-with’). +‘C-c t C-v’ + private (‘ada-private’). +‘C-c t C-w’ + when (‘ada-when’). +‘C-c t C-x’ + exception (‘ada-exception’). +‘C-c t C-y’ + type (‘ada-type’). + + +File: ada-mode.info, Node: Comment Handling, Next: GNU Free Documentation License, Prev: Statement Templates, Up: Top + +13 Comment Handling +******************* + +By default, comment lines get indented like Ada code. There are a few +additional functions to handle comments: + +‘M-;’ + Start a comment in default column. +‘M-j’ + Continue comment on next line. +‘C-c ;’ + Comment the selected region (add ‘--’ at the beginning of lines). +‘C-c :’ + Uncomment the selected region +‘M-q’ + autofill the current comment. + + +File: ada-mode.info, Node: GNU Free Documentation License, Next: Index, Prev: Comment Handling, Up: Top + +Appendix A 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. + + 0. 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/licenses/>. + + 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 (C) 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. + + +File: ada-mode.info, Node: Index, Prev: GNU Free Documentation License, Up: Top + +Index +***** + + +* Menu: + +* ada-adjust-case-buffer: Automatic Casing. (line 74) +* ada-array: Statement Templates. (line 39) +* ada-case: Statement Templates. (line 13) +* ada-case-read-exceptions: Automatic Casing. (line 79) +* ada-complete-identifier: Identifier completion. + (line 39) +* ada-create-case-exception: Automatic Casing. (line 54) +* ada-declare-block: Statement Templates. (line 15) +* ada-else: Statement Templates. (line 17) +* ada-elsif: Statement Templates. (line 41) +* ada-exception: Statement Templates. (line 61) +* ada-exception-block: Statement Templates. (line 11) +* ada-exit: Statement Templates. (line 37) +* ada-find-references: Moving Through Ada Code. + (line 37) +* ada-for-loop: Statement Templates. (line 19) +* ada-format-paramlist: Formatting Parameter Lists. + (line 7) +* ada-function-spec: Statement Templates. (line 43) +* ada-goto-declaration: Moving Through Ada Code. + (line 34) +* ada-header: Statement Templates. (line 21) +* ada-if: Statement Templates. (line 23) +* ada-loop: Statement Templates. (line 27) +* ada-move-to-end: Moving Through Ada Code. + (line 28) +* ada-move-to-start: Moving Through Ada Code. + (line 23) +* ada-next-package: Moving Through Ada Code. + (line 19) +* ada-next-procedure: Moving Through Ada Code. + (line 13) +* ada-package-body: Statement Templates. (line 25) +* ada-package-spec: Statement Templates. (line 45) +* ada-previous-package: Moving Through Ada Code. + (line 21) +* ada-previous-procedure: Moving Through Ada Code. + (line 16) +* ada-private: Statement Templates. (line 57) +* ada-procedure-spec: Statement Templates. (line 47) +* ada-record: Statement Templates. (line 49) +* ada-subprogram-body: Statement Templates. (line 29) +* ada-subtype: Statement Templates. (line 51) +* ada-task-body: Statement Templates. (line 31) +* ada-task-spec: Statement Templates. (line 53) +* ada-type: Statement Templates. (line 63) +* ada-use: Statement Templates. (line 35) +* ada-when: Statement Templates. (line 59) +* ada-while: Statement Templates. (line 33) +* ada-with: Statement Templates. (line 55) + + + +Tag Table: +Node: Top862 +Node: Overview2536 +Node: Installation3858 +Node: Customization5019 +Node: Non-standard file names5943 +Node: Other compiler7474 +Node: Other customization7978 +Node: Compiling Executing8652 +Node: Compile commands9328 +Node: Compiler errors12177 +Node: Project files13082 +Node: Project File Overview13795 +Node: GUI Editor16150 +Node: Project file variables16642 +Node: Compiling Examples23982 +Node: No project files24780 +Node: Set compiler options29651 +Node: Set source search path31696 +Node: Use GNAT project file34044 +Node: Use multiple GNAT project files36288 +Node: Moving Through Ada Code38239 +Node: Identifier completion40280 +Node: Automatic Smart Indentation41884 +Node: Formatting Parameter Lists44754 +Node: Automatic Casing45184 +Node: Statement Templates48588 +Node: Comment Handling50251 +Node: GNU Free Documentation License50806 +Node: Index76164 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/old_ada/doc/ada-mode.pdf b/old_ada/doc/ada-mode.pdf Binary files differnew file mode 100644 index 0000000..c3f3839 --- /dev/null +++ b/old_ada/doc/ada-mode.pdf diff --git a/old_ada/doc/ada-mode.texi b/old_ada/doc/ada-mode.texi new file mode 100644 index 0000000..1ac90cd --- /dev/null +++ b/old_ada/doc/ada-mode.texi @@ -0,0 +1,1526 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../../info/ada-mode.info +@settitle Ada Mode +@include docstyle.texi + +@copying +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. + +@quotation +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 ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs editing modes +@direntry +* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. +@end direntry + +@titlepage +@sp 10 +@title Ada Mode +@sp 2 +@subtitle An Emacs major mode for programming in Ada +@subtitle Ada Mode Version 4.00 +@sp 2 +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@node Top +@top Ada Mode + +@ifnottex +@insertcopying +@end ifnottex + +@menu +* Overview:: +* Installation:: Installing Ada mode on your system +* Customization:: Setting up Ada mode to your taste +* Compiling Executing:: Working with your application within Emacs +* Project files:: Describing the organization of your project +* Compiling Examples:: A small tutorial +* Moving Through Ada Code:: Moving easily through Ada sources +* Identifier completion:: Finishing words automatically +* Automatic Smart Indentation:: Indenting your code automatically as you type +* Formatting Parameter Lists:: Formatting subprograms' parameter lists + automatically +* Automatic Casing:: Adjusting the case of words automatically +* Statement Templates:: Inserting code templates +* Comment Handling:: Reformatting comments easily +* GNU Free Documentation License:: The license for this documentation. +* Index:: +@end menu + + +@node Overview +@chapter Overview + +The Emacs mode for programming in Ada helps the user in understanding +existing code and facilitates writing new code. + +When the GNU Ada compiler GNAT is used, the cross-reference +information output by the compiler is used to provide powerful code +navigation (jump to definition, find all uses, etc.). + +When you open a file with a file extension of @file{.ads} or +@file{.adb}, Emacs will automatically load and activate Ada mode. + +Ada mode works without any customization, if you are using the GNAT +compiler (@url{https://libre2.adacore.com/}) and the GNAT default +naming convention. + +You must customize a few things if you are using a different compiler +or file naming convention; @xref{Other compiler}, @xref{Non-standard +file names}. + +In addition, you may want to customize the indentation, +capitalization, and other things; @xref{Other customization}. + +Finally, for large Ada projects, you will want to set up an Emacs +Ada mode project file for each project; @xref{Project files}. Note +that these are different from the GNAT project files used by gnatmake +and other GNAT commands. + +See the Emacs info manual, section 'Running Debuggers Under Emacs', +for general information on debugging. + +@node Installation +@chapter Installation + +Ada mode is part of the standard Emacs distribution; if you use that, +no files need to be installed. + +Ada mode is also available as a separate distribution, from the Emacs +Ada mode website +@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The +separate distribution may be more recent. + +For installing the separate distribution, see the @file{README} file +in the distribution. + +To see what version of Ada mode you have installed, do @kbd{M-x +ada-mode-version}. + +The following files are provided with the Ada mode distribution: + +@itemize @bullet + +@item +@file{ada-mode.el}: The main file for Ada mode, providing indentation, +formatting of parameter lists, moving through code, comment handling +and automatic casing. + +@item +@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs +widgets. + +@item +@file{ada-stmt.el}: Ada statement templates. + +@item +@file{ada-xref.el}: GNAT cross-references, completion of identifiers, +and compilation. Also provides project files (which are not +GNAT-specific). + +@end itemize + +@node Customization +@chapter Customizing Ada mode + +Here we assume you are familiar with setting variables in Emacs, +either thru 'customize' or in elisp (in your @file{.emacs} file). For +a basic introduction to customize, elisp, and Emacs in general, see +the tutorial in +@iftex +@cite{The GNU Emacs Manual}. +@end iftex +@ifhtml +@cite{The GNU Emacs Manual}. +@end ifhtml +@ifinfo +@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. +@end ifinfo + +These global Emacs settings are strongly recommended (put them in your +.emacs): + +@example +(global-font-lock-mode t) +(transient-mark-mode t) +@end example + +@samp{(global-font-lock-mode t)} turns on syntax +highlighting for all buffers (it is off by default because it may be +too slow for some machines). + +@samp{(transient-mark-mode t)} highlights selected text. + +See the Emacs help for each of these variables for more information. + +@menu +* Non-standard file names:: +* Other compiler:: +* Other customization:: +@end menu + +@node Non-standard file names +@section Non-standard file names + +By default, Ada mode is configured to use the GNAT file naming +convention, where file names are a simple modification of the Ada +names, and the extension for specs and bodies are +@samp{.ads} and @samp{.adb}, respectively. + +Ada mode uses the file extensions to allow moving from a package body +to the corresponding spec and back. + +Ada mode supports a list of alternative file extensions for specs and bodies. + +For instance, if your spec and bodies files are called +@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you +can add the following to your @file{.emacs} file: + +@example +(ada-add-extensions "_s.ada" "_b.ada") +@end example + +You can define additional extensions: + +@example +(ada-add-extensions ".ads" "_b.ada") +(ada-add-extensions ".ads" ".body") +@end example + +This means that whenever Ada mode looks for the body for a file +whose extension is @file{.ads}, it will take the first available file +that ends with either @file{.adb}, @file{_b.ada} or +@file{.body}. + +Similarly, if Ada mode is looking for a spec, it will look for +@file{.ads} or @file{_s.ada}. + +If the filename is not derived from the Ada name following the GNAT +convention, things are a little more complicated. You then need to +rewrite the function @code{ada-make-filename-from-adaname}. Doing that +is beyond the scope of this manual; see the current definitions in +@file{ada-mode.el} and @file{ada-xref.el} for examples. + +@node Other compiler +@section Other compiler + +By default, Ada mode is configured to use the GNU Ada compiler GNAT. + +To use a different Ada compiler, you must specify the command lines +used to run that compiler, either in lisp variables or in Emacs +Ada mode project files. See @ref{Project file variables} for the list +of project variables, and the corresponding lisp variables. + +@node Other customization +@section Other customization + +All user-settable Ada mode variables can be set via the menu +@samp{Ada | Customize}. Click on the @samp{Help} button there for help +on using customize. + +To modify a specific variable, you can directly call the function +@code{customize-variable}; just type @kbd{M-x customize-variable +@key{RET} @var{variable-name} @key{RET}}). + +Alternately, you can specify variable settings in the Emacs +configuration file, @file{.emacs}. This file is coded in Emacs lisp, +and the syntax to set a variable is the following: +@example +(setq variable-name value) +@end example + +@node Compiling Executing +@chapter Compiling Executing + +Ada projects can be compiled, linked, and executed using commands on +the Ada menu. All of these commands can be customized via a project +file (@pxref{Project files}), but the defaults are sufficient for using +the GNAT compiler for simple projects (single files, or several files +in a single directory). + +Even when no project file is used, the GUI project editor (menu +@samp{Ada | Project | Edit}) shows the settings of the various project +file variables referenced here. + +@menu +* Compile commands:: +* Compiler errors:: +@end menu + +@node Compile commands +@section Compile commands + +Here are the commands for building and using an Ada project, as +listed in the Ada menu. + +In multi-file projects, there must be one file that is the main +program. That is given by the @code{main} project file variable; +it defaults to the current file if not yet set, but is also set by the +``set main and build'' command. + +@table @code + +@item Check file +Compiles the current file in syntax check mode, by running +@code{check_cmd} defined in the current project file. This typically +runs faster than full compile mode, speeding up finding and fixing +compilation errors. + +This sets @code{main} only if it has not been set yet. + +@item Compile file +Compiles the current file, by running @code{comp_cmd} from the current +project file. + +This does not set @code{main}. + +@item Set main and Build +Sets @code{main} to the current file, then executes the Build +command. + +@item Show main +Display @code{main} in the message buffer. + +@item Build +Compiles all obsolete units of the current @code{main}, and links +@code{main}, by running @code{make_cmd} from the current project. + +This sets @code{main} only if it has not been set yet. + +@item Run +Executes the main program in a shell, displayed in a separate Emacs +buffer. This runs @code{run_cmd} from the current project. The +execution buffer allows for interactive input/output. + +To modify the run command, in particular to provide or change the +command line arguments, type @kbd{C-u} before invoking the command. + +This command is not available for a cross-compilation toolchain. + +@end table +It is important when using these commands to understand how +@code{main} is used and changed. + +Build runs 'gnatmake' on the main unit. During a typical edit/compile +session, this is the only command you need to invoke, which is why it +is bound to @kbd{C-c C-c}. It will compile all files needed by the +main unit, and display compilation errors in any of them. + +Note that Build can be invoked from any Ada buffer; typically you will +be fixing errors in files other than the main, but you don't have to +switch back to the main to invoke the compiler again. + +Novices and students typically work on single-file Ada projects. In +this case, @kbd{C-c C-m} will normally be the only command needed; it +will build the current file, rather than the last-built main. + +There are three ways to change @code{main}: + +@enumerate +@item +Invoke @samp{Ada | Set main and Build}, which sets @code{main} to +the current file. + +@item +Invoke @samp{Ada | Project | Edit}, edit @code{main} and +@code{main}, and click @samp{[save]} + +@item +Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} + +@end enumerate + +@node Compiler errors +@section Compiler errors + +The @code{Check file}, @code{Compile file}, and @code{Build} commands +all place compilation errors in a separate buffer named +@file{*compilation*}. + +Each line in this buffer will become active: you can simply click on +it with the middle button of the mouse, or move point to it and press +@key{RET}. Emacs will then display the relevant source file and put +point on the line and column where the error was found. + +You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs +will jump to the first error. If you press that key again, it will +move you to the second error, and so on. + +Some error messages might also include references to other files. These +references are also clickable in the same way, or put point after the +line number and press @key{RET}. + +@node Project files +@chapter Project files + +An Emacs Ada mode project file specifies what directories hold sources +for your project, and allows you to customize the compilation commands +and other things on a per-project basis. + +Note that Ada mode project files @file{*.adp} are different than GNAT +compiler project files @file{*.gpr}. However, Emacs Ada mode can use a +GNAT project file to specify the project directories. If no +other customization is needed, a GNAT project file can be used without +an Emacs Ada mode project file. + +@menu +* Project File Overview:: +* GUI Editor:: +* Project file variables:: +@end menu + +@node Project File Overview +@section Project File Overview + +Project files have a simple syntax; they may be edited directly. Each +line specifies a project variable name and its value, separated by ``='': +@example +src_dir=/Projects/my_project/src_1 +src_dir=/Projects/my_project/src_2 +@end example + +Some variables (like @code{src_dir}) are lists; multiple occurrences +are concatenated. + +There must be no space between the variable name and ``='', and no +trailing spaces. + +Alternately, a GUI editor for project files is available (@pxref{GUI +Editor}). It uses Emacs widgets, similar to Emacs customize. + +The GUI editor also provides a convenient way to view current project +settings, if they have been modified using menu commands rather than +by editing the project file. + +After the first Ada mode build command is invoked, there is always a +current project file, given by the lisp variable +@code{ada-prj-default-project-file}. Currently, the only way to show +the current project file is to invoke the GUI editor. + +To find the project file the first time, Ada mode uses the following +search algorithm: + +@itemize @bullet +@item +If @code{ada-prj-default-project-file} is set, use that. + +@item +Otherwise, search for a file in the current directory with +the same base name as the Ada file, but extension given by +@code{ada-prj-file-extension} (default @code{".adp"}). + +@item +If not found, search for @file{*.adp} in the current directory; if +several are found, prompt the user to select one. + +@item +If none are found, use @file{default.adp} in the current directory (even +if it does not exist). + +@end itemize + +This algorithm always sets @code{ada-prj-default-project-file}, even +when the file does not actually exist. + +To change the project file before or after the first one is found, +invoke @samp{Ada | Project | Load ...}. + +Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}. +This sets @code{ada-prj-default-project-file}, and reads the project file. + +You can also specify a GNAT project file to @samp{Ada | Project | Load +...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the +file extension; if it is @code{.gpr}, the file is treated as a GNAT +project file. Any other extension is treated as an Emacs Ada mode +project file. + +@node GUI Editor +@section GUI Editor + +The project file editor is invoked with the menu @samp{Ada | Projects +| Edit}. + +Once in the buffer for editing the project file, you can save your +modification using the @samp{[save]} button at the bottom of the +buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, +kill the buffer or click on the @samp{[cancel]} button. + +@node Project file variables +@section Project file variables + +The following variables can be defined in a project file; some can +also be defined in lisp variables. + +To set a project variable that is a list, specify each element of the +list on a separate line in the project file. + +Any project variable can be referenced in other project variables, +using a shell-like notation. For instance, if the variable +@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the +@code{comp_opt} variable will be substituted when @code{comp_cmd} is +used. + +In addition, process environment variables can be referenced using the +same syntax, or the normal @code{$var} syntax. + +Most project variables have defaults that can be changed by setting +lisp variables; the table below identifies the lisp variable for each +project variable. Lisp variables corresponding to project variables +that are lists are lisp lists. + +In general, project variables are evaluated when referenced in +Emacs Ada mode commands. Relative file paths are expanded to +absolute relative to @code{$@{build_dir@}}. + +Here is the list of variables. In the default values, the current +directory @code{"."} is the project file directory. + +@table @asis +@c defined in ada-default-prj-properties; alphabetical order + +@item @code{ada_project_path_sep} [default: @code{":" or ";"}] +Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct +value for a native implementation of GNAT for the current operating +system. The user must override this when using Windows native GNAT +with Cygwin Emacs, and perhaps in other cases. + +Lisp variable: @code{ada-prj-ada-project-path-sep}. + +@item @code{ada_project_path} [default: @code{""}] +A list of directories to search for GNAT project files. + +If set, the @code{ADA_PROJECT_PATH} process environment variable is +set to this value in the Emacs process when the Emacs Ada mode project +is selected via menu @samp{Ada | Project | Load}. + +For @code{ada_project_path}, relative file paths are expanded to +absolute when the Emacs Ada project file is read, rather than when the +project file is selected. + +For example if the project file is in the directory +@file{/home/myproject}, the environment variable @code{GDS_ROOT} is +set to @code{/home/shared}, and the project file contains: +@example +ada_project_path_sep=: +ada_project_path=$GDS_ROOT/makerules +ada_project_path=../opentoken +@end example +then as a result the environment variable @code{ADA_PROJECT_PATH} will +be set to @code{"/home/shared/makerules:/home/opentoken/"}. + +The default value is not the current value of this environment +variable, because that will typically have been set by another +project, and will therefore be incorrect for this project. + +If you have the environment variable set correctly for all of your +projects, you do not need to set this project variable. + +@item @code{bind_opt} [default: @code{""}] +Holds user binder options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-bind-opt}. + +@item @code{build_dir} [default: @code{"."}] +The compile commands will be issued in this directory. + +@item @code{casing} [default: @code{("~/.emacs_case_exceptions")}] +List of files containing casing exceptions. See the help on +@code{ada-case-exception-file} for more info. +@c FIXME: section on case exceptions + +Lisp variable: @code{ada-case-exception-file}. + +@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] +Command used to syntax check a single file. +The name of the file is substituted for @code{full_current}. + +Lisp variable: @code{ada-prj-default-check-cmd} + +@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] +Command used to compile a single file. +The name of the file is substituted for @code{full_current}. + +Lisp variable: @code{ada-prj-default-comp-cmd}. + +@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] +Holds user compiler options; used in the default compile commands. The +default value tells gnatmake to generate library files for +cross-referencing even when there are errors. + +If source code for the project is in multiple directories, the +appropriate compiler options must be added here. @ref{Set source +search path} for examples of this. Alternately, GNAT project files may +be used; @ref{Use GNAT project file}. + +Lisp variable: @code{ada-prj-default-comp-opt}. + +@item @code{cross_prefix} [default: @code{""}] +Name of target machine in a cross-compilation environment. Used in +default compile and build commands. + +@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] +Command used to debug the application + +Lisp variable: @code{ada-prj-default-debugger}. + +@item @code{debug_post_cmd} [default: @code{""}] +Command executed after @code{debug_cmd}. + +@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] +Command executed before @code{debug_cmd}. + +@item @code{gnatfind_opt} [default: @code{"-rf"}] +Holds user gnatfind options; used in the default find commands. + +Lisp variable: @code{ada-prj-gnatfind-switches}. + +@item @code{gnatmake_opt} [default: @code{"-g"}] +Holds user gnatmake options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-gnatmake-opt}. + +@item @code{gpr_file} [default: @code{""}] +Specify GNAT project file. + +If set, the source and object directories specified in the GNAT +project file are appended to @code{src_dir} and @code{obj_dir}. This +allows specifying Ada source directories with a GNAT project file, and +other source directories with the Emacs project file. + +In addition, @code{-P@{gpr_file@}} is added to the project variable +@code{gnatmake_opt} whenever it is referenced. With the default +project variables, this passes the project file to all gnatmake +commands. + +Lisp variable: @code{ada-prj-default-gpr-file}. + +@c FIXME: add gnatstub-opts + +@item @code{link_opt} [default: @code{""}] +Holds user linker options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-link-opt}. + +@item @code{main} [default: current file] +Specifies the name of the executable file for the project; used in the +default build commands. + +@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] +Command used to build the application. + +Lisp variable: @code{ada-prj-default-make-cmd}. + +@item @code{obj_dir} [default: @code{"."}] +A list of directories to search for library files. Ada mode searches +this list for the @samp{.ali} files generated by GNAT that contain +cross-reference information. + +The compiler commands must place the @samp{.ali} files in one of these +directories; the default commands do that. + +@item @code{remote_machine} [default: @code{""}] +Name of the machine to log into before issuing the compile and build +commands. If this variable is empty, the command will be run on the +local machine. + +@item @code{run_cmd} [default: @code{"./$@{main@}"}] +Command used to run the application. + +@item @code{src_dir} [default: @code{"."}] +A list of directories to search for source files, both for compile +commands and source navigation. + +@end table + +@node Compiling Examples +@chapter Compiling Examples + +We present several small projects, and walk thru the process of +compiling, linking, and running them. + +The first example illustrates more Ada mode features than the others; +you should work thru that example before doing the others. + +All of these examples assume you are using GNAT. + +The source for these examples is available on the Emacs Ada mode +website mentioned in @xref{Installation}. + +@menu +* No project files:: Just menus +* Set compiler options:: A basic Ada mode project file +* Set source search path:: Source in multiple directories +* Use GNAT project file:: +* Use multiple GNAT project files:: +@end menu + +@node No project files +@section No project files +This example uses no project files. + +First, create a directory @file{Example_1}, containing: + +@file{hello.adb}: + +@example +with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +@end example + +Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate +compiler error handling. + +@file{hello_2.adb}: + +@example +with Hello_Pkg; +procedure Hello_2 +is begin + Hello_Pkg.Say_Hello; +end Hello_2; +@end example + +This file has no errors. + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +This file has no errors. + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +Yes, this is missing the keyword @code{body}; another compiler error +example. + +In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should +get a @file{*compilation*} buffer containing something like (the +directory paths will be different): + +@smallexample +cd c:/Examples/Example_1/ +gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ +gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +gnatmake: "c:/Examples/Example_1/hello.adb" compilation error +@end smallexample + +If you have enabled font-lock, the lines with actual errors (starting +with @file{hello.adb}) are highlighted, with the file name in red. + +Now type @kbd{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). +Or you can click the middle mouse button on the first error line. The +compilation buffer scrolls to put the first error on the top line, and +point is put at the place of the error in the @file{hello.adb} buffer. + +To fix the error, change the line to be + +@example + Ada.Text_IO.Put_Line ("hello from hello.adb"); +@end example + +Now invoke @samp{Ada | Show main}; this displays @samp{Ada mode main: hello}. + +Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build}. You are +prompted to save the file (if you haven't already). Then the +compilation buffer is displayed again, containing: + +@example +cd c:/Examples/Example_1/ +gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello.adb +gnatbind -x hello.ali +gnatlink hello.ali -o hello.exe -g +@end example + +The compilation has succeeded without errors; @file{hello.exe} now +exists in the same directory as @file{hello.adb}. + +Now invoke @samp{Ada | Run}. A @file{*run*} buffer is displayed, +containing + +@example +Hello from hello.adb + +Process run finished +@end example + +That completes the first part of this example. + +Now we will compile a multi-file project. Open the file +@file{hello_2.adb}, and invoke @samp{Ada | Set main and Build}. This +finds an error in @file{hello_pkg.adb}: + +@example +cd c:/Examples/Example_1/ +gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatq -gnatQ hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "hello_pkg.adb" compilation error +@end example + +This demonstrates that gnatmake finds the files needed by the main +program. However, it cannot find files in a different directory, +unless you use an Emacs Ada mode project file to specify the other directories; +@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT +project file}. + +Invoke @samp{Ada | Show main}; this displays @file{Ada mode main: hello_2}. + +Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}: + +@example +package body Hello_Pkg is +@end example + +Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build}. +gnatmake successfully builds @file{hello_2}. This demonstrates that +Emacs has remembered the main file, in the project variable +@code{main}, and used it for the Build command. + +Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. +The @file{*run*} buffer displays @code{Hello from hello_pkg.adb}. + +One final point. If you switch back to buffer @file{hello.adb}, and +invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is +because @code{main} is still set to @code{hello_2}, as you can +see when you invoke @samp{Ada | Project | Edit}. + +There are three ways to change @code{main}: + +@enumerate +@item +Invoke @samp{Ada | Set main and Build}, which sets @code{main} to +the current file. + +@item +Invoke @samp{Ada | Project | Edit}, edit @code{main}, and click @samp{[save]} + +@item +Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} + +@end enumerate + +@node Set compiler options +@section Set compiler options + +This example illustrates using an Emacs Ada mode project file to set a +compiler option. + +If you have files from @file{Example_1} open in Emacs, you should +close them so you don't get confused. Use menu @samp{File | Close +(current buffer)}. + +In directory @file{Example_2}, create these files: + +@file{hello.adb}: + +@example +with Ada.Text_IO; +procedure Hello +is begin + Put_Line("Hello from hello.adb"); +end Hello; +@end example + +This is the same as @file{hello.adb} from @file{Example_1}. It has two +errors; missing ``use Ada.Text_IO;'', and no space between +@code{Put_Line} and its argument list. + +@file{hello.adp}: + +@example +comp_opt=-gnatyt +@end example + +This tells the GNAT compiler to check for token spacing; in +particular, there must be a space preceding a parenthesis. + +In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and +select @file{Example_2/hello.adp}. + +Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and +Build}. You should get a @file{*compilation*} buffer containing +something like (the directory paths will be different): + +@example +cd c:/Examples/Example_2/ +gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs +gcc -c -g -gnatyt hello.adb +hello.adb:4:04: "Put_Line" is not visible +hello.adb:4:04: non-visible declaration at a-textio.ads:264 +hello.adb:4:04: non-visible declaration at a-textio.ads:260 +hello.adb:4:12: (style) space required +gnatmake: "hello.adb" compilation error +@end example + +Compare this to the compiler output in @ref{No project files}; the +gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by +@code{-cargs -gnaty}, and an additional error is reported in +@file{hello.adb} on line 4. This shows that @file{hello.adp} is being +used to set the compiler options. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Set source search path +@section Set source search path + +In this example, we show how to deal with files in more than one +directory. We start with the same code as in @ref{No project files}; +create those files (with the errors present) + +Create the directory @file{Example_3}, containing: + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +These are the same files from example 1; @file{hello_pkg.adb} has an +error on line 2. + +In addition, create a directory @file{Example_3/Other}, containing these files: + +@file{Other/hello_3.adb}: + +@example +with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_3 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_3"); +end Hello_3; +@end example + +There are no errors in this file. + +@file{Other/other.adp}: + +@example +src_dir=.. +comp_opt=-I.. +@end example + +Note that there must be no trailing spaces. + +In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and +select @file{Example_3/Other/other.adp}. + +Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and +Build}. You should get a @file{*compilation*} buffer containing +something like (the directory paths will be different): + +@example +cd c:/Examples/Example_3/Other/ +gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs +gcc -c -g -I.. hello_3.adb +gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error +@end example + +Compare the @code{-cargs} option to the compiler output in @ref{Set +compiler options}; this shows that @file{other.adp} is being used to +set the compiler options. + +Move to the error with @kbd{C-x `}. Ada mode searches the list of +directories given by @code{src_dir} for the file mentioned in the +compiler error message. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Use GNAT project file +@section Use GNAT project file + +In this example, we show how to use a GNAT project file, with no Ada +mode project file. + +Create the directory @file{Example_4}, containing: + +@file{hello_pkg.ads}: + +@example +package Hello_Pkg is + procedure Say_Hello; +end Hello_Pkg; +@end example + +@file{hello_pkg.adb}: + +@example +with Ada.Text_IO; +package Hello_Pkg is + procedure Say_Hello + is begin + Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); + end Say_Hello; +end Hello_Pkg; +@end example + +These are the same files from example 1; @file{hello_pkg.adb} has an +error on line 2. + +In addition, create a directory @file{Example_4/Gnat_Project}, +containing these files: + +@file{Gnat_Project/hello_4.adb}: + +@example +with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_4 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_4"); +end Hello_4; +@end example + +There are no errors in this file. + +@file{Gnat_Project/hello_4.gpr}: + +@example +Project Hello_4 is + for Source_Dirs use (".", ".."); +end Hello_4; +@end example + +In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and +select @file{Example_4/Gnat_Project/hello_4.gpr}. + +Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and +Build}. You should get a @file{*compilation*} buffer containing +something like (the directory paths will be different): + +@smallexample +cd c:/Examples/Example_4/Gnat_Project/ +gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb +gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error +@end smallexample + +Compare the @code{gcc} options to the compiler output in @ref{Set +compiler options}; this shows that @file{hello_4.gpr} is being used to +set the compiler options. + +Fixing the error, linking and running the code proceed as in @ref{No +project files}. + +@node Use multiple GNAT project files +@section Use multiple GNAT project files + +In this example, we show how to use multiple GNAT project files, +specifying the GNAT project search path in an Ada mode project file. + +Create the directory @file{Example_4} as specified in @ref{Use GNAT +project file}. + +Create the directory @file{Example_5}, containing: + +@file{hello_5.adb}: + +@example +with Hello_Pkg; +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello_5 +is begin + Hello_Pkg.Say_Hello; + Put_Line ("From hello_5"); +end Hello_5; +@end example + +There are no errors in this file. + +@file{hello_5.adp}: + +@example +ada_project_path=../Example_4/Gnat_Project +gpr_file=hello_5.gpr +@end example + +@file{hello_5.gpr}: + +@example +with "hello_4"; +Project Hello_5 is + for Source_Dirs use ("."); + package Compiler is + for Default_Switches ("Ada") use ("-g", "-gnatyt"); + end Compiler; +end Hello_5; +@end example + +In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and +select @file{Example_5/hello_5.adp}. + +Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and +Build}. You should get a @file{*compilation*} buffer containing +something like (the directory paths will be different): + +@smallexample +cd c:/Examples/Example_5/ +gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs +gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb +gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb +hello_pkg.adb:2:08: keyword "body" expected here [see file name] +gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error +@end smallexample + +Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown, +demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being +used to set the compilation search path. + +@node Moving Through Ada Code +@chapter Moving Through Ada Code + +There are several easy to use commands to navigate through Ada code. All +these functions are available through the Ada menu, and you can also +use the following key bindings or the command names. Some of these +menu entries are available only if the GNAT compiler is used, since +the implementation relies on the GNAT cross-referencing information. + +@table @kbd +@item M-C-e +@findex ada-next-procedure +Move to the next function/procedure/task, which ever comes next +(@code{ada-next-procedure}). +@item M-C-a +@findex ada-previous-procedure +Move to previous function/procedure/task +(@code{ada-previous-procedure}). +@item M-x ada-next-package +@findex ada-next-package +Move to next package. +@item M-x ada-previous-package +@findex ada-previous-package +Move to previous package. +@item C-c C-a +@findex ada-move-to-start +Move to matching start of @code{end} (@code{ada-move-to-start}). If +point is at the end of a subprogram, this command jumps to the +corresponding @code{begin} if the user option +@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to +the subprogram declaration. +@item C-c C-e +@findex ada-move-to-end +Move point to end of current block (@code{ada-move-to-end}). +@item C-c o +Switch between corresponding spec and body file +(@code{ff-find-other-file}). If point is in a subprogram, position +point on the corresponding declaration or body in the other file. +@item C-c c-d +@findex ada-goto-declaration +Move from any reference to its declaration, for from a declaration to +its body (for procedures, tasks, private and incomplete types). +@item C-c C-r +@findex ada-find-references +Runs the @file{gnatfind} command to search for all references to the +identifier surrounding point (@code{ada-find-references}). Use +@kbd{C-x `} (@code{next-error}) to visit each reference (as for +compilation errors). +@end table + +If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs +will try to run GNAT for you whenever cross-reference information is +needed, and is older than the current source file. + +@node Identifier completion +@chapter Identifier completion + +Emacs and Ada mode provide two general ways for the completion of +identifiers. This is an easy way to type faster: you just have to type +the first few letters of an identifiers, and then loop through all the +possible completions. + +The first method is general for Emacs. It works by parsing all open +files for possible completions. + +For instance, if the words @samp{my_identifier}, @samp{my_subprogram} +are the only words starting with @samp{my} in any of the opened files, +then you will have this scenario: + +@example +You type: my@kbd{M-/} +Emacs inserts: @samp{my_identifier} +If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with +@samp{my_subprogram}. +Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}. +@end example + +This is a very fast way to do completion, and the casing of words will +also be respected. + +The second method (@kbd{C-@key{TAB}}) is specific to Ada mode and the GNAT +compiler. Emacs will search the cross-information for possible +completions. + +The main advantage is that this completion is more accurate: only +existing identifier will be suggested. + +On the other hand, this completion is a little bit slower and requires +that you have compiled your file at least once since you created that +identifier. + +@table @kbd +@item C-@key{TAB} +@findex ada-complete-identifier +Complete current identifier using cross-reference information. +@item M-/ +Complete identifier using buffer information (not Ada-specific). +@end table + +@node Automatic Smart Indentation +@chapter Automatic Smart Indentation + +Ada mode comes with a full set of rules for automatic indentation. You +can also configure the indentation, via the following variables: + +@table @asis +@item @code{ada-broken-indent} (default value: 2) +Number of columns to indent the continuation of a broken line. + +@item @code{ada-indent} (default value: 3) +Number of columns for default indentation. + +@item @code{ada-indent-record-rel-type} (default value: 3) +Indentation for @code{record} relative to @code{type} or @code{use}. + +@item @code{ada-indent-return} (default value: 0) +Indentation for @code{return} relative to @code{function} (if +@code{ada-indent-return} is greater than 0), or the open parenthesis +(if @code{ada-indent-return} is negative or 0). Note that in the second +case, when there is no open parenthesis, the indentation is done +relative to @code{function} with the value of @code{ada-broken-indent}. + +@item @code{ada-label-indent} (default value: -4) +Number of columns to indent a label. + +@item @code{ada-stmt-end-indent} (default value: 0) +Number of columns to indent a statement @code{end} keyword on a separate line. + +@item @code{ada-when-indent} (default value: 3) +Indentation for @code{when} relative to @code{exception} or @code{case}. + +@item @code{ada-indent-is-separate} (default value: t) +Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. + +@item @code{ada-indent-to-open-paren} (default value: t) +Non-@code{nil} means indent according to the innermost open parenthesis. + +@item @code{ada-indent-after-return} (default value: t) +Non-@code{nil} means that the current line will also be re-indented +before inserting a newline, when you press @key{RET}. +@end table + +Most of the time, the indentation will be automatic, i.e., when you +press @key{RET}, the cursor will move to the correct column on the +next line. + +You can also indent single lines, or the current region, with @key{TAB}. + +Another mode of indentation exists that helps you to set up your +indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do +the following: + +@itemize @bullet +@item +Reindent the current line, as @key{TAB} would do. +@item +Temporarily move the cursor to a reference line, i.e., the line that +was used to calculate the current indentation. +@item +Display in the message window the name of the variable that provided +the offset for the indentation. +@end itemize + +The exact indentation of the current line is the same as the one for the +reference line, plus an offset given by the variable. + +@table @kbd +@item @key{TAB} +Indent the current line or the current region. +@item C-M-\ +Indent lines in the current region. +@item C-c @key{TAB} +Indent the current line and display the name of the variable used for +indentation. +@end table + +@node Formatting Parameter Lists +@chapter Formatting Parameter Lists + +@table @kbd +@item C-c C-f +@findex ada-format-paramlist +Format the parameter list (@code{ada-format-paramlist}). +@end table + +This aligns the declarations on the colon (@samp{:}) separating +argument names and argument types, and aligns the @code{in}, +@code{out} and @code{in out} keywords. + +@node Automatic Casing +@chapter Automatic Casing + +Casing of identifiers, attributes and keywords is automatically +performed while typing when the variable @code{ada-auto-case} is set. +Every time you press a word separator, the previous word is +automatically cased. + +You can customize the automatic casing differently for keywords, +attributes and identifiers. The relevant variables are the following: +@code{ada-case-keyword}, @code{ada-case-attribute} and +@code{ada-case-identifier}. + +All these variables can have one of the following values: + +@table @code +@item downcase-word +The word will be lowercase. For instance @code{My_vARIable} is +converted to @code{my_variable}. + +@item upcase-word +The word will be uppercase. For instance @code{My_vARIable} is +converted to @code{MY_VARIABLE}. + +@item ada-capitalize-word +The first letter and each letter following an underscore (@samp{_}) +are uppercase, others are lowercase. For instance @code{My_vARIable} +is converted to @code{My_Variable}. + +@item ada-loose-case-word +Characters after an underscore @samp{_} character are uppercase, +others are not modified. For instance @code{My_vARIable} is converted +to @code{My_VARIable}. +@end table + +Ada mode allows you to define exceptions to these rules, in a file +specified by the variable @code{ada-case-exception-file} +(default @file{~/.emacs_case_exceptions}). Each line in this file +specifies the casing of one word or word fragment. Comments may be +included, separated from the word by a space. + +If the word starts with an asterisk (@samp{*}), it defines the casing +as a word fragment (or ``substring''); part of a word between two +underscores or word boundary. + +For example: + +@example +DOD Department of Defense +*IO +GNAT The GNAT compiler from Ada Core Technologies +@end example + +The word fragment @code{*IO} applies to any word containing ``_io''; +@code{Text_IO}, @code{Hardware_IO}, etc. + +@findex ada-create-case-exception +There are two ways to add new items to this file: you can simply edit +it as you would edit any text file. Or you can position point on the +word you want to add, and select menu @samp{Ada | Edit | Create Case +Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). +The word will automatically be added to the current list of exceptions +and to the file. + +To define a word fragment case exception, select the word fragment, +then select menu @samp{Ada | Edit | Create Case Exception Substring}. + +It is sometimes useful to have multiple exception files around (for +instance, one could be the standard Ada acronyms, the second some +company specific exceptions, and the last one some project specific +exceptions). If you set up the variable @code{ada-case-exception-file} +as a list of files, each of them will be parsed and used in your emacs +session. However, when you save a new exception through the menu, as +described above, the new exception will be added to the first file in +the list. + +@table @kbd +@item C-c C-b +@findex ada-adjust-case-buffer +Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). +@item C-c C-y +Create a new entry in the exception dictionary, with the word under +the cursor (@code{ada-create-case-exception}) +@item C-c C-t +@findex ada-case-read-exceptions +Rereads the exception dictionary from the file +@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). +@end table + +@node Statement Templates +@chapter Statement Templates + +Templates are defined for most Ada statements, using the Emacs +``skeleton'' package. They can be inserted in the buffer using the +following commands: + +@table @kbd +@item C-c t b +@findex ada-exception-block +exception Block (@code{ada-exception-block}). +@item C-c t c +@findex ada-case +case (@code{ada-case}). +@item C-c t d +@findex ada-declare-block +declare Block (@code{ada-declare-block}). +@item C-c t e +@findex ada-else +else (@code{ada-else}). +@item C-c t f +@findex ada-for-loop +for Loop (@code{ada-for-loop}). +@item C-c t h +@findex ada-header +Header (@code{ada-header}). +@item C-c t i +@findex ada-if +if (@code{ada-if}). +@item C-c t k +@findex ada-package-body +package Body (@code{ada-package-body}). +@item C-c t l +@findex ada-loop +loop (@code{ada-loop}). +@item C-c p +@findex ada-subprogram-body +subprogram body (@code{ada-subprogram-body}). +@item C-c t t +@findex ada-task-body +task Body (@code{ada-task-body}). +@item C-c t w +@findex ada-while +while Loop (@code{ada-while}). +@item C-c t u +@findex ada-use +use (@code{ada-use}). +@item C-c t x +@findex ada-exit +exit (@code{ada-exit}). +@item C-c t C-a +@findex ada-array +array (@code{ada-array}). +@item C-c t C-e +@findex ada-elsif +elsif (@code{ada-elsif}). +@item C-c t C-f +@findex ada-function-spec +function Spec (@code{ada-function-spec}). +@item C-c t C-k +@findex ada-package-spec +package Spec (@code{ada-package-spec}). +@item C-c t C-p +@findex ada-procedure-spec +procedure Spec (@code{ada-package-spec}. +@item C-c t C-r +@findex ada-record +record (@code{ada-record}). +@item C-c t C-s +@findex ada-subtype +subtype (@code{ada-subtype}). +@item C-c t C-t +@findex ada-task-spec +task Spec (@code{ada-task-spec}). +@item C-c t C-u +@findex ada-with +with (@code{ada-with}). +@item C-c t C-v +@findex ada-private +private (@code{ada-private}). +@item C-c t C-w +@findex ada-when +when (@code{ada-when}). +@item C-c t C-x +@findex ada-exception +exception (@code{ada-exception}). +@item C-c t C-y +@findex ada-type +type (@code{ada-type}). +@end table + +@node Comment Handling +@chapter Comment Handling + +By default, comment lines get indented like Ada code. There are a few +additional functions to handle comments: + +@table @kbd +@item M-; +Start a comment in default column. +@item M-j +Continue comment on next line. +@item C-c ; +Comment the selected region (add @samp{--} at the beginning of lines). +@item C-c : +Uncomment the selected region +@item M-q +autofill the current comment. +@end table + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + +@node Index +@unnumbered Index + +@printindex fn + +@bye diff --git a/old_ada/doc/build.sh b/old_ada/doc/build.sh new file mode 100755 index 0000000..a0799fe --- /dev/null +++ b/old_ada/doc/build.sh @@ -0,0 +1,3 @@ +#! /usr/bin/env bash +texi2any -o ada-mode.info --no-split ada-mode.texi +texi2any --html -o ada-mode.html --no-split ada-mode.texi diff --git a/old_ada/doc/clean.sh b/old_ada/doc/clean.sh new file mode 100755 index 0000000..f7e90b1 --- /dev/null +++ b/old_ada/doc/clean.sh @@ -0,0 +1,2 @@ +#! /bin/sh +rm ada-mode.aux ada-mode.fn ada-mode.log ada-mode.toc diff --git a/old_ada/doc/doclicense.texi b/old_ada/doc/doclicense.texi new file mode 100644 index 0000000..eaf3da0 --- /dev/null +++ b/old_ada/doc/doclicense.texi @@ -0,0 +1,505 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{https://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{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. + +@item +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, La@TeX{} 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. + +@item +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. + +@item +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. + +@item +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. + +@item +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.'' + +@item +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. + +@item +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. + +@item +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. + +@item +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. + +@item +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 +@uref{https://www.gnu.org/licenses/}. + +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. + +@item +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. + +@end enumerate + +@page +@heading 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: + +@smallexample +@group + Copyright (C) @var{year} @var{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 group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.''@: line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +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. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff --git a/old_ada/doc/docstyle.texi b/old_ada/doc/docstyle.texi new file mode 100644 index 0000000..e740439 --- /dev/null +++ b/old_ada/doc/docstyle.texi @@ -0,0 +1,19 @@ +@c Emacs documentation style settings +@documentencoding UTF-8 +@c These two require Texinfo 5.0 or later, so we use the older +@c equivalent @set variables supported in 4.11 and hence +@ignore +@codequotebacktick on +@codequoteundirected on +@end ignore +@set txicodequoteundirected +@set txicodequotebacktick +@iftex +@c It turns out TeX sometimes fails to hyphenate, so we help it here +@hyphenation{au-to-mat-i-cal-ly} +@hyphenation{spec-i-fied} +@hyphenation{work-a-round} +@hyphenation{work-a-rounds} +@hyphenation{un-marked} +@hyphenation{dic-tion-ary} +@end iftex |