(Glossary): Explain `iff'.
[emacs.git] / man / ada-mode.texi
blob7acae36c74f62a2d56060379c4540ba69e1acb8b
1 \input texinfo  @c -*-texinfo-*-
2 @setfilename ../info/ada-mode
3 @settitle Ada Mode
5 @copying
6 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
7 2005, 2006, 2007  Free Software Foundation, Inc.
9 @quotation
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.2 or
12 any later version published by the Free Software Foundation; with the
13 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
14 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
15 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
16 license is included in the section entitled ``GNU Free Documentation
17 License'' in the Emacs manual.
19 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
20 this GNU Manual, like GNU software.  Copies published by the Free
21 Software Foundation raise funds for GNU development.''
23 This document is part of a collection distributed under the GNU Free
24 Documentation License.  If you want to distribute this document
25 separately from the collection, you can do so by adding a copy of the
26 license to the document, as described in section 6 of the license.
27 @end quotation
28 @end copying
30 @dircategory Emacs
31 @direntry
32 * Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
33 @end direntry
35 @titlepage
36 @sp 10
37 @title{Ada Mode}
38 @sp 2
39 @subtitle An Emacs major mode for programming in Ada
40 @subtitle Ada Mode Version 3.7
41 @sp 2
42 @page
43 @vskip 0pt plus 1filll
44 @insertcopying
45 @end titlepage
47 @c fixme; title page doesn't show up in ada-mode.info; why bother with
48 @c it?
50 @node Top, Overview, (dir), (dir)
52 @menu
53 * Overview::
54 * Installation::                Installing Ada mode on your system
55 * Customization::               Setting up Ada mode to your taste
56 * Compiling Executing::         Working with your application within Emacs
57 * Project files::               Describing the organization of your project
58 * Compiling Examples::          A small tutorial
59 * Moving Through Ada Code::     Moving easily through Ada sources
60 * Identifier completion::       Finishing words automatically
61 * Automatic Smart Indentation::  Indenting your code automatically as you type
62 * Formatting Parameter Lists::  Formatting subprograms' parameter lists
63                                      automatically
64 * Automatic Casing::            Adjusting the case of words automatically
65 * Statement Templates::         Inserting code templates
66 * Comment Handling::            Reformatting comments easily
67 * Index::
68 @end menu
71 @node Overview, Installation, Top, Top
72 @chapter Overview
74 The Emacs mode for programming in Ada helps the user in understanding
75 existing code and facilitates writing new code.
77 When the Gnu Ada compiler GNAT is used, the cross-reference
78 information output by the compiler is used to provide powerful code
79 navigation (jump to definition, find all uses, etc).
81 When you open a file with a file extension of @file{.ads} or
82 @file{.adb}, Emacs will automatically load and activate Ada mode.
84 Ada mode works without any customization, if you are using the GNAT
85 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
86 naming convention.
88 You must customize a few things if you are using a different compiler
89 or file naming convention; @xref{Other compiler}, @xref{Non-standard
90 file names}.
92 In addition, you may want to customize the indentation,
93 capitalization, and other things; @xref{Other customization}.
95 Finally, for large Ada projects, you will want to set up an Emacs
96 Ada mode project file for each project; @xref{Project files}. Note
97 that these are different from the GNAT project files used by gnatmake
98 and other GNAT commands.
100 See the Emacs info manual, section 'Running Debuggers Under Emacs',
101 for general information on debugging.
103 @node Installation, Customization, Overview, Top
104 @chapter Installation
106 Ada mode is part of the standard Emacs distribution; if you use that,
107 no files need to be installed.
109 Ada mode is also available as a separate distribution, from the Emacs
110 Ada mode website
111 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The
112 separate distribution may be more recent.
114 For installing the separate distribution, see the @file{README} file
115 in the distribution.
117 To see what version of Ada mode you have installed, do @key{M-x
118 ada-mode-version}.
120 The following files are provided with the Ada mode distribution:
122 @itemize @bullet
124 @item
125 @file{ada-mode.el}: The main file for Ada mode, providing indentation,
126 formatting of parameter lists, moving through code, comment handling
127 and automatic casing.
129 @item
130 @file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs
131 widgets.
133 @item
134 @file{ada-stmt.el}: Ada statement templates.
136 @item
137 @file{ada-xref.el}: GNAT cross-references, completion of identifiers,
138 and compilation. Also provides project files (which are not
139 GNAT-specific).
141 @end itemize
143 @node Customization, Compiling Executing, Installation, Top
144 @chapter Customizing Ada mode
146 Here we assume you are familiar with setting variables in Emacs,
147 either thru 'customize' or in elisp (in your @file{.emacs} file). For
148 a basic introduction to customize, elisp, and Emacs in general, see
149 the tutorial in
150 @iftex
151 @cite{The GNU Emacs Manual}.
152 @end iftex
153 @ifhtml
154 @cite{The GNU Emacs Manual}.
155 @end ifhtml
156 @ifinfo
157 @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
158 @end ifinfo
160 These global Emacs settings are strongly recommended (put them in your
161 .emacs):
163 @example
164 (global-font-lock-mode t)
165 (transient-mark-mode t)
166 @end example
168 @samp{(global-font-lock-mode t)} turns on syntax
169 highlighting for all buffers (it is off by default because it may be
170 too slow for some machines).
172 @samp{(transient-mark-mode t)} highlights selected text.
174 See the Emacs help for each of these variables for more information.
176 @menu
177 * Non-standard file names::
178 * Other compiler::
179 * Other customization::
180 @end menu
182 @node Non-standard file names, Other compiler, Customization, Customization
183 @section Non-standard file names
185 By default, Ada mode is configured to use the GNAT file naming
186 convention, where file names are a simple modification of the Ada
187 names, and the extension for specs and bodies are
188 @samp{.ads} and @samp{.adb}, respectively.
190 Ada mode uses the file extentions to allow moving from a package body
191 to the corresponding spec and back.
193 Ada mode supports a list of alternative file extensions for specs and bodies.
195 For instance, if your spec and bodies files are called
196 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
197 can add the following to your @file{.emacs} file:
199 @example
200 (ada-add-extensions "_s.ada" "_b.ada")
201 @end example
203 You can define additional extensions:
205 @example
206 (ada-add-extensions ".ads" "_b.ada")
207 (ada-add-extensions ".ads" ".body")
208 @end example
210 This means that whenever Ada mode looks for the body for a file
211 whose extension is @file{.ads}, it will take the first available file
212 that ends with either @file{.adb}, @file{_b.ada} or
213 @file{.body}.
215 Simililarly, if Ada mode is looking for a spec, it will look for
216 @file{.ads} or @file{_s.ada}.
218 If the filename is not derived from the Ada name following the GNAT
219 convention, things are a little more complicated. You then need to
220 rewrite the function @code{ada-make-filename-from-adaname}. Doing that
221 is beyond the scope of this manual; see the current definitions in
222 @file{ada-mode.el} and @file{ada-xref.el} for examples.
224 @node Other compiler, Other customization, Non-standard file names, Customization
225 @section Other compiler
227 By default, Ada mode is configured to use the Gnu Ada compiler GNAT.
229 To use a different Ada compiler, you must specify the command lines
230 used to run that compiler, either in lisp variables or in Emacs
231 Ada mode project files. See @ref{Project file variables} for the list
232 of project variables, and the corresponding lisp variables.
234 @node Other customization,  , Other compiler, Customization
235 @section Other customization
237 All user-settable Ada mode variables can be set via the menu
238 @samp{Ada | Customize}.  Click on the @samp{Help} button there for help
239 on using customize.
241 To modify a specific variable, you can directly call the function
242 @code{customize-variable}; just type @kbd{M-x customize-variable
243 @key{RET} @var{variable-name} @key{RET}}).
245 Alternately, you can specify variable settings in the Emacs
246 configuration file, @file{.emacs}. This file is coded in Emacs lisp,
247 and the syntax to set a variable is the following:
248 @example
249 (setq variable-name value)
250 @end example
252 @node Compiling Executing, Project files, Customization, Top
253 @chapter Compiling Executing
255 Ada projects can be compiled, linked, and executed using commands on
256 the Ada menu. All of these commands can be customized via a project
257 file (@pxref{Project files}), but the defaults are sufficient for using
258 the GNAT compiler for simple projects (single files, or several files
259 in a single directory).
261 Even when no project file is used, the GUI project editor (menu
262 @key{Ada | Project | Edit}) shows the settings of the various project
263 file variables referenced here.
265 @menu
266 * Compile commands::
267 * Compiler errors::
268 @end menu
270 @node Compile commands, Compiler errors, Compiling Executing, Compiling Executing
271 @section Compile commands
273 Here are the commands for building and using an Ada project, as
274 listed in the Ada menu.
276 In multi-file projects, there must be one file that is the main
277 program. That is given by the @code{main_unit} project file variable;
278 it defaults to the current file if not yet set, but is also set by the
279 ``set main and build'' command.
281 @table @code
283 @item Check file
284 Compiles the current file in syntax check mode, by running
285 @code{check_cmd} defined in the current project file. This typically
286 runs faster than full compile mode, speeding up finding and fixing
287 compilation errors.
289 This sets @code{main_unit} only if it has not been set yet.
291 @item Compile file
292 Compiles the current file, by running @code{comp_cmd} from the current
293 project file.
295 This does not set @code{main_unit}.
297 @item Set main and Build
298 Sets @code{main_unit} to the current file, then executes the Build
299 command.
301 @item Show main
302 Display @code{main_unit} in the message buffer.
304 @item Build
305 Compiles all obsolete units of the current @code{main_unit}, and links
306 @code{main_unit}, by running @code{make_cmd} from the current project.
308 This sets @code{main_unit} only if it has not been set yet.
310 @item Run
311 Executes the main program in a shell, displayed in a separate Emacs
312 buffer. This runs @code{run_cmd} from the current project. The
313 execution buffer allows for interactive input/output.
315 To modify the run command, in particular to provide or change the
316 command line arguments, type @key{C-u} before invoking the command.
318 This command is not available for a cross-compilation toolchain.
320 @end table
321 It is important when using these commands to understand how
322 @code{main_unit} is used and changed.
324 Build runs 'gnatmake' on the main unit. During a typical edit/compile
325 session, this is the only command you need to invoke, which is why it
326 is bound to @key{C-c C-c}. It will compile all files needed by the
327 main unit, and display compilation errors in any of them.
329 Note that Build can be invoked from any Ada buffer; typically you will
330 be fixing errors in files other than the main, but you don't have to
331 switch back to the main to invoke the compiler again.
333 Novices and students typically work on single-file Ada projects. In
334 this case, @key{C-c C-m} will normally be the only command needed; it
335 will build the current file, rather than the last-built main.
337 There are three ways to change @code{main_unit}:
339 @enumerate
340 @item
341 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
342 the current file.
344 @item
345 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
346 @code{main}, and click @key{[save]}
348 @item
349 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
351 @end enumerate
353 @node Compiler errors,  , Compile commands, Compiling Executing
354 @section Compiler errors
356 The @code{Check file}, @code{Compile file}, and @code{Build} commands
357 all place compilation errors in a separate buffer named
358 @code{*compilation*}.
360 Each line in this buffer will become active: you can simply click on
361 it with the middle button of the mouse, or move point to it and press
362 @key{RET}. Emacs will then display the relevant source file and put
363 point on the line and column where the error was found.
365 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
366 will jump to the first error. If you press that key again, it will
367 move you to the second error, and so on.
369 Some error messages might also include references to other files. These
370 references are also clickable in the same way, or put point after the
371 line number and press @key{RET}.
373 @node Project files, Compiling Examples, Compiling Executing, Top
374 @chapter Project files
376 An Emacs Ada mode project file specifies what directories hold sources
377 for your project, and allows you to customize the compilation commands
378 and other things on a per-project basis.
380 Note that Ada mode project files @samp{*.adp} are different than GNAT
381 compiler project files @samp{*.gpr}.
383 @menu
384 * Project File Overview::
385 * GUI Editor::
386 * Project file variables::
387 @end menu
389 @node Project File Overview, GUI Editor, Project files, Project files
390 @section Project File Overview
392 Project files have a simple syntax; they may be edited directly. Each
393 line specifies a project variable name and its value, separated by ``='':
394 @example
395 src_dir=/Projects/my_project/src_1
396 src_dir=/Projects/my_project/src_2
397 @end example
399 Some variables (like @code{src_dir}) are lists; multiple occurances
400 are concatenated.
402 There must be no space between the variable name and ``='', and no
403 trailing spaces.
405 Alternately, a GUI editor for project files is available (@pxref{GUI
406 Editor}). It uses Emacs widgets, similar to Emacs customize.
408 The GUI editor also provides a convenient way to view current project
409 settings, if they have been modified using menu commands rather than
410 by editing the project file.
412 After the first Ada mode build command is invoked, there is always a
413 current project file, given by the lisp variable
414 @code{ada-prj-default-project-file}. Currently, the only way to show
415 the current project file is to invoke the GUI editor.
417 To find the project file the first time, Ada mode uses the following
418 search algorithm:
420 @itemize @bullet
421 @item
422 If @code{ada-prj-default-project-file} is set, use that.
424 @item
425 Otherwise, search for a file in the current directory with
426 the same base name as the Ada file, but extension given by
427 @code{ada-prj-file-extension} (default @code{".adp"}).
429 @item
430 If not found, search for @file{*.adp} in the current directory; if
431 several are found, prompt the user to select one.
433 @item
434 If none are found, use @file{default.adp} in the current directory (even
435 if it does not exist).
437 @end itemize
439 This algorithm always sets @code{ada-prj-default-project-file}, even
440 when the file does not actually exist.
442 To change the project file before or after the first one is found,
443 invoke @key{Ada | Project | Load ...}.
445 Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}.
446 This sets @code{ada-prj-default-project-file}, and reads the project file.
448 @node GUI Editor, Project file variables, Project File Overview, Project files
449 @section GUI Editor
451 The project file editor is invoked with the menu @samp{Ada | Projects
452 | Edit}.
454 Once in the buffer for editing the project file, you can save your
455 modification using the @samp{[save]} button at the bottom of the
456 buffer, or the @kbd{C-x C-s} binding. To cancel your modifications,
457 kill the buffer or click on the @samp{[cancel]} button.
459 @node Project file variables,  , GUI Editor, Project files
460 @section Project file variables
462 The following variables can be defined in a project file; some can
463 also be defined in lisp variables.
465 To set a project variable that is a list, specify each element of the
466 list on a separate line in the project file.
468 Any project variable can be referenced in other project variables,
469 using a shell-like notation. For instance, if the variable
470 @code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the
471 @code{comp_opt} variable will be substituted when @code{comp_cmd} is
472 used.
474 Most project variables have defaults that can be changed by setting
475 lisp variables; the table below identifies the lisp variable for each
476 project variable. Lisp variables corresponding to project variables
477 that are lists are lisp lists.
479 Here is the list of variables. In the default values, the current
480 directory @code{"."} is the project file directory.
482 @c defined in ada-xref-set-default-prj-values; same order here
483 @table @asis
484 @item @code{build_dir}      [default: @code{"."}]
485 The compile commands will be issued in this directory.
487 @item @code{src_dir}        [default: @code{"."}]
488 A list of directories to search for source files, both for compile
489 commands and source navigation.
491 @item @code{obj_dir}        [default: @code{"."}]
492 A list of directories to search for library files. Ada mode searches
493 this list for the @samp{.ali} files generated by GNAT that contain
494 cross-reference information.
496 The compiler commands must place the @samp{.ali} files in one of these
497 directories; the default commands do that.
499 @item @code{casing}         [default: @code{("~/.emacs_case_exceptions")}
500 List of files containing casing exceptions. See the help on
501 @code{ada-case-exception-file} for more info.
502 @c FIXME: section on case exceptions
504 Lisp variable: @code{ada-case-exception-file}.
506 @item @code{comp_opt}       [default: @code{"-gnatq -gnatQ"}]
507 Holds user compiler options; used in the default compile commands. The
508 default value tells gnatmake to generate library files for
509 cross-referencing even when there are errors.
511 If source code for the project is in multiple directories, the
512 appropriate compiler options must be added here. @ref{Set source
513 search path} for examples of this. Alternately, GNAT project files may
514 be used; @ref{Use GNAT project file}.
516 Lisp variable: @code{ada-prj-default-comp-opt}.
518 @item @code{bind_opt}       [default: @code{""}]
519 Holds user binder options; used in the default build commands.
521 Lisp variable: @code{ada-prj-default-bind-opt}.
523 @item @code{link_opt}       [default: @code{""}]
524 Holds user linker options; used in the default build commands.
526 Lisp variable: @code{ada-prj-default-link-opt}.
528 @item @code{gnatmake_opt}   [default: @code{"-g"}]
529 Holds user gnatmake options; used in the default build commands.
531 If a GNAT project file is used (for example @file{project.gpr}), this
532 option should be set to @code{-Pproject.gpr}.
534 Lisp variable: @code{ada-prj-default-gnatmake-opt}.
536 @item @code{gnatfind_opt}   [default: @code{"-rf"}]
537 Holds user gnatfind options; used in the default find commands.
539 Lisp variable: @code{ada-prj-gnatfind-switches}.
541 @item @code{main}           [default: current file]
542 Specifies the name of the executable file for the project; used in the
543 default build commands.
545 @item @code{main_unit}      [default: current Ada unit]
546 Specifies the name of the main Ada unit for the project; used in the
547 default build commands.
549 @item @code{cross_prefix}   [default: @code{""}]
550 Name of target machine in a cross-compilation environment. Used in
551 default compile and build commands.
553 @item @code{remote_machine} [default: @code{""}]
554 Name of the machine to log into before issuing the compile and build
555 commands. If this variable is empty, the command will be run on the
556 local machine.
558 @item @code{comp_cmd}       [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
559 Command used to compile a single file.
560 The name of the file is substituted for @code{full_current}.
562 Lisp variable: @code{ada-prj-default-comp-cmd}.
564 @item @code{check_cmd}      [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
565 Command used to syntax check a single file.
566 The name of the file is substituted for @code{full_current}.
568 Lisp variable: @code{ada-prj-default-check-cmd}
570 @item @code{make_cmd}       [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
571 Command used to build the application.
573 Lisp variable: @code{ada-prj-default-make-cmd}.
575 @item @code{run_cmd}        [default: @code{"./$@{main@}"}]
576 Command used to run the application.
578 @item @code{debug_pre_cmd}  [default: @code{"cd $@{build_dir@}"}]
579 Command executed before @code{debug_cmd}.
581 @item @code{debug_cmd}      [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
582 Command used to debug the application
584 Lisp variable: @code{ada-prj-default-debugger}.
586 @item @code{debug_post_cmd} [default: @code{""}]
587 Command executed after @code{debug_cmd}.
589 @end table
591 @node Compiling Examples, Moving Through Ada Code, Project files, Top
592 @chapter Compiling Examples
594 We present several small projects, and walk thru the process of
595 compiling, linking, and running them.
597 The first example illustrates more Ada mode features than the others;
598 you should work thru that example before doing the others.
600 All of these examples assume you are using GNAT.
602 The source for these examples is available on the Emacs Ada mode
603 website mentioned in @xref{Installation}.
605 @menu
606 * No project files::            Just menus
607 * Set compiler options::        A basic Ada mode project file
608 * Set source search path::      Source in multiple directories
609 * Use GNAT project file::
610 @end menu
612 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
613 @section No project files
614 This example uses no project files.
616 First, create a directory @file{Example_1}, containing:
618 @file{hello.adb}:
620 @example
621 with Ada.Text_IO;
622 procedure Hello
623 is begin
624    Put_Line("Hello from hello.adb");
625 end Hello;
626 @end example
628 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
629 compiler error handling.
631 @file{hello_2.adb}:
633 @example
634 with Hello_Pkg;
635 procedure Hello_2
636 is begin
637    Hello_Pkg.Say_Hello;
638 end Hello_2;
639 @end example
641 @file{hello_pkg.ads}:
643 @example
644 package Hello_Pkg is
645    procedure Say_Hello;
646 end Hello_Pkg;
647 @end example
649 @file{hello_pkg.adb}:
651 @example
652 with Ada.Text_IO;
653 package Hello_Pkg is
654    procedure Say_Hello
655    is begin
656       Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
657    end Say_Hello;
658 end Hello_Pkg;
659 @end example
661 Yes, this is missing the keyword @code{body}; another compiler error
662 example.
664 In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
665 get a @code{*compilation*} buffer containing something like (the
666 directory paths will be different):
668 @example
669 cd c:/Examples/Example_1/
670 gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ
671 gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb
672 hello.adb:4:04: "Put_Line" is not visible
673 hello.adb:4:04: non-visible declaration at a-textio.ads:264
674 hello.adb:4:04: non-visible declaration at a-textio.ads:260
675 gnatmake: "c:/Examples/Example_1/hello.adb" compilation error
676 @end example
678 If you have enabled font-lock, the lines with actual errors (starting
679 with @file{hello.adb}) are highlighted, with the file name in red.
681 Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}).
682 Or you can click the middle mouse button on the first error line. The
683 compilation buffer scrolls to put the first error on the top line, and
684 point is put at the place of the error in the @file{hello.adb} buffer.
686 To fix the error, change the line to be
688 @example
689     Ada.Text_IO.Put_Line ("hello from hello.adb"):
690 @end example
692 Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}.
694 Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
695 prompted to save the file (if you haven't already). Then the
696 compilation buffer is displayed again, containing:
698 @example
699 cd c:/Examples/Example_1/
700 gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs  -largs
701 gcc -c -g -gnatq -gnatQ hello.adb
702 gnatbind -x hello.ali
703 gnatlink hello.ali -o hello.exe -g
704 @end example
706 The compilation has succeeded without errors; @file{hello.exe} now
707 exists in the same directory as @file{hello.adb}.
709 Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
710 containing
712 @example
713 Hello from hello.adb
715 Process run finished
716 @end example
718 That completes the first part of this example.
720 Now we will compile a multi-file project. Open the file
721 @file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This
722 finds an error in @file{hello_pkg.adb}:
724 @example
725 cd c:/Examples/Example_1/
726 gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs  -largs
727 gcc -c -g -gnatq -gnatQ hello_pkg.adb
728 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
729 gnatmake: "hello_pkg.adb" compilation error
730 @end example
732 This demonstrates that gnatmake finds the files needed by the main
733 program. However, it cannot find files in a different directory,
734 unless you use an Emacs Ada mode project file to specify the other directories;
735 @xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
736 project file}.
738 Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
740 Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
742 @example
743 package body Hello_Pkg is
744 @end example
746 Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
747 gnatmake successfully builds @file{hello_2}. This demonstrates that
748 Emacs has remembered the main file, in the project variable
749 @code{main_unit}, and used it for the Build command.
751 Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
752 The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
754 One final point. If you switch back to buffer @file{hello.adb}, and
755 invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
756 because @code{main_unit} is still set to @code{hello_2}, as you can
757 see when you invoke @key{Ada | Project | Edit}.
759 There are three ways to change @code{main_unit}:
761 @enumerate
762 @item
763 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
764 the current file.
766 @item
767 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
768 @code{main}, and click @key{[save]}
770 @item
771 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
773 @end enumerate
775 @node Set compiler options, Set source search path, No project files, Compiling Examples
776 @section Set compiler options
778 This example illustrates using an Emacs Ada mode project file to set a
779 compiler option.
781 If you have files from @file{Example_1} open in Emacs, you should
782 close them so you don't get confused. Use menu @key{File | Close
783 (current buffer)}.
785 In directory @file{Example_2}, create these files:
787 @file{hello.adb}:
789 @example
790 with Ada.Text_IO;
791 procedure Hello
792 is begin
793    Put_Line("Hello from hello.adb");
794 end Hello;
795 @end example
797 This is the same as @file{hello.adb} from @file{Example_1}. It has two
798 errors; missing ``use Ada.Text_IO;'', and no space between
799 @code{Put_Line} and its argument list.
801 @file{hello.adp}:
803 @example
804 comp_opt=-gnatyt
805 @end example
807 This tells the GNAT compiler to check for token spacing; in
808 particular, there must be a space preceding a parenthesis.
810 In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
811 select @file{Example_2/hello.adp}.
813 Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
814 Build}. You should get a @code{*compilation*} buffer containing
815 something like (the directory paths will be different):
817 @example
818 cd c:/Examples/Example_2/
819 gnatmake -o hello hello -g -cargs -gnatyt  -bargs  -largs
820 gcc -c -g -gnatyt hello.adb
821 hello.adb:4:04: "Put_Line" is not visible
822 hello.adb:4:04: non-visible declaration at a-textio.ads:264
823 hello.adb:4:04: non-visible declaration at a-textio.ads:260
824 hello.adb:4:12: (style) space required
825 gnatmake: "hello.adb" compilation error
826 @end example
828 Compare this to the compiler output in @ref{No project files}; the
829 gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
830 @code{-cargs -gnaty}, and an additional error is reported in
831 @file{hello.adb} on line 4. This shows that @file{hello.adp} is being
832 used to set the compiler options.
834 Fixing the error, linking and running the code proceed as in @ref{No
835 project files}.
837 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
838 @section Set source search path
840 In this example, we show how to deal with files in more than one
841 directory. We start with the same code as in @ref{No project files}; create those
842 files (with the errors present)
844 Create the directory @file{Example_3}, containing:
846 @file{hello_pkg.ads}:
848 @example
849 package Hello_Pkg is
850    procedure Say_Hello;
851 end Hello_Pkg;
852 @end example
854 @file{hello_pkg.adb}:
856 @example
857 with Ada.Text_IO;
858 package Hello_Pkg is
859    procedure Say_Hello
860    is begin
861       Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
862    end Say_Hello;
863 end Hello_Pkg;
864 @end example
866 These are the same files from example 1; @file{hello_pkg.adb} has an
867 error on line 2.
869 In addition, create a directory @file{Example_3/Other}, containing these files:
871 @file{Other/hello_3.adb}:
873 @example
874 with Hello_Pkg;
875 with Ada.Text_IO; use Ada.Text_IO;
876 procedure Hello_3
877 is begin
878    Hello_Pkg.Say_Hello;
879    Put_Line ("From hello_3");
880 end Hello_3;
881 @end example
883 There are no errors in this file.
885 @file{Other/other.adp}:
887 @example
888 src_dir=..
889 comp_opt=-I..
890 @end example
892 Note that there must be no trailing spaces.
894 In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
895 select @file{Example_3/Other/other.adp}.
897 Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
898 Build}. You should get a @code{*compilation*} buffer containing
899 something like (the directory paths will be different):
901 @example
902 cd c:/Examples/Example_3/Other/
903 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs  -largs
904 gcc -c -g -I.. hello_3.adb
905 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
906 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
907 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
908 @end example
910 Compare the @code{-cargs} option to the compiler output in @ref{Set
911 compiler options}; this shows that @file{other.adp} is being used to
912 set the compiler options.
914 Move to the error with @key{C-x `}. Ada mode searches the list of
915 directories given by @code{src_dir} for the file mentioned in the
916 compiler error message.
918 Fixing the error, linking and running the code proceed as in @ref{No
919 project files}.
921 @node Use GNAT project file,  , Set source search path, Compiling Examples
922 @section Use GNAT project file
924 In this example, we show how to use a GNAT project file.
926 Create the directory @file{Example_4}, containing:
928 @file{hello_pkg.ads}:
930 @example
931 package Hello_Pkg is
932    procedure Say_Hello;
933 end Hello_Pkg;
934 @end example
936 @file{hello_pkg.adb}:
938 @example
939 with Ada.Text_IO;
940 package Hello_Pkg is
941    procedure Say_Hello
942    is begin
943       Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
944    end Say_Hello;
945 end Hello_Pkg;
946 @end example
948 These are the same files from example 1; @file{hello_pkg.adb} has an
949 error on line 2.
951 In addition, create a directory @file{Example_4/Gnat_Project},
952 containing these files:
954 @file{Other/hello_4.adb}:
956 @example
957 with Hello_Pkg;
958 with Ada.Text_IO; use Ada.Text_IO;
959 procedure Hello_4
960 is begin
961    Hello_Pkg.Say_Hello;
962    Put_Line ("From hello_4");
963 end Hello_4;
964 @end example
966 There are no errors in this file.
968 @file{Gnat_Project/hello_4.adp}:
970 @example
971 src_dir=..
972 gnatmake_opt=-Phello_4.gpr
973 @end example
975 @file{Gnat_Project/hello_4.gpr}:
977 @example
978 Project Hello_4 is
979    for Source_Dirs use (".", "..");
980 end Hello_4;
981 @end example
983 In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
984 select @file{Example_4/Gnat_Project/hello_4.adp}.
986 Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
987 Build}. You should get a @code{*compilation*} buffer containing
988 something like (the directory paths will be different):
990 @example
991 cd c:/Examples/Example_4/Gnat_Project/
992 gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs  -largs
993 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
994 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
995 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
996 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
997 @end example
999 Compare the @code{gcc} options to the compiler output in @ref{Set
1000 compiler options}; this shows that @file{hello_4.gpr} is being used to
1001 set the compiler options.
1003 Fixing the error, linking and running the code proceed as in @ref{No
1004 project files}.
1006 @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
1007 @chapter Moving Through Ada Code
1008 @c -----------------------------------------------------------------------
1010 There are several easy to use commands to navigate through Ada code. All
1011 these functions are available through the Ada menu, and you can also
1012 use the following key bindings or the command names. Some of these
1013 menu entries are available only if the GNAT compiler is used, since
1014 the implementation relies on the GNAT cross-referencing information.
1016 @table @kbd
1017 @item M-C-e
1018 @findex ada-next-procedure
1019 Move to the next function/procedure/task, which ever comes next
1020 (@code{ada-next-procedure}).
1021 @item M-C-a
1022 @findex ada-previous-procedure
1023 Move to previous function/procedure/task
1024 (@code{ada-previous-procedure}).
1025 @item M-x ada-next-package
1026 @findex ada-next-package
1027 Move to next package.
1028 @item M-x ada-previous-package
1029 @findex ada-previous-package
1030 Move to previous package.
1031 @item C-c C-a
1032 @findex ada-move-to-start
1033 Move to matching start of @code{end} (@code{ada-move-to-start}).  If
1034 point is at the end of a subprogram, this command jumps to the
1035 corresponding @code{begin} if the user option
1036 @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
1037 the subprogram declaration.
1038 @item C-c C-e
1039 @findex ada-move-to-end
1040 Move point to end of current block (@code{ada-move-to-end}).
1041 @item C-c o
1042 Switch between corresponding spec and body file
1043 (@code{ff-find-other-file}).  If point is in a subprogram, position
1044 point on the corresponding declaration or body in the other file.
1045 @item C-c c-d
1046 @findex ada-goto-declaration
1047 Move from any reference to its declaration, for from a declaration to
1048 its body (for procedures, tasks, private and incomplete types).
1049 @item C-c C-r
1050 @findex ada-find-references
1051 Runs the @file{gnatfind} command to search for all references to the
1052 identifier surrounding point (@code{ada-find-references}). Use
1053 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1054 compilation errors).
1055 @end table
1057 If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
1058 will try to run GNAT for you whenever cross-reference information is
1059 needed, and is older than the current source file.
1061 @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
1062 @chapter Identifier completion
1064 Emacs and Ada mode provide two general ways for the completion of
1065 identifiers. This is an easy way to type faster: you just have to type
1066 the first few letters of an identifiers, and then loop through all the
1067 possible completions.
1069 The first method is general for Emacs. It works by parsing all open
1070 files for possible completions.
1072 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
1073 are the only words starting with @samp{my} in any of the opened files,
1074 then you will have this scenario:
1076 @example
1077 You type:  my@key{M-/}
1078 Emacs inserts:  @samp{my_identifier}
1079 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
1080 @samp{my_subprogram}.
1081 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
1082 @end example
1084 This is a very fast way to do completion, and the casing of words will
1085 also be respected.
1087 The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
1088 compiler. Emacs will search the cross-information for possible
1089 completions.
1091 The main advantage is that this completion is more accurate: only
1092 existing identifier will be suggested.
1094 On the other hand, this completion is a little bit slower and requires
1095 that you have compiled your file at least once since you created that
1096 identifier.
1098 @table @kbd
1099 @item C-@key{TAB}
1100 @findex ada-complete-identifier
1101 Complete current identifier using cross-reference information.
1102 @item M-/
1103 Complete identifier using buffer information (not Ada-specific).
1104 @end table
1106 @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
1107 @chapter Automatic Smart Indentation
1109 Ada mode comes with a full set of rules for automatic indentation. You
1110 can also configure the indentation, via the following variables:
1112 @table @asis
1113 @item @code{ada-broken-indent}           (default value: 2)
1114 Number of columns to indent the continuation of a broken line.
1116 @item @code{ada-indent}                  (default value: 3)
1117 Number of columns for default indentation.
1119 @item @code{ada-indent-record-rel-type}  (default value: 3)
1120 Indentation for @code{record} relative to @code{type} or @code{use}.
1122 @item @code{ada-indent-return}           (default value: 0)
1123 Indentation for @code{return} relative to @code{function} (if
1124 @code{ada-indent-return} is greater than 0), or the open parenthesis
1125 (if @code{ada-indent-return} is negative or 0).  Note that in the second
1126 case, when there is no open parenthesis, the indentation is done
1127 relative to @code{function} with the value of @code{ada-broken-indent}.
1129 @item @code{ada-label-indent}            (default value: -4)
1130 Number of columns to indent a label.
1132 @item @code{ada-stmt-end-indent}         (default value: 0)
1133 Number of columns to indent a statement @code{end} keyword on a separate line.
1135 @item @code{ada-when-indent}             (default value: 3)
1136 Indentation for @code{when} relative to @code{exception} or @code{case}.
1138 @item @code{ada-indent-is-separate}      (default value: t)
1139 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
1141 @item @code{ada-indent-to-open-paren}    (default value: t)
1142 Non-@code{nil} means indent according to the innermost open parenthesis.
1144 @item @code{ada-indent-after-return}     (default value: t)
1145 Non-@code{nil} means that the current line will also be re-indented
1146 before inserting a newline, when you press @key{RET}.
1147 @end table
1149 Most of the time, the indentation will be automatic, i.e when you
1150 press @key{RET}, the cursor will move to the correct column on the
1151 next line.
1153 You can also indent single lines, or the current region, with @key{TAB}.
1155 Another mode of indentation exists that helps you to set up your
1156 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
1157 the following:
1159 @itemize @bullet
1160 @item
1161 Reindent the current line, as @key{TAB} would do.
1162 @item
1163 Temporarily move the cursor to a reference line, i.e., the line that
1164 was used to calculate the current indentation.
1165 @item
1166 Display in the message window the name of the variable that provided
1167 the offset for the indentation.
1168 @end itemize
1170 The exact indentation of the current line is the same as the one for the
1171 reference line, plus an offset given by the variable.
1173 @table @kbd
1174 @item @key{TAB}
1175 Indent the current line or the current region.
1176 @item C-M-\
1177 Indent lines in the current region.
1178 @item C-c @key{TAB}
1179 Indent the current line and display the name of the variable used for
1180 indentation.
1181 @end table
1183 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
1184 @chapter Formatting Parameter Lists
1186 @table @kbd
1187 @item C-c C-f
1188 @findex ada-format-paramlist
1189 Format the parameter list (@code{ada-format-paramlist}).
1190 @end table
1192 This aligns the declarations on the colon (@samp{:}) separating
1193 argument names and argument types, and aligns the @code{in},
1194 @code{out} and @code{in out} keywords.
1196 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
1197 @chapter Automatic Casing
1199 Casing of identifiers, attributes and keywords is automatically
1200 performed while typing when the variable @code{ada-auto-case} is set.
1201 Every time you press a word separator, the previous word is
1202 automatically cased.
1204 You can customize the automatic casing differently for keywords,
1205 attributes and identifiers. The relevant variables are the following:
1206 @code{ada-case-keyword}, @code{ada-case-attribute} and
1207 @code{ada-case-identifier}.
1209 All these variables can have one of the following values:
1211 @table @code
1212 @item downcase-word
1213 The word will be lowercase. For instance @code{My_vARIable} is
1214 converted to @code{my_variable}.
1216 @item upcase-word
1217 The word will be uppercase. For instance @code{My_vARIable} is
1218 converted to @code{MY_VARIABLE}.
1220 @item ada-capitalize-word
1221 The first letter and each letter following an underscore (@samp{_})
1222 are uppercase, others are lowercase. For instance @code{My_vARIable}
1223 is converted to @code{My_Variable}.
1225 @item ada-loose-case-word
1226 Characters after an underscore @samp{_} character are uppercase,
1227 others are not modified. For instance @code{My_vARIable} is converted
1228 to @code{My_VARIable}.
1229 @end table
1231 Ada mode allows you to define exceptions to these rules, in a file
1232 specified by the variable variable @code{ada-case-exception-file}
1233 (default @file{~/.emacs_case_exceptions}). Each line in this file
1234 specifies the casing of one word or word fragment. Comments may be
1235 included, separated from the word by a space.
1237 If the word starts with an asterisk (@key{*}), it defines the casing
1238 af a word fragemnt (or ``substring''); part of a word between two
1239 underscores or word boundary.
1241 For example:
1243 @example
1244 DOD        Department of Defense
1246 GNAT       The GNAT compiler from Ada Core Technologies
1247 @end example
1249 The word fragment @code{*IO} applies to any word containing ``_io'';
1250 @code{Text_IO}, @code{Hardware_IO}, etc.
1252 @findex ada-create-case-exception
1253 There are two ways to add new items to this file: you can simply edit
1254 it as you would edit any text file. Or you can position point on the
1255 word you want to add, and select menu @samp{Ada | Edit | Create Case
1256 Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
1257 The word will automatically be added to the current list of exceptions
1258 and to the file.
1260 To define a word fragment case exception, select the word fragment,
1261 then select menu @samp{Ada | Edit | Create Case Exception Substring}.
1263 It is sometimes useful to have multiple exception files around (for
1264 instance, one could be the standard Ada acronyms, the second some
1265 company specific exceptions, and the last one some project specific
1266 exceptions). If you set up the variable @code{ada-case-exception-file}
1267 as a list of files, each of them will be parsed and used in your emacs
1268 session. However, when you save a new exception through the menu, as
1269 described above, the new exception will be added to the first file in
1270 the list.
1272 @table @kbd
1273 @item C-c C-b
1274 @findex ada-adjust-case-buffer
1275 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
1276 @item C-c C-y
1277 Create a new entry in the exception dictionary, with the word under
1278 the cursor (@code{ada-create-case-exception})
1279 @item C-c C-t
1280 @findex ada-case-read-exceptions
1281 Rereads the exception dictionary from the file
1282 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
1283 @end table
1285 @node Statement Templates, Comment Handling, Automatic Casing, Top
1286 @chapter Statement Templates
1288 Templates are defined for most Ada statements, using the Emacs
1289 ``skeleton'' package. They can be inserted in the buffer using the
1290 following commands:
1292 @table @kbd
1293 @item C-c t b
1294 @findex ada-exception-block
1295 exception Block (@code{ada-exception-block}).
1296 @item C-c t c
1297 @findex ada-case
1298 case (@code{ada-case}).
1299 @item C-c t d
1300 @findex ada-declare-block
1301 declare Block (@code{ada-declare-block}).
1302 @item C-c t e
1303 @findex ada-else
1304 else (@code{ada-else}).
1305 @item C-c t f
1306 @findex ada-for-loop
1307 for Loop (@code{ada-for-loop}).
1308 @item C-c t h
1309 @findex ada-header
1310 Header (@code{ada-header}).
1311 @item C-c t i
1312 @findex ada-if
1313 if (@code{ada-if}).
1314 @item C-c t k
1315 @findex ada-package-body
1316 package Body (@code{ada-package-body}).
1317 @item C-c t l
1318 @findex ada-loop
1319 loop (@code{ada-loop}).
1320 @item C-c p
1321 @findex ada-subprogram-body
1322 subprogram body (@code{ada-subprogram-body}).
1323 @item C-c t t
1324 @findex ada-task-body
1325 task Body (@code{ada-task-body}).
1326 @item C-c t w
1327 @findex ada-while
1328 while Loop (@code{ada-while}).
1329 @item C-c t u
1330 @findex ada-use
1331 use (@code{ada-use}).
1332 @item C-c t x
1333 @findex ada-exit
1334 exit (@code{ada-exit}).
1335 @item C-c t C-a
1336 @findex ada-array
1337 array (@code{ada-array}).
1338 @item C-c t C-e
1339 @findex ada-elsif
1340 elsif (@code{ada-elsif}).
1341 @item C-c t C-f
1342 @findex ada-function-spec
1343 function Spec (@code{ada-function-spec}).
1344 @item C-c t C-k
1345 @findex ada-package-spec
1346 package Spec (@code{ada-package-spec}).
1347 @item C-c t C-p
1348 @findex ada-procedure-spec
1349 procedure Spec (@code{ada-package-spec}.
1350 @item C-c t C-r
1351 @findex ada-record
1352 record (@code{ada-record}).
1353 @item C-c t C-s
1354 @findex ada-subtype
1355 subtype (@code{ada-subtype}).
1356 @item C-c t C-t
1357 @findex ada-task-spec
1358 task Spec (@code{ada-task-spec}).
1359 @item C-c t C-u
1360 @findex ada-with
1361 with (@code{ada-with}).
1362 @item C-c t C-v
1363 @findex ada-private
1364 private (@code{ada-private}).
1365 @item C-c t C-w
1366 @findex ada-when
1367 when (@code{ada-when}).
1368 @item C-c t C-x
1369 @findex ada-exception
1370 exception (@code{ada-exception}).
1371 @item C-c t C-y
1372 @findex ada-type
1373 type (@code{ada-type}).
1374 @end table
1376 @node Comment Handling, Index, Statement Templates, Top
1377 @chapter Comment Handling
1379 By default, comment lines get indented like Ada code. There are a few
1380 additional functions to handle comments:
1382 @table @kbd
1383 @item M-;
1384 Start a comment in default column.
1385 @item M-j
1386 Continue comment on next line.
1387 @item C-c ;
1388 Comment the selected region (add -- at the beginning of lines).
1389 @item C-c :
1390 Uncomment the selected region
1391 @item M-q
1392 autofill the current comment.
1393 @end table
1395 @node Index,  , Comment Handling, Top
1396 @unnumbered Index
1398 @printindex fn
1400 @contents
1401 @bye
1403 @ignore
1404    arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
1405 @end ignore