Copyright (C) 2000, ACT-Europe
This document may be copied, in whole or in part, in any form or by any means, as is or with alterations, provided that (1) alterations are clearly marked as alterations and (2) this copyright notice is included unmodified in any copy.
Glide is an integrated environment for the Gnat tool chain. It supports creation of complete applications from code editing through compilation and debugging within a single environment. Glide comprises the Emacs editor, the Gnat Ada95 compilation system and two debuggers - the command line debugger GDB available in prior versions of the Gnat package, and a new graphical debugger DDD.
Glide is currently available on Unix and the Windows NT platforms. The only difference between the Windows NT and UNIX platforms is the absence of DDD for Windows NT. Another graphical debugger called GDBTK is available for this platform, but is launched from outside Glide. DDD will be ported to the NT platform in the near future.
Since Glide is built from open source software components, you have access all of its source code.
In this description of the Glide integrated environment, we use the term Glide Editor instead of Emacs for the sake of a more uniform presentation. The purpose of this paper is to describe the capabilities and use of Glide in detail. For a quick introduction and "getting started" instructions, consult the Glide Tutorial, which will guide you through the process of application development, illustrated by several examples. You do not need any experience with Emacs or Gnat to get started, as the tutorial covers the pertinent details.
This chapter explains how to set up a new application within Glide. It describes file creation and the available editing tools. Its aim is to show you how to use the tools to write code very quickly.
Within Glide, most commands you can select through menus can also be invoked directly with keyboard shortcuts. If a shortcut exists, it appear next to the command in the menu.
There are two kinds of shortcuts; those beginning with C- designating
the ctrl key
and the ones beginning with M- designating
the alt key of your keyboard
. The -
sign appearing
between two characters means you must type them simultaneously.
For example, if you want to launch the Open File
command, you
can type the C-x C-f shortcut. This means that the following
key sequence is to be executed: Ctrl x are pressed simultaneously,
followed by Ctrl f pressed simultaneously. In general, the command names
appearing in the menus are intuitive, and their intent should be obvious.
This is especially so for the Files
menu. The purpose of this set
of commands is editing the files making in your application. In the succeeding
sections, the many useful capabilities for editing offered by Glide are described.
In this chapter you will discover tools you will use very frequently, which
allow you to work more easily and effectively than with ordinary editors.
The commands to open a file or a directory are in the Files
menu. To open a file, click on Files->Open File
. At the bottom
of the window in the status line, you will be asked for the path and name
of the file you wish to open. You can either open an existing or create a
new one by entering the desired path and name. In the latter case,
Glide will not warn you that the file doesn't yet exist, but will display
New File
in the status line to indicate it.
Opening a directory is similar to opening a file: the only difference is that you specify only the path of the directory. In response the editor window will be split into two parts, one of which will display the list of files it contains. You can edit any of these files by simply selecting its name from the list. Remember that each of these commands has a corresponding shortcut allowing you to work much more quickly.
Whenever a file is opened, the glide editor stores it into a
"buffer". When you want to work on a previously opened file, the arrow
keys cycle through the buffers Glide has created for each file
in the current session. Similarly, saving a file actually saves the
Glide buffer created for it. This is why, the Files
menu specifies
Save Buffer
rather than Save File
.
Another very useful feature of the editor is the ability to edit
two buffers simultaneously. Select Files->split
window
. The window is split into two parts and you can now
edit two different locations within the same file, or two different
files, at the same time.
This section describes tools that accelerate code editing. You will see that Glide reduces the detail you must attend to, while improving your editing efficiency.
Statement templates allow you to skip typing the required keywords in Ada
syntactic constructs. Depending on the construct you need,
Glide can insert a template for it into your buffer. To do this, you
simply select the desired construct from the Ada->Statements
menu and follow the instructions displayed in the status line.
For example, to create a file containing an Ada package body, you must
begin your file with a package body header. To insert it automatically,
select the menu item Ada->Statements
->Package Body
.
Glide will then insert the necessary keywords into the currently selected buffer,
i.e. package body
. It will then ask you to enter in
the status line the name of the package you are going to
implement. After you verify your entry, Glide will complete the package body
model as follows :
end Name of your package;
Now you have only to write the body code. You will certainly appreciate the power of statement templates once you have learned their corresponding shortcuts. Using menu selection will like take longer than directly typing keywords. That is why we have listed the shortcuts of the templates available within Glide :
The previous section explained how to avoid typing the headers of a specific
Ada construct within Glide. Glide goes further by supporting creation of
templates for subprograms. This functionality is implemented
through the gnat tool Gnatstub. Whenever you call the
Ada->Edit->Make body for subprograms
, gnatstub will be invoked
if it is installed in your environment, Otherwise, a similar algorithm will
simulate its functionality. In order for the command to execute,
the cursor must be in an Ada specification file buffer on a line where a
subprogram is declared. If you then click on Ada->Edit->Make
body for subprograms
, you will see the cursor move to the
corresponding package body file. The statement template for that
subprogram will be added to the body file buffer. This example, Test_Arrays,
is similar to what you will see (excepting the subprogram name):
procedure Test_Arrays is begin null; end Test_Arrays;
The next two tools are very useful for clear organization of the file you are writing. They eliminate the tedious task of indenting each line as you type and allow you to maintain a consistent casing style across multiple files. Glide thus offers you the ability to type very quickly without concerning yourself with formatting. The editor automatically formats the code for you, according to your specifications.
The Auto Casing feature automatically changes the case of keywords,
attributes and identifiers. You set automatic casing by selecting the
Ada->Options
menu and checking the See section Auto Casing
item. This feature is most useful when entering your own code. However, it
may happen that the code you are working on has not
been written by you and the casing may not suit you. In that
situation, you can change the case of the complete buffer or of any part
you select. For the first case you have only to call the
Ada->Edit->Adjust Case Buffer
command and for the second,
Ada->Edit->Adjust Case Selection
.
Of course, programmers and organizations generally use various casing
conventions. Glide's default casing approach can be modified to some
extent. If particular words require special casing, they are listed in the file
`.emacs_case_exceptions'. Glide refers to this file in order to case
such words correctly. To add a casing exception to the
list, place the cursor on a word written with the desired case and select
Ada->Edit
->Create Case exception
. If there are several
programmers on the same project, we recommend you that you put the file
into a shared directory. Whenever someone in the group modifies
the file, select the ada->Edit->Reload Case Exceptions
to
make Glide aware of the recent updates. To change the location of
the `.emacs_case_exceptions' file, go to the customization frame
(select Ada->Customize
). This presents a framework for customizing
Glide. For this specific case, locate the Ada Case Exceptions file variable
and click on the Show
button next to the label. On the grey line,
specify the new path of the file and click on State->Save
for future sessions
to effect the change. To exit the customization frame,
select the Files->Kill Current Buffer
button.
This section describes how to indent a line or a block of lines in your program file. There are several methods available. It is generally best to to use the available shortcuts for these commands as often as possible in order to type faster.
The usual way to indent your code, i.e. to start a line at a desired
position, is to use the TAB key before or after writing a
line of code (or to select the following item : Ada->Edit->Indent Line
).
Glide provides a more elegant way to do this automatically
each time you press Return. To set automatic indentation,
select Ada->Options
->Auto Indent After Return
.
You will quickly see when using these tools that the fastest method is to avoid the menus in favor of the shortcuts mentioned between parentheses.
Glide offers other kinds of indentation which allow you to write code and postpone the detail work of indenting. These tools are especially useful you need to cleanly indent code written by someone else. You in fact have three different ways to indent a block of lines after a file has been written.
Ada->Edit->Indent Lines in Selection
.
Ada->Edit->Indent Lines in File
.
We must emphasize that by design, if you have not
selected a block of lines before invoking Ada->Edit->Indent
Lines in Selection
, it will be substituted by Ada->Edit->Indent Lines in
File
.
You can check the rule used for the previous indentation by calling
Ada->Edit->Justify Current Indentation
(shortcut :
C-c TAB
). In this case, Glide will temporarily move the cursor
in your editor, displaying the offset in the status line.
Finally, Glide allows you to set indentation widths in place of those used by default. To configure this, we refer you to the section section Customization.
The Glide editor provides two general methods for identifier completion. This is an easy way to type faster: you type the first few letters of an identifier, then cycle through a list of possible completions.
The first method is general for all languages. It will work with Ada buffers, C buffers, Java buffers and so on. The idea is to parse all open buffers for possible completions. To use it, type the first few letters of the word and then type the shortcut M-/. Note that the words you can complete this way must already have an instance either in an earlier line of the file you are editing ,or in a file displayed in another buffer. See (See section The Buffer, a Characteristic of the Glide Editor, for more information).
For instance, if the following words are present in any of the opened files: my_identifier, my_subprogam, you will have this scenario:
You type: my M-/ Glide displays: my_identifier If you press M-/ again, Glide replaces my_identifier with my_subprogram. Pressing M-/ a third time redisplays my_identifier.
This is a very fast way to achieve completion, and the casing of words will be respected.
The second method is specific to Ada buffers. Glide searches the cross-reference
information found in the .ali files generated by Gnat for possible completions.
To use this kind of completion, type the first few letters of the word, then
either select Ada->Edit->Complete Identifier
or type its
corresponding shortcut C-TAB.
The main advantage of this type of completion is its high accuracy: only existing identifiers will be suggested. You don't need to have a file open that already contains instances of the identifiers.
On the other hand, this method is a little slower and requires that you have compiled your file at least once since you created the desired identifier.
To help you correctly align fields in a subprogram parameter list, Glide provides a function that will do most of the work for you. This function aligns the declarations on the colon (':') separating argument names and argument types, as well as aligning the 'in', 'out' and 'in out' keywords as required.
Ada mode exists to help you understand the structure of your source files. Some people also like having different colors or fonts depending on the context: for instance, comments should be displayed differently than keywords, which should be different than strings, ...
The Glide editor is able to display the following syntactic entities with independent formats:
The default colors might not be the ones you like. There is a very easy way to change them. Go to See section Customization to learn how to change Glide editor colors.
So far, we have focused our attention on how to quickly write Ada code using Glide facilities. We did not address how to manage comments and their appearance in a file. This section covers this topic.
Glide enables you to comment out code you have typed very quickly:
select the lines with the mouse left button to highlight them,
then select menu item Ada->Edit Comment
Selection
. To undo the command, select
Ada->Edit
->Uncomment Selection
. We suggest using the
associated shortcuts : C-c ; and C-c :.
You can choose three types of comment appearance to aid readability:
Ada->Edit->Fill Comment paragraph
when the cursor is
located within the paragraph. The corresponding shortcut is M-q.
By default your comments may not extend beyond 70 columns (you can
customize this feature), giving for example :
-- This is a very long comment that can -- be automatically justified by using -- the M-q keyboard shortcut. You can -- have multiple versions for the -- justification, including aligned to -- left, justified on both side...
Ada->Edit->Fill Comment Paragraph Justify
.
-- This is a very long comment that can be -- automatically justified by using the comment -- paragraph justify utility. Note that the end -- of the lines have changed compared to the -- previous justification showed just above.
Ada->Edit->Fill Comment Paragraph Postfix
.
Your comments will be demarcated by two hyphens on each
end of the line.
-- This is a very long comment that can be -- -- automatically justified by using the comment -- -- paragraph postfix utility. Note that this -- -- comment seems to be in a box! --
Searching for the definition of a procedure when viewing a call to it can be tricky - especially when you have many source files. Glide eases this task through cross references.
There are several kinds of cross references available providing different capabilities. In general, cross references move the cursor through the various source files of your application. They can also be used to display a list of the subprograms declared in a package.
The situation we mentioned above to introduce this subject
is easily solved by the cross-referencing capabilities described here.
If you have a package, subprogram or record / array type
instance and wish to visit its definition, place the cursor on the instance
and select the Ada->Goto->Declaration/Body
menu item.
The main window will split into two parts; the first buffer will contain the file
buffer you were editing at the point where you issued the command;
the new window will display a file buffer containing the procedure or package
declaration. The cursor will be on the specific line of the declaration.
If you leave the cursor at that position and repeat the command, the other part of the frame will display a file buffer containing the completion (implementation) of the declaration. Note that the cursor will have moved from the declaration of the procedure (or package or type) to its body. You can't go directly from a procedure call to its implementation. This cross-referencing capability only supports movement from a declaration to a body or from a body to a declaration. This is why clicking on an entity instance goes directly to its declaration.
instance ------------> declaration (specification file) | ^ | | | | V | body (implementation file)
A slightly more complex command performs the same operation but
directly displays the body implementation of the entity and its declaration files
in two different windows. Rather than selecting the first item of the
Ada
menu, select the Ada->Goto->Declaration Other Frame
item.
When you have viewed the information of interest, you can
return previous location by selecting Ada->Goto->Previous Reference
.
For example, if the cursor was on a declaration header before visiting its
implementation, this command can be used to return to the declaration.
Note, however, that this operation will display the same file in both parts of the
window. Place your cursor in the frame you want to keep, then click on
the File->One Window
menu item in order to remove the
unwanted frame.
Another functionality enables you to list all files referencing an entity.
The first part of the operation is the same, i.e. place the
cursor on an instance of the entity. The next step is to choose
Ada->Goto->List References
in the menu.
A more general alternative is to type the name of an entity in the
status line at the bottom of the main window, and select the
Ada->Goto->Goto References to any entity
menu item.
These commands have the same result: Glide searches all source files of the application for the entity you have selected. It then displays a list of all references to the entity. The first lines of this frame are the commands executed to find the references. These are followed by the list of references. Each line gives all information necessary in order to choose which reference you wish to visit: the name of the file containing the reference, its line and column numbers, and more interestingly, the kind of reference. If it is the declaration you will see in parentheses "(spec)"; if the body implementation "(body)"; if an instance there is nothing next to the column number in parentheses.. Finally, the entity name is listed next to its kind.
You can directly select and visit an item with the middle mouse button. As for the commands described earlier, the main window is split into two parts and the cursor is moved to the specified reference in one of them.
The speedbar is a file browser displayed in a separate window. Its purpose
is to list all the files in an application while providing same the cross
references. You can launch it by selecting the following item :
Ada->Speedbar
.
Each selectable file name is a menu which containing other items. Next to the
name of each file, the add / minus
operator indicates the
open /close
state of the menu. These states can be between
opened and closed by simply clicking on the operator. Clicking an item
in the menu (or on the menu name itself), will move the cursor to the
corresponding file buffer and reference, displaying it in the main window.
Earlier chapters described how to create a file and edit it, and how to use Glide to navigate an application. In this chapter, we move to the next step of building an application.
Glide bases its build processes on project files, which are described next.
Glide maintains an overview of the organization of an application (e.g the location of source and object files) in a file called the Project File. It assumes that all information necessary to build, run and debug an application exists in that file.
Creating this file is not mandatory since Glide always supplies a default one. However, if you want to customize information for an application, you will need to create and edit a new project file.
The name of the project file created for your application must always end with the extension `.adp'. The usual name given to this file is the name of the file containing the main unit (without an extension) followed by the `.adp' extension. The name of the default project file created by Glide is called `default.adp'.
To edit the current project file, either the default one implicitly created by
Glide or one you have modified for your application, select
Ada->Project->Edit current
and enter the name of the project
file. Glide will open a window containing four tabs enabling access to different
aspects of the project. The next section describes each of these panels.
When you open a project file, the General window is
displayed. You can switch to another one by clicking its tab.
The four windows follow the same pattern. Each contains some information
that can be modified on a grey background. If you wish, the information
that appears on the highlighted lines can be replaced. Clicking on the
Help
button, next to the line you want to alter, displays a
dialog explaining the purpose of that line and the required syntax. Notice
the string between braces near the help button. This string is very
useful for users who modify the configuration file. The strings are variable
names that store the information on the corresponding lines. This alias
preceded by the "$" character may be used to provide macro substitution
in other parts of the configuration file, thus avoiding the need to retype
the contents when needed elsewhere in the file.
example :
You can see an example on how to use these variables in the Paths and General menus. To pass from the General window to one of the others, click on the corresponding tab. In the Paths window, immediately above the first line, one such variable is used. Here, $(build_dir) replaces the complete line of the Build Directory defined in the General window. See the third line of this frame and the variable (build_dir) above it.
At the bottom of the window, you will notice three buttons. The first, Reset to Default Values, will reset all information you have entered from default project file. The next button, Cancel, will exit the project file without saving modifications, while the Save button will, conversely, save changes and exit from the project file.
The General window displays information on :
The Paths window lets you specify the directories where Glide will find the source and object files needed to build the application. When the default information on these lines is not sufficient, Glide provides several ways to specify additional directories :
INS
button. To delete a line, just click on the DEL
button, preceding
it.
Load From File
button, above each line and
give the name of the "listing file" to Glide in the status line when prompted.
Load Recursive Directory
button and enter the name of
this root directory. This approach will spare your having to create the
listings.
The Switches window allows you to change the compiler, binder, linker and make options. To modify them properly, you should consult the GNAT documentation for descriptions of the available switches.
-g
is required if you want
to generate debugging information, so you can subsequently run
your Ada application under a debugger.
The Ada frame gathers the command lines that Glide will issue to compile, build, run and debug the application.
Ada->Check file
menu item.
Ada->compile file
menu item.
Ada->build
menu item,. As for the previous line, you can replace it with a make
command if you have created a Makefile for your application and don't
wish to use the Gnat tools.
Ada->Run
menu item.
Ada->Debug
menu item.
This section will describe the steps involved in creating a correct project
file and associating it with an application. The default project file created
by Glide is suitable only for simple applications. More complex "real world"
application may require a more complex project file. Most of the default
commands gathered in the Ada window
won't need to be changed
very much and can take their values by default in your new project
file.
To create a new project file, select the Ada->Project->New
item
and enter its name in the status line. Glide allows you to associate
several project files to a given application: it may be useful
to apply different sets of commands depending on the context. However,
manipulating several project files for a single application can easily
lead to mistakes, so we recommend selecting one of these as the default
to be used by Glide for the building. After creating such a project file
creation, select the Ada->Set Default
item and enter your
default project file name into the status line. The project file you are using
at any given time is specified in the title bar of the main
window, before the name of the file being edited. Whenever you use the
ada->Edit current
item, the project file displayed in the title
bar is the one that will be edited.
Command summary for creating and associating a project file to an application :
Ada->Project->New
item, enter the new name.
This command creates the new project; fill the command
lines and save.
Ada->Set Default
item, enter the name of
the default project file for your application.
To associate a project file to the file currently being edited, select
the menu Ada->Project->Associate
and enter the name of the project file
you intend to associate to the buffered file.
Now that you have set up and associated a project file, you can execute the commands you have just configured (or not if you use the default project of Glide).
Ada->Check file
item.
Ada->Compile file
item.
Ada->Build
item.
Following execution of any of these commands, Glide may have detected errors in your program that it lists in a separate buffer. Click on any error with the middle mouse button to move the cursor to the corresponding source file location.
Ada->Run
item.
Ada->Debug
item.
You will see a new frame appearing; it is the DDD, the Data Display Debugger, which belongs to the free software family. This version has been adapted to the Ada language. You should read the Glide Tutorial to begin using it quickly, followed by DDD documentation for a more complete description.
There are two different kinds of customization available, depending on the features you wish to change:
The method for changing either of these aspects of Glide is quite similar, differing only in the menu used to reach the configuration buffer.
The tools already described are easily customized. They are each controlled by a variable whose value can be altered. There are two ways to access these variables in order to modify them. The first is through a menu, and the second is through shortcuts and command lines. Your preferred way will probably be through the menus explained below :
First open the customization buffer by selecting the
Ada->Customize
item. You will see a new buffer
displaying all the pertinent variables, along with a
Show/Hide
button controlling the visibility of
each.
@image{AdaCustomize, 12cm}
Click the Show
button and enter the new value you want
on the line for the variable. To save the field, click the State
button, which will pop up a dialog. Choose the item describing the action
you wish to take. Another way to save all modifications you have made
for the future session is to click [Save for Future Sessions]
button
at the top of the frame.
You can perform the same actions on variables via command lines
in the main window. To do so, type M-x customize-variable
RET
. A piece of advice: whenever you type something in the status
line, completion is always activated; rather than type the whole word,
use completion to go more quickly. You then enter the name of the variable
you want to change and validate. You can now set the value as previously
explained.
The next two sections describe how to set your own values for the variables that manage the indentation and casing utilities.
In this section, we describe the variables controlling indentation and the values they can assume. You set them using the instructions already given. The variables for configuring indentation are:
ada-broken-indent (default value: 2)
ada-indent (default value: 3)
ada-indent-record-rel-type (default value: 3)
ada-indent-return (default value: 0)
ada-label-indent (default value: -4)
ada-stmt-end-indent (default value: 0)
ada-when-indent (default value: 3)
ada-indent-is-separate (default value: t)
ada-indent-to-open-paren (default value: t)
ada-indent-after-return (default value: t)
You can set the casing for the keywords, identifiers and
attributes. To configure these casings you must respectively alter
the following variables ada-case-keyword,
ada-case-identifier, ada-case-attribute
, in the Ada->Customize
frame. Each of these variables can have one of the following values :
My_vARIable
is converted to my_variable
.
My_vARIable
is converted to MY_VARIABLE
.
My_vARIable
is converted to My_Variable
.
My_vARIable
is
converted to My_VARIable
.
Remember the Ada-case-exception-file
variable, which was
described in the See section Auto Casing section. Its purpose is
to store all words whose casing doesn't follow the rules into a file.
The colors displayed in the editor can also be configured. This is done
similarly to tool modification, except for the menu used. This customization
is part of Glide's editor, Emacs. To reach it select Help->Customize
->Specific Face
. Then press Return when Glide asks you which
face (ie color) you wish to configure. The window displayed is quite similar
to the one associated with the tools' variables: it shows all the colors that
the Glide editor will try to use. The most relevant variables are those
beginning with the font-
prefix. Alter this buffer as was explained for
the tools. All color modifications you make are saved in a file called
`.Emacs'. You can also change colors directly by writing
instructions in lisp, but it is far easier to configure the
them through the menu.
@image{EmacsCustomize, 12cm}
If you want to deactivate all the default Glide colors, launch Glide with the
option -nocolors
.
Glide's Ada->Help
menu groups references to the utilities
on which Glide is based. You can access the following documents:
If you need explanation of some point not covered in these documents,
check the Emacs' tutorial, as it may very well be related to Emacs
itself. This tutorial is accessed by selecting the
Help->Emacs Tutorial
item. That tutorial will
give you all the information you are likely to need on Emacs'
functionalities.
This document was generated on 5 November 2000 using the texi2html translator version 1.51.