\input texinfo @c -*-texinfo-*-@setfilename ../info/ada-mode@settitle Ada Mode@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!@comment The following lines inserts the copyright notice@comment into the Info file.@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!@copyingCopyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with theInvariant Sections being ``The GNU Manifesto'', ``Distribution'' and``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end quotation@end copying@dircategory Emacs@direntry* Ada mode: (ada-mode). Emacs mode for editing Ada code.@end direntry@titlepage@sp 10@title{Ada Mode}@sp 2@subtitle An Emacs major mode for programming Ada 95 with GNAT@subtitle July 1998 for Ada Mode Version 3.0@sp 2@page@vskip 0pt plus 1filll@insertcopying@end titlepage@node Top, Overview, (dir), (dir)@menu* Overview::* Installation:: Installing Ada mode on your system* Customization:: Setting up Ada mode to your taste* Project files:: Describing the organization of your project* Syntax highlighting:: Using specific colors and fonts to highlight the structure of your files* Moving Through Ada Code:: Moving easily through Ada sources* Identifier completion:: Finishing words automatically* Index Menu of Subprograms:: A menu of all the types and subprograms defined in your application* File Browser:: Easy access to your files* Automatic Smart Indentation:: Indenting your code automatically as you type* Formatting Parameter Lists:: Formatting subprograms' parameter lists automatically* Automatic Casing:: Adjusting the case of words automatically* Statement Templates:: Inserting code templates* Comment Handling:: Reformatting comments easily* Compiling Executing:: Working with your application within Emacs* Debugging:: Debugging your application* Using non-standard file names:: Configuring Emacs for special file names* Working Remotely:: Working on a different machine* Index::@end menu@c -----------------------------------------------------------------------@node Overview, Installation, Top, Top@chapter Overview@c -----------------------------------------------------------------------The Emacs mode for programming in Ada 95 with GNAT helps the user inunderstanding existing code and facilitates writing new code. Itfurthermore provides some utility functions for easier integration ofstandard Emacs features when programming in Ada.@section General features:@itemize @bullet@itemfull Integrated Development Environment:@itemize @bullet@itemsupport of ``project files'' for the configuration (directories,compilation options,...)@itemcompiling and stepping through error messages.@itemrunning and debugging your applications within Emacs.@end itemize@itemeasy to use for beginners by pull-down menus,@itemuser configurable by many user-option variables.@end itemize@section Ada mode features that help understanding code:@itemize @bullet@itemfunctions for easy and quick stepping through Ada code,@itemgetting cross reference information for identifiers (e.g. find thedefining place by a keystroke),@itemdisplaying an index menu of types and subprograms and move point tothe chosen one,@itemautomatic color highlighting of the various entities in Ada code.@end itemize@section Emacs support for writing Ada code:@itemize @bullet@itemswitching between spec and body files with eventuallyauto-generation of body files,@itemautomatic formatting of subprograms' parameter lists.@itemautomatic smart indentation according to Ada syntax,@itemautomatic completion of identifiers,@itemautomatic casing of identifiers, keywords, and attributes,@iteminsertion of statement templates,@itemfilling comment paragraphs like filling normal text,@end itemize@c -----------------------------------------------------------------------@node Installation, Customization, Overview, Top@chapter Installation@c -----------------------------------------------------------------------If you got Ada mode as a separate distribution, you should have alook at the @file{README} file. It explains the basic steps necessaryfor a good installation of the emacs Ada mode.Installing the Ada mode is basically just a matter of copying a fewfiles into the Emacs library directories. Every time you open a filewith a file extension of @file{.ads} or @file{.adb}, Emacs willautomatically load and activate Ada mode.@xref{Using non-standard file names}, if your files donot use these extensions and if you want Emacs to automatically start theAda mode every time you edit an Ada file.Also, for general usage variables that you might want to set,see@iftex@cite{The GNU Emacs Manual}.@end iftex@ifhtml@cite{The GNU Emacs Manual}.@end ifhtml@ifinfo@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}.@end ifinfo@c ---------------------------------------------------------------------@section Required files@c ---------------------------------------------------------------------This Ada mode works best with Emacs 20.3 or higher (the easy editingfeatures for the project files won't work with any older version), butmost of the commands should work with older versions too. Please try toinstall the most recent version of Emacs on your system beforeinstalling Ada mode.Although part of Ada mode is compiler-independent, the most advancedfeatures are specific to the Gnat compiler @url{http://www.gnat.com}.The following files are provided with the Ada mode distribution:@itemize @bullet@item@file{ada-mode.el}: The main file for Ada mode.This is the only file which does not require Gnat. It contains thefunctions for indentation, formatting of parameter lists, steppingthrough code, comment handling and automatic casing. Emacs versions20.2 and higher already contain Ada mode version 2.27, which is an olderversion of this file and should be replaced. Loading @file{ada-mode.el}from the current distribution supersedes the standard installation.@item@file{ada-stmt.el}: Contains the statement templates feature.@item@file{ada-xref.el}: This file provides the main support for Gnat.This is where the functions for cross-references, completion ofidentifiers, support for project files and compilation of yourapplication are defined.@item@file{ada-prj.el}: The functions to use for easy-edition of theproject files. This file is the only one which really requires Emacsat least 20.2. It uses the new widget features from Emacs.@end itemize@c --------------------------------------------------------------------@node Customization, Project files, Installation, Top@chapter Customizing Ada mode@c ---------------------------------------------------------------------Ada mode is fully customizable. Everything, from the file names tothe automatic indentation and the automatic casing can be adapted toyour own needs.There are two different kinds of variables that control thiscustomization, both are easy to modify.The first set of variables are standard Emacs variables. Of course, someare defined only for Ada mode, whereas others have a more generalmeaning in Emacs. Please see the Emacs documentation for moreinformation on the latest. In this documentation, we will detail all thevariables that are specific to Ada mode, and a few others. The nameswill be given, as in @code{ada-case-identifier}.Emacs provides an easy way to modify them, through a special mode calledcustomization. To access this mode, select the menu@samp{Ada->Customize}. This will open a new buffer with some fields thatyou can edit. For instance, you will get something like:@examplePut below the compiler switches.comp_opt= _____________________________________@end exampleThe first line gives a brief description of the variable. The secondline is the name of the variable and the field where you can give avalue for this variable. Simply type what you want in the field.When you are finished modifying the variables, you can simply click onthe @b{Save for future sessions} button at the top of the buffer (clickwith the middle mouse button). This will save the values in your@file{.emacs} file, so that next time you start Emacs they will have thesame values.To modify a specific variable, you can directly call the function@code{customize-variable} from Emacs (just type @kbd{M-xcustomize-variable @key{RET} @var{variable-name} @key{RET}}).Some users might prefer to modify the variables directly in theirconfiguration file, @file{.emacs}. This file is coded in Emacs lisp, andthe syntax to set a variable is the following:@example(setq variable-name value)@end exampleThe second set of variables for customization are set through the use ofproject files. These variables are specific to a given project, whereasthe first set was more general. For more information, please@xref{Project files}.@c ---------------------------------------------------------------------@node Project files, Syntax highlighting, Customization, Top@chapter Project files@c ---------------------------------------------------------------------@c ---------------------------------------------------------------------@section General overview@c ---------------------------------------------------------------------Emacs provides a full Integrated Development Environment for GNAT andAda programmers. That is to say, editing, compiling, executing anddebugging can be performed within Emacs in a convenient and natural way.To take full advantage of this features, it is possible to create a filein the main directory of your application, with a @samp{.adp} extension.This file contain all needed information dealing with the way yourapplication is organized between directories, the commands to compile,run and debug it etc. Creating this file is not mandatory and convenientdefaults are automatically provided for simple setups. It only becomesnecessary when those above mentioned defaults need customizing.A simple way to edit this file is provided for Emacs 20.2 or newer, withthe following functions, that you can access also through the Adamenu. It is also possible to edit the project file as a regular textfile.Once in the buffer for editing the project file, you can save yourmodification using the @samp{[OK]} button at the bottom of the buffer, orsimply use the usual @kbd{C-x C-s} binding. To cancel yourmodifications, simply kill the buffer or click on the @samp{[CANCEL]} buttonat the button.Each buffer using Ada mode will be associated with one project file whenthere is one available, so that Emacs can easily navigate throughrelated source files for instance.The exact algorithm to determine which project file should be used isdescribed in the next section, but you can force the project file youwant to use by setting one or two variables in your @file{.emacs} file.@itemize @bullet@itemTo set up a default project file to use for any directory, anywhereon your system, set the variable @code{ada-prj-default-project-file} tothe name of that file.@example(set 'ada-prj-default-project-file "/dir1/dir2/file")@end example@itemFor finer control, you can set a per-directory project file.This is done through the variable @code{ada-xref-default-prj-file}.@example (set 'ada-xref-default-prj-file '(("/dir1/dir2" . "/dir3/file1") ("/dir4/dir5" . "/dir6/file2")))@end exampleNote: This has a higher priority than the first variable, so the firstchoice is to use this variable settings, and otherwise@code{ada-prj-default-project-file}.@end itemize@table @kbd@item C-c u@findex ada-customizeCreate or edit the project file for the current buffer (@code{ada-customize}).@item C-c c@findex ada-change-prjChange the project file associated with the current Ada buffer (@code{ada-change-prj}).@item C-c d@findex ada-change-default-projectChange the default project file for the current directory(@code{ada-change-default-project}). Every new file opened from thisdirectory will be associated with that file by default.@item ada-set-default-project-file@findex ada-set-default-project-fileSet the default project file to use for *any* Ada file opened anywhereon your system. This sets this file only for the current Emacs session.@end table@c ---------------------------------------------------------------------@section Project file variables@c ---------------------------------------------------------------------The following variables can be defined in a project file. They all havea default value, so that small projects do not need to create a projectfile.Some variables below can be referenced in other variables, using ashell-like notation. For instance, if the variable @code{comp_cmd}contains a sequence like @code{$@{comp_opt@}}, the value of that variablewill be substituted.Here is the list of variables:@table @asis@item @code{src_dir} [default: @code{"./"}]This is a list of directories where Ada mode will look for sourcefiles. These directories are used mainly in two cases, both as a switchfor the compiler and for the cross-references.@item @code{obj_dir} [default: @code{"./"}]This is a list of directories where to look for object and libraryfiles. The library files are the @samp{.ali} files generated by Gnatand that contain cross-reference informations.@item @code{comp_opt} [default: @code{""}]Creates a variable which can be referred to subsequently by using the@code{$@{comp_opt@}} notation. This is intended to store the defaultswitches given to @command{gnatmake} and @command{gcc}.@item @code{bind_opt=@var{switches}} [default: @code{""}]Creates a variable which can be referred to subsequently by using the@code{$@{bind_opt@}} notation. This is intended to store the defaultswitches given to @command{gnatbind}.@item @code{link_opt=@var{switches}} [default: @code{""}]Creates a variable which can be referred to subsequently by using the@code{$@{link_opt@}} notation. This is intended to store the defaultswitches given to @command{gnatlink}.@item @code{main=@var{executable}} [default: @code{""}]Specifies the name of the executable for the application. This variablecan be referred to in the following lines by using the @code{$@{main@}}notation.@item @code{cross_prefix=@var{prefix}} [default: @code{""}]This variable should be set if you are working in a cross-compilationenvironment. This is the prefix used in front of the gnatmake commands.@item @code{remote_machine=@var{machine}} [default: @code{""}]This is the name of the machine to log into before issuing thecompilation command. If this variable is empty, the command will berun on the local machine. This will not work on Windows NT machines,since Ada mode will simply precede the compilation command with a@command{rsh} command, unknown on Windows.@item @code{comp_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"}]Specifies the command used to compile a single file in the application.The name of the file will be added at the end of this command.@item @code{make_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gnatmake $@{main@} -aI$@{src_dir@} -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"]}'Specifies the command used to recompile the whole application.@item @code{run_cmd=@var{command}} [default: @code{"$@{main@}"}]Specifies the command used to run the application.@item @code{debug_cmd=@var{command}} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}]Specifies the command used to debug the application@end table@c ---------------------------------------------------------------------@section Detailed algorithm@c ---------------------------------------------------------------------This section gives more details on the project file setup and is only ofinterest for advanced users.Usually, an Ada file is part of a larger application, whose sources andobjects can be spread over multiple directories. The first time emacs isasked to compile, run or debug an application, or when a cross referencefunction is used (goto declaration for instance), the following stepsare taken:@itemize @bullet@itemfind the appropriate project file, open and parse it.All the fields read in the project file are then stored by emacslocally. Finding the project file requires a few steps:@itemize @minus@itemif a file from the same directory was already associated witha project file, use the same one. This is the variable@code{ada-xref-default-prj-file} described above.@itemif the variable @code{ada-prj-default-project-file} is set,use the project file specified in this variable.@itemif there is a project file whose name is the same as the source fileexcept for the suffix, use this one.@itemif there's only one project file in the source directory, usethat one.@itemif there are more than one project file in the source directory,ask the user.@itemif there are no project files in the source directory use standarddefault values.@end itemizeThe first project file that is selected in a given directory becomes thedefault project file for this directory and is used implicitly for othersources unless specified otherwise by the user.@itemlook for the corresponding @samp{.ali} file in the @code{obj_dir} definedin the project file. If this file can not be found, emacs proposes tocompile the source using the @code{comp_cmd} defined in the project filein order to create the ali file.@itemwhen cross referencing is requested, the @samp{.ali} file is parsed todetermine the file and line of the identifier definition. It ispossible for the @samp{.ali} file to be older than the source file,in which case it will be recompiled if the variable@code{ada-xref-create-ali} is set, otherwise the reference is searchedin the obsolete ali file with possible inaccurate results.@itemlook for the file containing the declaration using the sourcepath @code{src_dir} defined in the project file. Put the cursor at thecorrect position and display this new cursor.@end itemize@c -----------------------------------------------------------------------@node Syntax highlighting, Moving Through Ada Code, Project files, Top@chapter Syntax highlighting@c -----------------------------------------------------------------------Ada mode is made to help you understand the structure of your sourcefiles. Some people like having colors or different fonts depending onthe context: commands should be displayed differently than keywords,which should also be different from strings, @dots{}Emacs is able to display in a different way the following syntacticentities:@itemize @bullet@item keywords@item commands@item strings@item gnatprep statements (preprocessor)@item types (under certain conditions)@item other words@end itemizeThis is not the default behavior for Emacs. You have to explicitlyactivate it. This requires that you add a new line in your @file{.emacs}file (if this file does not exist, just create it).@example(global-font-lock-mode t)@end exampleBut the default colors might not be the ones you like. Fortunately,there is a very easy way to change them. Just select the menu@samp{Help->Customize->Specific Face...} and press @key{RET}. Thiswill display a buffer will all the ``faces'' (the colors) that Emacs knowsabout. You can change any of them.@c -----------------------------------------------------------------------@node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top@chapter Moving Through Ada Code@c -----------------------------------------------------------------------There are several easy to use commands to stroll through Ada code. Allthese functions are available through the Ada menu, and you can also usethe following key bindings or the command names:@table @kbd@item C-M-e@findex ada-next-procedureMove to the next function/procedure/task, which ever comes next(@code{ada-next-procedure}).@item C-M-a@findex ada-previous-procedureMove to previous function/procedure/task(@code{ada-previous-procedure}).@item M-x ada-next-package@findex ada-next-packageMove to next package.@item M-x ada-prev-package@findex ada-prev-packageMove to previous package.@item C-c C-a@findex ada-move-to-startMove to matching start of @code{end} (@code{ada-move-to-start}). Ifpoint is at the end of a subprogram, this command jumps to thecorresponding @code{begin} if the user option@code{ada-move-to-declaration} is @code{nil} (default), it jumps tothe subprogram declaration otherwise.@item C-c C-e@findex ada-move-to-endMove point to end of current block (@code{ada-move-to-end}).@item C-c oSwitch between corresponding spec and body file(@code{ff-find-other-file}). If the cursor is on a subprogram, switchbetween declaration and body.@item C-c c-d@findex ada-goto-declarationMove from any reference to its declaration and switch betweendeclaration and body (for procedures, tasks, private and incompletetypes).@item C-c C-r@findex ada-find-referencesruns the @file{gnatfind} command to search for all references to theentity pointed by the cursor (@code{ada-find-references}). Use@kbd{C-x `} (@code{next-error}) to visit each reference (as forcompilation errors).@end tableThese functions use the information in the output of the Gnat Adacompiler. However, if your application was compiled with the@samp{-gnatx} switch, these functions will not work, since no extrainformation is generated by GNAT. See GNAT documentation for furtherinformation.Emacs will try to run Gnat for you whenever the cross-referenceinformations are older than your source file (provided the@code{ada-xref-create-ali} variable is non-@code{nil}). Gnat then produces afile with the same name as the current Ada file but with the extensionchanged to @file{.ali}. This files are normally used by the binder, butthey will also contain additional cross-referencing information.@c -----------------------------------------------------------------------@node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top@chapter Identifier completion@c -----------------------------------------------------------------------@c -----------------------------------------------------------------------@section Overview@c -----------------------------------------------------------------------Emacs and Ada mode provide two general ways for the completion ofidentifiers. This is an easy way to type faster: you just have to typethe first few letters of an identifiers, and then loop through all thepossible completions.The first method is general for Emacs. It will work both with Adabuffers, but also in C buffers, Java buffers, @enddots{} The idea is to parseall the opened buffers for possible completions.For instance, if the words @samp{my_identifier}, @samp{my_subprogram}are the only words starting with @samp{my} in any of the opened files,then you will have this scenario:@quotationYou type: my@key{M-/}Emacs inserts: @samp{my_identifier}If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with@samp{my_subprogram}.Pressing @key{M-/} once more will bring you back to @samp{my_identifier}.@end quotationThis is a very fast way to do completion, and the casing of words willalso be respected.The second method is specific to Ada buffer, and even to users of theGnat compiler. Emacs will search the cross-information found in the@samp{.ali} files generated by Gnat for possible completions.The main advantage is that this completion is more accurate: onlyexisting identifier will be suggested, you don't need to have a fileopened that already contains this identifiers, @enddots{}On the other hand, this completion is a little bit slower and requiresthat you have compiled your file at least once since you created thatidentifier.@c -----------------------------------------------------------------------@section Summary of commands@c -----------------------------------------------------------------------@table @kbd@item C-@key{TAB}@findex ada-complete-identifierComplete accurately current identifier using information in @samp{.ali} file(@code{ada-complete-identifier}).@item M-/Complete identifier using buffer information (not Ada-specific).@end table@c -----------------------------------------------------------------------@node Index Menu of Subprograms, File Browser, Identifier completion, Top@chapter Index Menu of Subprograms@c -----------------------------------------------------------------------You can display a choice menu with all procedure/function/taskdeclarations in the file and choose an item by mouse click to get to itsdeclaration. This function is accessible through the @samp{Ada} menu whenediting a Ada file, or simply through the following key binding:@table @kbd@item C-S-Mouse-3display index menu@end table@c -----------------------------------------------------------------------@node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top@chapter File Browser@c -----------------------------------------------------------------------Emacs provides a special mode, called @code{speedbar}. When this mode isactivated, a new frame is displayed, with a file browser. The files fromthe current directory are displayed, and you can click on them as youwould with any file browser. The following commands are then available.You can click on a directory name or file name to open it. The editorwill automatically select the best possible mode for this file,including of course Ada mode for files written in Ada.If you click on the @samp{[+]} symbol near a file name, all the symbols (types,variables and subprograms) defined in that file will be displayed, andyou can directly click on them to open the right file at the rightplace.You can activate this mode by typing @key{M-x speedbar} in the editor.This will open a new frame. A better way might be to associate thefollowing key binding@example(global-set-key [f7] 'speedbar-get-focus)@end exampleEvery time you press @key{F7}, the mouse will automatically move to thespeedbar frame (which will be created if it does not exist).@c -----------------------------------------------------------------------@node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top@chapter Automatic Smart Indentation@c -----------------------------------------------------------------------Ada mode comes with a full set of rules for automatic indentation.You can of course configure the indentation as you want, by setting thevalue of a few variables.As always, the preferred way to modify variables is to use the@samp{Ada->Customize} menu (don't forget to save your changes!). Thiswill also show you some example of code where this variable is used, andhopefully make things clearer.The relevant variables are the following:@table @asis@item @code{ada-broken-indent} (default value: 2)Number of columns to indent the continuation of a broken line.@item @code{ada-indent} (default value: 3)Width of the default indentation.@item @code{ada-indent-record-rel-type} (default value: 3)Indentation for @code{record} relative to @code{type} or @code{use}.@item @code{ada-indent-return} (default value: 0)Indentation for @code{return} relative to @code{function} (if@code{ada-indent-return} is greater than 0), or the open parenthesis(if @code{ada-indent-return} is negative or null). Note that in the secondcase, when there is no open parenthesis, the indentation is donerelative to @code{function} with the value of @code{ada-broken-indent}.@item @code{ada-label-indent} (default value: -4)Number of columns to indent a label.@item @code{ada-stmt-end-indent} (default value: 0)Number of columns to indent a statement @code{end} keyword on a separate line.@item @code{ada-when-indent} (default value: 3)Indentation for @code{when} relative to @code{exception} or @code{case}.@item @code{ada-indent-is-separate} (default value: t)Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line.@item @code{ada-indent-to-open-paren} (default value: t)Non-@code{nil} means indent according to the innermost open parenthesis.@item @code{ada-indent-after-return} (default value: t)Non-@code{nil} means that the current line will also be re-indented beforeinserting a newline, when you press @key{RET}.@end tableMost of the time, the indentation will be automatic, i.e when you willpress @key{RET}, the cursor will move to the correct column on thenext line.However, you might want or need sometimes to re-indent the current lineor a set of lines. For this, you can simply go to that line, or selectthe lines, and then press @key{TAB}. This will automatically re-indentthe lines.Another mode of indentation exists that helps you to set up yourindentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will dothe following:@itemize @bullet@itemReindent the current line, as @key{TAB} would do.@itemTemporarily move the cursor to a reference line, i.e., the line thatwas used to calculate the current indentation.@itemDisplay at the bottom of the window the name of the variable thatprovided the offset for the indentation.@end itemizeThe exact indentation of the current line is the same as the one for thereference line, plus an offset given by the variable.Once you know the name of the variable, you can either modify itthrough the usual @samp{Ada->Customize} menu, or by typing @kbd{M-xcustomize-variable @key{RET}} in the Emacs window, and then give thename of the variable.@table @kbd@item @key{TAB}Indent the current line or the current region.@item C-M-\Indent lines in the current selected block.@item C-c @key{TAB}Indent the current line and prints the name of the variable used forindentation.@end table@c -----------------------------------------------------------------------@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top@chapter Formatting Parameter Lists@c -----------------------------------------------------------------------To help you correctly align fields in a subprogram parameter list,Emacs provides one function that will do most of the work for you.This function will align the declarations on the colon (@samp{:})separating argument names and argument types, plus align the@code{in}, @code{out} and @code{in out} keywords if required.@table @kbd@item C-c C-f@findex ada-format-paramlistFormat the parameter list (@code{ada-format-paramlist}).@end table@c -----------------------------------------------------------------------@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top@chapter Automatic Casing@c -----------------------------------------------------------------------Casing of identifiers, attributes and keywords is automaticallyperformed while typing when the variable @code{ada-auto-case} is set.Every time you press a word separator, the previous word isautomatically cased.You can customize the automatic casing differently for keywords,attributes and identifiers. The relevant variables are the following:@code{ada-case-keyword}, @code{ada-case-attribute} and@code{ada-case-identifier}.All these variables can have one of the following values:@table @code@item downcase-wordThe previous word will simply be in all lower cases. For instance@code{My_vARIable} is converted to @code{my_variable}.@item upcase-wordThe previous word will be fully converted to upper cases. For instance@code{My_vARIable} is converted to @code{MY_VARIABLE}.@item ada-capitalize-wordAll letters, except the first one of the word and every letter after the@samp{_} character are lower cased. Other letters are upper cased. Forinstance @code{My_vARIable} is converted to @code{My_Variable}.@item ada-loose-case-wordNo letters is modified in the previous word, except the ones after the@samp{_} character that are upper cased. For instance @code{My_vARIable} isconverted to @code{My_VARIable}.@end tableThese functions, although they will work in most cases, will not beaccurate sometimes. The Ada mode allows you to define some exceptions,that will always be cased the same way.The idea is to create a dictionary of exceptions, and store it in afile. This file should contain one identifier per line, with the casingyou want to force. The default name for this file is@file{~/.emacs_case_exceptions}. You can of course change this name,through the variable @code{ada-case-exception-file}.Note that each line in this file must start with the key word whosecasing you want to specify. The rest of the line can be used forcomments (explaining for instance what an abbreviation means, asrecommended in the Ada 95 Quality and Style, paragraph 3.1.4). Thus, agood example for this file could be:@exampleDOD Department of DefenseText_IOGNAT The GNAT compiler from Ada Core Technologies@end exampleWhen working on project involving multiple programmers, we recommendthat every member of the team sets this variable to the same value,which should point to a system-wide file that each of them canwrite. That way, you will ensure that the casing is consistentthroughout your application(s).@findex ada-create-case-exceptionThere are two ways to add new items to this file: you can simply edit itas you would edit any text file, and add or suppress entries in thisfile. Remember that you should put one entity per line. The other,easier way, is to position the cursor over the word you want to add, inan Ada buffer. This word should have the casing you want. Then simplyselect the menu @samp{Ada->Edit->Create Case Exception}, or the key@kbd{C-c C-y} (@code{ada-create-case-exception}). The word willautomatically be added to the current list of exceptions and to the file.It is sometimes useful to have multiple exception files around (forinstance, one could be the standard Ada acronyms, the second somecompany specific exceptions, and the last one some project specificexceptions). If you set up the variable @code{ada-case-exception-file}as a list of files, each of them will be parsed and used in your emacssession.However, when you save a new exception through the menu, as describedabove, the new exception will be added to the first file in the listonly. You can not automatically add an exception to one of the otherfiles, although you can of course edit the files by hand at any time.Automatic casing can be performed on port or whole buffer using:@table @kbd@item C-c C-b@findex ada-adjust-case-bufferAdjust case in the whole buffer (@code{ada-adjust-case-buffer}).@item C-c C-yCreate a new entry in the exception dictionary, with the word underthe cursor (@code{ada-create-case-exception})@item C-c C-t@findex ada-case-read-exceptionsRereads the exception dictionary from the file@code{ada-case-exception-file} (@code{ada-case-read-exceptions}).@end table@c -----------------------------------------------------------------------@node Statement Templates, Comment Handling, Automatic Casing, Top@chapter Statement Templates@c -----------------------------------------------------------------------NOTE: This features are not available on VMS for Emacs 19.28. Thefunctions used here do not exist on Emacs 19.28.Templates exist for most Ada statements. They can be inserted in thebuffer using the following commands:@table @kbd@item C-c t b@findex ada-exception-blockexception Block (@code{ada-exception-block}).@item C-c t c@findex ada-casecase (@code{ada-case}).@item C-c t d@findex ada-declare-blockdeclare Block (@code{ada-declare-block}).@item C-c t e@findex ada-elseelse (@code{ada-else}).@item C-c t f@findex ada-for-loopfor Loop (@code{ada-for-loop}).@item C-c t h@findex ada-headerHeader (@code{ada-header}).@item C-c t i@findex ada-ifif (@code{ada-if}).@item C-c t k@findex ada-package-bodypackage Body (@code{ada-package-body}).@item C-c t l@findex ada-looploop (@code{ada-loop}).@item C-c p@findex ada-subprogram-bodysubprogram body (@code{ada-subprogram-body}).@item C-c t t@findex ada-task-bodytask Body (@code{ada-task-body}).@item C-c t w@findex ada-whilewhile Loop (@code{ada-while}).@item C-c t u@findex ada-useuse (@code{ada-use}).@item C-c t x@findex ada-exitexit (@code{ada-exit}).@item C-c t C-a@findex ada-arrayarray (@code{ada-array}).@item C-c t C-e@findex ada-elsifelsif (@code{ada-elsif}).@item C-c t C-f@findex ada-function-specfunction Spec (@code{ada-function-spec}).@item C-c t C-k@findex ada-package-specpackage Spec (@code{ada-package-spec}).@item C-c t C-p@findex ada-procedure-specprocedure Spec (@code{ada-package-spec}.@item C-c t C-r@findex ada-recordrecord (@code{ada-record}).@item C-c t C-s@findex ada-subtypesubtype (@code{ada-subtype}).@item C-c t C-t@findex ada-task-spectask Spec (@code{ada-task-spec}).@item C-c t C-u@findex ada-withwith (@code{ada-with}).@item C-c t C-v@findex ada-privateprivate (@code{ada-private}).@item C-c t C-w@findex ada-whenwhen (@code{ada-when}).@item C-c t C-x@findex ada-exceptionexception (@code{ada-exception}).@item C-c t C-y@findex ada-typetype (@code{ada-type}).@end table@c -----------------------------------------------------------------------@node Comment Handling, Compiling Executing, Statement Templates, Top@chapter Comment Handling@c -----------------------------------------------------------------------By default, comment lines get indented like Ada code. There are a fewadditional functions to handle comments:@table @kbd@item M-;Start a comment in default column.@item M-jContinue comment on next line.@item C-c ;Comment the selected region (add -- at the beginning of lines).@item C-c :Uncomment the selected region@item M-qautofill the current comment.@end table@c -----------------------------------------------------------------------@node Compiling Executing, Debugging, Comment Handling, Top@chapter Compiling Executing@c -----------------------------------------------------------------------Ada mode provides a much complete environment for compiling, debuggingand running an application within Emacs.All the commands used by Emacs to manipulate your application can becustomized in the project file. Some default values are provided, butthese will likely not be good enough for a big or even medium-sizedproject. See the section on the project file for an explanation on howto set up the commands to use.One of the variables you can set in your project file,@code{cross_prefix}, indicates whether you are using a cross-compilationenvironment, and if yes for which target. The default command used forcompilation will add this @code{cross_prefix} in front of the name:@code{gcc} will become @code{cross_prefix}-@code{gcc}, @code{gnatmake}will become @code{cross_prefix}-@code{gnatmake}, @enddots{}This will also modify the way your application is run and debugged,although this is not implemented at the moment.Here are the commands for building and using an Ada application@itemize @bullet@item Compiling the current sourceThis command is issued when issuing the @code{compile} command from theAda menu. It compiles unconditionally the current source using the@code{comp_cmd} variable of the project file. Compilation options can becustomized with the variable @code{comp_opt} of the project file.Emacs will display a new buffer that contains the result of thecompilation. Each line associated with an error will become active: youcan simply click on it with the middle button of the mouse, or move thecursor on it and press @key{RET}. Emacs will then display therelevant source file and put the cursor on the line and column the errorwas found at.You can also simply press the @kbd{C-x `} key and Emacs will jump to thefirst error. If you press that key again, it will move you to the seconderror, and so on.Some error messages might also include references to some files. Thesereferences are also clickable in the same way.@item (Re)building the whole applicationThis command is issued when you select the @code{build} command from theAda menu. It compiles all obsolete units of the current applicationusing the @code{make_cmd} variable of the project file. Compilationoptions can be customized with the variable @code{comp_opt} of theproject file, binder options with @code{bind_opt} and linker optionswith @code{link_opt}. The main unit of the application may be specifiedwith @code{main}.The compilation buffer is also active in the same way it was for the abovecommand.@item Running the applicationThis command is issued when you select the @code{run} command from theAda menu. It executes the current application in an emacsbuffer. Arguments can be passed through before executing. The executionbuffer allows for interactive input/output.This command is not yet available in a cross-compilationtoolchain. Emacs would first need to log on the target before runningthe application. This will be implemented in a future release of Gnat.@end itemize@c ---------------------------------------------------------------------@node Debugging, Using non-standard file names, Compiling Executing, Top@chapter Debugging your application@c ---------------------------------------------------------------------You can set up in the project file a command to use to debug yourapplication. Emacs is compatible with a lot of debuggers, and provide aneasy interface to them.This selection will focus on the gdb debugger, and two of the graphicalinterfaces that exist for it.In all cases, the main window in Emacs will be split in two: in theupper buffer, the source code will appear, whereas the debuggerinput/output window is displayed at the bottom. You can enter thedebugger commands as usual in the command window. Every time a newsource file is selected by the debugger (for instance as a result of a@code{frame} command), the appropriate source file is displayed in theupper buffer.The source window is interactive: you can click on an identifier with theright mouse button, and print its value in the debugger window. You canalso set a breakpoint simply by right-clicking on a line.You can easily use Emacs as the source window when you are using agraphical interface for the debugger. The interesting thing is that,whereas you still have the graphical nifties, you can also you thecross-references features that Ada mode provides to look at thedefinition for the identifiers, @enddots{}Here is how you can set up gdbtk and ddd for use with Emacs (These arethe commands you should setup in the project file):@itemize @bullet@item gdbtkshould be used with the switch @samp{--emacs_gdbtk}. It provides a nicebacktrace window, as well as a tasks window. You can click interactivelyon both of them, and Emacs will display the source file on the correctline.@item ddd (Data Display Debugger)should be used with the switches @samp{--tty} and@samp{--fullname}. Whenever you print a variable from Emacs, it willbe displayed graphically in the data window.@end itemize@c ---------------------------------------------------------------------@node Using non-standard file names, Working Remotely, Debugging, Top@chapter Using non-standard file names@c ---------------------------------------------------------------------By default, Emacs is configured to use the GNAT style file names, wherefile names are the package names, and the extension for spec and bodiesare respectively @samp{.ads} and @samp{.adb}.If you want to use other types of file names, you will need to modifyyour @file{.emacs} file.Adding new possible extensions is easy. Since Ada mode needs to knowhow to go from the body to the spec (and back), you always have tospecify both. A function is provided with Ada mode to add newextensions.For instance, if your spec and bodies files are called@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, youneed to add the following to your @file{.emacs} file:@example(ada-add-extensions "_s.ada" "_b.ada")@end exampleNote that it is possible to redefine the extension, even if they alreadyexist, as in:@example(ada-add-extensions ".ads" "_b.ada")(ada-add-extensions ".ads" ".body")@end exampleThis simply means that whenever the ada-mode will look for the body fora file whose extension is @file{.ads}, it will take the first availablefile that ends with either @file{.adb} (standard), @file{_b.ada} or@file{.body}.If the filename is not the unit name, then things are a little morecomplicated. You then need to rewrite the function@code{ada-make-filename-from-adaname} (see the file @file{ada-mode.el}for an example).@c ---------------------------------------------------------------------@node Working Remotely, Index, Using non-standard file names, Top@chapter Working Remotely@c ---------------------------------------------------------------------When you work on project that involve a lot of programmers, it isgenerally the case that you will edit the files on your own machine, butyou want to compile, run and debug your application in another buffer.Fortunately, here too Emacs provides a very convenient way to do this.@c ---------------------------------------------------------------------@section Remote editing@c ---------------------------------------------------------------------First of all, the files do not need to be on your machine. Emacs canedit any remote file, by doing transparent FTP sessions between yourmachine and the remote machine that stores your files. This is a specialEmacs mode, called @code{ange-ftp}. To use it, you just have to use aslightly different syntax when you open a file.For instance, if you want to open the file @file{/work/foo.adb} on the machinealeph.gnu.org, where you log in as qwe, you would simply do this:@exampleC-x C-f /qwe@@aleph.gnu.org:/work/foo.adb @key{RET}@end example@noindenti.e., use your name, the name of the machine and the name of the file.The first time, Emacs will ask you for a password that it will rememberuntil you close the current Emacs. Even if the ftp session times out,you won't need to reenter your password.Every time you save the file, Emacs will upload it to the remote machinetransparently. No file is modified on the local machine.@c ---------------------------------------------------------------------@section Remote compiling@c ---------------------------------------------------------------------If the machine you want to compile on is not the one your Emacs isrunning on, you can set the variable @code{remote_machine} in theproject file for your application.This will force Emacs to issue a @command{rsh} command for the compilation,instead of running it on the local machine. Unfortunately, this won'twork on Windows workstations, since this protocol is not supported.@exampleIf your @code{remote_machine} is aleph.gnu.org and the standardcompilation command is @code{cd /work/ && gnatmake foo}, then Emacs willactually issue the command @code{rsh aleph.gnu.org 'cd /work/ &&gnatmake foo'}.@end exampleThe advantage of using the @code{remote_machine} variable is that it iseasier to change that machine without having to modify the compilationcommand.Note that if you need to set up some environment variables before thecompilation, you need to insert a call to the appropriate initializationscript in the compilation command, for instance:@examplebuild_cmd= initialization_script; cd /work/ && gnatmake foo@end example@c ---------------------------------------------------------------------@section Remote running and debugging@c ---------------------------------------------------------------------This feature is not completely implemented yet.However, most of the time, you will be able to run your applicationremotely simply by replacing it with a @command{rsh} call.For instance, if your command was @code{$@{main@}}, you could replace it with@code{rsh aleph.gnu.org $@{main@}}.However, this would not work on vxworks, for instance, where@command{rsh} is not supported.@node Index, , Working Remotely, Top@unnumbered Index@printindex fn@contents@bye