1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../info/ada-mode
6 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
7 2005, 2006, 2007 Free Software Foundation, Inc.
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.
32 * Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
39 @subtitle An Emacs major mode for programming in Ada
40 @subtitle Ada Mode Version 3.7
43 @vskip 0pt plus 1filll
47 @c fixme; title page doesn't show up in ada-mode.info; why bother with
50 @node Top, Overview, (dir), (dir)
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
64 * Automatic Casing:: Adjusting the case of words automatically
65 * Statement Templates:: Inserting code templates
66 * Comment Handling:: Reformatting comments easily
71 @node Overview, Installation, Top, Top
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
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
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
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
117 To see what version of Ada mode you have installed, do @key{M-x
120 The following files are provided with the Ada mode distribution:
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.
130 @file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs
134 @file{ada-stmt.el}: Ada statement templates.
137 @file{ada-xref.el}: GNAT cross-references, completion of identifiers,
138 and compilation. Also provides project files (which are not
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
151 @cite{The GNU Emacs Manual}.
154 @cite{The GNU Emacs Manual}.
157 @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
160 These global Emacs settings are strongly recommended (put them in your
164 (global-font-lock-mode t)
165 (transient-mark-mode t)
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.
177 * Non-standard file names::
179 * Other customization::
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:
200 (ada-add-extensions "_s.ada" "_b.ada")
203 You can define additional extensions:
206 (ada-add-extensions ".ads" "_b.ada")
207 (ada-add-extensions ".ads" ".body")
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
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
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:
249 (setq variable-name value)
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.
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.
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
289 This sets @code{main_unit} only if it has not been set yet.
292 Compiles the current file, by running @code{comp_cmd} from the current
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
302 Display @code{main_unit} in the message buffer.
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.
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.
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}:
341 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
345 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
346 @code{main}, and click @key{[save]}
349 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
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}.
384 * Project File Overview::
386 * Project file variables::
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 ``='':
395 src_dir=/Projects/my_project/src_1
396 src_dir=/Projects/my_project/src_2
399 Some variables (like @code{src_dir}) are lists; multiple occurances
402 There must be no space between the variable name and ``='', and no
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
422 If @code{ada-prj-default-project-file} is set, use that.
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"}).
430 If not found, search for @file{*.adp} in the current directory; if
431 several are found, prompt the user to select one.
434 If none are found, use @file{default.adp} in the current directory (even
435 if it does not exist).
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
451 The project file editor is invoked with the menu @samp{Ada | Projects
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
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
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
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}.
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}.
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::
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:
624 Put_Line("Hello from hello.adb");
628 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
629 compiler error handling.
641 @file{hello_pkg.ads}:
649 @file{hello_pkg.adb}:
656 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
661 Yes, this is missing the keyword @code{body}; another compiler error
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):
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
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
689 Ada.Text_IO.Put_Line ("hello from hello.adb"):
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:
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
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,
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}:
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
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
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}:
743 package body Hello_Pkg is
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}:
763 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
767 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
768 @code{main}, and click @key{[save]}
771 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
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
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
785 In directory @file{Example_2}, create these files:
793 Put_Line("Hello from hello.adb");
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.
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):
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
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
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}:
854 @file{hello_pkg.adb}:
861 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
866 These are the same files from example 1; @file{hello_pkg.adb} has an
869 In addition, create a directory @file{Example_3/Other}, containing these files:
871 @file{Other/hello_3.adb}:
875 with Ada.Text_IO; use Ada.Text_IO;
879 Put_Line ("From hello_3");
883 There are no errors in this file.
885 @file{Other/other.adp}:
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):
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
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
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}:
936 @file{hello_pkg.adb}:
943 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
948 These are the same files from example 1; @file{hello_pkg.adb} has an
951 In addition, create a directory @file{Example_4/Gnat_Project},
952 containing these files:
954 @file{Other/hello_4.adb}:
958 with Ada.Text_IO; use Ada.Text_IO;
962 Put_Line ("From hello_4");
966 There are no errors in this file.
968 @file{Gnat_Project/hello_4.adp}:
972 gnatmake_opt=-Phello_4.gpr
975 @file{Gnat_Project/hello_4.gpr}:
979 for Source_Dirs use (".", "..");
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):
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
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
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.
1018 @findex ada-next-procedure
1019 Move to the next function/procedure/task, which ever comes next
1020 (@code{ada-next-procedure}).
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.
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.
1039 @findex ada-move-to-end
1040 Move point to end of current block (@code{ada-move-to-end}).
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.
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).
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).
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:
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}.
1084 This is a very fast way to do completion, and the casing of words will
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
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
1100 @findex ada-complete-identifier
1101 Complete current identifier using cross-reference information.
1103 Complete identifier using buffer information (not Ada-specific).
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:
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}.
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
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
1161 Reindent the current line, as @key{TAB} would do.
1163 Temporarily move the cursor to a reference line, i.e., the line that
1164 was used to calculate the current indentation.
1166 Display in the message window the name of the variable that provided
1167 the offset for the indentation.
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.
1175 Indent the current line or the current region.
1177 Indent lines in the current region.
1179 Indent the current line and display the name of the variable used for
1183 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
1184 @chapter Formatting Parameter Lists
1188 @findex ada-format-paramlist
1189 Format the parameter list (@code{ada-format-paramlist}).
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:
1213 The word will be lowercase. For instance @code{My_vARIable} is
1214 converted to @code{my_variable}.
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}.
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.
1244 DOD Department of Defense
1246 GNAT The GNAT compiler from Ada Core Technologies
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
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
1274 @findex ada-adjust-case-buffer
1275 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
1277 Create a new entry in the exception dictionary, with the word under
1278 the cursor (@code{ada-create-case-exception})
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}).
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
1294 @findex ada-exception-block
1295 exception Block (@code{ada-exception-block}).
1298 case (@code{ada-case}).
1300 @findex ada-declare-block
1301 declare Block (@code{ada-declare-block}).
1304 else (@code{ada-else}).
1306 @findex ada-for-loop
1307 for Loop (@code{ada-for-loop}).
1310 Header (@code{ada-header}).
1315 @findex ada-package-body
1316 package Body (@code{ada-package-body}).
1319 loop (@code{ada-loop}).
1321 @findex ada-subprogram-body
1322 subprogram body (@code{ada-subprogram-body}).
1324 @findex ada-task-body
1325 task Body (@code{ada-task-body}).
1328 while Loop (@code{ada-while}).
1331 use (@code{ada-use}).
1334 exit (@code{ada-exit}).
1337 array (@code{ada-array}).
1340 elsif (@code{ada-elsif}).
1342 @findex ada-function-spec
1343 function Spec (@code{ada-function-spec}).
1345 @findex ada-package-spec
1346 package Spec (@code{ada-package-spec}).
1348 @findex ada-procedure-spec
1349 procedure Spec (@code{ada-package-spec}.
1352 record (@code{ada-record}).
1355 subtype (@code{ada-subtype}).
1357 @findex ada-task-spec
1358 task Spec (@code{ada-task-spec}).
1361 with (@code{ada-with}).
1364 private (@code{ada-private}).
1367 when (@code{ada-when}).
1369 @findex ada-exception
1370 exception (@code{ada-exception}).
1373 type (@code{ada-type}).
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:
1384 Start a comment in default column.
1386 Continue comment on next line.
1388 Comment the selected region (add -- at the beginning of lines).
1390 Uncomment the selected region
1392 autofill the current comment.
1395 @node Index, , Comment Handling, Top
1404 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e