1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/ada-mode
6 Copyright @copyright{} 1999 - 2014 Free Software Foundation, Inc.
9 Permission is granted to copy, distribute and/or modify this document
10 under the terms of the GNU Free Documentation License, Version 1.3 or
11 any later version published by the Free Software Foundation; with no
12 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
13 and with the Back-Cover Texts as in (a) below. A copy of the license
14 is included in the section entitled ``GNU Free Documentation License''.
16 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
17 modify this GNU manual. Buying copies from the FSF supports it in
18 developing GNU and promoting software freedom.''
22 @dircategory Emacs editing modes
24 * Ada mode: (ada-mode). Emacs mode for editing and navigating Ada code.
29 @title Ada Mode Version 5.1.6
31 @vskip 0pt plus 1filll
37 @node Top, Overview, (dir), (dir)
45 * Installation:: Installing Ada mode on your system
46 * Customization:: Setting up Ada mode to your taste
47 * Compiling Executing:: Working with your application within Emacs
48 * Project files:: Describing the organization of your project
49 * Moving Through Ada Code:: Moving easily through Ada sources
50 * Identifier completion:: Finishing words automatically
51 * Indentation:: Indenting your code automatically as you type
52 * Statement skeletons:: Some code is written for you
53 * Aligning code:: Making it pretty
54 * Automatic casing:: Adjusting the case of words automatically
55 * Comment Handling:: Reformatting comments easily
57 * Developer overview::
58 * GNU Free Documentation License::
62 @node Overview, Installation, Top, Top
65 The Emacs mode for programming in Ada helps the user in reading
66 existing code and facilitates developing new code.
68 Cross-reference information output by the compiler is used to provide
69 powerful code navigation (jump to definition, find all uses, etc).
71 When you open a file with a file extension of @file{.ads} or
72 @file{.adb}, Emacs will automatically load and activate Ada
75 Ada mode works without any customization, if you are using the GNAT
76 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
79 You must customize a few things if you are using a different file
80 naming convention or compiler; @xref{Non-standard file names},
81 @xref{Other compiler}.
83 In addition, you may want to customize the indentation,
84 capitalization, and other things; @xref{Other customization}.
86 Finally, for large Ada projects, you will want to set up an Emacs Ada
87 mode project file for each project; @xref{Project files}. Note that
88 these are different from the GNAT project files used by the GNAT
91 @xref{Debuggers,,Debuggers,emacs,Emacs User Guide}, for general
92 information on debugging.
94 @node Installation, Customization, Overview, Top
97 Ada mode requires Emacs 24.2 or greater; it also requires the Emacs
98 lisp sources (not just the compiled binaries).
100 Ada mode is distributed in the Gnu ELPA package archive; it can be
101 installed via @code{M-x list-packages} (@pxref{Packages,,,emacs,Emacs
102 User Guide}). You must first enable packages in your @file{~/.emacs},
103 @emph{after} customizing @code{Info-default-directory-list} (if you do
110 Ada mode is also available as a separate distribution, from the Emacs
112 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}.
114 For installing the separate distribution, see the @file{README} file
117 To see what version of Ada mode you have installed, invoke @kbd{M-x
120 You may also want to install additional utilities:
123 * Ada Reference Manual::
129 @node Ada Reference Manual
130 @section Ada Reference Manual
131 The ELPA package ada-ref-man includes the Ada Reference Manual and
132 Annotated Ada Reference Manual in info format.
134 @node gnatinspect, gpr_query, Installation, Installation
136 Ada mode has experimental support for the new AdaCore cross reference
137 tool @code{gnatinspect}, which supports Ada, C, C++, and any other
138 language for which gcc provices the @code{-fdump-xref}.
140 @code{gnatinspect} is distributed as part of @code{gnatcoll}. Ada mode
141 requires the very latest version, in @code{gnatcoll 1.7w} distributed
144 To build @code{gnatinspect}, assuming GNAT GPL 2014 is installed in
145 @file{/usr/gnat-gpl-2014}, and @file{/usr/gnat-gpl-2014/bin} is in
149 tar xf ~/Downloads/gnatcoll-1.7x-src.tgz
151 ./configure --prefix=/usr/gnat-gpl-2014
152 make Gnatcoll_Build=Debug
153 sudo make Gnatcoll_Build=Debug install
156 To build an sqlite3 executable that is compatible with the database
157 created by gnatinspect:
160 cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
161 gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
164 @node gpr_query, Upgrading, gnatinspect, Installation
166 @file{gpr_query} is similar to @file{gnatinspect}, but customized for
167 Emacs ada-mode use. To install it, install @file{gnatinspect} as above
168 (@ref{gnatinspect}), then:
171 cd ~/.emacs.d/elpa/ada-mode-5.xx/build
172 make install-gpr_query
175 @node Upgrading, , gpr_query, Installation
176 @section Upgrading from previous versions
178 See the file NEWS for more details; here we summarize only important
179 user interface changes.
186 There are many user interface and API changes between 4.01 and 5.0.1;
187 we only document those that may be hard to diagnose here.
189 @code{prog-mode-hook} is no longer run by @code{ada-mode};
190 @code{ada-mode} is no longer derived from @code{prog-mode}. Use
191 @code{ada-mode-hook} instead.
196 @node Customization, Compiling Executing, Installation, Top
197 @chapter Customizing Ada mode
199 Here we assume you are familiar with setting variables in Emacs,
200 either thru 'customize' or in elisp (in your @file{.emacs} file). For
201 a basic introduction to customize, elisp, and Emacs in general, see
202 the tutorial (@kbd{C-h t}).
205 * Non-standard file names::
207 * Other cross-reference::
208 * Other customization::
211 @node Non-standard file names, Other compiler, Customization, Customization
212 @section Non-standard file names
214 By default, Ada mode is configured to use the GNAT file naming
215 convention, where file names are a simple modification of the Ada
216 names, and the extension for specs and bodies are
217 @samp{.ads} and @samp{.adb}, respectively.
219 Emacs uses the file extension to enable Ada mode; Ada mode uses the
220 file extentions to allow moving from a package body to the
221 corresponding spec and back.
223 Emacs and Ada mode support ways to use alternative file extensions for
224 specs and bodies. Note that you must also tell the compiler about
225 these extensions; doing that is beyond the scope of this manual.
227 For instance, if your spec and bodies files are called
228 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
229 can add the following to your @file{.emacs} file:
232 ;; Tell Ada mode about spec and body extensions
233 (ada-add-extensions "_s.ada" "_b.ada")
235 ;; Tell Emacs to use Ada mode for those extensions
236 (add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
239 You can define additional extensions:
242 (ada-add-extensions ".ads" "_b.ada")
243 (ada-add-extensions ".ads" ".body")
246 This means that whenever Ada mode looks for the body for a file
247 whose extension is @file{.ads}, it will take the first available file
248 that ends with either @file{.adb}, @file{_b.ada} or
251 Simililarly, if Ada mode is looking for a spec, it will look for
252 @file{.ads} or @file{_s.ada}.
254 If the filename excluding the extension is not derived from the Ada
255 name following the GNAT convention, you need to provide an alternate
256 function for @code{ada-file-name-from-ada-name}. Doing that is beyond
257 the scope of this manual; see the current definitions in
258 @file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.
260 @node Other compiler, Other cross-reference, Non-standard file names, Customization
261 @section Other compiler
262 The project variable @code{ada_compiler} (default elisp variable
263 @code{ada-compiler}) is used to index several variables that point to
264 the compiler-specific functions for corresponding Ada mode operations.
266 To use a compiler other than GNAT, you must write Emacs lisp code that
267 provides the interface to the compiler, and set @code{ada-compiler} and
268 the indirection variables.
270 See @file{ada-gnat-compile.el} for an example.
272 @node Other cross-reference, Other customization, Other compiler, Customization
273 @section Other cross-reference
274 The project variable @code{ada_xref} (default elisp variable
275 @code{ada-xref-tool}) is used to index several variables that point to
276 the cross-reference-tool-specific functions for corresponding Ada mode
279 The default cross-reference tool is @file{gnatxref}, provided by the
280 file @file{ada-gnat-xref.el}. Two other tools are supported:
281 @file{gnat_inspect} and @file{gpr_query}. To use these, add one of the
282 following to @file{~/.emacs}:
285 (require 'gnat-inspect)
289 To use @file{gpr_query}, the Ada code @file{gpr_query.adb} must be
290 compiled; see @ref{Installation}.
292 To use a cross reference tool other than the above, you must write
293 Emacs lisp code that provides the interface to the compiler, and set
294 @code{ada-xref-tool} and the indirection variables.
296 See @file{ada-gnat-xref.el}, @file{gnat-inspect.el},
297 @file{gpr-query.el} for examples.
299 @node Other customization, , Other cross-reference, Customization
300 @section Other customization
302 All user-settable Ada mode variables can be set via the menu
303 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
306 To modify a specific variable, you can directly call the function
307 @code{customize-variable}; just type @kbd{M-x customize-variable
308 @key{RET} @var{variable-name} @key{RET}}).
310 Alternately, you can specify variable settings in the Emacs
311 configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
312 and the syntax to set a variable is the following:
314 (setq variable-name value)
317 Some general Emacs settings that are useful for Ada files:
319 @item delete-trailing-whitespace
320 Deletes space, tab at end of line and blank lines at end of buffer.
322 Deletes tab characters that have crept into the file.
323 @item indent-tabs-mode
324 Don't insert tab characters when indenting.
325 @item copyright-update
326 Updates the copyright date in the file header comment, to the current
328 @item electric-pair-mode
329 Insert a matching right paren when you type a left paren.
331 Bind @code{hippie-expand} to a key; it expands the word before point, using
332 words from current buffer, other buffers, file names, etc; see
333 @code{hippie-expand-try-functions-list}. You can also add
334 @code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
335 which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
336 (@pxref{Statement skeletons}).
341 The above can all be set by the following code in your
342 @file{~/.emacs}. Note that some are functions are added to
343 @code{before-save-hook}; they run just before a buffer is written to
344 disk. Also, the order is important; ada-mode does not set up the
345 Ada-specific features of imenu and which-func unless they are loaded
349 (setq-default indent-tabs-mode nil)
350 (electric-pair-mode 1)
352 (require 'which-func)
354 (add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
355 (define-key ada-mode-map "\C-e" 'hippie-expand)
356 (add-hook 'ada-mode-hook
358 (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
359 (add-hook 'before-save-hook 'copyright-update nil t)
360 (add-hook 'before-save-hook
361 (lambda () (untabify (point-min) (point-max)))
365 @node Compiling Executing, Project files, Customization, Top
366 @chapter Compiling Executing
368 Ada projects can be compiled, linked, and executed using commands on
369 the Ada menu. All of these commands can be customized via a project
370 file (@pxref{Project files}), but the defaults are sufficient for using
371 the GNAT compiler for simple projects (single files, or several files
372 in a single directory).
374 For complex projects, you will want to use @code{make} or some other
375 build tool; in that case, you will need an Emacs Ada mode project file
376 to tell Emacs about the project directory tree and other settings.
380 * Compiling Examples::
384 @node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
385 @section Compile commands
387 Here are the commands for building an Ada project and running the main
390 In multi-file projects, there must be one file that is the main
391 program. That is given by the @code{main} project file variable;
392 it defaults to the current file if not yet set, but is also set by the
393 ``set main and build'' command.
394 @c IMPROVEME: get main from gpr via gnatinspect? not in gnatcoll 1.6w
399 Compiles the current file in syntax check mode, by running
400 @code{check_cmd} defined in the current project file. This typically
401 runs faster than full compile mode, speeding up finding and fixing
404 This sets @code{main} only if it has not been set yet.
407 Compiles the current file, by running @code{comp_cmd} from the current
410 This does not set @code{main}.
412 @item Set main and Build
413 Sets @code{main} to the current file, then executes the Build
417 Display @code{main} in the message buffer.
420 Compiles all obsolete units of the current @code{main}, and links
421 @code{main}, by running @code{make_cmd} from the current project.
423 This sets @code{main} only if it has not been set yet.
426 Executes the main program in a shell, displayed in a separate Emacs
427 buffer. This runs @code{run_cmd} from the current project. The
428 execution buffer allows for interactive input/output.
430 To modify the run command, in particular to provide or change the
431 command line arguments, type @kbd{C-u} before invoking the command.
433 This command is not available for a cross-compilation toolchain.
436 It is important when using these commands to understand how
437 @code{main} is used and changed.
439 Build runs 'gnatmake' on the main unit. During a typical edit/compile
440 session, this is the only command you need to invoke, which is why it
441 is bound to @kbd{C-c C-c}. It will compile all files needed by the
442 main unit, and display compilation errors in any of them.
444 Note that Build can be invoked from any Ada buffer; typically you will
445 be fixing errors in files other than the main, but you don't have to
446 switch back to the main to invoke the compiler again.
448 Novices and students typically work on single-file Ada projects. In
449 this case, @kbd{C-c C-m} will normally be the only command needed; it
450 will build the current file, rather than the last-built main.
452 There are three ways to change @code{main}:
456 Invoke @samp{Ada | Set main and Build}, which sets @code{main} to
460 Invoke @samp{Ada | Project | Edit}, edit @code{main} and
461 @code{main}, and click @samp{[save]}
464 Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main}
468 @node Compiling Examples, Compiler errors, Compile commands, Compiling Executing
469 @section Compiling Examples
471 We present several small projects, and walk thru the process of
472 compiling, linking, and running them.
474 The first example illustrates more Ada mode features than the others;
475 you should work thru that example before doing the others.
477 All of these examples assume you are using GNAT.
479 The source for these examples is available on the Emacs Ada mode
480 website mentioned in @xref{Installation}.
483 * No project files:: Just menus
484 * Set compiler options:: A basic Ada mode project file
485 * Set source search path:: Source in multiple directories
486 * Use GNAT project file::
487 * Use multiple GNAT project files::
491 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
492 @subsection No project files
493 This example uses no project files.
495 First, create a directory @file{Example_1}, containing:
503 Put_Line("Hello from hello.adb");
507 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
508 compiler error handling.
510 @file{hello_2.adb} has no errors:
520 @file{hello_pkg.ads} has no errors:
528 @file{hello_pkg.adb}:
535 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
540 Yes, this is missing the keyword @code{body}; another compiler error
541 example. However, note that the indentation engine parser accepts this
542 code with no errors, making it easier to indent slightly illegal Ada
545 In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
546 Check syntax}. You should get a @code{*compilation*} buffer containing
547 something like (the directory paths will be different):
550 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
551 Compilation started at Fri Oct 18 04:23:54
553 gnatmake -u -c -gnatc c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
554 gcc -c -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/ -gnatc -I- c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb
555 hello.adb:4:04: "Put_Line" is not visible
556 hello.adb:4:04: non-visible declaration at a-textio.ads:263
557 hello.adb:4:04: non-visible declaration at a-textio.ads:259
558 gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error
560 Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
563 The lines with actual errors (starting with @file{hello.adb}) are
564 highlighted, with the file name in red.
566 Now invoke @samp{Ada | Build | Next compilation error}. Or you can
567 click the middle mouse button on the first error line, or use the key
568 binding shown on the menu. The compilation buffer scrolls to put the
569 first error on the top line, and point is put at the place of the
570 error in the @file{hello.adb} buffer.
572 To fix the error, invoke @samp{Ada | Build | Fix compilation error};
573 this adds ``Ada.Text_Io.'' to the line:
576 Ada.Text_Io.Put_Line ("hello from hello.adb");
579 Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.
581 Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
582 prompted to save the file (if you haven't already). Then the
583 compilation buffer is displayed again, containing:
586 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
587 Compilation started at Fri Oct 18 20:39:33
589 gnatmake -o hello hello -cargs -bargs -largs
591 gnatbind -x hello.ali
592 gnatlink hello.ali -o hello.exe
594 Compilation finished at Fri Oct 18 20:39:34
597 The compilation has succeeded without errors; @file{hello.exe} now
598 exists in the same directory as @file{hello.adb}.
600 Now invoke @samp{Ada | Build | Run}. The @file{*compilation*} buffer
601 is displayed, containing
604 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
605 Compilation started at Fri Oct 18 20:41:53
610 Compilation finished at Fri Oct 18 20:41:53
613 That completes the first part of this example.
615 Now we will compile a multi-file project. Open the file
616 @file{hello_2.adb}, invoke @samp{Ada | Build | Set main and
617 Build}. This finds an error in @file{hello_pkg.adb}:
620 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
623 This demonstrates that gnatmake finds the files needed by the main
624 program. However, it cannot find files in a different directory,
625 unless you use an Emacs Ada mode project file or a GNAT project file
626 to specify the other directories; @xref{Set source search path},
627 @ref{Use GNAT project file}.
629 Invoke @samp{Ada | Build | Show main}; this displays @file{Ada mode
632 Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}:
635 package body Hello_Pkg is
638 Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build |
639 Build}. gnatmake successfully builds @file{hello_2}. This
640 demonstrates that Emacs has remembered the main file, in the project
641 variable @code{main}, and used it for the Build command.
643 Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Build
644 | Run}. The @code{*compilation*} buffer displays @code{Hello from
647 One final point. If you switch back to buffer @file{hello.adb}, and
648 invoke @samp{Ada | Build | Run}, @file{hello_2.exe} will be run. That
649 is because @code{main} is still set to @code{hello_2}, as you can see
650 when you invoke @samp{Ada | Build | Show main}.
652 There are two ways to change @code{main}:
656 Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
660 Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
661 specifies @code{main}.
665 @node Set compiler options, Set source search path, No project files, Compiling Examples
666 @subsection Set compiler options
668 This example illustrates using an Emacs Ada mode project file to set a
671 If you have files from @file{Example_1} open in Emacs, you should
672 close them so you don't get confused. Use menu @samp{File | Close
675 In directory @file{Example_2}, create these files:
683 Put_Line("Hello from hello.adb");
687 This is the same as @file{hello.adb} from @file{Example_1}. It has two
688 errors; missing ``use Ada.Text_IO;'', and no space between
689 @code{Put_Line} and its argument list.
697 This tells the GNAT compiler to check for token spacing; in
698 particular, there must be a space preceding a parenthesis.
700 In buffer @file{hello.adb}, invoke @samp{Ada | Build | Set main and
701 Build}. This finds the project file @file{hello.adp}, uses it to set
702 the compiler options, and builds the project. You should get a
703 @code{*compilation*} buffer containing something like (the directory
704 paths will be different):
707 cd c:/Examples/Example_2/
708 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
709 gcc -c -g -gnatyt hello.adb
710 hello.adb:4:04: "Put_Line" is not visible
711 hello.adb:4:04: non-visible declaration at a-textio.ads:264
712 hello.adb:4:04: non-visible declaration at a-textio.ads:260
713 hello.adb:4:12: (style) space required
714 gnatmake: "hello.adb" compilation error
717 Compare this to the compiler output in @ref{No project files}; the
718 gnatmake option @code{-cargs} has been replaced by @code{-cargs
719 -gnaty}, and an additional error is reported in @file{hello.adb} on
720 line 4. This shows that @file{hello.adp} is being used to set the
723 Fixing the error, linking and running the code proceed as in @ref{No
726 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
727 @subsection Set source search path
729 In this example, we show how to deal with files in more than one
730 directory, using an Emacs Ada mode project file to set the search
733 Create the directory @file{Example_3}, containing:
735 @file{hello_pkg.ads}:
743 @file{hello_pkg.adb}:
750 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
755 These are the same files from example 1; @file{hello_pkg.adb} has an
758 In addition, create a directory @file{Example_3/Other}, containing these files:
760 @file{Other/hello_3.adb}:
764 with Ada.Text_IO; use Ada.Text_IO;
768 Put_Line ("From hello_3");
772 There are no errors in this file.
774 @file{Other/other.adp}:
780 Note that there must be no trailing spaces.
782 In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
783 set project...}, and select @file{Example_3/Other/other.adp}. This
784 tells Emacs Ada mode to stop using the project file from
785 @file{Example_2}, and use the one for @file{Example_3}. Also note that
786 since this project file is not named @file{hello_3.adp}, it would not
789 Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
790 Build}. You should get a @code{*compilation*} buffer containing
791 something like (the directory paths will be different):
794 cd c:/Examples/Example_3/Other/
795 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
796 gcc -c -g -I.. hello_3.adb
797 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
798 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
799 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
802 Compare the @code{-cargs} option to the compiler output in @ref{Set
803 compiler options}; this shows that @file{other.adp} is being used to
804 set the compiler options.
806 Move to the error with @kbd{C-x `}. Ada mode searches the list of
807 directories given by @code{src_dir} for the file mentioned in the
808 compiler error message.
810 Fixing the error, linking and running the code proceed as in @ref{No
813 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
814 @subsection Use GNAT project file
816 In this example, we show how to use a GNAT project file, with no Ada
819 Create the directory @file{Example_4}, containing:
821 @file{hello_pkg.ads}:
829 @file{hello_pkg.adb}:
836 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
841 These are the same files from example 1; @file{hello_pkg.adb} has an
844 In addition, create a directory @file{Example_4/Gnat_Project},
845 containing these files:
847 @file{Gnat_Project/hello_4.adb}:
851 with Ada.Text_IO; use Ada.Text_IO;
855 Put_Line ("From hello_4");
859 There are no errors in this file.
861 @file{Gnat_Project/hello_4.gpr}:
865 for Source_Dirs use (".", "..");
869 In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and
870 select @file{Example_4/Gnat_Project/hello_4.gpr}.
872 Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and
873 Build}. You should get a @code{*compilation*} buffer containing
874 something like (the directory paths will be different):
877 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
878 Compilation started at Mon Oct 21 11:28:31
880 gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/hello_4.gpr -o hello_4 hello_4 -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -bargs -largs
881 gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
882 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
883 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
885 Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
888 Compare the @code{gcc} options to the compiler output in @ref{Set
889 compiler options}; this shows that @file{hello_4.gpr} is being used to
890 set the compiler options.
892 Fixing the error, linking and running the code proceed as in @ref{No
895 @node Use multiple GNAT project files, Use a Makefile, Use GNAT project file, Compiling Examples
896 @subsection Use multiple GNAT project files
898 In this example, we show how to use multiple GNAT project files,
899 specifying the GNAT project search path in an Ada mode project file.
901 Create the directory @file{Example_4} as specified in @ref{Use GNAT
904 Create the directory @file{Example_5}, containing:
910 with Ada.Text_IO; use Ada.Text_IO;
914 Put_Line ("From hello_5");
918 There are no errors in this file.
923 ada_project_path=../Example_4/Gnat_Project
932 for Source_Dirs use (".");
934 for Default_Switches ("Ada") use ("-g", "-gnatyt");
939 In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Find and
940 select project...}, and select @file{Example_5/hello_5.adp}. This
941 would also be found by default if no previous project file had been
944 Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
945 and Build}. You should get a @code{*compilation*} buffer containing
946 something like (the directory paths will be different):
949 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
950 Compilation started at Mon Oct 21 11:32:05
952 gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/hello_5.gpr -o hello_5 hello_5 -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -bargs -largs
953 gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
954 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
955 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
957 Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
960 Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
961 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
962 used to set the compilation search path.
964 @node Use a Makefile, , Use multiple GNAT project files, Compiling Examples
965 @subsection Use a Makefile
967 In this example, we show how to use a Makefile to build an Ada project
968 with GNAT, run the result, and clean the build directories.
970 Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
971 project file}, @ref{Use multiple GNAT project files}.
973 In @file{Example_5}, add the file:
978 # build and run hello_5 project
985 gprbuild -Phello_5.gpr hello_5
991 gnatclean -r -Phello_5
993 export GPR_PROJECT_PATH = ../Example_4/Gnat_Project
996 # eval:(ada-parse-prj-file "hello_5.adp")
997 # eval:(ada-select-prj-file "hello_5.adp")
1001 Close and re-open @file{Makefile}; the @samp{Local Variables} section
1002 sets the project file to @file{hello_5.adp} when the @file{Makefile}
1003 is opened. You can also use @key{C-x C-e} to execute the select line
1004 after the @file{Makefile} is opened, to change the project file back
1005 to @file{hello_5.adp}.
1007 In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
1008 default make command. This runs the @samp{all} target, which builds
1009 @file{hello_5} and runs it.
1011 @node Compiler errors, , Compiling Examples, Compiling Executing
1012 @section Compiler errors
1014 The @code{Check syntax} and @code{Build} commands, or running
1015 @code{make}, place compilation errors in a separate buffer named
1016 @code{*compilation*}.
1018 Each line in this buffer will become active: you can simply click on
1019 it with the middle button of the mouse, or move point to it and press
1020 @key{RET}. Emacs will then display the relevant source file and put
1021 point on the line and column where the error was found.
1023 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
1024 will jump to the first error. If you press that key again, it will
1025 move you to the second error, and so on.
1027 Some error messages also include references to other files. These
1028 references are accessed via @kbd{C-c `}.
1030 @node Project files, Moving Through Ada Code, Compiling Executing, Top
1031 @chapter Project files
1033 An Emacs Ada mode project file specifies what directories hold sources
1034 for your project, and allows you to customize the compilation commands
1035 and other things on a per-project basis.
1037 The default file extension for Ada mode project files is @file{*.adp}
1038 or @file{*.prj}. You can use a different extension by adding it to
1039 @code{ada-prj-file-extensions}, and a different syntax by adding a
1040 parser function to @code{ada-prj-parser-alist}.
1042 Note that Ada mode project files @file{*.adp} are different than GNAT
1043 compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
1044 GNAT project file to specify the project directories. If no
1045 other customization is needed, a GNAT project file can be used without
1046 an Emacs Ada mode project file.
1048 If no Emacs Ada mode project file is specified, some Ada mode
1049 functions are not available.
1052 * Project file overview::
1053 * Project file variables::
1056 @node Project file overview, Project file variables, Project files, Project files
1057 @section Project file overview
1059 Project files have a simple syntax; they may be edited directly. Each
1060 line specifies a project variable name and its value, separated by
1061 ``='' (spaces not allowed):
1063 src_dir=/Projects/my_project/src_1
1064 src_dir=/Projects/my_project/src_2
1067 Any line that does not have an ``='' is a comment.
1069 Some variables (like @code{src_dir}) are lists; multiple occurrences
1072 There must be no space between the variable name and ``='', and no
1075 The current project file is given by the lisp variable
1076 @code{ada-prj-default-project-file}, and shown by the menu command
1077 @key{Ada | Project Files | Show project}.
1079 To set the project file, use the menu command @samp{Ada | Set Project
1080 ...}, or the elisp functions @code{ada-parse-prj-file,
1081 ada-select-prj-file}. The latter can be added to a Makefile:
1085 # eval: (ada-parse-prj-file "ada-mode.prj")
1086 # eval: (ada-select-prj-file ada-mode.prj")
1090 You specify either a GNAT project file or an Emacs Ada mode project
1091 file; if the file extension is @code{.gpr}, the file is treated as a
1092 GNAT project file. Extensions given by @code{ada-prj-file-extensions}
1093 (default @file{.adp, .prj}) are treated as an Emacs Ada mode
1096 After a project file is parsed, you can make it current again with
1097 just @code{ada-select-prj-file}, or by selecting it from the menu.
1099 @node Project file variables, , Project file overview, Project files
1100 @section Project file variables
1102 To set a project variable that is a list, specify each element of the
1103 list on a separate line in the project file.
1105 Process environment variables can be referenced using the
1106 normal @code{$var} syntax.
1108 Most project variables have defaults that can be changed by setting
1109 elisp variables; the table below identifies the elisp variable for each
1110 project variable. Elisp variables corresponding to project variables
1111 that are lists are elisp lists.
1113 In general, project variables are evaluated when referenced in Emacs
1114 Ada mode commands. Relative file paths are expanded relative to the
1115 directory containing the project file.
1117 Ada mode defines some project variables; others are defined by the
1120 Here is the list of variables valid for all compilers. In the default
1121 values, the current directory @code{"."} is the directory containing
1125 @c These are the names that appear in the .adp file, which are the
1126 @c same as the symbols used with ada-prj-get
1128 @c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
1129 @c defaults defined in ada-mode.el ada-prj-default
1131 @item @code{ada_compiler} [default: @code{ada-compiler, gnat}]
1132 Ada compiler for this project. It must occur in the project file
1133 before any compiler-specific project variable.
1135 @item @code{auto_case} [default: @code{ada-auto-case, t}]
1136 Non-nil means automatically change case of preceding word while typing.
1138 @item @code{case_identifier} [default: @code{ada-case-identifier, ada-mixed-case}]
1139 Function to call to adjust the case of an Ada identifier.
1141 @item @code{case_keyword} [default: @code{ada-case-keyword, downcase-word}]
1142 Function to call to adjust the case of an Ada keyword.
1144 @item @code{case_strict} [default: @code{ada-case-strict, t}]
1145 If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
1146 Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.
1148 @item @code{casing} [default: @code{ada-case-exception-file, nil}]
1149 List of files containing casing exceptions. @xref{Automatic casing}.
1151 @item @code{el_file} [default: ]
1152 The value is a file name, which is loaded as an elisp file when the
1153 project file is parsed or selected. This allows setting Ada mode indentation
1154 variables, and any arbitrary elisp code used to customize the project.
1156 @item @code{path_sep} [default: @code{path-separator}]
1157 Separator character used in compiler search paths.
1159 @item @code{src_dir} [default: @code{"."}]
1160 A list of directories to search for source files.
1162 @item @code{xref_tool} [default: @code{ada-xref-tool, gnat-xref}]
1163 Cross reference tool for this project.
1167 The following variables are valid with the GNAT compiler:
1170 @c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
1171 @item @code{ada_project_path} [default: @code{""}]
1172 @c ada-prj-get 'prj_dir, 'proc_env
1173 A list of directories to search for GNAT project files.
1175 If set, the @code{GPR_PROJECT_PATH} process environment variable is
1176 set to this value in the child process that runs GNAT tools. If not
1177 set, @code{GPR_PROJECT_PATH} in the child process is inherited from
1180 If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
1181 environment variable set in the Emacs process correctly for all of
1182 your projects, you do not need to set this project variable.
1184 The project search path can also be set in GNAT aggregate
1185 projects. However, the gnat tools do not make that path available to
1186 Emacs, so you must duplicate it in an Emacs Ada project file.
1188 @item @code{gpr_file} [default: @code{""}]
1189 The GNAT project file.
1191 If set, the source and project directories specified in the GNAT
1192 project file are appended to @code{src_dir} and
1193 @code{ada_project_path}. This allows specifying Ada source directories
1194 with a GNAT project file, and other source directories with the Emacs
1197 @item @code{gpr_project_path} [default: @code{""}]
1198 Same as @code{ada_project_path}.
1202 @node Moving Through Ada Code, Identifier completion, Project files, Top
1203 @chapter Moving Through Ada Code
1205 There are several commands to navigate through Ada code. All
1206 these functions are available through the Ada menu and keybindings.
1208 Some of these commands rely on cross reference facilities provided by
1209 the compiler; the standard Emacs Ada mode only supports the GNAT
1210 compiler, but others can be added (@pxref{Other cross-reference}).
1214 @findex ada-goto-declaration
1215 Move from any use of an identifier to its declaration, for from a declaration to
1216 its body (if there is one).
1219 @findex ada-goto-declaration-parent
1220 Move from a child type declaration to the parent type declaration;
1221 display a list of references if there is more than one parent.
1224 @findex ada-next-statement-keyword
1225 Move to the next keyword in the current statement.
1227 For example, if point is on @samp{if}, move to @samp{then}.
1230 @findex ada-prev-statement-keyword
1231 Move to the previous keyword in the current statement.
1233 For example, if point is on @samp{then}, move to @samp{if}.
1236 @findex ada-find-other-file
1237 Switch between corresponding spec and body. There are several special
1242 If the region is active, it is assumed to contain an Ada package
1243 name; position point on the corresponding package declaration.
1246 If point is in the start line of a top level child package
1247 declaration (but not package body), or a child subprogram spec or
1248 body, position point on the corresponding parent package
1252 If point is in the start line of a top level separate body,
1253 position point on the corresponding separate stub declaration.
1256 If point is in a subprogram declaration or body, position point on the
1257 corresponding body or declaration in the other file.
1260 If point is on a @code{with} clause, position point on the
1261 corresponding declaration.
1266 @findex ada-show-references
1267 Show all references to the identifier surrounding point. Use
1268 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1269 compilation errors).
1272 @findex ada-show-overriding
1273 Show all declarations that override the primitive procedure at
1274 point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
1275 for compilation errors).
1278 @findex ada-show-overridden
1279 Show the declaration that the declaration at point overrides.
1282 Jump back to the previous location.
1284 @item Ada | Misc | Refresh cross reference cache
1285 Cross reference information is loaded from the compiler output when
1286 the first cross reference command is issued. If the code is recompiled
1287 after that, the cross reference information is reloaded by invoking
1292 @node Identifier completion, Indentation, Moving Through Ada Code, Top
1293 @chapter Identifier completion
1295 Emacs provides a general way of completing identifiers: @kbd{M-/}
1296 (bound to @code{dabbrev-expand}). This is an easy way to type faster:
1297 you just have to type the first few letters of an identifier, and then
1298 loop through all the possible completions.
1300 @kbd{M-/} works by parsing all open Ada files for possible
1303 For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
1304 are the only words starting with @samp{my} in any of the open Ada files,
1305 then you will have this scenario:
1308 You type: my@kbd{M-/}
1309 Emacs inserts: @samp{my_identifier}
1310 If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
1311 @samp{my_subprogram}.
1312 Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
1315 This is a very fast way to do completion, and the casing of words will
1318 @node Indentation, Statement skeletons, Identifier completion, Top
1319 @chapter Indentation
1321 Ada mode comes with a full set of rules for automatic indentation. You
1322 can also configure the indentation, via the following variables:
1325 @item @code{ada-indent} (default value: 3)
1326 Number of columns for default indentation.
1328 @item @code{ada-indent-broken} (default value: 2)
1329 Number of columns to indent the continuation of a broken line.
1331 @item @code{ada-indent-comment-col-0} (default value: nil)
1332 If non-nil, comments currently starting in column 0 are left in column
1333 0. Otherwise, they are indented with previous comments or code.
1335 @item @code{ada-indent-label} (default value: -3)
1336 Number of columns to indent a label.
1338 @item @code{ada-indent-record-rel-type} (default value: 3)
1339 Indentation for @code{record} relative to @code{type} or @code{use}.
1341 @item @code{ada-indent-renames} (default value: 2)
1342 Indentation for @code{renames} relative to the matching subprogram keyword.
1344 If the subprogram has parameters then if @code{ada-indent-renames} is
1345 zero or less the indentation is abs @code{ada-indent-renames} relative
1346 to the open parenthesis; if @code{ada-indent-renames} is one or more
1347 the indentation is relative to the line containing the keyword.
1349 If the subprogram has no parameters then @code{ada-indent-broken} the
1350 indentation is relative to the indentation of the line containing
1353 @item @code{ada-indent-return} (default value: 0)
1354 Indentation for @code{return} relative to the matching
1357 If the function has parameters, then if @code{ada-indent-return} is
1358 zero or less the indentation is abs @code{ada-indent-return} relative
1359 to the open parenthesis; if @code{ada-indent-return} is one or more,
1360 indentation is relative to line containing @code{function}.
1362 If the function has no parameters, @code{ada-indent-broken} is used
1363 relative to line containing @code{function}.
1365 @item @code{ada-indent-use} (default value: ada-indent-broken)
1366 Indentation for the lines in a @code{use} statement.
1368 @item @code{ada-indent-when} (default value: 3)
1369 Indentation for @code{when} relative to @code{exception}, @code{case},
1370 or @code{or} in @code{select}.
1372 @item @code{ada-indent-with} (default value: ada-indent-broken)
1373 Indentation for the lines in a @code{with} context clause.
1377 The indentation variables are buffer local; the global value may be
1378 overridden in an elisp file invoked by an @code{el_file} Emacs Ada
1379 mode project file statement, or in a file local variable section.
1381 The following keys indent portions of the text:
1385 Insert and indent a new line.
1388 Indent the current line, or the current region.
1391 Indent the current statement or declaration.
1395 The indentation algorithm relies on a grammar parser to identify the
1396 syntactic role for keywords and other words in the code. If the code
1397 is accepted by the parser, the indentation is done according to the
1398 rules in the indentation engine.
1400 If the code is not accepted (because it is partially complete during
1401 editing), the indentation engine falls back to the trivial algorithm
1402 of indenting each new line the same as the previous line. Once enough
1403 new text has been entered to make the code acceptable to the parser,
1404 the statement or declaration is properly indented.
1406 For example, if you are entering this code:
1414 when you type @kbd{RET B}, @code{B} is indented to the same column as
1415 @code{if}, because the parser does not find @code{end if;}. Then when
1416 you type the final @code{;} followed by @key{TAB}, all three lines are
1417 indented, putting @code{B} where it belongs.
1419 To be more user friendly, the parser accepts a superset of the Ada
1420 grammer. For example, the parser accepts this code for an @code{if}
1428 In general, any sequence of statements, and many expressions, may be
1431 One way to easily insert empty statements like this is using
1432 @ref{Statement skeletons}.
1434 In rare cases, the parser gets confused; it can be reset by invoking
1435 menu @key{Ada | Misc | Reset parser}. Please report such cases as a
1438 @node Statement skeletons, Aligning code, Indentation, Top
1439 @chapter Statement skeletons
1441 @kbd{C-c C-e} expands the previous one or two words into a statment
1442 skeleton. For example, @kbd{i f C-c C-e} expands to:
1451 All skeleton expansions are accepted by the indentation parser, so
1452 this is a convenient way to insert statements with correct
1455 For named statements (packages, loops, etc), the name is taken from
1456 the word before point, and the name of the statement from the word
1459 Some expansions prompt for more information, such as
1460 whether a spec or body is desired. For example, @kbd{package A_Package
1461 C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
1462 selected, the following code is inserted:
1465 package A_Package is
1470 Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
1471 (without prompting) to:
1481 Note that the order of the keyword @code{declare} and the name
1482 @code{A_Block} are reversed in the expansion; this may take some
1483 getting used to. Alternately, if no name is present in the buffer, you
1484 are prompted for a name: @kbd{declare C-c C-e} first prompts for a
1485 name, then expands to the above.
1487 The variable @code{ada-skel-initial-string} defines what to insert in
1488 a newly created empty buffer. It defaults to @code{@{header@}}, which
1489 is a placeholder defined by @code{ada-skel-header}, which inserts a
1490 typical header with a copyright license (choice of GPL or
1491 restricted). Users will typically want to override the definition of
1492 @code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
1493 provide more choices of copyright license.
1495 @node Aligning code, Automatic casing, Statement skeletons, Top
1496 @chapter Aligning code
1498 Aligning code adds space in each line so that similar parts of
1499 successive lines are aligned vertically. For example, a sequence of
1504 Another : Float := 1.0;
1505 More : Integer := 2;
1508 changes to this when aligned:
1512 Another : Float := 1.0;
1513 More : Integer := 2;
1516 Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
1517 statements surrounding point, or within the selected region.
1519 Parameter lists are also aligned:
1524 Another : out Float := 1.0;
1525 More : in out Integer := 2);
1533 Another : out Float := 1.0;
1534 More : in out Integer := 2);
1537 @node Automatic casing, Comment Handling, Aligning code, Top
1538 @chapter Automatic casing
1540 Casing of identifiers, attributes and keywords is automatically
1541 performed while typing when the variable @code{ada-auto-case} is
1542 non-nil (the default). Every time you type a word separator, the
1543 previous word is automatically cased.
1545 You can customize the automatic casing with the following variables:
1548 @item ada-case-keyword
1549 Value must be one of:
1552 Ada keywords will be lowercase.
1555 Ada keywords will be uppercase.
1558 @item ada-case-strict
1559 If non-nil, all identifiers are forced to @code{Mixed_Case}; first
1560 letter, and letter following ``_'' are uppercase; rest are
1563 If nil, the mixed case characters in identifiers are forced to upper
1564 case, but the other characters are not modified. That allows typing
1565 all uppercase identifiers without defining a casing exception.
1568 You can define exceptions to these rules, in files specified by the
1569 variable @code{ada-case-exception-file}. Each line in a case exception
1570 file specifies the casing of one word or word fragment. If an
1571 exception is defined in multiple files, the first occurrence is used.
1573 If the word starts with an asterisk (@code{*}), it defines the casing
1574 of a word fragment (or ``substring''); part of a word between two
1575 underscores or word boundary.
1585 The word fragment @code{*IO} applies to any word containing ``_io'';
1586 @code{Text_IO}, @code{Hardware_IO}, etc.
1588 @findex ada-case-create-exception
1589 There are two ways to add new items to this file: you can simply edit
1590 it as you would edit any text file. Or you can position point on the
1591 word you want to add, and select menu @samp{Ada | Casing | Create full
1592 exception} or @samp{Ada | Casing | Create partial exception}. The
1593 word will be added to the current list of exceptions and to the file.
1595 It is sometimes useful to have multiple exception files. For
1596 example, one could be the standard Ada acronyms, the second some
1597 company specific exceptions, and the last one some project specific
1598 exceptions. If you set up the variable @code{ada-case-exception-file}
1599 as a list of files, each of them will be parsed and used in your emacs
1600 session. When you create a new exception, you are prompted for the
1603 Other keys and menu entries are defined:
1607 @findex ada-case-adjust-at-point
1608 Adjust case of the word at point. With prefix arg, adjust case even if
1609 in comment. Normally, comments are not affected by case adjust.
1611 @item Ada | Casing | Adjust case region
1612 Adjust case in the active region.
1614 @item Ada | Casing | Adjust case buffer
1615 Adjust case in the active buffer.
1619 @node Comment Handling, Key summary, Automatic casing, Top
1620 @chapter Comment Handling
1622 By default, comment lines get indented like Ada code. There are a few
1623 additional functions to handle comments:
1627 @findex comment-dwim
1628 If the region is active, comment or uncomment it.
1630 If the current line is empty, start a comment.
1632 Otherwise, add a comment at the end of the line, in a column given by
1633 @code{comment-column}.
1636 @findex fill-paragraph
1637 Fill the current comment paragraph.
1640 @node Key summary, Developer overview, Comment Handling, Top
1641 @chapter Key summary
1642 @c search for @kbd and @key. Alphabetical by key sequence
1644 This table summarizes the keys described in this manual. Other keys
1645 are bound by Ada mode; see @key{C-h b} for a complete list. The
1646 Ada menu also displays keys bound to menu operations.
1650 @xref{Identifier completion}.
1651 Complete the word before point; repeat to cycle thru possible
1655 @xref{Comment Handling}.
1656 If the region is active, comment or uncomment it.
1659 @xref{Comment Handling}.
1660 Fill the current comment paragraph.
1664 Insert and indent a new line.
1668 Indent the current line, or the current region.
1672 Indent the current statement or declaration.
1675 @xref{Compiler errors}.
1676 Move to the location of the secondary reference in the current compilation error.
1679 @xref{Aligning code}.
1683 @xref{Compile commands}.
1684 Build the current main program.
1687 @xref{Moving Through Ada Code}.
1688 Move from any use of an identifier to its declaration, for from a declaration to its body.
1691 @xref{Moving Through Ada Code}.
1692 Move from a child type declaration to the parent type declaration.
1695 @xref{Statement skeletons}.
1696 Expand previous one or two words into a statement or declaration
1700 @xref{Compile commands}.
1701 Build the current file.
1704 @xref{Moving Through Ada Code}.
1705 Move to the next keyword in the current statement.
1708 @xref{Moving Through Ada Code}.
1709 Switch between corresponding spec and body, or find other spec.
1712 @xref{Moving Through Ada Code}.
1713 Move to the previous keyword in the current statement.
1716 @xref{Moving Through Ada Code}.
1717 Show all references to the identifier surrounding point.
1720 @xref{Automatic casing}.
1721 Adjust case of the word at point. With prefix arg, adjust case even if
1725 @xref{Moving Through Ada Code}.
1726 Show all declarations that override the primitive procedure at
1730 @xref{Automatic casing}.
1731 Create case exception.
1734 @xref{Compiler errors}.
1735 Move to the location of the next secondary compilation error.
1738 @xref{Compiler errors}.
1739 Move to the location of the next compilation error or show result.
1742 @xref{Comment Handling}.
1743 Fill the current comment paragraph.
1747 @node Developer overview, GNU Free Documentation License, Key summary, Top
1748 @chapter Developer overview
1749 If you'd like to contribute to Ada mode, or just understand the
1750 sources, here's an overview.
1753 * Directory structure::
1754 * Package organization::
1759 @node Directory structure, Package organization, Developer overview, Developer overview
1760 @section Directory structure
1762 @item org.emacs.ada-mode
1768 Elisp files; main code.
1771 Byte-compiled elisp files, not in the distribution. Generated by the
1772 Makefile target @code{byte-compile}, or by the Emacs package installer.
1774 Compiling the parse tables (@file{*-wy.el}) speeds up loading them
1775 significantly. Compiling other files speeds up parsing, but not
1778 One reason to byte-compile files is to find errors; the byte compiler
1779 reports undefined variables, wrong argument counts, etc.
1782 Parse tables, generated from the corresponding grammar @file{*.wy} by
1783 the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
1784 distribution and the monotone repository so users and Elisp developers
1785 don't have to install OpenToken.
1788 Diagnostic output from @file{wisi-generate.exe}, useful for tracing
1789 parses while debugging a grammar issue. Not in the tarball
1790 distribution or the monotone repository.
1793 Grammar files, specifying the language to be parsed. The syntax for
1794 these grammar files is similar to that for bison and wisent, but not
1795 the same; see the OpenToken documentation for more info.
1797 The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
1798 parser, so it tolerates some conflicts and ambiguities. This makes the
1799 grammars easier to write, and in particular makes it possible to let
1800 the Ada grammar closely match Annex P of the Ada Language Reference
1801 Manual (the syntax summary).
1804 Texinfo source for the user guides.
1807 Generated user guide in HTML format.
1810 Generated user guide in Emacs info format.
1816 Makefile for building the user guides, publishing to the web page or
1817 Gnu ELPA. Test drivers.
1820 Makefile for building and testing with the wisi-based
1821 parser. Separate from @file{build}, because there used to be a
1822 SMIE-based parser, and there might be another parser someday.
1824 The emacs used to byte-compile and run tests is given by the 'make'
1825 variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
1826 the make command line or by an environment variable.
1829 All tests for Ada mode, gpr mode, parser.
1831 Each test is run in a separate invocation of Emacs, so it is
1832 completely independent of all other tests.
1834 The tests are driven by the elisp code in @file{build/*.el}.
1836 In general, the Ada mode tests open the file, execute test actions,
1837 re-indent, and re-captialize the entire file. The result is diffed
1838 with the original, and must match.
1840 The test actions are defined by comments with the prefix
1841 @code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
1842 functions. This is used to test navigation features and other parser
1845 @item test/Example_*
1846 Starting files for examples in user guide.
1852 More tests; allows testing path search features.
1855 Tests of the elisp wisi grammar compiler and parser.
1858 @node Package organization, OpenToken, Directory structure, Developer overview
1859 @section Package organization
1868 @node Ada mode, gpr mode, Package organization, Package organization
1869 @subsection Ada mode
1870 Ada mode consists of all files with @file{ada-} prefix in the file
1875 The main file, implementing the keymap, menu, and top level
1878 It allows for different backend implementations for compiling,
1879 cross-referencing, and indenting. The functions for each of these
1880 backends dispatch thru global variables that are set by Emacs Ada mode
1881 project files. They default to the GNAT compiler, the gnatxref cross
1882 reference tool, and the ada-wisi indentation engine.
1885 Provides functions for compiling Ada files without a Makefile (or
1888 @item ada-fix-error.el
1889 Provides an interface to utilities for automatically fixing errors
1890 reported by the compiler. It dispatches to a compiler-specific
1893 @item ada-gnat-compile.el
1894 Implements the Ada mode compiler functions for the GNAT compiler.
1896 @item ada-gnat-xref.el
1897 Implements the Ada mode cross reference functions for the GNAT compiler.
1900 The Ada language grammar, and files generated from it by the OpenToken
1901 tool @file{wisi-generate.exe}.
1903 @item ada-indent-user-options.el
1904 All user-settable options for the Ada indentation engine.
1906 @item ada-mode-compat-23.4.el
1907 Defines functions used by Ada mode that are not in Emacs 23.4.
1909 Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
1910 partially supported. Earlier versions of Emacs are not supported.
1913 The Ada mode user guide source and compiled versions.
1916 Skeletons for expansion of Ada syntax (@pxref{Statement
1917 skeletons}). Extends the Emacs skeleton functions with ``tokens'',
1918 inspired by the lamented Else package (which was inspired by DEC LSE).
1920 @item ada-wisi-opentoken.el
1921 Indentation functions useful when editing OpenToken code; an example
1922 of extending the Ada mode indentation engine for special
1926 Implements the Ada mode indentation functions for the wisi indentation
1931 @node gpr mode, GNAT core, Ada mode, Package organization
1932 @subsection gpr mode
1934 gpr mode consists of all files with @file{gpr-} prefix in the file
1935 name. The functions in each file are similar to the similarly-named
1938 @node GNAT core, Wisi, gpr mode, Package organization
1939 @subsection GNAT core
1943 GNAT is actually a multi-language tool; it builds on top of the
1946 @file{gnat-core.el} is a start at a language-agnostic interface to the
1947 GNAT tools. It was first factored out from @file{ada-gnat.el} and
1948 @file{ada-mode.el} to support the multi-language
1949 @file{gnat-inspect.el}, which is still experimental.
1951 More code currently in @file{ada-mode.el} could be migrated to
1952 @file{gnat-core.el}, in particular the project file support.
1954 @item gnat-inspect.el
1955 Provides an experimental interface to the experimental multi-language
1956 cross-reference tool @file{gnatinspect} from AdaCore, which will
1957 supercede @file{gnatxref}.
1959 Implements the Ada mode cross-reference functions for the
1960 @file{gnatinspect} backend, and a minor mode providing similar
1965 @node Wisi, , GNAT core, Package organization
1968 The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
1973 Implements the lexer, the main parser driver,
1974 parser actions that cache parser information in text properties,
1975 utilities for indenting and navigating using the cached information,
1978 @item wisi-compile.el
1979 Implements the parse table
1980 compiler. @file{wisi-generate.exe} processes the grammar source
1981 @file{*.wy} into an elisp source representation of a parse table
1982 @file{*-wy.el}. That is compiled into an internal structure containing
1983 the state transitions and executable actions. The actions can be any
1984 elisp form; the intent is that they be calls to the action functions
1985 provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
1986 provided by @code{semantic}.
1989 Implements the generalized LALR parser.
1992 @node OpenToken, ELPA, Package organization, Developer overview
1994 Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
1995 the grammar sources into elisp parse tables. See
1996 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
1997 current information about which version of OpenToken is required, and
2000 The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
2001 build directory for OpenToken; you probably need to override it with
2002 an external environment variable or on the @code{make} command line.
2004 @node ELPA, , OpenToken, Developer overview
2006 Ada mode is published via the Gnu ELPA archive. To test a new version
2007 of Ada mode, we use a local Gnu ELPA archive. That requires fetching
2012 git clone git://git.savannah.gnu.org/emacs/elpa.git
2015 If you have an Emacs Savannah developer account, you can use:
2019 git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
2022 @file{build/Makefile} contains targets for copying Ada mode source to
2023 the elpa workspace, and for building the elpa archive there.
2025 @node GNU Free Documentation License, Index, Developer overview, Top
2026 @appendix GNU Free Documentation License
2027 @include doclicense.texi
2029 @node Index, , GNU Free Documentation License, Top