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.
31 @subtitle An Emacs major mode for programming in Ada
32 @subtitle Ada Mode Version 5.1.5
35 @vskip 0pt plus 1filll
41 @node Top, Overview, (dir), (dir)
49 * Installation:: Installing Ada mode on your system
50 * Customization:: Setting up Ada mode to your taste
51 * Compiling Executing:: Working with your application within Emacs
52 * Project files:: Describing the organization of your project
53 * Moving Through Ada Code:: Moving easily through Ada sources
54 * Identifier completion:: Finishing words automatically
55 * Indentation:: Indenting your code automatically as you type
56 * Statement skeletons:: Some code is written for you
57 * Aligning code:: Making it pretty
58 * Automatic casing:: Adjusting the case of words automatically
59 * Comment Handling:: Reformatting comments easily
61 * Developer overview::
62 * GNU Free Documentation License::
66 @node Overview, Installation, Top, Top
69 The Emacs mode for programming in Ada helps the user in reading
70 existing code and facilitates developing new code.
72 Cross-reference information output by the compiler is used to provide
73 powerful code 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
79 Ada mode works without any customization, if you are using the GNAT
80 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
83 You must customize a few things if you are using a different file
84 naming convention or compiler; @xref{Non-standard file names},
85 @xref{Other compiler}.
87 In addition, you may want to customize the indentation,
88 capitalization, and other things; @xref{Other customization}.
90 Finally, for large Ada projects, you will want to set up an Emacs Ada
91 mode project file for each project; @xref{Project files}. Note that
92 these are different from the GNAT project files used by the GNAT
95 @xref{Debuggers,,Debuggers,emacs,Emacs User Guide}, for general
96 information on debugging.
98 @node Installation, Customization, Overview, Top
101 Ada mode requires Emacs 24.2 or greater; it also requires the Emacs
102 lisp sources (not just the compiled binaries).
104 Ada mode is distributed in the Gnu ELPA package archive; it can be
105 installed via @code{M-x list-packages} (@pxref{Packages,,,emacs,Emacs
106 User Guide}). You must first enable packages in your @file{~/.emacs},
107 @emph{after} customizing @code{Info-default-directory-list} (if you do
114 Ada mode is also available as a separate distribution, from the Emacs
116 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}.
118 For installing the separate distribution, see the @file{README} file
121 To see what version of Ada mode you have installed, invoke @kbd{M-x
129 @node gnatinspect, Upgrading, Installation, Installation
131 Ada mode has experimental support for the new AdaCore cross reference
132 tool @code{gnatinspect}, which supports Ada, C, C++, and any other
133 language for which gcc provices the @code{-fdump-xref}.
135 @code{gnatinspect} is distributed as part of @code{gnatcoll}. Ada mode
136 requires the very latest version, in @code{gnatcoll 1.7w} distributed
139 To build @code{gnatinspect}, assuming GNAT GPL 2014 is installed in
140 @file{/usr/gnat-gpl-2014}, and @file{/usr/gnat-gpl-2014/bin} is in
144 tar xf ~/Downloads/gnatcoll-1.7x-src.tgz
146 ./configure --prefix=/usr/gnat-gpl-2014
147 make Gnatcoll_Build=Debug
148 sudo make Gnatcoll_Build=Debug install
151 To build an sqlite3 executable that is compatible with the database
152 created by gnatinspect:
155 cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
156 gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
159 @node Upgrading, , gnatinspect, Installation
160 @section Upgrading from previous versions
162 See the file NEWS for more details; here we summarize only important
163 user interface changes.
170 There are many user interface and API changes between 4.01 and 5.0.1;
171 we only document those that may be hard to diagnose here.
173 @code{prog-mode-hook} is no longer run by @code{ada-mode};
174 @code{ada-mode} is no longer derived from @code{prog-mode}. Use
175 @code{ada-mode-hook} instead.
180 @node Customization, Compiling Executing, Installation, Top
181 @chapter Customizing Ada mode
183 Here we assume you are familiar with setting variables in Emacs,
184 either thru 'customize' or in elisp (in your @file{.emacs} file). For
185 a basic introduction to customize, elisp, and Emacs in general, see
186 the tutorial (@kbd{C-h t}).
189 * Non-standard file names::
191 * Other cross-reference::
192 * Other customization::
195 @node Non-standard file names, Other compiler, Customization, Customization
196 @section Non-standard file names
198 By default, Ada mode is configured to use the GNAT file naming
199 convention, where file names are a simple modification of the Ada
200 names, and the extension for specs and bodies are
201 @samp{.ads} and @samp{.adb}, respectively.
203 Emacs uses the file extension to enable Ada mode; Ada mode uses the
204 file extentions to allow moving from a package body to the
205 corresponding spec and back.
207 Emacs and Ada mode support ways to use alternative file extensions for
208 specs and bodies. Note that you must also tell the compiler about
209 these extensions; doing that is beyond the scope of this manual.
211 For instance, if your spec and bodies files are called
212 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
213 can add the following to your @file{.emacs} file:
216 ;; Tell Ada mode about spec and body extensions
217 (ada-add-extensions "_s.ada" "_b.ada")
219 ;; Tell Emacs to use Ada mode for those extensions
220 (add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
223 You can define additional extensions:
226 (ada-add-extensions ".ads" "_b.ada")
227 (ada-add-extensions ".ads" ".body")
230 This means that whenever Ada mode looks for the body for a file
231 whose extension is @file{.ads}, it will take the first available file
232 that ends with either @file{.adb}, @file{_b.ada} or
235 Simililarly, if Ada mode is looking for a spec, it will look for
236 @file{.ads} or @file{_s.ada}.
238 If the filename excluding the extension is not derived from the Ada
239 name following the GNAT convention, you need to provide an alternate
240 function for @code{ada-file-name-from-ada-name}. Doing that is beyond
241 the scope of this manual; see the current definitions in
242 @file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.
244 @node Other compiler, Other cross-reference, Non-standard file names, Customization
245 @section Other compiler
246 The project variable @code{ada_compiler} (default elisp variable
247 @code{ada-compiler}) is used to index several variables that point to
248 the compiler-specific functions for corresponding Ada mode operations.
250 To use a compiler other than GNAT, you must write Emacs lisp code that
251 provides the interface to the compiler, and set @code{ada-compiler} and
252 the indirection variables.
254 See @file{ada-gnat-compile.el} for an example.
256 @node Other cross-reference, Other customization, Other compiler, Customization
257 @section Other cross-reference
258 The project variable @code{ada_xref} (default elisp variable
259 @code{ada-xref-tool}) is used to index several variables that point to
260 the cross-reference-tool-specific functions for corresponding Ada mode
263 To use a cross reference tool other than gnatxref, you must write
264 Emacs lisp code that provides the interface to the compiler, and set
265 @code{ada-xref-tool} and the indirection variables. This has already
266 been done for @code{gnatinspect}; set @code{ada-xref-tool} to
267 @code{'gnat_inspect}.
269 See @file{ada-gnat-xref.el} and @file{gnat-inspect.el} for examples.
271 @node Other customization, , Other cross-reference, Customization
272 @section Other customization
274 All user-settable Ada mode variables can be set via the menu
275 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
278 To modify a specific variable, you can directly call the function
279 @code{customize-variable}; just type @kbd{M-x customize-variable
280 @key{RET} @var{variable-name} @key{RET}}).
282 Alternately, you can specify variable settings in the Emacs
283 configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
284 and the syntax to set a variable is the following:
286 (setq variable-name value)
289 Some general Emacs settings that are useful for Ada files:
291 @item delete-trailing-whitespace
292 Deletes space, tab at end of line and blank lines at end of buffer.
294 Deletes tab characters that have crept into the file.
295 @item indent-tabs-mode
296 Don't insert tab characters when indenting.
297 @item copyright-update
298 Updates the copyright date in the file header comment, to the current
300 @item electric-pair-mode
301 Insert a matching right paren when you type a left paren.
303 Bind @code{hippie-expand} to a key; it expands the word before point, using
304 words from current buffer, other buffers, file names, etc; see
305 @code{hippie-expand-try-functions-list}. You can also add
306 @code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
307 which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
308 (@pxref{Statement skeletons}).
313 The above can all be set by the following code in your
314 @file{~/.emacs}. Note that some are functions are added to
315 @code{before-save-hook}; they run just before a buffer is written to
316 disk. Also, the order is important; ada-mode does not set up the
317 Ada-specific features of imenu and which-func unless they are loaded
321 (setq-default indent-tabs-mode nil)
322 (electric-pair-mode 1)
324 (require 'which-func)
326 (add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
327 (define-key ada-mode-map "\C-e" 'hippie-expand)
328 (add-hook 'ada-mode-hook
330 (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
331 (add-hook 'before-save-hook 'copyright-update nil t)
332 (add-hook 'before-save-hook
333 (lambda () (untabify (point-min) (point-max)))
337 @node Compiling Executing, Project files, Customization, Top
338 @chapter Compiling Executing
340 Ada projects can be compiled, linked, and executed using commands on
341 the Ada menu. All of these commands can be customized via a project
342 file (@pxref{Project files}), but the defaults are sufficient for using
343 the GNAT compiler for simple projects (single files, or several files
344 in a single directory).
346 For complex projects, you will want to use @code{make} or some other
347 build tool; in that case, you will need an Emacs Ada mode project file
348 to tell Emacs about the project directory tree and other settings.
352 * Compiling Examples::
356 @node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
357 @section Compile commands
359 Here are the commands for building an Ada project and running the main
362 In multi-file projects, there must be one file that is the main
363 program. That is given by the @code{main} project file variable;
364 it defaults to the current file if not yet set, but is also set by the
365 ``set main and build'' command.
366 @c IMPROVEME: get main from gpr via gnatinspect? not in gnatcoll 1.6w
371 Compiles the current file in syntax check mode, by running
372 @code{check_cmd} defined in the current project file. This typically
373 runs faster than full compile mode, speeding up finding and fixing
376 This sets @code{main} only if it has not been set yet.
379 Compiles the current file, by running @code{comp_cmd} from the current
382 This does not set @code{main}.
384 @item Set main and Build
385 Sets @code{main} to the current file, then executes the Build
389 Display @code{main} in the message buffer.
392 Compiles all obsolete units of the current @code{main}, and links
393 @code{main}, by running @code{make_cmd} from the current project.
395 This sets @code{main} only if it has not been set yet.
398 Executes the main program in a shell, displayed in a separate Emacs
399 buffer. This runs @code{run_cmd} from the current project. The
400 execution buffer allows for interactive input/output.
402 To modify the run command, in particular to provide or change the
403 command line arguments, type @kbd{C-u} before invoking the command.
405 This command is not available for a cross-compilation toolchain.
408 It is important when using these commands to understand how
409 @code{main} is used and changed.
411 Build runs 'gnatmake' on the main unit. During a typical edit/compile
412 session, this is the only command you need to invoke, which is why it
413 is bound to @kbd{C-c C-c}. It will compile all files needed by the
414 main unit, and display compilation errors in any of them.
416 Note that Build can be invoked from any Ada buffer; typically you will
417 be fixing errors in files other than the main, but you don't have to
418 switch back to the main to invoke the compiler again.
420 Novices and students typically work on single-file Ada projects. In
421 this case, @kbd{C-c C-m} will normally be the only command needed; it
422 will build the current file, rather than the last-built main.
424 There are three ways to change @code{main}:
428 Invoke @samp{Ada | Set main and Build}, which sets @code{main} to
432 Invoke @samp{Ada | Project | Edit}, edit @code{main} and
433 @code{main}, and click @samp{[save]}
436 Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main}
440 @node Compiling Examples, Compiler errors, Compile commands, Compiling Executing
441 @section Compiling Examples
443 We present several small projects, and walk thru the process of
444 compiling, linking, and running them.
446 The first example illustrates more Ada mode features than the others;
447 you should work thru that example before doing the others.
449 All of these examples assume you are using GNAT.
451 The source for these examples is available on the Emacs Ada mode
452 website mentioned in @xref{Installation}.
455 * No project files:: Just menus
456 * Set compiler options:: A basic Ada mode project file
457 * Set source search path:: Source in multiple directories
458 * Use GNAT project file::
459 * Use multiple GNAT project files::
463 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
464 @subsection No project files
465 This example uses no project files.
467 First, create a directory @file{Example_1}, containing:
475 Put_Line("Hello from hello.adb");
479 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
480 compiler error handling.
482 @file{hello_2.adb} has no errors:
492 @file{hello_pkg.ads} has no errors:
500 @file{hello_pkg.adb}:
507 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
512 Yes, this is missing the keyword @code{body}; another compiler error
513 example. However, note that the indentation engine parser accepts this
514 code with no errors, making it easier to indent slightly illegal Ada
517 In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
518 Check syntax}. You should get a @code{*compilation*} buffer containing
519 something like (the directory paths will be different):
522 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
523 Compilation started at Fri Oct 18 04:23:54
525 gnatmake -u -c -gnatc c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
526 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
527 hello.adb:4:04: "Put_Line" is not visible
528 hello.adb:4:04: non-visible declaration at a-textio.ads:263
529 hello.adb:4:04: non-visible declaration at a-textio.ads:259
530 gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error
532 Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
535 The lines with actual errors (starting with @file{hello.adb}) are
536 highlighted, with the file name in red.
538 Now invoke @samp{Ada | Build | Next compilation error}. Or you can
539 click the middle mouse button on the first error line, or use the key
540 binding shown on the menu. The compilation buffer scrolls to put the
541 first error on the top line, and point is put at the place of the
542 error in the @file{hello.adb} buffer.
544 To fix the error, invoke @samp{Ada | Build | Fix compilation error};
545 this adds ``Ada.Text_Io.'' to the line:
548 Ada.Text_Io.Put_Line ("hello from hello.adb");
551 Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.
553 Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
554 prompted to save the file (if you haven't already). Then the
555 compilation buffer is displayed again, containing:
558 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
559 Compilation started at Fri Oct 18 20:39:33
561 gnatmake -o hello hello -cargs -bargs -largs
563 gnatbind -x hello.ali
564 gnatlink hello.ali -o hello.exe
566 Compilation finished at Fri Oct 18 20:39:34
569 The compilation has succeeded without errors; @file{hello.exe} now
570 exists in the same directory as @file{hello.adb}.
572 Now invoke @samp{Ada | Build | Run}. The @file{*compilation*} buffer
573 is displayed, containing
576 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
577 Compilation started at Fri Oct 18 20:41:53
582 Compilation finished at Fri Oct 18 20:41:53
585 That completes the first part of this example.
587 Now we will compile a multi-file project. Open the file
588 @file{hello_2.adb}, invoke @samp{Ada | Build | Set main and
589 Build}. This finds an error in @file{hello_pkg.adb}:
592 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
595 This demonstrates that gnatmake finds the files needed by the main
596 program. However, it cannot find files in a different directory,
597 unless you use an Emacs Ada mode project file or a GNAT project file
598 to specify the other directories; @xref{Set source search path},
599 @ref{Use GNAT project file}.
601 Invoke @samp{Ada | Build | Show main}; this displays @file{Ada mode
604 Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}:
607 package body Hello_Pkg is
610 Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build |
611 Build}. gnatmake successfully builds @file{hello_2}. This
612 demonstrates that Emacs has remembered the main file, in the project
613 variable @code{main}, and used it for the Build command.
615 Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Build
616 | Run}. The @code{*compilation*} buffer displays @code{Hello from
619 One final point. If you switch back to buffer @file{hello.adb}, and
620 invoke @samp{Ada | Build | Run}, @file{hello_2.exe} will be run. That
621 is because @code{main} is still set to @code{hello_2}, as you can see
622 when you invoke @samp{Ada | Build | Show main}.
624 There are two ways to change @code{main}:
628 Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
632 Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
633 specifies @code{main}.
637 @node Set compiler options, Set source search path, No project files, Compiling Examples
638 @subsection Set compiler options
640 This example illustrates using an Emacs Ada mode project file to set a
643 If you have files from @file{Example_1} open in Emacs, you should
644 close them so you don't get confused. Use menu @samp{File | Close
647 In directory @file{Example_2}, create these files:
655 Put_Line("Hello from hello.adb");
659 This is the same as @file{hello.adb} from @file{Example_1}. It has two
660 errors; missing ``use Ada.Text_IO;'', and no space between
661 @code{Put_Line} and its argument list.
669 This tells the GNAT compiler to check for token spacing; in
670 particular, there must be a space preceding a parenthesis.
672 In buffer @file{hello.adb}, invoke @samp{Ada | Build | Set main and
673 Build}. This finds the project file @file{hello.adp}, uses it to set
674 the compiler options, and builds the project. You should get a
675 @code{*compilation*} buffer containing something like (the directory
676 paths will be different):
679 cd c:/Examples/Example_2/
680 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
681 gcc -c -g -gnatyt hello.adb
682 hello.adb:4:04: "Put_Line" is not visible
683 hello.adb:4:04: non-visible declaration at a-textio.ads:264
684 hello.adb:4:04: non-visible declaration at a-textio.ads:260
685 hello.adb:4:12: (style) space required
686 gnatmake: "hello.adb" compilation error
689 Compare this to the compiler output in @ref{No project files}; the
690 gnatmake option @code{-cargs} has been replaced by @code{-cargs
691 -gnaty}, and an additional error is reported in @file{hello.adb} on
692 line 4. This shows that @file{hello.adp} is being used to set the
695 Fixing the error, linking and running the code proceed as in @ref{No
698 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
699 @subsection Set source search path
701 In this example, we show how to deal with files in more than one
702 directory, using an Emacs Ada mode project file to set the search
705 Create the directory @file{Example_3}, containing:
707 @file{hello_pkg.ads}:
715 @file{hello_pkg.adb}:
722 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
727 These are the same files from example 1; @file{hello_pkg.adb} has an
730 In addition, create a directory @file{Example_3/Other}, containing these files:
732 @file{Other/hello_3.adb}:
736 with Ada.Text_IO; use Ada.Text_IO;
740 Put_Line ("From hello_3");
744 There are no errors in this file.
746 @file{Other/other.adp}:
752 Note that there must be no trailing spaces.
754 In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
755 set project...}, and select @file{Example_3/Other/other.adp}. This
756 tells Emacs Ada mode to stop using the project file from
757 @file{Example_2}, and use the one for @file{Example_3}. Also note that
758 since this project file is not named @file{hello_3.adp}, it would not
761 Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
762 Build}. You should get a @code{*compilation*} buffer containing
763 something like (the directory paths will be different):
766 cd c:/Examples/Example_3/Other/
767 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
768 gcc -c -g -I.. hello_3.adb
769 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
770 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
771 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
774 Compare the @code{-cargs} option to the compiler output in @ref{Set
775 compiler options}; this shows that @file{other.adp} is being used to
776 set the compiler options.
778 Move to the error with @kbd{C-x `}. Ada mode searches the list of
779 directories given by @code{src_dir} for the file mentioned in the
780 compiler error message.
782 Fixing the error, linking and running the code proceed as in @ref{No
785 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
786 @subsection Use GNAT project file
788 In this example, we show how to use a GNAT project file, with no Ada
791 Create the directory @file{Example_4}, containing:
793 @file{hello_pkg.ads}:
801 @file{hello_pkg.adb}:
808 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
813 These are the same files from example 1; @file{hello_pkg.adb} has an
816 In addition, create a directory @file{Example_4/Gnat_Project},
817 containing these files:
819 @file{Gnat_Project/hello_4.adb}:
823 with Ada.Text_IO; use Ada.Text_IO;
827 Put_Line ("From hello_4");
831 There are no errors in this file.
833 @file{Gnat_Project/hello_4.gpr}:
837 for Source_Dirs use (".", "..");
841 In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and
842 select @file{Example_4/Gnat_Project/hello_4.gpr}.
844 Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and
845 Build}. You should get a @code{*compilation*} buffer containing
846 something like (the directory paths will be different):
849 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
850 Compilation started at Mon Oct 21 11:28:31
852 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
853 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
854 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
855 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
857 Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
860 Compare the @code{gcc} options to the compiler output in @ref{Set
861 compiler options}; this shows that @file{hello_4.gpr} is being used to
862 set the compiler options.
864 Fixing the error, linking and running the code proceed as in @ref{No
867 @node Use multiple GNAT project files, Use a Makefile, Use GNAT project file, Compiling Examples
868 @subsection Use multiple GNAT project files
870 In this example, we show how to use multiple GNAT project files,
871 specifying the GNAT project search path in an Ada mode project file.
873 Create the directory @file{Example_4} as specified in @ref{Use GNAT
876 Create the directory @file{Example_5}, containing:
882 with Ada.Text_IO; use Ada.Text_IO;
886 Put_Line ("From hello_5");
890 There are no errors in this file.
895 ada_project_path=../Example_4/Gnat_Project
904 for Source_Dirs use (".");
906 for Default_Switches ("Ada") use ("-g", "-gnatyt");
911 In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Find and
912 select project...}, and select @file{Example_5/hello_5.adp}. This
913 would also be found by default if no previous project file had been
916 Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
917 and Build}. You should get a @code{*compilation*} buffer containing
918 something like (the directory paths will be different):
921 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
922 Compilation started at Mon Oct 21 11:32:05
924 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
925 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
926 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
927 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
929 Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
932 Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
933 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
934 used to set the compilation search path.
936 @node Use a Makefile, , Use multiple GNAT project files, Compiling Examples
937 @subsection Use a Makefile
939 In this example, we show how to use a Makefile to build an Ada project
940 with GNAT, run the result, and clean the build directories.
942 Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
943 project file}, @ref{Use multiple GNAT project files}.
945 In @file{Example_5}, add the file:
950 # build and run hello_5 project
957 gprbuild -Phello_5.gpr hello_5
963 gnatclean -r -Phello_5
965 export GPR_PROJECT_PATH = ../Example_4/Gnat_Project
968 # eval:(ada-parse-prj-file "hello_5.adp")
969 # eval:(ada-select-prj-file "hello_5.adp")
973 Close and re-open @file{Makefile}; the @samp{Local Variables} section
974 sets the project file to @file{hello_5.adp} when the @file{Makefile}
975 is opened. You can also use @key{C-x C-e} to execute the select line
976 after the @file{Makefile} is opened, to change the project file back
977 to @file{hello_5.adp}.
979 In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
980 default make command. This runs the @samp{all} target, which builds
981 @file{hello_5} and runs it.
983 @node Compiler errors, , Compiling Examples, Compiling Executing
984 @section Compiler errors
986 The @code{Check syntax} and @code{Build} commands, or running
987 @code{make}, place compilation errors in a separate buffer named
988 @code{*compilation*}.
990 Each line in this buffer will become active: you can simply click on
991 it with the middle button of the mouse, or move point to it and press
992 @key{RET}. Emacs will then display the relevant source file and put
993 point on the line and column where the error was found.
995 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
996 will jump to the first error. If you press that key again, it will
997 move you to the second error, and so on.
999 Some error messages also include references to other files. These
1000 references are accessed via @kbd{C-c `}.
1002 @node Project files, Moving Through Ada Code, Compiling Executing, Top
1003 @chapter Project files
1005 An Emacs Ada mode project file specifies what directories hold sources
1006 for your project, and allows you to customize the compilation commands
1007 and other things on a per-project basis.
1009 The default file extension for Ada mode project files is @file{*.adp}
1010 or @file{*.prj}. You can use a different extension by adding it to
1011 @code{ada-prj-file-extensions}, and a different syntax by adding a
1012 parser function to @code{ada-prj-parser-alist}.
1014 Note that Ada mode project files @file{*.adp} are different than GNAT
1015 compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
1016 GNAT project file to specify the project directories. If no
1017 other customization is needed, a GNAT project file can be used without
1018 an Emacs Ada mode project file.
1020 If no Emacs Ada mode project file is specified, some Ada mode
1021 functions are not available.
1024 * Project file overview::
1025 * Project file variables::
1028 @node Project file overview, Project file variables, Project files, Project files
1029 @section Project file overview
1031 Project files have a simple syntax; they may be edited directly. Each
1032 line specifies a project variable name and its value, separated by
1033 ``='' (spaces not allowed):
1035 src_dir=/Projects/my_project/src_1
1036 src_dir=/Projects/my_project/src_2
1039 Any line that does not have an ``='' is a comment.
1041 Some variables (like @code{src_dir}) are lists; multiple occurrences
1044 There must be no space between the variable name and ``='', and no
1047 The current project file is given by the lisp variable
1048 @code{ada-prj-default-project-file}, and shown by the menu command
1049 @key{Ada | Project Files | Show project}.
1051 To set the project file, use the menu command @samp{Ada | Set Project
1052 ...}, or the elisp functions @code{ada-parse-prj-file,
1053 ada-select-prj-file}. The latter can be added to a Makefile:
1057 # eval: (ada-parse-prj-file "ada-mode.prj")
1058 # eval: (ada-select-prj-file ada-mode.prj")
1062 You specify either a GNAT project file or an Emacs Ada mode project
1063 file; if the file extension is @code{.gpr}, the file is treated as a
1064 GNAT project file. Extensions given by @code{ada-prj-file-extensions}
1065 (default @file{.adp, .prj}) are treated as an Emacs Ada mode
1068 After a project file is parsed, you can make it current again with
1069 just @code{ada-select-prj-file}, or by selecting it from the menu.
1071 @node Project file variables, , Project file overview, Project files
1072 @section Project file variables
1074 To set a project variable that is a list, specify each element of the
1075 list on a separate line in the project file.
1077 Process environment variables can be referenced using the
1078 normal @code{$var} syntax.
1080 Most project variables have defaults that can be changed by setting
1081 elisp variables; the table below identifies the elisp variable for each
1082 project variable. Elisp variables corresponding to project variables
1083 that are lists are elisp lists.
1085 In general, project variables are evaluated when referenced in Emacs
1086 Ada mode commands. Relative file paths are expanded relative to the
1087 directory containing the project file.
1089 Ada mode defines some project variables; others are defined by the
1092 Here is the list of variables valid for all compilers. In the default
1093 values, the current directory @code{"."} is the directory containing
1097 @c These are the names that appear in the .adp file, which are the
1098 @c same as the symbols used with ada-prj-get
1100 @c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
1101 @c defaults defined in ada-mode.el ada-prj-default
1103 @item @code{ada_compiler} [default: @code{ada-compiler, gnat}]
1104 Ada compiler for this project. It must occur in the project file
1105 before any compiler-specific project variable.
1107 @item @code{auto_case} [default: @code{ada-auto-case, t}]
1108 Non-nil means automatically change case of preceding word while typing.
1110 @item @code{case_identifier} [default: @code{ada-case-identifier, ada-mixed-case}]
1111 Function to call to adjust the case of an Ada identifier.
1113 @item @code{case_keyword} [default: @code{ada-case-keyword, downcase-word}]
1114 Function to call to adjust the case of an Ada keyword.
1116 @item @code{case_strict} [default: @code{ada-case-strict, t}]
1117 If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
1118 Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.
1120 @item @code{casing} [default: @code{ada-case-exception-file, nil}]
1121 List of files containing casing exceptions. @xref{Automatic casing}.
1123 @item @code{el_file} [default: ]
1124 The value is a file name, which is loaded as an elisp file when the
1125 project file is parsed or selected. This allows setting Ada mode indentation
1126 variables, and any arbitrary elisp code used to customize the project.
1128 @item @code{path_sep} [default: @code{path-separator}]
1129 Separator character used in compiler search paths.
1131 @item @code{src_dir} [default: @code{"."}]
1132 A list of directories to search for source files.
1134 @item @code{xref_tool} [default: @code{ada-xref-tool, gnat-xref}]
1135 Cross reference tool for this project.
1139 The following variables are valid with the GNAT compiler:
1142 @c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
1143 @item @code{ada_project_path} [default: @code{""}]
1144 @c ada-prj-get 'prj_dir, 'proc_env
1145 A list of directories to search for GNAT project files.
1147 If set, the @code{GPR_PROJECT_PATH} process environment variable is
1148 set to this value in the child process that runs GNAT tools. If not
1149 set, @code{GPR_PROJECT_PATH} in the child process is inherited from
1152 If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
1153 environment variable set in the Emacs process correctly for all of
1154 your projects, you do not need to set this project variable.
1156 The project search path can also be set in GNAT aggregate
1157 projects. However, the gnat tools do not make that path available to
1158 Emacs, so you must duplicate it in an Emacs Ada project file.
1160 @item @code{gpr_file} [default: @code{""}]
1161 The GNAT project file.
1163 If set, the source and project directories specified in the GNAT
1164 project file are appended to @code{src_dir} and
1165 @code{ada_project_path}. This allows specifying Ada source directories
1166 with a GNAT project file, and other source directories with the Emacs
1169 @item @code{gpr_project_path} [default: @code{""}]
1170 Same as @code{ada_project_path}.
1174 @node Moving Through Ada Code, Identifier completion, Project files, Top
1175 @chapter Moving Through Ada Code
1177 There are several commands to navigate through Ada code. All
1178 these functions are available through the Ada menu and keybindings.
1180 Some of these commands rely on cross reference facilities provided by
1181 the compiler; the standard Emacs Ada mode only supports the GNAT
1182 compiler, but others can be added (@pxref{Other cross-reference}).
1186 @findex ada-goto-declaration
1187 Move from any use of an identifier to its declaration, for from a declaration to
1188 its body (if there is one).
1191 @findex ada-goto-declaration-parent
1192 Move from a child type declaration to the parent type declaration;
1193 display a list of references if there is more than one parent.
1196 @findex ada-next-statement-keyword
1197 Move to the next keyword in the current statement.
1199 For example, if point is on @samp{if}, move to @samp{then}.
1202 @findex ada-prev-statement-keyword
1203 Move to the previous keyword in the current statement.
1205 For example, if point is on @samp{then}, move to @samp{if}.
1208 @findex ada-find-other-file
1209 Switch between corresponding spec and body. There are several special
1214 If the region is active, it is assumed to contain an Ada package
1215 name; position point on the corresponding package declaration.
1218 If point is in the start line of a top level child package
1219 declaration (but not package body), or a child subprogram spec or
1220 body, position point on the corresponding parent package
1224 If point is in the start line of a top level separate body,
1225 position point on the corresponding separate stub declaration.
1228 If point is in a subprogram declaration or body, position point on the
1229 corresponding body or declaration in the other file.
1232 If point is on a @code{with} clause, position point on the
1233 corresponding declaration.
1238 @findex ada-show-references
1239 Show all references to the identifier surrounding point. Use
1240 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1241 compilation errors).
1244 @findex ada-show-overriding
1245 Show all declarations that override the primitive procedure at
1246 point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
1247 for compilation errors).
1250 @findex ada-show-overridden
1251 Show the declaration that the declaration at point overrides.
1254 Jump back to the previous location.
1256 @item Ada | Misc | Refresh cross reference cache
1257 Cross reference information is loaded from the compiler output when
1258 the first cross reference command is issued. If the code is recompiled
1259 after that, the cross reference information is reloaded by invoking
1264 @node Identifier completion, Indentation, Moving Through Ada Code, Top
1265 @chapter Identifier completion
1267 Emacs provides a general way of completing identifiers: @kbd{M-/}
1268 (bound to @code{dabbrev-expand}). This is an easy way to type faster:
1269 you just have to type the first few letters of an identifier, and then
1270 loop through all the possible completions.
1272 @kbd{M-/} works by parsing all open Ada files for possible
1275 For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
1276 are the only words starting with @samp{my} in any of the open Ada files,
1277 then you will have this scenario:
1280 You type: my@kbd{M-/}
1281 Emacs inserts: @samp{my_identifier}
1282 If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
1283 @samp{my_subprogram}.
1284 Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
1287 This is a very fast way to do completion, and the casing of words will
1290 @node Indentation, Statement skeletons, Identifier completion, Top
1291 @chapter Indentation
1293 Ada mode comes with a full set of rules for automatic indentation. You
1294 can also configure the indentation, via the following variables:
1297 @item @code{ada-indent} (default value: 3)
1298 Number of columns for default indentation.
1300 @item @code{ada-indent-broken} (default value: 2)
1301 Number of columns to indent the continuation of a broken line.
1303 @item @code{ada-indent-comment-col-0} (default value: nil)
1304 If non-nil, comments currently starting in column 0 are left in column
1305 0. Otherwise, they are indented with previous comments or code.
1307 @item @code{ada-indent-label} (default value: -3)
1308 Number of columns to indent a label.
1310 @item @code{ada-indent-record-rel-type} (default value: 3)
1311 Indentation for @code{record} relative to @code{type} or @code{use}.
1313 @item @code{ada-indent-renames} (default value: 2)
1314 Indentation for @code{renames} relative to the matching subprogram keyword.
1316 If the subprogram has parameters then if @code{ada-indent-renames} is
1317 zero or less the indentation is abs @code{ada-indent-renames} relative
1318 to the open parenthesis; if @code{ada-indent-renames} is one or more
1319 the indentation is relative to the line containing the keyword.
1321 If the subprogram has no parameters then @code{ada-indent-broken} the
1322 indentation is relative to the indentation of the line containing
1325 @item @code{ada-indent-return} (default value: 0)
1326 Indentation for @code{return} relative to the matching
1329 If the function has parameters, then if @code{ada-indent-return} is
1330 zero or less the indentation is abs @code{ada-indent-return} relative
1331 to the open parenthesis; if @code{ada-indent-return} is one or more,
1332 indentation is relative to line containing @code{function}.
1334 If the function has no parameters, @code{ada-indent-broken} is used
1335 relative to line containing @code{function}.
1337 @item @code{ada-indent-use} (default value: ada-indent-broken)
1338 Indentation for the lines in a @code{use} statement.
1340 @item @code{ada-indent-when} (default value: 3)
1341 Indentation for @code{when} relative to @code{exception}, @code{case},
1342 or @code{or} in @code{select}.
1344 @item @code{ada-indent-with} (default value: ada-indent-broken)
1345 Indentation for the lines in a @code{with} context clause.
1349 The indentation variables are buffer local; the global value may be
1350 overridden in an elisp file invoked by an @code{el_file} Emacs Ada
1351 mode project file statement, or in a file local variable section.
1353 The following keys indent portions of the text:
1357 Insert and indent a new line.
1360 Indent the current line, or the current region.
1363 Indent the current statement or declaration.
1367 The indentation algorithm relies on a grammar parser to identify the
1368 syntactic role for keywords and other words in the code. If the code
1369 is accepted by the parser, the indentation is done according to the
1370 rules in the indentation engine.
1372 If the code is not accepted (because it is partially complete during
1373 editing), the indentation engine falls back to the trivial algorithm
1374 of indenting each new line the same as the previous line. Once enough
1375 new text has been entered to make the code acceptable to the parser,
1376 the statement or declaration is properly indented.
1378 For example, if you are entering this code:
1386 when you type @kbd{RET B}, @code{B} is indented to the same column as
1387 @code{if}, because the parser does not find @code{end if;}. Then when
1388 you type the final @code{;} followed by @key{TAB}, all three lines are
1389 indented, putting @code{B} where it belongs.
1391 To be more user friendly, the parser accepts a superset of the Ada
1392 grammer. For example, the parser accepts this code for an @code{if}
1400 In general, any sequence of statements, and many expressions, may be
1403 One way to easily insert empty statements like this is using
1404 @ref{Statement skeletons}.
1406 In rare cases, the parser gets confused; it can be reset by invoking
1407 menu @key{Ada | Misc | Reset parser}. Please report such cases as a
1410 @node Statement skeletons, Aligning code, Indentation, Top
1411 @chapter Statement skeletons
1413 @kbd{C-c C-e} expands the previous one or two words into a statment
1414 skeleton. For example, @kbd{i f C-c C-e} expands to:
1423 All skeleton expansions are accepted by the indentation parser, so
1424 this is a convenient way to insert statements with correct
1427 For named statements (packages, loops, etc), the name is taken from
1428 the word before point, and the name of the statement from the word
1431 Some expansions prompt for more information, such as
1432 whether a spec or body is desired. For example, @kbd{package A_Package
1433 C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
1434 selected, the following code is inserted:
1437 package A_Package is
1442 Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
1443 (without prompting) to:
1453 Note that the order of the keyword @code{declare} and the name
1454 @code{A_Block} are reversed in the expansion; this may take some
1455 getting used to. Alternately, if no name is present in the buffer, you
1456 are prompted for a name: @kbd{declare C-c C-e} first prompts for a
1457 name, then expands to the above.
1459 The variable @code{ada-skel-initial-string} defines what to insert in
1460 a newly created empty buffer. It defaults to @code{@{header@}}, which
1461 is a placeholder defined by @code{ada-skel-header}, which inserts a
1462 typical header with a copyright license (choice of GPL or
1463 restricted). Users will typically want to override the definition of
1464 @code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
1465 provide more choices of copyright license.
1467 @node Aligning code, Automatic casing, Statement skeletons, Top
1468 @chapter Aligning code
1470 Aligning code adds space in each line so that similar parts of
1471 successive lines are aligned vertically. For example, a sequence of
1476 Another : Float := 1.0;
1477 More : Integer := 2;
1480 changes to this when aligned:
1484 Another : Float := 1.0;
1485 More : Integer := 2;
1488 Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
1489 statements surrounding point, or within the selected region.
1491 Parameter lists are also aligned:
1496 Another : out Float := 1.0;
1497 More : in out Integer := 2);
1505 Another : out Float := 1.0;
1506 More : in out Integer := 2);
1509 @node Automatic casing, Comment Handling, Aligning code, Top
1510 @chapter Automatic casing
1512 Casing of identifiers, attributes and keywords is automatically
1513 performed while typing when the variable @code{ada-auto-case} is
1514 non-nil (the default). Every time you type a word separator, the
1515 previous word is automatically cased.
1517 You can customize the automatic casing with the following variables:
1520 @item ada-case-keyword
1521 Value must be one of:
1524 Ada keywords will be lowercase.
1527 Ada keywords will be uppercase.
1530 @item ada-case-strict
1531 If non-nil, all identifiers are forced to @code{Mixed_Case}; first
1532 letter, and letter following ``_'' are uppercase; rest are
1535 If nil, the mixed case characters in identifiers are forced to upper
1536 case, but the other characters are not modified. That allows typing
1537 all uppercase identifiers without defining a casing exception.
1540 You can define exceptions to these rules, in files specified by the
1541 variable @code{ada-case-exception-file}. Each line in a case exception
1542 file specifies the casing of one word or word fragment. If an
1543 exception is defined in multiple files, the first occurrence is used.
1545 If the word starts with an asterisk (@code{*}), it defines the casing
1546 of a word fragemnt (or ``substring''); part of a word between two
1547 underscores or word boundary.
1557 The word fragment @code{*IO} applies to any word containing ``_io'';
1558 @code{Text_IO}, @code{Hardware_IO}, etc.
1560 @findex ada-case-create-exception
1561 There are two ways to add new items to this file: you can simply edit
1562 it as you would edit any text file. Or you can position point on the
1563 word you want to add, and select menu @samp{Ada | Casing | Create full
1564 exception} or @samp{Ada | Casing | Create partial exception}. The
1565 word will be added to the current list of exceptions and to the file.
1567 It is sometimes useful to have multiple exception files. For
1568 example, one could be the standard Ada acronyms, the second some
1569 company specific exceptions, and the last one some project specific
1570 exceptions. If you set up the variable @code{ada-case-exception-file}
1571 as a list of files, each of them will be parsed and used in your emacs
1572 session. When you create a new exception, you are prompted for the
1575 Other keys and menu entries are defined:
1579 @findex ada-case-adjust-at-point
1580 Adjust case of the word at point. With prefix arg, adjust case even if
1581 in comment. Normally, comments are not affected by case adjust.
1583 @item Ada | Casing | Adjust case region
1584 Adjust case in the active region.
1586 @item Ada | Casing | Adjust case buffer
1587 Adjust case in the active buffer.
1591 @node Comment Handling, Key summary, Automatic casing, Top
1592 @chapter Comment Handling
1594 By default, comment lines get indented like Ada code. There are a few
1595 additional functions to handle comments:
1599 @findex comment-dwim
1600 If the region is active, comment or uncomment it.
1602 If the current line is empty, start a comment.
1604 Otherwise, add a comment at the end of the line, in a column given by
1605 @code{comment-column}.
1608 @findex fill-paragraph
1609 Fill the current comment paragraph.
1612 @node Key summary, Developer overview, Comment Handling, Top
1613 @chapter Key summary
1614 @c search for @kbd and @key. Alphabetical by key sequence
1616 This table summarizes the keys described in this manual. Other keys
1617 are bound by Ada mode; see @key{C-h b} for a complete list. The
1618 Ada menu also displays keys bound to menu operations.
1622 @xref{Identifier completion}.
1623 Complete the word before point; repeat to cycle thru possible
1627 @xref{Comment Handling}.
1628 If the region is active, comment or uncomment it.
1631 @xref{Comment Handling}.
1632 Fill the current comment paragraph.
1636 Insert and indent a new line.
1640 Indent the current line, or the current region.
1644 Indent the current statement or declaration.
1647 @xref{Compiler errors}.
1648 Move to the location of the secondary reference in the current compilation error.
1651 @xref{Aligning code}.
1655 @xref{Compile commands}.
1656 Build the current main program.
1659 @xref{Moving Through Ada Code}.
1660 Move from any use of an identifier to its declaration, for from a declaration to its body.
1663 @xref{Moving Through Ada Code}.
1664 Move from a child type declaration to the parent type declaration.
1667 @xref{Statement skeletons}.
1668 Expand previous one or two words into a statement or declaration
1672 @xref{Compile commands}.
1673 Build the current file.
1676 @xref{Moving Through Ada Code}.
1677 Move to the next keyword in the current statement.
1680 @xref{Moving Through Ada Code}.
1681 Switch between corresponding spec and body, or find other spec.
1684 @xref{Moving Through Ada Code}.
1685 Move to the previous keyword in the current statement.
1688 @xref{Moving Through Ada Code}.
1689 Show all references to the identifier surrounding point.
1692 @xref{Automatic casing}.
1693 Adjust case of the word at point. With prefix arg, adjust case even if
1697 @xref{Moving Through Ada Code}.
1698 Show all declarations that override the primitive procedure at
1702 @xref{Automatic casing}.
1703 Create case exception.
1706 @xref{Compiler errors}.
1707 Move to the location of the next secondary compilation error.
1710 @xref{Compiler errors}.
1711 Move to the location of the next compilation error or show result.
1714 @xref{Comment Handling}.
1715 Fill the current comment paragraph.
1719 @node Developer overview, GNU Free Documentation License, Key summary, Top
1720 @chapter Developer overview
1721 If you'd like to contribute to Ada mode, or just understand the
1722 sources, here's an overview.
1725 * Directory structure::
1726 * Package organization::
1731 @node Directory structure, Package organization, Developer overview, Developer overview
1732 @section Directory structure
1734 @item org.emacs.ada-mode
1740 Elisp files; main code.
1743 Byte-compiled elisp files, not in the distribution. Generated by the
1744 Makefile target @code{byte-compile}, or by the Emacs package installer.
1746 Compiling the parse tables (@file{*-wy.el}) speeds up loading them
1747 significantly. Compiling other files speeds up parsing, but not
1750 One reason to byte-compile files is to find errors; the byte compiler
1751 reports undefined variables, wrong argument counts, etc.
1754 Parse tables, generated from the corresponding grammar @file{*.wy} by
1755 the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
1756 distribution and the monotone repository so users and Elisp developers
1757 don't have to install OpenToken.
1760 Diagnostic output from @file{wisi-generate.exe}, useful for tracing
1761 parses while debugging a grammar issue. Not in the tarball
1762 distribution or the monotone repository.
1765 Grammar files, specifying the language to be parsed. The syntax for
1766 these grammar files is similar to that for bison and wisent, but not
1767 the same; see the OpenToken documentation for more info.
1769 The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
1770 parser, so it tolerates some conflicts and ambiguities. This makes the
1771 grammars easier to write, and in particular makes it possible to let
1772 the Ada grammar closely match Annex P of the Ada Language Reference
1773 Manual (the syntax summary).
1776 Texinfo source for the user guides.
1779 Generated user guide in HTML format.
1782 Generated user guide in Emacs info format.
1788 Makefile for building the user guides, publishing to the web page or
1789 Gnu ELPA. Test drivers.
1792 Makefile for building and testing with the wisi-based
1793 parser. Separate from @file{build}, because there used to be a
1794 SMIE-based parser, and there might be another parser someday.
1796 The emacs used to byte-compile and run tests is given by the 'make'
1797 variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
1798 the make command line or by an environment variable.
1801 All tests for Ada mode, gpr mode, parser.
1803 Each test is run in a separate invocation of Emacs, so it is
1804 completely independent of all other tests.
1806 The tests are driven by the elisp code in @file{build/*.el}.
1808 In general, the Ada mode tests open the file, execute test actions,
1809 re-indent, and re-captialize the entire file. The result is diffed
1810 with the original, and must match.
1812 The test actions are defined by comments with the prefix
1813 @code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
1814 functions. This is used to test navigation features and other parser
1817 @item test/Example_*
1818 Starting files for examples in user guide.
1824 More tests; allows testing path search features.
1827 Tests of the elisp wisi grammar compiler and parser.
1830 @node Package organization, OpenToken, Directory structure, Developer overview
1831 @section Package organization
1840 @node Ada mode, gpr mode, Package organization, Package organization
1841 @subsection Ada mode
1842 Ada mode consists of all files with @file{ada-} prefix in the file
1847 The main file, implementing the keymap, menu, and top level
1850 It allows for different backend implementations for compiling,
1851 cross-referencing, and indenting. The functions for each of these
1852 backends dispatch thru global variables that are set by Emacs Ada mode
1853 project files. They default to the GNAT compiler, the gnatxref cross
1854 reference tool, and the ada-wisi indentation engine.
1857 Provides functions for compiling Ada files without a Makefile (or
1860 @item ada-fix-error.el
1861 Provides an interface to utilities for automatically fixing errors
1862 reported by the compiler. It dispatches to a compiler-specific
1865 @item ada-gnat-compile.el
1866 Implements the Ada mode compiler functions for the GNAT compiler.
1868 @item ada-gnat-xref.el
1869 Implements the Ada mode cross reference functions for the GNAT compiler.
1872 The Ada language grammar, and files generated from it by the OpenToken
1873 tool @file{wisi-generate.exe}.
1875 @item ada-indent-user-options.el
1876 All user-settable options for the Ada indentation engine.
1878 @item ada-mode-compat-23.4.el
1879 Defines functions used by Ada mode that are not in Emacs 23.4.
1881 Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
1882 partially supported. Earlier versions of Emacs are not supported.
1885 The Ada mode user guide source and compiled versions.
1888 Skeletons for expansion of Ada syntax (@pxref{Statement
1889 skeletons}). Extends the Emacs skeleton functions with ``tokens'',
1890 inspired by the lamented Else package (which was inspired by DEC LSE).
1892 @item ada-wisi-opentoken.el
1893 Indentation functions useful when editing OpenToken code; an example
1894 of extending the Ada mode indentation engine for special
1898 Implements the Ada mode indentation functions for the wisi indentation
1903 @node gpr mode, GNAT core, Ada mode, Package organization
1904 @subsection gpr mode
1906 gpr mode consists of all files with @file{gpr-} prefix in the file
1907 name. The functions in each file are similar to the similarly-named
1910 @node GNAT core, Wisi, gpr mode, Package organization
1911 @subsection GNAT core
1915 GNAT is actually a multi-language tool; it builds on top of the
1918 @file{gnat-core.el} is a start at a language-agnostic interface to the
1919 GNAT tools. It was first factored out from @file{ada-gnat.el} and
1920 @file{ada-mode.el} to support the multi-language
1921 @file{gnat-inspect.el}, which is still experimental.
1923 More code currently in @file{ada-mode.el} could be migrated to
1924 @file{gnat-core.el}, in particular the project file support.
1926 @item gnat-inspect.el
1927 Provides an experimental interface to the experimental multi-language
1928 cross-reference tool @file{gnatinspect} from AdaCore, which will
1929 supercede @file{gnatxref}.
1931 Implements the Ada mode cross-reference functions for the
1932 @file{gnatinspect} backend, and a minor mode providing similar
1937 @node Wisi, , GNAT core, Package organization
1940 The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
1945 Implements the lexer, the main parser driver,
1946 parser actions that cache parser information in text properties,
1947 utilities for indenting and navigating using the cached information,
1950 @item wisi-compile.el
1951 Implements the parse table
1952 compiler. @file{wisi-generate.exe} processes the grammar source
1953 @file{*.wy} into an elisp source representation of a parse table
1954 @file{*-wy.el}. That is compiled into an internal structure containing
1955 the state transitions and executable actions. The actions can be any
1956 elisp form; the intent is that they be calls to the action functions
1957 provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
1958 provided by @code{semantic}.
1961 Implements the generalized LALR parser.
1964 @node OpenToken, ELPA, Package organization, Developer overview
1966 Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
1967 the grammar sources into elisp parse tables. See
1968 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
1969 current information about which version of OpenToken is required, and
1972 The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
1973 build directory for OpenToken; you probably need to override it with
1974 an external environment variable or on the @code{make} command line.
1976 @node ELPA, , OpenToken, Developer overview
1978 Ada mode is published via the Gnu ELPA archive. To test a new version
1979 of Ada mode, we use a local Gnu ELPA archive. That requires fetching
1984 git clone git://git.savannah.gnu.org/emacs/elpa.git
1987 If you have an Emacs Savannah developer account, you can use:
1991 git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
1994 @file{build/Makefile} contains targets for copying Ada mode source to
1995 the elpa workspace, and for building the elpa archive there.
1997 @node GNU Free Documentation License, Index, Developer overview, Top
1998 @appendix GNU Free Documentation License
1999 @include doclicense.texi
2001 @node Index, , GNU Free Documentation License, Top