1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../info/ada-mode
6 * Ada mode: (ada-mode). The GNU Emacs mode for editing Ada.
9 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
10 @comment The following lines inserts the copyright notice
11 @comment into the Info file.
12 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
15 Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.1 or
19 any later version published by the Free Software Foundation; with the
20 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
21 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
22 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
23 license is included in the section entitled ``GNU Free Documentation
24 License'' in the Emacs manual.
26 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
27 this GNU Manual, like GNU software. Copies published by the Free
28 Software Foundation raise funds for GNU development.''
30 This document is part of a collection distributed under the GNU Free
31 Documentation License. If you want to distribute this document
32 separately from the collection, you can do so by adding a copy of the
33 license to the document, as described in section 6 of the license.
36 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
37 @comment TeX title page
38 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
44 @subtitle An Emacs major mode for programming Ada 95 with GNAT
45 @subtitle July 1998 for Ada Mode Version 3.0
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.1 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
56 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
57 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
58 license is included in the section entitled ``GNU Free Documentation
59 License'' in the Emacs manual.
61 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
62 this GNU Manual, like GNU software. Copies published by the Free
63 Software Foundation raise funds for GNU development.''
65 This document is part of a collection distributed under the GNU Free
66 Documentation License. If you want to distribute this document
67 separately from the collection, you can do so by adding a copy of the
68 license to the document, as described in section 6 of the license.
72 @node Top, Overview, (dir), (dir)
76 * Installation:: Installing Ada mode on your system
77 * Customization:: Setting up Ada mode to your taste
78 * Project files:: Describing the organization of your project
79 * Syntax highlighting:: Using specific colors and fonts to highlight
80 the structure of your files
81 * Moving Through Ada Code:: Moving easily through Ada sources
82 * Identifier completion:: Finishing words automatically
83 * Index Menu of Subprograms:: A menu of all the types and subprograms
84 defined in your application
85 * File Browser:: Easy access to your files
86 * Automatic Smart Indentation:: Indenting your code automatically as you type
87 * Formatting Parameter Lists:: Formating subprograms parameter lists
89 * Automatic Casing:: Adjusting the case of words automatically
90 * Statement Templates:: Inserting code templates
91 * Comment Handling:: Reformatting comments easily
92 * Compiling Executing:: Working with your application within Emacs
93 * Debugging:: Debugging your application
94 * Using non-standard file names:: Configuring Emacs for special file names
95 * Working Remotely:: Working on a different machine
100 @c -----------------------------------------------------------------------
101 @node Overview, Installation, Top, Top
103 @c -----------------------------------------------------------------------
105 The Emacs mode for programming in Ada 95 with GNAT helps the user in
106 understanding existing code and facilitates writing new code. It
107 furthermore provides some utility functions for easier integration of
108 standard Emacs features when programming in Ada.
110 @section General features:
114 full Integrated Development Environment:
117 support of ``project files'' for the configuration (directories,
118 compilation options,...)
120 compiling and stepping through error messages.
122 running and debugging your applications within Emacs.
125 easy to use for beginners by pull-down menus,
127 user configurable by many user-option variables.
130 @section Ada mode features that help understanding code:
134 functions for easy and quick stepping through Ada code,
136 getting cross reference information for identifiers (e.g. find the
137 defining place by a keystroke),
139 displaying an index menu of types and subprograms and move point to
142 automatic color highlighting of the various entities in Ada code.
145 @section Emacs support for writing Ada code:
149 switching between spec and body files with eventually
150 auto-generation of body files,
152 automatic formating of subprograms parameter lists.
154 automatic smart indentation according to Ada syntax,
156 automatic completion of identifiers,
158 automatic casing of identifiers, keywords, and attributes,
160 insertion of statement templates,
162 filling comment paragraphs like filling normal text,
165 @c -----------------------------------------------------------------------
166 @node Installation, Customization, Overview, Top
167 @chapter Installation
168 @c -----------------------------------------------------------------------
170 If you got Ada mode as a separate distribution, you should have a
171 look at the @file{README} file. It explains the basic steps necessary
172 for a good installation of the emacs Ada mode.
174 Installing the Ada mode is basically just a matter of copying a few
175 files into the Emacs library directories. Every time you open a file
176 with a file extension of @file{.ads} or @file{.adb}, Emacs will
177 automatically load and activate Ada mode.
179 @xref{Using non-standard file names}, if your files do
180 not use these extensions and if you want Emacs to automatically start the
181 Ada mode every time you edit an Ada file.
183 See also the Emacs Manual (@pxref{(Top,,,emacs, The Emacs Manual)}),
184 for general usage variables that you might want to set.
186 @c ---------------------------------------------------------------------
187 @section Required files
188 @c ---------------------------------------------------------------------
190 This Ada mode works best with Emacs 20.3 or higher (the easy editing
191 features for the project files won't work with any older version), but
192 most of the commands should work with older versions too. Please try to
193 install the most recent version of Emacs on your system before
196 Although part of Ada mode is compiler-independent, the most advanced
197 features are specific to the Gnat compiler @url{http://www.gnat.com}.
199 The following files are provided with the Ada mode distribution:
204 @file{ada-mode.el}: The main file for Ada mode.
205 This is the only file which does not require Gnat. It contains the
206 functions for indentation, formatting of parameter lists, stepping
207 through code, comment handling and automatic casing. Emacs versions
208 20.2 and higher already contain Ada mode version 2.27, which is an older
209 version of this file and should be replaced. Loading @file{ada-mode.el}
210 from the current distribution supersedes the standard installation.
213 @file{ada-stmt.el}: Contains the statement templates feature.
216 @file{ada-xref.el}: This file provides the main support for Gnat.
217 This is where the functions for cross-references, completion of
218 identifiers, support for project files and compilation of your
219 application are defined.
222 @file{ada-prj.el}: The functions to use for easy-edition of the
223 project files. This file is the only one which really requires Emacs
224 at least 20.2. It uses the new widget features from Emacs.
228 @c --------------------------------------------------------------------
229 @node Customization, Project files, Installation, Top
230 @chapter Customizing Ada mode
231 @c ---------------------------------------------------------------------
233 Ada mode is fully customizable. Everything, from the file names to
234 the automatic indentation and the automatic casing can be adapted to
237 There are two different kinds of variables that control this
238 customization, both are easy to modify.
240 The first set of variables are standard Emacs variables. Of course, some
241 are defined only for Ada mode, whereas others have a more general
242 meaning in Emacs. Please see the Emacs documentation for more
243 information on the latest. In this documentation, we will detail all the
244 variables that are specific to Ada mode, and a few others. The names
245 will be given, as in @code{ada-case-identifier}.
247 Emacs provides an easy way to modify them, through a special mode called
248 customization. To access this mode, select the menu
249 @samp{Ada->Customize}. This will open a new buffer with some fields that
250 you can edit. For instance, you will get something like:
252 Put below the compiler switches.
253 comp_opt= _____________________________________
255 The first line gives a brief description of the variable. The second
256 line is the name of the variable and the field where you can give a
257 value for this variable. Simply type what you want in the field.
259 When you are finished modifying the variables, you can simply click on
260 the @b{Save for future sessions} button at the top of the buffer (click
261 with the middle mouse button). This will save the values in your
262 @file{.emacs} file, so that next time you start Emacs they will have the
265 To modify a specific variable, you can directly call the function
266 @code{customize-variable} from Emacs (just type @kbd{M-x
267 customize-variable @key{RET} @var{variable-name} @key{RET}}).
269 Some users might prefer to modify the variables directly in their
270 configuration file, @file{.emacs}. This file is coded in Emacs lisp, and
271 the syntax to set a variable is the following:
273 (setq variable-name value)
276 The second set of variables for customization are set through the use of
277 project files. These variables are specific to a given project, whereas
278 the first set was more general. For more information, please
279 @xref{Project files}.
281 @c ---------------------------------------------------------------------
282 @node Project files, Syntax highlighting, Customization, Top
283 @chapter Project files
284 @c ---------------------------------------------------------------------
286 @c ---------------------------------------------------------------------
287 @section General overview
288 @c ---------------------------------------------------------------------
290 Emacs provides a full Integrated Development Environment for GNAT and
291 Ada programmers. That is to say, editing, compiling, executing and
292 debugging can be performed within Emacs in a convenient and natural way.
294 To take full advantage of this features, it is possible to create a file
295 in the main directory of your application, with a @samp{.adp} extension.
296 This file contain all needed information dealing with the way your
297 application is organized between directories, the commands to compile,
298 run and debug it etc. Creating this file is not mandatory and convenient
299 defaults are automatically provided for simple setups. It only becomes
300 necessary when those above mentioned defaults need customizing.
302 A simple way to edit this file is provided for Emacs 20.2 or newer, with
303 the following functions, that you can access also through the Ada
304 menu. It is also possible to edit the project file as a regular text
307 Once in the buffer for editing the project file, you can save your
308 modification using the @samp{[OK]} button at the bottom of the buffer, or
309 simply use the usual @kbd{C-x C-s} binding. To cancel your
310 modifications, simply kill the buffer or click on the @samp{[CANCEL]} button
313 Each buffer using Ada mode will be associated with one project file when
314 there is one available, so that Emacs can easily navigate through
315 related source files for instance.
317 The exact algorithm to determine which project file should be used is
318 described in the next section, but you can force the project file you
319 want to use by setting one or two variables in your @file{.emacs} file.
323 To set up a default project file to use for any directory, anywhere
324 on your system, set the variable @code{ada-prj-default-project-file} to
325 the name of that file.
328 (set 'ada-prj-default-project-file "/dir1/dir2/file")
332 For finer control, you can set a per-directory project file.
333 This is done through the variable @code{ada-xref-default-prj-file}.
336 (set 'ada-xref-default-prj-file
337 '(("/dir1/dir2" . "/dir3/file1")
338 ("/dir4/dir5" . "/dir6/file2")))
341 Note: This has a higher priority than the first variable, so the first
342 choice is to use this variable settings, and otherwise
343 @code{ada-prj-default-project-file}.
349 @findex ada-customize
350 Create or edit the project file for the current buffer (@code{ada-customize}).
352 @findex ada-change-prj
353 Change the project file associated with the current Ada buffer (@code{ada-change-prj}).
355 @findex ada-change-default-project
356 Change the default project file for the current directory
357 (@code{ada-change-default-project}). Every new file opened from this
358 directory will be associated with that file by default.
359 @item ada-set-default-project-file
360 @findex ada-set-default-project-file
361 Set the default project file to use for *any* Ada file opened anywhere
362 on your system. This sets this file only for the current Emacs session.
365 @c ---------------------------------------------------------------------
366 @section Project file variables
367 @c ---------------------------------------------------------------------
369 The following variables can be defined in a project file. They all have
370 a default value, so that small projects do not need to create a project
373 Some variables below can be referenced in other variables, using a
374 shell-like notation. For instance, if the variable @code{comp_cmd}
375 contains a sequence like @code{$@{comp_opt@}}, the value of that variable
378 Here is the list of variables:
381 @item @code{src_dir} [default: @code{"./"}]
382 This is a list of directories where Ada mode will look for source
383 files. These directories are used mainly in two cases, both as a switch
384 for the compiler and for the cross-references.
386 @item @code{obj_dir} [default: @code{"./"}]
387 This is a list of directories where to look for object and library
388 files. The library files are the @samp{.ali} files generated by Gnat
389 and that contain cross-reference informations.
391 @item @code{comp_opt} [default: @code{""}]
392 Creates a variable which can be referred to subsequently by using the
393 @code{$@{comp_opt@}} notation. This is intended to store the default
394 switches given to @command{gnatmake} and @command{gcc}.
396 @item @code{bind_opt=@var{switches}} [default: @code{""}]
397 Creates a variable which can be referred to subsequently by using the
398 @code{$@{bind_opt@}} notation. This is intended to store the default
399 switches given to @command{gnatbind}.
401 @item @code{link_opt=@var{switches}} [default: @code{""}]
402 Creates a variable which can be referred to subsequently by using the
403 @code{$@{link_opt@}} notation. This is intended to store the default
404 switches given to @command{gnatlink}.
406 @item @code{main=@var{executable}} [default: @code{""}]
407 Specifies the name of the executable for the application. This variable
408 can be referred to in the following lines by using the @code{$@{main@}}
411 @item @code{cross_prefix=@var{prefix}} [default: @code{""}]
412 This variable should be set if you are working in a cross-compilation
413 environment. This is the prefix used in front of the gnatmake commands.
415 @item @code{remote_machine=@var{machine}} [default: @code{""}]
416 This is the name of the machine to log into before issuing the
417 compilation command. If this variable is empty, the command will be
418 run on the local machine. This will not work on Windows NT machines,
419 since Ada mode will simply precede the compilation command with a
420 @command{rsh} command, unknown on Windows.
422 @item @code{comp_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"}]
423 Specifies the command used to compile a single file in the application.
424 The name of the file will be added at the end of this command.
426 @item @code{make_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gnatmake $@{main@} -aI$@{src_dir@} -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"]}'
427 Specifies the command used to recompile the whole application.
429 @item @code{run_cmd=@var{command}} [default: @code{"$@{main@}"}]
430 Specifies the command used to run the application.
432 @item @code{debug_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
433 Specifies the command used to debug the application
437 @c ---------------------------------------------------------------------
438 @section Detailed algorithm
439 @c ---------------------------------------------------------------------
441 This section gives more details on the project file setup and is only of
442 interest for advanced users.
444 Usually, an Ada file is part of a larger application, whose sources and
445 objects can be spread over multiple directories. The first time emacs is
446 asked to compile, run or debug an application, or when a cross reference
447 function is used (goto declaration for instance), the following steps
452 find the appropriate project file, open and parse it.
453 All the fields read in the project file are then stored by emacs
454 locally. Finding the project file requires a few steps:
458 if a file from the same directory was already associated with
459 a project file, use the same one. This is the variable
460 @code{ada-xref-default-prj-file} described above.
462 if the variable @code{ada-prj-default-project-file} is set,
463 use the project file specified in this variable.
465 if there is a project file whose name is the same as the source file
466 except for the suffix, use this one.
468 if there's only one project file in the source directory, use
471 if there are more than one project file in the source directory,
474 if there are no project files in the source directory use standard
478 The first project file that is selected in a given directory becomes the
479 default project file for this directory and is used implicitly for other
480 sources unless specified otherwise by the user.
483 look for the corresponding @samp{.ali} file in the @code{obj_dir} defined
484 in the project file. If this file can not be found, emacs proposes to
485 compile the source using the @code{comp_cmd} defined in the project file
486 in order to create the ali file.
489 when cross referencing is requested, the @samp{.ali} file is parsed to
490 determine the file and line of the identifier definition. It is
491 possible for the @samp{.ali} file to be older than the source file,
492 in which case it will be recompiled if the variable
493 @code{ada-xref-create-ali} is set, otherwise the reference is searched
494 in the obsolete ali file with possible inaccurate results.
497 look for the file containing the declaration using the source
498 path @code{src_dir} defined in the project file. Put the cursor at the
499 correct position and display this new cursor.
502 @c -----------------------------------------------------------------------
503 @node Syntax highlighting, Moving Through Ada Code, Project files, Top
504 @chapter Syntax highlighting
505 @c -----------------------------------------------------------------------
507 Ada mode is made to help you understand the structure of your source
508 files. Some people like having colors or different fonts depending on
509 the context: commands should be displayed differently than keywords,
510 which should also be different from strings, @dots{}
512 Emacs is able to display in a different way the following syntactic
519 @item gnatprep statements (preprocessor)
520 @item types (under certain conditions)
524 This is not the default behavior for Emacs. You have to explicitly
525 activate it. This requires that you add a new line in your @file{.emacs}
526 file (if this file does not exist, just create it).
529 (global-font-lock-mode t)
532 But the default colors might not be the ones you like. Fortunately,
533 there is a very easy way to change them. Just select the menu
534 @samp{Help->Customize->Specific Face...} and press @key{RET}. This
535 will display a buffer will all the ``faces'' (the colors) that Emacs knows
536 about. You can change any of them.
539 @c -----------------------------------------------------------------------
540 @node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top
541 @chapter Moving Through Ada Code
542 @c -----------------------------------------------------------------------
544 There are several easy to use commands to stroll through Ada code. All
545 these functions are available through the Ada menu, and you can also use
546 the following key bindings or the command names:
550 @findex ada-next-procedure
551 Move to the next function/procedure/task, which ever comes next
552 (@code{ada-next-procedure}).
554 @findex ada-previous-procedure
555 Move to previous function/procedure/task
556 (@code{ada-previous-procedure}).
557 @item M-x ada-next-package
558 @findex ada-next-package
559 Move to next package.
560 @item M-x ada-prev-package
561 @findex ada-prev-package
562 Move to previous package.
564 @findex ada-move-to-start
565 Move to matching start of @code{end} (@code{ada-move-to-start}). If
566 point is at the end of a subprogram, this command jumps to the
567 corresponding @code{begin} if the user option
568 @code{ada-move-to-declaration} is @code{nil} (default), it jumps to
569 the subprogram declaration otherwise.
571 @findex ada-move-to-end
572 Move point to end of current block (@code{ada-move-to-end}).
574 Switch between corresponding spec and body file
575 (@code{ff-find-other-file}). If the cursor is on a subprogram, switch
576 between declaration and body.
578 @findex ada-goto-declaration
579 Move from any reference to its declaration and switch between
580 declaration and body (for procedures, tasks, private and incomplete
583 @findex ada-find-references
584 runs the @file{gnatfind} command to search for all references to the
585 entity pointed by the cursor (@code{ada-find-references}). Use
586 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
590 These functions use the information in the output of the Gnat Ada
591 compiler. However, if your application was compiled with the
592 @samp{-gnatx} switch, these functions will not work, since no extra
593 information is generated by GNAT. See GNAT documentation for further
596 Emacs will try to run Gnat for you whenever the cross-reference
597 informations are older than your source file (provided the
598 @code{ada-xref-create-ali} variable is non-@code{nil}). Gnat then produces a
599 file with the same name as the current Ada file but with the extension
600 changed to @file{.ali}. This files are normally used by the binder, but
601 they will also contain additional cross-referencing information.
603 @c -----------------------------------------------------------------------
604 @node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top
605 @chapter Identifier completion
606 @c -----------------------------------------------------------------------
608 @c -----------------------------------------------------------------------
610 @c -----------------------------------------------------------------------
612 Emacs and Ada mode provide two general ways for the completion of
613 identifiers. This is an easy way to type faster: you just have to type
614 the first few letters of an identifiers, and then loop through all the
615 possible completions.
617 The first method is general for Emacs. It will work both with Ada
618 buffers, but also in C buffers, Java buffers, @enddots{} The idea is to parse
619 all the opened buffers for possible completions.
621 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
622 are the only words starting with @samp{my} in any of the opened files,
623 then you will have this scenario:
626 You type: my@key{M-/}
627 Emacs inserts: @samp{my_identifier}
628 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
629 @samp{my_subprogram}.
630 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
633 This is a very fast way to do completion, and the casing of words will
636 The second method is specific to Ada buffer, and even to users of the
637 Gnat compiler. Emacs will search the cross-information found in the
638 @samp{.ali} files generated by Gnat for possible completions.
640 The main advantage is that this completion is more accurate: only
641 existing identifier will be suggested, you don't need to have a file
642 opened that already contains this identifiers, @enddots{}
644 On the other hand, this completion is a little bit slower and requires
645 that you have compiled your file at least once since you created that
648 @c -----------------------------------------------------------------------
649 @section Summary of commands
650 @c -----------------------------------------------------------------------
654 @findex ada-complete-identifier
655 Complete accurately current identifier using information in @samp{.ali} file
656 (@code{ada-complete-identifier}).
658 Complete identifier using buffer information (not Ada-specific).
661 @c -----------------------------------------------------------------------
662 @node Index Menu of Subprograms, File Browser, Identifier completion, Top
663 @chapter Index Menu of Subprograms
664 @c -----------------------------------------------------------------------
666 You can display a choice menu with all procedure/function/task
667 declarations in the file and choose an item by mouse click to get to its
668 declaration. This function is accessible through the @samp{Ada} menu when
669 editing a Ada file, or simply through the following key binding:
676 @c -----------------------------------------------------------------------
677 @node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top
678 @chapter File Browser
679 @c -----------------------------------------------------------------------
681 Emacs provides a special mode, called @code{speedbar}. When this mode is
682 activated, a new frame is displayed, with a file browser. The files from
683 the current directory are displayed, and you can click on them as you
684 would with any file browser. The following commands are then available.
686 You can click on a directory name or file name to open it. The editor
687 will automatically select the best possible mode for this file,
688 including of course Ada mode for files written in Ada.
690 If you click on the @samp{[+]} symbol near a file name, all the symbols (types,
691 variables and subprograms) defined in that file will be displayed, and
692 you can directly click on them to open the right file at the right
695 You can activate this mode by typing @key{M-x speedbar} in the editor.
696 This will open a new frame. A better way might be to assicate the
697 following key binding
700 (global-set-key [f7] 'speedbar-get-focus)
703 Every time you press @key{F7}, the mouse will automatically move to the
704 speedbar frame (which will be created if it does not exist).
706 @c -----------------------------------------------------------------------
707 @node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top
708 @chapter Automatic Smart Indentation
709 @c -----------------------------------------------------------------------
711 Ada mode comes with a full set of rules for automatic indentation.
712 You can of course configure the indentation as you want, by setting the
713 value of a few variables.
715 As always, the preferred way to modify variables is to use the
716 @samp{Ada->Customize} menu (don't forget to save your changes!). This
717 will also show you some example of code where this variable is used, and
718 hopefully make things clearer.
720 The relevant variables are the following:
723 @item @code{ada-broken-indent} (default value: 2)
724 Number of columns to indent the continuation of a broken line.
726 @item @code{ada-indent} (default value: 3)
727 Width of the default indentation.
729 @item @code{ada-indent-record-rel-type} (default value: 3)
730 Indentation for @code{record} relative to @code{type} or @code{use}.
732 @item @code{ada-indent-return} (default value: 0)
733 Indentation for @code{return} relative to @code{function} (if
734 @code{ada-indent-return} is greater than 0), or the open parenthesis
735 (if @code{ada-indent-return} is negative or null). Note that in the second
736 case, when there is no open parenthesis, the indentation is done
737 relative to @code{function} with the value of @code{ada-broken-indent}.
739 @item @code{ada-label-indent} (default value: -4)
740 Number of columns to indent a label.
742 @item @code{ada-stmt-end-indent} (default value: 0)
743 Number of columns to indent a statement @code{end} keyword on a separate line.
745 @item @code{ada-when-indent} (default value: 3)
746 Indentation for @code{when} relative to @code{exception} or @code{case}.
748 @item @code{ada-indent-is-separate} (default value: t)
749 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
751 @item @code{ada-indent-to-open-paren} (default value: t)
752 Non-@code{nil} means indent according to the innermost open parenthesis.
754 @item @code{ada-indent-after-return} (default value: t)
755 Non-@code{nil} means that the current line will also be re-indented before
756 inserting a newline, when you press @key{RET}.
759 Most of the time, the indentation will be automatic, i.e when you will
760 press @key{RET}, the cursor will move to the correct column on the
763 However, you might want or need sometimes to re-indent the current line
764 or a set of lines. For this, you can simply go to that line, or select
765 the lines, and then press @key{TAB}. This will automatically re-indent
768 Another mode of indentation exists that helps you to set up your
769 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
774 Reindent the current line, as @key{TAB} would do.
776 Temporarily move the cursor to a reference line, i.e., the line that
777 was used to calculate the current indentation.
779 Display at the bottom of the window the name of the variable that
780 provided the offset for the indentation.
783 The exact indentation of the current line is the same as the one for the
784 reference line, plus an offset given by the variable.
786 Once you know the name of the variable, you can either modify it
787 through the usual @samp{Ada->Customize} menu, or by typing @kbd{M-x
788 customize-variable @key{RET}} in the Emacs window, and then give the
789 name of the variable.
793 Indent the current line or the current region.
795 Indent lines in the current selected block.
797 Indent the current line and prints the name of the variable used for
803 @c -----------------------------------------------------------------------
804 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
805 @chapter Formatting Parameter Lists
806 @c -----------------------------------------------------------------------
808 To help you correctly align fields in a subprogram parameter list,
809 Emacs provides one function that will do most of the work for you.
810 This function will align the declarations on the colon (@samp{:})
811 separating argument names and argument types, plus align the
812 @code{in}, @code{out} and @code{in out} keywords if required.
816 @findex ada-format-paramlist
817 Format the parameter list (@code{ada-format-paramlist}).
820 @c -----------------------------------------------------------------------
821 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
822 @chapter Automatic Casing
823 @c -----------------------------------------------------------------------
825 Casing of identifiers, attributes and keywords is automatically
826 performed while typing when the variable @code{ada-auto-case} is set.
827 Every time you press a word separator, the previous word is
830 You can customize the automatic casing differently for keywords,
831 attributes and identifiers. The relevant variables are the following:
832 @code{ada-case-keyword}, @code{ada-case-attribute} and
833 @code{ada-case-identifier}.
835 All these variables can have one of the following values:
839 The previous word will simply be in all lower cases. For instance
840 @code{My_vARIable} is converted to @code{my_variable}.
843 The previous word will be fully converted to upper cases. For instance
844 @code{My_vARIable} is converted to @code{MY_VARIABLE}.
846 @item ada-capitalize-word
847 All letters, except the first one of the word and every letter after the
848 @samp{_} character are lower cased. Other letters are upper cased. For
849 instance @code{My_vARIable} is converted to @code{My_Variable}.
851 @item ada-loose-case-word
852 No letters is modified in the previous word, except the ones after the
853 @samp{_} character that are upper cased. For instance @code{My_vARIable} is
854 converted to @code{My_VARIable}.
857 These functions, although they will work in most cases, will not be
858 accurate sometimes. The Ada mode allows you to define some exceptions,
859 that will always be cased the same way.
861 The idea is to create a dictionary of exceptions, and store it in a
862 file. This file should contain one identifier per line, with the casing
863 you want to force. The default name for this file is
864 @file{~/.emacs_case_exceptions}. You can of course change this name,
865 through the variable @code{ada-case-exception-file}.
867 Note that each line in this file must start with the key word whose
868 casing you want to specify. The rest of the line can be used for
869 comments (explaining for instance what an abbreviation means, as
870 recommended in the Ada 95 Quality and Style, paragraph 3.1.4). Thus, a
871 good example for this file could be:
874 DOD Department of Defense
876 GNAT The GNAT compiler from Ada Core Technologies
879 When working on project involving multiple programmers, we recommend
880 that every member of the team sets this variable to the same value,
881 which should point to a system-wide file that each of them can
882 write. That way, you will ensure that the casing is consistent
883 throughout your application(s).
885 @findex ada-create-case-exception
886 There are two ways to add new items to this file: you can simply edit it
887 as you would edit any text file, and add or suppress entries in this
888 file. Remember that you should put one entity per line. The other,
889 easier way, is to position the cursor over the word you want to add, in
890 an Ada buffer. This word should have the casing you want. Then simply
891 select the menu @samp{Ada->Edit->Create Case Exception}, or the key
892 @kbd{C-c C-y} (@code{ada-create-case-exception}). The word will
893 automatically be added to the current list of exceptions and to the file.
895 It is sometimes useful to have multiple exception files around (for
896 instance, one could be the standard Ada acronyms, the second some
897 company specific exceptions, and the last one some project specific
898 exceptions). If you set up the variable @code{ada-case-exception-file}
899 as a list of files, each of them will be parsed and used in your emacs
902 However, when you save a new exception through the menu, as described
903 above, the new exception will be added to the first file in the list
904 only. You can not automatically add an exception to one of the other
905 files, although you can of course edit the files by hand at any time.
907 Automatic casing can be performed on port or whole buffer using:
911 @findex ada-adjust-case-buffer
912 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
914 Create a new entry in the exception dictionary, with the word under
915 the cursor (@code{ada-create-case-exception})
917 @findex ada-case-read-exceptions
918 Rereads the exception dictionary from the file
919 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
922 @c -----------------------------------------------------------------------
923 @node Statement Templates, Comment Handling, Automatic Casing, Top
924 @chapter Statement Templates
925 @c -----------------------------------------------------------------------
927 NOTE: This features are not available on VMS for Emacs 19.28. The
928 functions used here do not exist on Emacs 19.28.
930 Templates exist for most Ada statements. They can be inserted in the
931 buffer using the following commands:
935 @findex ada-exception-block
936 exception Block (@code{ada-exception-block}).
939 case (@code{ada-case}).
941 @findex ada-declare-block
942 declare Block (@code{ada-declare-block}).
945 else (@code{ada-else}).
948 for Loop (@code{ada-for-loop}).
951 Header (@code{ada-header}).
956 @findex ada-package-body
957 package Body (@code{ada-package-body}).
960 loop (@code{ada-loop}).
962 @findex ada-subprogram-body
963 subprogram body (@code{ada-subprogram-body}).
965 @findex ada-task-body
966 task Body (@code{ada-task-body}).
969 while Loop (@code{ada-while}).
972 use (@code{ada-use}).
975 exit (@code{ada-exit}).
978 array (@code{ada-array}).
981 elsif (@code{ada-elsif}).
983 @findex ada-function-spec
984 function Spec (@code{ada-function-spec}).
986 @findex ada-package-spec
987 package Spec (@code{ada-package-spec}).
989 @findex ada-procedure-spec
990 procedure Spec (@code{ada-package-spec}.
993 record (@code{ada-record}).
996 subtype (@code{ada-subtype}).
998 @findex ada-task-spec
999 task Spec (@code{ada-task-spec}).
1002 with (@code{ada-with}).
1005 private (@code{ada-private}).
1008 when (@code{ada-when}).
1010 @findex ada-exception
1011 exception (@code{ada-exception}).
1014 type (@code{ada-type}).
1017 @c -----------------------------------------------------------------------
1018 @node Comment Handling, Compiling Executing, Statement Templates, Top
1019 @chapter Comment Handling
1020 @c -----------------------------------------------------------------------
1022 By default, comment lines get indented like Ada code. There are a few
1023 additional functions to handle comments:
1028 Start a comment in default column.
1030 Continue comment on next line.
1032 Comment the selected region (add -- at the beginning of lines).
1034 Uncomment the selected region
1036 autofill the current comment.
1039 @c -----------------------------------------------------------------------
1040 @node Compiling Executing, Debugging, Comment Handling, Top
1041 @chapter Compiling Executing
1042 @c -----------------------------------------------------------------------
1044 Ada mode provides a much complete environment for compiling, debugging
1045 and running an application within Emacs.
1047 All the commands used by Emacs to manipulate your application can be
1048 customized in the project file. Some default values are provided, but
1049 these will likely not be good enough for a big or even medium-sized
1050 project. See the section on the project file for an explanation on how
1051 to set up the commands to use.
1053 One of the variables you can set in your project file,
1054 @code{cross_prefix}, indicates whether you are using a cross-compilation
1055 environment, and if yes for which target. The default command used for
1056 compilation will add this @code{cross_prefix} in front of the name:
1057 @code{gcc} will become @code{cross_prefix}-@code{gcc}, @code{gnatmake}
1058 will become @code{cross_prefix}-@code{gnatmake}, @enddots{}
1060 This will also modify the way your application is run and debugged,
1061 although this is not implemented at the moment.
1063 Here are the commands for building and using an Ada application
1067 @item Compiling the current source
1068 This command is issued when issuing the @code{compile} command from the
1069 Ada menu. It compiles unconditionally the current source using the
1070 @code{comp_cmd} variable of the project file. Compilation options can be
1071 customized with the variable @code{comp_opt} of the project file.
1073 Emacs will display a new buffer that contains the result of the
1074 compilation. Each line associated with an error will become active: you
1075 can simply click on it with the middle button of the mouse, or move the
1076 cursor on it and press @key{RET}. Emacs will then display the
1077 relevant source file and put the cursor on the line and column the error
1080 You can also simply press the @kbd{C-x `} key and Emacs will jump to the
1081 first error. If you press that key again, it will move you to the second
1084 Some error messages might also include references to some files. These
1085 references are also clickable in the same way.
1088 @item (Re)building the whole application
1089 This command is issued when you select the @code{build} command from the
1090 Ada menu. It compiles all obsolete units of the current application
1091 using the @code{make_cmd} variable of the project file. Compilation
1092 options can be customized with the variable @code{comp_opt} of the
1093 project file, binder options with @code{bind_opt} and linker options
1094 with @code{link_opt}. The main unit of the application may be specified
1097 The compilation buffer is also active in the same way it was for the above
1100 @item Running the application
1101 This command is issued when you select the @code{run} command from the
1102 Ada menu. It executes the current application in an emacs
1103 buffer. Arguments can be passed through before executing. The execution
1104 buffer allows for interactive input/output.
1106 This command is not yet available in a cross-compilation
1107 toolchain. Emacs would first need to log on the target before running
1108 the application. This will be implemented in a future release of Gnat.
1112 @c ---------------------------------------------------------------------
1113 @node Debugging, Using non-standard file names, Compiling Executing, Top
1114 @chapter Debugging your application
1115 @c ---------------------------------------------------------------------
1117 You can set up in the project file a command to use to debug your
1118 application. Emacs is compatible with a lot of debuggers, and provide an
1119 easy interface to them.
1121 This selection will focus on the gdb debugger, and two of the graphical
1122 interfaces that exist for it.
1124 In all cases, the main window in Emacs will be split in two: in the
1125 upper buffer, the source code will appear, whereas the debugger
1126 input/output window is displayed at the bottom. You can enter the
1127 debugger commands as usual in the command window. Every time a new
1128 source file is selected by the debugger (for instance as a result of a
1129 @code{frame} command), the appropriate source file is displayed in the
1132 The source window is interactive: you can click on an identifier with the
1133 right mouse button, and print its value in the debugger window. You can
1134 also set a breakpoint simply by right-clicking on a line.
1136 You can easily use Emacs as the source window when you are using a
1137 graphical interface for the debugger. The interesting thing is that,
1138 whereas you still have the graphical nifties, you can also you the
1139 cross-references features that Ada mode provides to look at the
1140 definition for the identifiers, @enddots{}
1142 Here is how you can set up gdbtk and ddd for use with Emacs (These are
1143 the commands you should setup in the project file):
1147 should be used with the switch @samp{--emacs_gdbtk}. It provides a nice
1148 backtrace window, as well as a tasks window. You can click interactively
1149 on both of them, and Emacs will display the source file on the correct
1152 @item ddd (Data Display Debugger)
1153 should be used with the switches @samp{--tty} and
1154 @samp{--fullname}. Whenever you print a variable from Emacs, it will
1155 be displayed graphically in the data window.
1160 @c ---------------------------------------------------------------------
1161 @node Using non-standard file names, Working Remotely, Debugging, Top
1162 @chapter Using non-standard file names
1163 @c ---------------------------------------------------------------------
1165 By default, Emacs is configured to use the GNAT style file names, where
1166 file names are the package names, and the extension for spec and bodies
1167 are respectively @samp{.ads} and @samp{.adb}.
1169 If you want to use other types of file names, you will need to modify
1170 your @file{.emacs} file.
1172 Adding new possible extensions is easy. Since Ada mode needs to know
1173 how to go from the body to the spec (and back), you always have to
1174 specify both. A function is provided with Ada mode to add new
1177 For instance, if your spec and bodies files are called
1178 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
1179 need to add the following to your @file{.emacs} file:
1182 (ada-add-extensions "_s.ada" "_b.ada")
1185 Note that it is possible to redefine the extension, even if they already
1189 (ada-add-extensions ".ads" "_b.ada")
1190 (ada-add-extensions ".ads" ".body")
1193 This simply means that whenever the ada-mode will look for the body for
1194 a file whose extension is @file{.ads}, it will take the first available
1195 file that ends with either @file{.adb} (standard), @file{_b.ada} or
1198 If the filename is not the unit name, then things are a little more
1199 complicated. You then need to rewrite the function
1200 @code{ada-make-filename-from-adaname} (see the file @file{ada-mode.el}
1203 @c ---------------------------------------------------------------------
1204 @node Working Remotely, Index, Using non-standard file names, Top
1205 @chapter Working Remotely
1206 @c ---------------------------------------------------------------------
1208 When you work on project that involve a lot of programmers, it is
1209 generally the case that you will edit the files on your own machine, but
1210 you want to compile, run and debug your application in another buffer.
1212 Fortunately, here too Emacs provides a very convenient way to do this.
1214 @c ---------------------------------------------------------------------
1215 @section Remote editing
1216 @c ---------------------------------------------------------------------
1218 First of all, the files do not need to be on your machine. Emacs can
1219 edit any remote file, by doing transparent FTP sessions between your
1220 machine and the remote machine that stores your files. This is a special
1221 Emacs mode, called @code{ange-ftp}. To use it, you just have to use a
1222 slightly different syntax when you open a file.
1224 For instance, if you want to open the file @file{/work/foo.adb} on the machine
1225 aleph.gnu.org, where you log in as qwe, you would simply do this:
1228 C-x C-f /qwe@@aleph.gnu.org:/work/foo.adb @key{RET}
1232 i.e., use your name, the name of the machine and the name of the file.
1234 The first time, Emacs will ask you for a password that it will remember
1235 until you close the current Emacs. Even if the ftp session times out,
1236 you won't need to reenter your password.
1238 Every time you save the file, Emacs will upload it to the remote machine
1239 transparently. No file is modified on the local machine.
1241 @c ---------------------------------------------------------------------
1242 @section Remote compiling
1243 @c ---------------------------------------------------------------------
1245 If the machine you want to compile on is not the one your Emacs is
1246 running on, you can set the variable @code{remote_machine} in the
1247 project file for your application.
1249 This will force Emacs to issue a @command{rsh} command for the compilation,
1250 instead of running it on the local machine. Unfortunately, this won't
1251 work on Windows workstations, since this protocol is not supported.
1254 If your @code{remote_machine} is aleph.gnu.org and the standard
1255 compilation command is @code{cd /work/ && gnatmake foo}, then Emacs will
1256 actually issue the command @code{rsh aleph.gnu.org 'cd /work/ &&
1260 The advantage of using the @code{remote_machine} variable is that it is
1261 easier to change that machine without having to modify the compilation
1264 Note that if you need to set up some environment variables before the
1265 compilation, you need to insert a call to the appropriate initialization
1266 script in the compilation command, for instance:
1269 build_cmd= initialization_script; cd /work/ && gnatmake foo
1272 @c ---------------------------------------------------------------------
1273 @section Remote running and debugging
1274 @c ---------------------------------------------------------------------
1276 This feature is not completely implemented yet.
1278 However, most of the time, you will be able to run your application
1279 remotely simply by replacing it with a @command{rsh} call.
1280 For instance, if your command was @code{$@{main@}}, you could replace it with
1281 @code{rsh aleph.gnu.org $@{main@}}.
1283 However, this would not work on vxworks, for instance, where
1284 @command{rsh} is not supported.
1286 @node Index, , Working Remotely, Top