*** empty log message ***
[emacs.git] / man / ada-mode.texi
bloba74150fe75ae1aaf0c185952ed32a11c073ec4ef
1 \input texinfo  @c -*-texinfo-*-
2 @setfilename ../info/ada-mode
3 @settitle Ada Mode
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6 @comment The following lines inserts the copyright notice
7 @comment into the Info file.
8 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
10 @copying
11 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
13 @quotation
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with the
17 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
18 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
19 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
20 license is included in the section entitled ``GNU Free Documentation
21 License'' in the Emacs manual.
23 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
24 this GNU Manual, like GNU software.  Copies published by the Free
25 Software Foundation raise funds for GNU development.''
27 This document is part of a collection distributed under the GNU Free
28 Documentation License.  If you want to distribute this document
29 separately from the collection, you can do so by adding a copy of the
30 license to the document, as described in section 6 of the license.
31 @end quotation
32 @end copying
34 @dircategory Emacs
35 @direntry
36 * Ada mode: (ada-mode). Emacs mode for editing Ada code.
37 @end direntry
39 @titlepage
40 @sp 10
41 @title{Ada Mode}
42 @sp 2
43 @subtitle An Emacs major mode for programming Ada 95 with GNAT
44 @subtitle July 1998 for Ada Mode Version 3.0
45 @sp 2
46 @page
47 @vskip 0pt plus 1filll
48 @insertcopying
49 @end titlepage
52 @node Top, Overview, (dir), (dir)
54 @menu
55 * Overview::
56 * Installation::                  Installing Ada mode on your system
57 * Customization::                 Setting up Ada mode to your taste
58 * Project files::                 Describing the organization of your project
59 * Syntax highlighting::           Using specific colors and fonts to highlight
60                                     the structure of your files
61 * Moving Through Ada Code::       Moving easily through Ada sources
62 * Identifier completion::         Finishing words automatically
63 * Index Menu of Subprograms::     A menu of all the types and subprograms
64                                      defined in your application
65 * File Browser::                  Easy access to your files
66 * Automatic Smart Indentation::   Indenting your code automatically as you type
67 * Formatting Parameter Lists::    Formatting subprograms' parameter lists
68                                      automatically
69 * Automatic Casing::              Adjusting the case of words automatically
70 * Statement Templates::           Inserting code templates
71 * Comment Handling::              Reformatting comments easily
72 * Compiling Executing::           Working with your application within Emacs
73 * Debugging::                     Debugging your application
74 * Using non-standard file names:: Configuring Emacs for special file names
75 * Working Remotely::              Working on a different machine
76 * Index::
77 @end menu
80 @c -----------------------------------------------------------------------
81 @node Overview, Installation, Top, Top
82 @chapter Overview
83 @c -----------------------------------------------------------------------
85 The Emacs mode for programming in Ada 95 with GNAT helps the user in
86 understanding existing code and facilitates writing new code.  It
87 furthermore provides some utility functions for easier integration of
88 standard Emacs features when programming in Ada.
90 @section General features:
92 @itemize @bullet
93 @item
94 full Integrated Development Environment:
95 @itemize @bullet
96 @item
97 support of ``project files'' for the configuration (directories,
98 compilation options,...)
99 @item
100 compiling and stepping through error messages.
101 @item
102 running and debugging your applications within Emacs.
103 @end itemize
104 @item
105 easy to use for beginners by pull-down menus,
106 @item
107 user configurable by many user-option variables.
108 @end itemize
110 @section Ada mode features that help understanding code:
112 @itemize @bullet
113 @item
114 functions for easy and quick stepping through Ada code,
115 @item
116 getting cross reference information for identifiers (e.g. find the
117 defining place by a keystroke),
118 @item
119 displaying an index menu of types and subprograms and move point to
120 the chosen one,
121 @item
122 automatic color highlighting of the various entities in Ada code.
123 @end itemize
125 @section Emacs support for writing Ada code:
127 @itemize @bullet
128 @item
129 switching between spec and body files with eventually
130 auto-generation of body files,
131 @item
132 automatic formatting of subprograms' parameter lists.
133 @item
134 automatic smart indentation according to Ada syntax,
135 @item
136 automatic completion of identifiers,
137 @item
138 automatic casing of identifiers, keywords, and attributes,
139 @item
140 insertion of statement templates,
141 @item
142 filling comment paragraphs like filling normal text,
143 @end itemize
145 @c -----------------------------------------------------------------------
146 @node Installation, Customization, Overview, Top
147 @chapter Installation
148 @c -----------------------------------------------------------------------
150 If you  got Ada mode as  a separate distribution, you  should have a
151 look at the  @file{README} file.  It explains the  basic steps necessary
152 for a good installation of the emacs Ada mode.
154 Installing the  Ada mode  is basically  just a matter  of copying  a few
155 files into  the Emacs  library directories. Every  time you open  a file
156 with  a  file  extension  of  @file{.ads}  or  @file{.adb},  Emacs  will
157 automatically load and activate Ada mode.
159 @xref{Using non-standard file names}, if your files do
160 not use these extensions and if you want Emacs to automatically start the
161 Ada mode every time you edit an Ada file.
163 Also, for general usage variables that you might want to set,
165 @iftex
166 @cite{The GNU Emacs Manual}.
167 @end iftex
168 @ifhtml
169 @cite{The GNU Emacs Manual}.
170 @end ifhtml
171 @ifinfo
172 @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
173 @end ifinfo
175 @c ---------------------------------------------------------------------
176 @section Required files
177 @c ---------------------------------------------------------------------
179 This Ada  mode works best  with Emacs 20.3  or higher (the  easy editing
180 features for the  project files won't work with  any older version), but
181 most of the commands should work  with older versions too. Please try to
182 install  the  most  recent  version  of  Emacs  on  your  system  before
183 installing Ada mode.
185 Although part of Ada mode is compiler-independent, the most advanced
186 features are specific to the Gnat compiler @url{http://www.gnat.com}.
188 The following files are provided with the Ada mode distribution:
190 @itemize @bullet
192 @item
193 @file{ada-mode.el}: The main file for Ada mode.
194 This  is the  only file  which does  not require  Gnat. It  contains the
195 functions  for  indentation,  formatting  of parameter  lists,  stepping
196 through  code, comment  handling and  automatic casing.   Emacs versions
197 20.2 and higher already contain Ada mode version 2.27, which is an older
198 version of this file  and should be replaced. Loading @file{ada-mode.el}
199 from the current distribution supersedes the standard installation.
201 @item
202 @file{ada-stmt.el}: Contains the statement templates feature.
204 @item
205 @file{ada-xref.el}: This file provides the main support for Gnat.
206 This  is  where  the   functions  for  cross-references,  completion  of
207 identifiers,  support   for  project  files  and   compilation  of  your
208 application are defined.
210 @item
211 @file{ada-prj.el}: The functions to use for easy-edition of the
212 project files.  This file is the only one which really requires Emacs
213 at least 20.2. It uses the new widget features from Emacs.
215 @end itemize
217 @c --------------------------------------------------------------------
218 @node Customization, Project files, Installation, Top
219 @chapter Customizing Ada mode
220 @c ---------------------------------------------------------------------
222 Ada mode is  fully customizable. Everything, from the  file names to
223 the automatic  indentation and  the automatic casing  can be  adapted to
224 your own needs.
226 There  are   two  different  kinds   of  variables  that   control  this
227 customization, both are easy to modify.
229 The first set of variables are standard Emacs variables. Of course, some
230 are defined  only for Ada  mode, whereas others have  a more general
231 meaning  in   Emacs.  Please  see  the  Emacs   documentation  for  more
232 information on the latest. In this documentation, we will detail all the
233 variables that are specific to Ada mode, and a few others. The names
234 will be given, as in @code{ada-case-identifier}.
236 Emacs provides an easy way to modify them, through a special mode called
237 customization.    To    access    this    mode,    select    the    menu
238 @samp{Ada->Customize}.  This will open a new buffer with some fields that
239 you can edit.  For instance, you will get something like:
240 @example
241 Put below the compiler switches.
242 comp_opt= _____________________________________
243 @end example
244 The first  line gives a brief  description of the  variable.  The second
245 line is  the name of  the variable  and the field  where you can  give a
246 value for this variable. Simply type what you want in the field.
248 When you are  finished modifying the variables, you  can simply click on
249 the @b{Save for future sessions} button  at the top of the buffer (click
250 with  the  middle mouse  button).  This will  save  the  values in  your
251 @file{.emacs} file, so that next time you start Emacs they will have the
252 same values.
254 To modify a specific variable, you can directly call the function
255 @code{customize-variable} from Emacs (just type @kbd{M-x
256 customize-variable @key{RET} @var{variable-name} @key{RET}}).
258 Some users might prefer to modify the variables directly in their
259 configuration file, @file{.emacs}. This file is coded in Emacs lisp, and
260 the syntax to set a variable is the following:
261 @example
262 (setq variable-name value)
263 @end example
265 The second set of variables for customization are set through the use of
266 project files. These variables are  specific to a given project, whereas
267 the  first   set  was  more   general.  For  more   information,  please
268 @xref{Project files}.
270 @c ---------------------------------------------------------------------
271 @node Project files, Syntax highlighting, Customization, Top
272 @chapter Project files
273 @c ---------------------------------------------------------------------
275 @c ---------------------------------------------------------------------
276 @section General overview
277 @c ---------------------------------------------------------------------
279 Emacs provides a full Integrated Development Environment for GNAT and
280 Ada programmers. That is to say, editing, compiling, executing and
281 debugging can be performed within Emacs in a convenient and natural way.
283 To take full advantage of this features, it is possible to create a file
284 in  the main  directory of  your application,  with a  @samp{.adp} extension.
285 This  file contain  all needed  information  dealing with  the way  your
286 application is  organized between directories, the  commands to compile,
287 run and debug it etc. Creating this file is not mandatory and convenient
288 defaults are  automatically provided for simple setups.  It only becomes
289 necessary when those above mentioned defaults need customizing.
291 A simple way to edit this file is provided for Emacs 20.2 or newer, with
292 the  following functions,  that  you  can access  also  through the  Ada
293 menu. It  is also possible  to edit the  project file as a  regular text
294 file.
296 Once  in the  buffer for  editing the  project file,  you can  save your
297 modification using  the @samp{[OK]}  button at the  bottom of the  buffer, or
298 simply   use  the  usual   @kbd{C-x  C-s}   binding.   To   cancel  your
299 modifications, simply kill the buffer  or click on the @samp{[CANCEL]} button
300 at the button.
302 Each buffer using Ada mode will be associated with one project file when
303 there  is one  available,  so  that Emacs  can  easily navigate  through
304 related source files for instance.
306 The exact algorithm to determine which project file should be used is
307 described in the next section, but you can force the project file you
308 want to use by setting one or two variables in your @file{.emacs} file.
310 @itemize @bullet
311 @item
312 To set up a default project file to use for any directory, anywhere
313 on your system, set the variable @code{ada-prj-default-project-file} to
314 the name of that file.
316 @example
317 (set 'ada-prj-default-project-file "/dir1/dir2/file")
318 @end example
320 @item
321 For finer control, you can set a per-directory project file.
322 This is done through the variable @code{ada-xref-default-prj-file}.
324 @example
325   (set 'ada-xref-default-prj-file
326        '(("/dir1/dir2" . "/dir3/file1")
327          ("/dir4/dir5" . "/dir6/file2")))
328 @end example
330 Note: This has a higher priority than the first variable, so the first
331 choice is to use this variable settings, and otherwise
332 @code{ada-prj-default-project-file}.
333 @end itemize
336 @table @kbd
337 @item C-c u
338 @findex ada-customize
339 Create or edit the project file for the current buffer (@code{ada-customize}).
340 @item C-c c
341 @findex ada-change-prj
342 Change the project file associated with the current Ada buffer (@code{ada-change-prj}).
343 @item C-c d
344 @findex ada-change-default-project
345 Change the  default project  file for the  current directory
346 (@code{ada-change-default-project}).  Every new file opened  from this
347 directory will be  associated with that  file by default.
348 @item ada-set-default-project-file
349 @findex ada-set-default-project-file
350 Set the default  project file to use for *any*  Ada file opened anywhere
351 on your system. This sets this file only for the current Emacs session.
352 @end table
354 @c ---------------------------------------------------------------------
355 @section Project file variables
356 @c ---------------------------------------------------------------------
358 The following variables can be defined in a project file.  They all have
359 a default value, so that small  projects do not need to create a project
360 file.
362 Some  variables below  can be  referenced  in other  variables, using  a
363 shell-like  notation.   For instance,  if  the variable  @code{comp_cmd}
364 contains a sequence like @code{$@{comp_opt@}}, the value of that variable
365 will be substituted.
367 Here is the list of variables:
369 @table @asis
370 @item @code{src_dir}          [default: @code{"./"}]
371 This is  a list of directories where Ada mode will  look for source
372 files. These directories are used mainly  in two cases, both as a switch
373 for the compiler and for the cross-references.
375 @item @code{obj_dir}             [default: @code{"./"}]
376 This is a list of directories where to look for object and library
377 files.  The library files are the @samp{.ali} files generated by Gnat
378 and that contain cross-reference informations.
380 @item @code{comp_opt}            [default: @code{""}]
381 Creates a  variable which can be  referred to subsequently  by using the
382 @code{$@{comp_opt@}} notation.   This is  intended to store  the default
383 switches given to @command{gnatmake} and @command{gcc}.
385 @item @code{bind_opt=@var{switches}}   [default: @code{""}]
386 Creates a  variable which can be  referred to subsequently  by using the
387 @code{$@{bind_opt@}} notation.   This is  intended to store  the default
388 switches given to @command{gnatbind}.
390 @item @code{link_opt=@var{switches}}   [default: @code{""}]
391 Creates a  variable which can be  referred to subsequently  by using the
392 @code{$@{link_opt@}} notation.   This is  intended to store  the default
393 switches given to @command{gnatlink}.
395 @item @code{main=@var{executable}}     [default: @code{""}]
396 Specifies the name of the  executable for the application. This variable
397 can be referred to in  the following lines by using the @code{$@{main@}}
398 notation.
400 @item @code{cross_prefix=@var{prefix}} [default: @code{""}]
401 This variable  should be set if  you are working  in a cross-compilation
402 environment. This is the prefix used in front of the gnatmake commands.
404 @item @code{remote_machine=@var{machine}} [default: @code{""}]
405 This is the name of the machine to log into before issuing the
406 compilation command. If this variable is empty, the command will be
407 run on the local machine. This will not work on Windows NT machines,
408 since Ada mode will simply precede the compilation command with a
409 @command{rsh} command, unknown on Windows.
411 @item @code{comp_cmd=@var{command}}    [default: @code{"$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"}]
412 Specifies the command used to compile a single file in the application.
413 The name of the file will be added at the end of this command.
415 @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@}"]}'
416 Specifies the command used to recompile the whole application.
418 @item @code{run_cmd=@var{command}}     [default: @code{"$@{main@}"}]
419 Specifies the command used to run the application.
421 @item @code{debug_cmd=@var{command}}   [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
422 Specifies the command used to debug the application
424 @end table
426 @c ---------------------------------------------------------------------
427 @section Detailed algorithm
428 @c ---------------------------------------------------------------------
430 This section gives more details on the project file setup and is only of
431 interest for advanced users.
433 Usually, an Ada file is part  of a larger application, whose sources and
434 objects can be spread over multiple directories. The first time emacs is
435 asked to compile, run or debug an application, or when a cross reference
436 function is  used (goto declaration  for instance), the  following steps
437 are taken:
439 @itemize @bullet
440 @item
441 find the appropriate project file, open and parse it.
442 All  the fields  read  in the  project  file are  then  stored by  emacs
443 locally.  Finding the project file requires a few steps:
445 @itemize @minus
446 @item
447 if a file from the same directory was already associated with
448 a project file, use the same one. This is the variable
449 @code{ada-xref-default-prj-file} described above.
450 @item
451 if the variable @code{ada-prj-default-project-file} is set,
452 use the project file specified in this variable.
453 @item
454 if there is a project file whose name is the same as the source file
455 except for the suffix, use this one.
456 @item
457 if  there's only one project file in the source directory, use
458 that one.
459 @item
460 if there are more than one project file in the source directory,
461 ask the user.
462 @item
463 if there are no project files in the source directory use standard
464 default values.
465 @end itemize
467 The first project file that is selected in a given directory becomes the
468 default project file for this directory and is used implicitly for other
469 sources unless specified otherwise by the user.
471 @item
472 look for the corresponding @samp{.ali} file in the @code{obj_dir} defined
473 in the project  file.  If this file can not be  found, emacs proposes to
474 compile the source using the @code{comp_cmd} defined in the project file
475 in order to create the ali file.
477 @item
478 when cross referencing is requested, the @samp{.ali}  file is parsed to
479 determine  the  file and  line  of  the  identifier definition.   It  is
480 possible for  the @samp{.ali} file to be  older than the source  file,
481 in which case it will be recompiled if the variable
482 @code{ada-xref-create-ali} is set, otherwise the  reference is searched
483 in the  obsolete ali file with possible inaccurate results.
485 @item
486 look  for   the file containing the declaration using the source
487 path @code{src_dir} defined in the  project file.  Put the cursor at the
488 correct position and display this new cursor.
489 @end itemize
491 @c -----------------------------------------------------------------------
492 @node Syntax highlighting, Moving Through Ada Code, Project files, Top
493 @chapter Syntax highlighting
494 @c -----------------------------------------------------------------------
496 Ada mode is made to help you understand the structure of your source
497 files. Some  people like having  colors or different fonts  depending on
498 the  context: commands  should be  displayed differently  than keywords,
499 which should also be different from strings, @dots{}
501 Emacs is able to display in a different way the following syntactic
502 entities:
504 @itemize @bullet
505 @item keywords
506 @item commands
507 @item strings
508 @item gnatprep statements (preprocessor)
509 @item types (under certain conditions)
510 @item other words
511 @end itemize
513 This  is not  the default  behavior for  Emacs. You  have  to explicitly
514 activate it. This requires that you add a new line in your @file{.emacs}
515 file (if this file does not exist, just create it).
517 @example
518 (global-font-lock-mode t)
519 @end example
521 But  the default colors  might not  be the  ones you  like. Fortunately,
522 there  is  a  very  easy  way  to change  them.  Just  select  the  menu
523 @samp{Help->Customize->Specific  Face...}  and  press @key{RET}.  This
524 will display a buffer will all the ``faces'' (the colors) that Emacs knows
525 about. You can change any of them.
528 @c -----------------------------------------------------------------------
529 @node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top
530 @chapter Moving Through Ada Code
531 @c -----------------------------------------------------------------------
533 There are several  easy to use commands to stroll  through Ada code. All
534 these functions are available through the Ada menu, and you can also use
535 the following key bindings or the command names:
537 @table @kbd
538 @item C-M-e
539 @findex ada-next-procedure
540 Move to the next function/procedure/task, which ever comes next
541 (@code{ada-next-procedure}).
542 @item C-M-a
543 @findex ada-previous-procedure
544 Move to previous function/procedure/task
545 (@code{ada-previous-procedure}).
546 @item M-x ada-next-package
547 @findex ada-next-package
548 Move to next package.
549 @item M-x ada-prev-package
550 @findex ada-prev-package
551 Move to previous package.
552 @item C-c C-a
553 @findex ada-move-to-start
554 Move to matching start of @code{end} (@code{ada-move-to-start}).  If
555 point is at the end of a subprogram, this command jumps to the
556 corresponding @code{begin} if the user option
557 @code{ada-move-to-declaration} is @code{nil} (default), it jumps to
558 the subprogram declaration otherwise.
559 @item C-c C-e
560 @findex ada-move-to-end
561 Move point to end of current block (@code{ada-move-to-end}).
562 @item C-c o
563 Switch between corresponding spec and body file
564 (@code{ff-find-other-file}).  If the cursor is on a subprogram, switch
565 between declaration and body.
566 @item C-c c-d
567 @findex ada-goto-declaration
568 Move  from   any  reference  to  its  declaration   and  switch  between
569 declaration  and body  (for  procedures, tasks,  private and  incomplete
570 types).
571 @item C-c C-r
572 @findex ada-find-references
573 runs the @file{gnatfind} command to search for all references to the
574 entity pointed by the cursor (@code{ada-find-references}).  Use
575 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
576 compilation errors).
577 @end table
579 These  functions use  the  information in  the  output of  the Gnat  Ada
580 compiler.   However,   if  your   application  was  compiled   with  the
581 @samp{-gnatx}  switch, these  functions will  not work,  since  no extra
582 information  is generated by  GNAT. See  GNAT documentation  for further
583 information.
585 Emacs will  try to  run    Gnat for  you whenever the    cross-reference
586 informations  are     older   than your   source   file   (provided  the
587 @code{ada-xref-create-ali} variable is  non-@code{nil}).  Gnat  then produces a
588 file with the same name  as the current  Ada file but with the extension
589 changed to @file{.ali}. This files are normally used  by the binder, but
590 they will also contain additional cross-referencing information.
592 @c -----------------------------------------------------------------------
593 @node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top
594 @chapter Identifier completion
595 @c -----------------------------------------------------------------------
597 @c -----------------------------------------------------------------------
598 @section Overview
599 @c -----------------------------------------------------------------------
601 Emacs and  Ada mode provide  two general ways for  the completion of
602 identifiers. This is  an easy way to type faster: you  just have to type
603 the first few  letters of an identifiers, and then  loop through all the
604 possible completions.
606 The  first method  is general  for  Emacs. It  will work  both with  Ada
607 buffers, but also in C buffers,  Java buffers, @enddots{}  The idea is to parse
608 all the opened buffers for possible completions.
610 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
611 are the only words starting with @samp{my} in any of the opened files,
612 then you will have this scenario:
614 @quotation
615 You type:  my@key{M-/}
616 Emacs inserts:  @samp{my_identifier}
617 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
618 @samp{my_subprogram}.
619 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
620 @end quotation
622 This is a very  fast way to do completion, and the  casing of words will
623 also be respected.
625 The second  method is specific to Ada  buffer, and even to  users of the
626 Gnat compiler. Emacs will search the cross-information found in the
627 @samp{.ali} files generated by Gnat for possible completions.
629 The  main advantage  is  that  this completion  is  more accurate:  only
630 existing identifier  will be  suggested, you don't  need to have  a file
631 opened that already contains this identifiers, @enddots{}
633 On the other  hand, this completion is a little  bit slower and requires
634 that you  have compiled your file  at least once since  you created that
635 identifier.
637 @c -----------------------------------------------------------------------
638 @section Summary of commands
639 @c -----------------------------------------------------------------------
641 @table @kbd
642 @item C-@key{TAB}
643 @findex ada-complete-identifier
644 Complete accurately current identifier using information in @samp{.ali} file
645 (@code{ada-complete-identifier}).
646 @item M-/
647 Complete identifier using buffer information (not Ada-specific).
648 @end table
650 @c -----------------------------------------------------------------------
651 @node Index Menu of Subprograms, File Browser, Identifier completion, Top
652 @chapter Index Menu of Subprograms
653 @c -----------------------------------------------------------------------
655 You  can   display  a  choice  menu   with  all  procedure/function/task
656 declarations in the file and choose an item by mouse click to get to its
657 declaration.  This function is  accessible through  the @samp{Ada} menu when
658 editing a Ada file, or simply through the following key binding:
660 @table @kbd
661 @item C-S-Mouse-3
662 display index menu
663 @end table
665 @c -----------------------------------------------------------------------
666 @node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top
667 @chapter File Browser
668 @c -----------------------------------------------------------------------
670 Emacs provides a special mode, called @code{speedbar}. When this mode is
671 activated, a new frame is displayed, with a file browser. The files from
672 the current  directory are displayed, and  you can click on  them as you
673 would with any file browser. The following commands are then available.
675 You can click  on a directory name  or file name to open  it. The editor
676 will  automatically  select  the  best  possible  mode  for  this  file,
677 including of course Ada mode for files written in Ada.
679 If you click on the @samp{[+]} symbol near a file name, all the symbols (types,
680 variables and subprograms)  defined in that file will  be displayed, and
681 you  can directly click  on them  to open  the right  file at  the right
682 place.
684 You can activate  this mode by typing @key{M-x  speedbar} in the editor.
685 This  will open  a new  frame. A  better way  might be  to  associate the
686 following key binding
688 @example
689 (global-set-key [f7]  'speedbar-get-focus)
690 @end example
692 Every time you press @key{F7},  the mouse will automatically move to the
693 speedbar frame (which will be created if it does not exist).
695 @c -----------------------------------------------------------------------
696 @node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top
697 @chapter Automatic Smart Indentation
698 @c -----------------------------------------------------------------------
700 Ada mode  comes with a full set of  rules for automatic indentation.
701 You can of course configure the  indentation as you want, by setting the
702 value of a few variables.
704 As  always,  the  preferred  way  to  modify variables  is  to  use  the
705 @samp{Ada->Customize} menu  (don't forget  to save your  changes!). This
706 will also show you some example of code where this variable is used, and
707 hopefully make things clearer.
709 The relevant variables are the following:
711 @table @asis
712 @item @code{ada-broken-indent}           (default value: 2)
713 Number of columns to indent the continuation of a broken line.
715 @item @code{ada-indent}                  (default value: 3)
716 Width of the default indentation.
718 @item @code{ada-indent-record-rel-type}  (default value: 3)
719 Indentation for @code{record} relative to @code{type} or @code{use}.
721 @item @code{ada-indent-return}           (default value: 0)
722 Indentation for @code{return} relative to @code{function} (if
723 @code{ada-indent-return} is greater than 0), or the open parenthesis
724 (if @code{ada-indent-return} is negative or null).  Note that in the second
725 case, when there is no open parenthesis, the indentation is done
726 relative to @code{function} with the value of @code{ada-broken-indent}.
728 @item @code{ada-label-indent}            (default value: -4)
729 Number of columns to indent a label.
731 @item @code{ada-stmt-end-indent}         (default value: 0)
732 Number of columns to indent a statement @code{end} keyword on a separate line.
734 @item @code{ada-when-indent}             (default value: 3)
735 Indentation for @code{when} relative to @code{exception} or @code{case}.
737 @item @code{ada-indent-is-separate}      (default value: t)
738 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
740 @item @code{ada-indent-to-open-paren}    (default value: t)
741 Non-@code{nil} means indent according to the innermost open parenthesis.
743 @item @code{ada-indent-after-return}     (default  value: t)
744 Non-@code{nil}  means that  the current  line will  also be  re-indented before
745 inserting a newline, when you press @key{RET}.
746 @end table
748 Most of the  time, the indentation will be automatic,  i.e when you will
749 press @key{RET},  the cursor will move  to the correct  column on the
750 next line.
752 However, you might want or  need sometimes to re-indent the current line
753 or a set of  lines. For this, you can simply go  to that line, or select
754 the lines,  and then press @key{TAB}. This  will automatically re-indent
755 the lines.
757 Another mode of indentation exists that helps you to set up your
758 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
759 the following:
761 @itemize @bullet
762 @item
763 Reindent the current line, as @key{TAB} would do.
764 @item
765 Temporarily move the cursor to a reference line, i.e., the line that
766 was used to calculate the current indentation.
767 @item
768 Display at the bottom of the window the name of the variable that
769 provided the offset for the indentation.
770 @end itemize
772 The exact indentation of the current line is the same as the one for the
773 reference line, plus an offset given by the variable.
775 Once you know the name of the variable, you can either modify it
776 through the usual @samp{Ada->Customize} menu, or by typing @kbd{M-x
777 customize-variable @key{RET}} in the Emacs window, and then give the
778 name of the variable.
780 @table @kbd
781 @item @key{TAB}
782 Indent the current line or the current region.
783 @item C-M-\
784 Indent lines in the current selected block.
785 @item C-c @key{TAB}
786 Indent the current line and prints the name of the variable used for
787 indentation.
788 @end table
792 @c -----------------------------------------------------------------------
793 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
794 @chapter Formatting Parameter Lists
795 @c -----------------------------------------------------------------------
797 To help you correctly align fields in a subprogram parameter list,
798 Emacs provides one function that will do most of the work for you.
799 This function will align the declarations on the colon (@samp{:})
800 separating argument names and argument types, plus align the
801 @code{in}, @code{out} and @code{in out} keywords if required.
803 @table @kbd
804 @item C-c C-f
805 @findex ada-format-paramlist
806 Format the parameter list (@code{ada-format-paramlist}).
807 @end table
809 @c -----------------------------------------------------------------------
810 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
811 @chapter Automatic Casing
812 @c -----------------------------------------------------------------------
814 Casing  of   identifiers,  attributes  and   keywords  is  automatically
815 performed while  typing when  the variable @code{ada-auto-case}  is set.
816 Every  time   you  press  a   word  separator,  the  previous   word  is
817 automatically cased.
819 You  can  customize  the  automatic  casing  differently  for  keywords,
820 attributes and  identifiers. The  relevant variables are  the following:
821 @code{ada-case-keyword},          @code{ada-case-attribute}          and
822 @code{ada-case-identifier}.
824 All these variables can have one of the following values:
826 @table @code
827 @item downcase-word
828 The  previous word  will simply  be in  all lower  cases.   For instance
829 @code{My_vARIable} is converted to @code{my_variable}.
831 @item upcase-word
832 The previous word will be  fully converted to upper cases.  For instance
833 @code{My_vARIable} is converted to @code{MY_VARIABLE}.
835 @item ada-capitalize-word
836 All letters, except the first one of the word and every letter after the
837 @samp{_}  character are  lower cased.  Other  letters are  upper cased.   For
838 instance @code{My_vARIable} is converted to @code{My_Variable}.
840 @item ada-loose-case-word
841 No letters is  modified in the previous word, except  the ones after the
842 @samp{_} character that are  upper cased.  For instance @code{My_vARIable} is
843 converted to @code{My_VARIable}.
844 @end table
846 These  functions, although they  will work  in most  cases, will  not be
847 accurate sometimes. The  Ada mode allows you to  define some exceptions,
848 that will always be cased the same way.
850 The idea  is to  create a dictionary  of exceptions,  and store it  in a
851 file. This file should contain  one identifier per line, with the casing
852 you   want   to   force.   The   default   name   for   this   file   is
853 @file{~/.emacs_case_exceptions}.  You can  of course  change  this name,
854 through the variable @code{ada-case-exception-file}.
856 Note that  each line  in this file  must start  with the key  word whose
857 casing  you want  to  specify. The  rest of  the  line can  be used  for
858 comments  (explaining  for  instance  what  an  abbreviation  means,  as
859 recommended in the Ada 95  Quality and Style, paragraph 3.1.4).  Thus, a
860 good example for this file could be:
862 @example
863 DOD        Department of Defense
864 Text_IO
865 GNAT       The GNAT compiler from Ada Core Technologies
866 @end example
868 When  working on  project involving  multiple programmers,  we recommend
869 that every  member of  the team  sets this variable  to the  same value,
870 which  should  point  to  a  system-wide  file that  each  of  them  can
871 write.  That  way,  you  will  ensure  that  the  casing  is  consistent
872 throughout your application(s).
874 @findex ada-create-case-exception
875 There are two ways to add new items to this file: you can simply edit it
876 as you  would edit any  text file, and  add or suppress entries  in this
877 file.  Remember that  you should  put one  entity per  line.  The other,
878 easier way, is to position the cursor  over the word you want to add, in
879 an Ada buffer.  This word should have the casing  you want.  Then simply
880 select  the  menu @samp{Ada->Edit->Create  Case  Exception},  or the  key
881 @kbd{C-c C-y} (@code{ada-create-case-exception}). The word will
882 automatically be added to the current list of exceptions and to the file.
884 It  is sometimes  useful to  have multiple  exception files  around (for
885 instance,  one could  be  the  standard Ada  acronyms,  the second  some
886 company  specific exceptions,  and the  last one  some  project specific
887 exceptions).  If you  set up the variable @code{ada-case-exception-file}
888 as a list of  files, each of them will be parsed  and used in your emacs
889 session.
891 However, when  you save a new  exception through the  menu, as described
892 above, the  new exception will  be added to  the first file in  the list
893 only.  You  can not automatically add  an exception to one  of the other
894 files, although you can of course edit the files by hand at any time.
896 Automatic casing can be performed on port or whole buffer using:
898 @table @kbd
899 @item C-c C-b
900 @findex ada-adjust-case-buffer
901 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
902 @item C-c C-y
903 Create a new entry in the exception dictionary, with the word under
904 the cursor (@code{ada-create-case-exception})
905 @item C-c C-t
906 @findex ada-case-read-exceptions
907 Rereads the exception dictionary from the file
908 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
909 @end table
911 @c -----------------------------------------------------------------------
912 @node Statement Templates, Comment Handling, Automatic Casing, Top
913 @chapter Statement Templates
914 @c -----------------------------------------------------------------------
916 NOTE:  This features  are  not available  on  VMS for  Emacs 19.28.  The
917 functions used here do not exist on Emacs 19.28.
919 Templates exist  for most  Ada statements. They  can be inserted  in the
920 buffer using the following commands:
922 @table @kbd
923 @item C-c t b
924 @findex ada-exception-block
925 exception Block (@code{ada-exception-block}).
926 @item C-c t c
927 @findex ada-case
928 case (@code{ada-case}).
929 @item C-c t d
930 @findex ada-declare-block
931 declare Block (@code{ada-declare-block}).
932 @item C-c t e
933 @findex ada-else
934 else (@code{ada-else}).
935 @item C-c t f
936 @findex ada-for-loop
937 for Loop (@code{ada-for-loop}).
938 @item C-c t h
939 @findex ada-header
940 Header (@code{ada-header}).
941 @item C-c t i
942 @findex ada-if
943 if (@code{ada-if}).
944 @item C-c t k
945 @findex ada-package-body
946 package Body (@code{ada-package-body}).
947 @item C-c t l
948 @findex ada-loop
949 loop (@code{ada-loop}).
950 @item C-c p
951 @findex ada-subprogram-body
952 subprogram body (@code{ada-subprogram-body}).
953 @item C-c t t
954 @findex ada-task-body
955 task Body (@code{ada-task-body}).
956 @item C-c t w
957 @findex ada-while
958 while Loop (@code{ada-while}).
959 @item C-c t u
960 @findex ada-use
961 use (@code{ada-use}).
962 @item C-c t x
963 @findex ada-exit
964 exit (@code{ada-exit}).
965 @item C-c t C-a
966 @findex ada-array
967 array (@code{ada-array}).
968 @item C-c t C-e
969 @findex ada-elsif
970 elsif (@code{ada-elsif}).
971 @item C-c t C-f
972 @findex ada-function-spec
973 function Spec (@code{ada-function-spec}).
974 @item C-c t C-k
975 @findex ada-package-spec
976 package Spec (@code{ada-package-spec}).
977 @item C-c t C-p
978 @findex ada-procedure-spec
979 procedure Spec (@code{ada-package-spec}.
980 @item C-c t C-r
981 @findex ada-record
982 record (@code{ada-record}).
983 @item C-c t C-s
984 @findex ada-subtype
985 subtype (@code{ada-subtype}).
986 @item C-c t C-t
987 @findex ada-task-spec
988 task Spec (@code{ada-task-spec}).
989 @item C-c t C-u
990 @findex ada-with
991 with (@code{ada-with}).
992 @item C-c t C-v
993 @findex ada-private
994 private (@code{ada-private}).
995 @item C-c t C-w
996 @findex ada-when
997 when (@code{ada-when}).
998 @item C-c t C-x
999 @findex ada-exception
1000 exception (@code{ada-exception}).
1001 @item C-c t C-y
1002 @findex ada-type
1003 type (@code{ada-type}).
1004 @end table
1006 @c -----------------------------------------------------------------------
1007 @node Comment Handling, Compiling Executing, Statement Templates, Top
1008 @chapter Comment Handling
1009 @c -----------------------------------------------------------------------
1011 By default, comment lines get indented like Ada code. There are a few
1012 additional functions to handle comments:
1015 @table @kbd
1016 @item M-;
1017 Start a comment in default column.
1018 @item M-j
1019 Continue comment on next line.
1020 @item C-c ;
1021 Comment the selected region (add -- at the beginning of lines).
1022 @item C-c :
1023 Uncomment the selected region
1024 @item M-q
1025 autofill the current comment.
1026 @end table
1028 @c -----------------------------------------------------------------------
1029 @node Compiling Executing, Debugging, Comment Handling, Top
1030 @chapter Compiling Executing
1031 @c -----------------------------------------------------------------------
1033 Ada mode  provides a much complete environment  for compiling, debugging
1034 and running an application within Emacs.
1036 All the  commands used  by Emacs to  manipulate your application  can be
1037 customized in  the project file.  Some default values are  provided, but
1038 these will  likely not  be good  enough for a  big or  even medium-sized
1039 project.  See the section on the  project file for an explanation on how
1040 to set up the commands to use.
1042 One   of   the  variables   you   can   set   in  your   project   file,
1043 @code{cross_prefix}, indicates whether you are using a cross-compilation
1044 environment, and if  yes for which target. The  default command used for
1045 compilation  will add  this @code{cross_prefix}  in front  of  the name:
1046 @code{gcc}  will become  @code{cross_prefix}-@code{gcc}, @code{gnatmake}
1047 will become @code{cross_prefix}-@code{gnatmake}, @enddots{}
1049 This  will also modify  the way  your application  is run  and debugged,
1050 although this is not implemented at the moment.
1052 Here are the commands for building and using an Ada application
1054 @itemize @bullet
1056 @item Compiling the current source
1057 This command is issued when  issuing the @code{compile} command from the
1058 Ada  menu. It  compiles  unconditionally the  current  source using  the
1059 @code{comp_cmd} variable of the project file. Compilation options can be
1060 customized with the variable @code{comp_opt} of the project file.
1062 Emacs  will  display  a new  buffer  that  contains  the result  of  the
1063 compilation.  Each line associated with an error will become active: you
1064 can simply click on it with the  middle button of the mouse, or move the
1065 cursor  on  it and  press  @key{RET}.  Emacs  will then  display  the
1066 relevant source file and put the cursor on the line and column the error
1067 was found at.
1069 You can also simply press the @kbd{C-x `} key and Emacs will jump to the
1070 first error. If you press that key again, it will move you to the second
1071 error, and so on.
1073 Some error messages might also include references to some files. These
1074 references are also clickable in the same way.
1077 @item (Re)building the whole application
1078 This command is issued when you select the @code{build} command from the
1079 Ada menu.   It compiles  all obsolete units  of the  current application
1080 using  the @code{make_cmd}  variable  of the  project file.  Compilation
1081 options  can be  customized  with the  variable  @code{comp_opt} of  the
1082 project  file, binder  options with  @code{bind_opt} and  linker options
1083 with @code{link_opt}. The main unit  of the application may be specified
1084 with @code{main}.
1086 The compilation buffer is also active in the same way it was for the above
1087 command.
1089 @item Running the application
1090 This command is  issued when you select the  @code{run} command from the
1091 Ada   menu.   It   executes  the   current  application   in   an  emacs
1092 buffer. Arguments can be  passed through before executing. The execution
1093 buffer allows for interactive input/output.
1095 This   command   is   not   yet   available   in   a   cross-compilation
1096 toolchain. Emacs  would first need to  log on the  target before running
1097 the application. This will be implemented in a future release of Gnat.
1099 @end itemize
1101 @c ---------------------------------------------------------------------
1102 @node Debugging, Using non-standard file names, Compiling Executing, Top
1103 @chapter Debugging your application
1104 @c ---------------------------------------------------------------------
1106 You  can set  up in  the project  file a  command to  use to  debug your
1107 application. Emacs is compatible with a lot of debuggers, and provide an
1108 easy interface to them.
1110 This selection will focus on the  gdb debugger, and two of the graphical
1111 interfaces that exist for it.
1113 In all  cases, the main  window in  Emacs will be  split in two:  in the
1114 upper  buffer,  the  source  code  will  appear,  whereas  the  debugger
1115 input/output  window is  displayed at  the  bottom.  You  can enter  the
1116 debugger  commands as  usual in  the command  window. Every  time  a new
1117 source file is  selected by the debugger (for instance as  a result of a
1118 @code{frame} command),  the appropriate source file is  displayed in the
1119 upper buffer.
1121 The source window is interactive: you can click on an identifier with the
1122 right mouse button, and print its value in the debugger window. You can
1123 also set a breakpoint simply by right-clicking on a line.
1125 You  can easily use  Emacs as  the source  window when  you are  using a
1126 graphical  interface for the  debugger. The  interesting thing  is that,
1127 whereas  you still  have the  graphical nifties,  you can  also  you the
1128 cross-references  features that  Ada mode  provides to  look  at the
1129 definition for the identifiers, @enddots{}
1131 Here is how you  can set up gdbtk and ddd for  use with Emacs (These are
1132 the commands you should setup in the project file):
1134 @itemize @bullet
1135 @item gdbtk
1136 should  be used  with  the  switch @samp{--emacs_gdbtk}.   It  provides a  nice
1137 backtrace window, as well as a tasks window. You can click interactively
1138 on both of  them, and Emacs will display the source  file on the correct
1139 line.
1141 @item ddd (Data Display Debugger)
1142 should be used with the switches @samp{--tty} and
1143 @samp{--fullname}. Whenever you print a variable from Emacs, it will
1144 be displayed graphically in the data window.
1146 @end itemize
1149 @c ---------------------------------------------------------------------
1150 @node Using non-standard file names, Working Remotely, Debugging, Top
1151 @chapter Using non-standard file names
1152 @c ---------------------------------------------------------------------
1154 By default, Emacs is configured to  use the GNAT style file names, where
1155 file names are the package names,  and the extension for spec and bodies
1156 are respectively @samp{.ads} and @samp{.adb}.
1158 If you  want to  use other  types of file  names, you will need to modify
1159 your @file{.emacs} file.
1161 Adding new possible extensions is easy. Since Ada mode needs to know
1162 how to  go from  the body  to the spec  (and back),  you always  have to
1163 specify  both. A  function  is provided  with  Ada mode  to add  new
1164 extensions.
1166 For instance, if your spec and bodies files are called
1167 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
1168 need to add the following to your @file{.emacs} file:
1170 @example
1171 (ada-add-extensions "_s.ada" "_b.ada")
1172 @end example
1174 Note that it is possible to redefine the extension, even if they already
1175 exist, as in:
1177 @example
1178 (ada-add-extensions ".ads" "_b.ada")
1179 (ada-add-extensions ".ads" ".body")
1180 @end example
1182 This simply means that whenever the  ada-mode will look for the body for
1183 a file whose extension is  @file{.ads}, it will take the first available
1184 file  that ends  with  either @file{.adb}  (standard), @file{_b.ada}  or
1185 @file{.body}.
1187 If the filename is not the unit name, then things are a little more
1188 complicated.  You then need to rewrite the function
1189 @code{ada-make-filename-from-adaname} (see the file @file{ada-mode.el}
1190 for an example).
1192 @c ---------------------------------------------------------------------
1193 @node Working Remotely, Index, Using non-standard file names, Top
1194 @chapter Working Remotely
1195 @c ---------------------------------------------------------------------
1197 When  you work  on project  that  involve a  lot of  programmers, it  is
1198 generally the case that you will edit the files on your own machine, but
1199 you want to compile, run and debug your application in another buffer.
1201 Fortunately, here too Emacs provides a very convenient way to do this.
1203 @c ---------------------------------------------------------------------
1204 @section Remote editing
1205 @c ---------------------------------------------------------------------
1207 First of  all, the files do  not need to  be on your machine.  Emacs can
1208 edit any  remote file,  by doing transparent  FTP sessions  between your
1209 machine and the remote machine that stores your files. This is a special
1210 Emacs mode, called @code{ange-ftp}. To use it, you just have to use a
1211 slightly different syntax when you open a file.
1213 For instance, if you want to  open the file @file{/work/foo.adb} on the machine
1214 aleph.gnu.org, where you log in as qwe, you would simply do this:
1216 @example
1217 C-x C-f /qwe@@aleph.gnu.org:/work/foo.adb @key{RET}
1218 @end example
1220 @noindent
1221 i.e., use your name, the name of the machine and the name of the file.
1223 The first time, Emacs will ask  you for a password that it will remember
1224 until you  close the current Emacs.  Even if the ftp  session times out,
1225 you won't need to reenter your password.
1227 Every time you save the file, Emacs will upload it to the remote machine
1228 transparently. No file is modified on the local machine.
1230 @c ---------------------------------------------------------------------
1231 @section Remote compiling
1232 @c ---------------------------------------------------------------------
1234 If the  machine you  want to  compile on is  not the  one your  Emacs is
1235 running  on,  you can  set  the  variable  @code{remote_machine} in  the
1236 project file for your application.
1238 This  will force  Emacs  to issue  a  @command{rsh} command  for the  compilation,
1239 instead of  running it on  the local machine. Unfortunately,  this won't
1240 work on Windows workstations, since this protocol is not supported.
1242 @example
1243 If  your   @code{remote_machine}  is  aleph.gnu.org   and  the  standard
1244 compilation command is @code{cd /work/ && gnatmake foo}, then Emacs will
1245 actually  issue  the  command  @code{rsh  aleph.gnu.org  'cd  /work/  &&
1246 gnatmake foo'}.
1247 @end example
1249 The advantage of using the  @code{remote_machine} variable is that it is
1250 easier to change  that machine without having to  modify the compilation
1251 command.
1253 Note that if you need to set up some environment variables before the
1254 compilation, you need to insert a call to the appropriate initialization
1255 script in the compilation command, for instance:
1257 @example
1258 build_cmd= initialization_script; cd /work/ && gnatmake foo
1259 @end example
1261 @c ---------------------------------------------------------------------
1262 @section Remote running and debugging
1263 @c ---------------------------------------------------------------------
1265 This feature is not completely implemented yet.
1267 However, most of the time, you will be able to run your application
1268 remotely simply by replacing it with a @command{rsh} call.
1269 For instance, if your command was @code{$@{main@}}, you could replace it with
1270 @code{rsh aleph.gnu.org $@{main@}}.
1272 However, this would not work on vxworks, for instance, where
1273 @command{rsh} is not supported.
1275 @node Index, , Working Remotely, Top
1276 @unnumbered Index
1278 @printindex fn
1280 @contents
1281 @bye
1283 @ignore
1284    arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
1285 @end ignore