1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/ada-mode
6 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
7 2005, 2006, 2007, 2008, 2009 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.3 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 4.00
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} 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} 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}.
291 @item Set main and Build
292 Sets @code{main} to the current file, then executes the Build
296 Display @code{main} in the message buffer.
299 Compiles all obsolete units of the current @code{main}, and links
300 @code{main}, by running @code{make_cmd} from the current project.
302 This sets @code{main} 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} 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}:
335 Invoke @key{Ada | Set main and Build}, which sets @code{main} to
339 Invoke @key{Ada | Project | Edit}, edit @code{main} and
340 @code{main}, and click @key{[save]}
343 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main}
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}. However, Emacs Ada mode can use a
376 GNAT project project file to specify the project directories. If no
377 other customization is needed, a GNAT project file can be used without
378 an Emacs Ada mode project file.
381 * Project File Overview::
383 * Project file variables::
386 @node Project File Overview, GUI Editor, Project files, Project files
387 @section Project File Overview
389 Project files have a simple syntax; they may be edited directly. Each
390 line specifies a project variable name and its value, separated by ``='':
392 src_dir=/Projects/my_project/src_1
393 src_dir=/Projects/my_project/src_2
396 Some variables (like @code{src_dir}) are lists; multiple occurances
399 There must be no space between the variable name and ``='', and no
402 Alternately, a GUI editor for project files is available (@pxref{GUI
403 Editor}). It uses Emacs widgets, similar to Emacs customize.
405 The GUI editor also provides a convenient way to view current project
406 settings, if they have been modified using menu commands rather than
407 by editing the project file.
409 After the first Ada mode build command is invoked, there is always a
410 current project file, given by the lisp variable
411 @code{ada-prj-default-project-file}. Currently, the only way to show
412 the current project file is to invoke the GUI editor.
414 To find the project file the first time, Ada mode uses the following
419 If @code{ada-prj-default-project-file} is set, use that.
422 Otherwise, search for a file in the current directory with
423 the same base name as the Ada file, but extension given by
424 @code{ada-prj-file-extension} (default @code{".adp"}).
427 If not found, search for @file{*.adp} in the current directory; if
428 several are found, prompt the user to select one.
431 If none are found, use @file{default.adp} in the current directory (even
432 if it does not exist).
436 This algorithm always sets @code{ada-prj-default-project-file}, even
437 when the file does not actually exist.
439 To change the project file before or after the first one is found,
440 invoke @key{Ada | Project | Load ...}.
442 Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}.
443 This sets @code{ada-prj-default-project-file}, and reads the project file.
445 You can also specify a GNAT project file to @key{Ada | Project | Load
446 ...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the
447 file extension; if it is @code{.gpr}, the file is treated as a GNAT
448 project file. Any other extension is treated as an Emacs Ada mode
451 @node GUI Editor, Project file variables, Project File Overview, Project files
454 The project file editor is invoked with the menu @samp{Ada | Projects
457 Once in the buffer for editing the project file, you can save your
458 modification using the @samp{[save]} button at the bottom of the
459 buffer, or the @kbd{C-x C-s} binding. To cancel your modifications,
460 kill the buffer or click on the @samp{[cancel]} button.
462 @node Project file variables, , GUI Editor, Project files
463 @section Project file variables
465 The following variables can be defined in a project file; some can
466 also be defined in lisp variables.
468 To set a project variable that is a list, specify each element of the
469 list on a separate line in the project file.
471 Any project variable can be referenced in other project variables,
472 using a shell-like notation. For instance, if the variable
473 @code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the
474 @code{comp_opt} variable will be substituted when @code{comp_cmd} is
477 In addition, process environment variables can be referenced using the
478 same syntax, or the normal @code{$var} syntax.
480 Most project variables have defaults that can be changed by setting
481 lisp variables; the table below identifies the lisp variable for each
482 project variable. Lisp variables corresponding to project variables
483 that are lists are lisp lists.
485 In general, project variables are evaluated when referenced in
486 Emacs Ada mode commands. Relative file paths are expanded to
487 absolute relative to @code{$@{build_dir@}}.
489 Here is the list of variables. In the default values, the current
490 directory @code{"."} is the project file directory.
493 @c defined in ada-default-prj-properties; alphabetical order
495 @item @code{ada_project_path_sep} [default: @code{":" or ";"}]
496 Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct
497 value for a native implementation of GNAT for the current operating
498 system. The user must override this when using Windows native GNAT
499 with Cygwin Emacs, and perhaps in other cases.
501 Lisp variable: @code{ada-prj-ada-project-path-sep}.
503 @item @code{ada_project_path} [default: @code{""}]
504 A list of directories to search for GNAT project files.
506 If set, the @code{ADA_PROJECT_PATH} process environment variable is
507 set to this value in the Emacs process when the Emacs Ada mode project
508 is selected via menu @samp{Ada | Project | Load}.
510 For @code{ada_project_path}, relative file paths are expanded to
511 absolute when the Emacs Ada project file is read, rather than when the
512 project file is selected.
514 For example if the project file is in the directory
515 @file{/home/myproject}, the environment variable @code{GDS_ROOT} is
516 set to @code{/home/shared}, and the project file contains:
518 ada_project_path_sep=:
519 ada_project_path=$GDS_ROOT/makerules
520 ada_project_path=../opentoken
522 the environment variable @code{ADA_PROJECT_PATH} will be set to
523 @code{"/home/shared/makerules:/home/opentoken/"}.
525 The default value is not the current value of this environment
526 variable, because that will typically have been set by another
527 project, and will therefore be incorrect for this project.
529 If you have the environment variable set correctly for all of your
530 projects, you do not need to set this project variable.
532 @item @code{bind_opt} [default: @code{""}]
533 Holds user binder options; used in the default build commands.
535 Lisp variable: @code{ada-prj-default-bind-opt}.
537 @item @code{build_dir} [default: @code{"."}]
538 The compile commands will be issued in this directory.
540 @item @code{casing} [default: @code{("~/.emacs_case_exceptions")}
541 List of files containing casing exceptions. See the help on
542 @code{ada-case-exception-file} for more info.
543 @c FIXME: section on case exceptions
545 Lisp variable: @code{ada-case-exception-file}.
547 @item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
548 Command used to syntax check a single file.
549 The name of the file is substituted for @code{full_current}.
551 Lisp variable: @code{ada-prj-default-check-cmd}
553 @item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
554 Command used to compile a single file.
555 The name of the file is substituted for @code{full_current}.
557 Lisp variable: @code{ada-prj-default-comp-cmd}.
559 @item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]
560 Holds user compiler options; used in the default compile commands. The
561 default value tells gnatmake to generate library files for
562 cross-referencing even when there are errors.
564 If source code for the project is in multiple directories, the
565 appropriate compiler options must be added here. @ref{Set source
566 search path} for examples of this. Alternately, GNAT project files may
567 be used; @ref{Use GNAT project file}.
569 Lisp variable: @code{ada-prj-default-comp-opt}.
571 @item @code{cross_prefix} [default: @code{""}]
572 Name of target machine in a cross-compilation environment. Used in
573 default compile and build commands.
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}.
583 @item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}]
584 Command executed before @code{debug_cmd}.
586 @item @code{gnatfind_opt} [default: @code{"-rf"}]
587 Holds user gnatfind options; used in the default find commands.
589 Lisp variable: @code{ada-prj-gnatfind-switches}.
591 @item @code{gnatmake_opt} [default: @code{"-g"}]
592 Holds user gnatmake options; used in the default build commands.
594 Lisp variable: @code{ada-prj-default-gnatmake-opt}.
596 @item @code{gpr_file} [default: @code{""}]
597 Specify GNAT project file.
599 If set, the source and object directories specified in the GNAT
600 project file are appended to @code{src_dir} and @code{obj_dir}. This
601 allows specifying Ada source directories with a GNAT project file, and
602 other source directories with the Emacs project file.
604 In addition, @code{-P@{gpr_file@}} is added to the project variable
605 @code{gnatmake_opt} whenever it is referenced. With the default
606 project variables, this passes the project file to all gnatmake
609 Lisp variable: @code{ada-prj-default-gpr-file}.
611 @c FIXME: add gnatstub-opts
613 @item @code{link_opt} [default: @code{""}]
614 Holds user linker options; used in the default build commands.
616 Lisp variable: @code{ada-prj-default-link-opt}.
618 @item @code{main} [default: current file]
619 Specifies the name of the executable file for the project; used in the
620 default build commands.
622 @item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
623 Command used to build the application.
625 Lisp variable: @code{ada-prj-default-make-cmd}.
627 @item @code{obj_dir} [default: @code{"."}]
628 A list of directories to search for library files. Ada mode searches
629 this list for the @samp{.ali} files generated by GNAT that contain
630 cross-reference information.
632 The compiler commands must place the @samp{.ali} files in one of these
633 directories; the default commands do that.
635 @item @code{remote_machine} [default: @code{""}]
636 Name of the machine to log into before issuing the compile and build
637 commands. If this variable is empty, the command will be run on the
640 @item @code{run_cmd} [default: @code{"./$@{main@}"}]
641 Command used to run the application.
643 @item @code{src_dir} [default: @code{"."}]
644 A list of directories to search for source files, both for compile
645 commands and source navigation.
649 @node Compiling Examples, Moving Through Ada Code, Project files, Top
650 @chapter Compiling Examples
652 We present several small projects, and walk thru the process of
653 compiling, linking, and running them.
655 The first example illustrates more Ada mode features than the others;
656 you should work thru that example before doing the others.
658 All of these examples assume you are using GNAT.
660 The source for these examples is available on the Emacs Ada mode
661 website mentioned in @xref{Installation}.
664 * No project files:: Just menus
665 * Set compiler options:: A basic Ada mode project file
666 * Set source search path:: Source in multiple directories
667 * Use GNAT project file::
668 * Use multiple GNAT project files::
671 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
672 @section No project files
673 This example uses no project files.
675 First, create a directory @file{Example_1}, containing:
683 Put_Line("Hello from hello.adb");
687 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
688 compiler error handling.
700 This file has no errors.
702 @file{hello_pkg.ads}:
710 This file has no errors.
712 @file{hello_pkg.adb}:
719 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
724 Yes, this is missing the keyword @code{body}; another compiler error
727 In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
728 get a @code{*compilation*} buffer containing something like (the
729 directory paths will be different):
732 cd c:/Examples/Example_1/
733 gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ
734 gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb
735 hello.adb:4:04: "Put_Line" is not visible
736 hello.adb:4:04: non-visible declaration at a-textio.ads:264
737 hello.adb:4:04: non-visible declaration at a-textio.ads:260
738 gnatmake: "c:/Examples/Example_1/hello.adb" compilation error
741 If you have enabled font-lock, the lines with actual errors (starting
742 with @file{hello.adb}) are highlighted, with the file name in red.
744 Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}).
745 Or you can click the middle mouse button on the first error line. The
746 compilation buffer scrolls to put the first error on the top line, and
747 point is put at the place of the error in the @file{hello.adb} buffer.
749 To fix the error, change the line to be
752 Ada.Text_IO.Put_Line ("hello from hello.adb"):
755 Now invoke @key{Ada | Show main}; this displays @file{Ada mode main: hello}.
757 Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
758 prompted to save the file (if you haven't already). Then the
759 compilation buffer is displayed again, containing:
762 cd c:/Examples/Example_1/
763 gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs
764 gcc -c -g -gnatq -gnatQ hello.adb
765 gnatbind -x hello.ali
766 gnatlink hello.ali -o hello.exe -g
769 The compilation has succeeded without errors; @file{hello.exe} now
770 exists in the same directory as @file{hello.adb}.
772 Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
781 That completes the first part of this example.
783 Now we will compile a multi-file project. Open the file
784 @file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This
785 finds an error in @file{hello_pkg.adb}:
788 cd c:/Examples/Example_1/
789 gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs
790 gcc -c -g -gnatq -gnatQ hello_pkg.adb
791 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
792 gnatmake: "hello_pkg.adb" compilation error
795 This demonstrates that gnatmake finds the files needed by the main
796 program. However, it cannot find files in a different directory,
797 unless you use an Emacs Ada mode project file to specify the other directories;
798 @xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
801 Invoke @key{Ada | Show main}; this displays @file{Ada mode main: hello_2}.
803 Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
806 package body Hello_Pkg is
809 Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
810 gnatmake successfully builds @file{hello_2}. This demonstrates that
811 Emacs has remembered the main file, in the project variable
812 @code{main}, and used it for the Build command.
814 Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
815 The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
817 One final point. If you switch back to buffer @file{hello.adb}, and
818 invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
819 because @code{main} is still set to @code{hello_2}, as you can
820 see when you invoke @key{Ada | Project | Edit}.
822 There are three ways to change @code{main}:
826 Invoke @key{Ada | Set main and Build}, which sets @code{main} to
830 Invoke @key{Ada | Project | Edit}, edit @code{main}, and click @key{[save]}
833 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main}
837 @node Set compiler options, Set source search path, No project files, Compiling Examples
838 @section Set compiler options
840 This example illustrates using an Emacs Ada mode project file to set a
843 If you have files from @file{Example_1} open in Emacs, you should
844 close them so you don't get confused. Use menu @key{File | Close
847 In directory @file{Example_2}, create these files:
855 Put_Line("Hello from hello.adb");
859 This is the same as @file{hello.adb} from @file{Example_1}. It has two
860 errors; missing ``use Ada.Text_IO;'', and no space between
861 @code{Put_Line} and its argument list.
869 This tells the GNAT compiler to check for token spacing; in
870 particular, there must be a space preceding a parenthesis.
872 In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
873 select @file{Example_2/hello.adp}.
875 Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
876 Build}. You should get a @code{*compilation*} buffer containing
877 something like (the directory paths will be different):
880 cd c:/Examples/Example_2/
881 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
882 gcc -c -g -gnatyt hello.adb
883 hello.adb:4:04: "Put_Line" is not visible
884 hello.adb:4:04: non-visible declaration at a-textio.ads:264
885 hello.adb:4:04: non-visible declaration at a-textio.ads:260
886 hello.adb:4:12: (style) space required
887 gnatmake: "hello.adb" compilation error
890 Compare this to the compiler output in @ref{No project files}; the
891 gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
892 @code{-cargs -gnaty}, and an additional error is reported in
893 @file{hello.adb} on line 4. This shows that @file{hello.adp} is being
894 used to set the compiler options.
896 Fixing the error, linking and running the code proceed as in @ref{No
899 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
900 @section Set source search path
902 In this example, we show how to deal with files in more than one
903 directory. We start with the same code as in @ref{No project files};
904 create those files (with the errors present)
906 Create the directory @file{Example_3}, containing:
908 @file{hello_pkg.ads}:
916 @file{hello_pkg.adb}:
923 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
928 These are the same files from example 1; @file{hello_pkg.adb} has an
931 In addition, create a directory @file{Example_3/Other}, containing these files:
933 @file{Other/hello_3.adb}:
937 with Ada.Text_IO; use Ada.Text_IO;
941 Put_Line ("From hello_3");
945 There are no errors in this file.
947 @file{Other/other.adp}:
954 Note that there must be no trailing spaces.
956 In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
957 select @file{Example_3/Other/other.adp}.
959 Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
960 Build}. You should get a @code{*compilation*} buffer containing
961 something like (the directory paths will be different):
964 cd c:/Examples/Example_3/Other/
965 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
966 gcc -c -g -I.. hello_3.adb
967 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
968 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
969 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
972 Compare the @code{-cargs} option to the compiler output in @ref{Set
973 compiler options}; this shows that @file{other.adp} is being used to
974 set the compiler options.
976 Move to the error with @key{C-x `}. Ada mode searches the list of
977 directories given by @code{src_dir} for the file mentioned in the
978 compiler error message.
980 Fixing the error, linking and running the code proceed as in @ref{No
983 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
984 @section Use GNAT project file
986 In this example, we show how to use a GNAT project file, with no Ada
989 Create the directory @file{Example_4}, containing:
991 @file{hello_pkg.ads}:
999 @file{hello_pkg.adb}:
1003 package Hello_Pkg is
1006 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
1011 These are the same files from example 1; @file{hello_pkg.adb} has an
1014 In addition, create a directory @file{Example_4/Gnat_Project},
1015 containing these files:
1017 @file{Gnat_Project/hello_4.adb}:
1021 with Ada.Text_IO; use Ada.Text_IO;
1024 Hello_Pkg.Say_Hello;
1025 Put_Line ("From hello_4");
1029 There are no errors in this file.
1031 @file{Gnat_Project/hello_4.gpr}:
1035 for Source_Dirs use (".", "..");
1039 In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
1040 select @file{Example_4/Gnat_Project/hello_4.gpr}.
1042 Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
1043 Build}. You should get a @code{*compilation*} buffer containing
1044 something like (the directory paths will be different):
1047 cd c:/Examples/Example_4/Gnat_Project/
1048 gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs
1049 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
1050 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
1051 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
1052 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
1055 Compare the @code{gcc} options to the compiler output in @ref{Set
1056 compiler options}; this shows that @file{hello_4.gpr} is being used to
1057 set the compiler options.
1059 Fixing the error, linking and running the code proceed as in @ref{No
1062 @node Use multiple GNAT project files, , Use GNAT project file, Compiling Examples
1063 @section Use multiple GNAT project files
1065 In this example, we show how to use multiple GNAT project files,
1066 specifying the GNAT project search path in an Ada mode project file.
1068 Create the directory @file{Example_4} as specified in @ref{Use GNAT
1071 Create the directory @file{Example_5}, containing:
1077 with Ada.Text_IO; use Ada.Text_IO;
1080 Hello_Pkg.Say_Hello;
1081 Put_Line ("From hello_5");
1085 There are no errors in this file.
1090 ada_project_path=../Example_4/Gnat_Project
1091 gpr_file=hello_5.gpr
1099 for Source_Dirs use (".");
1101 for Default_Switches ("Ada") use ("-g", "-gnatyt");
1106 In buffer @file{hello_5.adb}, invoke @key{Ada | Project | Load...}, and
1107 select @file{Example_5/hello_5.adp}.
1109 Then, again in @file{hello_5.adb}, invoke @key{Ada | Set main and
1110 Build}. You should get a @code{*compilation*} buffer containing
1111 something like (the directory paths will be different):
1114 cd c:/Examples/Example_5/
1115 gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs
1116 gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb
1117 gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
1118 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
1119 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
1122 Now type @key{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
1123 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
1124 used to set the compilation search path.
1126 @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
1127 @chapter Moving Through Ada Code
1129 There are several easy to use commands to navigate through Ada code. All
1130 these functions are available through the Ada menu, and you can also
1131 use the following key bindings or the command names. Some of these
1132 menu entries are available only if the GNAT compiler is used, since
1133 the implementation relies on the GNAT cross-referencing information.
1137 @findex ada-next-procedure
1138 Move to the next function/procedure/task, which ever comes next
1139 (@code{ada-next-procedure}).
1141 @findex ada-previous-procedure
1142 Move to previous function/procedure/task
1143 (@code{ada-previous-procedure}).
1144 @item M-x ada-next-package
1145 @findex ada-next-package
1146 Move to next package.
1147 @item M-x ada-previous-package
1148 @findex ada-previous-package
1149 Move to previous package.
1151 @findex ada-move-to-start
1152 Move to matching start of @code{end} (@code{ada-move-to-start}). If
1153 point is at the end of a subprogram, this command jumps to the
1154 corresponding @code{begin} if the user option
1155 @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
1156 the subprogram declaration.
1158 @findex ada-move-to-end
1159 Move point to end of current block (@code{ada-move-to-end}).
1161 Switch between corresponding spec and body file
1162 (@code{ff-find-other-file}). If point is in a subprogram, position
1163 point on the corresponding declaration or body in the other file.
1165 @findex ada-goto-declaration
1166 Move from any reference to its declaration, for from a declaration to
1167 its body (for procedures, tasks, private and incomplete types).
1169 @findex ada-find-references
1170 Runs the @file{gnatfind} command to search for all references to the
1171 identifier surrounding point (@code{ada-find-references}). Use
1172 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1173 compilation errors).
1176 If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
1177 will try to run GNAT for you whenever cross-reference information is
1178 needed, and is older than the current source file.
1180 @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
1181 @chapter Identifier completion
1183 Emacs and Ada mode provide two general ways for the completion of
1184 identifiers. This is an easy way to type faster: you just have to type
1185 the first few letters of an identifiers, and then loop through all the
1186 possible completions.
1188 The first method is general for Emacs. It works by parsing all open
1189 files for possible completions.
1191 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
1192 are the only words starting with @samp{my} in any of the opened files,
1193 then you will have this scenario:
1196 You type: my@key{M-/}
1197 Emacs inserts: @samp{my_identifier}
1198 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
1199 @samp{my_subprogram}.
1200 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
1203 This is a very fast way to do completion, and the casing of words will
1206 The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
1207 compiler. Emacs will search the cross-information for possible
1210 The main advantage is that this completion is more accurate: only
1211 existing identifier will be suggested.
1213 On the other hand, this completion is a little bit slower and requires
1214 that you have compiled your file at least once since you created that
1219 @findex ada-complete-identifier
1220 Complete current identifier using cross-reference information.
1222 Complete identifier using buffer information (not Ada-specific).
1225 @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
1226 @chapter Automatic Smart Indentation
1228 Ada mode comes with a full set of rules for automatic indentation. You
1229 can also configure the indentation, via the following variables:
1232 @item @code{ada-broken-indent} (default value: 2)
1233 Number of columns to indent the continuation of a broken line.
1235 @item @code{ada-indent} (default value: 3)
1236 Number of columns for default indentation.
1238 @item @code{ada-indent-record-rel-type} (default value: 3)
1239 Indentation for @code{record} relative to @code{type} or @code{use}.
1241 @item @code{ada-indent-return} (default value: 0)
1242 Indentation for @code{return} relative to @code{function} (if
1243 @code{ada-indent-return} is greater than 0), or the open parenthesis
1244 (if @code{ada-indent-return} is negative or 0). Note that in the second
1245 case, when there is no open parenthesis, the indentation is done
1246 relative to @code{function} with the value of @code{ada-broken-indent}.
1248 @item @code{ada-label-indent} (default value: -4)
1249 Number of columns to indent a label.
1251 @item @code{ada-stmt-end-indent} (default value: 0)
1252 Number of columns to indent a statement @code{end} keyword on a separate line.
1254 @item @code{ada-when-indent} (default value: 3)
1255 Indentation for @code{when} relative to @code{exception} or @code{case}.
1257 @item @code{ada-indent-is-separate} (default value: t)
1258 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
1260 @item @code{ada-indent-to-open-paren} (default value: t)
1261 Non-@code{nil} means indent according to the innermost open parenthesis.
1263 @item @code{ada-indent-after-return} (default value: t)
1264 Non-@code{nil} means that the current line will also be re-indented
1265 before inserting a newline, when you press @key{RET}.
1268 Most of the time, the indentation will be automatic, i.e when you
1269 press @key{RET}, the cursor will move to the correct column on the
1272 You can also indent single lines, or the current region, with @key{TAB}.
1274 Another mode of indentation exists that helps you to set up your
1275 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
1280 Reindent the current line, as @key{TAB} would do.
1282 Temporarily move the cursor to a reference line, i.e., the line that
1283 was used to calculate the current indentation.
1285 Display in the message window the name of the variable that provided
1286 the offset for the indentation.
1289 The exact indentation of the current line is the same as the one for the
1290 reference line, plus an offset given by the variable.
1294 Indent the current line or the current region.
1296 Indent lines in the current region.
1298 Indent the current line and display the name of the variable used for
1302 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
1303 @chapter Formatting Parameter Lists
1307 @findex ada-format-paramlist
1308 Format the parameter list (@code{ada-format-paramlist}).
1311 This aligns the declarations on the colon (@samp{:}) separating
1312 argument names and argument types, and aligns the @code{in},
1313 @code{out} and @code{in out} keywords.
1315 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
1316 @chapter Automatic Casing
1318 Casing of identifiers, attributes and keywords is automatically
1319 performed while typing when the variable @code{ada-auto-case} is set.
1320 Every time you press a word separator, the previous word is
1321 automatically cased.
1323 You can customize the automatic casing differently for keywords,
1324 attributes and identifiers. The relevant variables are the following:
1325 @code{ada-case-keyword}, @code{ada-case-attribute} and
1326 @code{ada-case-identifier}.
1328 All these variables can have one of the following values:
1332 The word will be lowercase. For instance @code{My_vARIable} is
1333 converted to @code{my_variable}.
1336 The word will be uppercase. For instance @code{My_vARIable} is
1337 converted to @code{MY_VARIABLE}.
1339 @item ada-capitalize-word
1340 The first letter and each letter following an underscore (@samp{_})
1341 are uppercase, others are lowercase. For instance @code{My_vARIable}
1342 is converted to @code{My_Variable}.
1344 @item ada-loose-case-word
1345 Characters after an underscore @samp{_} character are uppercase,
1346 others are not modified. For instance @code{My_vARIable} is converted
1347 to @code{My_VARIable}.
1350 Ada mode allows you to define exceptions to these rules, in a file
1351 specified by the variable variable @code{ada-case-exception-file}
1352 (default @file{~/.emacs_case_exceptions}). Each line in this file
1353 specifies the casing of one word or word fragment. Comments may be
1354 included, separated from the word by a space.
1356 If the word starts with an asterisk (@key{*}), it defines the casing
1357 af a word fragemnt (or ``substring''); part of a word between two
1358 underscores or word boundary.
1363 DOD Department of Defense
1365 GNAT The GNAT compiler from Ada Core Technologies
1368 The word fragment @code{*IO} applies to any word containing ``_io'';
1369 @code{Text_IO}, @code{Hardware_IO}, etc.
1371 @findex ada-create-case-exception
1372 There are two ways to add new items to this file: you can simply edit
1373 it as you would edit any text file. Or you can position point on the
1374 word you want to add, and select menu @samp{Ada | Edit | Create Case
1375 Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
1376 The word will automatically be added to the current list of exceptions
1379 To define a word fragment case exception, select the word fragment,
1380 then select menu @samp{Ada | Edit | Create Case Exception Substring}.
1382 It is sometimes useful to have multiple exception files around (for
1383 instance, one could be the standard Ada acronyms, the second some
1384 company specific exceptions, and the last one some project specific
1385 exceptions). If you set up the variable @code{ada-case-exception-file}
1386 as a list of files, each of them will be parsed and used in your emacs
1387 session. However, when you save a new exception through the menu, as
1388 described above, the new exception will be added to the first file in
1393 @findex ada-adjust-case-buffer
1394 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
1396 Create a new entry in the exception dictionary, with the word under
1397 the cursor (@code{ada-create-case-exception})
1399 @findex ada-case-read-exceptions
1400 Rereads the exception dictionary from the file
1401 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
1404 @node Statement Templates, Comment Handling, Automatic Casing, Top
1405 @chapter Statement Templates
1407 Templates are defined for most Ada statements, using the Emacs
1408 ``skeleton'' package. They can be inserted in the buffer using the
1413 @findex ada-exception-block
1414 exception Block (@code{ada-exception-block}).
1417 case (@code{ada-case}).
1419 @findex ada-declare-block
1420 declare Block (@code{ada-declare-block}).
1423 else (@code{ada-else}).
1425 @findex ada-for-loop
1426 for Loop (@code{ada-for-loop}).
1429 Header (@code{ada-header}).
1434 @findex ada-package-body
1435 package Body (@code{ada-package-body}).
1438 loop (@code{ada-loop}).
1440 @findex ada-subprogram-body
1441 subprogram body (@code{ada-subprogram-body}).
1443 @findex ada-task-body
1444 task Body (@code{ada-task-body}).
1447 while Loop (@code{ada-while}).
1450 use (@code{ada-use}).
1453 exit (@code{ada-exit}).
1456 array (@code{ada-array}).
1459 elsif (@code{ada-elsif}).
1461 @findex ada-function-spec
1462 function Spec (@code{ada-function-spec}).
1464 @findex ada-package-spec
1465 package Spec (@code{ada-package-spec}).
1467 @findex ada-procedure-spec
1468 procedure Spec (@code{ada-package-spec}.
1471 record (@code{ada-record}).
1474 subtype (@code{ada-subtype}).
1476 @findex ada-task-spec
1477 task Spec (@code{ada-task-spec}).
1480 with (@code{ada-with}).
1483 private (@code{ada-private}).
1486 when (@code{ada-when}).
1488 @findex ada-exception
1489 exception (@code{ada-exception}).
1492 type (@code{ada-type}).
1495 @node Comment Handling, GNU Free Documentation License, Statement Templates, Top
1496 @chapter Comment Handling
1498 By default, comment lines get indented like Ada code. There are a few
1499 additional functions to handle comments:
1503 Start a comment in default column.
1505 Continue comment on next line.
1507 Comment the selected region (add -- at the beginning of lines).
1509 Uncomment the selected region
1511 autofill the current comment.
1514 @node GNU Free Documentation License, Index, Comment Handling, Top
1515 @appendix GNU Free Documentation License
1516 @include doclicense.texi
1518 @node Index, , GNU Free Documentation License, Top
1527 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e