~ubuntu-branches/ubuntu/maverick/gnat-gps/maverick

« back to all changes in this revision

Viewing changes to .pc/no-gtkextra.patch/docs/tutorial.texi

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2010-03-15 15:12:34 UTC
  • mfrom: (10.1.3 sid)
  • Revision ID: james.westby@ubuntu.com-20100315151234-2qyonhb0vh6wxb17
Tags: 4.3-5ubuntu1
BUildĀ onĀ armel.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
\input texinfo   @c -*-texinfo-*-
 
2
@input texiplus
 
3
@c %**start of header
 
4
@setfilename tutorial.info
 
5
@settitle GNAT Programming Studio Tutorial
 
6
@syncodeindex fn cp
 
7
 
 
8
@dircategory GNU Ada tools
 
9
@direntry
 
10
* GPS Tutorial: (gps_tutorial).   GNAT Programming Studio Tutorial
 
11
@end direntry
 
12
 
 
13
@set GPSVersion 4.3.0
 
14
 
 
15
@copying
 
16
Copyright @copyright{} 2002-2008, AdaCore.
 
17
 
 
18
This document is free; you can redistribute it and/or modify
 
19
it under the terms of the GNU General Public License as published by
 
20
the Free Software Foundation; either version 3 of the License, or
 
21
(at your option) any later version.
 
22
 
 
23
This document is distributed in the hope that it will be useful,
 
24
but WITHOUT ANY WARRANTY; without even the implied warranty of
 
25
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
26
GNU General Public License for more details.
 
27
 
 
28
You should have received a copy of the GNU General Public License along
 
29
with this program; if not, see @url{http://www.gnu.org/licenses/}.
 
30
@end copying
 
31
 
 
32
@titlepage
 
33
 
 
34
@title GNAT Programming Studio Tutorial
 
35
@subtitle Version @value{GPSVersion}
 
36
@subtitle Document revision level $Revision: 131088 $
 
37
@subtitle Date: $Date: 2008-10-20 14:21:00 +0200 (Mon, 20 Oct 2008) $
 
38
@author AdaCore
 
39
 
 
40
@page
 
41
@vskip 0pt plus 1filll
 
42
 
 
43
@insertcopying
 
44
 
 
45
@end titlepage
 
46
 
 
47
@ifnotinfo
 
48
@contents
 
49
@end ifnotinfo
 
50
 
 
51
@ifinfo
 
52
@node Top, Introduction, (dir), (dir)
 
53
@top GNAT Programming Studio Tutorial
 
54
 
 
55
GNAT Programming Studio Tutorial
 
56
 
 
57
Version @value{GPSVersion}
 
58
 
 
59
Date: $Date: 2008-10-20 14:21:00 +0200 (Mon, 20 Oct 2008) $
 
60
 
 
61
Copyright @copyright{} 2002-2007, AdaCore.
 
62
@insertcopying
 
63
 
 
64
@menu
 
65
* Introduction::
 
66
* Quick overview of the GPS areas::
 
67
* Editing sources::
 
68
* Building applications::
 
69
* Source Navigation::
 
70
* Search Dialog::
 
71
* Project View (entities)::
 
72
* Back to Source Navigation::
 
73
* Code Completion::
 
74
* Run::
 
75
* Debug::
 
76
* Call Graph::
 
77
* Locations Tree::
 
78
* Projects::
 
79
* Epilogue::
 
80
 
 
81
@end menu
 
82
@end ifinfo
 
83
 
 
84
@c --------------------------------------------------------------------
 
85
@node Introduction
 
86
@chapter Introduction
 
87
@c --------------------------------------------------------------------
 
88
 
 
89
@noindent
 
90
This document provides a guide through the major capabilities
 
91
of the GNAT Programming Studio by working on a code example: sdc, a simple
 
92
desktop calculator.
 
93
 
 
94
It is important to realize that the features that you are about to
 
95
experiment with are available on multiple platforms, using the same user
 
96
interface and capabilities, providing a user-friendly environment
 
97
with a tight integration between the tools.
 
98
 
 
99
Start GPS in the directory containing the tutorial files, or if the directory
 
100
is read-only, copy the @file{tutorial} directory and its subdirectories in a
 
101
local (writable) area, and start GPS from the @file{tutorial} directory, so
 
102
that GPS will load the right context.
 
103
 
 
104
By default, the tutorial sources can be found under
 
105
@code{<prefix>/share/examples/gps/tutorial}, where @code{<prefix>} is the
 
106
prefix directory of the GPS installation.
 
107
 
 
108
Alternatively, if you have already started GPS in another directory, you
 
109
can load the project @code{sdc.gpr} by using the menu @code{Project->Open...}
 
110
 
 
111
@c --------------------------------------------------------------------
 
112
@node Quick overview of the GPS areas
 
113
@chapter Quick overview of the GPS areas
 
114
@c --------------------------------------------------------------------
 
115
 
 
116
@noindent
 
117
 
 
118
Having launched GPS, you should now have access to a main window composed of
 
119
several areas:
 
120
 
 
121
@itemize @bullet
 
122
@item a menu bar at the top
 
123
@item a tool bar under the menu bar
 
124
@item a scenario view under the tool bar, on the left side
 
125
@item a project view under the scenario view, on the left side
 
126
@item a working area on the right of the project view
 
127
@item a messages window under the working area
 
128
@end itemize
 
129
 
 
130
@c --------------------------------------------------------------------
 
131
@node Editing sources
 
132
@chapter Editing sources
 
133
@c --------------------------------------------------------------------
 
134
 
 
135
@noindent
 
136
 
 
137
In the project view, open the @code{common} directory by clicking
 
138
on the @code{[+]} sign (a triangle under unix systems) on the left of
 
139
@code{common}.
 
140
This will open the directory and display a list of source files located
 
141
in this directory.
 
142
 
 
143
Now, double click on @file{sdc.adb}: this will open a source editor on this
 
144
file. The source code is syntax-highlighted: keywords, comments, strings and
 
145
characters have different colors.
 
146
 
 
147
As with many other properties, colors are configurable in GPS:
 
148
 
 
149
Select the menu @code{Edit->Preferences}. This will open a preferences
 
150
dialog window.
 
151
 
 
152
Select the @code{Editor->Fonts & Colors} page by clicking on the cross next to
 
153
the item @code{Editor} and then selecting the @code{Fonts & Colors} item.
 
154
 
 
155
As you go over the various lines and labels, you will notice that by
 
156
holding the mouse over a label, a tool tip pops up displaying on-line help
 
157
about the selected item.
 
158
 
 
159
Change the background color of the @code{Keywords} by clicking on the last
 
160
down arrow, at the right of the @code{Keywords} line.
 
161
 
 
162
Choose a color, e.g a light green. When you're done with the color
 
163
selection, simply click again on the arrow.
 
164
 
 
165
Click on the @code{Apply} button and look at the effects in the source
 
166
editor. If you like the new display, click on @code{OK} to confirm the
 
167
changes, otherwise clicking on @code{Cancel} will revert to the previous
 
168
color.
 
169
 
 
170
@c --------------------------------------------------------------------
 
171
@node Building applications
 
172
@chapter Building applications
 
173
@c --------------------------------------------------------------------
 
174
 
 
175
@noindent
 
176
 
 
177
Select the icon @code{Build Main: sdc.adb} on the toolbar: this will launch
 
178
a complete build of the @i{sdc} application. Note also that you can use a
 
179
key binding directly instead of this tool bar button (@key{F4}), or use the
 
180
corresponding menu item @code{Build->Project->sdc.adb}. If you use the menu
 
181
item, an extra intermediate dialog is displayed showing the actual command
 
182
line that will be used by GPS. Pressing @key{Enter} will launch also the build.
 
183
 
 
184
The build has generated a number of errors in a new window: the @i{Locations}
 
185
tree, displayed in the bottom area. The errors are also highlighted in the
 
186
corresponding source editor.
 
187
 
 
188
GPS has automatically jumped to the first error message
 
189
(@i{sdc.adb, 28:6  : (style) bad indentation}),
 
190
at the line (28) and column (6) of the error.
 
191
 
 
192
Fix the error by hand by inserting a space.
 
193
 
 
194
Now you can fix the next error by moving the cursor to the line 30 (press
 
195
the @key{down} arrow twice), and by using @key{Ctrl-Tab} (press first the
 
196
@key{Control} key, and then the @key{Tab} key on your keyboard): this key
 
197
combination asks the source editor to automatically re-indent the current
 
198
line.
 
199
 
 
200
Note that on some window managers or desktop environments,
 
201
@key{Ctrl-Tab} is already defined. If this is the case, you can change this
 
202
shortcut from the key shortcuts dialog (menu @code{Edit->Key shortcuts},
 
203
@code{Source editor} section, @code{Format selection} item).
 
204
 
 
205
You can then fix all the remaining errors by selecting the whole block
 
206
(from line 28 to line 40) and pressing @key{Ctrl-Tab}. To select a block,
 
207
you can either click on the left mouse button and select the area while
 
208
holding the button, or using the keyboard by pressing the @key{Shift} key
 
209
and moving the cursor using the @key{Up} or @key{Down} keys.
 
210
 
 
211
Press the @key{F4} key to build again. GPS will automatically save the
 
212
modified files, and start a build. This behavior (automatic saving of files
 
213
before building) can be configured in the preferences dialog.
 
214
 
 
215
If you look at the bottom right of the GPS window, you will notice that a
 
216
progress bar has appeared, displaying the current number of files compiled,
 
217
and the number of remaining files. This progress bar disappears when the
 
218
build is finished.
 
219
 
 
220
This should now report a successful build.
 
221
 
 
222
@c --------------------------------------------------------------------
 
223
@node Source Navigation
 
224
@chapter Source Navigation
 
225
@c --------------------------------------------------------------------
 
226
 
 
227
@noindent
 
228
 
 
229
Now let's try to understand a little bit about how the program is working by
 
230
looking at the @file{sdc.adb} editor: there's a loop, the main processing is
 
231
done by the functions Process and Next (at line 30).
 
232
 
 
233
Click around line 30, move the mouse over @code{Process} and let a tool tip
 
234
appear (@code{Tokens.Process global procedure declared at tokens.ads:19}): this
 
235
gives information about the kind of entity and the location (file and line) of
 
236
the declaration of this procedure, the profile of the parameters, and
 
237
documentation for this function, as extracted from the comments surrounding
 
238
the procedure declaration.
 
239
 
 
240
Do the same for @code{Next} (@code{Tokens.Next global function declared at
 
241
tokens.ads:15}).
 
242
 
 
243
Keeping the mouse over @code{Next}, display the contextual menu by clicking on
 
244
the right mouse button,
 
245
then click on @code{Goto declaration of Next}: we're now in the package
 
246
@code{Tokens}, in file @file{tokens.ads}; but where is this file in the project?
 
247
 
 
248
@c --------------------------------------------------------------------
 
249
@node Search Dialog
 
250
@chapter Search Dialog
 
251
@c --------------------------------------------------------------------
 
252
 
 
253
@noindent
 
254
 
 
255
Select the menu @code{Navigate->Find or Replace...}: this will open a search
 
256
dialog.
 
257
In the @code{Search for:} text entry type @file{tokens.ads}. Then
 
258
select @code{Project view} in the @code{Look in:} area. The search
 
259
area provides an easy way to search for text or regular expressions in
 
260
several contexts including the current file, the project view, @dots{}
 
261
 
 
262
Now click on @code{Find}. The file @file{tokens.ads}, in directory @code{struct}
 
263
is highlighted.
 
264
 
 
265
Close the search dialog by clicking on the @code{Close} button.
 
266
 
 
267
Note that in this specific case, a simpler way to locate a file in the
 
268
project view is to use the contextual menu from the source editor:
 
269
@code{Locate in Project View: tokens.ads}.
 
270
 
 
271
@c --------------------------------------------------------------------
 
272
@node Project View (entities)
 
273
@chapter Project View (entities)
 
274
@c --------------------------------------------------------------------
 
275
 
 
276
@noindent
 
277
Click on the @code{[+]} sign (or triangle) to open @file{tokens.ads} entities.
 
278
When you click on a file in the project view, you get
 
279
language sensitive information about the file, such as
 
280
@code{packages}, @code{subprograms}, @code{tasks}, ... for @code{Ada}.
 
281
 
 
282
Open the @code{subprogram} category, click on @code{Process}: this
 
283
will open @file{tokens.ads} and move the cursor on the first line
 
284
corresponding to the procedure @code{Process}.
 
285
 
 
286
Similarly, click on @code{Next}, and move your mouse on @code{Next}
 
287
in the source editor.
 
288
 
 
289
@c --------------------------------------------------------------------
 
290
@node Back to Source Navigation
 
291
@chapter Back to Source Navigation
 
292
@c --------------------------------------------------------------------
 
293
 
 
294
@noindent
 
295
 
 
296
Using the contextual menu, select @code{Goto body of Next};
 
297
scroll through the procedure @code{Next}, move the mouse on
 
298
@code{Instructions.Read} at line 46 and from the contextual menu, select
 
299
@code{Goto body of Read}.
 
300
 
 
301
We've now navigated quite a bit through the application source code,
 
302
which you can verify by clicking on the left arrow in the tool bar, to go
 
303
back to the previous locations visited.
 
304
 
 
305
Repeat the operation until you're back in @file{sdc.adb}.
 
306
As with the undo/redo capability in the source editor, the
 
307
@code{goto previous/next location} is infinite.
 
308
 
 
309
@c --------------------------------------------------------------------
 
310
@node Code Completion
 
311
@chapter Code Completion
 
312
@c --------------------------------------------------------------------
 
313
 
 
314
@noindent
 
315
 
 
316
Go on the line 38 of sdc.adb. You can see that there is a null instruction for
 
317
the case of Stack.Overflow. We are going to add some code here, using the
 
318
code assist capabilities.
 
319
 
 
320
Type @key{enter} to create a new line, and then @code{Scr}, and hit
 
321
@key{Ctrl+Space}. If you've never used
 
322
auto-completion before, GPS will pop a window asking you if you want to enable
 
323
the auto-completion engine. Answer "yes". You will see at the bottom right of
 
324
GPS a progress bar, showing the status of the completion database load. Note
 
325
that you can still work during this operation. The auto completion mechanism
 
326
can be disabled from the preferences if needed.
 
327
 
 
328
Wait until the progress bar disappears, and then hit @key{Ctrl+Space} again.
 
329
A completion popup will be displayed, showing all the entities of the project
 
330
begining with @code{Scr}. Select @code{Screen_Output}. The code will be
 
331
automatically completed in the editor. Then add a dot in your code. The
 
332
completion popup will be automatically triggered, and will offer you to
 
333
complete your code with the entities contained in the @code{Screen_Output}
 
334
package. Select @code{Msg}, add a space, and then an open parenthesis. Once
 
335
again, the completion windows will pop up, and show you the possible parameters
 
336
for msg. If you choose the first entry of the completion list
 
337
("params of Msg"), the call will
 
338
be automatically completed by a list of named parameters. Complete the list by
 
339
giving e.g. @code{"The stack is full."} for @code{S1}, @code{""} for @code{S2},
 
340
and @code{True} for @code{End_Line}.
 
341
 
 
342
Don't forget to add a semicolon at the end of the instruction. Then hit @key{F4}
 
343
in order to rebuild the application.
 
344
 
 
345
@c --------------------------------------------------------------------
 
346
@node Run
 
347
@chapter Run
 
348
@c --------------------------------------------------------------------
 
349
 
 
350
@noindent
 
351
It is now time to run the application: select the menu
 
352
@code{Build->Run->sdc}, which will open a dialog window.
 
353
Type @code{input.txt} in the text entry: this is the name of a text
 
354
file that will be passed as argument to the @i{sdc} program.
 
355
 
 
356
Now click on @code{OK}: a new window titled @code{Run: sdc input.txt}
 
357
is created at the bottom of the main window where the sdc application
 
358
runs and displays an unexpected internal error: this is a good opportunity
 
359
to use the integrated debugger.
 
360
 
 
361
Close the execution window by clicking on the x icon on the top right
 
362
corner of this window.
 
363
 
 
364
@c --------------------------------------------------------------------
 
365
@node Debug
 
366
@chapter Debug
 
367
@c --------------------------------------------------------------------
 
368
 
 
369
@noindent
 
370
 
 
371
Open the preferences dialog (menu @code{Edit->Preferences}) and
 
372
click on the @code{Debugger} item on the left; set the button
 
373
@code{Break on exceptions} to @i{Enabled}: this will enable by default a special
 
374
breakpoint every time an exception is raised. Click on @code{OK} to confirm your
 
375
change.
 
376
 
 
377
Now select the menu @code{Debug->Initialize->sdc}: a new window is
 
378
created: this is the debugger console.
 
379
You can also look at the various debug menu item and tool bar buttons which are
 
380
now activated.
 
381
 
 
382
Use the menu @code{Debug->Data->Call Stack}: this opens a new window on the
 
383
right of the source editors. If you select the contextual menu in the call
 
384
stack, various pieces of information can be displayed or
 
385
removed in the call stack. From this contextual menu, add the
 
386
@code{Frame Number} info by clicking on it.
 
387
 
 
388
Now select the menu @code{Debug->Run...}. Notice that @code{input.txt} has
 
389
been filled automatically for you since the two menus @code{Build->Run...} and
 
390
@code{Debug->Run...} are synchronized. Click on @code{OK}: the debugger should
 
391
stop on an exception (@code{Constraint_Error} in the file @file{stack.adb}, at
 
392
line 49).
 
393
 
 
394
Go up in the call stack by clicking on the @code{tokens.process} line
 
395
(frame number 6 or 7, depending on your GNAT version).
 
396
 
 
397
If you move the mouse over the parameter @code{T} at line 64, a tool tip is
 
398
displayed showing the value of @code{T}. You have probably noticed that
 
399
tool tips, like menus, are contextual: depending on the current session and
 
400
on the entity selected, different information is displayed.
 
401
 
 
402
Select the contextual menu @code{Debug->Display T}: this will open a new
 
403
window: the data window, with a box displaying graphically the contents
 
404
of the different fields of @code{T}, each clearly separated.
 
405
 
 
406
On @code{T} data display, select the contextual menu
 
407
@code{Display->Show Value + Type}: this displays for all fields both their
 
408
type and value.
 
409
 
 
410
Special colors are used in the data display: blue for pointers that can be
 
411
dereferenced by a double-click (double click on @code{T.val}); red for fields
 
412
that have been modified since last step.
 
413
 
 
414
In the contextual menu that pops up when you right-click on @code{T},
 
415
select @code{Debug->View memory at address of T}: a memory view is opened.
 
416
Use the @code{up} and @code{down} arrows on the right to visit memory.
 
417
 
 
418
Click in the memory dump, and modify it by typing numbers. Notice the
 
419
red color for modified values;
 
420
click on @code{Undo Changes} to cancel the modifications;
 
421
click on @code{Close} to close the memory window.
 
422
 
 
423
In the call stack, go back to @code{stack.push} frame (num 4 or 5).
 
424
Move the mouse over @code{Last} and let the debugger display its value: 0.
 
425
From the contextual menu, select @code{Goto declaration of Last}: this
 
426
will jump to the line 16 of @file{stack.adb}, where you can see that
 
427
@code{Last} is a @code{Natural}. Now click on the @code{Goto Previous Location}
 
428
button in the tool bar: we're now back at line 49 where we can see that for a
 
429
@code{Push} procedure, @code{Last} should be incremented, and not decremented.
 
430
 
 
431
Fix the line to @code{Last := Last + 1;}
 
432
 
 
433
Save the file (@key{Ctrl-S});
 
434
End the debug session: menu @code{Debug->Terminate};
 
435
Rebuild (press @key{F4} key);
 
436
Rerun (menu @code{Build->Run->sdc}): the program now completes as expected.
 
437
Close the execution window.
 
438
 
 
439
@c --------------------------------------------------------------------
 
440
@node Call Graph
 
441
@chapter Call Graph
 
442
@c --------------------------------------------------------------------
 
443
 
 
444
@noindent
 
445
Now go back to the file @file{sdc.adb}, move the mouse over the procedure
 
446
@i{sdc} at line 8, select the contextual menu
 
447
@code{Browsers->Sdc calls}: this will open a new window titled
 
448
@i{Call graph browser}.
 
449
 
 
450
Note that there is also a top level contextual menu (@code{Sdc calls})
 
451
which provides a tree view of the callers/callees.
 
452
 
 
453
In the call graph, click on the right arrow of @code{Process} (one of the
 
454
first items on the top). Also click on the right arrow of @code{error_msg}.
 
455
 
 
456
Select @code{Orthogonal links} in the contextual menu of the graph to change the
 
457
way links are displayed in the graph.
 
458
You may then play with the zoom (@key{=} and @key{-} keys).
 
459
 
 
460
If you select @code{Hide links} from @code{error_msg} contextual menu, this
 
461
will hide all the links that are related to this item: the link between the
 
462
callers and callees of @code{error_msg} are no longer displayed. This can
 
463
be useful when the graph becomes complex, to hide some parts. If you go back to
 
464
the contextual menu, you can now select @code{Show links} to show the links
 
465
again.
 
466
 
 
467
Click on right arrow of @code{process} (@code{(Decl) instructions.ads:12}).
 
468
 
 
469
The items can also be moved: move e.g @code{msg} item around.
 
470
 
 
471
You can also recompute the layout of all the current items by using
 
472
the contextual menu @code{Refresh layout}.
 
473
 
 
474
Click on left arrow of @code{msg}
 
475
to display who is calling @code{msg}. Notice that @code{view} calls @code{msg}.
 
476
 
 
477
Click on left arrow of @code{view}: the arrow disappears, and no
 
478
new items are created, which means that @code{view} isn't called by anyone,
 
479
so we're now going to remove this procedure.
 
480
 
 
481
@c --------------------------------------------------------------------
 
482
@node Locations Tree
 
483
@chapter Locations Tree
 
484
@c --------------------------------------------------------------------
 
485
 
 
486
@noindent
 
487
From @i{view}, click on the blue link: @code{stack.ads:32}, this will open
 
488
the file @file{stack.ads} at line 32.
 
489
Then from the source editor (file @file{stack.ads}), select the contextual
 
490
menu @code{References->Find all references to View}: this highlights the
 
491
@code{Locations} tree which now contains all the references for @code{view},
 
492
grouped by files (@file{stack.ads} and @file{stack.adb}).
 
493
 
 
494
The first location is highlighted automatically: this is the spec of the
 
495
procedure @code{View}. Now click in the tree on the @code{+} sign (or
 
496
triangle) at the left
 
497
of @file{stack.adb}: two locations are listed, at line 90 and 97.
 
498
Click on each of these locations: they correspond to the procedure body.
 
499
 
 
500
The @code{Find all references} capability is another way to list all the uses of
 
501
an entity, and it confirms that @code{View} isn't called in our project.
 
502
 
 
503
Remove @i{View} body by e.g selecting it, and pressing the @key{Delete} key,
 
504
then save the file (@key{Ctrl-S}).
 
505
 
 
506
Do the same for the spec, save the file.
 
507
 
 
508
Close the @file{stack.ads} and @file{stack.adb} files (menu File->Close,
 
509
or using the shortcut @key{Ctrl-W}), as well as the call graph window.
 
510
Rebuild by pressing the @key{F4} key.
 
511
 
 
512
@c "Let's now have a look at all the changes we've done so far, by looking at
 
513
@c  the version control system explorer, aka VCS explorer"
 
514
 
 
515
@c --------------------------------------------------------------------
 
516
@c @node Version Control
 
517
@c @chapter Version Control
 
518
@c --------------------------------------------------------------------
 
519
 
 
520
@c @noindent
 
521
@c From the project view, contextual menu on project @i{sdc}, select
 
522
@c @code{Version Control->Query status for project}. The VCS Explorer is
 
523
@c opened, listing the files in the project.
 
524
@c => Explain the use of icons for status, log files, ...
 
525
@c => The list can be sorted by status or by file name, by clicking
 
526
@c on the @code{Status} and @code{File name} labels.
 
527
 
 
528
@c Move the mouse over @file{stack.ads}, select the contextual menu
 
529
@c @code{Compare against head rev.}:
 
530
@c this will open a visual comparison between the version in the repository,
 
531
@c and the local (modified) file; You can see that scrolling is synchronized
 
532
@c between the two files, and that colors are used to show lines
 
533
@c added, removed and modified.
 
534
 
 
535
@c Close the Visual Comparison window
 
536
 
 
537
@c Go back to the VCS Explorer
 
538
 
 
539
@c On @file{stack.ads}, contextual menu, @code{Edit changelog}
 
540
 
 
541
@c In the change log, type a log, e.g: @code{(View): Removed, since unused}
 
542
 
 
543
@c Save and close the log editor.
 
544
@c This log file will now associated with @file{stack.ads} until the
 
545
@c next check in.
 
546
 
 
547
@c Go back to the VCS Explorer, @file{stack.ads} has now an icon
 
548
@c showing that a log is associated with this file.
 
549
 
 
550
@c On @file{stack.ads}, commit the file using the contextual menu,
 
551
@c entry @code{Commit}.
 
552
 
 
553
Let's now see how to create a project corresponding to the @i{sdc}
 
554
project we've used in this tutorial.
 
555
 
 
556
@c --------------------------------------------------------------------
 
557
@node Projects
 
558
@chapter Projects
 
559
@c --------------------------------------------------------------------
 
560
 
 
561
@menu
 
562
* Project Wizard::
 
563
* Project properties::
 
564
* Variable editor::
 
565
* Switch editor::
 
566
* Source dependencies::
 
567
* Project dependencies::
 
568
@end menu
 
569
 
 
570
@node Project Wizard
 
571
@section Project Wizard
 
572
@noindent
 
573
 
 
574
Go to the menu @code{Project->New...}: this is a standard wizard, with various
 
575
steps listed on the left area of the window.
 
576
 
 
577
The first page of the wizard allows you to select what kind of project you
 
578
want to build, depending on the information you have. Select the default
 
579
choice @code{Single Project}, and press @code{Forward}.
 
580
 
 
581
Type @i{sdc2} in the project name field.
 
582
 
 
583
Click on @code{Forward}: we are now on the language selection page.
 
584
It is possible to create a multi-language project by e.g. selecting the C or C++
 
585
check box.
 
586
 
 
587
Click on @code{Forward}: we are now on the @code{VCS page}. @i{VCS} stands
 
588
for @i{Version Control System}.
 
589
GPS provides a generic framework for @i{VCS} which allows it to support
 
590
new systems easily. Systems supported by default are CVS, ClearCase and
 
591
Subversion. Select @code{CVS}.
 
592
 
 
593
Click on @code{Forward}: this is the source directories selection,
 
594
used to specify the project's sources. Click on the @code{Add} button,
 
595
and select the @code{struct} directory, then click on @code{OK} to validate.
 
596
 
 
597
Click on @code{Forward}: this is the @code{Build} and @code{Exec} directory
 
598
selection, used to store object, ali files, ...
 
599
 
 
600
Click on the first @code{Browse} button, then click on
 
601
@code{obj}, and finally click on @code{OK}.
 
602
 
 
603
Click on @code{Forward}: this is the main units selection, used mainly for
 
604
building executables and debugging.
 
605
 
 
606
Click on @code{Add}, open the @code{common} directory and select
 
607
@code{sdc.adb}.
 
608
 
 
609
Click on @code{Forward}: this is the naming scheme editor.
 
610
GNAT is very flexible and can use any kind of naming scheme for Ada files.
 
611
In particular, you can easily set the default file
 
612
extensions (e.g by using one of the predefined schemes) and you
 
613
can also specify exceptions that use non standard file names.
 
614
 
 
615
Click on @code{Forward}: we're now in the switch selector.
 
616
Select @code{Recompile if switches changed}.
 
617
 
 
618
Click on @code{Ada} page.
 
619
 
 
620
Select @code{Full errors} and @code{Overflow checking}.
 
621
The boxes and the command line (the text entry at the
 
622
bottom of the page) are fully synchronized, e.g if you click on the
 
623
command line, and change @code{-gnatf} to @code{-gnat}, the
 
624
@code{Full errors} check box is unselected; now type @code{a} to get
 
625
@code{-gnata}, and notice that @code{Enable assertions} is now selected.
 
626
 
 
627
We've now created a project similar to the one used in this tutorial.
 
628
 
 
629
Click on @code{Cancel} to close the wizard.
 
630
 
 
631
Clicking on @code{Apply} instead would have created the project file
 
632
and loaded it in GPS.
 
633
 
 
634
@node Project properties
 
635
@section Project properties
 
636
@noindent
 
637
 
 
638
In the project view, on the project @i{sdc}, use the contextual menu
 
639
@code{Project->Properties}.
 
640
All the properties set in the project wizard can be found here as well.
 
641
You can switch between pages by clicking on the tabs located along the
 
642
left side of the window.
 
643
 
 
644
Once you're done exploring the property pages, click on the @code{Cancel}
 
645
button to close the properties window.
 
646
 
 
647
@node Variable editor
 
648
@section Variable editor
 
649
@noindent
 
650
 
 
651
Select the window titled "Scenario View".  If not available, you can open it
 
652
using the menu @code{Tools->Views->Scenario}.
 
653
This window contains a @code{Build} label.
 
654
 
 
655
This is a configuration variable. With GPS and the GNAT
 
656
project facility, you can define as many configuration variables as you want,
 
657
and modify any project settings (e.g. switches, sources, ...) based on the
 
658
values of configuration variables. These variables can also take any
 
659
number of different values.
 
660
 
 
661
The @code{Build} variable demonstrates a typical @code{Debug/Production}
 
662
configuration where we've set different switches for the two modes.
 
663
 
 
664
Click on the button at the left (@code{Edit variable properties}): this
 
665
is the variable editor, where values can be added or renamed.
 
666
Close the variable editor by clicking on the @code{Cancel} button.
 
667
 
 
668
Now, let's take a look at the switches set in the project.
 
669
 
 
670
@node Switch editor
 
671
@section Switch editor
 
672
@noindent
 
673
 
 
674
Select the menu item @code{Project->Edit File Switches}: a global
 
675
switch editor is displayed in the working area, showing the
 
676
switches associated with each file in the @code{sdc} project.
 
677
 
 
678
The editor lists the switches associated with each file in the project.
 
679
Gray entries indicate default (global) switches.  Notice that
 
680
@file{screen_output.adb} has specific switches, which are highlighted
 
681
using a different font.
 
682
 
 
683
Switch between @code{Debug} and @code{Production} mode in the @code{Build}
 
684
combo box: the switches are updated automatically.
 
685
 
 
686
Back to our project, let's now examine the dependencies between sources.
 
687
 
 
688
@node Source dependencies
 
689
@section Source dependencies
 
690
@noindent
 
691
 
 
692
Select @file{sdc.adb} in the @code{Project View} and then the contextual menu
 
693
item @code{Show dependencies for sdc.adb}: this will open a new graph showing
 
694
the dependencies between sources of the project.
 
695
 
 
696
Click on the right arrow of @file{tokens.ads} to display the files that
 
697
@file{tokens.ads} depends on. Similarly, click on the right arrow of
 
698
@file{stack.ads}.
 
699
 
 
700
@node Project dependencies
 
701
@section Project dependencies
 
702
@noindent
 
703
 
 
704
Back in the project view, on the @i{Sdc} project, select the contextual
 
705
menu @code{Project->Dependencies}, then on the @code{Add From File},
 
706
then open the @i{tutorial}
 
707
directory and click on the @code{projects} subdirectory. Select the file
 
708
@code{prj1.gpr}. Click on @code{Apply} to validate the change.
 
709
 
 
710
You can see the new dependency added in the project view, as a tree of
 
711
projects. In particular, project dependencies are duplicated: if you open
 
712
the @code{prj1} icon by clicking on the @code{[+]} sign (or triangle), and then
 
713
similarly open the @code{prj2} icon, you will notice that the project
 
714
@code{prj4} is displayed twice: once as a dependency of @code{prj2}, and
 
715
once as a dependency of @code{prj1}.
 
716
 
 
717
GPS can also display the graph of dependencies between projects: on @i{Sdc}
 
718
project, use the contextual menu
 
719
@code{Show projects imported by Sdc}: this will open a project hierarchy
 
720
browser.
 
721
 
 
722
On the @code{Sdc.gpr} project, select the contextual menu
 
723
@code{Show projects imported by Sdc recursively}.
 
724
 
 
725
In the browser, you can move the project items, and select them to highlight
 
726
the dependencies.
 
727
 
 
728
Close the project browser by clicking on the @code{[x]} sign at the top right
 
729
area of the window, or by typing @key{Ctrl-W}, or by using the menu
 
730
@code{File->Close}.
 
731
 
 
732
@c --------------------------------------------------------------------
 
733
@node Epilogue
 
734
@chapter Epilogue
 
735
@c --------------------------------------------------------------------
 
736
 
 
737
@noindent
 
738
This terminates our tour of GPS, the GNAT Programming Studio.
 
739
We hope this tutorial gave you a good overview of the general capabilities
 
740
available with GPS. A non exhaustive list of the features not mentioned in
 
741
this document includes:
 
742
 
 
743
@itemize @bullet
 
744
@item Documentation generation
 
745
@item Automatic generation of body files
 
746
@item Pretty printing
 
747
@item Visual comparison of files
 
748
@item Version control
 
749
@item Flexible multiple document interface
 
750
@item Code coverage
 
751
@end itemize
 
752
 
 
753
For more information, please look at the @i{User's Guide} (@url{gps.html}),
 
754
and also look at the @code{Tools} menu which gives access to most of these
 
755
capabilities.
 
756
 
 
757
@c @printindex cp
 
758
 
 
759
@bye