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.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
831 @code{main}, and click @key{[save]}
834 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main}
838 @node Set compiler options, Set source search path, No project files, Compiling Examples
839 @section Set compiler options
841 This example illustrates using an Emacs Ada mode project file to set a
844 If you have files from @file{Example_1} open in Emacs, you should
845 close them so you don't get confused. Use menu @key{File | Close
848 In directory @file{Example_2}, create these files:
856 Put_Line("Hello from hello.adb");
860 This is the same as @file{hello.adb} from @file{Example_1}. It has two
861 errors; missing ``use Ada.Text_IO;'', and no space between
862 @code{Put_Line} and its argument list.
870 This tells the GNAT compiler to check for token spacing; in
871 particular, there must be a space preceding a parenthesis.
873 In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
874 select @file{Example_2/hello.adp}.
876 Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
877 Build}. You should get a @code{*compilation*} buffer containing
878 something like (the directory paths will be different):
881 cd c:/Examples/Example_2/
882 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
883 gcc -c -g -gnatyt hello.adb
884 hello.adb:4:04: "Put_Line" is not visible
885 hello.adb:4:04: non-visible declaration at a-textio.ads:264
886 hello.adb:4:04: non-visible declaration at a-textio.ads:260
887 hello.adb:4:12: (style) space required
888 gnatmake: "hello.adb" compilation error
891 Compare this to the compiler output in @ref{No project files}; the
892 gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
893 @code{-cargs -gnaty}, and an additional error is reported in
894 @file{hello.adb} on line 4. This shows that @file{hello.adp} is being
895 used to set the compiler options.
897 Fixing the error, linking and running the code proceed as in @ref{No
900 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
901 @section Set source search path
903 In this example, we show how to deal with files in more than one
904 directory. We start with the same code as in @ref{No project files};
905 create those files (with the errors present)
907 Create the directory @file{Example_3}, containing:
909 @file{hello_pkg.ads}:
917 @file{hello_pkg.adb}:
924 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
929 These are the same files from example 1; @file{hello_pkg.adb} has an
932 In addition, create a directory @file{Example_3/Other}, containing these files:
934 @file{Other/hello_3.adb}:
938 with Ada.Text_IO; use Ada.Text_IO;
942 Put_Line ("From hello_3");
946 There are no errors in this file.
948 @file{Other/other.adp}:
955 Note that there must be no trailing spaces.
957 In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
958 select @file{Example_3/Other/other.adp}.
960 Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
961 Build}. You should get a @code{*compilation*} buffer containing
962 something like (the directory paths will be different):
965 cd c:/Examples/Example_3/Other/
966 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
967 gcc -c -g -I.. hello_3.adb
968 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
969 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
970 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
973 Compare the @code{-cargs} option to the compiler output in @ref{Set
974 compiler options}; this shows that @file{other.adp} is being used to
975 set the compiler options.
977 Move to the error with @key{C-x `}. Ada mode searches the list of
978 directories given by @code{src_dir} for the file mentioned in the
979 compiler error message.
981 Fixing the error, linking and running the code proceed as in @ref{No
984 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
985 @section Use GNAT project file
987 In this example, we show how to use a GNAT project file, with no Ada
990 Create the directory @file{Example_4}, containing:
992 @file{hello_pkg.ads}:
1000 @file{hello_pkg.adb}:
1004 package Hello_Pkg is
1007 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
1012 These are the same files from example 1; @file{hello_pkg.adb} has an
1015 In addition, create a directory @file{Example_4/Gnat_Project},
1016 containing these files:
1018 @file{Gnat_Project/hello_4.adb}:
1022 with Ada.Text_IO; use Ada.Text_IO;
1025 Hello_Pkg.Say_Hello;
1026 Put_Line ("From hello_4");
1030 There are no errors in this file.
1032 @file{Gnat_Project/hello_4.gpr}:
1036 for Source_Dirs use (".", "..");
1040 In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
1041 select @file{Example_4/Gnat_Project/hello_4.gpr}.
1043 Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
1044 Build}. You should get a @code{*compilation*} buffer containing
1045 something like (the directory paths will be different):
1048 cd c:/Examples/Example_4/Gnat_Project/
1049 gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs
1050 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
1051 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
1052 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
1053 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
1056 Compare the @code{gcc} options to the compiler output in @ref{Set
1057 compiler options}; this shows that @file{hello_4.gpr} is being used to
1058 set the compiler options.
1060 Fixing the error, linking and running the code proceed as in @ref{No
1063 @node Use multiple GNAT project files, , Use GNAT project file, Compiling Examples
1064 @section Use multiple GNAT project files
1066 In this example, we show how to use multiple GNAT project files,
1067 specifying the GNAT project search path in an Ada mode project file.
1069 Create the directory @file{Example_4} as specified in @ref{Use GNAT
1072 Create the directory @file{Example_5}, containing:
1078 with Ada.Text_IO; use Ada.Text_IO;
1081 Hello_Pkg.Say_Hello;
1082 Put_Line ("From hello_5");
1086 There are no errors in this file.
1091 ada_project_path=../Example_4/Gnat_Project
1092 gpr_file=hello_5.gpr
1100 for Source_Dirs use (".");
1102 for Default_Switches ("Ada") use ("-g", "-gnatyt");
1107 In buffer @file{hello_5.adb}, invoke @key{Ada | Project | Load...}, and
1108 select @file{Example_5/hello_5.adp}.
1110 Then, again in @file{hello_5.adb}, invoke @key{Ada | Set main and
1111 Build}. You should get a @code{*compilation*} buffer containing
1112 something like (the directory paths will be different):
1115 cd c:/Examples/Example_5/
1116 gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs
1117 gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb
1118 gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
1119 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
1120 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
1123 Now type @key{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
1124 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
1125 used to set the compilation search path.
1127 @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
1128 @chapter Moving Through Ada Code
1130 There are several easy to use commands to navigate through Ada code. All
1131 these functions are available through the Ada menu, and you can also
1132 use the following key bindings or the command names. Some of these
1133 menu entries are available only if the GNAT compiler is used, since
1134 the implementation relies on the GNAT cross-referencing information.
1138 @findex ada-next-procedure
1139 Move to the next function/procedure/task, which ever comes next
1140 (@code{ada-next-procedure}).
1142 @findex ada-previous-procedure
1143 Move to previous function/procedure/task
1144 (@code{ada-previous-procedure}).
1145 @item M-x ada-next-package
1146 @findex ada-next-package
1147 Move to next package.
1148 @item M-x ada-previous-package
1149 @findex ada-previous-package
1150 Move to previous package.
1152 @findex ada-move-to-start
1153 Move to matching start of @code{end} (@code{ada-move-to-start}). If
1154 point is at the end of a subprogram, this command jumps to the
1155 corresponding @code{begin} if the user option
1156 @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
1157 the subprogram declaration.
1159 @findex ada-move-to-end
1160 Move point to end of current block (@code{ada-move-to-end}).
1162 Switch between corresponding spec and body file
1163 (@code{ff-find-other-file}). If point is in a subprogram, position
1164 point on the corresponding declaration or body in the other file.
1166 @findex ada-goto-declaration
1167 Move from any reference to its declaration, for from a declaration to
1168 its body (for procedures, tasks, private and incomplete types).
1170 @findex ada-find-references
1171 Runs the @file{gnatfind} command to search for all references to the
1172 identifier surrounding point (@code{ada-find-references}). Use
1173 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1174 compilation errors).
1177 If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
1178 will try to run GNAT for you whenever cross-reference information is
1179 needed, and is older than the current source file.
1181 @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
1182 @chapter Identifier completion
1184 Emacs and Ada mode provide two general ways for the completion of
1185 identifiers. This is an easy way to type faster: you just have to type
1186 the first few letters of an identifiers, and then loop through all the
1187 possible completions.
1189 The first method is general for Emacs. It works by parsing all open
1190 files for possible completions.
1192 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
1193 are the only words starting with @samp{my} in any of the opened files,
1194 then you will have this scenario:
1197 You type: my@key{M-/}
1198 Emacs inserts: @samp{my_identifier}
1199 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
1200 @samp{my_subprogram}.
1201 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
1204 This is a very fast way to do completion, and the casing of words will
1207 The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
1208 compiler. Emacs will search the cross-information for possible
1211 The main advantage is that this completion is more accurate: only
1212 existing identifier will be suggested.
1214 On the other hand, this completion is a little bit slower and requires
1215 that you have compiled your file at least once since you created that
1220 @findex ada-complete-identifier
1221 Complete current identifier using cross-reference information.
1223 Complete identifier using buffer information (not Ada-specific).
1226 @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
1227 @chapter Automatic Smart Indentation
1229 Ada mode comes with a full set of rules for automatic indentation. You
1230 can also configure the indentation, via the following variables:
1233 @item @code{ada-broken-indent} (default value: 2)
1234 Number of columns to indent the continuation of a broken line.
1236 @item @code{ada-indent} (default value: 3)
1237 Number of columns for default indentation.
1239 @item @code{ada-indent-record-rel-type} (default value: 3)
1240 Indentation for @code{record} relative to @code{type} or @code{use}.
1242 @item @code{ada-indent-return} (default value: 0)
1243 Indentation for @code{return} relative to @code{function} (if
1244 @code{ada-indent-return} is greater than 0), or the open parenthesis
1245 (if @code{ada-indent-return} is negative or 0). Note that in the second
1246 case, when there is no open parenthesis, the indentation is done
1247 relative to @code{function} with the value of @code{ada-broken-indent}.
1249 @item @code{ada-label-indent} (default value: -4)
1250 Number of columns to indent a label.
1252 @item @code{ada-stmt-end-indent} (default value: 0)
1253 Number of columns to indent a statement @code{end} keyword on a separate line.
1255 @item @code{ada-when-indent} (default value: 3)
1256 Indentation for @code{when} relative to @code{exception} or @code{case}.
1258 @item @code{ada-indent-is-separate} (default value: t)
1259 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
1261 @item @code{ada-indent-to-open-paren} (default value: t)
1262 Non-@code{nil} means indent according to the innermost open parenthesis.
1264 @item @code{ada-indent-after-return} (default value: t)
1265 Non-@code{nil} means that the current line will also be re-indented
1266 before inserting a newline, when you press @key{RET}.
1269 Most of the time, the indentation will be automatic, i.e when you
1270 press @key{RET}, the cursor will move to the correct column on the
1273 You can also indent single lines, or the current region, with @key{TAB}.
1275 Another mode of indentation exists that helps you to set up your
1276 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
1281 Reindent the current line, as @key{TAB} would do.
1283 Temporarily move the cursor to a reference line, i.e., the line that
1284 was used to calculate the current indentation.
1286 Display in the message window the name of the variable that provided
1287 the offset for the indentation.
1290 The exact indentation of the current line is the same as the one for the
1291 reference line, plus an offset given by the variable.
1295 Indent the current line or the current region.
1297 Indent lines in the current region.
1299 Indent the current line and display the name of the variable used for
1303 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
1304 @chapter Formatting Parameter Lists
1308 @findex ada-format-paramlist
1309 Format the parameter list (@code{ada-format-paramlist}).
1312 This aligns the declarations on the colon (@samp{:}) separating
1313 argument names and argument types, and aligns the @code{in},
1314 @code{out} and @code{in out} keywords.
1316 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
1317 @chapter Automatic Casing
1319 Casing of identifiers, attributes and keywords is automatically
1320 performed while typing when the variable @code{ada-auto-case} is set.
1321 Every time you press a word separator, the previous word is
1322 automatically cased.
1324 You can customize the automatic casing differently for keywords,
1325 attributes and identifiers. The relevant variables are the following:
1326 @code{ada-case-keyword}, @code{ada-case-attribute} and
1327 @code{ada-case-identifier}.
1329 All these variables can have one of the following values:
1333 The word will be lowercase. For instance @code{My_vARIable} is
1334 converted to @code{my_variable}.
1337 The word will be uppercase. For instance @code{My_vARIable} is
1338 converted to @code{MY_VARIABLE}.
1340 @item ada-capitalize-word
1341 The first letter and each letter following an underscore (@samp{_})
1342 are uppercase, others are lowercase. For instance @code{My_vARIable}
1343 is converted to @code{My_Variable}.
1345 @item ada-loose-case-word
1346 Characters after an underscore @samp{_} character are uppercase,
1347 others are not modified. For instance @code{My_vARIable} is converted
1348 to @code{My_VARIable}.
1351 Ada mode allows you to define exceptions to these rules, in a file
1352 specified by the variable variable @code{ada-case-exception-file}
1353 (default @file{~/.emacs_case_exceptions}). Each line in this file
1354 specifies the casing of one word or word fragment. Comments may be
1355 included, separated from the word by a space.
1357 If the word starts with an asterisk (@key{*}), it defines the casing
1358 af a word fragemnt (or ``substring''); part of a word between two
1359 underscores or word boundary.
1364 DOD Department of Defense
1366 GNAT The GNAT compiler from Ada Core Technologies
1369 The word fragment @code{*IO} applies to any word containing ``_io'';
1370 @code{Text_IO}, @code{Hardware_IO}, etc.
1372 @findex ada-create-case-exception
1373 There are two ways to add new items to this file: you can simply edit
1374 it as you would edit any text file. Or you can position point on the
1375 word you want to add, and select menu @samp{Ada | Edit | Create Case
1376 Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
1377 The word will automatically be added to the current list of exceptions
1380 To define a word fragment case exception, select the word fragment,
1381 then select menu @samp{Ada | Edit | Create Case Exception Substring}.
1383 It is sometimes useful to have multiple exception files around (for
1384 instance, one could be the standard Ada acronyms, the second some
1385 company specific exceptions, and the last one some project specific
1386 exceptions). If you set up the variable @code{ada-case-exception-file}
1387 as a list of files, each of them will be parsed and used in your emacs
1388 session. However, when you save a new exception through the menu, as
1389 described above, the new exception will be added to the first file in
1394 @findex ada-adjust-case-buffer
1395 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
1397 Create a new entry in the exception dictionary, with the word under
1398 the cursor (@code{ada-create-case-exception})
1400 @findex ada-case-read-exceptions
1401 Rereads the exception dictionary from the file
1402 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
1405 @node Statement Templates, Comment Handling, Automatic Casing, Top
1406 @chapter Statement Templates
1408 Templates are defined for most Ada statements, using the Emacs
1409 ``skeleton'' package. They can be inserted in the buffer using the
1414 @findex ada-exception-block
1415 exception Block (@code{ada-exception-block}).
1418 case (@code{ada-case}).
1420 @findex ada-declare-block
1421 declare Block (@code{ada-declare-block}).
1424 else (@code{ada-else}).
1426 @findex ada-for-loop
1427 for Loop (@code{ada-for-loop}).
1430 Header (@code{ada-header}).
1435 @findex ada-package-body
1436 package Body (@code{ada-package-body}).
1439 loop (@code{ada-loop}).
1441 @findex ada-subprogram-body
1442 subprogram body (@code{ada-subprogram-body}).
1444 @findex ada-task-body
1445 task Body (@code{ada-task-body}).
1448 while Loop (@code{ada-while}).
1451 use (@code{ada-use}).
1454 exit (@code{ada-exit}).
1457 array (@code{ada-array}).
1460 elsif (@code{ada-elsif}).
1462 @findex ada-function-spec
1463 function Spec (@code{ada-function-spec}).
1465 @findex ada-package-spec
1466 package Spec (@code{ada-package-spec}).
1468 @findex ada-procedure-spec
1469 procedure Spec (@code{ada-package-spec}.
1472 record (@code{ada-record}).
1475 subtype (@code{ada-subtype}).
1477 @findex ada-task-spec
1478 task Spec (@code{ada-task-spec}).
1481 with (@code{ada-with}).
1484 private (@code{ada-private}).
1487 when (@code{ada-when}).
1489 @findex ada-exception
1490 exception (@code{ada-exception}).
1493 type (@code{ada-type}).
1496 @node Comment Handling, GNU Free Documentation License, Statement Templates, Top
1497 @chapter Comment Handling
1499 By default, comment lines get indented like Ada code. There are a few
1500 additional functions to handle comments:
1504 Start a comment in default column.
1506 Continue comment on next line.
1508 Comment the selected region (add -- at the beginning of lines).
1510 Uncomment the selected region
1512 autofill the current comment.
1515 @node GNU Free Documentation License, Index, Comment Handling, Top
1516 @appendix GNU Free Documentation License
1517 @include doclicense.texi
1519 @node Index, , GNU Free Documentation License, Top
1528 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e