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