| 1 | \input texinfo @c -*-texinfo-*- |
| 2 | @setfilename ../info/ada-mode |
| 3 | @settitle Ada Mode |
| 4 | @dircategory Editors |
| 5 | @direntry |
| 6 | * Ada mode: (ada-mode). The GNU Emacs mode for editing Ada. |
| 7 | @end direntry |
| 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 | |
| 154 | See the section @ref{Using non-standard file names}, if your files do |
| 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 | |
| 158 | See also the Emacs documentation @ref{(emacs)}, for general usage |
| 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 |