1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/ada-mode
6 Copyright @copyright{} 1999 - 2015 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.9
31 @vskip 0pt plus 1filll
37 @node Top, Overview, (dir), (dir)
39 Ada Mode Version 5.1.9
47 * Installation:: Installing Ada mode on your system
48 * Customization:: Setting up Ada mode to your taste
49 * Compiling Executing:: Working with your application within Emacs
50 * Project files:: Describing the organization of your project
51 * Moving Through Ada Code:: Moving easily through Ada sources
52 * Identifier completion:: Finishing words automatically
53 * Indentation:: Indenting your code automatically as you type
54 * Statement skeletons:: Some code is written for you
55 * Aligning code:: Making it pretty
56 * Automatic casing:: Adjusting the case of words automatically
57 * Comment Handling:: Reformatting comments easily
59 * Developer overview::
60 * GNU Free Documentation License::
64 @node Overview, Installation, Top, Top
67 The Emacs mode for programming in Ada helps the user in reading
68 existing code and facilitates developing new code.
70 Cross-reference information output by the compiler is used to provide
71 powerful code navigation (jump to definition, find all uses, etc).
73 When you open a file with a file extension of @file{.ads} or
74 @file{.adb}, Emacs will automatically load and activate Ada
77 Ada mode works without any customization, if you are using the GNAT
78 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
81 You must customize a few things if you are using a different file
82 naming convention or compiler; @xref{Non-standard file names},
83 @xref{Other compiler}.
85 In addition, you may want to customize the indentation,
86 capitalization, and other things; @xref{Other customization}.
88 Finally, for large Ada projects, you will want to set up an Emacs Ada
89 mode project file for each project; @xref{Project files}. Note that
90 these are different from the GNAT project files used by the GNAT
93 @xref{Debuggers,,Debuggers,emacs,Emacs User Guide}, for general
94 information on debugging.
96 @node Installation, Customization, Overview, Top
99 Ada mode requires Emacs 24.2 or greater.
101 Ada mode is distributed in the Gnu ELPA package archive; it can be
102 installed via @code{M-x list-packages} (@pxref{Packages,,,emacs,Emacs
103 User Guide}). You must first enable packages in your @file{~/.emacs},
104 @emph{after} customizing @code{Info-default-directory-list} (if you do
111 Ada mode is also available as a separate distribution, from the Emacs
113 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}.
115 For installing the separate distribution, see the @file{README} file
118 To see what version of Ada mode you have installed, invoke @kbd{M-x
121 You may also want to install additional utilities:
124 * Ada Reference Manual::
129 @node Ada Reference Manual, gpr_query, Installation, Installation
130 @section Ada Reference Manual
131 The ELPA package ada-ref-man includes the Ada Reference Manual and
132 Annotated Ada Reference Manual in info format.
134 @node gpr_query, Upgrading, Ada Reference Manual, Installation
136 Ada mode has support for an external cross reference
137 tool @code{gpr_query}, which supports Ada, C, C++, and any other
138 language for which AdaCore gcc provides the @code{-fdump-xref}
139 (@code{-fdump-xref} is an AdaCore extension).
141 @c FIXME: list xref features supported by gpr_query but not gnatfind
143 @c C and C++ source code
144 @c ada-xref-overriding-function
145 @c ada-xref-overridden-function
147 @code{gpr_query} requires the @code{gnatcoll} library provided by
148 AdaCore, distributed with GNAT GPL 2014.
150 To build @code{gpr_query}, assuming GNAT GPL 2014 is installed in
151 @file{/usr/gnat-gpl-2014}, and @file{/usr/gnat-gpl-2014/bin} is in
152 PATH (if you are running Windows, use Cygwin bash to run these
153 commands, with GNAT GPL bin first in PATH) (note that
154 gnatcoll-gpl-2014-src.tar.gz unzips to gnatcoll-1.7w-src):
157 tar xf ~/Downloads/gnatcoll-gpl-2014-src.tar.gz
159 ./configure --prefix=/usr/gnat-gpl-2014
160 @c on cygwin, finds cygwin as build type; not a problem
161 @c make Gnatcoll_Build=Debug
162 @c sudo make Gnatcoll_Build=Debug install
165 cd ~/.emacs.d/elpa/ada-mode-5.xx/build
169 To build an sqlite3 executable that is compatible with the database
170 created by @code{gpr_query}:
173 cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
174 gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
177 @node Upgrading, , gpr_query, Installation
178 @section Upgrading from previous versions
180 See the file NEWS for more details; here we summarize only important
181 user interface changes.
188 There are many user interface and API changes between 4.01 and 5.0.1;
189 we only document those that may be hard to diagnose here.
191 @code{prog-mode-hook} is no longer run by @code{ada-mode};
192 @code{ada-mode} is no longer derived from @code{prog-mode}. Use
193 @code{ada-mode-hook} instead.
198 @node Customization, Compiling Executing, Installation, Top
199 @chapter Customizing Ada mode
201 Here we assume you are familiar with setting variables in Emacs,
202 either thru 'customize' or in elisp (in your @file{.emacs} file). For
203 a basic introduction to customize, elisp, and Emacs in general, see
204 the tutorial (@kbd{C-h t}).
207 * Non-standard file names::
209 * Other cross-reference::
210 * Other customization::
213 @node Non-standard file names, Other compiler, Customization, Customization
214 @section Non-standard file names
216 By default, Ada mode is configured to use the GNAT file naming
217 convention, where file names are a simple modification of the Ada
218 names, and the extension for specs and bodies are
219 @samp{.ads} and @samp{.adb}, respectively.
221 Emacs uses the file extension to enable Ada mode; Ada mode uses the
222 file extentions to allow moving from a package body to the
223 corresponding spec and back.
225 Emacs and Ada mode support ways to use alternative file extensions for
226 specs and bodies. Note that you must also tell the compiler about
227 these extensions; doing that is beyond the scope of this manual.
229 For instance, if your spec and bodies files are called
230 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
231 can add the following to your @file{.emacs} file:
234 ;; Tell Ada mode about spec and body extensions
235 (ada-add-extensions "_s.ada" "_b.ada")
237 ;; Tell Emacs to use Ada mode for those extensions
238 (add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
241 You can define additional extensions:
244 (ada-add-extensions ".ads" "_b.ada")
245 (ada-add-extensions ".ads" ".body")
248 This means that whenever Ada mode looks for the body for a file
249 whose extension is @file{.ads}, it will take the first available file
250 that ends with either @file{.adb}, @file{_b.ada} or
253 Simililarly, if Ada mode is looking for a spec, it will look for
254 @file{.ads} or @file{_s.ada}.
256 If the filename excluding the extension is not derived from the Ada
257 name following the GNAT convention, you need to provide an alternate
258 function for @code{ada-file-name-from-ada-name}. Doing that is beyond
259 the scope of this manual; see the current definitions in
260 @file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.
262 @node Other compiler, Other cross-reference, Non-standard file names, Customization
263 @section Other compiler
264 The project variable @code{ada_compiler} (default elisp variable
265 @code{ada-compiler}) is used to index several variables that point to
266 the compiler-specific functions for corresponding Ada mode operations.
268 To use a compiler other than GNAT, you must write Emacs lisp code that
269 provides the interface to the compiler, and set @code{ada-compiler} and
270 the indirection variables.
272 See @file{ada-gnat-compile.el} for an example.
274 @node Other cross-reference, Other customization, Other compiler, Customization
275 @section Other cross-reference
276 The project variable @code{ada_xref} (default elisp variable
277 @code{ada-xref-tool}) is used to index several variables that point to
278 the cross-reference-tool-specific functions for corresponding Ada mode
281 The default cross-reference tool is @file{gnatxref}, provided by the
282 file @file{ada-gnat-xref.el}. One other tool is supported:
283 @file{gpr_query}. To use it, add the following to @file{~/.emacs}:
289 To use @file{gpr_query}, the Ada code @file{gpr_query.adb} must be
290 compiled; see @ref{Installation}. In addition, non-Ada code must be
291 compiled with the AdaCore gcc extension @code{-fdump-xref}.
293 To use a cross reference tool other than the above, you must write
294 Emacs lisp code that provides the interface to the compiler, and set
295 @code{ada-xref-tool} and the indirection variables.
297 See @file{ada-gnat-xref.el} and @file{gpr-query.el} for examples.
299 @node Other customization, , Other cross-reference, Customization
300 @section Other customization
302 All user-settable Ada mode variables can be set via the menu
303 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
306 To modify a specific variable, you can directly call the function
307 @code{customize-variable}; just type @kbd{M-x customize-variable
308 @key{RET} @var{variable-name} @key{RET}}).
310 Alternately, you can specify variable settings in the Emacs
311 configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
312 and the syntax to set a variable is the following:
314 (setq variable-name value)
317 Some general Emacs settings that are useful for Ada files:
319 @item delete-trailing-whitespace
320 Deletes space, tab at end of line and blank lines at end of buffer.
322 Deletes tab characters that have crept into the file.
323 @item indent-tabs-mode
324 Don't insert tab characters when indenting.
325 @item copyright-update
326 Updates the copyright date in the file header comment, to the current
328 @item electric-pair-mode
329 Insert a matching right paren when you type a left paren.
331 Bind @code{hippie-expand} to a key; it expands the word before point, using
332 words from current buffer, other buffers, file names, etc; see
333 @code{hippie-expand-try-functions-list}. You can also add
334 @code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
335 which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
336 (@pxref{Statement skeletons}).
338 Navigate to subprograms and types by name, from a minibuffer menu.
340 Navigate to subprograms and types by name, from a list in a dedicated window.
342 @item jit-lock-defer-time
343 In large files, parsing is slow, so it gets in the way of
344 interactive typing due to immediate font-lock triggering a
345 parse. Delay the font-lock by setting an Emacs file-local variable
350 -- jit-lock-defer-time: 0.5
356 The above can all be set by the following code in your
357 @file{~/.emacs}. Note that some are functions are added to
358 @code{before-save-hook}; they run just before a buffer is written to
359 disk. Also, the order is important; ada-mode does not set up the
360 Ada-specific features of imenu and speedbar unless imenu is loaded
364 (setq-default indent-tabs-mode nil)
365 (electric-pair-mode 1)
366 (require 'imenu) ;; also enables speedbar
368 (add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
369 (define-key ada-mode-map "\C-e" 'hippie-expand)
370 (add-hook 'ada-mode-hook
372 (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
373 (add-hook 'before-save-hook 'copyright-update nil t)
374 (add-hook 'before-save-hook
375 (lambda () (untabify (point-min) (point-max)))
379 @node Compiling Executing, Project files, Customization, Top
380 @chapter Compiling Executing
382 Ada projects can be compiled, linked, and executed using commands on
383 the Ada menu. All of these commands can be customized via a project
384 file (@pxref{Project files}), but the defaults are sufficient for using
385 the GNAT compiler for simple projects (single files, or several files
386 in a single directory).
388 For complex projects, you will want to use @code{make} or some other
389 build tool; in that case, you will need an Emacs Ada mode project file
390 to tell Emacs about the project directory tree and other settings.
394 * Compiling Examples::
398 @node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
399 @section Compile commands
401 Here are the commands for building an Ada project and running the main
404 In multi-file projects, there must be one file that is the main
405 program. That is given by the @code{main} project file variable;
406 it defaults to the current file if not yet set, but is also set by the
407 ``set main and build'' command.
412 Compiles the current file in syntax check mode, by running
413 @code{check_cmd} defined in the current project file. This typically
414 runs faster than full compile mode, speeding up finding and fixing
417 This sets @code{main} only if it has not been set yet.
420 Compiles the current file, by running @code{comp_cmd} from the current
423 This does not set @code{main}.
425 @item Set main and Build
426 Sets @code{main} to the current file, then executes the Build
430 Display @code{main} in the message buffer.
433 Compiles all obsolete units of the current @code{main}, and links
434 @code{main}, by running @code{make_cmd} from the current project.
436 This sets @code{main} only if it has not been set yet.
439 Executes the main program in a shell, displayed in a separate Emacs
440 buffer. This runs @code{run_cmd} from the current project. The
441 execution buffer allows for interactive input/output.
443 To modify the run command, in particular to provide or change the
444 command line arguments, type @kbd{C-u} before invoking the command.
446 This command is not available for a cross-compilation toolchain.
449 It is important when using these commands to understand how
450 @code{main} is used and changed.
452 Build runs 'gnatmake' on the main unit. During a typical edit/compile
453 session, this is the only command you need to invoke, which is why it
454 is bound to @kbd{C-c C-c}. It will compile all files needed by the
455 main unit, and display compilation errors in any of them.
457 Note that Build can be invoked from any Ada buffer; typically you will
458 be fixing errors in files other than the main, but you don't have to
459 switch back to the main to invoke the compiler again.
461 Novices and students typically work on single-file Ada projects. In
462 this case, @kbd{C-c C-m} will normally be the only command needed; it
463 will build the current file, rather than the last-built main.
465 There are three ways to change @code{main}:
469 Invoke @samp{Ada | Set main and Build}, which sets @code{main} to
473 Invoke @samp{Ada | Project | Edit}, edit @code{main} and
474 @code{main}, and click @samp{[save]}
477 Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main}
481 @node Compiling Examples, Compiler errors, Compile commands, Compiling Executing
482 @section Compiling Examples
484 We present several small projects, and walk thru the process of
485 compiling, linking, and running them.
487 The first example illustrates more Ada mode features than the others;
488 you should work thru that example before doing the others.
490 All of these examples assume you are using GNAT.
492 The source for these examples is available on the Emacs Ada mode
493 website mentioned in @xref{Installation}.
496 * No project files:: Just menus
497 * Set compiler options:: A basic Ada mode project file
498 * Set source search path:: Source in multiple directories
499 * Use GNAT project file::
500 * Use multiple GNAT project files::
504 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
505 @subsection No project files
506 This example uses no project files.
508 First, create a directory @file{Example_1}, containing:
516 Put_Line("Hello from hello.adb");
520 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
521 compiler error handling.
523 @file{hello_2.adb} has no errors:
533 @file{hello_pkg.ads} has no errors:
541 @file{hello_pkg.adb}:
548 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
553 Yes, this is missing the keyword @code{body}; another compiler error
554 example. However, note that the indentation engine parser accepts this
555 code with no errors, making it easier to indent slightly illegal Ada
558 In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
559 Check syntax}. You should get a @code{*compilation*} buffer containing
560 something like (the directory paths will be different):
563 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
564 Compilation started at Fri Oct 18 04:23:54
566 gnatmake -u -c -gnatc c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
567 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
568 hello.adb:4:04: "Put_Line" is not visible
569 hello.adb:4:04: non-visible declaration at a-textio.ads:263
570 hello.adb:4:04: non-visible declaration at a-textio.ads:259
571 gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error
573 Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
576 The lines with actual errors (starting with @file{hello.adb}) are
577 highlighted, with the file name in red.
579 Now invoke @samp{Ada | Build | Next compilation error}. Or you can
580 click the middle mouse button on the first error line, or use the key
581 binding shown on the menu. The compilation buffer scrolls to put the
582 first error on the top line, and point is put at the place of the
583 error in the @file{hello.adb} buffer.
585 To fix the error, invoke @samp{Ada | Build | Fix compilation error};
586 this adds ``Ada.Text_Io.'' to the line:
589 Ada.Text_Io.Put_Line ("hello from hello.adb");
592 Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.
594 Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
595 prompted to save the file (if you haven't already). Then the
596 compilation buffer is displayed again, containing:
599 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
600 Compilation started at Fri Oct 18 20:39:33
602 gnatmake -o hello hello -cargs -bargs -largs
604 gnatbind -x hello.ali
605 gnatlink hello.ali -o hello.exe
607 Compilation finished at Fri Oct 18 20:39:34
610 The compilation has succeeded without errors; @file{hello.exe} now
611 exists in the same directory as @file{hello.adb}.
613 Now invoke @samp{Ada | Build | Run}. The @file{*compilation*} buffer
614 is displayed, containing
617 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
618 Compilation started at Fri Oct 18 20:41:53
623 Compilation finished at Fri Oct 18 20:41:53
626 That completes the first part of this example.
628 Now we will compile a multi-file project. Open the file
629 @file{hello_2.adb}, invoke @samp{Ada | Build | Set main and
630 Build}. This finds an error in @file{hello_pkg.adb}:
633 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
636 This demonstrates that gnatmake finds the files needed by the main
637 program. However, it cannot find files in a different directory,
638 unless you use an Emacs Ada mode project file or a GNAT project file
639 to specify the other directories; @xref{Set source search path},
640 @ref{Use GNAT project file}.
642 Invoke @samp{Ada | Build | Show main}; this displays @file{Ada mode
645 Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}:
648 package body Hello_Pkg is
651 Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build |
652 Build}. gnatmake successfully builds @file{hello_2}. This
653 demonstrates that Emacs has remembered the main file, in the project
654 variable @code{main}, and used it for the Build command.
656 Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Build
657 | Run}. The @code{*compilation*} buffer displays @code{Hello from
660 One final point. If you switch back to buffer @file{hello.adb}, and
661 invoke @samp{Ada | Build | Run}, @file{hello_2.exe} will be run. That
662 is because @code{main} is still set to @code{hello_2}, as you can see
663 when you invoke @samp{Ada | Build | Show main}.
665 There are two ways to change @code{main}:
669 Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
673 Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
674 specifies @code{main}.
678 @node Set compiler options, Set source search path, No project files, Compiling Examples
679 @subsection Set compiler options
681 This example illustrates using an Emacs Ada mode project file to set a
684 If you have files from @file{Example_1} open in Emacs, you should
685 close them so you don't get confused. Use menu @samp{File | Close
688 In directory @file{Example_2}, create these files:
696 Put_Line("Hello from hello.adb");
700 This is the same as @file{hello.adb} from @file{Example_1}. It has two
701 errors; missing ``use Ada.Text_IO;'', and no space between
702 @code{Put_Line} and its argument list.
710 This tells the GNAT compiler to check for token spacing; in
711 particular, there must be a space preceding a parenthesis.
713 In buffer @file{hello.adb}, invoke @samp{Ada | Build | Set main and
714 Build}. This finds the project file @file{hello.adp}, uses it to set
715 the compiler options, and builds the project. You should get a
716 @code{*compilation*} buffer containing something like (the directory
717 paths will be different):
720 cd c:/Examples/Example_2/
721 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
722 gcc -c -g -gnatyt hello.adb
723 hello.adb:4:04: "Put_Line" is not visible
724 hello.adb:4:04: non-visible declaration at a-textio.ads:264
725 hello.adb:4:04: non-visible declaration at a-textio.ads:260
726 hello.adb:4:12: (style) space required
727 gnatmake: "hello.adb" compilation error
730 Compare this to the compiler output in @ref{No project files}; the
731 gnatmake option @code{-cargs} has been replaced by @code{-cargs
732 -gnaty}, and an additional error is reported in @file{hello.adb} on
733 line 4. This shows that @file{hello.adp} is being used to set the
736 Fixing the error, linking and running the code proceed as in @ref{No
739 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
740 @subsection Set source search path
742 In this example, we show how to deal with files in more than one
743 directory, using an Emacs Ada mode project file to set the search
746 Create the directory @file{Example_3}, containing:
748 @file{hello_pkg.ads}:
756 @file{hello_pkg.adb}:
763 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
768 These are the same files from example 1; @file{hello_pkg.adb} has an
771 In addition, create a directory @file{Example_3/Other}, containing these files:
773 @file{Other/hello_3.adb}:
777 with Ada.Text_IO; use Ada.Text_IO;
781 Put_Line ("From hello_3");
785 There are no errors in this file.
787 @file{Other/other.adp}:
793 Note that there must be no trailing spaces.
795 In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
796 set project...}, and select @file{Example_3/Other/other.adp}. This
797 tells Emacs Ada mode to stop using the project file from
798 @file{Example_2}, and use the one for @file{Example_3}. Also note that
799 since this project file is not named @file{hello_3.adp}, it would not
802 Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
803 Build}. You should get a @code{*compilation*} buffer containing
804 something like (the directory paths will be different):
807 cd c:/Examples/Example_3/Other/
808 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
809 gcc -c -g -I.. hello_3.adb
810 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
811 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
812 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
815 Compare the @code{-cargs} option to the compiler output in @ref{Set
816 compiler options}; this shows that @file{other.adp} is being used to
817 set the compiler options.
819 Move to the error with @kbd{C-x `}. Ada mode searches the list of
820 directories given by @code{src_dir} for the file mentioned in the
821 compiler error message.
823 Fixing the error, linking and running the code proceed as in @ref{No
826 @node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
827 @subsection Use GNAT project file
829 In this example, we show how to use a GNAT project file, with no Ada
832 Create the directory @file{Example_4}, containing:
834 @file{hello_pkg.ads}:
842 @file{hello_pkg.adb}:
849 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
854 These are the same files from example 1; @file{hello_pkg.adb} has an
857 In addition, create a directory @file{Example_4/Gnat_Project},
858 containing these files:
860 @file{Gnat_Project/hello_4.adb}:
864 with Ada.Text_IO; use Ada.Text_IO;
868 Put_Line ("From hello_4");
872 There are no errors in this file.
874 @file{Gnat_Project/hello_4.gpr}:
878 for Source_Dirs use (".", "..");
882 In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and
883 select @file{Example_4/Gnat_Project/hello_4.gpr}.
885 Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and
886 Build}. You should get a @code{*compilation*} buffer containing
887 something like (the directory paths will be different):
890 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
891 Compilation started at Mon Oct 21 11:28:31
893 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
894 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
895 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
896 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
898 Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
901 Compare the @code{gcc} options to the compiler output in @ref{Set
902 compiler options}; this shows that @file{hello_4.gpr} is being used to
903 set the compiler options.
905 Fixing the error, linking and running the code proceed as in @ref{No
908 @node Use multiple GNAT project files, Use a Makefile, Use GNAT project file, Compiling Examples
909 @subsection Use multiple GNAT project files
911 In this example, we show how to use multiple GNAT project files,
912 specifying the GNAT project search path in an Ada mode project file.
914 Create the directory @file{Example_4} as specified in @ref{Use GNAT
917 Create the directory @file{Example_5}, containing:
923 with Ada.Text_IO; use Ada.Text_IO;
927 Put_Line ("From hello_5");
931 There are no errors in this file.
936 ada_project_path=../Example_4/Gnat_Project
945 for Source_Dirs use (".");
947 for Default_Switches ("Ada") use ("-g", "-gnatyt");
952 In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Find and
953 select project...}, and select @file{Example_5/hello_5.adp}. This
954 would also be found by default if no previous project file had been
957 Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
958 and Build}. You should get a @code{*compilation*} buffer containing
959 something like (the directory paths will be different):
962 -*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
963 Compilation started at Mon Oct 21 11:32:05
965 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
966 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
967 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
968 gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
970 Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
973 Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
974 demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
975 used to set the compilation search path.
977 @node Use a Makefile, , Use multiple GNAT project files, Compiling Examples
978 @subsection Use a Makefile
980 In this example, we show how to use a Makefile to build an Ada project
981 with GNAT, run the result, and clean the build directories.
983 Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
984 project file}, @ref{Use multiple GNAT project files}.
986 In @file{Example_5}, add the file:
991 # build and run hello_5 project
998 gprbuild -Phello_5.gpr hello_5
1004 gnatclean -r -Phello_5
1006 export GPR_PROJECT_PATH = ../Example_4/Gnat_Project
1009 # eval:(ada-parse-prj-file "hello_5.adp")
1010 # eval:(ada-select-prj-file "hello_5.adp")
1014 Close and re-open @file{Makefile}; the @samp{Local Variables} section
1015 sets the project file to @file{hello_5.adp} when the @file{Makefile}
1016 is opened. You can also use @key{C-x C-e} to execute the select line
1017 after the @file{Makefile} is opened, to change the project file back
1018 to @file{hello_5.adp}.
1020 In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
1021 default make command. This runs the @samp{all} target, which builds
1022 @file{hello_5} and runs it.
1024 @node Compiler errors, , Compiling Examples, Compiling Executing
1025 @section Compiler errors
1027 The @code{Check syntax} and @code{Build} commands, or running
1028 @code{make}, place compilation errors in a separate buffer named
1029 @code{*compilation*}.
1031 Each line in this buffer will become active: you can simply click on
1032 it with the middle button of the mouse, or move point to it and press
1033 @key{RET}. Emacs will then display the relevant source file and put
1034 point on the line and column where the error was found.
1036 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
1037 will jump to the first error. If you press that key again, it will
1038 move you to the second error, and so on.
1040 Some error messages also include references to other files. These
1041 references are accessed via @kbd{C-c `}.
1043 @node Project files, Moving Through Ada Code, Compiling Executing, Top
1044 @chapter Project files
1046 An Emacs Ada mode project file specifies what directories hold sources
1047 for your project, and allows you to customize the compilation commands
1048 and other things on a per-project basis.
1050 The default file extension for Ada mode project files is @file{*.adp}
1051 or @file{*.prj}. You can use a different extension by adding it to
1052 @code{ada-prj-file-extensions}, and a different syntax by adding a
1053 parser function to @code{ada-prj-parser-alist}.
1055 Note that Ada mode project files @file{*.adp} are different than GNAT
1056 compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
1057 GNAT project file to specify the project directories. If no
1058 other customization is needed, a GNAT project file can be used without
1059 an Emacs Ada mode project file.
1061 If no Emacs Ada mode project file is specified, some Ada mode
1062 functions are not available.
1065 * Project file overview::
1066 * Project file variables::
1069 @node Project file overview, Project file variables, Project files, Project files
1070 @section Project file overview
1072 Project files have a simple syntax; they may be edited directly. Each
1073 line specifies a project variable name and its value, separated by
1074 ``='' (spaces not allowed):
1076 src_dir=/Projects/my_project/src_1
1077 src_dir=/Projects/my_project/src_2
1080 Any line that does not have an ``='' is a comment.
1082 Some variables (like @code{src_dir}) are lists; multiple occurrences
1085 There must be no space between the variable name and ``='', and no
1086 trailing spaces after the value.
1088 The current project file is given by the lisp variable
1089 @code{ada-prj-default-project-file}, and shown by the menu command
1090 @key{Ada | Project Files | Show project}.
1092 To set the project file, use the menu command @samp{Ada | Set Project
1093 ...}, or the elisp functions @code{ada-parse-prj-file,
1094 ada-select-prj-file}. The latter can be added to a Makefile:
1098 # eval: (ada-parse-prj-file "ada-mode.prj")
1099 # eval: (ada-select-prj-file ada-mode.prj")
1103 You specify either a GNAT project file or an Emacs Ada mode project
1104 file; if the file extension is @code{.gpr}, the file is treated as a
1105 GNAT project file. Extensions given by @code{ada-prj-file-extensions}
1106 (default @file{.adp, .prj}) are treated as an Emacs Ada mode
1109 After a project file is parsed, you can make it current again with
1110 just @code{ada-select-prj-file}, or by selecting it from the menu.
1112 @node Project file variables, , Project file overview, Project files
1113 @section Project file variables
1115 To set a project variable that is a list, specify each element of the
1116 list on a separate line in the project file. The value on the last
1117 line is the last element in the list.
1119 A variable name that starts with @code{$} is set as a process
1120 environment variable, for processes launched from Emacs for the
1123 In variable values, process environment variables can be referenced
1124 using the normal @code{$var} syntax.
1126 Most project variables have defaults that can be changed by setting
1127 elisp variables; the table below identifies the elisp variable for each
1128 project variable. Elisp variables corresponding to project variables
1129 that are lists are elisp lists.
1131 In general, project variables are evaluated when referenced in Emacs
1132 Ada mode commands. Relative file paths are expanded relative to the
1133 directory containing the project file.
1135 Ada mode defines some project variables; others are defined by the
1138 Here is the list of variables valid for all compilers. In the default
1139 values, the current directory @code{"."} is the directory containing
1143 @c These are the names that appear in the .adp file, which are the
1144 @c same as the symbols used with ada-prj-get
1146 @c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
1147 @c defaults defined in ada-mode.el ada-prj-default
1149 @item @code{ada_compiler} [default: @code{ada-compiler, gnat}]
1150 Ada compiler for this project. It must occur in the project file
1151 before any compiler-specific project variable.
1153 @item @code{auto_case} [default: @code{ada-auto-case, t}]
1154 Non-nil means automatically change case of preceding word while typing.
1156 @item @code{case_identifier} [default: @code{ada-case-identifier, ada-mixed-case}]
1157 Function to call to adjust the case of an Ada identifier.
1159 @item @code{case_keyword} [default: @code{ada-case-keyword, downcase-word}]
1160 Function to call to adjust the case of an Ada keyword.
1162 @item @code{case_strict} [default: @code{ada-case-strict, t}]
1163 If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
1164 Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.
1166 @item @code{casing} [default: @code{ada-case-exception-file, nil}]
1167 List of files containing casing exceptions. @xref{Automatic casing}.
1169 @item @code{el_file} [default: ]
1170 The value is a file name, which is loaded as an elisp file when the
1171 project file is parsed or selected. This allows setting Ada mode indentation
1172 variables, and any arbitrary elisp code used to customize the project.
1174 @item @code{path_sep} [default: @code{path-separator}]
1175 Separator character used in compiler search paths.
1177 @item @code{src_dir} [default: @code{"."}]
1178 A list of directories to search for source files.
1180 @item @code{xref_tool} [default: @code{ada-xref-tool, gnat-xref}]
1181 Cross reference tool for this project.
1185 The following variables are valid with the GNAT compiler:
1188 @c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
1189 @item @code{ada_project_path} [default: @code{""}]
1190 @c ada-prj-get 'prj_dir, 'proc_env
1191 A list of directories to search for GNAT project files.
1193 If set, the @code{GPR_PROJECT_PATH} process environment variable is
1194 set to this value in the child process that runs GNAT tools. If not
1195 set, @code{GPR_PROJECT_PATH} in the child process is inherited from
1198 If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
1199 environment variable set in the Emacs process correctly for all of
1200 your projects, you do not need to set this project variable.
1202 The project search path can also be set in GNAT aggregate
1203 projects. However, the gnat tools do not make that path available to
1204 Emacs, so you must duplicate it in an Emacs Ada project file.
1206 @item @code{gpr_file} [default: @code{""}]
1207 The GNAT project file.
1209 If set, the source and project directories specified in the GNAT
1210 project file are appended to @code{src_dir} and
1211 @code{ada_project_path}. This allows specifying Ada source directories
1212 with a GNAT project file, and other source directories with the Emacs
1215 @item @code{gpr_project_path} [default: @code{""}]
1216 Same as @code{ada_project_path}.
1218 @c FIXME: add ada-build project vars
1221 @node Moving Through Ada Code, Identifier completion, Project files, Top
1222 @chapter Moving Through Ada Code
1224 There are several commands to navigate through Ada code. All
1225 these functions are available through the Ada menu and keybindings.
1227 Some of these commands rely on cross reference facilities provided by
1228 the compiler; the standard Emacs Ada mode only supports the GNAT
1229 compiler, but others can be added (@pxref{Other cross-reference}).
1233 @findex ada-goto-declaration
1234 Move from any use of an identifier to its declaration, for from a declaration to
1235 its body (if there is one).
1238 @findex ada-goto-declaration-parent
1239 Move from a child type declaration to the parent type declaration;
1240 display a list of references if there is more than one parent.
1243 @findex ada-next-statement-keyword
1244 Move to the next keyword in the current statement.
1246 For example, if point is on @samp{if}, move to @samp{then}.
1249 @findex ada-prev-statement-keyword
1250 Move to the previous keyword in the current statement.
1252 For example, if point is on @samp{then}, move to @samp{if}.
1255 @findex ada-find-other-file
1256 Switch between corresponding spec and body. There are several special
1261 If the region is active, it is assumed to contain an Ada package
1262 name; position point on the corresponding package declaration.
1265 If point is in the start line of a top level child package
1266 declaration (but not package body), or a child subprogram spec or
1267 body, position point on the corresponding parent package
1271 If point is in the start line of a top level separate body,
1272 position point on the corresponding separate stub declaration.
1275 If point is in a subprogram declaration or body, position point on the
1276 corresponding body or declaration in the other file.
1279 If point is on a @code{with} clause, position point on the
1280 corresponding declaration.
1285 @findex ada-show-references
1286 Show all references to the identifier surrounding point. Use
1287 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
1288 compilation errors).
1291 @findex ada-show-overriding
1292 Show all declarations that override the primitive procedure at
1293 point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
1294 for compilation errors).
1297 @findex ada-show-overridden
1298 Show the declaration that the declaration at point overrides.
1301 Jump back to the previous location.
1303 @item Ada | Misc | Refresh cross reference cache
1304 Cross reference information is loaded from the compiler output when
1305 the first cross reference command is issued. If the code is recompiled
1306 after that, the cross reference information is reloaded by invoking
1311 @node Identifier completion, Indentation, Moving Through Ada Code, Top
1312 @chapter Identifier completion
1314 Emacs provides a general way of completing identifiers: @kbd{M-/}
1315 (bound to @code{dabbrev-expand}). This is an easy way to type faster:
1316 you just have to type the first few letters of an identifier, and then
1317 loop through all the possible completions.
1319 @kbd{M-/} works by parsing all open Ada files for possible
1322 For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
1323 are the only words starting with @samp{my} in any of the open Ada files,
1324 then you will have this scenario:
1327 You type: my@kbd{M-/}
1328 Emacs inserts: @samp{my_identifier}
1329 If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
1330 @samp{my_subprogram}.
1331 Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
1334 This is a very fast way to do completion, and the casing of words will
1337 @node Indentation, Statement skeletons, Identifier completion, Top
1338 @chapter Indentation
1340 Ada mode comes with a full set of rules for automatic indentation. You
1341 can also configure the indentation, via the following variables:
1344 @item @code{ada-indent} (default value: 3)
1345 Number of columns for default indentation.
1347 @item @code{ada-indent-broken} (default value: 2)
1348 Number of columns to indent the continuation of a broken line.
1350 @item @code{ada-indent-comment-col-0} (default value: nil)
1351 If non-nil, comments currently starting in column 0 are left in column
1352 0. Otherwise, they are indented with previous comments or code.
1354 @item @code{ada-indent-comment-gnat} (default value: nil)
1355 If non-nil, comments are indented to meet the GNAT style check; one
1359 multiple of @code{ada-indent}
1363 previous non-blank line
1366 Otherwise, they are indented with previous comments or code.
1368 @item @code{ada-indent-label} (default value: -3)
1369 Number of columns to indent a label.
1371 @item @code{ada-indent-record-rel-type} (default value: 3)
1372 Indentation for @code{record} relative to @code{type} or @code{use}.
1374 @item @code{ada-indent-renames} (default value: 2)
1375 Indentation for @code{renames} relative to the matching subprogram keyword.
1377 If the subprogram has parameters then if @code{ada-indent-renames} is
1378 zero or less the indentation is abs @code{ada-indent-renames} relative
1379 to the open parenthesis; if @code{ada-indent-renames} is one or more
1380 the indentation is relative to the line containing the keyword.
1382 If the subprogram has no parameters then @code{ada-indent-broken} the
1383 indentation is relative to the indentation of the line containing
1386 @item @code{ada-indent-return} (default value: 0)
1387 Indentation for @code{return} relative to the matching
1390 If the function has parameters, then if @code{ada-indent-return} is
1391 zero or less the indentation is abs @code{ada-indent-return} relative
1392 to the open parenthesis; if @code{ada-indent-return} is one or more,
1393 indentation is relative to line containing @code{function}.
1395 If the function has no parameters, @code{ada-indent-broken} is used
1396 relative to line containing @code{function}.
1398 @item @code{ada-indent-use} (default value: ada-indent-broken)
1399 Indentation for the lines in a @code{use} statement.
1401 @item @code{ada-indent-when} (default value: 3)
1402 Indentation for @code{when} relative to @code{exception}, @code{case},
1403 or @code{or} in @code{select}.
1405 @item @code{ada-indent-with} (default value: ada-indent-broken)
1406 Indentation for the lines in a @code{with} context clause.
1410 The indentation variables are buffer local; the global value may be
1411 overridden in an elisp file invoked by an @code{el_file} Emacs Ada
1412 mode project file statement, or in a file local variable section.
1414 The following keys indent portions of the text:
1418 Insert and indent a new line.
1421 Indent the current line, or the current region.
1424 Indent the current statement or declaration.
1428 The indentation algorithm relies on a grammar parser to identify the
1429 syntactic role for keywords and other words in the code. If the code
1430 is accepted by the parser, the indentation is done according to the
1431 rules in the indentation engine.
1433 If the code is not accepted (because it is partially complete during
1434 editing), the indentation engine falls back to the trivial algorithm
1435 of indenting each new line the same as the previous line. Once enough
1436 new text has been entered to make the code acceptable to the parser,
1437 the statement or declaration is properly indented.
1439 For example, if you are entering this code:
1447 when you type @kbd{RET B}, @code{B} is indented to the same column as
1448 @code{if}, because the parser does not find @code{end if;}. Then when
1449 you type the final @code{;} followed by @key{TAB}, all three lines are
1450 indented, putting @code{B} where it belongs.
1452 To be more user friendly, the parser accepts a superset of the Ada
1453 grammer. For example, the parser accepts this code for an @code{if}
1461 In general, any sequence of statements, and many expressions, may be
1464 One way to easily insert empty statements like this is using
1465 @ref{Statement skeletons}.
1467 In rare cases, the parser gets confused; it can be reset by invoking
1468 menu @key{Ada | Misc | Reset parser}. Please report such cases as a
1471 @node Statement skeletons, Aligning code, Indentation, Top
1472 @chapter Statement skeletons
1474 @kbd{C-c C-e} expands the previous one or two words into a statment
1475 skeleton. For example, @kbd{i f C-c C-e} expands to:
1484 All skeleton expansions are accepted by the indentation parser, so
1485 this is a convenient way to insert statements with correct
1488 For named statements (packages, loops, etc), the name is taken from
1489 the word before point, and the name of the statement from the word
1492 Some expansions prompt for more information, such as
1493 whether a spec or body is desired. For example, @kbd{package A_Package
1494 C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
1495 selected, the following code is inserted:
1498 package A_Package is
1503 Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
1504 (without prompting) to:
1514 Note that the order of the keyword @code{declare} and the name
1515 @code{A_Block} are reversed in the expansion; this may take some
1516 getting used to. Alternately, if no name is present in the buffer, you
1517 are prompted for a name: @kbd{declare C-c C-e} first prompts for a
1518 name, then expands to the above.
1520 The variable @code{ada-skel-initial-string} defines what to insert in
1521 a newly created empty buffer. It defaults to @code{@{header@}}, which
1522 is a placeholder defined by @code{ada-skel-header}, which inserts a
1523 typical header with a copyright license (choice of GPL or
1524 restricted). Users will typically want to override the definition of
1525 @code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
1526 provide more choices of copyright license.
1528 @node Aligning code, Automatic casing, Statement skeletons, Top
1529 @chapter Aligning code
1531 Aligning code adds space in each line so that similar parts of
1532 successive lines are aligned vertically. For example, a sequence of
1537 Another : Float := 1.0;
1538 More : Integer := 2;
1541 changes to this when aligned:
1545 Another : Float := 1.0;
1546 More : Integer := 2;
1549 Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
1550 statements surrounding point, or within the selected region.
1552 Parameter lists are also aligned:
1557 Another : out Float := 1.0;
1558 More : in out Integer := 2);
1566 Another : out Float := 1.0;
1567 More : in out Integer := 2);
1570 @node Automatic casing, Comment Handling, Aligning code, Top
1571 @chapter Automatic casing
1573 Casing of identifiers, attributes and keywords is automatically
1574 performed while typing when the variable @code{ada-auto-case} is
1575 non-nil (the default). Every time you type a word separator, the
1576 previous word is automatically cased.
1578 You can customize the automatic casing with the following variables:
1581 @item ada-case-keyword
1582 Value must be one of:
1585 Ada keywords will be lowercase.
1588 Ada keywords will be uppercase.
1591 @item ada-case-strict
1592 If non-nil, all identifiers are forced to @code{Mixed_Case}; first
1593 letter, and letter following ``_'' are uppercase; rest are
1596 If nil, the mixed case characters in identifiers are forced to upper
1597 case, but the other characters are not modified. That allows typing
1598 all uppercase identifiers without defining a casing exception.
1601 You can define exceptions to these rules, in files specified by the
1602 variable @code{ada-case-exception-file}. Each line in a case exception
1603 file specifies the casing of one word or word fragment. If an
1604 exception is defined in multiple files, the first occurrence is used.
1606 If the word starts with an asterisk (@code{*}), it defines the casing
1607 of a word fragment (or ``substring''); part of a word between two
1608 underscores or word boundary.
1618 The word fragment @code{*IO} applies to any word containing ``_io'';
1619 @code{Text_IO}, @code{Hardware_IO}, etc.
1621 @findex ada-case-create-exception
1622 There are two ways to add new items to this file: you can simply edit
1623 it as you would edit any text file. Or you can position point on the
1624 word you want to add, and select menu @samp{Ada | Casing | Create full
1625 exception} or @samp{Ada | Casing | Create partial exception}. The
1626 word will be added to the current list of exceptions and to the file.
1628 It is sometimes useful to have multiple exception files. For
1629 example, one could be the standard Ada acronyms, the second some
1630 company specific exceptions, and the last one some project specific
1631 exceptions. If you set up the variable @code{ada-case-exception-file}
1632 as a list of files, each of them will be parsed and used in your emacs
1633 session. When you create a new exception, you are prompted for the
1636 Other keys and menu entries are defined:
1640 @findex ada-case-adjust-at-point
1641 Adjust case of the word at point. With prefix arg, adjust case even if
1642 in comment. Normally, comments are not affected by case adjust.
1644 @item Ada | Casing | Adjust case region
1645 Adjust case in the active region.
1647 @item Ada | Casing | Adjust case buffer
1648 Adjust case in the active buffer.
1652 @node Comment Handling, Key summary, Automatic casing, Top
1653 @chapter Comment Handling
1655 By default, comment lines get indented like Ada code. There are a few
1656 additional functions to handle comments:
1660 @findex comment-dwim
1661 If the region is active, comment or uncomment it.
1663 If the current line is empty, start a comment.
1665 Otherwise, add a comment at the end of the line, in a column given by
1666 @code{comment-column}.
1669 @findex fill-paragraph
1670 Fill the current comment paragraph.
1673 @node Key summary, Developer overview, Comment Handling, Top
1674 @chapter Key summary
1675 @c search for @kbd and @key. Alphabetical by key sequence
1677 This table summarizes the keys described in this manual. Other keys
1678 are bound by Ada mode; see @key{C-h b} for a complete list. The
1679 Ada menu also displays keys bound to menu operations.
1683 @xref{Identifier completion}.
1684 Complete the word before point; repeat to cycle thru possible
1688 @xref{Comment Handling}.
1689 If the region is active, comment or uncomment it.
1692 @xref{Comment Handling}.
1693 Fill the current comment paragraph.
1697 Insert and indent a new line.
1701 Indent the current line, or the current region.
1705 Indent the current statement or declaration.
1708 @xref{Compiler errors}.
1709 Move to the location of the secondary reference in the current compilation error.
1712 @xref{Aligning code}.
1716 @xref{Compile commands}.
1717 Build the current main program.
1720 @xref{Moving Through Ada Code}.
1721 Move from any use of an identifier to its declaration, for from a declaration to its body.
1724 @xref{Moving Through Ada Code}.
1725 Move from a child type declaration to the parent type declaration.
1728 @xref{Statement skeletons}.
1729 Expand previous one or two words into a statement or declaration
1733 @xref{Compile commands}.
1734 Build the current file.
1737 @xref{Moving Through Ada Code}.
1738 Move to the next keyword in the current statement.
1741 @xref{Moving Through Ada Code}.
1742 Switch between corresponding spec and body, or find other spec.
1745 @xref{Moving Through Ada Code}.
1746 Move to the previous keyword in the current statement.
1749 @xref{Moving Through Ada Code}.
1750 Show all references to the identifier surrounding point.
1753 @xref{Automatic casing}.
1754 Adjust case of the word at point. With prefix arg, adjust case even if
1758 @xref{Moving Through Ada Code}.
1759 Show all declarations that override the primitive procedure at
1763 @xref{Automatic casing}.
1764 Create case exception.
1767 @xref{Compiler errors}.
1768 Move to the location of the next secondary compilation error.
1771 @xref{Compiler errors}.
1772 Move to the location of the next compilation error or show result.
1775 @xref{Comment Handling}.
1776 Fill the current comment paragraph.
1780 @node Developer overview, GNU Free Documentation License, Key summary, Top
1781 @chapter Developer overview
1782 If you'd like to contribute to Ada mode, or just understand the
1783 sources, here's an overview.
1786 * Directory structure::
1787 * Package organization::
1792 @node Directory structure, Package organization, Developer overview, Developer overview
1793 @section Directory structure
1795 @item org.emacs.ada-mode
1801 Elisp files; main code.
1804 Byte-compiled elisp files, not in the distribution. Generated by the
1805 Makefile target @code{byte-compile}, or by the Emacs package installer.
1807 Compiling the parse tables (@file{*-wy.el}) speeds up loading them
1808 significantly. Compiling other files speeds up parsing, but not
1811 One reason to byte-compile files is to find errors; the byte compiler
1812 reports undefined variables, wrong argument counts, etc.
1815 Parse tables, generated from the corresponding grammar @file{*.wy} by
1816 the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
1817 distribution and the monotone repository so users and Elisp developers
1818 don't have to install OpenToken.
1821 Diagnostic output from @file{wisi-generate.exe}, useful for tracing
1822 parses while debugging a grammar issue. Not in the tarball
1823 distribution or the monotone repository.
1826 Grammar files, specifying the language to be parsed. The syntax for
1827 these grammar files is similar to that for bison and wisent, but not
1828 the same; see the OpenToken documentation for more info.
1830 The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
1831 parser, so it tolerates some conflicts and ambiguities. This makes the
1832 grammars easier to write, and in particular makes it possible to let
1833 the Ada grammar closely match Annex P of the Ada Language Reference
1834 Manual (the syntax summary).
1837 Texinfo source for the user guides.
1840 Generated user guide in HTML format.
1843 Generated user guide in Emacs info format.
1849 Makefile for building the user guides, publishing to the web page or
1850 Gnu ELPA. Test drivers.
1853 Makefile for building and testing with the wisi-based
1854 parser. Separate from @file{build}, because there used to be a
1855 SMIE-based parser, and there might be another parser someday.
1857 The emacs used to byte-compile and run tests is given by the 'make'
1858 variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
1859 the make command line or by an environment variable.
1862 All tests for Ada mode, gpr mode, parser.
1864 Each test is run in a separate invocation of Emacs, so it is
1865 completely independent of all other tests.
1867 The tests are driven by the elisp code in @file{build/*.el}.
1869 In general, the Ada mode tests open the file, execute test actions,
1870 re-indent, and re-captialize the entire file. The result is diffed
1871 with the original, and must match.
1873 The test actions are defined by comments with the prefix
1874 @code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
1875 functions. This is used to test navigation features and other parser
1878 @item test/Example_*
1879 Starting files for examples in user guide.
1885 More tests; allows testing path search features.
1888 Tests of the elisp wisi grammar compiler and parser.
1891 @node Package organization, OpenToken, Directory structure, Developer overview
1892 @section Package organization
1901 @node Ada mode, gpr mode, Package organization, Package organization
1902 @subsection Ada mode
1903 Ada mode consists of all files with @file{ada-} prefix in the file
1908 The main file, implementing the keymap, menu, and top level
1911 It allows for different backend implementations for compiling,
1912 cross-referencing, and indenting. The functions for each of these
1913 backends dispatch thru global variables that are set by Emacs Ada mode
1914 project files. They default to the GNAT compiler, the gnatxref cross
1915 reference tool, and the ada-wisi indentation engine.
1918 Provides functions for compiling Ada files without a Makefile (or
1921 @item ada-fix-error.el
1922 Provides an interface to utilities for automatically fixing errors
1923 reported by the compiler. It dispatches to a compiler-specific
1926 @item ada-gnat-compile.el
1927 Implements the Ada mode compiler functions for the GNAT compiler.
1929 @item ada-gnat-xref.el
1930 Implements the Ada mode cross reference functions for the GNAT compiler.
1933 The Ada language grammar, and files generated from it by the OpenToken
1934 tool @file{wisi-generate.exe}.
1936 @item ada-indent-user-options.el
1937 All user-settable options for the Ada indentation engine.
1939 @item ada-mode-compat-23.4.el
1940 Defines functions used by Ada mode that are not in Emacs 23.4.
1942 Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
1943 partially supported. Earlier versions of Emacs are not supported.
1946 The Ada mode user guide source and compiled versions.
1949 Skeletons for expansion of Ada syntax (@pxref{Statement
1950 skeletons}). Extends the Emacs skeleton functions with ``tokens'',
1951 inspired by the lamented Else package (which was inspired by DEC LSE).
1953 @item ada-wisi-opentoken.el
1954 Indentation functions useful when editing OpenToken code; an example
1955 of extending the Ada mode indentation engine for special
1959 Implements the Ada mode indentation functions for the wisi indentation
1964 @node gpr mode, GNAT core, Ada mode, Package organization
1965 @subsection gpr mode
1967 gpr mode consists of all files with @file{gpr-} prefix in the file
1968 name. The functions in each file are similar to the similarly-named
1971 @node GNAT core, Wisi, gpr mode, Package organization
1972 @subsection GNAT core
1976 GNAT is actually a multi-language tool; it builds on top of the
1979 @file{gnat-core.el} is a start at a language-agnostic interface to the
1980 GNAT tools. It was first factored out from @file{ada-gnat.el} and
1981 @file{ada-mode.el} to support the multi-language @file{gpr_query.el}.
1983 More code currently in @file{ada-mode.el} could be migrated to
1984 @file{gnat-core.el}, in particular the project file support.
1987 Provides an interface to the external multi-language cross-reference
1988 tool @file{gpr_query}.
1990 Implements the Ada mode cross-reference functions for the
1991 @file{gpr_query} backend, and a minor mode providing similar
1996 @node Wisi, , GNAT core, Package organization
1999 The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
2004 Implements the lexer, the main parser driver,
2005 parser actions that cache parser information in text properties,
2006 utilities for indenting and navigating using the cached information,
2009 @item wisi-compile.el
2010 Implements the parse table
2011 compiler. @file{wisi-generate.exe} processes the grammar source
2012 @file{*.wy} into an elisp source representation of a parse table
2013 @file{*-wy.el}. That is compiled into an internal structure containing
2014 the state transitions and executable actions. The actions can be any
2015 elisp form; the intent is that they be calls to the action functions
2016 provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
2017 provided by @code{semantic}.
2020 Implements the generalized LALR parser.
2023 @node OpenToken, ELPA, Package organization, Developer overview
2025 Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
2026 the grammar sources into elisp parse tables. See
2027 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
2028 current information about which version of OpenToken is required, and
2031 The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
2032 build directory for OpenToken; you probably need to override it with
2033 an external environment variable or on the @code{make} command line.
2035 @node ELPA, , OpenToken, Developer overview
2037 Ada mode is published via the Gnu ELPA archive. To test a new version
2038 of Ada mode, we use a local Gnu ELPA archive. That requires fetching
2043 git clone git://git.savannah.gnu.org/emacs/elpa.git
2046 If you have an Emacs Savannah developer account, you can use:
2050 git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
2053 @file{build/Makefile} contains targets for copying Ada mode source to
2054 the elpa workspace, and for building the elpa archive there.
2056 @node GNU Free Documentation License, Index, Developer overview, Top
2057 @appendix GNU Free Documentation License
2058 @include doclicense.texi
2060 @node Index, , GNU Free Documentation License, Top