~ubuntu-branches/ubuntu/maverick/gnat-gps/maverick : revision 14

1

\input texinfo @c -*-texinfo-*-

2

@input texiplus

3

4

@c For uniformity, screenshots are generated using the following setup:

5

@c - Under Windows XP, using the default XP theme

6

@c - Using the standard Windows screen or window capture

7

@c (using e.g Ctrl-PrntScrn)

8

@c

9

@c - Save the resultat image (if needed, truncated to show only relevant

10

@c items) in jpeg format, quality 95%

11

12

@c %**start of header

13

@setfilename gps.info

14

@settitle Using the GNAT Programming Studio

15

@setchapternewpage odd

16

@syncodeindex fn cp

17

18

@set GPS

19

@set GPSVersion 4.3.0

20

21

@titlepage

22

23

@flushleft

24

@title{Using GPS}

25

@end flushleft

26

@sp 1

27

@flushright

28

@titlefont{The GNAT Programming Studio}

29

@end flushright

30

@sp 2

31

@subtitle Version @value{GPSVersion}

32

@subtitle Document revision level $Revision: 131155 $

33

@subtitle Date: $Date: 2008-10-21 15:24:10 +0200 (Tue, 21 Oct 2008) $

34

@author AdaCore

35

36

@page

37

@vskip 0pt plus 1filll

38

39

Copyright @copyright{} 2001-2008, AdaCore.

40

41

This document may be copied, in whole or in part, in any form or by any

42

means, as is or with alterations, provided that (1) alterations are clearly

43

marked as alterations and (2) this copyright notice is included

44

unmodified in any copy.

45

46

@end titlepage

47

48

@ifnottex

49

@ifhtml

50

@node Top, Introduction,,

51

@top Using the GNAT Programming Studio

52

@end ifhtml

53

@ifnothtml

54

@node Top, Introduction, (dir), (dir)

55

@top Using the GNAT Programming Studio

56

@end ifnothtml

57

58

Version @value{GPSVersion}

59

60

Date: $Date: 2008-10-21 15:24:10 +0200 (Tue, 21 Oct 2008) $

61

62

Copyright @copyright{} 2001-2008, AdaCore

63

This document may be copied, in whole or in part, in any form or by any

64

means, as is or with alterations, provided that (1) alterations are clearly

65

marked as alterations and (2) this copyright notice is included

66

unmodified in any copy.

67

68

@menu

69

* Introduction::

70

* Description of the Main Windows::

71

* Online Help::

72

* Multiple Document Interface::

73

* Editing Files::

74

* Source Navigation::

75

* Project Handling::

76

* Searching and Replacing::

77

* Compilation/Build::

78

* Source Browsing::

79

* Debugging::

80

* Version Control System::

81

* Tools::

82

* Working in a Cross Environment::

83

* Using GPS for Remote Development::

84

* Customizing and Extending GPS::

85

* Environment::

86

* Index table::

87

88

@detailmenu

89

90

--- The Detailed Node Listing ---

91

92

Description of the main windows

93

* The Welcome Dialog::

94

* The Menu Bar::

95

* The Tool Bar::

96

* The Work Space::

97

* The Project View::

98

* The File View::

99

* The Window View::

100

* The Outline View::

101

* The Clipboard View::

102

* The Callgraph View::

103

* Bookmarks::

104

* The Messages Window::

105

* The Shell and Python Windows::

106

* The Locations Tree::

107

* The Status Line::

108

* The Task Manager::

109

110

Online Help

111

* The Help Menu::

112

* Adding New Help Files::

113

114

Multiple Document Interface

115

* Selecting Windows::

116

* Closing Windows::

117

* Splitting Windows::

118

* Floating Windows::

119

* Moving Windows::

120

121

Editing Files

122

* General Information::

123

* Editing Sources::

124

* The File Selector::

125

* Menu Items::

126

* Recording and replaying macros::

127

* Contextual Menus for Editing Files::

128

* Handling of case exceptions::

129

* Refactoring::

130

* Using an External Editor::

131

* Using the Clipboard::

132

* Saving Files::

133

* Remote Files::

134

135

Source Navigation

136

* Support for Cross-References::

137

* The Navigate Menu::

138

* Contextual Menus for Source Navigation::

139

140

Project Handling

141

* Description of the Projects::

142

* Supported Languages::

143

* Scenarios and Configuration Variables::

144

* Extending Projects::

145

* Project View::

146

* Disabling Project Edition Features::

147

* The Project Menu::

148

* The Project Wizard::

149

* The Project Dependencies Editor::

150

* The Project Properties Editor::

151

* The Switches Editor::

152

* The Project Browser::

153

154

Searching and Replacing

155

156

Compilation/Build

157

* The Build Menu::

158

159

Source Browsing

160

* General Issues::

161

* Call Graph::

162

* Dependency Browser::

163

* Entity Browser::

164

165

Debugging

166

* The Debug Menu::

167

* The Call Stack Window::

168

* The Data Window::

169

* The Breakpoint Editor::

170

* The Memory Window::

171

* Using the Source Editor when Debugging::

172

* The Debugger Console::

173

* Customizing the Debugger::

174

* Upgrading from GVD to GPS::

175

176

Version Control System

177

* The VCS Explorer::

178

* The VCS Activities::

179

* The VCS Menu::

180

* The Version Control Contextual Menu::

181

* Working with global ChangeLog file::

182

* The Revision View::

183

184

Tools

185

* The Tools Menu::

186

* Visual Comparison::

187

* Code Fixing::

188

* Documentation Generation::

189

* Metrics::

190

* Code Coverage::

191

192

Working in a Cross Environment

193

* Customizing your Projects::

194

* Debugger Issues::

195

196

Using GPS for Remote Development

197

* Requirements::

198

* Setup the remote servers::

199

* Setup a remote project::

200

* Limitations::

201

202

Customizing and Extending GPS

203

* The Preferences Dialog::

204

* GPS Themes::

205

* The Key Manager Dialog::

206

* The Plug-ins Editor::

207

* Customizing through XML and Python files::

208

* Adding support for new tools::

209

* Customization examples::

210

* Scripting GPS::

211

* Adding support for new Version Control Systems::

212

* The Server Mode::

213

214

Customizing through XML and Python files

215

* Customization files and plugins::

216

* Defining Actions::

217

* Macro arguments::

218

* Filtering actions::

219

* Adding new menus::

220

* Adding contextual menus::

221

* Adding tool bar buttons::

222

* Binding actions to keys::

223

* Preferences support in custom files::

224

* Creating themes::

225

* Defining new search patterns::

226

* Adding support for new languages::

227

* Defining text aliases::

228

* Defining project attributes::

229

* Adding casing exceptions::

230

* Adding documentation::

231

* Adding stock icons::

232

@c * Defining a documentation format::

233

* Remote programming customization::

234

235

Adding support for new tools

236

* Defining supported languages::

237

* Defining default command line::

238

* Defining tool switches::

239

* Executing external tools::

240

241

Customization examples

242

* Menu example::

243

* Tool example::

244

245

Scripting GPS

246

* Scripts::

247

* Scripts and GPS actions::

248

* The GPS Shell::

249

* The Python Interpreter::

250

* Subprogram parameters::

251

* Python FAQ::

252

* Hooks::

253

254

Python FAQ

255

* Hello World! in python::

256

* Spawning external processes::

257

* Redirecting the output of spawned processes::

258

* Contextual menus on object directories only::

259

* Redirecting the output to specific windows::

260

* Reloading a python file in GPS::

261

* Printing the GPS Python documentation::

262

* Automatically loading python files at startup::

263

* Hiding contextual menus::

264

* Creating custom graphical interfaces::

265

266

Environment

267

* Command Line Options::

268

* Environment Variables::

269

* Running GPS on Mac OS X::

270

* Files::

271

* Reporting Suggestions and Bugs::

272

* Solving Problems::

273

274

@end detailmenu

275

@end menu

276

@end ifnottex

277

278

@iftex

279

@contents

280

@end iftex

281

282

@c --------------------------------------------------------------------

283

@node Introduction

284

@chapter Introduction

285

@cindex introduction

286

@c --------------------------------------------------------------------

287

288

@noindent

289

GPS is a complete integrated development environment that gives access

290

to a wide range of tools and integrates them smoothly.

291

292

@cindex HTML

293

@cindex help

294

GPS gives access to built-in file editing; HTML based help system;

295

complete compile/build/run cycle; intelligent source navigation;

296

project management; general graph technology giving access to many different

297

browsers such as source dependency, project dependency, call graphs,

298

entity view, etc@dots{}; fully integrated visual debugger; generic

299

version control system, providing access to CVS, Subversion, ClearCase,

300

and any other via xml plug-ins; many other tools such as a visual comparison,

301

automatic generation of files, source reformatting.

302

303

@cindex customization

304

GPS is fully customizable, providing several levels of customizations:

305

a first level, available through the preferences and key manager dialogs;

306

a second level, which allows you to customize your menu items, tool bar and key

307

bindings; a third level, which allows you to automate processing through

308

scripts (via xml and python scripting).

309

See @ref{Customizing and Extending GPS} for more details.

310

311

GPS also interacts with most versions of command-line tools such as

312

gcc, gdb, gnatmake, etc@dots{}.

313

314

@c --------------------------------------------------------------------

315

@node Description of the Main Windows

316

@chapter Description of the Main Windows

317

@cindex main windows

318

@c --------------------------------------------------------------------

319

320

@menu

321

* The Welcome Dialog::

322

* The Menu Bar::

323

* The Tool Bar::

324

* The Work Space::

325

* The Project View::

326

* The File View::

327

* The Window View::

328

* The Outline View::

329

* The Clipboard View::

330

* The Callgraph View::

331

* Bookmarks::

332

* The Messages Window::

333

* The Shell and Python Windows::

334

* The Locations Tree::

335

* The Execution Window::

336

* The Status Line::

337

* The Task Manager::

338

@end menu

339

340

@c --------------------------------------------------------------------

341

@node The Welcome Dialog

342

@section The Welcome Dialog

343

@cindex welcome dialog

344

@c --------------------------------------------------------------------

345

346

@iftex

347

@cindex screen shot

348

@image{welcome, 10.7cm}

349

@end iftex

350

351

@ifhtml

352

@cindex screen shot

353

@image{welcome}

354

@end ifhtml

355

356

@noindent

357

When starting GPS, a welcome dialog is displayed by default, giving the

358

following choices:

359

360

@table @b

361

@item Start with default project in directory

362

@cindex project

363

If you select this option and click on the @code{OK} button, GPS will

364

first look for a project called @file{default.gpr} in the current directory

365

and load it if found. Otherwise, it will copy in

366

the current directory the default project found under

367

@file{<prefix>/share/gps/default.gpr} and load it.

368

GPS will remove this copy when exiting or loading another project, if the

369

copy has not been modified during the session.

370

371

If the current directory is not writable, GPS will instead load directly

372

@code{<prefix>/share/gps/readonly.gpr}.

373

374

@item Create new project with wizard

375

@cindex project

376

Selecting this option and clicking on the @code{OK} button will start a

377

wizard allowing you to specify most of the properties for a new project. Once

378

the project is created, GPS will save it and load it automatically.

379

See @ref{The Project Wizard} for more details on the project wizard.

380

381

Several kinds of wizard are available. Depending on the kind of project,

382

you will get asked different type of information. In the end, GPS will create

383

one or more project files, and automatically load them.

384

385

One of the wizard, "From existing Ada sources", will try and import a set of

386

sources and object files, and attempt to create one or more project files so

387

that building your application through these project files will put the objects

388

in the same directory they are currently in. If you have not compiled your

389

application when launching this wizard, GPS will create a single project file

390

and all object files will be put in the same object directory. This is the

391

prefered method when importing sources with duplicate file names, since the

392

latter is only authorized in a single project file, not across various project

393

files.

394

395

@item Open existing project

396

@cindex project

397

You can select an existing project by clicking on the @code{Browse} button,

398

or by using a previously loaded project listed in the combo box. When a

399

project is selected, clicking on the @code{OK} button will load this

400

project and open the main window.

401

402

@item Always show this dialog when GPS starts

403

If unset, the welcome dialog won't be shown in future sessions.

404

In this case, GPS will behave as follows: it will first look for a

405

@code{-P} switch on the command line, and load the corresponding project if

406

present.

407

Then, it will look for a project file in the current directory and will

408

load the first project file found.

409

410

If no project file can be found in the current directory, GPS will start

411

with the default project.

412

413

To reset this property, go to the menu @code{Edit->Preferences}.

414

@cindex preferences

415

@xref{The Preferences Dialog}.

416

417

@item Quit

418

If you click on this button, GPS will terminate immediately.

419

@end table

420

421

@cindex command line

422

When you specify a -P switch on the command line, or if there is only one

423

project file in the current directory, GPS will start immediately with

424

the project file specified, instead of displaying the welcome dialog.

425

426

In addition, if you specify source files on the command line, GPS will also

427

start immediately, using the default project if no project is specified.

428

429

By default, files specified on the command line are taken as is and can

430

be absolute or relative pathnames. In addition, if you prepend a filename

431

with the @code{=} character, then GPS will look for the file in the source

432

search path of the project.

433

434

@c --------------------------------------------------------------------

435

@node The Menu Bar

436

@section The Menu Bar

437

@cindex menu bar

438

@c --------------------------------------------------------------------

439

440

@noindent

441

This is a standard menu bar that gives access to all the global

442

functionalities of GPS. It is usually easier to access a given functionality

443

using the various contextual menus provided throughout GPS: these menus

444

give direct access to the most relevant actions given the current context

445

(e.g. a project, a directory, a file, an entity, @dots{}). Contextual menus

446

pop up when the right mouse button is clicked or when using the special

447

@key{open contextual menu} key on most PC keyboards.

448

449

The menu bar gives access to the following items:

450

451

@table @b

452

453

@item File

454

@xref{The File Menu}.

455

456

@item Edit

457

@xref{The Edit Menu}.

458

459

@item Navigate

460

@xref{The Navigate Menu}.

461

462

@item VCS

463

@xref{The VCS Menu}.

464

465

@item Project

466

@xref{The Project Menu}.

467

468

@item Build

469

@xref{The Build Menu}.

470

471

@item Debug

472

@xref{The Debug Menu}.

473

474

@item Tools

475

@xref{The Tools Menu}.

476

477

@item Window

478

@xref{Multiple Document Interface}.

479

480

@item Help

481

@xref{The Help Menu}.

482

@end table

483

484

@c --------------------------------------------------------------------

485

@node The Tool Bar

486

@section The Tool Bar

487

@cindex tool bar

488

@c --------------------------------------------------------------------

489

490

@noindent

491

The tool bar provides shortcuts via buttons to some typical actions:

492

creating a new file, opening a file, saving the current file;

493

undo/redo last editing;

494

@cindex clipboard

495

cut to clipboard, copy to clipboard, paste from clipboard;

496

go to previous/next location;

497

@cindex debugger

498

start/continue the debugging session, step/next execution, finish

499

current procedure.

500

501

The icon on the far right of the tool bar will be animated to indicate that an

502

action (e.g. a build or a search) is going on in the background.

503

504

@c --------------------------------------------------------------------

505

@node The Work Space

506

@section The Work Space

507

@cindex work space

508

@cindex MDI

509

@cindex Multiple Document Interface

510

@c --------------------------------------------------------------------

511

512

The whole work space is based on a multiple document interface,

513

@xref{Multiple Document Interface}.

514

515

@c --------------------------------------------------------------------

516

@node The Project View

517

@section The Project View

518

@cindex project view

519

@cindex project view

520

@cindex project

521

@c --------------------------------------------------------------------

522

523

@noindent

524

The project view provides a representation of the various components of your

525

project hierarchy, as listed below.

526

It is displayed by default on the left side of the main window, and can

527

be selected by using the @code{Project->Project View} or

528

@code{Tools->Views->Project} menu items.

529

530

@cindex drag-n-drop

531

Under Windows, it is possible to drop files (coming e.g. from the Explorer)

532

in the project view with the following behavior: a project file dropped

533

will be loaded; any other file will be opened in a new source editor.

534

535

@iftex

536

@cindex screen shot

537

@image{project-view, 6.7cm}

538

@end iftex

539

540

@ifhtml

541

@cindex screen shot

542

@image{project-view}

543

@end ifhtml

544

545

@cindex interactive search

546

The project view, as well as the file and outline view provide an

547

interactive search capability allowing you to quickly

548

search in the information currently displayed. The default key

549

to start an interactive search is @key{control-f}.

550

@anchor{Interactive Search}

551

This will open a small window

552

at the bottom of the view where you can interactively type names.

553

The first matching name in the tree will be selected while you type it.

554

You can then also use the @key{up} and @key{down} keys to navigate through

555

all the items matching the current text.

556

557

The various components that are displayed are:

558

559

@table @b

560

@item projects

561

@cindex project view

562

All the sources you are working with are put under

563

control of projects. These projects are a way to store the switches to

564

use for the various tools, as well as a number of other properties.

565

566

They can be organized into a project hierarchy, where a root project

567

can import other projects, with their own set of sources.

568

569

Initially, a default project is created, that includes all the sources

570

in the current directory.

571

572

The @code{Project View} displays this project hierarchy: the top node

573

is the root project of your application (generally, this is where the

574

source file that contains the main subprogram will be located). Then a node

575

is displayed for each imported project, and recursively for their own imported

576

projects.

577

578

A given project might appear multiple times in the

579

@code{Project View}, if it is imported by several other projects.

580

581

There exists a second display for this project view, which lists

582

all projects with no hierarchy: all projects appear only once in the view,

583

at the top level. This display might be useful for deep project hierarchies, to

584

make it easier to find projects in the project view.

585

586

@cindex Show flat view

587

This display is activated through the contextual menu entry

588

@code{Show flat view}, which acts as a switch between the two displays.

589

590

A special icon with a pen mark is displayed if the project

591

was modified, but not saved yet. You can choose to save it at any time

592

by right-clicking on it. GPS will remind you to save it before any

593

compilation, or save it automatically, if the corresponding preference

594

is saved.

595

596

@item directories

597

@cindex directory

598

@cindex Windows

599

The files inside a project can be organized into several physical

600

directories on the disk. These directories are displayed under each

601

project node in the @code{Project View}

602

603

@cindex Show absolute paths

604

You can chose whether you want to see the absolute path names for the

605

directories or paths relative to the location of the project. This is done

606

through the @code{Show absolute paths} contextual menu.

607

608

Special nodes are created for object and executables directories. No

609

files are shown for these.

610

611

@cindex Show hidden directories

612

The contextual menu entry @code{Show hidden directories} can be used to filter

613

the directories considered as hidden. This can be used to not display the

614

version control directories like @file{CVS} or @file{.svn} for example.

615

616

@item files

617

@cindex file

618

@cindex file view

619

The source files themselves are stored in the directories, and

620

displayed under the corresponding nodes. Note that

621

only the source files that actually belong to the

622

project (i.e. are written in a language supported by that project and

623

follow its naming scheme) are actually visible.

624

For more information on supported languages, @xref{Supported Languages}.

625

626

A given file might appear multiple times in the @code{Project View},

627

if the project it belongs to is imported by several other projects.

628

629

If you left click on a file and keep the button pressed, you can drop it

630

anywhere in GPS to open an editor at that location.

631

632

@item entities

633

@cindex entity

634

If you open the node for a source file, the file is parsed by one of the

635

fast parsers integrated in GPS so that all entities declared in

636

the project can be shown. These entities are grouped into various

637

categories, which depend on the language. Typical categories include

638

subprograms, packages, types, variables, tasks, @dots{}

639

640

@end table

641

642

Double-clicking on a file, or simple clicking on any entity will open

643

a source editor and display respectively the first line in this file

644

or the line on which the entity is defined.

645

646

You can also drag a file anywhere into GPS. This will open a new editor

647

if the file is not already edited, or move the existing editor otherwise.

648

If you press @key{shift} at the same time, and the file is already edited,

649

a new view of the existing editor is created instead.

650

651

@c ??? Following is currently disabled

652

@c Moving the mouse over the different components displayed on the

653

@c project view will open tooltips with some more information

654

@c depending on the type of component:

655

656

@c @table @b

657

@c @item projects

658

@c The tooltip contains the project full pathname.

659

660

@c @item directories

661

@c The tooltip contains the directory full pathname and the project name in

662

@c which it is defined.

663

664

@c @item files

665

@c The tooltip contains the base filename and the project name in

666

@c which it is defined.

667

668

@c @item entities

669

@c The tooltip contains the entity name and parameters for routines followed

670

@c by the location in the form filename:line where it is declared.

671

@c @end table

672

673

@cindex search

674

@cindex find

675

If you open the search dialog through the @code{Navigate->Find or Replace...}

676

menu, you have the possibility to search for anything in the project view,

677

either a file or an entity. Note that searching for an entity can be slow

678

if you have lots of files, and/or big files.

679

680

@cindex view

681

@cindex locate in project view

682

A contextual menu, named @code{Locate in Project View}, is also provided when

683

inside a source editor. This will automatically search for the first entry for

684

this file in the project view. This contextual menu is also available in other

685

modules, e.g. when selecting a file in the @code{Dependency Browser}.

686

687

@subsection The configuration variables

688

@cindex configuration variable

689

@cindex project variable

690

@cindex variable

691

692

@cindex GNAT

693

@cindex project file

694

@cindex project

695

@noindent

696

As described in the GNAT User's Guide, the project files can be

697

configured through external variables (typically environment

698

variables). This means that e.g. the exact list of source files, or the

699

exact switches to use to compile the application can be changed when

700

the value of these external variables is changed.

701

702

GPS provides a simple access to these variables, through a window

703

called the @code{Scenario View}. These variables are called

704

@code{Configuration Variables}, since they provide various scenarios for

705

the same set of project files.

706

707

@iftex

708

@cindex screen shot

709

@image{scenario-view, 6.7cm}

710

@end iftex

711

712

@ifhtml

713

@cindex screen shot

714

@image{scenario-view}

715

@end ifhtml

716

717

A combo box is displayed in this area for each environment

718

variable the project depends on. The current value of the variable can

719

be set simply by selecting it from the pop-down window that appears

720

when you click on the arrow on the right of the variable name

721

722

@cindex project view

723

New variables can be added through the contextual menu

724

@code{Project->Add Configuration Variable} in the @code{Project View}.

725

The list of possible values for a variable can be changed by clicking on the

726

button on the left of the variable's name.

727

728

Whenever you change the value of one of the variables, the project is

729

automatically recomputed, and the list of source files or directories

730

is changed dynamically to reflect the new status of the

731

project. Starting a new compilation at that point will use the new

732

switches, and all the aspects of GPS are immediately affected

733

according to the new setup.

734

735

@c --------------------------------------------------------------------

736

@node The File View

737

@section The File View

738

@cindex File View

739

@c --------------------------------------------------------------------

740

741

@noindent

742

In addition to the @code{Project View}, GPS also provides a

743

@code{File View} through the @code{Tools->Views->Files} menu.

744

745

@iftex

746

@cindex screen shot

747

@image{file-view, 6.7cm}

748

@end iftex

749

750

@ifhtml

751

@cindex screen shot

752

@image{file-view}

753

@end ifhtml

754

755

In this view, directories are displayed exactly as they are organized

756

physically on the disk (including Windows drives).

757

758

By default, the @code{File View} will display all the files that exist

759

on the disk. Filters can be set through the contextual menu to only

760

show the files and directories that belong to the project

761

hierarchy by using the contextual menu @code{Show files from project only}.

762

763

Each source file can also be explored as described in

764

@ref{The Project View}. Drag and drop of files is also possible from the

765

files view, to conveniently open a file.

766

767

The contextual menu also allow you to create, rename and delete files and

768

directories. Some of those operations are also available from the Project View.

769

770

@c --------------------------------------------------------------------

771

@node The Window View

772

@section The Window View

773

@cindex Window View

774

@c --------------------------------------------------------------------

775

776

@noindent

777

The @code{Window View} displays the currently opened windows.

778

It is opened through the @code{Tools->Views->Windows} menu.

779

780

It can display the opened windows in one of two ways:

781

@itemize @bullet

782

@item Sorted alphabetically

783

@item Organized by notebooks, as in the GPS window itself. This latter view

784

is mostly useful if you have lots of windows open

785

@end itemize

786

787

The mode is selected through the contextual menu.

788

789

You can also choose, through this contextual menu, whether only the source

790

editors should be visible, or whether all windows should be displayed.

791

792

This window allows you to quickly select and focus on a particular window,

793

by clicking on the corresponding line with the left mouse button. If you

794

click and leave the mouse button pressed, this starts a drag and drop

795

operation so that you can also move the window to some other place in the

796

desktop (see the description of the MDI earlier in this document).

797

798

Multiple windows can be selected by clicking with the mouse while pressing

799

the control or shift keys. The Window view provides a contextual menu to

800

easily close all selected windows at once, which is a very fast way to

801

cleanup your desktop after you have finished working on a task.

802

803

@c --------------------------------------------------------------------

804

@node The Outline View

805

@section The Outline View

806

@cindex Outline View

807

@c --------------------------------------------------------------------

808

809

@noindent

810

The Outline View, which you can choose to activate through the

811

@code{Tools->Views->Outline} menu, shows the contents of the current file.

812

813

@iftex

814

@cindex screen shot

815

@image{outline-view, 10.7cm}

816

@end iftex

817

818

@ifhtml

819

@cindex screen shot

820

@image{outline-view}

821

@end ifhtml

822

823

The exact meaning of this depends on the language you are seeing. For

824

Ada, C and C++ files, this is the list of entities that are declared at

825

the global level in your current file (Ada packages, C++ classes,

826

subprograms, Ada types, @dots{}).

827

828

Clicking on any entity in this view will automatically jump to the right

829

line in the file, including if your file has been slightly modified since

830

the outline view was last refreshed.

831

832

To refresh the contents of the view, select the @code{Refresh}

833

entry in the contextual menu (right-click anywhere in the outline view).

834

Alternatively, you can switch temporarily to another window and come back

835

to the same editor, and the outline view will be refreshed.

836

837

There are several preferences associated with the outline view,

838

@xref{Outline Preferences}.

839

840

@c --------------------------------------------------------------------

841

@node The Clipboard View

842

@section The Clipboard View

843

@cindex clipboard view

844

@c --------------------------------------------------------------------

845

846

@noindent

847

GPS has an advanced mechanism for handling copy/paste operations.

848

849

When you select the menus @code{Edit->Copy} or @code{Edit->Cut}, GPS adds the

850

current selection to the clipboard. As opposed to what lots of applications

851

do, it doesn't discard the previous contents of the clipboard, but save it for

852

future usage. It saves a number of entries this way, up to 10 by default.

853

This value is configurable through the @code{Clipboard Size} preference.

854

855

When you select the menu @code{Edit->Paste}, GPS will paste the last entry

856

made in the clipboard at the current location in the editor.

857

858

If you immediately select @code{Edit->Paste Previous}, this newly inserted

859

text will be removed, and GPS will instead insert the second to last entry

860

added to the clipboard. You can keep selecting the same menu to get access

861

to older entries.

862

863

This is a very powerful mechanism, since it means you can copy several distinct

864

lines from a place in an editor, move to an other editor and paste all these

865

separate lines, without having to go back and forth between the two editors.

866

867

The @code{Clipboard View} provides a graphical mean of seeing what is currently

868

stored in the clipboard. It appears as a list of lines, each of which is

869

associated with one level of the clipboard. The text that shows in these lines

870

is the first line of the selection at that level that contains non blank

871

characters. Leading characters are discarded. @code{[...]} is prepended

872

or appended in case the selection has been truncated.

873

874

If you bring the mouse over a line in the @code{Clipboard View}, a tooltip will

875

pop up showing the entire selection corresponding to the line by opposition to

876

the possibly truncated one.

877

878

In addition, one of the lines has an arrow on its left. This indicates the

879

line that will be pasted when you select the menu @code{Edit->Paste}. If you

880

select instead the menu @code{Edit->Paste Previous}, then the line below that

881

one will be inserted instead.

882

883

If you double-click on any of these lines, GPS will insert the corresponding

884

text in the current editor, and make the line you clicked on the current line,

885

so that selecting @code{Edit->Paste} or the equivalent shortcut will now

886

insert that line.

887

888

The contextual menu in the clipboard view provides one entry, which is

889

@code{Append To Previous}. If you select this entry, the select line will

890

be append to the one below, and removed from the clipboard. This means that

891

selection @code{Edit->Paste} will in fact paste the two entries at the same

892

time. This is in particular useful when you want to copy lines from separate

893

places in the initial file, merge them, and then paste them together one or

894

more times later on, through a single operation.

895

896

The Clipboard View content is preserved between GPS sessions. As an exception,

897

huge entries are removed and replaced with an entry saying "[Big entry has

898

been removed]".

899

900

@c --------------------------------------------------------------------

901

@node The Callgraph View

902

@section The Callgraph View

903

@cindex callgraph

904

@c --------------------------------------------------------------------

905

906

@noindent

907

The callgraph view plays a role similar the callgraph browser. They display

908

the same information about entities, but in two different ways: the callgraph

909

view displays the information in a tree, easily navigable and perhaps easier

910

to manipulate when lots of entities are involved; the callgraph browser

911

displays the information as graphical boxes that can be manipulated on the

912

screen, and is best suited to generate a diagram that can be later exported

913

to your own documents.

914

915

This callgraph view is used to display the information about what subprograms

916

are called by a given entity, and, opposite, what entities are calling a

917

given entity.

918

919

Some references might be reported with an additional " (dispatching)" text.

920

In such a case, this indicates that the call to the entity is not explicit

921

in the sources, but could occur through dynamic dispatching. This of course

922

depends on what arguments are passed to the caller at run time, and it is

923

possible that the subprogram is in fact never dispatched to.

924

925

This view is automatically displayed when you select one of the contextual

926

menus @code{... calls} and

927

@code{... is called by}. Every time you select one of

928

these menus, a new view is opened to display that entity.

929

930

Whenever you expand a node from the tree by clicking on the small expander

931

arrow on the left of the line, further callgraph information is computed for

932

the selected entity, which makes it very easy to get information for a full

933

callgraph tree.

934

935

Closing and expanding a node again will recompute the callgraph for the

936

entity.

937

938

On the right side of the main tree, a list displays the locations of calls for

939

the selected entity. Clicking on entries in this list opens editors showing

940

the corresponding location.

941

942

The Callgraph View supports keyboard navigation: @code{Up} and @code{Down}

943

keys navigate between listed locations, @code{Left} collapses the current

944

level, @code{Right} expands the current level, and @code{Return} jumps to the

945

currently selected location.

946

947

All open callgraph views are automatically saved in the desktop, and restored

948

the next time you restart GPS. However, the information displayed in these

949

might no longer be accurate at this stage, since it shows the status of the

950

callgraph during the last GPS session.

951

952

@c --------------------------------------------------------------------

953

@node Bookmarks

954

@section Bookmarks

955

@cindex bookmark

956

@c --------------------------------------------------------------------

957

958

@noindent

959

Bookmarks are a convenient way to remember places in your code or in your

960

environment so that you can go back to them at any point in the future.

961

These bookmarks are saved automatically whenever they are modified, and

962

restored when GPS is reloaded, so that they exist across GPS sessions.

963

964

Bookmarks will automatically remember the exact location in an editor, not

965

in terms of line/column, but in terms of which word they point to. If you

966

modify the file through GPS, the bookmark will be automatically updated to

967

keep refering to the same place. Likewise if you close and reopen the file.

968

However, when the file is modified outside of GPS, the bookmark will not be

969

aware of that change, and will thus reference another place in the file.

970

971

The menu @code{Edit->Create Bookmark} allows you to create a bookmark

972

at the current location (either in the editor, or the browser for instance).

973

974

All the bookmarks you have created will be visible in the

975

@code{Tools->Views->Bookmarks} window. Clicking on the small icon to the left

976

side of each line will immediately jump to that bookmark.

977

978

You can rename a bookmark so that it is easier to remember what it refers to.

979

To do so, open the Bookmarks window, and click twice on the line of the

980

bookmark. This will change the way the name is displayed, so that you can edit

981

it in place. Press @key{enter} when you are done modifying the name.

982

983

You can delete an existing bookmark by right clicking on the line, and

984

select @code{Delete bookmark} in the contextual menu.

985

986

@c --------------------------------------------------------------------

987

@node The Messages Window

988

@section The Messages Window

989

@cindex messages

990

@cindex messages window

991

@c --------------------------------------------------------------------

992

993

@cindex build

994

@cindex errors

995

@noindent

996

The Messages window is used by GPS to display information and feedback

997

about operations, such as build output, information about processes

998

launched, error messages.

999

1000

@iftex

1001

@cindex screen shot

1002

@image{messages, 11.7cm}

1003

@end iftex

1004

1005

@ifhtml

1006

@cindex screen shot

1007

@image{messages}

1008

@end ifhtml

1009

1010

This is a read-only window, which means that only output is available,

1011

no input is possible.

1012

1013

@cindex execution window

1014

@cindex execution

1015

@cindex shell window

1016

@cindex shell

1017

For an input/output window, see @ref{The Execution Window} and also

1018

@ref{The Shell and Python Windows}.

1019

1020

@c --------------------------------------------------------------------

1021

@node The Shell and Python Windows

1022

@section The Shell and Python Windows

1023

@cindex python window

1024

@cindex shell

1025

@cindex shell window

1026

@cindex interactive command

1027

@cindex command

1028

@c --------------------------------------------------------------------

1029

1030

@noindent

1031

These windows give access to the various scripting languages supported

1032

by GPS, and allow you to type commands such as editing a file or

1033

compiling without using the menu items or the mouse.

1034

1035

Some of these windows, especially the python window, might not be

1036

visible in your version of GPS, if GPS wasn't compiled with the

1037

support for that specific scripting language.

1038

1039

To show the shell consoles, select the menu @code{Tools}.

1040

1041

See @ref{Scripting GPS} for more information on using

1042

scripting languages within GPS.

1043

1044

@iftex

1045

@cindex screen shot

1046

@image{shell-window, 11.7cm}

1047

@end iftex

1048

1049

@ifhtml

1050

@cindex screen shot

1051

@image{shell-window}

1052

@end ifhtml

1053

1054

@cindex key

1055

You can use the @key{up} and @key{down} keys to navigate through the

1056

history of commands.

1057

1058

@c --------------------------------------------------------------------

1059

@node The Locations Tree

1060

@section The Locations Tree

1061

@cindex location

1062

@cindex locations tree

1063

@c --------------------------------------------------------------------

1064

1065

@cindex search

1066

@cindex compilation

1067

@cindex build

1068

@noindent

1069

The Location Tree is filled whenever GPS needs to display a list of

1070

locations in the source files (typically, when performing a global

1071

search, compilation results, and so on).

1072

1073

@iftex

1074

@cindex screen shot

1075

@image{locations-view, 11.7cm}

1076

@end iftex

1077

1078

@ifhtml

1079

@cindex screen shot

1080

@image{locations-view, 12.7cm}

1081

@end ifhtml

1082

1083

@cindex category

1084

@cindex file

1085

The Location Tree shows a hierarchy of categories, which contain

1086

files, which contain locations. Clicking on a location item will bring

1087

up a file editor at the requested place. Right-clicking on file or

1088

category items brings up a contextual menu allowing you to remove the

1089

corresponding node from the view.

1090

1091

Every time a new category is created, as a result of a compilation or a

1092

search operation for instance, the first entry of that category is

1093

automatically selected, and the corresponding editor opened. This behavior

1094

can be controlled through a preference @code{Jump To First Location}.

1095

1096

@cindex key

1097

@cindex menu

1098

To navigate through the next and previous location (also called @code{Tag}),

1099

you can use the menu items @code{Navigate->Previous Tag} and

1100

@code{Navigate->Next Tag}, or the corresponding key bindings.

1101

1102

Left-clicking on a line in the Location Tree brings up a contextual

1103

menu with the following entries:

1104

1105

@table @b

1106

@item Sort by subcategory

1107

Toggle the sorting of the entries by sub-categories. This is useful,

1108

for example, for separating the warnings from the errors in the build

1109

results.

1110

1111

@item Expand category

1112

Expand all the files in the current categories.

1113

1114

@item Collapse all

1115

Collapse all the categories in the Locations View

1116

1117

@item Jump to location

1118

Open the location contained in the message, if any.

1119

1120

@item Clear Locations View

1121

Remove all entries from the Locations View.

1122

1123

@end table

1124

1125

In some cases, a wrench icon will be associated on the left of a compilation

1126

message. See @ref{Code Fixing} for more information on how to make advantage

1127

of this icon.

1128

1129

@c --------------------------------------------------------------------

1130

@node The Execution Window

1131

@section The Execution Window

1132

@cindex execution

1133

@cindex execution window

1134

@c --------------------------------------------------------------------

1135

1136

@cindex run

1137

@noindent

1138

Each time a program is launched using the menu @code{Build->Run}, a new

1139

execution window is created to provide input and output for this program.

1140

1141

In order to allow post mortem analysis and copy/pasting, the execution

1142

windows are not destroyed when the application terminates.

1143

1144

@cindex key

1145

@cindex menu

1146

To close an execution window, click on the cross icon on the top right corner

1147

of the window, or use the menu @code{File->Close}, or the menu

1148

@code{Window->Close} or the key binding @key{Ctrl-W}.

1149

1150

If you close the execution window while the application is still running,

1151

a dialog window is displayed, asking whether you want to kill the application,

1152

or to cancel the close operation.

1153

1154

@c --------------------------------------------------------------------

1155

@node The Status Line

1156

@section The Status Line

1157

@cindex status

1158

@cindex status line

1159

@cindex status bar

1160

@cindex progress bar

1161

@c --------------------------------------------------------------------

1162

1163

@noindent

1164

The status line is composed of two areas: on the left a status bar and

1165

on the right one or several progress bars.

1166

1167

@cindex messages

1168

The status bar is used to display temporary information about GPS

1169

operations. Note that most of the information GPS displays can be found

1170

in the @code{Messages} window.

1171

1172

@cindex build

1173

The progress bars are used to display information about on going

1174

operations such as builds, searches, or VCS commands. These tasks

1175

operate in the background, and can be paused/resumed via a contextual

1176

menu. This contextual menu is available by right-clicking on the

1177

progress bars themselves or on the corresponding lines in the Task

1178

Manager. See @ref{The Task Manager}

1179

1180

@c --------------------------------------------------------------------

1181

@node The Task Manager

1182

@section The Task Manager

1183

@cindex tasks

1184

@cindex background tasks

1185

@cindex task manager

1186

@c --------------------------------------------------------------------

1187

1188

@noindent

1189

The Task Manager window lists all the currently running GPS operations

1190

that run in the background, such as builds, searches or VCS commands.

1191

1192

For each of these tasks, the Task Manager shows the status of the

1193

task, and the current progress. The execution of theses tasks can be

1194

suspended using a contextual menu, brought up by right-clicking on a

1195

line.

1196

1197

When exiting GPS, if there are tasks running in the Task Manager, a window

1198

will display those tasks. You can also bring up a contextual menu on the

1199

items in this window.

1200

You can force the exit at any time by pressing the confirmation button, which

1201

will kill all remaining tasks, or continue working in GPS by pressing the

1202

Cancel button.

1203

1204

@iftex

1205

@cindex screen shot

1206

@image{task-manager, 9cm}

1207

@end iftex

1208

1209

@ifhtml

1210

@cindex screen shot

1211

@image{task-manager}

1212

@end ifhtml

1213

1214

@c --------------------------------------------------------------------

1215

@node Online Help

1216

@chapter Online Help

1217

@cindex Online help

1218

@cindex help

1219

@cindex HTML

1220

@c --------------------------------------------------------------------

1221

1222

@menu

1223

* The Help Menu::

1224

* Adding New Help Files::

1225

@end menu

1226

1227

@noindent

1228

By default when you start GPS, the working area contains a welcome page

1229

giving a few starting points in the online help.

1230

1231

Online help for the GNAT tools is available from the @code{Help} menu item.

1232

GPS launches an external html browser to view these pages. (See

1233

@ref{The Preferences Dialog} on how to configure this under Unix. Under

1234

Windows systems, the default HTML browser is used.)

1235

1236

@node The Help Menu

1237

@section The Help Menu

1238

@noindent

1239

The Help menu item provides the following entries:

1240

1241

@table @b

1242

1243

@item Welcome

1244

Open the GPS Welcome page.

1245

1246

@item Open HTML file...

1247

Open a file selection dialog to load an HTML file.

1248

1249

@item Contents

1250

Open a special HTML file that contains links for all the

1251

documentation files currently registered in GPS, @xref{Adding New Help Files}.

1252

1253

@item About

1254

Display a dialog giving information about the versions of GPS and GNAT used:

1255

1256

@iftex

1257

@cindex screen shot

1258

@image{about, 8.7cm}

1259

@end iftex

1260

1261

@ifhtml

1262

@cindex screen shot

1263

@image{about}

1264

@end ifhtml

1265

1266

@end table

1267

1268

This menu contains a number of additional entries, depending on what

1269

documentation packages were installed on your system. See the next

1270

section to see how to add new help files.

1271

1272

@node Adding New Help Files

1273

@section Adding New Help Files

1274

@cindex gps_index.xml

1275

@noindent

1276

GPS will search for the help files in the list of directories set in

1277

the environment variable @code{GPS_DOC_PATH} (a colon-separated list

1278

of directories on Unix systems, or semicolon-separated list of

1279

directories on Windows systems). In addition, the

1280

default directory @code{<prefix>/share/doc/gps/html} is also searched. If the

1281

file cannot be found in any of these directories, the corresponding

1282

menu item will be disabled.

1283

1284

The environment variable @code{GPS_DOC_PATH} can either be set by each

1285

user in his own environment, or can be set system-wide by modifying

1286

the small wrapper script @file{gps} itself on Unix systems.

1287

1288

It can also be set programmatically through the GPS shell or any of the

1289

scripting languages. This is done with

1290

1291

@smallexample

1292

GPS.add_doc_directory ("/home/foo")

1293

@end smallexample

1294

1295

The specific list of files shown in the menus is set by reading the

1296

index files in each of the directories in @code{GPS_DOC_PATH}. These

1297

index files must be called @file{gps_index.xml}.

1298

1299

The format of these index files is specified in @pxref{Adding documentation}.

1300

1301

@c --------------------------------------------------------------------

1302

@node Multiple Document Interface

1303

@chapter Multiple Document Interface

1304

@cindex MDI

1305

@cindex Multiple Document Interface

1306

@cindex window manager

1307

@cindex work space

1308

@c --------------------------------------------------------------------

1309

1310

@menu

1311

* Selecting Windows::

1312

* Closing Windows::

1313

* Splitting Windows::

1314

* Floating Windows::

1315

* Moving Windows::

1316

@end menu

1317

1318

@noindent

1319

All the windows that are part of the GPS environment are under control

1320

of what is commonly called a multiple document interface (MDI for

1321

short). This is a common paradigm on windowing systems, where related

1322

windows are put into a bigger window which is itself under control of

1323

the system or the windows manager.

1324

1325

This means that, by default, no matter how many editors, browsers,

1326

views, @dots{} windows you have opened, your system will still see only

1327

one window (On Windows systems, the task bar shows only one

1328

icon). However, you can organize the GPS windows exactly the way you

1329

want, all inside the GPS main window.

1330

1331

This section will show the various capacities that GPS provides to

1332

help you organize your workspace.

1333

1334

@c --------------------------------------------------------------------

1335

@node Selecting Windows

1336

@section Selecting Windows

1337

@cindex window selection

1338

@c --------------------------------------------------------------------

1339

1340

@noindent

1341

At any time, there is only one selected window in GPS (the @b{active

1342

window}). You can select a window either by clicking in its title bar,

1343

which will then get a different color, or by selecting its name in the

1344

menu @code{Window}.

1345

1346

Alternatively, windows can be selected with the keyboard. By default,

1347

the selection key is @key{Alt-Tab}. When you press it, a temporary

1348

dialog is popped-up on the screen, with the name of the window that

1349

will be selected when the key is released. If you press the selection

1350

key multiple times, this will iterate over all the windows currently

1351

open in GPS.

1352

1353

This interactive selection dialog is associated with a filter,

1354

displayed below the name of the selected window. If you maintain

1355

@key{Alt} pressed while pressing other keys than @key{Tab}, this

1356

will modify the current filter. From then on, pressing

1357

@key{Alt-Tab} will only iterate through those windows that match

1358

the filter.

1359

1360

The filter is matched by any window whose name contains the letter you

1361

have typed. For instance, if you are currently editing the files

1362

@file{unit1.adb} and @file{file.adb}, pressing @key{t} will only leave

1363

@file{unit1.adb} selectable.

1364

1365

@c --------------------------------------------------------------------

1366

@node Closing Windows

1367

@section Closing Windows

1368

@cindex close

1369

@c --------------------------------------------------------------------

1370

1371

@cindex title bar

1372

@noindent

1373

Wherever the windows are displayed, they are always closed in the same

1374

manner. In the right side of the title bar of the window, one small

1375

button is displayed, looking like a cross. Clicking on

1376

this button will close the window.

1377

1378

An alternative way to close the window is to double-click on the icon

1379

to the left of the title bar of the window. Not all windows have such

1380

an icon, but editors do for instance.

1381

1382

When a window is closed, the focus is given to the window of the same

1383

part of the MDI (each of the docks or the middle area) that previously

1384

had the focus. Therefore, if you simply open an editor as a result of

1385

a cross-reference query, you can simply close that editor to go back

1386

to where you were before.

1387

1388

Alternatively, you can also select the window by clicking anywhere in

1389

its title bar, and then select the menu @code{Window->Close}

1390

1391

@c --------------------------------------------------------------------

1392

@node Splitting Windows

1393

@section Splitting Windows

1394

@cindex Splitting

1395

@c --------------------------------------------------------------------

1396

1397

@noindent

1398

The window in the central area of the MDI can be split at will, through

1399

any combination of horizontal and vertical splits.

1400

This feature requires at least two windows (text editors, browsers, @dots{})

1401

to be superimposed in the central area. Selecting either the

1402

@code{Window->Split Horizontally} or @code{Window->Split Vertically} menus

1403

will then split the selected window in two. In the left (resp. top) pane,

1404

the currently selected window will be left on its own. The rest of the

1405

previously superimposed windows will be put in the right (resp. bottom)

1406

pane. You can then in turn split these remaining windows to achieve any

1407

layout you want.

1408

1409

All split windows can be resized interactively by dragging the handles that

1410

separate them. A preference (menu

1411

@code{Edit->Preferences}) controls whether this resizing is done in opaque

1412

mode or border mode. In the latter case, only the new handle position will

1413

be displayed while the mouse is dragged.

1414

1415

You may want to bind the key shortcuts to the menus

1416

@code{Window->Split Horizontally}

1417

as well as @code{Window->Split Vertically} using

1418

the key manager. In addition, if you want to

1419

achieve an effect similar to e.g. the standard Emacs behavior (where

1420

@key{control-x 2} splits a window horizontally, and @key{control-x 3} splits

1421

a window vertically), you can use the key manager

1422

(@pxref{The Key Manager Dialog}).

1423

1424

Several editors or browsers can be put in the same area of the MDI. In such

1425

a case, they will be grouped together in a notebook widget, and you can

1426

select any of them by clicking on the corresponding tab. Note that if there

1427

are lots of windows, two small arrows will appear on the right of the tabs.

1428

Clicking on these arrows will show the remaining tabs.

1429

1430

In some cases GPS will change the color and size of the title (name) of a

1431

window in the notebook tab. This indicates that the window content has been

1432

updated, but the window wasn't visible. Typically, this is used to indicate

1433

that new messages have been written in the messages or console window.

1434

1435

@c --------------------------------------------------------------------

1436

@node Floating Windows

1437

@section Floating Windows

1438

@cindex floating

1439

@cindex top level

1440

@c --------------------------------------------------------------------

1441

1442

@noindent

1443

Although the MDI, as described so far, is already extremely flexible,

1444

it is possible that you prefer to have several top-level windows under

1445

direct control of your system or window manager. This would be the

1446

case for instance if you want to benefit from some extra possibilities

1447

that your system might provide (virtual desktops, different window

1448

decoration depending on the window's type, transparent windows, @dots{}).

1449

1450

GPS is fully compatible with this behavior, since windows can also be

1451

@b{floating windows}. Any window that is currently embedded in the MDI

1452

can be made floating at any time, simply by selecting the window and

1453

then selecting the menu @code{Window->Floating}. The window will then

1454

be detached, and can be moved anywhere on your screen, even outside of

1455

GPS's main window.

1456

1457

@cindex menu

1458

There are two ways to put a floating window back under control of GPS.

1459

The more general method is to select the window through its title in

1460

the menu @code{Window}, and then unselect @code{Window->Floating}.

1461

1462

@cindex preferences

1463

The second method assumes that the preference @b{Destroy Floats} in

1464

the menu @code{Edit->Preferences} has been set to false. Then, you can

1465

simply close the floating window by clicking in the appropriate title

1466

bar button, and the window will be put back in GPS. If you actually

1467

want to close it, you need to click once again on the cross button in

1468

its title bar.

1469

1470

@cindex all floating

1471

A special mode is also available in GPS, where all windows are

1472

floating. The MDI area in the main window becomes invisible. This can be

1473

useful if you rely on windows handling facilities supported by your

1474

system or window manager but not available in GPS. This might also be

1475

useful if you want to have windows on various virtual desktops, should

1476

your window manager support this.

1477

1478

This special mode is activated through a preference (menu

1479

@code{Edit->Preferences}). This preference is entitled @b{All

1480

Floating}.

1481

1482

@c --------------------------------------------------------------------

1483

@node Moving Windows

1484

@section Moving Windows

1485

@cindex moving

1486

@c --------------------------------------------------------------------

1487

1488

@noindent

1489

As we have seen, the organization of windows can be changed at any time

1490

by selecting a notebook containing several editors or browsers, and selecting

1491

one of the Split menus in the @code{Window} menu.

1492

1493

@cindex drag-n-drop

1494

A more intuitive method is also provided, based on

1495

the drag-and-drop paradigm. The idea is simply to select a window,

1496

wherever it is, and then, by clicking on it and moving the mouse while

1497

keeping the left button pressed, drop it anywhere else inside GPS.

1498

1499

Selecting an item so that it can be dragged is done simply by clicking

1500

with the left mouse button in its title bar, and keep the button

1501

pressed while moving the mouse.

1502

1503

If the window is inside a notebook, you can also choose to select the

1504

notebook tab to start dragging the window around. In such a case, the windows

1505

within the notebook can also be reordered: select the tab, then start moving

1506

left or right to the new position the window should have. Note that your mouse

1507

must remain within the tab area, since otherwise GPS will enter in the mode

1508

where the window can be put in other notebooks.

1509

1510

While you keep the mouse button pressed, and move the mouse around, the

1511

selected drop area is highlighted with a dashed border. This shows precisely

1512

where the window would be put if you were to release the mouse button at

1513

that point.

1514

1515

Here are the various places where a window can be dropped:

1516

1517

@table @b

1518

@item Inside the MDI

1519

The location of the current window is indicated by a dashed rectangle, and

1520

the window you are dragging will be positioned at the same location as that

1521

rectangle: either on top of the window on which you dropped it (therefore they

1522

will both be put inside a notebook), or to one of the sides of that window,

1523

splitting as needed.

1524

1525

@item System window

1526

If you drop a window outside of GPS (for

1527

instance, on the background of your screen), the window will be floated.

1528

1529

@end table

1530

1531

If you maintain the @key{shift} key pressed while dropping the window,

1532

this might result in a copy operation instead of a simple move. For instance,

1533

if you are dropping an editor, a new view of the same editor will be created,

1534

resulting in two views present in GPS: the original one is left at its initial

1535

location, and a second view is created at the new location.

1536

1537

If you maintain the @key{control} key pressed while dropping the window,

1538

all the windows that were in the same notebook are moved, instead of the

1539

single one you selected. This is the fastest way to move a group of windows

1540

to a new location, instead of moving them one by one.

1541

1542

@c --------------------------------------------------------------------

1543

@node Editing Files

1544

@chapter Editing Files

1545

@cindex editing

1546

@c --------------------------------------------------------------------

1547

1548

@menu

1549

* General Information::

1550

* Editing Sources::

1551

* The File Selector::

1552

* Menu Items::

1553

* Recording and replaying macros::

1554

* Contextual Menus for Editing Files::

1555

* Handling of case exceptions::

1556

* Refactoring::

1557

* Using an External Editor::

1558

* Using the Clipboard::

1559

* Saving Files::

1560

* Remote Files::

1561

@end menu

1562

1563

@c --------------------------------------------------------------------------

1564

@node General Information

1565

@section General Information

1566

@c --------------------------------------------------------------------------

1567

1568

@noindent

1569

Source editing is one of the central parts of GPS, giving in turn access

1570

to many other functionalities, including extended source navigation and

1571

source analyzing tools.

1572

1573

@iftex

1574

@cindex screen shot

1575

@image{source-editor, 12.7cm}

1576

@end iftex

1577

1578

@ifhtml

1579

@cindex screen shot

1580

@image{source-editor}

1581

@end ifhtml

1582

1583

The integrated source editor provides all the usual capabilities found in

1584

integrated environments, including:

1585

1586

@table @b

1587

@item A title bar

1588

Showing the full name of the file including path information.

1589

1590

@item Line number information

1591

This is the left area of the source editor. Line numbers can be disabled

1592

from the preferences. @xref{The Preferences Dialog}.

1593

Note that this area can also display additional information, such as

1594

the current line of execution when debugging, or cvs annotations.

1595

1596

@item A scrollbar

1597

Located on the right of the editor, it allows you to scroll through the source

1598

file.

1599

1600

@item A Speed Column

1601

This column, when visible, is located on the left of the editor. It allows you

1602

to view all the highlighted lines in a file, at a glance. For example, all the

1603

lines containing compilation errors are displayed in the Speed Column.

1604

See @ref{The Preferences Dialog} for information on how to customize the

1605

behavior of the Speed Column.

1606

1607

@item A status bar

1608

Giving information about the file. It is divided in two sections, one

1609

on the left and one on the right of the window.

1610

1611

@table @i

1612

@item The left section

1613

1614

The first box on the left shows the current subprogram name for languages

1615

that support this capability. Currently @code{Ada}, @code{C} and @code{C++}

1616

have this ability. See @ref{The Preferences Dialog} to enable or

1617

disable this feature.

1618

1619

@item The right section

1620

1621

If the file is maintained under version control, and version control is

1622

supported and enabled in GPS, the first box on the left will show VCS

1623

information on the file: the VCS kind (e.g. @i{CVS}), followed by the revision

1624

number, and if available, the status of the file.

1625

1626

The second box shows the current editing mode. This is either

1627

@i{Insert} or @i{Overwrite} and can be changed using the insert

1628

keyboard keys by default.

1629

1630

The third box shows the writable state of the file.

1631

You can change this state by clicking on the label directly: this will

1632

switch between @i{Writable} and @i{Read Only}.

1633

Note that this will not change the permissions of the file on disk, it will

1634

only change the writable state of the source editor within GPS.

1635

1636

When trying to save a file which is read only on the disk, GPS will ask for

1637

confirmation, and if possible, will force saving of the file, keeping its read

1638

only state.

1639

1640

The fourth box shows whether the file has been modified since the last

1641

save. The three possible states are:

1642

1643

@table @i

1644

@item Unmodified

1645

The file has not been modified since the file has been loaded or saved.

1646

1647

@item Modified

1648

The file has been modified since last load or save. Note that if you undo all

1649

the editing operations until the last save operation, this label will change

1650

to @i{Unmodified}.

1651

1652

@item Saved

1653

The file has been saved and not modified since.

1654

1655

@end table

1656

1657

The fifth box displays the position of the cursor in the file by a line and

1658

a column number.

1659

@end table

1660

1661

@item A contextual menu

1662

Displayed when you right-click on any area of the source editor.

1663

See in particular @ref{Contextual Menus for Source Navigation}

1664

for more details.

1665

1666

@item Syntax highlighting

1667

Based on the programming language associated with the file, reserved words

1668

and languages constructs such as comments and strings are highlighted in

1669

different colors and fonts. See @ref{The Preferences Dialog} for a list of

1670

settings that can be customized.

1671

1672

By default, GPS knows about many languages. You can also easily add support

1673

for other languages through XML files. Most languages supported by GPS

1674

will provide syntax highlighting in the editor.

1675

1676

@item Automatic indentation

1677

@cindex indentation

1678

When enabled, lines are automatically indented each time you press the

1679

@key{Enter} key, or by pressing the indentation key.

1680

The indentation key is @key{Ctrl-Tab} by default, and can be changed in the

1681

key manager dialog, @xref{The Key Manager Dialog}.

1682

1683

If a set of lines is selected when you press the indentation key, this whole

1684

set of lines will be indented.

1685

1686

@item Tooltips

1687

@cindex tooltip

1688

When you leave the mouse over a word in the source editor, a small window

1689

will automatically pop up if there are relevant contextual information to

1690

display about the word.

1691

1692

The type of information displayed depends on the current state of GPS.

1693

1694

In normal mode, the entity kind and the location of declaration is

1695

displayed when this information is available. That is, when the

1696

cross-reference information about the current file has been

1697

generated. If there is no relevant information, no tooltip is displayed.

1698

See @ref{Support for Cross-References} for more information.

1699

1700

In addition, the documentation for the entity is displayed. This is the block

1701

of comments just before or just after the entity's declaration of body. There

1702

mustn't be any blank line between the two. For instance, the following are

1703

valid documentation for Ada and C:

1704

1705

@smallexample

1706

-- A comment for A

1707

A : Integer;

1708

1709

B : Integer;

1710

-- A comment for B

1711

1712

C : Integer;

1713

1714

-- Not a comment for C, there is a blank linke

1715

@end smallexample

1716

1717

In debugging mode, the value of the variable under the mouse is displayed in

1718

the pop up window if the variable is known to the debugger.

1719

Otherwise, the normal mode information is displayed.

1720

1721

You can disable the automatic pop up of tool tips in the Editor section of

1722

the preferences dialog. @xref{The Preferences Dialog}.

1723

1724

@item Code completion

1725

@cindex completion

1726

1727

GPS provides two kinds of code completion: a smart code completion based

1728

on semantic information (see @ref{Smart Completion}), and a text completion.

1729

1730

It is useful when editing a file and using often the same words to get

1731

automatic word completion. This is possible by typing the @key{Ctrl-/} key

1732

combination (customizable through the key manager dialog) after a partial

1733

word: the next possible completion will be inserted in the editor. Typing this

1734

key again will cycle through the list of possible completions.

1735

1736

Text completions are searched in all currently open source files, by first

1737

looking at the closest words and then looking further in the source as needed.

1738

1739

@item Delimiter highlighting

1740

@cindex delimiter

1741

When the cursor is moved before an opening delimiter or after a closing

1742

delimiter, then both delimiters will be highlighted. The following characters

1743

are considered delimiters: ()[]@{@}.

1744

You can disable highlighting of delimiters in the preferences.

1745

1746

You can also jump to a corresponding delimiter by using the @key{Ctrl-'} key,

1747

that can be configured in the preferences. Typing twice on this key will move

1748

the cursor back to its original position.

1749

1750

@item Current line highlighting

1751

@cindex current line

1752

You can configure the editor to highlight the current line with a certain

1753

color. @xref{The Preferences Dialog}.

1754

1755

@item Current block highlighting

1756

@cindex block

1757

If this preference is enabled, the editor will highlight the current block

1758

of code, e.g. the current @code{begin...end} block, or loop statement,

1759

etc@dots{}

1760

1761

The block highlighting will also take into account the changes made in

1762

your source code, and will recompute automatically the current block when

1763

needed.

1764

1765

This capability is currently implemented for Ada, C and C++ languages.

1766

1767

@item Block folding

1768

@cindex block

1769

When enabled, the editor will display @code{-} icons on the left side,

1770

corresponding to the beginning of subprograms. If you click on one of these

1771

icons, all the lines corresponding to this subprogram are hidden, except

1772

the first one. As for the block highlighting, these icons are recomputed

1773

automatically when you modify your sources and are always kept up to date.

1774

1775

This capability is currently implemented for Ada, C and C++ languages.

1776

1777

@c @item Automatic syntax checking

1778

@c @cindex automatic syntax checking

1779

@c When enabled, the editor will perform on-the-fly syntax checks, and will

1780

@c underline the errors in your file as you type.

1781

1782

@item Auto save

1783

@cindex auto save

1784

You can configure the editor to periodically save modified files.

1785

See @ref{autosave delay} for a full description of this capability.

1786

1787

@end table

1788

1789

@cindex emacs

1790

GPS also integrates with existing third party editors such as

1791

@code{Emacs} or @code{vi}. @xref{Using an External Editor}.

1792

1793

@c --------------------------------------------------------------------------

1794

@node Editing Sources

1795

@section Editing Sources

1796

@cindex editing

1797

@cindex source file

1798

@c --------------------------------------------------------------------------

1799

1800

@subsection Key bindings

1801

@cindex key

1802

@noindent

1803

In addition to the standard keys used to navigate in the editor (up, down,

1804

right, left, page up, page down), the integrated editor provides a number of

1805

key bindings allowing easy navigation in the file.

1806

1807

In addition, there are several ways to define new key bindings, see

1808

@ref{Defining text aliases} and @ref{Binding actions to keys}.

1809

1810

@table @key

1811

@item Ctrl-Shift-u

1812

@cindex hexadecimal

1813

@cindex ASCII

1814

Pressing these three keys and then holding Ctrl-Shift allow you to enter

1815

characters using their hexadecimal

1816

value. For example, pressing @key{Ctrl-Shift-u-2-0} will insert a space

1817

character (ASCII 32, which is 20 in hexadecimal).

1818

1819

@item Ctrl-x / Shift-delete

1820

Cut to clipboard

1821

1822

@item Ctrl-c / Ctrl-insert

1823

Copy to clipboard

1824

1825

@item Ctrl-v / Shift-insert

1826

Paste from clipboard

1827

1828

@item Ctrl-s

1829

Save file to disk

1830

1831

@item Ctrl-z

1832

Undo previous insertion/deletion

1833

1834

@item Ctrl-r

1835

Redo previous insertion/deletion

1836

1837

@item Insert

1838

Toggle overwrite mode

1839

1840

@item Ctrl-a

1841

Select the whole file

1842

1843

@item Home / Ctrl-Pgup

1844

Go to the beginning of the line

1845

1846

@item End / Ctrl-Pgdown

1847

Go to the end of the line

1848

1849

@item Ctrl-Home

1850

Go to the beginning of the file

1851

1852

@item Ctrl-End

1853

Go to the end of the file

1854

1855

@item Ctrl-up

1856

Go to the beginning of the line, or to the previous line if already at the

1857

beginning of the line.

1858

1859

@item Ctrl-down

1860

Go to the end of the line, or to the beginning of the next line if already at

1861

the end of the line.

1862

1863

@item Ctrl-delete

1864

Delete end of the current word.

1865

1866

@item Ctrl-backspace

1867

Delete beginning of the current word.

1868

1869

@end table

1870

1871

@c --------------------------------------------------------------------------

1872

@node The File Selector

1873

@section The File Selector

1874

@cindex file selector

1875

@c --------------------------------------------------------------------------

1876

1877

@cindex Windows

1878

@noindent

1879

The file selector is a dialog used to select a file. Under Windows, the

1880

default is to use the standard file selection widget. Under other platforms,

1881

the file selector is a built-in dialog:

1882

1883

@iftex

1884

@cindex screen shot

1885

@image{open-file, 10.7cm}

1886

@end iftex

1887

1888

@ifhtml

1889

@cindex screen shot

1890

@image{open-file}

1891

@end ifhtml

1892

1893

@noindent

1894

This dialog provides the following areas and capabilities:

1895

1896

@itemize @bullet

1897

@item A tool bar on the top composed of five buttons giving access to common

1898

navigation features:

1899

1900

@table @b

1901

@item left arrow

1902

go back in the list of directories visited

1903

1904

@item right arrow

1905

go forward

1906

1907

@item up arrow

1908

go to parent directory

1909

1910

@item refresh

1911

refresh the contents of the directory

1912

1913

@item home

1914

go to home directory (value of the HOME environment variable, or @code{/} if

1915

not defined)

1916

@end table

1917

1918

@item A list with the current directory and the last directories explored.

1919

You can modify the current directory by modifying the text entry and hitting

1920

@key{Enter}, or by clicking on the right arrow and choose a previous directory

1921

in the pop down list displayed.

1922

1923

@item A directory tree. You can open or close directories by clicking on the

1924

@code{+} and @code{-} icons on the left of the directories, or

1925

navigate using the keyboard keys: @key{up} and @key{down} to select the

1926

previous or the next directory, @key{+} and @key{-} to expand and collapse

1927

the current directory, and @key{backspace} to select the parent directory.

1928

1929

@item A file list. This area lists the files contained in the selected

1930

directory. If a filter is selected in the filter area, only the relevant

1931

files for the given filter are displayed. Depending on the context, the

1932

list of files may include additional information about the files, e.g. the

1933

kind of a file, its size, etc@dots{}

1934

1935

@item A filter area. Depending on the context, one or several filters are

1936

available to select only a subset of files to display. The filter

1937

@i{All files} which is always available will display all files in the

1938

directory selected.

1939

1940

@item A file name area. This area will display the name of the current file

1941

selected, if any.

1942

You can also type a file or directory name directly, and complete the name

1943

automatically by using the @key{Tab} key.

1944

1945

@item A button bar with the @code{OK} and @code{Cancel} buttons.

1946

When you have selected the right file, clock on @code{OK} to confirm, or

1947

click on @code{Cancel} at any time to cancel and close the file selection.

1948

1949

@end itemize

1950

1951

@c --------------------------------------------------------------------------

1952

@node Menu Items

1953

@section Menu Items

1954

@cindex menu

1955

@c --------------------------------------------------------------------------

1956

1957

@noindent

1958

The main menus that give access to extended functionalities related to

1959

source editing are described in this section.

1960

1961

@subsection The File Menu

1962

@anchor{The File Menu}

1963

@noindent

1964

1965

@table @b

1966

@item New

1967

@cindex new file

1968

Open a new untitled source editor.

1969

No syntax highlighting is performed until the file is saved, since GPS needs

1970

to know the file name in order to choose the programming language associated

1971

with a file.

1972

1973

@cindex Ada

1974

When you save a new file for the first time, GPS will ask you to enter the

1975

name of the file. In case you have started typing Ada code, GPS will try

1976

to guess based on the first main entity in the editor and on the current

1977

naming scheme, what should be the default name of this new file.

1978

1979

@item New View

1980

@cindex new view

1981

@cindex view

1982

Create a new view of the current editor. The new view shares the same

1983

contents: if you modify one of the source views, the other view is updated

1984

at the same time. This is particularly useful when you want to display two

1985

separate parts of the same file, for example a function spec and its body.

1986

1987

A new view can also be created by keeping the @key{shift} key pressed while

1988

drag-and-dropping the editor (see @ref{Moving Windows}). This second method is

1989

preferred, since you can then specify directly where you want to put the new

1990

view. The default when using the menu is that the new view is put on top of

1991

the editor itself.

1992

1993

@item Open...

1994

@cindex open

1995

@cindex Windows

1996

Open a file selection dialog where you can select a file to edit.

1997

Under Windows, this is the standard file selector. Under other platforms,

1998

this is a built-in file selector described in @ref{The File Selector}.

1999

2000

@item Open From Project...

2001

@anchor{Open From Project}

2002

@cindex open

2003

@cindex project

2004

Open a dialog where you can easily and rapidly select a source file from your

2005

project.

2006

2007

@iftex

2008

@cindex screen shot

2009

@image{open-from-project, 7cm}

2010

@end iftex

2011

2012

@ifhtml

2013

@cindex screen shot

2014

@image{open-from-project}

2015

@end ifhtml

2016

2017

The first text area allows you to type a file name. You can start the beginning

2018

of a file name, and use the @key{Tab} key to complete the file name. If there

2019

are several possible completions, the common prefix will be displayed, and

2020

a list of all possible completions will be displayed in the second text area.

2021

2022

@cindex key

2023

You can then either complete the name by typing it, or continue hitting the

2024

@key{Tab} key to cycle through the possible completions, or click on one of the

2025

completions in the list displayed.

2026

2027

If you press the down arrow key, the focus will move to the list of

2028

completions, so that you can select a file from this list without using the

2029

mouse.

2030

2031

Once you have made your choice, click on the @code{OK} button to validate.

2032

Clicking on @code{Cancel} or hitting the @key{Esc} key will cancel the

2033

operation and close the dialog.

2034

2035

This dialog will only show each file once. If you have extended

2036

projects in your hierarchy, some files may be redefined in some

2037

extending project. In this case, only the files from the extending

2038

project are shown, and you cannot have access through this dialog to

2039

the overridden files of the extended project. Of course, you can still

2040

use the project view or the standard @code{File->Open} menu to

2041

open these files.

2042

2043

@item Recent

2044

@cindex recent

2045

Open a sub menu containing a list of the ten most recent files opened in GPS,

2046

so that you can reopen them easily.

2047

2048

@item Save

2049

@cindex save

2050

Save the current source editor if needed.

2051

2052

@item Save As...

2053

@cindex save as

2054

Same current file under a different name, using the file selector dialog.

2055

@xref{The File Selector}.

2056

2057

@item Save More

2058

@cindex save

2059

Give access to extra save capabilities.

2060

2061

@table @i

2062

@c @item All Editors

2063

@c Save all modified source editors.

2064

2065

@item All

2066

@cindex save all

2067

Save all items, including projects, etc@dots{}

2068

2069

@item Desktop

2070

@cindex save desktop

2071

Save the desktop to a file. The desktop includes information about

2072

files, graphs, @dots{} and their window size and position in GPS. The desktop

2073

is saved per top level project, so that if you reload the same project you get

2074

back to the same situation you were in when you left GPS. Instead, if you load

2075

a different project another desktop will be loaded (or the default desktop).

2076

2077

@item Default Desktop

2078

@cindex save default desktop

2079

Save the current desktop as the default desktop. The next time you

2080

start GPS, if there is no saved desktop associated with the chosen project,

2081

then this desktop will be used. If you haven't saved explicitely a default

2082

desktop, GPS will use its own default desktop from

2083

@file{prefix/share/gps/desktop.xml} in its installation directory.

2084

2085

This default desktop is never overidden automatically by GPS.

2086

2087

@end table

2088

2089

@item Change Directory...

2090

@cindex directory

2091

Open a directory selection dialog that lets you change the current working

2092

directory.

2093

2094

@item Messages

2095

@cindex messages

2096

This sub menu gives access to functionalities related to the Messages window.

2097

@xref{The Messages Window}.

2098

2099

@table @i

2100

@item Clear

2101

@cindex messages

2102

@cindex clear

2103

Clear the contents of the Messages window.

2104

2105

@item Save As...

2106

@cindex save as

2107

Save the contents of the Messages window to a file. A file selector is

2108

displayed to choose the name and location of the file.

2109

2110

@item Load Contents...

2111

@cindex load

2112

Open a file selector to load the contents of a file in the Messages

2113

window. Source locations are identified and loaded in the Locations Tree.

2114

@xref{The Locations Tree}.

2115

2116

@end table

2117

2118

@item Close

2119

@cindex close

2120

Close the current window. This applies to all GPS windows, not only source

2121

editors.

2122

2123

@c @item Close All

2124

@c Close all windows.

2125

2126

@item Print

2127

@cindex print

2128

Print the current window contents, optionally saving it interactively if it has

2129

been modified. The Print Command specified in the preferences is used if it is

2130

defined. On Unix this command is required; on Windows it is optional.

2131

2132

On Windows, if no command is specified in the preferences the standard Windows

2133

print dialog box is displayed. This dialog box allows the user to specify the

2134

target printer, the properties of the printer, which pages to print (all, or a

2135

specific range of pages), the number of copies to print, and, when more than

2136

one copy is specified, whether the pages should be collated. Pressing the

2137

Cancel button on the dialog box returns to GPS without printing the window

2138

contents; otherwise the specified pages and copies are printed on the selected

2139

printer. Each page is printed with a header containing the name of the file

2140

(if the window has ever been saved). The page number is printed on the bottom

2141

of each page.

2142

@xref{Print Command}.

2143

2144

@item Exit

2145

@cindex exit

2146

@cindex quit

2147

Exit GPS after confirmation and if needed, confirmation about saving modified

2148

windows and editors.

2149

2150

@end table

2151

2152

@subsection The Edit Menu

2153

@anchor{The Edit Menu}

2154

@cindex menu

2155

@cindex edit

2156

@noindent

2157

2158

@table @b

2159

@item Undo

2160

@cindex undo

2161

Undo previous insertion/deletion in the current editor.

2162

2163

@item Redo

2164

@cindex redo

2165

Redo previous insertion/deletion in the current editor.

2166

2167

@item Cut

2168

@cindex cut

2169

Cut the current selection and store it in the clipboard.

2170

2171

@item Copy

2172

@cindex copy

2173

@cindex yank

2174

Copy the current selection to the clipboard.

2175

2176

@item Paste

2177

@cindex paste

2178

Paste the contents of the clipboard to the current cursor position.

2179

2180

@item Paste Previous

2181

@cindex paste previous

2182

GPS stores a list of all the text that was previously copied into the clipboard

2183

through the use of Copy or Cut.

2184

2185

By default, if you press Paste, the newest text will be copied at the current

2186

position. But if you select Paste Previous immediately after (one or more times)

2187

you can instead paste text that was copied previously in the clipboard.

2188

2189

For instance, if you copy through @code{Edit->Copy} the text "First", then

2190

copy the text "Second", you can then select @code{Edit->Paste} to insert

2191

"Second" at the current location. If you then select

2192

@code{Edit->Paste Previous}, "Second" will be replaced by "First".

2193

2194

Selecting this menu several times will replace the text previously pasted

2195

by the previous one in the list saved in the clipboard. When reaching the end

2196

of this list, GPS will started from the beginning, and insert again the last

2197

text copied into the clipboard.

2198

2199

The size of this list is controlled by the @code{Clipboard Size} preference.

2200

2201

For more information, @xref{The Clipboard View}.

2202

2203

@item Select All

2204

@cindex select all

2205

Select the whole contents of the current source editor.

2206

2207

@item Insert File...

2208

Open a file selection dialog and insert the contents of this file in

2209

the current source editor, at the current cursor location.

2210

2211

@item Insert Shell Output...

2212

Open an input window at the bottom of the GPS window where you can specify any

2213

external command. The output of the command will be inserted at the current

2214

editor location in case of success. If text is selected, the text is passed

2215

to the external command and replaced by the command's output.

2216

2217

@item Format Selection

2218

@cindex format selection

2219

Indent and format the selection or the current line.

2220

@xref{The Preferences Dialog}, for preferences related to source formatting.

2221

2222

@item Smart Completion

2223

@anchor{Smart Completion}

2224

@cindex completion

2225

2226

Complete the identifier prefix under the cursor, and list the results in a

2227

pop-up list. This command can take advantage of and entity database and offers

2228

completions from the entire project, along with documentation extracted from

2229

comments surrounding declarations. To take full advantage of this feature, the

2230

smart completion preference must be enabled, which will imply the load of the

2231

entity database at GPS startup. The first time you use this feature, GPS will

2232

ask you wether you want this enabled or not.

2233

2234

In order to use this feature, open any Ada file, and begin to type an

2235

identifier. It has to be an identifier declared either in the current file (and

2236

accessible from the cursor location) or in one of the packages of the project

2237

loaded. Move the cursor right after the last character of the incomplete

2238

identifier and hit the completion key (which is @key{ctrl+space} by default).

2239

GPS will open a popup displaying all the known identifiers beginning with the

2240

prefix you typed. You can then browse among the various proposals by clicking

2241

on the @key{up} and @key{down} keys, or using the left scrollbar. For each

2242

entity, a documentation box is filled. If the location of the entity is known,

2243

it's displayed as an hyperlink, and you can jump directly to its declaration by

2244

clicking on it.

2245

2246

Typing new letters will reduce the range of proposal, as long as there remain

2247

solutions. Once you've selected the expected completion, you can validate by

2248

pressing @key{Enter}.

2249

2250

Typing control characters (ie, characters which cannot be used in identifiers)

2251

will also validate the current selection.

2252

2253

GPS is also able to complete automatically subprogram parameter or dotted

2254

notations. For example, if you type

2255

2256

@smallexample

2257

with Ada.

2258

@end smallexample

2259

2260

the smart completion window will appear automatically, listing all the child

2261

and nested packages of Ada. You can configure the time interval after which

2262

the completion window appears (@pxref{The Preferences Dialog}).

2263

2264

You can also write the beginning of the package, e.g.:

2265

2266

@smallexample

2267

with Ada.Text

2268

@end smallexample

2269

2270

pressing the completion key will offer you Text_IO.

2271

2272

If you are in a code section, you will be able to complete the fields of

2273

a record, or the contents of a package, e.g.:

2274

2275

@smallexample

2276

type R is record

2277

Field1 : Integer;

2278

Field2 : Integer;

2279

end record;

2280

2281

V : R;

2282

2283

begin

2284

2285

V.

2286

@end smallexample

2287

2288

Completing V. will propose Field1 and Field2.

2289

2290

The smart completion can also give you the possible parameters of a call

2291

you're currently making. For example, in the following code:

2292

2293

@smallexample

2294

2295

procedure Proc (A, B, C : Integer);

2296

2297

begin

2298

2299

Proc (1,

2300

@end smallexample

2301

2302

If you hit the completion key after the comma, the smart completion engine

2303

will propose you to complete with the named parameters "B =>", "C =>" or

2304

directly to complete with all the remaining parameters, which in this case

2305

will be "B =>, C => )".

2306

2307

@iftex

2308

@cindex screen shot

2309

@image{smart-completion, 15cm}

2310

@end iftex

2311

2312

@ifhtml

2313

@cindex screen shot

2314

@image{smart-completion}

2315

@end ifhtml

2316

2317

Limitations:

2318

2319

@table @bullet

2320

@item Completion does not work with generics.

2321

2322

@item This feature is currently only available for Ada.

2323

Using the smart completion on non Ada files behaves as the identifier completion does.

2324

@xref{Complete Identifier}.

2325

2326

@end table

2327

2328

@item More Completion

2329

@cindex completion

2330

2331

This submenu contains more ways to automatically complete code

2332

2333

@table @bullet

2334

@item Expand Alias

2335

Consider the current word as an alias and expand according to aliases

2336

defined in @ref{Defining text aliases}.

2337

2338

@item Complete Identifier

2339

@anchor{Complete Identifier}

2340

@cindex complete identifier

2341

Complete the identifier prefix under the cursor. This command will cycle

2342

through all identifiers starting with the given prefix.

2343

2344

@item Complete Block

2345

@cindex complete block

2346

Close the current statement (if, case, loop) or unit (procedure,

2347

function, package). This action works only on an Ada buffer.

2348

2349

@end table

2350

2351

@item Selection

2352

@cindex selection

2353

2354

@table @bullet

2355

2356

@item Comment Lines

2357

@cindex comment

2358

Comment the current selection or line based on the current programming

2359

language syntax.

2360

2361

@item Uncomment Lines

2362

@cindex uncomment

2363

Remove the comment delimiters from the current selection or line.

2364

2365

@item Refill

2366

@cindex refill

2367

Refill text on the selection or current line according to the right

2368

margin as defined by the right margin preference

2369

(@pxref{The Preferences Dialog}).

2370

2371

@item Refill with fmt

2372

@cindex refill

2373

@cindex fmt

2374

Refill text on the selection or current line using the external utility

2375

@code{fmt}. If @code{fmt} is not found on your system, this menu will not be

2376

displayed.

2377

2378

@item Sort

2379

Sort the selected lines alphabetically. This is particularly useful when

2380

editing non source code, or for specific parts of the code, like with clauses

2381

in Ada.

2382

2383

@item Sort Reverse

2384

Sort the selected lines in reverse alphabetical order

2385

2386

@item Pipe in external program...

2387

Open an input window at the bottom of the GPS window where you can specify any

2388

external command, which will take the current selection as input. The output of

2389

the command will replace the contents of the selection on success.

2390

2391

@end table

2392

2393

@item Fold all blocks

2394

@cindex fold

2395

Collapse all the blocks in the current file.

2396

2397

@item Unfold all blocks

2398

@cindex unfold

2399

Uncollapse all the blocks in the current file.

2400

2401

@item Create Bookmark

2402

Creates a new Bookmark at cursor position. For more information,

2403

@xref{Bookmarks}.

2404

2405

@item Pretty Print

2406

@cindex gnatpp

2407

@cindex pretty print

2408

Pretty print the current source editor by calling the external tool

2409

@code{gnatpp}. It is possible to specify @code{gnatpp} switches in the

2410

switch editor. @xref{The Switches Editor}.

2411

2412

@item Generate Body

2413

@cindex gnatstub

2414

@cindex generate body

2415

Generate Ada body stub for the current source editor by calling the

2416

external tool @code{gnatstub}.

2417

2418

@item Unit Testing

2419

@cindex AUnit

2420

@cindex unit testing

2421

@cindex testing

2422

This sub menu gives access to dialogs that make it easy to generate

2423

AUnit stubs. AUnit is an Ada unit testing framework.

2424

2425

@table @i

2426

@item New Test Case...

2427

Create a new test case. See AUnit documentation for more details.

2428

2429

@c @item Add Routine...

2430

@c Add a new routine in the current test. See AUnit documentation for more details.

2431

2432

@item New Test Suite...

2433

Create a new test suite. See AUnit documentation for more details.

2434

2435

@item New Test Harness...

2436

Create a new test harness. See AUnit documentation for more details.

2437

2438

@end table

2439

2440

@item Aliases

2441

@cindex alias

2442

Display the Aliases editor. @xref{Defining text aliases}.

2443

2444

@item Key shortcuts

2445

@cindex key shortcuts

2446

Give access to the key manager dialog, to associate commands with special

2447

keys. @xref{The Key Manager Dialog}.

2448

2449

@item Preferences

2450

@cindex preferences

2451

Give access to the preferences dialog. @xref{The Preferences Dialog}.

2452

2453

@end table

2454

2455

@c --------------------------------------------------------------------

2456

@node Recording and replaying macros

2457

@section Recording and replaying macros

2458

@cindex macros

2459

@c --------------------------------------------------------------------

2460

2461

@noindent

2462

It is often convenient to be able to repeat a given key sequence a

2463

number of times.

2464

2465

GPS supports this with several different methods:

2466

2467

@itemize @bullet

2468

@item Repeat the next action

2469

2470

If there is a single key press that you wish to repeat a number of

2471

times, you should first use the GPS action @code{"Repeat Next"} (bound

2472

by default to @key{control-u}, but this can be changed as usual through

2473

the @code{/Edit/Key Shortcuts} menu), then entering the number of times

2474

you wish to repeat, and finally pressing the key you want.

2475

2476

For instance, the following sequence @key{control-u 79 -} will insert

2477

79 characters '-' in the current editor. This proves often useful to

2478

insert separators.

2479

2480

If you are using the emacs mode (see @code{/Tools/Plug-ins} menu),

2481

you can also use the sequence @key{control-u 30 control-k} to delete

2482

30 lines.

2483

2484

@item Recording macros

2485

2486

If you wish to repeat a sequence of more than 1 key, you should record

2487

this sequence as a macro. All macro-related menus are found in

2488

@code{/Tools/Macros}, although it is often more convenient to use these

2489

through key bindings, which you can of course override.

2490

2491

You must indicate to GPS that it should start recording the keys you are

2492

pressing. This is done through the @code{/Tools/Macros/Start Keyboard Macro}

2493

menu. As its name indicates, this only records keyboard events, not mouse

2494

events. Until you select @code{/Tools/Macros/Stop Macro}, GPS will keep

2495

recording the events.

2496

2497

In Emacs mode, the macro actions are bound to @key{control-x (},

2498

@key{control-x )} and @key{control-x e} key shortcuts. For instance,

2499

you can execute the following to create a very simple macro that deletes the

2500

current line, wherever your cursor initially is on that line:

2501

2502

@smallexample

2503

@key{control-x (} # start recording

2504

@key{control-a} # go to beginning of line

2505

@key{control-k} # delete line

2506

@key{control-x )} # stop recording

2507

@end smallexample

2508

2509

@end itemize

2510

2511

@c --------------------------------------------------------------------

2512

@node Contextual Menus for Editing Files

2513

@section Contextual Menus for Editing Files

2514

@cindex case exceptions

2515

@c --------------------------------------------------------------------

2516

2517

Whenever you ask for a contextual menu (using e.g. the third button

2518

on your mouse) on a source file, you will get access to a number of

2519

entries, displayed or not depending on the current context.

2520

2521

Menu entries include the following categories:

2522

2523

@table @b

2524

2525

@item Source Navigation

2526

@xref{Contextual Menus for Source Navigation}.

2527

2528

@item Edit with external editor

2529

@xref{Using an External Editor}.

2530

2531

@item Dependencies

2532

@xref{Dependency Browser}.

2533

2534

@item Entity browsing

2535

@xref{Entity Browser}.

2536

2537

@item Project view

2538

@xref{The Project View}.

2539

2540

@item Version control

2541

@xref{The Version Control Contextual Menu}.

2542

2543

@item Debugger

2544

@xref{Using the Source Editor when Debugging}.

2545

2546

@item Case exceptions

2547

@xref{Handling of case exceptions}.

2548

2549

@item Refactoring

2550

@xref{Refactoring}.

2551

2552

@end table

2553

2554

@cindex language, editor

2555

@cindex character set

2556

In addition, an entry @code{Properties...} is always visible in this

2557

contextual menu. When you select it, a dialog pops up that allows you

2558

to override the language used for the file, or the character set.

2559

2560

This can be used for instance if you want to open a file that does not

2561

belong to the current project, but where you want to benefit from the

2562

syntax highlighting that GPS knows how to.

2563

2564

It is not recommended to override the language for source files that

2565

belong to the project. Instead, you should use the @code{Project Properties}

2566

dialog and change the naming scheme if appropriate. This will ensure better

2567

consistency between GPS and the compiler in the way they manipulate the

2568

file.

2569

2570

@c -----------------------------------------------------------------

2571

@node Handling of case exceptions

2572

@section Handling of case exceptions

2573

@cindex casing

2574

@c -----------------------------------------------------------------

2575

2576

GPS keeps a set of case exceptions that is used by all

2577

case insensitive languages. When editing or reformatting a buffer for

2578

such a language the case exception dictionary will be checked

2579

first. If an exception is found for this word or a substring of the

2580

word, it will be used; otherwise the specified casing for keywords or

2581

identifiers is used. A substring is defined as a part of the word

2582

separated by underscores.

2583

2584

Note that this feature is not activated for entities (keywords or

2585

identifiers) for which the casing is set to @code{Unchanged}. See

2586

@pxref{The Preferences Dialog}.

2587

2588

A contextual menu named @b{Casing} has the following entries:

2589

2590

@table @b

2591

@item Lower @i{entity}

2592

Set the selected entity in lower case.

2593

2594

@item Upper @i{entity}

2595

Set the selected entity in upper case.

2596

2597

@item Mixed @i{entity}

2598

Set the selected entity in mixed case (set the first letter and

2599

letters before an underscore in upper case, all other letters are set

2600

to lower case).

2601

2602

@item Smart Mixed @i{entity}

2603

Set the selected entity in smart mixed case. Idem as above except that

2604

upper case letters are kept unchanged.

2605

2606

@item Add exception for @i{entity}

2607

Add the current entity into the case exception dictionary.

2608

2609

@item Remove exception for @i{entity}

2610

Remove the current entity from the case exception dictionary.

2611

@end table

2612

2613

To add or remove a substring exception into/from the dictionary you need to

2614

first select the substring on the editor. In this case the last two

2615

contextual menu entries will be:

2616

2617

@table @b

2618

@item Add substring exception for @i{str}

2619

Add the selected substring into the case substring exception dictionary.

2620

2621

@item Remove substring exception for @i{str}

2622

Remove the selected substring from the case substring exception dictionary.

2623

@end table

2624

2625

@c --------------------------------------------------------------------------

2626

@node Refactoring

2627

@section Refactoring

2628

@cindex refactoring

2629

@c --------------------------------------------------------------------------

2630

2631

@noindent

2632

GPS includes basic facilities for refactoring your code. Refactoring is the

2633

standard term used to describe manipulation of the source code that do not

2634

affect the behavior of the application, but help reorganize the source code

2635

to make it more readable, more extendable, @dots{}

2636

2637

Refactoring technics are generally things that programmers are used to do by

2638

hand, but which are faster and more secure to do automatically through a tool.

2639

2640

One of the basic recommendations when you refactor your code is to recompile

2641

and test your application very regularly, to make sure that each of the small

2642

modifications you made to it didn't break the behavior of your application.

2643

This is particularly true with GPS, since it relies on the cross-references

2644

information that is generated by the compilar. If some of the source files

2645

have not been recompiled recently, GPS will print warning messages indicating

2646

that the renaming operation might be dangerous and/or only partial.

2647

2648

GPS currently provides the following refactoring capabilities:

2649

2650

@table @bullet

2651

@item Rename entity

2652

Clicking on an entity in a source file and selecting the

2653

@code{Refactoring/Rename} menu will open a dialog asking for the new name

2654

of the entity. GPS will rename all instances of the entity in your application.

2655

This includes the definition of the entity, its body, all calls to it, etc@dots{}

2656

Of course, no comment is updated, and you should probably check manually that

2657

the comment for the entity still applies.

2658

2659

GPS will handle primitive operations by also renaming the operations it

2660

overrides or that overrides it. This means that any dispatching call to that

2661

operation will also be renamed, and the application should still work as

2662

before. If you are renaming a parameter to a subprogram, GPS can also rename

2663

parameters with similar names in overriding or overridden subprograms.

2664

2665

The behavior when handling read-only files can be specified: by default,

2666

GPS will not do any refactoring in these files, and will display a dialog

2667

listing all of them; but you can also choose to make them writable just

2668

as if you had clicked on the "Read-Only" button in the status bar of the

2669

editor and then have GPS perform the renaming in them as well.

2670

2671

@item Name parameters

2672

If you are editing Ada code and click on a call to a subprogram, GPS will

2673

display a contextual menu @code{Refactoring/Name parameters}, which will

2674

replace all unnamed parameters by named parameters, as in:

2675

2676

@smallexample

2677

Call (1, 2)

2678

=>

2679

Call (Param1 => 1, Param2 => 2);

2680

@end smallexample

2681

2682

@item Extract Method

2683

This refactoring is used to move some code from one place to a separate

2684

subprogram. The goal is to simplify the original subprogram, by moving part of

2685

its code elsewhere.

2686

GPS takes care of finding which parameters the new subprogram should have,

2687

whether they should be "in", "in out" or "out" parameters, and whether the

2688

new subprogram should be a procedure or a function. It also replaces the code

2689

in the original subprogram by a call to the new subprogram.

2690

2691

@smallexample

2692

procedure Proc (Param1 : Integer) is

2693

Local1 : Integer;

2694

begin

2695

Local1 := Param1; -- line 4

2696

Local1 := Local1 + 1; -- line 5

2697

Local1 := Local1 + 4;

2698

end Proc;

2699

2700

When lines 4 and 5 are extracted, we get:

2701

function New_Method (Param1 : Integer) return Integer is

2702

Local1 : Integer;

2703

begin

2704

Local1 := Param1; -- line 4

2705

Local1 := Local1 + 1; -- line 5

2706

return Local1;

2707

end New_Method;

2708

2709

procedure Proc (Param1 : Integer) is

2710

Local1 : Integer;

2711

begin

2712

Local1 := New_Method (Param1);

2713

Local1 := Local1 + 4;

2714

end Proc;

2715

@end smallexample

2716

2717

The above example, albeit trivial, shows in particular that GPS knows how

2718

to find which parameters should be transfered to the new subprogram.

2719

2720

GPS will use, for the parameters, the same name that was used for the local

2721

variable. Very often, it will make sense to recompile the new version of the

2722

source, and then apply the @code{Rename Entity} refactoring to have more

2723

specific names for the parameters, or the @code{Name Parameters} refactoring

2724

so that the call to the new method uses named parameters to further clarify

2725

the code.

2726

2727

This refactoring is only available if you have selected at least a full line

2728

of text, not a partial selection in a line of text.

2729

2730

@end table

2731

2732

@c --------------------------------------------------------------------------

2733

@node Using an External Editor

2734

@section Using an External Editor

2735

@cindex editor

2736

@cindex external editor

2737

@cindex emacs

2738

@cindex vi

2739

@c --------------------------------------------------------------------------

2740

2741

@noindent

2742

GPS is fully integrated with a number of external editors, in

2743

particular @code{Emacs} and @code{vi}. The choice of the default

2744

external editor is done in the preferences. @xref{The Preferences Dialog}.

2745

@cindex preferences

2746

The following values are recognized:

2747

2748

@table @code

2749

@item gnuclient

2750

@cindex gnuclient

2751

This is the recommended client. It is based on Emacs, but needs an

2752

extra package to be installed. This is the only client that provides a

2753

full integration in GPS, since any extended lisp command can be sent

2754

to the Emacs server.

2755

2756

By default, gnuclient will open a new Emacs frame for every file

2757

that is opened. You might want to add the following code to your

2758

@file{.emacs} file (create one if needed) so that the same Emacs frame

2759

is reused every time:

2760

2761

@cindex example

2762

@smallexample

2763

(setq gnuserv-frame (car (frame-list)))

2764

@end smallexample

2765

2766

@cindex gnuserv url

2767

See @url{http://www.hpl.hp.com/people/ange/gnuserv/home.html} for more

2768

information.

2769

2770

@item emacsclient

2771

@cindex emacsclient

2772

This is a program that is always available if you have installed

2773

Emacs. As opposed to starting a new Emacs every time, it will reuse an

2774

existing Emacs session. It is then extremely fast to open a file.

2775

2776

@item emacs

2777

@cindex emacs

2778

This client will start a new Emacs session every time a file needs to

2779

be opened. You should use @code{emacsclient} instead, since it is much

2780

faster, and makes it easier to copy and paste between multiple

2781

files. Basically, the only reason to use this external editor is if

2782

your system doesn't support @code{emacsclient}.

2783

2784

@item vim

2785

@cindex vim

2786

@code{Vim} is a vi-like editor that provides a number of enhancements,

2787

for instance syntax highlighting for all the languages supported by

2788

GPS. Selecting this external editor will start an xterm (or command

2789

window, depending on your system) with a running @code{vim} process editing

2790

the file.

2791

2792

Note that one limitation of this editor is that if GPS needs to open

2793

the same file a second time, it will open a new editor, instead of

2794

reusing the existing one.

2795

2796

@cindex Windows

2797

To enable this capability, the xterm executable must be found in the PATH,

2798

and thus is not supported on Windows systems. Under Windows systems,

2799

you can use the @code{custom} editor instead.

2800

2801

@item vi

2802

@cindex vi

2803

This editor works exactly like vim, but uses the standard @code{vi}

2804

command instead of @code{vim}.

2805

2806

@item custom

2807

@cindex custom editor

2808

You can specify any external editor by choosing this item. The full

2809

command line used to call the editor can be specified in the

2810

preferences (see @ref{custom editor command}).

2811

2812

@item none

2813

No external editor is used, and the contextual menus simply won't

2814

appear.

2815

@end table

2816

2817

In the cases that require an Emacs server, GPS will try several

2818

solutions if no already running server was found. It will first try to

2819

spawn the glide environment distributed with GNAT. If not found in the

2820

PATH, it will then start a standard Emacs. The project file currently used

2821

in GPS will be set appropriately the first time Emacs is spawned. This means

2822

that if you load a new project in GPS, or modify the paths of the current

2823

project, you should kill any running Emacs, so that a new one is spawned

2824

by GPS with the appropriate project.

2825

2826

@cindex menu

2827

Alternatively, you can reload explicitly the project from

2828

Emacs itself by using the menu @code{Project->Load}

2829

2830

@cindex preferences

2831

In the preferences, there are three settings that allow you to select

2832

the external editor (if left to an empty string, GPS will

2833

automatically select the first editor available on your system), to

2834

specify the custom editor command, in case you've selector this item, and

2835

whether this editor should always be used every time you double-click

2836

on a file, or whether you need to explicitly select the contextual

2837

menu to open the external editor.

2838

2839

@c --------------------------------------------------------------------------

2840

@node Using the Clipboard

2841

@section Using the Clipboard

2842

@cindex clipboard

2843

@cindex cut

2844

@cindex copy

2845

@cindex yank

2846

@cindex paste

2847

@cindex X-Window

2848

@c --------------------------------------------------------------------------

2849

2850

@noindent

2851

This section concerns X-Window users who are used to cutting and

2852

pasting with the middle mouse button. In the GPS text editor, as in

2853

many recent X applications, the @i{GPS clipboard} is set by explicit

2854

cut/copy/paste actions, either through menu items or keyboard

2855

shortcuts, and the @i{primary clipboard} (i.e. the ``middle button''

2856

clipboard) is set by the current selection.

2857

2858

Therefore, copy/paste between GPS and other X applications using the

2859

@i{primary clipboard} will still work, provided that there is some

2860

text currently selected. The @i{GPS clipboard}, when set, will

2861

override the @i{primary clipboard}.

2862

2863

@cindex url

2864

See @url{http://www.freedesktop.org/standards/clipboards.txt} for more

2865

information.

2866

2867

@c --------------------------------------------------------------------------

2868

@node Saving Files

2869

@section Saving Files

2870

@cindex saving

2871

@c --------------------------------------------------------------------------

2872

2873

@noindent

2874

After you have finished modifying your files, you need to save them. The basic

2875

method to do that is to select the menu @code{File->Save}, which saves the

2876

currently selected file.

2877

2878

You can also use the menu @code{File->Save As...} if you want to save the

2879

file with another name, or in another directory.

2880

2881

If you have multiple files to save, another possibility is to use the menu

2882

@code{File->Save More->All}. This will open a dialog listing all the currently

2883

modified editors that need saving. You can then select individually which

2884

one should be saved, and click on @code{Save} to do the actual saving.

2885

2886

When calling external commands, such as compiling a file, if the

2887

@code{Auto save} preference is disabled, this same dialog is also used,

2888

to make sure that e.g. the compiler will take into account your local changes.

2889

If the preference is enabled, the saving is performed automatically.

2890

2891

@iftex

2892

@cindex screen shot

2893

@image{save-dialog, 7cm}

2894

@end iftex

2895

2896

@ifhtml

2897

@cindex screen shot

2898

@image{save-dialog}

2899

@end ifhtml

2900

2901

You can conveniently select or unselect all the files at once by clicking on

2902

the title of the first column (labeled @i{Select}). This will toggle

2903

the selection status of the first line, and have the same status for all other

2904

editors.

2905

2906

If you press @code{Cancel} instead of @code{Save}, no saving will take place,

2907

and the action that displayed this dialog is also canceled. Such actions can

2908

be for instance starting a compilation command, a VCS operation, or quitting

2909

GPS with unsaved files.

2910

2911

@c --------------------------------------------------------------------

2912

@node Remote Files

2913

@section Remote Files

2914

@cindex remote files

2915

@cindex ftp

2916

@cindex ssh

2917

@cindex rsh

2918

@cindex rsync

2919

@cindex telnet

2920

@cindex http

2921

@c --------------------------------------------------------------------

2922

2923

@noindent

2924

GPS has a basic support for working with files on remote hosts. This includes

2925

a number of protocols, described below, which allow you to read a file from

2926

a remote host, edit it locally, and then save it transparently to the remote

2927

machine.

2928

2929

For now, the support for remote files is only available through the GPS

2930

shell window. You start editing a remote file by typing a line similar to

2931

2932

@smallexample

2933

Editor.edit protocol://user@@machine/full/path

2934

@end smallexample

2935

2936

where "protocol" should be replaced by the name of the protocol you want to

2937

use, "user" is the login name you wish to use on the remote "machine", and

2938

"/full/path" is the full path on the remote machine to access the file.

2939

2940

The user name is optional. If it is the same as on the local machine, you

2941

can omit the user name as well as the "@@" sign.

2942

2943

Likewise, the machine name is optional, if you want to get a file from the

2944

local host. This can be used to access files belonging to another user. In this

2945

case, you need to specify the "@@" sign, but do not insert a machine name right

2946

after it.

2947

2948

Remote files can also be used if you want to work with GPS, but the machine on

2949

which the files are found isn't supported by GPS.

2950

2951

The following protocols are supported:

2952

2953

@table @b

2954

@item ssh

2955

This protocol is based on the ssh command line tool, which must therefore be

2956

available in the path. It provides encrypted and secure connections to the

2957

remote host. Files are transfered in-line, that is the connection is established

2958

the first time you access the remote host, and kept open for all further

2959

access.

2960

2961

@cindex password

2962

Although ssh can be setup not to require a password, GPS will automatically

2963

detect if a password is asked and open a dialog to query it.

2964

2965

The remote system must be a Unix-like system with support for standard Unix

2966

commands like @code{test}, @code{echo}, @code{rm} and @code{ls}.

2967

2968

In the sample shell command above, you would replace the word "protocol" with

2969

"ssh" to use this protocol.

2970

2971

@item rsh

2972

This protocol behaves like ssh, except that the connections are not encrypted.

2973

However, this protocol is generally available on all Unix machines by default.

2974

2975

It has the same requirements that the ssh protocol. To use it, substitute the

2976

word "rsh" to "protocol" in the example above.

2977

2978

@item telnet

2979

This protocol is based on the standard telnet protocol. It behaves much like

2980

the two protocols above, with an unencrypted connection.

2981

2982

To use it, substitute the word "telnet" to "protocol" in the example above.

2983

2984

@item scp

2985

This protocol is also based on one of the tools of the ssh suite. It provides

2986

encrypted connections, and uses a mixture of ssh and scp connections.

2987

Various commands like querying the time stamp of a file are executed through a

2988

permanent ssh connection, whereas files are downloaded and uploaded through

2989

a one-time scp command.

2990

2991

It basically has the same behavior as the ssh protocol, although it might be

2992

slightly slower since a new connection has to be established every time a file

2993

is fetched from, or written to the remote host. However, it might work better

2994

than ssh if the file contains 8 bit characters.

2995

2996

To use it, substitute the word "scp" to "protocol" in the example above.

2997

2998

@item rsync

2999

Just like scp is based on ssh, this protocol is based on rsh. It depends on

3000

the external tool rsync, and uses a mixture of a rsh connection for commands

3001

like querying the time stamp of a file, and one-time connections with rsync

3002

to transfer the files.

3003

3004

Rsync is specially optimized to transfer only the parts of a file that are

3005

different from the one already on the remote host. Therefore, it will generally

3006

provide the best performance when writing the file back to the remote host.

3007

3008

If you set up the environment variable RSYNC_RSH to ssh before starting gps,

3009

the connection will then be encrypted when transferring the files.

3010

3011

To use this protocol, substitute the word "rsync" to "protocol" in the

3012

example above.

3013

3014

@item ftp

3015

This protocol provides only limited capabilities, but can be used to retrieve

3016

or write a file back through an ftp connection, possibly even through an

3017

anonymous ftp connection.

3018

3019

To use this protocol, substitute the word "ftp" to "protocol" in the example

3020

above.

3021

3022

@item http

3023

This is the usual http protocol to download documents from the web. It is in

3024

particular useful for documentation

3025

3026

@end table

3027

3028

@c --------------------------------------------------------------------

3029

@node Source Navigation

3030

@chapter Source Navigation

3031

@cindex source navigation

3032

@cindex navigation

3033

@c --------------------------------------------------------------------

3034

3035

@menu

3036

* Support for Cross-References::

3037

* The Navigate Menu::

3038

* Contextual Menus for Source Navigation::

3039

@end menu

3040

3041

@c --------------------------------------------------------------------

3042

@node Support for Cross-References

3043

@section Support for Cross-References

3044

@cindex cross-references

3045

@c --------------------------------------------------------------------

3046

3047

@noindent

3048

GPS provides cross-reference navigation for program entities, such as

3049

types, procedures, functions, variables, @dots{}, defined in your

3050

application. The cross-reference support in GPS relies on

3051

language-specific tools as explained below.

3052

3053

@table @b

3054

@item Ada

3055

@cindex Ada

3056

@cindex GNAT

3057

The GNAT compiler is used to generate the cross-references information

3058

needed by GPS. This means that you must compile your application before

3059

you browse through the cross-references or view various graphs in GPS.

3060

If sources have been modified, you should recompile the modified files.

3061

3062

@cindex -gnatQ

3063

@cindex -k

3064

If you need to navigate through sources that do not compile (e.g after

3065

modifications, or while porting an application), GNAT can still generate

3066

partial cross-reference information if you specify the @code{-gnatQ}

3067

compilation option. Along with the @code{-k} option of gnatmake, it is

3068

then possible to generate as much relevant information as possible for

3069

your non compilable sources.

3070

3071

@cindex ALI

3072

There are a few special cases where GPS cannot find the external file

3073

(called @file{ALI file}) that contains the cross-reference

3074

information. Most likely, this is either because you haven't compiled

3075

your sources yet, or because the source code has changed since the

3076

@file{ALI file} was generated.

3077

3078

@cindex project

3079

It could also be that you haven't included in the project the object

3080

directories that contain the @file{ALI files}.

3081

3082

@cindex separate unit

3083

In addition, one special case cannot be handled automatically. This

3084

is for separate units, whose file names have been crunched through the

3085

@command{gnatkr} command. To handle this, you should force GPS to parse

3086

all the @file{ALI files} in the appropriate object directory. This is

3087

done by right-clicking on the object directory in the project view

3088

(left-side panel on the main window), and selecting the menu "Parse

3089

all xref information".

3090

3091

@item C/C++

3092

@cindex C

3093

@cindex C++

3094

To enable the navigation features for C and C++ source files, you need

3095

to first generate a database of symbol references, by going through the

3096

menu Build->Recompute Xref info. Messages in the console window

3097

will indicate the state of the processing. Due to the nature of these

3098

languages, in order to provide accurate cross-references, GPS needs to

3099

generate the database in two phases: a first pass parses all the files

3100

that have been modified since the previous parsing, and a second pass

3101

generates global cross-references by analyzing the complete database.

3102

It is thus expected that for large projects, this phase can take a

3103

significant amount of CPU to proceed.

3104

3105

@cindex overloaded

3106

@cindex #ifdef

3107

In some cases, GPS won't be able to determine the exact function involved

3108

in a cross-reference. This will typically occur for overloaded functions,

3109

or if multiple functions with the same name, but under different

3110

@code{#ifdef} sections, are defined. In this case, GPS will display a

3111

dialog listing the possible choices to resolve the ambiguity.

3112

3113

@cindex namespace

3114

@cindex macro

3115

In addition, the C/C++ parser has the following limitations: namespaces

3116

are currently ignored (no specific processing is done for namespaces);

3117

minimal support for templates; no attempt is made to process the macros and

3118

other preprocessor defines.

3119

Macros are considered as special entities, so it is possible to navigate

3120

from a macro use to its definition, but the macro content is ignored,

3121

which means for example that function calls made through macros

3122

won't be detected.

3123

3124

@end table

3125

3126

@subsection Loading xref info in memory

3127

@cindex Load xref info in memory

3128

3129

The cross-reference information, as mentioned above, is generated either

3130

by the compiler when you recompile your sources, or explicitly when you

3131

select the menu @code{Build->Recompute Xref info}.

3132

3133

This information will be loaded in memory automatically by GPS when it

3134

needs it, and as little as possible, to limit the memory footprint. However,

3135

this means that some operations, for instance searching for all the references

3136

to a global entity, will need to parse most, if not all, of the cross-reference

3137

information. This will slow done the search the first time (and then the

3138

information is in memory and the search is fast, unless the cross-reference

3139

information has been regenerated on the disk).

3140

3141

You can select the menu @code{Build->Load xref info in memory} to force GPS to

3142

load all the available information immediately in memory. This will speed up

3143

future queries.

3144

3145

This menu can also be used in some cases for C and C++. Since these languages

3146

have no notion of package, the declaration of a subprogram and its actual

3147

implementation can be in two different files with vastly different names.

3148

GPS in such case will not be able to display a @code{Goto body} contextual

3149

menu unless it has already parsed both files. A way to get fully accurate

3150

cross-reference information is thus to load all information into memory

3151

before attempting any navigation operation.

3152

3153

A special case has been put in place so that both @file{file.h} and

3154

@file{file.cpp} are loaded together in memory. This means that in the general

3155

case where an entity is defined in @file{foo.h} and implemented in

3156

@file{foo.cpp}, nothing special needs to be done. The specific file extensions

3157

depend on the naming scheme specified in your project.

3158

3159

A preference can be set to have GPS load the cross-information automatically

3160

on startup, @xref{The Preferences Dialog}.

3161

@c ??? need to xref to specific pref, this xref is too general

3162

3163

@c --------------------------------------------------------------------

3164

@node The Navigate Menu

3165

@section The Navigate Menu

3166

@cindex navigate

3167

@c --------------------------------------------------------------------

3168

3169

@noindent

3170

3171

@table @b

3172

@item Find or Replace...

3173

@cindex find

3174

@cindex search

3175

@cindex replace

3176

Open the find and replace dialog. @xref{Searching and Replacing}.

3177

3178

@item Find Next

3179

@cindex find next

3180

Find next occurrence of the current search. @xref{Searching and Replacing}.

3181

3182

@item Find Previous

3183

@cindex find previous

3184

Find previous occurrence of the current search.

3185

@xref{Searching and Replacing}.

3186

3187

@item Find All References

3188

@anchor{Find All References}

3189

@cindex find all references

3190

Find all the references to the current entity in the project. The search

3191

is based on the semantic information extracted from the sources, this is not

3192

a simple text search. The result of the search is displayed in the location

3193

window, see @ref{The Locations Tree}.

3194

3195

@item Goto Declaration

3196

@cindex goto declaration

3197

Go to the declaration/spec of the current entity. The current entity is

3198

determined by the word located around the cursor.

3199

This item is also accessible through the editor's contextual menu directly.

3200

This capability requires the availability of cross-reference information.

3201

@xref{Support for Cross-References}.

3202

3203

@item Goto Body

3204

@cindex goto body

3205

Go to the body/implementation of the current entity.

3206

This item is also accessible through the editor's contextual menu directly.

3207

This capability requires the availability of cross-reference information.

3208

@xref{Support for Cross-References}.

3209

3210

@item Goto Matching Delimiter

3211

@cindex goto matching delimiter

3212

Go to the delimiter matching the one right before (for a closing delimiter) or

3213

right after (for an opening delimiter) the cursor if any.

3214

3215

@item Goto Line...

3216

@cindex goto line

3217

Open a dialog where you can type a line number, in order to jump to a specific

3218

location in the current source editor.

3219

3220

@item Goto File Spec<->Body

3221

@cindex goto file spec/body

3222

@cindex Ada

3223

Open the corresponding spec file if the current edited file is a body file,

3224

or body file otherwise. This option is only available for the Ada language.

3225

This item is also accessible through the editor's contextual menu

3226

3227

@c @item Goto Parent Unit

3228

@c @cindex goto parent unit

3229

@c This item is also accessible through the editor's contextual menu

3230

3231

This capability requires support for cross-references.

3232

This item is also accessible through the editor's contextual menu

3233

3234

@item Start Of Statement

3235

@cindex Start Of Statement

3236

Move the cursor position to the start of the current statement, move

3237

to the start of the enclosing statement if the cursor position is

3238

already at the start of the statement.

3239

3240

@item End Of Statement

3241

@cindex End Of Statement

3242

Move the current cursor position to the end of the statement, move

3243

to the end of the enclosing statement if the cursor position is

3244

already at the end of the statement.

3245

3246

@item Previous Subprogram

3247

@cindex Previous Subprogram

3248

Move the current cursor position to the start of the previous procedure,

3249

function, task, protected record or entry.

3250

3251

@item Next Subprogram

3252

@cindex Next Subprogram

3253

Move the current cursor position to the start of the next procedure,

3254

function, task, protected record or entry.

3255

3256

@item Previous Tag

3257

@cindex tag

3258

@cindex previous tag

3259

@cindex locations tree

3260

Go to previous tag/location. @xref{The Locations Tree}.

3261

3262

@item Next Tag

3263

@cindex tag

3264

@cindex next tag

3265

@cindex locations tree

3266

Go to next tag/location. @xref{The Locations Tree}.

3267

3268

@item Back

3269

@cindex Back

3270

Go to previous location.

3271

3272

@item Forward

3273

@cindex Forward

3274

Go to next location.

3275

3276

@end table

3277

3278

@c --------------------------------------------------------------------

3279

@node Contextual Menus for Source Navigation

3280

@section Contextual Menus for Source Navigation

3281

@cindex contextual menu

3282

@c --------------------------------------------------------------------

3283

3284

@noindent

3285

This contextual menu is available from any source editor.

3286

If you right click over an entity, or first select text, the contextual

3287

menu will apply to this selection or entity.

3288

3289

@table @b

3290

@item Goto declaration of @i{entity}

3291

@cindex goto declaration

3292

Go to the declaration/spec of @i{entity}. The current entity is

3293

determined by the word located around the cursor or by the current selection

3294

if any.

3295

This capability requires support for cross-references.

3296

3297

@item Goto body of @i{entity}

3298

@cindex goto body

3299

Go to the body/implementation of @i{entity}.

3300

This capability requires support for cross-references.

3301

3302

@item Goto declarations of @i{entity}

3303

@cindex goto declaration

3304

This contextual menu appears when you are clicking on a subprogram call that

3305

is a dispatching call. In such a case, there is no possibility for GPS to

3306

know what subprogram will actually be called at run time, since that depends

3307

on dynamic information. It therefore gives you a list of all entities in the

3308

tagged type hierarchy, and let you choose which of the declarations you want

3309

to jump to. See also the @file{methods.py} plug-in (enabled by default) which,

3310

given an object, lists all its primitive operations in a contextual menu so

3311

that you can easily jump to them. See also the contextual menu

3312

@file{References/Find References To...} which allows you to find all calls

3313

to a subprogram or to one of its overriding subprograms.

3314

3315

@item Goto bodies of @i{entity}

3316

@cindex goto body

3317

This is similar to @i{Goto declarations of}, but applies to the bodies of

3318

the entities.

3319

3320

@item Goto file spec/body

3321

@cindex goto file spec/body

3322

@cindex Ada

3323

Open the corresponding spec file if the current edited file is a body file,

3324

or body file otherwise. This option is only available for the Ada language.

3325

3326

@item @i{Entity} calls

3327

Display a list of all subprograms called by @i{entity} in a tree view. This is generally more convenient than using the corresponding Browsers/ submenu if you expect lots of references, @xref{The Callgraph View}.

3328

3329

@item @i{Entity} is called by

3330

Display a list of all subprograms calling @i{entity} in a tree view. This is generally more convenient than using the correponding Browsers/ submenu if you expect lots of references, @xref{The Callgraph View}.

3331

3332

@item References

3333

@cindex references

3334

This item gives access to different capabilities related to listing or

3335

displaying references to the current entity or selection.

3336

3337

@table @command

3338

@item Find all references to @i{entity}

3339

@cindex find all references

3340

Find all references to @i{entity} in all the files in the project, @xref{Find All References}.

3341

3342

@item Find all references...

3343

This menu is similar to the one above, except it is possible to select more

3344

precisely what kind of reference should be selected. It is also possible

3345

to indicate the scope of the search, and whether the context (or caller)

3346

at each reference should be displayed. Computing the caller information will

3347

take slightly longer though.

3348

3349

@cindex primitive operation

3350

This dialog has an option @code{Include overriding and overriden operations},

3351

which, when activated, will include references to overriden or overriding

3352

entities of the one you selected.

3353

3354

This is particularly useful when you are wondering whether you can easily

3355

modify the profile of a primitive operation, since you can then see what

3356

other entities will also be impacted. If you select only the @code{declaration}

3357

check box, you will see the list of all related primitive operations.

3358

3359

@cindex imported entities

3360

This dialog also allows you to find out which entities are imported from

3361

a given file/unit. Click on any entity from that file (for instance on the

3362

@code{with} line for Ada code), then select the @code{All entities imported

3363

from same file} toggle button. This will display in the location window the

3364

list of all entities imported from the same file as the entity selected.

3365

3366

In addition, if you have selected the @code{Show context} option, you will

3367

get a list of all the exact references to these entities within the file.

3368

Otherwise, you just get a pointer to the declaration of the imported

3369

entities.

3370

3371

@item Find all local references to @i{entity}

3372

@cindex find all local references

3373

Find all references to @i{entity} in the current file (or in the current

3374

top level unit for Ada sources).

3375

See @ref{Find All References} for more details.

3376

3377

@item Variables used in @i{entity}

3378

@cindex variables used

3379

Find all variables (local or global) used in @i{entity} and list each first

3380

reference in the locations window.

3381

@end table

3382

3383

@item Methods of @i{entity}

3384

@cindex methods

3385

@cindex primitive operations

3386

This submenu is only visible if you have activated the plug-in

3387

@file{methods.py} (which is the case by default), and when you click on

3388

a tagged type or an instance of a tagged type. This menu lists all the

3389

primitive operations of that type, and you can therefore easily jump to

3390

the declaration of any of these operations.

3391

3392

@item Browsers

3393

@cindex browsers

3394

This item gives access to graph representations of callers and callees for

3395

subprograms.

3396

3397

@table @command

3398

@item @i{Entity} calls

3399

@cindex call graph

3400

@cindex calls

3401

Open or raise the call graph browser on the specified entity and display all

3402

the subprograms called by @i{entity}. @xref{Call Graph}.

3403

3404

@item @i{Entity} is called by

3405

@cindex call graph

3406

@cindex called by

3407

Open or raise the call graph browser on the specified entity and display all

3408

the subprograms calling @i{entity}. @xref{Call Graph}.

3409

3410

Note that this capability requires a global look up in the project

3411

cross-references, which may take a significant amount of time the first

3412

time. After a global look up, information is cached in memory, so that

3413

further global queries will be faster.

3414

@end table

3415

3416

@item Show expanded code

3417

For Ada files only, this entry will generate a .dg file using your gnat

3418

compiler (using the -gnatGL switch), and will open this file at the location

3419

corresponding to the current source line. this can be useful when investigating

3420

low-level issues and tracing precisely how the source code is transformed by

3421

the GNAT front-end.

3422

3423

@end table

3424

3425

@c --------------------------------------------------------------------

3426

@node Project Handling

3427

@chapter Project Handling

3428

@cindex project

3429

@c --------------------------------------------------------------------

3430

3431

@noindent

3432

@cindex project view

3433

The section on the project view (@ref{The Project View}) has

3434

already given a brief overview of what the projects are, and the

3435

information they contain.

3436

3437

This chapter provides more in-depth information, and describes

3438

how such projects can be created and maintained.

3439

3440

@menu

3441

* Description of the Projects::

3442

* Supported Languages::

3443

* Scenarios and Configuration Variables::

3444

* Extending Projects::

3445

* Project View::

3446

* Disabling Project Edition Features::

3447

* The Project Menu::

3448

* The Project Wizard::

3449

* The Project Dependencies Editor::

3450

* The Project Properties Editor::

3451

* The Switches Editor::

3452

* The Project Browser::

3453

@end menu

3454

3455

@c -------------------------------------------------------------------

3456

@node Description of the Projects

3457

@section Description of the Projects

3458

@cindex project description

3459

@c -------------------------------------------------------------------

3460

3461

@subsection Project files and GNAT tools

3462

@cindex project file

3463

@cindex GNAT

3464

3465

@noindent

3466

This section describes what the projects are, and what information

3467

they contain.

3468

3469

The most important thing to note is that the projects used by GPS are

3470

the same as the ones used by GNAT. These are text files (using the

3471

extension @file{.gpr}) which can be edited either manually, with any

3472

text editor, or through the more advanced GPS interface.

3473

3474

The exact syntax of the project files is fully described in the GNAT

3475

User's Guide (@url{gnat_ug.html}) and GNAT Reference Manual

3476

(@url{gnat_rm.html}). This is recommended reading if you want to use

3477

some of the more advanced capabilities of project files which are not

3478

yet supported by the graphical interface.

3479

3480

GPS can load any project file, even those that you have been

3481

edited manually. Furthermore, you can manually edit project files

3482

created by GPS.

3483

3484

Typically you will not need to edit project files manually, since several

3485

graphical tools such as the project wizard (@ref{The Project Wizard})

3486

and the properties editor(@ref{The Project Properties Editor}) are

3487

provided.

3488

3489

@cindex normalization of projects

3490

GPS doesn't preserve the layout nor comments of manually created

3491

projects after you have edited them in GPS. For instance, multiple case

3492

statements in the project will be coalesced into a single case statement.

3493

This normalization is required for GPS to be able to preserve the previous

3494

semantic of the project in addition to the new settings.

3495

3496

@cindex GNAT

3497

All command-line GNAT tools are project aware, meaning that the notion

3498

of project goes well beyond GPS' user interface. Most capabilities

3499

of project files can be accessed without using GPS itself, making

3500

project files very attractive.

3501

3502

@cindex ADA_PROJECT_PATH

3503

GPS uses the same mechanisms to locate project files as GNAT

3504

itself:

3505

3506

@itemize @bullet

3507

@item absolute paths

3508

@item relative paths.

3509

These paths, when used in a with line as described below, are relative

3510

to the location of the project that does the with.

3511

@item ADA_PROJECT_PATH.

3512

If this environment variable is set, it contains a colon-separated (or

3513

semicolon under Windows) list of directories in which the project files are

3514

searched.

3515

@item predefined project path.

3516

The compiler itself defines a predefined project path, in which standard

3517

libraries can be installed, like XML/Ada for instance.

3518

@end itemize

3519

3520

@subsection Contents of project files

3521

@cindex project file

3522

3523

@noindent

3524

Project files contain all the information that describe the

3525

organization of your source files, object files and executables.

3526

3527

@cindex project comments

3528

A project file can contain comments, which have the same format as in Ada,

3529

that is they start by "--" and extend to the end of the line.

3530

You can add comments when you edit the project file manually. GPS will

3531

attempt to preserve them when you save the project through the menu, but this

3532

will not always be possible. It helps if the comments are put at the end of

3533

the line, as in

3534

3535

@smallexample

3536

project Default is

3537

for Source_Dirs use (); -- No source in this project

3538

end Default;

3539

@end smallexample

3540

3541

@cindex sub project

3542

Generally, one project file will not be enough to describe a complex

3543

organization. In this case, you will create and use a project hierarchy,

3544

with a root project importing other sub projects. Each of the projects

3545

and sub projects is responsible for its own set of sources (compiling

3546

them with the appropriate switches, put the resulting files in the

3547

right directories, @dots{}).

3548

3549

@cindex GNAT

3550

Each project contains the following information

3551

(see the GNAT user's guide for the full list)

3552

3553

@itemize @bullet

3554

@item @b{List of imported projects}:

3555

@cindex imported project

3556

When you are compiling sources from this project, the compiler

3557

(either through GNAT or the automatically generated Makefiles) will

3558

first make sure that all the imported projects have been correctly

3559

recompiled and are up-to-date. This way, dependencies between

3560

source files are properly handled.

3561

3562

If one of the source files of project A depends on some source

3563

files from project B, then B must be imported by A. If this isn't

3564

the case, the compiler will complain that some of the source files

3565

cannot be found.

3566

3567

One important rule is that each source file name must be unique in

3568

the project hierarchy (i.e. a file cannot be under control of two

3569

different projects). This ensures that the same file will be found

3570

no matter what project is managing the source file that uses

3571

3572

@item @b{List of source directories}:

3573

@cindex source directory

3574

All the sources managed by a project are found in one or more

3575

source directories. Each project can have multiple source

3576

directories, and a given source directory might be shared by

3577

multiple projects.

3578

3579

@item @b{Object directory}:

3580

@cindex object directory

3581

When the sources of the project are compiled, the resulting object

3582

files are put into this object directory. There exist exactly one object

3583

directory for each project. If you need to split the object files

3584

among multiple object directories, you need to create multiple

3585

projects importing one another as appropriate.

3586

3587

When sources from imported sub-projects are recompiled, the

3588

resulting object files are put in the sub project's own object

3589

directory, and will never pollute the parent's object directory.

3590

3591

@item @b{Exec directory}:

3592

@cindex exec directory

3593

When a set of object files is linked into an executable, this executable

3594

is put in the exec directory of the project file. If this attribute

3595

is unspecified, the object directory is used.

3596

3597

@item @b{List of source files}:

3598

@cindex source file

3599

The project is responsible for managing a set of source

3600

files. These files can be written in any programming

3601

languages. Currently, the graphical interface supports Ada, C and C++.

3602

3603

The default to find this set of source files is to take all the

3604

files in the source directories that follow the naming scheme (see

3605

below) for each language. In addition if you edit the

3606

project file manually, it is possible to provide an explicit list of source

3607

files.

3608

3609

This attribute cannot be modified graphically yet.

3610

3611

@item @b{List of main units}:

3612

@cindex main unit

3613

The main units of a project (or main files in some languages) are

3614

the units that contain the main subprogram of the application, and

3615

that can be used to link the rest of the application.

3616

3617

The name of the file is generally related to the name of the

3618

executable.

3619

3620

A given project file hierarchy can be used to compile and link

3621

several executables. GPS will automatically update the Compile, Run

3622

and Debug menu with the list of executables, based on this list.

3623

3624

@item @b{Naming schemes}:

3625

@cindex naming scheme

3626

The naming scheme refers to the way files are named for each

3627

languages of the project. This is used by GPS to choose the language

3628

support to use when a source file is opened. This is also used to

3629

know what tools should be used to compile or otherwise work with a

3630

source file.

3631

3632

@item @b{Embedded targets and cross environments}:

3633

@cindex cross environment

3634

GPS supports cross environment software development: GPS itself can

3635

run on a given host, such as GNU/Linux, while compilations, runs and

3636

debugging occur on a different remote host, such as Sun/Solaris.

3637

3638

@cindex VxWorks

3639

GPS also supports embedded targets (VxWorks, @dots{}) by specifying

3640

alternate names for the build and debug tools.

3641

3642

The project file contains the information required to log on the

3643

remote host.

3644

3645

@item @b{Tools}:

3646

@cindex tools

3647

Project files provide a simple way to specify the compiler and

3648

debugger commands to use.

3649

3650

@item @b{Switches}:

3651

@cindex switches

3652

Each tool that is used by GPS (compiler, pretty-printer, debugger,

3653

@dots{}) has its own set of switches. Moreover, these switches may

3654

depend on the specific file being processed, and the programming

3655

language it is written in.

3656

3657

@end itemize

3658

3659

@c -------------------------------------------------------------------

3660

@node Supported Languages

3661

@section Supported Languages

3662

@cindex languages

3663

@cindex text files

3664

@c -------------------------------------------------------------------

3665

3666

@noindent

3667

Another information stored in the project is the list of languages that

3668

this project knows about. GPS support any number of language, with any name

3669

you choose. However, advanced support is only provided by default for some

3670

languages (Ada, C and C++), and you can specify other properties of the

3671

languages through customization files

3672

(@pxref{Adding support for new languages}).

3673

3674

By default, the graphical interface will only give you a choice of languages

3675

among the ones that are known to GPS at that point, either through the default

3676

GPS support or your customization files. But you can also edit the project

3677

files by hand to add support for any language.

3678

3679

Languages are a very important part of the project definition. For each

3680

language, you should specify a naming scheme that allows GPS to associate

3681

files with that language. You would for instance specify that all @file{.adb}

3682

files are Ada, all @file{.txt} files are standard text files, and so on.

3683

3684

Only the files that have a known language associated with them are displayed

3685

in the @code{Project View}, or available for easy selection through the

3686

@code{File->Open From Project} menu. Similarly, only these files are shown

3687

in the Version Control System interface.

3688

3689

It is therefore important to properly setup your project to make these files

3690

available conveniently in GPS, although of course you can still open any file

3691

through the @code{File->Open} menu.

3692

3693

If your project includes some README files, or other text files, you should

3694

add "txt" as a language (or any other name you want), and make sure that

3695

these files are associated with that language in the @code{Project properties

3696

editor}.

3697

3698

By default, GPS provides support for a number of languages. In most cases,

3699

this support takes the form of syntax highlighting in the editor, and possibly

3700

the Outline View. Other languages have advanced cross-references available.

3701

3702

All the supported languages can be added to the project, but you can also add

3703

your own languages as you need (either by editing the project files by hand,

3704

or by creating XML files to add GPS support for these languages, which will

3705

then show in the project properties editor graphically).

3706

3707

@c -------------------------------------------------------------------

3708

@node Scenarios and Configuration Variables

3709

@section Scenarios and Configuration Variables

3710

@cindex configuration variable

3711

@cindex project variable

3712

@cindex variable

3713

@c -------------------------------------------------------------------

3714

3715

@noindent

3716

The behavior of projects can be further tailored by the use of

3717

scenarios.

3718

3719

@cindex project attribute

3720

All the attributes of a project, except its list of imported projects,

3721

can be chosen based on the value of external variables, whose value is

3722

generally coming from the host computer environment, or directly set in

3723

GPS. The interface to manipulate these scenarios is the scenario view, which

3724

can be displayed by selecting the menu @code{Tools->Views->Scenario}.

3725

It can be convenient to drag this window with your mouse, and drop it above

3726

the project view, so that you can see both at the same time.

3727

3728

This area allows you to select new values for the scenario variables defined

3729

in your project, and thus change dynamically the view GPS has of your project

3730

and your source files.

3731

3732

@cindex compile

3733

@cindex debug

3734

This facility can for instance be used to compile all the sources either

3735

in debug mode (so that the executables can be run in the debugger), or

3736

in optimized mode (to reduce the space and increase the speed when

3737

delivering the software). In this configuration scenario, all the

3738

attributes (source directories, tools, @dots{}) remain the same, except

3739

for the compilation switches. It would be more difficult to maintain a

3740

completely separate hierarchy of project, and it is much more efficient

3741

to create a new configuration variable and edit the switches for the

3742

appropriate scenario (@ref{The Project Properties Editor}).

3743

3744

@subsection Creating new configuration variables

3745

@cindex creating configuration variable

3746

3747

@noindent

3748

Creating a new scenario variable is done through the contextual menu

3749

(right-click) in the Project View or the Scenario View itself. Select the

3750

menu @code{Project->Add Configuration Variable}. This opens the following

3751

dialog:

3752

3753

@iftex

3754

@cindex screen shot

3755

@image{scenarios, 10cm}

3756

@end iftex

3757

3758

@ifhtml

3759

@cindex screen shot

3760

@image{scenarios}

3761

@end ifhtml

3762

3763

There are two main areas in this dialog: in the top line, you specify

3764

the name of the variable. This name is used for two purposes:

3765

3766

@itemize @bullet

3767

@item It is displayed in the scenario view

3768

@cindex scenario view

3769

3770

@item This is the name of the environment variable from which the

3771

initial value is read. When GPS is started, all configuration

3772

variables are initialized from the host computer environment, although

3773

you can of course change its value later on inside GPS. Note that

3774

selecting a new value for the scenario variable does not change the

3775

actual value of the environment variable, which is only used to get the

3776

default initial value of the scenario variable.

3777

3778

When you spawn external tools like gnatmake for instance, you can

3779

also specify the value they will use for the scenario variable by

3780

using a command line switch, typically @code{-X}.

3781

3782

@end itemize

3783

3784

If you click on the arrow on the right of this name area, GPS will

3785

display the list of all the environment variables that are currently

3786

defined. However, you don't need to pick the name of an existing

3787

variable, neither must the variable exist when GPS is started.

3788

3789

The second part of this dialog is the list of authorized value for

3790

this variable. Any other value will generate an error reported by

3791

GPS, and the project won't be loaded as a result.

3792

3793

One of these values is the default value (the one whose button in the

3794

Default column is selected). This means that if the environment

3795

variable doesn't exist when GPS is started, GPS will behave as if it

3796

did exist with this default value.

3797

3798

The list of possible values can be edited through the @code{Remove},

3799

@code{Add} and @code{Rename} buttons, although you can also simply

3800

click on the value itself to change it.

3801

3802

@subsection Editing existing configuration variables

3803

@cindex editing configuration variable

3804

3805

@noindent

3806

If at least one configuration variable is defined in your project, the

3807

scenario view will contain something similar to:

3808

3809

@iftex

3810

@cindex screen shot

3811

@image{explorer-scenario, 5.5cm}

3812

@end iftex

3813

3814

@ifhtml

3815

@cindex screen shot

3816

@image{explorer-scenario}

3817

@end ifhtml

3818

3819

@cindex Unix

3820

This screen shot shows two configuration variables, named @code{Build}

3821

and @code{OS}, with their current value (resp. @code{Debug} and

3822

@code{Unix}).

3823

3824

You can easily change the current value of any of these variables by

3825

clicking on the arrow on the right of the value. This will display a

3826

pop-up window with the list of possible values, from which you select

3827

the one you wish to use.

3828

3829

As soon as a new value is selected, GPS will recompute the project

3830

view (in case source directories, object directories or list

3831

of source files have changed). A number of things will also be updated

3832

(like the list of executables in the @code{Compile}, @code{Run} and

3833

@code{Debug} menus).

3834

3835

@cindex browsers

3836

@cindex call graph

3837

Currently, GPS will not recompute the contents of the various browsers

3838

(call graph, dependencies, @dots{}) for this updated project. This would be too

3839

expensive to do every time the value changes, and therefore you need

3840

to explicitly request an update.

3841

3842

@c ??? Need to explain how to force an update, once this is implemented

3843

3844

You can change the list of possible values for a configuration

3845

variable at any time by clicking on the button to the far left of the

3846

variable's name. This will pop up the same dialog that is used to create

3847

new variables. This dialog also allows you to change the name of the

3848

scenario variable. This name is the same as the environment variable that

3849

is used to set the initial value of the scenario variable.

3850

3851

@cindex removing variable

3852

Removing a variable is done by clicking on the button immediately to

3853

the left of the variable's name. GPS will then display a confirmation

3854

dialog.

3855

3856

If you confirm that you want to delete the variable, GPS will simply

3857

remove the variable, and from now on act as if the variable always had

3858

the value it had when it was deleted.

3859

3860

@c --------------------------------------------------------------------

3861

@node Extending Projects

3862

@section Extending Projects

3863

@cindex projects, extending

3864

@c --------------------------------------------------------------------

3865

3866

@subsection Description of extending projects

3867

3868

@noindent

3869

The project files were designed to support big projects, with several

3870

hundreds or thousands of source files. In such contexts, one developer

3871

will generally work on a subset of the sources. It is also not rare for

3872

such a project to take several hours to fully compile. Most developers

3873

therefore do not need to have the full copy of the project compiled on

3874

their own machine or personal disk space.

3875

3876

However, it is still useful to be able to access other source files

3877

of the application, for instance to find out whether a subprogram can be

3878

changed and where it is currently called.

3879

3880

Such a setup can be achieved through extending projects. These are

3881

special types of projects that inherit most of their attributes and source

3882

files from another project, and can have, in their source directories, some

3883

source files that hide/replace those inherited from the original project.

3884

3885

When compiling such projects, the compiler will put the newly created

3886

project files in the extending project's directory, and will leave the original

3887

untouched. As a result, the original project can be shared read-only among

3888

several developers (for instance, it is usual for this original project to be

3889

the result of a nightly build of the application).

3890

3891

@subsection Creating extending projects

3892

3893

@noindent

3894

This project wizard allows you to easily create extending projects. You

3895

should select an empty directory (which will be created automatically if

3896

needed), as well as a list of source files you want to work on initially.

3897

New files can also be added later.

3898

3899

As a result, GPS will copy the selected source files to the new directory

3900

(if you so decided), and create a number of project files there. It will then

3901

load a new project, which has the same properties as the previous

3902

one, except that some files are found transparently in the new directory,

3903

and object files resulting from the compilation are create into that

3904

directory as opposed to the object directory of the original project.

3905

3906

@subsection Adding files to extending projects

3907

@cindex Add To Extending Project

3908

3909

@noindent

3910

Once you have loaded an extending project in GPS, things work mostly

3911

transparently. If you open a file through the @code{File->Open From Project}

3912

dialog, the files found in the local directory of your extending project

3913

will be picked up first.

3914

3915

The build actions will create object files in the extending project's

3916

directory, leaving the original project untouched.

3917

3918

It might happen that you want to start working on a source file that you

3919

had not added in the extending project when it was created. You can of course

3920

edit the file found in the original project, provided you have write access

3921

to it. However, it is generally better to edit it in the context of the

3922

extending project, so that the original project can be shared among

3923

developers.

3924

3925

This can be done by clicking on the file in the @code{Project View}, then

3926

selecting the menu @code{Add To Extending Project}. This will popup a

3927

dialog asking whether you want GPS to copy the file to the extending

3928

project's directory for you. GPS might also create some new project files

3929

in that directory if necessary, and automatically reload the project as

3930

needed. From then on, if you use the menu @code{File->Open From Project},

3931

GPS will first see the file from the extending project.

3932

3933

Note that open editors will still be editing the same file they were before,

3934

so you should open the new file if needed.

3935

3936

@c -------------------------------------------------------------------

3937

@node Project View

3938

@section The Project View

3939

@cindex project view

3940

@c -------------------------------------------------------------------

3941

3942

@noindent

3943

The project view, as mentioned in the general description of the

3944

GPS window, is one of the views found by default on the left

3945

of the window. It shows in a tree structure the project hierarchy,

3946

along with all the source files belonging to the project, and the

3947

entities declared in the source files.

3948

3949

It is worth noting that the project view provides a tree representation of

3950

the project hierarchy. If a project is imported by multiple other

3951

projects in the hierarchy, then this project will appear multiple times

3952

in the project view.

3953

3954

@cindex limited with

3955

Likewise, if you have edited the project manually and have used the

3956

@code{limited with} construct to have cycles in the project

3957

dependencies, the cycle will expand infinitely. For instance, if

3958

project @file{a} imports project @file{b}, which in turns imports

3959

project @file{a} through a @code{limited with} clause, then expanding

3960

the node for @file{a} will show @file{b}. In turn, expanding the node

3961

for @file{b} will show a node for @file{a}, and so on.

3962

3963

The contextual menu in this project view provides a number of items to

3964

modify the project hierarchy (what each project imports), as well as

3965

to visualize and modify the attributes for each projects (compilation

3966

switches, naming scheme, @dots{})

3967

3968

The following entries are available in the contextual menu:

3969

3970

@table @command

3971

@item Show Projects Imported by...

3972

This item will open a new window in GPS, the project browser, which

3973

displays graphically the relationships between each project in the

3974

hierarchy.

3975

3976

@item Save The Project...

3977

@cindex saving projects

3978

This item can be selected to save a single project in the hierarchy

3979

after it was modified. Modified but unsaved projects in the hierarchy

3980

have a special icon (a pen mark is drawn on top of the

3981

standard icon). If you would rather save all the modified projects in

3982

a single step, use the menu bar item @code{Project->Save All}.

3983

3984

@item Project/Properties

3985

This item will open a new dialog, and give access to all the

3986

attributes of the project: tool switches, naming schemes, source

3987

directories, @dots{} @xref{The Project Properties Editor}.

3988

3989

@item Project/Edit source file

3990

@cindex edit project source file

3991

This menu will load the project file into an editor, so that you can

3992

manually edit it. This should be used if you need to access some

3993

features of the project files that are not accessible graphically

3994

(renames statements, variables, @dots{})

3995

3996

@item Project/Dependencies...

3997

@cindex project dependency

3998

This opens the dependencies editor (@pxref{The Project Dependencies Editor}).

3999

4000

@item Add Configuration Variable

4001

@cindex add configuration variable

4002

This menu item should be used to add new configuration variables, as

4003

described in @ref{Scenarios and Configuration Variables}.

4004

4005

@item Build

4006

This menu offers the submenu "Clean" which remove all object files and other

4007

compilation artifacts associated to the current project.

4008

4009

@end table

4010

4011

@cindex saving projects

4012

Any time one or several projects are modified, the contents of the

4013

project view is automatically refreshed. No project is automatically

4014

saved. This provides a simple way to temporarily test new values for

4015

the project attributes.

4016

Unsaved modified projects are shown with a special icon in the project

4017

view, displaying a pen mark on top of the standard

4018

icon:

4019

4020

@iftex

4021

@cindex screen shot

4022

@image{project-modified}

4023

@end iftex

4024

4025

@ifhtml

4026

@cindex screen shot

4027

@image{project-modified}

4028

@end ifhtml

4029

4030

Note that in all tree views in GPS, you can use the @key{+} and @key{-} keys

4031

to expand and collapse nodes (e.g. projects and directories).

4032

4033

@c -------------------------------------------------------------------

4034

@node Disabling Project Edition Features

4035

@section Disabling Project Edition Features

4036

@cindex project editing

4037

@c -------------------------------------------------------------------

4038

4039

@noindent

4040

The project files should generally be considered as part of the sources,

4041

and thus be put under control of a version control system. As such, you

4042

might want to prevent accidental editing of the project files, either

4043

by you or some other person using the same GPS installation.

4044

4045

The main thing to do to prevent such accidental edition is to change

4046

the write permissions on the project files themselves. On Unix systems,

4047

you could also change the owner of the file. When GPS cannot write a

4048

project file, it will report an error to the user.

4049

4050

However, the above doesn't prevent a user from trying to do some

4051

modifications at the GUI level, since the error message only occurs when

4052

trying to save the project (this is by design, so that temporary modification

4053

can be done in memory).

4054

4055

You can disable all the project editing related menus in GPS by adding

4056

special startup switches. The recommended way is to create a small batch

4057

script that spawns GPS with these switches. You should use the following

4058

command line:

4059

4060

@smallexample

4061

gps --traceoff=MODULE.PROJECT_VIEWER --traceoff=MODULE.PROJECT_PROPERTIES

4062

@end smallexample

4063

4064

What these do it prevent the loading of the two GPS modules that are

4065

responsible for project edition. However, this also has an impact on the

4066

python functions that are exported by GPS, and thus could break some

4067

plug-ins. Another solution which might apply in your case is simply to

4068

hide the corresponding project-editing menus and contextual menus. This

4069

could be done by creating a small python plugin for GPS

4070

(@pxref{Customizing through XML and Python files}, which contains the

4071

following code:

4072

4073

@smallexample

4074

import GPS

4075

GPS.Menu.get ("/Project/Edit Project Properties").hide()

4076

GPS.Contextual ('Edit project properties').hide()

4077

GPS.Contextual ('Save project').hide()

4078

GPS.Contextual ('Add configuration variable').hide()

4079

@end smallexample

4080

4081

@c -------------------------------------------------------------------

4082

@node The Project Menu

4083

@section The Project Menu

4084

@cindex project menu

4085

@c -------------------------------------------------------------------

4086

4087

The menu bar item @code{Project} contains several commands that

4088

generally act on the whole project hierarchy. If you only want to act

4089

on a single project, use the contextual menu in the project view.

4090

4091

Some of these menus apply to the currently selected project. This

4092

notion depends on what window is currently active in GPS: if it is the

4093

project view, the selected project is either the selected node (if

4094

it is a project), or its parent project (for a file, directory, @dots{}).

4095

If the currently active window is an editor, the selected project is

4096

the one that contains the file.

4097

4098

In all cases, if there is no currently selected project, the menu will

4099

apply to the root project of the hierarchy.

4100

4101

These commands are:

4102

4103

@table @command

4104

@item New

4105

This menu will open the project wizard (@ref{The Project Wizard}), so

4106

that you can create new project. On exit, the wizard asks whether the

4107

newly created project should be loaded. If you select @code{Yes}, the new

4108

project will replace the currently loaded project hierarchy.

4109

4110

You will get asked what information you would like to create the project from.

4111

In particular, you can create a set of project files from existing Ada

4112

sources.

4113

4114

@item Open

4115

This menu opens a file selection dialog, so that any existing project

4116

can be loaded into GPS. The newly loaded project replaces the currently

4117

loaded project hierarchy. GPS works on a single project hierarchy at

4118

a time.

4119

4120

@item Recent

4121

This menu can be used to easily switch between the last projects that

4122

were loaded in GPS.

4123

4124

@item Edit Project Properties

4125

This menu applies to the currently selected project, and will open the

4126

project properties dialog for this project.

4127

4128

@item Save All

4129

This will save all the modified projects in the hierarchy.

4130

4131

@item Edit File Switches

4132

@anchor{File Switches}

4133

This menu applies to the currently selected project. This will open a

4134

new window in GPS, listing all the source files for this project,

4135

along with the switches that will be used to compile them, @xref{The

4136

Switches Editor}.

4137

4138

@item Reload Project

4139

@cindex reload project

4140

@cindex C

4141

@cindex C++

4142

Reload the project from the disk, to take into account modifications done

4143

outside of GPS. In

4144

particular, it will take into account new files added externally to the source

4145

directories.

4146

This isn't needed for modifications made through GPS.

4147

4148

@item Project View

4149

Open (or raise if it is already open) the project view on the left side

4150

of the GPS window.

4151

4152

@end table

4153

4154

@c -------------------------------------------------------------------

4155

@node The Project Wizard

4156

@section The Project Wizard

4157

@cindex project wizard

4158

@c -------------------------------------------------------------------

4159

4160

@noindent

4161

The project wizard allows you to create in a few steps a new project file.

4162

It has a number of pages, each dedicated to editing a specific set of

4163

attributes for the project.

4164

4165

The typical way to access this wizard is through the

4166

@code{Project->New...} menu.

4167

4168

The project wizard is also launched when a new dependency is created

4169

between two projects, through the contextual menu in the project

4170

view.

4171

4172

@iftex

4173

@cindex screen shot

4174

@image{project-wizard, 12.7cm}

4175

@end iftex

4176

4177

@ifhtml

4178

@cindex screen shot

4179

@image{project-wizard}

4180

@end ifhtml

4181

4182

The wizard gives access to the following list of pages:

4183

4184

@itemize @bullet

4185

@item Project type

4186

@item Project Naming

4187

@item Languages Selection

4188

@item Version Control System Selection

4189

@item Source Directories Selection

4190

@item Build Directory

4191

@item Main Units

4192

@item Library

4193

@item Naming Scheme

4194

@item Switches

4195

@end itemize

4196

4197

@c ------------------------------------------------------------------

4198

@subsection Project Type

4199

@c ------------------------------------------------------------------

4200

4201

@noindent

4202

Several types of project wizards are provided in GPS. Depending on the

4203

information you have or your current setup, you will choose one or the

4204

other.

4205

4206

@itemize @bullet

4207

@item Single Project

4208

4209

This is likely the wizard you will use most often. It creates a project

4210

file from scratch, and asks you for the location of source directories,

4211

the object directory, @dots{}; The rest of this chapter describes this wizard

4212

in more details

4213

4214

@item Project Tree

4215

4216

This wizard will attempt to create a set of one or more project files to

4217

represent your current build environment. It will analyze what

4218

your sources are, where the corresponding object files are, and will try

4219

and find some possible setup for the project files (remember that a given

4220

@file{.gpr} project file can be associated with a single object directory.

4221

4222

This wizard might not work in all cases, but is worth a try to get you

4223

started if you already have an existing set of sources

4224

4225

@item Convert GLIDE Project (.adp)

4226

4227

This wizard will help you convert a @file{.adp} project file that is used

4228

by the GLIDE environment. The same restrictions apply as above, except

4229

that the list of source directories, object directories

4230

and tool switches are read directly from that file.

4231

4232

@item Library Project

4233

@cindex project, library

4234

4235

This specialized wizard is similar to the Single Project wizard, except it

4236

adds one extra page, the Library page. The output of the compilation of this

4237

project is a library (shared or static), as opposed to an executable in the

4238

case of @code{Single Project}.

4239

4240

@item Extending Project

4241

@cindex project, extending

4242

4243

This specialized wizard allows you to easily create extending projects

4244

(@pxref{Extending Projects}).

4245

4246

@end itemize

4247

4248

@c ------------------------------------------------------------------

4249

@subsection Project Naming

4250

@c ------------------------------------------------------------------

4251

4252

@noindent

4253

This is the first page displayed by any of the wizard.

4254

4255

You must enter the name and location of the project to create. This

4256

name must be a valid Ada identifier (i.e. start with a letter,

4257

optionally followed by a series of digits, letters or

4258

underscores). Spaces are not allowed. Likewise, reserved Ada keywords

4259

must be avoided. If the name is invalid, GPS will display an error

4260

message when you press the @code{Forward} button.

4261

4262

Child projects can be created from this dialog. These are project whose

4263

name is of the form @code{Parent.Child}. GPS will automatically generate

4264

the dependency to the parent project so as to make the child project

4265

valid.

4266

4267

In this page, you should also select what languages the source files

4268

in this project are written in. Currently supported languages are @code{Ada},

4269

@code{C} and @code{C++}. Multiple languages can be used for a single

4270

project.

4271

4272

The last part of this page is used to indicate how the path should be

4273

stored in the generated project file. Most of the time, this setting

4274

will have no impact on your work. However, if you wish to edit the

4275

project files by hand, or be able to duplicate a project hierarchy to

4276

another location on your disk, it might be useful to indicate that

4277

paths should be stored as relative paths (they will be relative to the

4278

location of the project file).

4279

4280

@c ------------------------------------------------------------------

4281

@subsection Languages Selection

4282

@cindex Languages

4283

@c ------------------------------------------------------------------

4284

4285

@noindent

4286

This page is used to select the programming languages used for the

4287

sources of this project. By default, only @code{Ada} is selected.

4288

New languages can be added to this list by using XML files, see the

4289

section on customizing GPS (@pxref{Adding support for new languages}).

4290

4291

@c ------------------------------------------------------------------

4292

@subsection VCS Selection

4293

@cindex Version Control System

4294

@cindex VCS

4295

@c ------------------------------------------------------------------

4296

4297

@noindent

4298

The second page in the project wizard allows you to select which Version

4299

Control system is to be used for the source files of this project.

4300

4301

GPS doesn't attempt to automatically guess what it should use, so you

4302

must specify it if you want the VCS operations to be available to you.

4303

4304

The two actions @code{Log checker} and @code{File checker} are the

4305

name and location of programs to be run just prior an actual commit of

4306

the files in the Version Control System. These should be used for

4307

instance if you wish to enforce style checks before a file is actually

4308

made available to other developers in your team.

4309

4310

If left blank, no program will be run.

4311

4312

@c ------------------------------------------------------------------

4313

@subsection Source Directories Selection

4314

@c ------------------------------------------------------------------

4315

4316

@noindent

4317

This page lists and edits the list of source directories for the

4318

project. Any number of source directory can be used (the default is to

4319

use the directory which contains the project file, as

4320

specified in the first page of the wizard).

4321

4322

If you do not specify any source directory, no source file will be

4323

associated with the project, since GPS wouldn't know where to look for

4324

them.

4325

4326

To add source directories to the project, select a directory in the

4327

top frame, and click on the down arrow. This will add the directory to

4328

the bottom frame, which contains the current list of source directories.

4329

4330

You can also add a directory and all its subdirectories recursively by

4331

using the contextual menu in the top frame. This contextual menu also

4332

provides an entry to create new directories, if needed.

4333

4334

To remove source directories from the project, select the directory in

4335

the bottom frame, and click on the up arrow, or use the contextual

4336

menu.

4337

4338

All the files in these directories that match one of the language

4339

supported by the project are automatically associated with that

4340

project.

4341

4342

The relative sizes of the top and bottom frame can be changed by

4343

clicking on the separation line between the two frames and dragging

4344

the line up or down.

4345

4346

@c ------------------------------------------------------------------

4347

@subsection Build Directory

4348

@cindex object directory

4349

@cindex exec directory

4350

@c ------------------------------------------------------------------

4351

4352

@noindent

4353

The object directory is the location where the files resulting from

4354

the compilation of sources (e.g. @file{.o} files) are placed.

4355

One object directory is associated for each project.

4356

4357

The exec directory is the location where the executables are put. By

4358

default, this is the same directory as the object directory.

4359

4360

@c ------------------------------------------------------------------

4361

@subsection Main Units

4362

@cindex main units

4363

@c ------------------------------------------------------------------

4364

4365

@noindent

4366

The main units of a project are the files that should be compiled and

4367

linked to obtain executables.

4368

4369

Typically, for C applications, these are the files that contain the

4370

@code{main()} function. For Ada applications, these are the files that

4371

contain the main subprogram each partition in the project.

4372

4373

These files are treated specially by GPS. Some sub-menus of

4374

@code{Build} and @code{Debug} will have predefined entries for the

4375

main units, which makes it more convenient to compile and link your

4376

executables.

4377

4378

To add main units click on the @code{Add} button. This opens a file

4379

selection dialog. No check is currently done that the selected file

4380

belongs to the project, but GPS will complain later if it doesn't.

4381

4382

When compiled, each main unit will generate an executable, whose name

4383

is visible in the second column in this page. If you are using a

4384

recent enough version of GNAT (3.16 or more recent), you can change

4385

the name of this executable by clicking in the second column and

4386

changing the name interactively.

4387

4388

@c ------------------------------------------------------------------

4389

@subsection Library

4390

@cindex library projects

4391

@c ------------------------------------------------------------------

4392

4393

@noindent

4394

This page allows you to configure your project so that the output of

4395

its compilation is a library (shared or static), as opposed to an

4396

executable or a simple set of objet files. This library can then be linked

4397

with other executables (and will be automatically if the project is imported

4398

by another one.

4399

4400

You need to define the attributes in the top box to transform your project

4401

into a library project. See the tooltips that appear when you leave your

4402

mouse on top of the label to the left of each field.

4403

4404

If you define any of the attributes in the Standalone Library box, you

4405

will compile a standalone library. This is a library that takes care of

4406

its elaboration by itself, instead of relying on its caller to elaborate

4407

it as is standard in Ada. You also have more control over what files make

4408

up the public interface to the library, and what files are private to the

4409

library and invisible from the outside.

4410

4411

@c ------------------------------------------------------------------

4412

@subsection Naming Scheme

4413

@cindex naming scheme

4414

@c ------------------------------------------------------------------

4415

4416

@noindent

4417

A naming scheme indicates the file naming conventions used in the different

4418

languages supported by a given project.

4419

For example, all @file{.adb} files are Ada files, all @file{.c} files are

4420

C files.

4421

4422

GPS is very flexible in this respect, and allows you to specify the

4423

default extension for the files in a given programming language. GPS makes a

4424

distinction between spec (or header) files, which generally contain

4425

no executable code, only declarations, and body files which contain

4426

the actual code. For languages other than Ada, this header file is

4427

used rather than the body file when you select @code{Go To

4428

Declaration} in the contextual menu of editors.

4429

4430

In a language like Ada, the distinction between spec and body

4431

is part of the definition of the language itself, and you should be

4432

sure to specify the appropriate extensions.

4433

4434

The default naming scheme for Ada is GNAT's naming scheme (@file{.ads}

4435

for specs and @file{.adb} for bodies). In addition, a number of predefined

4436

naming schemes for other compilers are available in the first combo box on

4437

the page. You can also create your own customized scheme by entering a

4438

free text in the text entries.

4439

4440

@iftex

4441

@cindex screen shot

4442

@image{naming-scheme, 10.7cm}

4443

@end iftex

4444

4445

@ifhtml

4446

@cindex screen shot

4447

@image{naming-scheme}

4448

@end ifhtml

4449

4450

For all languages, GPS accepts exceptions to this standard naming

4451

scheme. For instance, this let you specify that in addition to using

4452

@file{.adb} for Ada body files, the file @file{foo.ada} should also be

4453

considered as an Ada file.

4454

4455

The list of exceptions is displayed in the bottom list of the naming

4456

scheme editor. To remove entries from this list, select the line you

4457

want to remove, and then press the @key{Del} key.

4458

The contents of the lines can be edited interactively, by

4459

double-clicking on the line and column you want to edit.

4460

4461

To add new entries to this list, use the fields at the bottom of

4462

the window, and press the update button.

4463

4464

@c ------------------------------------------------------------------

4465

@subsection Switches

4466

@anchor{Switches}

4467

@cindex switches

4468

@c ------------------------------------------------------------------

4469

4470

@noindent

4471

The last page of the project wizard is used to select the

4472

default switches to be used by the various tools that GPS calls (compiler,

4473

linker, binder, pretty printer, @dots{}).

4474

4475

@iftex

4476

@cindex screen shot

4477

@image{switch-editor, 10.7cm}

4478

@end iftex

4479

4480

@ifhtml

4481

@cindex screen shot

4482

@image{switch-editor}

4483

@end ifhtml

4484

4485

This page appears as a notebook, where each page is associated with a

4486

specific tool. All these pages have the same structure:

4487

4488

@table @b

4489

@item Graphical selection of switches

4490

The top part of each page contains a set of buttons, combo boxes,

4491

entry fields, @dots{} which give fast and intuitive access to the most

4492

commonly used switches for that tool.

4493

4494

@item Textual selection of switches

4495

The bottom part is an editable entry field, where you can directly

4496

type the switches. This makes it easier to move from

4497

an older setup (e.g. Makefile, script) to GPS, by copy-pasting switches.

4498

@end table

4499

4500

The two parts of the pages are kept synchronized at any time: clicking

4501

on a button will edit the entry field to show the new switch; adding a

4502

new switch by hand in the entry field will activate the corresponding

4503

button if there is one.

4504

4505

Any switch can be added to the entry field, even if there is no

4506

corresponding button. In this case, GPS will simply forward it to the

4507

tool when it is called, without trying to represent it graphically.

4508

4509

@c -------------------------------------------------------------------

4510

@node The Project Dependencies Editor

4511

@section The Project Dependencies Editor

4512

@cindex project dependencies

4513

@c -------------------------------------------------------------------

4514

4515

@noindent

4516

You can edit the dependencies between projects through the contextual

4517

menu @code{Project->Dependencies...} in the Project View.

4518

4519

This view makes it easy to indicate that your project depends on external

4520

libraries, or other modules in your source code. For instance, you can

4521

give access to the GtkAda graphical library in your project by adding

4522

a project dependency to gtkada.gpr, assuming GtkAda has been installed

4523

in your system.

4524

4525

The dependencies also determine in what order your application is built.

4526

When you compile a project, the builder will first make sure that the projects

4527

it depends on are up-to-date, and otherwise recompile them.

4528

4529

@iftex

4530

@cindex screen shot

4531

@image{project-deps, 12.7cm}

4532

@end iftex

4533

4534

@ifhtml

4535

@cindex screen shot

4536

@image{project-deps}

4537

@end ifhtml

4538

4539

When you select that contextual menu, GPS will open a dialog that allows

4540

you to add or remove dependencies to your project. New dependencies are

4541

added by selecting a project file name from one of several sources:

4542

4543

@itemize @bullet

4544

@item One of the loaded project from the current project tree

4545

4546

@item One of the predefined projects

4547

4548

These are the projects that are found in one of the directories referenced

4549

in the @code{ADA_PROJECT_PATH} environment variable. Typically, these

4550

include third party libraries, such as GtkAda, win32ada, @dots{}

4551

4552

@item A new project created through the project wizard

4553

4554

@item Any project file located on the disk

4555

4556

@end itemize

4557

4558

In all these cases, you will generally be able to choose whether this should

4559

be a simple dependency, or a limited dependency. The latter allows you to have

4560

mutually dependent projects (A depends on B, which in turns depends on A

4561

even indirectly), although you cannot reference the attribute of such a project

4562

in the current project (for instance to indicate that the compiler switches

4563

to use for A are the same as for B -- you need to duplicate that information).

4564

4565

In some cases, GPS will force a limited dependency on you to avoid loops in

4566

the dependencies that would make the project tree illegal.

4567

4568

@c -------------------------------------------------------------------

4569

@node The Project Properties Editor

4570

@section The Project Properties Editor

4571

@cindex project properties editor

4572

@c -------------------------------------------------------------------

4573

4574

@noindent

4575

The project properties editor gives you access at any time to the properties

4576

of your project. It is accessible through the menu

4577

@code{Project->Edit Project Properties}, and through the contextual menu

4578

@code{Edit project properties} on any project item, e.g. from the Project

4579

View or the Project Browser.

4580

4581

If there was an error loading the project (invalid syntax,

4582

non-existing directories, @dots{}), a warning dialog is displayed when you

4583

select the menu. This reminds you that the project might be only

4584

partially loaded, and editing it might result in the loss of data. In

4585

such cases, it is recommended that you edit the project file manually,

4586

which you can do directly from the pop-up dialog.

4587

4588

Fix the project file as you would for any text file, and then reload

4589

it manually (through the @code{Project->Open...} or

4590

@code{Project->Recent} menus.

4591

4592

@iftex

4593

@cindex screen shot

4594

@image{project-properties, 12.7cm}

4595

@end iftex

4596

4597

@ifhtml

4598

@cindex screen shot

4599

@image{project-properties}

4600

@end ifhtml

4601

4602

The project properties editor is divided in three parts:

4603

4604

@table @b

4605

@item The attributes editor

4606

The contents of this editor are very similar to that of the project

4607

wizard (@pxref{The Project Wizard}). In fact, all pages but the

4608

@code{General} page are exactly the same, and you should therefore

4609

read the description for these in the project wizard chapter.

4610

4611

The general page gives access to more attributes than the general page

4612

of the project wizard does. In addition, you can select the name of the

4613

external tools that GPS uses (such as compilers, debugger, @dots{}).

4614

4615

See also @ref{Working in a Cross Environment} for more info on the

4616

@code{Cross environment} attributes.

4617

4618

@item The project selector

4619

This area, in the top-right corner of the properties editor, contains

4620

a list of all the projects in the hierarchy. The value in the

4621

attributes editor is applied to all the selected projects in this

4622

selector. You cannot unselect the project for which you activated

4623

the contextual menu.

4624

4625

Clicking on the right title bar (@code{Project}) of this selector will sort the

4626

projects in ascending or descending order.

4627

4628

Clicking on the left title bar (untitled) will select or unselect all

4629

the projects.

4630

4631

This selector has two different possible presentations, chosen by the

4632

toggle button on top: you can either get a sorted list of all the

4633

projects, each one appearing only once. Or you can have the same

4634

project hierarchy as displayed in the project view.

4635

4636

@item The scenario selector

4637

This area, in the bottom-right corner of the properties editor, lists

4638

all the scenario variables declared for the project hierarchy. By

4639

selecting some or all of their values, you can chose to which scenario

4640

the modifications in the attributes editor apply.

4641

4642

Clicking on the left title bar (untitled, on the left of the @code{Scenario}

4643

label) will select or unselect all values of all variables.

4644

4645

To select all values of a given variable, click on the corresponding check

4646

button.

4647

4648

@end table

4649

4650

@c -------------------------------------------------------------------

4651

@node The Switches Editor

4652

@section The Switches Editor

4653

@cindex switches editor

4654

@c -------------------------------------------------------------------

4655

4656

@noindent

4657

The switches editor, available through the menu @code{Project->Edit

4658

Switches}, lists all the source files associated with the selected

4659

project.

4660

4661

For each file, the compiler switches are listed. These switches are

4662

displayed in gray if they are the default switches defined at the

4663

project level (@pxref{The Project Properties Editor}). They are defined

4664

in black if they are specific to a given file.

4665

4666

Double-clicking in the switches column allows you to edit the switches

4667

for a specific file. It is possible to edit the switches for multiple

4668

files at the same time by selecting them before displaying the contextual

4669

menu (@code{Edit switches for all selected files}).

4670

4671

When you double-click in one of the columns that contain the switches,

4672

a new dialog is opened that allows you to edit the switches specific to

4673

the selected files.

4674

4675

This dialog has a button titled @code{Revert}. Clicking on this button

4676

will cancel any file-specific switch, and revert to the default

4677

switches defined at the project level.

4678

4679

@iftex

4680

@cindex screen shot

4681

@image{switch-editor-revert, 11.7cm}

4682

@end iftex

4683

4684

@ifhtml

4685

@cindex screen shot

4686

@image{switch-editor-revert}

4687

@end ifhtml

4688

4689

@c -------------------------------------------------------------------

4690

@node The Project Browser

4691

@section The Project Browser

4692

@cindex project browser

4693

@c -------------------------------------------------------------------

4694

4695

@noindent

4696

The project graph is a special kind of browser (@pxref{Source

4697

Browsing}). It shows the dependencies between all the project in the

4698

project hierarchy. Two items in this browser will be linked if one of

4699

them imports the other.

4700

4701

@cindex examine projects imported by

4702

It is accessed through the contextual menu in the project view, by

4703

selecting the @code{Show projects imported by...} item, when

4704

right-clicking on a project node.

4705

4706

Clicking on the left arrow in the title bar of the items will display

4707

all the projects that import that project. Similarly, clicking

4708

on the right arrow will display all the projects that are imported by

4709

that project.

4710

4711

The contextual menu obtained by right-clicking on a project item

4712

contains several items. Most of them are added by the project editor,

4713

and gives direct access to editing the properties of the project,

4714

adding dependencies@dots{}

4715

@xref{The Project View}.

4716

4717

@iftex

4718

@cindex screen shot

4719

@image{project-browser, 10cm}

4720

@end iftex

4721

4722

@ifhtml

4723

@cindex screen shot

4724

@image{project-browser}

4725

@end ifhtml

4726

4727

Some new items are added to the menu:

4728

4729

@table @command

4730

@item Locate in Project View

4731

@cindex locate in Project View

4732

Selecting this item will switch the focus to the project view, and

4733

highlight the first project node found that matches the project in the

4734

browser item. This is a convenient way to get information like the

4735

list of directories or source files for that project.

4736

4737

@item Show dependencies

4738

@cindex show dependencies

4739

This item plays the same role as the right arrow in the title bar, and

4740

display all the projects in the hierarchy that are imported directly

4741

by the selected project

4742

4743

@item Show recursive dependencies

4744

@cindex show recursive dependencies

4745

This item will display all the dependencies recursively for the

4746

project (i.e. the projects it imports directly, the projects that

4747

are imported by them, and so on).

4748

4749

@item Show projects depending on

4750

@cindex show projects depending on

4751

This item plays the same role as the left arrow in the title bar, and

4752

displays all the projects that directly import the selected project.

4753

@end table

4754

4755

@c --------------------------------------------------------------------

4756

@node Searching and Replacing

4757

@chapter Searching and Replacing

4758

@cindex find

4759

@cindex search

4760

@cindex replace

4761

@c --------------------------------------------------------------------

4762

4763

@noindent

4764

GPS provides extensive search capabilities among its different

4765

elements. For instance, it is possible to search in the currently

4766

edited source file, or in all the source files belonging to the

4767

project, even those that are not currently open. It is also possible

4768

to search in the project view (on the left side of the main GPS

4769

window), @dots{}

4770

@cindex project view

4771

4772

@cindex menu

4773

@cindex key

4774

@cindex search context

4775

All these search contexts are grouped into a single graphical window,

4776

that you can open either through the menu @code{Navigate->Find/Replace...}, or

4777

the shortcut @key{Ctrl-F}.

4778

4779

By default, the search window is floating, ie appears as a dialog on top of

4780

GPS. You can choose to put it inside the multiple document interface

4781

permanently for easier access. This can be done by selecting the menu

4782

@code{Window->Floating}, and then drag-and-dropping the search window in a

4783

new location if you wish (for instance above the Project View).

4784

4785

Selecting either of these two options will pop up a dialog on the

4786

screen, similar to the following:

4787

4788

@iftex

4789

@cindex screen shot

4790

@image{search-hide, 5cm}

4791

@end iftex

4792

4793

@ifhtml

4794

@cindex screen shot

4795

@image{search-hide}

4796

@end ifhtml

4797

4798

On this screen shot, you can see three entry fields:

4799

4800

@table @command

4801

@item Search for

4802

@cindex search for

4803

This is the location where you type the string or pattern you are

4804

looking for. The search widget supports two modes, either fixed strings

4805

or regular expressions. You can commute between the two modes by

4806

either clicking on the @code{Options} button and selecting the

4807

appropriate check box, or by opening the combo box (click on the arrow

4808

on the right of the entry field).

4809

4810

In this combo box, a number of predefined patterns are provided. The

4811

top two ones are empty patterns, that automatically set up the

4812

appropriate fixed strings/regular expression mode. The other regular

4813

expressions are language-specific, and will match patterns like Ada

4814

type definition, C++ method declaration, @dots{}

4815

@cindex C++

4816

@cindex Ada

4817

4818

@item Replace with

4819

@cindex replace with

4820

This field should contain the string that will replace the occurrences

4821

of the pattern defined above.

4822

The combo box provides a history of previously used replacement

4823

strings.

4824

4825

@item Look in

4826

@cindex look in

4827

This field defines the context in which the search should

4828

occur.

4829

@cindex search context

4830

GPS will automatically select the most appropriate context when you

4831

open the search dialog, depending on which component currently has the

4832

focus. If several contexts are possible for one component (for example, the

4833

editor has "Current_File", "Files from Project", "Files..." and "Open Files"),

4834

then the last one you've been using will be selected. You can of course change

4835

the context to another one if needed.

4836

4837

Clicking on the arrow on the right will display the list of all

4838

possible contexts. This list includes:

4839

4840

@table @code

4841

@item Project View

4842

Search in the project view. An extra @i{Scope} box will be displayed

4843

where you can specify the scope of your search, which can be a set of:

4844

@code{Projects, Directories, Files, Entities}. The search in entities

4845

may take a long time, search each file is parsed during the search.

4846

4847

@item Open Files

4848

Search in all the files that are currently open in the source editor. The

4849

@i{Scope} entry is described in the @code{Files...} section below.

4850

4851

@item Files...

4852

Search in a given set of files. An extra @i{Files} box will be displayed

4853

where you can specify the files by using standard shell (Unix or Windows)

4854

regular expression, e.g. @code{*.ad?} for all files ending with .ad and any

4855

trailing character. The directory specified where the search starts, and

4856

the @i{Recursive search} button whether sub directories will be searched

4857

as well.

4858

4859

The @i{Scope} entry is used to restrict the search to a set of language

4860

constructs, e.g. to avoid matching on comments when you

4861

are only interested in actual code, or to only search strings and

4862

comments, and ignore the code.

4863

4864

@item Files From Project

4865

Search in all the files from the project, including files from project

4866

dependencies. The @i{Scope} entry is described in the @code{Files...}

4867

section above.

4868

4869

@item Current File

4870

Search in the current source editor.

4871

The @i{Scope} entry is described in the @code{Files...} section above.

4872

4873

@item Project Browser

4874

Search in the project browser (@pxref{The Project Browser}).

4875

4876

@end table

4877

4878

@end table

4879

4880

The second part of the window is a row of buttons, to start the search

4881

(or continue to the next occurrence), and to display the options.

4882

4883

@iftex

4884

@cindex screen shot

4885

@image{search-options, 6cm}

4886

@end iftex

4887

4888

@ifhtml

4889

@cindex screen shot

4890

@image{search-options}

4891

@end ifhtml

4892

4893

There are five check boxes in this options box.

4894

4895

@table @b

4896

@item @code{"Regexp"}

4897

@cindex regular expression

4898

This button commutes between fixed string patterns and regular

4899

expressions. You can also commute between these two modes

4900

by selecting the arrow on the right of the @code{Search for:} field.

4901

The grammar followed by the regular expressions is similar to the Perl and

4902

Python regular expressions grammar, and is documented in the GNAT run time file

4903

@file{g-regpat.ads}. To open it from GPS, you can use the open from project

4904

dialog (@code{File->Open From Project...}) and type g-regpat.ads. See

4905

@ref{Open From Project} for more information on this dialog.

4906

4907

@item @code{"Case Sensitive"}

4908

@cindex case sensitive

4909

By default, patterns are case insensitive (upper-case letters and

4910

lower-case letters are considered as equivalent). You can change this

4911

behavior by clicking on this check box.

4912

4913

@item @code{"Whole Word"}

4914

@cindex whole word

4915

If activated, this check box will force the search engine to ignore

4916

substrings. "sensitive" will no longer match "insensitive".

4917

4918

@item @code{Select on Match}

4919

@cindex select window on match

4920

When this button is selected, the focus is given to the editor that contains

4921

the match, so that you can start editing the text immediatly. If the button is

4922

not selected, the focus is left on the search window, so that you can press

4923

Enter to search for the next occurrence.

4924

4925

@item @code{Close on Match}

4926

@cindex close dialog on match

4927

This button only appears if the search window is floating. If this button is

4928

enabled, the search window will be automatically closed when an

4929

occurrence of the search string is found.

4930

4931

@end table

4932

4933

Pressing the @code{Find} / @code{Previous} buttons performs an interactive

4934

search.

4935

It stops as soon as one occurrence of the pattern is found.

4936

search. Once a first occurrence has been found, the @code{Find} button is

4937

renamed to @code{Next}.

4938

You then have to press the @code{Next} button (or the equivalent shortcut

4939

@key{Ctrl-N}) to go to the next occurrence.

4940

4941

If you use the @code{Find all} button, the search widget will start

4942

searching for all occurrences right away, and put the results in a new

4943

window called @code{Locations}, @xref{The Locations Tree}.

4944

4945

The @code{Replace} and @code{Replace & Find} buttons are grayed out as long as

4946

no occurence of the pattern is found. In order to enable them, you have to

4947

start a search, e.g. by pressing the @code{Find} button. Pressing @code{Replace}

4948

will replace the current occurence (and therefore the two buttons will be

4949

grayed out), and @code{Replace & Find} will replace the occurence and then

4950

jump to the next one, if any. If you don't want to replace the current

4951

occurence, you can jump directly to the next one by pressing @code{Next}.

4952

4953

The @code{Repl all} button will replace all the occurences found. By default,

4954

a popup is displayed and ask for confirmation. It's possible to disable this

4955

popup by either checking the box "Do not ask this question again", or by going

4956

in the Search pannel of the preferences pages, and unchecking "Confirmation for

4957

'Replace all'". The confirmation popup can be reenabled through this checkbox.

4958

4959

@cindex MDI

4960

@cindex Multiple Document Interface

4961

As most GPS components, the search window is under control of the

4962

multiple document interface, and can thus be integrated into the main

4963

GPS window instead of being an external window.

4964

4965

@cindex menu

4966

To force this behavior, open the menu @code{Window}, select

4967

@code{Search} in the list at the bottom of the menu, and then select

4968

either @code{Floating} or @code{Docked}.

4969

4970

If you save the desktop (@code{File->Save More->Desktop}, GPS will

4971

automatically reopen the search dialog in its new place when it is

4972

started next time.

4973

4974

@c --------------------------------------------------------------------

4975

@node Compilation/Build

4976

@chapter Compilation/Build

4977

@cindex compilation

4978

@cindex build

4979

@c --------------------------------------------------------------------

4980

4981

@noindent

4982

This chapter describes how to compile files, build executables and run

4983

them. Most capabilities can be accessed through the @code{Build} menu item,

4984

or through the @code{Build} and @code{Run} contextual menu items, as

4985

described in the following section.

4986

4987

When compiler messages are detected by GPS, an entry is added in the

4988

@i{Locations tree}, allowing you to easily navigate through the compiler

4989

messages (see @ref{The Locations Tree}), or even to automatically correct some

4990

errors or warnings (see @ref{Code Fixing}).

4991

4992

@menu

4993

* The Build Menu::

4994

@end menu

4995

4996

@node The Build Menu

4997

@section The Build Menu

4998

@noindent

4999

The build menu gives access to capabilities related to checking, parsing and

5000

compiling files, as well as creating and running executables.

5001

note that this menu is fully configurable via the @code{Targets} dialog,

5002

so what is documented in this manual are the default menus.

5003

5004

@table @b

5005

@item Check Syntax

5006

Check the syntax of the current source file. Display an error message in

5007

the @i{Messages} window if no file is currently selected.

5008

5009

@item Check Semantic

5010

Check the semantic of the current source file. Display an error message in

5011

the @i{Messages} window if no file is currently selected.

5012

5013

@item Compile File

5014

Compile the current file.

5015

By default, will display an intermediate dialog where you can add extra

5016

switches, or simply press @key{Enter} to get the standard (or previous)

5017

switches.

5018

Display an error message in the @i{Messages} window if no file is selected.

5019

5020

If errors or warnings occur during the compilation, the corresponding locations

5021

will appear in the Locations Tree. If the corresponding Preference is set, the

5022

source lines will be highlighted in the editors (see

5023

@ref{The Preferences Dialog}).

5024

To remove the highlighting on these lines, remove the files from the Locations

5025

Tree.

5026

5027

@item Project

5028

@table @i

5029

@item Build <main>

5030

The menu will list of all mains defined in your project hierarchy.

5031

Each menu item will build the selected main.

5032

5033

@item Build All

5034

Build and link all main units defined in your project.

5035

If no main unit is specified in your project, build all files defined

5036

in your project and subprojects recursively.

5037

For a library project file, compile sources and recreate the library

5038

when needed.

5039

5040

@item Compile All Sources

5041

Compile all source files defined in the top level project.

5042

5043

@item Build <current file>

5044

Consider the currently selected file as a main file, and build it.

5045

5046

@item Custom Build...

5047

Display a text entry where you can enter any external command. This menu

5048

is very useful when you already have existing build scripts, make files,

5049

@dots{} and want to invoke them from GPS. If the @code{SHELL} environment

5050

variable is defined (to e.g. @code{/bin/sh}), then the syntax used to

5051

execute the command is the one for this shell. Otherwise, the command

5052

will be spawned directly by GPS without any shell interpretation.

5053

5054

@end table

5055

5056

@item Clean

5057

@table @i

5058

@item Clean All

5059

Remove all object files and other compilation artifacts associated to all

5060

projects related to the current one. It allows to restart a complete build

5061

from scratch.

5062

5063

@item Clean Root

5064

Remove all object files and other compilation artifacts associated to the

5065

root project. It does not clean objects from other related projects.

5066

@end table

5067

5068

@item Run

5069

@table @i

5070

@item main

5071

For each main source file defined in your top level project, an entry

5072

is listed to run the executable associated with this main file.

5073

Running an application will first open a dialog where you can specify

5074

command line arguments to your application, if needed. You can also

5075

specify whether the application should be run within GPS (the default),

5076

or using an external terminal.

5077

5078

When running an application from GPS, a new execution window is added in the

5079

bottom area where input and output of the application is handled. This

5080

window is never closed automatically, even when the application terminates,

5081

so that you can still have access to the application's output. If you

5082

explicitly close an execution window while an application is still running,

5083

a dialog window will be displayed to confirm whether the application should

5084

be terminated.

5085

5086

When using an external terminal, GPS launches an external terminal

5087

utility that will take care of the execution and input/output of your

5088

application. This external utility can be configured in the preferences

5089

dialog (@i{External Commands->Execute command}).

5090

5091

The GPS execution windows have several limitations compared to external

5092

terminals. In particular, they do not handle signals like @key{ctrl-z}

5093

and @key{control-c}. In general, if you are running an interactive

5094

application, we strongly encourage you to run in an external terminal.

5095

5096

Similarly, the @code{Run} contextual menu accessible from a project

5097

entity contains the same entries.

5098

5099

@item Custom...

5100

Similar to the entry above, except that you can run any arbitrary executable.

5101

If the @code{SHELL} environment

5102

variable is defined (to e.g. @code{/bin/sh}), then the syntax used to

5103

execute the command is the one for this shell. Otherwise, the command

5104

will be spawned directly by GPS without any shell interpretation.

5105

5106

@item Last Launched

5107

This menu spawns the same command you previously spawned through the Run

5108

menu. However, it does not open an intermediate dialog. If you bind this

5109

dialog to a key shortcut through the @code{/Edit/Key Shortcuts} menu, this

5110

provides a convenient way to spawn the same command multiple times

5111

5112

@end table

5113

5114

@item Recompute Xref info

5115

@cindex C

5116

@cindex C++

5117

Recompute the cross-reference information for Ada, C and C++ source files.

5118

@xref{Support for Cross-References}.

5119

5120

@item Load xref info in meomry

5121

@cindex C

5122

@cindex C++

5123

Load all the cross-reference information in memory. This menu is generally

5124

not needed, @xref{Support for Cross-References}.

5125

5126

@item Settings

5127

@table @i

5128

@item Targets

5129

@c ??? TODO

5130

@item Toolchains

5131

@c ??? TODO

5132

5133

@end table

5134

@end table

5135

5136

The @code{Tools->Interrupt} menu can be used to interrupt the last compilation

5137

or run command. Once you have interrupted that last operation, you can

5138

interrupt the previous one by selecting the same menu again.

5139

5140

However, the easiest way to interrupt a specific operation, no matter if it was

5141

started last or not, is to use the @code{Task Manager}, through the

5142

@code{Tools->Views->Tasks} menu. It will show one line per running process,

5143

and right-clicking on any of these lines gives the possibility to interrupt

5144

that process.

5145

5146

If your application is build through a Makefile, you should probably load

5147

the @file{Makefile.py} startup script (see the menu @code{/Tools/Plug-ins}).

5148

5149

@c --------------------------------------------------------------------

5150

@node Source Browsing

5151

@chapter Source Browsing

5152

@cindex source browsing

5153

@c --------------------------------------------------------------------

5154

5155

@menu

5156

* General Issues::

5157

* Call Graph::

5158

* Dependency Browser::

5159

* Entity Browser::

5160

@end menu

5161

5162

@c --------------------------------------------------------------------

5163

@node General Issues

5164

@section General Issues

5165

@c --------------------------------------------------------------------

5166

5167

@noindent

5168

GPS contains several kinds of browsers, that have a common set of

5169

basic functionalities. There are currently four such browsers: the

5170

project browser (@pxref{The Project Browser}), the call graph

5171

(@pxref{Call Graph}), the dependency browser (@pxref{Dependency

5172

Browser}) and the entity browser (@pxref{Entity Browser}).

5173

5174

All these browsers are interactive viewers. They contain a number of

5175

items, whose visual representation depends on the type of information

5176

displayed in the browser (they can be projects, files, entities, @dots{}).

5177

5178

In addition, the following capabilities are provided in all browsers:

5179

5180

@table @b

5181

@item Scrolling

5182

When a lot of items are displayed in the canvas, the currently visible

5183

area might be too small to display all of them. In this case,

5184

scrollbars will be added on the sides, so that you can make other

5185

items visible. Scrolling can also be done with the arrow keys.

5186

5187

@item Layout

5188

A basic layout algorithm is used to organize the items. This algorithm

5189

is layer oriented: items with no parents are put in the first layer,

5190

then their direct children are put in the second layer, and so

5191

on. Depending on the type of browser, these layers are organized

5192

either vertically or horizontally. This algorithm tries to preserve as

5193

much as possible the positions of the items that were moved

5194

interactively.

5195

5196

The @code{Refresh layout} menu item in the background contextual menu

5197

can be used to recompute the layout of items at any time, even for

5198

items that were previously moved interactively.

5199

5200

@item Interactive moving of items

5201

Items can be moved interactively with the mouse. Click and drag the

5202

item by clicking on its title bar. The links will still be displayed

5203

during the move, so that you can check whether it overlaps any other

5204

item. If you are trying to move the item outside of the visible part

5205

of the browser, the latter will be scrolled.

5206

5207

@item Links

5208

Items can be linked together, and will remain connected when items are

5209

moved. Different types of links exist, see the description of the

5210

various browsers.

5211

5212

By default, links are displayed as straight lines. You can choose to

5213

use orthogonal links instead, which are displayed only with vertical

5214

or horizontal lines. Select the entry @code{orthogonal links} in the

5215

background contextual menu.

5216

5217

@item Exporting

5218

@cindex export

5219

@cindex image

5220

@cindex png

5221

@cindex svg

5222

The entire contents of a browser can be exported as a @code{PNG} image

5223

using the entry @code{Export to PNG...} in the background contextual menu.

5224

It can also be exported in @code{SVG} format using the @code{Export to SVG...}

5225

entry.

5226

5227

@item Zooming

5228

Several different zoom levels are available. The contextual menu in

5229

the background of the browser contains three entries: @code{zoom in},

5230

@code{zoom out} and @code{zoom}. The latter is used to select directly

5231

the zoom level you want.

5232

5233

This zooming capability is generally useful when lots of items are

5234

displayed in the browser, to get a more general view of the layout and

5235

the relationships between the items.

5236

5237

@item Selecting items

5238

Items can be selected by clicking inside them. Multiple items can be

5239

selected by holding the @key{control} key while clicking in the

5240

item. Alternatively, you can click and drag the mouse inside the

5241

background of the browser. All the items found in the selection

5242

rectangle when the mouse is released will be selected.

5243

5244

Selected items are drawn with a different title bar color. All items

5245

linked to them also use a different title bar color, as well as the

5246

links. This is the most convenient way to understand the relationships

5247

between items when lots of them are present in the browser.

5248

5249

@item Hyper-links

5250

Some of the items will contain hyper links, displayed in blue by

5251

default, and underlined. Clicking on these will generally display new

5252

items.

5253

5254

@end table

5255

5256

Two types of contextual menus are available in the browsers: the

5257

background contextual menu is available by right-clicking in the

5258

background area (i.e. outside of any item). As described above, it

5259

contains entries for the zooming, selecting of orthogonal links, and

5260

refresh; the second kind of contextual menu is available by

5261

right-clicking in items.

5262

5263

The latter menu contains various entries. Most of the entries are

5264

added by various modules in GPS (VCS module, source

5265

editor, @dots{}). In addition, each kind of browser also has some specific

5266

entries, which is described in the corresponding browser's section.

5267

5268

There are two common items in all item contextual menus:

5269

5270

@table @command

5271

@item Hide Links

5272

Browsers can become confusing if there are many items and many

5273

links. You can lighten them by selecting this menu entry. As

5274

a result, the item will remain in the canvas, but none of the links to

5275

or from it will be visible. Selecting the item will still

5276

highlight linked items, so that this information remains available.

5277

5278

@item Remove unselected items

5279

Selecting this menu will remove all the items that are not currently

5280

selected. This is a convenient method to clean up the contents of the

5281

browser.

5282

5283

@item Remove selected items

5284

Selecting this menu will remove all the items that are currently selected.

5285

5286

@end table

5287

5288

@c --------------------------------------------------------------------

5289

@node Call Graph

5290

@section Call Graph

5291

@cindex call graph

5292

@c --------------------------------------------------------------------

5293

5294

@noindent

5295

The call graph shows graphically the relationship between subprogram

5296

callers and callees. A link between two items indicate that one of

5297

them is calling the other.

5298

5299

@cindex renaming entities

5300

A special handling is provided for renaming entities (in Ada): if a

5301

subprogram is a renaming of another one, both items will be displayed

5302

in the browser, with a special hashed link between the two. Since the

5303

renaming subprogram doesn't have a proper body, you will then need to

5304

ask for the subprograms called by the renamed to get the list.

5305

5306

@iftex

5307

@cindex screen shot

5308

@image{call-graph, 12.7cm}

5309

@end iftex

5310

5311

@ifhtml

5312

@cindex screen shot

5313

@image{call-graph}

5314

@end ifhtml

5315

5316

In this browser, clicking on the right arrow in the title bar will

5317

display all the entities that are called by the selected item.

5318

5319

Clicking on the left arrow will display all the entities that call the

5320

selected item (i.e. its callers).

5321

5322

This browser is accessible through the contextual menu in the project

5323

view and source editor, by selecting one of the items:

5324

5325

All boxes in this browser list several information: the location of their

5326

declaration, and the list of all their references in the other entities

5327

currently displayed in the browser. If you close the box for an entity that

5328

calls them, the matching references are also hidden, to keep the contents

5329

of the browser simpler.

5330

5331

@table @command

5332

@item Browsers->@i{Entity} calls

5333

Display all the entities called by the selected entity. This has the

5334

same effect as clicking on the right title bar arrow if the item is

5335

already present in the call graph.

5336

5337

@item Browsers->@i{Entity} is called by

5338

Display all the entities called by the selected entity. This has the

5339

same effect as clicking on the left title bar arrow if the item is

5340

already present in the call graph.

5341

@end table

5342

5343

The contextual menu available by right-clicking on the entities in the

5344

browser has the following new entries, in addition to the ones added by

5345

other modules of GPS.

5346

5347

@table @command

5348

@item @i{Entity} calls

5349

Same as described above.

5350

5351

@item @i{Entity} is called by

5352

Same as described above.

5353

5354

@item Go To Spec

5355

Selecting this item will open a source editor that displays the

5356

declaration of the entity.

5357

5358

@item Go To Body

5359

Selecting this item will open a source editor that displays the

5360

body of the entity.

5361

5362

@item Locate in Project View

5363

Selecting this menu entry will move the focus to the project view,

5364

and select the first node representing the file in which the entity is

5365

declared. This makes it easier to see which other entities are

5366

declared in the same file.

5367

@end table

5368

5369

@c --------------------------------------------------------------------

5370

@node Dependency Browser

5371

@section Dependency Browser

5372

@cindex dependency browser

5373

@c --------------------------------------------------------------------

5374

5375

@noindent

5376

The dependency browser shows the dependencies between source

5377

files. Each item in the browser represents one source file.

5378

5379

@iftex

5380

@cindex screen shot

5381

@image{dependency-browser, 12.7cm}

5382

@end iftex

5383

5384

@ifhtml

5385

@cindex screen shot

5386

@image{dependency-browser}

5387

@end ifhtml

5388

5389

In this browser, clicking on the right arrow in the title bar will

5390

display the list of files that the selected file depends on. A file

5391

depend on another one if it explicitly imports it (@code{with}

5392

statement in Ada, or @code{#include} in C/C++). Implicit dependencies

5393

are currently not displayed in this browser, since the information is

5394

accessible by opening the other direct dependencies.

5395

5396

Clicking on the left arrow in the title bar will display the list of

5397

files that depend on the selected file.

5398

5399

This browser is accessible through the contextual menu in the

5400

project view and the source editor, by selecting one of the following items:

5401

5402

@table @command

5403

@item Show dependencies for @i{file}

5404

@cindex show dependencies for

5405

5406

This has the same effect as clicking on the right arrow for a file

5407

already in the browser, and will display the direct dependencies for

5408

that file.

5409

5410

@item Show files depending on @i{file}

5411

@cindex show files depending on

5412

5413

This has the same effect as clicking on the left arrow for a file

5414

already in the browser, and will display the list of files that

5415

directly depend on that file.

5416

5417

@end table

5418

5419

The background contextual menu in the browser adds a few entries to

5420

the standard menu:

5421

5422

@table @command

5423

@item Open file...

5424

5425

This menu entry will display an external dialog in which you can

5426

select the name of a file to analyze.

5427

5428

@item Recompute dependencies

5429

@cindex recompute dependencies

5430

5431

This menu entry will check that all links displays in the dependency

5432

browser are still valid. If not, they are removed. The arrows in the

5433

title bar are also reset if necessary, in case new dependencies were

5434

added for the files.

5435

5436

The browser is not refreshed automatically, since there are lots of

5437

cases where the dependencies might change (editing source files,

5438

changing the project hierarchy or the value of the scenario

5439

variables, @dots{})

5440

5441

It also recomputes the layout of the graph, and will change the current

5442

position of the boxes.

5443

5444

@item Show system files

5445

@cindex show system files

5446

5447

This menu entry indicates whether standard system files (runtime files

5448

for instance in the case of Ada) are displayed in the browser. By

5449

default, these files will only be displayed if you explicitly select

5450

them through the @code{Open file} menu, or the contextual menu in the

5451

project view.

5452

5453

@item Show implicit dependencies

5454

@cindex show implicit dependencies

5455

5456

This menu entry indicates whether implicit dependencies should also be

5457

displayed for the files. Implicit dependencies are files that are

5458

required to compile the selected file, but that are not explicitly

5459

imported through a @code{with} or @code{#include} statement. For

5460

instance, the body of generics in Ada is an implicit dependency.

5461

Any time one of the implicit dependencies is modified, the selected

5462

file should be recompiled as well.

5463

5464

@end table

5465

5466

The contextual menu available by right clicking on an item also adds a

5467

number of entries:

5468

5469

@table @command

5470

@item Analyze other file

5471

@cindex analyze other file

5472

5473

This will open a new item in the browser, displaying the complement

5474

file for the selected one. In Ada, this would be the body if you

5475

clicked on a spec file, or the opposite. In C, it depends on the

5476

naming conventions you specified in the project properties, but you

5477

would generally go from a @file{.h} file to a @file{.c} file and back.

5478

5479

@item Show dependencies for @i{file}

5480

@cindex show files depending on file

5481

5482

These play the same role as in the project view contextual menu

5483

5484

@end table

5485

5486

@c --------------------------------------------------------------------

5487

@node Entity Browser

5488

@section Entity Browser

5489

@cindex entity browser

5490

@c --------------------------------------------------------------------

5491

5492

@noindent

5493

The entity browser displays static information about any source

5494

entity.

5495

5496

The exact content of the items depend on the type of the item. For

5497

instance:

5498

5499

@table @code

5500

@item Ada record / C struct

5501

The list of fields, each as an hyper link, is displayed. Clicking on

5502

one of the fields will open a new item for the type.

5503

5504

@item Ada tagged type / C++ class

5505

The list of attributes and methods is displayed. They are also

5506

click-able hyper-links.

5507

5508

@item Subprograms

5509

The list of parameters is displayed

5510

5511

@item Packages

5512

The list of all the entities declared in that package is displayed

5513

5514

@item and more...

5515

5516

@end table

5517

5518

@iftex

5519

@cindex screen shot

5520

@image{entity-browser, 12.7cm}

5521

@end iftex

5522

5523

@ifhtml

5524

@cindex screen shot

5525

@image{entity-browser}

5526

@end ifhtml

5527

5528

This browser is accessible through the contextual menu in the

5529

project view and source editor, when clicking on an entity:

5530

5531

@table @command

5532

@item Browsers/Examine entity @i{entity}

5533

@cindex examine entity

5534

5535

Open a new item in the entity browser that displays information for

5536

the selected entity.

5537

5538

@end table

5539

5540

Most information in the items are click-able (by default, they appear as

5541

underlined blue text). Clicking on one of these hyper links will open

5542

a new item in the entity browser for the selected entity.

5543

5544

This browser can display the parent entities for an item. For

5545

instance, for a C++ class or Ada tagged type, this would be the types

5546

it derives from. This is accessible by clicking on the up arrow in the

5547

title bar of the item.

5548

5549

Likewise, children entities (for instance types that derive from the

5550

item) can be displayed by clicking on the down arrow in the title bar.

5551

5552

An extra button appear in the title bar for the C++ class or Ada

5553

tagged types, which toggles whether the inherited methods (or

5554

primitive operations in Ada) should be displayed. By default, only the

5555

new methods, or the ones that override an inherited one, are

5556

displayed. The parent's methods are not shown, unless you click on this

5557

title bar button.

5558

5559

@c --------------------------------------------------------------------

5560

@node Debugging

5561

@chapter Debugging

5562

@cindex debugger

5563

@cindex debugging

5564

@c --------------------------------------------------------------------

5565

5566

@noindent

5567

GPS is also a graphical front-end for text-based debuggers such as GDB.

5568

A knowledge of the basics of the underlying debugger used by GPS will help

5569

understanding how GPS works and what kind of functionalities it provides.

5570

5571

Please refer to the debugger-specific documentation -

5572

e.g. the GDB documentation

5573

@ifhtml

5574

(@url{gdb.html})

5575

@end ifhtml

5576

- for more details.

5577

5578

The integrated debugger provided by GPS is using an improved version of

5579

the GVD engine, so the functionalities between GVD and GPS are very similar.

5580

If you are familiar with GVD, you may be interested in reading

5581

@ref{Upgrading from GVD to GPS} which explains the differences between the

5582

two environments.

5583

5584

Debugging is tightly integrated with the other components of GPS. For

5585

example, it is possible to edit files and navigate through your sources

5586

while debugging.

5587

5588

@cindex menu

5589

To start a debug session, go to the menu @code{Debug->Initialize}, and choose

5590

either the name of your executable, if you have specified the name of

5591

your main program(s) in the project properties, or start an empty debug

5592

session using the @code{<no main file>} item. It is then possible to load

5593

any file to debug, by using the menu @code{Debug->Debug->Load File...}

5594

5595

Note that you can create multiple debuggers by using the @code{Initialize}

5596

menu several times: this will create a new debugger each time.

5597

All the debugger-related actions (e.g. stepping, running) are performed on

5598

the current debugger, which is represented by the current debugger console.

5599

To switch between debuggers, simply select its corresponding console.

5600

5601

After the debugger has been initialized, you have access to two new windows:

5602

the data window (in the top of the working area), and the debugger console

5603

(in a new page, after the Messages and Shell windows).

5604

All the menus under @code{Debugger}

5605

are now also accessible, and you also have access to additional contextual

5606

menus, in particular in the source editor where it is possible to easily

5607

display variables, set breakpoints, and get automatic display

5608

(via @i{tool tips}) of object values.

5609

5610

@cindex menu

5611

When you want to quit the debugger without quitting GPS, go to the menu

5612

@code{Debug->Terminate Current}, that will terminate your current debug

5613

session, or the menu @code{Debug->Terminate} that will terminate all your

5614

debug sessions at once.

5615

5616

@menu

5617

* The Debug Menu::

5618

* The Call Stack Window::

5619

* The Data Window::

5620

* The Breakpoint Editor::

5621

* The Memory Window::

5622

* Using the Source Editor when Debugging::

5623

* The Assembly Window::

5624

* The Debugger Console::

5625

* Customizing the Debugger::

5626

* Upgrading from GVD to GPS::

5627

@end menu

5628

5629

@c --------------------------------------------------------------------

5630

@node The Debug Menu

5631

@section The Debug Menu

5632

@cindex menu

5633

@cindex debug

5634

@cindex debugger

5635

@c --------------------------------------------------------------------

5636

5637

@noindent

5638

The @code{Debug} entry in the menu bar provides operations that act at a

5639

global level. Key shortcuts are available for the most common operations, and

5640

are displayed in the menus themselves.

5641

Here is a detailed list of the menu items that can be found in the menu bar:

5642

5643

@table @b

5644

@item Run...

5645

@cindex run

5646

Opens a dialog window allowing you to specify the arguments to pass to the

5647

program to be debugged, and whether this program should be stopped at the

5648

beginning of the main subprogram. If you confirm by clicking on the @i{OK}

5649

button, the program will be launched according to the arguments entered.

5650

5651

@item Step

5652

@cindex step

5653

Execute the program until it reaches a different source line.

5654

5655

@item Step Instruction

5656

@cindex stepi

5657

Execute the program for one machine instruction only.

5658

5659

@item Next

5660

@cindex next

5661

Execute the program until it reaches the next source line,

5662

stepping over subroutine calls.

5663

5664

@item Next Instruction

5665

@cindex nexti

5666

Execute the program until it reaches the next machine instruction,

5667

stepping over subroutine calls.

5668

5669

@item Finish

5670

@cindex finish

5671

Continue execution until selected stack frame returns.

5672

5673

@item Continue

5674

@cindex continue

5675

Continue execution of the program being debugged.

5676

5677

@item Interrupt

5678

@cindex interrupt

5679

Asynchronously interrupt the program being debugged. Note that depending on

5680

the state of the program, you may stop it in low-level system code that does

5681

not have debug information, or in some cases, not even a coherent state. Use

5682

of breakpoints is preferable to interrupting programs. Interrupting programs

5683

is nevertheless required in some situations, for example when the

5684

program appears to be in an infinite (or at least very time-consuming) loop.

5685

5686

@item Terminate Current

5687

@cindex terminate

5688

Terminate the current debug session

5689

by terminating the underlying debugger (e.g @code{gdb}) used

5690

to handle the low level debugging. You can control what happens to the

5691

windows through the @code{Debugger/Debugger Windows} preference.

5692

5693

@item Terminate

5694

@cindex terminate

5695

Terminate all your debug sessions. Same as @code{Terminate Current} if there

5696

is only one debugger open.

5697

5698

@end table

5699

5700

@subsection Debug

5701

5702

@table @b

5703

5704

@item Connect to Board...

5705

@cindex connect

5706

@cindex board

5707

@cindex target

5708

@cindex cross debugger

5709

Opens a simple dialog to connect to a remote board. This option is only

5710

relevant to cross debuggers.

5711

5712

@item Load File...

5713

@cindex load

5714

5715

@anchor{open program menu}

5716

Opens a file selection dialog that allows you to choose a program to

5717

debug. The program to debug is either an executable for native debugging, or

5718

a partially linked module for cross environments (e.g VxWorks).

5719

5720

@item Add Symbols...

5721

@cindex add symbols

5722

Add the symbols from a given file/module. This corresponds to the gdb

5723

command @i{add-symbol-file}. This menu is particularly useful under VxWorks

5724

targets, where the modules can be loaded independently of the debugger.

5725

For instance, if a module is independently loaded on the target (e.g. using

5726

windshell), it is absolutely required to use this functionality,

5727

otherwise the debugger won't work properly.

5728

5729

@item Attach...

5730

@cindex attach

5731

Instead of starting a program to debug, you can instead attach to an

5732

already running process. To do so, you need to specify the process id

5733

of the process you want to debug. The process might be busy in an

5734

infinite loop, or waiting for event processing. Note that as for

5735

@ref{core files}, you need to specify an executable before attaching to a

5736

process.

5737

5738

@item Detach

5739

@cindex detach

5740

Detaches the currently debugged process from the underlying debugger.

5741

This means that the executable will continue to run independently. You can use

5742

the @i{Attach To Process} menu later to re-attach to this process.

5743

5744

@item Debug Core File...

5745

@cindex core file

5746

@anchor{core files}

5747

This will open a file selection dialog that allows you to debug a core file

5748

instead of debugging a running process. Note that you must first specify an

5749

executable to debug before loading a core file.

5750

5751

@item Kill

5752

@cindex kill

5753

Kills the process being debugged.

5754

5755

@end table

5756

5757

@subsection Data

5758

@cindex menu

5759

@cindex data

5760

@noindent

5761

Note that most items in this menu need to access the underlying debugger

5762

when the process is stopped, not when it is running. This means that you first

5763

need to stop the process on a breakpoint or interrupt it, before using

5764

the following commands. Failing to do so will result in blank windows.

5765

5766

@table @b

5767

@item Data Window

5768

Displays the Data window. If this window already exists, it is raised so

5769

that it becomes visible

5770

5771

@item Call Stack

5772

@cindex call stack

5773

Displays the Call Stack window.

5774

See @ref{The Call Stack Window} for more details.

5775

5776

@item Threads

5777

@cindex thread

5778

Opens a new window containing the list of threads currently present in

5779

the executable as reported by the underlying debugger. For each thread,

5780

it will give information such as internal identifier, name and status.

5781

This information is language- and debugger-dependent. You should refer to

5782

the underlying debugger's documentation for more details.

5783

As indicated above, the process being debugged needs to be stopped

5784

before using this command, otherwise a blank list will be displayed.

5785

5786

When supported by the underlying debugger, clicking on a thread will

5787

change the context (variables, call stack, source file) displayed,

5788

allowing you to inspect the stack of the selected thread.

5789

5790

@item Tasks

5791

@cindex task

5792

For GDB only, this will open a new window containing the list of Ada

5793

tasks currently present in the executable. Similarly to the thread

5794

window, you can switch to a selected task context by clicking on it, if

5795

supported by GDB. See the GDB documentation for the list of

5796

items displayed for each task.

5797

5798

As for the thread window, the process being debugged needs to be stopped

5799

before using this window.

5800

5801

@iftex

5802

@cindex screen shot

5803

@image{tasks, 10.7cm}

5804

@end iftex

5805

5806

@ifhtml

5807

@cindex screen shot

5808

@image{tasks}

5809

@end ifhtml

5810

5811

@item Protection Domains

5812

@cindex protection domain

5813

For VxWorks AE only, this will open a new window containing the

5814

list of available protection domains in the target. To change to a

5815

different protection domain, simply click on it. A @c{*} character

5816

indicates the current protection domain.

5817

5818

@item Assembly

5819

@cindex assembly

5820

Opens a new window displaying an assembly dump of the current code

5821

being executed.

5822

See @ref{The Assembly Window} for more details.

5823

5824

@item Edit Breakpoints

5825

@cindex breakpoint

5826

Opens an advanced window to create and modify any kind of breakpoint,

5827

including watchpoints (see @ref{The Breakpoint Editor}).

5828

For simple breakpoint creation, see the description of the source window.

5829

5830

@item Examine Memory

5831

@cindex memory view

5832

Opens a memory viewer/editor. See @ref{The Memory Window} for more

5833

details.

5834

5835

@item Command History

5836

@cindex command

5837

@cindex history

5838

Opens a dialog with the list of commands executed in the current session.

5839

You can select any number of items in this list and replay the selection

5840

automatically.

5841

5842

@item Display Local Variables

5843

@cindex local variables

5844

Opens an item in the Data Window containing all the local variables

5845

for the current frame.

5846

5847

@item Display Arguments

5848

@cindex arguments

5849

Opens an item in the Data Window containing the arguments

5850

for the current frame.

5851

5852

@item Display Registers

5853

@cindex registers

5854

Opens an item in the Data Window containing the machine registers

5855

for the current frame.

5856

5857

@item Display Any Expression...

5858

@cindex display expression

5859

Opens a small dialog letting you specify an arbitrary expression

5860

in the Data Window. This expression can be a variable name, or a

5861

more complex expression, following the syntax of the underlying debugger.

5862

See the documentation of e.g gdb for more details on the syntax.

5863

The check button @i{Expression is a subprogram call} should be enabled

5864

if the expression is actually a debugger

5865

command (e.g @code{p/x var}) or a procedure call in the program being

5866

debugged (e.g @code{call my_proc}).

5867

5868

@item Recompute

5869

@cindex recompute

5870

Recomputes and refreshes all the items displayed in the Data Window.

5871

@end table

5872

5873

@c --------------------------------------------------------------------

5874

@node The Call Stack Window

5875

@section The Call Stack Window

5876

@cindex call stack

5877

@c --------------------------------------------------------------------

5878

5879

@noindent

5880

The call stack window gives a list of frames corresponding to the current

5881

execution stack for the current thread/task.

5882

5883

@iftex

5884

@cindex screen shot

5885

@image{call-stack, 12.7cm}

5886

@end iftex

5887

5888

@ifhtml

5889

@cindex screen shot

5890

@image{call-stack}

5891

@end ifhtml

5892

5893

The bottom frame corresponds to the outermost frame where the thread is

5894

currently stopped. This frame corresponds to the first function

5895

executed by the current thread (e.g main if the main thread is in C).

5896

You can click on any frame to switch to the caller's context, this will

5897

update the display in the source window. See also the up and down

5898

buttons in the tool bar to go up and down one frame in the call stack.

5899

5900

@cindex contextual menu

5901

The contextual menu (right mouse button) allows you to choose which

5902

information you want to display in the call stack window (via check buttons):

5903

@itemize @bullet

5904

@item Frame number: the debugger frame number (usually starts at 0 or 1)

5905

@item Program Counter: the low level address corresponding to the

5906

function's entry point.

5907

@item Subprogram Name: the name of the subprogram in a given frame

5908

@item Parameters: the parameters of the subprogram

5909

@item File Location: the filename and line number information.

5910

@end itemize

5911

5912

By default, only the subprogram name is displayed.

5913

You can hide the call stack window by closing it, as for other windows, and

5914

show it again using the menu @code{Data->Call Stack}.

5915

5916

@c --------------------------------------------------------------------

5917

@node The Data Window

5918

@section The Data Window

5919

@cindex data

5920

@cindex data window

5921

@c --------------------------------------------------------------------

5922

5923

@c --------------------------------------------------------------------

5924

@subsection Description

5925

@c --------------------------------------------------------------------

5926

5927

@noindent

5928

5929

The Data Window is the area in which various information about the debugged

5930

process can be displayed. This includes the value of selected variables, the

5931

current contents of the registeres, the local variables, @dots{}

5932

5933

@cindex Data Window

5934

This window is not open by default when you start the debugger. It will be

5935

created automatically when needed (e.g. when using the Debug constextual menu

5936

to display a variable). You can also force its display through the menu

5937

@code{Debug->Data->Data Window}.

5938

5939

However, if you save the desktop through the menu

5940

@code{File->Save More->Desktop} while the data window is open, it will be

5941

automatically reopen the next time the desktop is loaded, for instance when

5942

restarting GPS.

5943

5944

The contents of the data window is preserved by default whenever you close it.

5945

Thus, if you reopen the data window either during the same debugger session,

5946

or automatically when you start a debugger on the same executable, it will

5947

display the same items again. This behavior is controlled by the

5948

@code{Preserve State on Exit} preference.

5949

5950

@cindex menu

5951

@cindex contextual menu

5952

The data window contains all the graphic boxes that can be accessed

5953

using the @i{Data->Display} menu items, or the data window

5954

@i{Display Expression...} contextual menu, or the source window

5955

@i{Display} contextual menu items, or finally the

5956

@i{graph} command in the debugger console.

5957

5958

For each of these commands, a box is displayed in the data window

5959

with the following information:

5960

5961

@iftex

5962

@cindex screen shot

5963

@image{canvas, 9.8cm}

5964

@end iftex

5965

5966

@ifhtml

5967

@cindex screen shot

5968

@image{canvas}

5969

@end ifhtml

5970

5971

@itemize @bullet

5972

@item A title bar containing:

5973

@cindex title bar

5974

@itemize @bullet

5975

@item The number of this expression: this is a positive number starting

5976

from 1 and incremented for each new box displayed. It represents the

5977

internal identifier of the box.

5978

5979

@item The name of the expression: this is the expression or variable

5980

specified when creating the box.

5981

5982

@item An icon representing either a flash light, or a lock.

5983

@cindex icon

5984

This is a click-able icon that will change the state of the box from

5985

automatically updated (the flash light icon) to frozen (the lock

5986

icon).

5987

When frozen, the value is grayed, and will not change until you change

5988

the state. When updated, the value of the box will be recomputed each

5989

time an execution command is sent to the debugger (e.g step, next).

5990

5991

@item An icon representing an 'X'.

5992

@cindex icon

5993

You can click on this icon to close/delete any box.

5994

@end itemize

5995

5996

@item A main area.

5997

The main area will display the data value hierarchically

5998

in a language-sensitive manner. The canvas knows about data structures

5999

of various languages (e.g @code{C}, @code{Ada}, @code{C++}) and will

6000

organize them accordingly.

6001

For example, each field of a record/struct/class, or each item of an

6002

array will be displayed separately. For each subcomponent, a thin box

6003

is displayed to distinguish it from the other components.

6004

@end itemize

6005

6006

@cindex contextual menu

6007

A contextual menu, that takes into account the current component selected

6008

by the mouse, gives access to the following capabilities:

6009

@table @b

6010

@item Close @i{component}

6011

Closes the selected item.

6012

6013

@item Hide all @i{component}

6014

@cindex hide

6015

Hides all subcomponents of the selected item. To select a particular field

6016

or item in a record/array, move your mouse over the name of this

6017

component, not over the box containing the values for this item.

6018

6019

@item Show all @i{component}

6020

@cindex show

6021

Shows all subcomponents of the selected item.

6022

6023

@item Clone @i{component}

6024

@cindex clone

6025

Clones the selected component into a new, independent item.

6026

6027

@item View memory at address of @i{component}

6028

@cindex memory view

6029

Brings up the memory view dialog and explore memory at the address of the

6030

component.

6031

6032

@item Set value of @i{component}

6033

Sets the value of a selected component. This will open an entry box

6034

where you can enter the new value of a variable/component. Note that

6035

GDB does not perform any type or range checking on the value entered.

6036

6037

@item Update Value

6038

@cindex update value

6039

Refreshes the value displayed in the selected item.

6040

6041

@item Show Value

6042

@cindex show value

6043

Shows only the value of the item.

6044

6045

@item Show Type

6046

@cindex show type

6047

Shows only the type of each field for the item.

6048

6049

@item Show Value+Type

6050

Shows both the value and the type of the item.

6051

6052

@c ??? Should have screen shot with value + type

6053

6054

@item Auto refresh

6055

@cindex auto refresh

6056

Enables or disables the automatic refreshing of the item upon program execution

6057

(e.g step, next).

6058

6059

@end table

6060

6061

@cindex contextual menu

6062

A contextual menu can be accessed in the canvas itself (point the mouse to

6063

an empty area in the canvas, and click on the right mouse button) with the

6064

following entries:

6065

@table @b

6066

@item Display Expression...

6067

@cindex display expression

6068

Open a small dialog letting you specify an arbitrary expression

6069

in the Data Window. This expression can be a variable name, or a

6070

more complex expression, following the syntax of the current language and

6071

underlying debugger.

6072

See the documentation of e.g gdb for more details on the syntax.

6073

The check button @i{Expression is a subprogram call} should be enabled

6074

if the expression is actually not an expression but rather a debugger

6075

command (e.g @code{p/x var}) or a procedure call in the program being

6076

debugged (e.g @code{call my_proc}).

6077

6078

@item Align On Grid

6079

@cindex align

6080

Enables or disables alignment of items on the grid.

6081

6082

@item Detect Aliases

6083

@cindex aliases

6084

Enables or disables the automatic detection of shared data structures.

6085

Each time you display an item or dereference a pointer, all

6086

the items already displayed on the canvas are considered and their addresses

6087

are compared with the address of the new item to display. If they match,

6088

(for example if you tried to dereference a pointer to an object already

6089

displayed) instead of creating a new item a link will be displayed.

6090

6091

@item Zoom in

6092

@cindex zoom in

6093

Redisplays the items in the data window with a bigger font

6094

6095

@item Zoom out

6096

@cindex zoom out

6097

Displays the items in the data window with smaller fonts and pixmaps. This

6098

can be used when you have several items in the window and you can't see all

6099

of them at the same time (for instance if you are displaying a tree and

6100

want to clearly see its structure).

6101

6102

@item Zoom

6103

@cindex zoom

6104

Allows you to choose the zoom level directly from a menu.

6105

6106

@item Clear

6107

@cindex clear

6108

When this item is selected, all the boxes currently displayed are removed.

6109

6110

@end table

6111

6112

@c --------------------------------------------------------------------

6113

@subsection Manipulating items

6114

@c --------------------------------------------------------------------

6115

6116

@subsubsection Moving items

6117

@noindent

6118

All the items on the canvas have some common behavior and can be fully

6119

manipulated with the mouse.

6120

They can be moved freely anywhere on the canvas, simply by clicking on

6121

them and then dragging the mouse. Note that if you are trying to move

6122

an item outside of the visible area of the data window, the latter will

6123

be scrolled so as to make the new position visible.

6124

6125

Automatic scrolling is also provided if you move the mouse while dragging

6126

an item near the borders of the data window. As long as the mouse

6127

remains close to the border and the button is pressed on the item,

6128

the data window is scrolled and the item is moved. This provides an

6129

easy way to move an item a long distance from its initial position.

6130

6131

@subsubsection Colors

6132

@noindent

6133

Most of the items are displayed using several colors, each

6134

conveying a special meaning. Here is the meaning assigned to all colors

6135

(note that the exact color can be changed through the preferences

6136

dialog; these are the default colors):

6137

6138

@iftex

6139

@cindex screen shot

6140

@image{colors, 10cm}

6141

@end iftex

6142

6143

@ifhtml

6144

@cindex screen shot

6145

@image{colors}

6146

@end ifhtml

6147

6148

@table @b

6149

6150

@item black

6151

This is the default color used to print the value of variables or

6152

expressions.

6153

6154

@item blue

6155

@cindex C

6156

@cindex Ada

6157

This color is used for C pointers (or Ada access values), i.e. all the variables

6158

and fields that are memory addresses that denote some other value in

6159

memory.

6160

6161

You can easily dereference these (that is to say see the value pointed to)

6162

by double-clicking on the blue text itself.

6163

6164

@item red

6165

This color is used for variables and fields whose value has changed since

6166

the data window was last displayed. For instance, if you display an array

6167

in the data window and then select the @i{Next} button in the tool bar, then

6168

the elements of the array whose value has just changed will appear in red.

6169

6170

@cindex menu

6171

As another example, if you choose to display the value of local variables in

6172

the data window (@i{Display->Display Local Variables}), then only the

6173

variables whose value has changed are highlighted, the others are left in

6174

black.

6175

6176

@end table

6177

6178

@subsubsection Icons

6179

@cindex icon

6180

@noindent

6181

Several different icons can be used in the display of items. They also

6182

convey special meanings.

6183

6184

@table @b

6185

6186

@item trash bin icon

6187

This icon indicates that the debugger could not get the value of the

6188

variable or expression. There might be several reasons, for instance the

6189

variable is currently not in scope (and thus does not exist), or it might

6190

have been optimized away by the compiler. In all cases, the display will be

6191

updated as soon as the variable becomes visible again.

6192

6193

@item package icon

6194

This icon indicates that part of a complex structure is currently hidden.

6195

Manipulating huge items in the data window (for instance if the variable

6196

is an array of hundreds of complex elements) might not be very helpful. As a

6197

result, you can shrink part of the value to save some screen space and make it

6198

easier to visualize the interesting parts of these variables.

6199

6200

Double-clicking on this icon will expand the hidden part, and clicking on

6201

any sub-rectangle in the display of the variable will hide that part and

6202

replace it with that icon.

6203

6204

See also the description of the contextual menu to automatically show or hide

6205

all the contents of an item. Note also that one alternative to hiding

6206

subcomponents is to clone them in a separate item (see the contextual menu

6207

again).

6208

6209

@end table

6210

6211

@c --------------------------------------------------------------------

6212

@node The Breakpoint Editor

6213

@section The Breakpoint Editor

6214

@cindex breakpoint editor

6215

@cindex breakpoint

6216

@c --------------------------------------------------------------------

6217

6218

@iftex

6219

@cindex screen shot

6220

@image{breakpoints, 11.7cm}

6221

@end iftex

6222

6223

@ifhtml

6224

@cindex screen shot

6225

@image{breakpoints}

6226

@end ifhtml

6227

6228

@noindent

6229

@cindex menu

6230

The breakpoint editor can be accessed from the menu

6231

@i{Data->Edit Breakpoints}. It allows manipulation of different kinds

6232

of breakpoints: at a source location, on a subprogram, at an executable

6233

address, on memory access (watchpoints), and on Ada exceptions.

6234

6235

The top area provides an interface to create the different kinds of

6236

breakpoints, while the bottom area lists existing breakpoints and

6237

their characteristics.

6238

6239

It is possible to access advanced breakpoint characteristics for a given

6240

breakpoint. First, select a breakpoint in the list. Then, click

6241

on the @i{Advanced} button, which will display a new dialog window.

6242

You can specify commands to run automatically after a breakpoint

6243

is hit, or specify how many times a selected breakpoint will be ignored.

6244

If running VxWorks AE, you can also change the Scope and Action settings

6245

for breakpoints.

6246

6247

@iftex

6248

@cindex screen shot

6249

@image{bp-advanced, 8.7cm}

6250

@end iftex

6251

6252

@ifhtml

6253

@cindex screen shot

6254

@image{bp-advanced}

6255

@end ifhtml

6256

6257

@subsection Scope/Action Settings for VxWorks AE

6258

@cindex VxWorks AE

6259

6260

@noindent

6261

In VxWorks AE breakpoints have two extra properties:

6262

6263

@itemize @bullet

6264

@item Scope:

6265

@cindex scope

6266

which task(s) can hit a given breakpoint. Possible Scope values are:

6267

@itemize @minus

6268

@item task:

6269

@cindex task

6270

the breakpoint can only be hit by the task that was active when the

6271

breakpoint was set. If the breakpoint is set before the program is

6272

run, the breakpoint will affect the environment task

6273

@item pd:

6274

@cindex protection domain

6275

any task in the current protection domain can hit that breakpoint

6276

@item any:

6277

any task in any protection domain can hit that breakpoint. This

6278

setting is only allowed for tasks in the Kernel domain.

6279

6280

@end itemize

6281

6282

@item Action:

6283

@cindex action

6284

when a task hits a breakpoints, which tasks are stopped:

6285

@itemize @minus

6286

@item task:

6287

@cindex task

6288

stop only the task that hit the breakpoint.

6289

@item pd:

6290

@cindex protection domain

6291

stop all tasks in the current protection domain

6292

@item all:

6293

stop all breakable tasks in the system

6294

6295

@end itemize

6296

@end itemize

6297

6298

These two properties can be set/changed through the advanced breakpoints

6299

characteristics by clicking on the @i{Advanced} button. There are two

6300

ways of setting these properties:

6301

6302

@itemize @bullet

6303

6304

@item Per breakpoint settings:

6305

after setting a breakpoint (the default Scope/Action values will be

6306

task/task), select the @i{Scope/Action} tab in the @i{Advanced} settings.

6307

To change these settings on a given breakpoint, select it from

6308

the breakpoints list, select the desired values of Scope and Action and click

6309

on the @i{Update} button.

6310

6311

@item Default session settings:

6312

select the @i{Scope/Action} tab in the

6313

@i{Advanced} settings. Select the desired Scope and Action settings, check

6314

the @i{Set as session defaults} check box below and click the @i{Close}

6315

button. From now on, every new breakpoint will have the selected values

6316

for Scope and Action.

6317

6318

@end itemize

6319

6320

@cindex saving breakpoints

6321

@cindex breakpoints, saving

6322

If you have enabled the preference @code{Preserve state on exit}, GPS will

6323

automatically save the currently set breakpoints, and restore them the next

6324

time you debug the same executable. This allows you to immediately start

6325

debugging your application again, without reseting the breakpoints every time.

6326

6327

@c --------------------------------------------------------------------

6328

@node The Memory Window

6329

@section The Memory Window

6330

@cindex memory view

6331

@c --------------------------------------------------------------------

6332

6333

@iftex

6334

@cindex screen shot

6335

@image{memory-view, 12.7cm}

6336

@end iftex

6337

6338

@ifhtml

6339

@cindex screen shot

6340

@image{memory-view}

6341

@end ifhtml

6342

6343

@noindent

6344

The memory window allows you to display the contents of memory by

6345

specifying either an address, or a variable name.

6346

6347

@cindex C

6348

@cindex hexadecimal

6349

To display memory contents, enter the address using the C hexadecimal notation:

6350

0xabcd, or the name of a variable, e.g foo, in the @i{Location} text entry.

6351

In the latter case, its address is computed automatically. Then either press

6352

@i{Enter} or click on the @i{View} button. This will display the memory with

6353

the corresponding addresses in the bottom text area.

6354

6355

@cindex ASCII

6356

You can also specify the unit size (@i{Byte}, @i{Halfword} or @i{Word}),

6357

the format (@i{Hexadecimal}, @i{Decimal}, @i{Octal} or @i{ASCII}), and you

6358

can display the corresponding ASCII value at the same time.

6359

6360

@cindex key

6361

The @i{up} and @i{down} arrows as well as the @key{Page up} and @key{Page down}

6362

keys in the memory text area allows you to walk through the memory in

6363

order of ascending/descending addresses respectively.

6364

6365

Finally, you can modify a memory area by simply clicking on the location

6366

you want to modify, and by entering the new values. Modified values will

6367

appear in a different color (red by default) and will only be taken into

6368

account (i.e written to the target) when you click on the @i{Submit changes}

6369

button. Clicking on the @i{Undo changes} or going up/down in the memory

6370

will undo your editing.

6371

6372

Clicking on @i{Close} will close the memory window, canceling your last

6373

pending changes, if any.

6374

6375

@c --------------------------------------------------------------------

6376

@node Using the Source Editor when Debugging

6377

@section Using the Source Editor when Debugging

6378

@cindex source file

6379

@cindex editing

6380

@cindex debug

6381

@c --------------------------------------------------------------------

6382

6383

@noindent

6384

When debugging, the left area of each source editor provides the

6385

following information:

6386

6387

@table @b

6388

@item Lines with code

6389

In this area, blue dots are present next to lines for which the debugger

6390

has debug information, in other words, lines that have been compiled with

6391

debug information and for which the compiler has generated some code.

6392

Currently, there is no check when you try to set a breakpoint on a non dotted

6393

line: this will simply send the breakpoint command to the underlying

6394

debugger, and usually (e.g in the case of gdb) result in setting a

6395

breakpoint at the closest location that matches the file and line that you

6396

specified.

6397

@item Current line executed

6398

@cindex current line

6399

This is a green arrow showing the line about to be executed.

6400

6401

@item Lines with breakpoints

6402

@cindex breakpoint

6403

For lines where breakpoints have been set, a red mark is displayed on top

6404

of the blue dot for the line. You can add and delete

6405

breakpoints by clicking on this area (the first click will set a breakpoint,

6406

the second click will remove it).

6407

@end table

6408

6409

@iftex

6410

@cindex screen shot

6411

@image{tooltips, 12.7cm}

6412

@end iftex

6413

6414

@ifhtml

6415

@cindex screen shot

6416

@image{tooltips}

6417

@end ifhtml

6418

6419

@cindex syntax highlighting

6420

@cindex tooltip

6421

The second area in the source window is a text window on the right that

6422

displays the source files, with syntax highlighting.

6423

If you leave the cursor over a variable, a tooltip will

6424

appear showing the value of this variable. Automatic tooltips can be

6425

disabled in the preferences menu.

6426

@cindex preferences

6427

See @ref{preferences dialog}.

6428

6429

@cindex contextual menu

6430

When the debugger is active, the contextual menu of the source window

6431

contains a sub menu called @code{Debug} providing the following entries.

6432

6433

Note that these entries are dynamic: they will apply to the entity

6434

found under the cursor when the menu is displayed (depending on the current

6435

language). In addition, if a selection has been made in the source window the

6436

text of the selection will be used instead. This allows you to display

6437

more complex expressions easily (for example by adding some comments to your

6438

code with the complex expressions you want to be able to display in the

6439

debugger).

6440

6441

@table @b

6442

@item Print @i{selection}

6443

@cindex print

6444

Prints the selection (or by default the name under the cursor) in the

6445

debugger console.

6446

6447

@item Display @i{selection}

6448

@cindex display

6449

Displays the selection (or by default the name under the cursor) in the

6450

data window. The value will be automatically refreshed each time the process

6451

state changes (e.g after a step or a next command). To freeze the display

6452

in the canvas, you can either click on the corresponding icon in the data

6453

window, or use the contextual menu for the specific item (see

6454

@ref{The Data Window} for more information).

6455

6456

@item Print @i{selection}.all

6457

Dereferences the selection (or by default the name under the cursor) and

6458

prints the value in the debugger console.

6459

6460

@item Display @i{selection}.all

6461

Dereferences the selection (or by default the name under the cursor) and

6462

displays the value in the data window.

6463

6464

@item View memory at address of @i{selection}

6465

@cindex memory view

6466

Brings up the memory view dialog and explores memory at the address of the

6467

selection.

6468

6469

@item Set Breakpoint on Line @i{xx}

6470

@cindex breakpoint

6471

Sets a breakpoint on the line under the cursor, in the current file.

6472

6473

@item Set Breakpoint on @i{selection}

6474

Sets a breakpoint at the beginning of the subprogram named @i{selection}

6475

6476

@item Continue Until Line @i{xx}

6477

@cindex continue until

6478

Continues execution (the program must have been started previously) until

6479

it reaches the specified line.

6480

6481

@item Show Current Location

6482

@cindex current location

6483

Jumps to the current line of execution. This is particularly useful after

6484

navigating through your source code.

6485

6486

@end table

6487

6488

@c --------------------------------------------------------------------

6489

@node The Assembly Window

6490

@section The Assembly Window

6491

@c --------------------------------------------------------------------

6492

6493

It is sometimes convenient to look at the assembly code for the subprogram

6494

or source line you are currently debugging.

6495

6496

You can open the assembly window by using the menu

6497

@code{Debug->Data->Assembly}.

6498

6499

@iftex

6500

@cindex screen shot

6501

@image{assembly, 12.7cm}

6502

@end iftex

6503

6504

@ifhtml

6505

@cindex screen shot

6506

@image{assembly}

6507

@end ifhtml

6508

6509

The current assembly instruction is highlighted with a green

6510

arrow on its left. The instructions corresponding to the current source

6511

line are highlighted in red by default. This allows you to easily see

6512

where the program counter will point to, once you have pressed the "Next"

6513

button on the tool bar.

6514

6515

Moving to the next assembly instruction is done through the "Nexti"

6516

(next instruction) button in the tool bar. If you choose "Stepi"

6517

instead (step instruction), this will also jump to the subprogram

6518

being called.

6519

6520

For efficiency reasons, only a small part of the assembly code around the

6521

current instruction is displayed.

6522

You can specify in the @ref{preferences dialog} how many instructions

6523

are displayed by default. Also, you can easily

6524

display the instructions immediately preceding or following the

6525

currently displayed instructions by pressing one of the @key{Page up} or

6526

@key{Page down} keys, or by using the contextual menu in the assembly

6527

window.

6528

6529

A convenient complement when debugging at the assembly level is the

6530

ability of displaying the contents of machine registers.

6531

When the debugger supports it (as gdb does), you can select the

6532

@code{Data->Display Registers} menu to get an item in the canvas that will

6533

show the current contents of each machine register, and that will be updated

6534

every time one of them changes.

6535

6536

You might also choose to look at a single register.

6537

With gdb, select the @code{Data->Display Any Expression}, entering

6538

something like

6539

6540

@cindex example

6541

@smallexample

6542

output /x $eax

6543

@end smallexample

6544

6545

in the field, and selecting the toggle button "Expression is a subprogram

6546

call". This will create a new canvas item that will be refreshed every

6547

time the value of the register (in this case eax) changes.

6548

6549

@c --------------------------------------------------------------------

6550

@node The Debugger Console

6551

@section The Debugger Console

6552

@cindex debugger

6553

@cindex debugger console

6554

@c --------------------------------------------------------------------

6555

6556

@noindent

6557

This is the text window located at the bottom of the main window.

6558

In this console, you have direct access to the underlying debugger,

6559

and can send commands (you need to refer to the underlying debugger's

6560

documentation, but usually typing @i{help} will give you an overview of

6561

the commands available).

6562

6563

If the underlying debugger allows it, pressing @key{Tab} in this

6564

window will provide completion for the command that is being typed (or for

6565

its arguments).

6566

6567

There are also additional commands defined to provide a simple

6568

text interface to some graphical features.

6569

6570

Here is the complete list of such commands. The arguments between square

6571

brackets are optional and can be omitted.

6572

6573

@table @command

6574

@item graph (print|display) expression [dependent on display_num] [link_name name] [at x, y] [num num]

6575

@cindex graph print

6576

@cindex graph display

6577

This command creates a new item in the canvas, that shows the value of

6578

@var{Expression}. @var{Expression} should be the name of a variable, or one

6579

of its fields, that is in the current scope for the debugger.

6580

6581

The command @code{graph print} will create a frozen item, that is not

6582

automatically refreshed when the debugger stops, whereas @code{graph display}

6583

displays an automatically refreshed item.

6584

6585

The new item is associated with a number, that is visible in its title bar.

6586

This number can be specified through the @code{num} keyword, and will be taken

6587

into account if no such item already exists.

6588

These numbers can be used to create links between the items, using the

6589

second argument to the command, @var{dependent on}. The link itself (i.e. the

6590

line) can be given a name that is automatically displayed, using the third

6591

argument.

6592

6593

@item graph (print|display) `command`

6594

This command is similar to the one above, except it should be used to

6595

display the result of a debugger command in the canvas.

6596

6597

For instance, if you want to display the value of a variable in hexadecimal

6598

rather than the default decimal with gdb, you should use a command like:

6599

6600

@cindex example

6601

@smallexample

6602

graph display `print /x my_variable`

6603

@end smallexample

6604

6605

This will evaluate the command between back-quotes every time the debugger

6606

stops, and display this in the canvas. The lines that have changed will

6607

be automatically highlighted (in red by default).

6608

6609

This command is the one used by default to display the value of registers

6610

for instance.

6611

6612

@item graph (enable|disable) display display_num [display_num ...]

6613

@cindex graph enable

6614

@cindex graph disable

6615

This command will change the refresh status of items in the canvas. As

6616

explained above, items are associated with a number visible in their title

6617

bar.

6618

6619

Using the @code{graph enable} command will force the item to be automatically

6620

refreshed every time the debugger stops, whereas the @code{graph disable}

6621

command will freeze the item.

6622

6623

@item graph undisplay display_num

6624

@cindex graph undisplay

6625

This command will remove an item from the canvas

6626

6627

@item view (source|asm|source_asm)

6628

@cindex view

6629

@cindex asm

6630

This command indicates what should be displayed in the source window.

6631

The first option indicates that only the source code should be visible,

6632

the second one specifies that only the assembly code should be visible,

6633

and the last one indicates that both should be displayed.

6634

6635

@end table

6636

6637

@node Upgrading from GVD to GPS

6638

@section Upgrading from GVD to GPS

6639

@noindent

6640

This section is intended for users already familiar with GVD, in order

6641

to help them transitioning to GPS. If you have not used GVD, you may want

6642

to skip this section.

6643

6644

This section outlines the differences between GVD and GPS, and also

6645

lists some of the advantages of GPS compared to GVD.

6646

6647

@subsection Command Line Switches

6648

@noindent

6649

The following command line switches related to debugging are available

6650

in GPS:

6651

6652

@table @code

6653

@item --debug

6654

Automatically start a debug session, as done by GVD.

6655

You can also specify a program name and its arguments, so this

6656

option replaces the @code{--pargs} and @code{executable-file} arguments in GVD.

6657

6658

@item --debugger

6659

Equivalent to the same GVD option, with the difference that

6660

arguments can be specified as well, replacing the @code{--dargs} option.

6661

6662

@item --target

6663

Same as in GVD.

6664

@end table

6665

6666

For example, the equivalent of the following command line using a sh-like

6667

shell would be:

6668

6669

@smallexample

6670

$ gvd --debugger=gdb-5 executable --pargs 1 2 3

6671

@end smallexample

6672

6673

would be

6674

6675

@smallexample

6676

$ gps --debug="executable 1 2 3" --debugger=gdb-5

6677

@end smallexample

6678

6679

@table @code

6680

@item --traceon=GVD.OUT

6681

6682

This switch replaces the --log-level=4 option that was

6683

used to get the full log of the communications between GVD

6684

and the underlying debugger.

6685

6686

@end table

6687

6688

@subsection Menu Items

6689

@noindent

6690

All the debugger-related menus in GVD can be found under the 'Debug'

6691

menu in GPS, with the following mapping:

6692

6693

@table @code

6694

@item File->xxx

6695

available under @code{Debug->Debug->xxx}

6696

6697

@item Program->xxx

6698

available under @code{Debug->xxx}

6699

6700

@item Data->xxx

6701

available under @code{Debug->Data->xxx}

6702

@end table

6703

6704

The menu @code{File->New Debugger...} is replaced by the combination of

6705

the menu @code{Debug->Initialize} and the project properties, available

6706

under @code{Project->Edit Project Properties} where you can similarly

6707

specify your @i{Debugger Host} (called @i{Tools Host}), your

6708

@i{Program Host}, the @i{Protocol} used by the underlying debugger

6709

to communicate with the target, and the name of the debugger.

6710

To conveniently switch between multiple debugger configurations, we

6711

recommend to use a scenario variable and set different properties based

6712

on the value of this variable. See

6713

@ref{Scenarios and Configuration Variables} and

6714

@ref{Working in a Cross Environment} for more details.

6715

6716

@subsection Tool Bar Buttons

6717

@noindent

6718

GPS provides by default fewer debugger buttons than GVD, because some

6719

buttons are actually not used very often, and others have been merged.

6720

In addition, it will be possible in the future to completely configure

6721

the GPS tool bar.

6722

6723

@table @code

6724

@item Run

6725

Menu @code{Debug->Run...} (@key{F2})

6726

6727

@item Start

6728

Start/Continue button

6729

6730

@item Step

6731

Step button

6732

6733

@item Stepi

6734

Menu @code{Debug->Step Instruction} (@key{Shift-F5})

6735

6736

@item Next

6737

Next button

6738

6739

@item Nexti

6740

Menu @code{Debug->Next Instruction} (@key{Shift-F6})

6741

6742

@item Finish

6743

Finish button

6744

6745

@item Cont

6746

Start/Continue button

6747

6748

@item Up

6749

Up button

6750

6751

@item Down

6752

Down button

6753

6754

@item Interrupt

6755

Menu @code{Debug->Interrupt} (@key{Control-Backslash})

6756

@end table

6757

6758

@subsection Key Short Cuts

6759

@noindent

6760

The same key shortcuts have been kept by default between GVD and GPS

6761

except for the Interrupt menu, which is now @key{Control-Backslash} instead

6762

of @key{Esc}.

6763

6764

@subsection Contextual Menus

6765

@noindent

6766

All the debugger-related contextual menus can now be found under the

6767

@code{Debug} sub-menu.

6768

6769

The only difference is the contextual menu @code{Show} used to display

6770

the assembly dump of the current code. It is replaced by the menu

6771

@code{Debug->Data->Assembly}, see @ref{The Assembly Window} for more

6772

details.

6773

6774

@subsection File Explorer

6775

@noindent

6776

The file explorer provided in GVD is replaced by the @code{Project View}

6777

and the @code{File View} in GPS.

6778

6779

When using the @code{--debug} command line switch and no explicit project

6780

file, GPS will automatically create a project file in a way very

6781

similar to what GVD does to display its file explorer, and available under

6782

the @code{Project View}.

6783

6784

In addition, the @code{File View} gives access to any file in your file

6785

system, even if it is not available as part of the debug information.

6786

6787

@subsection Advantages of GPS

6788

@noindent

6789

The advantages when using GPS instead of GVD can be classified in two main

6790

categories: when not using project files, and when using them.

6791

6792

When not using project files, you get access to the following advantages

6793

in GPS:

6794

6795

@itemize @bullet

6796

@item Complete source editor including indentation, shortcuts, multiple

6797

views, @dots{}

6798

See @ref{Editing Files} for more details.

6799

6800

@item A more stable and robust debugger engine.

6801

The debugger engine included in GPS corresponds to GVD version 2.0.

6802

In effect, GPS @i{is} the new version of GVD.

6803

6804

@item Better look and feel.

6805

GPS uses the new version of the graphical toolkit used by GVD, which

6806

provides a modern look and feel and a more stable interface under Windows

6807

(with additions such as support for the mouse wheel).

6808

6809

@item Support for version control systems

6810

which is integrated and available through a few mouse clicks or key bindings.

6811

See @ref{Version Control System} for more details.

6812

6813

@item A more flexible window handling,

6814

see @ref{Multiple Document Interface} for more details.

6815

@end itemize

6816

6817

When using project files, you will get, in addition to the advantages listed

6818

above:

6819

6820

@itemize @bullet

6821

@item Source navigation, see @ref{Source Navigation} for more details.

6822

6823

@item Source Browsers,

6824

in particular the entity browser, a nice complement of the debugger data window.

6825

See @ref{Source Browsing} for more details.

6826

6827

@item Builds, see @ref{Compilation/Build} for more details.

6828

6829

@item Semantic support.

6830

In particular, GPS is be able to e.g. differentiate variables from types when

6831

displaying a contextual menu, which is not possible in GVD.

6832

6833

@item Flexibility of project files, see @ref{Project Handling} for more details.

6834

@end itemize

6835

6836

@c --------------------------------------------------------------------

6837

@node Customizing the Debugger

6838

@section Customizing the Debugger

6839

@cindex debugger

6840

@c --------------------------------------------------------------------

6841

6842

@noindent

6843

GPS is a high-level interface to several debugger backends, in particular gdb.

6844

Each back end has its own strengths, but you can enhance the command line

6845

interface to these backends through GPS, using Python.

6846

6847

This section will provide a small such example. The idea is to provide the

6848

notion of "alias" in the debugger console. For example, this can be used so

6849

that you type "foo", and this really executes a longer command, like displaying

6850

the value of a variable with a long name.

6851

6852

@code{gdb} already provides this feature through the @code{define} keywords,

6853

but we will in fact rewrite that feature in terms of python.

6854

6855

GPS provides an extensive Python API to interface with each of the running

6856

debugger. In particular, it provides the function "send", which can be used

6857

to send a command to the debugger, and get its output, and the function

6858

"set_output", which can be used when you implement your own functions.

6859

6860

It also provides, through @code{hook}, the capability to monitor the state of

6861

the debugger back-end. In particular, one such hook,

6862

@code{debugger_command_action_hook} is called when the user has typed a

6863

command in the debugger console, and before the command is executed. This can

6864

be used to add your own commands. The example below uses this hook.

6865

6866

Here is the code:

6867

6868

@smallexample

6869

import GPS

6870

6871

aliases=@{@}

6872

6873

def set_alias (name, command):

6874

"""Set a new debugger alias. Typing this alias in a debugger window

6875

will then execute command"""

6876

global aliases

6877

aliases[name] = command

6878

6879

def execute_alias (debugger, name):

6880

return debugger.send (aliases[name], output=False)

6881

6882

def debugger_commands (hook, debugger, command):

6883

global aliases

6884

words = command.split()

6885

if words[0] == "alias":

6886

set_alias (words[1], " ".join (words [2:]))

6887

return True

6888

elif aliases.has_key (words [0]):

6889

debugger.set_output (execute_alias (debugger, words[0]))

6890

return True

6891

else:

6892

return False

6893

6894

GPS.Hook ("debugger_command_action_hook").add (debugger_commands)

6895

@end smallexample

6896

6897

The list of aliases is stored in the global variable @code{aliases}, which

6898

is modified by @code{set_alias}. Whenever the user executes an alias, the

6899

real command send to the debugger is sent through @code{execute_alias}.

6900

6901

The real part of the work is done by @code{debugger_commands}. If the user

6902

is executing the @code{alias} command, it defines a new alias. Otherwise, if

6903

he typed the name of an alias, we really want to execute that alias. Else,

6904

we let the debugger back-end handle that command.

6905

6906

After you have copied this example in the @file{$HOME/.gps/plug-ins} directory,

6907

you can start a debugger as usual in GPS, and type the following in its

6908

console:

6909

6910

@smallexample

6911

(gdb) alias foo print a_long_long_name

6912

(gdb) foo

6913

@end smallexample

6914

6915

The first command defines the alias, the second line executes it.

6916

6917

This alias can also be used within the @code{graph display} command, so that

6918

the value of the variable is in fact displayed in the data window automatically,

6919

for instance:

6920

6921

@smallexample

6922

(gdb) graph display `foo`

6923

@end smallexample

6924

6925

Other examples can be programmed. You could write complex python functions,

6926

which would for instance query the value of several variables, and pretty

6927

print the result. This complex python function can then be called from the

6928

debugger console, or automatically every time the debugger stops through the

6929

@code{graph display} command.

6930

6931

@c --------------------------------------------------------------------

6932

@node Version Control System

6933

@chapter Version Control System

6934

@cindex version control

6935

@c --------------------------------------------------------------------

6936

6937

@menu

6938

* The VCS Explorer::

6939

* The VCS Activities::

6940

* The VCS Menu::

6941

* The Version Control Contextual Menu::

6942

* Working with global ChangeLog file::

6943

* The Revision View::

6944

@end menu

6945

6946

GPS offers the possibility for multiple developers to work on the same project,

6947

through the integration of version control systems (VCS). Each project can be

6948

associated to a VCS, through the @code{VCS} tab in the Project property

6949

editor. @xref{The Project Properties Editor}.

6950

6951

GPS does not come with any version control system: it uses underlying

6952

command-line systems such as CVS, Subversion or ClearCase to perform

6953

the low level operations, and provides a high level user interface on

6954

top of them. Be sure to have a properly installed version control

6955

system before enabling it under GPS.

6956

6957

The systems that are supported out of the box in GPS are CVS, Subversion and

6958

ClearCase. There are two interfaces to ClearCase: the standard

6959

ClearCase interface, which is built-in and uses a generic GPS

6960

terminology for VCS operations, and the Native ClearCase interface,

6961

which is fully customizable and uses by default the terminology

6962

specific to ClearCase. There are also two interfaces for Subversion on

6963

Windows, one for Cygwin/Subversion and one for native Subversion.

6964

6965

Note that, at the moment, only Snapshot Views are supported in the

6966

ClearCase integration; Dynamic Views are not supported.

6967

6968

It is also possible to add your own support for other version control systems,

6969

or modify the existing CVS, Subversion and ClearCase interfaces,

6970

see @ref{Adding support for new Version Control Systems} for more information.

6971

6972

When using CVS or Subversion, GPS will also need a corresponding

6973

@command{patch} command that usually comes with it. If you are under

6974

Windows, be sure to install a set of CVS and patch executables that

6975

are compatible. Additionally a GNU @command{diff} command is required to

6976

use Subversion.

6977

6978

It is recommended that you first get familiar with the version control

6979

system that you intend to use in GPS first, since many concepts used in GPS

6980

assume basic knowledge of the underlying system.

6981

6982

Associating a VCS to a project enables the use of basic VCS features on the

6983

source files contained in the project. Those basic features typically include

6984

the checking in and out of files, the querying of file status, file revision

6985

history, comparison between various revisions, and so on.

6986

6987

Administration of VCS systems is not handled by GPS at this

6988

stage. Therefore, before working on a project using version control

6989

system, make sure that the system is properly set-up before launching

6990

GPS.

6991

6992

@cindex password

6993

Note: the set-up must make sure that the VCS commands can be launched without

6994

entering a password.

6995

6996

@node The VCS Explorer

6997

@section The VCS Explorer

6998

@cindex VCS explorer

6999

@cindex version control

7000

@noindent

7001

7002

The VCS Explorer provides an overview of source files and their

7003

status. A file edited in GPS will be automatically added on the VCS

7004

Explorer with a Modified status (see below).

7005

7006

@iftex

7007

@cindex screen shot

7008

@image{vcs-explorer, 10.7cm}

7009

@end iftex

7010

7011

@ifhtml

7012

@cindex screen shot

7013

@image{vcs-explorer}

7014

@end ifhtml

7015

7016

The easiest way to bring up the VCS Explorer is through the menu

7017

@code{VCS->Explorer}. The Explorer can also be brought up using the

7018

contextual menu @code{Version Control->Query status} on files,

7019

directories and projects in the file and project views, and on file

7020

editors. @xref{The Version Control Contextual Menu}.

7021

7022

The VCS Explorer contains the following columns:

7023

7024

@table @b

7025

@item Project / File

7026

This is a two levels tree, the first level contains the name of the

7027

project and the second the name of files inside the project. Next to

7028

the project name the VCS name, if any, is displayed. This is the only

7029

information available for a project. The columns described below are for

7030

the files only. This column can be sorted by clicking on the header.

7031

7032

@item Status

7033

Shows the status of the file. This column can be sorted by clicking on

7034

the header. The different possible status for files are the following:

7035

7036

@table @code

7037

7038

@item Unknown

7039

@iftex

7040

@image{gps-vcs-unknown}

7041

@end iftex

7042

@ifhtml

7043

@image{gps-vcs-unknown}

7044

@end ifhtml

7045

The status is not yet determined or the VCS repository is not able to

7046

give this information (for example if it is unavailable, or locked).

7047

7048

@item Not registered

7049

@iftex

7050

@image{gps-vcs-not-registered}

7051

@end iftex

7052

@ifhtml

7053

@image{gps-vcs-not-registered}

7054

@end ifhtml

7055

The file is not known to the VCS repository.

7056

7057

@item Up-to-date

7058

@iftex

7059

@image{gps-vcs-up-to-date}

7060

@end iftex

7061

@ifhtml

7062

@image{gps-vcs-up-to-date}

7063

@end ifhtml

7064

The file corresponds to the latest version in the corresponding branch

7065

on the repository.

7066

7067

@item Added

7068

@iftex

7069

@image{gps-vcs-added}

7070

@end iftex

7071

@ifhtml

7072

@image{gps-vcs-added}

7073

@end ifhtml

7074

The file has been added remotely but is not yet updated in the local

7075

view.

7076

7077

@item Removed

7078

@iftex

7079

@image{gps-vcs-removed}

7080

@end iftex

7081

@ifhtml

7082

@image{gps-vcs-removed}

7083

@end ifhtml

7084

The file still exists locally but is known to have been removed from

7085

the VCS repository.

7086

7087

@item Modified

7088

@iftex

7089

@image{gps-vcs-modified}

7090

@end iftex

7091

@ifhtml

7092

@image{gps-vcs-modified}

7093

@end ifhtml

7094

The file has been modified by the user or has been explicitly opened

7095

for editing.

7096

7097

@item Needs merge

7098

@iftex

7099

@image{gps-vcs-needs-merge}

7100

@end iftex

7101

@ifhtml

7102

@image{gps-vcs-needs-merge}

7103

@end ifhtml

7104

The file has been modified locally and on the repository.

7105

7106

@item Needs update

7107

@iftex

7108

@image{gps-vcs-needs-update}

7109

@end iftex

7110

@ifhtml

7111

@image{gps-vcs-needs-update}

7112

@end ifhtml

7113

The file has been modified in the repository but not locally.

7114

7115

@item Contains merge conflicts

7116

@iftex

7117

@image{gps-vcs-has-conflicts}

7118

@end iftex

7119

@ifhtml

7120

@image{gps-vcs-has-conflicts}

7121

@end ifhtml

7122

The file contains conflicts from a previous update operation.

7123

@end table

7124

7125

@item Log

7126

This column indicates whether a revision log exists for this file.

7127

7128

@item Activity

7129

The name of the activity the file belongs to. See @ref{The VCS Activities}

7130

for more details.

7131

7132

@item Working rev.

7133

Indicates the version of the local file.

7134

7135

@item Head rev.

7136

Indicates the most recent version of the file in the repository.

7137

7138

@end table

7139

7140

The VCS Explorer supports multiple selections. To select a single

7141

line, simply left-click on it. To select a range of lines, select the

7142

first line in the range, then hold down the @key{Shift} key and select the

7143

last line in the range. To add or remove single columns from the

7144

selection, hold down the @key{Control} key and left-click on the

7145

columns that you want to select/unselect. It is also possible to

7146

select files having the same status using the @code{Select files same status}

7147

menu entry. See @ref{The Version Control Contextual Menu}.

7148

7149

@cindex interactive search

7150

The explorer also provides an interactive search capability allowing you to

7151

quickly look for a given file name. The default key to start an interactive

7152

search is @key{Ctrl-i}. See @ref{Interactive Search} for more details.

7153

7154

The VCS contextual menu can be brought up from the VCS explorer by

7155

left-clicking on a selection or on a single line. @xref{The Version

7156

Control Contextual Menu}.

7157

7158

@node The VCS Activities

7159

@section The VCS Activities

7160

@cindex VCS activities

7161

@cindex version control

7162

@noindent

7163

7164

The VCS Activities give the ability to group files to be committed

7165

together. The set of files can be committed atomically if supported by

7166

the version control system used.

7167

7168

@iftex

7169

@cindex screen shot

7170

@image{vcs-activities, 10.7cm}

7171

@end iftex

7172

7173

@ifhtml

7174

@cindex screen shot

7175

@image{vcs-activities}

7176

@end ifhtml

7177

7178

The way to bring up the VCS Activities view is through the

7179

@code{VCS->Activities} menu.

7180

7181

The VCS Activities view contains the following columns:

7182

7183

@table @b

7184

@item Activity / File

7185

The name of the activity or files belonging to an activity. This

7186

column can be sorted by clicking on the header.

7187

7188

@item Status

7189

Shows the status of the file. This column can be sorted by clicking on

7190

the header. See @ref{The VCS Explorer} for a full description.

7191

7192

@item Log

7193

This column indicates whether a revision log exists for this file.

7194

7195

@item Working rev.

7196

Indicates the version of the local file.

7197

7198

@item Head rev.

7199

Indicates the most recent version of the file in the repository.

7200

@end table

7201

7202

The VCS Explorer supports multiple selections. To select a single

7203

line, simply left-click on it. To select a range of lines, select the

7204

first line in the range, then hold down the @key{Shift} key and select the

7205

last line in the range. To add or remove single columns from the

7206

selection, hold down the @key{Control} key and left-click on the

7207

columns that you want to select/unselect.

7208

7209

There are different contextual menu entries depending on the

7210

position on the screen.

7211

On an empty area we have a simple contextual menu:

7212

7213

@table @b

7214

@item Create new activity

7215

Create a new activity. The name can be edited by double clicking on it.

7216

@end table

7217

7218

On an activity line the contextual menu is:

7219

7220

@table @b

7221

@item Group commit

7222

This is a selectable menu entry. It is activated only if the

7223

VCS supports atomic commit and absolute filenames. See @ref{The VCS node}

7224

for full details.

7225

7226

@item Create new activity

7227

Create a new activity. The name can be edited by double clicking on it.

7228

7229

@item Re-open activity / Close activity

7230

If the activity is closed it is possible to re-open it and if it is

7231

opened it is possible to close it manually.

7232

7233

@item Delete activity

7234

Remove the activity.

7235

7236

@item Commit activity

7237

Commit the activity. If group commit is activated then the commit log

7238

content is generated using a template file fully configurable.

7239

See @ref{Files}.

7240

If group commit is not activated then the log content for each

7241

activity file is the file log catenated with the activity log. After

7242

this operation the file's log are removed but the activity log is kept

7243

as documentation.

7244

7245

@item Query status

7246

Query the status for all the source files contained in the activity.

7247

7248

@item Update

7249

Update all the source files contained in the activity.

7250

7251

@item Compare against head revision

7252

Show a visual comparison between the local activity files and the most recent

7253

version of those files in the repository.

7254

7255

@item Build patch file

7256

Create a patch file (in text format) for the activity. The patch file

7257

contains a header (the activity log and file's logs) and the diff of

7258

each file. The header format is fully configurable using a template

7259

file. See @ref{Files}.

7260

7261

@item Edit revision log

7262

Edit the current revision log for activity. This log is shared with

7263

all the activity files.

7264

7265

@item Remove revision log

7266

Remove the current revision log for activity. This menu is present

7267

only if the activity revision log exists.

7268

@end table

7269

7270

On a file line the contextual menu contains:

7271

7272

@table @b

7273

@item Create new activity

7274

Create a new activity. The name can be edited by double clicking on

7275

it.

7276

7277

@item Remove from activity

7278

Remove the selected file from the activity and delete the

7279

activity log.

7280

7281

@item Edit revision log

7282

Edit the current revision log for the selected file.

7283

7284

@end table

7285

7286

@node The VCS Menu

7287

@section The VCS Menu

7288

@cindex version control

7289

@cindex menu

7290

@noindent

7291

7292

Basic VCS operations can be accessed through the VCS menu. Most of

7293

these functions act on the current selection, i.e. on the selected items

7294

in the VCS Explorer if it is present, or on the currently selected

7295

file editor, or on the currently selected item in the

7296

@code{Tools->Views->Files}.

7297

In most cases, the VCS contextual menu offers more control on

7298

VCS operations. @xref{The Version Control Contextual Menu}.

7299

7300

@table @b

7301

@item Explorer

7302

Open or raise the VCS Explorer. @xref{The VCS Explorer}.

7303

7304

@item Update all projects

7305

Update the source files in the current project, and all imported

7306

sub-projects, recursively.

7307

7308

@item Query status for all projects

7309

Query the status of all files in the project and all imported sub-projects.

7310

7311

@item Create tag...

7312

Create a tag or branch tag starting from a specific root

7313

directory. The name of the tag is a simple name.

7314

7315

@item Switch tag...

7316

Switch the local copy to a specific tag. The name of the tag depends

7317

on the external VCS used. For CVS this this the simple tag name, for

7318

Subversion the tag must conform to the default repository layout. For

7319

a branch tag this is @code{/branches/<tag_name>/<root_dir>}.

7320

@end table

7321

7322

For a description of the other entries in the VCS menu, see

7323

@ref{The Version Control Contextual Menu}

7324

7325

@node The Version Control Contextual Menu

7326

@section The Version Control Contextual Menu

7327

7328

@noindent

7329

This section describes the version control contextual menu displayed when you

7330

right-click on an entity (e.g. a file, a directory, a project) from various

7331

parts of GPS, including the project view, the source editor and the VCS

7332

Explorer.

7333

7334

Depending on the context, some of the items described in this section won't

7335

be shown, which means that they are not relevant to the current context.

7336

7337

@table @b

7338

@item Remove project

7339

Only displayed on a project line. This will remove the selected

7340

project from the VCS Explorer.

7341

7342

@item Expand all

7343

Expand all VCS Explorer project nodes.

7344

7345

@item Collapse all

7346

Collapse all VCS Explorer project nodes.

7347

7348

@item Clear View

7349

Clear the VCS Explorer.

7350

7351

@item Query status

7352

Query the status of the selected item. Brings up the VCS Explorer.

7353

7354

@item Update

7355

@anchor{Update}

7356

Update the currently selected item (file, directory or project).

7357

7358

@item Commit

7359

@anchor{Commit}

7360

Submits the changes made to the file to the repository, and queries

7361

the status for the file once the change is made.

7362

7363

It is possible to tell GPS to check the file before the actual commit

7364

happens. This is done by specifying a @code{File checker} in the

7365

@code{VCS} tab of the project properties dialog. This @code{File

7366

checker} is in fact a script or executable that takes an absolute file

7367

name as argument, and displays any error message on the standard

7368

output. The VCS commit operation will actually occur only if nothing

7369

was written on the standard output.

7370

7371

It is also possible to check the change-log of a file before commit, by

7372

specifying a @code{Log checker} in the project properties dialog. This

7373

works on change-log files in the same way as the @code{File checker} works on

7374

source files.

7375

7376

@item Open

7377

@anchor{Open}

7378

Open the currently selected file for writing. On some VCS systems,

7379

this is a necessary operation, and on other systems it is not.

7380

7381

@item View entire revision history

7382

@anchor{View revision history}

7383

Show the revision logs for all previous revisions of this file.

7384

7385

@item View specific revision history

7386

Show the revision logs for one previous revision of this file.

7387

7388

@item Compare against head revision

7389

@cindex compare

7390

@anchor{Compare against head}

7391

Show a visual comparison between the local file and the most recent

7392

version of that file in the repository.

7393

7394

@item Compare against other revision

7395

@anchor{Compare against working}

7396

Show a visual comparison between the local file and one specific

7397

version of that file in the repository.

7398

7399

@item Compare two revisions

7400

@anchor{Compare against revision}

7401

Show a visual comparison between two specific revisions

7402

of the file in the repository.

7403

7404

@item Compare base against head

7405

@anchor{Compare base against head}

7406

Show a visual comparison between the corresponding version of the

7407

file in the repository and the most recent version of that file.

7408

7409

@item Compare against tag/branch

7410

@anchor{Compare base against tag/branch}

7411

Only available on a Revision View and over a tag/branch. Show a visual

7412

comparison between the corresponding version of the file in the

7413

repository and the version of that file in the tag/branch.

7414

7415

@item Annotate

7416

@anchor{Annotate}

7417

Display the annotations for the file, i.e. the information for each

7418

line of the file showing the revision corresponding to that file, and

7419

additional information depending on the VCS system.

7420

7421

When using CVS or Subversion, the annotations are clickable. Left-clicking on

7422

an annotation line will query and display the changelog associated to the

7423

specific revision for this line.

7424

7425

@item Remove Annotate

7426

Remove the annotations from the selected file.

7427

7428

@item Edit revision log

7429

Edit the current revision log for the selected file.

7430

7431

@item Edit global ChangeLog

7432

Edit the global ChangeLog entry for the selected file.

7433

@pxref{Working with global ChangeLog file}.

7434

7435

@item Remove revision log

7436

Clear the current revision associated to the selected file.

7437

7438

@item Add

7439

Add a file to the repository, using the current revision log for this

7440

file. If no revision log exists, activating this menu will create

7441

one. The file is committed in the repository.

7442

7443

@item Add/No commit

7444

Add a file to the repository, using the current revision log for this

7445

file. If no revision log exists, activating this menu will create

7446

one. The file is not committed in the repository.

7447

7448

@item Remove

7449

Remove a file from the repository, using the current revision log for

7450

this file. If no revision log exists, activating this menu will create

7451

one. The modification is committed in the repository.

7452

7453

@item Remove/No commit

7454

Remove a file from the repository, using the current revision log for

7455

this file. If no revision log exists, activating this menu will create

7456

one. The modification is not committed in the repository.

7457

7458

@item Revert

7459

Revert a locale file to the repository revision, discarding all local

7460

changes.

7461

7462

@item Resolved

7463

Mark files' merge conflics as resolved. Some version control systems

7464

(like Subversion) will block any commit until this action is called.

7465

7466

@item Switch tag/bracnh

7467

Only available on a Revision View and over a tag/branch name. Will

7468

switch the tree starting from a selected root to this specific tag or

7469

branch.

7470

7471

@item Merge

7472

Only available on a Revision View and over a tag/branch name. Merge

7473

file changes made on this specific tag/branch.

7474

7475

@item View revision

7476

Only available on a Revision View and over a revision.

7477

7478

@item Commit as new Activity

7479

An action to prepare a group-commit in just one-click. This action will:

7480

7481

@itemize @bullet

7482

@item create an anonymous activity,

7483

@item add all files selected into the VCS Explorer into the newly

7484

created anonymous activity,

7485

@item open the activity log,

7486

@end itemize

7487

7488

Just fill the activity log and commit the anonymous activity.

7489

7490

@item Add to Activity

7491

A menu containing all the current activities. Selecting one will add

7492

the current file to this activity. This menu is present only if the

7493

file is not already part of an activity.

7494

7495

@item Remove from Activity

7496

Remove file from the given activity. This menu is present only if the

7497

file is already part of an activity.

7498

7499

@item Directory

7500

Only available when the current context contains directory information

7501

7502

@table @i

7503

@item Add/No commit

7504

Add the selected directory into the VCS.

7505

7506

@item Remove/No commit

7507

Remove the selected directory from the VCS.

7508

7509

@item Commit

7510

Commit the selected directory into the VCS. This action is available

7511

only if the VCS supports commit on directories, @pxref{The VCS node}.

7512

7513

@item Add to Activity

7514

Add the selected directory into the VCS. This action is available

7515

only if the VCS supports commit on directories, @pxref{The VCS node}.

7516

7517

@item Query status for directory

7518

Query status for the files contained in the selected directory.

7519

7520

@item Update directory

7521

Update the files in the selected directory.

7522

7523

@item Query status for directory recursively

7524

Query status for the files in the selected directory and all

7525

subdirectories recursively. Links and hidden directories are not

7526

included.

7527

7528

@item Update directory recursively

7529

Update the files in the selected directory and all

7530

subdirectories recursively. Links and hidden directories not included..

7531

7532

@end table

7533

7534

@item Project

7535

Only available when the current context contains project information

7536

7537

@table @i

7538

@item List all files in project

7539

Bring up the VCS Explorer with all the source files contained in the project.

7540

7541

@item Query status for project

7542

Query the status for all the source files contained in the project.

7543

7544

@item Update project

7545

Update all the source files in the project.

7546

7547

@item List all files in project and sub-projects

7548

Bring up the VCS Explorer with all the source files contained in the

7549

project and all imported sub-projects.

7550

7551

@item Query status for project and sub-projects

7552

Query the status for all the source files contained in the project

7553

and all imported sub-projects.

7554

7555

@item Update project and sub-projects

7556

Update all the source files in the project and all imported

7557

sub-projects.

7558

7559

@end table

7560

7561

@item Select files same status

7562

Select the files having the same status as the current selected file.

7563

7564

@item Filters

7565

Only available from the VCS Explorer. This menu controls filtering of the

7566

items displayed in the list.

7567

7568

@table @i

7569

@item Show all status

7570

Do not filter out any file from the list in the VCS Explorer.

7571

7572

@item Hide all status

7573

Filter out all the files from the list in the VCS Explorer.

7574

7575

@item Show <status>

7576

When disabled, filter out the files with the given status from the VCS

7577

Explorer.

7578

@end table

7579

7580

@end table

7581

7582

@node Working with global ChangeLog file

7583

@section Working with global ChangeLog file

7584

@cindex global ChangeLog

7585

@cindex ChangeLog file

7586

@noindent

7587

7588

A global ChangeLog file contains revision logs for all files in a

7589

directory and is named @file{ChangeLog}. The format for such a file

7590

is:

7591

7592

@smallexample

7593

@b{ISO-DATE @i{name <e-mail>}}

7594

7595

<HT>* @b{filename}[, @b{filename}]:

7596

<HT>revision history

7597

@end smallexample

7598

7599

where:

7600

7601

@table @b

7602

@item ISO-DATE

7603

A date with the ISO format YYYY-MM-DD

7604

7605

@item name

7606

A name, generally the developer name

7607

7608

@item <e-mail>

7609

The e-mail address of the developer surrounded with '<' and '>' characters.

7610

7611

@item HT

7612

Horizontal tabulation (or 8 spaces)

7613

@end table

7614

7615

The @i{name} and @i{<e-mail>} items can be entered automatically by setting

7616

the @var{GPS_CHANGELOG_USER} environment variable. Note that there is

7617

two spaces between the @i{name} and the @i{<e-mail>}.

7618

7619

@smallexample

7620

On sh shell:

7621

7622

export GPS_CHANGELOG_USER="John Doe <john.doe@@home.com>"

7623

7624

On Windows shell:

7625

set GPS_CHANGELOG_USER="John Doe <john.doe@@home.com>"

7626

@end smallexample

7627

7628

Using the menu entry @b{Edit global ChangeLog} will open the file

7629

@file{ChangeLog} in the directory where the current selected file is

7630

and create the corresponding @file{ChangeLog} entry. This means that

7631

the ISO date and filename headers will be created if not yet

7632

present. You will have to enter your name and e-mail address.

7633

7634

This @file{ChangeLog} file serve as a repository for revision logs,

7635

when ready to check-in a file use the standard @b{Edit revision log}

7636

menu command. This will open the standard revision log buffer with the

7637

content filled from the global @file{ChangeLog} file.

7638

7639

@node The Revision View

7640

@section The Revision View

7641

7642

@noindent

7643

The revision view is used to display a revision tree for a given

7644

file. Each node contains information for a specific revision of

7645

the file.

7646

7647

@iftex

7648

@cindex screen shot

7649

@image{revision-view, 13.5cm}

7650

@end iftex

7651

7652

@ifhtml

7653

@cindex screen shot

7654

@image{revision-view}

7655

@end ifhtml

7656

7657

@table @b

7658

7659

@item the revision number

7660

This corresponds to the external VCS revision number.

7661

7662

@item author

7663

The author of this revision.

7664

7665

@item date / log

7666

For root nodes this column contains the check-in date and eventually

7667

the list of tags and branches associated with this revision. For

7668

children nodes this contains the log for the corresponding revision.

7669

7670

@end table

7671

7672

@c --------------------------------------------------------------------

7673

@node Tools

7674

@chapter Tools

7675

@cindex tools

7676

@c --------------------------------------------------------------------

7677

7678

@menu

7679

* The Tools Menu::

7680

* Visual Comparison::

7681

* Code Fixing::

7682

* Documentation Generation::

7683

* Metrics::

7684

* Code Coverage::

7685

@end menu

7686

7687

@node The Tools Menu

7688

@section The Tools Menu

7689

@noindent

7690

The @code{Tools} menu gives access to additional tools. Some items are

7691

currently disabled, meaning that these are planned tools not yet available.

7692

7693

The list of active items includes:

7694

7695

@table @b

7696

@item Views

7697

7698

@table @b

7699

7700

@item Bookmarks

7701

@cindex bookmark

7702

@xref{Bookmarks}.

7703

7704

@item Call Tree

7705

Open a tree view of function callers and callees. See also @ref{Call Graph}.

7706

7707

@item Clipboard

7708

@xref{The Clipboard View}.

7709

7710

@item Files

7711

Open a file system explorer on the left area.

7712

@xref{The File View}.

7713

7714

@item File Switches

7715

@xref{File Switches}.

7716

7717

@item Outline

7718

Open a view of the current source editor.

7719

@xref{The Outline View}.

7720

7721

@item Project

7722

@xref{The Project View}.

7723

7724

@item Remote

7725

@xref{Setup a remote project}.

7726

7727

@item Scenario

7728

@xref{Scenarios and Configuration Variables}.

7729

7730

@item Tasks

7731

@xref{The Task Manager}.

7732

7733

@item VCS Explorer

7734

@xref{The VCS Explorer}.

7735

7736

@item VCS Activities

7737

@xref{The VCS Activities}.

7738

7739

@item Windows

7740

Open a view containing all currently opened files.

7741

@xref{The Window View}.

7742

7743

@end table

7744

7745

@item Browsers

7746

7747

@table @b

7748

@item Call Graph

7749

@xref{Call Graph}.

7750

7751

@item Dependency

7752

@xref{Dependency Browser}.

7753

7754

@item Entity

7755

@xref{Entity Browser}.

7756

7757

@end table

7758

7759

@item Coding Standard

7760

@c ??? need documentation

7761

7762

@item Compare

7763

@cindex visual diff

7764

@xref{Visual Comparison}.

7765

7766

@item Consoles

7767

@table @b

7768

7769

@item GPS Shell

7770

@cindex shell

7771

Open a shell console at the bottom area of GPS. Note that this not an OS

7772

shell console, but a GPS shell console, where you can type GPS specific

7773

commands such as @code{help}.

7774

7775

@xref{The Shell and Python Windows}.

7776

7777

@item Python

7778

@cindex python

7779

Open a python console to access the python interpreter.

7780

@xref{The Shell and Python Windows}.

7781

7782

@item OS Shell

7783

@cindex shell

7784

Open an OS (Windows or Unix) console, using the environment variables

7785

@code{SHELL} and @code{COMSPEC} to determine which shell to use. This is

7786

currently a relatively simple implementation, without support for e.g.

7787

completion or ANSI codes.

7788

@end table

7789

7790

@item Coverage

7791

@cindex code coverage

7792

@xref{Code Coverage}.

7793

7794

@item Documentation

7795

@cindex documentation

7796

@xref{Documentation Generation}.

7797

7798

@item Macro

7799

@cindex macros

7800

@xref{Recording and replaying macros}.

7801

7802

@item Metrics

7803

@cindex metrics

7804

@xref{Metrics}.

7805

7806

@item Plug-ins

7807

@cindex plug-ins

7808

@xref{The Plug-ins Editor}.

7809

7810

@item Interrupt

7811

@cindex interrupt

7812

Interrupt the last task launched (e.g. compilation, vcs query, @dots{}).

7813

7814

@end table

7815

7816

@node Visual Comparison

7817

@section Visual Comparison

7818

@cindex visual diff

7819

@noindent

7820

7821

The visual comparison, available either from the VCS menus or from the Tools

7822

menu, provide a way to display graphically differences between two or three

7823

files, or two different versions of the same file.

7824

7825

The 2-file comparison tool is based on the standard text command

7826

@command{diff}, available on all Unix systems. Under Windows, a default

7827

implementation is provided with GPS, called @command{gnudiff.exe}.

7828

You may want to provide an alternate implementation by e.g. installing a

7829

set of Unix tools such as cygwin (@url{http://www.cygwin.com}).

7830

7831

The 3-file comparison tool is based on the text command @command{diff3},

7832

available on all Unix systems. Under Windows, this tool is not shipped

7833

with GPS. It is available as part of cygwin, for example.

7834

7835

When querying a visual comparison in GPS, the user area will show, side by

7836

side, editors for the files involved in the comparison. The reference file is

7837

placed by default on the left side.

7838

7839

Color highlighting will be added to the file editors:

7840

7841

@table @b

7842

@item gray

7843

This color is used for all the chunks on the reference (left) file. Only

7844

the modified (right) file is displayed with different colors.

7845

7846

@item yellow

7847

This color is used to display lines that have been modified compared to the

7848

reference file. When there are fine differences within one line, they are

7849

shown in a brighter yellow.

7850

7851

@item green

7852

Used to display lines added compared to the reference file; in other words,

7853

lines that are not present in the reference file.

7854

7855

@item red

7856

Used to display lines removed from the reference file; in other words,

7857

lines that are present only in the reference file.

7858

7859

@end table

7860

7861

These colors can be configured, @pxref{The Preferences Dialog}.

7862

7863

As with all highlighted lines in GPS, the visual differences highlights are

7864

visible in the Speed Column at the left of the editors.

7865

7866

Blank lines are also added in the editors, in places that correspond to

7867

existing lines in the other editors. The vertical and horizontal scrolling

7868

are synchronized between all editors involved in a visual comparison.

7869

7870

When a visual comparison is created, the Locations View is populated with the

7871

entries for each chunk of differences, and can be used to navigate between

7872

those.

7873

7874

Closing one of the editors involved in a visual comparison removes the

7875

highlighting, blank lines, and scrolling in the other editors.

7876

7877

Editors involved in a visual comparison have a contextual menu

7878

@code{Visual diff} that contains the following entries:

7879

7880

@table @code

7881

@item Recompute

7882

Regenerates the visual comparison. This is useful, for example, when one of

7883

the editors has been modified by hand while it was involved in a visual

7884

comparison

7885

7886

@item Hide

7887

Removes the highlighting corresponding to the visual comparison from all

7888

editors involved

7889

7890

@item Close editors

7891

Closes all editors involved in this visual comparison

7892

7893

@item Use this editor as reference

7894

Change the reference to this editor. (This is only visible when displaying a

7895

visual comparison involving 3 files).

7896

7897

@end table

7898

7899

@iftex

7900

@cindex screen shot

7901

@image{visual-diff, 12.7cm}

7902

@end iftex

7903

7904

@ifhtml

7905

@cindex screen shot

7906

@image{visual-diff}

7907

@end ifhtml

7908

7909

@node Code Fixing

7910

@section Code Fixing

7911

@cindex code fixing

7912

@cindex wrench icon

7913

@noindent

7914

7915

GPS provides an interactive way to fix or improve your source code, based on

7916

messages (errors and warnings) generated by the GNAT compiler.

7917

7918

@c There are two ways to access this capability: the first (and preferred) one

7919

@c is integrated with the @i{Locations tree} (see @ref{The Locations Tree});

7920

@c the other provides a separate dialog accessible through the menu

7921

@c @code{Tools->Code Fixing}.

7922

7923

This capability is integrated with the @i{Locations tree} (see

7924

@ref{The Locations Tree}): when GPS can take advantage of a compiler message,

7925

an icon is added on the left side of the line.

7926

7927

For a simple fix, a wrench icon is displayed. If you click with

7928

the left button on this icon, the code will be fixed automatically, and you

7929

will see the change in the corresponding source editor. An example of a simple

7930

fix, is the addition of a missing semicolon.

7931

7932

You can also check what action will be performed by clicking on the right

7933

button which will display a contextual menu with a text explaining the action

7934

that will be performed. Similarly, if you display the contextual menu anywhere

7935

else on the message line, a sub menu called @i{Code Fixing} gives you

7936

access to the same information. In the previous example of a missing

7937

semicolon, the menu will contain an entry labeled @i{Add expected string ";"}.

7938

7939

Once the code change has been performed, the tool icon is no longer displayed.

7940

7941

For more complex fixes, where more than one change is possible, the icon

7942

will display in additional of the tool, a red question mark. In this case,

7943

clicking on the icon will display the contextual menu directly, giving you

7944

access to the possible choices. For example, this will be the case when

7945

an ambiguity is reported by the compiler for resolving an entity.

7946

7947

@node Documentation Generation

7948

@section Documentation Generation

7949

@cindex documentation generation

7950

@noindent

7951

7952

GPS provides a documentation generator which processes source files

7953

and generates annotated HTML files.

7954

7955

Note that starting with GPS 4.2, a brand new Documentation generator has been

7956

put in place. This new generator is much faster than the previous one, and

7957

produces cleaner and clearer html files.

7958

7959

It is based on the source cross-reference information (e.g. generated by

7960

GNAT for Ada files). This means that you should ensure that cross-reference

7961

information has been generated before generating the documentation.

7962

It also relies on standard comments that it extracts from the source code.

7963

Note that unlike other similar tools, no macro needs to be put in your

7964

comments. The engine in charge of extracting them coupled with the

7965

cross-reference engine gives GPS all the flexibility needed to generate

7966

accurate documentation.

7967

7968

The documentation is put into a directory called @file{doc}, created

7969

under the object directory of the root project loaded in GPS.

7970

7971

Once the documentation is generated, the main documentation file is loaded

7972

in your default browser.

7973

7974

The documentation generator uses a set of templates files to control the final

7975

rendering. This means that you can control precisely the rendering of the

7976

generated documentation. The templates used for generating the documentation

7977

can be found under @file{<install_dir>/share/gps/docgen2}. If you need a

7978

different layout as the proposed one, you can change directly those files.

7979

7980

Starting with GPS 4.3, user-defined structured comments can now be used to

7981

improve the generated documentation. To define your own structured comments,

7982

you should refer to the GPS python extension documentation (from GPS Help menu,

7983

choose 'Python extensions').

7984

7985

@c For a description of the

7986

@c documentation generator renderer @pxref{Defining a documentation format}.

7987

7988

The documentation generator can be invoked from two places inside GPS:

7989

7990

@table @b

7991

@item @ref{The Tools Menu}

7992

7993

@table @command

7994

@item Generate project

7995

Generate documentation for all files from the loaded project.

7996

7997

@item Generate projects & subprojects

7998

Generate documentation for all files from the loaded project as well all

7999

its subprojects.

8000

8001

@item Generate current file

8002

Generate documentation for the file you are currently editing.

8003

8004

@item Generate for...

8005

This will open a File Selector Dialog (@pxref{The File Selector}) and

8006

documentation will be generated for the file you select.

8007

8008

@end table

8009

8010

@item The Contextual Menu

8011

8012

When relevant (depending on the context), right-clicking with your mouse

8013

will show a @code{Documentation} contextual menu.

8014

8015

From a source file contextual menu, you have one option called

8016

@command{Generate for <filename>}, that will generate documentation

8017

for this file and if needed its corresponding body

8018

(@pxref{The Preferences Dialog}).

8019

8020

From a project contextual menu (@pxref{The Project View}), you will have the

8021

choice between generating documentation for all files from the selected project

8022

only or from the selected project recursively.

8023

8024

You will find the list of all documentation options in

8025

@ref{The Preferences Dialog}.

8026

8027

@item Restrictions

8028

There are some restrictions in the generated documentation:

8029

8030

@itemize @bullet

8031

@item The formal part of generics is not always displayed.

8032

@end itemize

8033

8034

Furthermore, the documentation generator relies on the ALI files created by

8035

GNAT. Depending on the version of GNAT used, the following restrictions may

8036

or may not apply:

8037

8038

@itemize @bullet

8039

@item A type named @i{type} may be generated in the type index.

8040

8041

@item Parameters and objects of private generic types may be considered as

8042

types.

8043

@end itemize

8044

@end table

8045

8046

@node Metrics

8047

@section Metrics

8048

@cindex Metrics

8049

@noindent

8050

8051

GPS provides an interface with the GNAT software metrics generation tool

8052

@code{gnatmetric}.

8053

8054

The metrics can be computed for the entire project, one source file belonging to

8055

the project, or (when applicable) a specific entity in the source file, e.g. a

8056

subprogram.

8057

8058

The metrics generator can be invoked from two places inside GPS:

8059

8060

@table @b

8061

@item @ref{The Tools Menu}

8062

8063

@table @command

8064

@item Metrics->Compute metrics for root project

8065

Generate metrics for all files from the root project.

8066

8067

@item Metrics->Compute metrics for current file

8068

Generate metrics for the current source file.

8069

8070

@end table

8071

8072

@item The Contextual Menu

8073

8074

When relevant (depending on the context), right-clicking with your mouse

8075

will show metrics-related contextual menu entries.

8076

8077

From a source file contextual menu, you have an option called

8078

@command{Metrics for file} that will generate the metrics for

8079

the current file.

8080

8081

From a project contextual menu (@pxref{The Project View}), you have an

8082

option @command{Metrics for project} that will generate the metrics for

8083

all files in the project.

8084

8085

@end table

8086

8087

Each of these commands produces a new window in the left-side area,

8088

which shows the computed metrics as a hierarchical tree view. The metrics

8089

are arranged by files, and then by scopes inside the files in a nested fashion.

8090

Double-clicking on any of the files or scopes displayed will open the

8091

appropriate source location in the editor. Any errors encountered during

8092

metrics computation will be displayed in the Locations Window.

8093

8094

@c --------------------------------------------------------------------

8095

@node Code Coverage

8096

@section Code Coverage

8097

@cindex Code Coverage

8098

@noindent

8099

@c --------------------------------------------------------------------

8100

8101

GPS is fitted with a strong integration of Gcov, the GNU code coverage

8102

utility.

8103

8104

Code coverage information can be computed from, loaded and visualized in GPS.

8105

This can be done file by file, for each files of the current project,

8106

project by project (in case of dependencies) or for the entire project hierarchy

8107

currently used in GPS.

8108

8109

Once computed then loaded, the coverage information is summarized in a

8110

graphical report (shaped as a tree-view with percentage bars for each item)

8111

and used to decorate source code through mechanisms such as line highlighting or

8112

coverage annotations.

8113

8114

All the coverage related operations are reachable via the

8115

@command{Tools->Coverage} menu.

8116

8117

In order to be loaded in GPS, the coverage information need to be computed

8118

before, using the @command{Tools->Coverage->Compute coverage files} menu for

8119

instance.

8120

8121

At each attempt, GPS automatically tries to load the needed information and

8122

reports errors for missing or corrupted @command{.gcov} files.

8123

8124

To be able to produce coverage information from Gcov, your project must have

8125

been compiled with the @command{-fprofile-arcs} and @command{-ftest-coverage}"

8126

switches, respectively "Instrument arcs" and "Code coverage" entries in

8127

@ref{The Project Properties Editor}, and run once.

8128

8129

@table @b

8130

@item @ref{The Tools Menu}

8131

8132

The @command{Tools->Coverage} menu have an incremental set of entries,

8133

depending on the context.

8134

8135

@table @command

8136

8137

@item Coverage->Compute coverage files

8138

Generates the @command{.gcov} files of current and properly compiled and run

8139

projects.

8140

8141

@item Coverage->Remove coverage files

8142

Deletes all the @command{.gcov} of current projects.

8143

8144

@c \hline

8145

8146

@item Coverage->Show report

8147

Open a new window summarizing the coverage information currently loaded in GPS.

8148

8149

@c \hline

8150

8151

@item Coverage->Load data for all projects

8152

Load or re-load the coverage information of every projects and subprojects.

8153

8154

@item Coverage->Load data for project @code{XXX}

8155

Load or re-load the coverage information of the project @code{XXX}.

8156

8157

@item Coverage->Load data for @file{xxxxxxxx.xxx}

8158

Load or re-load the coverage information of the specified source file.

8159

8160

@c \hline

8161

8162

@item Coverage->Clear coverage from memory

8163

Drop every coverage information loaded in GPS.

8164

8165

@end table

8166

8167

@item The Contextual Menu

8168

8169

When clicking on a project, file or subprogram entity (including the entities

8170

listed in the coverage report), you have access to a @command{Coverage} submenu.

8171

8172

These submenus contain the following entries, adapted to the context related

8173

element. For instance, if you click on a file, you will have:

8174

8175

@table @command

8176

@item Coverage->Show coverage information

8177

Append an annotation column to the left side of the current source editor.

8178

This column indicates which lines are covered and which aren't. Unexecuted lines

8179

are also listed in the @ref{The Locations Tree}.

8180

8181

@item Coverage->Hide coverage information

8182

Withdraw from the current source editor a previously set coverage annotation

8183

column and clear @ref{The Locations Tree} from the eventually listed uncovered

8184

lines.

8185

8186

@item Coverage->Load data for @file{xxxxxxxx.xxx}

8187

Load or re-load the coverage information of the specified source file.

8188

8189

@item Coverage->Remove data of @file{xxxxxxxx.xxx}

8190

Remove the coverage information of the specified source file from GPS memory.

8191

8192

@item Coverage->Show Coverage report

8193

Open a new window summarizing the coverage information. (This entry appears

8194

only if the contextual menu has been created from outside of the Coverage

8195

Report.)

8196

@end table

8197

8198

@item The Coverage Report

8199

8200

When coverage information are loaded into GPS, a graphical report of coverage

8201

is displayed.

8202

8203

This report contains a tree of Projects, Files and Subprograms with

8204

corresponding coverage information for each node in sided columns.

8205

8206

@iftex

8207

@cindex screen shot

8208

@image{report-of-analysis_tree, 8.7cm}

8209

@end iftex

8210

8211

@ifhtml

8212

@cindex screen shot

8213

@image{report-of-analysis_tree}

8214

@end ifhtml

8215

8216

The contextual menus generated on this widget contain, in addition to the

8217

regular entries, some specific Coverage Report entries.

8218

8219

These entries allow you to expand or fold the tree, and also to display flat

8220

lists of files or subprograms instead of the tree. A flat list of file will

8221

look like:

8222

8223

@iftex

8224

@cindex screen shot

8225

@image{report-of-analysis_flat, 8.7cm}

8226

@end iftex

8227

8228

@ifhtml

8229

@cindex screen shot

8230

@image{report-of-analysis_flat}

8231

@end ifhtml

8232

8233

@end table

8234

8235

GPS and Gcov both support many different programming languages, and so code

8236

coverage features are available in GPS for many languages. But, note that

8237

subprogram coverage details are not available for every supported languages.

8238

8239

To finish, note that if you change the current main project in GPS, using the

8240

@command{Project->Open} menu for instance, you will also drop every loaded

8241

coverage information as they are related to the working project.

8242

8243

@c --------------------------------------------------------------------

8244

@node Working in a Cross Environment

8245

@chapter Working in a Cross Environment

8246

@cindex cross environment

8247

@c --------------------------------------------------------------------

8248

8249

@menu

8250

* Customizing your Projects::

8251

* Debugger Issues::

8252

@end menu

8253

8254

@noindent

8255

This chapter explains how to adapt your project and configure GPS when working

8256

in a cross environment.

8257

8258

@node Customizing your Projects

8259

@section Customizing your Projects

8260

@cindex project

8261

8262

@noindent

8263

This section describes some possible ways to customize your projects when

8264

working in a cross environment. For more details on the project capabilities,

8265

see @ref{Project Handling}.

8266

8267

When using the project editor to modify the project's properties, two

8268

areas are particularly relevant to cross environments:

8269

@code{Cross environment} part of the @code{General} page and

8270

@code{Tools}, part of the @code{Languages} page.

8271

8272

In the @code{Tools} section, you will typically need to change the name of

8273

the compiler(s) and the debugger, as well as gnatls' name if you are

8274

using Ada.

8275

8276

For example, assuming you have an Ada project, and using a powerpc VxWorks

8277

configuration. You will set the @i{Ada compiler} to

8278

@code{powerpc-wrs-vxworks-gnatmake}; @i{Gnatls} to

8279

@code{powerpc-wrs-vxworks-gnatls} and @i{Debugger} to

8280

@code{powerpc-wrs-vxworks-gdb}.

8281

8282

If you are using an alternative run time, e.g. a @i{soft float} run time,

8283

you need to add the option @code{--RTS=soft-float} to the @i{Gnatls}

8284

property, e.g: @code{powerpc-wrs-vxworks-gnatls --RTS=soft-float}, and

8285

add this same option to the @i{Make} switches in the switch editor.

8286

See @ref{Switches} for more details on the switch editor.

8287

8288

To modify your project to support configurations such as multiple targets,

8289

or multiple hosts, you can create scenario variables, and modify the setting

8290

of the Tools parameters based on the value of these variables. See

8291

@ref{Scenarios and Configuration Variables} for more information on these

8292

variables.

8293

8294

For example, you may want to create a variable called @code{Target} to handle

8295

the different kind of targets handled in your project:

8296

8297

@table @b

8298

@item Target

8299

Native, Embedded

8300

@item Target

8301

Native, PowerPC, M68K

8302

@end table

8303

8304

Similarly, you may define a @code{Board} variable listing the different

8305

boards used in your environment and change the @i{Program host} and @i{Protocol}

8306

settings accordingly.

8307

8308

In some cases, it is useful to provide a different body file for a given

8309

package (e.g. to handle target specific differences). A possible approach

8310

in this case is to use a configuration variable (e.g. called @code{TARGET}),

8311

and specify a different naming scheme for this body file (in the project

8312

properties, @code{Naming} tab), based on the value of @code{TARGET}.

8313

8314

@node Debugger Issues

8315

@section Debugger Issues

8316

@cindex debugger

8317

@noindent

8318

This section describes some debugger issues that are specific to cross

8319

environments. You will find more information on debugging by reading

8320

@ref{Debugging}.

8321

8322

To connect automatically to the right remote debug agent when

8323

starting a debugging session (using the menu @code{Debug->Initialize}),

8324

be sure to specify the @code{Program host} and @code{Protocol} project

8325

properties, as described in the previous section.

8326

8327

For example, if you are using the @i{Tornado} environment, with a target

8328

server called @code{target_ppc}, set the @code{Protocol} to @code{wtx} and

8329

the @code{Program host} to @code{target_ppc}.

8330

8331

Once the debugger is initialized, you can also connect to a remote agent

8332

by using the menu @code{Debug->Debug->Connect to Board...}. This will open

8333

a dialog where you can specify the target name (e.g. the name of your

8334

@cindex board

8335

board or debug agent) and the communication protocol.

8336

8337

In order to load a new module on the target, you can select the menu

8338

@code{Debug->Debug->Load File...}.

8339

8340

If a module has been loaded on the target and is not known

8341

to the current debug session, use the menu

8342

@code{Debug->Debug->Add Symbols...} to load the symbol tables in the current

8343

debugger.

8344

8345

Similarly, if you are running the underlying debugger (gdb) on a remote

8346

machine, you can specify the name of this machine by setting the

8347

@code{Tools host} field of the project properties.

8348

8349

@c --------------------------------------------------------------------

8350

@node Using GPS for Remote Development

8351

@chapter Using GPS for Remote Development

8352

@cindex remote

8353

@cindex network

8354

@cindex client/server

8355

@c --------------------------------------------------------------------

8356

@menu

8357

* Requirements::

8358

* Setup the remote servers::

8359

* Setup a remote project::

8360

* Limitations::

8361

@end menu

8362

8363

@noindent

8364

In a network environment, it is common for programmers to use as a desktop

8365

a computer that is not directly suitable for their development tasks. For

8366

instance, each developers may have a PC running Windows or GNU/Linux as their

8367

main entrypoint to the company network and do all their development activities

8368

on servers potentially running a different operating system and on which the

8369

various project resources are shared. A typical way of operating in such an

8370

environment is to access the server through X-Window. GPS does naturally work

8371

in such a context but it is not necessarily the most efficient organization.

8372

Running GPS remotely on a shared remote server will increase the workload of the

8373

server as well as the traffic on the network. When the network is slow or

8374

saturated, the user interactions can become uncomfortably sluggish. This is a

8375

pity when the desktop used to access the network is often a powerful PC which

8376

remains idle most of the time. GPS offers the possibility to run natively on the

8377

desktop while compilation, run and/or debug activities are performed

8378

transparently on one or several remote server.

8379

8380

@node Requirements

8381

@section Requirements

8382

8383

@noindent

8384

In order to compile, run or debug on a remote host from GPS, three conditions

8385

need to be met:

8386

8387

@itemize

8388

@item

8389

@cindex password

8390

Have a remote connection to the host using 'rsh', 'ssh' or 'telnet'. Note that

8391

GPS can now handle passwords for such connections.

8392

8393

@item

8394

Either have a Network Filesystem (i.e. NFS, SMB or equivalent) sharing the

8395

project files between the host and the target, or having rsync installled on

8396

both client and server.

8397

8398

@item

8399

Subprojects must be withed by the main project using relative paths, or the

8400

same absolute paths exist on the involved machines.

8401

@end itemize

8402

8403

@noindent

8404

The full remote development setup is performed in several steps:

8405

@itemize

8406

@item Setup the remote servers configuration.

8407

@item Setup a remote project.

8408

@end itemize

8409

8410

@c -----------------------------------------------------------------------

8411

@node Setup the remote servers

8412

@section Setup the remote servers

8413

@c -----------------------------------------------------------------------

8414

8415

@menu

8416

* The remote configuration dialog::

8417

* Connection settings::

8418

* Paths settings::

8419

@end menu

8420

8421

@c -----------------------------------------------------------------------

8422

@node The remote configuration dialog

8423

@subsection The remote configuration dialog

8424

@c -----------------------------------------------------------------------

8425

8426

@noindent

8427

In order to configure remote servers, you need to open the remote

8428

configuration dialog. A predefined configuration can also be set when

8429

installing GPS, using xml files. @xref{Defining a remote server}, and

8430

@xref{Defining a remote path translation}, for more information.

8431

8432

The remote configuration dialog is opened via the remote view. You can

8433

open it using the menu @code{Tools->Views->Remote}.

8434

8435

@iftex

8436

@cindex screen shot

8437

@image{remote-view, 4.8cm}

8438

@end iftex

8439

8440

@ifhtml

8441

@cindex screen shot

8442

@image{remote-view}

8443

@end ifhtml

8444

8445

Once the Remote View is opened, click on @code{Settings} to open

8446

the servers configuration dialog.

8447

8448

@iftex

8449

@cindex screen shot

8450

@image{servers-configuration, 11.5cm}

8451

@end iftex

8452

8453

@ifhtml

8454

@cindex screen shot

8455

@image{servers-configuration}

8456

@end ifhtml

8457

8458

@noindent

8459

This dialog is composed of two parts:

8460

@itemize

8461

@item

8462

The left part of the dialog contains the list of configured servers,

8463

identified by their nickname. Three buttons allow you to create, reinitialize

8464

or delete a server.

8465

@item

8466

The right part of the dialog contains the selected server's configuration.

8467

@end itemize

8468

8469

You need first to create a new server. For this, click on the button

8470

@code{Add Server} on the bottom left part of the dialog. Enter a nickname

8471

identifying the server you want to connect to (this is not necessarily the

8472

network name of this server). Note that this nickname identifies the server and

8473

thus needs to be unique. This new server is then automatically selected,

8474

and the right part of the dialog shows its configuration, which is empty for

8475

the most part.

8476

8477

@c -----------------------------------------------------------------------

8478

@node Connection settings

8479

@subsection Connection settings

8480

@c -----------------------------------------------------------------------

8481

8482

The first configuration part that needs to be filled concerns the way

8483

we will connect to this server:

8484

8485

You have to enter first all mandatory fields, identified by an asterisk:

8486

@itemize

8487

@item

8488

The network name is the name used to connect to this server via your network.

8489

It can be either an IP address, a host name of your local network, or a fully

8490

qualified network name.

8491

@item

8492

The remote access tool is the tool used to connect to this server. You select

8493

it using the drop down list. The following tools are supported natively by

8494

GPS: ssh, rsh, telnet and plink (Windows tool) in ssh, rsh or telnet mode.

8495

@xref{Defining a remote connection tool}, if you need to add a

8496

specific tool.

8497

Note also that if one of those tools is not installed (e.g. is not in

8498

your path), then it won't appear in the tools list.

8499

@item

8500

The shell tells GPS what shell runs on the remote server. The following unix

8501

shells are supported by GPS: sh, bash, csh and tcsh. Windows' shell is also

8502

supported (cmd.exe). @xref{Limitations}, for cygwin's shell usage on

8503

windows: it is preferable to use cmd.exe as a remote shell on Windows servers.

8504

@end itemize

8505

8506

@noindent

8507

Other fields might need to be taken into consideration, but they are not

8508

mandatory. They are for the most part accessible through the advanced

8509

configuration pane.

8510

8511

@itemize

8512

@item

8513

The remote sync tool is used to synchronize remote and local filesystems, if

8514

these are not shared filesystems. For now, only rsync is supported.

8515

@item

8516

The Extra Init Commands field represent initialization commands sent to the

8517

server upon connection: when GPS connects to your remote machine, the chosen

8518

shell is launched, and your default initialization files are read (i.e. .bashrc

8519

file for the bash shell). Then GPS sends these extra init commands, allowing

8520

you for example to specify a compilation toolchain.

8521

@item

8522

(In Advanced configuration pane) The user name specifies the name used to connect to the server. If unspecified,

8523

the remote access tool will most of the time use your current login name. If

8524

not, and a user name is requested, gps will prompt you for a user name when

8525

requested.

8526

@item

8527

(In Advanced configuration pane) The timeout value is used to determine if a connection to a remote host is

8528

dead. All elementary operations performed on the remote host (i.e. operations

8529

that are normally almost immediate to perform) will use this timeout value. By

8530

default, this value is set to 10s. If you have a very slow network connection

8531

or a very overloaded server, set this timeout to a higher value.

8532

@item

8533

(In Advanced configuration pane) The maximum number of connections determines the maximum number of simultaneous

8534

connections GPS is allowed to perform to this server. In fact, if you want to

8535

compile, debug and execute at the same time on the machine, GPS will need

8536

more that one connection to do this. The default value is 3.

8537

@item

8538

(In Advanced configuration pane) The Debug console allow you to easily

8539

debug a remote connection. If checked, it will open a console

8540

reporting all exchanges between GPS and the selected server.

8541

@end itemize

8542

8543

@c -----------------------------------------------------------------------

8544

@node Paths settings

8545

@subsection Paths settings

8546

@c -----------------------------------------------------------------------

8547

8548

The last configuration part is to define the path translations between

8549

your local host and the remote server.

8550

8551

The remote paths definition will allow GPS to translate your locally loaded

8552

project (e.g. the project that resides in your local filesystem) to

8553

paths used on the remote server. This part also tells GPS how to keep

8554

those paths synchronized between the local machine and the remote server.

8555

8556

All your project's dependencies must then reside in a path that is defined

8557

here. Note that you can retrieve those paths by using @code{gnat list

8558

-v -Pyour_project}.

8559

8560

To add a new path, click on the @code{+} button, and enter the corresponding

8561

local and remote paths.

8562

8563

You can easily select the desired paths by clicking on the icon next

8564

to the path's entry. Remote browsing is allowed only when the

8565

connection configuration is set (@xref{Connection settings}.) Clicking

8566

on @code{Apply} will apply your connection configuration and allow you

8567

to browse the remote host to select the remote paths.

8568

8569

Four kind of paths synchronisation can be set for each defined path:

8570

@itemize

8571

@item @code{None}: no synchronisation is required from GPS, the paths

8572

are shared using an OS mechanism like NFS.

8573

@item @code{Always}: source path of your project. They are kept

8574

synchronised by GPS before and after every remote action.

8575

@item @code{Once to local}/@code{Once to remote}: project's

8576

dependencies. They are synchronized once when a remote project is

8577

loaded or when a local project is set remote. They can be still

8578

manually synchronized using the Remote View (@xref{The remote view}.)

8579

@end itemize

8580

8581

The way those paths need to be configured depend on your network architecture.

8582

8583

@itemize

8584

@item

8585

If your project is on a filesystem that is shared between your host and

8586

the remote host (using NFS of SMB filestems, for example), then only the roots

8587

of those filesystems need to be specified, using each server's native paths (on

8588

Windows, the paths will be expressed using X:\my\mounted\directory\ while on

8589

unix, the paths will be expressed using /mnt/path/).

8590

@item

8591

In case the project's files are synchronized using rsync, then defining

8592

a too generic path translation will lead to very slow synchronization. You will

8593

then need to define as specific paths as possible, in order to speed up

8594

the synchronization process.

8595

@end itemize

8596

8597

@c -----------------------------------------------------------------------

8598

@node Setup a remote project

8599

@section Setup a remote project

8600

@cindex remote project

8601

@c -----------------------------------------------------------------------

8602

8603

@menu

8604

* Remote operations::

8605

* The remote view::

8606

* Loading a remote project::

8607

@end menu

8608

8609

@c -----------------------------------------------------------------------

8610

@node Remote operations

8611

@subsection Remote operations

8612

@c -----------------------------------------------------------------------

8613

8614

@noindent

8615

GPS defines four different remote operation categories: Build operations,

8616

Debug operations, Execution operations and Tools operations. All compiler

8617

related operations are performed on the Build_Server. The Tools server is

8618

somewhat special and will be explained later. The debugger is run on

8619

the Debug_Server, and the project's resulting programs are run on the

8620

Execution_Server. The GPS_Server (the local machine) is used for all

8621

other operations.

8622

8623

The Tools server is defined to handle all compiler related operations that do

8624

not depend on a specific compiler version. It is used in dual compilation mode

8625

to determine whether the action can be safely run using a bleeding edge

8626

compiler toolchain (this is the tools server), or whether we need to stick with

8627

a specific older compiler version.

8628

8629

In case the remote mode is activated, and the dual compilation mode is not,

8630

then all Tools server operations are executed on the build server. Else, if the

8631

dual compilation mode is activated, then the tools server operations are always

8632

executed on the local machine.

8633

8634

@c -----------------------------------------------------------------------

8635

@node The remote view

8636

@subsection The remote view

8637

@c -----------------------------------------------------------------------

8638

8639

The Remote view (@code{Tools->Views->Remote}) allows you to assign to

8640

each operation category a configured server (when the Servers

8641

assignment tab is fully expanded) or assign at once all categories to

8642

a unique server (when the Servers assignment tab is collapsed) for the

8643

currently loaded project.

8644

8645

@iftex

8646

@cindex screen shot

8647

@image{remote-view-full, 4.8cm}

8648

@end iftex

8649

8650

@ifhtml

8651

@cindex screen shot

8652

@image{remote-view-full}

8653

@end ifhtml

8654

8655

@noindent

8656

When a server is selected for a particular category, the change is not

8657

immediately performed. Thus, the server's name will appear in red. You can

8658

check the configuration before applying it by pressing the

8659

@code{Check} button. This will test for correct remote hosts

8660

connection, and will check that the project path exists on the build server and

8661

has an equivalence on the local machine.

8662

8663

Clicking on the @code{Apply} button will perform the following actions:

8664

@itemize

8665

@item Read the default project paths on the Build machine and translate them

8666

into local paths.

8667

@item Synchronize from the build server the paths marked as Sync @code{Always} or @code{Once to

8668

local}.

8669

@item Load the translated local project.

8670

@item Assign the Build, Execution and Debug servers.

8671

@end itemize

8672

8673

If one of the above operations fail, then errors are reported in the

8674

@code{Messages} view, and the previous project is kept.

8675

8676

Once a remote server is assigned, this remote configuration will be

8677

automatically loaded each time the project is loaded.

8678

8679

@c -----------------------------------------------------------------------

8680

@node Loading a remote project

8681

@subsection Loading a remote project

8682

@c -----------------------------------------------------------------------

8683

8684

@noindent

8685

If the project you want to work with is already on a distant server, you can

8686

directly load it on your local GPS.

8687

8688

To do this, you need to use the @code{Project->Open From Host} menu.

8689

Then you select the server's nickname. This will show you its file tree.

8690

Navigate to your project, select it. The project will be loaded as described

8691

above, with all remote operations categories assigned to the selected server by

8692

default.

8693

8694

You can reload your project using the local files on your machine, the

8695

remote configuration will then be automatically reapplied.

8696

8697

@c -----------------------------------------------------------------------

8698

@node Limitations

8699

@section Limitations

8700

@c -----------------------------------------------------------------------

8701

8702

The GPS remote mode involves a few limitations:

8703

8704

@itemize

8705

@item Execution: you cannot use an external terminal to remotely execute your

8706

application. The @code{Use external terminal} checkbox of the run dialog will

8707

then have no effect if the program is run remotely.

8708

8709

@item Debugging: you cannot use a separate execution window. The

8710

@code{Use separate execution window} option is ignored for remote

8711

debugging sessions.

8712

8713

@item Cygwin on remote host: the GNAT compilation toolchain does not

8714

understand cygwin's mounted directories. In order to use GPS with

8715

a remote Windows server using cygwin's bash, you need to use

8716

directories that are the same on Windows and Cygwin (absolute

8717

paths). For example, a project having a C:\my_project will be accepted

8718

if cygwin's path is /my_project, but will not if

8719

/cygdrive/c/my_project is used.

8720

8721

Note that even if you use cygwin's sshd on such a server, you can

8722

still access it using cmd.exe (@xref{Connection settings}.)

8723

@end itemize

8724

8725

@c --------------------------------------------------------------------

8726

@node Customizing and Extending GPS

8727

@chapter Customizing and Extending GPS

8728

@cindex customization

8729

@c --------------------------------------------------------------------

8730

8731

@menu

8732

* The Preferences Dialog::

8733

* GPS Themes::

8734

* The Key Manager Dialog::

8735

* The Plug-ins Editor::

8736

* Customizing through XML and Python files::

8737

* Adding support for new tools::

8738

* Customization examples::

8739

* Scripting GPS::

8740

* Adding support for new Version Control Systems::

8741

* The Server Mode::

8742

@end menu

8743

8744

@noindent

8745

GPS provides several levels of customization, from simple preferences dialog

8746

to powerful scripting capability through the @code{python} language.

8747

This chapters describes each of these capabilities.

8748

8749

@node The Preferences Dialog

8750

@section The Preferences Dialog

8751

@anchor{preferences dialog}

8752

@cindex preferences

8753

@noindent

8754

This dialog, available through the menu @code{Edit->Preferences}, allows you to

8755

modify the global preferences of GPS.

8756

To enable the new preferences, you simply need to confirm by pressing

8757

the @code{OK} button. To test your changes, you can use the @code{Apply}

8758

button. Pressing the @code{Cancel} button will undo all your changes.

8759

8760

@iftex

8761

@cindex screen shot

8762

@image{preferences-general, 10.7cm}

8763

@end iftex

8764

8765

@ifhtml

8766

@cindex screen shot

8767

@image{preferences-general}

8768

@end ifhtml

8769

8770

Each preference is composed of a label displaying the name of the

8771

preference, and an editing area to modify its value. If you leave to mouse

8772

over the label, a tool tip will be displayed giving an on-line help on the

8773

preference.

8774

8775

The preferences dialog is composed of several areas, accessible through the

8776

tabs at the left of the dialog.

8777

Each page corresponds to a set of preferences.

8778

8779

@itemize @bullet

8780

@item @b{Themes}

8781

8782

This page allows you to quickly change the current settings for GPS, including

8783

preferences, key bindings, menus@dots{}; See @ref{GPS Themes} for more

8784

information on themes. It is only displayed when there are themes registered.

8785

8786

@item @b{General}

8787

8788

@table @i

8789

@item Default font

8790

@cindex font

8791

The default font used in GPS

8792

8793

@item Fixed view font

8794

@cindex font

8795

The fixed (monospace) font used in views like the outline view, the bookmark

8796

view, @dots{}; As much as possible, this font should use a fixed width for

8797

characters, for a better rendering

8798

8799

@item Character set

8800

@cindex character set

8801

@cindex ISO-8859-1

8802

Name of character set to use when reading or writting text files.

8803

GPS uses UTF-8 and Unicode internally, which can handle any character in

8804

any language. However, your system will generally not support Unicode natively,

8805

and thus the contents of the files should be translated from the file system

8806

encoding to unicode.

8807

8808

This preference indicates the file system encoding in use. It defaults to

8809

ISO-8859-1, which corresponds to western european characters.

8810

8811

@item Display splash screen

8812

@cindex splash screen

8813

Whether a splash screen should be displayed when starting GPS.

8814

8815

@item Display welcome window

8816

@cindex welcome dialog

8817

Whether GPS should display the welcome window for the selection of the project

8818

to use.

8819

8820

@item Tool bar style

8821

@cindex tool bar

8822

How the tool bar should be displayed: not at all, with small icons or with

8823

large icons

8824

8825

@item Show status bar

8826

@cindex status bar

8827

Whether the status bar at the bottom of the GPS window should be displayed.

8828

This status bar contains one or more progress bars while GPS is executing long

8829

actions like a build or a search. These progress bars can be used to monitor

8830

the progress of those actions.

8831

8832

If you wish to save vertical screen space, you can hide this status

8833

bar. The progress bars will no longer be visible. Instead, you can

8834

display the Task Manager through the @code{Tools->Views->Tasks} menu,

8835

to get similar information. This manager can then be put on the right

8836

or left side of the GPS window, for instance just below the Project

8837

View.

8838

8839

@item Show text in tool bar

8840

@cindex tool bar

8841

Whether the tool bar should show both text and icons, or only icons.

8842

8843

@item Auto save

8844

@cindex auto save

8845

Whether unsaved files and projects should be saved automatically before

8846

calling external tools (e.g. before a build).

8847

8848

@item Save project-specific desktop on exit

8849

@cindex desktop

8850

Whether the desktop (size and positions of all windows) should be saved when

8851

exiting. The default desktop is never saved automatically, i.e. GPS will only

8852

save a desktop associated with the current project. If you are working with

8853

a project created automatically by GPS, the desktop will not be saved.

8854

8855

@item Save editor in desktop

8856

@cindex desktop

8857

Determines when source editors should be saved in the desktop: @code{Never},

8858

@code{Always}, or when a source file is associated with the current project

8859

(@code{From_Project}).

8860

8861

@item Clipboard size

8862

@cindex clipboard

8863

This controls the size of the list where all the entries copied into the

8864

clipboard through @code{Edit->Copy} and @code{Edit->Cut} are saved. This list

8865

is navigated through the menu @code{Edit->Paste} and

8866

@code{Edit->Paste Previous}, as described earlier in this guide.

8867

8868

@item Multi language build

8869

Whether GPS should build more than just Ada sources for projects containing Ada

8870

and other languages (e.g. C).

8871

8872

By default, GPS will call gnatmake to build projects containing Ada sources,

8873

meaning that non Ada sources won't be built. By enabling this preference,

8874

a multi-language build tool (see below), will be called.

8875

8876

@item Multi language builder

8877

The multi-language builder to be used in case multi-language build has been

8878

activated (see above).

8879

8880

By default, @code{gprbuild} will be used. Alternatively, its prototype

8881

@code{gprmake} can be selected although we do not recommend it at this stage.

8882

8883

@item Jump to first location

8884

@cindex location

8885

Whether the first entry of the location window should be selected

8886

automatically, and thus whether the corresponding editor should be

8887

immediately open.

8888

8889

@end table

8890

8891

@item @b{Windows}

8892

8893

@cindex MDI

8894

@cindex Multiple Document Interface

8895

This section specifies preferences that apply to the @i{Multiple Document

8896

Interface} described in @ref{Multiple Document Interface}.

8897

8898

@table @i

8899

@item Opaque

8900

@cindex opaque

8901

If True, items will be resized or moved opaquely when not maximized.

8902

8903

@item Destroy floats

8904

@cindex float

8905

If False, closing the window associated with a floating item will put the item

8906

back in the main GPS window, but will not destroy it. If True, the item is

8907

destroyed.

8908

8909

@item All floating

8910

@cindex float

8911

If True, then all the windows will be floating by default, i.e. be under the

8912

control of your system (Windows) or your window manager (Unix machines). This

8913

replaces the MDI.

8914

8915

@item Short titles for floats

8916

@cindex float

8917

If True, all floating windows will have a short title. In particular, base

8918

file names will be used for editors instead of full names.

8919

8920

@item Background color

8921

@cindex color

8922

Color to use for the background of the MDI.

8923

8924

@item Title bar color

8925

@cindex color

8926

Color to use for the title bar of unselected items.

8927

8928

@item Selected title bar color

8929

@cindex color

8930

Color to use for the title bar of selected items.

8931

8932

@item Show title bars

8933

If True, each window in GPS will have its own title bars, showing some

8934

particular information (like the name of the file edited for editors), and

8935

some buttons to iconify, maximize or close the window. This title bar is

8936

highlighted when the window is the one currently selected.

8937

8938

If False, the title bar is not displayed, to save space on the screen. The

8939

tabs of the notebooks will then be highlighted.

8940

8941

@item Notebook tabs policy

8942

Indicates when the notebook tabs should be displayed. If set to "Never", you

8943

will have to select the window in the Window menu, or through the keyboard.

8944

If set to "Automatic", then the tabs will be shown when two or more windows

8945

are stacked.

8946

8947

@item Notebook tabs position

8948

Indicates where the notebook tabs should be displayed

8949

8950

@end table

8951

8952

@item @b{Editor}

8953

@cindex editor

8954

@table @i

8955

@item General

8956

8957

@table @b

8958

@item Strip blanks

8959

@cindex strip blanks

8960

Whether the editor should remove trailing blanks when saving a file.

8961

8962

@item Line terminator

8963

@cindex line terminator

8964

Choose between @i{Unix}, @i{Windows} and @i{Unchanged} line terminators when

8965

saving files. Choosing @i{Unchanged} will use the original line terminator

8966

when saving the file; @i{Unix} will use LF line terminators;

8967

@i{Windows} will use CRLF line terminators.

8968

8969

@item Display line numbers

8970

@cindex display line numbers

8971

Whether the line numbers should be displayed in file editors.

8972

8973

@item Display subprogram names

8974

@cindex Display subprogram names

8975

Whether the subprogram name should be displayed in the editor's status bar.

8976

8977

@item Tooltips

8978

@cindex tooltip

8979

Whether tool tips should be displayed automatically.

8980

8981

@item Tooltips timeout

8982

@cindex tooltip timeout

8983

Time (in milliseconds) before displaying tooltips.

8984

8985

@item Highlight delimiters

8986

@cindex highlight delimiter

8987

Determine whether the delimiter matching the character following the

8988

cursor should be highlighted. The list of delimiters includes: @code{@{@}[]()}

8989

8990

@item Autosave delay

8991

@cindex autosave delay

8992

@anchor{autosave delay}

8993

The period (in seconds) after which an editor is automatically saved,

8994

0 if none.

8995

8996

Each modified file is saved under a file called @code{.#filename#}, which is

8997

removed on the next explicit save operation.

8998

8999

@item Right margin

9000

@cindex right margin

9001

The right margin to highlight. 0 if none.

9002

This value is also used to implement the @code{Edit->Refill} command.

9003

9004

@item Block highlighting

9005

@cindex block highlighting

9006

Whether the editor should highlight the current block.

9007

The current block depends on the programming language, and will include

9008

e.g. procedures, loops, if statements, @dots{}

9009

9010

@item Block folding

9011

@cindex block folding

9012

Whether the editor should provide the ability to fold/unfold blocks.

9013

9014

@c @item Automatic syntax check

9015

@c @cindex automatic syntax

9016

@c Whether GPS should automatically check syntax in background for the source

9017

@c files that are being edited.

9018

9019

@item Speed Column Policy

9020

@cindex speed column policy

9021

When the Speed Column should be shown on the side of the editors:

9022

@table @code

9023

9024

@item Never

9025

The Speed Column is never displayed.

9026

9027

@item Automatic

9028

The Speed Column is shown whenever lines are highlighted in the editor, for

9029

example to show the current execution point, or lines

9030

containing compilation errors, @dots{};

9031

It disappears when no lines are highlighted.

9032

9033

@item Always

9034

The Speed Column is always displayed.

9035

9036

@end table

9037

9038

@item External editor

9039

@cindex external editor

9040

The default external editor to use.

9041

9042

@item Custom editor command

9043

@anchor{custom editor command}

9044

Specify the command line for launching a custom editor.

9045

It is assumed that the command will create a new window/terminal as needed.

9046

If the editor itself does not provide this capability (such as vi or pico under

9047

Unix systems), you can use an external terminal command, e.g:

9048

9049

@smallexample

9050

xterm -geo 80x50 -exe vi +%l %f

9051

@end smallexample

9052

9053

The following substitutions are provided:

9054

@table @code

9055

@item %l

9056

line to display

9057

9058

@item %c

9059

column to display

9060

9061

@item %f

9062

full pathname of file to edit

9063

9064

@item %e

9065

extended lisp inline command

9066

9067

@item %p

9068

top level project file name

9069

9070

@item %%

9071

percent sign ('%')

9072

@end table

9073

9074

@item Always use external editor

9075

True if all editions should be done with the external editor. This will

9076

deactivate completely the internal editor. False if the external editor

9077

needs to be explicitly called by the user.

9078

9079

@item Smart completion

9080

@cindex smart completion

9081

When enabled, GPS loads on startup all the information needed for the

9082

Smart completion to work.

9083

9084

@item Smart completion timeout

9085

The timeout, expressed in milliseconds, after which the Smart completion

9086

window appears automatically after entering a triggering character, such as '.'

9087

9088

@end table

9089

9090

@item Fonts & Colors

9091

@cindex font

9092

@cindex color

9093

9094

@table @b

9095

@item Default

9096

The default font, default foreground and default background colors used

9097

in the source editor.

9098

9099

@item Keywords

9100

Font and colors used to highlight keywords.

9101

9102

@item Comments

9103

Font and colors used to highlight comments.

9104

Setting the color to white will set a transparent color.

9105

9106

@item Annotated Comments

9107

Font and colors used to highlight annotated comments.

9108

Only relevant to Ada currently. Annotated comments are comments immediately

9109

followed by a special character, e.g. @code{#[]}.

9110

Setting the color to white will set a transparent color.

9111

9112

@item Strings

9113

Font and colors used to highlight strings.

9114

Setting the color to white will set a transparent color.

9115

9116

@item Current line color

9117

Color for highlighting the current line. Leave it to blank for no highlighting.

9118

Setting the color to white will set a transparent color.

9119

9120

@item Current block color

9121

Color for highlighting the current source block.

9122

9123

@item Delimiter highlighting color

9124

Color for highlighting delimiters.

9125

9126

@item Search results highlighting

9127

Color for highlighting the search results in the text of source editors.

9128

9129

@item Cursor color

9130

Color used for the cursor in editors and interactive consoles

9131

9132

@item Cursor aspect ratio

9133

Defines the size of the cursor, relatively to characters. 100 means the

9134

cursor will occupy the same size as a character, 10 means it will only

9135

occupy 10% of the size occupies by a character.

9136

9137

@end table

9138

9139

@item Ada

9140

@cindex Ada

9141

9142

@table @b

9143

@item Auto indentation

9144

@cindex indentation

9145

How the editor should indent Ada sources.

9146

None means no indentation; Simple means that indentation from the previous

9147

line is used for the next line; Extended means that a language specific

9148

parser is used for indenting sources.

9149

9150

@item Use tabulations

9151

@cindex tabulation

9152

Whether the editor should use tabulations when indenting.

9153

9154

@item Default indentation

9155

@cindex indentation level

9156

The number of spaces for the default Ada indentation.

9157

9158

@item Continuation lines

9159

@cindex continuation line

9160

The number of extra spaces for continuation lines.

9161

9162

@item Declaration lines

9163

@cindex declaration line

9164

The number of extra spaces for multiple line declarations.

9165

For example, using a value of 4, here is how the following code would be

9166

indented:

9167

9168

@cindex example

9169

@smallexample

9170

variable1,

9171

variable2,

9172

variable3 : Integer;

9173

@end smallexample

9174

9175

@item Conditional continuation lines

9176

@cindex conditional line

9177

The number of extra spaces used to indent multiple lines conditionals

9178

within parentheses.

9179

9180

For example, when this preference is set to 1 (the default), continuation

9181

lines are indented based on the previous parenthesis plus one space:

9182

9183

@cindex example

9184

@smallexample

9185

if (Condition1

9186

and then Condition2)

9187

then

9188

@end smallexample

9189

9190

When this preference is set to 3, this gives:

9191

9192

@cindex example

9193

@smallexample

9194

if (Condition1

9195

and then Condition2)

9196

then

9197

@end smallexample

9198

9199

@item Record indentation

9200

@cindex record indentation

9201

The number of extra spaces for record definitions, when the @code{record}

9202

keyword is on its own line.

9203

9204

For example, when this preference is set to 3 (the default), the

9205

following sample will be indented as:

9206

9207

@cindex example

9208

@smallexample

9209

type T is

9210

record

9211

F : Integer;

9212

end record;

9213

@end smallexample

9214

9215

When this preference is set to 1, this gives:

9216

9217

@cindex example

9218

@smallexample

9219

type T is

9220

record

9221

F : Integer;

9222

end record;

9223

@end smallexample

9224

9225

@item Case indentation

9226

@cindex case indentation

9227

Whether GPS should indent case statements with an extra level, as used in the

9228

Ada Reference Manual, e.g:

9229

9230

@cindex example

9231

@smallexample

9232

case Value is

9233

when others =>

9234

null;

9235

end case;

9236

@end smallexample

9237

9238

If this preference is set to @code{Non_Rm_Style}, this would be indented as:

9239

9240

@cindex example

9241

@smallexample

9242

case Value is

9243

when others =>

9244

null;

9245

end case;

9246

@end smallexample

9247

9248

By default (@code{Automatic}), GPS will choose to indent with an extra

9249

level or not based on the first @code{when} construct: if the first

9250

@code{when} is indented by an extra level, the whole case statement will

9251

be indented following the RM style.

9252

9253

@item Casing policy

9254

The way the editor will handle the case settings below.

9255

@code{Disabled} no auto-casing will be done;

9256

@code{End_Of_Line} auto-casing will be done when hitting @key{Enter} key;

9257

@code{On_The_Fly} auto-casing will be done word-by-word while typing.

9258

For the @code{End_Of_Line} and @code{On_The_Fly} policies it is always

9259

possible to force the casing of the current line by pressing the indentation

9260

key (@key{Ctrl-Tab} by default).

9261

9262

@item Reserved word casing

9263

How the editor should handle reserved words casing.

9264

@code{Unchanged} will keep the casing as-is;

9265

@code{Upper} will change the casing of all reserved words to upper case;

9266

@code{Lower} will change the casing to lower case;

9267

@code{Mixed} will change the casing to mixed case (all characters to

9268

lower case except first character and characters after an underscore

9269

which are set to upper case);

9270

@code{Smart_Mixed} As above but do not force upper case characters to

9271

lower case.

9272

9273

@item Identifier casing

9274

How the editor should handle identifiers casing.

9275

The values are the same as for the @i{Reserved word casing} preference.

9276

9277

@item Format operators/delimiters

9278

Whether the editor should add extra spaces around operators and delimiters

9279

if needed.

9280

If enabled, an extra space will be added when needed in the following cases:

9281

before an opening parenthesis;

9282

after a closing parenthesis, comma, semicolon;

9283

around all Ada operators (e.g. @code{<=}, @code{:=}, @code{=>}, @dots{})

9284

9285

@item Align colons in declarations

9286

Whether the editor should automatically align colons in declarations and

9287

parameter lists. Note that the alignment is computed by taking into account

9288

the current buffer up to the current line (or end of the current selection),

9289

so if declarations continue after the current line, you can select

9290

the declarations lines and hit the reformat key.

9291

9292

@item Align associations on arrows

9293

Whether the editor should automatically align arrows in associations

9294

(e.g. aggregates or function calls). See also previous preference.

9295

9296

@item Align declarations after colon

9297

Whether the editor should align continuation lines in variable declarations

9298

based on the colon character.

9299

9300

Consider the following code:

9301

9302

@cindex example

9303

@smallexample

9304

Variable : constant String :=

9305

"a string";

9306

@end smallexample

9307

9308

If this preference is enabled, it will be indented as follows:

9309

9310

@cindex example

9311

@smallexample

9312

Variable : constant String :=

9313

"a string";

9314

@end smallexample

9315

9316

@item Indent comments

9317

Whether to indent lines containing only comments and blanks, or to keep

9318

these lines unchanged.

9319

9320

@item Align comments on keywords

9321

Whether to align comment lines following @code{record} and

9322

@code{is} keywords immediately with no extra space.

9323

9324

When enabled, the following code will be indented as:

9325

9326

@cindex example

9327

@smallexample

9328

package P is

9329

-- Comment

9330

9331

[...]

9332

end P;

9333

@end smallexample

9334

9335

When disabled, the indentation will be:

9336

9337

@cindex example

9338

@smallexample

9339

package P is

9340

-- Comment

9341

9342

[...]

9343

end P;

9344

@end smallexample

9345

9346

@end table

9347

9348

@item C & C++

9349

@cindex C

9350

@cindex C++

9351

9352

@table @b

9353

@item Auto indentation

9354

@cindex indentation

9355

How the editor should indent C/C++ sources.

9356

None means no indentation; Simple means that indentation from the previous

9357

line is used for the next line; Extended means that a language specific

9358

parser is used for indenting sources.

9359

9360

@item Use tabulations

9361

@cindex tabulation

9362

Whether the editor should use tabulations when indenting. If True,

9363

the editor will replace each occurrence of eight characters by a tabulation

9364

character.

9365

9366

@item Default indentation

9367

@cindex indentation

9368

The number of spaces for the default indentation.

9369

9370

@end table

9371

9372

@end table

9373

9374

@item @b{Debugger}

9375

@cindex debugger

9376

@table @i

9377

9378

@item Preserve State on Exit

9379

@cindex breakpoint

9380

If this preference is enabled, the debugger will automatically save breakpoints

9381

when it exists, and restore them the next time the same executable is debugged.

9382

This is a convenient way to work on an executable, where the typical usage

9383

looks like compile, debug, compile, debug, @dots{}

9384

9385

When the preference is enabled, the debugger will also preserve the contents

9386

of the data window whenever it is closed. Reopening the window either during

9387

the same debugger session, or automatically when a new debugger is started

9388

on the same executable, will recreate the same boxes within the data window.

9389

9390

@item Debugger Windows

9391

@cindex debugger windows

9392

This preference controls what happens to debugger-related windows, like the

9393

call stack, the data window, the tasks view,..., when the debugger is

9394

terminated. There are three possible behavior:

9395

@itemize @bullet

9396

@item Close Windows

9397

9398

In this case, all these windows are closed. This saves memory and space on

9399

the screen, but you will need to explicitly reopen them and put them in the

9400

right location on the desktop the next time you start a debugger session.

9401

9402

@item Keep Windows

9403

9404

In this case, the windows are cleared, but kept on the desktop. When you

9405

start a new debugger session, the windows will be automatically reused. This

9406

ensures that you won't have to reopen and reposition them, but takes space

9407

on your screen

9408

9409

@item Hide Windows

9410

9411

The windows are cleared, and hidden. When you start a new debugger session,

9412

they are automatically made visible again and reused. This also ensures you

9413

will not have to reopen and reposition them, but requires a bit of memory.

9414

If you move some windows around while these windows are hidden, they might

9415

reappear in unexpected location the next time, although you then just have

9416

to move them.

9417

9418

@end itemize

9419

9420

@item Break on exceptions

9421

@cindex breakpoint

9422

@cindex exception

9423

Specifies whether a breakpoint on all exceptions should be set by

9424

default when loading a program. This setup is only taken into account

9425

when a new debugger is initialized, and will not modify a running

9426

debugger (use the breakpoint editor for running debuggers).

9427

9428

@item Execution window

9429

@cindex execution

9430

@cindex tty

9431

Specifies whether the debugger should create a separate execution

9432

window for the program being debugged.

9433

9434

Note that this preference cannot be taken into account for the current

9435

debug session: you need to terminate the current debug session and restart

9436

a new one.

9437

9438

If true, a separate console will be created. Under Unix systems, this

9439

console is another window in the bottom part of the main window; under

9440

Windows, this is a separate window created by the underlying gdb, since

9441

Windows does not have the notion of separate terminals (aka ttys).

9442

9443

Note that in this mode under Windows, the @code{Debug->Interrupt} menu

9444

will only interrupt the debugged program with recent versions of gdb.

9445

If you are using older versions of gdb, you need to hit

9446

@key{Ctrl-C} in the separate execution window to interrupt it while it is

9447

running. Note also that this separate execution window uses the default

9448

system-wide console properties (the size of the window, the

9449

colors...). It is possible to change those properties using e.g. the

9450

default console menu (top-left of the console) on Windows XP.

9451

9452

If false, no execution window will be created. The debugger assumes that the

9453

program being debugged does not require input, or that if it does, input

9454

is handled outside GPS. For example, when you attach to a running process,

9455

this process already has a separate associated terminal.

9456

9457

@item Show lines with code

9458

Specifies whether the source editor should display blue dots for lines

9459

that contain code. If set to @i{False}, gray dots will be displayed instead

9460

on each line, allowing breakpoint on any line. Disabling this option provides

9461

a faster feedback, since GPS does not need to query the debugger about which

9462

lines contain code.

9463

9464

@item Detect aliases

9465

@cindex aliases

9466

If enabled, do not create new items when an item with the same address is

9467

already present on the canvas.

9468

9469

@item Assembly range size

9470

@cindex range size

9471

Number of assembly lines to display in the initial display of the assembly

9472

window. If the size is 0, then the whole subprogram is displayed, but this

9473

can take a very long time on slow machines.

9474

9475

@item Current assembly line

9476

Color used to highlight the assembly code for the current line.

9477

9478

@item Color highlighting

9479

@cindex color

9480

Color used for highlighting in the debugger console.

9481

9482

@item Clickable item

9483

Indicates color to be used for the items that are click-able (e.g pointers).

9484

9485

@item Changed data

9486

Indicates color to be used to highlight fields in the data window that have

9487

changed since the last update.

9488

9489

@item Memory color

9490

Color used by default in the memory view window.

9491

9492

@item Memory highlighting

9493

Color used for highlighted items in the memory view.

9494

9495

@item Memory selection

9496

Color used for selected items in the memory view.

9497

9498

@item Item name

9499

Indicates the font to be used for the name of the item in the data window.

9500

9501

@item Item type

9502

Indicates font to be used to display the type of the item in the data window.

9503

9504

@item Max item width

9505

The maximum width an item can have.

9506

9507

@item Max item height

9508

The maximum height an item can have.

9509

9510

@end table

9511

9512

@item @b{External Commands}

9513

@cindex helper

9514

@cindex external commands

9515

@table @i

9516

@item List processes

9517

Command used to list processes running on the machine.

9518

9519

@item Remote shell

9520

@cindex remote shell

9521

Program used to run a process on a remote machine. You can specify arguments,

9522

e.g. @code{rsh -l user}

9523

9524

@item Remote copy

9525

@cindex remote copy

9526

Program used to copy a file from a remote machine. You can specify arguments,

9527

e.g. @code{rcp -l user}

9528

9529

@item Execute command

9530

@cindex execution

9531

Program used to execute commands externally.

9532

9533

@item HTML Browser

9534

@cindex html

9535

Only used under Unix, not relevant under Windows where the default HTML

9536

browser is used.

9537

Program used to execute view HTML files, for instance the documentation.

9538

Empty by default, which means that GPS will try to find a suitable HTML

9539

browser automatically. Only change the value if GPS cannot find a HTML

9540

browser, or if the browser found is not your preferred one.

9541

9542

@item Print command

9543

@cindex print

9544

@cindex a2ps

9545

@cindex PrintFile

9546

@anchor{Print Command}

9547

External program used to print files.

9548

9549

This program is required under Unix systems in order to print, and is set to

9550

@code{a2ps} by default.

9551

If @code{a2ps} is not installed on your system, you can download it

9552

from @url{ftp://ftp.enst.fr/pub/unix/a2ps/}, although other printing programs

9553

such as @code{lp} can be specified instead.

9554

9555

Under Windows systems, this program is optional and is empty by default, since

9556

a built-in printing is provided. An external tool will be used if specified,

9557

such as the PrintFile freeware utility available from

9558

@url{http://www.lerup.com/printfile/descr.html}

9559

9560

@end table

9561

9562

@item @b{Search}

9563

@cindex search

9564

@table @b

9565

9566

@item Confirmation for "Replace all"

9567

@cindex replace

9568

Enable or disable the confirmation popup for the replace all action.

9569

9570

@item Close on Match

9571

@cindex search

9572

If this option is enabled, the search window will be closed when a match is

9573

found.

9574

9575

@item Select on Match

9576

@cindex search

9577

If this option is enabled, the focus will be given to the editor when a match

9578

is found.

9579

9580

@item Preserve Search Context

9581

@cindex search

9582

If this option is enabled, the contents of the "Look in:" field will be

9583

preserved between consecutive searches in files.

9584

@end table

9585

9586

@item @b{Browsers}

9587

@cindex browsers

9588

@table @i

9589

@item General

9590

9591

@table @b

9592

@item Selected item color

9593

@cindex color

9594

Color to use to draw the selected item.

9595

9596

@item Background color

9597

@cindex color

9598

Color used to draw the background of the browsers.

9599

9600

@item Hyper link color

9601

@cindex color

9602

Color used to draw the hyper links in the items.

9603

9604

@item Selected link color

9605

@cindex color

9606

Color to use for links between selected items.

9607

9608

@item Default link color

9609

@cindex color

9610

Color used to draw the links between unselected items.

9611

9612

@item Ancestor items color

9613

@cindex color

9614

Color to use for the background of the items linked to the selected item.

9615

9616

@item Offspring items color

9617

@cindex color

9618

Color to use for the background of the items linked from the selected item.

9619

9620

@item Vertical layout

9621

@cindex vertical layout

9622

Whether the layout of the graph should be vertical (@i{True}) or

9623

horizontal (@i{False}). This setting applies to most browsers (call graph

9624

for instance), but does not apply to the entities browsers.

9625

9626

@end table

9627

9628

@item File Dependencies

9629

9630

@table @b

9631

@item Show system files

9632

@cindex Ada

9633

@cindex C

9634

Whether the system files (Ada runtime or standard C include files) should be

9635

visible in the browser.

9636

9637

@item Show implicit dependencies

9638

@cindex implicit dependency

9639

@cindex dependency

9640

If False, then only the explicit dependencies are shown in the browser.

9641

Otherwise, all dependencies, even implicit, are displayed.

9642

9643

@end table

9644

9645

@end table

9646

9647

@item @b{Visual diff}

9648

@cindex visual diff

9649

@cindex file comparison

9650

9651

Note that in order to perform visual comparison between files, GPS

9652

needs to call external tool (not distributed with GPS) such as @command{diff}

9653

or @command{patch}. These tools are usually found on most unix systems, and

9654

may not be available by default on other OSes. Under Windows, you can

9655

download them from one of the unix toolsets

9656

available, such as msys (@url{http://www.mingw.org/msys.shtml}) or

9657

cygwin (@url{http://www.cygwin.com}).

9658

9659

@table @i

9660

9661

@item Diff command

9662

@cindex diff

9663

@cindex -u

9664

@cindex -c

9665

Command used to compute differences between two files.

9666

Arguments can also be specified. The visual diff expects a standard diff

9667

output with no context (that is, no @code{-c} nor @code{-u} switch).

9668

Arguments of interest may include (this will depend on the version of diff

9669

used):

9670

9671

@table @b

9672

@item -b

9673

Ignore changes in amount of white space.

9674

9675

@item -B

9676

Ignore changes that just insert or delete blank lines.

9677

9678

@item -i

9679

Ignore changes in case; consider upper and lower case letters equivalent.

9680

9681

@item -w

9682

Ignore white space when comparing lines.

9683

9684

@end table

9685

9686

@item Patch command

9687

@cindex patch

9688

Command used to apply a patch. Arguments can also be specified.

9689

This command is used internally by GPS to perform the visual comparison on

9690

versioned files (e.g. when performing a comparison with a version control

9691

system).

9692

9693

This command should be compatible with the @command{GNU patch} utility.

9694

9695

@item Use old diff

9696

@cindex old diff

9697

Use the old version of the visual comparison.

9698

9699

@item Diff3 command

9700

@cindex diff3

9701

This item is only displayed if the preference @i{Use old diff} is disabled.

9702

Command used to query a 3-way diff. See @i{Diff command} for a description

9703

of the parameters.

9704

9705

@item Default color

9706

This item is only displayed if the preference @i{Use old diff} is disabled.

9707

The color used to indicate lines on which there is a difference, in the

9708

"reference" editor.

9709

9710

@item Old color

9711

This item is only displayed if the preference @i{Use old diff} is disabled.

9712

The color used to indicate spaces used by lines not present in one of the

9713

editors in a 3-way diff and present in the other editors.

9714

9715

@item Append color

9716

This item is only displayed if the preference @i{Use old diff} is disabled.

9717

The color used to display the lines that are present in an editor but not in the

9718

reference editor.

9719

9720

@item Remove color

9721

This item is only displayed if the preference @i{Use old diff} is disabled.

9722

The color used to display the lines that are present in the reference editor

9723

but not in other editors.

9724

9725

@item Change color

9726

This item is only displayed if the preference @i{Use old diff} is disabled.

9727

The color used to display the lines that have changed between the reference

9728

editor and the other editors.

9729

9730

@item Fine change color

9731

This item is only displayed if the preference @i{Use old diff} is disabled.

9732

The color used to highlight fine differences within a modified line.

9733

9734

@item Context length

9735

@cindex context length

9736

This item is only displayed if the preference @i{Use old diff} is enabled.

9737

The number of lines displayed before and after each chunk of differences.

9738

Specifying -1 will display the whole file.

9739

9740

@end table

9741

9742

@item @b{Messages}

9743

@cindex messages

9744

@table @i

9745

@item Color highlighting

9746

@cindex color

9747

Color used to highlight text in the messages window.

9748

9749

@item Color highlighting

9750

@cindex errors

9751

Color used to highlight lines causing compilation errors/warnings in the

9752

source editors. When this color is set to white, the errors/warnings are

9753

not highlighted. (@ref{Compilation/Build})

9754

9755

@item File pattern

9756

@cindex file pattern

9757

@cindex location

9758

Pattern used to detect file locations and the type of the output from the

9759

messages window.

9760

This is particularly useful when using an external tool such as a compiler

9761

or a search tool, so that GPS will highlight and allow navigation through source

9762

locations. This is a standard system V regular expression containing from two

9763

to five parenthesized subexpressions corresponding to the file, line, column,

9764

warnings or style error patterns.

9765

9766

@item File index

9767

@cindex file index

9768

Index of filename in the file pattern.

9769

9770

@item Line index

9771

@cindex line index

9772

Index of the line number in the file pattern.

9773

9774

@item Column index

9775

@cindex column index

9776

Index of the column number in the file pattern.

9777

9778

@item Warning index

9779

@cindex warning index

9780

Index of the warning identifier in the file pattern.

9781

9782

@item Style index

9783

@cindex column index

9784

Index of the style error identifier in the file pattern.

9785

9786

@end table

9787

9788

@item @b{Project}

9789

@table @i

9790

9791

@item Relative project paths

9792

@cindex relative project path

9793

Whether paths should be absolute or relative when the projects are modified.

9794

9795

@item Fast Project Loading

9796

@cindex fast project loading

9797

If the project respects a number of restrictions, activating the preference

9798

will provide major speed up when GPS parses the project. This is especially

9799

noticeable if the source files are on a network drive.

9800

9801

GPS assumes that the following restricitions are true when the preference

9802

is activated. If this isn't the case, no error is reported, and only minor

9803

drawacks will be visible in GPS (no detection that two files are the same

9804

if one of them is a symbolic link for instance, although GPS will still

9805

warn you if you are trying to overwrite a file modified on the disk).

9806

9807

The restrictions are the following:

9808

@itemize -

9809

@item Symbolic links shouldn't be used in the project.

9810

More precisely, you can only have symbolic links that point to files

9811

outside of the project, but not to another file in the project

9812

9813

@item Directories can't have source names.

9814

No directory name should match the naming scheme defined in the

9815

project. For instance, if you are using the default GNAT naming scheme,

9816

you cannot have directories with names ending with ".ads" or ".adb"

9817

9818

@end itemize

9819

9820

@item Load Xref info on project load

9821

@cindex load xref info on project load

9822

Whether the Xref information should be automatically loaded into memory when

9823

a new project is loaded. @xref{Support for Cross-References}.

9824

9825

@item Hidden directories pattern

9826

@cindex hidden directories pattern

9827

A regular expression used to match hidden directories. Such directories

9828

are not displayed by default in the project view, and are not taken into

9829

account for VCS operations working on directories.

9830

9831

@end table

9832

9833

@item @b{Outline}

9834

@anchor{Outline Preferences}

9835

9836

@table @i

9837

@item Font

9838

9839

You can choose a specific font for the outline view. Typically, this will

9840

be used to use a slightly smaller font than in the editor, so that you can

9841

see more entities at once on the screen.

9842

9843

@item Show Profiles

9844

9845

For some of the languages, in particular Ada, GPS can display the profile

9846

(list of parameters) for the subprograms. This can be used to differentiate

9847

between overloaded entities (ie entities with the same name). Disabling

9848

this preference will only show the entity name.

9849

9850

@item Sort alphabetically

9851

9852

If this preference is activated, the entities will be sorted alphabetically

9853

in the outline view. If disabled, they will be displayed in the order they are

9854

found in the source file.

9855

9856

@item Link with Editor

9857

9858

If this option is set, the current subprogram will be selected in the outline

9859

view every time the cursor position changes in the current editor. This

9860

option requires some computation for GPS, and you might want to avoid the

9861

slow down by disabling it.

9862

9863

@item Show file name

9864

9865

If this option is set, the outline view will show the name of the file on its

9866

first line, and indent slightly all following lines. If this option is unset,

9867

this will save some screen real estate, but you will have to look at the

9868

current editor to see what file is descrived in the Outline View.

9869

9870

@end table

9871

9872

@item @b{Documentation}

9873

@anchor{Documention Preferences}

9874

9875

This section specifies preferences that apply to the

9876

@i{Documentation Generator}. @ref{Documentation Generation} for more

9877

information.

9878

9879

@table @i

9880

@item Process body files

9881

9882

If this preference is enabled, implementation files will be processed.

9883

Otherwise, only the specification files will.

9884

9885

@item Show private entities

9886

9887

By default, no documentation is generated for private entities.

9888

Enabling this preference will change this behavior.

9889

9890

@item Call graph

9891

9892

If enabled, the documentation tool will compute and take advantage of source

9893

references to e.g generate call graph information.

9894

Activating this option will slow down the documentation generation process.

9895

9896

@item Up-to-date files only

9897

9898

If enabled, only files having up-to-date cross references information will be

9899

documented.

9900

9901

@item Comments filter regexp

9902

9903

A regular expression used to filter to comments found in the source code before

9904

using them for generating documentation. For example "^!.*" will remove all

9905

comments starting with '!'.

9906

9907

@item Spawn a browser

9908

9909

If enabled, a browser is spawned after each documentation generation to view

9910

the generated files. This browser is not spawned if disabled.

9911

9912

@end table

9913

9914

@end itemize

9915

9916

@c -----------------------------------------------------------------

9917

@node GPS Themes

9918

@section GPS Themes

9919

@cindex themes

9920

@c -----------------------------------------------------------------

9921

9922

@noindent

9923

GPS provides an extensive support for themes. Themes are predefined set

9924

of value for the preferences, for the key bindings, or any other

9925

configurable aspect of GPS.

9926

9927

For instance, color themes are a convenient way to change all colors in

9928

GPS at once, according to predefined choices (strongly contrasted colors,

9929

monochrome,...). It is also possible to have key themes, defining a set

9930

of key bindings to emulate e.g. other editors.

9931

9932

Any number of themes can be activated at the same time through the

9933

preferences dialog (@code{Edit->Preferences}). This dialog contains a list

9934

of all themes that GPS knows about, organized into categories for convenient

9935

handling. Just click on the buttons on the left of each theme name to activate

9936

that theme.

9937

9938

Note that this will immediately change the current preferences settings. For

9939

instance, if the theme you just selected changes the colors in the editor,

9940

these are changed immediately in the @code{Editor->Fonts & Colors}. You can

9941

of course still press @code{Cancel} to keep your previous settings

9942

9943

If multiple themes are active at the same time and try to override the same

9944

preferences, the last theme which is loaded by GPS will override all previously

9945

loaded themes. However, there is no predefined order in which the themes are

9946

loaded.

9947

9948

@c -----------------------------------------------------------------

9949

@node The Key Manager Dialog

9950

@section The Key Manager Dialog

9951

@c -----------------------------------------------------------------

9952

@noindent

9953

9954

The key manager is accessible through the menu @code{Edit->Key Shortcuts}.

9955

This dialog provides an easy way to associate key shortcuts with actions.

9956

These actions are either predefined in GPS, or defined in your own

9957

customization files, as documented in @ref{Customizing through XML and Python files}.

9958

It also provides an easy way to redefine the menu shortcuts.

9959

9960

@iftex

9961

@cindex screen shot

9962

@image{key-shortcuts, 8.7cm}

9963

@end iftex

9964

9965

@ifhtml

9966

@cindex screen shot

9967

@image{key-shortcuts}

9968

@end ifhtml

9969

9970

Actions are referenced by their name, and are grouped into categories. These

9971

categories indicate when the action applies. For instance, the indentation

9972

command only applies in source editors, whereas the command to change the

9973

current window applies anywhere in GPS.

9974

The categories can be explicitly specified when you created your own actions

9975

through XML files (@pxref{Defining Actions}).

9976

9977

Through the key manager, you can define key bindings similar to what Emacs

9978

uses (@key{control-x} followed by @key{control-k} for instance). To register

9979

such key bindings, you need to press the @code{Grab} button as usual, and then

9980

type the shortcut. The recording of the key binding will stop a short while

9981

after the last key stroke.

9982

9983

If you define complex shortcuts for menus, they will not appear next to

9984

the menu name when you select it with the mouse. This is expected, and is

9985

due to technical limitations in the graphical toolkit that GPS uses.

9986

9987

When you assign a new shortcut to an action, the following happens:

9988

9989

@itemize @bullet

9990

@item All actions and menus currently associated with the same key will no

9991

longer be executed when the key is pressed.

9992

@item All key shortcuts defined for this action are replaced by the new one.

9993

As a result, the action is only executable through this new shortcut.

9994

@end itemize

9995

9996

@c -----------------------------------------------------------------

9997

@node The Plug-ins Editor

9998

@section The Plug-ins Editor

9999

@cindex plug-ins

10000

@c -----------------------------------------------------------------

10001

10002

@noindent

10003

GPS can be extensively customized through external plug-ins. You can

10004

write your own plug-ins (@pxref{Customization files and plugins}), but

10005

GPS also comes with its own collection of plug-ins.

10006

10007

Some of them are loaded by default when GPS starts (for instance the

10008

support for the CVS version management system or support for

10009

highlighting in various programming languages); others are available

10010

for any user but not loaded automatically by GPS, for instance an

10011

Emacs emulation mode.

10012

10013

Among the plug-ins that are provided with GPS, you will find:

10014

@itemize @bullet

10015

@item Emacs emulation

10016

@cindex Emacs

10017

Several plug-ins emulate some of the functions provided by Emacs, such

10018

as the interactive search, manipulation of rectangles, navigation in

10019

the editor, and of course the usual Emacs key shortcuts

10020

10021

This emacs mode used to be activated in the preferences dialog, on the

10022

Themes page, but you should now activate it by loading the @file{emacs.xml}

10023

plug-in.

10024

10025

@item Makefile support

10026

@cindex Makefile

10027

A plug-in is provided that parses a Makefile and creates menus for each of

10028

its possible targets, so that you can easily start a make command.

10029

10030

@item Cross-references enhancements

10031

Various plug-ins take advantage of GPS's cross-references information to

10032

create additional menus to navigate (for instance to jump to the primitive

10033

operations of Ada tagged types, to the body of Ada separate entities, @dots{})

10034

10035

@item Text manipulation

10036

Several plug-ins provide support for advanced text manipulation in the

10037

editors, for instance to be able to align a set of lines based on various

10038

criteria, or to manipulate a rectangular selection of text.

10039

@end itemize

10040

10041

You can chose graphically which plug-ins should or should not be loaded

10042

on startup. To do so, select the menu @code{/Tools/Plug-ins}.

10043

This brings up a new window, containing two parts:

10044

10045

@itemize @bullet

10046

@item On the left is the list of all known plug-ins.

10047

10048

As described in @xref{Customization files and plugins}, GPS will

10049

search for candidates in various directories, and based on these

10050

directories decide whether to automatically load the plug-in or not.

10051

10052

This list indicates the name of the plug-in, and whether it has been

10053

loaded in this GPS session (when the toggle button is checked).

10054

10055

@item On the right are the details for the selected plug-in

10056

10057

This window is displayed as a notebook with two pages: on the first

10058

one you will see the exact location of the plug-in, the reason why it

10059

was loaded or not, and, more importantly, the source of the plug-in.

10060

By convention, each plug-in starts with a general comment that

10061

indicates the purpose of this plug-in, and some more detailed

10062

documentation on its usage.

10063

10064

For those interested, this also contains the plug-in itself, so that

10065

this can act as an example to create your own customization script.

10066

10067

Technically, the list of plug-in to load or not to load

10068

are stored in the file

10069

@file{HOME/.gps/startup.xml}.

10070

10071

If you have modified anything through this dialog (the list of plug-ins

10072

to load or unload), you will

10073

need to restart GPS. GPS cannot unload a module, since it can have too

10074

many possible effects on GPS (adding menus, overriding key

10075

shortcuts, @dots{}).

10076

10077

A dialog is displayed asking you whether you would like to exit GPS

10078

now. This will properly save all your files.

10079

10080

@end itemize

10081

10082

@c -----------------------------------------------------------------

10083

@node Customizing through XML and Python files

10084

@section Customizing through XML and Python files

10085

@cindex customization

10086

@c -----------------------------------------------------------------

10087

10088

@menu

10089

* Customization files and plugins::

10090

* Defining Actions::

10091

* Macro arguments::

10092

* Filtering actions::

10093

* Adding new menus::

10094

* Adding contextual menus::

10095

* Adding tool bar buttons::

10096

* Binding actions to keys::

10097

* Preferences support in custom files::

10098

* Creating themes::

10099

* Defining new search patterns::

10100

* Adding support for new languages::

10101

* Defining text aliases::

10102

* Defining project attributes::

10103

* Adding casing exceptions::

10104

* Adding documentation::

10105

* Adding stock icons::

10106

@c * Defining a documentation format::

10107

* Remote programming customization::

10108

@end menu

10109

10110

@c -----------------------------------------------------------------------

10111

@node Customization files and plugins

10112

@subsection Customization files and plugins

10113

@c -----------------------------------------------------------------------

10114

10115

@noindent

10116

You can customize lots of capabilities in GPS using files that are

10117

loaded by GPS at start up.

10118

10119

For example, you can add items in the menu and tool bars, as well as

10120

defining new key bindings, new languages, new tools, @dots{};

10121

Using Python as a programming language, you can also add brand new facilities

10122

and integrate your own tools in the GPS platform.

10123

10124

These customization files are searched for at startup in several different

10125

places. Depending on the location where they are found, these files will either

10126

be automatically loaded by GPS (and thus can immediately modify things in GPS),

10127

or will simply be made visible in the Plug-ins Editor

10128

(@pxref{The Plug-ins Editor}).

10129

10130

These directories are searched for in the order given below. Any script loaded

10131

latter can override setups done by previously loaded scripts. For instance,

10132

they could override a key shortcut, remove a menu, redefining a GPS

10133

action, @dots{}

10134

10135

In the directory names below, @file{INSTALL} is the name of the directory in

10136

which you have installed GPS. @file{HOME} is the user's home directory, either

10137

by default or as overriden by the @code{GPS_HOME} environment variable. If none

10138

of these exist, GPS will use the @code{USERPROFILE} environment variable.

10139

10140

In all these directories, only the files with @file{.xml} or @file{.py}

10141

extensions are taken into account. Other files are ignored, although for

10142

compatibility with future versions of GPS it is recommended not to keep other

10143

files in the same directory.

10144

10145

@itemize @bullet

10146

@item Automatically loaded system wide modules

10147

10148

The @file{INSTALL/share/gps/plug-ins} directory should contain the files that

10149

GPS will automatically load by default (unless overriden by the user through

10150

the Plug-ins Editor). These plug-ins are visible to any user on the

10151

system that uses the same GPS installation. This directory should be reserved

10152

for critical plug-ins that almost every one should use.

10153

10154

@item Not automatically loaded system wide modules

10155

10156

The @file{INSTALL/share/gps/library} directory should contain the files that

10157

GPS should show in the Plug-ins Editor, but not load automatically.

10158

Typically, these would be files that add optional capabilities to GPS, for

10159

instance an emacs emulation mode, or additional editor capabilities that a lot

10160

of users would not generally use.

10161

10162

@item @code{GPS_CUSTOM_PATH}

10163

10164

This environment variable can be set before launching GPS. It should contain

10165

a list of directories, separated by semicolons (';') on Windows systems and

10166

colons (':') on Unix systems. All the files in these directories with the

10167

appropriate extensions will be automatically loaded by default by GPS,

10168

unless overriden by the user through the Plug-ins Editor.

10169

10170

This is a convenient way to have project-specific customization files. You can

10171

for instance create scripts, or icons, that set the appropriate value for the

10172

variable and then start GPS. Depending on your project, this allows you to

10173

load specific aliases which do not make sense for other projects.

10174

10175

@item Automatically loaded user directory

10176

10177

The directory @file{HOME/.gps/plug-ins} is searched last. Any script

10178

found in there will be automatically loaded unless overriden in the

10179

Plug-ins Editor.

10180

10181

This is a convenient way for users to create their own plug-ins, or

10182

test them before they are made available to the whole system by

10183

copying them to one of the other directories.

10184

10185

@end itemize

10186

10187

Any script loaded by GPS can contain customization for various aspects

10188

of GPS, mixing aliases, new languages or menus, @dots{} in a single

10189

file. This is a convenient way to distribute your plug-ins to other

10190

users.

10191

10192

@subsubsection Python files

10193

10194

Although the format of the python plug-ins is free (as long as it can

10195

be executed by Python), the following organization is suggested. These

10196

plug-ins will be visible in the Plug-ins Editor, and therefore having

10197

a common format makes it easier for users to understand the goal of the

10198

plug-ins:

10199

10200

@itemize @bullet

10201

@item Comment

10202

10203

The first part of the script should be a general comment on the goal and

10204

usage of the script. This comment should use python's triple-quote

10205

convention, rather than start-of-line hash ('#') signs.

10206

10207

The first line of the comment should be a one liner explaining the goal

10208

of the script. It is separated by a blank line from the rest of the

10209

comment.

10210

10211

The rest of the comment is free-form.

10212

10213

@item Customization variables

10214

10215

If your script can be configured by the user by changing some global

10216

variables, they should be listed in their own section, and fully

10217

documented. The user can then, through the /Tools/Plug-ins editor

10218

change the value of these variables

10219

10220

@item Implementation

10221

10222

The implementation should be separated from the initial comment by a

10223

form-feed (control-L) character. The startup scripts editor will know

10224

not to display the rest of the script on the first page of the editor.

10225

10226

Generally speaking, scripts should avoid executing code as soon as they

10227

are loaded. This gives a chance to the user to change the value of global

10228

variables or even override functions before the script is actually launched.

10229

10230

The solution is to connect to the @code{"gps_started"} hook, as in

10231

10232

@smallexample

10233

^L

10234

###########################################################

10235

## No user customization below this line

10236

###########################################################

10237

10238

import GPS

10239

10240

def on_gps_started (hook_name):

10241

... launch the script

10242

10243

GPS.Hook ("gps_started").add (on_gps_started)

10244

@end smallexample

10245

10246

@end itemize

10247

10248

@subsubsection XML files

10249

10250

XML files must be utf8-encoded by default. In addition, you can

10251

specify any specific encoding through the standard @code{<?xml

10252

encoding="..." ?>} declaration, as in the following example:

10253

10254

@smallexample

10255

<?xml version="1.0" encoding="iso-8859-1"?>

10256

10257

10258

<title>encoded text</title>

10259

</submenu>

10260

@end smallexample

10261

10262

These files must be valid XML files, i.e. must start with the

10263

@code{<?xml?>} tag, and contain a single root XML node, the name of which is

10264

left to your consideration. The general format is therefore

10265

10266

@smallexample

10267

<?xml version="1.0" ?>

10268

<root_node>

10269

...

10270

</root_node>

10271

@end smallexample

10272

10273

It is also recommended that the first line after the @code{<?xml?>} tag

10274

contains a general comment describing the purpose and usage of the script.

10275

This comment will be made visible in the Plug-ins editor.

10276

10277

The list of valid XML nodes that can be specified under <root> is

10278

described in later sections. It includes:

10279

10280

@table @code

10281

@item <action>

10282

(@pxref{Defining Actions})

10283

@item <key>

10284

(@pxref{Binding actions to keys})

10285

@item <submenu>

10286

(@pxref{Adding new menus})

10287

@item <pref>

10288

(@pxref{Preferences support in custom files})

10289

@item <preference>

10290

(@pxref{Preferences support in custom files})

10291

@item <alias>

10292

(@pxref{Defining text aliases})

10293

@item <language>

10294

(@pxref{Adding support for new languages})

10295

@item <button>

10296

(@pxref{Adding tool bar buttons})

10297

@item <entry>

10298

(@pxref{Adding tool bar buttons})

10299

@item <vsearch-pattern>

10300

(@pxref{Defining new search patterns})

10301

@item <tool>

10302

(@pxref{Adding support for new tools})

10303

@item <filter>

10304

(@pxref{Filtering actions})

10305

@item <contextual>

10306

(@pxref{Adding contextual menus})

10307

@item <case_exceptions>

10308

(@pxref{Adding casing exceptions})

10309

@item <documentation_file>

10310

(@pxref{Adding documentation})

10311

@item <doc_path>

10312

(@pxref{Adding documentation})

10313

@item <stock>

10314

(@pxref{Adding stock icons})

10315

@item <project_attribute>

10316

(@pxref{Defining project attributes})

10317

@c @item <docgen_backend>

10318

@c (@pxref{Defining a documentation format})

10319

@item <remote_machine_descriptor>

10320

(@pxref{Defining a remote server})

10321

@item <remote_path_config>

10322

(@pxref{Defining a remote path translation})

10323

@item <remote_connection_config>

10324

(@pxref{Defining a remote connection tool})

10325

@item <rsync_configuration>

10326

(@pxref{Configuring rsync usage})

10327

@end table

10328

10329

@c -----------------------------------------------------------------------

10330

@node Defining Actions

10331

@subsection Defining Actions

10332

@cindex action

10333

@cindex <action>

10334

@cindex <shell>

10335

@cindex <external>

10336

@cindex <filter>

10337

@c -----------------------------------------------------------------------

10338

10339

@noindent

10340

This facility distinguishes the actions from their associated menus or

10341

key bindings. Actions can take several forms: external commands,

10342

shell commands and predefined commands, as will be explained in more details

10343

below.

10344

10345

The general form to define new actions is to use the @code{<action>} tag.

10346

This tag accepts the following attributes:

10347

10348

@table @code

10349

@item name (mandatory)

10350

This tag must be specified. It provides the name by which the action is

10351

referenced in other parts of the customization files, for instance when it is

10352

associated with a menu or a toolbar button. The name can contain any character,

10353

although it is recommended to avoid XML special characters. It mustn't

10354

start with a '/'.

10355

10356

@item output (optional)

10357

If specified, this attribute indicates where the output of the commands will

10358

be sent by default. This can be overridden by each command, using the same

10359

attribute for @code{<shell>} and @code{<external>} tags,

10360

@xref{Redirecting the command output}.

10361

10362

@item show-command (optional, default true)

10363

If specified, this attribute indicates whether the text of the command itself

10364

should be displayed at the same location as its output. Neither will be

10365

displayed if the output is hidden. The default is to show the command along

10366

with its output.

10367

This attribute can be overridden for each command.

10368

10369

@item show-task-manager (optional, default false)

10370

This attribute indicates whether an entry should be created in the task

10371

manager to show this command. Associated with this entry is the progress

10372

bar indicator, so if you hide the entry, no progress will be shown. On the

10373

other hand, several progress bars might be displayed for your action if you

10374

show the progress bar here, which might be an issue depending on the

10375

context.

10376

This attribute can be overriden for each external command.

10377

10378

@item category (optional, default "General")

10379

The category in the keybindings editor (menu @code{Edit/Key bindings}) in which

10380

the action should be shown to the user. If you specify an empty string, the

10381

action is considered as an implementation detail, and not displayed in the

10382

editor. The user will thus not be able to assign it a keybinding through the

10383

graphical user interface (although this is still doable through XML commands).

10384

@end table

10385

10386

If you are defining the same action multiple times, the last definition will

10387

be kept. However, existing menus, buttons, @dots{} that already reference that

10388

action will keep their existing semantic. The new definition will only be

10389

used for all new menus created from that point on.

10390

10391

The @code{<action>} can have one or

10392

several children, all of which define a particular command to execute. All

10393

of these commands are executed one after the other, unless one of them

10394

fails in which case the following commands are not executed.

10395

10396

The following XML tags are valid children for @code{<action>}.

10397

@table @code

10398

10399

@cindex external

10400

@item <external>

10401

This defines a command to execute through the system (i.e. a standard Unix or

10402

Windows command)

10403

10404

Note for Windows users: like under UNIX, scripts can be called

10405

from custom menu. In order to do that, you need to write your script in a

10406

@file{.bat} or @file{.cmd} file, and call this file as usual.

10407

The @code{external} tag would e.g. look like:

10408

10409

@smallexample

10410

<?xml version="1.0" ?>

10411

<external_example>

10412

10413

<external>c:\.gps\my_scripts\my_cmd.cmd</external>

10414

</action>

10415

</external_example>

10416

@end smallexample

10417

10418

This tag accepts the following attributes:

10419

10420

@table @code

10421

@item server (optional)

10422

This attribute can be used to execute the external command on a remote

10423

server. The accepted values are @code{"gps_server"} (default),

10424

@code{"build_server"}, @code{"execution_server"}, @code{"debug_server"} and

10425

@code{"tools_server"}.

10426

@xref{Remote operations}, for explanation of what these servers are.

10427

10428

@item check-password (optional)

10429

@cindex password

10430

This attribute can be used to tell GPS to check and handle password prompts

10431

from the external command. The accepted values are @code{"false"} (default)

10432

and @code{"true"}.

10433

10434

@item show-command (optional)

10435

This attribute can be used to override the homonym attribute specified for

10436

the @code{<action>} tag.

10437

10438

@item output (optional)

10439

This attribute can be used to override the homonym attribute specified for

10440

the @code{<action>} tag.

10441

10442

@item progress-regexp (optional)

10443

This attribute specifies a regular expression that the output of the

10444

command will be checked against. Every time the regular expression matches,

10445

it should provide two numeric values that are used to display the usual

10446

progress indicators at the bottom-right corner of the GPS window, as

10447

happens during regular compilations.

10448

10449

The name of the action is printed in the progress bar while the action is

10450

executing.

10451

10452

@smallexample

10453

<?xml version="1.0" ?>

10454

<progress_action>

10455

10456

<external

10457

progress-regexp="(\d+) out of (\d+).*$"

10458

progress-current="1"

10459

progress-final="2"

10460

progress-hide="true">gnatmake foo.adb

10461

</external>

10462

</action>

10463

</progress_action>

10464

@end smallexample

10465

10466

@item progress-current (optional, default is 1)

10467

This is the opening parenthesis count index in @code{progress-regexp}

10468

that contains the current step.

10469

10470

@item progress-final (optional, default is 2)

10471

This is the opening parenthesis count index in @code{progress-regexp}

10472

that contains the current last step. This last index can grow as

10473

needed. For example, gnatmake will output the number of

10474

the file it is currently examining, and the total number of files to be

10475

examined. However, that last number may grow up, since parsing a new file

10476

might generate a list of additional files to parse later on.

10477

10478

@item progress-hide (optional, default is true)

10479

If this attribute is set to the value "true", then all the lines that

10480

match @code{progress-regexp} and are used to compute the progress will

10481

not be displayed in the output console. For any other value of this

10482

attribute, these lines are displayed along will the rest of the output.

10483

10484

@item show-task-manager (optional, default inherited from @code{<action>})

10485

This attribute indicates whether an entry should be created in the task

10486

manager to show this command. Associated with this entry is the progress

10487

bar indicator, so if you hide the entry, no progress will be shown. On the

10488

other hand, several progress bars might be displayed for your action if you

10489

show the progress bar here, which might be an issue depending on the

10490

context.

10491

10492

If you have set a value for @code{progress-regexp}, this will automatically

10493

be set to true by default so that the progress bar is indeed displayed in

10494

the task manager. You can still override it explicitly for that

10495

@code{<external>} element to force hiding the progress bar.

10496

10497

@end table

10498

10499

@cindex on-failure

10500

@item <on-failure>

10501

10502

This tag specifies a group of command to be executed if the previous

10503

external command fails. Typically, this is used to parse the output of the

10504

command and fill the location window appropriately

10505

(@pxref{Processing the tool output}).

10506

10507

For instance, the following action spawn an external tool, and parses its

10508

output to the location window and the automatic fixing tool if the external

10509

tool happens to fail.

10510

10511

In this group of commands the %... and $... macros can be used (@pxref{Macro arguments}).

10512

10513

@smallexample

10514

<?xml version="1.0" ?>

10515

<action_launch_to_location>

10516

10517

10518

<on-failure>

10519

<shell>Locations.parse "%1" category<shell>

10520

<external>echo the error message is "%2"</external>

10521

</on-failure>

10522

<external>echo the tool succeeded with message %1</external>

10523

</action>

10524

</action_launch_to_location>

10525

@end smallexample

10526

10527

@cindex shell

10528

@cindex shell

10529

@cindex interactive command

10530

@item <shell>

10531

As well as external commands, you can use custom menu items to invoke GPS

10532

commands using the @code{shell} tag. These are command written in one of the

10533

shell scripts supported by GPS.

10534

10535

This tag supports the same @code{show-command} and @code{output} attributes

10536

as the @code{<action>} tag.

10537

10538

The following example shows how to

10539

create two actions to invoke the @code{help} interactive command and to open

10540

the file @file{main.c}.

10541

10542

@smallexample

10543

<?xml version="1.0" ?>

10544

<help>

10545

10546

10547

</action>

10548

10549

10550

</action>

10551

</help>

10552

@end smallexample

10553

10554

By default, commands are expected to be written in the GPS shell language.

10555

However, you can specify the language through the @code{lang} attribute. Its

10556

default value is @code{"shell"}.

10557

10558

The value of this attribute could also be "python".

10559

10560

When programming with the GPS shell, you can execute multiple commands

10561

by separating them with semicolons. Therefore, the following example

10562

adds a menu which lists all the files used by the current file, in a

10563

project browser.

10564

10565

@smallexample

10566

<?xml version="1.0" ?>

10567

<current_file_uses>

10568

10569

10570

10571

</action>

10572

</current_file_uses>

10573

@end smallexample

10574

10575

@item <description>

10576

@cindex description

10577

This tag contains a description for the command, which is used in the

10578

graphical editor for the key manager. @xref{The Key Manager Dialog}.

10579

10580

@item <filter>, <filter_and>, <filter_or>

10581

@cindex filter

10582

This is the context in which the action can be executed,

10583

@xref{Filtering actions}.

10584

10585

@end table

10586

10587

It is possible to mix both shell commands and external commands. For

10588

instance, the following command opens an xterm (on Unix systems only)

10589

in the current directory, which depends on the context.

10590

10591

@smallexample

10592

<?xml version="1.0" ?>

10593

<xterm_directory>

10594

10595

10596

<external>xterm</external>

10597

</action>

10598

</xterm_directory>

10599

@end smallexample

10600

10601

As seen in some of the examples above, some special strings are expanded by

10602

GPS just prior to executing the command. These are the "%f", "%d",.. See below

10603

for a full list.

10604

10605

More information on chaining commands is provided in @xref{Chaining commands}.

10606

10607

Some actions are also predefined in GPS itself. This include for instance

10608

aliases expansion, manipulating MDI windows, @dots{};

10609

All known actions (predefined

10610

and the ones you have defined in your own customization files) can be

10611

discovered by opening the key shortcut editor (@code{Edit->Key shortcuts} menu).

10612

10613

@c ---------------------------------------------------------------------

10614

@node Macro arguments

10615

@subsection Macro arguments

10616

@cindex menu

10617

@cindex argument

10618

@cindex substitution

10619

@c ---------------------------------------------------------------------

10620

10621

@noindent

10622

When an action is defined, you can use macro arguments to pass to your

10623

shell or external commands. Macro arguments

10624

are special parameters that are transformed every time the command is executed.

10625

The following macro arguments are provided.

10626

10627

The equivalent python command is given for all tests. These commands are useful

10628

when you are writing a full python script, and want to test for yourself

10629

whether the context is properly defined.

10630

10631

@table @code

10632

@item %a

10633

If the user clicked within the Locations Window, this is the name of the

10634

category to which the current line belongs

10635

10636

@item %builder

10637

Replaced by the default builder configured in GPS.

10638

This can be e.g. @code{gnatmake}, or @code{gprbuild}.

10639

Note: this macro is only available in the commands defined in the Build

10640

Manager and the Build Launcher dialogs.

10641

10642

@item %c

10643

This is the column number on which the user clicked.

10644

Python equivalent:

10645

@smallexample

10646

GPS.current_context().column()

10647

@end smallexample

10648

10649

@item %d

10650

The current directory.

10651

Python equivalent:

10652

@smallexample

10653

GPS.current_context().directory()

10654

@end smallexample

10655

10656

@item %dk

10657

The krunched name of the current directory.

10658

10659

@item %e

10660

Name of the entity the user clicked on.

10661

Python equivalent:

10662

@smallexample

10663

GPS.current_context().entity().name()

10664

@end smallexample

10665

10666

@item %ek

10667

Krunched name of the entity the user clicked on.

10668

This is the same as @code{%e}, except long names are shorted as in @code{%fk}.

10669

10670

@item %eL

10671

Replaced by either an empty string, or @code{-eL}, depending on whether the

10672

@code{Fast Project Loading} preference if set or not.

10673

@code{-eL} is used by GNAT tools to specify whether symbolink links

10674

should be followed or not when parsing projects.

10675

Note: this macro is only available in the commands defined in the Build

10676

Manager and the Build Launcher dialogs.

10677

10678

@item %f

10679

Base name of the currently selected file.

10680

Python equivalent:

10681

@smallexample

10682

import os.path

10683

os.path.basename (GPS.current_context().file().name())

10684

@end smallexample

10685

10686

@item %F

10687

Absolute name of the currently opened file.

10688

Python equivalent:

10689

@smallexample

10690

GPS.current_context().file().name()

10691

@end smallexample

10692

10693

@item %fk

10694

Krunched base name of the currently selected file.

10695

This is the same as %f, except that long names are shortened, and their middle

10696

letters are replaced by "[...]". This should be used in particular in menu

10697

labels, to keep the menus narrow.

10698

10699

@item %fp

10700

Base name of the currently selected file. If the file is not part of the project

10701

tree, or no file is selected, generate an error on the Messages window.

10702

Note: this macro is only available in the commands defined in the Build

10703

Manager and the Build Launcher dialogs.

10704

10705

@item %gnatmake

10706

Replaced by the gnatmake executable configured in your project file.

10707

10708

@item %gprclean

10709

Replaced by the default cleaner configured in GPS.

10710

This can be e.g. @code{gnat clean}, or @code{gprclean}.

10711

Note: this macro is only available in the commands defined in the Build

10712

Manager and the Build Launcher dialogs.

10713

10714

@item %i

10715

If the user clicked within the Project View, this is the name of the parent

10716

project, ie the one that is importing the one the user clicked on. Note that

10717

with this definition of parent project, a given project might have multiple

10718

parents. The one that is returned is read from the Project View itself.

10719

10720

@item %l

10721

This is the line number on which the user clicked.

10722

Python equivalent:

10723

@smallexample

10724

GPS.current_context().line()

10725

@end smallexample

10726

10727

@item %p

10728

The current project. This is the name of the project, not the project file, ie

10729

the @file{.gpr} extension is not included in this name, and the casing is the

10730

one found inside the project file, not the one of the file name itself.

10731

If the current context is an editor, this is the name of the project to which

10732

the source file belongs.

10733

Python equivalent:

10734

@smallexample

10735

GPS.current_context().project().name()

10736

@end smallexample

10737

10738

@item %P

10739

The root project. This is the name of the project, not the project file.

10740

Python equivalent:

10741

@smallexample

10742

GPS.Project.root().name()

10743

@end smallexample

10744

10745

@item %pp

10746

The current project file pathname. If a file is selected, this is the project

10747

file to which the source file belongs.

10748

Python equivalent:

10749

@smallexample

10750

GPS.current_context().project().file().name()

10751

@end smallexample

10752

10753

@item %PP

10754

The root project pathname.

10755

Python equivalent:

10756

@smallexample

10757

GPS.Project.root().file().name()

10758

@end smallexample

10759

10760

@item %pps

10761

This is similar to @code{%pp}, except it returns the project name prepended

10762

with @code{-P}, or an empty string if there is no project file selected and the

10763

current source file doesn't belong to any project. This is mostly for use with

10764

the GNAT command line tools. The project name is quoted if it contains spaces.

10765

Python equivalent:

10766

@smallexample

10767

if GPS.current_context().project():

10768

return "-P" & GPS.current_context().project().file().name()

10769

@end smallexample

10770

10771

@item %PPs

10772

This is similar to @code{%PP}, except it returns the project name prepended

10773

with @code{-P}, or an empty string if the root project is the default project.

10774

This is mostly for use with the GNAT command line tools.

10775

10776

@item %(p|P)[r](d|s)[f]

10777

Substituted by the list of sources or directories of a given project. This list

10778

is a list of space-separated, quoted names (all names are surrounded by double

10779

quotes, for proper handling of spaces in directories or file names).

10780

10781

@table @code

10782

@item P

10783

the root project.

10784

10785

@item p

10786

the selected project, or the root project if there is no project selected.

10787

10788

@item r

10789

recurse through the projects: sub projects will be listed as well as their

10790

sub projects, etc@dots{}

10791

10792

@item d

10793

list the source directories.

10794

10795

Python equivalent:

10796

@smallexample

10797

GPS.current_context().project().source_dirs()

10798

@end smallexample

10799

10800

@item s

10801

list the source files.

10802

10803

Python equivalent:

10804

@smallexample

10805

GPS.current_context().project().sources()

10806

@end smallexample

10807

10808

@item f

10809

output the list into a file and substitute the parameter with the

10810

name of that file. This file is never deleted by GPS, it is your responsibility

10811

to do so.

10812

@end table

10813

10814

@item %s

10815

This is the text selected by the user, if a single line was selected. When

10816

multiple lines were selected, this returns the empty string

10817

10818

@item %S

10819

This is either the text selected by the user, of the current entity if there

10820

is no selection. If the entity is part of an expression ("A.B.C"), then the

10821

whole expression is used instead of the entity name.

10822

10823

@item %X

10824

Replaced by a list of switches of the form @code{-X<variable>=<value>}, where

10825

<variable> is the name of a scenario variable and <value> its current

10826

value, as configured in the Scenario View. All the scenario variables

10827

defined in the current project tree will be listed.

10828

Note: this macro is only available in the commands defined in the Build

10829

Manager and the Build Launcher dialogs.

10830

10831

@item %vars

10832

Replaced by a list of switches of the form @code{<variable>=<value>}, where

10833

<variable> is the name of a scenario variable and <value> its current

10834

value, as configured in the Scenario View. All the scenario variables

10835

defined in the current project tree will be listed.

10836

Alternatively, you can also use @code{%vars(-D)} to generate a list of

10837

switches of the form @code{-D<variable>=<value>}.

10838

Note: this macro is only available in the commands defined in the Build

10839

Manager and the Build Launcher dialogs.

10840

10841

@item %M

10842

Replaced by the base filename of the Main source being considered for building.

10843

Note: this macro is only available in the commands defined in the Build

10844

Manager and the Build Launcher dialogs.

10845

10846

@item %%

10847

Replaced by the % sign.

10848

@end table

10849

10850

@cindex example

10851

Examples:

10852

10853

@table @code

10854

@item %Ps

10855

Replaced by a list of source files in the root project.

10856

10857

@item %prs

10858

Replaced by a list of files in the current project, and all imported

10859

sub projects, recursively.

10860

10861

@item %prdf

10862

Replaced by the name of a file that contains a list of source

10863

directories in the current project, and all imported sub projects,

10864

recursively.

10865

@end table

10866

10867

Another type of macros are expanded before commands are executed: These

10868

all start with the @code{$} character, and represent parameters passed to

10869

the action by its caller. Depending on the context, GPS will give zero, one

10870

or more arguments to the action. This is in particular used when you define

10871

your own VCS system. See also the shell function @code{execute_action}, which

10872

you can use yourself to execute an action and pass it some arguments.

10873

10874

These arguments are the following

10875

@table @code

10876

@item $1, $2, ... $n

10877

Where n is a number. These are each argument passed to the action

10878

10879

@item $1-, $2-, ... $n-

10880

This represents a string concatenating the specified argument and all

10881

arguments after it

10882

10883

@item $*

10884

This represents a string concatenating all arguments passed to the action

10885

10886

@item $repeat

10887

This is the number of times the action has been repeated in a row. It will in

10888

general be 1 (ie this is the first execution of the action), unless the user

10889

has first executed the action @code{"Repeat Next"}, which allows automatic

10890

repetition of an action.

10891

10892

By default, when the action "Repeat Next" is invoked by the user, it will repeat

10893

the following action as many times as the user specified. However, in some cases,

10894

either for efficiency reasons or simply for technical reasons, you might want to

10895

handle yourself the repear. This can be done with the following action

10896

declaration:

10897

10898

@smallexample

10899

10900

<shell lang="python">if $repeat==1: my_function($remaining + 1)</shell>

10901

</action>

10902

10903

def my_function (count):

10904

"""Perform an action count times"""

10905

...

10906

@end smallexample

10907

10908

Basically, the technics here is to only perform something the first time the

10909

action is called (hence the if statement), but pass your shell function the

10910

number of times that it should repeat (hence the @code{$remaining} parameter).

10911

10912

@item $remaining

10913

This is similar to $repeat, and indicates the number of times that the action

10914

remains to be executed. This will generally be 0, unless the user has chosen

10915

to automatically repeat the action a number of times.

10916

10917

@end table

10918

10919

@c ----------------------------------------------------------------------

10920

@node Filtering actions

10921

@subsection Filtering actions

10922

@cindex <filter>

10923

@cindex <filter_and>

10924

@cindex <filter_or>

10925

@c ----------------------------------------------------------------------

10926

10927

@noindent

10928

By default, an action will execute in any context in GPS. The user just

10929

selects the menu or key, and GPS tries to execute the action.

10930

10931

It is possible to restrict when an action should be considered as valid. If the

10932

current context is incorrect for the action, GPS will not attempt to run

10933

anything, and will display an error message for the user.

10934

10935

Actions can be restricted in several ways:

10936

10937

@enumerate

10938

@item Using macro arguments (@pxref{Macro arguments}).

10939

If you are using one of the macro arguments defined in the previous section,

10940

anywhere in the chain of commands for that action, GPS will first check that

10941

the information is available, and if not will not start running any of the

10942

shell commands or external commands for that action.

10943

10944

For instance, if you have specified @code{%F} as a parameter to one of the

10945

commands, GPS will check prior to running the action that there is a current

10946

file. This can be either a currently selected file editor, or for instance that

10947

the project view is selected, and a file node inside it is also selected.

10948

10949

You do not have to specify anything else, this filtering is automatic

10950

10951

Note however that the current context might contain more information than you

10952

expect. For instance, if you click on a file name in the Project View, then

10953

the current context contains a file (thus satisfies @code{%F}), but also

10954

contains a project (and thus satisfies @code{%p} and similar macros).

10955

10956

@item Defining explicit filters

10957

Explicit restrictions can be specified in the customization files. These are

10958

specified through the @code{<filter>}, @code{<filter_and>}

10959

and @code{<filter_or>} tags, see below.

10960

10961

These tags can be used to further restrict when the command is valid. For

10962

instance, you can use them to specify that the command only applies to Ada

10963

files, or only if a source editor is currently selected.

10964

10965

@end enumerate

10966

10967

@subsubsection The filters tags

10968

10969

Such filters can be defined in one of two places in the customization files:

10970

10971

@enumerate

10972

@item At the toplevel.

10973

At the same level as other tags such as @code{<action>}, @code{<menu>} or

10974

@code{<button>} tags, you can define named filters. These are general filters,

10975

that can be referenced elsewhere without requiring code duplication.

10976

10977

@item As a child of the @code{<action>} tag.

10978

Such filters are anonymous, although they provide exactly the same capabilities

10979

as the ones above. These are mostly meant for simple filters, or filters that

10980

you use only once.

10981

@end enumerate

10982

10983

There are three different kinds of tags:

10984

10985

@table @code

10986

@item <filter>

10987

This defines a simple filter. This tag takes no child tag.

10988

10989

@item <filter_and>

10990

All the children of this tag are composed together to form a compound filter.

10991

They are evaluated in turn, and as soon as one of them fails, the whole filter

10992

fails. Children of this tag can be of type @code{<filter>}, @code{<filter_and>}

10993

and @code{<filter_or>}.

10994

10995

@item <filter_or>

10996

All the children of this tag are composed together to form a compound filter.

10997

They are evaluated in turn, and as soon as one of them succeeds, the whole

10998

filter succeeds. Children of this tag can be of type @code{<filter>},

10999

@code{<filter_and>} and @code{<filter_or>}.

11000

11001

@end table

11002

11003

If several such tags are found following one another under an @code{<action>}

11004

tag, they are combined through "or", i.e. any of the filters may match for the

11005

action to be executed.

11006

11007

The @code{<filter>}, @code{<filter_and>} and @code{<filter_or>} tags accept the

11008

following set of common attributes:

11009

11010

@table @code

11011

@item name (optional)

11012

This attribute is used to create named filters, that can be reused elsewhere

11013

in actions or compound filters through the @code{id} attribute. The name can

11014

take any form.

11015

11016

@item error (optional)

11017

This is the error message printed in the GPS console if the filter doesn't

11018

match, and thus the action cannot be executed. If you are composing filters

11019

through @code{<filter_and>} and @code{<filter_or>}, only the error message of

11020

the top-level filter will be printed.

11021

11022

@end table

11023

11024

In addition, the @code{<filter>} has the following specific attributes:

11025

11026

@table @code

11027

@item id (optional)

11028

If this attribute is specified, all other attributes are ignored. This is used

11029

to reference a named filter previously defined. Here is for instance how you

11030

can make an action depend on a named filter:

11031

11032

@smallexample

11033

<?xml version="1.0" ?>

11034

<test_filter>

11035

11036

11037

11038

11039

</action>

11040

</test_filter>

11041

@end smallexample

11042

11043

A number of filters are predefined by GPS itself.

11044

11045

@table @code

11046

@item Source editor

11047

This filter will only match if the currently selected window in GPS is an

11048

editor.

11049

@item Explorer_Project_Node

11050

Matches when clicking on a project node in the Project View

11051

@item Explorer_Directory_Node

11052

Matches when clicking on a directory node in the Project View

11053

@item Explorer_File_Node

11054

Matches when clicking on a file node in the Project View

11055

@item Explorer_Entity_Node

11056

Matches when clicking on an entity node in the Project View

11057

@end table

11058

11059

@item language (optional)

11060

This attribute specifies the name of the language that must be associated

11061

with the current file to match. For instance, if you specify @code{ada},

11062

you must have an Ada file selected, or the action won't execute. The language

11063

for a file is found by GPS following several algorithms (file extensions, and

11064

via the naming scheme defined in the project files).

11065

11066

@item shell_cmd (optional)

11067

This attribute specifies a shell command to execute. The output value of this

11068

command is used to find whether the filter matches: if it returns "1" or

11069

"true", the filter matches. In any other case, the filter fails.

11070

11071

Macro arguments (%f, %p, @dots{}) are fully supported in the text of the

11072

command to execute.

11073

11074

@item shell_lang (optional)

11075

This attribute specifies in which language the shell command above is written.

11076

Its default value indicates that the command is written using the GPS shell.

11077

11078

@item module (optional)

11079

This attribute specifies that the filter only matches if the current window

11080

was setup by this specific GPS module. For instance, if you specify

11081

"Source_Editor", this filter will only match when the active window is a source

11082

editor.

11083

11084

The list of module names can be obtained by typing @code{lsmod} in the shell

11085

console at the bottom of the GPS window.

11086

11087

This attribute is mostly useful when creating new contextual menus.

11088

11089

@end table

11090

11091

When several attributes are specified for a @code{<filter>} node (which is not

11092

possible with @code{id}), they must all match for the action to be executed.

11093

11094

@smallexample

11095

<?xml version="1.0" ?>

11096

<!-- The following filter will only match if the currently selected

11097

window is a text editor editing an Ada source file -->

11098

<ada_editor>

11099

<filter_and name="Source editor in Ada" >

11100

11101

11102

</filter_and>

11103

11104

11105

11106

11107

11108

11109

</action>

11110

11111

<!-- An action with an anonymous filter. It will be executed if the

11112

selected file is in Ada, even if the file was selected through

11113

the project view -->

11114

11115

11116

11117

11118

</action>

11119

</ada_editor>

11120

@end smallexample

11121

11122

@c ----------------------------------------------------------------------

11123

@node Adding new menus

11124

@subsection Adding new menus

11125

@cindex menus

11126

@cindex <menu>

11127

@cindex <submenu>

11128

@cindex <title>

11129

@c ----------------------------------------------------------------------

11130

11131

@noindent

11132

These commands can be associated with menus, tool bar buttons and keys. All

11133

of these use similar syntax.

11134

11135

Binding a menu to an action is done through the @code{<menu>} and

11136

@code{<submenu>} tags.

11137

11138

The @code{<menu>} tag takes the following attributes:

11139

11140

@table @code

11141

@item action (mandatory)

11142

This attribute specifies which action to execute

11143

when the menu is selected by the user. If no action by this name was defined,

11144

no new menu is added. The action name can start with a '/', in which case

11145

it represents the absolute path to a menu to execute instead.

11146

11147

This attribute can be omitted only when no title is specified for the menu

11148

to make it a separator (see below).

11149

11150

If a filter is associated with the action through the @code{<filter>} tag,

11151

then the menu will be greyed out when the filter doesn't match. As a

11152

result, users will not be able to click on it.

11153

11154

@item before (optional)

11155

It specifies the name of another menu item before

11156

which the new menu should be inserted. The reference menu must have been

11157

created before, otherwise the new menu is inserted at the end. This attribute

11158

can be used to control where precisely the new menu should be made visible.

11159

11160

@item after (optional)

11161

This attribute is similar to @code{before}, but has a lower priority. If it

11162

is specified, and there is no @code{before} attribute, it specifies a reference

11163

menu after which the new menu should be inserted.

11164

11165

@end table

11166

11167

It should also have one XML child called @code{<title>} which specifies the

11168

label of the menu. This is really a path to a menu, and thus you can define

11169

submenus by specifying something like "/Parent1/Parent2/Menu" in the title

11170

to automatically create the parent menus if they don't exist yet.

11171

11172

You can define the accelerator keys for your menus, using underscores

11173

in the titles. Thus, if you want an accelerator on the first letter in

11174

a menu named @code{File}, set its title as @code{_File}.

11175

11176

The tag @code{<submenu>} accepts the following attributes:

11177

11178

@table @code

11179

@item before (optional)

11180

See description above, same as for @code{<menu>}

11181

11182

@item after (optional)

11183

See description above, same as for @code{<menu>}

11184

@end table

11185

11186

It accepts several children, among @code{<title>} (which must be specified

11187

at most once), @code{<submenu>} (for nested menus), and @code{<menu>}.

11188

11189

Since @code{<submenu>} doesn't accept the @code{action} attribute, you should

11190

use @code{<menu>} for clickable items that should result in an action, and

11191

@code{<submenu>} if you want to define several menus with the same path.

11192

11193

You can specify which menu the new item is added to in one of two ways:

11194

11195

@itemize @bullet

11196

@item Specify a path in the @code{title} attribute of @code{<menu>}

11197

@item Put the @code{<menu>} as a child of a @code{<submenu>} node

11198

This requires slightly more typing, but it allows you to specify the exact

11199

location, at each level, of the parent menu (before or after an existing

11200

menu).

11201

@end itemize

11202

11203

For example, this adds an item named @code{mymenu} to the standard

11204

@code{Edit} menu.

11205

11206

@smallexample

11207

<?xml version="1.0" ?>

11208

<test>

11209

11210

11211

11212

<title>mymenu</title>

11213

</menu>

11214

</submenu>

11215

</test>

11216

@end smallexample

11217

11218

The following has exactly the same effect:

11219

11220

@smallexample

11221

<?xml version="1.0" ?>

11222

<test>

11223

11224

<title>Edit/mymenu</title>

11225

</menu>

11226

</test>

11227

@end smallexample

11228

11229

The following adds a new item "stats" to the "unit testing" submenu

11230

in "my_tools".

11231

11232

@smallexample

11233

<?xml version="1.0" ?>

11234

<test>

11235

11236

<title>/My_Tools/unit testing/stats</title>

11237

</menu>

11238

</test>

11239

@end smallexample

11240

11241

The previous syntax is shorter, but less flexible than the following,

11242

where we also force the My_Tools menu, if it doesn't exist yet, to

11243

appear after the File menu. This is not doable by using only @code{<menu>}

11244

tags. We also insert several items in that new menu

11245

11246

@smallexample

11247

<?xml version="1.0" ?>

11248

<test>

11249

11250

<title>My_Tools</title>

11251

11252

<title>unit testing/stats</title>

11253

</menu>

11254

11255

<title>unit testing/stats2</title>

11256

</menu>

11257

</submenu>

11258

</test>

11259

@end smallexample

11260

11261

@cindex menu separator

11262

Adding an item with an empty title or no title at all inserts a

11263

menu separator. For instance, the following example will insert a separator

11264

followed by a File/Custom menu:

11265

11266

@smallexample

11267

<?xml version="1.0" ?>

11268

<menus>

11269

11270

11271

11272

11273

11274

<title>Custom</title>

11275

</menu>

11276

</submenu>

11277

</menus>

11278

@end smallexample

11279

11280

@c ----------------------------------------------------------------------

11281

@node Adding contextual menus

11282

@subsection Adding contextual menus

11283

@cindex <contextual>

11284

@c ----------------------------------------------------------------------

11285

11286

@noindent

11287

The actions can also be used to contribute new entries in the contextual

11288

menus everywhere in GPS. These menus are displayed when the user presses

11289

the right mouse button, and should only show actions relevant to the current

11290

context.

11291

11292

Such contributions are done through the @code{<contextual>} tag, which takes

11293

the following attributes:

11294

11295

@table @code

11296

@item "action" (mandatory)

11297

Name of the action to execute, and must be defined elsewhere in one of the

11298

customization files.

11299

11300

If this attribute is set to an empty string, a separator will be inserted

11301

in the contextual menu instead. If you specify a reference item with one of

11302

the "before" or "after" attribute, the separator will be visible only when

11303

the reference item is visible.

11304

11305

@item "before" (optional, default="")

11306

If it is specified, this attribute should be the name of another contextual,

11307

before which the new menu should appear. The name of predefined contextual

11308

menus can be found by looking at the output of "Contextual.list" in the shell

11309

console. The name of the contextual menus you define yourself is the value of

11310

the @code{<title>} child.

11311

11312

There is no guarantee that the new menu will appear just before the referenced

11313

menu. In particular, it won't be the case if the new menu is created before

11314

the reference menu was created, or if another later contextual menu indicates

11315

that it must be displayed before the same reference item.

11316

11317

@item "after" (optional, default="")

11318

Same as "before", except it indicates the new menu should appear after the

11319

reference item.

11320

11321

If both "after" and "before" are specified, only the latter is taken into

11322

account.

11323

11324

@end table

11325

11326

It accepts one child tag, @code{<Title>} which specifies the name of the

11327

menu entry. If this child is not specified, the menu entry will use the name

11328

of the action itself. The title is in fact the full path to the new menu entry.

11329

Therefore, you can create submenus by using a title of the form

11330

"Parent1/Parent2/Menu".

11331

11332

Special characters can be used in the title, and will be automatically

11333

expended based on the current context. These are exactly the ones described

11334

in the section for macros arguments, @xref{Macro arguments}.

11335

11336

The new contextual menu will only be shown if the filters associated with the

11337

action match the current context.

11338

11339

For instance, the following example inserts a new contextual menu which prints

11340

the name of the current file in the GPS console. This contextual menu is only

11341

displayed in source editors. This contextual menu entry is followed by a

11342

separator line, visible when the menu is visible

11343

11344

@smallexample

11345

<?xml version="1.0" ?>

11346

<print>

11347

11348

11349

11350

</action>

11351

11352

11353

<Title>Print Current File Name</Title>

11354

</contextual>

11355

11356

</print>

11357

@end smallexample

11358

11359

@c ----------------------------------------------------------------------

11360

@node Adding tool bar buttons

11361

@subsection Adding tool bar buttons

11362

@cindex tool bar

11363

@cindex <button>

11364

@cindex <entry>

11365

@c ----------------------------------------------------------------------

11366

11367

@noindent

11368

As an alternative to creating new menu items, you can create new

11369

buttons on the tool bar, with a similar syntax, by using

11370

the @code{<button>} tag. As for the @code{<menu>} tag, it requires an

11371

@code{action} attribute which specifies what should be done when the button

11372

is pressed. The button is not created if no such action was created.

11373

11374

@cindex jpeg

11375

@cindex png

11376

@cindex gif

11377

@cindex xpm

11378

Within this tag, the tag @code{<pixmap>} can be used to indicate

11379

the location of an image file (of the type @code{jpeg, png, gif}

11380

or @code{xpm}) to be used as icon for the button. An empty

11381

@code{<button>} tag indicates a separator in the tool bar.

11382

11383

A title can also be specified with @code{<title>}. This will be visible only

11384

if the user choses to see both text and icons (or text only) in the tool bar.

11385

This title also acts as a tooltip (popup help message) when the button is

11386

displayed as an icon only.

11387

11388

The following example defines a new button:

11389

11390

@smallexample

11391

<?xml version="1.0" ?>

11392

<stats>

11393

11394

<title>stats</title>

11395

<pixmap>/my_pixmaps/button.jpg</pixmap>

11396

</button>

11397

</stats>

11398

@end smallexample

11399

11400

The @code{<button>} tag allows you to create a simple button that the user

11401

can press to start an action. GPS also supports another type of button,

11402

a combo box, from which the user can choose among a list of choices. Such

11403

a combo box can be created with the @code{<entry>} tag.

11404

11405

This tag accepts the following arguments:

11406

11407

@table @code

11408

@item id (mandatory)

11409

11410

This should be a unique id for this combo box, and will be used later on

11411

to refer it, in particular from the scripting languages. It can be any

11412

string

11413

11414

@item label (default is "")

11415

11416

The text of a label to display on the left of the combo box. If this isn't

11417

specified, no text will be displayed

11418

11419

@item on-changed (default is "")

11420

11421

The name of a GPS action to execute whenever the user selects a new value

11422

in the combo box. This action is called with two parameters, the unique id

11423

of the combo box and the newly selected text respectively.

11424

@end table

11425

11426

It also accepts any number of @code{<choice>} tags, each of which defines

11427

one of the values the user can choose from. These tags accepts one optional

11428

attribute, "on-selected", which is the name of a GPS action to call when

11429

that particular value is selected.

11430

11431

@smallexample

11432

11433

<shell>echo A new animal was selected in combo $1: animal is $2</shell>

11434

</action>

11435

11436

<shell>echo Congratulations on choosing a Gnu</shell>

11437

</action>

11438

11439

<choice>Elephant</choice>

11440

11441

</entry>

11442

@end smallexample

11443

11444

A more convenient interface exists for Python, the GPS.Toolbar class, which

11445

gives you the same flexibility as above, but also gives you dynamic control

11446

over the entry. See the python documentation.

11447

11448

@c ---------------------------------------------------------------------

11449

@node Binding actions to keys

11450

@subsection Binding actions to keys

11451

@cindex key

11452

@cindex <key>

11453

@c ----------------------------------------------------------------------

11454

11455

@noindent

11456

All the actions defined above can be bound to specific key shortcuts through

11457

the @code{<key>} attribute. As usual, it requires one @code{<action>}

11458

attribute to specify what to do when the key is pressed. The name of the

11459

action can start with a '/' to indicate that a menu should be executed

11460

instead of a user-defined action.

11461

11462

If the action is the empty string, then instead the key will no longer be

11463

bound to any action.

11464

11465

This tag doesn't contain any child tag. Instead, its text contents specified

11466

the keyboard shortcut. The name

11467

of the key can be prefixed by @code{control-}, @code{alt-}, @code{shift-} or

11468

any combination of these to specify the key modifiers to apply.

11469

11470

You can also define multiple key bindings similar to Emacs's by separating them

11471

by a space. For instance, @code{control-x control-k} means that the user should

11472

press @key{control-x}, followed by a @key{control-k} to activate the

11473

corresponding action. This is only possible if the prefix key is not already

11474

bound to an action. If it is, you should first unbound it by passing an

11475

empty action to @code{<key>}.

11476

11477

Use an empty string to describe the key binding if you wish to deactivate a

11478

preexisting binding. The second example below deactivates the standard binding.

11479

11480

@smallexample

11481

<?xml version="1.0" ?>

11482

<keys>

11483

<key action="expand alias">control-o</key>

11484

11485

11486

11487

<key action="/Window/Close">control-x control-w</key>

11488

</key>

11489

@end smallexample

11490

11491

Multiple actions can be bound to the same key binding. They will all be

11492

executed in turn, followed by any menu for which this key is an accelerator.

11493

11494

When GPS processes a @code{<key>} tag, it does the following:

11495

@itemize @bullet

11496

@item Removes all actions bound to that key.

11497

This ensures that if you press the key, any action associated with it by

11498

default in GPS or in some other XML file will no longer be executed, and

11499

only the last one will be executed.

11500

@item Adds the new key to the list of shortcuts that can execute the

11501

action. Any existing shortcut on the action is preserved, and

11502

therefore there are multiple possible shortcuts for this action.

11503

@end itemize

11504

11505

@c ----------------------------------------------------------------

11506

@node Preferences support in custom files

11507

@subsection Preferences support in custom files

11508

@c ----------------------------------------------------------------

11509

11510

@subsubsection Creating new preferences

11511

@cindex <preference>

11512

11513

@noindent

11514

GPS has a number of predefined preferences to configure its behavior and its

11515

appearance. They are all customizable through the Edit->Preferences menu.

11516

11517

However, you might wish to add your own kind of preferences for your extension

11518

modules. This can easily be done through the usual GPS customization files.

11519

Preferences are different from project attributes (@pxref{Defining project attributes}),

11520

in that the latter will vary depending on which project is loaded

11521

by the user, whereas preferences are always set to the same value no matter

11522

what project is loaded.

11523

11524

Such preferences are created with the @code{<preference>} tag, which takes

11525

a number of attributes.

11526

11527

@table @code

11528

@item name (mandatory)

11529

11530

This is the name of the preference, used when the preference is saved by

11531

GPS in the @file{$HOME/.gps/preferences} file, and to query the value of

11532

a preference interactively through the @code{GPS.Preference} class in the

11533

GPS shell or python. There are a few limitation to the form of these names:

11534

they cannot contain space or underscore characters. You should replace the

11535

latter with minus signs for instance.

11536

11537

@item page (optional, default is "General")

11538

11539

The name of the page in the preferences editor where the preference can

11540

be edited. If this is the name of a non-existing page, GPS will automatically

11541

create it. If this is the empty string (""), the preference will not be

11542

editable interactively. This could be used to save a value from one session

11543

of GPS to the next, without allowing the user to alter it.

11544

11545

Subpages are references by separating pages name with colons (':').

11546

11547

@item default (optional, default depends on the type of the preference)

11548

11549

The default value of the preference, when not set by the user. This is 0 for

11550

integer preferences, the empty string for string preferences, True for boolean

11551

values, and the first possible choice for choice preferences.

11552

11553

@item tip (optional, default is "")

11554

11555

This is the text of the tooltip that appears in the preferences editor

11556

dialog.

11557

11558

@item label (mandatory)

11559

11560

This is the name of the preference as it appears in the preferences editor

11561

dialog

11562

11563

@item type (mandatory)

11564

11565

This is the type of the preference, and should be one of:

11566

11567

@itemize

11568

@item "boolean"

11569

11570

The preference can be True or False.

11571

11572

@item "integer"

11573

11574

The preference is an integer. Two optional attributes can be specified for

11575

@code{<preference>}, "minimum" and "maximum", which define the range of

11576

valid values for that integer. Default values are 0 and 10 respectively.

11577

11578

@item "string"

11579

11580

The preference is a string, which might contain any value

11581

11582

@item "color"

11583

11584

The preference is a color name, in the format of a named color such as

11585

"yellow", or a string similar to "#RRGGBB", where RR is the red component,

11586

GG is the green component, and BB is the blue component

11587

11588

@item "font"

11589

11590

The preference is a font

11591

11592

@item "choices"

11593

11594

The preference is a string, whose value is chosen among a static list of

11595

possible values. Each possible value is defined in a @code{<choice>} child

11596

of the @code{<preference>} node.

11597

11598

@end itemize

11599

11600

@end table

11601

11602

Here is an example that defines a few new preferences:

11603

11604

@smallexample

11605

<?xml version="1.0"?>

11606

11607

<preference name="my-int"

11608

page="Editor"

11609

label="My Integer"

11610

default="30"

11611

minimum="20"

11612

maximum="35"

11613

page="Manu"

11614

type="integer" />

11615

11616

<preference name="my-enum"

11617

page="Editor:Fonts & Colors"

11618

label="My Enum"

11619

default="1"

11620

type="choices" >

11621

<choice>Choice1</choice>

11622

<choice>Choice2</choice>

11623

<choice>Choice3</choice>

11624

</preference>

11625

</custom>

11626

@end smallexample

11627

11628

The values of the above preferences can be queries in the scripting languages:

11629

11630

@itemize

11631

11632

@item GPS shell

11633

11634

@smallexample

11635

Preference "my-enum"

11636

Preference.get %1

11637

@end smallexample

11638

11639

@item Python

11640

11641

@smallexample

11642

val = GPS.Preference ("my-enum").get ()

11643

val2 = GPS.Preference ("my-int").get ()

11644

@end smallexample

11645

11646

@end itemize

11647

11648

@subsubsection Setting preferences values

11649

@cindex <pref>

11650

11651

@noindent

11652

You can force specific default values for the preferences in the customization

11653

files through the @code{<pref>} tag. This is the same tag that is used by

11654

GPS itself when it saves the preferences edited through the preferences

11655

dialog.

11656

11657

This tag requires on attribute:

11658

11659

@table @code

11660

@item name

11661

This is the name of the preference of which you are setting a default value.

11662

Such names are predefined when the preference is registered in GPS, and can

11663

be found by looking at the @file{$HOME/.gps/preferences} file for each user,

11664

or by looking at one of the predefined GPS themes.

11665

@end table

11666

11667

It accepts no child tag, but the value of the @code{<pref>} tag defines the

11668

default value of the preference, which will be used unless the user has

11669

overridden it in his own preferences file.

11670

11671

Any setting that you have defined in the customization files will be

11672

overridden by the user's preferences file itself, unless the user was still

11673

using the default value of that preference.

11674

11675

This @code{<pref>} tag is mostly intended for use through the themes

11676

(@pxref{Creating themes}).

11677

11678

@c ----------------------------------------------------------------

11679

@node Creating themes

11680

@subsection Creating themes

11681

@cindex themes creation

11682

@cindex <theme>

11683

@c ----------------------------------------------------------------

11684

11685

@noindent

11686

In addition to the predefined themes that come with GPS, you can create

11687

your own themes and share them between users. You can then selectively

11688

chose which themes they want to activate through the preferences dialog

11689

(@pxref{GPS Themes}).

11690

11691

Creating new themes is done in the customization files through

11692

the @code{<theme>} tag.

11693

11694

This tag accepts a number of attributes:

11695

11696

@table @code

11697

@item name (mandatory)

11698

This is the name of the theme, as it will appear in the preferences dialog

11699

11700

@item description (optional)

11701

This text should explain what the text does. It appears in the preferences

11702

dialog when the user selects that theme.

11703

11704

@item category (optional, default is General)

11705

This is the name of the category in which the theme should be presented in

11706

the preferences dialog. Categories are currently only used to organize themes

11707

graphically. New categories are created automatically if you chose one that

11708

doesn't exist yet.

11709

11710

@end table

11711

11712

This tag accepts any other customization tag that can be put in the

11713

customization files. This includes setting preferences (@code{<pref>},

11714

defining key bindings (@code{<key}), defining menus (@code{<menu>}), @dots{}

11715

11716

If the same theme is defined in multiple locations (multiple times in the

11717

same customization file or in different files), their effects will be

11718

cumulated. The first definition of the theme seen by GPS will set the

11719

description and category for this theme.

11720

11721

All the children tags of the theme will be executed when the theme is activated

11722

through the preferences dialog. Although there is no strict ordering in which

11723

order the children will be executed, the global order is the same as for the

11724

customization files themselves: first the predefined themes of GPS, then the

11725

ones defined in customization files found through the @code{GPS_CUSTOM_PATH}

11726

directories, and finally the ones defined in files found in the user's

11727

own GPS directory.

11728

11729

@smallexample

11730

<?xml version="1.0" ?>

11731

<my-plug-in>

11732

11733

<menu action="my action"><title>/Edit/My Theme Menu</title></menu>

11734

</theme>

11735

</my-plug-in>

11736

@end smallexample

11737

11738

@c ----------------------------------------------------------------

11739

@node Defining new search patterns

11740

@subsection Defining new search patterns

11741

@cindex <vsearch-pattern>

11742

@cindex predefined patterns

11743

@c ----------------------------------------------------------------

11744

11745

@noindent

11746

The search dialog contains a number of predefined search patterns for Ada, C

11747

and C++. These are generally complex regular expressions, presented in the

11748

dialog with a more descriptive name. This includes for instance

11749

"Ada assignment", which will match all such assignments.

11750

11751

You can define your own search patterns in the customization files. This is

11752

done through the @code{<vsearch-pattern>} tag. This tag can have a number of

11753

children tags:

11754

11755

@table @code

11756

@item <name>

11757

11758

This tag is the string that is displayed in the search dialog to

11759

represent the new pattern. This is the text that the user will

11760

effectively see, instead of the often hard to understand regular

11761

expression.

11762

11763

@item <regexp>

11764

11765

This tag provides the regular expression to use when the pattern has

11766

been selected by the user. Be careful that you must protect reserved

11767

XML characters such as '<' and replace them by their equivalent

11768

expansion ("<" for this character).

11769

11770

This accepts one optional attribute, named @code{case-sensitive}. This

11771

attribute accepts one of two possible values ("true" or "false") which

11772

indicates whether the search should distinguish lower case and upper

11773

case letters. Its default value is "false".

11774

11775

@item <string>

11776

11777

This tag provides a constant string that should be searched.

11778

Only one of @code{<regexp>} and @code{<string>} should be provided. If

11779

both exists, the first @code{<regexp>} child found is used. If there is

11780

none, the first @code{<string>} child is used.

11781

11782

The tag accepts the same optional attribute @code{case-sensitive} as

11783

above

11784

@end table

11785

11786

Here is a small example on how the "Ada assignment" pattern was

11787

defined.

11788

11789

@smallexample

11790

<?xml version="1.0" ?>

11791

11792

<vsearch-pattern>

11793

<name>Ada: assignment</name>

11794

11795

</vsearch-pattern>

11796

</search>

11797

@end smallexample

11798

11799

@c --------------------------------------------------------------------------

11800

@node Adding support for new languages

11801

@subsection Adding support for new languages

11802

@cindex <Language>

11803

@c --------------------------------------------------------------------------

11804

11805

@noindent

11806

You can define new languages in a custom file by using the @code{Language}

11807

tag. Defining languages gives GPS the ability to highlight the syntax of a

11808

file, explore a file (using e.g. the project view), find files

11809

associated with a given language, @dots{}

11810

11811

As described previously for menu items, any file in the @file{plug-ins}

11812

directory will be loaded by GPS at start up. Therefore, you can either

11813

define new languages in a separate file, or reuse a file where you already

11814

define actions and menus.

11815

11816

The following tags are available in a @code{Language} section:

11817

11818

@table @code

11819

@item Name

11820

A short string describing the name of the language.

11821

11822

@item Parent

11823

If set to the name of an existing language (e.g. @code{Ada}, @code{C++}) or

11824

another custom language, this language will inherit by default all its

11825

properties from this language. Any field explicitly defined for this language

11826

will override the inherited settings.

11827

11828

@item Spec_Suffix

11829

A string describing the suffix of spec/definition files for this language.

11830

If the language does not have the notion of spec or definition file, you

11831

can ignore this value, and consider using the @code{Extension} tag instead.

11832

This tag must be unique.

11833

11834

@item Body_Suffix

11835

A string describing the suffix of body/implementation files for this language.

11836

This tag works in coordination with the @code{Spec_Suffix}, so that the user

11837

can choose to easily go from one file to the other.

11838

This tag must be unique.

11839

11840

@item Extension

11841

A string describing one of the valid extensions for this language. There can

11842

be several such children. The extension must start with a '.' character

11843

11844

@item Keywords

11845

A V7 style regular expression for recognizing and highlighting keywords.

11846

Multiple @code{Keywords} tags can be specified, and will be concatenated

11847

into a single regular expression. If the regular expression needs to match

11848

characters other than letters and underscore, you must also edit the

11849

@code{Wordchars} node. If a parent language has been specified for the

11850

current language definition it is possible to append to the parent Keywords

11851

by setting the @code{mode} attribute to @code{append}, the default value is

11852

@code{override} meaning that the keywords definition will replace the

11853

parent's one.

11854

11855

The full grammar of the regular expression can be found in the spec of the

11856

file @file{g-regpat.ads} in the GNAT run time.

11857

11858

@item Wordchars

11859

Most languages have keywords that only contain letters, digits and underscore

11860

characters. However, if you want to also include other special characters

11861

(for instance '<' and '>' in XML), you need to use this tag to let GPS

11862

know. The value of this node is a string made of all the special word

11863

characters. You do not need to include letters, digits or underscores.

11864

11865

@item Engine

11866

The name of a dynamic library providing one or several of the functions

11867

described below.

11868

11869

The name can be a full pathname, or a short name. E.g. under most Unix systems

11870

if you specify @code{custom}, GPS will look for @code{libcustom.so} in

11871

the @code{LD_LIBRARY_PATH} run time search path. You can also specify

11872

explicitly e.g. @code{libcustom.so} or @code{/usr/lib/libcustom.so}.

11873

11874

For each of the following five items, GPS will look for the corresponding

11875

symbol in @code{Engine} and if found, will call this symbol when needed.

11876

Otherwise, it will default to the static behavior, as defined by the other

11877

language-related items describing a language.

11878

11879

You will find the required specification for the C and Ada languages

11880

to implement the following functions in the directory

11881

@file{<prefix>/share/examples/gps/language} of your GPS installation.

11882

@file{language_custom.ads} is the Ada spec file; @file{language_custom.h} is

11883

the C spec file; @file{gpr_custom.ad?} are example files showing a possible Ada

11884

implementation of the function @code{Comment_Line}

11885

for the GPS project files (@file{.gpr} files), or any other Ada-like language;

11886

@file{gprcustom.c} is the C version of gpr_custom.adb.

11887

11888

@item Comment_Line

11889

Name of a symbol in the specified shared library corresponding to a

11890

function that will comment or uncomment a line (used to implement the menu

11891

@code{Edit->Un/Comment Lines}).

11892

11893

@item Parse_Constructs

11894

Name of a symbol in the specified shared library corresponding to a

11895

function that will parse constructs of a given buffer.

11896

11897

This procedure is used by GPS to implement several capabilities such as

11898

listing constructs in the project view, highlighting the current block of

11899

code, going to the next or previous procedure, @dots{}

11900

11901

@item Format_Buffer

11902

Name of a symbol in the specified shared library corresponding to a

11903

function that will indent and format a given buffer.

11904

11905

This procedure is used to implement the auto indentation when hitting the

11906

@key{enter} key, or when using the format key on the current selection or

11907

the current line.

11908

11909

@item Parse_Entities

11910

Name of a symbol in the specified shared library corresponding to a

11911

function that will parse entities (e.g. comments, keywords, @dots{}) of a given

11912

buffer. This procedure is used to highlight the syntax of a file, and

11913

overrides the @code{Context} node described below.

11914

11915

@item Context

11916

Describes the context used to highlight the syntax of a file.

11917

11918

@table @code

11919

@item Comment_Start

11920

A string defining the beginning of a multiple-line comment.

11921

11922

@item Comment_End

11923

A string defining the end of a multiple-line comment.

11924

11925

@item New_Line_Comment_Start

11926

A regular expression defining the beginning of a single line comment

11927

(ended at the next end of line). This regular expression may contain

11928

multiple possible line starts, such as @code{;|#} for comments starting

11929

after a semicolon or after the hash sign. If a parent language has been

11930

specified for the current language definition it is possible to append

11931

to the parent New_Line_Comment_Start by setting the @code{mode} attribute to

11932

@code{append}, the default value is @code{override} meaning that the

11933

New_Line_Comment_Start definition will replace the parent's one.

11934

11935

@item String_Delimiter

11936

A character defining the string delimiter.

11937

11938

@item Quote_Character

11939

A character defining the quote character, used for e.g. canceling the

11940

meaning of a string delimiter (@code{\} in C).

11941

11942

@item Constant_Character

11943

A character defining the beginning of a character literal.

11944

11945

@item Can_Indent

11946

A boolean indicating whether indentation should be enabled for this

11947

language. The indentation mechanism used will be the same for all languages:

11948

the number of spaces at the beginning of the current line is used when

11949

indenting the next line.

11950

11951

@item Syntax_Highlighting

11952

A boolean indicating whether the syntax should be highlighted/colorized.

11953

11954

@item Case_Sensitive

11955

A boolean indicating whether the language (and in particular the identifiers

11956

and keywords) is case sensitive.

11957

@end table

11958

11959

@item Categories

11960

Optional node to describe the categories supported by the project view

11961

for the current language. This node contains a list of @code{Category} nodes,

11962

each describing the characteristics of a given category, with the following

11963

nodes:

11964

11965

@table @code

11966

@item Name

11967

Name of the category, which can be either one of the following

11968

predefined categories:

11969

package, namespace, procedure, function, task, method, constructor,

11970

destructor, protected, entry,

11971

class, structure, union, type, subtype, variable, local_variable,

11972

representation_clause,

11973

with, use, include,

11974

loop_statement, case_statement, if_statement, select_statement,

11975

accept_statement, declare_block, simple_block, exception_handler,

11976

or any arbitrary name, which will create a new category.

11977

11978

@item Pattern

11979

Regular expression used to detect a language category.

11980

As for the @code{Keywords} node, multiple @code{Pattern} tags can be

11981

specified and will be concatenated into a single regular expression.

11982

11983

@item Index

11984

Index in the pattern used to extract the name of the entity contained in

11985

this category.

11986

11987

@item End_Index

11988

Optional attribute that indicates the index in the pattern used to start

11989

the next search. Default value is the end of the pattern.

11990

11991

@item Icon

11992

Name of a stock icon that should be used for that category (@pxref{Adding stock icons}). This attribute is currently ignored, and is reserved for future

11993

uses.

11994

@end table

11995

11996

@ifset extendedlanguage

11997

@item Project_Field

11998

This tag describes the tools that are used to support this

11999

language. The name of these tools is stored in the project files, and

12000

therefore only a limited number of tools can be specified. Note that this

12001

tag is currently only used by the project properties and wizard, and is

12002

not taken into account by other components.

12003

12004

This node has two attributes:

12005

12006

@table @code

12007

@item Name

12008

Name of the attribute in the project file. Currently, only

12009

@code{"compiler_command"} can be specified.

12010

12011

@item Index

12012

If present, this attributes indicates the index to use for the

12013

attribute in the project file. The line defining this attribute

12014

would therefore look like:

12015

12016

@smallexample

12017

for Name ("Index") use "value";

12018

@end smallexample

12019

12020

e.g:

12021

12022

@smallexample

12023

for Compiler_Command ("my_language") use "my_compiler";

12024

@end smallexample

12025

12026

The value of the index should be either the empty string or the

12027

name of the language.

12028

12029

@end table

12030

12031

The value of this tag is the string to use in the project properties

12032

editor when editing this project field.

12033

@end ifset

12034

12035

@end table

12036

12037

@noindent

12038

Here is an example of a possible language definition for the GPS project

12039

files:

12040

12041

@cindex example

12042

@smallexample

12043

<?xml version="1.0"?>

12044

12045

12046

<Name>Project File</Name>

12047

<Spec_Suffix>.gpr</Spec_Suffix>

12048

12049

<Keywords>limited|null|others|</Keywords>

12050

12051

12052

12053

<New_Line_Comment_Start>--</New_Line_Comment_Start>

12054

<String_Delimiter>"</String_Delimiter>

12055

<Constant_Character>'</Constant_Character>

12056

<Can_Indent>True</Can_Indent>

12057

<Syntax_Highlighting>True</Syntax_Highlighting>

12058

<Case_Sensitive>False</Case_Sensitive>

12059

</Context>

12060

12061

12062

12063

<Name>package</Name>

12064

<Pattern>^[ \t]*package[ \t]+((\w|\.)+)</Pattern>

12065

12066

</Category>

12067

12068

12069

12070

12071

</Category>

12072

</Categories>

12073

12074

12075

<Comment_Line>gpr_comment_line</Comment_Line>

12076

</Language>

12077

</Custom>

12078

@end smallexample

12079

12080

@c --------------------------------------------------------------------------

12081

@node Defining text aliases

12082

@subsection Defining text aliases

12083

@cindex aliases

12084

@cindex <alias>

12085

@c --------------------------------------------------------------------------

12086

12087

@noindent

12088

GPS provides a mechanism known as @b{aliases}. These are defined

12089

through the menu @code{Edit->Aliases}.

12090

12091

Each alias has a name, which is generally a short string of characters.

12092

When you type them in any textual entry in GPS (generally a source editor, but

12093

also entry fields for instance in the file selector), and then press the special

12094

activation key (by default @key{control-o}, controlled by a

12095

preference), this name is removed from the source editor, and replaced

12096

by the text you have associated with it.

12097

12098

Alias names may be composed of any character except newlines, but must start

12099

with a letter. GPS will jump to the start of each word before the current

12100

cursor position, and if the characters between this word start and the

12101

cursor position is an alias name (the comparison is case insensitive), this

12102

alias is expanded.

12103

12104

@iftex

12105

@cindex screen shot

12106

@image{aliases, 10.7cm}

12107

@end iftex

12108

12109

@ifhtml

12110

@cindex screen shot

12111

@image{aliases}

12112

@end ifhtml

12113

12114

The alias editor is divided into three main parts: on the left side, the list of

12115

currently defined aliases is shown. Clicking on any of them will

12116

display the replacement text for this alias. If you click again the

12117

selected alias, GPS displays a text entry which you can use to rename

12118

an existing alias. Alias names must start with a letter. A check

12119

button at the bottom selects whether the read-only aliases

12120

(i.e. system-wide aliases) should be displayed.

12121

12122

The second part is the expansion text for the alias, at the bottom

12123

right corner. This replacement text can used multiple lines, and

12124

contain some special text that act as a special replacement. These

12125

special texts are highlighted in a different color. You can insert

12126

these special entities either by typing them, or by right-clicking in

12127

the editor, and select the entity in the contextual menu.

12128

12129

The following special entities are currently defined:

12130

12131

@table @code

12132

@item %_

12133

This is the position where the cursor should be put once the

12134

replacement text has been inserted in the editor.

12135

12136

@item %(name)

12137

This is the name of a parameter. @i{name} can be any string you want,

12138

excluding closing parenthesis. See below for more information on

12139

parameters.

12140

12141

@item %D

12142

This is the current date, in ISO format. The year is displayed first,

12143

then the month and the day

12144

12145

@item %H

12146

This is the current time (hour, minutes and seconds)

12147

12148

@item %l

12149

If the expansion of the alias is done in a source editor, this is the

12150

line on which the cursor is when pressing @key{control-o}.

12151

12152

@item %c

12153

This is similar to @i{%l}, except it returns the current column.

12154

12155

@item %f

12156

If the expansion is done in a source editor, this is the name of the

12157

current file (its base name only, this doesn't include the directory)

12158

12159

@item %d

12160

If the expansion is done in a source editor, this is the directory in

12161

which the current file is

12162

12163

@item %p

12164

If the expansion is done in a source editor, this is the base name of

12165

the project file to which the file belongs.

12166

12167

@item %P

12168

If the expansion is done in a source editor, this is the full path

12169

name to the project file (directory and base name).

12170

12171

@item %O

12172

Used for recursive aliases expansion. This special character will expand

12173

the text seen before it in the current alias, after replacement of the

12174

parameters and possibly other recursive expansions. This is similar to pressing

12175

@key{control-o} (or any key you have defined for alias expansion) in the

12176

expanded form of the alias.

12177

12178

@item %%

12179

Inserts a percent sign as part of the expanded text

12180

12181

You cannot expand an alias recursively when already expanding that alias. For

12182

instance, if the alias expansion for @i{procedure} contains @i{procedure%O},

12183

the inner procedure will not be expanded.

12184

12185

@end table

12186

12187

The indentation as set in the expansion of the alias is preserved when

12188

the alias is expanded. All the lines will be indented the same amount

12189

to the right as the alias name. You can override this default behavior

12190

by selecting the check button @code{Indent source editor after expansion}.

12191

In this case, GPS will replace the name of the alias by its expansion,

12192

and then automatically recompute the position of each line with its

12193

internal indentation engine, as if the text had been inserted manually.

12194

12195

The third part of the aliases editor, at the top right corner, lists

12196

the parameters for the currently selected alias. Any time you insert a

12197

@i{%(name)} string in the expansion text, GPS automatically detects

12198

there is a new parameter reference (or an old reference has changed

12199

name or was removed); the list of parameters is automatically updated

12200

to show the current list.

12201

12202

Each parameters has three attributes:

12203

12204

@table @b

12205

@item name

12206

This is the name you use in the expansion text of the alias in the

12207

@i{%(name)} special entity.

12208

12209

@item Environment

12210

This specifies whether the default value of the parameter comes from

12211

the list of environment variables set before GPS was started.

12212

12213

@item default value

12214

Instead of getting the default value from the environment variable,

12215

you can also specify a fixed text.

12216

Clicking on the initial value of the currently selected variable opens

12217

a text entry which you can use to edit this default value.

12218

12219

@end table

12220

12221

When an alias that contains parameters is expanded, GPS will first

12222

display a dialog to ask for the value of the parameters. You can

12223

interactively enter this value, which replaces all the @i{%(name)}

12224

entities in the expansion text.

12225

12226

@subsection Aliases files

12227

12228

@noindent

12229

The customization files described earlier can also contain aliases

12230

definition. This can be used for instance to create project or system wide

12231

aliases. All the customization files will be parsed to look for aliases

12232

definition.

12233

12234

All these customization files are considered as read-only by GPS,

12235

and therefore cannot be edited through the graphical interface. It is

12236

possible to override some of the aliases in your own custom files.

12237

12238

There is one specific files, which must contain only aliases definition. This

12239

is the file @file{$HOME/.gps/aliases}. Whenever you edit aliases graphically,

12240

or create new ones, they are stored in this file, which is the only one that

12241

GPS will ever modify automatically.

12242

12243

The system files are loaded first, and aliases defined there can be

12244

overridden by the user-defined file.

12245

12246

These files are standard XML customization files.

12247

The specific XML tag to use is @i{<alias>}, one per new alias.

12248

The following example contains a standalone customization file, but you might

12249

wish to merge the @i{<alias>} tag in any other customization file.

12250

12251

The following tags are available:

12252

12253

@table @code

12254

@item alias

12255

This indicates the start of a new alias. It has one mandatory

12256

attribute, @code{name}, which the text to type in the source editor

12257

before pressing @key{control-o}.

12258

It has one optional attribute, @code{indent}, which, if set to @i{true},

12259

indicate that GPS should recompute the indentation of the newly inserted

12260

paragraph after the expansion.

12261

12262

@item param

12263

These are children of the @code{alias} node. There is one per

12264

parameter of the alias. They have one mandatory attribute,

12265

@code{name}, which is the name to type between @i{%(name)} in the

12266

alias expansion text.

12267

12268

They have one optional attribute, @code{environment}, which indicates

12269

the default value must be read from the environment variables if it is

12270

set to true.

12271

12272

These tags contain text, which is the default value for the parameter.

12273

12274

@item text

12275

This is a child of the @code{alias} node, whose value is the

12276

replacement text for the alias.

12277

@end table

12278

12279

Here is an example of an alias file:

12280

12281

@smallexample

12282

<?xml version="1.0"?>

12283

12284

12285

12286

12287

<text>procedure %(p) is

12288

%(env)%_

12289

end %(p);</text>

12290

</alias>

12291

</Aliases>

12292

@end smallexample

12293

12294

@c --------------------------------------------------------------------------

12295

@node Defining project attributes

12296

@subsection Defining project attributes

12297

@cindex project attributes

12298

@cindex <project_attribute>

12299

@c --------------------------------------------------------------------------

12300

12301

@noindent

12302

The project files are required by GPS, and are used to store various

12303

pieces of information related to the current set of source files. This

12304

includes how to find the source files, how the files should be compiled,

12305

or manipulated through various tools, @dots{}.

12306

12307

However, the default set of attributes that are usable in a project file

12308

is limited to the attributes needed by the tool packaged with GPS or GNAT.

12309

12310

If you are delivering your own tools, you might want to store similar

12311

information in the project files themselves, since these are a very

12312

convenient place to associate some specific settings with a given set of

12313

source files.

12314

12315

GPS lets manipulate the contents of projects through XML customization

12316

files and script commands. You can therefore add you own typed attributes

12317

into the projects, so that they are saved automatically when the user

12318

saves the project, and reloaded automatically the next time GPS is started.

12319

12320

@subsubsection Declaring the new attributes

12321

12322

New project attributes can be declared in two ways: either using the advanced

12323

XML tags below, or using the @code{<tool>} tag (@pxref{Defining tool switches}).

12324

12325

The customization files support the @code{<project_attribute>} tag,

12326

which is used to declare all the new attributes that GPS should expect

12327

in a project. Attributes that have not been declared explictly will

12328

not be accessible through the GPS scripting languagues, and will

12329

generate warnings in the Messages window.

12330

12331

Project attributes are typed: they can either have a single value, or

12332

have a set of such values (a list). The values can in turn be a

12333

free-form string, a file name, a directory name, or a value extracted

12334

from a list of preset values.

12335

12336

Attributes that have been declared in these customization files will

12337

also be graphically editable through the project properties dialog, or

12338

the project wizard. Therefore, you should specify when an attribute is

12339

defined how it should be presented to the GPS user.

12340

12341

The @code{<project_attribute>} tag accepts the following attributes:

12342

12343

@itemize @bullet

12344

@item @code{package} (a string, default value: "")

12345

12346

This is the package in the project file in which the attribute is

12347

stored. Common practice suggests that one such package should be used

12348

for each tool. These packages provide namespaces, so that attributes

12349

with the same name, but for different tools, do not conflict with each

12350

other.

12351

12352

@item @code{name} (a string, mandatory)

12353

12354

This is the name of the attribute. This should be a string with no

12355

space, and that represents a valid Ada identifier (typically, it

12356

should start with a letter and be followed by a set of letters, digits

12357

or underscore characters). This is an internal name that is used when

12358

saving the attribute in a project file.

12359

12360

@item @code{editor_page} (a string, default value: "General")

12361

12362

This is the name of the page in the Project Properties editor dialog

12363

in which the attribute is presented. If no such page already exists, a

12364

new one will be created as needed. If the page already exists, the

12365

attribute will be appended at its bottom.

12366

12367

@item @code{editor_section} (a string, default value: "")

12368

12369

This is the name of the section, inside editor page, in which the

12370

attribute is displayed. These sections are surrounded by frames, the

12371

title of which is given by the @code{editor_section} attribute.

12372

If this attribute is not specified, the attribute is put in an

12373

untitled section.

12374

12375

@item @code{label} (a string, default value: the name of the attribute)

12376

12377

If this attribute is set to a value other than the empty string

12378

@code{""}, a textual label is displayed to the left of the attribute

12379

in the graphical editor. This should be used to identify the

12380

attribute. However, it can be left to the empty string if the

12381

attribute is in a named section of its own, since the title of the

12382

section might be a good enough indication.

12383

12384

@item @code{description} (a string, default value: "")

12385

12386

This is the help message that describes the role of the attribute. It

12387

is displayed in a tooltip if the user leaves the mouse on top of the

12388

attribute for a while.

12389

12390

@item @code{list} (a boolean, default value: "false")

12391

12392

If this is set to @code{"true"}, the project attribute will in fact

12393

contains a list of values, as opposed to a single value. This is used

12394

for instance for the list of source directories in standard projects.

12395

12396

@item @code{ordered} (a boolean, default value: "false")

12397

12398

This is only relevant if the project attribute contains a list of

12399

values. This indicates whether the order of the values is relevant.

12400

In most cases, it will not matter. However, for instance, the order of

12401

source directories matters, since this also indicates where the source

12402

files will be searched, stopping at the first match.

12403

12404

@item @code{omit_if_default} (a boolean, default value: "true")

12405

12406

This indicates whether the project attribute should be set explicitly

12407

in the project if the user has left it to its default value. This can

12408

be used to keep the project files a simple as possible, if all the

12409

tools that will use this project attribute know about the default

12410

value. If this isn't the case, set @code{omit_if_default} to "false"

12411

to force the generation of the project attribute.

12412

12413

@item @code{base_name_only} (a boolean, default value: "false")

12414

12415

If the attribute contains a file name or a directory name, this

12416

indicates whether the full path should be stored, or only the base

12417

name. In most cases, the full path should be used. However, since GPS

12418

automatically looks for source files in the list of directories, for

12419

instance, the list of source files should only contain base

12420

names. This also increases the portability of project files.

12421

12422

@item @code{case_sensitive_index} (a boolean, default value: "false")

12423

12424

This XML attribute is only relevant for project attributes that are

12425

indexed on another one (see below for more information on indexed

12426

attributes). It indicates whether two indexes that differ only by

12427

their casing should be considered the same. For instance, if the index

12428

is the name of one of the languages supported by GPS, the index is

12429

case insensitive since "Ada" is the same as "C". However, if the index

12430

is the name of a file on Windows, the index is case-insensitive.

12431

12432

@item @code{hide_in} (a string, default value: "")

12433

12434

This XML attribute defines the various context in which this attribute

12435

should not be editable graphically. Currently, GPS provides two such

12436

contexts ("wizard" and "properties", corresponding to the project

12437

creation wizard and the project properties editor). If any of those

12438

context is specified in hide_in, then the widget to edit this

12439

attribute will not be shown. The goal is to keep the graphical

12440

interface simple.

12441

12442

@item @code{disable_if_not_set} (a boolean, default value: "false")

12443

12444

If this attribute is set to "true", the editor for this attribute will be

12445

greyed out if the attribute is not explicitly set in the project. In most cases,

12446

this is not needed, since the default value of the attribute can be used to leave

12447

the editor active at all time. However, when the value of the attribute is

12448

automatically computed depending on other attributes, the default value cannot be

12449

easily specified in the XML file, and in this case it might be easier to grey out

12450

the editor. An extra check box is displayed next to the attribute so that the user

12451

can choose to activate the editor and add the attribute to the project.

12452

12453

@item @code{disable} (a space-separated list of attribute names, default: "")

12454

12455

This is a list of attribute whose editor should be greyed out if the current

12456

attribute is specified. This only works if both the current attribute and the

12457

referenced attributes have their @code{disable_if_not_set} attribute set to "true".

12458

This can be used to have mutually exclusive attributes present in the editor

12459

12460

@end itemize

12461

12462

@subsubsection Declaring the type of the new attributes

12463

12464

The type of the project attribute is specified through one or several

12465

child tags of @code{<project_attribute>}. The following tags are

12466

recognized.

12467

12468

@itemize @bullet

12469

@cindex <string>

12470

@item @code{<string>}

12471

12472

This tag indicates that the attribute is made of one (or more if it is

12473

a list) strings. This

12474

tag accepts the following XML attributes:

12475

12476

@itemize -

12477

@item @code{default} (a string, default value: "")

12478

12479

This gives the default value to be used for the string (and therefore

12480

the project attribute), in case the user hasn't overridden it.

12481

12482

If the attribute's type is a file or a directory, the default value will be

12483

normalized (ie an absolute path will be generated from it, based on the

12484

project's location, where @code{"."} will represent the project's directory).

12485

As a special case, if default is surrounded by parenthesis, no normalization

12486

takes place, so that you can later on test whether the user is still using

12487

the default value or not).

12488

12489

A special case if when @code{default} is set to "project source files". In this

12490

case, this is automatically replaced by the known list of source files for the

12491

project. This doesn't work from the project wizard, since the list of source files

12492

hasn't been computed at that stage.

12493

12494

@item @code{type} (one of "", "file", "directory", default "")

12495

12496

This indicates what the string represents. In the first case, any

12497

value can be used. In the second case, it should represent a file

12498

name, although no check is done to make sure the file actually exists

12499

on the disk. But GPS will be able to do some special marshalling with

12500

the file name. The third case indicates that GPS should expect a

12501

directory.

12502

12503

@item @code{filter} (one of "none", "project", "extending_project")

12504

12505

This attribute is ignored for all types except @code{"file"}. In this case,

12506

it further specifies what kind of files can be used in this attribute. If

12507

the filter is @code{"none"}, then any file anywhere on the system is valid.

12508

If the filter is @code{"project"}, then only files from the selected project

12509

can be specified. If the filter is @code{"extended_project"}, then only the

12510

files from the project extended by the current project can be specified. The

12511

attribute will not be shown if the current project is not an extending project.

12512

12513

@item @code{allow_empty} (one of "True" or "False, default "True")

12514

12515

This attribute indicates whether the value for this attribute can be an

12516

empty string. If not, the user must specify a value or an error message will

12517

be displayed in the project properties editor and project wizard.

12518

12519

@end itemize

12520

12521

@cindex <choice>

12522

@item @code{<choice>}

12523

12524

This tag can be repeated several times. It indicates one of the valid

12525

values for the attribute, and can be used to provide a static list of

12526

such values. If it is combined with a @code{<string>} tag, this

12527

indicates that the attribute can be any string, although a set of

12528

possible values is provided to the user for ease of use.

12529

This tag accepts one optional attribute, @code{"default"}, which is a

12530

boolean. It indicates whether this value is the default to use for the

12531

project attribute.

12532

12533

If several @code{<choice>} tags are used, it is possible that several

12534

of them are part of the default value if the project attribute is a

12535

list, as opposed to a single value.

12536

12537

@cindex <shell>

12538

@item @code{<shell>}

12539

12540

This tag is a GPS scripting command to execute to get a list of valid

12541

values for the attribute. The command should return a list. As for the

12542

@code{<choice>} tag, the @code{<shell>} tag can be combined with a

12543

@code{<string>} tag to indicate that the list of values returned by

12544

the scripting command is only a set of possible values, but that the

12545

project attribute can in fact take any value.

12546

12547

The @code{<shell>} tag accepts two attributes:

12548

12549

@itemize -

12550

@item @code{lang} (a string, default value: "shell")

12551

12552

The scripting language in which the command is written. Currently, the

12553

only other possible value is "python".

12554

12555

@item @code{default} (a string, default value: "")

12556

12557

The default value that the project attribute takes if the user hasn't

12558

overridden it.

12559

@end itemize

12560

12561

@end itemize

12562

12563

@cindex indexed project attributes

12564

@cindex project attributes, indexed

12565

@cindex <index>

12566

@cindex <specialized_index>

12567

12568

In some cases, the type of the project attribute, or at least its

12569

default value, depends on what the attribute applies to. The project

12570

file support this in the form of indexed project attribute. This is

12571

for instance used to specify what should be the name of the executable

12572

generated when compiling each of the main files in the project (ie the

12573

executable name for @code{gps.adb} should be @code{gps.exe}, the one

12574

for @code{main.c} should be @code{myapp.exe}, and so on).

12575

12576

Such attributes can also be declared through XML files. In such cases,

12577

the @code{<project_attribute>} tag should have one @code{<index>}

12578

child, and zero or more @code{<specialized_index>} children.

12579

Each of these two tags in turn take one of the already mentioned

12580

@code{<string>}, @code{<choice>} or @code{<shell>} tag.

12581

12582

The @code{<index>} tag indicates what other project attribute is used

12583

to index the current one. In the example given above for the

12584

executable names, the index is the attribute that contains the list of

12585

main files for the project.

12586

12587

It accepts the following XML attributes:

12588

12589

@itemize @bullet

12590

@item @code{attribute} (a string, mandatory)

12591

12592

The name of the other attribute. This other attribute must be declared

12593

elsewhere in the customization files, and must be a list of values,

12594

not a single value.

12595

12596

@item @code{package} (a string, default value: "")

12597

12598

The package in which the index project attribute is defined. This is

12599

used to uniquely identify homonym attributes.

12600

@end itemize

12601

12602

The @code{<specialized_index>} is used to override the default type of

12603

the attribute for specific values of the index. For instance, the

12604

project files contains an attribute that specify what the name of the

12605

compiler is for each language. It is indexed on the project attribute

12606

that list the languages used for the source files of the project. Its

12607

default value depends on the language ("gnatmake" for Ada, "gcc" for

12608

C, and so on). This attribute accepts requires one XML attribute:

12609

12610

@itemize @bullet

12611

@item @code{value} (a string, mandatory)

12612

12613

This is the value of the attribute for which the type is overriden.

12614

@end itemize

12615

12616

Note that almost all the standard project attributes are defined

12617

through an XML file, @file{projects.xml}, which is part of the GPS

12618

installation. Check this file to get advanced examples on how to

12619

declare project attributes.

12620

12621

@subsubsection Examples

12622

12623

The following example declares three attributes, with a single string

12624

as their value. This string represents a file or a directory in the

12625

last two cases. You can simply copy this into a @file{.xml} file in

12626

your @file{$HOME/.gps/plug-ins} directory, as usual.

12627

12628

@smallexample

12629

<?xml version="1.0"?>

12630

12631

<project_attribute

12632

name="Single1"

12633

package="Test"

12634

editor_page="Tests single"

12635

editor_section="Single"

12636

description="Any string">

12637

12638

12639

</project_attribute>

12640

12641

<project_attribute

12642

name="File1"

12643

package="Test"

12644

editor_page="Tests single"

12645

editor_section="Single"

12646

description="Any file" >

12647

12648

12649

</project_attribute>

12650

12651

<project_attribute

12652

name="Directory1"

12653

package="Test"

12654

editor_page="Tests single"

12655

editor_section="Single"

12656

description="Any directory" >

12657

12658

12659

</project_attribute>

12660

</custom>

12661

@end smallexample

12662

12663

The following example declares an attribute whose value is a

12664

string. However, a list of predefined possible values is also

12665

provided, as an help for interactive edition for the user. If the

12666

@code{<string>} tag wasn't given, the attribute's value would have two

12667

be one of the three possible choices.

12668

12669

@smallexample

12670

<?xml version="1.0" ?>

12671

12672

<project_attribute

12673

name="Static2"

12674

package="Test"

12675

editor_page="Tests single"

12676

editor_section="Single"

12677

description="Choice from static list (or any string)" >

12678

12679

<choice>Choice1</choice>

12680

<choice default="true" >Choice2</choice>

12681

<choice>Choice3</choice>

12682

12683

</project_attribute>

12684

</custom>

12685

@end smallexample

12686

12687

The following example declares an attribute whose value is one of the

12688

languages currently supported by GPS. Since this list of languages is

12689

only know when GPS is executed, a script command is used to query this

12690

list.

12691

12692

@smallexample

12693

<?xml version="1.0" ?>

12694

12695

<project_attribute

12696

name="Dynamic1"

12697

package="Test"

12698

editor_page="Tests single"

12699

editor_section="Single"

12700

description="Choice from dynamic list" >

12701

12702

<shell default="C" >supported_languages</shell>

12703

</project_attribute>

12704

</custom>

12705

@end smallexample

12706

12707

The following example declares an attribute whose value is a set of

12708

file names. The order of files in this list matters to the tools that

12709

are using this project attribute.

12710

12711

@smallexample

12712

<?xml version="1.0" ?>

12713

12714

<project_attribute

12715

name="File_List1"

12716

package="Test"

12717

editor_page="Tests list"

12718

editor_section="Lists"

12719

list="true"

12720

ordered="true"

12721

description="List of any file" >

12722

12723

12724

</project_attribute>

12725

</custom>

12726

@end smallexample

12727

12728

The following example declares an attribute whose value is a set of

12729

predefined possible values. By default, two such values are selected,

12730

unless the user overrides this default setting.

12731

12732

@smallexample

12733

<?xml version="1.0" ?>

12734

12735

<project_attribute

12736

name="Static_List1"

12737

package="Test"

12738

editor_page="Tests list"

12739

editor_section="Lists"

12740

list="true"

12741

description="Any set of values from a static list" >

12742

12743

<choice>Choice1</choice>

12744

<choice default="true">Choice2</choice>

12745

<choice default="true">Choice3</choice>

12746

</project_attribute>

12747

</custom>

12748

@end smallexample

12749

12750

The following example declares an attribute whose value is a

12751

string. However, the value is specific to each language (this could

12752

for instance be used for the name of the compiler to use for a given

12753

language). This is an indexed project attribute. It has two default

12754

values, one for Ada, one for C. All other languages have no default

12755

value.

12756

12757

@smallexample

12758

<?xml version="1.0" ?>

12759

12760

<project_attribute

12761

name="Compiler_Name"

12762

package="Test"

12763

editor_page="Tests indexed"

12764

editor_section="Single"

12765

12766

12767

</index>

12768

<specialized_index value="Ada" >

12769

12770

</specialized_index>

12771

<specialized_index value="C" >

12772

12773

</specialized_index>

12774

</project_attribute>

12775

</custom>

12776

@end smallexample

12777

12778

@subsubsection Accessing the project attributes

12779

12780

The new attributes that were defined are accessible from the GPS

12781

scripting languages, like all the standard attributes, @pxref{Querying

12782

project switches}.

12783

12784

You can for instance access the Compiler_Name attribute we created

12785

above with a python command similar to:

12786

12787

@smallexample

12788

GPS.Project.root().get_attribute_as_string ("Compiler_Name", "Test", "Ada")

12789

@end smallexample

12790

12791

You can also access the list of main files for the project, for

12792

instance, by calling

12793

12794

@smallexample

12795

GPS.Project.root().get_attribute_as_list ("main")

12796

@end smallexample

12797

12798

@c --------------------------------------------------------------------------

12799

@node Adding casing exceptions

12800

@subsection Adding casing exceptions

12801

@cindex case_exceptions

12802

@cindex <case_exceptions>

12803

@c --------------------------------------------------------------------------

12804

12805

@noindent

12806

A set of case exceptions can be declared in this file. Each case

12807

exception is put inside the tag @code{<word>} or @code{<substring>}. These

12808

exceptions are used by GPS to set identifiers or keywords case when

12809

editing case insensitive languages (except if corresponding case is

12810

set to Unchanged). @pxref{The Preferences Dialog}.

12811

12812

@smallexample

12813

<?xml version="1.0" ?>

12814

12815

<case_exceptions>

12816

12817

12818

12819

</case_exceptions>

12820

</exceptions>

12821

@end smallexample

12822

12823

@c --------------------------------------------------------------------------

12824

@node Adding documentation

12825

@subsection Adding documentation

12826

@cindex <documentation_file>

12827

@c --------------------------------------------------------------------------

12828

12829

@noindent

12830

New documentation can be added in GPS in various ways. This is useful if you

12831

want to point to your own project documentation for instance.

12832

12833

The first possibility is to create a new menu, through a @code{<menu>} tag

12834

in an XML file, associated with an action that either spawn an external

12835

web browser or calls the internal @code{GPS.Help.browse()} shell command.

12836

12837

However, this will not show the documentation in the @code{Help->Contents}

12838

menu, which you also might want to do.

12839

12840

To have both results, you should use the @code{<documentation_file>} tag

12841

in an XML file. These tags are generally found in the @file{gps_index.xml}

12842

files, as documented in @pxref{Adding New Help Files}, but you can in fact

12843

add them in any of your customization files.

12844

12845

The documentation files you display can contain the usual type of html links.

12846

In addition, GPS will treat specially links starting with '%', and consider

12847

them as script commands to execute instead of file to display. The following

12848

example show how to insert a link that will in effect open a file in GPS when

12849

clicked by the user

12850

12851

@smallexample

12852

<a href="%shell:Editor.editor g-os_lib.ads">Open runtime file</a>

12853

@end smallexample

12854

12855

The first word after '%' is the name of the language, and the command to

12856

execute is found after the ':' character.

12857

12858

The @code{<documentation_file>} accepts a number of child nodes:

12859

12860

@table @b

12861

@item name

12862

This is the name of the file. It can be either an absolute file name,

12863

or a file name relative to one of the directories in @code{GPS_DOC_PATH}.

12864

If this child is omitted, you must specify a @code{<shell>} child.

12865

12866

This name can contain a reference to a specific anchor in the html

12867

file, using the standard HTML syntax.

12868

12869

@smallexample

12870

<name>file#anchor</name>

12871

@end smallexample

12872

12873

@item shell

12874

This child specifies the name of a shell command to execute to get the

12875

name of the HTML file. This command can for instance create the HTML file

12876

dynamically, or download it locally using some special mechanism.

12877

This child accepts one attribute, @code{"lang"}, which is the name of the

12878

language in which the command is written

12879

12880

@item descr

12881

This is the description for this help file. It appears in a tool tip

12882

for the menu item.

12883

12884

@item category

12885

This is used in the @code{Help->Contents} menu to organize all the

12886

documentation files.

12887

12888

@item menu

12889

This is the full path to the menu. It behaves like a UNIX path, except

12890

it reference the various menus, starting from the menu bar itself. The

12891

first character of this path must be @code{"/"}. The last part of the

12892

path is the name of the new menu item. If not set, no menu is

12893

displayed for this file, although it will still appear in the

12894

@code{Help->Contents} menu

12895

12896

The @code{<menu>} child tag accepts two attributes.

12897

12898

@table @b

12899

@item before (optional, default="")

12900

12901

The name of the menu before which the new entry should be inserted. If the

12902

new menu is inserted in some submenus, this tag controls the deeper nesting.

12903

Parent menus are created as needed, but if you wish to control their specific

12904

order, you should create them first with a @code{<menu>} tag.

12905

12906

@item after (optional, default="")

12907

12908

The name of the menu after which the new entry should be inserted.

12909

@end table

12910

12911

@end table

12912

12913

The following example shows how to create a new entry "item" in the Help

12914

menu, that will display @file{file.html}. The latter is searched in the

12915

@code{GPS_DOC_PATH} list of directories.

12916

12917

@smallexample

12918

<?xml version="1.0"?>

12919

<index>

12920

<documentation_file>

12921

12922

<descr>Tooltip text</descr>

12923

12924

12925

</documentation_file>

12926

</index>

12927

@end smallexample

12928

12929

@cindex <doc_path>

12930

As mentioned above, HTML files are looked for through the @code{GPS_DOC_PATH}

12931

environment variable. However, you can also use the @code{<doc_path>} XML

12932

node to defined additional directories to be searched.

12933

12934

Such a directory is relative to the installation directory of GPS.

12935

12936

@smallexample

12937

<?xml version="1.0"?>

12938

<GPS>

12939

<doc_path>doc/application/</doc_path>

12940

</GPS>

12941

@end smallexample

12942

12943

will add the directory @file{<prefix>/doc/application} to the search path

12944

for the documentation.

12945

12946

Such a directory can also be added through Python, as in:

12947

12948

@smallexample

12949

GPS.HTML.add_doc_directory ('doc/application')

12950

@end smallexample

12951

12952

@c --------------------------------------------------------------------------

12953

@node Adding stock icons

12954

@subsection Adding stock icons

12955

@cindex stock_icons

12956

@cindex <stock_icons>

12957

@c --------------------------------------------------------------------------

12958

12959

@noindent

12960

XML files can be used to define ``stock icons''. Stock icons are pictures

12961

that are identified by their label, and which are used through GPS in various

12962

places, such as buttons, menus, toolbars, and so on.

12963

12964

The stock icons must be declared using the tag @code{<icon>}, within the global

12965

tag @code{<stock>}. The attribute @code{id} indicates the label used to identify

12966

the stock icon, and the attribute @code{file} points to the file which contains

12967

the actual picture, either in absolute format, or relative to the directory

12968

which contains the XML file.

12969

12970

If the stock icon is to be used in a toolbar, use the attribute @code{label} to

12971

specify the text to display in the toolbar, under the button, when the toolbar

12972

is configured to show text.

12973

12974

For icons that are intended to be displayed at multiple sizes, you can specify

12975

multiple files corresponding to these multiple sizes. This is done by adding

12976

children to the main icon node, with the tag @code{alternate}, containing

12977

a @code{file} attribute and a @code{size} attribute which correspond to the

12978

size for which this alternate source should be used.

12979

12980

Possible sizes are:

12981

12982

@table @code

12983

@item 1

12984

Menu item (ideal size: 16x16 pixels)

12985

12986

@item 2

12987

Button in a small toolbar (ideal size: 18x18 pixels)

12988

12989

@item 3

12990

Button in a large toolbar (ideal size: 24x24 pixels)

12991

12992

@item 4

12993

Image for a standard button (ideal size: 20x20 pixels)

12994

12995

@item 5

12996

Image used during drag-and-drop operation (ideal size: 32x32 pixels)

12997

12998

@item 6

12999

Main image in a dialog (ideal size: 48x48 pixels)

13000

13001

@end table

13002

13003

Here is an example:

13004

@smallexample

13005

<?xml version="1.0"?>

13006

<my_visual_preferences>

13007

<stock>

13008

13009

13010

<icon id="myproject-multipurpose-image"

13011

label="do something"

13012

file="icons/icon_default.png">

13013

13014

13015

13016

</icon>

13017

13018

</stock>

13019

</my_visual_preferences>

13020

@end smallexample

13021

13022

Note: as shown in the example above, it is a good practice to prefix the label

13023

by a unique name (e.g. @code{myproject-}), in order to make sure that

13024

predefined stock icons will not get overridden by your icons.

13025

13026

@c ??? Not available with docgen2, this needs to be implemented.

13027

@c --------------------------------------------------------------------------

13028

@c @node Defining a documentation format

13029

@c @subsection Defining a Documentation format

13030

@c @cindex documentation

13031

@c @cindex HTML

13032

@c @cindex templates files

13033

@c --------------------------------------------------------------------------

13034

13035

@c GPS has support for textual (as opposed to binary format like PDF)

13036

@c documentation format. A textual documentation format can be described

13037

@c using external template files. This way, it is possible to add support

13038

@c for new textual documentation format by providing a set of templates files.

13039

@c

13040

@c The node name to define a new documentation format is @code{docgen_backend}.

13041

@c

13042

@c The attributes for this node are:

13043

@c

13044

@c @table @code

13045

@c @item name (string)

13046

@c The name of the documentation format (for example HTML).

13047

@c

13048

@c @item format (string)

13049

@c The format is either @b{text} or @b{binary}. Only @b{text} is

13050

@c supported at the moment.

13051

@c @end table

13052

@c

13053

@c There are two categories of children. One is to describe the format

13054

@c itself, the other is to specify the set of template to use. In the

13055

@c latter case the children's name are ending with @code{_template}:

13056

@c

13057

@c @table @code

13058

@c @item extension

13059

@c The extension to use for the generated files. This name is also used

13060

@c as part of the directory name under which the documentation is generated.

13061

@c

13062

@c @item description

13063

@c A description about the documentation format. GPS uses this description

13064

@c in the documentation selection dialog.

13065

@c

13066

@c @item file_header_template

13067

@c Point to a template file used as header for each generated files.

13068

@c

13069

@c @item file_footer_template

13070

@c Point to a template file used as footer for each generated files.

13071

@c

13072

@c @item comment_template

13073

@c Point to a template file used to output comment strings.

13074

@c

13075

@c @item keyword_template

13076

@c Point to a template file used to output keywords.

13077

@c

13078

@c @item string_template

13079

@c Point to a template file used to output strings.

13080

@c

13081

@c @item char_template

13082

@c Point to a template file used to output characters.

13083

@c

13084

@c @item subtitle_template

13085

@c Point to a template file used to output a subtitle give its name, size and

13086

@c indentation level.

13087

@c

13088

@c @item package_desc_template

13089

@c Point to a template file used to output package's description.

13090

@c

13091

@c @item package_template

13092

@c Point to a template file used to output the package declaration or

13093

@c ending.

13094

@c

13095

@c @item with_template

13096

@c Point to a template file used to output with clauses.

13097

@c

13098

@c @item variable_template

13099

@c Point to a template file used to output variables declarations.

13100

@c

13101

@c @item exception_template

13102

@c Point to a template file used to output exception declaration.

13103

@c

13104

@c @item type_template

13105

@c Point to a template file used to output type declarations.

13106

@c

13107

@c @item tagged_type_template

13108

@c Point to a template file used to output tagged types.

13109

@c

13110

@c @item calls_references_template

13111

@c Point to a template file used to output subprograms calls.

13112

@c

13113

@c @item caller_references_template

13114

@c Point to a template file used to output caller references.

13115

@c

13116

@c @item entity_template

13117

@c Point to a template file used to output entity.

13118

@c

13119

@c @item subprogram_template

13120

@c Point to a template file used to output subprograms.

13121

@c

13122

@c @item header_template

13123

@c Point to a template file used to output the start a package description.

13124

@c

13125

@c @item footer_template

13126

@c Point to a template file used to output the end of a package description.

13127

@c

13128

@c @item private_header_template

13129

@c Point to a template file used to output the start of package's private section.

13130

@c

13131

@c @item main_frame_template

13132

@c Point to a template file used to output the main file (the file

13133

@c @file{index.html} in the HTML backend for example).

13134

@c

13135

@c @item unit_index_header_template

13136

@c Point to a template file used to output the units index header.

13137

@c

13138

@c @item subprogram_index_header_template

13139

@c Point to a template file used to output the subprograms index header.

13140

@c

13141

@c @item type_index_header_template

13142

@c Point to a template file used to output the types index header.

13143

@c

13144

@c @item tagged_type_index_header_template

13145

@c Point to a template file used to output the tagged types index header.

13146

@c

13147

@c @item item_index_template

13148

@c Point to a template file used to output an item index.

13149

@c

13150

@c @item tagged_type_index_template

13151

@c Point to a template file used to output the tagged types index.

13152

@c

13153

@c @item private_index_header_template

13154

@c Point to a template file used to output the private types index header.

13155

@c

13156

@c @item public_index_header_template

13157

@c Point to a template file used to output the public types index header.

13158

@c

13159

@c @item index_footer_template

13160

@c Point to a template file used to output the end of indexes.

13161

@c

13162

@c @item block_template

13163

@c Point to a template file used to output block of text with a reference.

13164

@c

13165

@c @item link_template

13166

@c Point to a template file used to output all cross references.

13167

@c

13168

@c @item description_template

13169

@c Point to a template file used to output subprograms description based

13170

@c on comments found just below its spec.

13171

@c @end table

13172

@c

13173

@c All template files are given as relative path. GPS will first look for the

13174

@c template file under @code{share/gps/docgen} and if not found it looks

13175

@c under @code{$HOME/.gps/docgen}.

13176

@c

13177

@c A template file is a file that contains tags and commands. Those files

13178

@c are parsed by the @code{Templates Parser} module as found in

13179

@c @code{AWS}. We give hereafter a short description of this format, for

13180

@c a complete description see the Templates Parser User's Guide.

13181

@c

13182

@c @table @code

13183

@c @item simple tag

13184

@c A simple tag is surrounded by @code{@@_} and @code{_@@} like in

13185

@c @code{@@_NAME_@@}. The templates engine will replace @code{@@_NAME_@@}

13186

@c with the value associated with the tag named @code{NAME}.

13187

@c

13188

@c @item vector tag

13189

@c A vector tag contains a set of values. Each value will be used in

13190

@c sequence if the tag appears inside a @code{TABLE} command tag.

13191

@c

13192

@c For example, if the vector tag COLOR contains the three values Red,

13193

@c Green and Blue then:

13194

@c

13195

@c @smallexample

13196

@c @@@@TABLE@@@@

13197

@c > @@_COLOR_@@

13198

@c @@@@END_TABLE@@@@

13199

@c @end smallexample

13200

@c

13201

@c Will be expanded as:

13202

@c

13203

@c @smallexample

13204

@c > Red

13205

@c > Green

13206

@c > Blue

13207

@c @end smallexample

13208

@c

13209

@c @item filter

13210

@c

13211

@c Filters can be added to any tag. For example it is possible to output

13212

@c all values in upper case by applying the @code{UPPER} filter in the previous

13213

@c example.

13214

@c

13215

@c @smallexample

13216

@c @@@@TABLE@@@@

13217

@c > @@_UPPER:COLOR_@@

13218

@c @@@@END_TABLE@@@@

13219

@c @end smallexample

13220

@c

13221

@c Will be expanded as:

13222

@c

13223

@c @smallexample

13224

@c > RED

13225

@c > GREEN

13226

@c > BLUE

13227

@c @end smallexample

13228

@c

13229

@c It exists many filters, see the Template Parser User's Guide for a

13230

@c complete description.

13231

@c @end table

13232

@c

13233

@c Note that each HTML template files, provided with GPS, contains a

13234

@c complete description of the usage of each tag in the header comments.

13235

@c

13236

@c --------------------------------------------------------------------------

13237

@node Remote programming customization

13238

@subsection Remote programming customization

13239

@cindex remote

13240

@c --------------------------------------------------------------------------

13241

13242

@menu

13243

* Defining a remote connection tool::

13244

* Defining a shell::

13245

* Configuring rsync usage::

13246

* Defining a remote server::

13247

* Defining a remote path translation::

13248

@end menu

13249

13250

@noindent

13251

13252

The configuration of the remote programming functionality has two

13253

separate parts: the tools configuration (remote connection tools,

13254

shells, and rsync parameters) and the servers configuration.

13255

13256

The first part (see @ref{Defining a remote connection tool},

13257

@ref{Defining a shell} and @ref{Configuring rsync usage}) is handled

13258

by a pre-installed file in the plug-ins directory called

13259

@file{protocols.xml}.

13260

13261

The second part (see @ref{Defining a remote server} and @ref{Defining

13262

a remote path translation}), when configured via the user interface

13263

(see @ref{Setup the remote servers}), will create a remote.xml file in

13264

the user's gps directory. System-wide servers can be also installed.

13265

13266

@c --------------------------------------------------------------------

13267

@node Defining a remote connection tool

13268

@subsubsection Defining a remote connection tool

13269

@cindex remote

13270

@c --------------------------------------------------------------------

13271

13272

@noindent

13273

Several remote access tools are already defined in GPS: ssh, rsh,

13274

telnet and plink. It is possible to add other tools, using the node

13275

@code{remote_connection_config}.

13276

13277

The attributes for this node are:

13278

13279

@table @code

13280

@item name (string) (mandatory)

13281

The name of the tool. This name does not necessarilly correspond to

13282

the command used to launch the tool.

13283

13284

@end table

13285

13286

The following children are defined:

13287

13288

@table @code

13289

@item start_command (mandatory)

13290

The command used to launch the tool.

13291

This tag supports the @code{use_pipes} attribute. This attribute selects on

13292

Windows the way GPS will launch the remote tools, and can take the following

13293

values:

13294

@table @code

13295

@item true

13296

use pipes to launch the tool.

13297

@item false (default)

13298

use a tty emulation, which is a bit slower but allow

13299

password prompts retrieval with some tools.

13300

@end table

13301

Note that this argument has effects only on Windows platforms.

13302

13303

@item start_command_common_args (optional)

13304

The arguments that are provided to the tool. This string can contain the

13305

following replacement macros:

13306

@table @code

13307

@item %C

13308

is replaced by the command executed on the remote host (e.g. the shell command)

13309

@item %h

13310

is replaced by the remote host name

13311

@item %U

13312

is replaced by the start_command_user_args, if a user is specified

13313

@item %u

13314

is replaced by the user name

13315

@end table

13316

13317

Note that if neither %u nor %U is found, and a user is specified in the remote

13318

connection configuration, then the start_command_user_args is placed at the

13319

beginning of the arguments.

13320

13321

@item start_command_user_args (optional)

13322

The arguments used to define a specific user during connection. %u is replaced

13323

by the user name

13324

13325

@item send_interrupt (optional)

13326

The characters sequence to send to the remote tool to interrupt the remote

13327

application. If unset, then an Interrupt signal is sent directly to the remote

13328

tool.

13329

13330

@item user_prompt_ptrn (optional)

13331

A regular expression, used to catch user name prompts from the

13332

connection tool. If undefined, a default regular expression is used.

13333

13334

@item password_prompt_ptrn (optional)

13335

@cindex password

13336

A regular expression, used to catch password prompts from the

13337

connection tool. If undefined, a default regular expression is used.

13338

13339

@item passphrase_prompt_ptrn (optional)

13340

A regular expression, used to catch passphrase prompts from the

13341

connection tool. If undefined, a default regular expression is used.

13342

13343

@item use_cr_lf (optional)

13344

Boolean value, used to tell GPS if the connection tool requires CR+LF

13345

characters to determine an end of line, or if LF is sufficient. Set to

13346

false by default.

13347

13348

@item extra_ptrn (optional)

13349

Complex child. Used to catch extra prompts from the connection tool,

13350

other than password, passphrase or usename prompts. This tag has an

13351

attribute @code{auto_answer} telling if GPS automatically answers to

13352

this prompt, or ask the user. If auto_answer is @code{true}, then this

13353

tag needs an @code{answer} child, whose value is used for the answer. If

13354

auto_answer is @code{false}, then this tag needs a @code{question} child,

13355

whose value is used as question to the end user.

13356

13357

@c ??? need an example

13358

13359

@end table

13360

13361

@c --------------------------------------------------------------------

13362

@node Defining a shell

13363

@subsubsection Defining a shell

13364

@cindex remote

13365

@c --------------------------------------------------------------------

13366

13367

@noindent

13368

Several shells are already defined in GPS: sh, bash, csh, tcsh and

13369

cmd.exe (Windows). It is possible to add other shells, using the node

13370

@code{remote_shell_config}.

13371

13372

The attributes for this node are:

13373

13374

@table @code

13375

@item name (string) (mandatory)

13376

The name of the shell. This name does not necessarilly correspond to

13377

the command used to launch the shell.

13378

13379

@end table

13380

13381

The following children are defined:

13382

13383

@table @code

13384

@item start_command (mandatory)

13385

The command used to launch the shell. If arguments are required, they

13386

should be put here, separated with spaces.

13387

13388

@item generic_prompt (optional)

13389

The regular expression used to identify a prompt after the initial

13390

connection. If not set, a default value is used.

13391

13392

@item gps_prompt (mandatory)

13393

The regular expression used to identify a prompt after the initial

13394

setup is performed. If not set, a default value is used.

13395

13396

@item filesystem (mandatory)

13397

Takes the following values: @code{unix} or @code{windows}. This is the

13398

filesystem used by the shell.

13399

13400

@item init_commands (optional)

13401

Complex child. Each @code{cmd} child contains a command used to

13402

initialise a new session.

13403

13404

@item exit_commands (optional)

13405

Complex child. Each @code{cmd} child contains a command used to

13406

exit a session.

13407

13408

@item no_echo_command (optional)

13409

Command used to suppress the echo of the remote shell.

13410

13411

@item cd_command (mandatory)

13412

Command used to go to a directory. @code{%d} is replaced by the

13413

directory's full name.

13414

13415

@item get_status_command (mandatory)

13416

Command used to retrieve the status of the last command launched.

13417

13418

@item get_status_ptrn (mandatory)

13419

Regular expression used to retrieve the status returned by

13420

@code{get_status_command}. A pair of parenthesis is required, and

13421

identifies the status.

13422

13423

@end table

13424

13425

@c --------------------------------------------------------------------

13426

@node Configuring rsync usage

13427

@subsubsection Configuring rsync usage

13428

@cindex rsync

13429

@c --------------------------------------------------------------------

13430

13431

@noindent

13432

GPS has native support for the rsync tool, for paths synchronization

13433

during remote programming operations.

13434

13435

By default, GPS will use --rsh=ssh option if ssh is the main

13436

connection tool for the concerned server. It will also define the -L

13437

switch when transfering files to a Windows local host.

13438

13439

It is possible to define additional arguments to rsync using the

13440

@code{rsync_configuration} tag.

13441

13442

This tag accepts the child tagged @code{arguments}, and containing

13443

additional arguments to pass to rsync.

13444

13445

@c --------------------------------------------------------------------

13446

@node Defining a remote server

13447

@subsubsection Defining a remote server

13448

@cindex server

13449

@cindex remote

13450

@c --------------------------------------------------------------------

13451

13452

@noindent

13453

Remote servers can be defined via the user interface, as described in

13454

@ref{Setup the remote servers}. This user interface will create a

13455

remote.xml file in the user's gps directory, which in turn can be

13456

installed in any plug-ins directory to set the values

13457

system-wide. This file will define for each server the node

13458

@code{remote_machine_descriptor}.

13459

13460

The attributes for this node are:

13461

@table @code

13462

@item nickname (mandatory)

13463

Identifies uniquely the server in GPS.

13464

13465

@item network_name (mandatory)

13466

The server's network name or IP address.

13467

13468

@item remote_access (mandatory)

13469

The tool's name used to access the server. Shall point to one of the

13470

tools defined in @ref{Defining a remote connection tool}.

13471

13472

@item remote_shell (mandatory)

13473

The shell's name used to access the server. Shall point to one of the

13474

shells defined in @ref{Defining a shell}.

13475

13476

@item remote_sync (mandatory)

13477

The remote file synchronisation tool used to synchronize files between

13478

the local host and the server. Only @code{rsync} is recognized currently.

13479

13480

@item debug_console (optional)

13481

Can take the value @code{True} or @code{False}. Tells if a debug console

13482

should be displayed during connection with a remote host. False by default.

13483

@end table

13484

13485

The children for this node are:

13486

@table @code

13487

@item extra_init_commands (optional)

13488

Complex child. Can contain @code{cmd} children whose values are used

13489

to set server specific initialization commands.

13490

13491

@item max_nb_connections (optional)

13492

Positive number representing the maximum number of simultaneous

13493

connections GPS can launch.

13494

13495

@item timeout (optional)

13496

Positive number representing a timeout value (in ms) used for every

13497

action performed on the remote host.

13498

@end table

13499

13500

@c --------------------------------------------------------------------

13501

@node Defining a remote path translation

13502

@subsubsection Defining a remote path translation

13503

@cindex server

13504

@cindex path

13505

@cindex remote

13506

@c --------------------------------------------------------------------

13507

13508

@noindent

13509

Remote path translation can also be defined via the user interface, as

13510

described in @ref{Setup the remote servers}. The remote paths

13511

translation are defined with the node @code{remote_path_config}.

13512

13513

The attributes for this node are:

13514

@table @code

13515

@item server_name (mandatory)

13516

The server name concerned by the paths translation.

13517

@end table

13518

13519

The @code{remote_path_config} node contains @code{mirror_path}

13520

children.

13521

13522

The attributes for the node @code{mirror_path} are:

13523

@table @code

13524

@item local_path (mandatory)

13525

The absolute local path, expressed using the local filesystem

13526

standards.

13527

@item remote_path (mandatory)

13528

The absolute remote path, expressed using the remote filesystem

13529

standards.

13530

@item sync (mandatory)

13531

Specify the synchronization mechanism used for the paths

13532

(see @ref{Paths settings}). Possible values are

13533

@code{NEVER}, @code{ONCE_TO_LOCAL}, @code{ONCE_TO_REMOTE} and @code{ALWAYS}.

13534

@end table

13535

13536

@c --------------------------------------------------------------------------

13537

@node Adding support for new tools

13538

@section Adding support for new tools

13539

@cindex external tool

13540

@cindex <tool>

13541

@c --------------------------------------------------------------------------

13542

13543

@menu

13544

* Defining supported languages::

13545

* Defining default command line::

13546

* Defining tool switches::

13547

* Executing external tools::

13548

@end menu

13549

13550

@noindent

13551

GPS has built-in support for external tools. This feature can be used to

13552

support a wide variety of tools (in particular, to specify different

13553

compilers). Regular enhancements are done in this area, so if you are

13554

planning to use the external tool support in GPS, check for the latest GPS

13555

version available.

13556

13557

Typically, the following things need to be achieved to successfully use a

13558

tool:

13559

13560

@itemize @bullet

13561

@item Specify its command line switches

13562

@item Pass it the appropriate arguments depending on the current context, or

13563

on user input

13564

@item Spawn the tool

13565

@item Optionally parse its result and act accordingly

13566

@end itemize

13567

13568

Each of these points is discussed in further sections. In all these cases, most

13569

of the work can be done statically through XML customization files.

13570

These files have the same format as other XML customization files

13571

(@pxref{Customizing through XML and Python files}), and the tool descriptions are found in

13572

@code{<tool>} tags.

13573

13574

This tag accepts the following attributes:

13575

13576

@table @code

13577

@item name (mandatory)

13578

This is the name of the tool. This is purely descriptive, and will appear

13579

throughout the GPS interface whenever this tool is referenced. This includes

13580

for instances the tabs of the switches editor.

13581

13582

@item package (Default value is ide)

13583

This optional attribute specifies which package should be used in the project

13584

to store information about this tool, in particular its switches. Most of

13585

the time the default value should be used, unless you are working with one of

13586

the predefined packages.

13587

13588

See also @xref{Defining project attributes}, for more information on defining

13589

your own project attributes. Using the "package", "attribute" or "index"

13590

XML attributes of <tool> will implicitly create new project attributes as

13591

needed.

13592

13593

If this attribute is set to "ide", then the switches cannot be set for a

13594

specific file, only at the project level. Support for file-specific switches

13595

currently requires modification of the GPS sources themselves.

13596

13597

@item attribute (Default value is default_switches)

13598

This optional attribute specifies the name of the attribute in the project

13599

which is used to store the switches for that tool.

13600

13601

@item index (Default value is the tool name)

13602

This optional attribute specifies what index is used in the project. This is

13603

mostly for internal use by GPS, and describes what index of the project

13604

attribute is used to store the switches for that tool.

13605

13606

@item override (Default value is 'false')

13607

This optional attribute specifies whether the tool definition can be redefined.

13608

The accepted values are 'true' or 'false'. If override is not set, and the tool

13609

is defined several times, then a Warning will be displayed.

13610

13611

@end table

13612

13613

This tag accepts the following children, described in separate sections:

13614

13615

@table @code

13616

@item <switches>

13617

(@pxref{Defining tool switches})

13618

@item <language>

13619

(@pxref{Defining supported languages})

13620

@item <initial-cmd-line>

13621

(@pxref{Defining default command line})

13622

@end table

13623

13624

@c --------------------------------------------------------------------------

13625

@node Defining supported languages

13626

@subsection Defining supported languages

13627

@cindex <language>

13628

@c --------------------------------------------------------------------------

13629

13630

@noindent

13631

This is the language to which the tool applies. There can be from no to any

13632

number of such nodes for one @code{<tool>} tag.

13633

13634

If no language is specified, the tool applies to all languages. In particular,

13635

the switches editor page will be displayed for all languages, no matter what

13636

languages they support.

13637

13638

If at least one language is specified, the switches editor page will only be

13639

displayed if that language is supported by the project.

13640

13641

@smallexample

13642

<?xml version="1.0" ?>

13643

<my_tool>

13644

13645

13646

13647

</tool>

13648

</my_tool>

13649

@end smallexample

13650

13651

@c --------------------------------------------------------------------------

13652

@node Defining default command line

13653

@subsection Defining default command line

13654

@cindex <initial-cmd-line>

13655

@c --------------------------------------------------------------------------

13656

13657

@noindent

13658

It is possible to define the command line that should be used for a tool when

13659

the user is using the default project, or hasn't overridden this command line

13660

in the project.

13661

13662

This is done through the @code{<initial-cmd-line>} tag, as a child of the

13663

@code{<tool>} tag. Its value is the command line that would be passed to the

13664

tool. This command line is parsed as usual, e.g. quotes are taken into account

13665

to avoid splitting switches each time a space is encountered.

13666

13667

@smallexample

13668

<?xml version="1.0" ?>

13669

<my_tool>

13670

13671

<initial-cmd-line>-a -b -c</initial-cmd-line>

13672

</tool>

13673

</my_tool>

13674

@end smallexample

13675

13676

@c --------------------------------------------------------------------------

13677

@node Defining tool switches

13678

@subsection Defining tool switches

13679

@cindex <switches>

13680

@c --------------------------------------------------------------------------

13681

13682

@noindent

13683

The user has to be able to specify which switches to use with the tool.

13684

If the tool is simply called through custom menus, you might

13685

want to hard code some or all of the switches. However, in the general case

13686

it is better to use the project properties editor, so that project-specific

13687

switches can be specified.

13688

13689

This is what GPS does by default for Ada, C and C++. You can find in the GPS

13690

installation directory how the switches for these languages are defined in an

13691

XML file. These provide extended examples of the use of customization files.

13692

13693

The switches editor in the project properties editor provides a powerful

13694

interface to the command line, where the user can edit the command line both as

13695

text and through GUI widgets.

13696

13697

The switches are declared through the @code{<switches>} tag in the

13698

customization file, which must be a child of a @code{<tool>} tag as described

13699

above.

13700

13701

This @code{<switches>} tag accepts the following attributes:

13702

13703

@table @code

13704

@item lines (default value is 1)

13705

The switches in the project properties editor are organized into boxes,

13706

each surrounded by a frame, optionally with a title. This attribute specifies

13707

the number of rows of such frames.

13708

13709

@item columns (default value is 1)

13710

This attribute specifies the number of columns of frames in the project

13711

properties page.

13712

13713

@item separator (default value is "")

13714

This attribute specifies the default character that should go between a switch

13715

and its value, to distinguishes cases like "-a 1", "-a1" and "-a=1". This can

13716

be overridden separately for each switch. Note that if you want the separator

13717

to be a space, you must use the value @code{" "} rather than @code{" "},

13718

since XML parser must normalize the latter to the empty string when reading

13719

the XML file.

13720

13721

@item use_scrolled_window (Default value is false)

13722

This optional attribute specifies if the boxes of the project editor are placed

13723

into scrolled window. This is particularily useful if the number of displayed

13724

switches if important.

13725

13726

@item show_command_line (Default value is true)

13727

If this attribute is set to "false", the command line will not be displayed

13728

in the project properties editor. This can be used for instance if you only

13729

want users to edit it through the buttons and other widgets, and not directly.

13730

13731

@item switch_char (Default value is "-")

13732

This is the leading character of command line arguments that indicate they

13733

are considered as switches. Arguments not starting with this character will

13734

be kept as is, and cannot have graphical widgets associated with them

13735

13736

@item sections (Default value is empty)

13737

This is a space separated list of switches delimiting a section (such as

13738

"-bargs -cargs -largs"). A section of switches is a set of switches that

13739

need to be grouped together and preceded by a specific switch. Sections are

13740

always placed at the end of the command line, after regular switches.

13741

13742

@end table

13743

13744

This @code{<switches>} tag can have any number of child tag, among the

13745

following. They can be repeated multiple times if you need several check boxes.

13746

For consistency, most of these child tags accept attributes among the

13747

following:

13748

13749

@table @code

13750

@item line (default value is 1)

13751

This indicates the row of the frame that should contain the switch. See the

13752

description of @code{lines} above.

13753

13754

@item column (default value is 1)

13755

This indicates the column of the frame that should contain the switch. See the

13756

description of @code{columns} above.

13757

13758

@item label (mandatory)

13759

This is the label which is displayed in the graphical interface

13760

13761

@item switch (mandatory)

13762

This is the text that should be put on the command line if that switch is

13763

selected. Depending on its type, a variant of the text might be put instead,

13764

see the description of @code{combo} and @code{spin} below.

13765

This switch shouldn't contain any space.

13766

13767

@item switch-off (default value is empty)

13768

This attribute is used for @code{<check>} tags, and indicates the switch

13769

used for deactivating the concerned feature. This is useful for features that

13770

are on by default on certain occasions, but can be individually deactivated.

13771

13772

@item section (default value is empty)

13773

This is the switch section delimiter (such as "-cargs"). See the 'sections'

13774

attribute of the tag 'switches' for more information.

13775

13776

@item tip (default value is empty)

13777

This is the tooltip which describes that switch more extensively. It is

13778

displayed in a small popup window if the user leaves the mouse on top of

13779

the widget. Note that tags accepting the tip attribute also accept a single

13780

child @code{<tip>} whose value will contain the text to be displayed. The

13781

advantage of the latter is that the text formatting is then kept.

13782

13783

@item before (default value is "false")

13784

This attribute is used to indicate that a switch needs to be always inserted

13785

at the begining of the command line.

13786

13787

@item min (default value is 1)

13788

This attribute is used for @code{<spin>} tags, and indicates the minimum

13789

value authorized for that switch.

13790

13791

@item max (default value is 1)

13792

This attribute is used for @code{<spin>} tags, and indicates the maximum

13793

value authorized for that switch.

13794

13795

@item default (default value is 1)

13796

This attribute is used for @code{<check>} and @code{<spin>} tags. See the

13797

description below.

13798

13799

@item noswitch (default is empty)

13800

This attribute is only valid for @code{<combo>} tags, and described below.

13801

13802

@item nodigit (default is empty)

13803

This attribute is only valid for @code{<combo>} tags, and described below.

13804

13805

@item value (mandatory)

13806

This attribute is only valid for @code{<combo-entry>} tags.

13807

13808

@item separator (default is the value given to @code{<switches>}

13809

This attribute specifies the separator to use between the switch and its value.

13810

See the description of this attribute for @code{<switches>}.

13811

13812

@end table

13813

13814

Here are the valid children for @code{<switches>}:

13815

13816

@table @code

13817

@item <title>

13818

@cindex <title>

13819

This tag, which accepts the @code{line} and @code{column} attributes, is used

13820

to give a name to a specific frame.

13821

The value of the tag is the title itself. You do not have to specify

13822

a name, and this can be left to an empty value.

13823

13824

Extra attributes for @code{<title>} are:

13825

13826

@table @code

13827

@item line-span (default value is 1)

13828

This indicates how many rows the frame should span. If this is set to 0, then

13829

the frame is hidden from the user. See for instance the Ada or C switches

13830

editor.

13831

13832

@item column-span (default value is 1)

13833

This indicates how many columns the frame should span. If this is set to 0,

13834

then the frame is hidden from the user. See for instance the Ada or C

13835

switches editor.

13836

@end table

13837

13838

@item <check>

13839

@cindex <check>

13840

This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},

13841

@code{switch-off}, @code{section}, @code{default}, @code{before} and @code{tip}

13842

attributes.

13843

13844

This tag doesn't have any value. An optional @code{<tip>} child can be present.

13845

13846

It creates a toggle button. When the latter is active, the text defined in the

13847

switch attribute is added as is to the command line. The switch can be also

13848

activated by default (@code{default} attribute is "on" or "true"). In this

13849

case, deactivating the switch will add @code{switch-off} to the command line.

13850

13851

@item <spin>

13852

@cindex <spin>

13853

This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},

13854

@code{section}, @code{tip}, @code{min}, @code{max}, @code{separator} and

13855

@code{default} attributes.

13856

13857

This tag doesn't have any value. An optional @code{<tip>} child can be present.

13858

13859

This switch will add the contents of the @code{switch} attribute followed by

13860

the current numeric value of the widget to the command line. This is typically

13861

used to indicate indentation length for instance.

13862

If the current value of the widget is equal to the @code{default} attribute,

13863

then nothing is added to the command line.

13864

13865

@item <radio>

13866

@cindex <radio>

13867

@cindex <radio-entry>

13868

This tag accepts the @code{line} and @code{column} attributes. It groups any

13869

number of children, each of which is associated with its own switch. However,

13870

only one of the children can be selected at any given time.

13871

13872

The children must have the tag @code{radio-entry}. This tag accepts the

13873

attributes @code{label}, @code{switch}, @code{section}, @code{before} and

13874

@code{tip}. As a special case, the switch attribute can have an empty value

13875

("") to indicate this is the default switch to use in this group of radio

13876

buttons.

13877

13878

This tag doesn't have any value. An optional @code{<tip>} child can also be

13879

present.

13880

13881

@item <field>

13882

@cindex <field>

13883

This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},

13884

@code{section}, @code{separator}, @code{before} and @code{tip} attributes.

13885

13886

This tag doesn't have any value. An optional @code{<tip>} child can be present.

13887

13888

This tag describes a text edition field, which can

13889

contain any text the user types. This text will be prefixed by the value of

13890

the @code{switch} attribute, and the separator (by default nothing). If no text

13891

is entered in the field

13892

by the user, nothing is put on the command line.

13893

13894

This tag accepts two extra attributes:

13895

13896

@table @code

13897

@item as-directory (optional)

13898

@cindex as-directory

13899

If this attribute is specified and set to "true", then an extra "Browse"

13900

button is displayed, so that the user can easily select a directory.

13901

13902

@item as-file (optional)

13903

@cindex as-file

13904

This attribute is similar to @code{as-directory}, but opens a dialog to

13905

select a file instead of a directory. If both attributes are set to "true",

13906

the user will select a file.

13907

@end table

13908

13909

@item <combo>

13910

@cindex <combo>

13911

@cindex <combo-entry>

13912

This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},

13913

@code{section}, @code{before}, @code{tip}, @code{noswitch}, @code{separator}

13914

and @code{nodigit} attributes.

13915

13916

The tag @code{<combo>} accepts any number of @code{combo-entry} children tags,

13917

each of which accepts the @code{label} and @code{value} attribute. An optional

13918

@code{<tip>} child can also be present.

13919

13920

The text inserted in the command line is the text from the @code{switch}

13921

attribute, concatenated with the text of the @code{value} attribute for the

13922

currently selected entry. If the value of the current entry is the same

13923

as that of the @code{nodigit} attribute, then only the text of the

13924

@code{switch} attribute is put on the command line. This is in fact necessary

13925

to interpret the gcc switch "-O" as "-O1".

13926

13927

If the value of the current entry is that of the @code{noswitch} attribute,

13928

then nothing is put in the command line.

13929

13930

@item <popup>

13931

@cindex <popup>

13932

This tag accepts the @code{line}, @code{column}, @code{label}, @code{lines}

13933

and @code{columns} attributes. This displays a simply button that, when

13934

clicked, displays a dialog with some extra switches. This dialog, just as the

13935

switches editor itself, is organizes into lines and columns of frames, the

13936

number of which is provided by the @code{lines} and @code{columns} attributes.

13937

13938

This tag accepts any number of children, which are the same as the

13939

@code{<switches>} attribute itself.

13940

13941

@item <dependency>

13942

@cindex <dependency>

13943

This tag is used to describe a relationship between two switches. It is used

13944

for instance when the "Debug Information" switch is selected for "Make", which

13945

forces it for the Ada compiler as well.

13946

13947

It has its own set of attributes:

13948

13949

@table @code

13950

@item master-page master-switch master-section

13951

These two attributes define the switch that possibly forces a specific

13952

setting on the slave switch. In our example, they would have the values

13953

"Make" and "-g".

13954

The switch referenced by these attributes must be of type @code{<check>}

13955

or @code{<field>}. If it is part of a section, then 'master-section' needs

13956

to be defined. If the check button is selected, it forces the

13957

selection of the slave check button. Likewise, if the field is set to

13958

any value, it forces the selection of the slave.

13959

13960

@item slave-page slave-switch slave-section

13961

These two attributes define the switch which is acted upon by the master

13962

switch. In our example, they would have the values "Ada" and "-g".

13963

The switch referenced by these attributes must be of type @code{<check>}.

13964

13965

@item master-status slave-status

13966

These two switches indicate which state of the master switch forces which

13967

state of the slave-status. In our example, they would have the values

13968

"on" and "on", so that when the make debug information is activated, the

13969

compiler debug information is also activated. However, if the make debug

13970

information is not activated, no specific setup is forced for the compiler

13971

debug information.

13972

if master-status is "off" and the master switch is a field, then the

13973

status of the slave will be changed when no value is set in the field.

13974

@end table

13975

13976

@item <default-value-dependency>

13977

@cindex <default-value-dependency>

13978

This tag is used to describe a relationship between two switches. It is

13979

slightly different from the <dependency> tag in that the relationship concerns

13980

only the default activation states. It is used for instance when the "-gnatwa"

13981

switch is selected for the "Ada" Compiler, which imply that the default values

13982

for "-gnatwc", "-gnatwd", etc. become activated by default. They can however

13983

still be deactivated with respectively "-gnatwC" and "-gnatwD".

13984

13985

It has its own set of attributes:

13986

@table @code

13987

@item master-switch

13988

This is the switch that triggers the dependency. If @code{master-switch} is

13989

present in the command line, then the switch's default status of

13990

@code{slave-switch} is modified accordingly.

13991

13992

@item slave-switch

13993

This is the switch whose default value depends on @code{master-switch}. This

13994

needs to be a switch already defined in a @code{<switch>} tag. It can match

13995

its 'switch' or 'switch-off' attributes. In the latter case, the

13996

slave-switch default value is deactivated if master-switch is present.

13997

@end table

13998

13999

@item <expansion>

14000

@cindex <expansion>

14001

@cindex <entry>

14002

This tag is used to describe how switches can be grouped together on the

14003

command line to keep it shorter. It is also used to define aliases between

14004

switches.

14005

14006

It is easier to explain it through an example. Specifying the GNAT switch

14007

"-gnatyy" is equivalent to specifying "-gnaty3abcefhiklmnprst". This is in

14008

fact a style check switch, with a number of default values. But it is also

14009

equivalent to decomposing it into several switches, as in "-gnatya",

14010

"-gnatyb", @dots{}; With this information, GPS will try to keep the

14011

command line length as short as possible, to keep it readable.

14012

14013

Both these aspects are defined in a unique @code{<expansion>} tag, which

14014

accepts two attributes: @code{switch} is mandatory, and @code{alias} is

14015

optional. Alias contains the text "-gnatyabcefhiklmnprst" in our example.

14016

14017

There are two possible uses for this tag:

14018

@itemize -

14019

@item If the "alias" attribute is not specified, then the "switch" attribute

14020

indicates that all switches starting with that prefix should be grouped.

14021

For instance, if you pass "-gnatw" as the value for the "switch" attribute,

14022

then a command line with "-gnatwa -gnatw.b" will in fact result in "-gnatwa.b".

14023

14024

@item If the "alias" attribute is specified, then the "switch" attribute is

14025

considered as a shorter way of writting "alias". For instance, if "switch"

14026

is "-gnatyy" and "alias" is "-gnaty3abcefhiklmnprst", then the user can simply

14027

type "-gnatyy" to mean the whole set of options.

14028

@end itemize

14029

14030

The same "switch" attribute can be used in two expansion nodes if you want

14031

to combine the behavior.

14032

14033

For historical reasons, this tag accepts @code{<entry>} children, but these

14034

are no longer used.

14035

14036

@end table

14037

14038

@c --------------------------------------------------------------------------

14039

@node Executing external tools

14040

@subsection Executing external tools

14041

@c --------------------------------------------------------------------------

14042

14043

@menu

14044

* Chaining commands::

14045

* Saving open windows::

14046

* Querying project switches::

14047

* Querying switches interactively::

14048

* Redirecting the command output::

14049

* Processing the tool output::

14050

@end menu

14051

14052

@noindent

14053

The user has now specified the default switches he wants to use for the

14054

external tool. Spawning the external tool can be done either from a menu

14055

item, or as a result of a key press.

14056

14057

Both cases are described in an XML customization file, as described previously,

14058

and both are setup to execute what GPS calls an action, i.e. a set of commands

14059

defined by the @code{<action>} tag.

14060

14061

@c --------------------------------------------------------------------------

14062

@node Chaining commands

14063

@subsubsection Chaining commands

14064

@c --------------------------------------------------------------------------

14065

14066

This action tag, as described previously, executes one or more commands, which

14067

can either be internal GPS commands (written in any of the scripting language

14068

supported by GPS), or external commands provided by executables found on the

14069

PATH.

14070

14071

The command line for each of these commands can either be hard-coded in the

14072

customization file, or be the result of previous commands executed as part of

14073

the same action. As GPS executes each command from the action in turn, it

14074

saves its output on a stack as needed. If a command line contains a special

14075

construct @code{%1}, @code{%2}@dots{} then these constructs will be replaced

14076

by the result of respectively the last command executed, the previous from last

14077

command, and so on. They are replaced by the returned value of the command, not

14078

by any output it might have done to some of the consoles in GPS.

14079

14080

Every time you execute a new command, it pushes the previous %1, %2@dots{}

14081

parameters one step further on the stack, so that they become respectively %2,

14082

%3@dots{} and the output of that command becomes %1.

14083

14084

The result value of the previous commands is substituted exactly as is. However, if

14085

the output is surrounded by quotes, they are ignored when a substitution takes

14086

place, so you need to put them back if they are needed. The reason for this

14087

behavior is so that for scripting languages that systematically protect their

14088

output with quotes (simple or double), these quotes are sometimes in the

14089

way when calling external commands.

14090

14091

@smallexample

14092

<?xml version="1.0" ?>

14093

14094

14095

14096

<external> echo with quotes: "%1"</external>

14097

<external> echo without quotes: %2</external/>

14098

</action>

14099

</quotes>

14100

@end smallexample

14101

14102

If one of the commands in the action raises an error, the execution of the

14103

action is stopped immediately, and no further command is performed.

14104

14105

@c --------------------------------------------------------------------------

14106

@node Saving open windows

14107

@subsubsection Saving open windows

14108

@c --------------------------------------------------------------------------

14109

14110

@cindex MDI.save_all

14111

Before launching the external tool, you might want to force GPS to save all

14112

open files, the project@dots{}; This is done using the same command GPS itself

14113

uses before starting a compilation. This command is called @code{MDI.save_all},

14114

and takes one optional boolean argument which specifies whether an interactive

14115

dialog should be displayed for the user.

14116

14117

Since this command aborts when the user presses cancel, you can

14118

simply put it in its own @code{<shell>} command, as in:

14119

14120

@smallexample

14121

<?xml version="1.0" ?>

14122

<save_children>

14123

14124

14125

<external>echo Run unless Cancel was pressed</external>

14126

</action>

14127

</save_children>

14128

@end smallexample

14129

14130

@c --------------------------------------------------------------------------

14131

@node Querying project switches

14132

@subsubsection Querying project switches

14133

@cindex get_tool_switches_as_string

14134

@cindex get_tool_switches_as_list

14135

@cindex get_attribute_as_string

14136

@cindex get_attribute_as_list

14137

@c --------------------------------------------------------------------------

14138

14139

Some GPS shell commands can be used to query the default switches set by the

14140

user in the project file. These are @code{get_tool_switches_as_string},

14141

@code{get_tool_switches_as_list}, or, more generally,

14142

@code{get_attribute_as_string} and @code{get_attribute_as_list}. The first

14143

two require a unique parameter which is the name of the tool as specified in

14144

the @code{<tool>} tag. This name is case-sensitive. The last two commands are

14145

more general and can be used to query the status of any attribute from the

14146

project. See their description by typing the following in the GPS shell

14147

console window:

14148

14149

@smallexample

14150

help Project.get_attribute_as_string

14151

help Project.get_attribute_as_list

14152

@end smallexample

14153

14154

The following is a short example on how to query the switches for the tool

14155

"Find" from the project, @xref{Tool example}. It first creates an object

14156

representing the current project, then passes this object as the first

14157

argument of the @code{get_tool_switches_as_string} command. The last external

14158

command is a simple output of these switches

14159

14160

@smallexample

14161

<?xml version="1.0" ?>

14162

<find_switches>

14163

14164

<shell>Project %p</shell>

14165

<shell>Project.get_tool_switches_as_string %1 Find </shell>

14166

14167

</action>

14168

</find_switches>

14169

@end smallexample

14170

14171

The following example shows how something similar can be done from Python, in

14172

a simpler manner. For a change, this function queries the Ada compiler

14173

switches for the current project, and prints them out in the messages

14174

window. The

14175

14176

@smallexample

14177

<?xml version="1.0" ?>

14178

<query_switches>

14179

14180

<shell lang="python">GPS.Project("%p").get_attribute_as_list

14181

(package="compiler",

14182

attribute="default_switches",

14183

index="ada")</shell>

14184

<external>echo compiler switches= %1</external>

14185

</action>

14186

</query_switches>

14187

@end smallexample

14188

14189

@c --------------------------------------------------------------------------

14190

@node Querying switches interactively

14191

@subsubsection Querying switches interactively

14192

@cindex input_dialog

14193

@cindex yes_no_dialog

14194

@c --------------------------------------------------------------------------

14195

14196

Another solution to query the arguments for the tool is to ask the user

14197

interactively.

14198

The scripting languages provides a number of solutions for these.

14199

14200

They generally have their own native way to read input, possibly by creating

14201

a dialog.

14202

14203

In addition, the simplest solution is to use the predefined GPS commands for

14204

this. These are the two functions:

14205

14206

@table @code

14207

@item yes_no_dialog

14208

This function takes a single argument, which is a question to display. Two

14209

buttons are then available to the user, "Yes" and "No". The result of this

14210

function is the button the user has selected, as a boolean value.

14211

14212

@item input_dialog

14213

This function is more general. It takes a minimum of two arguments, with no

14214

upper limit. The first argument is a message describing what input is expected

14215

from the user. The second, third and following arguments each correspond to

14216

an entry line in the dialog, to query one specific value (as a string). The

14217

result of this function is a list of strings, each corresponding to these

14218

arguments.

14219

14220

From the GPS shell, it is only convenient to query one value at a time, since

14221

it doesn't have support for lists, and would return a concatenation of the

14222

values. However, this function is especially useful with other scripting

14223

languages.

14224

@end table

14225

14226

The following is a short example that queries the name of a directory and a

14227

file name, and displays each in the Messages window.

14228

14229

@smallexample

14230

<?xml version="1.0" ?>

14231

<query_file>

14232

14233

<shell lang="python">list=GPS.MDI.input_dialog \

14234

("Please enter directory and file name", "Directory", "File")</shell>

14235

<shell lang="python">print ("Dir=" + list[0], "File=" + list[1])</shell>

14236

</shell>

14237

</action>

14238

</query_file>

14239

@end smallexample

14240

14241

@c --------------------------------------------------------------------------

14242

@node Redirecting the command output

14243

@subsubsection Redirecting the command output

14244

@cindex output

14245

@c --------------------------------------------------------------------------

14246

14247

@noindent

14248

The output of external commands is send by default to the GPS console window.

14249

In addition, finer control can be exercised using the @code{output} attribute

14250

of the @code{<external>} and @code{<shell>} tags.

14251

14252

This attribute is a string that may take any value. Two values have specific

14253

meanings:

14254

14255

@table @code

14256

@item "none"

14257

The output of the command, as well as the text of the command itself, will not

14258

be shown to the user at all.

14259

14260

@item ""

14261

The output of the command is sent to the GPS console window, entitled

14262

"Messages".

14263

14264

@item other values

14265

A new window is created, with the title given by the attribute. If such

14266

a window already exists, it is cleared up before any of the command in the

14267

chain is executed. The output of the command, as well

14268

as the text of the command itself, are sent to this new window.

14269

@end table

14270

14271

This attribute can also be specified at the @code{<action>} tag level, in which

14272

case it defines the default value for all @code{<shell>} and @code{<external>}

14273

tags underneath. If it isn't specified for the action itself, its default value

14274

will always be the empty string, i.e. output is sent to the GPS console.

14275

14276

@smallexample

14277

<?xml version="1.0" ?>

14278

<ls>

14279

14280

14281

14282

</action>

14283

</ls>

14284

@end smallexample

14285

14286

@c --------------------------------------------------------------------------

14287

@node Processing the tool output

14288

@subsubsection Processing the tool output

14289

@c --------------------------------------------------------------------------

14290

14291

@noindent

14292

The output of the tool has now either been hidden or made visible to the user

14293

in one or more windows.

14294

14295

There are several additional things that can be done with this output, for

14296

further integration of the tool in GPS.

14297

14298

@enumerate

14299

@item Parsing error messages

14300

@cindex Locations.parse

14301

14302

External tools can usually display error messages for the user that

14303

are associated with specific files and locations in these files. This is for

14304

instance the way the GPS builder itself analyzes the output of @code{make}.

14305

14306

This can be done for your own tools using the shell command

14307

@code{Locations.parse}. This command takes several arguments, so that you

14308

can specify your own regular expression to find the file name, line number and

14309

so on in the error message. By default, it is configured to work

14310

seamlessly with error message of the forms:

14311

14312

@smallexample

14313

file:line: message

14314

file:line:column: message

14315

@end smallexample

14316

14317

Please refer to the online help for this command to get more information

14318

(by e.g. typing @code{help Locations.parse} in the GPS Shell).

14319

14320

Here is a small example on how to run a make command and send the errors to the

14321

location window afterward.

14322

14323

For languages that support it, it is also recommended that you quote the

14324

argument with triple quotes, so that any special character (newlines, quotes,

14325

@dots{}) in the output of the tool are not specially interpreted by GPS. Note

14326

also that you should leave a space at the end, in case the output itself ends

14327

with a quote.

14328

14329

@smallexample

14330

<?xml version="1.0" ?>

14331

<make>

14332

14333

14334

<on-failure>

14335

<shell>Locations.parse """%1 """ make_example</shell>

14336

</on-failure>

14337

</action>

14338

</make>

14339

@end smallexample

14340

14341

@item Auto-correcting errors

14342

@cindex Codefix.parse

14343

14344

GPS has support for automatically correcting errors for some of the languages.

14345

You can get access to this auto-fixing feature through the @code{Codefix.parse}

14346

shell command, which takes the same arguments as for @code{Locations.parse}.

14347

14348

This will automatically add pixmaps to the relevant entries in the location

14349

window, and therefore @code{Locations.parse} should be called first prior to

14350

calling this command.

14351

14352

Errors can also be fixed automatically by calling the methods of the

14353

@code{Codefix} class. Several codefix sessions can be active at the same time,

14354

each of which is associated with a specific category. The list of currently

14355

active sessions can be retrieved through the @code{Codefix.sessions()} command.

14356

14357

@cindex Codefix.errors

14358

@cindex CodefixError.fix

14359

@cindex CodefixError.possible_fixes

14360

If support for python is enabled, you can also manipulate the fixable errors

14361

for a given session.

14362

To do so, you must first get a handle on that section, as shown in the example

14363

below. You can then get the list of fixable errors through the @code{errors}

14364

command.

14365

14366

Each error is of the class @code{CodefixError}, which has one important

14367

method @code{fix} which allows you to perform an automatic fixing for that

14368

error. The list of possible fixes is retrieved through @code{possible_fixes}.

14369

14370

@smallexample

14371

print GPS.Codefix.sessions ()

14372

session = GPS.Codefix ("category")

14373

errors = session.errors ()

14374

print errors [0].possible_fixes ()

14375

errors [0].fix ()

14376

@end smallexample

14377

14378

@end enumerate

14379

14380

@c ----------------------------------------------------------------

14381

@node Customization examples

14382

@section Customization examples

14383

@c ----------------------------------------------------------------

14384

14385

@menu

14386

* Menu example::

14387

* Tool example::

14388

@end menu

14389

14390

@c ----------------------------------------------------------------

14391

@node Menu example

14392

@subsection Menu example

14393

@c ----------------------------------------------------------------

14394

14395

@noindent

14396

This section provides a full example of a customization file.

14397

It creates a top-level menu named @code{custom menu}.

14398

This menu contains a menu item named @code{item 1}, which is associated to the

14399

external command @code{external-command 1}, a sub menu named @code{other menu},

14400

etc@dots{}

14401

14402

@smallexample

14403

<?xml version="1.0"?>

14404

<menu-example>

14405

14406

<external>external-command 1</external>

14407

</action>

14408

14409

14410

14411

</action>

14412

14413

14414

<title>custom menu</title>

14415

14416

14417

</menu>

14418

14419

14420

<title>other menu</title>

14421

14422

14423

</menu>

14424

</submenu>

14425

</submenu>

14426

</menu-example>

14427

@end smallexample

14428

14429

@c ----------------------------------------------------------------

14430

@node Tool example

14431

@subsection Tool example

14432

@c ----------------------------------------------------------------

14433

14434

@noindent

14435

This section provides an example that defines a new tool. This is only a short

14436

example, since Ada, C and C++ support themselves are provided through such

14437

a file, available in the GPS installation.

14438

14439

This example adds support for the "find" Unix utility, with a few switches. All

14440

these switches are editable through the project properties editor.

14441

14442

It also adds a new action and menu. The action associated with this menu gets

14443

the default switches from the currently selected project, and then ask the

14444

user interactively for the name of the file to search.

14445

14446

@smallexample

14447

<?xml version="1.0" ?>

14448

14449

14450

14451

<title column="1" >Filters</title>

14452

<title column="2" >Actions</title>

14453

14454

<spin label="Modified less than n days ago" switch="-mtime-"

14455

min="0" max="365" default="0" />

14456

14457

14458

14459

</switches>

14460

</tool>

14461

14462

14463

<shell>Project %p</shell>

14464

<shell>Project.get_tool_switches_as_string %1 Find </shell>

14465

<shell>MDI.input_dialog "Name of file to search" Filename</shell>

14466

14467

</action>

14468

14469

14470

<Title>External</Title>

14471

14472

<Title>Launch find</Title>

14473

</menu>

14474

</Submenu>

14475

</toolexample>

14476

@end smallexample

14477

14478

@c --------------------------------------------------------------------

14479

@node Scripting GPS

14480

@section Scripting GPS

14481

@cindex scripts

14482

@c --------------------------------------------------------------------

14483

14484

@menu

14485

* Scripts::

14486

* Scripts and GPS actions::

14487

* The GPS Shell::

14488

* The Python Interpreter::

14489

* Subprogram parameters::

14490

* Python FAQ::

14491

* Hooks::

14492

@end menu

14493

14494

@c ---------------------------------------------------------------------

14495

@node Scripts

14496

@subsection Scripts

14497

@c ---------------------------------------------------------------------

14498

14499

@noindent

14500

Scripts are small programs that interact with GPS and allow you to

14501

perform complex tasks repetitively and easily. GPS includes support

14502

for two scripting languages currently, although additional languages

14503

might be added in the future. These two languages are described in the

14504

following section.

14505

14506

Support for scripting is currently work in progress in GPS. As a

14507

result, not many commands are currently exported by GPS, although

14508

their number is increasing daily. These commands are similar to what

14509

is available to people who extend GPS directly in Ada, but with a

14510

strong advantage: they do not require any recompilation of the GPS

14511

core, and can be tested and executed interactively.

14512

14513

The goal of such scripts is to be able to help automate processes such

14514

as builds, automatic generation of graphs, @dots{}

14515

14516

These languages all have a separate console associated with them,

14517

which you can open from the @code{Tools} menu. In each of these

14518

console, GPS will display a prompt, at which you can type interactive

14519

commands. These console provide completion of the command names

14520

through the @key{tab} key.

14521

14522

For instance, in the GPS shell console you can start typing

14523

@smallexample

14524

GPS> File

14525

@end smallexample

14526

14527

then press the @key{tab} key, which will list all the functions whose

14528

name starts with "File".

14529

14530

A similar feature is available in the python console, which also

14531

provides completion for all the standard python commands and modules.

14532

14533

All the scripting languages share the same set of commands exported by

14534

GPS, thanks to a abstract interface defined in the GPS core. As a

14535

result, GPS modules do not have to be modified when new scripting

14536

languages are added.

14537

14538

@cindex --load

14539

Scripts can be executed immediately upon startup of GPS by using the

14540

command line switch @code{--load}. Specifying the following command

14541

line:

14542

14543

@smallexample

14544

gps --load=shell:mytest.gps

14545

@end smallexample

14546

14547

will force the gps script @file{mytest.gps} to be executed

14548

immediately, before GPS starts reacting to user's requests. This is

14549

useful if you want to do some special initializations of the

14550

environment. It can also be used as a command line interface to GPS,

14551

if you script's last command is to exit GPS.

14552

14553

@cindex --eval

14554

In-line commands can also be given directly on the command line through

14555

@code{--eval} command line switch.

14556

14557

For instance, if you want to analyze an entity in the entity browser

14558

from the command line, you would pass the following command switches:

14559

14560

@smallexample

14561

gps --eval=shell:'Entity entity_name file_name; Entity.show %1'

14562

@end smallexample

14563

14564

See the section @ref{Customizing through XML and Python files} on how to bind key

14565

shortcuts to shell commands.

14566

14567

@c --------------------------------------------------------------------

14568

@node Scripts and GPS actions

14569

@subsection Scripts and GPS actions

14570

@cindex execute_action

14571

@c --------------------------------------------------------------------

14572

14573

@noindent

14574

There is a strong relationship between GPS actions, as defined in the

14575

customization files (@pxref{Defining Actions}), and scripting languages

14576

14577

Actions can be bound to menus and keys through the customization files or

14578

the @code{Edit->Key shortcuts} dialog.

14579

14580

These actions can execute any script command, @xref{Defining Actions}. This is

14581

done through the @code{<shell>} XML tag.

14582

14583

But the opposite is also true. From a script, you can execute any action

14584

registered in GPS. This can for instance be used to split windows, highlight

14585

lines in the editor, @dots{} when no equivalent shell function exists. This can

14586

also be used to execute external commands, if the scripting language doesn't

14587

support this in an easy manner.

14588

14589

Such calls are made through a call to @code{execute_action}, as in the

14590

following example:

14591

14592

@smallexample

14593

execute_action "Split horizontally"

14594

@end smallexample

14595

14596

@smallexample

14597

GPS.execute_action (action="Split horizontally")

14598

@end smallexample

14599

14600

The list of actions known to GPS can be found through the

14601

@code{Edit->Key shortcuts} dialog. Action names are case sensitive.

14602

14603

Some of the shell commands take subprograms as parameters. If you are using

14604

the GPS shell, this means you have to pass the name of a GPS action. If

14605

you are using Python, this means that you pass a subprogram,

14606

@xref{Subprogram parameters}.

14607

14608

@c ------------------------------------------------------------------------

14609

@node The GPS Shell

14610

@subsection The GPS Shell

14611

@cindex gps shell

14612

@c ------------------------------------------------------------------------

14613

14614

@noindent

14615

The GPS shell is a very simple-minded, line-oriented language. It is

14616

accessible through the @code{Shell} window at the bottom of the GPS

14617

window. It is similar to a Unix shell, or a command window on Windows

14618

systems.

14619

14620

Type @code{help} at the prompt to get the list of available commands,

14621

or @code{help} followed by the name of a command to get more

14622

information on that specific command.

14623

14624

The following example shows how to get some information on a source

14625

entity, and find all references to this entity in the application. It

14626

searches for the entity "entity_name", which has at least one

14627

reference anywhere in the file "file_name.adb". After the first

14628

command, GPS returns an identifier for this entity, which can be used

14629

for all commands that need an entity as a parameter, as is the case

14630

for the second command. When run, the second command will

14631

automatically display all matching references in the location window.

14632

14633

@smallexample

14634

GPS> Entity my_entity file_name.adb

14635

<Entity_0x09055790>

14636

GPS> Entity.find_all_refs <Entity_0x09055790>

14637

@end smallexample

14638

14639

Since the GPS shell is very simple, it doesn't provide any reference

14640

counting for the result types. As a result, all the values returned by

14641

a command, such as @code{<Entity_0x09055790>} in the example above,

14642

are kept in memory.

14643

14644

@cindex clear_cache command

14645

The GPS shell provides the command @code{clear_cache} which removes

14646

all such values from the memory. After this command is run, you can no

14647

longer use references obtained from previous commands, although of

14648

course you can run these commands again to get a new reference.

14649

14650

The return value of the 9 previous commands can easily be recalled by

14651

passing @code{%1}, @code{%2}, @dots{} on the command line. For instance,

14652

the previous example could be rewritten as

14653

14654

@smallexample

14655

GPS> Entity my_entity file_name.adb

14656

<Entity_0x09055790>

14657

GPS> Entity.find_all_refs %1

14658

@end smallexample

14659

14660

These return values will be modified also for internal commands sent

14661

by GPS, so you should really only use this when you emit multiple

14662

commands at the same time, and don't do any other action in GPS. This

14663

is mostly useful when used for command-line scripts (see @code{--eval}

14664

and @code{--load}), or for custom files, @xref{Customizing through XML and Python files}.

14665

14666

Arguments to commands can, but need not, be quoted. If they don't contain

14667

any space, double-quote ('"') or newline characters, you do not need to quote

14668

them. Otherwise, you should surround them with double-quotes, and protect

14669

any double-quote part of the argument by preceding it with a backslash.

14670

14671

There is another way to quote a command: use three double-quotes characters in

14672

a row. Any character loses its special meaning until the next three

14673

double-quotes characters set. This is useful if you do not know in advance

14674

the contents of the string you are quoting.

14675

14676

@smallexample

14677

Locations.parse """%1 """ category_name

14678

@end smallexample

14679

14680

@node The Python Interpreter

14681

@subsection The Python Interpreter

14682

@cindex python

14683

@c ------------------------------------------------------------------------

14684

14685

@noindent

14686

Python is an interpreted object-oriented language, created by Guido

14687

Van Rossum. It is similar in its capabilities to languages such as

14688

Perl, Tcl or Lisp. This section is not a tutorial on python

14689

programming. See @url{http://www.python.org/doc/current/} to access the

14690

documentation for the current version of python.

14691

14692

If python support has been enabled, the python shell is accessible through the

14693

@code{Python} window at the bottom of the GPS window. You can also

14694

display it by using the menu @file{Tools->Consoles->Python}.

14695

14696

The full documentation on what GPS makes visible through python is available

14697

through the @code{/Help/Python extensions}.

14698

14699

The same example that was used to show the GPS shell follows, now using

14700

python. As you can notice, the name of the commands is

14701

similar, although they are not run exactly in the same

14702

way. Specifically, GPS benefits from the object-oriented aspects of

14703

python to create classes and instances of these classes.

14704

14705

In the first line, a new instance of the class Entity is created

14706

through the @code{create_entity} function. Various methods can then be

14707

applied to that instance, including @code{find_all_refs}, which lists

14708

all references to that entity in the location window:

14709

14710

@smallexample

14711

>>> e=GPS.Entity ("entity_name", "file_name.adb")

14712

>>> e.find_all_refs()

14713

@end smallexample

14714

14715

The screen representation of the classes exported by GPS to python has

14716

been modified, so that most GPS functions will return an instance of a

14717

class, but still display their output in a user-readable manner.

14718

14719

Python has extensive introspection capabilities. Continuing the

14720

previous example, you can find what class @code{e} is an instance of

14721

with the following command:

14722

14723

@smallexample

14724

>>> help(e)

14725

Help on instance of Entity:

14726

14727

<GPS.Entity instance>

14728

@end smallexample

14729

14730

It is also possible to find all attributes and methods that can be

14731

applied to @code{e}, as in the following example:

14732

14733

@smallexample

14734

>>> dir (e)

14735

['__doc__', '__gps_data__', '__module__', 'called_by', 'calls',

14736

'find_all_refs']

14737

@end smallexample

14738

14739

Note that the list of methods may vary depending on what modules were

14740

loaded in GPS, since each module can add its own methods to any class.

14741

14742

In addition, the list of all existing modules and objects currently known

14743

in the interpreter can be found with the following command:

14744

14745

@smallexample

14746

>>> dir ()

14747

['GPS', 'GPSStdout', '__builtins__', '__doc__', '__name__', 'e', 'sys']

14748

@end smallexample

14749

14750

You can also load and execute python scripts with the @code{execfile} command,

14751

as in the following example:

14752

14753

@smallexample

14754

>>> execfile ("test.py")

14755

@end smallexample

14756

14757

Python supports named parameters. Most functions exported by GPS define

14758

names for their parameters, so that you can use this Python feature, and

14759

make your scripts more readable. A notable exception to this rule are the

14760

functions that take a variable number of parameters.

14761

Using named parameters allows you to specify the parameters in any order

14762

you wish, e.g:

14763

14764

@smallexample

14765

>>> e=GPS.Entity (name="foo", file="file.adb")

14766

@end smallexample

14767

14768

@subsection Python modules

14769

14770

On startup, GPS will automatically import (with python's @code{import}

14771

command) all the files with the extension @file{.py} found in the directory

14772

@file{$HOME/.gps/plug-ins}, the directory @file{$prefix/share/gps/plug-ins}

14773

or in the directories pointed to by

14774

@file{GPS_CUSTOM_PATH}. These files are loaded only after all standard

14775

GPS modules have been loaded, as well as the custom files, and before

14776

the script file or batch commands specified on the command lines with

14777

the @code{--eval} or @code{--load} switches.

14778

14779

As a result, one can use the usual GPS functions exported to python in these

14780

startup scripts. Likewise, the script run from the command line can use

14781

functions defined in the startup files.

14782

14783

Since the @code{import} command is used, the functions defined in this

14784

modules will only be accessible by prefixing their name by the name of the

14785

file in which they are defined. For instance if a file @file{mystartup.py}

14786

is copied to the startup directory, and defines the function @code{func},

14787

then the latter will be accessible in GPS through @code{mystartup.func}.

14788

14789

Python's own mechanism for loading files at startup (the environment

14790

variable @code{PYTHONSTARTUP}) is not suitable for use within the context

14791

of GPS. When python is loaded by GPS, the GPS module itself is not yet

14792

available, and thus any script that depends on that module will fail to

14793

load correctly. Instead, copy your script to one of the plug-ins directories,

14794

as documented above.

14795

14796

If you are writing a set of python scripts that other people will use,

14797

you need to provide several things:

14798

14799

@itemize

14800

@item The python files themselves. This is a set of @file{.py} files, which

14801

the user should install in the @file{plug-ins} directory.

14802

14803

@item Optionally: an XML file with the format described in the customization section

14804

of this documentation. This XML file should create a set of actions,

14805

through the @code{<action>} tag, exported to the user. This allows him

14806

to either create menus to execute these commands or to bind them to special

14807

key shortcuts. The menus can be created directly in python, with the

14808

@code{GPS.Menu} class. The same XML can in fact be directly embedded in the

14809

python file itself and executed through @code{GPS.parse_xml}.

14810

@end itemize

14811

14812

The following example defines a python command that inserts a line full of

14813

dashes ('-') at the current cursor location. This command is associated with

14814

the key binding @key{control-c n}, and can be distributed as a single XML

14815

file.

14816

14817

@smallexample

14818

# This code can be stored in a file test.py in $HOME/.gps/plug-ins

14819

from GPS import *

14820

14821

def add_dashes_line():

14822

Editor.replace_text (current_context().file().name(),

14823

current_context().location().line(),

14824

current_context().location().column(),

14825

"--------------------------------", 0, 0)

14826

GPS.parse_xml ("""

14827

14828

<shell lang="python">test.add_dashes_line()</shell>

14829

<context>Source editor</context>

14830

</action>

14831

<key action="dashes line">control-c n</key>

14832

""")

14833

14834

@end smallexample

14835

14836

Several complex examples are provided in the GPS distribution, in the

14837

directory @file{examples/python}. These are modules that you might want

14838

to use for your own GPS, but more important that will show how GPS can

14839

be extended from Python.

14840

14841

If your script doesn't do what you expect it to do, there are several

14842

ways to debug it, among which the easiest is probably to add some "print"

14843

statements. Since some output of the scripts is sometimes hidden by GPS

14844

(for instance for interactive commands), you might not see this output.

14845

14846

In this case, you can reuse the tracing facility embedded in GPS itself.

14847

Modify the file @file{$HOME/.gps/traces.cfg}, and add the following line:

14848

14849

@smallexample

14850

PYTHON.OUT=yes

14851

@end smallexample

14852

14853

This will include the python traces as part of the general traces available

14854

in the file @file{$HOME/.gps/log}. Note that it may slow down GPS if there is

14855

a lot of output to process.

14856

14857

@c --------------------------------------------------------------------

14858

@node Subprogram parameters

14859

@subsection Subprogram parameters

14860

@cindex subprogram parameters

14861

@c --------------------------------------------------------------------

14862

14863

@noindent

14864

A few of the functions exported by GPS in the GPS shell or in python expect

14865

a subprogram as a parameter.

14866

14867

This is handled in different ways depending on what language your are using:

14868

14869

@itemize @bullet

14870

@item GPS shell

14871

14872

It isn't possible to define new functions in the GPS shell. However, this

14873

concept is similar to the GPS actions (@pxref{Defining Actions}), which

14874

allow you to execute a set of commands and launch external processes.

14875

14876

Therefore, a subprogram parameter in the GPS shell is a string, which is the

14877

name of the action to execute.

14878

14879

For instance, the following code defines the action "on_edition",

14880

which is called every time a new file is edited. The action is defined

14881

in the shell itself, although this could be more conveniently done in

14882

a separate customization file.

14883

14884

@smallexample

14885

parse_xml """<action name="on_edition">

14886

<shell>echo "File edited"</shell></action>"""

14887

Hook "file_edited"

14888

Hook.add %1 "on_edition"

14889

@end smallexample

14890

14891

@item Python

14892

14893

Python of course has its own notion of subprogram, and GPS is fully compatible

14894

with it. As a result, the syntax is much more natural than in the GPS shell.

14895

The following example has the same result as above:

14896

14897

@smallexample

14898

import GPS

14899

def on_edition(self, *arg):

14900

print "File edited"

14901

GPS.Hook ("file_edited").add (on_edition)

14902

@end smallexample

14903

14904

Things are in fact slightly more complex if you want to pass methods

14905

as arguments. Python has basically three notions of callable

14906

subprograms, detailed below. The following examples all create a combo

14907

box in the toolbar, which calls a subprogram whenever its value is

14908

changed. The documentation for the combo box indicates that the

14909

callback in this case takes two parameters:

14910

14911

@itemize -

14912

@item The instance of the combo

14913

@item The current selection in the combo box

14914

@end itemize

14915

14916

The first parameter is the instance of the combo box associated with

14917

the toolbar widget, and, as always in python, you can store your own

14918

data in the instance, as shown in the examples below.

14919

14920

Here is the description of the various subprograms:

14921

14922

@itemize @bullet

14923

@item Global subprograms

14924

14925

These are standard subprograms, found outside class definitions. There

14926

is no implicit parameter in this case. However, if you need to pass

14927

data to such a subprogram, you need to use global variables

14928

14929

@smallexample

14930

import GPS

14931

14932

my_var = "global data"

14933

14934

def on_changed (combo, choice):

14935

global my_var

14936

print "on_changed called: " + \

14937

my_var + " " + combo.data + " " + choice

14938

14939

combo = GPS.Combo \

14940

("name", label="name", on_changed=on_changed)

14941

GPS.Toolbar().append (combo)

14942

combo.data = "My own data"

14943

@end smallexample

14944

14945

@item Unbound methods

14946

14947

These are methods of a class. You do not specify, when you pass the

14948

method in parameter to the combo box, what instance should be passed

14949

as its first parameter. Therefore, there is no extra parameter either.

14950

14951

Note however than whatever class the method is defined in, the first

14952

parameter is always an instance of the class documented in the GPS

14953

documentation (in this case a GPS.Combo instance), not an

14954

instance of the current class.

14955

14956

In this first example, since we do not have access to the instance of

14957

MyClass, we also need to store the global data as a class

14958

component. This is a problem if multiple instances of the class can

14959

be created.

14960

14961

@smallexample

14962

import GPS

14963

class MyClass:

14964

my_var = "global data"

14965

def __init__ (self):

14966

self.combo = GPS.Combo \

14967

("name", label="name", on_changed=MyClass.on_changed)

14968

GPS.Toolbar().append (self.combo)

14969

self.combo.data = "My own data"

14970

14971

def on_changed (combo, choice):

14972

## No direct access to the instance of MyClass.

14973

print "on_changed called: " + \

14974

MyClass.my_var + " " + combo.data + " " + choice

14975

14976

MyClass()

14977

@end smallexample

14978

14979

As the example above explains, there is no direct access to MyClass

14980

when executing on_changed. An easy workaround is the following, in

14981

which the global data can be stored in the instance of MyClass,

14982

and thus be different for each instance of MyClass.

14983

14984

@smallexample

14985

import GPS

14986

class MyClass:

14987

def __init__ (self):

14988

self.combo = GPS.Combo \

14989

("name", label="name", on_changed=MyClass.on_changed)

14990

GPS.Toolbar().append (self.combo)

14991

self.combo.data = "My own data"

14992

self.combo.myclass = self ## Save the instance

14993

self.my_var = "global data"

14994

14995

def on_changed (combo, choice):

14996

print "on_changed called: " + \

14997

combo.myclass.my_var + " " + combo.data + " " + choice

14998

14999

MyClass()

15000

@end smallexample

15001

15002

@item Bound methods

15003

15004

The last example works as expected, but is not convenient to use. The

15005

solution here is to use a bound method, which is a method for a

15006

specific instance of a class. Such a method always has an extra first

15007

parameter, set implicitly by Python or GPS, which is the instance of

15008

the class the method is defined in.

15009

15010

Notice the way we pass the method in parameter to append(), and the

15011

extra third argument to on_changed in the example below.

15012

15013

@smallexample

15014

import GPS

15015

class MyClass:

15016

def __init__ (self):

15017

self.combo = GPS.Combo \

15018

("name", label="name", on_changed=self.on_changed)

15019

GPS.Toolbar().append (self.combo)

15020

self.combo.data = "My own data"

15021

self.my_var = "global data"

15022

15023

def on_changed (self, combo, choice):

15024

# self is the instance of MyClass specified in call to append()

15025

print "on_changed called: " + \

15026

self.my_var + " " + combo.data + " " + choice

15027

15028

MyClass()

15029

@end smallexample

15030

15031

It is often convenient to use the object-oriented approach when writing

15032

python scripts. If for instance you want to spawn an external process,

15033

GPS provides the @code{GPS.Process} class. When you create an instance,

15034

you specify a callback to be called when some input is made available

15035

by the process. Matching the above example, the code would look something

15036

like:

15037

15038

@smallexample

15039

class MyClass:

15040

def __init__ (self):

15041

self.process = GPS.Process

15042

("command_line", on_match = self.on_match)

15043

15044

def on_match (self, process, matched, unmatched);

15045

print "Process output: " + unmatched + matched + "\n"

15046

@end smallexample

15047

15048

A more natural approach, rather than having a class that has a process

15049

field, is to directly extend the @code{GPS.Process} class, as in:

15050

15051

@smallexample

15052

class MyClass (GPS.Process):

15053

def __init__ (self):

15054

GPS.Process.__init__ \

15055

(self, "command_line", on_match = self.on_match)

15056

15057

def on_match (self, matched, unmatched);

15058

print "Process output: " + unmatched + matched + "\n"

15059

@end smallexample

15060

15061

Any command that can be used on a process (such as @code{send}) can then

15062

directly be used on instances of MyClass.

15063

15064

There is one non-obvious improvement in the code above: the @code{on_match}

15065

callback has one less parameter. What happens is the following: as per

15066

the documentation of @code{GPS.Process.__init__}, GPS gives three arguments

15067

to its @code{on_match} callback: the instance of the process (@code{process}

15068

in the first example above), the string that matched the regular expression,

15069

and the string before that match.

15070

15071

In the first example above, we are passing @code{self.on_match}, ie a

15072

bound method, as a callback. That tells python that it should automatically,

15073

and transparently, add an extra first parameter when calling

15074

@code{MyClass.on_match}, which is @code{self}. This is why the first example

15075

has four parameters to @code{on_match}.

15076

15077

However, the second example only has three parameters, because GPS has

15078

detected that @code{self} (the instance of @code{MyClass}) and the

15079

instance of @code{GPS.Process} are the same in this case. Thus it doesn't

15080

add an extra parameter (@code{self} and @code{process} would have been

15081

the same).

15082

15083

@end itemize

15084

15085

@end itemize

15086

15087

@c ------------------------------------------------------------------------

15088

@node Python FAQ

15089

@subsection Python FAQ

15090

@cindex python

15091

@c ------------------------------------------------------------------------

15092

15093

@noindent

15094

This section lists some of the problems that have been encountered while using

15095

Python inside GPS. This is not a general Python discussion.

15096

15097

@menu

15098

* Hello World! in python::

15099

* Spawning external processes::

15100

* Redirecting the output of spawned processes::

15101

* Contextual menus on object directories only::

15102

* Redirecting the output to specific windows::

15103

* Reloading a python file in GPS::

15104

* Printing the GPS Python documentation::

15105

* Automatically loading python files at startup::

15106

* Hiding contextual menus::

15107

* Creating custom graphical interfaces::

15108

@end menu

15109

15110

@c -------------------------------------------

15111

@node Hello World! in python

15112

@subsubsection Hello World! in python

15113

15114

Writing a python script to interact with GPS is very simple. Here we show

15115

how to create a new menu in GPS that when clicked, diplays a dialog saying

15116

the famous ``Hello World!''.

15117

15118

Here is the code that you need to put in hello_world.py:

15119

15120

@smallexample

15121

import GPS

15122

15123

def hello_world (self):

15124

GPS.MDI.dialog ("Hello World!")

15125

15126

GPS.Menu.create ("/Help/Hello World!", on_activate=hello_world)

15127

@end smallexample

15128

15129

In order to use this plug-in, you can launch GPS with the following command

15130

line:

15131

15132

@smallexample

15133

$ gps --load=python:hello_world.py

15134

@end smallexample

15135

15136

If would want the plug-in to be loaded everytime you launch GPS without having

15137

to specify it on the command line, you should copy hello_world.py to your

15138

@code{$HOME/.gps/plug-ins/} directory or @code{%USERPROFILE%\.gps\} under

15139

Windows.

15140

15141

Alternatively, you can add the directory in which you plug-in is located to

15142

you @code{GPS_CUSTOM_PATH} environment variable.

15143

For a description of the various environment variables used by GPS,

15144

@pxref{Environment Variables}.

15145

15146

@c -------------------------------------------

15147

@node Spawning external processes

15148

@subsubsection Spawning external processes

15149

15150

There exist various solutions to spawn external processes from a script:

15151

15152

@itemize

15153

@item Use the functionalities provided by the @code{GPS.Process} class

15154

@item Execute a GPS action through @code{GPS.execute_action}.

15155

15156

This action should have an @code{<external>} XML node indicating how to

15157

launch the process

15158

15159

@item Create a pipe and execute the process with @code{os.popen()} calls

15160

15161

This solution doesn't provide a full interaction with the process, though.

15162

15163

@item Use a standard expect library of Python

15164

15165

The use of an expect library may be a good solution. There are various python

15166

expect libraries that already exist.

15167

15168

These libraries generally try to copy the parameters of the standard @code{file}

15169

class. They may fail doing so, as GPS's consoles do not fully emulate all

15170

the primitive functions of that class (there is no file descriptor for

15171

instance).

15172

15173

When possible, it is recommended to use one of the methods above instead.

15174

@end itemize

15175

15176

@c -------------------------------------------

15177

@node Redirecting the output of spawned processes

15178

@subsubsection Redirecting the output of spawned processes

15179

15180

In general, it is possible to redirect the output of any Python script to

15181

any GPS window (either an already existing one, or creating one automatically),

15182

through the @code{"output"} attribute of XML configuration files.

15183

15184

However, there is a limitation in python that the output of processes spawned

15185

through os.exec() or os.spawn() is redirected to the standard output, and not

15186

to the usual python output that GPS has overriden.

15187

15188

There are two solutions for this:

15189

@itemize @bullet

15190

@item Execute the external process through a pipe

15191

15192

The output of the pipe is then redirected to Python's output, as in:

15193

15194

@smallexample

15195

import os, sys

15196

def my_external():

15197

f = os.popen ('ls')

15198

console = GPS.Console ("ls")

15199

for l in f.readlines():

15200

console.write (' ' + l)

15201

@end smallexample

15202

15203

This solution allows you, at the same time, to modify the output, for instance

15204

to indent it as in the example above.

15205

15206

@item Execute the process through GPS

15207

15208

You can go through the process of defining an XML customization string for

15209

GPS, and execute your process this way, as in:

15210

15211

@smallexample

15212

GPS.parse_xml ("""

15213

15214

15215

</action>""")

15216

15217

def my_external():

15218

GPS.execute_action ("ls")

15219

@end smallexample

15220

15221

This solution also allows you to send the output to a different window than the

15222

rest of your script. But you cannot filter or modify the output as in the

15223

first solution.

15224

15225

@end itemize

15226

15227

@c ----------------------------------------------

15228

@node Contextual menus on object directories only

15229

@subsubsection Contextual menus on object directories only

15230

15231

The following filter can be used for actions that can only execute in the

15232

Project View, and only when the user clicks on an object directory. The

15233

contextual menu entry will not be visible in other contexts

15234

15235

@smallexample

15236

<?xml version="1.0" ?>

15237

<root>

15238

<filter name="object directory"

15239

shell_cmd="import os.path; os.path.samefile (GPS.current_context().project().object_dirs()[0],GPS.current_context().directory())"

15240

shell_lang="python"

15241

module="Explorer" />

15242

15243

15244

15245

<shell>echo "Success"</shell>

15246

</action>

15247

15248

15249

<Title>Test on object directory</Title>

15250

</contextual>

15251

</root>

15252

@end smallexample

15253

15254

Another example would be to have a filter so that the contextual menu only

15255

appears when on a project node in the Project View. Using @code{%P} in your

15256

command is not enough, since the current context when you click on a file

15257

or directory also contain information about the project this file or directory

15258

belongs to. Thus this implicit filter will not be enough to hide your

15259

contextual menu.

15260

15261

As a result, you need to do a slightly more complex test, where you check that

15262

the current context doesn't contains information on directories (which will

15263

disable the contextual menu for directories, files and entities). Since the

15264

command uses @code{%P}, GPS garantees that a project is available.

15265

15266

We'll implement this contextual menu in a Python file, called

15267

@file{filters.py}.

15268

15269

@smallexample

15270

import GPS

15271

def on_project():

15272

try:

15273

GPS.current_context().directory()

15274

return False

15275

except:

15276

return True

15277

15278

GPS.parse_xml ("""

15279

15280

<filter module="Explorer"

15281

shell_lang="python"

15282

shell_cmd="filters.on_project()" />

15283

<shell>echo current project is %P</shell>

15284

</action>

15285

15286

<title>Print current project</title>

15287

</contextual>""")

15288

@end smallexample

15289

15290

The example above shows the flexibility of filters, since you can pretty much

15291

do anything you wish through the shell commands. However, it is complex to

15292

write for such a simple filter. Luckily, GPS provides a predefined filter

15293

just for that purpose, so that you can write instead, in an XML file:

15294

15295

@smallexample

15296

15297

15298

<shell>echo current project is %P</shell>

15299

</action>

15300

@end smallexample

15301

15302

@c --------------------------------------------------------

15303

@node Redirecting the output to specific windows

15304

@subsubsection Redirecting the output to specific windows

15305

15306

By default, the output of all python commands is displayed in the Python

15307

console. However, you might want in some cases to create other windows in

15308

GPS for this output. This can be done in one of two ways:

15309

15310

@itemize @bullet

15311

@item Define a new action

15312

15313

If the whole output of your script should be redirected to the same window,

15314

or if the script will only be used interactively through a menu or a key

15315

binding, the easiest way is to create a new XML action, and redirect the

15316

output, as in

15317

15318

@smallexample

15319

<?xml version="1.0" ?>

15320

<root>

15321

15322

<shell lang="python">print "a"</shell>

15323

</action>

15324

</root>

15325

@end smallexample

15326

15327

All the various shell commands in your action can be output in a different

15328

window, and this also applies for the output of external commands.

15329

15330

@item Explicit redirection

15331

15332

If, however, you want to control in your script where the output should be

15333

sent, for instance if you can't know that statically when you write your

15334

commands, you can use the following code:

15335

15336

@smallexample

15337

sys.stdin = sys.stdout = GPS.Console ("New window")

15338

print "foo"

15339

print (sys.stdin.read ())

15340

sys.stdin = sys.stdout = GPS.Console ("Python")

15341

@end smallexample

15342

15343

The first line redirect all input and output to a new window, which is

15344

created if it doesn't exist yet. Note however that the output of stderr

15345

is not redirected, and you need to explicitely do it for @code{sys.stderr}.

15346

15347

The last line restore the default Python console. You must do this

15348

at the end of your script, or all scripts will continue to use the new

15349

consoles.

15350

15351

You can alternatively create separate objects for the output, and use them

15352

in turn:

15353

15354

@smallexample

15355

my_out = GPS.Console ("New Window")

15356

my_out2 = GPS.Console ("New Window2")

15357

15358

sys.stdout=my_out

15359

print "a"

15360

sys.stdout=my_out2

15361

print "b"

15362

sys.stdout=GPS.Console ("Python")

15363

@end smallexample

15364

15365

The parameter to the constructor @code{GPS.Console} indicates whether any

15366

output sent to that console should be saved by GPS, and reused for the

15367

@code{%1}, @code{%2}, @dots{} parameters if the command is executed in a

15368

GPS action. That should generally be 1, except for stderr where it should

15369

be 0.

15370

@end itemize

15371

15372

@c -------------------------------------------

15373

@node Reloading a python file in GPS

15374

@subsubsection Reloading a python file in GPS

15375

15376

After you have made modification to a python file, you might want to

15377

reload it in GPS. This requires careful use of python commands.

15378

15379

Here is an example. Lets assume you have a python file (@file{"mymod.py"})

15380

which contains the following:

15381

15382

@smallexample

15383

GPS.parse_xml ("""

15384

15385

<shell lang="python">mymod.myfunc()</shell>

15386

</action>""")

15387

15388

def myfunc():

15389

print "In myfunc\n"

15390

@end smallexample

15391

15392

As you can guess from this file, it defines an action "my_action", that you

15393

can for instance associate with a keybinding through the Edit->Key shortcuts

15394

menu.

15395

15396

If this file has been copied in one of the @file{plug-ins} directories,

15397

it will be automatically loaded at startup.

15398

15399

Notice that the function @code{myfunc} is thus found in a separate namespace,

15400

with the name @code{mymod}, same as the file.

15401

15402

If you decide, during your GPS session, to edit this file and have the

15403

function print "In myfunc2" instead, you then have to reload the file by

15404

typing the following command in the Python console:

15405

15406

@smallexample

15407

> execfile ("HOME/.gps/plug-ins/mymod.py", mymod.__dict__)

15408

@end smallexample

15409

15410

The first parameter is the full path to the file that you want to reload.

15411

The second argument is less obvious, but indicates that the file should be

15412

reloaded in the namespace @code{mymod}.

15413

15414

If you omit the optional second parameter, Python will load the file, but

15415

the function @code{myfunc} will be defined in the global namespace, and thus

15416

the new definition is accessible through

15417

15418

@smallexample

15419

> myfunc()

15420

@end smallexample

15421

15422

Thus, the key shortcut you had set, which still executes @code{mymod.myfunc()}

15423

will keep executing the old definition.

15424

15425

By default, GPS provides a contextual menu when you are editing a Python

15426

file. This contextual menu (Python->Reload module) will take care of all

15427

the above details.

15428

15429

@c -------------------------------------------

15430

@node Printing the GPS Python documentation

15431

@subsubsection Printing the GPS Python documentation

15432

15433

The python extension provided by GPS is fully documentation in this

15434

manual and a separate manual accessible through the Help menu in GPS.

15435

15436

However, this documentation is provided in HTML, and might not be the

15437

best suitable for printing, if you wish to do so.

15438

15439

The following paragraph explains how you can generate your own documentation

15440

for any python module, including GPS, and print the result.

15441

15442

@smallexample

15443

import pydoc

15444

pydoc.writedoc (GPS)

15445

@end smallexample

15446

15447

In the last comamnd, @code{GPS} is the name of the module that you want

15448

to print the documentation for.

15449

15450

These commands generate a @file{.html} file in the current directory.

15451

15452

Alternatively, you can generate a simple text file with

15453

15454

@smallexample

15455

e=file("./python_doc", "w")

15456

e.write (pydoc.text.document (GPS))

15457

e.flush()

15458

@end smallexample

15459

15460

This text file includes bold characters by default. Such bold characters

15461

are correctly interpreted by tools such as @file{a2ps} which can be used

15462

to convert the text file into a postscript document.

15463

15464

@c -------------------------------------------

15465

@node Automatically loading python files at startup

15466

@subsubsection Automatically loading python files at startup

15467

15468

@noindent

15469

At startup, GPS will automatically load all python files found in

15470

the directories @file{share/gps/plug-ins} and

15471

@file{$HOME/.gps/plug-ins}.

15472

15473

In addition, python files located under

15474

@file{<prefix>/share/gps/python} can be imported (using the @code{import}

15475

command) by any python script.

15476

15477

You can also set the @code{PYTHONPATH} environment variable to add other

15478

directories to the python search path.

15479

15480

@c --------------------------------------------------------------------

15481

@node Hiding contextual menus

15482

@subsubsection Hiding contextual menus

15483

@cindex contextual menus

15484

15485

@noindent

15486

GPS provides most of its tools through contextual menus, accessed by right

15487

clicking in various parts of GPS. Due to the number of tools provided by GPS,

15488

these contextual menus tend to be big, and you might want to control what

15489

should be displayed in them. There are several ways to control this:

15490

15491

@itemize @bullet

15492

@item Define appropriate filters for your actions

15493

15494

If you are creating your own contextual menus through customization files and

15495

XML, these menus are associated with actions (@code{<action>}) that you have

15496

created yourself most of the time. In this case, you need to define filters

15497

appropriately, through the @code{<filter>} tag, to decide when the action

15498

is relevant, and therefore when the contextual menu should be displayed.

15499

15500

@item Use shell commands to hide the menus

15501

15502

If you want to control the visibility of predefined contextual menus, or

15503

for menus where you cannot easily modify the associated filter, you can

15504

use shell and python commands to hide the menu entry. For this, you will

15505

need to find out the name of the menu, which can be done by checking the

15506

list returned by @code{GPS.Contextual.list()} and using the most likely

15507

entry. This name is also the value of the @code{<title>} tag for contextual

15508

menus that you have created yourself. Using this name, you can then disable

15509

the contextual menu by executing:

15510

15511

@smallexample

15512

GPS.Contextual ("name").hide()

15513

@end smallexample

15514

15515

in the python console

15516

15517

@end itemize

15518

15519

@c --------------------------------------------------------------------

15520

@node Creating custom graphical interfaces

15521

@subsubsection Creating custom graphical interfaces

15522

@cindex pygtk

15523

15524

@noindent

15525

GPS is based on the Gtk+ graphical toolkit, which is available under many

15526

platforms and for many programming languages.

15527

15528

You can install an third party package, downloadable from

15529

@url{http://www.pygtk.org}, which is a python binding to Gtk+.

15530

Using pygtk, you will be able to create your own dialogs and graphical

15531

windows using the python capabilities provided by GPS.

15532

15533

See the menu @code{Help->Python Extensions}, in particular the @code{GPS.MDI}

15534

documentation, for a sample of code on how to create your own graphical

15535

interfaces and integrate them in GPS.

15536

15537

@c --------------------------------------------------------------------

15538

@node Hooks

15539

@subsection Hooks

15540

@cindex hooks

15541

@c --------------------------------------------------------------------

15542

15543

@noindent

15544

A @b{hook} is a named set of commands to be executed on particular occasions

15545

as a result of user actions in GPS.

15546

15547

GPS and its various modules define a number of standard hooks, which are

15548

called for instance when a new project is loaded, when a file is edited, and

15549

so on. You can define your own commands to be executed in such cases.

15550

15551

@cindex hooks, Hook.list

15552

@cindex hooks, Hook.describe

15553

You can find out the list of hooks that GPS currently knows about by calling

15554

the @b{Hook.list} function, which takes no argument, and returns a list of

15555

hook names that you can use. More advanced description for each hook is

15556

available through the @code{Help->Python Extensions}.

15557

15558

@smallexample

15559

GPS> Hook.list

15560

project_changed

15561

open_file_action_hook

15562

preferences_changed

15563

[...]

15564

15565

Python> GPS.Hook.list()

15566

@end smallexample

15567

15568

@cindex hooks, type

15569

The description of each hooks includes a pointer to the type of the hook, that

15570

is what parameters the subprograms in this hook will receive. For instance:

15571

15572

@cindex hooks, Hook.list_types

15573

The list of all known hook types can be found through the @b{Hook.list_types}

15574

command. This takes no argument and returns a list of all known types of hooks.

15575

As before, you can more information for each of these type through a call to

15576

@b{Hook.describe_type}.

15577

15578

@c ----------------------------------

15579

@subsubsection Adding commands to hooks

15580

@c ----------------------------------

15581

15582

@noindent

15583

You can add your own command to existing hooks through a call to the

15584

@b{Hook.add} command. Whenever the hook is executed by GPS or another script,

15585

your command will also be executed, and will be given the parameters that

15586

were specified when the hook is run. The first parameter is always the name

15587

of the hook being executed.

15588

15589

This @b{Hook.add} applies to an instance of the hook class, and takes one

15590

parameter, the command to be executed. This is a subprogram parameter (@pxref{Subprogram parameters}).

15591

15592

@itemize @bullet

15593

@item GPS shell

15594

15595

The command can be any GPS action (@pxref{Defining Actions}). The arguments for

15596

the hook will be passed to the action, and are available as $1, $2, @dots{};

15597

In the following example, the message "Just executed

15598

the hook: project_changed" will be printed in the Shell console. Note that we

15599

are defining the action to be executed inline, but this could in fact be

15600

defined in a separate XML customization file for convenience.

15601

15602

@smallexample

15603

GPS> parse_xml """<action name="my_action"><shell>echo "Just executed the hook"</shell></action_name>"""

15604

GPS> Hook project_changed

15605

GPS> Hook.add %1 "my_action"

15606

@end smallexample

15607

15608

@item Python

15609

15610

The command must be a subprogram to execute. The arguments for the

15611

hook will be passed to this subprogram. In the following example, the

15612

message "The hook project_changed was executed by GPS" will be displayed in the

15613

Python console whenever the project changes.

15614

15615

@smallexample

15616

def my_callback (name):

15617

print "The hook " + name + " was executed by GPS"

15618

GPS.Hook ("project_changed").add (my_callback)

15619

@end smallexample

15620

15621

@end itemize

15622

15623

The example above shows the simplest type of hook, which doesn't take any

15624

argument. However, most hooks receive several parameters. For instance, the

15625

hook "file_edited" receives the file name as a parameter.

15626

15627

@itemize @bullet

15628

@item GPS shell

15629

15630

The following code will print the name of the hook ("file_edited") and the

15631

name of the file in the shell console every time a file is open by GPS.

15632

@smallexample

15633

GPS> parse_xml """<action name="my_action"><shell>echo name=$1 file=$2</shell></action>"""

15634

GPS> Hook "file_edited"

15635

GPS> Hook.add %1 "my_action"

15636

@end smallexample

15637

15638

@item Python

15639

15640

The following code prints the name of the file being edited by GPS in the

15641

python console whenever a new editor is opened. The second argument is of type

15642

GPS.File.

15643

15644

@smallexample

15645

def my_file_callback (name, file):

15646

print "Editing " + file.name()

15647

GPS.Hook ("file_edited").add (my_file_callback)

15648

@end smallexample

15649

15650

@end itemize

15651

15652

@c ----------------------------------

15653

@subsubsection Action hooks

15654

@cindex hooks, action_hooks

15655

@cindex hooks, open_file_action_hook

15656

@c ----------------------------------

15657

15658

@noindent

15659

Some hooks have a special use in GPS. Their name always ends with

15660

"_action_hook".

15661

15662

As opposed to the standard hooks described in the previous section, the

15663

execution of the action hooks stops as soon as one of the subprograms returns

15664

a True value ("1" or "true"). The subprograms associated with that hook are

15665

executed one after the other. If any such subprogram knows how to act for that

15666

hook, it should do the appropriate action and return "1".

15667

15668

Other action hooks expect a string as a return value instead of a boolean. The

15669

execution will stop when a subprogram returns a non-empty string.

15670

15671

This mechanism is used extensively by GPS internally. For instance, whenever

15672

a file needs to be opened in an editor, GPS executes the

15673

"open_file_action_hook" hook to request its editing. Several modules are

15674

connected to that hook.

15675

15676

One of the first modules to be executed is the external editor module. If the

15677

user has chosen to use an external editor, this module will simply spawn

15678

Emacs or the external editor that the user has selected, and return 1. This

15679

immediately stops the execution of the "open_file_action_hook".

15680

15681

However, if the user doesn't want to use external editors, this module will

15682

return 0. This will keep executing the hook, and in particular will execute the

15683

source editor module, which will always act and open an editor internally in

15684

GPS.

15685

15686

This is a very flexible mechanism. In your own script, you could choose to

15687

have some special handling for files with a ".foo" extension for instance. If

15688

the user wants to open such a file, you would spawn for instance an external

15689

command (say "my_editor") on this file, instead of opening it in GPS.

15690

15691

This is done with a code similar to the following

15692

15693

@smallexample

15694

from os.path import *

15695

import os

15696

def my_foo_handler (name, file, line, column, \

15697

column_end, enable_nav, new_file, reload):

15698

if splitext (file.name())[1] == ".foo":

15699

os.spawnv \

15700

(os.P_NOWAIT, "/usr/bin/emacs", ("emacs", file.name()))

15701

return 1 ## Prevent further execution of the hook

15702

return 0 ## Let other subprograms in the hook do their job

15703

15704

GPS.Hook ("open_file_action_hook").add (my_foo_handler)

15705

@end smallexample

15706

15707

@c --------------------------------------------------------------------

15708

@subsubsection Running hooks

15709

@cindex hooks, Hook.run

15710

@c --------------------------------------------------------------------

15711

15712

@noindent

15713

Any module in GPS is responsible for running the hooks when appropriate.

15714

Most of the time, the subprograms exported by GPS to the scripting languages

15715

will properly run the hook. But you might also need to run them in your own

15716

scripts.

15717

15718

As usual, this will result in the execution of all the functions bound to

15719

that hook, whether they are defined in Ada or in any of the scripting

15720

languages.

15721

15722

This is done through the @b{Hook.run} command. This applies to an instance

15723

of the Hook class, and a variable number of arguments

15724

These must be in the right order and of the right type

15725

for that specific type of hook.

15726

15727

If you are running an action hook, the execution will stop as usual as soon

15728

as one of the subprograms return a True value.

15729

15730

The following example shows how to run a simple hook with no parameter, and

15731

a more complex hook with several parameters. The latter will in fact request

15732

the opening of an editor for the file in GPS, and thus has an immediately

15733

visible effect on the interface. The file is opened at line 100. See the

15734

description of the hook for more information on the other parameters.

15735

15736

@smallexample

15737

GPS.Hook ("project_changed").run()

15738

GPS.Hook ("open_file_action_hook").run \

15739

(GPS.File ("test.adb"), 100, 1, 0, 1, 1, 1)

15740

@end smallexample

15741

15742

@c --------------------------------------------------------------------

15743

@subsubsection Creating new hooks

15744

@cindex hooks, creating

15745

@cindex hooks, Hook.register

15746

@c --------------------------------------------------------------------

15747

15748

@noindent

15749

The list of hooks known to GPS is fully dynamic. GPS itself declares a

15750

number of hooks, mostly for its internal use although of course you can

15751

also connect to them.

15752

15753

But you can also create your own hooks to report events happening in your

15754

own modules and programs. This way, any other script or GPS module can

15755

react to these events.

15756

15757

Such hooks can either be of a type exported by GPS, which constraints the

15758

list of parameters for the callbacks, but make such hooks more portable and

15759

secure; or they can be of a general type, which allows basically any kind

15760

of parameters. In the latter case, checks are done at runtime to ensure that

15761

the subprogram that is called as a result of running the hook has the right

15762

number of parameters. If this isn't the case, GPS will complain and display

15763

error messages. Such general hooks will also not pass their parameters to

15764

other scripting languages.

15765

15766

Creating new hooks is done through a call to @b{Hook.register}. This function

15767

takes two arguments: the name of the hook you are creating,

15768

and the type of the hook.

15769

15770

The name of the hook is left to you. Any character is allowed in that name,

15771

although using only alphanumerical characters is recommended.

15772

15773

The type of the hook must be one of the following:

15774

15775

@itemize @bullet

15776

@item "" (the empty string)

15777

15778

This indicates that the hook doesn't take any argument. None should be given

15779

to @b{Hook.run}, and none should be

15780

expected by the various commands connected to that hook, apart from

15781

the hook name itself.

15782

15783

@item one of the values returned by @b{Hook.list_types}

15784

15785

This indicates that the hook is of one of the types exported by GPS itself. The

15786

advantage of using such explicit types as opposed to "general" is that GPS

15787

is able to make more tests for the validity of the parameters. Such hooks can

15788

also be connected to from other scripting languages.

15789

15790

@item "general"

15791

15792

This indicates that the hook is of the general type that allows any number of

15793

parameter, of any type. Other scripts will be able to connect to it, but will

15794

not be executed when the hook is run if they do not expect the same number of

15795

parameters that was given to @b{Hook.run}. Other scripts in other language will

15796

only receive the hook name in parameter, not the full list of parameters.

15797

15798

@end itemize

15799

15800

A small trick worth noting: if the command bound to a hook doesn't have the

15801

right number of parameters that this hook provide, the command will not be

15802

executed and GPS will report an error. You can make sure that your command

15803

will always be executed by either giving default values for its parameter, or

15804

by using python's syntax to indicate a variable number of arguments.

15805

15806

This is especially useful if you are connecting to a "general" hook, since you

15807

do not really know in advance how many parameters the call of @b{Hook.run} will

15808

provide.

15809

15810

@smallexample

15811

## This callback can be connected to any type of hook

15812

def trace (name, *args):

15813

print "hook=" + name

15814

15815

## This callback can be connected to hooks with one or two parameters

15816

def trace2 (name, arg1, arg2=100):

15817

print "hook=" + str (arg1) + str (arg2)

15818

15819

Hook.register ("my_custom_hook", "general")

15820

Hook ("my_custom_hook").add (trace2)

15821

Hook ("my_custom_hook").run (1, 2) ## Prints 1 2

15822

Hook ("my_custom_hook").run (1) ## Prints 1 100

15823

@end smallexample

15824

15825

@c --------------------------------------------------------------------

15826

@node Adding support for new Version Control Systems

15827

@section Adding support for new Version Control Systems

15828

@cindex generic_vcs

15829

@c --------------------------------------------------------------------

15830

15831

@menu

15832

* Custom VCS interfaces::

15833

* Describing a VCS::

15834

* Implementing VCS actions::

15835

@end menu

15836

15837

@node Custom VCS interfaces

15838

@subsection Custom VCS interfaces

15839

15840

@noindent

15841

The Version Control interface in GPS can be customized, either to

15842

refine the behavior of the existing system and adapt it to specific

15843

needs, or to add support for other Version Control systems.

15844

15845

Custom VCS interfaces are defined entirely through XML files. Those

15846

files are read in the same location as all the other XML

15847

customizations that GPS offers. See @ref{Customizing through XML and Python files} for a

15848

complete description.

15849

15850

There are two steps to follow when creating a custom VCS

15851

interface. The first step is to describe the VCS itself, and the

15852

second step is to implement actions corresponding to all the

15853

operations that this VCS can perform. The following two sections

15854

(@ref{Describing a VCS} and @ref{Implementing VCS actions}) describe

15855

those steps.

15856

15857

GPS is distributed with XML files describing the interfaces to

15858

ClearCase, CVS and Subversion. These XML files are located in the directory

15859

@code{share/gps/plug-ins} in the GPS installation, and can be used as a

15860

reference for implementing new custom VCS interfaces.

15861

15862

@node Describing a VCS

15863

@subsection Describing a VCS

15864

15865

@menu

15866

* The VCS node::

15867

* Associating actions to operations::

15868

* Defining revision information::

15869

* Defining status::

15870

* Output parsers::

15871

@end menu

15872

15873

@node The VCS node

15874

@subsubsection The VCS node

15875

15876

@noindent

15877

The @code{vcs} node is the toplevel node which contains the

15878

description of the general behavior expected from the VCS. It has the

15879

following attributes:

15880

15881

@table @code

15882

@item name

15883

The attribute @code{name} indicates the identifier of the VCS. The

15884

casing of this name is important, and the same casing must be used in

15885

the project files.

15886

15887

@item absolute_names

15888

The attribute @code{absolute_names} indicates the behavior of the

15889

VCS relative to file names, and can take the values @code{TRUE} or

15890

@code{FALSE}. If it is set to @code{TRUE}, it means that all

15891

commands in the VCS will work on absolute file names. If it set to

15892

@code{FALSE}, it means that all actions work on base file names, and

15893

that GPS will move to the appropriate directory before executing an

15894

action.

15895

15896

@item group_queries_by_directory

15897

The attribute @code{group_queries_by_directory} indicates that, when querying

15898

status for all the source files in a directory, a query for the directory

15899

should be launched, instead of launching a query for multiple files.

15900

This operation is faster on some Version Control systems. By default, this

15901

is set to @code{FALSE}.

15902

15903

@item ignore_file

15904

The attribute @code{ignore_file} specifies the name of the file used

15905

by the VCS Explorer to get the list of files to ignore. By default for

15906

the CVS mode this is set to @file{.cvsignore}.

15907

15908

@item atomic_commands

15909

The attribute @code{atomic_commands} specifies if the VCS supports

15910

atomicity and can take the values @code{TRUE} or @code{FALSE}. If it

15911

is set to @code{TRUE} it means that the VCS supports atomic

15912

commands. It is @code{FALSE} by default. This attribute is important

15913

to trigger the activities group commit feature. See @xref{The VCS Activities}.

15914

15915

@item path_style

15916

The attribute @code{path_style} specifies which kind of directory separator

15917

is supported by the VCS and can take the values @code{UNIX},

15918

@code{DOS}, @code{Cygwin} or @code{System_Default}. The later value is

15919

the default value. With this attribute it is possible to control the

15920

directory separator to use when specifying files to the VCS. For the

15921

@code{Cygwin} case the drive is specified as @code{/cygdrive/<drive>}.

15922

15923

@item dir_sep

15924

Alias for @code{path_style}, obsolescent.

15925

15926

@item commit_directory

15927

The attribute @code{commit_directory} specifies if the VCS supports

15928

commit on directories and can take the values @code{TRUE} or @code{FALSE}.

15929

If it is set to @code{TRUE} it means that the VCS supports commit on

15930

directories this is the case for @code{Subversion} for example.

15931

@end table

15932

15933

Note that to support group commit with shared log on GPS both

15934

@code{absolute_name} and @code{atomic_commands} must be true. This is

15935

the case for the Subversion VCS for example.

15936

15937

Here is an example, adapted to the use of CVS:

15938

15939

@smallexample

15940

15941

15942

(... description of action associations ...)

15943

(... description of supported status ...)

15944

(... description of output parsers ...)

15945

15946

</vcs>

15947

@end smallexample

15948

15949

@node Associating actions to operations

15950

@subsubsection Associating actions to operations

15951

15952

@noindent

15953

GPS knows about a certain set of predefined ``operations'' that a VCS

15954

can perform. The user can decide to implement some of them - not

15955

necessarily all of them - in this section.

15956

15957

The following node is used to associate a predefined operation to an

15958

action:

15959

15960

@smallexample

15961

15962

@end smallexample

15963

15964

Where:

15965

@table @samp

15966

@item OPERATION

15967

is the name of the predefined action. The list of predefined actions

15968

is described in @ref{Implementing VCS actions},

15969

15970

@item ACTION_LABEL

15971

is the name of the corresponding gps Action that will be launched when

15972

GPS wants to ask the VCS to perform OPERATION,

15973

15974

@item NAME OF OPERATION

15975

is the name that will appear in the GPS menus when working on a file

15976

under the control of the defined VCS.

15977

@end table

15978

15979

@node Defining revision information

15980

@subsubsection Defining revision information

15981

15982

@noindent

15983

Some VCS reports revisions number from which it is possible to deduce

15984

the related branches. This is the case in CVS for example where a

15985

revision number for a branch uses as prefix the branch point revision

15986

number. For such VCS it is possible to specify two regular

15987

expressions:

15988

15989

@table @b

15990

15991

@item @code{parent_revision}

15992

15993

Parse the revision number and report as first match the parent revision.

15994

15995

@smallexample

15996

<parent_revision regexp="..." />

15997

@end smallexample

15998

15999

For CVS on @b{1.2.4.5} it must match @b{1.2}.

16000

16001

@item @code{branch_root_revision}

16002

16003

Parse the revision number and report as first match the branch root

16004

revision.

16005

16006

@smallexample

16007

<branch_root_revision regexp="..." />

16008

@end smallexample

16009

16010

For CVS on @b{1.2.4.5} it must match @b{1.2.4}.

16011

@end table

16012

16013

@node Defining status

16014

@subsubsection Defining status

16015

16016

@noindent

16017

All VCS have the notion of ``status'' or ``state'' to describe the

16018

relationship between the local file and the repository. The XML node

16019

@code{status} is used to describe the status that are known to a

16020

custom VCS, and the icons associated to it:

16021

16022

@smallexample

16023

16024

@end smallexample

16025

16026

Where:

16027

@table @samp

16028

@item STATUS_LABEL

16029

is the name of the status, for example ``Up to date'' or ``Needs update''

16030

in the context of CVS.

16031

@item STOCK_LABEL

16032

is the stock identifier of the icon associated to this status, that

16033

will be used, for example, in the VCS Explorer. See section

16034

@ref{Adding stock icons} for more details on how to define stock

16035

icons.

16036

@end table

16037

16038

Note that the order in which status are defined in the XML file is

16039

important: the first status to be displayed must correspond to the

16040

status ``Up-to-date'' or equivalent.

16041

16042

@node Output parsers

16043

@subsubsection Output parsers

16044

16045

@noindent

16046

There are cases in which GPS needs to parse the output of the VCS

16047

commands: when querying the status, or when ``annotating'' a

16048

file.

16049

16050

The following parsers can be implemented in the @code{vcs} node.

16051

16052

@table @b

16053

@item @code{<status_parser>} and @code{<local_status_parser>}

16054

These parsers are used by the command VCS.status_parse, to parse a string for

16055

the status of files controlled by a VCS.

16056

16057

They accept the following child nodes:

16058

16059

@table @b

16060

@item @code{<regexp>} (mandatory)

16061

Indicates the regular expression to match.

16062

@item @code{<file_index>}

16063

An index of a parenthesized expression in @code{regexp} that contains the name

16064

of a file.

16065

@item @code{<status_index>}

16066

An index of a parenthesized expression in @code{regexp} that contains the file

16067

status. This status is passed through the regular expressions defined in the

16068

@code{status_matcher} nodes, see below.

16069

@item @code{<local_revision_index>}

16070

An index of a parenthesized expression in @code{regexp} that contains the name

16071

of the local revision (the version of the file that was checked out).

16072

@item @code{<repository_revision_index>}

16073

An index of a parenthesized expression in @code{regexp} that contains the name

16074

of the repository revision (the latest version of the file in the VCS).

16075

16076

@item @code{<status_matcher>}

16077

A regular expression which, when matching an expressions, identifies the status

16078

passed in the node attribute @code{label}.

16079

@end table

16080

16081

@item @code{<annotations_parser>}

16082

This parser is used by the command VCS.annotations_parse, to parse a string for

16083

annotations in a file controlled by a VCS.

16084

16085

It accepts the following child nodes:

16086

16087

@table @b

16088

@item @code{<regexp>} (mandatory)

16089

Indicates the regular expression to match.

16090

16091

@item @code{<repository_revision_index>} (mandatory)

16092

An index of a parenthesized expression in @code{regexp} that contains the

16093

repository revision of the line.

16094

16095

@item @code{<author_index>}

16096

An index of a parenthesized expression in @code{regexp} that contains the

16097

author of the line.

16098

16099

@item @code{<date_index>}

16100

An index of a parenthesized expression in @code{regexp} that contains the

16101

date of the line.

16102

16103

@item @code{<file_index>}

16104

An index of a parenthesized expression in @code{regexp} that indicates the

16105

part of the line that belongs to the file.

16106

16107

@item @code{<tooltip_pattern>}

16108

A template pattern that will be used to format the tooltip information.

16109

It can contain text and reference parenthesized expressions in

16110

@code{regexp} using \@code{n} (where @code{n} represents the nth

16111

expression in @code{regexp}).

16112

16113

@end table

16114

16115

@item @code{<log_parser>}

16116

This parser is used by the command VCS.log_parse, to parse a string for

16117

revision histories in a file controlled by a VCS.

16118

16119

It accepts the following child nodes:

16120

16121

@table @b

16122

@item @code{<regexp>} (mandatory)

16123

Indicates the regular expression to match.

16124

16125

@item @code{<repository_revision_index>} (mandatory)

16126

An index of a parenthesized expression in @code{regexp} that contains the

16127

repository revision of the log.

16128

16129

@item @code{<author_index>}

16130

An index of a parenthesized expression in @code{regexp} that contains the

16131

author of the log.

16132

16133

@item @code{<date_index>}

16134

An index of a parenthesized expression in @code{regexp} that contains the

16135

date of the log.

16136

16137

@item @code{<log_index>}

16138

An index of a parenthesized expression in @code{regexp} that contains the

16139

actual text of the log.

16140

@end table

16141

16142

@item @code{<revision_parser>}

16143

This parser is used by the command VCS.revision_parse, to parse a string for

16144

revision tags and branches in a file controlled by a VCS.

16145

16146

It accepts the following child nodes:

16147

16148

@table @b

16149

@item @code{<regexp>} (mandatory)

16150

Indicates the regular expression to match.

16151

16152

@item @code{<sym_index>} (mandatory)

16153

An index of a parenthesized expression in @code{regexp} that contains the

16154

tags or branches symbolic name of the revision.

16155

16156

@item @code{<repository_revision_index>} (mandatory)

16157

An index of a parenthesized expression in @code{regexp} that contains the

16158

repository revision number of the revision.

16159

16160

@end table

16161

16162

@end table

16163

16164

@node Implementing VCS actions

16165

@subsection Implementing VCS actions

16166

16167

@noindent

16168

A number of ``standard'' VCS operations are known to GPS. Each of

16169

these operations can be implemented, using Actions. See @ref{Defining

16170

Actions}) for a complete description of how to implement actions.

16171

16172

Here is a list of all the defined VCS operations, and their

16173

parameters:

16174

16175

@table @code

16176

16177

@item status_files

16178

@table @code

16179

@item $1 = whether the log files should be cleared when obtaining up-to-date status

16180

@item $2- = the list of files to query status for.

16181

@end table

16182

Query the status for a list of files. This should perform a complete

16183

VCS query and return results as complete as possible.

16184

16185

@item status_dir

16186

@table @code

16187

@item $1 = the directory.

16188

@end table

16189

Same as above, but works on all the files in one directory.

16190

16191

@item status_dir_recursive

16192

@table @code

16193

@item $1 = the directory.

16194

@end table

16195

Same as above, but works on all the files in one directory and all

16196

subdirectories, recursively.

16197

16198

@item local_status_files

16199

@table @code

16200

@item $* = list of files

16201

@end table

16202

Query the local status for specified files. This query should be as

16203

fast as possible, not connecting to any remote VCS. The results need

16204

not be complete, but it is not useful to implement this command if

16205

the output does not contain at least the working revision.

16206

16207

@item open

16208

@table @code

16209

@item $* = list of files

16210

@end table

16211

Open files or directories for editing. This command should be

16212

implemented on any VCS that require an explicit check-out/open/edit

16213

action before being able to edit a file.

16214

16215

@item update

16216

@table @code

16217

@item $* = list of files

16218

@end table

16219

Bring the specified files in sync with the latest repository revision.

16220

16221

@item resolved

16222

@table @code

16223

@item $* = list of files

16224

@end table

16225

Mark files' merge conflics as resolved. Some version control systems

16226

(like Subversion) will block any commit until this action is called.

16227

16228

@item commit

16229

@table @code

16230

@item $1 = log file

16231

@item $2- = list of files

16232

@end table

16233

Commit/submit/check-in files or directories with provided log. The log is

16234

passed in a file.

16235

16236

@item commit_dir

16237

@table @code

16238

@item $1 = log

16239

@item $2 = directory

16240

@end table

16241

Commit/submit one directory with provided log. The log is passed in

16242

a file.

16243

16244

@item history_text

16245

@table @code

16246

@item $1 = file

16247

@end table

16248

Query the entire changelog history for the specified file. The result

16249

is expected to be placed into an editor as plain text.

16250

16251

@item history

16252

@table @code

16253

@item $1 = file

16254

@end table

16255

Query the entire changelog history for the specified file. The result

16256

is expected to be placed into a Revision View.

16257

16258

@item history_revision

16259

@table @code

16260

@item $1 = revision

16261

@item $2 = file

16262

@end table

16263

Query the history for corresponding revision of the specified file.

16264

16265

@item annotate

16266

@table @code

16267

@item $1 = file

16268

@end table

16269

Query the annotations for a file.

16270

16271

@item add

16272

@table @code

16273

@item $1 = log

16274

@item $2- = list of files or dirs

16275

@end table

16276

Add files/dirs to the repository, with the provided revision log. The

16277

added files/dirs are commited.

16278

16279

@item add_no_commit

16280

@table @code

16281

@item $1 = log

16282

@item $2- = list of files or dirs

16283

@end table

16284

Add files/dirs to the repository, with the provided revision log. The

16285

added files/dirs are not commited.

16286

16287

@item remove

16288

@table @code

16289

@item $1 = log

16290

@item $2 = file or dir

16291

@end table

16292

Remove file/dir from the repository, with the provided revision log.

16293

16294

@item remove_no_commit

16295

@table @code

16296

@item $1 = log

16297

@item $2 = file or dir

16298

@end table

16299

Remove file/dir from the repository, with the provided revision log.

16300

The removed files/dirs are not commited.

16301

16302

@item revert

16303

@table @code

16304

@item $* = files

16305

@end table

16306

Revert the local file to repository revision, cancelling all local

16307

changes, and close the file for editing if it was open.

16308

16309

@item diff_patch

16310

@table @code

16311

@item $1 = file

16312

@end table

16313

Create a textual diff for the given file. This command is used to

16314

build the activity patch file.

16315

16316

@item diff_head

16317

@table @code

16318

@item $1 = file

16319

@end table

16320

Display a visual comparison between the local file and the latest

16321

repository revision. The diff command must report a @i{normal} diff

16322

as opposed to @i{context} or @i{unified} ones.

16323

16324

@item diff_base_head

16325

@table @code

16326

@item $1 = file

16327

@end table

16328

Display a visual comparison between the revision from which the file

16329

has been checked-out and the latest revision. The diff command must

16330

report a @i{normal} diff as opposed to @i{context} or @i{unified} ones.

16331

16332

@item diff_working

16333

@table @code

16334

@item $1 = file

16335

@end table

16336

Display a visual comparison between the local file and the revision

16337

from which it was obtained. The diff command must report a @i{normal} diff

16338

as opposed to @i{context} or @i{unified} ones.

16339

16340

@item diff

16341

@table @code

16342

@item $1 = rev

16343

@item $2 = file

16344

@end table

16345

Display a visual comparison between the local file and the specified

16346

revision. The diff command must report a @i{normal} diff

16347

as opposed to @i{context} or @i{unified} ones.

16348

16349

@item diff2

16350

@table @code

16351

@item $1 = revision 1

16352

@item $2 = revision 2

16353

@item $3 = file

16354

@end table

16355

Display a visual comparison between the two specified revisions of

16356

the file. The diff command must report a @i{normal} diff

16357

as opposed to @i{context} or @i{unified} ones.

16358

16359

@end table

16360

16361

@c --------------------------------------------------------------------

16362

@node The Server Mode

16363

@section The Server Mode

16364

@cindex server

16365

@c --------------------------------------------------------------------

16366

16367

@noindent

16368

In order to give access to the GPS capabilities from external processes

16369

(e.g. @code{Emacs}), GPS can be launched in @i{server mode}.

16370

16371

The two relevant command line switches are @code{--server} and

16372

@code{--hide}.

16373

16374

@code{--server} will open a socket on the given port, allowing multiple

16375

clients to connect to a running GPS, and sending GPS shell or python

16376

commands.

16377

16378

@code{--hide} tells GPS not to display its main window when starting.

16379

note that under unix systems, you still need to have access to the current

16380

screen (as determined by the @code{DISPLAY} environment variable) in this

16381

mode.

16382

16383

Using the two switches together provides a way to launch GPS as a background

16384

process with no initial user interface.

16385

16386

Clients connecting through a standard socket have access to a simple

16387

shell using @code{GPS>> } as the separating prompt between each command. This

16388

is needed in order to determine when the output (result) of a command

16389

is terminated.

16390

16391

All the GPS shell commands (as defined in @ref{The GPS Shell}) are

16392

available from this shell. In addition, the python interpreter, if

16393

enabled, is also available through the use of the @code{python} prefix

16394

before a python command.

16395

16396

For example, sending @code{pwd} through the socket will send the @code{pwd}

16397

command through the GPS shell and display the result on the socket;

16398

similarly, sending @code{python GPS.pwd()} will send the @code{GPS.help()}

16399

command through the python interpreter (see @ref{The Python Interpreter} for

16400

more details).

16401

16402

The socket shell provides also additional commands:

16403

16404

@itemize @bullet

16405

@item logout

16406

This command will inform the GPS server that the connection should now

16407

be closed.

16408

16409

@item id <string>

16410

This command will register the current session with a given string.

16411

This string can then be used within GPS itself (for example via a

16412

.xml or python plug-in) to display extra information to the client via

16413

the socket, using the command GPS.Socket().send.

16414

@end itemize

16415

16416

For example, let suppose that we start gps with the @code{--server=1234}

16417

command: this will bring up GPS as usual.

16418

16419

Now, on a separate terminal, create a simple client by typing the following:

16420

16421

@smallexample

16422

telnet localhost 1234

16423

Trying 127.0.0.1...

16424

Connected to localhost.

16425

Escape character is '^]'.

16426

GPS>> id test-1

16427

id set to 'test-1'

16428

GPS>> pwd

16429

c:\working-dir\

16430

GPS>>

16431

@end smallexample

16432

16433

Then in the GPS Python Console:

16434

16435

@smallexample

16436

>>> GPS.Socket ("test-1").send ("hello, it's time to logout\n");

16437

@end smallexample

16438

16439

At this point, the following is received on the client (telnet) side:

16440

16441

@smallexample

16442

GPS>> hello, it's time to logout

16443

@end smallexample

16444

16445

We can then close the client:

16446

16447

@smallexample

16448

logout

16449

Connection closed by foreign host.

16450

@end smallexample

16451

16452

@c --------------------------------------------------------------------

16453

@node Environment

16454

@chapter Environment

16455

@cindex environment

16456

@c --------------------------------------------------------------------

16457

16458

@menu

16459

* Command Line Options::

16460

* Environment Variables::

16461

* Running GPS on Mac OS X::

16462

* Files::

16463

* Reporting Suggestions and Bugs::

16464

* Solving Problems::

16465

@end menu

16466

16467

@node Command Line Options

16468

@section Command Line Options

16469

@cindex command line

16470

@cindex options

16471

16472

@cindex example

16473

@smallexample

16474

Usage:

16475

gps [options] [-Pproject-file] [[+line] source1] [[+line] source2] ...

16476

Options:

16477

--help Show this help message and exit

16478

--version Show the GPS version and exit

16479

--debug[=program] Start a debug session and optionally load the

16480

program with the given arguments

16481

--debugger debugger Specify the debugger's command line

16482

--hide Hide GPS main window

16483

--host=tools_host Use tools_host to launch tools (e.g. gdb)

16484

--target=TARG:PRO Load program on machine TARG using protocol PRO

16485

--load=lang:file Execute an external file written in the

16486

language lang

16487

--eval=lang:file Execute an in-line script written in the

16488

language lang

16489

--readonly Open all files in read-only mode

16490

--server=port Start GPS in server mode, opening a socket on the

16491

given port

16492

--tracelist Output the current configuration for logs

16493

--traceon=name Activate the logs for a given module

16494

--traceoff=name Deactivate the logs for a given module

16495

--tracefile=file Parse an alternate configuration file for the logs

16496

16497

Source files can be absolute or relative pathnames.

16498

If you prepend a file name with '=', this file will be

16499

searched anywhere on the project's source path

16500

16501

To open a file at a given line, use the '+line' prefix, e.g.

16502

gps +40 source.adb

16503

16504

@code{tools_host} corresponds to a remote host's nickname as defined in

16505

@ref{Setup the remote servers}.

16506

16507

@end smallexample

16508

16509

@c --------------------------------------------------------------------

16510

@node Environment Variables

16511

@section Environment Variables

16512

@cindex environment

16513

@cindex environment variables

16514

@c --------------------------------------------------------------------

16515

16516

@noindent

16517

The following environment variables can be set to override some default

16518

settings in GPS:

16519

16520

@table @samp

16521

@item GPS_ROOT

16522

@cindex GPS_ROOT

16523

Override the default root directory specified when GPS

16524

is built (during the @i{configure} process, see the file @code{INSTALL} in

16525

the GPS sources for more details) to access information such as the location

16526

of the translation files.

16527

16528

@item GPS_HOME

16529

@cindex GPS_HOME

16530

@cindex Windows

16531

Override the variable HOME if present. All the configuration files and

16532

directories used by GPS are either relative to $HOME/.gps (%HOME%\.gps

16533

under Windows) if GPS_HOME is not set, or to $GPS_HOME/.gps (respectively

16534

%GPS_HOME%\.gps) if set.

16535

16536

@item GPS_DOC_PATH

16537

@cindex GPS_DOC_PATH

16538

Set the search path for the documentation. @xref{Adding New Help Files}.

16539

16540

@item GPS_CUSTOM_PATH

16541

@cindex GPS_CUSTOM_PATH

16542

Contains a list of directories to search for custom files. See

16543

@ref{Customizing through XML and Python files} for more details.

16544

16545

@item GPS_CHANGELOG_USER

16546

@cindex GPS_CHANGELOG_USER

16547

Contains the user and e-mail to use in the global ChangeLog

16548

files. Note that the common usage is to have two spaces between the

16549

name and the e-mail. Ex: "John Does <john.doe@@home.com>"

16550

16551

@item GPS_STARTUP_PATH

16552

@cindex GPS_STARTUP_PATH

16553

Contains the value of the @code{PATH} environment variable just before GPS

16554

was started. This is used by GPS to restore the proper environment before

16555

spawning applications, no matter what particular directories it needed to

16556

set for its own purpose.

16557

16558

@item GPS_STARTUP_LD_LIBRARY_PATH

16559

@cindex GPS_STARTUP_LD_LIBRARY_PATH

16560

Same as @code{GPS_STARTUP_LD_LIBRARY_PATH} but for the @code{LD_LIBRARY_PATH}

16561

variable.

16562

16563

@end table

16564

16565

@c --------------------------------------------------------------------

16566

@node Running GPS on Mac OS X

16567

@section Running GPS on Mac OS X

16568

@cindex Mac OS

16569

@c --------------------------------------------------------------------

16570

16571

@noindent

16572

The current version of GPS on Mac OS X requires an X11 server. Such a server

16573

is distributed with Mac OS X Panther and Mac OS X Tiger.

16574

16575

Additionally, if you are launching GPS from a standard Terminal, you need to

16576

specify the display on which to launch GPS, by typing:

16577

16578

@code{export DISPLAY=:0}

16579

16580

before launching GPS.

16581

16582

Note: GPS does not support files with line endings in CR.

16583

16584

@c --------------------------------------------------------------------

16585

@node Files

16586

@section Files

16587

@cindex files

16588

@c --------------------------------------------------------------------

16589

16590

@noindent

16591

16592

@table @file

16593

@item $HOME/.gps

16594

@cindex Windows

16595

@cindex HOME

16596

GPS state directory. Defaults to C:\.gps under Windows systems if HOME or

16597

USERPROFILE environment variables are not defined.

16598

16599

@item $HOME/.gps/log

16600

@cindex log

16601

@anchor{log file}

16602

Log file created automatically by GPS.

16603

When GPS is running, it will create a file named @file{log.<pid>}, where

16604

@file{<pid>} is the GPS process id, so that multiple GPS sessions do not

16605

clobber each other's log. In case of a successful session, this

16606

file is renamed @file{log} when exiting; in case of an unexpected exit

16607

(a bug box will be displayed), the log file is kept under its original name.

16608

16609

Note that the name of the log file is configured by the @file{traces.cfg}

16610

file.

16611

16612

@item $HOME/.gps/aliases

16613

@cindex aliases

16614

File containing the user-defined aliases (@pxref{Defining text aliases}).

16615

16616

@item $HOME/.gps/plug-ins

16617

Directory containing files with user-defined plug-ins.

16618

All xml and python files found under this directory are loaded by GPS during

16619

start up.

16620

You can create/edit these files to add your own menu/tool-bar entries in GPS,

16621

or define support for new languages.

16622

@pxref{Customizing through XML and Python files} and

16623

@pxref{Adding support for new languages}.

16624

16625

@item $HOME/.gps/keys.xml

16626

Contains all the key bindings for the actions defined in GPS or in the

16627

custom files. This only contains the key bindings overridden through the

16628

key shortcuts editor (see @ref{The Key Manager Dialog}).

16629

16630

@item $HOME/.gps/gtkrc

16631

@cindex Dynamic Key Binding

16632

@cindex gtkrc

16633

Configuration and theme file for gtkrc. This file can be edited to activate

16634

gtk+ specific aspects, or change the look of GPS in some measure. Mostly,

16635

everything can be done through the standard GPS preferences, but this file

16636

can be used to get access to the old GPS preference "Dynamic Key Binding".

16637

This preference activated a gtk+ behavior were key shortcuts for menu can be

16638

changed by simply pressing the appropriate key combination when the mouse is

16639

over that menu. It has various dangereous aspects and is not fully supported

16640

by GPS, so was removed as a preference, but you can add the following line

16641

in @file{gtkrc} to get this back:

16642

@smallexample

16643

gtk-can-change-accels=1

16644

@end smallexample

16645

16646

@item $HOME/.gps/actions.xml

16647

Contains the definition of all the actions that were defined through the

16648

graphical interface. This is loaded last, and overrides all actions defined

16649

elsewhere.

16650

16651

@item $HOME/.gps/desktop.xml

16652

Desktop file in XML format (using the menu @code{File->Save More->Desktop}),

16653

loaded automatically if found.

16654

16655

@item $HOME/.gps/locations.xml

16656

This file contains the list of locations that GPS has previously edited. It

16657

corresponds to the history navigation (@code{Navigate->Back} and

16658

@code{Navigate->Forward})

16659

16660

@item $HOME/.gps/properties.xml

16661

This file is used to store file-specific properties across GPS sessions. In

16662

particular, it contains the encoding to use for various files when the

16663

default encoding isn't appropriate.

16664

16665

@item $HOME/.gps/histories.xml

16666

@cindex history

16667

Contains the state and history of combo boxes (e.g. the

16668

@code{Run->Custom...} dialog).

16669

16670

@item $HOME/.gps/targets.xml

16671

@cindex targets

16672

Contains the build targets defined by the user.

16673

16674

@item $HOME/.gps/preferences

16675

@cindex preferences

16676

Contains all the preferences in XML format, as specified in the

16677

preferences menu.

16678

16679

@item $HOME/.gps/traces.cfg

16680

Default configuration for the system traces. These traces are used to analyze

16681

problems with GPS.

16682

By default, they are sent to the file @file{$HOME/.gps/log.<pid>}.

16683

16684

This file is created automatically when the @file{$HOME/.gps/} directory is

16685

created. If you remove it manually, it won't be recreated the next time you

16686

start GPS.

16687

16688

@item $HOME/.gps/startup.xml

16689

This file contains the list of scripts to load at startup, as well as

16690

additional code that need to be executed to setup the script.

16691

16692

@item $HOME/.gpe/activity_log.tmplt

16693

Template file used to generate activities' group commit-log and patch

16694

file's header. If not present the system wide template (see below) is

16695

used. The set of configurable tags are described into this template.

16696

@cindex activity log template

16697

@cindex activity, log template

16698

16699

@item @i{prefix}

16700

The prefix directory where GPS is installed, e.g @file{/opt/gps}.

16701

16702

@item @i{prefix}/bin

16703

The directory containing the GPS executables.

16704

16705

@item @i{prefix}/etc/gps

16706

The directory containing global configuration files for GPS.

16707

16708

@item @i{prefix}/lib

16709

This directory contains the shared libraries used by GPS.

16710

16711

@item @i{prefix}/share/doc/gps/html

16712

GPS will look for all the documentation files under this directory.

16713

16714

@item @i{prefix}/share/examples/gps

16715

This directory contains source code examples.

16716

16717

@item @i{prefix}/share/examples/gps/language

16718

This directory contains sources showing how to provide a shared library to

16719

dynamically define a new language. See @ref{Adding support for new languages}.

16720

16721

@item @i{prefix}/share/examples/gps/tutorial

16722

This directory contains the sources used by the GPS tutorial.

16723

@ifhtml

16724

@cindex url

16725

See @url{gps-tutorial.html}.

16726

@end ifhtml

16727

16728

@item @i{prefix}/share/gps/plug-ins

16729

Directory containing files with system-wide plug-ins (xml and python files)

16730

loaded automatically at start-up.

16731

16732

@item @i{prefix}/share/gps/library

16733

Directory containing files with system-wide plug-ins (xml and python files)

16734

that are not loaded automatically at startup, but can be selected in the

16735

Plug-ins editor.

16736

16737

@item @i{prefix}/share/gps/gps-animation.png

16738

@cindex png

16739

Default image displayed in the top right corner of GPS when GPS is idle.

16740

16741

@item @i{prefix}/share/gps/gps-animation.gif

16742

@cindex gif

16743

Animated image displayed in the top right corner of GPS to indicate that

16744

actions (e.g compilation) are on going. If you remove this file, the idle

16745

image (@file{gps-animation.png}) will always be displayed.

16746

16747

@item @i{prefix}/share/gps/gps-splash.png

16748

@cindex png

16749

Splash screen displayed by default when GPS is started.

16750

16751

@item @i{prefix}/share/gps/desktop.xml

16752

@cindex default desktop

16753

@cindex desktop, default

16754

This is the description of the default desktop that GPS uses when the user

16755

hasn't defined his own default desktop and no project specific desktop exists.

16756

You can modify this file if you want, knowing that this will impact all users

16757

of GPS sharing this installation.

16758

The format of this file is the same as $HOME/.gps/desktop.xml, which can be

16759

copied from your own directory if you wish.

16760

16761

@item @i{prefix}/share/gps/default.gpr

16762

@cindex default project

16763

Default project used by GPS. Can be modified after installation time to

16764

provide useful default for a given system or project.

16765

16766

@item @i{prefix}/share/gps/readonly.gpr

16767

Project used by GPS as the default project when working in a read-only

16768

directory.

16769

16770

@item @i{prefix}/share/gps/activity_log.tmplt

16771

Template file used by default to generate activities' group commit-log

16772

and patch file's header. This file can be copied into user home

16773

directory and customized (see above).

16774

16775

@item @i{prefix}/share/locale

16776

Directory used to retrieve the translation files, when relevant.

16777

16778

@end table

16779

16780

@c --------------------------------------------------------------------

16781

@node Reporting Suggestions and Bugs

16782

@section Reporting Suggestions and Bugs

16783

@cindex suggestions

16784

@cindex submitting bugs

16785

@c --------------------------------------------------------------------

16786

16787

@noindent

16788

If you would like to make suggestions about GPS, or if you encountered a bug,

16789

please report it to @uref{mailto:report@@gnat.com} if you are a supported

16790

user, and to @uref{mailto:gps-devel@@lists.act-europe.fr} otherwise.

16791

16792

Please try to include a detailed description of the problem, including

16793

sources to reproduce it if possible/needed, and/or a scenario describing the

16794

actions performed to reproduce the problem, as well as the tools (e.g

16795

@i{debugger}, @i{compiler}, @i{call graph}) involved.

16796

16797

The files @file{$HOME/.gps/log} may also

16798

bring some useful information when reporting a bug.

16799

16800

In case GPS generates a bug box, the log file will be kept under a separate

16801

name (@file{$HOME/.gps/log.<pid>} so that it does not get erased by further

16802

sessions. Be sure to include the right log file when reporting a bug box.

16803

16804

@c --------------------------------------------------------------------

16805

@node Solving Problems

16806

@section Solving Problems

16807

@cindex problems

16808

@cindex solving problems

16809

@c --------------------------------------------------------------------

16810

16811

@noindent

16812

This section addresses some common problems that may arise when using or

16813

installing GPS.

16814

16815

@table @samp

16816

16817

@item Non-privileged users cannot start GPS

16818

Q: I have installed GPS originally as super user, and ran GPS successfully,

16819

but normal users can't.

16820

16821

A: You should check the permissions of the directory $HOME/.gps and its

16822

subdirectories, they should be owned by the user.

16823

16824

@item GPS crashes whenever I open a source editor

16825

This is usually due to font problems. Editing the file

16826

@file{$HOME/.gps/preferences} and changing the name of the fonts, e.g

16827

changing @i{Courier} by @i{Courier Medium}, and @i{Helvetica} by @i{Sans}

16828

should solve the problem.

16829

16830

@item GPS refuses to start the debugger

16831

@cindex debugger

16832

If GPS cannot properly initialize the debugger (using the menu

16833

@code{Debug->Initialize}), it is usually because the underlying debugger

16834

(gdb) cannot be launched properly. To verify this, try to launch the

16835

'gdb' command from a shell (i.e outside GPS). If gdb cannot be launched from

16836

a shell, it usually means that you are using a wrong version of gdb

16837

(e.g a version of gdb built for Solaris 8, but run on Solaris 2.6).

16838

16839

@item GPS is frozen during a debugging session

16840

@cindex debugger

16841

If GPS is no longer responding while debugging an application you should

16842

first wait a little bit, since some communications between GPS and gdb

16843

can take a long time to finish. If GPS is still not responding after a

16844

few minutes, you can usually get the control back in GPS by either typing

16845

@key{Ctrl-C} in the shell where you've started GPS: this should unblock it;

16846

if it does not work, you can kill the gdb process launched by GPS using the

16847

@code{ps} and @code{kill}, or the @code{top} command under Unix,

16848

@cindex Unix

16849

@cindex Windows

16850

and the @code{Task Manager} under Windows: this will terminate your debugging

16851

session, and will unblock GPS.

16852

16853

@item My Ada program fails during elaboration. How can I debug it ?

16854

@cindex -g

16855

@cindex gnatmake

16856

If your program was compiled with GNAT, the main program is

16857

generated by the binder. This program is an ordinary Ada (or C if the

16858

@option{-C} switch was used) program, compiled in the usual manner,

16859

and fully debuggable provided that the @option{-g} switch is used on

16860

the @command{gnatlink} command (or @option{-g} is used in the

16861

@command{gnatmake} command itself).

16862

16863

The name of this package containing the main program is

16864

@file{b~xxx.ads/adb} where xxx is the name of the Ada main unit given

16865

in the gnatbind command, and you can edit and debug this file in the

16866

normal manner. You will see a series of calls to the elaboration

16867

routines of the packages, and you can debug these in the usual manner,

16868

just as if you were debugging code in your application.

16869

16870

@item How can I debug the Ada run-time library ?

16871

The run time distributed in binary versions of GNAT hasn't been

16872

compiled with debug information. Thus, it needs to be recompiled

16873

before you can actually debug it.

16874

16875

The simplest is to recompile your application by adding the switches

16876

@option{-a} and @option{-f} to the @command{gnatmake} command

16877

line. This extra step is then no longer required, assuming that you

16878

keep the generated object and ali files corresponding to the GNAT run time

16879

available.

16880

16881

Another possibility on Unix systems is to use the file @file{Makefile.adalib}

16882

that can be found in the adalib directory of your GNAT installation and

16883

specify e.g @option{-g -O2} for the @option{CFLAGS} switches.

16884

16885

@item The GPS main window is not displayed

16886

If when launching GPS, nothing happens, you can try to rename the @file{.gps}

16887

directory (see @ref{Files}) to start from a fresh set up.

16888

16889

@item My project have several files with the same name. How can I import it in GPS?

16890

GPS's projects do not allow implicit overriding of sources file, i.e.

16891

you cannot have multiple times the same file name in the project

16892

hierarchy. The reason is that GPS needs to know exactly where the file

16893

is, and cannot reliably guess which occurrence to use.

16894

16895

There are several solutions to handle this issue:

16896

16897

@itemize @bullet

16898

@item Put all duplicate files in the same project

16899

16900

There is one specific case where a project is allowed to have duplicate source

16901

files: if the list of source directories is specified explicitly. All

16902

duplicate files must be in the same project. With these conditions, there is

16903

no ambiguity for GPS and the GNAT tools which file to use, and the first

16904

file found on the source path is the one hiding all the others. GPS only

16905

shows the first file.

16906

16907

You can then have a scenario variable that changes the order of source

16908

directories to give visibility on one of the other duplicate files.

16909

16910

@item Use scenario variables in the project

16911

16912

The idea is that you define various scenarios in your project (For

16913

instance compiling in "debug" mode or "production" mode), and change

16914

the source directories depending on this setup. Such projects can be

16915

edited directly from GPS (in the project properties editor, this is

16916

the right part of the window, as described in this documentation). On

16917

top of the project view (left part of the GPS main window), you

16918

have a combo box displayed for each of the variable, allowing a simple

16919

switch between scenarios depending on what you want to build.

16920

16921

@item Use extending projects

16922

16923

These projects cannot currently be created through GPS, so you will

16924

need to edit them by hand. See the GNAT user's guide for more

16925

information on extending projects.

16926

16927

The idea behind this approach is that you can have a local overriding of some

16928

source files from the common build/source setup (if you are working

16929

on a small part of the whole system, you may not want to have a complete

16930

copy of the code on your local machine).

16931

16932

@end itemize

16933

16934

@item GPS is very slow compared to previous versions under unix (GPS < 4.0.0)

16935

16936

GPS 4.0.0 and above need the X RENDER extension when running under unix

16937

systems to perform at a reasonable speed, so you need to make sure you X

16938

server properly supports this extension.

16939

16940

@end table

16941

16942

@c --------------------------------------------------------------------

16943

@node Index table

16944

@unnumbered Index

16945

@printindex cp

16946

16947

@bye