Merge commit '0cda39255827f283e7578cd469ae42daad9556a2' from js2-mode

[gnu-emacs-elpa] / packages / ada-mode / ada-mode.texi

\input texinfo  @c -*-texinfo-*-
@setfilename ../../info/ada-mode
@settitle Ada Mode

@copying
Copyright @copyright{} 1999 - 2015  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.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying

@dircategory Emacs editing modes
@direntry
* Ada mode: (ada-mode).         Emacs mode for editing and navigating Ada code.
@end direntry

@titlepage
@sp 10
@title Ada Mode Version 5.1.9
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@node Top, Overview, (dir), (dir)

Ada Mode Version 5.1.9

@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
* Moving Through Ada Code::     Moving easily through Ada sources
* Identifier completion::       Finishing words automatically
* Indentation::                 Indenting your code automatically as you type
* Statement skeletons::         Some code is written for you
* Aligning code::               Making it pretty
* Automatic casing::            Adjusting the case of words automatically
* Comment Handling::            Reformatting comments easily
* Key summary::
* Developer overview::
* GNU Free Documentation License::
* Index::
@end menu

@node Overview, Installation, Top, Top
@chapter Overview

The Emacs mode for programming in Ada helps the user in reading
existing code and facilitates developing new code.

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 file
naming convention or compiler; @xref{Non-standard file names},
@xref{Other compiler}.

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 the GNAT
tools.

@xref{Debuggers,,Debuggers,emacs,Emacs User Guide}, for general
information on debugging.

@node Installation, Customization, Overview, Top
@chapter Installation

Ada mode requires Emacs 24.2 or greater.

Ada mode is distributed in the Gnu ELPA package archive; it can be
installed via @code{M-x list-packages} (@pxref{Packages,,,emacs,Emacs
User Guide}). You must first enable packages in your @file{~/.emacs},
@emph{after} customizing @code{Info-default-directory-list} (if you do
that):

@example
(package-initialize)
@end example

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}.

For installing the separate distribution, see the @file{README} file
in the distribution.

To see what version of Ada mode you have installed, invoke @kbd{M-x
ada-mode-version}.

You may also want to install additional utilities:

@menu
* Ada Reference Manual::
* gpr_query::
* Upgrading::
@end menu

@node Ada Reference Manual, gpr_query, Installation, Installation
@section Ada Reference Manual
The ELPA package ada-ref-man includes the Ada Reference Manual and
Annotated Ada Reference Manual in info format.

@node gpr_query, Upgrading, Ada Reference Manual, Installation
@section gpr_query
Ada mode has support for an external cross reference
tool @code{gpr_query}, which supports Ada, C, C++, and any other
language for which AdaCore gcc provides the @code{-fdump-xref}
(@code{-fdump-xref} is an AdaCore extension).

@c FIXME: list xref features supported by gpr_query but not gnatfind
@c at least:
@c C and C++ source code
@c ada-xref-overriding-function
@c ada-xref-overridden-function

@code{gpr_query} requires the @code{gnatcoll} library provided by
AdaCore, distributed with GNAT GPL 2014.

To build @code{gpr_query}, assuming GNAT GPL 2014 is installed in
@file{/usr/gnat-gpl-2014}, and @file{/usr/gnat-gpl-2014/bin} is in
PATH (if you are running Windows, use Cygwin bash to run these
commands, with GNAT GPL bin first in PATH) (note that
gnatcoll-gpl-2014-src.tar.gz unzips to gnatcoll-1.7w-src):

@example
tar xf ~/Downloads/gnatcoll-gpl-2014-src.tar.gz
cd gnatcoll-1.7w-src
./configure --prefix=/usr/gnat-gpl-2014
@c on cygwin, finds cygwin as build type; not a problem
@c make Gnatcoll_Build=Debug
@c sudo make Gnatcoll_Build=Debug install
make
sudo make install
cd ~/.emacs.d/elpa/ada-mode-5.xx/build
make install
@end example

To build an sqlite3 executable that is compatible with the database
created by @code{gpr_query}:

@example
cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
@end example

@node Upgrading,  , gpr_query, Installation
@section Upgrading from previous versions

See the file NEWS for more details; here we summarize only important
user interface changes.

@table @samp
@item from 5.0.1
    Nothing to do.

@item from 4.01
There are many user interface and API changes between 4.01 and 5.0.1;
we only document those that may be hard to diagnose here.

@code{prog-mode-hook} is no longer run by @code{ada-mode};
@code{ada-mode} is no longer derived from @code{prog-mode}. Use
@code{ada-mode-hook} instead.


@end table

@node Customization, Compiling Executing, Installation, Top
@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 (@kbd{C-h t}).

@menu
* Non-standard file names::
* Other compiler::
* Other cross-reference::
* Other customization::
@end menu

@node Non-standard file names, Other compiler, Customization, Customization
@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.

Emacs uses the file extension to enable Ada mode; Ada mode uses the
file extentions to allow moving from a package body to the
corresponding spec and back.

Emacs and Ada mode support ways to use alternative file extensions for
specs and bodies. Note that you must also tell the compiler about
these extensions; doing that is beyond the scope of this manual.

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
;; Tell Ada mode about spec and body extensions
(ada-add-extensions "_s.ada" "_b.ada")

;; Tell Emacs to use Ada mode for those extensions
(add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
@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}.

Simililarly, if Ada mode is looking for a spec, it will look for
@file{.ads} or @file{_s.ada}.

If the filename excluding the extension is not derived from the Ada
name following the GNAT convention, you need to provide an alternate
function for @code{ada-file-name-from-ada-name}. Doing that is beyond
the scope of this manual; see the current definitions in
@file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.

@node Other compiler, Other cross-reference, Non-standard file names, Customization
@section Other compiler
The project variable @code{ada_compiler} (default elisp variable
@code{ada-compiler}) is used to index several variables that point to
the compiler-specific functions for corresponding Ada mode operations.

To use a compiler other than GNAT, you must write Emacs lisp code that
provides the interface to the compiler, and set @code{ada-compiler} and
the indirection variables.

See @file{ada-gnat-compile.el} for an example.

@node Other cross-reference, Other customization, Other compiler, Customization
@section Other cross-reference
The project variable @code{ada_xref} (default elisp variable
@code{ada-xref-tool}) is used to index several variables that point to
the cross-reference-tool-specific functions for corresponding Ada mode
operations.

The default cross-reference tool is @file{gnatxref}, provided by the
file @file{ada-gnat-xref.el}. One other tool is supported:
@file{gpr_query}. To use it, add the following to @file{~/.emacs}:

@example
(require 'gpr-query)
@end example

To use @file{gpr_query}, the Ada code @file{gpr_query.adb} must be
compiled; see @ref{Installation}. In addition, non-Ada code must be
compiled with the AdaCore gcc extension @code{-fdump-xref}.

To use a cross reference tool other than the above, you must write
Emacs lisp code that provides the interface to the compiler, and set
@code{ada-xref-tool} and the indirection variables.

See @file{ada-gnat-xref.el} and @file{gpr-query.el} for examples.

@node Other customization,  , Other cross-reference, 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

Some general Emacs settings that are useful for Ada files:
@table @code
@item delete-trailing-whitespace
Deletes space, tab at end of line and blank lines at end of buffer.
@item untabify
Deletes tab characters that have crept into the file.
@item indent-tabs-mode
Don't insert tab characters when indenting.
@item copyright-update
Updates the copyright date in the file header comment, to the current
year.
@item electric-pair-mode
Insert a matching right paren when you type a left paren.
@item hippie-expand
Bind @code{hippie-expand} to a key; it expands the word before point, using
words from current buffer, other buffers, file names, etc; see
@code{hippie-expand-try-functions-list}. You can also add
@code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
(@pxref{Statement skeletons}).
@item imenu
Navigate to subprograms and types by name, from a minibuffer menu.
@item speedbar
Navigate to subprograms and types by name, from a list in a dedicated window.
@item which-func
@item jit-lock-defer-time
In large files, parsing is slow, so it gets in the way of
interactive typing due to immediate font-lock triggering a
parse. Delay the font-lock by setting an Emacs file-local variable
in an Ada comment:

@example
--  Local Variables:
--  jit-lock-defer-time: 0.5
--  End:
@end example

@end table

The above can all be set by the following code in your
@file{~/.emacs}. Note that some are functions are added to
@code{before-save-hook}; they run just before a buffer is written to
disk. Also, the order is important; ada-mode does not set up the
Ada-specific features of imenu and speedbar unless imenu is loaded
first.

@example
(setq-default indent-tabs-mode nil)
(electric-pair-mode 1)
(require 'imenu) ;; also enables speedbar
(require 'ada-mode)
(add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
(define-key ada-mode-map "\C-e"     'hippie-expand)
(add-hook 'ada-mode-hook
   (lambda ()
    (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
    (add-hook 'before-save-hook 'copyright-update nil t)
    (add-hook 'before-save-hook
              (lambda () (untabify (point-min) (point-max)))
               nil t)))
@end example

@node Compiling Executing, Project files, Customization, Top
@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).

For complex projects, you will want to use @code{make} or some other
build tool; in that case, you will need an Emacs Ada mode project file
to tell Emacs about the project directory tree and other settings.

@menu
* Compile commands::
* Compiling Examples::
* Compiler errors::
@end menu

@node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
@section Compile commands

Here are the commands for building an Ada project and running the main
program.

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 Compiling Examples, Compiler errors, Compile commands, Compiling Executing
@section 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::
* Use a Makefile::
@end menu

@node No project files, Set compiler options, Compiling Examples, Compiling Examples
@subsection 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} has no errors:

@example
with Hello_Pkg;
procedure Hello_2
is begin
   Hello_Pkg.Say_Hello;
end Hello_2;
@end example

@file{hello_pkg.ads} has no errors:

@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

Yes, this is missing the keyword @code{body}; another compiler error
example. However, note that the indentation engine parser accepts this
code with no errors, making it easier to indent slightly illegal Ada
code.

In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
Check syntax}. You should get a @code{*compilation*} buffer containing
something like (the directory paths will be different):

@example
-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
Compilation started at Fri Oct 18 04:23:54

gnatmake -u -c -gnatc  c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
gcc -c -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/ -gnatc -I- c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb
hello.adb:4:04: "Put_Line" is not visible
hello.adb:4:04: non-visible declaration at a-textio.ads:263
hello.adb:4:04: non-visible declaration at a-textio.ads:259
gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error

Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
@end example

The lines with actual errors (starting with @file{hello.adb}) are
highlighted, with the file name in red.

Now invoke @samp{Ada | Build | Next compilation error}.  Or you can
click the middle mouse button on the first error line, or use the key
binding shown on the menu.  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, invoke @samp{Ada | Build | Fix compilation error};
this adds ``Ada.Text_Io.'' to the line:

@example
    Ada.Text_Io.Put_Line ("hello from hello.adb");
@end example

Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.

Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
prompted to save the file (if you haven't already). Then the
compilation buffer is displayed again, containing:

@example
-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
Compilation started at Fri Oct 18 20:39:33

gnatmake -o hello hello  -cargs  -bargs  -largs
gcc -c hello.adb
gnatbind -x hello.ali
gnatlink hello.ali -o hello.exe

Compilation finished at Fri Oct 18 20:39:34
@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 | Build | Run}. The @file{*compilation*} buffer
is displayed, containing

@example
-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
Compilation started at Fri Oct 18 20:41:53

./hello
Hello from hello.adb

Compilation finished at Fri Oct 18 20:41:53
@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}, invoke @samp{Ada | Build | Set main and
Build}. This finds an error in @file{hello_pkg.adb}:

@example
hello_pkg.adb:2:08: keyword "body" expected here [see file name]
@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 or a GNAT project file
to specify the other directories; @xref{Set source search path},
@ref{Use GNAT project file}.

Invoke @samp{Ada | Build | 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 |
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 | Build
| Run}.  The @code{*compilation*} buffer displays @code{Hello from
hello_pkg.adb}.

One final point. If you switch back to buffer @file{hello.adb}, and
invoke @samp{Ada | Build | 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 | Build | Show main}.

There are two ways to change @code{main}:

@enumerate
@item
Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
the current file.

@item
Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
specifies @code{main}.

@end enumerate

@node Set compiler options, Set source search path, No project files, Compiling Examples
@subsection 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 | Build | Set main and
Build}. This finds the project file @file{hello.adp}, uses it to set
the compiler options, and builds the project. You should get a
@code{*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} 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, Use GNAT project file, Set compiler options, Compiling Examples
@subsection Set source search path

In this example, we show how to deal with files in more than one
directory, using an Emacs Ada mode project file to set the search
path.

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=..
@end example

Note that there must be no trailing spaces.

In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
set project...}, and select @file{Example_3/Other/other.adp}. This
tells Emacs Ada mode to stop using the project file from
@file{Example_2}, and use the one for @file{Example_3}. Also note that
since this project file is not named @file{hello_3.adp}, it would not
be found by default.

Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
Build}. You should get a @code{*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, Use multiple GNAT project files, Set source search path, Compiling Examples
@subsection 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 @code{*compilation*} buffer containing
something like (the directory paths will be different):

@example
-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
Compilation started at Mon Oct 21 11:28:31

gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/hello_4.gpr -o hello_4 hello_4  -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude  -bargs  -largs
gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
hello_pkg.adb:2:08: keyword "body" expected here [see file name]
gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error

Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
@end example

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, Use a Makefile, Use GNAT project file, Compiling Examples
@subsection 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 | Find and
select project...}, and select @file{Example_5/hello_5.adp}. This
would also be found by default if no previous project file had been
selected.

Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
and Build}. You should get a @code{*compilation*} buffer containing
something like (the directory paths will be different):

@example
-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
Compilation started at Mon Oct 21 11:32:05

gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/hello_5.gpr -o hello_5 hello_5  -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude  -bargs  -largs
gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
hello_pkg.adb:2:08: keyword "body" expected here [see file name]
gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error

Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
@end example

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 Use a Makefile,  , Use multiple GNAT project files, Compiling Examples
@subsection Use a Makefile

In this example, we show how to use a Makefile to build an Ada project
with GNAT, run the result, and clean the build directories.

Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
project file},  @ref{Use multiple GNAT project files}.

In @file{Example_5}, add the file:

@file{Makefile}:

@example
# build and run hello_5 project

all : build run

.PHONY : force

build : force
        gprbuild -Phello_5.gpr hello_5

run :
        ./hello_5

clean :
        gnatclean -r -Phello_5

export GPR_PROJECT_PATH = ../Example_4/Gnat_Project

# Local Variables:
# eval:(ada-parse-prj-file "hello_5.adp")
# eval:(ada-select-prj-file "hello_5.adp")
# End:
@end example

Close and re-open @file{Makefile}; the @samp{Local Variables} section
sets the project file to @file{hello_5.adp} when the @file{Makefile}
is opened. You can also use @key{C-x C-e} to execute the select line
after the @file{Makefile} is opened, to change the project file back
to @file{hello_5.adp}.

In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
default make command. This runs the @samp{all} target, which builds
@file{hello_5} and runs it.

@node Compiler errors,  , Compiling Examples, Compiling Executing
@section Compiler errors

The @code{Check syntax} and @code{Build} commands, or running
@code{make}, place compilation errors in a separate buffer named
@code{*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 also include references to other files. These
references are accessed via @kbd{C-c `}.

@node Project files, Moving Through Ada Code, Compiling Executing, Top
@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.

The default file extension for Ada mode project files is @file{*.adp}
or @file{*.prj}. You can use a different extension by adding it to
@code{ada-prj-file-extensions}, and a different syntax by adding a
parser function to @code{ada-prj-parser-alist}.

Note that Ada mode project files @file{*.adp} are different than GNAT
compiler project files @samp{*.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.

If no Emacs Ada mode project file is specified, some Ada mode
functions are not available.

@menu
* Project file overview::
* Project file variables::
@end menu

@node Project file overview, Project file variables, Project files, Project files
@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
``='' (spaces not allowed):
@example
src_dir=/Projects/my_project/src_1
src_dir=/Projects/my_project/src_2
@end example

Any line that does not have an ``='' is a comment.

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 after the value.

The current project file is given by the lisp variable
@code{ada-prj-default-project-file}, and shown by the menu command
@key{Ada | Project Files | Show project}.

To set the project file, use the menu command @samp{Ada | Set Project
...}, or the elisp functions @code{ada-parse-prj-file,
ada-select-prj-file}. The latter can be added to a Makefile:

@example
# Local Variables:
# eval: (ada-parse-prj-file "ada-mode.prj")
# eval: (ada-select-prj-file ada-mode.prj")
# End:
@end example

You specify either a GNAT project file or an Emacs Ada mode project
file; if the file extension is @code{.gpr}, the file is treated as a
GNAT project file. Extensions given by @code{ada-prj-file-extensions}
(default @file{.adp, .prj}) are treated as an Emacs Ada mode
project file.

After a project file is parsed, you can make it current again with
just @code{ada-select-prj-file}, or by selecting it from the menu.

@node Project file variables,  , Project file overview, Project files
@section Project file variables

To set a project variable that is a list, specify each element of the
list on a separate line in the project file. The value on the last
line is the last element in the list.

A variable name that starts with @code{$} is set as a process
environment variable, for processes launched from Emacs for the
project.

In variable values, process environment variables can be referenced
using the normal @code{$var} syntax.

Most project variables have defaults that can be changed by setting
elisp variables; the table below identifies the elisp variable for each
project variable. Elisp variables corresponding to project variables
that are lists are elisp lists.

In general, project variables are evaluated when referenced in Emacs
Ada mode commands. Relative file paths are expanded relative to the
directory containing the project file.

Ada mode defines some project variables; others are defined by the
compiler.

Here is the list of variables valid for all compilers. In the default
values, the current directory @code{"."} is the directory containing
the project file.

@table @asis
@c These are the names that appear in the .adp file, which are the
@c same as the symbols used with ada-prj-get
@c
@c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
@c defaults defined in ada-mode.el ada-prj-default

@item @code{ada_compiler}   [default: @code{ada-compiler, gnat}]
Ada compiler for this project. It must occur in the project file
before any compiler-specific project variable.

@item @code{auto_case}      [default: @code{ada-auto-case, t}]
Non-nil means automatically change case of preceding word while typing.

@item @code{case_identifier}   [default: @code{ada-case-identifier, ada-mixed-case}]
Function to call to adjust the case of an Ada identifier.

@item @code{case_keyword}   [default: @code{ada-case-keyword, downcase-word}]
Function to call to adjust the case of an Ada keyword.

@item @code{case_strict}    [default: @code{ada-case-strict, t}]
If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.

@item @code{casing}         [default: @code{ada-case-exception-file, nil}]
List of files containing casing exceptions. @xref{Automatic casing}.

@item @code{el_file}        [default: ]
The value is a file name, which is loaded as an elisp file when the
project file is parsed or selected. This allows setting Ada mode indentation
variables, and any arbitrary elisp code used to customize the project.

@item @code{path_sep}       [default: @code{path-separator}]
Separator character used in compiler search paths.

@item @code{src_dir}        [default: @code{"."}]
A list of directories to search for source files.

@item @code{xref_tool}      [default: @code{ada-xref-tool, gnat-xref}]
Cross reference tool for this project.

@end table

The following variables are valid with the GNAT compiler:

@table @asis
@c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
@item @code{ada_project_path}   [default: @code{""}]
@c ada-prj-get 'prj_dir, 'proc_env
A list of directories to search for GNAT project files.

If set, the @code{GPR_PROJECT_PATH} process environment variable is
set to this value in the child process that runs GNAT tools. If not
set, @code{GPR_PROJECT_PATH} in the child process is inherited from
the Emacs process.

If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
environment variable set in the Emacs process correctly for all of
your projects, you do not need to set this project variable.

The project search path can also be set in GNAT aggregate
projects. However, the gnat tools do not make that path available to
Emacs, so you must duplicate it in an Emacs Ada project file.

@item @code{gpr_file}   [default: @code{""}]
The GNAT project file.

If set, the source and project directories specified in the GNAT
project file are appended to @code{src_dir} and
@code{ada_project_path}. This allows specifying Ada source directories
with a GNAT project file, and other source directories with the Emacs
project file.

@item @code{gpr_project_path}   [default: @code{""}]
Same as @code{ada_project_path}.

@c FIXME: add ada-build project vars
@end table

@node Moving Through Ada Code, Identifier completion, Project files, Top
@chapter Moving Through Ada Code

There are several commands to navigate through Ada code. All
these functions are available through the Ada menu and keybindings.

Some of these commands rely on cross reference facilities provided by
the compiler; the standard Emacs Ada mode only supports the GNAT
compiler, but others can be added (@pxref{Other cross-reference}).

@table @kbd
@item C-c C-d
@findex ada-goto-declaration
Move from any use of an identifier to its declaration, for from a declaration to
its body (if there is one).

@item C-c M-d
@findex ada-goto-declaration-parent
Move from a child type declaration to the parent type declaration;
display a list of references if there is more than one parent.

@item C-c C-n
@findex ada-next-statement-keyword
Move to the next keyword in the current statement.

For example, if point is on @samp{if}, move to @samp{then}.

@item C-c C-p
@findex ada-prev-statement-keyword
Move to the previous keyword in the current statement.

For example, if point is on @samp{then}, move to @samp{if}.

@item C-c C-o
@findex ada-find-other-file
Switch between corresponding spec and body. There are several special
cases:

@itemize @bullet
@item
If the region is active, it is assumed to contain an Ada package
name; position point on the corresponding package declaration.

@item
If point is in the start line of a top level child package
declaration (but not package body), or a child subprogram spec or
body, position point on the corresponding parent package
declaration.

@item
If point is in the start line of a top level separate body,
position point on the corresponding separate stub declaration.

@item
If point is in a subprogram declaration or body, position point on the
corresponding body or declaration in the other file.

@item
If point is on a @code{with} clause, position point on the
corresponding declaration.

@end itemize

@item C-c C-r
@findex ada-show-references
Show all references to the identifier surrounding point. Use
@kbd{C-x `} (@code{next-error}) to visit each reference (as for
compilation errors).

@item C-c C-x
@findex ada-show-overriding
Show all declarations that override the primitive procedure at
point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
for compilation errors).

@item C-c M-x
@findex ada-show-overridden
Show the declaration that the declaration at point overrides.

@item C-u SPACE
Jump back to the previous location.

@item Ada | Misc | Refresh cross reference cache
Cross reference information is loaded from the compiler output when
the first cross reference command is issued. If the code is recompiled
after that, the cross reference information is reloaded by invoking
this menu command.

@end table

@node Identifier completion, Indentation, Moving Through Ada Code, Top
@chapter Identifier completion

Emacs provides a general way of completing identifiers: @kbd{M-/}
(bound to @code{dabbrev-expand}). This is an easy way to type faster:
you just have to type the first few letters of an identifier, and then
loop through all the possible completions.

@kbd{M-/} works by parsing all open Ada files for possible
completions.

For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
are the only words starting with @samp{my} in any of the open Ada 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.

@node Indentation, Statement skeletons, Identifier completion, Top
@chapter 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-indent}                  (default value: 3)
Number of columns for default indentation.

@item @code{ada-indent-broken}           (default value: 2)
Number of columns to indent the continuation of a broken line.

@item @code{ada-indent-comment-col-0}  (default value: nil)
If non-nil, comments currently starting in column 0 are left in column
0.  Otherwise, they are indented with previous comments or code.

@item @code{ada-indent-comment-gnat}  (default value: nil)
If non-nil, comments are indented to meet the GNAT style check; one
of:
   @itemize
   @item
   multiple of @code{ada-indent}
   @item
   next non-blank line
   @item
   previous non-blank line
   @end itemize

Otherwise, they are indented with previous comments or code.

@item @code{ada-indent-label}            (default value: -3)
Number of columns to indent a label.

@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-renames}           (default value: 2)
Indentation for @code{renames} relative to the matching subprogram keyword.

If the subprogram has parameters then if @code{ada-indent-renames} is
zero or less the indentation is abs @code{ada-indent-renames} relative
to the open parenthesis; if @code{ada-indent-renames} is one or more
the indentation is relative to the line containing the keyword.

If the subprogram has no parameters then @code{ada-indent-broken} the
indentation is relative to the indentation of the line containing
the keyword.

@item @code{ada-indent-return}           (default value: 0)
Indentation for @code{return} relative to the matching
 @code{function}.

If the function has parameters, then if @code{ada-indent-return} is
zero or less the indentation is abs @code{ada-indent-return} relative
to the open parenthesis; if @code{ada-indent-return} is one or more,
indentation is relative to line containing @code{function}.

If the function has no parameters, @code{ada-indent-broken} is used
relative to line containing @code{function}.

@item @code{ada-indent-use}  (default value: ada-indent-broken)
Indentation for the lines in a @code{use} statement.

@item @code{ada-indent-when}             (default value: 3)
Indentation for @code{when} relative to @code{exception}, @code{case},
or @code{or} in @code{select}.

@item @code{ada-indent-with}             (default value: ada-indent-broken)
Indentation for the lines in a @code{with} context clause.

@end table

The indentation variables are buffer local; the global value may be
overridden in an elisp file invoked by an @code{el_file} Emacs Ada
mode project file statement, or in a file local variable section.

The following keys indent portions of the text:
@table @kbd

@item RET
Insert and indent a new line.

@item TAB
Indent the current line, or the current region.

@item C-c TAB
Indent the current statement or declaration.

@end table

The indentation algorithm relies on a grammar parser to identify the
syntactic role for keywords and other words in the code. If the code
is accepted by the parser, the indentation is done according to the
rules in the indentation engine.

If the code is not accepted (because it is partially complete during
editing), the indentation engine falls back to the trivial algorithm
of indenting each new line the same as the previous line. Once enough
new text has been entered to make the code acceptable to the parser,
the statement or declaration is properly indented.

For example, if you are entering this code:

@example
if A then
   B;
end if;
@end example

when you type @kbd{RET B}, @code{B} is indented to the same column as
@code{if}, because the parser does not find @code{end if;}. Then when
you type the final @code{;} followed by @key{TAB}, all three lines are
indented, putting @code{B} where it belongs.

To be more user friendly, the parser accepts a superset of the Ada
grammer. For example, the parser accepts this code for an @code{if}
statement:

@example
if then
end if;
@end example

In general, any sequence of statements, and many expressions, may be
omitted.

One way to easily insert empty statements like this is using
@ref{Statement skeletons}.

In rare cases, the parser gets confused; it can be reset by invoking
menu @key{Ada | Misc | Reset parser}. Please report such cases as a
bug.

@node Statement skeletons, Aligning code, Indentation, Top
@chapter Statement skeletons

@kbd{C-c C-e} expands the previous one or two words into a statment
skeleton. For example, @kbd{i f C-c C-e} expands to:

@example
if  then
elsif  then
else
end if;
@end example

All skeleton expansions are accepted by the indentation parser, so
this is a convenient way to insert statements with correct
indentation.

For named statements (packages, loops, etc), the name is taken from
the word before point, and the name of the statement from the word
before that.

Some expansions prompt for more information, such as
whether a spec or body is desired. For example, @kbd{package A_Package
C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
selected, the following code is inserted:

@example
package A_Package is
private
end A_Package;
@end example

Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
(without prompting) to:

@example
A_Block:
   declare
   begin
   exception
   end A_Block;
@end example

Note that the order of the keyword @code{declare} and the name
@code{A_Block} are reversed in the expansion; this may take some
getting used to. Alternately, if no name is present in the buffer, you
are prompted for a name: @kbd{declare C-c C-e} first prompts for a
name, then expands to the above.

The variable @code{ada-skel-initial-string} defines what to insert in
a newly created empty buffer. It defaults to @code{@{header@}}, which
is a placeholder defined by @code{ada-skel-header}, which inserts a
typical header with a copyright license (choice of GPL or
restricted). Users will typically want to override the definition of
@code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
provide more choices of copyright license.

@node Aligning code, Automatic casing, Statement skeletons, Top
@chapter Aligning code

Aligning code adds space in each line so that similar parts of
successive lines are aligned vertically. For example, a sequence of
declarations:

@example
A : Integer;
Another : Float := 1.0;
More : Integer := 2;
@end example

changes to this when aligned:

@example
A       : Integer;
Another : Float   := 1.0;
More    : Integer := 2;
@end example

Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
statements surrounding point, or within the selected region.

Parameter lists are also aligned:

@example
   procedure Foo
     (A : in Integer;
      Another : out Float := 1.0;
      More : in out Integer := 2);
@end example

is aligned to:

@example
   procedure Foo
     (A       : in     Integer;
      Another :    out Float   := 1.0;
      More    : in out Integer := 2);
@end example

@node Automatic casing, Comment Handling, Aligning code, Top
@chapter Automatic casing

Casing of identifiers, attributes and keywords is automatically
performed while typing when the variable @code{ada-auto-case} is
non-nil (the default). Every time you type a word separator, the
previous word is automatically cased.

You can customize the automatic casing with the following variables:

@table @code
@item ada-case-keyword
Value must be one of:
@table @code
@item downcase-word
Ada keywords will be lowercase.

@item upcase-word
Ada keywords will be uppercase.
@end table

@item ada-case-strict
If non-nil, all identifiers are forced to @code{Mixed_Case}; first
letter, and letter following ``_'' are uppercase; rest are
lowercase.

If nil, the mixed case characters in identifiers are forced to upper
case, but the other characters are not modified. That allows typing
all uppercase identifiers without defining a casing exception.
@end table

You can define exceptions to these rules, in files specified by the
variable @code{ada-case-exception-file}. Each line in a case exception
file specifies the casing of one word or word fragment. If an
exception is defined in multiple files, the first occurrence is used.

If the word starts with an asterisk (@code{*}), it defines the casing
of a word fragment (or ``substring''); part of a word between two
underscores or word boundary.

For example:

@example
DOD
*IO
GNAT
@end example

The word fragment @code{*IO} applies to any word containing ``_io'';
@code{Text_IO}, @code{Hardware_IO}, etc.

@findex ada-case-create-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 | Casing | Create full
exception} or @samp{Ada | Casing | Create partial exception}.  The
word will be added to the current list of exceptions and to the file.

It is sometimes useful to have multiple exception files. For
example, 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. When you create a new exception, you are prompted for the
file to save it in.

Other keys and menu entries are defined:

@table @kbd
@item C-c C-w
@findex ada-case-adjust-at-point
Adjust case of the word at point. With prefix arg, adjust case even if
in comment. Normally, comments are not affected by case adjust.

@item Ada | Casing | Adjust case region
Adjust case in the active region.

@item Ada | Casing | Adjust case buffer
Adjust case in the active buffer.

@end table

@node Comment Handling, Key summary, Automatic casing, Top
@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-;
@findex comment-dwim
If the region is active, comment or uncomment it.

If the current line is empty, start a comment.

Otherwise, add a comment at the end of the line, in a column given by
@code{comment-column}.

@item M-q
@findex fill-paragraph
Fill the current comment paragraph.
@end table

@node Key summary, Developer overview, Comment Handling, Top
@chapter Key summary
@c search for @kbd and @key. Alphabetical by key sequence

This table summarizes the keys described in this manual. Other keys
are bound by Ada mode; see @key{C-h b} for a complete list. The
Ada menu also displays keys bound to menu operations.

@table @kbd
@item M-/
@xref{Identifier completion}.
Complete the word before point; repeat to cycle thru possible
completions.

@item M-;
@xref{Comment Handling}.
If the region is active, comment or uncomment it.

@item M-q
@xref{Comment Handling}.
Fill the current comment paragraph.

@item RET
@xref{Indentation}.
Insert and indent a new line.

@item TAB
@xref{Indentation}.
Indent the current line, or the current region.

@item C-c TAB
@xref{Indentation}.
Indent the current statement or declaration.

@item C-c `
@xref{Compiler errors}.
Move to the location of the secondary reference in the current compilation error.

@item C-c C-a
@xref{Aligning code}.
Align code.

@item C-c C-c
@xref{Compile commands}.
Build the current main program.

@item C-c C-d
@xref{Moving Through Ada Code}.
Move from any use of an identifier to its declaration, for from a declaration to its body.

@item C-c M-d
@xref{Moving Through Ada Code}.
Move from a child type declaration to the parent type declaration.

@item C-c C-e
@xref{Statement skeletons}.
Expand previous one or two words into a statement or declaration
skeleton.

@item C-c C-c
@xref{Compile commands}.
Build the current file.

@item C-c C-n
@xref{Moving Through Ada Code}.
Move to the next keyword in the current statement.

@item C-c C-o
@xref{Moving Through Ada Code}.
Switch between corresponding spec and body, or find other spec.

@item C-c C-p
@xref{Moving Through Ada Code}.
Move to the previous keyword in the current statement.

@item C-c C-r
@xref{Moving Through Ada Code}.
Show all references to the identifier surrounding point.

@item C-c C-w
@xref{Automatic casing}.
Adjust case of the word at point. With prefix arg, adjust case even if
in comment.

@item C-c C-x
@xref{Moving Through Ada Code}.
Show all declarations that override the primitive procedure at
point.

@item C-c C-y
@xref{Automatic casing}.
Create case exception.

@item C-c `
@xref{Compiler errors}.
Move to the location of the next secondary compilation error.

@item C-x `
@xref{Compiler errors}.
Move to the location of the next compilation error or show result.

@item M-q
@xref{Comment Handling}.
Fill the current comment paragraph.

@end table

@node Developer overview, GNU Free Documentation License, Key summary, Top
@chapter Developer overview
If you'd like to contribute to Ada mode, or just understand the
sources, here's an overview.

@menu
* Directory structure::
* Package organization::
* OpenToken::
* ELPA::
@end menu

@node Directory structure, Package organization, Developer overview, Developer overview
@section Directory structure
@table @file
@item org.emacs.ada-mode
Main source.

File extensions:
@table @file
@item *.el
Elisp files; main code.

@item *.elc
Byte-compiled elisp files, not in the distribution. Generated by the
Makefile target @code{byte-compile}, or by the Emacs package installer.

Compiling the parse tables (@file{*-wy.el}) speeds up loading them
significantly. Compiling other files speeds up parsing, but not
noticeably.

One reason to byte-compile files is to find errors; the byte compiler
reports undefined variables, wrong argument counts, etc.

@item *-wy.el
Parse tables, generated from the corresponding grammar @file{*.wy} by
the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
distribution and the monotone repository so users and Elisp developers
don't have to install OpenToken.

@item *-wy.output
Diagnostic output from @file{wisi-generate.exe}, useful for tracing
parses while debugging a grammar issue. Not in the tarball
distribution or the monotone repository.

@item *.wy
Grammar files, specifying the language to be parsed. The syntax for
these grammar files is similar to that for bison and wisent, but not
the same; see the OpenToken documentation for more info.

The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
parser, so it tolerates some conflicts and ambiguities. This makes the
grammars easier to write, and in particular makes it possible to let
the Ada grammar closely match Annex P of the Ada Language Reference
Manual (the syntax summary).

@item *.texi
Texinfo source for the user guides.

@item *.html
Generated user guide in HTML format.

@item *.info
Generated user guide in Emacs info format.


@end table

@item build
Makefile for building the user guides, publishing to the web page or
Gnu ELPA. Test drivers.

@item build/wisi
Makefile for building and testing with the wisi-based
parser. Separate from @file{build}, because there used to be a
SMIE-based parser, and there might be another parser someday.

The emacs used to byte-compile and run tests is given by the 'make'
variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
the make command line or by an environment variable.

@item test
All tests for Ada mode, gpr mode, parser.

Each test is run in a separate invocation of Emacs, so it is
completely independent of all other tests.

The tests are driven by the elisp code in @file{build/*.el}.

In general, the Ada mode tests open the file, execute test actions,
re-indent, and re-captialize the entire file. The result is diffed
with the original, and must match.

The test actions are defined by comments with the prefix
@code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
functions. This is used to test navigation features and other parser
effects.

@item test/Example_*
Starting files for examples in user guide.

@item test/gpr
Tests for gpr mode.

@item test/subdir
More tests; allows testing path search features.

@item test/wisi
Tests of the elisp wisi grammar compiler and parser.
@end table

@node Package organization, OpenToken, Directory structure, Developer overview
@section Package organization

@menu
* Ada mode::
* gpr mode::
* GNAT core::
* Wisi::
@end menu

@node Ada mode, gpr mode, Package organization, Package organization
@subsection Ada mode
Ada mode consists of all files with @file{ada-} prefix in the file
name.

@table @file
@item ada-mode.el
The main file, implementing the keymap, menu, and top level
functionality.

It allows for different backend implementations for compiling,
cross-referencing, and indenting. The functions for each of these
backends dispatch thru global variables that are set by Emacs Ada mode
project files. They default to the GNAT compiler, the gnatxref cross
reference tool, and the ada-wisi indentation engine.

@item ada-build.el
Provides functions for compiling Ada files without a Makefile (or
similar tool).

@item ada-fix-error.el
Provides an interface to utilities for automatically fixing errors
reported by the compiler. It dispatches to a compiler-specific
backend.

@item ada-gnat-compile.el
Implements the Ada mode compiler functions for the GNAT compiler.

@item ada-gnat-xref.el
Implements the Ada mode cross reference functions for the GNAT compiler.

@item ada-grammar.*
The Ada language grammar, and files generated from it by the OpenToken
tool @file{wisi-generate.exe}.

@item ada-indent-user-options.el
All user-settable options for the Ada indentation engine.

@item ada-mode-compat-23.4.el
Defines functions used by Ada mode that are not in Emacs 23.4.

Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
partially supported. Earlier versions of Emacs are not supported.

@item ada-mode.texi
The Ada mode user guide source and compiled versions.

@item ada-skel.el
Skeletons for expansion of Ada syntax (@pxref{Statement
skeletons}). Extends the Emacs skeleton functions with ``tokens'',
inspired by the lamented Else package (which was inspired by DEC LSE).

@item ada-wisi-opentoken.el
Indentation functions useful when editing OpenToken code; an example
of extending the Ada mode indentation engine for special
circumstances.

@item ada-wisi.el
Implements the Ada mode indentation functions for the wisi indentation
engine backend.

@end table

@node gpr mode, GNAT core, Ada mode, Package organization
@subsection gpr mode

gpr mode consists of all files with @file{gpr-} prefix in the file
name. The functions in each file are similar to the similarly-named
Ada mode files.

@node GNAT core, Wisi, gpr mode, Package organization
@subsection GNAT core
@table @file

@item gnat-core.el
GNAT is actually a multi-language tool; it builds on top of the
multi-language gcc.

@file{gnat-core.el} is a start at a language-agnostic interface to the
GNAT tools. It was first factored out from @file{ada-gnat.el} and
@file{ada-mode.el} to support the multi-language @file{gpr_query.el}.

More code currently in @file{ada-mode.el} could be migrated to
@file{gnat-core.el}, in particular the project file support.

@item gpr-query.el
Provides an interface to the external multi-language cross-reference
tool @file{gpr_query}.

Implements the Ada mode cross-reference functions for the
@file{gpr_query} backend, and a minor mode providing similar
functions for C++.

@end table

@node Wisi,  , GNAT core, Package organization
@subsection Wisi

The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
a name.

@table @file
@item wisi.el
Implements the lexer, the main parser driver,
parser actions that cache parser information in text properties,
utilities for indenting and navigating using the cached information,
and general setup.

@item wisi-compile.el
Implements the parse table
compiler. @file{wisi-generate.exe} processes the grammar source
@file{*.wy} into an elisp source representation of a parse table
@file{*-wy.el}. That is compiled into an internal structure containing
the state transitions and executable actions. The actions can be any
elisp form; the intent is that they be calls to the action functions
provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
provided by @code{semantic}.

@item wisi-parse.el
Implements the generalized LALR parser.
@end table

@node OpenToken, ELPA, Package organization, Developer overview
@section OpenToken
Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
the grammar sources into elisp parse tables. See
@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
current information about which version of OpenToken is required, and
how to get it.

The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
build directory for OpenToken; you probably need to override it with
an external environment variable or on the @code{make} command line.

@node ELPA,  , OpenToken, Developer overview
@section ELPA
Ada mode is published via the Gnu ELPA archive. To test a new version
of Ada mode, we use a local Gnu ELPA archive. That requires fetching
Gnu ELPA via git:

@example
cd /Projects
git clone git://git.savannah.gnu.org/emacs/elpa.git
@end example

If you have an Emacs Savannah developer account, you can use:

@example
cd /Projects
git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
@end example

@file{build/Makefile} contains targets for copying Ada mode source to
the elpa workspace, and for building the elpa archive there.

@node GNU Free Documentation License, Index, Developer overview, Top
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index,  , GNU Free Documentation License, Top
@unnumbered Index

@printindex fn

@bye