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