[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to ada-mode.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to ada-mode.texi |
|
Date: |
Thu, 06 Sep 2007 04:58:23 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:58:23
Index: ada-mode.texi
===================================================================
RCS file: ada-mode.texi
diff -N ada-mode.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ ada-mode.texi 6 Sep 2007 04:58:23 -0000 1.1
@@ -0,0 +1,1410 @@
+\input texinfo @c -*-texinfo-*-
address@hidden ../info/ada-mode
address@hidden Ada Mode
+
address@hidden
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+``GNU GENERAL PUBLIC LICENSE'', 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'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
address@hidden direntry
+
address@hidden
address@hidden 10
address@hidden Mode}
address@hidden 2
address@hidden An Emacs major mode for programming in Ada
address@hidden Ada Mode Version 3.7
address@hidden 2
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden fixme; title page doesn't show up in ada-mode.info; why bother
with
address@hidden it?
+
address@hidden Top, Overview, (dir), (dir)
+
address@hidden
+* 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::
address@hidden menu
+
+
address@hidden Overview, Installation, Top, Top
address@hidden 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
address@hidden, 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.
+
address@hidden Installation, Customization, Overview, Top
address@hidden 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
address@hidden://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 @key{M-x
+ada-mode-version}.
+
+The following files are provided with the Ada mode distribution:
+
address@hidden @bullet
+
address@hidden
address@hidden: The main file for Ada mode, providing indentation,
+formatting of parameter lists, moving through code, comment handling
+and automatic casing.
+
address@hidden
address@hidden: GUI editing of Ada mode project files, using Emacs
+widgets.
+
address@hidden
address@hidden: Ada statement templates.
+
address@hidden
address@hidden: GNAT cross-references, completion of identifiers,
+and compilation. Also provides project files (which are not
+GNAT-specific).
+
address@hidden itemize
+
address@hidden Customization, Compiling Executing, Installation, Top
address@hidden 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
address@hidden
address@hidden GNU Emacs Manual}.
address@hidden iftex
address@hidden
address@hidden GNU Emacs Manual}.
address@hidden ifhtml
address@hidden
address@hidden, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
address@hidden ifinfo
+
+These global Emacs settings are strongly recommended (put them in your
+.emacs):
+
address@hidden
+(global-font-lock-mode t)
+(transient-mark-mode t)
address@hidden example
+
address@hidden(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).
+
address@hidden(transient-mark-mode t)} highlights selected text.
+
+See the Emacs help for each of these variables for more information.
+
address@hidden
+* Non-standard file names::
+* Other compiler::
+* Other customization::
address@hidden menu
+
address@hidden Non-standard file names, Other compiler, Customization,
Customization
address@hidden 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
address@hidden and @samp{.adb}, respectively.
+
+Ada mode uses the file extentions 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
address@hidden@var{unit}_s.ada} and @address@hidden, respectively, you
+can add the following to your @file{.emacs} file:
+
address@hidden
+(ada-add-extensions "_s.ada" "_b.ada")
address@hidden example
+
+You can define additional extensions:
+
address@hidden
+(ada-add-extensions ".ads" "_b.ada")
+(ada-add-extensions ".ads" ".body")
address@hidden 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
address@hidden
+
+Simililarly, if Ada mode is looking for a spec, it will look for
address@hidden 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
address@hidden and @file{ada-xref.el} for examples.
+
address@hidden Other compiler, Other customization, Non-standard file names,
Customization
address@hidden 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.
+
address@hidden Other customization, , Other compiler, Customization
address@hidden Other customization
+
+All user-settable Ada mode variables can be set via the menu
address@hidden | Customize}. Click on the @samp{Help} button there for help
+on using customize.
+
+To modify a specific variable, you can directly call the function
address@hidden; just type @kbd{M-x customize-variable
address@hidden @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:
address@hidden
+(setq variable-name value)
address@hidden example
+
address@hidden Compiling Executing, Project files, Customization, Top
address@hidden 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
address@hidden | Project | Edit}) shows the settings of the various project
+file variables referenced here.
+
address@hidden
+* Compile commands::
+* Compiler errors::
address@hidden menu
+
address@hidden Compile commands, Compiler errors, Compiling Executing,
Compiling Executing
address@hidden 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_unit} project file variable;
+it defaults to the current file if not yet set, but is also set by the
+``set main and build'' command.
+
address@hidden @code
+
address@hidden Check file
+Compiles the current file in syntax check mode, by running
address@hidden 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_unit} only if it has not been set yet.
+
address@hidden Compile file
+Compiles the current file, by running @code{comp_cmd} from the current
+project file.
+
+This does not set @code{main_unit}.
+
address@hidden Set main and Build
+Sets @code{main_unit} to the current file, then executes the Build
+command.
+
address@hidden Show main
+Display @code{main_unit} in the message buffer.
+
address@hidden Build
+Compiles all obsolete units of the current @code{main_unit}, and links
address@hidden, by running @code{make_cmd} from the current project.
+
+This sets @code{main_unit} only if it has not been set yet.
+
address@hidden 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 @key{C-u} before invoking the command.
+
+This command is not available for a cross-compilation toolchain.
+
address@hidden table
+It is important when using these commands to understand how
address@hidden 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 @key{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, @key{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_unit}:
+
address@hidden
address@hidden
+Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+the current file.
+
address@hidden
+Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
address@hidden, and click @key{[save]}
+
address@hidden
+Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main_unit}
+
address@hidden enumerate
+
address@hidden Compiler errors, , Compile commands, Compiling Executing
address@hidden Compiler errors
+
+The @code{Check file}, @code{Compile file}, and @code{Build} commands
+all place compilation errors in a separate buffer named
address@hidden
+
+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
address@hidden 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}.
+
address@hidden Project files, Compiling Examples, Compiling Executing, Top
address@hidden 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 @samp{*.adp} are different than GNAT
+compiler project files @samp{*.gpr}.
+
address@hidden
+* Project File Overview::
+* GUI Editor::
+* Project file variables::
address@hidden menu
+
address@hidden Project File Overview, GUI Editor, Project files, Project files
address@hidden 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 ``='':
address@hidden
+src_dir=/Projects/my_project/src_1
+src_dir=/Projects/my_project/src_2
address@hidden example
+
+Some variables (like @code{src_dir}) are lists; multiple occurances
+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
address@hidden 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:
+
address@hidden @bullet
address@hidden
+If @code{ada-prj-default-project-file} is set, use that.
+
address@hidden
+Otherwise, search for a file in the current directory with
+the same base name as the Ada file, but extension given by
address@hidden (default @code{".adp"}).
+
address@hidden
+If not found, search for @file{*.adp} in the current directory; if
+several are found, prompt the user to select one.
+
address@hidden
+If none are found, use @file{default.adp} in the current directory (even
+if it does not exist).
+
address@hidden 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 @key{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.
+
address@hidden GUI Editor, Project file variables, Project File Overview,
Project files
address@hidden 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.
+
address@hidden Project file variables, , GUI Editor, Project files
address@hidden 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
address@hidden contains @address@hidden@}}, the value of the
address@hidden variable will be substituted when @code{comp_cmd} is
+used.
+
+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.
+
+Here is the list of variables. In the default values, the current
+directory @code{"."} is the project file directory.
+
address@hidden defined in ada-xref-set-default-prj-values; same order here
address@hidden @asis
address@hidden @code{build_dir} [default: @code{"."}]
+The compile commands will be issued in this directory.
+
address@hidden @code{src_dir} [default: @code{"."}]
+A list of directories to search for source files, both for compile
+commands and source navigation.
+
address@hidden @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.
+
address@hidden @code{casing} [default:
@code{("~/.emacs_case_exceptions")}
+List of files containing casing exceptions. See the help on
address@hidden for more info.
address@hidden FIXME: section on case exceptions
+
+Lisp variable: @code{ada-case-exception-file}.
+
address@hidden @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}.
+
address@hidden @code{bind_opt} [default: @code{""}]
+Holds user binder options; used in the default build commands.
+
+Lisp variable: @code{ada-prj-default-bind-opt}.
+
address@hidden @code{link_opt} [default: @code{""}]
+Holds user linker options; used in the default build commands.
+
+Lisp variable: @code{ada-prj-default-link-opt}.
+
address@hidden @code{gnatmake_opt} [default: @code{"-g"}]
+Holds user gnatmake options; used in the default build commands.
+
+If a GNAT project file is used (for example @file{project.gpr}), this
+option should be set to @code{-Pproject.gpr}.
+
+Lisp variable: @code{ada-prj-default-gnatmake-opt}.
+
address@hidden @code{gnatfind_opt} [default: @code{"-rf"}]
+Holds user gnatfind options; used in the default find commands.
+
+Lisp variable: @code{ada-prj-gnatfind-switches}.
+
address@hidden @code{main} [default: current file]
+Specifies the name of the executable file for the project; used in the
+default build commands.
+
address@hidden @code{main_unit} [default: current Ada unit]
+Specifies the name of the main Ada unit for the project; used in the
+default build commands.
+
address@hidden @code{cross_prefix} [default: @code{""}]
+Name of target machine in a cross-compilation environment. Used in
+default compile and build commands.
+
address@hidden @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.
+
address@hidden @code{comp_cmd} [default: @code{"address@hidden@}gnatmake
-u -c address@hidden@} address@hidden@} -cargs address@hidden@}"}]
+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}.
+
address@hidden @code{check_cmd} [default: @code{"address@hidden@}gnatmake
-u -c -gnatc address@hidden@} address@hidden@} -cargs address@hidden@}"}]
+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}
+
address@hidden @code{make_cmd} [default: @code{"address@hidden@}gnatmake
-o address@hidden@} address@hidden@} address@hidden@} -cargs address@hidden@}
-bargs address@hidden@} -largs address@hidden@}"}]
+Command used to build the application.
+
+Lisp variable: @code{ada-prj-default-make-cmd}.
+
address@hidden @code{run_cmd} [default: @code{"./address@hidden@}"}]
+Command used to run the application.
+
address@hidden @code{debug_pre_cmd} [default: @code{"cd address@hidden@}"}]
+Command executed before @code{debug_cmd}.
+
address@hidden @code{debug_cmd} [default: @code{"address@hidden@}gdb
address@hidden@}"}]
+Command used to debug the application
+
+Lisp variable: @code{ada-prj-default-debugger}.
+
address@hidden @code{debug_post_cmd} [default: @code{""}]
+Command executed after @code{debug_cmd}.
+
address@hidden table
+
address@hidden Compiling Examples, Moving Through Ada Code, Project files, Top
address@hidden 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}.
+
address@hidden
+* 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::
address@hidden menu
+
address@hidden No project files, Set compiler options, Compiling Examples,
Compiling Examples
address@hidden No project files
+This example uses no project files.
+
+First, create a directory @file{Example_1}, containing:
+
address@hidden:
+
address@hidden
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
address@hidden example
+
+Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
+compiler error handling.
+
address@hidden:
+
address@hidden
+with Hello_Pkg;
+procedure Hello_2
+is begin
+ Hello_Pkg.Say_Hello;
+end Hello_2;
address@hidden example
+
address@hidden:
+
address@hidden
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
address@hidden example
+
address@hidden:
+
address@hidden
+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;
address@hidden example
+
+Yes, this is missing the keyword @code{body}; another compiler error
+example.
+
+In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
+get a @code{*compilation*} buffer containing something like (the
+directory paths will be different):
+
address@hidden
+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
address@hidden example
+
+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 @key{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
+
address@hidden
+ Ada.Text_IO.Put_Line ("hello from hello.adb"):
address@hidden example
+
+Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit:
hello}.
+
+Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
+prompted to save the file (if you haven't already). Then the
+compilation buffer is displayed again, containing:
+
address@hidden
+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
address@hidden example
+
+The compilation has succeeded without errors; @file{hello.exe} now
+exists in the same directory as @file{hello.adb}.
+
+Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
+containing
+
address@hidden
+Hello from hello.adb
+
+Process run finished
address@hidden example
+
+That completes the first part of this example.
+
+Now we will compile a multi-file project. Open the file
address@hidden, and invoke @key{Ada | Set main and Build}. This
+finds an error in @file{hello_pkg.adb}:
+
address@hidden
+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
address@hidden 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;
address@hidden source search path}, or a GNAT project file; @ref{Use GNAT
+project file}.
+
+Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
+
+Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
+
address@hidden
+package body Hello_Pkg is
address@hidden example
+
+Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
+gnatmake successfully builds @file{hello_2}. This demonstrates that
+Emacs has remembered the main file, in the project variable
address@hidden, and used it for the Build command.
+
+Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
+The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
+
+One final point. If you switch back to buffer @file{hello.adb}, and
+invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
+because @code{main_unit} is still set to @code{hello_2}, as you can
+see when you invoke @key{Ada | Project | Edit}.
+
+There are three ways to change @code{main_unit}:
+
address@hidden
address@hidden
+Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
+the current file.
+
address@hidden
+Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
address@hidden, and click @key{[save]}
+
address@hidden
+Invoke @key{Ada | Project | Load}, and load a project file that specifies
@code{main_unit}
+
address@hidden enumerate
+
address@hidden Set compiler options, Set source search path, No project files,
Compiling Examples
address@hidden 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 @key{File | Close
+(current buffer)}.
+
+In directory @file{Example_2}, create these files:
+
address@hidden:
+
address@hidden
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
address@hidden 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
address@hidden and its argument list.
+
address@hidden:
+
address@hidden
+comp_opt=-gnatyt
address@hidden 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 @key{Ada | Project | Load...}, and
+select @file{Example_2/hello.adp}.
+
+Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
address@hidden
+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
address@hidden example
+
+Compare this to the compiler output in @ref{No project files}; the
+gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
address@hidden -gnaty}, and an additional error is reported in
address@hidden 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}.
+
address@hidden Set source search path, Use GNAT project file, Set compiler
options, Compiling Examples
address@hidden 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:
+
address@hidden:
+
address@hidden
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
address@hidden example
+
address@hidden:
+
address@hidden
+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;
address@hidden 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:
+
address@hidden/hello_3.adb}:
+
address@hidden
+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;
address@hidden example
+
+There are no errors in this file.
+
address@hidden/other.adp}:
+
address@hidden
+src_dir=..
+comp_opt=-I..
address@hidden example
+
+Note that there must be no trailing spaces.
+
+In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_3/Other/other.adp}.
+
+Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
address@hidden
+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
address@hidden 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 @key{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}.
+
address@hidden Use GNAT project file, , Set source search path, Compiling
Examples
address@hidden Use GNAT project file
+
+In this example, we show how to use a GNAT project file.
+
+Create the directory @file{Example_4}, containing:
+
address@hidden:
+
address@hidden
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
address@hidden example
+
address@hidden:
+
address@hidden
+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;
address@hidden 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:
+
address@hidden/hello_4.adb}:
+
address@hidden
+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;
address@hidden example
+
+There are no errors in this file.
+
address@hidden/hello_4.adp}:
+
address@hidden
+src_dir=..
+gnatmake_opt=-Phello_4.gpr
address@hidden example
+
address@hidden/hello_4.gpr}:
+
address@hidden
+Project Hello_4 is
+ for Source_Dirs use (".", "..");
+end Hello_4;
address@hidden example
+
+In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
+select @file{Example_4/Gnat_Project/hello_4.adp}.
+
+Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
address@hidden
+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
address@hidden 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}.
+
address@hidden Moving Through Ada Code, Identifier completion, Compiling
Examples, Top
address@hidden Moving Through Ada Code
address@hidden
-----------------------------------------------------------------------
+
+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.
+
address@hidden @kbd
address@hidden M-C-e
address@hidden ada-next-procedure
+Move to the next function/procedure/task, which ever comes next
+(@code{ada-next-procedure}).
address@hidden M-C-a
address@hidden ada-previous-procedure
+Move to previous function/procedure/task
+(@code{ada-previous-procedure}).
address@hidden M-x ada-next-package
address@hidden ada-next-package
+Move to next package.
address@hidden M-x ada-previous-package
address@hidden ada-previous-package
+Move to previous package.
address@hidden C-c C-a
address@hidden 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
address@hidden is @code{nil} (default), otherwise it jumps to
+the subprogram declaration.
address@hidden C-c C-e
address@hidden ada-move-to-end
+Move point to end of current block (@code{ada-move-to-end}).
address@hidden 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.
address@hidden C-c c-d
address@hidden ada-goto-declaration
+Move from any reference to its declaration, for from a declaration to
+its body (for procedures, tasks, private and incomplete types).
address@hidden C-c C-r
address@hidden ada-find-references
+Runs the @file{gnatfind} command to search for all references to the
+identifier surrounding point (@code{ada-find-references}). Use
address@hidden `} (@code{next-error}) to visit each reference (as for
+compilation errors).
address@hidden table
+
+If the @code{ada-xref-create-ali} variable is address@hidden, Emacs
+will try to run GNAT for you whenever cross-reference information is
+needed, and is older than the current source file.
+
address@hidden Identifier completion, Automatic Smart Indentation, Moving
Through Ada Code, Top
address@hidden 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:
+
address@hidden
+You type: address@hidden/}
+Emacs inserts: @samp{my_identifier}
+If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
address@hidden
+Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
address@hidden example
+
+This is a very fast way to do completion, and the casing of words will
+also be respected.
+
+The second method (@key{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.
+
address@hidden @kbd
address@hidden address@hidden
address@hidden ada-complete-identifier
+Complete current identifier using cross-reference information.
address@hidden M-/
+Complete identifier using buffer information (not Ada-specific).
address@hidden table
+
address@hidden Automatic Smart Indentation, Formatting Parameter Lists,
Identifier completion, Top
address@hidden 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:
+
address@hidden @asis
address@hidden @code{ada-broken-indent} (default value: 2)
+Number of columns to indent the continuation of a broken line.
+
address@hidden @code{ada-indent} (default value: 3)
+Number of columns for default indentation.
+
address@hidden @code{ada-indent-record-rel-type} (default value: 3)
+Indentation for @code{record} relative to @code{type} or @code{use}.
+
address@hidden @code{ada-indent-return} (default value: 0)
+Indentation for @code{return} relative to @code{function} (if
address@hidden 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}.
+
address@hidden @code{ada-label-indent} (default value: -4)
+Number of columns to indent a label.
+
address@hidden @code{ada-stmt-end-indent} (default value: 0)
+Number of columns to indent a statement @code{end} keyword on a separate line.
+
address@hidden @code{ada-when-indent} (default value: 3)
+Indentation for @code{when} relative to @code{exception} or @code{case}.
+
address@hidden @code{ada-indent-is-separate} (default value: t)
address@hidden means indent @code{is separate} or @code{is abstract} if on a
single line.
+
address@hidden @code{ada-indent-to-open-paren} (default value: t)
address@hidden means indent according to the innermost open parenthesis.
+
address@hidden @code{ada-indent-after-return} (default value: t)
address@hidden means that the current line will also be re-indented
+before inserting a newline, when you press @key{RET}.
address@hidden 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:
+
address@hidden @bullet
address@hidden
+Reindent the current line, as @key{TAB} would do.
address@hidden
+Temporarily move the cursor to a reference line, i.e., the line that
+was used to calculate the current indentation.
address@hidden
+Display in the message window the name of the variable that provided
+the offset for the indentation.
address@hidden 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.
+
address@hidden @kbd
address@hidden @key{TAB}
+Indent the current line or the current region.
address@hidden C-M-\
+Indent lines in the current region.
address@hidden C-c @key{TAB}
+Indent the current line and display the name of the variable used for
+indentation.
address@hidden table
+
address@hidden Formatting Parameter Lists, Automatic Casing, Automatic Smart
Indentation, Top
address@hidden Formatting Parameter Lists
+
address@hidden @kbd
address@hidden C-c C-f
address@hidden ada-format-paramlist
+Format the parameter list (@code{ada-format-paramlist}).
address@hidden table
+
+This aligns the declarations on the colon (@samp{:}) separating
+argument names and argument types, and aligns the @code{in},
address@hidden and @code{in out} keywords.
+
address@hidden Automatic Casing, Statement Templates, Formatting Parameter
Lists, Top
address@hidden 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:
address@hidden, @code{ada-case-attribute} and
address@hidden
+
+All these variables can have one of the following values:
+
address@hidden @code
address@hidden downcase-word
+The word will be lowercase. For instance @code{My_vARIable} is
+converted to @code{my_variable}.
+
address@hidden upcase-word
+The word will be uppercase. For instance @code{My_vARIable} is
+converted to @code{MY_VARIABLE}.
+
address@hidden 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}.
+
address@hidden 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}.
address@hidden table
+
+Ada mode allows you to define exceptions to these rules, in a file
+specified by the variable 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 (@key{*}), it defines the casing
+af a word fragemnt (or ``substring''); part of a word between two
+underscores or word boundary.
+
+For example:
+
address@hidden
+DOD Department of Defense
+*IO
+GNAT The GNAT compiler from Ada Core Technologies
address@hidden example
+
+The word fragment @code{*IO} applies to any word containing ``_io'';
address@hidden, @code{Hardware_IO}, etc.
+
address@hidden 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.
+
address@hidden @kbd
address@hidden C-c C-b
address@hidden ada-adjust-case-buffer
+Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
address@hidden C-c C-y
+Create a new entry in the exception dictionary, with the word under
+the cursor (@code{ada-create-case-exception})
address@hidden C-c C-t
address@hidden ada-case-read-exceptions
+Rereads the exception dictionary from the file
address@hidden (@code{ada-case-read-exceptions}).
address@hidden table
+
address@hidden Statement Templates, Comment Handling, Automatic Casing, Top
address@hidden 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:
+
address@hidden @kbd
address@hidden C-c t b
address@hidden ada-exception-block
+exception Block (@code{ada-exception-block}).
address@hidden C-c t c
address@hidden ada-case
+case (@code{ada-case}).
address@hidden C-c t d
address@hidden ada-declare-block
+declare Block (@code{ada-declare-block}).
address@hidden C-c t e
address@hidden ada-else
+else (@code{ada-else}).
address@hidden C-c t f
address@hidden ada-for-loop
+for Loop (@code{ada-for-loop}).
address@hidden C-c t h
address@hidden ada-header
+Header (@code{ada-header}).
address@hidden C-c t i
address@hidden ada-if
+if (@code{ada-if}).
address@hidden C-c t k
address@hidden ada-package-body
+package Body (@code{ada-package-body}).
address@hidden C-c t l
address@hidden ada-loop
+loop (@code{ada-loop}).
address@hidden C-c p
address@hidden ada-subprogram-body
+subprogram body (@code{ada-subprogram-body}).
address@hidden C-c t t
address@hidden ada-task-body
+task Body (@code{ada-task-body}).
address@hidden C-c t w
address@hidden ada-while
+while Loop (@code{ada-while}).
address@hidden C-c t u
address@hidden ada-use
+use (@code{ada-use}).
address@hidden C-c t x
address@hidden ada-exit
+exit (@code{ada-exit}).
address@hidden C-c t C-a
address@hidden ada-array
+array (@code{ada-array}).
address@hidden C-c t C-e
address@hidden ada-elsif
+elsif (@code{ada-elsif}).
address@hidden C-c t C-f
address@hidden ada-function-spec
+function Spec (@code{ada-function-spec}).
address@hidden C-c t C-k
address@hidden ada-package-spec
+package Spec (@code{ada-package-spec}).
address@hidden C-c t C-p
address@hidden ada-procedure-spec
+procedure Spec (@code{ada-package-spec}.
address@hidden C-c t C-r
address@hidden ada-record
+record (@code{ada-record}).
address@hidden C-c t C-s
address@hidden ada-subtype
+subtype (@code{ada-subtype}).
address@hidden C-c t C-t
address@hidden ada-task-spec
+task Spec (@code{ada-task-spec}).
address@hidden C-c t C-u
address@hidden ada-with
+with (@code{ada-with}).
address@hidden C-c t C-v
address@hidden ada-private
+private (@code{ada-private}).
address@hidden C-c t C-w
address@hidden ada-when
+when (@code{ada-when}).
address@hidden C-c t C-x
address@hidden ada-exception
+exception (@code{ada-exception}).
address@hidden C-c t C-y
address@hidden ada-type
+type (@code{ada-type}).
address@hidden table
+
address@hidden Comment Handling, GNU Free Documentation License, Statement
Templates, Top
address@hidden Comment Handling
+
+By default, comment lines get indented like Ada code. There are a few
+additional functions to handle comments:
+
address@hidden @kbd
address@hidden M-;
+Start a comment in default column.
address@hidden M-j
+Continue comment on next line.
address@hidden C-c ;
+Comment the selected region (add -- at the beginning of lines).
address@hidden C-c :
+Uncomment the selected region
address@hidden M-q
+autofill the current comment.
address@hidden table
+
address@hidden GNU Free Documentation License, Index, Comment Handling, Top
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Index, , GNU Free Documentation License, Top
address@hidden Index
+
address@hidden fn
+
address@hidden
address@hidden
+
address@hidden
+ arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
address@hidden ignore