1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/ada-mode
6 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
7 2005, 2006, 2007, 2008 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 no
13 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
14 and with the Back-Cover Texts as in (a) below. A copy of the license
15 is included in the section entitled ``GNU Free Documentation License''.
17 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
18 modify this GNU manual. Buying copies from the FSF supports it in
19 developing GNU and promoting software freedom.''
25 * Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
32 @subtitle An Emacs major mode for programming in Ada
33 @subtitle Ada Mode Version 3.7
36 @vskip 0pt plus 1filll
40 @c fixme; title page doesn't show up in ada-mode.info; why bother with
43 @node Top, Overview, (dir), (dir)
47 * Installation:: Installing Ada mode on your system
48 * Customization:: Setting up Ada mode to your taste
49 * Compiling Executing:: Working with your application within Emacs
50 * Project files:: Describing the organization of your project
51 * Compiling Examples:: A small tutorial
52 * Moving Through Ada Code:: Moving easily through Ada sources
53 * Identifier completion:: Finishing words automatically
54 * Automatic Smart Indentation:: Indenting your code automatically as you type
55 * Formatting Parameter Lists:: Formatting subprograms' parameter lists
57 * Automatic Casing:: Adjusting the case of words automatically
58 * Statement Templates:: Inserting code templates
59 * Comment Handling:: Reformatting comments easily
60 * GNU Free Documentation License:: The license for this documentation.
65 @node Overview, Installation, Top, Top
68 The Emacs mode for programming in Ada helps the user in understanding
69 existing code and facilitates writing new code.
71 When the Gnu Ada compiler GNAT is used, the cross-reference
72 information output by the compiler is used to provide powerful code
73 navigation (jump to definition, find all uses, etc).
75 When you open a file with a file extension of @file{.ads} or
76 @file{.adb}, Emacs will automatically load and activate Ada mode.
78 Ada mode works without any customization, if you are using the GNAT
79 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
82 You must customize a few things if you are using a different compiler
83 or file naming convention; @xref{Other compiler}, @xref{Non-standard
86 In addition, you may want to customize the indentation,
87 capitalization, and other things; @xref{Other customization}.
89 Finally, for large Ada projects, you will want to set up an Emacs
90 Ada mode project file for each project; @xref{Project files}. Note
91 that these are different from the GNAT project files used by gnatmake
92 and other GNAT commands.
94 See the Emacs info manual, section 'Running Debuggers Under Emacs',
95 for general information on debugging.
97 @node Installation, Customization, Overview, Top
100 Ada mode is part of the standard Emacs distribution; if you use that,
101 no files need to be installed.
103 Ada mode is also available as a separate distribution, from the Emacs
105 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The
106 separate distribution may be more recent.
108 For installing the separate distribution, see the @file{README} file
111 To see what version of Ada mode you have installed, do @key{M-x
114 The following files are provided with the Ada mode distribution:
119 @file{ada-mode.el}: The main file for Ada mode, providing indentation,
120 formatting of parameter lists, moving through code, comment handling
121 and automatic casing.
124 @file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs
128 @file{ada-stmt.el}: Ada statement templates.
131 @file{ada-xref.el}: GNAT cross-references, completion of identifiers,
132 and compilation. Also provides project files (which are not
137 @node Customization, Compiling Executing, Installation, Top
138 @chapter Customizing Ada mode
140 Here we assume you are familiar with setting variables in Emacs,
141 either thru 'customize' or in elisp (in your @file{.emacs} file). For
142 a basic introduction to customize, elisp, and Emacs in general, see
145 @cite{The GNU Emacs Manual}.
148 @cite{The GNU Emacs Manual}.
151 @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
154 These global Emacs settings are strongly recommended (put them in your
158 (global-font-lock-mode t)
159 (transient-mark-mode t)
162 @samp{(global-font-lock-mode t)} turns on syntax
163 highlighting for all buffers (it is off by default because it may be
164 too slow for some machines).
166 @samp{(transient-mark-mode t)} highlights selected text.
168 See the Emacs help for each of these variables for more information.
171 * Non-standard file names::
173 * Other customization::
176 @node Non-standard file names, Other compiler, Customization, Customization
177 @section Non-standard file names
179 By default, Ada mode is configured to use the GNAT file naming
180 convention, where file names are a simple modification of the Ada
181 names, and the extension for specs and bodies are
182 @samp{.ads} and @samp{.adb}, respectively.
184 Ada mode uses the file extentions to allow moving from a package body
185 to the corresponding spec and back.
187 Ada mode supports a list of alternative file extensions for specs and bodies.
189 For instance, if your spec and bodies files are called
190 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
191 can add the following to your @file{.emacs} file:
194 (ada-add-extensions "_s.ada" "_b.ada")
197 You can define additional extensions:
200 (ada-add-extensions ".ads" "_b.ada")
201 (ada-add-extensions ".ads" ".body")
204 This means that whenever Ada mode looks for the body for a file
205 whose extension is @file{.ads}, it will take the first available file
206 that ends with either @file{.adb}, @file{_b.ada} or
209 Simililarly, if Ada mode is looking for a spec, it will look for
210 @file{.ads} or @file{_s.ada}.
212 If the filename is not derived from the Ada name following the GNAT
213 convention, things are a little more complicated. You then need to
214 rewrite the function @code{ada-make-filename-from-adaname}. Doing that
215 is beyond the scope of this manual; see the current definitions in
216 @file{ada-mode.el} and @file{ada-xref.el} for examples.
218 @node Other compiler, Other customization, Non-standard file names, Customization
219 @section Other compiler
221 By default, Ada mode is configured to use the Gnu Ada compiler GNAT.
223 To use a different Ada compiler, you must specify the command lines
224 used to run that compiler, either in lisp variables or in Emacs
225 Ada mode project files. See @ref{Project file variables} for the list
226 of project variables, and the corresponding lisp variables.
228 @node Other customization, , Other compiler, Customization
229 @section Other customization
231 All user-settable Ada mode variables can be set via the menu
232 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
235 To modify a specific variable, you can directly call the function
236 @code{customize-variable}; just type @kbd{M-x customize-variable
237 @key{RET} @var{variable-name} @key{RET}}).
239 Alternately, you can specify variable settings in the Emacs
240 configuration file, @file{.emacs}. This file is coded in Emacs lisp,
241 and the syntax to set a variable is the following:
243 (setq variable-name value)
246 @node Compiling Executing, Project files, Customization, Top
247 @chapter Compiling Executing
249 Ada projects can be compiled, linked, and executed using commands on
250 the Ada menu. All of these commands can be customized via a project
251 file (@pxref{Project files}), but the defaults are sufficient for using
252 the GNAT compiler for simple projects (single files, or several files
253 in a single directory).
255 Even when no project file is used, the GUI project editor (menu
256 @key{Ada | Project | Edit}) shows the settings of the various project
257 file variables referenced here.
264 @node Compile commands, Compiler errors, Compiling Executing, Compiling Executing
265 @section Compile commands
267 Here are the commands for building and using an Ada project, as
268 listed in the Ada menu.
270 In multi-file projects, there must be one file that is the main
271 program. That is given by the @code{main_unit} project file variable;
272 it defaults to the current file if not yet set, but is also set by the
273 ``set main and build'' command.
278 Compiles the current file in syntax check mode, by running
279 @code{check_cmd} defined in the current project file. This typically
280 runs faster than full compile mode, speeding up finding and fixing
283 This sets @code{main_unit} only if it has not been set yet.
286 Compiles the current file, by running @code{comp_cmd} from the current
289 This does not set @code{main_unit}.
291 @item Set main and Build
292 Sets @code{main_unit} to the current file, then executes the Build
296 Display @code{main_unit} in the message buffer.
299 Compiles all obsolete units of the current @code{main_unit}, and links
300 @code{main_unit}, by running @code{make_cmd} from the current project.
302 This sets @code{main_unit} only if it has not been set yet.
305 Executes the main program in a shell, displayed in a separate Emacs
306 buffer. This runs @code{run_cmd} from the current project. The
307 execution buffer allows for interactive input/output.
309 To modify the run command, in particular to provide or change the
310 command line arguments, type @key{C-u} before invoking the command.
312 This command is not available for a cross-compilation toolchain.
315 It is important when using these commands to understand how
316 @code{main_unit} is used and changed.
318 Build runs 'gnatmake' on the main unit. During a typical edit/compile
319 session, this is the only command you need to invoke, which is why it
320 is bound to @key{C-c C-c}. It will compile all files needed by the
321 main unit, and display compilation errors in any of them.
323 Note that Build can be invoked from any Ada buffer; typically you will
324 be fixing errors in files other than the main, but you don't have to
325 switch back to the main to invoke the compiler again.
327 Novices and students typically work on single-file Ada projects. In
328 this case, @key{C-c C-m} will normally be the only command needed; it
329 will build the current file, rather than the last-built main.
331 There are three ways to change @code{main_unit}:
335 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
339 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
340 @code{main}, and click @key{[save]}
343 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
347 @node Compiler errors, , Compile commands, Compiling Executing
348 @section Compiler errors
350 The @code{Check file}, @code{Compile file}, and @code{Build} commands
351 all place compilation errors in a separate buffer named
352 @code{*compilation*}.
354 Each line in this buffer will become active: you can simply click on
355 it with the middle button of the mouse, or move point to it and press
356 @key{RET}. Emacs will then display the relevant source file and put
357 point on the line and column where the error was found.
359 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
360 will jump to the first error. If you press that key again, it will
361 move you to the second error, and so on.
363 Some error messages might also include references to other files. These
364 references are also clickable in the same way, or put point after the
365 line number and press @key{RET}.
367 @node Project files, Compiling Examples, Compiling Executing, Top
368 @chapter Project files
370 An Emacs Ada mode project file specifies what directories hold sources
371 for your project, and allows you to customize the compilation commands
372 and other things on a per-project basis.
374 Note that Ada mode project files @samp{*.adp} are different than GNAT
375 compiler project files @samp{*.gpr}.
378 * Project File Overview::
380 * Project file variables::
383 @node Project File Overview, GUI Editor, Project files, Project files
384 @section Project File Overview
386 Project files have a simple syntax; they may be edited directly. Each
387 line specifies a project variable name and its value, separated by ``='':
389 src_dir=/Projects/my_project/src_1
390 src_dir=/Projects/my_project/src_2
393 Some variables (like @code{src_dir}) are lists; multiple occurances
396 There must be no space between the variable name and ``='', and no
399 Alternately, a GUI editor for project files is available (@pxref{GUI
400 Editor}). It uses Emacs widgets, similar to Emacs customize.
402 The GUI editor also provides a convenient way to view current project
403 settings, if they have been modified using menu commands rather than
404 by editing the project file.
406 After the first Ada mode build command is invoked, there is always a
407 current project file, given by the lisp variable
408 @code{ada-prj-default-project-file}. Currently, the only way to show
409 the current project file is to invoke the GUI editor.
411 To find the project file the first time, Ada mode uses the following
416 If @code{ada-prj-default-project-file} is set, use that.
419 Otherwise, search for a file in the current directory with
420 the same base name as the Ada file, but extension given by
421 @code{ada-prj-file-extension} (default @code{".adp"}).
424 If not found, search for @file{*.adp} in the current directory; if
425 several are found, prompt the user to select one.
428 If none are found, use @file{default.adp} in the current directory (even
429 if it does not exist).
433 This algorithm always sets @code{ada-prj-default-project-file}, even
434 when the file does not actually exist.
436 To change the project file before or after the first one is found,
437 invoke @key{Ada | Project | Load ...}.
439 Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}.
440 This sets @code{ada-prj-default-project-file}, and reads the project file.
442 @node GUI Editor, Project file variables, Project File Overview, Project files
445 The project file editor is invoked with the menu @samp{Ada | Projects
448 Once in the buffer for editing the project file, you can save your
449 modification using the @samp{[save]} button at the bottom of the
450 buffer, or the @kbd{C-x C-s} binding. To cancel your modifications,
451 kill the buffer or click on the @samp{[cancel]} button.
453 @node Project file variables, , GUI Editor, Project files
454 @section Project file variables
456 The following variables can be defined in a project file; some can
457 also be defined in lisp variables.
459 To set a project variable that is a list, specify each element of the
460 list on a separate line in the project file.
462 Any project variable can be referenced in other project variables,
463 using a shell-like notation. For instance, if the variable
464 @code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the
465 @code{comp_opt} variable will be substituted when @code{comp_cmd} is
468 Most project variables have defaults that can be changed by setting
469 lisp variables; the table below identifies the lisp variable for each
470 project variable. Lisp variables corresponding to project variables
471 that are lists are lisp lists.
473 Here is the list of variables. In the default values, the current
474 directory @code{"."} is the project file directory.
476 @c defined in ada-xref-set-default-prj-values; same order here
478 @item @code{build_dir} [default: @code{"."}]
479 The compile commands will be issued in this directory.
481 @item @code{src_dir} [default: @code{"."}]
482 A list of directories to search for source files, both for compile
483 commands and source navigation.
485 @item @code{obj_dir} [default: @code{"."}]
486 A list of directories to search for library files. Ada mode searches
487 this list for the @samp{.ali} files generated by GNAT that contain
488 cross-reference information.
490 The compiler commands must place the @samp{.ali} files in one of these
491 directories; the default commands do that.
493 @item @code{casing} [default: @code{("~/.emacs_case_exceptions")}
494 List of files containing casing exceptions. See the help on
495 @code{ada-case-exception-file} for more info.
496 @c FIXME: section on case exceptions
498 Lisp variable: @code{ada-case-exception-file}.
500 @item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]
501 Holds user compiler options; used in the default compile commands. The
502 default value tells gnatmake to generate library files for
503 cross-referencing even when there are errors.
505 If source code for the project is in multiple directories, the
506 appropriate compiler options must be added here. @ref{Set source
507 search path} for examples of this. Alternately, GNAT project files may
508 be used; @ref{Use GNAT project file}.
510 Lisp variable: @code{ada-prj-default-comp-opt}.
512 @item @code{bind_opt} [default: @code{""}]
513 Holds user binder options; used in the default build commands.
515 Lisp variable: @code{ada-prj-default-bind-opt}.
517 @item @code{link_opt} [default: @code{""}]
518 Holds user linker options; used in the default build commands.
520 Lisp variable: @code{ada-prj-default-link-opt}.
522 @item @code{gnatmake_opt} [default: @code{"-g"}]
523 Holds user gnatmake options; used in the default build commands.
525 If a GNAT project file is used (for example @file{project.gpr}), this
526 option should be set to @code{-Pproject.gpr}.
528 Lisp variable: @code{ada-prj-default-gnatmake-opt}.
530 @item @code{gnatfind_opt} [default: @code{"-rf"}]
531 Holds user gnatfind options; used in the default find commands.
533 Lisp variable: @code{ada-prj-gnatfind-switches}.
535 @item @code{main} [default: current file]
536 Specifies the name of the executable file for the project; used in the
537 default build commands.
539 @item @code{main_unit} [default: current Ada unit]
540 Specifies the name of the main Ada unit for the project; used in the
541 default build commands.
543 @item @code{cross_prefix} [default: @code{""}]
544 Name of target machine in a cross-compilation environment. Used in
545 default compile and build commands.
547 @item @code{remote_machine} [default: @code{""}]
548 Name of the machine to log into before issuing the compile and build
549 commands. If this variable is empty, the command will be run on the
552 @item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
553 Command used to compile a single file.
554 The name of the file is substituted for @code{full_current}.
556 Lisp variable: @code{ada-prj-default-comp-cmd}.
558 @item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
559 Command used to syntax check a single file.
560 The name of the file is substituted for @code{full_current}.
562 Lisp variable: @code{ada-prj-default-check-cmd}
564 @item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
565 Command used to build the application.
567 Lisp variable: @code{ada-prj-default-make-cmd}.
569 @item @code{run_cmd} [default: @code{"./$@{main@}"}]
570 Command used to run the application.
572 @item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}]
573 Command executed before @code{debug_cmd}.
575 @item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
576 Command used to debug the application
578 Lisp variable: @code{ada-prj-default-debugger}.
580 @item @code{debug_post_cmd} [default: @code{""}]
581 Command executed after @code{debug_cmd}.
585 @node Compiling Examples, Moving Through Ada Code, Project files, Top
586 @chapter Compiling Examples
588 We present several small projects, and walk thru the process of
589 compiling, linking, and running them.
591 The first example illustrates more Ada mode features than the others;
592 you should work thru that example before doing the others.
594 All of these examples assume you are using GNAT.
596 The source for these examples is available on the Emacs Ada mode
597 website mentioned in @xref{Installation}.
600 * No project files:: Just menus
601 * Set compiler options:: A basic Ada mode project file
602 * Set source search path:: Source in multiple directories
603 * Use GNAT project file::
606 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
607 @section No project files
608 This example uses no project files.
610 First, create a directory @file{Example_1}, containing:
618 Put_Line("Hello from hello.adb");
622 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
623 compiler error handling.
635 @file{hello_pkg.ads}:
643 @file{hello_pkg.adb}:
650 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
655 Yes, this is missing the keyword @code{body}; another compiler error
658 In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
659 get a @code{*compilation*} buffer containing something like (the
660 directory paths will be different):
663 cd c:/Examples/Example_1/
664 gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ
665 gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb
666 hello.adb:4:04: "Put_Line" is not visible
667 hello.adb:4:04: non-visible declaration at a-textio.ads:264
668 hello.adb:4:04: non-visible declaration at a-textio.ads:260
669 gnatmake: "c:/Examples/Example_1/hello.adb" compilation error
672 If you have enabled font-lock, the lines with actual errors (starting
673 with @file{hello.adb}) are highlighted, with the file name in red.
675 Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}).
676 Or you can click the middle mouse button on the first error line. The
677 compilation buffer scrolls to put the first error on the top line, and
678 point is put at the place of the error in the @file{hello.adb} buffer.
680 To fix the error, change the line to be
683 Ada.Text_IO.Put_Line ("hello from hello.adb"):
686 Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}.
688 Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
689 prompted to save the file (if you haven't already). Then the
690 compilation buffer is displayed again, containing:
693 cd c:/Examples/Example_1/
694 gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs
695 gcc -c -g -gnatq -gnatQ hello.adb
696 gnatbind -x hello.ali
697 gnatlink hello.ali -o hello.exe -g
700 The compilation has succeeded without errors; @file{hello.exe} now
701 exists in the same directory as @file{hello.adb}.
703 Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
712 That completes the first part of this example.
714 Now we will compile a multi-file project. Open the file
715 @file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This
716 finds an error in @file{hello_pkg.adb}:
719 cd c:/Examples/Example_1/
720 gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs
721 gcc -c -g -gnatq -gnatQ hello_pkg.adb
722 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
723 gnatmake: "hello_pkg.adb" compilation error
726 This demonstrates that gnatmake finds the files needed by the main
727 program. However, it cannot find files in a different directory,
728 unless you use an Emacs Ada mode project file to specify the other directories;
729 @xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
732 Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
734 Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
737 package body Hello_Pkg is
740 Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
741 gnatmake successfully builds @file{hello_2}. This demonstrates that
742 Emacs has remembered the main file, in the project variable
743 @code{main_unit}, and used it for the Build command.
745 Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
746 The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
748 One final point. If you switch back to buffer @file{hello.adb}, and
749 invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
750 because @code{main_unit} is still set to @code{hello_2}, as you can
751 see when you invoke @key{Ada | Project | Edit}.
753 There are three ways to change @code{main_unit}:
757 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
761 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
762 @code{main}, and click @key{[save]}
765 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
769 @node Set compiler options, Set source search path, No project files, Compiling Examples
770 @section Set compiler options
772 This example illustrates using an Emacs Ada mode project file to set a
775 If you have files from @file{Example_1} open in Emacs, you should
776 close them so you don't get confused. Use menu @key{File | Close
779 In directory @file{Example_2}, create these files:
787 Put_Line("Hello from hello.adb");
791 This is the same as @file{hello.adb} from @file{Example_1}. It has two
792 errors; missing ``use Ada.Text_IO;'', and no space between
793 @code{Put_Line} and its argument list.
801 This tells the GNAT compiler to check for token spacing; in
802 particular, there must be a space preceding a parenthesis.
804 In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
805 select @file{Example_2/hello.adp}.
807 Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
808 Build}. You should get a @code{*compilation*} buffer containing
809 something like (the directory paths will be different):
812 cd c:/Examples/Example_2/
813 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
814 gcc -c -g -gnatyt hello.adb
815 hello.adb:4:04: "Put_Line" is not visible
816 hello.adb:4:04: non-visible declaration at a-textio.ads:264
817 hello.adb:4:04: non-visible declaration at a-textio.ads:260
818 hello.adb:4:12: (style) space required
819 gnatmake: "hello.adb" compilation error
822 Compare this to the compiler output in @ref{No project files}; the
823 gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
824 @code{-cargs -gnaty}, and an additional error is reported in
825 @file{hello.adb} on line 4. This shows that @file{hello.adp} is being
826 used to set the compiler options.
828 Fixing the error, linking and running the code proceed as in @ref{No
831 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
832 @section Set source search path
834 In this example, we show how to deal with files in more than one
835 directory. We start with the same code as in @ref{No project files}; create those
836 files (with the errors present)
838 Create the directory @file{Example_3}, containing:
840 @file{hello_pkg.ads}:
848 @file{hello_pkg.adb}:
855 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
860 These are the same files from example 1; @file{hello_pkg.adb} has an
863 In addition, create a directory @file{Example_3/Other}, containing these files:
865 @file{Other/hello_3.adb}:
869 with Ada.Text_IO; use Ada.Text_IO;
873 Put_Line ("From hello_3");
877 There are no errors in this file.
879 @file{Other/other.adp}:
886 Note that there must be no trailing spaces.
888 In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
889 select @file{Example_3/Other/other.adp}.
891 Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
892 Build}. You should get a @code{*compilation*} buffer containing
893 something like (the directory paths will be different):
896 cd c:/Examples/Example_3/Other/
897 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
898 gcc -c -g -I.. hello_3.adb
899 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
900 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
901 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
904 Compare the @code{-cargs} option to the compiler output in @ref{Set
905 compiler options}; this shows that @file{other.adp} is being used to
906 set the compiler options.
908 Move to the error with @key{C-x `}. Ada mode searches the list of
909 directories given by @code{src_dir} for the file mentioned in the
910 compiler error message.
912 Fixing the error, linking and running the code proceed as in @ref{No
915 @node Use GNAT project file, , Set source search path, Compiling Examples
916 @section Use GNAT project file
918 In this example, we show how to use a GNAT project file.
920 Create the directory @file{Example_4}, containing:
922 @file{hello_pkg.ads}:
930 @file{hello_pkg.adb}:
937 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
942 These are the same files from example 1; @file{hello_pkg.adb} has an
945 In addition, create a directory @file{Example_4/Gnat_Project},
946 containing these files:
948 @file{Other/hello_4.adb}:
952 with Ada.Text_IO; use Ada.Text_IO;
956 Put_Line ("From hello_4");
960 There are no errors in this file.
962 @file{Gnat_Project/hello_4.adp}:
966 gnatmake_opt=-Phello_4.gpr
969 @file{Gnat_Project/hello_4.gpr}:
973 for Source_Dirs use (".", "..");
977 In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
978 select @file{Example_4/Gnat_Project/hello_4.adp}.
980 Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
981 Build}. You should get a @code{*compilation*} buffer containing
982 something like (the directory paths will be different):
985 cd c:/Examples/Example_4/Gnat_Project/
986 gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs
987 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
988 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
989 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
990 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
993 Compare the @code{gcc} options to the compiler output in @ref{Set
994 compiler options}; this shows that @file{hello_4.gpr} is being used to
995 set the compiler options.
997 Fixing the error, linking and running the code proceed as in @ref{No
1000 @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
1001 @chapter Moving Through Ada Code
1002 @c -----------------------------------------------------------------------
1004 There are several easy to use commands to navigate through Ada code. All
1005 these functions are available through the Ada menu, and you can also
1006 use the following key bindings or the command names. Some of these
1007 menu entries are available only if the GNAT compiler is used, since
1008 the implementation relies on the GNAT cross-referencing information.
1012 @findex ada-next-procedure
1013 Move to the next function/procedure/task, which ever comes next
1014 (@code{ada-next-procedure}).
1016 @findex ada-previous-procedure
1017 Move to previous function/procedure/task
1018 (@code{ada-previous-procedure}).
1019 @item M-x ada-next-package
1020 @findex ada-next-package
1021 Move to next package.
1022 @item M-x ada-previous-package
1023 @findex ada-previous-package
1024 Move to previous package.
1026 @findex ada-move-to-start
1027 Move to matching start of @code{end} (@code{ada-move-to-start}). If
1028 point is at the end of a subprogram, this command jumps to the
1029 corresponding @code{begin} if the user option
1030 @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
1031 the subprogram declaration.
1033 @findex ada-move-to-end
1034 Move point to end of current block (@code{ada-move-to-end}).
1036 Switch between corresponding spec and body file
1037 (@code{ff-find-other-file}). If point is in a subprogram, position
1038 point on the corresponding declaration or body in the other file.
1040 @findex ada-goto-declaration
1041 Move from any reference to its declaration, for from a declaration to
1042 its body (for procedures, tasks, private and incomplete types).
1044 @findex ada-find-references
1045 Runs the @file{gnatfind} command to search for all references to the
1046 identifier surrounding point (@code{ada-find-references}). Use
1047 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1048 compilation errors).
1051 If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
1052 will try to run GNAT for you whenever cross-reference information is
1053 needed, and is older than the current source file.
1055 @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
1056 @chapter Identifier completion
1058 Emacs and Ada mode provide two general ways for the completion of
1059 identifiers. This is an easy way to type faster: you just have to type
1060 the first few letters of an identifiers, and then loop through all the
1061 possible completions.
1063 The first method is general for Emacs. It works by parsing all open
1064 files for possible completions.
1066 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
1067 are the only words starting with @samp{my} in any of the opened files,
1068 then you will have this scenario:
1071 You type: my@key{M-/}
1072 Emacs inserts: @samp{my_identifier}
1073 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
1074 @samp{my_subprogram}.
1075 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
1078 This is a very fast way to do completion, and the casing of words will
1081 The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
1082 compiler. Emacs will search the cross-information for possible
1085 The main advantage is that this completion is more accurate: only
1086 existing identifier will be suggested.
1088 On the other hand, this completion is a little bit slower and requires
1089 that you have compiled your file at least once since you created that
1094 @findex ada-complete-identifier
1095 Complete current identifier using cross-reference information.
1097 Complete identifier using buffer information (not Ada-specific).
1100 @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
1101 @chapter Automatic Smart Indentation
1103 Ada mode comes with a full set of rules for automatic indentation. You
1104 can also configure the indentation, via the following variables:
1107 @item @code{ada-broken-indent} (default value: 2)
1108 Number of columns to indent the continuation of a broken line.
1110 @item @code{ada-indent} (default value: 3)
1111 Number of columns for default indentation.
1113 @item @code{ada-indent-record-rel-type} (default value: 3)
1114 Indentation for @code{record} relative to @code{type} or @code{use}.
1116 @item @code{ada-indent-return} (default value: 0)
1117 Indentation for @code{return} relative to @code{function} (if
1118 @code{ada-indent-return} is greater than 0), or the open parenthesis
1119 (if @code{ada-indent-return} is negative or 0). Note that in the second
1120 case, when there is no open parenthesis, the indentation is done
1121 relative to @code{function} with the value of @code{ada-broken-indent}.
1123 @item @code{ada-label-indent} (default value: -4)
1124 Number of columns to indent a label.
1126 @item @code{ada-stmt-end-indent} (default value: 0)
1127 Number of columns to indent a statement @code{end} keyword on a separate line.
1129 @item @code{ada-when-indent} (default value: 3)
1130 Indentation for @code{when} relative to @code{exception} or @code{case}.
1132 @item @code{ada-indent-is-separate} (default value: t)
1133 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
1135 @item @code{ada-indent-to-open-paren} (default value: t)
1136 Non-@code{nil} means indent according to the innermost open parenthesis.
1138 @item @code{ada-indent-after-return} (default value: t)
1139 Non-@code{nil} means that the current line will also be re-indented
1140 before inserting a newline, when you press @key{RET}.
1143 Most of the time, the indentation will be automatic, i.e when you
1144 press @key{RET}, the cursor will move to the correct column on the
1147 You can also indent single lines, or the current region, with @key{TAB}.
1149 Another mode of indentation exists that helps you to set up your
1150 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
1155 Reindent the current line, as @key{TAB} would do.
1157 Temporarily move the cursor to a reference line, i.e., the line that
1158 was used to calculate the current indentation.
1160 Display in the message window the name of the variable that provided
1161 the offset for the indentation.
1164 The exact indentation of the current line is the same as the one for the
1165 reference line, plus an offset given by the variable.
1169 Indent the current line or the current region.
1171 Indent lines in the current region.
1173 Indent the current line and display the name of the variable used for
1177 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
1178 @chapter Formatting Parameter Lists
1182 @findex ada-format-paramlist
1183 Format the parameter list (@code{ada-format-paramlist}).
1186 This aligns the declarations on the colon (@samp{:}) separating
1187 argument names and argument types, and aligns the @code{in},
1188 @code{out} and @code{in out} keywords.
1190 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
1191 @chapter Automatic Casing
1193 Casing of identifiers, attributes and keywords is automatically
1194 performed while typing when the variable @code{ada-auto-case} is set.
1195 Every time you press a word separator, the previous word is
1196 automatically cased.
1198 You can customize the automatic casing differently for keywords,
1199 attributes and identifiers. The relevant variables are the following:
1200 @code{ada-case-keyword}, @code{ada-case-attribute} and
1201 @code{ada-case-identifier}.
1203 All these variables can have one of the following values:
1207 The word will be lowercase. For instance @code{My_vARIable} is
1208 converted to @code{my_variable}.
1211 The word will be uppercase. For instance @code{My_vARIable} is
1212 converted to @code{MY_VARIABLE}.
1214 @item ada-capitalize-word
1215 The first letter and each letter following an underscore (@samp{_})
1216 are uppercase, others are lowercase. For instance @code{My_vARIable}
1217 is converted to @code{My_Variable}.
1219 @item ada-loose-case-word
1220 Characters after an underscore @samp{_} character are uppercase,
1221 others are not modified. For instance @code{My_vARIable} is converted
1222 to @code{My_VARIable}.
1225 Ada mode allows you to define exceptions to these rules, in a file
1226 specified by the variable variable @code{ada-case-exception-file}
1227 (default @file{~/.emacs_case_exceptions}). Each line in this file
1228 specifies the casing of one word or word fragment. Comments may be
1229 included, separated from the word by a space.
1231 If the word starts with an asterisk (@key{*}), it defines the casing
1232 af a word fragemnt (or ``substring''); part of a word between two
1233 underscores or word boundary.
1238 DOD Department of Defense
1240 GNAT The GNAT compiler from Ada Core Technologies
1243 The word fragment @code{*IO} applies to any word containing ``_io'';
1244 @code{Text_IO}, @code{Hardware_IO}, etc.
1246 @findex ada-create-case-exception
1247 There are two ways to add new items to this file: you can simply edit
1248 it as you would edit any text file. Or you can position point on the
1249 word you want to add, and select menu @samp{Ada | Edit | Create Case
1250 Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
1251 The word will automatically be added to the current list of exceptions
1254 To define a word fragment case exception, select the word fragment,
1255 then select menu @samp{Ada | Edit | Create Case Exception Substring}.
1257 It is sometimes useful to have multiple exception files around (for
1258 instance, one could be the standard Ada acronyms, the second some
1259 company specific exceptions, and the last one some project specific
1260 exceptions). If you set up the variable @code{ada-case-exception-file}
1261 as a list of files, each of them will be parsed and used in your emacs
1262 session. However, when you save a new exception through the menu, as
1263 described above, the new exception will be added to the first file in
1268 @findex ada-adjust-case-buffer
1269 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
1271 Create a new entry in the exception dictionary, with the word under
1272 the cursor (@code{ada-create-case-exception})
1274 @findex ada-case-read-exceptions
1275 Rereads the exception dictionary from the file
1276 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
1279 @node Statement Templates, Comment Handling, Automatic Casing, Top
1280 @chapter Statement Templates
1282 Templates are defined for most Ada statements, using the Emacs
1283 ``skeleton'' package. They can be inserted in the buffer using the
1288 @findex ada-exception-block
1289 exception Block (@code{ada-exception-block}).
1292 case (@code{ada-case}).
1294 @findex ada-declare-block
1295 declare Block (@code{ada-declare-block}).
1298 else (@code{ada-else}).
1300 @findex ada-for-loop
1301 for Loop (@code{ada-for-loop}).
1304 Header (@code{ada-header}).
1309 @findex ada-package-body
1310 package Body (@code{ada-package-body}).
1313 loop (@code{ada-loop}).
1315 @findex ada-subprogram-body
1316 subprogram body (@code{ada-subprogram-body}).
1318 @findex ada-task-body
1319 task Body (@code{ada-task-body}).
1322 while Loop (@code{ada-while}).
1325 use (@code{ada-use}).
1328 exit (@code{ada-exit}).
1331 array (@code{ada-array}).
1334 elsif (@code{ada-elsif}).
1336 @findex ada-function-spec
1337 function Spec (@code{ada-function-spec}).
1339 @findex ada-package-spec
1340 package Spec (@code{ada-package-spec}).
1342 @findex ada-procedure-spec
1343 procedure Spec (@code{ada-package-spec}.
1346 record (@code{ada-record}).
1349 subtype (@code{ada-subtype}).
1351 @findex ada-task-spec
1352 task Spec (@code{ada-task-spec}).
1355 with (@code{ada-with}).
1358 private (@code{ada-private}).
1361 when (@code{ada-when}).
1363 @findex ada-exception
1364 exception (@code{ada-exception}).
1367 type (@code{ada-type}).
1370 @node Comment Handling, GNU Free Documentation License, Statement Templates, Top
1371 @chapter Comment Handling
1373 By default, comment lines get indented like Ada code. There are a few
1374 additional functions to handle comments:
1378 Start a comment in default column.
1380 Continue comment on next line.
1382 Comment the selected region (add -- at the beginning of lines).
1384 Uncomment the selected region
1386 autofill the current comment.
1389 @node GNU Free Documentation License, Index, Comment Handling, Top
1390 @appendix GNU Free Documentation License
1391 @include doclicense.texi
1393 @node Index, , GNU Free Documentation License, Top
1402 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e