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.7
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::
128 @node Ada Reference Manual, gpr_query, Installation, Installation
129 @section Ada Reference Manual
130 The ELPA package ada-ref-man includes the Ada Reference Manual and
131 Annotated Ada Reference Manual in info format.
133 @node gpr_query, Upgrading, Ada Reference Manual, Installation
135 Ada mode has support for an external cross reference
136 tool @code{gpr_query}, which supports Ada, C, C++, and any other
137 language for which AdaCore gcc provices the @code{-fdump-xref}
138 (@code{-fdump-xref} is an AdaCore extension).
140 @code{gpr_query} requires the @code{gnatcoll} library provided by
141 AdaCore. Ada mode requires the very latest version @code{gnatcoll
142 1.7w} distributed with GNAT GPL 2014.
144 To build @code{gpr_query}, 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 @c make Gnatcoll_Build=Debug
153 @c sudo make Gnatcoll_Build=Debug install
156 cd ~/.emacs.d/elpa/ada-mode-5.xx/build
157 make install-gpr_query
160 To build an sqlite3 executable that is compatible with the database
161 created by @code{gpr_query}:
164 cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
165 gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
168 @node Upgrading, , gpr_query, Installation
169 @section Upgrading from previous versions
171 See the file NEWS for more details; here we summarize only important
172 user interface changes.
179 There are many user interface and API changes between 4.01 and 5.0.1;
180 we only document those that may be hard to diagnose here.
182 @code{prog-mode-hook} is no longer run by @code{ada-mode};
183 @code{ada-mode} is no longer derived from @code{prog-mode}. Use
184 @code{ada-mode-hook} instead.
189 @node Customization, Compiling Executing, Installation, Top
190 @chapter Customizing Ada mode
192 Here we assume you are familiar with setting variables in Emacs,
193 either thru 'customize' or in elisp (in your @file{.emacs} file). For
194 a basic introduction to customize, elisp, and Emacs in general, see
195 the tutorial (@kbd{C-h t}).
198 * Non-standard file names::
200 * Other cross-reference::
201 * Other customization::
204 @node Non-standard file names, Other compiler, Customization, Customization
205 @section Non-standard file names
207 By default, Ada mode is configured to use the GNAT file naming
208 convention, where file names are a simple modification of the Ada
209 names, and the extension for specs and bodies are
210 @samp{.ads} and @samp{.adb}, respectively.
212 Emacs uses the file extension to enable Ada mode; Ada mode uses the
213 file extentions to allow moving from a package body to the
214 corresponding spec and back.
216 Emacs and Ada mode support ways to use alternative file extensions for
217 specs and bodies. Note that you must also tell the compiler about
218 these extensions; doing that is beyond the scope of this manual.
220 For instance, if your spec and bodies files are called
221 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
222 can add the following to your @file{.emacs} file:
225 ;; Tell Ada mode about spec and body extensions
226 (ada-add-extensions "_s.ada" "_b.ada")
228 ;; Tell Emacs to use Ada mode for those extensions
229 (add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
232 You can define additional extensions:
235 (ada-add-extensions ".ads" "_b.ada")
236 (ada-add-extensions ".ads" ".body")
239 This means that whenever Ada mode looks for the body for a file
240 whose extension is @file{.ads}, it will take the first available file
241 that ends with either @file{.adb}, @file{_b.ada} or
244 Simililarly, if Ada mode is looking for a spec, it will look for
245 @file{.ads} or @file{_s.ada}.
247 If the filename excluding the extension is not derived from the Ada
248 name following the GNAT convention, you need to provide an alternate
249 function for @code{ada-file-name-from-ada-name}. Doing that is beyond
250 the scope of this manual; see the current definitions in
251 @file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.
253 @node Other compiler, Other cross-reference, Non-standard file names, Customization
254 @section Other compiler
255 The project variable @code{ada_compiler} (default elisp variable
256 @code{ada-compiler}) is used to index several variables that point to
257 the compiler-specific functions for corresponding Ada mode operations.
259 To use a compiler other than GNAT, you must write Emacs lisp code that
260 provides the interface to the compiler, and set @code{ada-compiler} and
261 the indirection variables.
263 See @file{ada-gnat-compile.el} for an example.
265 @node Other cross-reference, Other customization, Other compiler, Customization
266 @section Other cross-reference
267 The project variable @code{ada_xref} (default elisp variable
268 @code{ada-xref-tool}) is used to index several variables that point to
269 the cross-reference-tool-specific functions for corresponding Ada mode
272 The default cross-reference tool is @file{gnatxref}, provided by the
273 file @file{ada-gnat-xref.el}. One other tool is supported:
274 @file{gpr_query}. To use it, add the following to @file{~/.emacs}:
280 To use @file{gpr_query}, the Ada code @file{gpr_query.adb} must be
281 compiled; see @ref{Installation}.
283 To use a cross reference tool other than the above, you must write
284 Emacs lisp code that provides the interface to the compiler, and set
285 @code{ada-xref-tool} and the indirection variables.
287 See @file{ada-gnat-xref.el} and @file{gpr-query.el} for examples.
289 @node Other customization, , Other cross-reference, Customization
290 @section Other customization
292 All user-settable Ada mode variables can be set via the menu
293 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
296 To modify a specific variable, you can directly call the function
297 @code{customize-variable}; just type @kbd{M-x customize-variable
298 @key{RET} @var{variable-name} @key{RET}}).
300 Alternately, you can specify variable settings in the Emacs
301 configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
302 and the syntax to set a variable is the following:
304 (setq variable-name value)
307 Some general Emacs settings that are useful for Ada files:
309 @item delete-trailing-whitespace
310 Deletes space, tab at end of line and blank lines at end of buffer.
312 Deletes tab characters that have crept into the file.
313 @item indent-tabs-mode
314 Don't insert tab characters when indenting.
315 @item copyright-update
316 Updates the copyright date in the file header comment, to the current
318 @item electric-pair-mode
319 Insert a matching right paren when you type a left paren.
321 Bind @code{hippie-expand} to a key; it expands the word before point, using
322 words from current buffer, other buffers, file names, etc; see
323 @code{hippie-expand-try-functions-list}. You can also add
324 @code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
325 which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
326 (@pxref{Statement skeletons}).
328 Navigate to subprograms and types by name, from a minibuffer menu.
330 Navigate to subprograms and types by name, from a list in a dedicated window.
334 The above can all be set by the following code in your
335 @file{~/.emacs}. Note that some are functions are added to
336 @code{before-save-hook}; they run just before a buffer is written to
337 disk. Also, the order is important; ada-mode does not set up the
338 Ada-specific features of imenu and speedbar unless imenu is loaded
342 (setq-default indent-tabs-mode nil)
343 (electric-pair-mode 1)
344 (require 'imenu) ;; also enables speedbar
346 (add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
347 (define-key ada-mode-map "\C-e" 'hippie-expand)
348 (add-hook 'ada-mode-hook
350 (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
351 (add-hook 'before-save-hook 'copyright-update nil t)
352 (add-hook 'before-save-hook
353 (lambda () (untabify (point-min) (point-max)))
357 @node Compiling Executing, Project files, Customization, Top
358 @chapter Compiling Executing
360 Ada projects can be compiled, linked, and executed using commands on
361 the Ada menu. All of these commands can be customized via a project
362 file (@pxref{Project files}), but the defaults are sufficient for using
363 the GNAT compiler for simple projects (single files, or several files
364 in a single directory).
366 For complex projects, you will want to use @code{make} or some other
367 build tool; in that case, you will need an Emacs Ada mode project file
368 to tell Emacs about the project directory tree and other settings.
372 * Compiling Examples::
376 @node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
377 @section Compile commands
379 Here are the commands for building an Ada project and running the main
382 In multi-file projects, there must be one file that is the main
383 program. That is given by the @code{main} project file variable;
384 it defaults to the current file if not yet set, but is also set by the
385 ``set main and build'' command.
390 Compiles the current file in syntax check mode, by running
391 @code{check_cmd} defined in the current project file. This typically
392 runs faster than full compile mode, speeding up finding and fixing
395 This sets @code{main} only if it has not been set yet.
398 Compiles the current file, by running @code{comp_cmd} from the current
401 This does not set @code{main}.
403 @item Set main and Build
404 Sets @code{main} to the current file, then executes the Build
408 Display @code{main} in the message buffer.
411 Compiles all obsolete units of the current @code{main}, and links
412 @code{main}, by running @code{make_cmd} from the current project.
414 This sets @code{main} only if it has not been set yet.
417 Executes the main program in a shell, displayed in a separate Emacs
418 buffer. This runs @code{run_cmd} from the current project. The
419 execution buffer allows for interactive input/output.
421 To modify the run command, in particular to provide or change the
422 command line arguments, type @kbd{C-u} before invoking the command.
424 This command is not available for a cross-compilation toolchain.
427 It is important when using these commands to understand how
428 @code{main} is used and changed.
430 Build runs 'gnatmake' on the main unit. During a typical edit/compile
431 session, this is the only command you need to invoke, which is why it
432 is bound to @kbd{C-c C-c}. It will compile all files needed by the
433 main unit, and display compilation errors in any of them.
435 Note that Build can be invoked from any Ada buffer; typically you will
436 be fixing errors in files other than the main, but you don't have to
437 switch back to the main to invoke the compiler again.
439 Novices and students typically work on single-file Ada projects. In
440 this case, @kbd{C-c C-m} will normally be the only command needed; it
441 will build the current file, rather than the last-built main.
443 There are three ways to change @code{main}:
447 Invoke @samp{Ada | Set main and Build}, which sets @code{main} to
451 Invoke @samp{Ada | Project | Edit}, edit @code{main} and
452 @code{main}, and click @samp{[save]}
455 Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main}
459 @node Compiling Examples, Compiler errors, Compile commands, Compiling Executing
460 @section Compiling Examples
462 We present several small projects, and walk thru the process of
463 compiling, linking, and running them.
465 The first example illustrates more Ada mode features than the others;
466 you should work thru that example before doing the others.
468 All of these examples assume you are using GNAT.
470 The source for these examples is available on the Emacs Ada mode
471 website mentioned in @xref{Installation}.
474 * No project files:: Just menus
475 * Set compiler options:: A basic Ada mode project file
476 * Set source search path:: Source in multiple directories
477 * Use GNAT project file::
478 * Use multiple GNAT project files::
482 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
483 @subsection No project files
484 This example uses no project files.
486 First, create a directory @file{Example_1}, containing:
494 Put_Line("Hello from hello.adb");
498 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
499 compiler error handling.
501 @file{hello_2.adb} has no errors:
511 @file{hello_pkg.ads} has no errors:
519 @file{hello_pkg.adb}:
526 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
531 Yes, this is missing the keyword @code{body}; another compiler error
532 example. However, note that the indentation engine parser accepts this
533 code with no errors, making it easier to indent slightly illegal Ada
536 In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
537 Check syntax}. You should get a @code{*compilation*} buffer containing
538 something like (the directory paths will be different):
541 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
542 Compilation started at Fri Oct 18 04:23:54
544 gnatmake -u -c -gnatc c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
545 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
546 hello.adb:4:04: "Put_Line" is not visible
547 hello.adb:4:04: non-visible declaration at a-textio.ads:263
548 hello.adb:4:04: non-visible declaration at a-textio.ads:259
549 gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error
551 Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
554 The lines with actual errors (starting with @file{hello.adb}) are
555 highlighted, with the file name in red.
557 Now invoke @samp{Ada | Build | Next compilation error}. Or you can
558 click the middle mouse button on the first error line, or use the key
559 binding shown on the menu. The compilation buffer scrolls to put the
560 first error on the top line, and point is put at the place of the
561 error in the @file{hello.adb} buffer.
563 To fix the error, invoke @samp{Ada | Build | Fix compilation error};
564 this adds ``Ada.Text_Io.'' to the line:
567 Ada.Text_Io.Put_Line ("hello from hello.adb");
570 Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.
572 Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
573 prompted to save the file (if you haven't already). Then the
574 compilation buffer is displayed again, containing:
577 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
578 Compilation started at Fri Oct 18 20:39:33
580 gnatmake -o hello hello -cargs -bargs -largs
582 gnatbind -x hello.ali
583 gnatlink hello.ali -o hello.exe
585 Compilation finished at Fri Oct 18 20:39:34
588 The compilation has succeeded without errors; @file{hello.exe} now
589 exists in the same directory as @file{hello.adb}.
591 Now invoke @samp{Ada | Build | Run}. The @file{*compilation*} buffer
592 is displayed, containing
595 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
596 Compilation started at Fri Oct 18 20:41:53
601 Compilation finished at Fri Oct 18 20:41:53
604 That completes the first part of this example.
606 Now we will compile a multi-file project. Open the file
607 @file{hello_2.adb}, invoke @samp{Ada | Build | Set main and
608 Build}. This finds an error in @file{hello_pkg.adb}:
611 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
614 This demonstrates that gnatmake finds the files needed by the main
615 program. However, it cannot find files in a different directory,
616 unless you use an Emacs Ada mode project file or a GNAT project file
617 to specify the other directories; @xref{Set source search path},
618 @ref{Use GNAT project file}.
620 Invoke @samp{Ada | Build | Show main}; this displays @file{Ada mode
623 Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}:
626 package body Hello_Pkg is
629 Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build |
630 Build}. gnatmake successfully builds @file{hello_2}. This
631 demonstrates that Emacs has remembered the main file, in the project
632 variable @code{main}, and used it for the Build command.
634 Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Build
635 | Run}. The @code{*compilation*} buffer displays @code{Hello from
638 One final point. If you switch back to buffer @file{hello.adb}, and
639 invoke @samp{Ada | Build | Run}, @file{hello_2.exe} will be run. That
640 is because @code{main} is still set to @code{hello_2}, as you can see
641 when you invoke @samp{Ada | Build | Show main}.
643 There are two ways to change @code{main}:
647 Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
651 Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
652 specifies @code{main}.
656 @node Set compiler options, Set source search path, No project files, Compiling Examples
657 @subsection Set compiler options
659 This example illustrates using an Emacs Ada mode project file to set a
662 If you have files from @file{Example_1} open in Emacs, you should
663 close them so you don't get confused. Use menu @samp{File | Close
666 In directory @file{Example_2}, create these files:
674 Put_Line("Hello from hello.adb");
678 This is the same as @file{hello.adb} from @file{Example_1}. It has two
679 errors; missing ``use Ada.Text_IO;'', and no space between
680 @code{Put_Line} and its argument list.
688 This tells the GNAT compiler to check for token spacing; in
689 particular, there must be a space preceding a parenthesis.
691 In buffer @file{hello.adb}, invoke @samp{Ada | Build | Set main and
692 Build}. This finds the project file @file{hello.adp}, uses it to set
693 the compiler options, and builds the project. You should get a
694 @code{*compilation*} buffer containing something like (the directory
695 paths will be different):
698 cd c:/Examples/Example_2/
699 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
700 gcc -c -g -gnatyt hello.adb
701 hello.adb:4:04: "Put_Line" is not visible
702 hello.adb:4:04: non-visible declaration at a-textio.ads:264
703 hello.adb:4:04: non-visible declaration at a-textio.ads:260
704 hello.adb:4:12: (style) space required
705 gnatmake: "hello.adb" compilation error
708 Compare this to the compiler output in @ref{No project files}; the
709 gnatmake option @code{-cargs} has been replaced by @code{-cargs
710 -gnaty}, and an additional error is reported in @file{hello.adb} on
711 line 4. This shows that @file{hello.adp} is being used to set the
714 Fixing the error, linking and running the code proceed as in @ref{No
717 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
718 @subsection Set source search path
720 In this example, we show how to deal with files in more than one
721 directory, using an Emacs Ada mode project file to set the search
724 Create the directory @file{Example_3}, containing:
726 @file{hello_pkg.ads}:
734 @file{hello_pkg.adb}:
741 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
746 These are the same files from example 1; @file{hello_pkg.adb} has an
749 In addition, create a directory @file{Example_3/Other}, containing these files:
751 @file{Other/hello_3.adb}:
755 with Ada.Text_IO; use Ada.Text_IO;
759 Put_Line ("From hello_3");
763 There are no errors in this file.
765 @file{Other/other.adp}:
771 Note that there must be no trailing spaces.
773 In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
774 set project...}, and select @file{Example_3/Other/other.adp}. This
775 tells Emacs Ada mode to stop using the project file from
776 @file{Example_2}, and use the one for @file{Example_3}. Also note that
777 since this project file is not named @file{hello_3.adp}, it would not
780 Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
781 Build}. You should get a @code{*compilation*} buffer containing
782 something like (the directory paths will be different):
785 cd c:/Examples/Example_3/Other/
786 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
787 gcc -c -g -I.. hello_3.adb
788 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
789 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
790 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
793 Compare the @code{-cargs} option to the compiler output in @ref{Set
794 compiler options}; this shows that @file{other.adp} is being used to
795 set the compiler options.
797 Move to the error with @kbd{C-x `}. Ada mode searches the list of
798 directories given by @code{src_dir} for the file mentioned in the
799 compiler error message.
801 Fixing the error, linking and running the code proceed as in @ref{No
804 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
805 @subsection Use GNAT project file
807 In this example, we show how to use a GNAT project file, with no Ada
810 Create the directory @file{Example_4}, containing:
812 @file{hello_pkg.ads}:
820 @file{hello_pkg.adb}:
827 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
832 These are the same files from example 1; @file{hello_pkg.adb} has an
835 In addition, create a directory @file{Example_4/Gnat_Project},
836 containing these files:
838 @file{Gnat_Project/hello_4.adb}:
842 with Ada.Text_IO; use Ada.Text_IO;
846 Put_Line ("From hello_4");
850 There are no errors in this file.
852 @file{Gnat_Project/hello_4.gpr}:
856 for Source_Dirs use (".", "..");
860 In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and
861 select @file{Example_4/Gnat_Project/hello_4.gpr}.
863 Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and
864 Build}. You should get a @code{*compilation*} buffer containing
865 something like (the directory paths will be different):
868 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
869 Compilation started at Mon Oct 21 11:28:31
871 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
872 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
873 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
874 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
876 Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
879 Compare the @code{gcc} options to the compiler output in @ref{Set
880 compiler options}; this shows that @file{hello_4.gpr} is being used to
881 set the compiler options.
883 Fixing the error, linking and running the code proceed as in @ref{No
886 @node Use multiple GNAT project files, Use a Makefile, Use GNAT project file, Compiling Examples
887 @subsection Use multiple GNAT project files
889 In this example, we show how to use multiple GNAT project files,
890 specifying the GNAT project search path in an Ada mode project file.
892 Create the directory @file{Example_4} as specified in @ref{Use GNAT
895 Create the directory @file{Example_5}, containing:
901 with Ada.Text_IO; use Ada.Text_IO;
905 Put_Line ("From hello_5");
909 There are no errors in this file.
914 ada_project_path=../Example_4/Gnat_Project
923 for Source_Dirs use (".");
925 for Default_Switches ("Ada") use ("-g", "-gnatyt");
930 In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Find and
931 select project...}, and select @file{Example_5/hello_5.adp}. This
932 would also be found by default if no previous project file had been
935 Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
936 and Build}. You should get a @code{*compilation*} buffer containing
937 something like (the directory paths will be different):
940 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
941 Compilation started at Mon Oct 21 11:32:05
943 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
944 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
945 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
946 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
948 Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
951 Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
952 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
953 used to set the compilation search path.
955 @node Use a Makefile, , Use multiple GNAT project files, Compiling Examples
956 @subsection Use a Makefile
958 In this example, we show how to use a Makefile to build an Ada project
959 with GNAT, run the result, and clean the build directories.
961 Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
962 project file}, @ref{Use multiple GNAT project files}.
964 In @file{Example_5}, add the file:
969 # build and run hello_5 project
976 gprbuild -Phello_5.gpr hello_5
982 gnatclean -r -Phello_5
984 export GPR_PROJECT_PATH = ../Example_4/Gnat_Project
987 # eval:(ada-parse-prj-file "hello_5.adp")
988 # eval:(ada-select-prj-file "hello_5.adp")
992 Close and re-open @file{Makefile}; the @samp{Local Variables} section
993 sets the project file to @file{hello_5.adp} when the @file{Makefile}
994 is opened. You can also use @key{C-x C-e} to execute the select line
995 after the @file{Makefile} is opened, to change the project file back
996 to @file{hello_5.adp}.
998 In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
999 default make command. This runs the @samp{all} target, which builds
1000 @file{hello_5} and runs it.
1002 @node Compiler errors, , Compiling Examples, Compiling Executing
1003 @section Compiler errors
1005 The @code{Check syntax} and @code{Build} commands, or running
1006 @code{make}, place compilation errors in a separate buffer named
1007 @code{*compilation*}.
1009 Each line in this buffer will become active: you can simply click on
1010 it with the middle button of the mouse, or move point to it and press
1011 @key{RET}. Emacs will then display the relevant source file and put
1012 point on the line and column where the error was found.
1014 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
1015 will jump to the first error. If you press that key again, it will
1016 move you to the second error, and so on.
1018 Some error messages also include references to other files. These
1019 references are accessed via @kbd{C-c `}.
1021 @node Project files, Moving Through Ada Code, Compiling Executing, Top
1022 @chapter Project files
1024 An Emacs Ada mode project file specifies what directories hold sources
1025 for your project, and allows you to customize the compilation commands
1026 and other things on a per-project basis.
1028 The default file extension for Ada mode project files is @file{*.adp}
1029 or @file{*.prj}. You can use a different extension by adding it to
1030 @code{ada-prj-file-extensions}, and a different syntax by adding a
1031 parser function to @code{ada-prj-parser-alist}.
1033 Note that Ada mode project files @file{*.adp} are different than GNAT
1034 compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
1035 GNAT project file to specify the project directories. If no
1036 other customization is needed, a GNAT project file can be used without
1037 an Emacs Ada mode project file.
1039 If no Emacs Ada mode project file is specified, some Ada mode
1040 functions are not available.
1043 * Project file overview::
1044 * Project file variables::
1047 @node Project file overview, Project file variables, Project files, Project files
1048 @section Project file overview
1050 Project files have a simple syntax; they may be edited directly. Each
1051 line specifies a project variable name and its value, separated by
1052 ``='' (spaces not allowed):
1054 src_dir=/Projects/my_project/src_1
1055 src_dir=/Projects/my_project/src_2
1058 Any line that does not have an ``='' is a comment.
1060 Some variables (like @code{src_dir}) are lists; multiple occurrences
1063 There must be no space between the variable name and ``='', and no
1066 The current project file is given by the lisp variable
1067 @code{ada-prj-default-project-file}, and shown by the menu command
1068 @key{Ada | Project Files | Show project}.
1070 To set the project file, use the menu command @samp{Ada | Set Project
1071 ...}, or the elisp functions @code{ada-parse-prj-file,
1072 ada-select-prj-file}. The latter can be added to a Makefile:
1076 # eval: (ada-parse-prj-file "ada-mode.prj")
1077 # eval: (ada-select-prj-file ada-mode.prj")
1081 You specify either a GNAT project file or an Emacs Ada mode project
1082 file; if the file extension is @code{.gpr}, the file is treated as a
1083 GNAT project file. Extensions given by @code{ada-prj-file-extensions}
1084 (default @file{.adp, .prj}) are treated as an Emacs Ada mode
1087 After a project file is parsed, you can make it current again with
1088 just @code{ada-select-prj-file}, or by selecting it from the menu.
1090 @node Project file variables, , Project file overview, Project files
1091 @section Project file variables
1093 To set a project variable that is a list, specify each element of the
1094 list on a separate line in the project file.
1096 Process environment variables can be referenced using the
1097 normal @code{$var} syntax.
1099 Most project variables have defaults that can be changed by setting
1100 elisp variables; the table below identifies the elisp variable for each
1101 project variable. Elisp variables corresponding to project variables
1102 that are lists are elisp lists.
1104 In general, project variables are evaluated when referenced in Emacs
1105 Ada mode commands. Relative file paths are expanded relative to the
1106 directory containing the project file.
1108 Ada mode defines some project variables; others are defined by the
1111 Here is the list of variables valid for all compilers. In the default
1112 values, the current directory @code{"."} is the directory containing
1116 @c These are the names that appear in the .adp file, which are the
1117 @c same as the symbols used with ada-prj-get
1119 @c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
1120 @c defaults defined in ada-mode.el ada-prj-default
1122 @item @code{ada_compiler} [default: @code{ada-compiler, gnat}]
1123 Ada compiler for this project. It must occur in the project file
1124 before any compiler-specific project variable.
1126 @item @code{auto_case} [default: @code{ada-auto-case, t}]
1127 Non-nil means automatically change case of preceding word while typing.
1129 @item @code{case_identifier} [default: @code{ada-case-identifier, ada-mixed-case}]
1130 Function to call to adjust the case of an Ada identifier.
1132 @item @code{case_keyword} [default: @code{ada-case-keyword, downcase-word}]
1133 Function to call to adjust the case of an Ada keyword.
1135 @item @code{case_strict} [default: @code{ada-case-strict, t}]
1136 If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
1137 Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.
1139 @item @code{casing} [default: @code{ada-case-exception-file, nil}]
1140 List of files containing casing exceptions. @xref{Automatic casing}.
1142 @item @code{el_file} [default: ]
1143 The value is a file name, which is loaded as an elisp file when the
1144 project file is parsed or selected. This allows setting Ada mode indentation
1145 variables, and any arbitrary elisp code used to customize the project.
1147 @item @code{path_sep} [default: @code{path-separator}]
1148 Separator character used in compiler search paths.
1150 @item @code{src_dir} [default: @code{"."}]
1151 A list of directories to search for source files.
1153 @item @code{xref_tool} [default: @code{ada-xref-tool, gnat-xref}]
1154 Cross reference tool for this project.
1158 The following variables are valid with the GNAT compiler:
1161 @c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
1162 @item @code{ada_project_path} [default: @code{""}]
1163 @c ada-prj-get 'prj_dir, 'proc_env
1164 A list of directories to search for GNAT project files.
1166 If set, the @code{GPR_PROJECT_PATH} process environment variable is
1167 set to this value in the child process that runs GNAT tools. If not
1168 set, @code{GPR_PROJECT_PATH} in the child process is inherited from
1171 If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
1172 environment variable set in the Emacs process correctly for all of
1173 your projects, you do not need to set this project variable.
1175 The project search path can also be set in GNAT aggregate
1176 projects. However, the gnat tools do not make that path available to
1177 Emacs, so you must duplicate it in an Emacs Ada project file.
1179 @item @code{gpr_file} [default: @code{""}]
1180 The GNAT project file.
1182 If set, the source and project directories specified in the GNAT
1183 project file are appended to @code{src_dir} and
1184 @code{ada_project_path}. This allows specifying Ada source directories
1185 with a GNAT project file, and other source directories with the Emacs
1188 @item @code{gpr_project_path} [default: @code{""}]
1189 Same as @code{ada_project_path}.
1193 @node Moving Through Ada Code, Identifier completion, Project files, Top
1194 @chapter Moving Through Ada Code
1196 There are several commands to navigate through Ada code. All
1197 these functions are available through the Ada menu and keybindings.
1199 Some of these commands rely on cross reference facilities provided by
1200 the compiler; the standard Emacs Ada mode only supports the GNAT
1201 compiler, but others can be added (@pxref{Other cross-reference}).
1205 @findex ada-goto-declaration
1206 Move from any use of an identifier to its declaration, for from a declaration to
1207 its body (if there is one).
1210 @findex ada-goto-declaration-parent
1211 Move from a child type declaration to the parent type declaration;
1212 display a list of references if there is more than one parent.
1215 @findex ada-next-statement-keyword
1216 Move to the next keyword in the current statement.
1218 For example, if point is on @samp{if}, move to @samp{then}.
1221 @findex ada-prev-statement-keyword
1222 Move to the previous keyword in the current statement.
1224 For example, if point is on @samp{then}, move to @samp{if}.
1227 @findex ada-find-other-file
1228 Switch between corresponding spec and body. There are several special
1233 If the region is active, it is assumed to contain an Ada package
1234 name; position point on the corresponding package declaration.
1237 If point is in the start line of a top level child package
1238 declaration (but not package body), or a child subprogram spec or
1239 body, position point on the corresponding parent package
1243 If point is in the start line of a top level separate body,
1244 position point on the corresponding separate stub declaration.
1247 If point is in a subprogram declaration or body, position point on the
1248 corresponding body or declaration in the other file.
1251 If point is on a @code{with} clause, position point on the
1252 corresponding declaration.
1257 @findex ada-show-references
1258 Show all references to the identifier surrounding point. Use
1259 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1260 compilation errors).
1263 @findex ada-show-overriding
1264 Show all declarations that override the primitive procedure at
1265 point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
1266 for compilation errors).
1269 @findex ada-show-overridden
1270 Show the declaration that the declaration at point overrides.
1273 Jump back to the previous location.
1275 @item Ada | Misc | Refresh cross reference cache
1276 Cross reference information is loaded from the compiler output when
1277 the first cross reference command is issued. If the code is recompiled
1278 after that, the cross reference information is reloaded by invoking
1283 @node Identifier completion, Indentation, Moving Through Ada Code, Top
1284 @chapter Identifier completion
1286 Emacs provides a general way of completing identifiers: @kbd{M-/}
1287 (bound to @code{dabbrev-expand}). This is an easy way to type faster:
1288 you just have to type the first few letters of an identifier, and then
1289 loop through all the possible completions.
1291 @kbd{M-/} works by parsing all open Ada files for possible
1294 For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
1295 are the only words starting with @samp{my} in any of the open Ada files,
1296 then you will have this scenario:
1299 You type: my@kbd{M-/}
1300 Emacs inserts: @samp{my_identifier}
1301 If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
1302 @samp{my_subprogram}.
1303 Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
1306 This is a very fast way to do completion, and the casing of words will
1309 @node Indentation, Statement skeletons, Identifier completion, Top
1310 @chapter Indentation
1312 Ada mode comes with a full set of rules for automatic indentation. You
1313 can also configure the indentation, via the following variables:
1316 @item @code{ada-indent} (default value: 3)
1317 Number of columns for default indentation.
1319 @item @code{ada-indent-broken} (default value: 2)
1320 Number of columns to indent the continuation of a broken line.
1322 @item @code{ada-indent-comment-col-0} (default value: nil)
1323 If non-nil, comments currently starting in column 0 are left in column
1324 0. Otherwise, they are indented with previous comments or code.
1326 @item @code{ada-indent-label} (default value: -3)
1327 Number of columns to indent a label.
1329 @item @code{ada-indent-record-rel-type} (default value: 3)
1330 Indentation for @code{record} relative to @code{type} or @code{use}.
1332 @item @code{ada-indent-renames} (default value: 2)
1333 Indentation for @code{renames} relative to the matching subprogram keyword.
1335 If the subprogram has parameters then if @code{ada-indent-renames} is
1336 zero or less the indentation is abs @code{ada-indent-renames} relative
1337 to the open parenthesis; if @code{ada-indent-renames} is one or more
1338 the indentation is relative to the line containing the keyword.
1340 If the subprogram has no parameters then @code{ada-indent-broken} the
1341 indentation is relative to the indentation of the line containing
1344 @item @code{ada-indent-return} (default value: 0)
1345 Indentation for @code{return} relative to the matching
1348 If the function has parameters, then if @code{ada-indent-return} is
1349 zero or less the indentation is abs @code{ada-indent-return} relative
1350 to the open parenthesis; if @code{ada-indent-return} is one or more,
1351 indentation is relative to line containing @code{function}.
1353 If the function has no parameters, @code{ada-indent-broken} is used
1354 relative to line containing @code{function}.
1356 @item @code{ada-indent-use} (default value: ada-indent-broken)
1357 Indentation for the lines in a @code{use} statement.
1359 @item @code{ada-indent-when} (default value: 3)
1360 Indentation for @code{when} relative to @code{exception}, @code{case},
1361 or @code{or} in @code{select}.
1363 @item @code{ada-indent-with} (default value: ada-indent-broken)
1364 Indentation for the lines in a @code{with} context clause.
1368 The indentation variables are buffer local; the global value may be
1369 overridden in an elisp file invoked by an @code{el_file} Emacs Ada
1370 mode project file statement, or in a file local variable section.
1372 The following keys indent portions of the text:
1376 Insert and indent a new line.
1379 Indent the current line, or the current region.
1382 Indent the current statement or declaration.
1386 The indentation algorithm relies on a grammar parser to identify the
1387 syntactic role for keywords and other words in the code. If the code
1388 is accepted by the parser, the indentation is done according to the
1389 rules in the indentation engine.
1391 If the code is not accepted (because it is partially complete during
1392 editing), the indentation engine falls back to the trivial algorithm
1393 of indenting each new line the same as the previous line. Once enough
1394 new text has been entered to make the code acceptable to the parser,
1395 the statement or declaration is properly indented.
1397 For example, if you are entering this code:
1405 when you type @kbd{RET B}, @code{B} is indented to the same column as
1406 @code{if}, because the parser does not find @code{end if;}. Then when
1407 you type the final @code{;} followed by @key{TAB}, all three lines are
1408 indented, putting @code{B} where it belongs.
1410 To be more user friendly, the parser accepts a superset of the Ada
1411 grammer. For example, the parser accepts this code for an @code{if}
1419 In general, any sequence of statements, and many expressions, may be
1422 One way to easily insert empty statements like this is using
1423 @ref{Statement skeletons}.
1425 In rare cases, the parser gets confused; it can be reset by invoking
1426 menu @key{Ada | Misc | Reset parser}. Please report such cases as a
1429 @node Statement skeletons, Aligning code, Indentation, Top
1430 @chapter Statement skeletons
1432 @kbd{C-c C-e} expands the previous one or two words into a statment
1433 skeleton. For example, @kbd{i f C-c C-e} expands to:
1442 All skeleton expansions are accepted by the indentation parser, so
1443 this is a convenient way to insert statements with correct
1446 For named statements (packages, loops, etc), the name is taken from
1447 the word before point, and the name of the statement from the word
1450 Some expansions prompt for more information, such as
1451 whether a spec or body is desired. For example, @kbd{package A_Package
1452 C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
1453 selected, the following code is inserted:
1456 package A_Package is
1461 Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
1462 (without prompting) to:
1472 Note that the order of the keyword @code{declare} and the name
1473 @code{A_Block} are reversed in the expansion; this may take some
1474 getting used to. Alternately, if no name is present in the buffer, you
1475 are prompted for a name: @kbd{declare C-c C-e} first prompts for a
1476 name, then expands to the above.
1478 The variable @code{ada-skel-initial-string} defines what to insert in
1479 a newly created empty buffer. It defaults to @code{@{header@}}, which
1480 is a placeholder defined by @code{ada-skel-header}, which inserts a
1481 typical header with a copyright license (choice of GPL or
1482 restricted). Users will typically want to override the definition of
1483 @code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
1484 provide more choices of copyright license.
1486 @node Aligning code, Automatic casing, Statement skeletons, Top
1487 @chapter Aligning code
1489 Aligning code adds space in each line so that similar parts of
1490 successive lines are aligned vertically. For example, a sequence of
1495 Another : Float := 1.0;
1496 More : Integer := 2;
1499 changes to this when aligned:
1503 Another : Float := 1.0;
1504 More : Integer := 2;
1507 Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
1508 statements surrounding point, or within the selected region.
1510 Parameter lists are also aligned:
1515 Another : out Float := 1.0;
1516 More : in out Integer := 2);
1524 Another : out Float := 1.0;
1525 More : in out Integer := 2);
1528 @node Automatic casing, Comment Handling, Aligning code, Top
1529 @chapter Automatic casing
1531 Casing of identifiers, attributes and keywords is automatically
1532 performed while typing when the variable @code{ada-auto-case} is
1533 non-nil (the default). Every time you type a word separator, the
1534 previous word is automatically cased.
1536 You can customize the automatic casing with the following variables:
1539 @item ada-case-keyword
1540 Value must be one of:
1543 Ada keywords will be lowercase.
1546 Ada keywords will be uppercase.
1549 @item ada-case-strict
1550 If non-nil, all identifiers are forced to @code{Mixed_Case}; first
1551 letter, and letter following ``_'' are uppercase; rest are
1554 If nil, the mixed case characters in identifiers are forced to upper
1555 case, but the other characters are not modified. That allows typing
1556 all uppercase identifiers without defining a casing exception.
1559 You can define exceptions to these rules, in files specified by the
1560 variable @code{ada-case-exception-file}. Each line in a case exception
1561 file specifies the casing of one word or word fragment. If an
1562 exception is defined in multiple files, the first occurrence is used.
1564 If the word starts with an asterisk (@code{*}), it defines the casing
1565 of a word fragment (or ``substring''); part of a word between two
1566 underscores or word boundary.
1576 The word fragment @code{*IO} applies to any word containing ``_io'';
1577 @code{Text_IO}, @code{Hardware_IO}, etc.
1579 @findex ada-case-create-exception
1580 There are two ways to add new items to this file: you can simply edit
1581 it as you would edit any text file. Or you can position point on the
1582 word you want to add, and select menu @samp{Ada | Casing | Create full
1583 exception} or @samp{Ada | Casing | Create partial exception}. The
1584 word will be added to the current list of exceptions and to the file.
1586 It is sometimes useful to have multiple exception files. For
1587 example, one could be the standard Ada acronyms, the second some
1588 company specific exceptions, and the last one some project specific
1589 exceptions. If you set up the variable @code{ada-case-exception-file}
1590 as a list of files, each of them will be parsed and used in your emacs
1591 session. When you create a new exception, you are prompted for the
1594 Other keys and menu entries are defined:
1598 @findex ada-case-adjust-at-point
1599 Adjust case of the word at point. With prefix arg, adjust case even if
1600 in comment. Normally, comments are not affected by case adjust.
1602 @item Ada | Casing | Adjust case region
1603 Adjust case in the active region.
1605 @item Ada | Casing | Adjust case buffer
1606 Adjust case in the active buffer.
1610 @node Comment Handling, Key summary, Automatic casing, Top
1611 @chapter Comment Handling
1613 By default, comment lines get indented like Ada code. There are a few
1614 additional functions to handle comments:
1618 @findex comment-dwim
1619 If the region is active, comment or uncomment it.
1621 If the current line is empty, start a comment.
1623 Otherwise, add a comment at the end of the line, in a column given by
1624 @code{comment-column}.
1627 @findex fill-paragraph
1628 Fill the current comment paragraph.
1631 @node Key summary, Developer overview, Comment Handling, Top
1632 @chapter Key summary
1633 @c search for @kbd and @key. Alphabetical by key sequence
1635 This table summarizes the keys described in this manual. Other keys
1636 are bound by Ada mode; see @key{C-h b} for a complete list. The
1637 Ada menu also displays keys bound to menu operations.
1641 @xref{Identifier completion}.
1642 Complete the word before point; repeat to cycle thru possible
1646 @xref{Comment Handling}.
1647 If the region is active, comment or uncomment it.
1650 @xref{Comment Handling}.
1651 Fill the current comment paragraph.
1655 Insert and indent a new line.
1659 Indent the current line, or the current region.
1663 Indent the current statement or declaration.
1666 @xref{Compiler errors}.
1667 Move to the location of the secondary reference in the current compilation error.
1670 @xref{Aligning code}.
1674 @xref{Compile commands}.
1675 Build the current main program.
1678 @xref{Moving Through Ada Code}.
1679 Move from any use of an identifier to its declaration, for from a declaration to its body.
1682 @xref{Moving Through Ada Code}.
1683 Move from a child type declaration to the parent type declaration.
1686 @xref{Statement skeletons}.
1687 Expand previous one or two words into a statement or declaration
1691 @xref{Compile commands}.
1692 Build the current file.
1695 @xref{Moving Through Ada Code}.
1696 Move to the next keyword in the current statement.
1699 @xref{Moving Through Ada Code}.
1700 Switch between corresponding spec and body, or find other spec.
1703 @xref{Moving Through Ada Code}.
1704 Move to the previous keyword in the current statement.
1707 @xref{Moving Through Ada Code}.
1708 Show all references to the identifier surrounding point.
1711 @xref{Automatic casing}.
1712 Adjust case of the word at point. With prefix arg, adjust case even if
1716 @xref{Moving Through Ada Code}.
1717 Show all declarations that override the primitive procedure at
1721 @xref{Automatic casing}.
1722 Create case exception.
1725 @xref{Compiler errors}.
1726 Move to the location of the next secondary compilation error.
1729 @xref{Compiler errors}.
1730 Move to the location of the next compilation error or show result.
1733 @xref{Comment Handling}.
1734 Fill the current comment paragraph.
1738 @node Developer overview, GNU Free Documentation License, Key summary, Top
1739 @chapter Developer overview
1740 If you'd like to contribute to Ada mode, or just understand the
1741 sources, here's an overview.
1744 * Directory structure::
1745 * Package organization::
1750 @node Directory structure, Package organization, Developer overview, Developer overview
1751 @section Directory structure
1753 @item org.emacs.ada-mode
1759 Elisp files; main code.
1762 Byte-compiled elisp files, not in the distribution. Generated by the
1763 Makefile target @code{byte-compile}, or by the Emacs package installer.
1765 Compiling the parse tables (@file{*-wy.el}) speeds up loading them
1766 significantly. Compiling other files speeds up parsing, but not
1769 One reason to byte-compile files is to find errors; the byte compiler
1770 reports undefined variables, wrong argument counts, etc.
1773 Parse tables, generated from the corresponding grammar @file{*.wy} by
1774 the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
1775 distribution and the monotone repository so users and Elisp developers
1776 don't have to install OpenToken.
1779 Diagnostic output from @file{wisi-generate.exe}, useful for tracing
1780 parses while debugging a grammar issue. Not in the tarball
1781 distribution or the monotone repository.
1784 Grammar files, specifying the language to be parsed. The syntax for
1785 these grammar files is similar to that for bison and wisent, but not
1786 the same; see the OpenToken documentation for more info.
1788 The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
1789 parser, so it tolerates some conflicts and ambiguities. This makes the
1790 grammars easier to write, and in particular makes it possible to let
1791 the Ada grammar closely match Annex P of the Ada Language Reference
1792 Manual (the syntax summary).
1795 Texinfo source for the user guides.
1798 Generated user guide in HTML format.
1801 Generated user guide in Emacs info format.
1807 Makefile for building the user guides, publishing to the web page or
1808 Gnu ELPA. Test drivers.
1811 Makefile for building and testing with the wisi-based
1812 parser. Separate from @file{build}, because there used to be a
1813 SMIE-based parser, and there might be another parser someday.
1815 The emacs used to byte-compile and run tests is given by the 'make'
1816 variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
1817 the make command line or by an environment variable.
1820 All tests for Ada mode, gpr mode, parser.
1822 Each test is run in a separate invocation of Emacs, so it is
1823 completely independent of all other tests.
1825 The tests are driven by the elisp code in @file{build/*.el}.
1827 In general, the Ada mode tests open the file, execute test actions,
1828 re-indent, and re-captialize the entire file. The result is diffed
1829 with the original, and must match.
1831 The test actions are defined by comments with the prefix
1832 @code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
1833 functions. This is used to test navigation features and other parser
1836 @item test/Example_*
1837 Starting files for examples in user guide.
1843 More tests; allows testing path search features.
1846 Tests of the elisp wisi grammar compiler and parser.
1849 @node Package organization, OpenToken, Directory structure, Developer overview
1850 @section Package organization
1859 @node Ada mode, gpr mode, Package organization, Package organization
1860 @subsection Ada mode
1861 Ada mode consists of all files with @file{ada-} prefix in the file
1866 The main file, implementing the keymap, menu, and top level
1869 It allows for different backend implementations for compiling,
1870 cross-referencing, and indenting. The functions for each of these
1871 backends dispatch thru global variables that are set by Emacs Ada mode
1872 project files. They default to the GNAT compiler, the gnatxref cross
1873 reference tool, and the ada-wisi indentation engine.
1876 Provides functions for compiling Ada files without a Makefile (or
1879 @item ada-fix-error.el
1880 Provides an interface to utilities for automatically fixing errors
1881 reported by the compiler. It dispatches to a compiler-specific
1884 @item ada-gnat-compile.el
1885 Implements the Ada mode compiler functions for the GNAT compiler.
1887 @item ada-gnat-xref.el
1888 Implements the Ada mode cross reference functions for the GNAT compiler.
1891 The Ada language grammar, and files generated from it by the OpenToken
1892 tool @file{wisi-generate.exe}.
1894 @item ada-indent-user-options.el
1895 All user-settable options for the Ada indentation engine.
1897 @item ada-mode-compat-23.4.el
1898 Defines functions used by Ada mode that are not in Emacs 23.4.
1900 Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
1901 partially supported. Earlier versions of Emacs are not supported.
1904 The Ada mode user guide source and compiled versions.
1907 Skeletons for expansion of Ada syntax (@pxref{Statement
1908 skeletons}). Extends the Emacs skeleton functions with ``tokens'',
1909 inspired by the lamented Else package (which was inspired by DEC LSE).
1911 @item ada-wisi-opentoken.el
1912 Indentation functions useful when editing OpenToken code; an example
1913 of extending the Ada mode indentation engine for special
1917 Implements the Ada mode indentation functions for the wisi indentation
1922 @node gpr mode, GNAT core, Ada mode, Package organization
1923 @subsection gpr mode
1925 gpr mode consists of all files with @file{gpr-} prefix in the file
1926 name. The functions in each file are similar to the similarly-named
1929 @node GNAT core, Wisi, gpr mode, Package organization
1930 @subsection GNAT core
1934 GNAT is actually a multi-language tool; it builds on top of the
1937 @file{gnat-core.el} is a start at a language-agnostic interface to the
1938 GNAT tools. It was first factored out from @file{ada-gnat.el} and
1939 @file{ada-mode.el} to support the multi-language @file{gpr_query.el}.
1941 More code currently in @file{ada-mode.el} could be migrated to
1942 @file{gnat-core.el}, in particular the project file support.
1945 Provides an interface to the external multi-language cross-reference
1946 tool @file{gpr_query}.
1948 Implements the Ada mode cross-reference functions for the
1949 @file{gpr_query} backend, and a minor mode providing similar
1954 @node Wisi, , GNAT core, Package organization
1957 The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
1962 Implements the lexer, the main parser driver,
1963 parser actions that cache parser information in text properties,
1964 utilities for indenting and navigating using the cached information,
1967 @item wisi-compile.el
1968 Implements the parse table
1969 compiler. @file{wisi-generate.exe} processes the grammar source
1970 @file{*.wy} into an elisp source representation of a parse table
1971 @file{*-wy.el}. That is compiled into an internal structure containing
1972 the state transitions and executable actions. The actions can be any
1973 elisp form; the intent is that they be calls to the action functions
1974 provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
1975 provided by @code{semantic}.
1978 Implements the generalized LALR parser.
1981 @node OpenToken, ELPA, Package organization, Developer overview
1983 Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
1984 the grammar sources into elisp parse tables. See
1985 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
1986 current information about which version of OpenToken is required, and
1989 The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
1990 build directory for OpenToken; you probably need to override it with
1991 an external environment variable or on the @code{make} command line.
1993 @node ELPA, , OpenToken, Developer overview
1995 Ada mode is published via the Gnu ELPA archive. To test a new version
1996 of Ada mode, we use a local Gnu ELPA archive. That requires fetching
2001 git clone git://git.savannah.gnu.org/emacs/elpa.git
2004 If you have an Emacs Savannah developer account, you can use:
2008 git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
2011 @file{build/Makefile} contains targets for copying Ada mode source to
2012 the elpa workspace, and for building the elpa archive there.
2014 @node GNU Free Documentation License, Index, Developer overview, Top
2015 @appendix GNU Free Documentation License
2016 @include doclicense.texi
2018 @node Index, , GNU Free Documentation License, Top