|
25906
|
1 \input texinfo @c -*-texinfo-*-
|
|
25913
|
2 @setfilename ../info/ada-mode
|
|
25906
|
3 @settitle Ada Mode
|
|
|
4
|
|
37403
|
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
6 @comment The following lines inserts the copyright notice
|
|
|
7 @comment into the Info file.
|
|
|
8 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
25906
|
9
|
|
47737
|
10 @copying
|
|
64890
|
11 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
|
|
68639
|
12 2005, 2006 Free Software Foundation, Inc.
|
|
25906
|
13
|
|
47737
|
14 @quotation
|
|
37403
|
15 Permission is granted to copy, distribute and/or modify this document
|
|
65555
|
16 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
37403
|
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.
|
|
25906
|
23
|
|
37403
|
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.''
|
|
25906
|
27
|
|
37403
|
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.
|
|
47737
|
32 @end quotation
|
|
|
33 @end copying
|
|
37403
|
34
|
|
47737
|
35 @dircategory Emacs
|
|
|
36 @direntry
|
|
|
37 * Ada mode: (ada-mode). Emacs mode for editing Ada code.
|
|
|
38 @end direntry
|
|
25906
|
39
|
|
|
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
|
|
47737
|
49 @insertcopying
|
|
37403
|
50 @end titlepage
|
|
25906
|
51
|
|
|
52
|
|
|
53 @node Top, Overview, (dir), (dir)
|
|
|
54
|
|
|
55 @menu
|
|
|
56 * Overview::
|
|
38864
|
57 * Installation:: Installing Ada mode on your system
|
|
|
58 * Customization:: Setting up Ada mode to your taste
|
|
25906
|
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
|
|
46918
|
68 * Formatting Parameter Lists:: Formatting subprograms' parameter lists
|
|
25906
|
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
|
|
39367
|
77 * Index::
|
|
25906
|
78 @end menu
|
|
|
79
|
|
|
80
|
|
|
81 @c -----------------------------------------------------------------------
|
|
|
82 @node Overview, Installation, Top, Top
|
|
|
83 @chapter Overview
|
|
|
84 @c -----------------------------------------------------------------------
|
|
|
85
|
|
|
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.
|
|
|
90
|
|
|
91 @section General features:
|
|
|
92
|
|
|
93 @itemize @bullet
|
|
38864
|
94 @item
|
|
|
95 full Integrated Development Environment:
|
|
25906
|
96 @itemize @bullet
|
|
38864
|
97 @item
|
|
|
98 support of ``project files'' for the configuration (directories,
|
|
25906
|
99 compilation options,...)
|
|
38864
|
100 @item
|
|
|
101 compiling and stepping through error messages.
|
|
|
102 @item
|
|
|
103 running and debugging your applications within Emacs.
|
|
25906
|
104 @end itemize
|
|
38864
|
105 @item
|
|
|
106 easy to use for beginners by pull-down menus,
|
|
|
107 @item
|
|
|
108 user configurable by many user-option variables.
|
|
25906
|
109 @end itemize
|
|
|
110
|
|
|
111 @section Ada mode features that help understanding code:
|
|
|
112
|
|
|
113 @itemize @bullet
|
|
38864
|
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
|
|
25906
|
118 defining place by a keystroke),
|
|
38864
|
119 @item
|
|
|
120 displaying an index menu of types and subprograms and move point to
|
|
25906
|
121 the chosen one,
|
|
38864
|
122 @item
|
|
|
123 automatic color highlighting of the various entities in Ada code.
|
|
25906
|
124 @end itemize
|
|
|
125
|
|
|
126 @section Emacs support for writing Ada code:
|
|
|
127
|
|
|
128 @itemize @bullet
|
|
38864
|
129 @item
|
|
|
130 switching between spec and body files with eventually
|
|
25906
|
131 auto-generation of body files,
|
|
38864
|
132 @item
|
|
46918
|
133 automatic formatting of subprograms' parameter lists.
|
|
38864
|
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,
|
|
25906
|
144 @end itemize
|
|
|
145
|
|
|
146 @c -----------------------------------------------------------------------
|
|
|
147 @node Installation, Customization, Overview, Top
|
|
|
148 @chapter Installation
|
|
|
149 @c -----------------------------------------------------------------------
|
|
|
150
|
|
38864
|
151 If you got Ada mode as a separate distribution, you should have a
|
|
25906
|
152 look at the @file{README} file. It explains the basic steps necessary
|
|
|
153 for a good installation of the emacs Ada mode.
|
|
|
154
|
|
|
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
|
|
38864
|
158 automatically load and activate Ada mode.
|
|
25906
|
159
|
42326
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
160 @xref{Using non-standard file names}, if your files do
|
|
25906
|
161 not use these extensions and if you want Emacs to automatically start the
|
|
|
162 Ada mode every time you edit an Ada file.
|
|
|
163
|
42326
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
164 Also, for general usage variables that you might want to set,
|
|
49600
|
165 see
|
42326
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
166 @iftex
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
167 @cite{The GNU Emacs Manual}.
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
168 @end iftex
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
169 @ifhtml
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
170 @cite{The GNU Emacs Manual}.
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
171 @end ifhtml
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
172 @ifinfo
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
173 @ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
174 @end ifinfo
|
|
25906
|
175
|
|
|
176 @c ---------------------------------------------------------------------
|
|
|
177 @section Required files
|
|
|
178 @c ---------------------------------------------------------------------
|
|
|
179
|
|
|
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
|
|
38864
|
184 installing Ada mode.
|
|
25906
|
185
|
|
38864
|
186 Although part of Ada mode is compiler-independent, the most advanced
|
|
25906
|
187 features are specific to the Gnat compiler @url{http://www.gnat.com}.
|
|
|
188
|
|
|
189 The following files are provided with the Ada mode distribution:
|
|
|
190
|
|
|
191 @itemize @bullet
|
|
|
192
|
|
38864
|
193 @item
|
|
|
194 @file{ada-mode.el}: The main file for Ada mode.
|
|
25906
|
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.
|
|
|
201
|
|
38864
|
202 @item
|
|
|
203 @file{ada-stmt.el}: Contains the statement templates feature.
|
|
25906
|
204
|
|
38864
|
205 @item
|
|
|
206 @file{ada-xref.el}: This file provides the main support for Gnat.
|
|
25906
|
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.
|
|
|
210
|
|
38864
|
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.
|
|
25906
|
215
|
|
|
216 @end itemize
|
|
|
217
|
|
|
218 @c --------------------------------------------------------------------
|
|
|
219 @node Customization, Project files, Installation, Top
|
|
38864
|
220 @chapter Customizing Ada mode
|
|
25906
|
221 @c ---------------------------------------------------------------------
|
|
|
222
|
|
38864
|
223 Ada mode is fully customizable. Everything, from the file names to
|
|
25906
|
224 the automatic indentation and the automatic casing can be adapted to
|
|
|
225 your own needs.
|
|
|
226
|
|
|
227 There are two different kinds of variables that control this
|
|
|
228 customization, both are easy to modify.
|
|
|
229
|
|
|
230 The first set of variables are standard Emacs variables. Of course, some
|
|
38864
|
231 are defined only for Ada mode, whereas others have a more general
|
|
25906
|
232 meaning in Emacs. Please see the Emacs documentation for more
|
|
|
233 information on the latest. In this documentation, we will detail all the
|
|
38864
|
234 variables that are specific to Ada mode, and a few others. The names
|
|
25906
|
235 will be given, as in @code{ada-case-identifier}.
|
|
|
236
|
|
|
237 Emacs provides an easy way to modify them, through a special mode called
|
|
|
238 customization. To access this mode, select the menu
|
|
38864
|
239 @samp{Ada->Customize}. This will open a new buffer with some fields that
|
|
25906
|
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.
|
|
|
248
|
|
|
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.
|
|
|
254
|
|
|
255 To modify a specific variable, you can directly call the function
|
|
38864
|
256 @code{customize-variable} from Emacs (just type @kbd{M-x
|
|
|
257 customize-variable @key{RET} @var{variable-name} @key{RET}}).
|
|
25906
|
258
|
|
|
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
|
|
|
265
|
|
|
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}.
|
|
|
270
|
|
|
271 @c ---------------------------------------------------------------------
|
|
|
272 @node Project files, Syntax highlighting, Customization, Top
|
|
|
273 @chapter Project files
|
|
|
274 @c ---------------------------------------------------------------------
|
|
|
275
|
|
|
276 @c ---------------------------------------------------------------------
|
|
|
277 @section General overview
|
|
|
278 @c ---------------------------------------------------------------------
|
|
|
279
|
|
|
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.
|
|
|
283
|
|
|
284 To take full advantage of this features, it is possible to create a file
|
|
38864
|
285 in the main directory of your application, with a @samp{.adp} extension.
|
|
25906
|
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.
|
|
|
291
|
|
|
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.
|
|
|
296
|
|
|
297 Once in the buffer for editing the project file, you can save your
|
|
38864
|
298 modification using the @samp{[OK]} button at the bottom of the buffer, or
|
|
25906
|
299 simply use the usual @kbd{C-x C-s} binding. To cancel your
|
|
38864
|
300 modifications, simply kill the buffer or click on the @samp{[CANCEL]} button
|
|
25906
|
301 at the button.
|
|
|
302
|
|
|
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.
|
|
|
306
|
|
|
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.
|
|
|
310
|
|
|
311 @itemize @bullet
|
|
38864
|
312 @item
|
|
|
313 To set up a default project file to use for any directory, anywhere
|
|
25906
|
314 on your system, set the variable @code{ada-prj-default-project-file} to
|
|
|
315 the name of that file.
|
|
38864
|
316
|
|
25906
|
317 @example
|
|
38864
|
318 (set 'ada-prj-default-project-file "/dir1/dir2/file")
|
|
25906
|
319 @end example
|
|
|
320
|
|
38864
|
321 @item
|
|
|
322 For finer control, you can set a per-directory project file.
|
|
25906
|
323 This is done through the variable @code{ada-xref-default-prj-file}.
|
|
38864
|
324
|
|
25906
|
325 @example
|
|
|
326 (set 'ada-xref-default-prj-file
|
|
|
327 '(("/dir1/dir2" . "/dir3/file1")
|
|
|
328 ("/dir4/dir5" . "/dir6/file2")))
|
|
|
329 @end example
|
|
38864
|
330
|
|
25906
|
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
|
|
|
335
|
|
|
336
|
|
|
337 @table @kbd
|
|
38864
|
338 @item C-c u
|
|
39367
|
339 @findex ada-customize
|
|
38864
|
340 Create or edit the project file for the current buffer (@code{ada-customize}).
|
|
49600
|
341 @item C-c c
|
|
39367
|
342 @findex ada-change-prj
|
|
38864
|
343 Change the project file associated with the current Ada buffer (@code{ada-change-prj}).
|
|
25906
|
344 @item C-c d
|
|
39367
|
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.
|
|
38864
|
349 @item ada-set-default-project-file
|
|
39367
|
350 @findex ada-set-default-project-file
|
|
25906
|
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
|
|
|
354
|
|
|
355 @c ---------------------------------------------------------------------
|
|
|
356 @section Project file variables
|
|
|
357 @c ---------------------------------------------------------------------
|
|
|
358
|
|
|
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.
|
|
|
362
|
|
|
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.
|
|
|
367
|
|
|
368 Here is the list of variables:
|
|
|
369
|
|
38864
|
370 @table @asis
|
|
|
371 @item @code{src_dir} [default: @code{"./"}]
|
|
|
372 This is a list of directories where Ada mode will look for source
|
|
25906
|
373 files. These directories are used mainly in two cases, both as a switch
|
|
|
374 for the compiler and for the cross-references.
|
|
|
375
|
|
38864
|
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.
|
|
25906
|
380
|
|
38864
|
381 @item @code{comp_opt} [default: @code{""}]
|
|
25906
|
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
|
|
38864
|
384 switches given to @command{gnatmake} and @command{gcc}.
|
|
25906
|
385
|
|
38864
|
386 @item @code{bind_opt=@var{switches}} [default: @code{""}]
|
|
25906
|
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
|
|
38864
|
389 switches given to @command{gnatbind}.
|
|
25906
|
390
|
|
38864
|
391 @item @code{link_opt=@var{switches}} [default: @code{""}]
|
|
25906
|
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
|
|
38864
|
394 switches given to @command{gnatlink}.
|
|
25906
|
395
|
|
38864
|
396 @item @code{main=@var{executable}} [default: @code{""}]
|
|
25906
|
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.
|
|
|
400
|
|
38864
|
401 @item @code{cross_prefix=@var{prefix}} [default: @code{""}]
|
|
25906
|
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.
|
|
|
404
|
|
38864
|
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.
|
|
25906
|
411
|
|
38864
|
412 @item @code{comp_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"}]
|
|
25906
|
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.
|
|
|
415
|
|
38864
|
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@}"]}'
|
|
25906
|
417 Specifies the command used to recompile the whole application.
|
|
|
418
|
|
38864
|
419 @item @code{run_cmd=@var{command}} [default: @code{"$@{main@}"}]
|
|
25906
|
420 Specifies the command used to run the application.
|
|
|
421
|
|
38864
|
422 @item @code{debug_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
|
|
25906
|
423 Specifies the command used to debug the application
|
|
|
424
|
|
|
425 @end table
|
|
|
426
|
|
|
427 @c ---------------------------------------------------------------------
|
|
|
428 @section Detailed algorithm
|
|
|
429 @c ---------------------------------------------------------------------
|
|
|
430
|
|
|
431 This section gives more details on the project file setup and is only of
|
|
|
432 interest for advanced users.
|
|
|
433
|
|
|
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:
|
|
|
439
|
|
|
440 @itemize @bullet
|
|
38864
|
441 @item
|
|
|
442 find the appropriate project file, open and parse it.
|
|
25906
|
443 All the fields read in the project file are then stored by emacs
|
|
|
444 locally. Finding the project file requires a few steps:
|
|
|
445
|
|
|
446 @itemize @minus
|
|
38864
|
447 @item
|
|
|
448 if a file from the same directory was already associated with
|
|
25906
|
449 a project file, use the same one. This is the variable
|
|
|
450 @code{ada-xref-default-prj-file} described above.
|
|
38864
|
451 @item
|
|
|
452 if the variable @code{ada-prj-default-project-file} is set,
|
|
25906
|
453 use the project file specified in this variable.
|
|
38864
|
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
|
|
25906
|
459 that one.
|
|
38864
|
460 @item
|
|
|
461 if there are more than one project file in the source directory,
|
|
25906
|
462 ask the user.
|
|
38864
|
463 @item
|
|
|
464 if there are no project files in the source directory use standard
|
|
25906
|
465 default values.
|
|
|
466 @end itemize
|
|
|
467
|
|
|
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.
|
|
|
471
|
|
38864
|
472 @item
|
|
38881
|
473 look for the corresponding @samp{.ali} file in the @code{obj_dir} defined
|
|
25906
|
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.
|
|
|
477
|
|
38864
|
478 @item
|
|
38881
|
479 when cross referencing is requested, the @samp{.ali} file is parsed to
|
|
25906
|
480 determine the file and line of the identifier definition. It is
|
|
38881
|
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.
|
|
25906
|
485
|
|
38864
|
486 @item
|
|
|
487 look for the file containing the declaration using the source
|
|
25906
|
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
|
|
|
491
|
|
|
492 @c -----------------------------------------------------------------------
|
|
|
493 @node Syntax highlighting, Moving Through Ada Code, Project files, Top
|
|
|
494 @chapter Syntax highlighting
|
|
|
495 @c -----------------------------------------------------------------------
|
|
|
496
|
|
38864
|
497 Ada mode is made to help you understand the structure of your source
|
|
25906
|
498 files. Some people like having colors or different fonts depending on
|
|
|
499 the context: commands should be displayed differently than keywords,
|
|
38864
|
500 which should also be different from strings, @dots{}
|
|
25906
|
501
|
|
|
502 Emacs is able to display in a different way the following syntactic
|
|
|
503 entities:
|
|
|
504
|
|
|
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
|
|
|
513
|
|
|
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).
|
|
|
517
|
|
|
518 @example
|
|
38864
|
519 (global-font-lock-mode t)
|
|
25906
|
520 @end example
|
|
|
521
|
|
|
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
|
|
38864
|
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
|
|
25906
|
526 about. You can change any of them.
|
|
|
527
|
|
|
528
|
|
|
529 @c -----------------------------------------------------------------------
|
|
|
530 @node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top
|
|
|
531 @chapter Moving Through Ada Code
|
|
|
532 @c -----------------------------------------------------------------------
|
|
|
533
|
|
|
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:
|
|
|
537
|
|
|
538 @table @kbd
|
|
40705
|
539 @item C-M-e
|
|
39367
|
540 @findex ada-next-procedure
|
|
38864
|
541 Move to the next function/procedure/task, which ever comes next
|
|
|
542 (@code{ada-next-procedure}).
|
|
40705
|
543 @item C-M-a
|
|
39367
|
544 @findex ada-previous-procedure
|
|
38864
|
545 Move to previous function/procedure/task
|
|
|
546 (@code{ada-previous-procedure}).
|
|
|
547 @item M-x ada-next-package
|
|
39367
|
548 @findex ada-next-package
|
|
25906
|
549 Move to next package.
|
|
38864
|
550 @item M-x ada-prev-package
|
|
39367
|
551 @findex ada-prev-package
|
|
25906
|
552 Move to previous package.
|
|
38864
|
553 @item C-c C-a
|
|
39367
|
554 @findex ada-move-to-start
|
|
38864
|
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
|
|
39367
|
561 @findex ada-move-to-end
|
|
38864
|
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.
|
|
25906
|
567 @item C-c c-d
|
|
39367
|
568 @findex ada-goto-declaration
|
|
25906
|
569 Move from any reference to its declaration and switch between
|
|
|
570 declaration and body (for procedures, tasks, private and incomplete
|
|
|
571 types).
|
|
38864
|
572 @item C-c C-r
|
|
39367
|
573 @findex ada-find-references
|
|
38864
|
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).
|
|
25906
|
578 @end table
|
|
|
579
|
|
|
580 These functions use the information in the output of the Gnat Ada
|
|
|
581 compiler. However, if your application was compiled with the
|
|
38864
|
582 @samp{-gnatx} switch, these functions will not work, since no extra
|
|
25906
|
583 information is generated by GNAT. See GNAT documentation for further
|
|
|
584 information.
|
|
|
585
|
|
|
586 Emacs will try to run Gnat for you whenever the cross-reference
|
|
|
587 informations are older than your source file (provided the
|
|
38864
|
588 @code{ada-xref-create-ali} variable is non-@code{nil}). Gnat then produces a
|
|
25906
|
589 file with the same name as the current Ada file but with the extension
|
|
38864
|
590 changed to @file{.ali}. This files are normally used by the binder, but
|
|
25906
|
591 they will also contain additional cross-referencing information.
|
|
|
592
|
|
|
593 @c -----------------------------------------------------------------------
|
|
|
594 @node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top
|
|
|
595 @chapter Identifier completion
|
|
|
596 @c -----------------------------------------------------------------------
|
|
|
597
|
|
|
598 @c -----------------------------------------------------------------------
|
|
|
599 @section Overview
|
|
|
600 @c -----------------------------------------------------------------------
|
|
|
601
|
|
38864
|
602 Emacs and Ada mode provide two general ways for the completion of
|
|
25906
|
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.
|
|
|
606
|
|
|
607 The first method is general for Emacs. It will work both with Ada
|
|
38864
|
608 buffers, but also in C buffers, Java buffers, @enddots{} The idea is to parse
|
|
25906
|
609 all the opened buffers for possible completions.
|
|
|
610
|
|
38864
|
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:
|
|
|
614
|
|
|
615 @quotation
|
|
25906
|
616 You type: my@key{M-/}
|
|
38864
|
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
|
|
25906
|
622
|
|
|
623 This is a very fast way to do completion, and the casing of words will
|
|
|
624 also be respected.
|
|
|
625
|
|
|
626 The second method is specific to Ada buffer, and even to users of the
|
|
38881
|
627 Gnat compiler. Emacs will search the cross-information found in the
|
|
|
628 @samp{.ali} files generated by Gnat for possible completions.
|
|
25906
|
629
|
|
|
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
|
|
38864
|
632 opened that already contains this identifiers, @enddots{}
|
|
25906
|
633
|
|
|
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.
|
|
|
637
|
|
|
638 @c -----------------------------------------------------------------------
|
|
|
639 @section Summary of commands
|
|
|
640 @c -----------------------------------------------------------------------
|
|
|
641
|
|
|
642 @table @kbd
|
|
38864
|
643 @item C-@key{TAB}
|
|
39367
|
644 @findex ada-complete-identifier
|
|
38864
|
645 Complete accurately current identifier using information in @samp{.ali} file
|
|
|
646 (@code{ada-complete-identifier}).
|
|
25906
|
647 @item M-/
|
|
38864
|
648 Complete identifier using buffer information (not Ada-specific).
|
|
25906
|
649 @end table
|
|
|
650
|
|
|
651 @c -----------------------------------------------------------------------
|
|
|
652 @node Index Menu of Subprograms, File Browser, Identifier completion, Top
|
|
|
653 @chapter Index Menu of Subprograms
|
|
|
654 @c -----------------------------------------------------------------------
|
|
|
655
|
|
|
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
|
|
38864
|
658 declaration. This function is accessible through the @samp{Ada} menu when
|
|
|
659 editing a Ada file, or simply through the following key binding:
|
|
25906
|
660
|
|
|
661 @table @kbd
|
|
36509
|
662 @item C-S-Mouse-3
|
|
25906
|
663 display index menu
|
|
|
664 @end table
|
|
|
665
|
|
|
666 @c -----------------------------------------------------------------------
|
|
|
667 @node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top
|
|
|
668 @chapter File Browser
|
|
|
669 @c -----------------------------------------------------------------------
|
|
|
670
|
|
|
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.
|
|
|
675
|
|
|
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,
|
|
38864
|
678 including of course Ada mode for files written in Ada.
|
|
25906
|
679
|
|
38864
|
680 If you click on the @samp{[+]} symbol near a file name, all the symbols (types,
|
|
25906
|
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.
|
|
|
684
|
|
|
685 You can activate this mode by typing @key{M-x speedbar} in the editor.
|
|
46918
|
686 This will open a new frame. A better way might be to associate the
|
|
25906
|
687 following key binding
|
|
|
688
|
|
|
689 @example
|
|
|
690 (global-set-key [f7] 'speedbar-get-focus)
|
|
|
691 @end example
|
|
|
692
|
|
38864
|
693 Every time you press @key{F7}, the mouse will automatically move to the
|
|
25906
|
694 speedbar frame (which will be created if it does not exist).
|
|
|
695
|
|
|
696 @c -----------------------------------------------------------------------
|
|
|
697 @node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top
|
|
|
698 @chapter Automatic Smart Indentation
|
|
|
699 @c -----------------------------------------------------------------------
|
|
|
700
|
|
38864
|
701 Ada mode comes with a full set of rules for automatic indentation.
|
|
25906
|
702 You can of course configure the indentation as you want, by setting the
|
|
|
703 value of a few variables.
|
|
|
704
|
|
|
705 As always, the preferred way to modify variables is to use the
|
|
38864
|
706 @samp{Ada->Customize} menu (don't forget to save your changes!). This
|
|
25906
|
707 will also show you some example of code where this variable is used, and
|
|
|
708 hopefully make things clearer.
|
|
|
709
|
|
|
710 The relevant variables are the following:
|
|
|
711
|
|
38864
|
712 @table @asis
|
|
|
713 @item @code{ada-broken-indent} (default value: 2)
|
|
|
714 Number of columns to indent the continuation of a broken line.
|
|
25906
|
715
|
|
38864
|
716 @item @code{ada-indent} (default value: 3)
|
|
|
717 Width of the default indentation.
|
|
25906
|
718
|
|
38864
|
719 @item @code{ada-indent-record-rel-type} (default value: 3)
|
|
|
720 Indentation for @code{record} relative to @code{type} or @code{use}.
|
|
25906
|
721
|
|
38864
|
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}.
|
|
25906
|
728
|
|
38864
|
729 @item @code{ada-label-indent} (default value: -4)
|
|
|
730 Number of columns to indent a label.
|
|
25906
|
731
|
|
38864
|
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.
|
|
25906
|
734
|
|
38864
|
735 @item @code{ada-when-indent} (default value: 3)
|
|
|
736 Indentation for @code{when} relative to @code{exception} or @code{case}.
|
|
25906
|
737
|
|
38864
|
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.
|
|
25906
|
740
|
|
38864
|
741 @item @code{ada-indent-to-open-paren} (default value: t)
|
|
|
742 Non-@code{nil} means indent according to the innermost open parenthesis.
|
|
25906
|
743
|
|
38864
|
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}.
|
|
25906
|
747 @end table
|
|
|
748
|
|
|
749 Most of the time, the indentation will be automatic, i.e when you will
|
|
38864
|
750 press @key{RET}, the cursor will move to the correct column on the
|
|
25906
|
751 next line.
|
|
|
752
|
|
|
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
|
|
38864
|
755 the lines, and then press @key{TAB}. This will automatically re-indent
|
|
25906
|
756 the lines.
|
|
|
757
|
|
38864
|
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:
|
|
|
761
|
|
25906
|
762 @itemize @bullet
|
|
38864
|
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.
|
|
25906
|
771 @end itemize
|
|
|
772
|
|
|
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.
|
|
|
775
|
|
38864
|
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.
|
|
25906
|
780
|
|
|
781 @table @kbd
|
|
38864
|
782 @item @key{TAB}
|
|
|
783 Indent the current line or the current region.
|
|
40705
|
784 @item C-M-\
|
|
38864
|
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
|
|
25906
|
788 indentation.
|
|
|
789 @end table
|
|
|
790
|
|
|
791
|
|
|
792
|
|
|
793 @c -----------------------------------------------------------------------
|
|
|
794 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
|
|
|
795 @chapter Formatting Parameter Lists
|
|
|
796 @c -----------------------------------------------------------------------
|
|
|
797
|
|
38864
|
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.
|
|
25906
|
803
|
|
|
804 @table @kbd
|
|
38864
|
805 @item C-c C-f
|
|
39367
|
806 @findex ada-format-paramlist
|
|
38864
|
807 Format the parameter list (@code{ada-format-paramlist}).
|
|
25906
|
808 @end table
|
|
|
809
|
|
|
810 @c -----------------------------------------------------------------------
|
|
|
811 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
|
|
|
812 @chapter Automatic Casing
|
|
|
813 @c -----------------------------------------------------------------------
|
|
|
814
|
|
|
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.
|
|
|
819
|
|
|
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}.
|
|
|
824
|
|
|
825 All these variables can have one of the following values:
|
|
|
826
|
|
38864
|
827 @table @code
|
|
25906
|
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}.
|
|
|
831
|
|
|
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}.
|
|
|
835
|
|
|
836 @item ada-capitalize-word
|
|
|
837 All letters, except the first one of the word and every letter after the
|
|
38864
|
838 @samp{_} character are lower cased. Other letters are upper cased. For
|
|
25906
|
839 instance @code{My_vARIable} is converted to @code{My_Variable}.
|
|
|
840
|
|
|
841 @item ada-loose-case-word
|
|
|
842 No letters is modified in the previous word, except the ones after the
|
|
38864
|
843 @samp{_} character that are upper cased. For instance @code{My_vARIable} is
|
|
25906
|
844 converted to @code{My_VARIable}.
|
|
|
845 @end table
|
|
|
846
|
|
|
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.
|
|
|
850
|
|
|
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}.
|
|
|
856
|
|
|
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
|
|
38864
|
860 recommended in the Ada 95 Quality and Style, paragraph 3.1.4). Thus, a
|
|
25906
|
861 good example for this file could be:
|
|
|
862
|
|
|
863 @example
|
|
|
864 DOD Department of Defense
|
|
|
865 Text_IO
|
|
|
866 GNAT The GNAT compiler from Ada Core Technologies
|
|
|
867 @end example
|
|
|
868
|
|
|
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).
|
|
|
874
|
|
39367
|
875 @findex ada-create-case-exception
|
|
25906
|
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
|
|
38864
|
881 select the menu @samp{Ada->Edit->Create Case Exception}, or the key
|
|
39367
|
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.
|
|
25906
|
884
|
|
|
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.
|
|
|
891
|
|
|
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.
|
|
|
896
|
|
|
897 Automatic casing can be performed on port or whole buffer using:
|
|
38864
|
898
|
|
25906
|
899 @table @kbd
|
|
|
900 @item C-c C-b
|
|
39367
|
901 @findex ada-adjust-case-buffer
|
|
|
902 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
|
|
25906
|
903 @item C-c C-y
|
|
|
904 Create a new entry in the exception dictionary, with the word under
|
|
39367
|
905 the cursor (@code{ada-create-case-exception})
|
|
25906
|
906 @item C-c C-t
|
|
39367
|
907 @findex ada-case-read-exceptions
|
|
25906
|
908 Rereads the exception dictionary from the file
|
|
39367
|
909 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
|
|
25906
|
910 @end table
|
|
|
911
|
|
|
912 @c -----------------------------------------------------------------------
|
|
|
913 @node Statement Templates, Comment Handling, Automatic Casing, Top
|
|
|
914 @chapter Statement Templates
|
|
|
915 @c -----------------------------------------------------------------------
|
|
|
916
|
|
|
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.
|
|
|
919
|
|
|
920 Templates exist for most Ada statements. They can be inserted in the
|
|
|
921 buffer using the following commands:
|
|
|
922
|
|
|
923 @table @kbd
|
|
|
924 @item C-c t b
|
|
39367
|
925 @findex ada-exception-block
|
|
|
926 exception Block (@code{ada-exception-block}).
|
|
25906
|
927 @item C-c t c
|
|
39367
|
928 @findex ada-case
|
|
|
929 case (@code{ada-case}).
|
|
25906
|
930 @item C-c t d
|
|
39367
|
931 @findex ada-declare-block
|
|
|
932 declare Block (@code{ada-declare-block}).
|
|
25906
|
933 @item C-c t e
|
|
39367
|
934 @findex ada-else
|
|
|
935 else (@code{ada-else}).
|
|
25906
|
936 @item C-c t f
|
|
39367
|
937 @findex ada-for-loop
|
|
|
938 for Loop (@code{ada-for-loop}).
|
|
25906
|
939 @item C-c t h
|
|
39367
|
940 @findex ada-header
|
|
|
941 Header (@code{ada-header}).
|
|
25906
|
942 @item C-c t i
|
|
39367
|
943 @findex ada-if
|
|
|
944 if (@code{ada-if}).
|
|
25906
|
945 @item C-c t k
|
|
39367
|
946 @findex ada-package-body
|
|
|
947 package Body (@code{ada-package-body}).
|
|
25906
|
948 @item C-c t l
|
|
39367
|
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}).
|
|
25906
|
954 @item C-c t t
|
|
39367
|
955 @findex ada-task-body
|
|
|
956 task Body (@code{ada-task-body}).
|
|
25906
|
957 @item C-c t w
|
|
39367
|
958 @findex ada-while
|
|
|
959 while Loop (@code{ada-while}).
|
|
25906
|
960 @item C-c t u
|
|
39367
|
961 @findex ada-use
|
|
|
962 use (@code{ada-use}).
|
|
25906
|
963 @item C-c t x
|
|
39367
|
964 @findex ada-exit
|
|
|
965 exit (@code{ada-exit}).
|
|
25906
|
966 @item C-c t C-a
|
|
39367
|
967 @findex ada-array
|
|
|
968 array (@code{ada-array}).
|
|
25906
|
969 @item C-c t C-e
|
|
39367
|
970 @findex ada-elsif
|
|
|
971 elsif (@code{ada-elsif}).
|
|
25906
|
972 @item C-c t C-f
|
|
39367
|
973 @findex ada-function-spec
|
|
|
974 function Spec (@code{ada-function-spec}).
|
|
25906
|
975 @item C-c t C-k
|
|
39367
|
976 @findex ada-package-spec
|
|
|
977 package Spec (@code{ada-package-spec}).
|
|
25906
|
978 @item C-c t C-p
|
|
39367
|
979 @findex ada-procedure-spec
|
|
|
980 procedure Spec (@code{ada-package-spec}.
|
|
25906
|
981 @item C-c t C-r
|
|
39367
|
982 @findex ada-record
|
|
|
983 record (@code{ada-record}).
|
|
25906
|
984 @item C-c t C-s
|
|
39367
|
985 @findex ada-subtype
|
|
|
986 subtype (@code{ada-subtype}).
|
|
25906
|
987 @item C-c t C-t
|
|
39367
|
988 @findex ada-task-spec
|
|
|
989 task Spec (@code{ada-task-spec}).
|
|
25906
|
990 @item C-c t C-u
|
|
39367
|
991 @findex ada-with
|
|
|
992 with (@code{ada-with}).
|
|
25906
|
993 @item C-c t C-v
|
|
39367
|
994 @findex ada-private
|
|
|
995 private (@code{ada-private}).
|
|
25906
|
996 @item C-c t C-w
|
|
39367
|
997 @findex ada-when
|
|
|
998 when (@code{ada-when}).
|
|
25906
|
999 @item C-c t C-x
|
|
39367
|
1000 @findex ada-exception
|
|
|
1001 exception (@code{ada-exception}).
|
|
25906
|
1002 @item C-c t C-y
|
|
39367
|
1003 @findex ada-type
|
|
|
1004 type (@code{ada-type}).
|
|
25906
|
1005 @end table
|
|
|
1006
|
|
|
1007 @c -----------------------------------------------------------------------
|
|
|
1008 @node Comment Handling, Compiling Executing, Statement Templates, Top
|
|
|
1009 @chapter Comment Handling
|
|
|
1010 @c -----------------------------------------------------------------------
|
|
|
1011
|
|
|
1012 By default, comment lines get indented like Ada code. There are a few
|
|
|
1013 additional functions to handle comments:
|
|
|
1014
|
|
|
1015
|
|
|
1016 @table @kbd
|
|
|
1017 @item M-;
|
|
|
1018 Start a comment in default column.
|
|
|
1019 @item M-j
|
|
|
1020 Continue comment on next line.
|
|
38864
|
1021 @item C-c ;
|
|
25906
|
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
|
|
|
1028
|
|
|
1029 @c -----------------------------------------------------------------------
|
|
|
1030 @node Compiling Executing, Debugging, Comment Handling, Top
|
|
|
1031 @chapter Compiling Executing
|
|
|
1032 @c -----------------------------------------------------------------------
|
|
|
1033
|
|
|
1034 Ada mode provides a much complete environment for compiling, debugging
|
|
|
1035 and running an application within Emacs.
|
|
|
1036
|
|
|
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.
|
|
|
1042
|
|
|
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}
|
|
38881
|
1048 will become @code{cross_prefix}-@code{gnatmake}, @enddots{}
|
|
25906
|
1049
|
|
|
1050 This will also modify the way your application is run and debugged,
|
|
|
1051 although this is not implemented at the moment.
|
|
|
1052
|
|
|
1053 Here are the commands for building and using an Ada application
|
|
|
1054
|
|
|
1055 @itemize @bullet
|
|
|
1056
|
|
|
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.
|
|
|
1062
|
|
|
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
|
|
38864
|
1066 cursor on it and press @key{RET}. Emacs will then display the
|
|
25906
|
1067 relevant source file and put the cursor on the line and column the error
|
|
|
1068 was found at.
|
|
|
1069
|
|
|
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.
|
|
|
1073
|
|
|
1074 Some error messages might also include references to some files. These
|
|
|
1075 references are also clickable in the same way.
|
|
|
1076
|
|
|
1077
|
|
|
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}.
|
|
|
1086
|
|
|
1087 The compilation buffer is also active in the same way it was for the above
|
|
|
1088 command.
|
|
|
1089
|
|
|
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.
|
|
|
1095
|
|
|
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.
|
|
|
1099
|
|
|
1100 @end itemize
|
|
|
1101
|
|
|
1102 @c ---------------------------------------------------------------------
|
|
|
1103 @node Debugging, Using non-standard file names, Compiling Executing, Top
|
|
|
1104 @chapter Debugging your application
|
|
|
1105 @c ---------------------------------------------------------------------
|
|
|
1106
|
|
|
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.
|
|
|
1110
|
|
|
1111 This selection will focus on the gdb debugger, and two of the graphical
|
|
|
1112 interfaces that exist for it.
|
|
|
1113
|
|
|
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.
|
|
|
1121
|
|
|
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.
|
|
|
1125
|
|
|
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
|
|
38864
|
1129 cross-references features that Ada mode provides to look at the
|
|
|
1130 definition for the identifiers, @enddots{}
|
|
25906
|
1131
|
|
|
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):
|
|
|
1134
|
|
|
1135 @itemize @bullet
|
|
|
1136 @item gdbtk
|
|
38864
|
1137 should be used with the switch @samp{--emacs_gdbtk}. It provides a nice
|
|
25906
|
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.
|
|
|
1141
|
|
|
1142 @item ddd (Data Display Debugger)
|
|
38864
|
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.
|
|
25906
|
1146
|
|
|
1147 @end itemize
|
|
|
1148
|
|
|
1149
|
|
|
1150 @c ---------------------------------------------------------------------
|
|
|
1151 @node Using non-standard file names, Working Remotely, Debugging, Top
|
|
|
1152 @chapter Using non-standard file names
|
|
|
1153 @c ---------------------------------------------------------------------
|
|
|
1154
|
|
|
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
|
|
38864
|
1157 are respectively @samp{.ads} and @samp{.adb}.
|
|
25906
|
1158
|
|
|
1159 If you want to use other types of file names, you will need to modify
|
|
38864
|
1160 your @file{.emacs} file.
|
|
25906
|
1161
|
|
38864
|
1162 Adding new possible extensions is easy. Since Ada mode needs to know
|
|
25906
|
1163 how to go from the body to the spec (and back), you always have to
|
|
38864
|
1164 specify both. A function is provided with Ada mode to add new
|
|
25906
|
1165 extensions.
|
|
|
1166
|
|
38864
|
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:
|
|
25906
|
1170
|
|
|
1171 @example
|
|
|
1172 (ada-add-extensions "_s.ada" "_b.ada")
|
|
|
1173 @end example
|
|
|
1174
|
|
|
1175 Note that it is possible to redefine the extension, even if they already
|
|
|
1176 exist, as in:
|
|
|
1177
|
|
|
1178 @example
|
|
|
1179 (ada-add-extensions ".ads" "_b.ada")
|
|
|
1180 (ada-add-extensions ".ads" ".body")
|
|
|
1181 @end example
|
|
|
1182
|
|
|
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}.
|
|
|
1187
|
|
38864
|
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).
|
|
25906
|
1192
|
|
|
1193 @c ---------------------------------------------------------------------
|
|
39367
|
1194 @node Working Remotely, Index, Using non-standard file names, Top
|
|
25906
|
1195 @chapter Working Remotely
|
|
|
1196 @c ---------------------------------------------------------------------
|
|
|
1197
|
|
|
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.
|
|
|
1201
|
|
|
1202 Fortunately, here too Emacs provides a very convenient way to do this.
|
|
|
1203
|
|
|
1204 @c ---------------------------------------------------------------------
|
|
|
1205 @section Remote editing
|
|
|
1206 @c ---------------------------------------------------------------------
|
|
|
1207
|
|
|
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.
|
|
|
1213
|
|
38864
|
1214 For instance, if you want to open the file @file{/work/foo.adb} on the machine
|
|
25906
|
1215 aleph.gnu.org, where you log in as qwe, you would simply do this:
|
|
|
1216
|
|
38864
|
1217 @example
|
|
|
1218 C-x C-f /qwe@@aleph.gnu.org:/work/foo.adb @key{RET}
|
|
|
1219 @end example
|
|
25906
|
1220
|
|
38864
|
1221 @noindent
|
|
|
1222 i.e., use your name, the name of the machine and the name of the file.
|
|
25906
|
1223
|
|
|
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.
|
|
|
1227
|
|
|
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.
|
|
|
1230
|
|
|
1231 @c ---------------------------------------------------------------------
|
|
|
1232 @section Remote compiling
|
|
|
1233 @c ---------------------------------------------------------------------
|
|
|
1234
|
|
|
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.
|
|
|
1238
|
|
38864
|
1239 This will force Emacs to issue a @command{rsh} command for the compilation,
|
|
25906
|
1240 instead of running it on the local machine. Unfortunately, this won't
|
|
|
1241 work on Windows workstations, since this protocol is not supported.
|
|
|
1242
|
|
|
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
|
|
|
1249
|
|
|
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.
|
|
|
1253
|
|
|
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:
|
|
|
1257
|
|
|
1258 @example
|
|
38864
|
1259 build_cmd= initialization_script; cd /work/ && gnatmake foo
|
|
25906
|
1260 @end example
|
|
|
1261
|
|
|
1262 @c ---------------------------------------------------------------------
|
|
|
1263 @section Remote running and debugging
|
|
|
1264 @c ---------------------------------------------------------------------
|
|
|
1265
|
|
|
1266 This feature is not completely implemented yet.
|
|
|
1267
|
|
|
1268 However, most of the time, you will be able to run your application
|
|
38864
|
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@}}.
|
|
25906
|
1272
|
|
38864
|
1273 However, this would not work on vxworks, for instance, where
|
|
|
1274 @command{rsh} is not supported.
|
|
25906
|
1275
|
|
39367
|
1276 @node Index, , Working Remotely, Top
|
|
|
1277 @unnumbered Index
|
|
|
1278
|
|
|
1279 @printindex fn
|
|
|
1280
|
|
25906
|
1281 @contents
|
|
|
1282 @bye
|
|
52401
|
1283
|
|
|
1284 @ignore
|
|
|
1285 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
|
|
|
1286 @end ignore
|
