Mercurial > emacs
diff man/ada-mode.texi @ 25906:3a06267f733d
New file.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Thu, 07 Oct 1999 14:46:58 +0000 |
parents | |
children | 2552233fdd74 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/ada-mode.texi Thu Oct 07 14:46:58 1999 +0000 @@ -0,0 +1,1183 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ada-mode.info +@settitle Ada Mode + +@ifinfo +This file documents Ada mode. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under same conditions as for modified versions. +@end ifinfo + +@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 + +@comment This is for the copyright page. +@page +@vskip 0pt plus 1filll + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the same conditions as for modified versions. + +@end titlepage + +@node Top, Overview, (dir), (dir) + +@menu +* Overview:: +* Installation:: Installing the Ada mode on your system +* Customization:: Setting up the 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:: Formating 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 +@end menu + + +@c ----------------------------------------------------------------------- +@node Overview, Installation, Top, Top +@chapter Overview +@c ----------------------------------------------------------------------- + +The Emacs mode for programming in Ada 95 with GNAT helps the user in +understanding existing code and facilitates writing new code. It +furthermore provides some utility functions for easier integration of +standard Emacs features when programming in Ada. + +@section General features: + +@itemize @bullet +@item full Integrated Development Environment : +@itemize @bullet +@item support of 'project files' for the configuration (directories, +compilation options,...) +@item compiling and stepping through error messages. +@item running and debugging your applications within Emacs. +@end itemize +@item easy to use for beginners by pull-down menus, +@item user configurable by many user-option variables. +@end itemize + +@section Ada mode features that help understanding code: + +@itemize @bullet +@item functions for easy and quick stepping through Ada code, +@item getting cross reference information for identifiers (e.g. find the +defining place by a keystroke), +@item displaying an index menu of types and subprograms and move point to +the chosen one, +@item automatic color highlighting of the various entities in Ada code. +@end itemize + +@section Emacs support for writing Ada code: + +@itemize @bullet +@item switching between spec and body files with eventually +auto-generation of body files, +@item automatic formating of subprograms parameter lists. +@item automatic smart indentation according to Ada syntax, +@item automatic completion of identifiers, +@item automatic casing of identifiers, keywords, and attributes, +@item insertion of statement templates, +@item filling comment paragraphs like filling normal text, +@end itemize + +@c ----------------------------------------------------------------------- +@node Installation, Customization, Overview, Top +@chapter Installation +@c ----------------------------------------------------------------------- + +If you got the Ada mode as a separate distribution, you should have a +look at the @file{README} file. It explains the basic steps necessary +for a good installation of the emacs Ada mode. + +Installing the Ada mode is basically just a matter of copying a few +files into the Emacs library directories. Every time you open a file +with a file extension of @file{.ads} or @file{.adb}, Emacs will +automatically load and activate the Ada mode. + +See the section @xref{Using non-standard file names} if your files do +not use these extensions and if you want Emacs to automatically start the +Ada mode every time you edit an Ada file. + +See also the Emacs documentation @xref{(emacs)} for general usage +variables that you might want to set. + +@c --------------------------------------------------------------------- +@section Required files +@c --------------------------------------------------------------------- + +This Ada mode works best with Emacs 20.3 or higher (the easy editing +features for the project files won't work with any older version), but +most of the commands should work with older versions too. Please try to +install the most recent version of Emacs on your system before +installing the Ada mode. + +Although part of the Ada mode is compiler independent, the most advanced +features 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 the Ada mode. +This is the only file which does not require Gnat. It contains the +functions for indentation, formatting of parameter lists, stepping +through code, comment handling and automatic casing. Emacs versions +20.2 and higher already contain Ada mode version 2.27, which is an older +version 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 of +identifiers, support for project files and compilation of your +application are defined. + +@item @file{ada-prj.el}: The functions to use for easy-edition of the +project files. This file is the only one which really requires Emacs at +least 20.2. It uses the new widget features from Emacs. + +@end itemize + +@c -------------------------------------------------------------------- +@node Customization, Project files, Installation, Top +@chapter Customizing the Ada mode +@c --------------------------------------------------------------------- + +The ada-mode is fully customizable. Everything, from the file names to +the automatic indentation and the automatic casing can be adapted to +your own needs. + +There are two different kinds of variables that control this +customization, both are easy to modify. + +The first set of variables are standard Emacs variables. Of course, some +are defined only for the Ada mode, whereas others have a more general +meaning in Emacs. Please see the Emacs documentation for more +information on the latest. In this documentation, we will detail all the +variables that are specific to the Ada mode, and a few others. The names +will be given, as in @code{ada-case-identifier}. + +Emacs provides an easy way to modify them, through a special mode called +customization. To access this mode, select the menu +@kbd{Ada->Customize}. This will open a new buffer with some fields that +you can edit. For instance, you will get something like: +@example +Put below the compiler switches. +comp_opt= _____________________________________ +@end example +The first line gives a brief description of the variable. The second +line is the name of the variable and the field where you can give a +value for this variable. Simply type what you want in the field. + +When you are finished modifying the variables, you can simply click on +the @b{Save for future sessions} button at the top of the buffer (click +with the middle mouse button). This will save the values in your +@file{.emacs} file, so that next time you start Emacs they will have the +same values. + +To modify a specific variable, you can directly call the function +@code{customize-variable} from Emacs (just type @key{M-x +customize-variable RET} and then type the variable name. + +Some users might prefer to modify the variables directly in their +configuration file, @file{.emacs}. This file is coded in Emacs lisp, and +the syntax to set a variable is the following: +@example +(setq variable-name value) +@end example + +The second set of variables for customization are set through the use of +project files. These variables are specific to a given project, whereas +the 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 and +Ada programmers. That is to say, editing, compiling, executing and +debugging can be performed within Emacs in a convenient and natural way. + +To take full advantage of this features, it is possible to create a file +in the main directory of your application, with a '.adp' extension. +This file contain all needed information dealing with the way your +application is organized between directories, the commands to compile, +run and debug it etc. Creating this file is not mandatory and convenient +defaults are automatically provided for simple setups. It only becomes +necessary when those above mentioned defaults need customizing. + +A simple way to edit this file is provided for Emacs 20.2 or newer, with +the following functions, that you can access also through the Ada +menu. It is also possible to edit the project file as a regular text +file. + +Once in the buffer for editing the project file, you can save your +modification using the '[OK]' button at the bottom of the buffer, or +simply use the usual @kbd{C-x C-s} binding. To cancel your +modifications, simply kill the buffer or click on the '[CANCEL]' button +at the button. + +Each buffer using Ada mode will be associated with one project file when +there is one available, so that Emacs can easily navigate through +related source files for instance. + +The exact algorithm to determine which project file should be used is +described in the next section, but you can force the project file you +want to use by setting one or two variables in your @file{.emacs} file. + +@itemize @bullet +@item To set up a default project file to use for any directory, anywhere +on your system, set the variable @code{ada-prj-default-project-file} to +the name of that file. +@example + (set 'ada-prj-default-project-file "/dir1/dir2/file") +@end example + +@item For a finer controlled, 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 example +Note: This has a higher priority than the first variable, so the first +choice is to use this variable settings, and otherwise +@code{ada-prj-default-project-file}. +@end itemize + + +@table @kbd +@item C-c u ada-customize menu: Ada->Project->New/Edit +Create or edit the project file for the current buffer. +@item C-c c ada-change-prj +Change the project file associated with the current Ada buffer. +@item C-c d +Change the default project file for the current directory. Every new +file opened from this directory will be associated with that file by +default. +@item ada-set-default-project-file menu: Ada->Project->Set Default +Set the default project file to use for *any* Ada file opened anywhere +on 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 have +a default value, so that small projects do not need to create a project +file. + +Some variables below can be referenced in other variables, using a +shell-like notation. For instance, if the variable @code{comp_cmd} +contains a sequence like @code{$@{comp_opt@}}, the value of that variable +will be substituted. + +Here is the list of variables: + +@table @code +@item src_dir [default: "./"] +This is a list of directories where the Ada mode will look for source +files. These directories are used mainly in two cases, both as a switch +for the compiler and for the cross-references. + +@item obj_dir [default: "./"] +This is a list of directories where to look for object and library +files. The library files are the .ali files generated by Gnat and that +contain cross-reference informations. + +@item comp_opt [default: ""] +Creates a variable which can be referred to subsequently by using the +@code{$@{comp_opt@}} notation. This is intended to store the default +switches given to `gnatmake' and `gcc'. + +@item bind_opt=SWITCHES [default: ""] +Creates a variable which can be referred to subsequently by using the +@code{$@{bind_opt@}} notation. This is intended to store the default +switches given to `gnatbind'. + +@item link_opt=SWITCHES [default: ""] +Creates a variable which can be referred to subsequently by using the +@code{$@{link_opt@}} notation. This is intended to store the default +switches given to `gnatlink'. + +@item main=EXECUTABLE [default: ""] +Specifies the name of the executable for the application. This variable +can be referred to in the following lines by using the @code{$@{main@}} +notation. + +@item cross_prefix=PREFIX [default: ""] +This variable should be set if you are working in a cross-compilation +environment. This is the prefix used in front of the gnatmake commands. + +@item remote_machine=MACHINE [default: ""] +This is the name of the machine to log into before issuing the +compilation command. If this variable is empty, the command will be run +on the local machine. This will not work on Windows NT machines, since +the Ada mode will simply precede the compilation command with a 'rsh' +command, unknown on Windows. + +@item comp_cmd=COMMAND [default: "$@{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 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@}"]' +Specifies the command used to recompile the whole application. + +@item run_cmd=COMMAND [default: "$@{main@}"] +Specifies the command used to run the application. + +@item debug_cmd=COMMAND [default: "$@{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 of +interest for advanced users. + +Usually, an Ada file is part of a larger application, whose sources and +objects can be spread over multiple directories. The first time emacs is +asked to compile, run or debug an application, or when a cross reference +function is used (goto declaration for instance), the following steps +are taken: + +@itemize @bullet +@item find the appropriate project file, open and parse it. +All the fields read in the project file are then stored by emacs +locally. Finding the project file requires a few steps: + +@itemize @minus +@item if a file from the same directory was already associated with +a project file, use the same one. This is the variable +@code{ada-xref-default-prj-file} described above. +@item if the variable @code{ada-prj-default-project-file} is set, +use the project file specified in this variable. +@item if there is a project file whose name is the same as the source file + except for the suffix, use this one. +@item if there's only one project file in the source directory, use +that one. +@item if there are more than one project file in the source directory, +ask the user. +@item if there are no project files in the source directory use standard +default values. +@end itemize + +The first project file that is selected in a given directory becomes the +default project file for this directory and is used implicitly for other +sources unless specified otherwise by the user. + +@item look for the corresponding .ali file in the @code{obj_dir} defined +in the project file. If this file can not be found, emacs proposes to +compile the source using the @code{comp_cmd} defined in the project file +in order to create the ali file. + +@item when cross referencing is requested, the .ali file is parsed to +determine the file and line of the identifier definition. It is +possible for the .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 searched in the obsolete ali file with +possible inaccurate results. + +@item look for the file containing the declaration using the source +path @code{src_dir} defined in the project file. Put the cursor at the +correct position and display this new cursor. +@end itemize + +@c ----------------------------------------------------------------------- +@node Syntax highlighting, Moving Through Ada Code, Project files, Top +@chapter Syntax highlighting +@c ----------------------------------------------------------------------- + +The Ada mode is made to help you understand the structure of your source +files. Some people like having colors or different fonts depending on +the context: commands should be displayed differently than keywords, +which should also be different from strings, ... + +Emacs is able to display in a different way the following syntactic +entities: + +@itemize @bullet +@item keywords +@item commands +@item strings +@item gnatprep statements (preprocessor) +@item types (under certain conditions) +@item other words +@end itemize + +This is not the default behavior for Emacs. You have to explicitly +activate 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 example + +But the default colors might not be the ones you like. Fortunately, +there is a very easy way to change them. Just select the menu +@kbd{Help->Customize->Specific Face...} and press @kbd{Return}. This +will display a buffer will all the "faces" (the colors) that Emacs knows +about. 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. All +these functions are available through the Ada menu, and you can also use +the following key bindings or the command names: + +@table @kbd +@item M-C-e ada-next-procedure +Move to the next function/procedure/task, which ever comes next. +@item M-C-a ada-previous-procedure +Move to previous function/procedure/task. +@item ada-next-package +Move to next package. +@item ada-prev-package +Move to previous package. +@item C-c C-a ada-move-to-start +Move to matching start of @code{end}. If point is at the end of a +subprogram, this command jumps to the corresponding @code{begin} if the +user option @code{ada-move-to-declaration} is @code{nil} (default), it +jumps to the subprogram declaration otherwise. +@item C-c C-e ada-move-to-end +Move point to end of current block. +@item C-c o ff-find-other-file +Switch between corresponding spec and body file. If the cursor is on a +subprogram, switch between declaration and body. +@item C-c c-d +Move from any reference to its declaration and switch between +declaration and body (for procedures, tasks, private and incomplete +types). +@item C-c C-r ada-find-references +runs the @file{gnatfind} command to search for all references to the +entity pointed by the cursor. Use 'next-error' function, or C-x `, to +visit each reference (as for compilation errors). +@end table + +These functions use the information in the output of the Gnat Ada +compiler. However, if your application was compiled with the +@code{-gnatx} switch, these functions will not work, since no extra +information is generated by GNAT. See GNAT documentation for further +information. + +Emacs will try to run Gnat for you whenever the cross-reference +informations are older than your source file (provided the +@code{ada-xref-create-ali} variable is non nil). Gnat then produces a +file with the same name as the current Ada file but with the extension +changed to @code{.ali}. This files are normally used by the binder, but +they 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 the Ada mode provide two general ways for the completion of +identifiers. This is an easy way to type faster: you just have to type +the first few letters of an identifiers, and then loop through all the +possible completions. + +The first method is general for Emacs. It will work both with Ada +buffers, but also in C buffers, Java buffers, ... The idea is to parse +all the opened buffers for possible completions. + +For instance, if the following words are present in any of the opened +files: my_identifier, my_subprogam, then you will have this scenario: +@example +You type: my@key{M-/} +Emacs will display: my_identifier +If you press @key{M-/} once again, Emacs will replace my_identifier with +my_subprogram. +Pressing @key{M-/} once more will bring you back to my_identifier. +@end example + +This is a very fast way to do completion, and the casing of words will +also be respected. + +The second method is specific to Ada buffer, and even to users of the +Gnat compiler. Emacs will search the cross-information found in the .ali +files generated by Gnat for possible completions. + +The main advantage is that this completion is more accurate: only +existing identifier will be suggested, you don't need to have a file +opened that already contains this identifiers,... + +On the other hand, this completion is a little bit slower and requires +that you have compiled your file at least once since you created that +identifier. + +@c ----------------------------------------------------------------------- +@section Summary of commands +@c ----------------------------------------------------------------------- + +@table @kbd +@item C-TAB ada-complete-identifier +complete accurately current identifier using information in .ali file +@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/task +declarations in the file and choose an item by mouse click to get to its +declaration. This function is accessible through the 'Ada' menu when +editing a Ada file, or simply through the following key binding : + +@table @kbd +@item C-S-mouse-3 +display 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 is +activated, a new frame is displayed, with a file browser. The files from +the current directory are displayed, and you can click on them as you +would with any file browser. The following commands are then available. + +You can click on a directory name or file name to open it. The editor +will automatically select the best possible mode for this file, +including of course the ada-mode for files written in Ada + +If you click on the [+] symbol near a file name, all the symbols (types, +variables and subprograms) defined in that file will be displayed, and +you can directly click on them to open the right file at the right +place. + +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 assicate the +following key binding + +@example +(global-set-key [f7] 'speedbar-get-focus) +@end example + +Every time you press @key{f7}, the mouse will automatically move to the +speedbar 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 ----------------------------------------------------------------------- + +The Ada mode comes with a full set of rules for automatic indentation. +You can of course configure the indentation as you want, by setting the +value of a few variables. + +As always, the preferred way to modify variables is to use the +@code{Ada->Customize} menu (don't forget to save your changes!). This +will also show you some example of code where this variable is used, and +hopefully make things clearer. + +The relevant variables are the following: + +@table @code +@item ada-broken-indent (default value: 2) +Number of columns to indent the continuation of a broken line + +@item ada-indent (default value: 3) +Width of the default indentation + +@item ada-indent-record-rel-type (default value: 3) +Indentation for 'record' relative to 'type' or 'use' + +@item ada-indent-return (default value: 0) +Indentation for 'return' relative to 'function' (if ada-indent-return +is greater than 0), or the open parenthesis (if ada-indent-return is +negative or null). Note that in the second case, when there is no +open parenthesis, the indentation is done relative to 'function' with +the value of ada-broken-indent. + +@item ada-label-indent (default value: -4) +Number of columns to indent a label + +@item ada-stmt-end-indent (default value: 0) +Number of columns to indent a statement 'end' keyword on a separate line + +@item ada-when-indent (default value: 3) +Indentation for 'when' relative to 'exception' or 'case' + +@item ada-indent-is-separate (default value: t) +Non-nil means indent 'is separate' or 'is abstract' if on a single line + +@item ada-indent-to-open-paren (default value: t) +Non-nil means indent according to the innermost open parenthesis + +@item ada-indent-after-return (default value: t) +Non-nil means that the current line will also be re-indented before +inserting a newline, when you press @kbd{Return}. + +@end table + +Most of the time, the indentation will be automatic, i.e when you will +press @kbd{Return}, the cursor will move to the correct column on the +next line. + +However, you might want or need sometimes to re-indent the current line +or a set of lines. For this, you can simply go to that line, or select +the lines, and then press @kbd{TAB}. This will automatically re-indent +the lines. + +Another mode of indentation exists that helps you to set up your +indentation scheme. If you press @kbd{C-c TAB}, the ada-mode will do the +following: +@itemize @bullet +@item Reindent the current line, as @kbd{TAB} would do +@item Temporarily move the cursor to a reference line, i.e the line that + was used to calculate the current indentation +@item Display at the bottom of the window the name of the variable that + provided the offset for the indentation +@end itemize + +The exact indentation of the current line is the same as the one for the +reference line, plus an offset given by the variable. + +Once you know the name of the variable, you can either modify it through +the usual @key{Ada->Customize} menu, or by typing @key{M-x +customize-variable RET} in the Emacs window, and then give the name of +the variable. + +@table @kbd +@item TAB +indent the current line or the current region. +@item M-C-\ +indent lines in the current selected block. +@item C-c TAB +indent the current line and prints the name of the variable used for +indentation. +@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 (':') separating +argument names and argument types, plus align the 'in', 'out' and 'in +out' keywords if required. + +@table @kbd +@item C-c C-f ada-format-paramlist +Format the parameter list. +@end table + +@c ----------------------------------------------------------------------- +@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top +@chapter Automatic Casing +@c ----------------------------------------------------------------------- + +Casing of identifiers, attributes and keywords is automatically +performed while typing when the variable @code{ada-auto-case} is set. +Every time you press a word separator, the previous word is +automatically 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 @kbd +@item downcase-word +The previous word will simply be in all lower cases. For instance +@code{My_vARIable} is converted to @code{my_variable}. + +@item upcase-word +The previous word will be fully converted to upper cases. For instance +@code{My_vARIable} is converted to @code{MY_VARIABLE}. + +@item ada-capitalize-word +All letters, except the first one of the word and every letter after the +'_' character are lower cased. Other letters are upper cased. For +instance @code{My_vARIable} is converted to @code{My_Variable}. + +@item ada-loose-case-word +No letters is modified in the previous word, except the ones after the +'_' character that are upper cased. For instance @code{My_vARIable} is +converted to @code{My_VARIable}. +@end table + +These functions, although they will work in most cases, will not be +accurate 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 a +file. This file should contain one identifier per line, with the casing +you 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 whose +casing you want to specify. The rest of the line can be used for +comments (explaining for instance what an abbreviation means, as +recommended in the Ada 95 Quality and Style, paragrpah 3.1.4). Thus, a +good example for this file could be: + +@example +DOD Department of Defense +Text_IO +GNAT The GNAT compiler from Ada Core Technologies +@end example + +When working on project involving multiple programmers, we recommend +that every member of the team sets this variable to the same value, +which should point to a system-wide file that each of them can +write. That way, you will ensure that the casing is consistent +throughout your application(s). + +There are two ways to add new items to this file: you can simply edit it +as you would edit any text file, and add or suppress entries in this +file. 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, in +an Ada buffer. This word should have the casing you want. Then simply +select the menu @kbd{Ada->Edit->Create Case Exception}, or the key +@kbd{C-c C-y}. The word will automatically be added to the current list +of exceptions and to the file. + +It is sometimes useful to have multiple exception files around (for +instance, one could be the standard Ada acronyms, the second some +company specific exceptions, and the last one some project specific +exceptions). 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 emacs +session. + +However, when you save a new exception through the menu, as described +above, the new exception will be added to the first file in the list +only. You can not automatically add an exception to one of the other +files, 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 +Adjust case in the whole buffer. +@item C-c C-y +Create a new entry in the exception dictionary, with the word under +the cursor +@item C-c C-t +Rereads the exception dictionary from the file +@code{ada-case-exception-file}. +@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. The +functions used here do not exist on Emacs 19.28. + +Templates exist for most Ada statements. They can be inserted in the +buffer using the following commands: + +@table @kbd +@item C-c t b +exception Block +@item C-c t c +case. +@item C-c t d +declare Block. +@item C-c t e +else. +@item C-c t f +for Loop. +@item C-c t h +Header. +@item C-c t i +if. +@item C-c t k +package Body. +@item C-c t l +loop. +@item C-c t t +task Body. +@item C-c t w +while Loop. +@item C-c t u +use. +@item C-c t x +exit. +@item C-c t C-a +array. +@item C-c t C-e +elsif. +@item C-c t C-f +function Spec. +@item C-c t C-k +package Spec. +@item C-c t C-p +procedure Spec. +@item C-c t C-r +record. +@item C-c t C-s +subtype. +@item C-c t C-t +task Spec. +@item C-c t C-u +with. +@item C-c t C-v +private. +@item C-c t C-w +when. +@item C-c t C-x +exception. +@item C-c t C-y +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 few +additional functions to handle comments: + + +@table @kbd +@item M-; +Start a comment in default column. +@item M-j +Continue comment on next line. +@item C-c ; comment-region +Comment the selected region (add -- at the beginning of lines). +@item C-c : +Uncomment the selected region +@item M-q +autofill 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, debugging +and running an application within Emacs. + +All the commands used by Emacs to manipulate your application can be +customized in the project file. Some default values are provided, but +these will likely not be good enough for a big or even medium-sized +project. See the section on the project file for an explanation on how +to 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-compilation +environment, and if yes for which target. The default command used for +compilation 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}, ... + +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 source +This command is issued when issuing the @code{compile} command from the +Ada menu. It compiles unconditionally the current source using the +@code{comp_cmd} variable of the project file. Compilation options can be +customized with the variable @code{comp_opt} of the project file. + +Emacs will display a new buffer that contains the result of the +compilation. Each line associated with an error will become active: you +can simply click on it with the middle button of the mouse, or move the +cursor on it and press @kbd{Return}. Emacs will then display the +relevant source file and put the cursor on the line and column the error +was found at. + +You can also simply press the @kbd{C-x `} key and Emacs will jump to the +first error. If you press that key again, it will move you to the second +error, and so on. + +Some error messages might also include references to some files. These +references are also clickable in the same way. + + +@item (Re)building the whole application +This command is issued when you select the @code{build} command from the +Ada menu. It compiles all obsolete units of the current application +using the @code{make_cmd} variable of the project file. Compilation +options can be customized with the variable @code{comp_opt} of the +project file, binder options with @code{bind_opt} and linker options +with @code{link_opt}. The main unit of the application may be specified +with @code{main}. + +The compilation buffer is also active in the same way it was for the above +command. + +@item Running the application +This command is issued when you select the @code{run} command from the +Ada menu. It executes the current application in an emacs +buffer. Arguments can be passed through before executing. The execution +buffer allows for interactive input/output. + +This command is not yet available in a cross-compilation +toolchain. Emacs would first need to log on the target before running +the 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 your +application. Emacs is compatible with a lot of debuggers, and provide an +easy interface to them. + +This selection will focus on the gdb debugger, and two of the graphical +interfaces that exist for it. + +In all cases, the main window in Emacs will be split in two: in the +upper buffer, the source code will appear, whereas the debugger +input/output window is displayed at the bottom. You can enter the +debugger commands as usual in the command window. Every time a new +source file is selected by the debugger (for instance as a result of a +@code{frame} command), the appropriate source file is displayed in the +upper buffer. + +The source window is interactive: you can click on an identifier with the +right mouse button, and print its value in the debugger window. You can +also set a breakpoint simply by right-clicking on a line. + +You can easily use Emacs as the source window when you are using a +graphical interface for the debugger. The interesting thing is that, +whereas you still have the graphical nifties, you can also you the +cross-references features that the ada-mode provides to look at the +definition for the identifiers,... + +Here is how you can set up gdbtk and ddd for use with Emacs (These are +the commands you should setup in the project file): + +@itemize @bullet +@item gdbtk +should be used with the switch --emacs_gdbtk. It provides a nice +backtrace window, as well as a tasks window. You can click interactively +on both of them, and Emacs will display the source file on the correct +line. + +@item ddd (Data Display Debugger) +should be used with the switches --tty and -fullname. Whenever you +print a variable from Emacs, it will be 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, where +file names are the package names, and the extension for spec and bodies +are respectively .ads and .adb. + +If you want to use other types of file names, you will need to modify +your .emacs configuration file. + +Adding new possible extensions is easy. Since the ada-mode needs to know +how to go from the body to the spec (and back), you always have to +specify both. A function is provided with the ada-mode to add new +extensions. + +For instance, if your files are called <unit>_s.ada and <unit>_b.ada +respectively for spec and bodies, you need to add the following to your +@file{.emacs} : + +@example +(ada-add-extensions "_s.ada" "_b.ada") +@end example + +Note that it is possible to redefine the extension, even if they already +exist, as in: + +@example +(ada-add-extensions ".ads" "_b.ada") +(ada-add-extensions ".ads" ".body") +@end example + +This simply means that whenever the ada-mode will look for the body for +a file whose extension is @file{.ads}, it will take the first available +file 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 more +complicated. You then need to rewrite the function +ada-make-filename-from-adaname (see the file @file{ada-mode.el} for an +example). + +@c --------------------------------------------------------------------- +@node Working Remotely, ,Using non-standard file names, Top +@chapter Working Remotely +@c --------------------------------------------------------------------- + +When you work on project that involve a lot of programmers, it is +generally the case that you will edit the files on your own machine, but +you 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 can +edit any remote file, by doing transparent FTP sessions between your +machine and the remote machine that stores your files. This is a special +Emacs mode, called @code{ange-ftp}. To use it, you just have to use a +slightly different syntax when you open a file. + +@example +For instance, if you want to open the file /work/foo.adb on the machine +aleph.gnu.org, where you log in as qwe, you would simply do this: + +@key{C-x C-f} /qwe@@aleph.gnu.org:/work/foo.adb @key{Return} + +i.e put your name, the name of the machine and the name of the file. +@end example + +The first time, Emacs will ask you for a password that it will remember +until 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 machine +transparently. 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 is +running on, you can set the variable @code{remote_machine} in the +project file for your application. + +This will force Emacs to issue a rsh command for the compilation, +instead of running it on the local machine. Unfortunately, this won't +work on Windows workstations, since this protocol is not supported. + +@example +If your @code{remote_machine} is aleph.gnu.org and the standard +compilation command is @code{cd /work/ && gnatmake foo}, then Emacs will +actually issue the command @code{rsh aleph.gnu.org 'cd /work/ && +gnatmake foo'}. +@end example + +The advantage of using the @code{remote_machine} variable is that it is +easier to change that machine without having to modify the compilation +command. + +Note that if you need to set up some environment variables before the +compilation, you need to insert a call to the appropriate initialization +script in the compilation command, for instance: + +@example +build_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 application +remotely simply by replacing it with a 'rsh' call on Unix. + +@example +For instance, if your command was '$@{main@}', you could replace it with +'rsh aleph.gnu.org $@{main@}'. +@end example + +However, this would not fully work for instance on vxworks, where rsh +is not supported. + +@contents +@bye