~mildred/+junk/jam-shell : revision 1

1

<HTML>

2

3

<TITLE> Jam - Make(1) Redux </TITLE>

4

5

<BODY>

6

7

8

9

<H1> Jam - Make(1) Redux </H1>

10

11

The <a href=http://www.perforce.com/jam/jam.html>Jam</a> Executable

12

13

</CENTER>

14

15

<DL>

16

17

<DT> <H2> USAGE </H2> <DD>

18

19

<PRE>

20

jam [ -a ] [ -g ] [ -n ] [ -q ] [ -v ]

21

[ -d debug ]

22

[ -f jambase ]

23

[ -j jobs ]

24

[ -o actionsfile ]

25

[ -s var=value ]

26

[ -t target ]

27

[ target ... ]

28

</PRE>

29

30

<DT> <H2> DESCRIPTION </H2> <DD>

31

32

33

34

Jam is a program construction tool, like make(1).

35

36

37

38

Jam recursively builds target files from source files,

39

using dependency information and updating actions expressed in

40

the Jambase file, which is written in jam's own interpreted

41

language. The default Jambase is compiled into jam and

42

provides a boilerplate for common use, relying on a user-provide

43

file "Jamfile" to enumerate actual targets and sources.

44

45

46

47

The Jambase is described in the <a href="Jambase.html">Jambase

48

Reference</a> and the document <a href="Jamfile.html">Using

49

Jamfiles and Jambase</A>.

50

51

<DT> <H2> OPTIONS </H2> <DD>

52

53

54

55

If target is provided on the command line, jam

56

builds target; otherwise jam builds the target

57

'all'.

58

59

60

61

Jam may be invoked with the following options:

62

63

64

65

66

<TD> Build all targets anyway, even if they are up-to-date.

67

68

69

<TD> Turn on display option c and off the default

70

display (summary info and actions):

71

72

73

<DT> a <DD> Show summary info, actions, quiet actions, and the

74

use of temporary targets

75

<DT> c <DD> Show the names of files that cause rebuilds, i.e.

76

new sources, missing targets, etc.

77

<DT> d <DD> Display a dependency graph (in jam syntax).

78

<DT> m <DD> Display the dependency analysis, and target/source

79

timestamps and paths

80

<DT> x <DD> Show shell arguments

81

</DL>

82

83

84

<TD> Enable cummulative debugging levels from 1 to n.

85

Interesting values are:

86

87

88

<DT> 1 <DD> Show actions and summary info (the default)

89

<DT> 3 <DD> Old name for -dm (described above)

90

<DT> 5 <DD> Show rule invocations and variable expansions

91

<DT> 6 <DD> Show directory/header file/archive scans

92

<DT> 7 <DD> Show variable settings

93

<DT> 8 <DD> Show variable fetches

94

<DT> 9 <DD> Show variable manipulation, scanner tokens

95

</DL>

96

97

98

<TD> Enable debugging level n.

99

100

101

<TD> Turn off all debugging levels. Only errors are emitted.

102

103

<TR><TD VALIGN=TOP><CODE> -f jambase</CODE>

104

<TD>Read jambase instead of using the built-in Jambase.

105

Multiple -f flags are permitted.

106

107

108

<TD> Build targets with the newest sources first, rather than

109

in the order of appearance in the Jambase/Jamfiles.

110

111

112

<TD> Run up to n shell commands concurrently (UNIX

113

and NT only). The default is 1.

114

115

116

<TD> Don't actually execute the updating actions, but do

117

everything else. This changes the debug level to -dax.

118

119

120

<TD> Write the updating actions to the specified file instead

121

of running them (or outputting them, as on the Mac).

122

123

124

<TD> Quit quickly (as if an interrupt was received)

125

as soon as any target build fails.

126

127

<TR><TD VALIGN=TOP><CODE> -s var=value</CODE>

128

<TD> Set the variable var to value, overriding

129

both internal variables and variables imported from the

130

environment.

131

132

<TR><TD VALIGN=TOP><CODE> -t target</CODE>

133

<TD> Rebuild target and everything that depends on it,

134

even if it is up-to-date.

135

136

137

<TD> Print the version of jam and exit.

138

139

</TABLE>

140

141

<DT> <H2> OPERATION </H2> <DD>

142

143

144

145

Jam has four phases of operation: start-up, parsing,

146

binding, and updating.

147

148

<DT> <H3> Start-up </H3> <DD>

149

150

151

152

Upon start-up, jam imports environment variable settings

153

into jam variables. Environment variables are split at

154

blanks with each word becoming an element in the variable's list

155

of values. Environment variables whose names end in PATH are

156

split at $(SPLITPATH) characters (e.g., ":" for Unix).

157

158

159

160

To set a variable's value on the command line, overriding the

161

variable's environment value, use the -s option. To see variable

162

assignments made during jam's execution, use the -d+7

163

option.

164

165

<DT> <H3> Parsing </H3> <DD>

166

167

168

169

In the parsing phase, jam reads and executes the Jambase

170

file, by default the built-in one. It is written in the jam

171

language. See <a href="#language"> Language</a> below. The

172

last action of the Jambase is to read (via the "include" rule)

173

a user-provided file called "Jamfile".

174

175

176

177

Collectively, the purpose of the Jambase and the Jamfile is to

178

name built target and source files, construct the dependency

179

graph among them, and associate build actions with targets.

180

The Jambase defines boilerplate rules and variable assignments,

181

and the Jamfile uses these to specify the actual relationship

182

among the target and source files. See the <a

183

href="Jambase.html">Jambase Reference</a> and the document <a

184

href="Jamfile.html">Using Jamfiles and Jambase</A> for information.

185

186

187

<DT> <H3> Binding </H3> <DD>

188

</A>

189

190

<H5> Binding </H5>

191

192

After parsing, jam recursively descends the dependency

193

graph and binds every file target with a location in the

194

filesystem.

195

196

<H5> Targets </H5> <DD>

197

198

Any string value in jam can represent a target, and it

199

does so if the DEPENDS or INCLUDES rules make it part of the

200

dependency graph. Build targets are files to be updated. Source

201

targets are the files used in updating build targets. Build

202

targets and source targets are collectively referred to as file

203

targets, and frequently build targets are source targets for

204

other build targets. Pseudotargets are symbols which represent

205

dependencies on other targets, but which are not themselves

206

associated with any real file.

207

208

209

210

A file target's identifier is generally the file's name, which can

211

be absolutely rooted, relative to the directory of jam's

212

invocation, or simply local (no directory). Most often it is the

213

last case, and the actual file path is bound using the $(SEARCH)

214

and $(LOCATE) special variables. See <A HREF="#search"> SEARCH

215

and LOCATE Variables</A> below. A local filename is optionally

216

qualified with "grist," a string value used to assure uniqueness.

217

A file target with an identifier of the form file(member)

218

is a library member (usually an ar(1) archive on UNIX).

219

220

221

222

The use of $(SEARCH) and $(LOCATE) allows jam to separate

223

the the location of files from their names, so that Jamfiles can

224

refer to files locally (i.e. relative to the Jamfile's directory),

225

yet still be usable when jam is invoked from a distant

226

directory. The use of grist allows files with the same name

227

to be identified uniquely, so that jam can read a whole

228

directory tree of Jamfiles and not mix up same-named targets.

229

230

<H5> Update Determination </H5>

231

232

After binding each target, jam determines whether the

233

target needs updating, and if so marks the target for the updating

234

phase. A target is normally so marked if it is missing, it is

235

older than any of its sources, or any of its sources are marked

236

for updating. This behavior can be modified by the application

237

of special built-in rules. See <A HREF="#bindingmods">Modifying

238

Binding</A> below.

239

240

<H5> Header File Scanning </H5>

241

242

During the binding phase, jam also performs header file

243

scanning, where it looks inside source files for the implicit

244

dependencies on other files caused by C's #include syntax. This

245

is controlled by the special variables $(HDRSCAN) and $(HDRRULE).

246

The result of the scan is formed into a rule invocation, with

247

the scanned file as the target and the found included file names

248

as the sources. Note that this is the only case where rules

249

are invoked outside the parsing phase. See <A

250

HREF="#hdrscan">HDRSCAN and HDRRULE Variables</A> below.

251

252

<DT> <H3> Updating </H3> <DD>

253

254

255

256

After binding, jam again recursively descends the dependency

257

graph, this time executing the update actions for each target

258

marked for update during the binding phase. If a target's

259

updating actions fail, then all other targets which depend on

260

that target are skipped.

261

262

263

264

The -j flag instructs jam to build more than one target

265

at a time. If there are multiple actions on a single target,

266

they are run sequentially. The -g flag reorders builds so that

267

targets with newest sources are built first. Normally, they are

268

built in the order of appearance in the Jamfiles.

269

270

271

<DT> <H2> LANGUAGE </H2> <DD>

272

</A>

273

274

<DT> <H3> Overview </H3> <DD>

275

276

Jam has a interpreted, procedural language with a few

277

select features to effect program construction. Statements in

278

jam are rule (procedure) definitions, rule invocations,

279

updating action definitions, flow-of-control structures, variable

280

assignments, and sundry language support.

281

282

<DT> <H3> Lexical Features </H3> <DD>

283

284

285

286

Jam treats its input files as whitespace-separated tokens,

287

with two exceptions: double quotes (") can enclose whitespace to

288

embed it into a token, and everything between the matching curly

289

braces ({}) in the definition of a updating actions is treated

290

as a single string. A backslash (\) can escape a double quote,

291

or any single whitespace character.

292

293

294

295

Jam requires whitespace (blanks, tabs, or newlines) to

296

surround all tokens, including the colon (:) and semicolon

297

(;) tokens.

298

299

300

301

Jam keywords (as mentioned in this document) are reserved

302

and generally must be quoted with double quotes (") to be used

303

as arbitrary tokens, such as variable or target names.

304

305

<DT> <H3> Datatype </H3> <DD>

306

307

308

309

Jam's only data type is a one-dimensional list of arbitrary

310

strings. They arise as literal (whitespace-separated) tokens in

311

the Jambase or included files, as the result of variable expansion

312

of those tokens, or as the return value from a rule invocation.

313

314

<DT> <H3> Rules </H3> <DD>

315

316

317

318

The basic jam language entity is called a rule. A rule

319

is simply a procedure definition, with a body of jam

320

statements to be run when the rule is invoked. The syntax of

321

rule invocation make it possible to write Jamfiles that look

322

a bit like Makefiles.

323

324

325

326

Rules take up to 9 arguments ($(1) through $(9), each a list)

327

and can have a return value (a single list). A rule's return

328

value can be expanded in a list by enclosing the rule invocation

329

with <tt>[</tt> and <tt>]</tt>.

330

331

<DT> <H3> Updating Actions </H3> <DD>

332

333

334

335

A rule may have updating actions associated with it, in which

336

case arguments $(1) and $(2) are treated as built targets and

337

sources, respectively. Updating actions are the OS shell commands

338

to execute when updating the built targets of the rule.

339

340

341

342

When an rule with updating actions is invoked, those actions are

343

added to those associated with its built targets ($(1)) before

344

the rule's procedure is run. Later, to build the targets in the

345

updating phase, the actions are passed to the OS command shell,

346

with $(1) and $(2) replaced by bound versions of the target names.

347

See <A HREF="#binding"> Binding</A> above.

348

349

350

<DT> <H3> Statements </H3> <DD>

351

352

353

354

Jam's langauge has the following statements:

355

356

357

358

359

360

rulename field1 : field2 : ...

361

: fieldN ;

362

363

</CODE>

364

365

<DD> Invoke a rule. A rule is invoked with values in

366

field1 through fieldN (9 max). They may be

367

referenced in the procedure's statements as $(1)

368

through $(<9>N). $(<) and $(>) are synonymous

369

with $(1) and $(2).

370

371

372

rulename undergoes <A HREF="#varexp"> variable

373

expansion</A>. If the resulting list is more than one value,

374

each rule is invoked with the same arguments, and the result

375

of the invocation is the concatenation of all the results.

376

377

378

379

actions [ modifiers ] rulename { commands }

380

381

</CODE>

382

383

<DD> Define a rule's updating actions, replacing any previous

384

definition. The first two arguments may be referenced in

385

the action's commands as $(1) and $(2) or $(<)

386

and $(>).

387

388

389

390

The following action modifiers are understood:

391

392

393

394

<TR><TD WIDTH=30%><CODE> actions bind vars </CODE></TD>

395

<TD> $(vars) will be replaced with bound values.</TD>

396

</TR>

397

398

<TR><TD><CODE> actions existing </CODE></TD>

399

<TD> $(>) includes only source targets currently existing.</TD>

400

</TR>

401

402

<TR><TD><CODE> actions ignore </CODE></TD>

403

<TD> The return status of the commands is ignored.</TD>

404

</TR>

405

406

<TR><TD><CODE> actions piecemeal </CODE></TD>

407

<TD> commands are repeatedly invoked with a subset

408

of $(>) small enough to fit in the command buffer on this

409

OS.</TD>

410

</TR>

411

412

<TR><TD><CODE> actions quietly </CODE></TD>

413

<TD> The action is not echoed to the standard output.</TD>

414

</TR>

415

416

<TR><TD><CODE> actions together </CODE></TD>

417

<TD> The $(>) from multiple invocations of the same action

418

on the same built target are glommed together.</TD>

419

</TR>

420

421

<TR><TD><CODE> actions updated </CODE></TD>

422

<TD> $(>) includes only source targets themselves marked

423

for updating.</TD>

424

</TR>

425

426

</TABLE>

427

428

429

430

break

431

432

</CODE>

433

434

<DD> Breaks out of the closest enclosing for

435

or while loop.

436

437

438

439

continue

440

441

</CODE>

442

443

<DD> Jumps to the end of the closest enclosing for

444

or while loop.

445

446

447

448

for var in list { statements }

449

450

</CODE>

451

452

<DD> Executes statements for each element in

453

list, setting the variable var to the element

454

value.

455

456

457

458

</A>

459

460

if cond { statements } [ else statement ]

461

462

</CODE>

463

464

<DD> Does the obvious; the else clause is optional.

465

cond is built of:

466

467

468

469

470

<TD> true if any a element is a non-zero-length

471

string</TD>

472

473

<TD> list a matches list b

474

string-for-string</TD>

475

476

<TD> list a does not match list b</TD>

477

478

<TD> a[i] string is less than b[i]

479

string, where i is first mismatched element

480

in lists a and b</TD>

481

482

<TD> every a string is less than or equal to

483

its b counterpart</TD>

484

485

<TD> a[i] string is greater than b[i]

486

string, where i is first mismatched element</TD>

487

488

<TD> every a string is greater than or equal to

489

its b counterpart</TD>

490

491

<TD> true if all elements of a can be found

492

in b, or if a has no elements</TD>

493

494

<TD> condition not true</TD>

495

496

<TD> conjunction</TD>

497

498

<TD> disjunction</TD>

499

500

<TD> precedence grouping</TD>

501

502

</TABLE>

503

504

505

506

include file ;

507

508

</CODE>

509

510

<DD> Causes jam to read the named file.

511

The file is bound like a regular target (see <A

512

HREF="#binding"> Binding</A> above) but unlike a regular

513

target the include file cannot be built. Marking an include

514

file target with the NOCARE rule makes it optional:

515

if it is missing, it causes no error.

516

517

518

519

The include file is inserted into the input stream during

520

the parsing phase. The primary input file and all the included

521

file(s) are treated as a single file; that is, jam

522

infers no scope boundaries from included files.

523

524

525

526

local vars [ = values ] ;

527

528

</CODE>

529

530

<DD> Creates new vars inside to the enclosing {}

531

block, obscuring any previous values they might have. The

532

previous values for vars are restored when the current

533

block ends. Any rule called or file included will see the

534

local and not the previous value (this is sometimes called

535

Dynamic Scoping). The local statement may appear anywhere,

536

even outside of a block (in which case the previous value

537

is restored when the input ends). The vars are

538

initialized to values if present, or left uninitialized

539

otherwise.

540

541

542

543

on target statement ;

544

545

</CODE>

546

547

<DD> Run statement under the influence of

548

target's target-specific variables. These variables

549

become local copies during statement's run, but they

550

may be updated as target-specific variables using the usual

551

"variable on targets =" syntax.

552

553

554

555

556

return values ;

557

558

</CODE>

559

560

<DD> Within a rule body, the return statement sets the return

561

value for an invocation of the rule and terminates the rule's

562

execution.

563

564

565

566

rule rulename [ : vars ] { statements }

567

568

</CODE>

569

570

<DD> Define a rule's procedure, replacing any previous

571

definition. If vars are provided, they are assigned

572

the values of the parameters ($(1) to $(9)) when statements

573

are executed, as with the local statement.

574

575

576

577

578

switch value

579

</A>

580

{

581

case pattern1 : statements ;

582

case pattern2 : statements ;

583

...

584

}

585

586

</CODE>

587

588

<DD> The switch statement executes zero or one of the

589

enclosed statements, depending on which, if any, is

590

the first case whose pattern matches value.

591

The pattern values are not variable-expanded. The

592

pattern values may include the following wildcards:

593

594

<TABLE>

595

596

597

<TD> match any single character </TD>

598

599

<TD> match zero or more characters </TD>

600

<TR><TD><CODE> [chars] </CODE></TD>

601

<TD> match any single character in chars </TD>

602

<TR><TD><CODE> [^chars] </CODE></TD>

603

<TD> match any single character not in chars </TD>

604

605

<TD> match x (escapes the other wildcards) </TD>

606

607

</TABLE>

608

609

610

611

while cond { statements }

612

613

</CODE>

614

615

<DD> Repeatedly execute statements while cond

616

remains true upon entry. (See the description of cond

617

expression syntax under <a href="#if">if</a>, above).

618

</DL></TABLE>

619

620

621

<DT> <H3> Variables </H3> <DD>

622

623

624

625

Jam variables are lists of zero or more elements, with

626

each element being a string value. An undefined variable is

627

indistinguishable from a variable with an empty list, however,

628

a defined variable may have one more elements which are null

629

strings. All variables are referenced as $(variable).

630

631

632

633

Variables are either global or target-specific. In the latter

634

case, the variable takes on the given value only during the

635

target's binding, header file scanning, and updating; and during

636

the "on target statement" statement.

637

638

639

640

A variable is defined with:

641

642

643

644

645

variable = elements ; </CODE>

646

647

variable += elements ; </CODE>

648

649

variable ?= elements ; </CODE>

650

651

variable on targets = elements ; </CODE>

652

653

variable on targets += elements ; </CODE>

654

655

variable on targets ?= elements ; </CODE>

656

657

</DL></TABLE>

658

659

660

661

The first three forms set variable globally. The last

662

three forms set a target-specific variable. The = operator

663

replaces any previous elements of variable with

664

elements; the += operation adds elements to

665

variable's list of elements; the ?= operator sets

666

variable only if it was previously unset. The last form

667

"variable on targets ?= elements" checks

668

to see if the target-specific, not the global, variable is set.

669

(The ?= operator also has an old form "default =".)

670

671

672

673

Variables referenced in updating commands will be replaced with

674

their values; target-specific values take precedence over global

675

values. Variables passed as arguments ($(1) and $(2)) to actions

676

are replaced with their bound values; the "bind" modifier can

677

be used on actions to cause other variables to be replaced with

678

bound values. See <A HREF="#actionmods">Action Modifiers</A>

679

above.

680

681

682

683

Jam variables are not re-exported to the environment of

684

the shell that executes the updating actions, but the updating

685

actions can reference jam variables with $(variable).

686

687

688

<DT> <H3> Variable Expansion </H3> <DD>

689

</A>

690

691

692

693

During parsing, jam performs variable expansion on each

694

token that is not a keyword or rule name. Such tokens with

695

embedded variable references are replaced with zero or more

696

tokens. Variable references are of the form $(v) or

697

$(vm), where v is the variable name, and m

698

are optional modifiers.

699

700

701

702

Variable expansion in a rule's actions is similar to variable

703

expansion in statements, except that the action string is

704

tokenized at whitespace regardless of quoting.

705

706

707

708

The result of a token after variable expansion is the

709

product of the components of the token, where each

710

component is a literal substring or a list substituting a variable

711

reference. For example:

712

713

714

715

$(X) -> a b c

716

t$(X) -> ta tb tc

717

$(X)z -> az bz cz

718

$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c

719

720

</CODE></TABLE>

721

722

723

724

The variable name and modifiers can themselves contain

725

a variable reference, and this partakes of the product

726

as well:

727

728

729

730

$(X) -> a b c

731

$(Y) -> 1 2

732

$(Z) -> X Y

733

$($(Z)) -> a b c 1 2

734

735

</CODE></TABLE>

736

737

738

739

Because of this product expansion, if any variable reference in

740

a token is undefined, the result of the expansion is an empty

741

list. If any variable element is a null string, the result

742

propagates the non-null elements:

743

744

745

746

$(X) -> a ""

747

$(Y) -> "" 1

748

$(Z) ->

749

*$(X)$(Y)* -> *a* *a1* ** *1*

750

*$(X)$(Z)* ->

751

752

</CODE></TABLE>

753

754

755

756

A variable element's string value can be parsed into grist and

757

filename-related components. Modifiers to a variable are used

758

to select elements, select components, and replace components.

759

The modifiers are:

760

761

762

763

764

<TD>Select element number n (starting at 1). If

765

the variable contains fewer than n elements,

766

the result is a zero-element list.

767

768

769

<TD>Select elements number n through m.

770

771

772

<TD>Select elements number n through the last.

773

774

775

<TD>Select filename base.

776

777

778

<TD>Select (last) filename suffix.

779

780

781

<TD>Select archive member name.

782

783

784

<TD>Select directory path.

785

786

787

<TD>Select parent directory.

788

789

790

<TD>Select grist.

791

792

793

<TD>Replace lowercase characters with uppercase.

794

795

796

<TD>Replace uppercase characters with lowercase.

797

798

<TR><TD><CODE> :chars </CODE>

799

<TD>Select the components listed in chars.

800

801

<TR><TD><CODE> :G=grist </CODE>

802

<TD>Replace grist with grist.

803

804

805

<TD>Replace directory with path.

806

807

808

<TD>Replace the base part of file name with base.

809

810

811

<TD>Replace the suffix of file name with suf.

812

813

814

<TD>Replace the archive member name with mem.

815

816

817

<TD>Prepend root to the whole file name, if not

818

already rooted.

819

820

<TR><TD><CODE> :E=value </CODE>

821

<TD>Use value instead if the variable is unset.

822

823

<TR><TD><CODE> :J=joinval </CODE>

824

<TD>Concatentate list elements into single

825

element, separated by joinval.

826

827

</TABLE>

828

829

830

831

On VMS, $(var:P) is the parent directory of $(var:D); on Unix

832

and NT, $(var:P) and $(var:D) are the same.

833

834

835

<DT> <H3> Built-in Rules </H3> <DD>

836

837

838

Jam has twelve built-in rules, all of which are pure

839

procedure rules without updating actions. They are in

840

three groups: the first builds the dependency graph;

841

the second modifies it; and the third are just utility

842

rules.

843

844

<H5> Dependency Building </H5>

845

846

847

848

849

DEPENDS targets1 : targets2 ;

850

</CODE>

851

852

<DD> Builds a direct dependency: makes each of targets1

853

depend on each of targets2. Generally, targets1

854

will be rebuilt if targets2 are themselves rebuilt are

855

or are newer than targets1.

856

857

858

INCLUDES targets1 : targets2 ;

859

</CODE>

860

861

<DD> Builds a sibling dependency: makes any target that depends

862

on any of targets1 also depend on each of targets2.

863

This reflects the dependencies that arise when one source file

864

includes another: the object built from the source file depends

865

both on the original and included source file, but the two

866

sources files don't depend on each other. For example:

867

868

<CODE>

869

DEPENDS foo.o : foo.c ;

870

INCLUDES foo.c : foo.h ;

871

</CODE>

872

873

874

875

"foo.o" depends on "foo.c" and "foo.h" in this example.

876

877

</DL></TABLE>

878

879

880

<H5> Modifying Binding </H5>

881

</A>

882

883

884

885

The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and

886

TEMPORARY modify the dependency graph so that jam treats

887

the targets differently during its target binding phase. See

888

<A HREF="#binding">Binding</A> above. Normally, jam

889

updates a target if it is missing, if its filesystem modification

890

time is older than any of its dependencies (recursively), or if

891

any of its dependencies are being updated. This basic behavior

892

can be changed by invoking the following rules:

893

894

895

896

897

ALWAYS targets ;

898

</CODE>

899

900

<DD> Causes targets to be rebuilt regardless of whether

901

they are up-to-date (they must still be in the dependency graph).

902

This is used for the clean and uninstall targets, as they have

903

no dependencies and would otherwise appear never to need building.

904

It is best applied to targets that are also NOTFILE targets,

905

but it can also be used to force a real file to be updated as

906

well.

907

908

909

LEAVES targets ;

910

</CODE>

911

912

<DD> Makes each of targets depend only on its leaf sources,

913

and not on any intermediate targets. This makes it immune to

914

its dependencies being updated, as the "leaf" dependencies are

915

those without their own dependencies and without updating actions.

916

This allows a target to be updated only if original source files

917

change.

918

919

920

NOCARE targets ;

921

</CODE>

922

923

<DD> Causes jam to ignore targets that neither

924

can be found nor have updating actions to build them. Normally

925

for such targets jam issues a warning and then skips

926

other targets that depend on these missing targets. The HdrRule

927

in Jambase uses NOCARE on the header file names found during

928

header file scanning, to let jam know that the included

929

files may not exist. For example, if a #include is within an

930

#ifdef, the included file may not actually be around.

931

932

933

NOTFILE targets ;

934

</CODE>

935

936

<DD> Marks targets as pseudotargets and not real files.

937

No timestamp is checked, and so the actions on such a target

938

are only executed if the target's dependencies are updated, or

939

if the target is also marked with ALWAYS. The default jam

940

target "all" is a pseudotarget. In Jambase, NOTFILE is used to

941

define several addition convenient pseudotargets.

942

943

944

NOUPDATE targets ;

945

</CODE>

946

947

<DD> Causes the timestamps on targets to be ignored.

948

This has two effects: first, once the target has been created

949

it will never be updated; second, manually updating target will

950

not cause other targets to be updated. In Jambase, for example,

951

this rule is applied to directories by the MkDir rule, because

952

MkDir only cares that the target directory exists, not when it

953

has last been updated.

954

955

956

TEMPORARY targets ;

957

</CODE>

958

959

<DD> Marks targets as temporary, allowing them to be

960

removed after other targets that depend upon them have been

961

updated. If a TEMPORARY target is missing, jam uses the

962

timestamp of the target's parent. Jambase uses TEMPORARY to

963

mark object files that are archived in a library after they are

964

built, so that they can be deleted after they are archived.

965

966

</DL></TABLE>

967

968

<H5> Utility Rules </H5>

969

970

The remaining rules are utility rules.

971

972

973

974

975

ECHO args ;

976

Echo args ;

977

echo args ;

978

</CODE>

979

980

<DD> Blurts out the message args to stdout.

981

982

983

EXIT args ;

984

Exit args ;

985

exit args ;

986

</CODE>

987

988

<DD> Blurts out the message args to stdout and then exits

989

with a failure status.

990

991

992

GLOB directories : patterns ;

993

</CODE>

994

995

<DD> Scans directories for files matching patterns,

996

returning the list of matching files (with directory prepended).

997

patterns uses the same syntax as in the switch

998

statement. Only useful within the <tt>[ ]</tt> construct, to

999

change the result into a list.

1000

1001

1002

MATCH regexps : list ;

1003

</CODE>

1004

1005

<DD> Matches the egrep(1) style regular expressions

1006

regexps against the strings in list. The result

1007

is the concatenation of matching <tt>()</tt> subexpressions for

1008

each string in list, and for each regular expression in

1009

regexps. Only useful within the <tt>[ ]</tt> construct,

1010

to change the result into a list.

1011

1012

</DL></TABLE>

1013

1014

<DT> <H3> Built-in Variables </H3> <DD>

1015

1016

1017

1018

This section discusses variables that have special meaning to

1019

jam.

1020

1021

1022

<H4> SEARCH and LOCATE Variables </H4>

1023

</A>

1024

1025

1026

1027

These two variables control the binding of file target names to

1028

locations in the file system. Generally, $(SEARCH) is used to

1029

find existing sources while $(LOCATE) is used to fix the location

1030

for built targets.

1031

1032

1033

1034

Rooted (absolute path) file targets are bound as is. Unrooted

1035

file target names are also normally bound as is, and thus relative

1036

to the current directory, but the settings of $(LOCATE) and

1037

$(SEARCH) alter this:

1038

1039

1040

1041

<UL>

1042

1043

<LI> If $(LOCATE) is set then the target is bound relative to

1044

the first directory in $(LOCATE). Only the first element is

1045

used for binding.

1046

1047

<LI> If $(SEARCH) is set then the target is bound to the first

1048

directory in $(SEARCH) where the target file already exists.

1049

1050

<LI> If the $(SEARCH) search fails, the target is bound relative

1051

to the current directory anyhow.

1052

1053

</UL>

1054

1055

1056

1057

Both $(SEARCH) and $(LOCATE) should be set target-specific and

1058

not globally. If they were set globally, jam would use

1059

the same paths for all file binding, which is not likely to

1060

produce sane results. When writing your own rules, especially

1061

ones not built upon those in Jambase, you may need to set

1062

$(SEARCH) or $(LOCATE) directly. Almost all of the rules defined

1063

in Jambase set $(SEARCH) and $(LOCATE) to sensible values for

1064

sources they are looking for and targets they create, respectively.

1065

1066

1067

<H4> HDRSCAN and HDRRULE Variables </H4>

1068

</A>

1069

1070

1071

1072

These two variable control header file scanning. $(HDRSCAN) is

1073

an egrep(1) pattern, with ()'s surrounding the file name,

1074

used to find file inclusion statements in source files. Jambase

1075

uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE)

1076

is the name of a rule to invoke with the results of the scan:

1077

the scanned file is the target, the found files are the sources.

1078

$(HDRRULE) is run under the influence of the scanned file's

1079

target-specific variables.

1080

1081

1082

1083

Both $(HDRSCAN) and $(HDRRULE) must be set for header file

1084

scanning to take place, and they should be set target-specific

1085

and not globally. If they were set globally, all files, including

1086

executables and libraries, would be scanned for header file

1087

include statements.

1088

1089

1090

1091

The scanning for header file inclusions is not exact, but it is

1092

at least dynamic, so there is no need to run something like

1093

makedepend(GNU) to create a static dependency file. The

1094

scanning mechanism errs on the side of inclusion (i.e., it is

1095

more likely to return filenames that are not actually used by

1096

the compiler than to miss include files) because it can't tell

1097

if #include lines are inside #ifdefs or other conditional logic.

1098

In Jambase, HdrRule applies the NOCARE rule to each header file

1099

found during scanning so that if the file isn't present yet

1100

doesn't cause the compilation to fail, jam won't care.

1101

1102

1103

1104

Also, scanning for regular expressions only works where the

1105

included file name is literally in the source file. It can't

1106

handle languages that allow including files using variable names

1107

(as the Jam language itself does).

1108

1109

<H4> Platform Identifier Variables </H4>

1110

1111

1112

1113

A number of Jam built-in variables can be used to identify

1114

runtime platform:

1115

1116

1117

1118

1119

1120

<TR><TD>OS<TD>OS identifier string

1121

<TR><TD>OSPLAT<TD>Underlying architecture, when applicable

1122

<TR><TD>MAC<TD>true on MAC platform

1123

<TR><TD>NT<TD>true on NT platform

1124

<TR><TD>OS2<TD>true on OS2 platform

1125

<TR><TD>UNIX<TD>true on Unix platforms

1126

<TR><TD>VMS<TD>true on VMS platform

1127

1128

</TABLE>

1129

1130

<H4> Jam Version Variables </H4>

1131

1132

1133

1134

1135

1136

<TR><TD>JAMDATE<TD>Time and date at jam start-up.

1137

<TR><TD>JAMUNAME<TD>Ouput of uname(1) command (Unix only)

1138

<TR><TD>JAMVERSION<TD>jam version, as reported by jam -v.

1139

1140

</TABLE>

1141

1142

<H4> JAMSHELL Variable </H4>

1143

1144

1145

1146

When jam executes a rule's action block, it forks and

1147

execs a shell, passing the action block as an argument to the

1148

shell. The invocation of the shell can be controlled by

1149

$(JAMSHELL). The default on Unix is, for example:

1150

1151

1152

1153

<CODE>JAMSHELL = /bin/sh -c % ;</CODE>

1154

1155

1156

1157

The % is replaced with the text of the action block.

1158

1159

1160

1161

Jam does not directly support building in parallel across

1162

multiple hosts, since that is heavily dependent on the local

1163

environment. To build in parallel across multiple hosts, you

1164

need to write your own shell that provides access to the multiple

1165

hosts. You then reset $(JAMSHELL) to reference it.

1166

1167

1168

1169

Just as jam expands a % to be the text of the rule's

1170

action block, it expands a ! to be the multi-process slot number.

1171

The slot number varies between 1 and the number of concurrent

1172

jobs permitted by the -j flag given on the command line. Armed

1173

with this, it is possible to write a multiple host shell. For

1174

example:

1175

1176

1177

1178

1179

1180

#!/bin/sh

1181

1182

# This sample JAMSHELL uses the SunOS on(1) command to execute a

1183

# command string with an identical environment on another host.

1184

1185

# Set JAMSHELL = jamshell ! %

1186

#

1187

# where jamshell is the name of this shell file.

1188

#

1189

# This version handles up to -j6; after that they get executed

1190

# locally.

1191

1192

case $1 in

1193

1|4) on winken sh -c "$2";;

1194

2|5) on blinken sh -c "$2";;

1195

3|6) on nod sh -c "$2";;

1196

*) eval "$2";;

1197

esac

1198

1199

</CODE></TABLE>

1200

1201

1202

<DT> <H2> DIAGNOSTICS </H2> <DD>

1203

1204

1205

1206

In addition to generic error messages, jam may emit one of

1207

the following:

1208

1209

1210

1211

<DT><CODE> warning: unknown rule X </CODE> <DD>

1212

1213

A rule was invoked that has not been defined with

1214

an "actions" or "rule" statement.

1215

1216

<DT><CODE> using N temp target(s) </CODE> <DD>

1217

1218

Targets marked as being temporary (but nonetheless

1219

present) have been found.

1220

1221

<DT><CODE> updating N target(s) </CODE> <DD>

1222

1223

Targets are out-of-date and will be updated.

1224

1225

<DT><CODE> can't find N target(s) </CODE> <DD>

1226

1227

Source files can't be found and there are no

1228

actions to create them.

1229

1230

<DT><CODE> can't make N target(s) </CODE> <DD>

1231

1232

Due to sources not being found, other targets cannot be made.

1233

1234

<DT><CODE> warning: X depends on itself </CODE> <DD>

1235

1236

A target depends on itself either directly or

1237

through its sources.

1238

1239

1240

1241

A target is not present and no actions have been

1242

defined to create it.

1243

1244

<DT><CODE> X skipped for lack of Y </CODE> <DD>

1245

1246

A source failed to build, and thus a target cannot

1247

be built.

1248

1249

<DT><CODE> warning: using independent target X </CODE> <DD>

1250

1251

A target that is not a dependency of any other

1252

target is being referenced with $(<) or $(>).

1253

1254

<DT><CODE> X removed </CODE> <DD>

1255

1256

Jam removed a partially built target after being

1257

interrupted.

1258

1259

</DL></TABLE>

1260

1261

<DT> <H2> BUGS, LIMITATIONS </H2> <DD>

1262

1263

1264

1265

The -j flag can cause jam to get confused when single

1266

actions update more than one target at a time. jam may

1267

proceed as if the targets were built even though they are still

1268

under construction.

1269

1270

1271

1272

For parallel building to be successful, the dependencies among

1273

files must be properly spelled out, as targets tend to get built

1274

in a quickest-first ordering. Also, beware of un-parallelizable

1275

commands that drop fixed-named files into the current directory,

1276

like yacc(1) does.

1277

1278

1279

1280

With the -j flag, errors from failed commands can get staggeringly

1281

mixed up.

1282

1283

1284

1285

A poorly set $(JAMSHELL) is likely to result in silent failure.

1286

1287

1288

1289

1290

1291

<UL>

1292

1293

<LI> <a href="Jambase.html">Jambase Reference</a>

1294

1295

<LI> <a href="Jamfile.html">Using Jamfiles and Jambase</a>

1296

1297

</UL>

1298

1299

1300

1301

Jam documentation and source are available from the <A

1302

HREF="http://public.perforce.com/public/index.html">Perforce

1303

Public Depot</a>.

1304

1305

<DT> <H2> AUTHOR </H2> <DD>

1306

1307

1308

Jam's author is Christopher Seiwald (<a

1309

href="mailto:seiwald@perforce.com">seiwald@perforce.com</A>).

1310

Documentation is provided by

1311

<A HREF="http://www.perforce.com">Perforce Software, Inc.</A>

1312

1313

</DL>

1314

1315

<HR>

1316

1317

1318

1319

1320

1321

Comments to <A HREF="mailto:info@perforce.com">info@perforce.com</A>

1322

1323

Last updated: May, 2002

1324

1325

$Id: //public/jam/src/Jam.html#19 $

1326

1327

</BODY>

1328

</HTML>

1329