25906
|
1 \input texinfo @c -*-texinfo-*-
|
25913
|
2 @setfilename ../info/ada-mode
|
25906
|
3 @settitle Ada Mode
|
|
4
|
47737
|
5 @copying
|
64890
|
6 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
|
75348
|
7 2005, 2006, 2007 Free Software Foundation, Inc.
|
25906
|
8
|
47737
|
9 @quotation
|
37403
|
10 Permission is granted to copy, distribute and/or modify this document
|
65555
|
11 under the terms of the GNU Free Documentation License, Version 1.2 or
|
37403
|
12 any later version published by the Free Software Foundation; with the
|
|
13 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
|
|
14 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
|
|
15 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
16 license is included in the section entitled ``GNU Free Documentation
|
|
17 License'' in the Emacs manual.
|
25906
|
18
|
37403
|
19 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
20 this GNU Manual, like GNU software. Copies published by the Free
|
|
21 Software Foundation raise funds for GNU development.''
|
25906
|
22
|
37403
|
23 This document is part of a collection distributed under the GNU Free
|
|
24 Documentation License. If you want to distribute this document
|
|
25 separately from the collection, you can do so by adding a copy of the
|
|
26 license to the document, as described in section 6 of the license.
|
47737
|
27 @end quotation
|
|
28 @end copying
|
37403
|
29
|
47737
|
30 @dircategory Emacs
|
|
31 @direntry
|
74004
|
32 * Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code.
|
47737
|
33 @end direntry
|
25906
|
34
|
|
35 @titlepage
|
|
36 @sp 10
|
|
37 @title{Ada Mode}
|
|
38 @sp 2
|
74004
|
39 @subtitle An Emacs major mode for programming in Ada
|
|
40 @subtitle Ada Mode Version 3.7
|
25906
|
41 @sp 2
|
|
42 @page
|
|
43 @vskip 0pt plus 1filll
|
47737
|
44 @insertcopying
|
37403
|
45 @end titlepage
|
25906
|
46
|
74004
|
47 @c fixme; title page doesn't show up in ada-mode.info; why bother with
|
|
48 @c it?
|
25906
|
49
|
|
50 @node Top, Overview, (dir), (dir)
|
|
51
|
|
52 @menu
|
|
53 * Overview::
|
74004
|
54 * Installation:: Installing Ada mode on your system
|
|
55 * Customization:: Setting up Ada mode to your taste
|
|
56 * Compiling Executing:: Working with your application within Emacs
|
|
57 * Project files:: Describing the organization of your project
|
|
58 * Compiling Examples:: A small tutorial
|
|
59 * Moving Through Ada Code:: Moving easily through Ada sources
|
|
60 * Identifier completion:: Finishing words automatically
|
|
61 * Automatic Smart Indentation:: Indenting your code automatically as you type
|
|
62 * Formatting Parameter Lists:: Formatting subprograms' parameter lists
|
25906
|
63 automatically
|
74004
|
64 * Automatic Casing:: Adjusting the case of words automatically
|
|
65 * Statement Templates:: Inserting code templates
|
|
66 * Comment Handling:: Reformatting comments easily
|
77235
|
67 * GNU Free Documentation License:: The license for this documentation.
|
39367
|
68 * Index::
|
25906
|
69 @end menu
|
|
70
|
|
71
|
|
72 @node Overview, Installation, Top, Top
|
|
73 @chapter Overview
|
74004
|
74
|
|
75 The Emacs mode for programming in Ada helps the user in understanding
|
|
76 existing code and facilitates writing new code.
|
|
77
|
|
78 When the Gnu Ada compiler GNAT is used, the cross-reference
|
|
79 information output by the compiler is used to provide powerful code
|
|
80 navigation (jump to definition, find all uses, etc).
|
|
81
|
|
82 When you open a file with a file extension of @file{.ads} or
|
|
83 @file{.adb}, Emacs will automatically load and activate Ada mode.
|
25906
|
84
|
74004
|
85 Ada mode works without any customization, if you are using the GNAT
|
|
86 compiler (@url{https://libre2.adacore.com/}) and the GNAT default
|
|
87 naming convention.
|
25906
|
88
|
74004
|
89 You must customize a few things if you are using a different compiler
|
|
90 or file naming convention; @xref{Other compiler}, @xref{Non-standard
|
|
91 file names}.
|
|
92
|
|
93 In addition, you may want to customize the indentation,
|
|
94 capitalization, and other things; @xref{Other customization}.
|
25906
|
95
|
74004
|
96 Finally, for large Ada projects, you will want to set up an Emacs
|
|
97 Ada mode project file for each project; @xref{Project files}. Note
|
|
98 that these are different from the GNAT project files used by gnatmake
|
|
99 and other GNAT commands.
|
|
100
|
|
101 See the Emacs info manual, section 'Running Debuggers Under Emacs',
|
|
102 for general information on debugging.
|
|
103
|
|
104 @node Installation, Customization, Overview, Top
|
|
105 @chapter Installation
|
25906
|
106
|
74004
|
107 Ada mode is part of the standard Emacs distribution; if you use that,
|
|
108 no files need to be installed.
|
|
109
|
|
110 Ada mode is also available as a separate distribution, from the Emacs
|
|
111 Ada mode website
|
|
112 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The
|
|
113 separate distribution may be more recent.
|
|
114
|
|
115 For installing the separate distribution, see the @file{README} file
|
|
116 in the distribution.
|
|
117
|
|
118 To see what version of Ada mode you have installed, do @key{M-x
|
|
119 ada-mode-version}.
|
|
120
|
|
121 The following files are provided with the Ada mode distribution:
|
25906
|
122
|
|
123 @itemize @bullet
|
74004
|
124
|
38864
|
125 @item
|
74004
|
126 @file{ada-mode.el}: The main file for Ada mode, providing indentation,
|
|
127 formatting of parameter lists, moving through code, comment handling
|
|
128 and automatic casing.
|
|
129
|
38864
|
130 @item
|
74004
|
131 @file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs
|
|
132 widgets.
|
|
133
|
38864
|
134 @item
|
74004
|
135 @file{ada-stmt.el}: Ada statement templates.
|
|
136
|
38864
|
137 @item
|
74004
|
138 @file{ada-xref.el}: GNAT cross-references, completion of identifiers,
|
|
139 and compilation. Also provides project files (which are not
|
|
140 GNAT-specific).
|
|
141
|
25906
|
142 @end itemize
|
|
143
|
74004
|
144 @node Customization, Compiling Executing, Installation, Top
|
|
145 @chapter Customizing Ada mode
|
25906
|
146
|
74004
|
147 Here we assume you are familiar with setting variables in Emacs,
|
|
148 either thru 'customize' or in elisp (in your @file{.emacs} file). For
|
|
149 a basic introduction to customize, elisp, and Emacs in general, see
|
|
150 the tutorial in
|
42326
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
151 @iftex
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
152 @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
|
153 @end iftex
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
154 @ifhtml
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
155 @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
|
156 @end ifhtml
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
157 @ifinfo
|
939fbbfd59d8
Fix typo in cross-reference for `Using non-standard file names'
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
158 @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
|
159 @end ifinfo
|
25906
|
160
|
74004
|
161 These global Emacs settings are strongly recommended (put them in your
|
|
162 .emacs):
|
|
163
|
|
164 @example
|
|
165 (global-font-lock-mode t)
|
|
166 (transient-mark-mode t)
|
|
167 @end example
|
25906
|
168
|
74004
|
169 @samp{(global-font-lock-mode t)} turns on syntax
|
|
170 highlighting for all buffers (it is off by default because it may be
|
|
171 too slow for some machines).
|
25906
|
172
|
74004
|
173 @samp{(transient-mark-mode t)} highlights selected text.
|
25906
|
174
|
74004
|
175 See the Emacs help for each of these variables for more information.
|
25906
|
176
|
74004
|
177 @menu
|
|
178 * Non-standard file names::
|
|
179 * Other compiler::
|
|
180 * Other customization::
|
|
181 @end menu
|
|
182
|
|
183 @node Non-standard file names, Other compiler, Customization, Customization
|
|
184 @section Non-standard file names
|
25906
|
185
|
74004
|
186 By default, Ada mode is configured to use the GNAT file naming
|
|
187 convention, where file names are a simple modification of the Ada
|
|
188 names, and the extension for specs and bodies are
|
|
189 @samp{.ads} and @samp{.adb}, respectively.
|
25906
|
190
|
74004
|
191 Ada mode uses the file extentions to allow moving from a package body
|
|
192 to the corresponding spec and back.
|
|
193
|
|
194 Ada mode supports a list of alternative file extensions for specs and bodies.
|
|
195
|
|
196 For instance, if your spec and bodies files are called
|
|
197 @file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
|
|
198 can add the following to your @file{.emacs} file:
|
25906
|
199
|
74004
|
200 @example
|
|
201 (ada-add-extensions "_s.ada" "_b.ada")
|
|
202 @end example
|
25906
|
203
|
74004
|
204 You can define additional extensions:
|
25906
|
205
|
74004
|
206 @example
|
|
207 (ada-add-extensions ".ads" "_b.ada")
|
|
208 (ada-add-extensions ".ads" ".body")
|
|
209 @end example
|
25906
|
210
|
74004
|
211 This means that whenever Ada mode looks for the body for a file
|
|
212 whose extension is @file{.ads}, it will take the first available file
|
|
213 that ends with either @file{.adb}, @file{_b.ada} or
|
|
214 @file{.body}.
|
25906
|
215
|
74004
|
216 Simililarly, if Ada mode is looking for a spec, it will look for
|
|
217 @file{.ads} or @file{_s.ada}.
|
25906
|
218
|
74004
|
219 If the filename is not derived from the Ada name following the GNAT
|
|
220 convention, things are a little more complicated. You then need to
|
|
221 rewrite the function @code{ada-make-filename-from-adaname}. Doing that
|
|
222 is beyond the scope of this manual; see the current definitions in
|
|
223 @file{ada-mode.el} and @file{ada-xref.el} for examples.
|
|
224
|
|
225 @node Other compiler, Other customization, Non-standard file names, Customization
|
|
226 @section Other compiler
|
|
227
|
|
228 By default, Ada mode is configured to use the Gnu Ada compiler GNAT.
|
25906
|
229
|
74004
|
230 To use a different Ada compiler, you must specify the command lines
|
|
231 used to run that compiler, either in lisp variables or in Emacs
|
|
232 Ada mode project files. See @ref{Project file variables} for the list
|
|
233 of project variables, and the corresponding lisp variables.
|
25906
|
234
|
74004
|
235 @node Other customization, , Other compiler, Customization
|
|
236 @section Other customization
|
|
237
|
|
238 All user-settable Ada mode variables can be set via the menu
|
|
239 @samp{Ada | Customize}. Click on the @samp{Help} button there for help
|
|
240 on using customize.
|
25906
|
241
|
|
242 To modify a specific variable, you can directly call the function
|
74004
|
243 @code{customize-variable}; just type @kbd{M-x customize-variable
|
|
244 @key{RET} @var{variable-name} @key{RET}}).
|
25906
|
245
|
74004
|
246 Alternately, you can specify variable settings in the Emacs
|
|
247 configuration file, @file{.emacs}. This file is coded in Emacs lisp,
|
|
248 and the syntax to set a variable is the following:
|
25906
|
249 @example
|
|
250 (setq variable-name value)
|
|
251 @end example
|
|
252
|
74004
|
253 @node Compiling Executing, Project files, Customization, Top
|
|
254 @chapter Compiling Executing
|
|
255
|
|
256 Ada projects can be compiled, linked, and executed using commands on
|
|
257 the Ada menu. All of these commands can be customized via a project
|
|
258 file (@pxref{Project files}), but the defaults are sufficient for using
|
|
259 the GNAT compiler for simple projects (single files, or several files
|
|
260 in a single directory).
|
|
261
|
|
262 Even when no project file is used, the GUI project editor (menu
|
|
263 @key{Ada | Project | Edit}) shows the settings of the various project
|
|
264 file variables referenced here.
|
|
265
|
|
266 @menu
|
|
267 * Compile commands::
|
|
268 * Compiler errors::
|
|
269 @end menu
|
|
270
|
|
271 @node Compile commands, Compiler errors, Compiling Executing, Compiling Executing
|
|
272 @section Compile commands
|
|
273
|
|
274 Here are the commands for building and using an Ada project, as
|
|
275 listed in the Ada menu.
|
|
276
|
|
277 In multi-file projects, there must be one file that is the main
|
|
278 program. That is given by the @code{main_unit} project file variable;
|
|
279 it defaults to the current file if not yet set, but is also set by the
|
|
280 ``set main and build'' command.
|
|
281
|
|
282 @table @code
|
|
283
|
|
284 @item Check file
|
|
285 Compiles the current file in syntax check mode, by running
|
|
286 @code{check_cmd} defined in the current project file. This typically
|
|
287 runs faster than full compile mode, speeding up finding and fixing
|
|
288 compilation errors.
|
|
289
|
|
290 This sets @code{main_unit} only if it has not been set yet.
|
25906
|
291
|
74004
|
292 @item Compile file
|
|
293 Compiles the current file, by running @code{comp_cmd} from the current
|
|
294 project file.
|
|
295
|
|
296 This does not set @code{main_unit}.
|
|
297
|
|
298 @item Set main and Build
|
|
299 Sets @code{main_unit} to the current file, then executes the Build
|
|
300 command.
|
|
301
|
|
302 @item Show main
|
|
303 Display @code{main_unit} in the message buffer.
|
|
304
|
|
305 @item Build
|
|
306 Compiles all obsolete units of the current @code{main_unit}, and links
|
|
307 @code{main_unit}, by running @code{make_cmd} from the current project.
|
|
308
|
|
309 This sets @code{main_unit} only if it has not been set yet.
|
25906
|
310
|
74004
|
311 @item Run
|
|
312 Executes the main program in a shell, displayed in a separate Emacs
|
|
313 buffer. This runs @code{run_cmd} from the current project. The
|
|
314 execution buffer allows for interactive input/output.
|
|
315
|
|
316 To modify the run command, in particular to provide or change the
|
|
317 command line arguments, type @key{C-u} before invoking the command.
|
|
318
|
|
319 This command is not available for a cross-compilation toolchain.
|
25906
|
320
|
74004
|
321 @end table
|
|
322 It is important when using these commands to understand how
|
|
323 @code{main_unit} is used and changed.
|
|
324
|
|
325 Build runs 'gnatmake' on the main unit. During a typical edit/compile
|
|
326 session, this is the only command you need to invoke, which is why it
|
|
327 is bound to @key{C-c C-c}. It will compile all files needed by the
|
|
328 main unit, and display compilation errors in any of them.
|
|
329
|
|
330 Note that Build can be invoked from any Ada buffer; typically you will
|
|
331 be fixing errors in files other than the main, but you don't have to
|
|
332 switch back to the main to invoke the compiler again.
|
25906
|
333
|
74004
|
334 Novices and students typically work on single-file Ada projects. In
|
|
335 this case, @key{C-c C-m} will normally be the only command needed; it
|
|
336 will build the current file, rather than the last-built main.
|
|
337
|
|
338 There are three ways to change @code{main_unit}:
|
|
339
|
|
340 @enumerate
|
|
341 @item
|
|
342 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
|
|
343 the current file.
|
|
344
|
|
345 @item
|
|
346 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
|
|
347 @code{main}, and click @key{[save]}
|
|
348
|
|
349 @item
|
|
350 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
|
|
351
|
|
352 @end enumerate
|
25906
|
353
|
74004
|
354 @node Compiler errors, , Compile commands, Compiling Executing
|
|
355 @section Compiler errors
|
|
356
|
|
357 The @code{Check file}, @code{Compile file}, and @code{Build} commands
|
|
358 all place compilation errors in a separate buffer named
|
|
359 @code{*compilation*}.
|
|
360
|
|
361 Each line in this buffer will become active: you can simply click on
|
|
362 it with the middle button of the mouse, or move point to it and press
|
|
363 @key{RET}. Emacs will then display the relevant source file and put
|
|
364 point on the line and column where the error was found.
|
|
365
|
|
366 You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
|
|
367 will jump to the first error. If you press that key again, it will
|
|
368 move you to the second error, and so on.
|
|
369
|
|
370 Some error messages might also include references to other files. These
|
|
371 references are also clickable in the same way, or put point after the
|
|
372 line number and press @key{RET}.
|
|
373
|
|
374 @node Project files, Compiling Examples, Compiling Executing, Top
|
|
375 @chapter Project files
|
25906
|
376
|
74004
|
377 An Emacs Ada mode project file specifies what directories hold sources
|
|
378 for your project, and allows you to customize the compilation commands
|
|
379 and other things on a per-project basis.
|
|
380
|
|
381 Note that Ada mode project files @samp{*.adp} are different than GNAT
|
|
382 compiler project files @samp{*.gpr}.
|
|
383
|
|
384 @menu
|
|
385 * Project File Overview::
|
|
386 * GUI Editor::
|
|
387 * Project file variables::
|
|
388 @end menu
|
|
389
|
|
390 @node Project File Overview, GUI Editor, Project files, Project files
|
|
391 @section Project File Overview
|
25906
|
392
|
74004
|
393 Project files have a simple syntax; they may be edited directly. Each
|
|
394 line specifies a project variable name and its value, separated by ``='':
|
|
395 @example
|
|
396 src_dir=/Projects/my_project/src_1
|
|
397 src_dir=/Projects/my_project/src_2
|
|
398 @end example
|
|
399
|
|
400 Some variables (like @code{src_dir}) are lists; multiple occurances
|
|
401 are concatenated.
|
|
402
|
|
403 There must be no space between the variable name and ``='', and no
|
|
404 trailing spaces.
|
25906
|
405
|
74004
|
406 Alternately, a GUI editor for project files is available (@pxref{GUI
|
|
407 Editor}). It uses Emacs widgets, similar to Emacs customize.
|
|
408
|
|
409 The GUI editor also provides a convenient way to view current project
|
|
410 settings, if they have been modified using menu commands rather than
|
|
411 by editing the project file.
|
|
412
|
|
413 After the first Ada mode build command is invoked, there is always a
|
|
414 current project file, given by the lisp variable
|
|
415 @code{ada-prj-default-project-file}. Currently, the only way to show
|
|
416 the current project file is to invoke the GUI editor.
|
|
417
|
|
418 To find the project file the first time, Ada mode uses the following
|
|
419 search algorithm:
|
25906
|
420
|
|
421 @itemize @bullet
|
38864
|
422 @item
|
74004
|
423 If @code{ada-prj-default-project-file} is set, use that.
|
38864
|
424
|
74004
|
425 @item
|
|
426 Otherwise, search for a file in the current directory with
|
|
427 the same base name as the Ada file, but extension given by
|
|
428 @code{ada-prj-file-extension} (default @code{".adp"}).
|
25906
|
429
|
38864
|
430 @item
|
74004
|
431 If not found, search for @file{*.adp} in the current directory; if
|
|
432 several are found, prompt the user to select one.
|
38864
|
433
|
74004
|
434 @item
|
|
435 If none are found, use @file{default.adp} in the current directory (even
|
|
436 if it does not exist).
|
38864
|
437
|
25906
|
438 @end itemize
|
|
439
|
74004
|
440 This algorithm always sets @code{ada-prj-default-project-file}, even
|
|
441 when the file does not actually exist.
|
25906
|
442
|
74004
|
443 To change the project file before or after the first one is found,
|
|
444 invoke @key{Ada | Project | Load ...}.
|
|
445
|
|
446 Or, in lisp, evaluate @code{ada-set-default-project-file "/path/file.adp"}.
|
|
447 This sets @code{ada-prj-default-project-file}, and reads the project file.
|
|
448
|
|
449 @node GUI Editor, Project file variables, Project File Overview, Project files
|
|
450 @section GUI Editor
|
|
451
|
|
452 The project file editor is invoked with the menu @samp{Ada | Projects
|
|
453 | Edit}.
|
|
454
|
|
455 Once in the buffer for editing the project file, you can save your
|
|
456 modification using the @samp{[save]} button at the bottom of the
|
|
457 buffer, or the @kbd{C-x C-s} binding. To cancel your modifications,
|
|
458 kill the buffer or click on the @samp{[cancel]} button.
|
|
459
|
|
460 @node Project file variables, , GUI Editor, Project files
|
|
461 @section Project file variables
|
|
462
|
|
463 The following variables can be defined in a project file; some can
|
|
464 also be defined in lisp variables.
|
|
465
|
|
466 To set a project variable that is a list, specify each element of the
|
|
467 list on a separate line in the project file.
|
|
468
|
|
469 Any project variable can be referenced in other project variables,
|
|
470 using a shell-like notation. For instance, if the variable
|
|
471 @code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the
|
|
472 @code{comp_opt} variable will be substituted when @code{comp_cmd} is
|
|
473 used.
|
25906
|
474
|
74004
|
475 Most project variables have defaults that can be changed by setting
|
|
476 lisp variables; the table below identifies the lisp variable for each
|
|
477 project variable. Lisp variables corresponding to project variables
|
|
478 that are lists are lisp lists.
|
|
479
|
|
480 Here is the list of variables. In the default values, the current
|
|
481 directory @code{"."} is the project file directory.
|
25906
|
482
|
74004
|
483 @c defined in ada-xref-set-default-prj-values; same order here
|
|
484 @table @asis
|
|
485 @item @code{build_dir} [default: @code{"."}]
|
|
486 The compile commands will be issued in this directory.
|
|
487
|
|
488 @item @code{src_dir} [default: @code{"."}]
|
|
489 A list of directories to search for source files, both for compile
|
|
490 commands and source navigation.
|
25906
|
491
|
74004
|
492 @item @code{obj_dir} [default: @code{"."}]
|
|
493 A list of directories to search for library files. Ada mode searches
|
|
494 this list for the @samp{.ali} files generated by GNAT that contain
|
|
495 cross-reference information.
|
|
496
|
|
497 The compiler commands must place the @samp{.ali} files in one of these
|
|
498 directories; the default commands do that.
|
25906
|
499
|
74004
|
500 @item @code{casing} [default: @code{("~/.emacs_case_exceptions")}
|
|
501 List of files containing casing exceptions. See the help on
|
|
502 @code{ada-case-exception-file} for more info.
|
|
503 @c FIXME: section on case exceptions
|
25906
|
504
|
74004
|
505 Lisp variable: @code{ada-case-exception-file}.
|
|
506
|
|
507 @item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}]
|
|
508 Holds user compiler options; used in the default compile commands. The
|
|
509 default value tells gnatmake to generate library files for
|
|
510 cross-referencing even when there are errors.
|
25906
|
511
|
74004
|
512 If source code for the project is in multiple directories, the
|
|
513 appropriate compiler options must be added here. @ref{Set source
|
|
514 search path} for examples of this. Alternately, GNAT project files may
|
|
515 be used; @ref{Use GNAT project file}.
|
|
516
|
|
517 Lisp variable: @code{ada-prj-default-comp-opt}.
|
25906
|
518
|
74004
|
519 @item @code{bind_opt} [default: @code{""}]
|
|
520 Holds user binder options; used in the default build commands.
|
|
521
|
|
522 Lisp variable: @code{ada-prj-default-bind-opt}.
|
|
523
|
|
524 @item @code{link_opt} [default: @code{""}]
|
|
525 Holds user linker options; used in the default build commands.
|
|
526
|
|
527 Lisp variable: @code{ada-prj-default-link-opt}.
|
25906
|
528
|
74004
|
529 @item @code{gnatmake_opt} [default: @code{"-g"}]
|
|
530 Holds user gnatmake options; used in the default build commands.
|
|
531
|
|
532 If a GNAT project file is used (for example @file{project.gpr}), this
|
|
533 option should be set to @code{-Pproject.gpr}.
|
|
534
|
|
535 Lisp variable: @code{ada-prj-default-gnatmake-opt}.
|
25906
|
536
|
74004
|
537 @item @code{gnatfind_opt} [default: @code{"-rf"}]
|
|
538 Holds user gnatfind options; used in the default find commands.
|
|
539
|
|
540 Lisp variable: @code{ada-prj-gnatfind-switches}.
|
|
541
|
|
542 @item @code{main} [default: current file]
|
|
543 Specifies the name of the executable file for the project; used in the
|
|
544 default build commands.
|
|
545
|
|
546 @item @code{main_unit} [default: current Ada unit]
|
|
547 Specifies the name of the main Ada unit for the project; used in the
|
|
548 default build commands.
|
25906
|
549
|
74004
|
550 @item @code{cross_prefix} [default: @code{""}]
|
|
551 Name of target machine in a cross-compilation environment. Used in
|
|
552 default compile and build commands.
|
|
553
|
|
554 @item @code{remote_machine} [default: @code{""}]
|
|
555 Name of the machine to log into before issuing the compile and build
|
|
556 commands. If this variable is empty, the command will be run on the
|
|
557 local machine.
|
25906
|
558
|
74004
|
559 @item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
|
|
560 Command used to compile a single file.
|
|
561 The name of the file is substituted for @code{full_current}.
|
|
562
|
|
563 Lisp variable: @code{ada-prj-default-comp-cmd}.
|
|
564
|
|
565 @item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}]
|
|
566 Command used to syntax check a single file.
|
|
567 The name of the file is substituted for @code{full_current}.
|
25906
|
568
|
74004
|
569 Lisp variable: @code{ada-prj-default-check-cmd}
|
|
570
|
|
571 @item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
|
|
572 Command used to build the application.
|
|
573
|
|
574 Lisp variable: @code{ada-prj-default-make-cmd}.
|
|
575
|
|
576 @item @code{run_cmd} [default: @code{"./$@{main@}"}]
|
|
577 Command used to run the application.
|
25906
|
578
|
74004
|
579 @item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}]
|
|
580 Command executed before @code{debug_cmd}.
|
25906
|
581
|
74004
|
582 @item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]
|
|
583 Command used to debug the application
|
25906
|
584
|
74004
|
585 Lisp variable: @code{ada-prj-default-debugger}.
|
25906
|
586
|
74004
|
587 @item @code{debug_post_cmd} [default: @code{""}]
|
|
588 Command executed after @code{debug_cmd}.
|
25906
|
589
|
|
590 @end table
|
|
591
|
74004
|
592 @node Compiling Examples, Moving Through Ada Code, Project files, Top
|
|
593 @chapter Compiling Examples
|
|
594
|
|
595 We present several small projects, and walk thru the process of
|
|
596 compiling, linking, and running them.
|
|
597
|
|
598 The first example illustrates more Ada mode features than the others;
|
|
599 you should work thru that example before doing the others.
|
|
600
|
|
601 All of these examples assume you are using GNAT.
|
|
602
|
|
603 The source for these examples is available on the Emacs Ada mode
|
|
604 website mentioned in @xref{Installation}.
|
|
605
|
|
606 @menu
|
|
607 * No project files:: Just menus
|
|
608 * Set compiler options:: A basic Ada mode project file
|
|
609 * Set source search path:: Source in multiple directories
|
|
610 * Use GNAT project file::
|
|
611 @end menu
|
|
612
|
|
613 @node No project files, Set compiler options, Compiling Examples, Compiling Examples
|
|
614 @section No project files
|
|
615 This example uses no project files.
|
|
616
|
|
617 First, create a directory @file{Example_1}, containing:
|
|
618
|
|
619 @file{hello.adb}:
|
|
620
|
|
621 @example
|
|
622 with Ada.Text_IO;
|
|
623 procedure Hello
|
|
624 is begin
|
|
625 Put_Line("Hello from hello.adb");
|
|
626 end Hello;
|
|
627 @end example
|
25906
|
628
|
74004
|
629 Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
|
|
630 compiler error handling.
|
|
631
|
|
632 @file{hello_2.adb}:
|
|
633
|
|
634 @example
|
|
635 with Hello_Pkg;
|
|
636 procedure Hello_2
|
|
637 is begin
|
|
638 Hello_Pkg.Say_Hello;
|
|
639 end Hello_2;
|
|
640 @end example
|
|
641
|
|
642 @file{hello_pkg.ads}:
|
|
643
|
|
644 @example
|
|
645 package Hello_Pkg is
|
|
646 procedure Say_Hello;
|
|
647 end Hello_Pkg;
|
|
648 @end example
|
|
649
|
|
650 @file{hello_pkg.adb}:
|
|
651
|
|
652 @example
|
|
653 with Ada.Text_IO;
|
|
654 package Hello_Pkg is
|
|
655 procedure Say_Hello
|
|
656 is begin
|
|
657 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
|
|
658 end Say_Hello;
|
|
659 end Hello_Pkg;
|
|
660 @end example
|
|
661
|
|
662 Yes, this is missing the keyword @code{body}; another compiler error
|
|
663 example.
|
|
664
|
|
665 In buffer @file{hello.adb}, invoke @key{Ada | Check file}. You should
|
|
666 get a @code{*compilation*} buffer containing something like (the
|
|
667 directory paths will be different):
|
25906
|
668
|
74004
|
669 @example
|
|
670 cd c:/Examples/Example_1/
|
|
671 gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ
|
|
672 gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb
|
|
673 hello.adb:4:04: "Put_Line" is not visible
|
|
674 hello.adb:4:04: non-visible declaration at a-textio.ads:264
|
|
675 hello.adb:4:04: non-visible declaration at a-textio.ads:260
|
|
676 gnatmake: "c:/Examples/Example_1/hello.adb" compilation error
|
|
677 @end example
|
|
678
|
|
679 If you have enabled font-lock, the lines with actual errors (starting
|
|
680 with @file{hello.adb}) are highlighted, with the file name in red.
|
|
681
|
|
682 Now type @key{C-x `} (on a PC keyboard, @key{`} is next to @key{1}).
|
|
683 Or you can click the middle mouse button on the first error line. The
|
|
684 compilation buffer scrolls to put the first error on the top line, and
|
|
685 point is put at the place of the error in the @file{hello.adb} buffer.
|
|
686
|
|
687 To fix the error, change the line to be
|
|
688
|
|
689 @example
|
|
690 Ada.Text_IO.Put_Line ("hello from hello.adb"):
|
|
691 @end example
|
|
692
|
|
693 Now invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}.
|
|
694
|
|
695 Now (in buffer @file{hello.adb}), invoke @key{Ada | Build}. You are
|
|
696 prompted to save the file (if you haven't already). Then the
|
|
697 compilation buffer is displayed again, containing:
|
|
698
|
|
699 @example
|
|
700 cd c:/Examples/Example_1/
|
|
701 gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs
|
|
702 gcc -c -g -gnatq -gnatQ hello.adb
|
|
703 gnatbind -x hello.ali
|
|
704 gnatlink hello.ali -o hello.exe -g
|
|
705 @end example
|
|
706
|
|
707 The compilation has succeeded without errors; @file{hello.exe} now
|
|
708 exists in the same directory as @file{hello.adb}.
|
|
709
|
|
710 Now invoke @key{Ada | Run}. A @file{*run*} buffer is displayed,
|
|
711 containing
|
|
712
|
|
713 @example
|
|
714 Hello from hello.adb
|
25906
|
715
|
74004
|
716 Process run finished
|
|
717 @end example
|
|
718
|
|
719 That completes the first part of this example.
|
|
720
|
|
721 Now we will compile a multi-file project. Open the file
|
|
722 @file{hello_2.adb}, and invoke @key{Ada | Set main and Build}. This
|
|
723 finds an error in @file{hello_pkg.adb}:
|
|
724
|
|
725 @example
|
|
726 cd c:/Examples/Example_1/
|
|
727 gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs
|
|
728 gcc -c -g -gnatq -gnatQ hello_pkg.adb
|
|
729 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
|
|
730 gnatmake: "hello_pkg.adb" compilation error
|
|
731 @end example
|
|
732
|
|
733 This demonstrates that gnatmake finds the files needed by the main
|
|
734 program. However, it cannot find files in a different directory,
|
|
735 unless you use an Emacs Ada mode project file to specify the other directories;
|
|
736 @xref{Set source search path}, or a GNAT project file; @ref{Use GNAT
|
|
737 project file}.
|
25906
|
738
|
74004
|
739 Invoke @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}.
|
|
740
|
|
741 Move to the error with @key{C-x `}, and fix the error by adding @code{body}:
|
|
742
|
|
743 @example
|
|
744 package body Hello_Pkg is
|
|
745 @end example
|
|
746
|
|
747 Now, while still in @file{hello_pkg.adb}, invoke @key{Ada | Build}.
|
|
748 gnatmake successfully builds @file{hello_2}. This demonstrates that
|
|
749 Emacs has remembered the main file, in the project variable
|
|
750 @code{main_unit}, and used it for the Build command.
|
|
751
|
|
752 Finally, again while in @file{hello_pkg.adb}, invoke @key{Ada | Run}.
|
|
753 The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}.
|
|
754
|
|
755 One final point. If you switch back to buffer @file{hello.adb}, and
|
|
756 invoke @key{Ada | Run}, @file{hello_2.exe} will be run. That is
|
|
757 because @code{main_unit} is still set to @code{hello_2}, as you can
|
|
758 see when you invoke @key{Ada | Project | Edit}.
|
|
759
|
|
760 There are three ways to change @code{main_unit}:
|
|
761
|
|
762 @enumerate
|
38864
|
763 @item
|
74004
|
764 Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to
|
|
765 the current file.
|
25906
|
766
|
38864
|
767 @item
|
74004
|
768 Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and
|
|
769 @code{main}, and click @key{[save]}
|
25906
|
770
|
38864
|
771 @item
|
74004
|
772 Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit}
|
|
773
|
|
774 @end enumerate
|
|
775
|
|
776 @node Set compiler options, Set source search path, No project files, Compiling Examples
|
|
777 @section Set compiler options
|
|
778
|
|
779 This example illustrates using an Emacs Ada mode project file to set a
|
|
780 compiler option.
|
|
781
|
|
782 If you have files from @file{Example_1} open in Emacs, you should
|
|
783 close them so you don't get confused. Use menu @key{File | Close
|
|
784 (current buffer)}.
|
|
785
|
|
786 In directory @file{Example_2}, create these files:
|
|
787
|
|
788 @file{hello.adb}:
|
|
789
|
|
790 @example
|
|
791 with Ada.Text_IO;
|
|
792 procedure Hello
|
|
793 is begin
|
|
794 Put_Line("Hello from hello.adb");
|
|
795 end Hello;
|
|
796 @end example
|
25906
|
797
|
74004
|
798 This is the same as @file{hello.adb} from @file{Example_1}. It has two
|
|
799 errors; missing ``use Ada.Text_IO;'', and no space between
|
|
800 @code{Put_Line} and its argument list.
|
|
801
|
|
802 @file{hello.adp}:
|
|
803
|
|
804 @example
|
|
805 comp_opt=-gnatyt
|
|
806 @end example
|
|
807
|
|
808 This tells the GNAT compiler to check for token spacing; in
|
|
809 particular, there must be a space preceding a parenthesis.
|
25906
|
810
|
74004
|
811 In buffer @file{hello.adb}, invoke @key{Ada | Project | Load...}, and
|
|
812 select @file{Example_2/hello.adp}.
|
|
813
|
|
814 Then, again in buffer @file{hello.adb}, invoke @key{Ada | Set main and
|
|
815 Build}. You should get a @code{*compilation*} buffer containing
|
|
816 something like (the directory paths will be different):
|
|
817
|
|
818 @example
|
|
819 cd c:/Examples/Example_2/
|
|
820 gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
|
|
821 gcc -c -g -gnatyt hello.adb
|
|
822 hello.adb:4:04: "Put_Line" is not visible
|
|
823 hello.adb:4:04: non-visible declaration at a-textio.ads:264
|
|
824 hello.adb:4:04: non-visible declaration at a-textio.ads:260
|
|
825 hello.adb:4:12: (style) space required
|
|
826 gnatmake: "hello.adb" compilation error
|
|
827 @end example
|
25906
|
828
|
74004
|
829 Compare this to the compiler output in @ref{No project files}; the
|
|
830 gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by
|
|
831 @code{-cargs -gnaty}, and an additional error is reported in
|
|
832 @file{hello.adb} on line 4. This shows that @file{hello.adp} is being
|
|
833 used to set the compiler options.
|
|
834
|
|
835 Fixing the error, linking and running the code proceed as in @ref{No
|
|
836 project files}.
|
|
837
|
|
838 @node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
|
|
839 @section Set source search path
|
25906
|
840
|
74004
|
841 In this example, we show how to deal with files in more than one
|
|
842 directory. We start with the same code as in @ref{No project files}; create those
|
|
843 files (with the errors present)
|
|
844
|
|
845 Create the directory @file{Example_3}, containing:
|
|
846
|
|
847 @file{hello_pkg.ads}:
|
|
848
|
|
849 @example
|
|
850 package Hello_Pkg is
|
|
851 procedure Say_Hello;
|
|
852 end Hello_Pkg;
|
|
853 @end example
|
|
854
|
|
855 @file{hello_pkg.adb}:
|
25906
|
856
|
74004
|
857 @example
|
|
858 with Ada.Text_IO;
|
|
859 package Hello_Pkg is
|
|
860 procedure Say_Hello
|
|
861 is begin
|
|
862 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
|
|
863 end Say_Hello;
|
|
864 end Hello_Pkg;
|
|
865 @end example
|
|
866
|
|
867 These are the same files from example 1; @file{hello_pkg.adb} has an
|
|
868 error on line 2.
|
|
869
|
|
870 In addition, create a directory @file{Example_3/Other}, containing these files:
|
25906
|
871
|
74004
|
872 @file{Other/hello_3.adb}:
|
|
873
|
|
874 @example
|
|
875 with Hello_Pkg;
|
|
876 with Ada.Text_IO; use Ada.Text_IO;
|
|
877 procedure Hello_3
|
|
878 is begin
|
|
879 Hello_Pkg.Say_Hello;
|
|
880 Put_Line ("From hello_3");
|
|
881 end Hello_3;
|
|
882 @end example
|
|
883
|
|
884 There are no errors in this file.
|
|
885
|
|
886 @file{Other/other.adp}:
|
25906
|
887
|
|
888 @example
|
74004
|
889 src_dir=..
|
|
890 comp_opt=-I..
|
|
891 @end example
|
|
892
|
|
893 Note that there must be no trailing spaces.
|
|
894
|
|
895 In buffer @file{hello_3.adb}, invoke @key{Ada | Project | Load...}, and
|
|
896 select @file{Example_3/Other/other.adp}.
|
|
897
|
|
898 Then, again in @file{hello_3.adb}, invoke @key{Ada | Set main and
|
|
899 Build}. You should get a @code{*compilation*} buffer containing
|
|
900 something like (the directory paths will be different):
|
|
901
|
|
902 @example
|
|
903 cd c:/Examples/Example_3/Other/
|
|
904 gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
|
|
905 gcc -c -g -I.. hello_3.adb
|
|
906 gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
|
|
907 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
|
|
908 gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
|
|
909 @end example
|
|
910
|
|
911 Compare the @code{-cargs} option to the compiler output in @ref{Set
|
|
912 compiler options}; this shows that @file{other.adp} is being used to
|
|
913 set the compiler options.
|
|
914
|
|
915 Move to the error with @key{C-x `}. Ada mode searches the list of
|
|
916 directories given by @code{src_dir} for the file mentioned in the
|
|
917 compiler error message.
|
|
918
|
|
919 Fixing the error, linking and running the code proceed as in @ref{No
|
|
920 project files}.
|
|
921
|
|
922 @node Use GNAT project file, , Set source search path, Compiling Examples
|
|
923 @section Use GNAT project file
|
|
924
|
|
925 In this example, we show how to use a GNAT project file.
|
|
926
|
|
927 Create the directory @file{Example_4}, containing:
|
|
928
|
|
929 @file{hello_pkg.ads}:
|
|
930
|
|
931 @example
|
|
932 package Hello_Pkg is
|
|
933 procedure Say_Hello;
|
|
934 end Hello_Pkg;
|
|
935 @end example
|
|
936
|
|
937 @file{hello_pkg.adb}:
|
|
938
|
|
939 @example
|
|
940 with Ada.Text_IO;
|
|
941 package Hello_Pkg is
|
|
942 procedure Say_Hello
|
|
943 is begin
|
|
944 Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
|
|
945 end Say_Hello;
|
|
946 end Hello_Pkg;
|
25906
|
947 @end example
|
|
948
|
74004
|
949 These are the same files from example 1; @file{hello_pkg.adb} has an
|
|
950 error on line 2.
|
|
951
|
|
952 In addition, create a directory @file{Example_4/Gnat_Project},
|
|
953 containing these files:
|
|
954
|
|
955 @file{Other/hello_4.adb}:
|
|
956
|
|
957 @example
|
|
958 with Hello_Pkg;
|
|
959 with Ada.Text_IO; use Ada.Text_IO;
|
|
960 procedure Hello_4
|
|
961 is begin
|
|
962 Hello_Pkg.Say_Hello;
|
|
963 Put_Line ("From hello_4");
|
|
964 end Hello_4;
|
|
965 @end example
|
|
966
|
|
967 There are no errors in this file.
|
|
968
|
|
969 @file{Gnat_Project/hello_4.adp}:
|
|
970
|
|
971 @example
|
|
972 src_dir=..
|
|
973 gnatmake_opt=-Phello_4.gpr
|
|
974 @end example
|
|
975
|
|
976 @file{Gnat_Project/hello_4.gpr}:
|
25906
|
977
|
74004
|
978 @example
|
|
979 Project Hello_4 is
|
|
980 for Source_Dirs use (".", "..");
|
|
981 end Hello_4;
|
|
982 @end example
|
25906
|
983
|
74004
|
984 In buffer @file{hello_4.adb}, invoke @key{Ada | Project | Load...}, and
|
|
985 select @file{Example_4/Gnat_Project/hello_4.adp}.
|
|
986
|
|
987 Then, again in @file{hello_4.adb}, invoke @key{Ada | Set main and
|
|
988 Build}. You should get a @code{*compilation*} buffer containing
|
|
989 something like (the directory paths will be different):
|
|
990
|
|
991 @example
|
|
992 cd c:/Examples/Example_4/Gnat_Project/
|
|
993 gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs
|
|
994 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb
|
|
995 gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb
|
|
996 hello_pkg.adb:2:08: keyword "body" expected here [see file name]
|
|
997 gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error
|
|
998 @end example
|
|
999
|
|
1000 Compare the @code{gcc} options to the compiler output in @ref{Set
|
|
1001 compiler options}; this shows that @file{hello_4.gpr} is being used to
|
|
1002 set the compiler options.
|
|
1003
|
|
1004 Fixing the error, linking and running the code proceed as in @ref{No
|
|
1005 project files}.
|
|
1006
|
|
1007 @node Moving Through Ada Code, Identifier completion, Compiling Examples, Top
|
25906
|
1008 @chapter Moving Through Ada Code
|
|
1009 @c -----------------------------------------------------------------------
|
|
1010
|
74004
|
1011 There are several easy to use commands to navigate through Ada code. All
|
|
1012 these functions are available through the Ada menu, and you can also
|
|
1013 use the following key bindings or the command names. Some of these
|
|
1014 menu entries are available only if the GNAT compiler is used, since
|
|
1015 the implementation relies on the GNAT cross-referencing information.
|
25906
|
1016
|
|
1017 @table @kbd
|
74004
|
1018 @item M-C-e
|
39367
|
1019 @findex ada-next-procedure
|
38864
|
1020 Move to the next function/procedure/task, which ever comes next
|
|
1021 (@code{ada-next-procedure}).
|
74004
|
1022 @item M-C-a
|
39367
|
1023 @findex ada-previous-procedure
|
38864
|
1024 Move to previous function/procedure/task
|
|
1025 (@code{ada-previous-procedure}).
|
|
1026 @item M-x ada-next-package
|
39367
|
1027 @findex ada-next-package
|
25906
|
1028 Move to next package.
|
74004
|
1029 @item M-x ada-previous-package
|
|
1030 @findex ada-previous-package
|
25906
|
1031 Move to previous package.
|
38864
|
1032 @item C-c C-a
|
39367
|
1033 @findex ada-move-to-start
|
38864
|
1034 Move to matching start of @code{end} (@code{ada-move-to-start}). If
|
|
1035 point is at the end of a subprogram, this command jumps to the
|
|
1036 corresponding @code{begin} if the user option
|
74004
|
1037 @code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to
|
|
1038 the subprogram declaration.
|
38864
|
1039 @item C-c C-e
|
39367
|
1040 @findex ada-move-to-end
|
38864
|
1041 Move point to end of current block (@code{ada-move-to-end}).
|
|
1042 @item C-c o
|
|
1043 Switch between corresponding spec and body file
|
74004
|
1044 (@code{ff-find-other-file}). If point is in a subprogram, position
|
|
1045 point on the corresponding declaration or body in the other file.
|
25906
|
1046 @item C-c c-d
|
39367
|
1047 @findex ada-goto-declaration
|
74004
|
1048 Move from any reference to its declaration, for from a declaration to
|
|
1049 its body (for procedures, tasks, private and incomplete types).
|
38864
|
1050 @item C-c C-r
|
39367
|
1051 @findex ada-find-references
|
74004
|
1052 Runs the @file{gnatfind} command to search for all references to the
|
|
1053 identifier surrounding point (@code{ada-find-references}). Use
|
38864
|
1054 @kbd{C-x `} (@code{next-error}) to visit each reference (as for
|
|
1055 compilation errors).
|
25906
|
1056 @end table
|
|
1057
|
74004
|
1058 If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs
|
|
1059 will try to run GNAT for you whenever cross-reference information is
|
|
1060 needed, and is older than the current source file.
|
25906
|
1061
|
74004
|
1062 @node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top
|
25906
|
1063 @chapter Identifier completion
|
|
1064
|
74004
|
1065 Emacs and Ada mode provide two general ways for the completion of
|
|
1066 identifiers. This is an easy way to type faster: you just have to type
|
|
1067 the first few letters of an identifiers, and then loop through all the
|
25906
|
1068 possible completions.
|
|
1069
|
74004
|
1070 The first method is general for Emacs. It works by parsing all open
|
|
1071 files for possible completions.
|
25906
|
1072
|
38864
|
1073 For instance, if the words @samp{my_identifier}, @samp{my_subprogram}
|
|
1074 are the only words starting with @samp{my} in any of the opened files,
|
|
1075 then you will have this scenario:
|
|
1076
|
74004
|
1077 @example
|
25906
|
1078 You type: my@key{M-/}
|
38864
|
1079 Emacs inserts: @samp{my_identifier}
|
|
1080 If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with
|
|
1081 @samp{my_subprogram}.
|
|
1082 Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.
|
74004
|
1083 @end example
|
25906
|
1084
|
74004
|
1085 This is a very fast way to do completion, and the casing of words will
|
25906
|
1086 also be respected.
|
|
1087
|
74004
|
1088 The second method (@key{C-TAB}) is specific to Ada mode and the GNAT
|
|
1089 compiler. Emacs will search the cross-information for possible
|
|
1090 completions.
|
25906
|
1091
|
74004
|
1092 The main advantage is that this completion is more accurate: only
|
|
1093 existing identifier will be suggested.
|
25906
|
1094
|
74004
|
1095 On the other hand, this completion is a little bit slower and requires
|
|
1096 that you have compiled your file at least once since you created that
|
|
1097 identifier.
|
25906
|
1098
|
|
1099 @table @kbd
|
38864
|
1100 @item C-@key{TAB}
|
39367
|
1101 @findex ada-complete-identifier
|
74004
|
1102 Complete current identifier using cross-reference information.
|
25906
|
1103 @item M-/
|
38864
|
1104 Complete identifier using buffer information (not Ada-specific).
|
25906
|
1105 @end table
|
|
1106
|
74004
|
1107 @node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top
|
|
1108 @chapter Automatic Smart Indentation
|
25906
|
1109
|
74004
|
1110 Ada mode comes with a full set of rules for automatic indentation. You
|
|
1111 can also configure the indentation, via the following variables:
|
25906
|
1112
|
38864
|
1113 @table @asis
|
|
1114 @item @code{ada-broken-indent} (default value: 2)
|
|
1115 Number of columns to indent the continuation of a broken line.
|
25906
|
1116
|
38864
|
1117 @item @code{ada-indent} (default value: 3)
|
74004
|
1118 Number of columns for default indentation.
|
25906
|
1119
|
38864
|
1120 @item @code{ada-indent-record-rel-type} (default value: 3)
|
|
1121 Indentation for @code{record} relative to @code{type} or @code{use}.
|
25906
|
1122
|
38864
|
1123 @item @code{ada-indent-return} (default value: 0)
|
|
1124 Indentation for @code{return} relative to @code{function} (if
|
|
1125 @code{ada-indent-return} is greater than 0), or the open parenthesis
|
74004
|
1126 (if @code{ada-indent-return} is negative or 0). Note that in the second
|
38864
|
1127 case, when there is no open parenthesis, the indentation is done
|
|
1128 relative to @code{function} with the value of @code{ada-broken-indent}.
|
25906
|
1129
|
38864
|
1130 @item @code{ada-label-indent} (default value: -4)
|
|
1131 Number of columns to indent a label.
|
25906
|
1132
|
38864
|
1133 @item @code{ada-stmt-end-indent} (default value: 0)
|
|
1134 Number of columns to indent a statement @code{end} keyword on a separate line.
|
25906
|
1135
|
38864
|
1136 @item @code{ada-when-indent} (default value: 3)
|
|
1137 Indentation for @code{when} relative to @code{exception} or @code{case}.
|
25906
|
1138
|
38864
|
1139 @item @code{ada-indent-is-separate} (default value: t)
|
|
1140 Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.
|
25906
|
1141
|
38864
|
1142 @item @code{ada-indent-to-open-paren} (default value: t)
|
|
1143 Non-@code{nil} means indent according to the innermost open parenthesis.
|
25906
|
1144
|
74004
|
1145 @item @code{ada-indent-after-return} (default value: t)
|
|
1146 Non-@code{nil} means that the current line will also be re-indented
|
|
1147 before inserting a newline, when you press @key{RET}.
|
25906
|
1148 @end table
|
|
1149
|
74004
|
1150 Most of the time, the indentation will be automatic, i.e when you
|
|
1151 press @key{RET}, the cursor will move to the correct column on the
|
25906
|
1152 next line.
|
|
1153
|
74004
|
1154 You can also indent single lines, or the current region, with @key{TAB}.
|
25906
|
1155
|
38864
|
1156 Another mode of indentation exists that helps you to set up your
|
|
1157 indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do
|
|
1158 the following:
|
|
1159
|
25906
|
1160 @itemize @bullet
|
38864
|
1161 @item
|
|
1162 Reindent the current line, as @key{TAB} would do.
|
|
1163 @item
|
|
1164 Temporarily move the cursor to a reference line, i.e., the line that
|
|
1165 was used to calculate the current indentation.
|
|
1166 @item
|
74004
|
1167 Display in the message window the name of the variable that provided
|
|
1168 the offset for the indentation.
|
25906
|
1169 @end itemize
|
|
1170
|
|
1171 The exact indentation of the current line is the same as the one for the
|
|
1172 reference line, plus an offset given by the variable.
|
|
1173
|
|
1174 @table @kbd
|
38864
|
1175 @item @key{TAB}
|
|
1176 Indent the current line or the current region.
|
40705
|
1177 @item C-M-\
|
74004
|
1178 Indent lines in the current region.
|
38864
|
1179 @item C-c @key{TAB}
|
74004
|
1180 Indent the current line and display the name of the variable used for
|
25906
|
1181 indentation.
|
|
1182 @end table
|
|
1183
|
|
1184 @node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
|
|
1185 @chapter Formatting Parameter Lists
|
|
1186
|
|
1187 @table @kbd
|
38864
|
1188 @item C-c C-f
|
39367
|
1189 @findex ada-format-paramlist
|
38864
|
1190 Format the parameter list (@code{ada-format-paramlist}).
|
25906
|
1191 @end table
|
|
1192
|
74004
|
1193 This aligns the declarations on the colon (@samp{:}) separating
|
|
1194 argument names and argument types, and aligns the @code{in},
|
|
1195 @code{out} and @code{in out} keywords.
|
|
1196
|
25906
|
1197 @node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
|
|
1198 @chapter Automatic Casing
|
|
1199
|
74004
|
1200 Casing of identifiers, attributes and keywords is automatically
|
|
1201 performed while typing when the variable @code{ada-auto-case} is set.
|
|
1202 Every time you press a word separator, the previous word is
|
25906
|
1203 automatically cased.
|
|
1204
|
74004
|
1205 You can customize the automatic casing differently for keywords,
|
|
1206 attributes and identifiers. The relevant variables are the following:
|
|
1207 @code{ada-case-keyword}, @code{ada-case-attribute} and
|
25906
|
1208 @code{ada-case-identifier}.
|
|
1209
|
|
1210 All these variables can have one of the following values:
|
|
1211
|
38864
|
1212 @table @code
|
25906
|
1213 @item downcase-word
|
74004
|
1214 The word will be lowercase. For instance @code{My_vARIable} is
|
|
1215 converted to @code{my_variable}.
|
25906
|
1216
|
|
1217 @item upcase-word
|
74004
|
1218 The word will be uppercase. For instance @code{My_vARIable} is
|
|
1219 converted to @code{MY_VARIABLE}.
|
25906
|
1220
|
|
1221 @item ada-capitalize-word
|
74004
|
1222 The first letter and each letter following an underscore (@samp{_})
|
|
1223 are uppercase, others are lowercase. For instance @code{My_vARIable}
|
|
1224 is converted to @code{My_Variable}.
|
25906
|
1225
|
|
1226 @item ada-loose-case-word
|
74004
|
1227 Characters after an underscore @samp{_} character are uppercase,
|
|
1228 others are not modified. For instance @code{My_vARIable} is converted
|
|
1229 to @code{My_VARIable}.
|
25906
|
1230 @end table
|
|
1231
|
74004
|
1232 Ada mode allows you to define exceptions to these rules, in a file
|
|
1233 specified by the variable variable @code{ada-case-exception-file}
|
|
1234 (default @file{~/.emacs_case_exceptions}). Each line in this file
|
|
1235 specifies the casing of one word or word fragment. Comments may be
|
|
1236 included, separated from the word by a space.
|
25906
|
1237
|
74004
|
1238 If the word starts with an asterisk (@key{*}), it defines the casing
|
|
1239 af a word fragemnt (or ``substring''); part of a word between two
|
|
1240 underscores or word boundary.
|
25906
|
1241
|
74004
|
1242 For example:
|
25906
|
1243
|
|
1244 @example
|
|
1245 DOD Department of Defense
|
74004
|
1246 *IO
|
25906
|
1247 GNAT The GNAT compiler from Ada Core Technologies
|
|
1248 @end example
|
|
1249
|
74004
|
1250 The word fragment @code{*IO} applies to any word containing ``_io'';
|
|
1251 @code{Text_IO}, @code{Hardware_IO}, etc.
|
25906
|
1252
|
39367
|
1253 @findex ada-create-case-exception
|
74004
|
1254 There are two ways to add new items to this file: you can simply edit
|
|
1255 it as you would edit any text file. Or you can position point on the
|
|
1256 word you want to add, and select menu @samp{Ada | Edit | Create Case
|
|
1257 Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}).
|
|
1258 The word will automatically be added to the current list of exceptions
|
|
1259 and to the file.
|
25906
|
1260
|
74004
|
1261 To define a word fragment case exception, select the word fragment,
|
|
1262 then select menu @samp{Ada | Edit | Create Case Exception Substring}.
|
25906
|
1263
|
74004
|
1264 It is sometimes useful to have multiple exception files around (for
|
|
1265 instance, one could be the standard Ada acronyms, the second some
|
|
1266 company specific exceptions, and the last one some project specific
|
|
1267 exceptions). If you set up the variable @code{ada-case-exception-file}
|
|
1268 as a list of files, each of them will be parsed and used in your emacs
|
|
1269 session. However, when you save a new exception through the menu, as
|
|
1270 described above, the new exception will be added to the first file in
|
|
1271 the list.
|
38864
|
1272
|
25906
|
1273 @table @kbd
|
|
1274 @item C-c C-b
|
39367
|
1275 @findex ada-adjust-case-buffer
|
|
1276 Adjust case in the whole buffer (@code{ada-adjust-case-buffer}).
|
25906
|
1277 @item C-c C-y
|
|
1278 Create a new entry in the exception dictionary, with the word under
|
39367
|
1279 the cursor (@code{ada-create-case-exception})
|
25906
|
1280 @item C-c C-t
|
39367
|
1281 @findex ada-case-read-exceptions
|
25906
|
1282 Rereads the exception dictionary from the file
|
39367
|
1283 @code{ada-case-exception-file} (@code{ada-case-read-exceptions}).
|
25906
|
1284 @end table
|
|
1285
|
|
1286 @node Statement Templates, Comment Handling, Automatic Casing, Top
|
|
1287 @chapter Statement Templates
|
|
1288
|
74004
|
1289 Templates are defined for most Ada statements, using the Emacs
|
|
1290 ``skeleton'' package. They can be inserted in the buffer using the
|
|
1291 following commands:
|
25906
|
1292
|
|
1293 @table @kbd
|
|
1294 @item C-c t b
|
39367
|
1295 @findex ada-exception-block
|
|
1296 exception Block (@code{ada-exception-block}).
|
25906
|
1297 @item C-c t c
|
39367
|
1298 @findex ada-case
|
|
1299 case (@code{ada-case}).
|
25906
|
1300 @item C-c t d
|
39367
|
1301 @findex ada-declare-block
|
|
1302 declare Block (@code{ada-declare-block}).
|
25906
|
1303 @item C-c t e
|
39367
|
1304 @findex ada-else
|
|
1305 else (@code{ada-else}).
|
25906
|
1306 @item C-c t f
|
39367
|
1307 @findex ada-for-loop
|
|
1308 for Loop (@code{ada-for-loop}).
|
25906
|
1309 @item C-c t h
|
39367
|
1310 @findex ada-header
|
|
1311 Header (@code{ada-header}).
|
25906
|
1312 @item C-c t i
|
39367
|
1313 @findex ada-if
|
|
1314 if (@code{ada-if}).
|
25906
|
1315 @item C-c t k
|
39367
|
1316 @findex ada-package-body
|
|
1317 package Body (@code{ada-package-body}).
|
25906
|
1318 @item C-c t l
|
39367
|
1319 @findex ada-loop
|
|
1320 loop (@code{ada-loop}).
|
|
1321 @item C-c p
|
|
1322 @findex ada-subprogram-body
|
|
1323 subprogram body (@code{ada-subprogram-body}).
|
25906
|
1324 @item C-c t t
|
39367
|
1325 @findex ada-task-body
|
|
1326 task Body (@code{ada-task-body}).
|
25906
|
1327 @item C-c t w
|
39367
|
1328 @findex ada-while
|
|
1329 while Loop (@code{ada-while}).
|
25906
|
1330 @item C-c t u
|
39367
|
1331 @findex ada-use
|
|
1332 use (@code{ada-use}).
|
25906
|
1333 @item C-c t x
|
39367
|
1334 @findex ada-exit
|
|
1335 exit (@code{ada-exit}).
|
25906
|
1336 @item C-c t C-a
|
39367
|
1337 @findex ada-array
|
|
1338 array (@code{ada-array}).
|
25906
|
1339 @item C-c t C-e
|
39367
|
1340 @findex ada-elsif
|
|
1341 elsif (@code{ada-elsif}).
|
25906
|
1342 @item C-c t C-f
|
39367
|
1343 @findex ada-function-spec
|
|
1344 function Spec (@code{ada-function-spec}).
|
25906
|
1345 @item C-c t C-k
|
39367
|
1346 @findex ada-package-spec
|
|
1347 package Spec (@code{ada-package-spec}).
|
25906
|
1348 @item C-c t C-p
|
39367
|
1349 @findex ada-procedure-spec
|
|
1350 procedure Spec (@code{ada-package-spec}.
|
25906
|
1351 @item C-c t C-r
|
39367
|
1352 @findex ada-record
|
|
1353 record (@code{ada-record}).
|
25906
|
1354 @item C-c t C-s
|
39367
|
1355 @findex ada-subtype
|
|
1356 subtype (@code{ada-subtype}).
|
25906
|
1357 @item C-c t C-t
|
39367
|
1358 @findex ada-task-spec
|
|
1359 task Spec (@code{ada-task-spec}).
|
25906
|
1360 @item C-c t C-u
|
39367
|
1361 @findex ada-with
|
|
1362 with (@code{ada-with}).
|
25906
|
1363 @item C-c t C-v
|
39367
|
1364 @findex ada-private
|
|
1365 private (@code{ada-private}).
|
25906
|
1366 @item C-c t C-w
|
39367
|
1367 @findex ada-when
|
|
1368 when (@code{ada-when}).
|
25906
|
1369 @item C-c t C-x
|
39367
|
1370 @findex ada-exception
|
|
1371 exception (@code{ada-exception}).
|
25906
|
1372 @item C-c t C-y
|
39367
|
1373 @findex ada-type
|
|
1374 type (@code{ada-type}).
|
25906
|
1375 @end table
|
|
1376
|
77235
|
1377 @node Comment Handling, GNU Free Documentation License, Statement Templates, Top
|
25906
|
1378 @chapter Comment Handling
|
|
1379
|
|
1380 By default, comment lines get indented like Ada code. There are a few
|
|
1381 additional functions to handle comments:
|
|
1382
|
|
1383 @table @kbd
|
|
1384 @item M-;
|
|
1385 Start a comment in default column.
|
|
1386 @item M-j
|
|
1387 Continue comment on next line.
|
38864
|
1388 @item C-c ;
|
25906
|
1389 Comment the selected region (add -- at the beginning of lines).
|
|
1390 @item C-c :
|
|
1391 Uncomment the selected region
|
|
1392 @item M-q
|
|
1393 autofill the current comment.
|
|
1394 @end table
|
|
1395
|
77235
|
1396 @node GNU Free Documentation License, Index, Comment Handling, Top
|
|
1397 @appendix GNU Free Documentation License
|
|
1398 @include doclicense.texi
|
|
1399
|
|
1400 @node Index, , GNU Free Documentation License, Top
|
39367
|
1401 @unnumbered Index
|
|
1402
|
|
1403 @printindex fn
|
|
1404
|
25906
|
1405 @contents
|
|
1406 @bye
|
52401
|
1407
|
|
1408 @ignore
|
|
1409 arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e
|
|
1410 @end ignore
|