~noskcaj/ubuntu/vivid/jhbuild/3.12 : revision 7

1

<?xml version="1.0" encoding="utf-8" standalone="no"?>

2

3

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

4

5

6

7

<title>Handbok för JHBuild</title>

8

9

10

<firstname>James</firstname>

11

<surname>Henstridge</surname>

12

</author>

13

14

15

<surname>Adams-Collier</surname>

16

</author>

17

18

<firstname>Frederic</firstname>

19

<surname>Peters</surname>

20

</author>

21

22

<firstname>David</firstname>

23

<surname>Turner</surname>

24

</author>

25

</authorgroup>

26

27

28

<holder>James Henstridge</holder>

29

</copyright><copyright><year>2008</year><holder>Daniel Nylander (po@danielnylander.se)</holder></copyright>

30

31

32

<revnumber>Handbok för JHBuild v0.5</revnumber>

33

<date>Januari 2008</date>

34

</revision>

35

36

<revnumber>Handbok för JHBuild v0.1</revnumber>

37

<date>Augusti 2007</date>

38

</revision>

39

</revhistory>

40

41

<para>JHBuild is a tool used to build the whole GNOME desktop from the

42

version control system. JHBuild can also be customized to build other

43

projects too.</para>

44

</abstract>

45

</articleinfo>

46

47

48

<title>Introduktion</title>

49

50

<para>JHBuild is a tool designed to ease building collections of source

51

packages, called <quote>modules</quote>. JHBuild uses <quote>module

52

set</quote> files to describe the modules available to build. The

53

<quote>module set</quote> files include dependency information that allows

54

JHBuild to discover what modules need to be built and in what order.

55

</para>

56

57

<para>JHBuild was originally written for building

58

<ulink url="http://www.gnome.org">GNOME</ulink>, but has since been

59

extended to be usable with other projects. A <quote>module set</quote>

60

file can be hosted on a web server, allowing for build rules independent

61

of the JHBuild project.</para>

62

63

<para>JHBuild can build modules from a variety of sources, including

64

<ulink url="http://www.cvshome.org/">CVS</ulink>,

65

<ulink url="http://subversion.tigris.org/">Subversion,</ulink>

66

<ulink url="http://wiki.gnuarch.org/">Arch</ulink>,

67

<ulink url="http://www.bazaar-vcs.org/">Bazaar</ulink>,

68

<ulink url="http://darcs.net/">Darcs</ulink>,

69

<ulink url="http://git.or.cz/">Git</ulink> and

70

<ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink>

71

repositories, as well as Tar and Zip archives hosted on web or FTP sites.

72

JHBuild can build modules using a variety of build systems, including

73

Autotools, CMake, WAF, Python Distutils and Perl Makefiles.</para>

74

75

<para>JHBuild is not intended as a replacement for the distribution's

76

package management system. Instead, it makes it easy to build software

77

into a separate install prefix without interfering with the rest of the

78

system.</para>

79

</section>

80

81

82

<title>Komma igång</title>

83

84

<para>JHBuild requires a few set up steps to be run before building

85

software. JHBuild requires some prerequisite software, and it is necessary

86

to install prerequisite tools needed to obtain and build the software

87

modules.</para>

88

89

90

<title>Installera JHBuild</title>

91

92

<para>JHBuild requires a Python runtime. Verify Python >= 2.3 is

93

installed.</para>

94

95

<para>The recommended way to download JHBuild is via the version control

96

system, <command>git</command>. This can be achieved with the following

97

command. It is recommended to run the command from a new directory where

98

all source code will be installed, for example,

99

<filename>~/checkout/gnome</filename>.</para>

100

101

<screen><prompt>$</prompt> <userinput>git clone git://git.gnome.org/jhbuild</userinput>

102

103

104

105

<para>This will download JHBuild into a new folder named

106

<filename>jhbuild</filename> under the current directory. Now to build

107

and install JHBuild:</para>

108

109

<screen><prompt>$</prompt> <userinput>cd jhbuild</userinput>

110

<prompt>$</prompt> <userinput>./autogen.sh</userinput>

111

112

113

114

<prompt>$</prompt> <userinput>make install</userinput>

115

116

117

118

<para>If <application>gnome-common</application>,

119

<application>gnome-doc-utils</application> and

120

<application>autotools</application> are available,

121

<filename>autogen.sh</filename> will configure JHBuild to install via

122

<application>autotools</application>. If

123

<application>gnome-common</application>,

124

<application>gnome-doc-utils</application> and

125

<application>autotools</application> are not available,

126

<filename>autogen.sh</filename> will configure JHBuild to install via a

127

plain Makefile. To always use the plain Makefile method pass

128

<option>--simple-install</option> to <filename>autogen.sh</filename>.

129

</para>

130

131

<para>If the above steps complete successfully, a small shell script

132

will be installed in <filename>~/.local/bin</filename> to start JHBuild.

133

Add <filename>~/.local/bin</filename> to the <envar>PATH</envar>:</para>

134

135

<screen><prompt>$</prompt> <userinput>PATH=$PATH:~/.local/bin</userinput>

136

137

138

<para>To permanently add <filename>~/.local/bin</filename> to the

139

<envar>PATH</envar> variable, run the following command:</para>

140

141

142

<prompt>$</prompt> <userinput>echo PATH=$PATH:~/.local/bin >> ~/.bashrc</userinput>

143

144

145

<para>Before running JHBuild, it is necessary to set up a configuration

146

file located at <filename>~/.jhbuildrc</filename>.</para>

147

</section>

148

149

150

<title>Konfigurera JHBuild</title>

151

152

<para>The <filename>~/.jhbuildrc</filename> file uses Python syntax to

153

set configuration variables for JHBuild. An example is provided with

154

JHBuild, see <filename>examples/sample.jhbuildrc</filename>. Copy

155

<filename>examples/sample.jhbuildrc</filename> to

156

<filename>~/.jhbuildrc</filename> and customize as required.</para>

157

158

<para>The sample configuration will make JHBuild build the

159

<application>meta-gnome-core</application> and

160

<application>meta-gnome-apps-tested</application> modules and

161

dependencies from the <systemitem>gnome-apps-3.4</systemitem> module

162

set. JHBuild will unpack source trees to

163

<filename>~/checkout/gnome</filename> and install all files to

164

subdirectories of <filename>/opt/gnome</filename>. The two directories

165

must be writable.</para>

166

167

<para>Configuration variables are documented in

168

<xref linkend="config-reference"/>. The most commonly used variables

169

are:</para>

170

171

172

<?dbhtml list-presentation="table"?>

173

174

<term>

175

176

</term>

177

178

<simpara>A dictionary that can be used to specify an alternative

179

repository location for a particular repository. This

180

configuration variable is useful to a module developer. By

181

default, JHBuild will check out code from repositories using an

182

anonymous repository location. The dictionary keys are short

183

repository names and the values are alternative repository

184

location strings. For example:</simpara>

185

186

<programlisting>repos['git.gnome.org'] = 'ssh://<replaceable>username</replaceable>@git.gnome.org/git/'</programlisting>

187

</listitem>

188

</varlistentry>

189

190

<term>

191

192

</term>

193

194

<simpara>A string or list of strings specifying the name(s) of the

195

module set(s) to use. This can either be the filename of a

196

moduleset included with JHBuild (excluding the path and

197

extension), or a full HTTP URL to an externally managed moduleset.

198

HTTP URL modulesets are cached locally. If a module with the same

199

name is present in more than one moduleset, the last set listed

200

takes priority. Modulesets provided with JHBuild are updated to

201

match the current GNOME development release.</simpara>

202

</listitem>

203

</varlistentry>

204

205

<term>

206

207

</term>

208

209

<simpara>A list of strings specifying the modules to build. The

210

list of modules actually built will be recursively expanded to

211

include all the dependencies unless the

212

213

<command>buildone</command></link> command is used. Defaults to

214

<literal>['meta-gnome-desktop']</literal>.</simpara>

215

</listitem>

216

</varlistentry>

217

218

<term>

219

220

</term>

221

222

<simpara>A string specifying the directory to unpack source trees

223

to. Unless <link linkend="cfg-buildroot">

224

<varname>buildroot</varname></link> is set, builds will occur in

225

this directory too. Defaults to

226

<filename>~/checkout/gnome</filename>.</simpara>

227

</listitem>

228

</varlistentry>

229

230

<term>

231

232

</term>

233

234

<simpara>A string specifying the prefix to install modules to.

235

<varname>prefix</varname> must be an absolute path. This directory

236

must be writable. Defaults to <literal>'/opt/gnome'</literal>.

237

</simpara>

238

</listitem>

239

</varlistentry>

240

241

<term>

242

243

</term>

244

245

<simpara>A string containing arguments passed to the

246

<command>autogen.sh</command> script of all modules. Can be

247

overridden for particular modules using the

248

249

<varname>module_autogenargs</varname></link> dictionary.</simpara>

250

</listitem>

251

</varlistentry>

252

253

<term>

254

255

</term>

256

257

<simpara>A string listing additional arguments to be passed to

258

<command>make</command>. Defaults to <literal>''</literal>.

259

</simpara>

260

</listitem>

261

</varlistentry>

262

</variablelist>

263

</section>

264

265

266

<title>Build Prerequisites</title>

267

268

<para>Before any modules can be built, it is necessary to have certain

269

build tools installed. Common build tools include the GNU Autotools

270

(<application>autoconf</application>,

271

<application>automake</application>, <application>libtool</application>

272

and <application>gettext</application>), The GNU Toolchain

273

(<application>binutils</application>, <application>gcc</application>,

274

<application>g++</application>), pkg-config and Python, depending on

275

which modules will be built.</para>

276

277

<para>JHBuild can check the tools are installed using the

278

<command>sanitycheck</command> command:</para>

279

280

<screen><prompt>$</prompt> <userinput>jhbuild sanitycheck</userinput></screen>

281

282

<para>If this command displays any messages, the errors can be fixed in

283

one of two ways:</para>

284

285

286

287

<simpara>Install the required package from your distribution's

288

repository. A list of

289

<ulink url="http://live.gnome.org/JhbuildDependencies">package

290

names</ulink> for different distributions is maintained on the GNOME

291

wiki. Run the <command>sanitycheck</command> command again after

292

installing the distribution's packages to ensure the required tools

293

are present.</simpara>

294

</listitem>

295

296

<simpara>Run the <command>bootstrap</command> command to download,

297

build and install the build prerequisites:</simpara>

298

299

<screen><prompt>$</prompt> <userinput>jhbuild bootstrap</userinput></screen>

300

301

<para>When complete, run the <command>sanitycheck</command> command

302

to verify the required tools are present.</para>

303

304

<note>

305

<para>The <command>bootstrap</command> command does not build all

306

the package dependencies required by the build tools. If your

307

distribution does not provide the required packages, they will

308

need to be built outside of the JHBuild environment.</para>

309

310

<para>The build tools dependencies include

311

<application>m4</application>, <application>perl</application> and

312

a C compiler (for example, <application>gcc</application>).</para>

313

</note>

314

</listitem>

315

</orderedlist>

316

</section>

317

318

319

<title>Using JHBuild</title>

320

321

<para>After set up is complete, JHBuild can be used to build software.

322

To build all the modules selected in the

323

<filename>~/.jhbuildrc</filename> file, run the following command:

324

</para>

325

326

<screen><prompt>$</prompt> <userinput>jhbuild build</userinput></screen>

327

328

<para>JHBuild will download, configure, compile and install each of the

329

modules. If an error occurs at any stage, JHBuild will present a menu

330

asking what to do. The choices include dropping to a shell to fix the

331

error, rerunning the build from various stages, giving up on the module,

332

or ignore the error and continue.</para>

333

334

<note>

335

<simpara>Giving up on a module will cause any modules depending on the

336

module to fail.</simpara>

337

</note>

338

339

<para>Below is an example of the menu displayed:</para>

340

341

<screen> [1] Rerun phase build

342

[2] Ignore error and continue to install

343

[3] Give up on module

344

[4] Start shell

345

[5] Reload configuration

346

[6] Go to phase "wipe directory and start over"

347

[7] Go to phase "configure"

348

[8] Go to phase "clean"

349

[9] Go to phase "distclean"

350

<prompt>choice:</prompt> </screen>

351

352

<para>It is also possible to build a different set of modules and their

353

dependencies by passing the module names as arguments to the

354

<command>build</command> command. For example, to build gtk+:</para>

355

356

<screen><prompt>$</prompt> <userinput>jhbuild build gtk+</userinput></screen>

357

358

<para>If JHBuild is cancelled part way through a build, it is possible

359

to resume the build at a particular module using the

360

<option>--start-at</option> option:</para>

361

362

<screen><prompt>$</prompt> <userinput>jhbuild build --start-at=pango</userinput></screen>

363

364

<para>To build one or more modules, ignoring their dependencies, JHBuild

365

provides the <command>buildone</command> command. For the

366

<command>buildone</command> command to complete successfully, all

367

dependencies must be previously built and installed or provided by

368

distribution packages.</para>

369

370

<screen><prompt>$</prompt> <userinput>jhbuild buildone gtk+</userinput></screen>

371

372

<para>To get a list of the modules and dependencies JHBuild will build,

373

and the order they will be built, use the <command>list</command>

374

command:</para>

375

376

<screen><prompt>$</prompt> <userinput>jhbuild list</userinput></screen>

377

378

<para>To get information about a particular module, use the

379

<command>info</command> command:</para>

380

381

<screen><prompt>$</prompt> <userinput>jhbuild info gtk+</userinput></screen>

382

383

<para>To download or update all the software sources without building,

384

use the <command>update</command> command. The <command>update</command>

385

command provides an opportunity to modify the sources before building

386

and can be useful if internet bandwidth varies.</para>

387

388

<screen><prompt>$</prompt> <userinput>jhbuild update</userinput></screen>

389

390

<para>Later, JHBuild can build everything without downloading or

391

updating the sources:</para>

392

393

<screen><prompt>$</prompt> <userinput>jhbuild build --no-network</userinput></screen>

394

395

<para>To run a particular command with the same environment used by

396

JHBuild, use the <command>run</command> command:</para>

397

398

<screen><prompt>$</prompt> <userinput>jhbuild run <replaceable>program</replaceable></userinput></screen>

399

400

<para>To start a shell with the same environment used by JHBuild, use

401

the <command>shell</command> command:</para>

402

403

<screen><prompt>$</prompt> <userinput>jhbuild shell</userinput></screen>

404

</section>

405

</section>

406

407

408

<title>JHBuild and GNOME</title>

409

410

<para>This section provides guidance on building, installing and running

411

GNOME.</para>

412

413

414

<title>Building GNOME</title>

415

416

<para>To build GNOME some development packages are required. This

417

includes:</para>

418

419

420

421

<simpara>DocBook XML DTD and XSLT stylesheets. These need to be

422

registered in the XML catalog

423

(<filename>/etc/xml/catalog</filename>).</simpara>

424

</listitem>

425

426

<simpara>X libraries</simpara>

427

</listitem>

428

429

<simpara><filename>libsmbclient</filename> from Samba (used for

430

browsing Windows networks).</simpara>

431

</listitem>

432

433

<simpara><filename>libbz2</filename> from bzip2.</simpara>

434

</listitem>

435

436

<simpara><filename>libpng</filename>, <filename>libjpeg</filename>

437

and <filename>libtiff</filename> (used for image loading).</simpara>

438

</listitem>

439

</itemizedlist>

440

441

<para>If installing distribution packages, and if applicable for your

442

distribution, install the corresponding <quote>dev</quote> or

443

<quote>devel</quote> packages. A list of

444

<ulink url="http://live.gnome.org/JhbuildDependencies">package

445

names</ulink> for different distributions is maintained on the GNOME

446

wiki.</para>

447

</section>

448

449

450

<title>Running a Single GNOME Application</title>

451

452

<para>This section details how to run a single GNOME application. The

453

application will run within the current desktop environment. To run the

454

application within the complete JHBuild GNOME see

455

456

457

<para>Launch a JHBuild shell. The JHBuild shell has all the necessary

458

environment variables set.</para>

459

460

<screen><prompt>$</prompt><userinput>jhbuild shell</userinput></screen>

461

462

<para>Verify the correct application will be run. For example:</para>

463

464

<screen><prompt>$</prompt><userinput>which gedit</userinput>

465

/opt/gnome/bin/gedit</screen>

466

467

<para>Run the application:</para>

468

469

<screen><prompt>$</prompt><userinput>gedit &</userinput></screen>

470

471

<para>Alternatively, run the application using the

472

<command>run</command> command:</para>

473

474

<screen><prompt>$</prompt><userinput>jhbuild run gedit</userinput></screen>

475

</section>

476

477

478

<title>Running the GNOME Desktop Environment</title>

479

480

<para>Create a new user account to run the JHBuild GNOME. Running

481

JHBuild GNOME using different user account is recommended to avoid

482

problems caused by user settings stored in the home directory. This

483

manual refers to the new account as

484

<systemitem class="username">gnomedev</systemitem>.</para>

485

486

<para>Setup JHBuild on the new

487

<systemitem class="username">gnomedev</systemitem> account. Copy or

488

soft-link <filename>~/.jhbuildrc</filename> and

489

<filename>~/.local/bin/jhbuild</filename> to

490

<systemitem class="username">gnomedev</systemitem> home directory.

491

</para>

492

493

<para>Open a terminal as the user

494

<systemitem class="username">gnomedev</systemitem>. Permanently add

495

<filename>~/.local/bin</filename> to the <envar>PATH</envar> variable,

496

run the following command:</para>

497

498

<screen><prompt>$</prompt> <userinput>echo PATH=$PATH:~/.local/bin >> ~/.bashrc</userinput></screen>

499

500

<para>Test JHBuild works:</para>

501

502

<screen><prompt>$</prompt> <userinput>jhbuild run pkg-config gtk+-2.0 --modversion</userinput>

503

2.20.1</screen>

504

505

<para>There are two different methods to run JHBuild GNOME:</para>

506

507

508

509

<para>Nested window <emphasis>(recommended)</emphasis>.</para>

510

</listitem>

511

512

<para>Display manager.</para>

513

</listitem>

514

</orderedlist>

515

516

517

<title>Setup GNOME to run in a nested window</title>

518

519

<para>Build and install JHBuild GNOME.</para>

520

521

<para>Install the <application>Xephyr</application> application. On

522

Fedora the system package is called

523

<filename>xorg-x11-server-Xephyr</filename>, on Ubuntu and Debian the

524

system package is called <filename>xserver-xephyr</filename>.</para>

525

526

<para>Test <application>Xephyr</application> works:</para>

527

528

<screen><prompt>$</prompt><userinput>Xephyr -ac -screen 800x600 :1 2> /dev/null &</userinput></screen>

529

530

<para>If successful, a window with black background will be displayed.

531

Close the <application>Xephyr</application> window.</para>

532

533

<para>Enable system services. JHBuild GNOME will use the

534

<filename>/usr/bin</filename> system <application>D-Bus</application>

535

daemon and the system services within

536

<filename>/usr/share/dbus-1/system-services/</filename>. JHBuild GNOME

537

will use the JHBuild session <application>D-Bus</application> daemon

538

and the services within

539

<filename><replaceable>/opt/gnome</replaceable>/share/dbus-1/services/</filename>.

540

Replace <filename>/opt/gnome</filename> with GNOME install

541

<varname>prefix</varname> in the command below:</para>

542

543

<screen><prompt>$</prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>

544

<prompt>$</prompt><userinput>ln -s /var/run/dbus <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>

545

<prompt>$</prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput>

546

<prompt>$</prompt><userinput>ln -s /var/lib/dbus/machine-id <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput></screen>

547

548

<para>Create a GNOME startup script at

549

<filename>~/.local/bin/gnome-jhbuild-xephyr-session</filename> with

550

the following, replacing <filename>/opt/gnome</filename> with GNOME

551

install <varname>prefix</varname>:</para>

552

553

<programlisting>#!/bin/sh

554

555

GNOME=<replaceable>/opt/gnome</replaceable>

556

557

GDK_USE_XFT=1

558

XDG_DATA_DIRS=$XDG_DATA_DIRS:$GNOME/share

559

XDG_CONFIG_DIRS=$XDG_CONFIG_DIRS:$GNOME/etc/xdg

560

561

jhbuild run gnome-session

562

</programlisting>

563

564

<para>Make the file

565

<filename>~/.local/bin/gnome-jhbuild-xephyr-session</filename>

566

executable:</para>

567

568

<screen><prompt>$</prompt><userinput>chmod u+x ~/.local/bin/gnome-jhbuild-xephyr-session</userinput></screen>

569

</section>

570

571

572

<title>Running GNOME in a nested window</title>

573

574

<para>Open a terminal as the user

575

<systemitem class="username">gnomedev</systemitem>.</para>

576

577

<para>Run <application>Xephyr</application>:</para>

578

579

<screen><prompt># </prompt><userinput>Xephyr -ac -screen 800x600 :1 2> /dev/null &</userinput></screen>

580

581

<para>Set the <varname>DISPLAY</varname> environment variable:</para>

582

583

<screen><prompt># </prompt><userinput>export DISPLAY=:1</userinput></screen>

584

585

<para>Start GNOME:</para>

586

587

<screen><prompt># </prompt><userinput>gnome-jhbuild-xephyr-session</userinput></screen>

588

589

<para>If successful, JHBuild GNOME will be displayed in Xephyr window.

590

If unsuccessful, check the output of the terminal window.</para>

591

</section>

592

593

594

<title>Setup GNOME to run from the display manager</title>

595

596

<para>Build and install JHBuild GNOME.</para>

597

598

<para>Enable system services. JHBuild GNOME will use the

599

<filename>/usr/bin</filename> system <application>D-Bus</application>

600

daemon and the system services within

601

<filename>/usr/share/dbus-1/system-services/</filename>. JHBuild GNOME

602

will use the JHBuild session <application>D-Bus</application> daemon

603

and the services within

604

<filename><replaceable>/opt/gnome</replaceable>/share/dbus-1/services/</filename>.

605

Replace <filename>/opt/gnome</filename> with GNOME install

606

<varname>prefix</varname> in the command below:</para>

607

608

<screen><prompt>$</prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>

609

<prompt>$</prompt><userinput>ln -s /var/run/dbus <replaceable>/opt/gnome</replaceable>/var/run/dbus</userinput>

610

<prompt>$</prompt><userinput>rm -rf <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput>

611

<prompt>$</prompt><userinput>ln -s /var/lib/dbus/machine-id <replaceable>/opt/gnome</replaceable>/var/lib/dbus/machine-id</userinput></screen>

612

613

<para>Create a GNOME startup script at

614

<filename>/usr/bin/gnome-jhbuild-session</filename> with the

615

following, replacing <filename>/opt/gnome</filename> with GNOME

616

install <varname>prefix</varname>:</para>

617

618

<programlisting>#!/bin/sh

619

620

GNOME=<replaceable>/opt/gnome</replaceable>

621

622

GDK_USE_XFT=1

623

XDG_DATA_DIRS=$XDG_DATA_DIRS:$GNOME/share

624

XDG_CONFIG_DIRS=$XDG_CONFIG_DIRS:$GNOME/etc/xdg

625

626

jhbuild run gnome-session

627

</programlisting>

628

629

<para>Make the file

630

<filename>/usr/bin/gnome-jhbuild-session</filename> executable:</para>

631

632

<screen><prompt>$</prompt><userinput>chmod a+x /usr/bin/gnome-jhbuild-session</userinput></screen>

633

634

<para>To add a new session entry in the display manager, create

635

<filename>/usr/share/xsessions/gnome-jhbuild.desktop</filename> and

636

enter:</para>

637

638

<programlisting>[Desktop Entry]

639

Name=GNOME (JHBuild)

640

Comment=This session logs you into GNOME testing session

641

TryExec=/usr/bin/gnome-jhbuild-session

642

Exec=/usr/bin/gnome-jhbuild-session

643

Icon=

644

Type=Application</programlisting>

645

646

<para>Restart <command>gdm</command>.</para>

647

648

<para/>

649

</section>

650

651

652

<title>Running GNOME from the display manager</title>

653

654

<para>To run the JHBuild GNOME, select the GNOME (JHBuild) session at

655

the display manager before entering

656

<systemitem class="username">gnomedev</systemitem> login credentials.

657

If successful, JHBuild GNOME will be displayed. If unsuccessful, check

658

the log within the <filename>~gnomedev/.xsession-errors</filename>

659

file.</para>

660

</section>

661

</section>

662

</section>

663

664

665

<title>Buildbot Integration</title>

666

667

<para>Coupled with the <ulink url="http://buildbot.net">Buildbot</ulink>

668

project, JHBuild can also function as a continuous integration tool. The

669

Buildbot configuration is used by the GNOME project at

670

<ulink url="http://build.gnome.org">build.gnome.org</ulink>.</para>

671

672

673

<title>Configuring a Buildbot Slave</title>

674

675

<para>A Buildbot slave is a variation of a normal JHBuild installation

676

that serves the requests of a Buildbot master. It is recommended to set

677

up JHBuild and complete a build with most modules building successfully

678

before adding the Buildbot customizations.</para>

679

680

<para>Buildbot commands are options to the <command>bot</command>

681

command. To download and install the extra required software, run the

682

following command:</para>

683

684

<screen><prompt>$</prompt> <userinput>jhbuild bot --setup</userinput></screen>

685

686

<para>Once this step has completed successfully, three new configuration

687

variables are required in <filename>~/.jhbuildrc</filename>.</para>

688

689

<note>

690

<para>It is not possible to use an alternate configuration file, the

691

692

get desired effects.</para>

693

</note>

694

695

696

jhbuildbot_master = 'build.gnome.org:9070'

697

jhbuildbot_slavename = 'slavename'

698

jhbuildbot_password = 'password'

699

</programlisting>

700

701

<para><varname>jhbuildbot_master</varname> is a string specifying the

702

Buildbot master server; it defaults to

703

<literal>'build.gnome.org:9070'</literal>.

704

<varname>jhbuildbot_slavename</varname> and

705

<varname>jhbuildbot_password</varname> identify the slave on the master

706

server. Contact the Buildbot master administrators to obtain the slave

707

name and password.</para>

708

709

<note>

710

<para>The administrators of

711

<ulink url="http://build.gnome.org">build.gnome.org</ulink> can be

712

reached on the <ulink url="mailto:build-brigade-list@gnome.org">Build

713

Brigade mailing list</ulink>.</para>

714

</note>

715

</section>

716

717

<!-- TODO: configuring a buildbot master

718

719

<title>Configuring a Buildbot Master</title>

720

</section>

721

-->

722

</section>

723

724

725

<title>Kommandoreferens</title>

726

727

<para>JHBuild uses a command line syntax similar to tools like CVS:</para>

728

729

<cmdsynopsis><command>jhbuild</command>

730

<arg><replaceable>global-options</replaceable></arg>

731

<arg choice="plain"><replaceable>command</replaceable></arg>

732

<arg><replaceable>command-arguments</replaceable></arg>

733

</cmdsynopsis>

734

735

<para>The global JHBuild options are:</para>

736

737

738

739

740

741

<replaceable>config</replaceable>

742

</term>

743

744

<simpara>Use an alternative configuration file instead of the

745

default <filename>~/.jhbuildrc</filename>.</simpara>

746

</listitem>

747

</varlistentry>

748

749

<term>

750

<option>-m</option>, <option>--moduleset</option>

751

<replaceable>moduleset</replaceable>

752

</term>

753

754

<simpara>Use a module set other than the module set listed in the

755

configuration file. This option can be a relative path if the module

756

set is located in the JHBuild moduleset folder, or an absolute path

757

if located elsewhere.</simpara>

758

</listitem>

759

</varlistentry>

760

761

<term>

762

<option>--no-interact</option>

763

</term>

764

765

<simpara>Do not prompt the user for any input. This option is useful

766

if leaving a build unattended, in order to ensure the build is not

767

interrupted.</simpara>

768

</listitem>

769

</varlistentry>

770

</variablelist>

771

772

<para>Command specific options are listed below.</para>

773

774

775

<title>autobuild</title>

776

777

<para>The <command>autobuild</command> command automatically builds the

778

modules as specified in the configuration file, and then upload the

779

results to JhAutobuild.</para>

780

781

<cmdsynopsis><command>jhbuild autobuild</command>

782

<arg>--autogen</arg>

783

<arg>--clean</arg>

784

<arg>--distcheck</arg>

785

<arg rep="repeat">--skip=<replaceable>module</replaceable></arg>

786

<arg>--start-at=<replaceable>module</replaceable></arg>

787

<arg>--report-url=<replaceable>reporturl</replaceable></arg>

788

<arg>--verbose</arg>

789

</cmdsynopsis>

790

791

<para>The <option>--autogen</option>, <option>--clean</option>,

792

<option>--distcheck</option>, <option>--skip</option> and

793

<option>--start-at</option> options are processed as per the

794

795

command.</para>

796

797

798

799

<term>

800

<option>--report-url=<replaceable>reporturl</replaceable></option>,

801

<option>-r <replaceable>reporturl</replaceable></option>

802

</term>

803

804

<simpara>This option specifies the JhAutobuild URL to report to.

805

</simpara>

806

</listitem>

807

</varlistentry>

808

809

<term>

810

<option>--verbose</option>, <option>-v</option>

811

</term>

812

813

<simpara>If specified, JHBuild's output will be more verbose.

814

</simpara>

815

</listitem>

816

</varlistentry>

817

</variablelist>

818

</section>

819

820

821

<title>bootstrap</title>

822

823

<para>The <command>bootstrap</command> command installs a set of build

824

utilities required to build most modules (e.g.

825

<application>autoconf</application>,

826

<application>automake</application>, etc).</para>

827

828

<cmdsynopsis><command>jhbuild bootstrap</command>

829

</cmdsynopsis>

830

831

<para>The <command>bootstrap</command> command builds modules using the

832

same method as the <command>build</command> command, but uses the

833

<filename>bootstrap.modules</filename> moduleset.</para>

834

835

<para>See the

836

837

command documentation for available options.</para>

838

</section>

839

840

841

<title>build</title>

842

843

<para>The <command>build</command> command builds one or more packages,

844

including their dependencies.</para>

845

846

<cmdsynopsis><command>jhbuild build</command>

847

<arg>--autogen</arg>

848

<arg>--clean</arg>

849

<arg>--check</arg>

850

851

<arg>--distcheck</arg>

852

<arg>--ignore-suggests</arg>

853

<arg>--no-network</arg>

854

<arg rep="repeat">--skip=<replaceable>module</replaceable></arg>

855

<arg>--start-at=<replaceable>module</replaceable></arg>

856

857

858

859

<arg>--try-checkout</arg>

860

<arg>--no-poison</arg>

861

<arg>--force</arg>

862

<arg>--build-optional-modules</arg>

863

864

<arg rep="repeat">module</arg>

865

</cmdsynopsis>

866

867

<para>If no module names are provided on the command line, the

868

869

file will be used.</para>

870

871

872

873

<term>

874

<option>-a</option>, <option>--autogen</option>

875

</term>

876

877

<simpara>Always run <command>autogen.sh</command> before building

878

modules. By default, <command>autogen.sh</command> will only be

879

called if the top-level makefile is missing. Otherwise, JHBuild

880

relies on the package's makefiles to detect if configure needs to

881

be rebuilt or rerun.</simpara>

882

</listitem>

883

</varlistentry>

884

885

<term>

886

<option>-c</option>, <option>--clean</option>

887

</term>

888

889

<simpara>Run <command>make clean</command> before building

890

modules.</simpara>

891

</listitem>

892

</varlistentry>

893

894

<term>

895

<option>--check</option>

896

</term>

897

898

<simpara>Run <command>make check</command> after building modules.

899

</simpara>

900

</listitem>

901

</varlistentry>

902

903

<term>

904

905

</term>

906

907

<simpara>Run <command>make dist</command> after building modules.

908

</simpara>

909

</listitem>

910

</varlistentry>

911

912

<term>

913

<option>--distcheck</option>

914

</term>

915

916

<simpara>Run <command>make distcheck</command> after building

917

modules.</simpara>

918

</listitem>

919

</varlistentry>

920

921

<term>

922

<option>--ignore-suggests</option>

923

</term>

924

925

<simpara>Do not build soft dependencies.</simpara>

926

</listitem>

927

</varlistentry>

928

929

<term>

930

<option>-n</option>, <option>--no-network</option>

931

</term>

932

933

<simpara>Do not access the network when building modules. This

934

will skip download or update stages in a build. If a module can't

935

be built without network access, the module build will fail.

936

</simpara>

937

</listitem>

938

</varlistentry>

939

940

<term>

941

<option>-s</option>,

942

<option>--skip</option>=<replaceable>module,...</replaceable>

943

</term>

944

945

<simpara>Do not build the listed modules. Used to skip the

946

building of specified dependencies.</simpara>

947

</listitem>

948

</varlistentry>

949

950

<term>

951

952

</term>

953

954

<simpara>Ignore modules that do not match

955

<replaceable>tag</replaceable>. Modules are automatically

956

attributed a tag matching the name of the module's module set.

957

</simpara>

958

</listitem>

959

</varlistentry>

960

961

<term>

962

<option>-t</option>,

963

<option>--start-at</option>=<replaceable>module</replaceable>

964

</term>

965

966

<simpara>Start at the named module rather than at the beginning of

967

the list. This option is useful if the build was interrupted.

968

</simpara>

969

</listitem>

970

</varlistentry>

971

972

<term>

973

974

</term>

975

976

<simpara>If supported by the underlying version control system,

977

update the source tree to the specified date before building. An

978

ISO date format is required, e.g. <literal>"2009-09-18

979

02:32Z"</literal>.</simpara>

980

</listitem>

981

</varlistentry>

982

983

<term>

984

985

</term>

986

987

<simpara>Run graphical tests on the actual X server rather than in

988

a simulated Xvfb.</simpara>

989

</listitem>

990

</varlistentry>

991

992

<term>

993

<option>-C</option>, <option>--try-checkout</option>

994

</term>

995

996

<simpara>If the build fails, and if supported by the version

997

control system, force a checkout and run

998

<command>autogen.sh</command> before retrying the build.</simpara>

999

</listitem>

1000

</varlistentry>

1001

1002

<term>

1003

<option>-N</option>, <option>--no-poison</option>

1004

</term>

1005

1006

<simpara>If one or more of a module's dependencies failed, this

1007

option forces JHBuild to try to build the module anyway.</simpara>

1008

</listitem>

1009

</varlistentry>

1010

1011

<term>

1012

<option>-f</option>, <option>--force</option>

1013

</term>

1014

1015

<simpara>Build the modules even if policy states it is not

1016

required.</simpara>

1017

</listitem>

1018

</varlistentry>

1019

1020

<term>

1021

<option>--build-optional-modules</option>

1022

</term>

1023

1024

<simpara>Modules listed as optional dependencies, may not be

1025

required to build the module. This option forces JHBuild to build

1026

optional dependencies.</simpara>

1027

</listitem>

1028

</varlistentry>

1029

1030

<term>

1031

1032

</term>

1033

1034

<simpara>Skip modules installed more recently than the specified

1035

relative time. The <replaceable>time</replaceable> string format

1036

is a number followed by a unit. The following units are supported:

1037

seconds (s), minutes (m), hours (h) and days (d). For example,

1038

<option>--min-age=2h</option> will skip modules built less than

1039

two hours ago.</simpara>

1040

</listitem>

1041

</varlistentry>

1042

</variablelist>

1043

</section>

1044

1045

1046

<title>buildone</title>

1047

1048

<para>The <command>buildone</command> command is similar to

1049

<command>build</command>, but it does not build the dependent modules.

1050

It is useful for rebuilding one or more modules.</para>

1051

1052

<cmdsynopsis><command>jhbuild buildone</command>

1053

<arg>--autogen</arg>

1054

<arg>--clean</arg>

1055

<arg>--check</arg>

1056

<arg>--distcheck</arg>

1057

<arg>--no-network</arg>

1058

1059

1060

<arg>--force</arg>

1061

1062

<arg choice="plain" rep="repeat">module</arg>

1063

</cmdsynopsis>

1064

1065

<para>The <option>--autogen</option>, <option>--check</option>,

1066

<option>--clean</option>, <option>-d</option>,

1067

<option>--distcheck</option>, <option>--no-network</option>,

1068

<option>-D</option> and <option>-x</option> options are processed as per

1069

the

1070

1071

command.</para>

1072

1073

<para>At least one module must be listed on the command line.</para>

1074

</section>

1075

1076

1077

<title>checkbranches</title>

1078

1079

<para>The <command>checkbranches</command> checks the module's branches

1080

are defined correctly within the version control system and the branches

1081

are consistent with the module set.</para>

1082

1083

<cmdsynopsis><command>jhbuild checkbranches</command>

1084

<arg rep="repeat">--branch=<replaceable>branch</replaceable></arg>

1085

</cmdsynopsis>

1086

1087

1088

1089

<term>

1090

<option>--branch</option>=<replaceable>branch</replaceable>,

1091

<option>-b</option> <replaceable>branch</replaceable>

1092

</term>

1093

1094

<simpara>The branch to check.</simpara>

1095

</listitem>

1096

</varlistentry>

1097

</variablelist>

1098

1099

<screen><prompt>$</prompt> <userinput>jhbuild -m gnome-2.20 checkbranches</userinput>

1100

libgnomecanvas is missing branch definition for gnome-2-20

1101

1102

</section>

1103

1104

1105

<title>clean</title>

1106

1107

<para>The <command>clean</command> command cleans the build directories

1108

of one or more modules.</para>

1109

1110

<cmdsynopsis><command>jhbuild clean</command>

1111

<arg rep="repeat">--skip=<replaceable>module</replaceable></arg>

1112

<arg>--start-at=<replaceable>module</replaceable></arg>

1113

</cmdsynopsis>

1114

1115

<para>If no module names are provided on the command line, the

1116

1117

file will be used.</para>

1118

1119

<para>See the

1120

1121

command documentation for a description of available options.</para>

1122

</section>

1123

1124

1125

1126

1127

<para>The <command>dot</command> command generates a file describing the

1128

directed graph formed by the dependencies between a set of modules. This

1129

file can then be processed using the

1130

<ulink url="http://www.graphviz.org/">GraphViz</ulink> software to

1131

produce a diagram.</para>

1132

1133

<cmdsynopsis><command>jhbuild dot</command>

1134

1135

<arg>--clusters</arg>

1136

<arg rep="repeat">module</arg>

1137

</cmdsynopsis>

1138

1139

<para>If no module names are provided on the command line, the

1140

1141

file will be used.</para>

1142

1143

<para>The <option>--soft-deps</option> option adds dotted lines from the

1144

modules to the soft dependencies. The <option>--clusters</option> option

1145

groups modules from

1146

1147

together.</para>

1148

1149

<para>The output of the dot command can be piped to the dot utility to

1150

generate a PostScript file:</para>

1151

1152

<screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tps > dependencies.ps</userinput></screen>

1153

1154

<para>Or a PNG image:</para>

1155

1156

<screen><prompt>$</prompt> <userinput>jhbuild dot <replaceable>modules</replaceable> | dot -Tpng > dependencies.png</userinput></screen>

1157

1158

1159

<title>Sample JHBuild dot output</title>

1160

1161

1162

1163

1164

</imageobject>

1165

</mediaobject>

1166

</screenshot>

1167

</figure>

1168

</section>

1169

1170

1171

1172

1173

<para>The <command>gui</command> command starts a graphical interface to

1174

JHBuild which can be used to select modules to build and change some

1175

options.</para>

1176

1177

<cmdsynopsis><command>jhbuild gui</command>

1178

</cmdsynopsis>

1179

1180

<para>The graphical interface is rendered using GTK, so extra support

1181

libraries are required.</para>

1182

</section>

1183

1184

1185

1186

1187

<para>The <command>info</command> command displays information about one

1188

or more modules.</para>

1189

1190

<cmdsynopsis><command>jhbuild info</command>

1191

<arg choice="plain" rep="repeat">module</arg>

1192

</cmdsynopsis>

1193

1194

<para>The command displays the module name, type, dependencies,

1195

dependent packages, the source directory, and the time it was last

1196

installed with JHBuild. If available, information specific to the module

1197

type such as the CVS repository or download URL will also be displayed.

1198

</para>

1199

1200

<para>If there is no module specified the command will display

1201

information about all the modules defined in the module set.</para>

1202

</section>

1203

1204

1205

1206

1207

<para>The <command>list</command> command displays the expanded list of

1208

modules the <command>build</command> command would build.</para>

1209

1210

<cmdsynopsis><command>jhbuild list</command>

1211

1212

1213

1214

<arg>--start-at=<replaceable>module</replaceable></arg>

1215

1216

<arg>--ignore-suggests</arg>

1217

<arg>--list-optional-modules</arg>

1218

<arg rep="repeat">module</arg>

1219

</cmdsynopsis>

1220

1221

<para>If no module names are provided on the command line, the

1222

1223

file will be used.</para>

1224

1225

<para>The <option>--skip</option>, <option>--start-at</option>,

1226

<option>--tags</option>, and <option>--ignore-suggests</option> options

1227

are processed as per the

1228

1229

command.</para>

1230

1231

1232

1233

<term>

1234

<option>-a</option>, <option>--all-modules</option>

1235

</term>

1236

1237

<simpara>List all the modules from the module set regardless of

1238

the build dependencies.</simpara>

1239

</listitem>

1240

</varlistentry>

1241

1242

<term>

1243

<option>-r</option>, <option>--show-revision</option>

1244

</term>

1245

1246

<simpara>If a module is set to a branch, show the branch name with

1247

the module name.</simpara>

1248

</listitem>

1249

</varlistentry>

1250

1251

<term>

1252

<option>--list-optional-modules</option>

1253

</term>

1254

1255

<simpara>This option forces JHBuild to list optional dependencies.

1256

</simpara>

1257

</listitem>

1258

</varlistentry>

1259

</variablelist>

1260

</section>

1261

1262

1263

<title>rdepends</title>

1264

1265

<para>The <command>rdepends</command> command displays the reverse

1266

dependencies of a module.</para>

1267

1268

<cmdsynopsis><command>jhbuild rdepends</command>

1269

<arg>module</arg>

1270

</cmdsynopsis>

1271

1272

1273

1274

<term>

1275

<option>--dependencies</option>

1276

</term>

1277

1278

<simpara>Show dependency path next to modules.</simpara>

1279

</listitem>

1280

</varlistentry>

1281

1282

<term>

1283

<option>--direct</option>

1284

</term>

1285

1286

<simpara>Limit display to modules directly depending on specified

1287

module.</simpara>

1288

</listitem>

1289

</varlistentry>

1290

</variablelist>

1291

</section>

1292

1293

1294

1295

1296

<para>The <command>run</command> command runs the specified command

1297

using the same environment that JHBuild uses when building modules.

1298

</para>

1299

1300

<cmdsynopsis><command>jhbuild run</command>

1301

<arg>--in-builddir</arg>

1302

<arg>--in-checkoutdir</arg>

1303

<arg choice="plain"><replaceable>program</replaceable></arg>

1304

<arg rep="repeat"><replaceable>argument</replaceable></arg>

1305

</cmdsynopsis>

1306

1307

<para>If using JHBuild to build GNOME, this command can be useful in X

1308

startup scripts.</para>

1309

1310

1311

1312

<term>

1313

<option>--in-builddir</option>=<replaceable>module</replaceable>

1314

</term>

1315

1316

<simpara>Run the command in the build directory of the specified

1317

module.</simpara>

1318

</listitem>

1319

</varlistentry>

1320

</variablelist>

1321

1322

1323

1324

<term>

1325

<option>--in-checkoutdir</option>=<replaceable>module</replaceable>

1326

</term>

1327

1328

<simpara>Run the command in the source directory of the specified

1329

module.</simpara>

1330

</listitem>

1331

</varlistentry>

1332

</variablelist>

1333

</section>

1334

1335

1336

<title>sanitycheck</title>

1337

1338

<para>The <command>sanitycheck</command> command performs a number of

1339

checks to verify the build environment is okay.</para>

1340

1341

<cmdsynopsis><command>jhbuild sanitycheck</command>

1342

</cmdsynopsis>

1343

1344

<para>Some of the checks include:</para>

1345

1346

1347

1348

<simpara>The checkout and install prefixes are writable.</simpara>

1349

</listitem>

1350

1351

<simpara>The required build tools are installed.</simpara>

1352

</listitem>

1353

1354

<simpara>Some commonly used macros are available in the search paths

1355

of the <command>aclocal</command> commands associated with the

1356

various versions of <command>automake</command>.</simpara>

1357

</listitem>

1358

1359

<simpara>The XML catalog contains the DocBook DTD and stylesheets.

1360

</simpara>

1361

</listitem>

1362

</itemizedlist>

1363

</section>

1364

1365

1366

<title>shell</title>

1367

1368

<para>The <command>shell</command> command starts the user's shell with

1369

the same environment as JHBuild uses when building modules.</para>

1370

1371

<cmdsynopsis><command>jhbuild shell</command>

1372

</cmdsynopsis>

1373

1374

<para>This command is equivalent to the following:</para>

1375

1376

<screen><prompt>$</prompt> <userinput>jhbuild run $SHELL</userinput></screen>

1377

1378

<para>The <envar>UNDER_JHBUILD</envar> environment variable will be set

1379

to "true" when this shell is active. You can use the presence of that

1380

variable to customize your shell's prompt to indicate that you indeed

1381

are under a jhbuild-controlled shell. For example, you may want to put

1382

this in your <filename>.bashrc</filename>:</para>

1383

1384

1385

if [ -n "$UNDER_JHBUILD" ]; then

1386

PS1="[jhbuild] $PS1"

1387

fi

1388

</screen>

1389

1390

<para>This will make your bash shell display

1391

<literal>[jhbuild]</literal> before your normal prompt, making it easier

1392

to see which shells are under a jhbuild environment.</para>

1393

</section>

1394

1395

1396

<title>sysdeps</title>

1397

1398

<para>The <command>sysdeps</command> command displays a list of

1399

dependency modules that are provided by installed system packages.

1400

JHBuild will not build the modules from source if the configuration

1401

variable

1402

1403

is <constant>True</constant>.</para>

1404

1405

<para>The <command>sysdeps</command> command also displays a list of

1406

dependency modules where the installed system packages are too old.

1407

JHBuild will build newer modules from source.</para>

1408

1409

<para>The <command>sysdeps</command> command also displays a list of

1410

dependency modules with no matching system package installed.</para>

1411

1412

<cmdsynopsis><command>jhbuild sysdeps</command>

1413

<arg>--install</arg>

1414

</cmdsynopsis>

1415

1416

1417

1418

<term>

1419

<option>--install</option>

1420

</term>

1421

1422

<simpara>This option installs system packages which are

1423

dependencies of the moduleset. The system packages are installed

1424

using <application>PackageKit</application>.</simpara>

1425

</listitem>

1426

</varlistentry>

1427

</variablelist>

1428

1429

1430

<title><command>sysdeps</command> example</title>

1431

<screen><prompt>$</prompt> <userinput>jhbuild sysdeps</userinput>

1432

System installed packages which are new enough:

1433

speex (required=1.2rc1, installed=1.2rc1)

1434

libdiscid (required=0.2.2, installed=0.2.2)

1435

telepathy-farsight (required=0.0.14, installed=0.0.16)

1436

lcms2 (required=2.2, installed=2.2)

1437

...

1438

System installed packages which are too old:

1439

webkitgtk-3.0 (required=1.5.1, installed=1.4.0)

1440

...

1441

No matching system package installed:

1442

libvala-0.14 (required=0.13.1)

1443

...</screen>

1444

</example>

1445

</section>

1446

1447

1448

<title>tinderbox</title>

1449

1450

<para>The <command>tinderbox</command> command is similar to

1451

<command>build</command>, but writes all terminal output to HTML files

1452

suitable for publishing on a website. It can be used to set up systems

1453

similar to Mozilla's Tinderbox, or Debian's Buildd.</para>

1454

1455

<cmdsynopsis><command>jhbuild tinderbox</command>

1456

<arg>--autogen</arg>

1457

<arg>--clean</arg>

1458

<arg>--no-network</arg>

1459

<arg>--output=<replaceable>directory</replaceable></arg>

1460

<arg rep="repeat">--skip=<replaceable>module</replaceable></arg>

1461

<arg>--start-at=<replaceable>module</replaceable></arg>

1462

1463

1464

1465

1466

<arg rep="repeat">module</arg>

1467

</cmdsynopsis>

1468

1469

<para>The <option>--autogen</option>, <option>--clean</option>,

1470

<option>--no-network</option>, <option>--skip</option>,

1471

<option>--start-at</option>, <option>-D</option>, <option>-C</option>,

1472

<option>-N</option> and <option>-f</option> options are processed as per

1473

the

1474

1475

command.</para>

1476

1477

1478

1479

<term>

1480

<option>-o</option>,

1481

<option>--output</option>=<replaceable>directory</replaceable>

1482

</term>

1483

1484

<simpara>The directory to write the HTML files.</simpara>

1485

</listitem>

1486

</varlistentry>

1487

</variablelist>

1488

</section>

1489

1490

1491

<title>uninstall</title>

1492

1493

<para>The <command>uninstall</command> command uninstalls one or more

1494

modules.</para>

1495

1496

<cmdsynopsis><command>jhbuild uninstall</command>

1497

<arg choice="plain" rep="repeat">module</arg>

1498

</cmdsynopsis>

1499

</section>

1500

1501

1502

<title>update</title>

1503

1504

<para>The <command>update</command> command is similar to

1505

<command>build</command>, but only performs the download or update stage

1506

for modules without building them.</para>

1507

1508

<cmdsynopsis><command>jhbuild update</command>

1509

<arg rep="repeat">--skip=<replaceable>module</replaceable></arg>

1510

<arg>--start-at=<replaceable>module</replaceable></arg>

1511

1512

<arg>--ignore-suggests</arg>

1513

1514

<arg rep="repeat">module</arg>

1515

</cmdsynopsis>

1516

1517

<para>The <option>--skip</option>, <option>--start-at</option>,

1518

<option>--tags</option>, <option>--ignore-suggests</option> and

1519

<option>-D</option> options are processed as per the

1520

1521

command.</para>

1522

</section>

1523

1524

1525

<title>updateone</title>

1526

1527

<para>The <command>updateone</command> command is similar to

1528

<command>update</command>, but it does not update the dependent modules.

1529

It is useful for updating one or more modules.</para>

1530

1531

<cmdsynopsis><command>jhbuild updateone</command>

1532

1533

<arg choice="plain" rep="repeat">module</arg>

1534

</cmdsynopsis>

1535

1536

<para>The <option>-D</option> option is processed as per the

1537

1538

command.</para>

1539

1540

<para>At least one module must be listed on the command line.</para>

1541

</section>

1542

</section>

1543

1544

1545

<title>Configuration File Reference</title>

1546

1547

<para>The <filename>~/.jhbuildrc</filename> file uses standard Python

1548

syntax. The file is run, and the resulting variables defined in the

1549

namespace are used to control how JHBuild acts. A set of default values

1550

are inserted into the namespace before running the user's configuration

1551

file.</para>

1552

1553

<para>Boolean configuration variables are set using syntax as demonstrated

1554

in the following example:</para>

1555

1556

<programlisting>use_local_modulesets = True</programlisting>

1557

1558

<para>String configuration variables are set using syntax as demonstrated

1559

in the following example:</para>

1560

1561

<programlisting>autogenargs = '--disable-static --disable-gtk-doc'</programlisting>

1562

1563

<para>List configuration variables are set using syntax as demonstrated in

1564

the following example:</para>

1565

1566

<programlisting>skip = ['mozilla', 'pulseaudio']</programlisting>

1567

1568

<para>Dictionary configuration variables are set using syntax as

1569

demonstrated in the following example:</para>

1570

1571

<programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>

1572

1573

1574

<title>Configuration Variables</title>

1575

1576

1577

<?dbhtml list-presentation="table"?>

1578

1579

1580

<varname>alwaysautogen</varname>

1581

</term>

1582

1583

<simpara>A boolean value if set to <constant>True</constant>,

1584

always run <command>autogen.sh</command> before

1585

<command>make</command>, even if a makefile exists. This is

1586

equivalent to passing <option>--always-autogen</option> option to

1587

JHBuild. Defaults to <constant>False</constant>.</simpara>

1588

</listitem>

1589

</varlistentry>

1590

1591

1592

<varname>autogenargs</varname>

1593

</term>

1594

1595

<simpara>A string containing arguments passed to the

1596

<command>autogen.sh</command> script of all modules. Can be

1597

overridden for particular modules using the

1598

<varname>module_autogenargs</varname> dictionary.</simpara>

1599

</listitem>

1600

</varlistentry>

1601

1602

1603

<varname>branches</varname>

1604

</term>

1605

1606

<simpara>A dictionary specifying which branch to use for specific

1607

modules. This is useful if you are making some changes on a branch

1608

of a module and want JHBuild to build that branch instead of the

1609

one listed in the module set.</simpara>

1610

1611

<simpara>The definition of branches depends on the module VCS:

1612

</simpara>

1613

1614

1615

1616

<simpara>CVS: revision. E.g.

1617

<literal>'BRANCH-PROJECT-0_8'</literal></simpara>

1618

</listitem>

1619

1620

<simpara>Bazaar: URI of module branch. E.g.

1621

<literal>'http://bzr.example.net/project/gnome-2-28'</literal>

1622

</simpara>

1623

</listitem>

1624

1625

<simpara>Git: tuple, with first part being an optional

1626

repository (or the None value) and the second part the name of

1627

the branch. E.g. <literal>('git://git.example.net/project',

1628

'gnome-2-28')</literal></simpara>

1629

1630

1631

<title>Simple example</title>

1632

<programlisting>branches['modulename'] = (None, 'branchname')</programlisting>

1633

</example>

1634

</listitem>

1635

1636

<simpara>Subversion: URI of module branch E.g.

1637

<literal>'svn://svn.example.net/project/gnome-2-28'</literal>

1638

</simpara>

1639

</listitem>

1640

</itemizedlist>

1641

</listitem>

1642

</varlistentry>

1643

1644

1645

<varname>builddir_pattern</varname>

1646

</term>

1647

1648

<simpara>A <function>printf</function> style formatting pattern

1649

used to generate build directory names. This is only used when

1650

using separate source and build trees. The <literal>%s</literal>

1651

in the format string will be replaced with

1652

<varname>checkoutdir</varname>. Defaults to

1653

1654

</listitem>

1655

</varlistentry>

1656

1657

1658

<varname>buildroot</varname>

1659

</term>

1660

1661

<simpara>A string specifying the parent directory to place build

1662

trees. Defaults to <constant>None</constant>, which causes builds

1663

to be performed within the source trees.</simpara>

1664

</listitem>

1665

</varlistentry>

1666

1667

1668

<varname>buildscript</varname>

1669

</term>

1670

1671

<simpara>A string specifying which buildscript to use. The

1672

recommended setting is the default, <literal>terminal</literal>.

1673

In particular, do not set to <literal>gtk</literal>.</simpara>

1674

</listitem>

1675

</varlistentry>

1676

1677

1678

<varname>build_policy</varname>

1679

</term>

1680

1681

<simpara>A string specifying which modules to build. The three

1682

possible options are <literal>all</literal>, to build all modules

1683

requested, <literal>updated</literal> to build only modules which

1684

have changed, or <literal>updated-deps</literal> to build modules

1685

which have changed or which have dependencies which have changed.

1686

Defaults to <literal>updated-deps</literal>.</simpara>

1687

</listitem>

1688

</varlistentry>

1689

1690

1691

<varname>checkoutroot</varname>

1692

</term>

1693

1694

<simpara>A string specifying the directory to unpack source trees

1695

to. Unless <varname>buildroot</varname> is set, builds will occur

1696

in this directory too. Defaults to

1697

<filename>~/checkout/gnome</filename>.</simpara>

1698

</listitem>

1699

</varlistentry>

1700

1701

1702

<varname>checkout_mode</varname>

1703

</term>

1704

1705

<simpara>A string specifying how the checkout is performed for

1706

directories in version control. Defaults to

1707

<literal>update</literal>. This can be set per module using

1708

<varname>module_checkout_mode</varname>. Possible values are

1709

<literal>update</literal> (update checkout directory),

1710

<literal>clobber</literal> (wipe out directory before checking out

1711

the sources), <literal>export</literal> (wipe out directory then

1712

create an unversioned copy of the sources) and

1713

<literal>copy</literal> (checkout in a directory different from

1714

the one it will build).</simpara>

1715

</listitem>

1716

</varlistentry>

1717

1718

1719

1720

</term>

1721

1722

<simpara>A string specifying the directory to copy to, if the copy

1723

1724

<varname>checkout_mode</varname></link> is in use. Defaults to the

1725

checkout directory.</simpara>

1726

</listitem>

1727

</varlistentry>

1728

1729

1730

<varname>cvs_program</varname>

1731

</term>

1732

1733

<simpara>A string specifying which program to use for CVS support.

1734

This can be <literal>git-cvsimport</literal>, or

1735

<literal>cvs</literal>. Defaults to <literal>cvs</literal>.

1736

</simpara>

1737

</listitem>

1738

</varlistentry>

1739

1740

1741

<varname>dvcs_mirror_dir</varname>

1742

</term>

1743

1744

<simpara>A string specifying a local mirror directory. JHBuild

1745

will create local mirrors of repositories at the specified

1746

directory. The mirrors can be shared by multiple repository

1747

groups, saving space and time because hard-links will be used for

1748

local clones. The commands <command>update</command> and

1749

<command>updateone</command> will create the mirrors and fetch new

1750

commits from the online repositories. This option is only

1751

supported by Git and Bazaar repositories.</simpara>

1752

</listitem>

1753

</varlistentry>

1754

1755

1756

<varname>installprog</varname>

1757

</term>

1758

1759

<simpara>A string specifying a program to use as replacement for

1760

<literal>/usr/bin/install</literal>. If available, defaults to the

1761

<literal>install-check</literal> wrapper provided by JHBuild. The

1762

<literal>install-check</literal> wrapper optimizes header

1763

installation to reduce the time taken for rebuilds.</simpara>

1764

</listitem>

1765

</varlistentry>

1766

1767

1768

<varname>ignore_suggests</varname>

1769

</term>

1770

1771

<simpara>A boolean value specifying whether to ignore soft

1772

dependencies when calculating the dependency tree. Defaults to

1773

<constant>False</constant>.</simpara>

1774

</listitem>

1775

</varlistentry>

1776

1777

1778

<varname>interact</varname>

1779

</term>

1780

1781

<simpara>A boolean value specifying whether to interact with the

1782

user. Setting this value to <constant>False</constant> is

1783

equivalent to passing the <option>--no-interact</option> option.

1784

Defaults to <constant>True</constant>.</simpara>

1785

</listitem>

1786

</varlistentry>

1787

1788

1789

<varname>makeargs</varname>

1790

</term>

1791

1792

<simpara>A string listing additional arguments to be passed to

1793

<command>make</command>. Defaults to <literal>''</literal>.

1794

</simpara>

1795

</listitem>

1796

</varlistentry>

1797

1798

1799

<varname>makecheck</varname>

1800

</term>

1801

1802

<simpara>A boolean value specifying whether to run <command>make

1803

check</command> after <command>make</command>. Defaults to

1804

<constant>False</constant>.</simpara>

1805

</listitem>

1806

</varlistentry>

1807

1808

1809

<varname>makecheck_advisory</varname>

1810

</term>

1811

1812

<simpara>A boolean value specifying whether failures when running

1813

<command>make check</command> should be advisory only and not

1814

cause a build failure. Defaults to <constant>False</constant>.

1815

</simpara>

1816

</listitem>

1817

</varlistentry>

1818

1819

1820

<varname>makeclean</varname>

1821

</term>

1822

1823

<simpara>A boolean value specifying whether to run <command>make

1824

clean</command> before <command>make</command>. Defaults to

1825

<constant>False</constant>.</simpara>

1826

</listitem>

1827

</varlistentry>

1828

1829

1830

<varname>makedist</varname>

1831

</term>

1832

1833

<simpara>A boolean value specifying whether to run <command>make

1834

dist</command> after <command>make</command>. Defaults to

1835

<constant>False</constant>. This setting is equivalent to passing

1836

the <option>--dist</option> option.</simpara>

1837

</listitem>

1838

</varlistentry>

1839

1840

1841

<varname>makedistcheck</varname>

1842

</term>

1843

1844

<simpara>A boolean value specifying whether to run <command>make

1845

distcheck</command> after <command>make</command>. Defaults to

1846

<constant>False</constant>. This setting is equivalent to passing

1847

the <option>--distcheck</option> option.</simpara>

1848

</listitem>

1849

</varlistentry>

1850

1851

1852

<varname>module_autogenargs</varname>

1853

</term>

1854

1855

<simpara>A dictionary mapping module names to strings specifying

1856

the arguments to be passed to <command>autogen.sh</command>. The

1857

setting in <varname>module_autogenargs</varname> is used instead

1858

of the global <varname>autogenargs</varname> setting. If a

1859

particular module isn't listed in the dictionary, the global

1860

<varname>autogenargs</varname> will be used.</simpara>

1861

</listitem>

1862

</varlistentry>

1863

1864

1865

<varname>module_checkout_mode</varname>

1866

</term>

1867

1868

<simpara>A dictionary specifying which checkout mode to use for

1869

modules. This overrides the global

1870

<varname>checkout_mode</varname> setting.</simpara>

1871

</listitem>

1872

</varlistentry>

1873

1874

1875

<varname>module_makeargs</varname>

1876

</term>

1877

1878

<simpara>A dictionary mapping module names to strings specifying

1879

the arguments to pass to <command>make</command>. The setting in

1880

<varname>module_makeargs</varname> replaces the value of

1881

<varname>makeargs</varname>. If a particular module isn't listed

1882

in the dictionary, the global <varname>makeargs</varname> will be

1883

used.</simpara>

1884

</listitem>

1885

</varlistentry>

1886

1887

1888

<varname>module_makecheck</varname>

1889

</term>

1890

1891

<simpara>A dictionary mapping module names to boolean values

1892

specifying whether to run <command>make check</command> after

1893

<command>make</command>. The setting in

1894

<varname>module_makecheck</varname> replaces the value of

1895

<varname>makecheck</varname>. If a particular module isn't listed

1896

in the dictionary, the global <varname>makecheck</varname> will be

1897

used.</simpara>

1898

</listitem>

1899

</varlistentry>

1900

1901

1902

<varname>module_nopoison</varname>

1903

</term>

1904

1905

<simpara>A dictionary mapping module names to boolean values. If a

1906

module is set to <constant>True</constant>, JHBuild will attempt

1907

to build dependent modules even if the specified module failed.

1908

The setting in <varname>module_nopoison</varname> replaces the

1909

value of <varname>nopoison</varname>. If a particular module isn't

1910

listed in the dictionary, the global <varname>nopoison</varname>

1911

will be used.</simpara>

1912

</listitem>

1913

</varlistentry>

1914

1915

1916

<varname>module_extra_env</varname>

1917

</term>

1918

1919

<simpara>A dictionary mapping module names to dictionaries with

1920

extra environment variables to pass when executing commands for

1921

the module.</simpara>

1922

</listitem>

1923

</varlistentry>

1924

1925

1926

<varname>modules</varname>

1927

</term>

1928

1929

<simpara>A list of strings specifying the modules to build. The

1930

list of modules actually built will be recursively expanded to

1931

include all the dependencies unless the

1932

1933

<command>buildone</command></link> command is used. Defaults to

1934

<literal>['meta-gnome-desktop']</literal>.</simpara>

1935

</listitem>

1936

</varlistentry>

1937

1938

1939

<varname>moduleset</varname>

1940

</term>

1941

1942

<simpara>A string or list of strings specifying the name(s) of the

1943

module set(s) to use. This can either be the filename of a

1944

moduleset included with JHBuild (excluding the path and

1945

extension), or a full HTTP URL to an externally managed moduleset.

1946

HTTP URL modulesets are cached locally. If a module with the same

1947

name is present in more than one moduleset, the last set listed

1948

takes priority. Modulesets provided with JHBuild are updated to

1949

match the current GNOME development release.</simpara>

1950

</listitem>

1951

</varlistentry>

1952

1953

1954

<varname>modulesets_dir</varname>

1955

</term>

1956

1957

<simpara>A string specifying the directory containing the

1958

modulesets to use. Defaults to the

1959

<filename>modulesets/</filename> directory in JHBuild sources.

1960

</simpara>

1961

</listitem>

1962

</varlistentry>

1963

1964

1965

<varname>nice_build</varname>

1966

</term>

1967

1968

<simpara>Run builds under the <constant>SCHED_IDLE</constant>

1969

priority on Linux, <command>nice</command> on other Unix. This can

1970

dramatically improve desktop interactivity for parallel builds

1971

while having only a negligible impact on build throughput.

1972

</simpara>

1973

</listitem>

1974

</varlistentry>

1975

1976

1977

<varname>nobuild</varname>

1978

</term>

1979

1980

<simpara>A boolean value, if set to <constant>True</constant>

1981

JHBuild will not build modules, but just download and unpack the

1982

sources. The default vale is <constant>False</constant>.</simpara>

1983

</listitem>

1984

</varlistentry>

1985

1986

1987

<varname>nonetwork</varname>

1988

</term>

1989

1990

<simpara>A boolean value specifying whether to access the network.

1991

This affects checking out or updating CVS modules, downloading

1992

tarballs and updating module sets. Setting this to

1993

<constant>True</constant> is equivalent to passing the

1994

<option>--no-network</option> option. Defaults to

1995

<constant>False</constant>.</simpara>

1996

</listitem>

1997

</varlistentry>

1998

1999

2000

<varname>nonotify</varname>

2001

</term>

2002

2003

<simpara>A boolean value specifying whether to emit notifications

2004

using the notification daemon. If set to

2005

<constant>False</constant>, notifications are emitted. Defaults to

2006

2007

</listitem>

2008

</varlistentry>

2009

2010

2011

<varname>nopoison</varname>

2012

</term>

2013

2014

<simpara>A boolean value, if set to <constant>True</constant>

2015

JHBuild attempts to build modules even if one or more of the

2016

module's dependencies failed to build. This option is equivalent

2017

to the <option>--no-poison</option> argument. The default value is

2018

<constant>False</constant>.</simpara>

2019

</listitem>

2020

</varlistentry>

2021

2022

2023

<varname>notrayicon</varname>

2024

</term>

2025

2026

<simpara>A boolean value specifying whether to show an icon in the

2027

system tray using Zenity. If set to <constant>False</constant>,

2028

notifications are emitted. Defaults to <constant>True</constant>.

2029

</simpara>

2030

</listitem>

2031

</varlistentry>

2032

2033

2034

<varname>noxvfb</varname>

2035

</term>

2036

2037

<simpara>A boolean value, if set to <constant>True</constant>

2038

JHBuild will run any graphical tests on the real X server, rather

2039

than using <command>Xvfb</command>. This option is equivalent to

2040

passing <option>--no-xvfb</option>. The default value is

2041

<constant>False</constant></simpara>

2042

</listitem>

2043

</varlistentry>

2044

2045

2046

<varname>partial_build</varname>

2047

</term>

2048

2049

<simpara>A boolean value, if set to <constant>True</constant>

2050

JHBuild will not build dependency modules if corresponding system

2051

packages are installed and sufficient version. Defaults to

2052

2053

</listitem>

2054

</varlistentry>

2055

2056

2057

<varname>prefix</varname>

2058

</term>

2059

2060

<simpara>A string specifying the prefix to install modules to.

2061

<varname>prefix</varname> must be an absolute path. This directory

2062

must be writable. Defaults to <literal>'/opt/gnome'</literal>.

2063

</simpara>

2064

</listitem>

2065

</varlistentry>

2066

2067

2068

<varname>pretty_print</varname>

2069

</term>

2070

2071

<simpara>A boolean value specifying whether to pretty format the

2072

subprocess output. Only CVS output supports pretty printing.

2073

Disable if the pretty printing causes problems. Defaults to

2074

2075

</listitem>

2076

</varlistentry>

2077

2078

2079

<varname>print_command_pattern</varname>

2080

</term>

2081

2082

<simpara>A string displayed before JHBuild executes a command.

2083

<varname>%(command)s</varname> in the string will be replaced with

2084

the command about to be executed. <varname>%(cwd)s</varname> in

2085

the string will be replaced with the current working directory.

2086

Defaults to <literal>'%(command)s'</literal>.</simpara>

2087

</listitem>

2088

</varlistentry>

2089

2090

2091

<varname>progress_bar</varname>

2092

</term>

2093

2094

<simpara>A boolean value specifying whether to display a progress

2095

bar during <link linkend="cfg-quiet-mode">quiet mode </link>.

2096

Defaults to <literal>True</literal>.</simpara>

2097

</listitem>

2098

</varlistentry>

2099

2100

2101

<varname>quiet_mode</varname>

2102

</term>

2103

2104

<simpara>A boolean value, if set to <constant>True</constant>

2105

disables the output of running commands. Defaults to

2106

<literal>False</literal>.</simpara>

2107

</listitem>

2108

</varlistentry>

2109

2110

2111

<varname>repos</varname>

2112

</term>

2113

2114

<simpara>A dictionary specifying an alternative repository

2115

location for a particular repository. This configuration variable

2116

is useful to a module developer. By default, JHBuild will check

2117

out code from repositories using an anonymous repository location.

2118

The dictionary keys are short repository names and the values are

2119

the alternative repository location strings. For example:

2120

</simpara>

2121

2122

<programlisting>repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'</programlisting>

2123

</listitem>

2124

</varlistentry>

2125

2126

<term>

2127

2128

</term>

2129

2130

<simpara>A list of modules to skip. This <option>--skip</option>

2131

command line option extends the list. This list is empty by

2132

default.</simpara>

2133

</listitem>

2134

</varlistentry>

2135

2136

<term>

2137

<varname>sticky_date</varname>

2138

</term>

2139

2140

<simpara>A string if set, and if supported by the underlying

2141

version control system, JHBuild will update the source tree to the

2142

specified date before building. An ISO date format is required,

2143

e.g.

2144

<literal>'<replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>'</literal>.

2145

Defaults to <constant>None</constant>.</simpara>

2146

</listitem>

2147

</varlistentry>

2148

2149

<term>

2150

<varname>svn_program</varname>

2151

</term>

2152

2153

<simpara>A string specifying which program to use for subversion

2154

support. This can be <literal>svn</literal>,

2155

<literal>git-svn</literal> or <literal>bzr</literal>. Defaults to

2156

2157

</listitem>

2158

</varlistentry>

2159

2160

<term>

2161

<varname>tarballdir</varname>

2162

</term>

2163

2164

<simpara>A string if set, tarballs will be downloaded to the

2165

specified directory instead of <varname>checkoutroot</varname>.

2166

This is useful if you have multiple JHBuild environments or

2167

regularly clear out <varname>checkoutroot</varname> and want to

2168

reduce bandwidth usage.</simpara>

2169

</listitem>

2170

</varlistentry>

2171

2172

<term>

2173

<varname>tinderbox_outputdir</varname>

2174

</term>

2175

2176

<simpara>A string specifying the directory to store

2177

<command>jhbuild tinderbox</command> output. This string can be

2178

overridden by the <option>--output</option> option. Defaults to

2179

<constant>None</constant>, so either the command line option must

2180

be used or this variable must be set in the configuration file.

2181

</simpara>

2182

</listitem>

2183

</varlistentry>

2184

2185

<term>

2186

<varname>trycheckout</varname>

2187

</term>

2188

2189

<simpara>A boolean value, if set to <constant>True</constant>

2190

JHBuild will automatically try to solve failures by 1) running

2191

<command>autogen.sh</command> again, and 2) checking out a newer

2192

version of a module from version control. This setting is

2193

equivalent to passing the <option>--try-checkout</option> option.

2194

</simpara>

2195

</listitem>

2196

</varlistentry>

2197

2198

<term>

2199

2200

</term>

2201

2202

<simpara>A boolean value that specifies whether to install

2203

libraries to <filename>lib64</filename> directories. If set,

2204

<literal>--libdir=\${exec_prefix}/lib64</literal> will be passed

2205

to configure. Defaults to <constant>True</constant> if running on

2206

<literal>x86_64</literal>, <literal>ppc64</literal> or

2207

<literal>s390x</literal> Linux, and <constant>False</constant> on

2208

other systems.</simpara>

2209

</listitem>

2210

</varlistentry>

2211

2212

<term>

2213

<varname>use_local_modulesets</varname>

2214

</term>

2215

2216

<simpara>A boolean value that specifies to use modulesets that

2217

were checked out along the JHBuild source code; instead of

2218

downloading them on-the-fly from GNOME version control system.

2219

Defaults to <constant>False</constant>.</simpara>

2220

</listitem>

2221

</varlistentry>

2222

2223

<term>

2224

<varname>xvfbargs</varname>

2225

</term>

2226

2227

<simpara>A string listing arguments to pass to

2228

<command>Xvfb</command> if running graphical tests.</simpara>

2229

</listitem>

2230

</varlistentry>

2231

</variablelist>

2232

</section>

2233

2234

2235

<title>Other Configuration File Structures</title>

2236

2237

<para>In addition to the above variables, there are other settings that

2238

can be set in the configuration file:</para>

2239

2240

2241

2242

<term>

2243

<varname>os.environ</varname>

2244

</term>

2245

2246

<para>A dictionary representing the environment. This environment

2247

is passed to processes that JHBuild spawns.</para>

2248

2249

<para>Some influential environment variables include

2250

<envar>CPPFLAGS</envar>, <envar>CFLAGS</envar>,

2251

<envar>INSTALL</envar> and <envar>LDFLAGS</envar>. For example:

2252

</para>

2253

2254

<programlisting>os.environ['CFLAGS'] = '-O0 -g'</programlisting>

2255

</listitem>

2256

</varlistentry>

2257

2258

<term>

2259

<function>addpath</function>(<parameter>envvar</parameter>,

2260

<parameter>pathname</parameter>)

2261

</term>

2262

2263

<para>This will add a directory to the <envar>PATH</envar>

2264

environment variable. <function>addpath</function> will correctly

2265

handle the case when the environment variable is initially empty

2266

(having a stray colon at the beginning or end of an environment

2267

variable can have unexpected consequences).</para>

2268

2269

<para><function>addpath</function> has special handling for the

2270

<envar>ACLOCAL_FLAGS</envar> environment variable, which expects

2271

paths to be listed in the form <literal>-I

2272

<replaceable>pathname</replaceable></literal>.</para>

2273

</listitem>

2274

</varlistentry>

2275

2276

<term>

2277

<function>prependpath</function>(<parameter>envvar</parameter>,

2278

<parameter>pathname</parameter>)

2279

</term>

2280

2281

<para>After processing the configuration file, JHBuild will alter

2282

some paths based on variables such as <varname>prefix</varname>

2283

(e.g. adding <literal>$prefix/bin</literal> to the start of

2284

2285

2286

<para>The <function>prependpath</function> function works like

2287

<function>addpath</function>, except that the environment variable

2288

is modified after JHBuild has made its changes to the environment.

2289

</para>

2290

</listitem>

2291

</varlistentry>

2292

</variablelist>

2293

</section>

2294

</section>

2295

2296

2297

<title>Module Set File Syntax</title>

2298

2299

<para>JHBuild uses XML files to describe the dependencies between modules.

2300

A RELAX-NG schema and Document Type Definition are included with JHBuild

2301

in the <filename>modulesets/</filename> directory. The RELAX-NG schema can

2302

be used to edit module set files using <literal>nxml-mode</literal> in

2303

Emacs.</para>

2304

2305

<para>The top-level element in a module set file is

2306

<sgmltag class="element">moduleset</sgmltag> element. No XML namespace is

2307

used. The elements below the top-level come in three types: module

2308

sources, include statements and module definitions.</para>

2309

2310

2311

<title>Module Sources</title>

2312

2313

<para>Rather than listing the full location of every module, a number of

2314

"module sources" are listed in the module set, and then referenced by

2315

name in the module definitions. As well as reducing the amount of

2316

redundant information in the module set, it makes it easy for a user to

2317

specify an alternative source for those modules (for CVS and Subversion,

2318

it is common for developers and users to use different repository access

2319

methods).</para>

2320

2321

<para>The <sgmltag class="element">repository</sgmltag> element is used

2322

to describe all types of repository. The

2323

<sgmltag class="element">branch</sgmltag> element is used inside module

2324

definition to specify additional settings.</para>

2325

2326

2327

<repository name="<replaceable>name</replaceable>"

2328

type="<replaceable>type</replaceable>"

2329

[ default="<replaceable>default</replaceable>" ]

2330

[ password="<replaceable>password</replaceable>" ]

2331

[ cvsroot="<replaceable>cvsroot</replaceable>" ]

2332

[ archive="<replaceable>archive</replaceable>" ]

2333

[ href="<replaceable>href</replaceable>" ]

2334

[ server="<replaceable>server</replaceable>" ]

2335

[ database="<replaceable>database</replaceable>" ]

2336

[ defbranch="<replaceable>defbranch</replaceable>" ]

2337

[ trunk-template="<replaceable>trunk-template</replaceable>" ]

2338

[ branches-template="<replaceable>branches-template</replaceable>" ]

2339

[ tags-template="<replaceable>tags-template</replaceable>" ]

2340

[ developer-href-example="<replaceable>developer-href-example</replaceable>" ] />

2341

</programlisting>

2342

2343

<para>The <sgmltag class="attribute">name</sgmltag> attribute is a

2344

unique identifier for the repository.</para>

2345

2346

<para>The <sgmltag class="attribute">default</sgmltag> attribute

2347

specifies whether this repository is the default source for this module

2348

set.</para>

2349

2350

<para>The <sgmltag class="attribute">type</sgmltag> attribute specifies

2351

the type of repository. It can be one of: <literal>arch</literal>,

2352

<literal>bzr</literal>, <literal>cvs</literal>,

2353

<literal>darcs</literal>, <literal>fossil</literal>,

2354

<literal>git</literal>, <literal>hg</literal>, <literal>mnt</literal>,

2355

<literal>svn</literal>, <literal>tarball</literal>. Other attributes

2356

depend on the <sgmltag class="attribute">type</sgmltag>, as well as the

2357

<sgmltag class="element">branch</sgmltag> used inside module

2358

definitions. Those are described below in the repository type

2359

sub-sections.</para>

2360

2361

<para>The <sgmltag class="attribute">developer-href-example</sgmltag>

2362

attribute is used to specify the format of the URL for the repository

2363

used by developers. This is informational only.</para>

2364

2365

<para>The <sgmltag class="element">branch</sgmltag> element is used

2366

inside module definitions.</para>

2367

2368

2369

<branch

2370

[ repo="<replaceable>repository</replaceable>" ]

2371

[ module="<replaceable>module name</replaceable>" ]

2372

[ checkoutdir="<replaceable>checkoutdir</replaceable>" ]

2373

[ revision="<replaceable>revision</replaceable>" ]

2374

[ tag="<replaceable>tag</replaceable>" ]

2375

[ update-new-dirs="<replaceable>update-new-dirs</replaceable>" ]

2376

[ override-checkoutdir="<replaceable>override-checkoutdir</replaceable>" ]

2377

[ subdir="<replaceable>subdir</replaceable>" ]

2378

[ branch="<replaceable>branch</replaceable>" ]

2379

[ version="<replaceable>version</replaceable>" ]

2380

[ size="<replaceable>size</replaceable>" ]

2381

[ source-subdir="<replaceable>source-subdir</replaceable>" ]

2382

[ hash="<replaceable>hash</replaceable>" ]/>

2383

</programlisting>

2384

2385

<para>All atributes have sensible defaults and depend on the module and

2386

repository definitions. Common attributes are described here.</para>

2387

2388

<para>The <sgmltag class="attribute">repo</sgmltag> attribute is used to

2389

specify non-default repository name.</para>

2390

2391

<para>The <sgmltag class="attribute">module</sgmltag> attribute is used

2392

to specify module name to checkout from the repository. Defaults to

2393

module id.</para>

2394

2395

<para>The <sgmltag class="attribute">checkoutdir</sgmltag> attribute is

2396

used to specify the checkout directory name. Defaults to module id.

2397

</para>

2398

2399

<para>Other attributes are described below</para>

2400

2401

2402

2403

2404

<para>This repository type is used to define a Arch repository.</para>

2405

2406

<para>The <sgmltag class="attribute">archive</sgmltag> attribute is

2407

used to specify the archive to use.</para>

2408

2409

<para>The <sgmltag class="attribute">href</sgmltag> attribute is used

2410

to specify the URL of the repository.</para>

2411

2412

2413

<repository type="arch" name="rhythmbox"

2414

archive="rhythmbox-devel@gnome.org--2004"

2415

href="http://web.rhythmbox.org/arch/2004"/>

2416

</programlisting>

2417

</section>

2418

2419

2420

<title>Bazaar</title>

2421

2422

<para>This repository type is used to define a Bazaar repository. It

2423

is recommended to have Bazaar 1.16 or higher.</para>

2424

2425

2426

<repository type="bzr" name="launchpad.net"

2427

href="lp:"/>

2428

</programlisting>

2429

2430

<para>Additional attributes are:

2431

<sgmltag class="attribute">trunk-template</sgmltag> (defaults to

2432

<literal>"%(module)s"</literal>) and

2433

<sgmltag class="attribute">branches-template</sgmltag> (defaults to

2434

<literal>"%(module)s/%(branch)s</literal>"). These attributes are used

2435

to specify templates for constructing URL. A

2436

<sgmltag class="element">branch</sgmltag> element in the module

2437

definitions can specify <sgmltag class="attribute">branch</sgmltag>

2438

and <sgmltag class="attribute">user</sgmltag> attributes. These values

2439

will be substitued in the templates. If either of those are defined

2440

<sgmltag class="attribute">branches-template</sgmltag> is used,

2441

otherwise <sgmltag class="attribute">trunk-template</sgmltag> is used.

2442

This way you can ovveride repository to build modules from your

2443

personal branch or build many modules fron a repository with

2444

non-standard layout.</para>

2445

2446

<para>An addition <sgmltag class="element">branch</sgmltag> element

2447

accepts <sgmltag class="attribute">revspec</sgmltag> attibute to

2448

anchor on a particular revision. Any valid <literal>bzr

2449

revspec</literal> is accepted, for example <literal>date:yesterday,

2450

-5, tag:0.1</literal> to get first revision since yesterday, 5 commits

2451

behind the tip or tag "0.1". See <literal>bzr help

2452

revisionspec</literal> for all possible values.</para>

2453

2454

<para>For example repository with

2455

<sgmltag class="attribute">template</sgmltag> attributes defined:

2456

</para>

2457

2458

2459

<repository type="bzr" name="launchpad.net"

2460

href="lp:"

2461

trunk-template="~bzr-pqm/%(module)s/bzr.dev"

2462

branches-template="~bzr-pqm/%(module)s/%(branch)s"/>

2463

</programlisting>

2464

2465

<para>Example <sgmltag class="element">branch</sgmltag> elements for

2466

the above repository:</para>

2467

2468

2469

<branch repo="launchpad.net"

2470

module="bzr"

2471

checkoutdir="bzr-next"/>

2472

</programlisting>

2473

2474

2475

<branch repo="launchpad.net"

2476

module="bzr"

2477

branch="2.2"

2478

checkoutdir="bzr-beta"/>

2479

</programlisting>

2480

</section>

2481

2482

2483

2484

2485

<para>This repository type is used to define a CVS repository.</para>

2486

2487

<para>The <sgmltag class="attribute">password</sgmltag> attribute is

2488

used to specify the password to the repository.</para>

2489

2490

<para>The <sgmltag class="attribute">cvsroot</sgmltag> attribute is

2491

used to specify the root of the repository.</para>

2492

2493

2494

<repository type="cvs" name="tango.freedesktop.org"

2495

cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango"

2496

password=""/>

2497

</programlisting>

2498

2499

2500

2501

<para>Additional attributes are:

2502

<sgmltag class="attribute">revision</sgmltag>,

2503

<sgmltag class="attribute">update-new-dirs</sgmltag> and

2504

<sgmltag class="attribute">override-checkoutdir</sgmltag>.</para>

2505

</section>

2506

2507

2508

<title>Darcs</title>

2509

2510

<para>This repository type is used to define a Darcs repository.

2511

</para>

2512

2513

2514

<repository type="darcs" name="telepathy.freedesktop.org"

2515

href="http://projects.collabora.co.uk/darcs/telepathy/"/>

2516

</programlisting>

2517

</section>

2518

2519

2520

2521

2522

<para>This repository type is used to define a Git repository.</para>

2523

2524

2525

<repository type="git" name="git.freedesktop.org"

2526

href="git://anongit.freedesktop.org/git/"/>

2527

</programlisting>

2528

2529

<para>It allows the following attributes on the

2530

<sgmltag class="element">branch</sgmltag> element:</para>

2531

2532

<para>The <sgmltag class="attribute">revision</sgmltag> attribute is

2533

used to specify a local or remote-tracking branch to switch to in the

2534

update phase. It defaults to 'master'. It is possible to override this

2535

attribute with the <varname>branches</varname> configuration variable.

2536

The switch will only be performed, if the current branch is tracking a

2537

remote branch, to not disturb your own work.</para>

2538

2539

<para>The <sgmltag class="attribute">tag</sgmltag> attribute is used

2540

to specify a revision to unconditionally check out in the update

2541

phase. It overrides the <sgmltag class="attribute">revision</sgmltag>

2542

attribute.</para>

2543

2544

<!-- TODO I can't say much about the subdir attribute. In the

2545

end it will just be appended to checkoutdir.

2546

https://bugzilla.gnome.org/show_bug.cgi?id=342846

2547

-->

2548

2549

2550

<branch repo="git.freedesktop.org" module="swfdec/swfdec"

2551

checkoutdir="swfdec"

2552

revision="<replaceable>local-or-remote-branch</replaceable>"

2553

tag="<replaceable>tree-ish</replaceable>"/>

2554

</programlisting>

2555

</section>

2556

2557

2558

<title>Mercurial</title>

2559

2560

<para>This repository type is used to define a Mercurial repository.

2561

</para>

2562

2563

2564

<repository type="hg" name="hg.gtk-vnc"

2565

href="http://gtk-vnc.codemonkey.ws/hg/" />

2566

</programlisting>

2567

2568

2569

2570

</programlisting>

2571

</section>

2572

2573

2574

<title>Monotone</title>

2575

2576

<para>This repository type is used to define a Monotone repository.

2577

</para>

2578

2579

<para>The <sgmltag class="attribute">server</sgmltag> attribute is

2580

used to specify the repository server.</para>

2581

2582

<para>The <sgmltag class="attribute">database</sgmltag> attribute is

2583

used to specify the database to use for the repository.</para>

2584

2585

<para>The <sgmltag class="attribute">defbranch</sgmltag> attribute is

2586

used specify the branch of the repository to use.</para>

2587

2588

2589

<repository type="mtn" name="pidgin.im"

2590

server="pidgin.im" database="pidgin.im.mtn"

2591

defbranch="im.pidgin.pidgin"/>

2592

</programlisting>

2593

</section>

2594

2595

2596

<title>Subversion</title>

2597

2598

<para>This repository type is used to define a Subversion repository.

2599

</para>

2600

2601

2602

<repository type="svn" name="svn.gnome.org" default="yes"

2603

href="http://svn.gnome.org/svn/"/>

2604

</programlisting>

2605

2606

2607

2608

<para>It allows a <sgmltag class="attribute">revision</sgmltag> on the

2609

<sgmltag class="element">branch</sgmltag> element. This attribute

2610

defines the branch to checkout or, if it is a number, a specific

2611

revision to checkout.</para>

2612

2613

2614

2615

</programlisting>

2616

2617

<para>It is possible to specify custom <literal>svn</literal> layout

2618

using <sgmltag class="attribute">trunk-template</sgmltag> (defaults to

2619

"%(module)s/trunk"),

2620

<sgmltag class="attribute">branches-template</sgmltag> (defaults to

2621

"%(module)s/branches/%(branch)s") and

2622

<sgmltag class="attribute">tags-template</sgmltag> (defaults to

2623

"%(module)s/tags/%(tag)s")</para>

2624

</section>

2625

2626

2627

<title>Tarballs</title>

2628

2629

<para>This repository type is used to define a tarball repository.

2630

</para>

2631

2632

2633

<repository type="tarball" name="dbus/dbus-python"

2634

href="http://dbus.freedesktop.org/releases/dbus-python/"/>

2635

</programlisting>

2636

2637

<para>It allows the following attributes on the

2638

<sgmltag class="element">branch</sgmltag> element:</para>

2639

2640

<para>The <sgmltag class="attribute">module</sgmltag> attribute

2641

specifies the file to download and compile, the

2642

<sgmltag class="attribute">version</sgmltag> attribute specifies the

2643

module version.</para>

2644

2645

<para>The <sgmltag class="attribute">size</sgmltag> and

2646

<sgmltag class="attribute">hash</sgmltag>, as well as the obsolete

2647

<sgmltag class="attribute">md5sum</sgmltag>, attributes are optional.

2648

If these attributes are present, they are used to check that the

2649

source package was downloaded correctly.</para>

2650

2651

<para>Any number of <sgmltag class="element">patch</sgmltag> elements

2652

may be nested inside the <sgmltag class="element">branch</sgmltag>

2653

element. These patches are applied, in order, to the source tree after

2654

unpacking. The <sgmltag class="attribute">file</sgmltag> attribute

2655

gives the patch filename, and the

2656

<sgmltag class="attribute">strip</sgmltag> attribute says how many

2657

levels of directories to prune when applying the patch.</para>

2658

2659

<para>For module sets shipped with JHBuild, the patch files are looked

2660

up in the <filename>jhbuild/patches/</filename> directory; for module

2661

sets referred by URI, the patch files are looked for in the same

2662

directory as the moduleset file, or in its

2663

<filename>patches/</filename> subdirectory. It is also possible for

2664

the <sgmltag class="attribute">file</sgmltag> attribute to specify a

2665

URI, in which case it will be downloaded from that location.</para>

2666

2667

2668

<branch module="dbus-python-0.80.2.tar.gz" version="0.80.2"

2669

repo="dbus/dbus-python"

2670

hash="md5:2807bc85215c995bd595e01edd9d2077" size="453499">

2671

2672

</branch>

2673

</programlisting>

2674

2675

<para>A tarball <sgmltag class="element">branch</sgmltag> element may

2676

also contain <sgmltag class="element">quilt</sgmltag> elements which

2677

specify nested <sgmltag class="element">branch</sgmltag> to import.

2678

</para>

2679

</section>

2680

</section>

2681

2682

2683

<title>Including Other Module Sets</title>

2684

2685

<para>JHBuild allows one module set to include the contents of another

2686

by reference using the <sgmltag class="element">include</sgmltag>

2687

element.</para>

2688

2689

2690

2691

</programlisting>

2692

2693

<para>The <sgmltag class="attribute">href</sgmltag> is a URI reference

2694

to the module set to be included, relative to the file containing the

2695

<sgmltag class="element">include</sgmltag> element.</para>

2696

2697

<para>Only module definitions are imported from the referenced module

2698

set - module sources are not. Multiple levels of includes are allowed,

2699

but include loops are not (there isn't any code to handle loops at the

2700

moment).</para>

2701

</section>

2702

2703

2704

<title>Module Definitions</title>

2705

2706

<para>There are various types of module definitions that can be used in

2707

a module set file, and the list can easily be extended. Only the most

2708

common ones will be mentioned here.</para>

2709

2710

<para>They are all basically composed of a

2711

<sgmltag class="element">branch</sgmltag> element describing how to get

2712

the module and <sgmltag class="element">dependencies</sgmltag>,

2713

<sgmltag class="element">suggests</sgmltag> and

2714

<sgmltag class="element">after</sgmltag> elements to declare the

2715

dependencies of the module.</para>

2716

2717

<para>Any modules listed in the

2718

<sgmltag class="element">dependencies</sgmltag> element will be added to

2719

the module list for <command>jhbuild build</command> if it isn't already

2720

included, and make sure the dependent modules are built first.</para>

2721

2722

<para>After generating the modules list, the modules listed in the

2723

<sgmltag class="element">suggests</sgmltag> element will be used to

2724

further sort the modules list (although it will not pull any additional

2725

modules). This is intended for cases where a module has an optional

2726

dependency on another module.</para>

2727

2728

2729

<title>autotools</title>

2730

2731

<para>The <sgmltag class="element">autotools</sgmltag> element is used

2732

to define a module which is compiled using the GNU Autotools build

2733

system.</para>

2734

2735

2736

<autotools id="<replaceable>id</replaceable>"

2737

[ autogenargs="<replaceable>autogenargs</replaceable>" ]

2738

[ makeargs="<replaceable>makeargs</replaceable>" ]

2739

[ makeinstallargs="<replaceable>makeinstallargs</replaceable>" ]

2740

[ autogen-sh="<replaceable>autogen-sh</replaceable>" ]

2741

[ makefile="<replaceable>makefile</replaceable>" ]

2742

[ skip-autogen="<replaceable>skip-autogen</replaceable>" ]

2743

[ autogen-template="<replaceable>autogen-template</replaceable>" ]

2744

[ check-target="<replaceable>check-target</replaceable>" ]

2745

[ supports-non-srcdir-builds="<replaceable>supports-non-srcdir-builds</replaceable>" ]>

2746

2747

2748

[...]

2749

</branch>

2750

2751

2752

<dep package="<replaceable>modulename</replaceable>"/>

2753

...

2754

</dependencies>

2755

<after>

2756

<dep package="<replaceable>modulename</replaceable>"/>

2757

...

2758

</after>

2759

2760

</autotools>

2761

</programlisting>

2762

2763

<para>The <sgmltag class="attribute">autogenargs</sgmltag> and

2764

<sgmltag class="attribute">makeargs</sgmltag> and

2765

<sgmltag class="attribute">makeinstallargs</sgmltag> attributes are

2766

used to specify additional arguments to pass to

2767

<command>autogen.sh</command>, <command>make</command> and

2768

<command>make install</command> respectively.</para>

2769

2770

<para>The <sgmltag class="attribute">autogen-sh</sgmltag> attribute

2771

specifies the name of the autogen.sh script to run. The value

2772

<literal>autoreconf</literal> can be used if your module has no

2773

<command>autogen.sh</command> script equivalent. In that case, JHBuild

2774

will run <command>autoreconf -i</command>, followed by the proper

2775

<command>configure</command>.

2776

<sgmltag class="attribute">skip-autogen</sgmltag> chooses whether or

2777

not to run autogen.sh, it is a boolean with an extra

2778

<literal>never</literal> value to tell JHBuild to never skip running

2779

<command>autogen.sh</command>.

2780

<sgmltag class="attribute">makefile</sgmltag> specifies the filename

2781

of the makefile to use.</para>

2782

2783

<para>The

2784

<sgmltag class="attribute">supports-non-srcdir-builds</sgmltag>

2785

attribute is used to mark modules that can't be cleanly built using a

2786

separate source directory.</para>

2787

2788

<para>The <sgmltag class="attribute">autogen-template</sgmltag>

2789

attribute can be used if you need finer control over the autogen

2790

command line. It is a python format string, which will be substituted

2791

with the following variables: <varname>srcdir</varname>,

2792

<varname>autogen-sh</varname>, <varname>prefix</varname>,

2793

<varname>libdir</varname>, and <varname>autogenargs</varname>. For

2794

example, here is the default autogen-template:</para>

2795

2796

2797

%(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s

2798

</programlisting>

2799

2800

<para>The <sgmltag class="attribute">check-target</sgmltag> attribute

2801

must be specified (with false as value) for modules that do not have a

2802

<command>make check</command> target.</para>

2803

</section>

2804

2805

2806

<title>cmake</title>

2807

2808

<para>The <sgmltag class="element">cmake</sgmltag> element is used to

2809

define a module which is built using the CMake build system.</para>

2810

2811

2812

<cmake id="<replaceable>modulename</replaceable>">

2813

2814

[...]

2815

</branch>

2816

2817

2818

<dep package="<replaceable>modulename</replaceable>"/>

2819

...

2820

</dependencies>

2821

<after>

2822

<dep package="<replaceable>modulename</replaceable>"/>

2823

...

2824

</after>

2825

</cmake>

2826

</programlisting>

2827

</section>

2828

2829

2830

<title>distutils</title>

2831

2832

<para>The <sgmltag class="element">distutils</sgmltag> element is used

2833

to define a module which is built using python's distutils</para>

2834

2835

2836

<distutils id="<replaceable>modulename</replaceable>"

2837

[ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]>

2838

2839

[...]

2840

</branch>

2841

2842

2843

<dep package="<replaceable>modulename</replaceable>"/>

2844

...

2845

</dependencies>

2846

<after>

2847

<dep package="<replaceable>modulename</replaceable>"/>

2848

...

2849

</after>

2850

</distutils>

2851

</programlisting>

2852

</section>

2853

2854

2855

<title>linux</title>

2856

2857

<para>The <sgmltag class="element">linux</sgmltag> element defines a

2858

module used to build a linux kernel. In addition, a separate kernel

2859

configuration can be chosen using the

2860

<sgmltag class="element">kconfig</sgmltag> subelement.</para>

2861

2862

2863

<linux id="<replaceable>id</replaceable>"

2864

[ makeargs="<replaceable>makeargs</replaceable>" ]>

2865

2866

2867

[...]

2868

</branch>

2869

2870

2871

<dep package="<replaceable>modulename</replaceable>"/>

2872

...

2873

</dependencies>

2874

<after>

2875

<dep package="<replaceable>modulename</replaceable>"/>

2876

...

2877

</after>

2878

2879

<kconfig [ repo="<replaceable>repo</replaceable>" ]

2880

version="<replaceable>version</replaceable>"

2881

[ module="<replaceable>module</replaceable>" ]

2882

[ config="<replaceable>config</replaceable>" ] />

2883

2884

</linux>

2885

</programlisting>

2886

</section>

2887

2888

2889

2890

2891

<para>The <sgmltag class="element">perl</sgmltag> element is used to

2892

build perl modules.</para>

2893

2894

<para>The <sgmltag class="attribute">makeargs</sgmltag> attribute is

2895

used to specify additional arguments to pass to

2896

2897

2898

2899

<perl id="<replaceable>modulename</replaceable>"

2900

[ makeargs="<replaceable>makeargs</replaceable>" ]>

2901

2902

2903

[...]

2904

</branch>

2905

2906

2907

<dep package="<replaceable>modulename</replaceable>"/>

2908

...

2909

</dependencies>

2910

<after>

2911

<dep package="<replaceable>modulename</replaceable>"/>

2912

...

2913

</after>

2914

2915

</perl>

2916

</programlisting>

2917

</section>

2918

2919

2920

2921

2922

<para>The <sgmltag class="element">waf</sgmltag> element is used to

2923

define a module which is built using the Waf build system.</para>

2924

2925

<para>The <sgmltag class="attribute">waf-command</sgmltag> attribute

2926

is used to specify the waf command script to use; it defaults to

2927

2928

2929

2930

<waf id="<replaceable>modulename</replaceable>">

2931

[ waf-command="<replaceable>waf-command</replaceable>" ]>

2932

2933

[...]

2934

</branch>

2935

2936

2937

<dep package="<replaceable>modulename</replaceable>"/>

2938

...

2939

</dependencies>

2940

<after>

2941

<dep package="<replaceable>modulename</replaceable>"/>

2942

...

2943

</after>

2944

</waf>

2945

</programlisting>

2946

</section>

2947

2948

2949

<title>testmodule</title>

2950

2951

<para>The <sgmltag class="element">testmodule</sgmltag> element is

2952

used to create a module which runs a suite of tests using LDTP or

2953

Dogtail.</para>

2954

2955

2956

<testmodule id="<replaceable>id</replaceable>"

2957

type="<replaceable>type</replaceable>">

2958

2959

2960

[...]

2961

</branch>

2962

2963

2964

<dep package="<replaceable>modulename</replaceable>"/>

2965

...

2966

</dependencies>

2967

<after>

2968

<dep package="<replaceable>modulename</replaceable>"/>

2969

...

2970

</after>

2971

2972

2973

<tested package="<replaceable>package</replaceable>" />

2974

</testedmodules>

2975

2976

</testmodule>

2977

</programlisting>

2978

2979

<para>The <sgmltag class="attribute">type</sgmltag> attribute gives

2980

the type of tests to be run in the module. 'dogtail' uses python to

2981

invoke all .py files. 'ldtp' invokes 'ldtprunner run.xml'.</para>

2982

2983

<para>Unless the noxvfb configuration option is set, an Xvfb server is

2984

started to run the tests in</para>

2985

</section>

2986

2987

2988

<title>metamodule</title>

2989

2990

<para>The <sgmltag class="element">metamodule</sgmltag> element

2991

defines a module that doesn't actually do anything. The only purpose

2992

of a module of this type is its dependencies.</para>

2993

2994

<para>For example, meta-gnome-desktop depends on all the key

2995

components of the GNOME desktop, therefore telling JHBuild to install

2996

it actually installs the full desktop.</para>

2997

2998

2999

<metamodule id="<replaceable>modulename</replaceable>">

3000

3001

<dep package="<replaceable>modulename</replaceable>"/>

3002

...

3003

</dependencies>

3004

3005

<dep package="<replaceable>modulename</replaceable>"/>

3006

...

3007

</suggests>

3008

</metamodule>

3009

</programlisting>

3010

3011

<para>The <sgmltag class="attribute">id</sgmltag> attribute gives the

3012

name of the module. The child elements are handled as for

3013

3014

</para>

3015

</section>

3016

</section>

3017

3018

3019

<title>Deprecated Elements</title>

3020

3021

3022

<title>Module Sources</title>

3023

3024

3025

<title>cvsroot</title>

3026

3027

<para>The <sgmltag class="element">cvsroot</sgmltag> element is now

3028

deprecated - the <sgmltag class="element">repository</sgmltag>

3029

element should be used instead.</para>

3030

3031

<para>The <sgmltag class="element">cvsroot</sgmltag> element is used

3032

to describe a CVS repository.</para>

3033

3034

3035

<cvsroot name="<replaceable>rootname</replaceable>"

3036

[ default="<replaceable>yes|no</replaceable>" ]

3037

root="<replaceable>anon-cvsroot</replaceable>"

3038

password="<replaceable>anon-password</replaceable>"/>

3039

</programlisting>

3040

3041

<para>The <sgmltag class="attribute">name</sgmltag> attribute should

3042

be a unique identifier for the CVS repository.</para>

3043

3044

<para>The <sgmltag class="attribute">default</sgmltag> attribute

3045

says whether this is the default module source for this module set

3046

file.</para>

3047

3048

<para>The <sgmltag class="attribute">root</sgmltag> attribute lists

3049

the CVS root used for anonymous access to this repository, and the

3050

<sgmltag class="attribute">password</sgmltag> attribute gives the

3051

password used for anonymous access.</para>

3052

</section>

3053

3054

3055

<title>svnroot</title>

3056

3057

<para>The <sgmltag class="element">svnroot</sgmltag> element is now

3058

deprecated - the <sgmltag class="element">repository</sgmltag>

3059

element should be used instead.</para>

3060

3061

<para>The <sgmltag class="element">svnroot</sgmltag> element is used

3062

to describe a Subversion repository.</para>

3063

3064

3065

<svnroot name="<replaceable>rootname</replaceable>"

3066

[ default="<replaceable>yes|no</replaceable>" ]

3067

href="<replaceable>anon-svnroot</replaceable>"/>

3068

</programlisting>

3069

3070

<para>The <sgmltag class="attribute">name</sgmltag> attribute should

3071

be a unique identifier for the Subversion repository.</para>

3072

3073

<para>If <sgmltag class="attribute">default</sgmltag> attribute says

3074

whether this is the default module source for this module set file.

3075

</para>

3076

3077

<para>The <sgmltag class="attribute">href</sgmltag> attribute lists

3078

the base URL for the repository. This will probably be either a

3079

<literal>http</literal>, <literal>https</literal> or

3080

3081

</section>

3082

3083

3084

<title>arch-archive</title>

3085

3086

<para>The <sgmltag class="element">arch-archive</sgmltag> element is

3087

now deprecated - the <sgmltag class="element">repository</sgmltag>

3088

element should be used instead.</para>

3089

3090

<para>The <sgmltag class="element">arch-archive</sgmltag> element is

3091

used to describe a GNU Arch archive.</para>

3092

3093

3094

<arch-archive name="<replaceable>archivename</replaceable>"

3095

[ default="<replaceable>yes|no</replaceable>" ]

3096

href="<replaceable>mirror-url</replaceable>"/>

3097

</programlisting>

3098

3099

<para>The <sgmltag class="attribute">name</sgmltag> attribute should

3100

be the Arch archive name.</para>

3101

3102

<para>If <sgmltag class="attribute">default</sgmltag> attribute says

3103

whether this is the default module source for this module set file.

3104

</para>

3105

3106

<para>The <sgmltag class="attribute">href</sgmltag> attribute lists

3107

a public mirror URL for the archive.</para>

3108

</section>

3109

</section>

3110

3111

3112

3113

3114

<title>Deprecated Module Types</title>

3115

3116

3117

<para>This section describes deprecated elements, they may still be

3118

used in existing module sets but it is advised not to use them

3119

anymore.</para>

3120

</warning>

3121

3122

3123

<title>tarball</title>

3124

3125

3126

<para>This deprecated element is just a thin wrapper around both

3127

<sgmltag class="element">autotools</sgmltag> module type and

3128

<sgmltag class="element">tarball</sgmltag> repository type.</para>

3129

</important>

3130

3131

<para>The <sgmltag class="element">tarball</sgmltag> element is used

3132

to define a module that is to be built from a tarball.</para>

3133

3134

3135

<tarball id="<replaceable>modulename</replaceable>"

3136

[ version="<replaceable>version</replaceable>" ]

3137

[ checkourdir="<replaceable>checkoutdir</replaceable>" ]

3138

[ autogenargs="<replaceable>autogenargs</replaceable>" ]

3139

[ makeargs="<replaceable>makeargs</replaceable>" ]

3140

[ autogen-sh="<replaceable>autogen-sh</replaceable>" ]

3141

[ supports-non-srcdir-builds="<replaceable>yes|no</replaceable>" ]>

3142

<source href="<replaceable>source-url</replaceable>"

3143

[ size="<replaceable>source-size</replaceable>" ]

3144

[ hash="<replaceable>source-algo:source-hash</replaceable>" ]

3145

[ md5sum="<replaceable>source-md5sum</replaceable>" ]/>

3146

3147

<patch file="<replaceable>filename</replaceable>" strip="<replaceable>level</replaceable>"/>

3148

...

3149

</patches>

3150

3151

<dep package="<replaceable>modulename</replaceable>"/>

3152

...

3153

</dependencies>

3154

3155

<dep package="<replaceable>modulename</replaceable>"/>

3156

...

3157

</suggests>

3158

</tarball>

3159

</programlisting>

3160

3161

<para>The <sgmltag class="attribute">id</sgmltag> and

3162

<sgmltag class="attribute">version</sgmltag> attributes are used to

3163

identify the module.</para>

3164

3165

<para>The <sgmltag class="element">source</sgmltag> element

3166

specifies the file to download and compile. The

3167

<sgmltag class="attribute">href</sgmltag> attribute is mandatory,

3168

while the <sgmltag class="attribute">size</sgmltag> and

3169

<sgmltag class="attribute">hash</sgmltag>, as well as the obsolete

3170

<sgmltag class="attribute">md5sum</sgmltag>, attributes are

3171

optional. If these last two attributes are present, they are used to

3172

check that the source package was downloaded correctly.</para>

3173

3174

<para>The <sgmltag class="element">patches</sgmltag> element is used

3175

to specify one or more patches to apply to the source tree after

3176

unpacking, the <sgmltag class="attribute">file</sgmltag> attribute

3177

gives the patch filename, and the

3178

<sgmltag class="attribute">strip</sgmltag> attribute says how many

3179

levels of directories to prune when applying the patch.</para>

3180

3181

<para>For module sets shipped with JHBuild, the patch files are

3182

looked up in the <filename>jhbuild/patches/</filename> directory;

3183

for module sets referred by URI, the patch files are looked for in

3184

the same directory as the moduleset file, or in its

3185

<filename>patches/</filename> subdirectory. It is also possible for

3186

the <sgmltag class="attribute">file</sgmltag> attribute to specify a

3187

URI, in which case it will be downloaded from that location.</para>

3188

3189

<para>The other attributes and the

3190

<sgmltag class="element">dependencies</sgmltag>,

3191

<sgmltag class="element">suggests</sgmltag> and

3192

<sgmltag class="element">after</sgmltag> elements are processed as

3193

for

3194

3195

</para>

3196

</section>

3197

</section>

3198

3199

3200

</section>

3201

3202

3203

</section>

3204

</article>