Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/tools/build/jam_src/Jamfile.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago
added boost
File size: 49.0 KB

Line
1	<HTML>
2	<TITLE>
3	Jamfiles and Jambase
4	</TITLE>
5	<BODY>
6	<CENTER>
7	<A HREF=http://www.perforce.com/jam/jam.html>
8	Jam/MR
9	</a>
10	<A NAME="TOP">
11	<H2>
12	Using Jamfiles and Jambase
13	</H2>
14	</A>
15	</CENTER>
16	<P>
17	This document describes how to write Jamfiles using the Jam/MR Jambase
18	rules to build software products.
19	Related documents of interest are:
20	<UL>
21	<LI>
22	<a href="Jam.html">The Jam/MR Executable Program</A>,
23	which describes using the <b>jam</b> command and the
24	langauge used in Jambase
25	<LI>
26	<A href="Jambase.html">Jambase Reference</A>,
27	which summarizes the Jambase rules and variables
28	</UL>
29	<P>
30	Jam/MR documentation and source are available from the
31	<A HREF=http://public.perforce.com/public/index.html>Perforce Public Depot</a>.
32	<HR>
33	<P>
34	<H2>
35	Overview
36	</H2>
37	<P>
38	<B>jam,</B> the Jam executable program,
39	recursively builds target files from source files
40	using dependency and build specifications defined
41	in Jam rules files.
42	<B>jam</B> parses the rules files to identify targets
43	and sources,
44	examines the filesystem to determine which
45	targets need updating, and issues OS commands to update
46	targets.
47	<P>
48	A base rules file called "Jambase" is provided with the
49	Jam distribution.
50	The Jambase file defines rules and variables which support
51	standard software build operations, like compiling, linking,
52	etc.
53	<P>
54	When the Jambase rules are used,
55	<B>jam</B> reads Jambase, then reads a file called
56	"Jamfile" in the current directory.
57	The Jamfile describes what to do with the source files in
58	its directory. It may also cause
59	Jamfiles in other directories to be read.
60	<P>
61	Under certain circumstances, the first Jamfile read
62	also causes a site-specific "Jamrules" file to be read.
63	The Jamrules file is an optional set of rule and variable
64	definitions used to define site-specific processing.
65	<P>
66	<H4>
67	The Basic Jamfile
68	</H4>
69	<P>
70	Jamfiles contain rule invocations, which usually look like:
71	<PRE>
72	<I>RuleName</I> <I>targets</I> : <I>targets</I> ;
73	</PRE>
74	The target(s) to the left of the colon usually indicate
75	what gets built, and the target(s) to the right of the
76	colon usually indicate what it is built from.
77	<P>
78	<P>
79	A Jamfile can be as simple as this:
80	<PRE>
81	Main myprog : main.c util.c ;
82	</PRE>
83	This specifies that there is a main.c and util.c file in the same
84	directory as the Jamfile, and that those source files should be
85	compiled and linked into an executable called myprog.
86	If you cd to the directory where this Jamfile lives,
87	you can see the exactly how <b>jam</b> would
88	build myprog with:
89	<PRE>
90	jam -n
91	</PRE>
92	Or, you can actually build myprog with the command:
93	<PRE>
94	jam
95	</PRE>
96
97	<P>
98	<H4>
99	Whitespace
100	</H4>
101	Jamfile elements are delimited by whitespace (blanks, tabs, or
102	newlines). Elements to be delimited include rule names, targets,
103	colons, and semicolons. A common mistake users make is to forget the
104	whitespace, e.g.,
105	<PRE>
106	Main myprog: main.c util.c ; #<I>WRONG!</I>
107	</PRE>
108	Jam doesn't distinguish between a typo and a target called "myprog:",
109	so if you get strange results, the first thing
110	you should check for in your Jamfile is missing whitespace.
111	<P>
112	<H4>
113	Filenames, Target Identifiers, and Buildable Targets
114	</H4>
115	<P>
116	Consider this Jamfile:
117	<PRE>
118	Main myprog : main.c util.c ;
119	LinkLibraries myprog : libtree ;
120	Library libtree : treemake.c treetrav.c ;
121	</PRE>
122	<P>
123	The Main rule specifies that an executable called myprog will be built.
124	The compiled main.c and util.c objects will be linked to produce
125	myprog.
126	The LinkLibraries rule specifies that libtree will
127	be linked into myprog as well.
128	The Library rule specifies which source files will be compiled and
129	archived into the libtree library.
130	<P>
131	The Jamfile above refers to targets like "myprog" and "libtree".
132	However, depending on the platform you're building on, the actual
133	filenames of those targets could be "myprog.exe" and "libtree.lib".
134	Most Jambase rules supply the actual filenames of targets,
135	so that Jamfiles themselves need not make any
136	platform-specific filename references.
137	<P>
138	The <b>jam</b> program builds up a list of unique target identifiers.
139	Unless you are using the SubDir rules (described later),
140	the default identifier for a file target is its filename. In the above
141	example, the target identifiers are the filenames: myprog.exe,
142	libtree.lib, main.obj, etc.
143	<P>
144	While all Jambase rules refer to "targets",
145	not all targets are buildable.
146	There are two kinds of buildable targets:
147	file targets and pseudotargets.
148	File targets are objects that can be found in the filesystem.
149	Pseudotargets are symbolic, and represent other targets.
150	<P>
151	You can use any buildable target on the <b>jam</b> command line to
152	build a subset of defined targets. For example:
153	<PRE>
154	jam libtree.a
155	</PRE>
156	on Unix builds the libtree library and all the compiled objects
157	that go in it.
158	<P>
159	<H4>
160	Pseudotargets
161	</H4>
162	<P>
163	Most Jambase rules that define file targets also define pseudotargets
164	which are dependent on types of file targets.
165	For example, Jambase defines a pseudotarget called "lib", which
166	is dependent on file targets created by the Library rule. So
167	the command:
168	<PRE>
169	jam lib
170	</PRE>
171	used with the above example would cause the libtree library to be built.
172	Also, there is one pseudotarget built into <b>jam</b> itself, called
173	"all". Jambase sets "all" dependent on (almost) all other targets.
174	<P>
175	In the unfortunate case where you have a buildable target whose name
176	is the same as one of the Jambase pseudotargets, you'll have problems
177	with the conflicting target name.
178	Your workaround choices are:
179	<P>
180	<ol>
181	<lI>Change the name of your buildable file or directory that conflicts.
182	<p>
183	<li>Modify your Jambase and change the name of the conflicting pseudotarget.
184	(Pseudotargets are defined in Jambase using the NOTFILE rule.)
185	<p>
186	<li>Use grist on the conflicting target name in your Jamfile. E.g., instead
187	of
188	<PRE>
189	File lib : libfoo.a ;
190	</PRE>
191	try
192	<PRE>
193	File <dir>lib : libfoo.a ;
194	</PRE>
195	</ol>
196	<P>
197
198	<H4>
199	Dependencies
200	</H4>
201	<P>
202	Jambase rules set dependencies on targets, so that if you update a
203	source file, all the file targets that depend on that source
204	file, and only the ones that depend on that source file,
205	will be updated (rebuilt) the next time you run <b>jam</b>.
206	<P>
207	Here are some of the dependencies
208	that get set when <b>jam</b> runs on NT using the example Jamfile above:
209	<CENTER>
210	<TABLE>
211	<TR><TD><B>Target</B><TD>   <TD><B>Depends on</B></TD>
212	<TR><TD>myprog.exe<TD><TD>main.obj, util.obj, libtree.lib
213	<TR><TD>libtree.lib<TD><TD>treemake.obj, treetrav.obj
214	<TR><TD>treetrav.obj<TD><TD>treetrav.c
215	</TABLE>
216	</CENTER>
217	<P>
218	Furthermore, the Main and Library rules set up recursive
219	header scanning on their source targets.
220	So after <b>jam</b> has finished parsing the Jamfile and
221	setting the rule-driven dependencies, it scans the source
222	files for "#include" lines. All #include files found during
223	this scan become dependencies of the compiled object.
224	E.g., all header files used to compile treetrav.c would
225	be made dependencies of treetrav.obj.
226	<P>
227	As a result, when you run <b>jam</b>, it will rebuild targets
228	if either the source files change or the
229	header files change. You can't tell by looking at a Jamfile
230	which header files are dependencies, but you can easily
231	display those dependencies with:
232	<PRE>
233	jam -nd+3
234	</PRE>
235	<H4>
236	Rule Ordering
237	</H4>
238	<P>
239	Rules which specify dependencies, like the Main, Library, and
240	LinkLibrary rules, can be invoked in any order. <b>jam</b>
241	figures out the order in which targets are built from
242	their dependencies.
243	<P>
244	Some rules, however, set variables which are used by subsequent
245	rule invocations, and their ordering is important.
246	For example, the SubDir* rules (discussed
247	later) must be invoked in a particular order.
248
249	<P>
250	<H4>
251	Detailed Jambase Specifications
252	</H4>
253	<P>
254	This document describes how to use various Jambase rules
255	from a functional point of view.
256	You can see the summary of available Jambase rules in the
257	<a href="Jambase.html">Jambase Reference</A>.
258	The detailed specifications for any Jambase rule
259	can be found by reading the rule definition itself
260	in the Jambase file.
261	<P>
262
263	<HR>
264	<H2>
265	Handling Directory Trees
266	</H2>
267	The SubDir* rules are used to
268	define source code directory hierarchies.
269	With SubDir and SubInclude, you can use <b>jam</b>
270	to build software from source files and Jamfiles spread
271	across many directories, as is typical for large projects.
272	The SubDir* rules unify an entire
273	source code tree so that <b>jam</b> can read in
274	all the Jamfiles in one pass and
275	compute dependencies across the entire project.
276	<P>
277	To use the SubDir* rules, you must:
278	<P>
279	<OL>
280	<LI> Preface the Jamfile in each directory with an invocation
281	of the SubDir rule.
282	<P>
283	<LI> Place at the root of the tree a file named Jamrules.
284	This file could be empty, but in
285	practice it contains user-provided rules and variable
286	definitions that are shared throughout the
287	tree. Examples of such definitions are library
288	names, header directories, install directories,
289	compiler flags, etc. This file is good candidate
290	for automatic customizing with autoconf(GNU).
291	<P>
292	<LI> Optionally, set an environment variable pointing
293	to the root directory of the srouce tree. The
294	variable's name is left up to you, but in these
295	examples, we use TOP.
296	</OL>
297	<P>
298	<H4>
299	SubDir Rule
300	</H4>
301	<P>
302	The SubDir rule must be invoked before any rules that
303	refer to the contents of the directory - it is best to put
304	it at the top of each Jamfile. For example:
305	<PRE>
306	# Jamfile in $(TOP)/src/util directory.
307
308	SubDir TOP src util ;
309
310	Main myprog : main.c util.c ;
311	LinkLibraries myprog : libtree ;
312	Library libtree : treemake.c treetrav.c ;
313	</PRE>
314	This compiles four files in $(TOP)/src/util, archives
315	two of the objects into libtree, and links the whole
316	thing into myprog.
317	Outputs are placed in the $(TOP)/src/util
318	directory.
319	<P>
320	This doesn't appear to be any different from
321	the previous example that didn't have a SubDir rule,
322	but two things are happening behind the scenes:
323	<OL>
324	<LI>The SubDir rule causes <b>jam</b> to read
325	in the $(TOP)/Jamrules file.
326	(The Jamrules file can alternately be named by the
327	variable $(xxxRULES), where xxx is the name of the
328	root variable, e.g., $(TOPRULES)).
329	<P>
330	The Jamrules file can contain variable definitions
331	and rule definitions specific to your codeline.
332	It allows you to completely customize your build
333	environment without having to rewrite Jambase.
334	Jamrules is only read
335	in once, at the first SubDir invocation.
336	<P>
337	<LI>
338	The SubDir rule initializes a set of variables
339	that are used by Main and other rules to
340	uniquely identify the source files in this
341	directory and assign locations to the targets
342	built from files in this directory.
343	<P>
344	When you have set a root variable, e.g., $(TOP),
345	SubDir constructs path names rooted with $(TOP),
346	e.g., $(TOP)/src/util.
347	Otherwise, SubDir constructs relative pathnames
348	to the root directory, computed from the number
349	of arguments to the first SubDir rule, e.g.,
350	../../src/util. In either case, the SubDir
351	rule constructs the path names that locate source
352	files.
353	You'll see how this is useful later.
354	<P>
355	</UL>
356
357	<P>
358	The SubDir rule takes as its first argument the root
359	variable's name and takes as subsequent arguments the
360	directory names leading from the root to the directory of
361	the current Jamfile. Note that the name of the subdirectory
362	is given as individual elements: the SubDir rule
363	does not use system-specific directory name syntax.
364	<P>
365	<P>
366	<H4>
367	SubInclude Rule
368	</H4>
369	The SubInclude rule is used in a Jamfile to cause another
370	Jamfile to be read in.
371	Its arguments are in the same format as
372	SubDir's.
373	<P>
374	The recommended practice is only to include one level of
375	subdirectories at a time, and let the Jamfile in each subdirectory
376	include its own subdirectories. This allows a
377	user to sit in any arbitrary directory of the source tree
378	and build that subtree. For example:
379	<PRE>
380	# This is $(TOP)/Jamfile, top level Jamfile for mondo project.
381
382	SubInclude TOP src ;
383	SubInclude TOP man ;
384	SubInclude TOP misc ;
385	SubInclude TOP util ;
386	</PRE>
387	If a directory has both subdirectories of its own as well
388	as files that need building, the SubIncludes should be
389	either before the SubDir rule or be at the end of the Jamfile
390	- not between the SubDir and other rule invocations.
391	For example:
392	<PRE>
393	# This is $(TOP)/src/Jamfile:
394
395	SubDir TOP src ;
396
397	Main mondo : mondo.c ;
398	LinkLibraries mondo : libmisc libutil ;
399
400	SubInclude TOP src misc ;
401	SubInclude TOP src util ;
402	</PRE>
403	<P>
404	(<b>jam</b> processes all the Jamfiles it reads as if
405	it were reading one single, large Jamfile.
406	Build rules like Main and LinkLibraries rely on the
407	preceding SubDir rule to set up source file and
408	output file locations, and SubIncludes rules read in
409	Jamfiles that contain SubDir rules. So if you put
410	a SubIncludes rule between a SubDir and a Main
411	rule, <b>jam</b> will try to find the source files
412	for the Main rule in the wrong directory.)
413	<P>
414	<H4>
415	Variables Used to Handle Directory Trees
416	</H4>
417	The following variables are set by the SubDir rule
418	and used by the Jambase rules that define file targets:
419	<P>
420	<CENTER>
421	<TABLE>
422	<TR><TD VALIGN=TOP>
423	SEARCH_SOURCE
424	<TD><TD>The SubDir targets (e.g., "TOP src util")
425	are used to construct a pathname (e.g., $(TOP)/src/util),
426	and that pathname is assigned to $(SEARCH_SOURCE).
427	Rules like Main and Library use $(SEARCH_SOURCE)
428	to set search paths on source files.
429	<TR><TD VALIGN=TOP>
430	LOCATE_SOURCE
431	<TD><TD>Initialized by the SubDir rule to the same
432	value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET
433	is set.
434	$(LOCATE_SOURCE) is used by rules that build
435	generated source files (e.g., Yacc and Lex) to
436	set location of output files.
437	Thus the default location of built source files
438	is the directory of the Jamfile that defines them.
439	<TR><TD VALIGN=TOP>
440	LOCATE_TARGET
441	<TD><TD>Initalized by the SubDir rule to the same
442	value as $(SEARCH_SOURCE), unless ALL_LOCATE_TARGET
443	is set.
444	$(LOCATE_TARGET) is used by rules that build
445	binary objects (e.g., Main and Library) to
446	set location of output files.
447	Thus the default location of built binaray files
448	is the directory of the Jamfile that defines them.
449	<TR><TD VALIGN=TOP>
450	ALL_LOCATE_TARGET
451	<TD><TD>
452	If $(ALL_LOCATE_TARGET) is set, LOCATE_SOURCE
453	and and LOCATE_TARGET are set to $(ALL_LOCATE_TARGET)
454	instead of to $(SEARCH_SOURCE). This can be used to
455	direct built files to be written to a location outside
456	of the source tree, and enables building from read-only
457	source trees.
458	<TR><TD VALIGN=TOP>
459	SOURCE_GRIST
460	<TD><TD>The SubDir targets are formed into a string
461	like "src!util" and that string is assigned to
462	SOURCE_GRIST. Rules that define file targets
463	use $(SOURCE_GRIST) to set the "grist" attribute
464	on targets. This is used to assure uniqueness
465	of target identifiers where filenames themselves
466	are not unique.
467	For example, the target identifiers of
468	$(TOP)/src/client/main.c and $(TOP)/src/server/main.c
469	would be <src!client>main.c and <src!server>main.c.
470	</TABLE>
471	</CENTER>
472	<P>
473	The $(LOCATE_TARGET) and $(SEARCH_SOURCE) variables are used
474	extensively by rules in Jambase: most rules that generate
475	targets (like Main, Object, etc.) set $(LOCATE) to
476	$(LOCATE_TARGET) for the targets they generate, and rules
477	that use sources (most all of them) set $(SEARCH) to be
478	$(SEARCH_SOURCE) for the sources they use.
479	<P>
480	$(LOCATE) and $(SEARCH) are better explained in
481	<A HREF="Jam.html">The Jam Executable Program</A>
482	but in brief they tell <B>jam</B> where to create new targets and
483	where to find existing ones, respectively.
484	<P>
485	Note that you can reset these variables
486	after SubDir sets them. For example, this Jamfile builds
487	a program called gensrc, then runs it to create a source file
488	called new.c:
489	<PRE>
490	SubDir TOP src util ;
491	Main gensrc : gensrc.c ;
492	LOCATE_SOURCE = $(NEWSRC) ;
493	GenFile new.c : gensrc ;
494	</PRE>
495	By default, new.c would be written into the
496	$(TOP)/src/util directory, but resetting LOCATE_SOURCE causes
497	it to be written to the $(NEWSRC) directory. ($(NEWSRC) is assumed
498	to have been set elsewhere, e.g., in Jamrules.)
499	<P>
500	<H4>
501	VMS Notes
502	</H4>
503	On VMS, the logical name table is not imported as is the
504	environment on UNIX. To use the SubDir and related rules,
505	you must set the value of the variable that names the root
506	directory. For example:
507	<PRE>
508	TOP = USR_DISK:[JONES.SRC] ;
509
510	SubInclude TOP util ;
511	</PRE>
512	The variable must have a value that looks like a directory
513	or device. If you choose, you can use a concealed logical.
514	For example:
515	<PRE>
516	TOP = TOP: ;
517
518	SubInclude TOP util ;
519	</PRE>
520	The : at the end of TOP makes the value of $(TOP) look
521	like a device name, which jam respects as a directory name
522	and will use when trying to access files. TOP must then
523	be defined from DCL:
524	<PRE>
525	$ define/job/translation=concealed TOP DK100:[USERS.JONES.SRC.]
526	</PRE>
527	Note three things: the concealed translation allows the
528	logical to be used as a device name; the device name in
529	the logical (here DK100) cannot itself be concealed logical
530	(VMS rules, man); and the directory component of the
531	definition must end in a period (more VMS rules).
532	<P>
533	<H2>
534	Building Executables and Libraries
535	</H2>
536	<P>
537	The rules that build executables and libraries are: Main, Library,
538	and LinkLibraries.
539	<H4>
540	Main Rule
541	</H4>
542	The Main rule compiles source files and links the resulting
543	objects into an executable. For example:
544	<PRE>
545	Main myprog : main.c util.c ;
546	</PRE>
547	This compiles main.c and util.c and links main.o and
548	util.o into myprog. The object files and resulting
549	executable are named appropriately for the platform.
550	<P>
551	Main can also be used to build shared libraries and/or
552	dynamic link libraries, since those are also linked
553	objects. E.g.:
554	<PRE>
555	Main driver$(SUFSHR) : driver.c ;
556	</PRE>
557	Normally, Main uses $(SUFEXE) to determine the suffix on
558	the filename of the built target. To override it,
559	you can supply a suffix explicity.
560	In this case,
561	$(SUFSHR) is assumed to be the OS-specific shared library
562	suffix, defined in Jamrules with something
563	like:
564	<PRE>
565	if $(UNIX) { SUFSHR = .so ; }
566	else if $(NT) { SUFSHR = .dll ; }
567	</PRE>
568	<P>
569	Main uses the Objects rule to compile source targets.
570
571	<H4>
572	Library Rule
573	</H4>
574	The Library rule compiles source files, archives the
575	resulting object files into a library, and then deletes
576	the object files. For example:
577	<PRE>
578	Library libstring : strcmp.c strcpy.c strlen.c ;
579	Library libtree : treemake.c treetrav.c ;
580	</PRE>
581	This compiles five source files, archives three of the
582	object files into libstring and the other two into libtree.
583	Actual library filenames are formed with the $(SUFLIB) suffix.
584	Once the objects are safely in the libraries, the
585	objects are deleted.
586	<P>
587	Library uses the Objects rule to compile source files.
588	<P>
589	<H4>
590	LinkLibraries Rule
591	</H4>
592	To link executables with built libraries, use
593	the LinkLibraries rule. For example:
594	<PRE>
595	Main myprog : main.c util.c ;
596	LinkLibraries myprog : libstring libtree ;
597	</PRE>
598	The LinkLibraries rule does two things: it makes the
599	libraries dependencies of the executable, so that they get
600	built first; and it makes the libraries show up on the
601	command line that links the executable. The ordering of
602	the lines above is not important, because <b>jam</b> builds targets
603	in the order that they are needed.
604	<P>
605	You can put multiple libraries on a single invocation of
606	the LinkLibraries rule, or you can provide them in multiple
607	invocations. In both cases, the libraries appear on
608	the link command line in the order in which they were
609	encountered. You can also provide multiple executables to
610	the LinkLibraries rule, if they need the same libraries,
611	e.g.:
612	<PRE>
613	LinkLibraries prog1 prog2 prog3 : libstring libtree ;
614	</PRE>
615	<P>
616	<H4>
617	Variables Used in Building Executables and Libraries
618	</H4>
619	<CENTER>
620	<TABLE>
621	<TR><TD>
622	AR
623	<TD><TD>Archive command, used for Library targets.
624	<TR><TD>
625	SUFEXE
626	<TD>*<TD>Suffix on filenames of executables referenced
627	by Main and LinkLibraries.
628	<TR><TD>
629	LINK
630	<TD><TD>Link command, used for Main targets.
631	<TR><TD>
632	LINKFLAGS
633	<TD><TD>Linker flags.
634	<TR><TD>
635	LINKLIBS
636	<TD><TD>Link libraries that aren't dependencies. (See note
637	below.)
638	<TR><TD>
639	EXEMODE
640	<TD>*<TD>File permissions on Main targets.
641	<TR><TD>
642	MODE
643	<TD><TD>Target-specific file permissions on Main targets
644	(set from $(EXEMODE))
645	<TR><TD>
646	RANLIB
647	<TD><TD>Name of ranlib program, if any.
648	</TABLE>
649	</CENTER>
650
651	<P>
652	Variables above marked with "*" are used by the Main,
653	Library, and LinkLibraries rules. Their values at the
654	time the rules are invoked are used to set target-specific
655	variables.
656	<P>
657	All other variables listed above are globally defined,
658	and are used in actions that update Main and Library
659	targets. This means that the global values of those
660	variables are used, uness target-specific values have
661	been set.
662	(For instance, a target-specific MODE value is set by
663	the Main rule.)
664	The target-specific values always override
665	global values.
666	<P>
667	Note that there are two ways to specify link libraries for
668	executables:
669	<UL>
670	<LI>Use the LinkLibraries rule
671	to specify built libraries; i.e., libraries
672	that are built by Library rules. This assures that
673	these libraries are built first, and that Main targets are
674	rebuilt when the libraries are updated.
675	<P>
676	<LI>Use the LINKLIBS variable to specify external
677	libraries; e.g., system libraries or third-party libraries.
678	The LINKLIBS variable must be set to the the actual
679	link command flag that specifies the libraries.
680	<P>
681	</UL>
682	<P>
683	For example:
684	<PRE>
685	<I>#In Jamrules:</I>
686	if $(UNIX) { X11LINKLIBS = -lXext -lX11 ; }
687	if $(NT) { X11LINKLIBS = libext.lib libX11.lib ; }
688
689	<I>#In Jamfile:</I>
690	Main xprog : xprog.c ;
691	LINKLIBS on xprog$(SUFEXE) = $(X11LINKLIBS) ;
692	LinkLibraries xprog : libxutil ;
693	Library libxutil : xtop.c xbottom.c xutil.c ;
694	</PRE>
695	This example uses the Jam syntax "variable on target" to
696	set a target-specific variable. In this way, only xprog
697	will be linked with this special $(X11LINKLIBS),
698	even if other executables were going to be built
699	by the same Jamfile. Note that when you set a variable
700	on a target, you have to specify the target identifer
701	exactly, which in this case is the suffixed filename of
702	the executable.
703	The actual link command line on Unix, for example, would
704	look something like this:
705	<PRE>
706	cc -o xprog xprog.o libxutil.a -lXext -lX11
707	</PRE>
708	<H2>
709	Compiling
710	</H2>
711	Compiling of source files occurs normally as a byproduct
712	of the Main or Library rules, which call the rules
713	described here. These rules may also be called explicitly
714	if the Main and Library behavior doesn't satisfy your
715	requirements.
716	<P>
717	<H4>
718	Objects Rule
719	</H4>
720	The Main and Library rules call the Objects rule on source files.
721	Compiled object files built by
722	the Objects rule are a dependency of the <I>obj</i>
723	pseudotarget, so "jam obj" will build object files used in
724	Main and Library rules.
725	<P>
726	Target identifiers created by the Objects rule have grist
727	set to $(SOURCE_GRIST). So given this Jamfile:
728	<PRE>
729	SubDir TOP src lock ;
730	Main locker : lock.c ;
731	</PRE>
732	the object file created is lock.o (or lock.obj) and
733	its target identifier is <src!lock>lock.o
734	(or <src!lock>lock.obj).
735
736	<P>
737	You can also call Objects directly. For example:
738	<PRE>
739	Objects a.c b.c c.c ;
740	</PRE>
741	This compiles a.c into a.o, b.c into b.o, etc. The object
742	file suffix is supplied by the Objects rule.
743	<P>
744	<H4>
745	Object Rule
746	</H4>
747	Objects gets its work done by calling the Object rule on
748	each of the source files.
749	You could use the Object rule directly.
750	For example, on Unix, you could use:
751	<PRE>
752	Object foo.o : foo.c ;
753	</PRE>
754	However, the Object rule does not provide suffixes, and
755	it does not provide the grist needed to construct target
756	identifiers if you are using the SubDir* rules.
757	A portable and robust Jamfile would need to invoke Object thus:
758	<PRE>
759	Object <src!util>foo$(SUFOBJ) : <src!util>foo.c ;
760	</PRE>
761	which is inelegant and clearly shows why using Objects
762	is better than using Object.
763	<P>
764	If there's any advantage to the Object rule, it's
765	that it doesn't require that the object name bear
766	any relationship to the source. It is thus possible to
767	compile the same file into different objects. For example:
768
769	<PRE>
770	Object a.o : foo.c ;
771	Object b.o : foo.c ;
772	Object c.o : foo.c ;
773	</PRE>
774	This compiles foo.c (three times) into a.o, b.o, and c.o.
775	Later examples show how this is useful.
776	<P>
777	The Object rule looks at the suffix of the source file and
778	calls the appropriate rules to do the actual preprocessing
779	(if any) and compiling needed to produce the output object file.
780	The Object rule is
781	capable of the generating of an object file from any
782	type of source. For example:
783	<PRE>
784	Object grammar$(SUFOBJ) : grammar.y ;
785	Object scanner$(SUFOBJ) : scanner.l ;
786	Object fastf$(SUFOBJ) : fastf.f ;
787	Object util$(SUFOBJ) : util.c ;
788	</PRE>
789	An even more elegant way to get the same result is to let the
790	Objects rule call Object:
791	<PRE>
792	Objects grammar.y scanner.l fastf.f util.c ;
793	</PRE>
794	<P>
795	In addition to calling the compile rules, Object sets up
796	a bunch of variables specific to the source and target
797	files. (See Variables Used in Compiling, below.)
798	<P>
799	<H4>
800	Cc, C++, Yacc, Lex, Fortran, As, etc. Rules
801	</H4>
802	<P>
803	The Object rule calls compile rules specific to the suffix of
804	the source file. (You can see which suffixes are supported
805	by looking at the Object rule definition in Jambase.)
806	Because the extra work done by the
807	Object rule, it is not always useful to call the compile
808	rules directly. But the adventurous user might attempt
809	it. For example:
810	<PRE>
811	Yacc grammar.c : grammar.y ;
812	Lex scan.c : scan.l ;
813	Cc prog.o : prog.c ;
814	</PRE>
815	These examples individually run yacc(1), lex(1), and the C
816	compiler on their sources.
817	<P>
818	<H4>
819	UserObject Rule
820	</H4>
821	Any files with suffixes not understood by the Object rule
822	are passed to the UserObject rule. The default definition
823	of UserObject simply emits a warning that the suffix is
824	not understood. This Jambase rule definition is intended to be
825	overridden in Jamrules with one that recognizes the project-specific
826	source file suffixes. For example:
827
828	<PRE>
829	#In Jamrules:
830
831	rule UserObject
832	{
833	switch $(>)
834	{
835	case *.rc : ResourceCompiler $(<) : $(>) ;
836	case * : ECHO "unknown suffix on" $(>) ;
837	}
838	}
839
840	rule ResourceCompiler
841	{
842	DEPENDS $(<) : $(>) ;
843	Clean clean : $(<) ;
844	}
845
846	actions ResourceCompiler
847	{
848	rc /fo $(<) $(RCFLAGS) $(>)
849	}
850
851
852	#In Jamfile:
853
854	Library liblock : lockmgr.c ;
855	if $(NT) { Library liblock : lock.rc ; }
856	</PRE>
857	<P>
858	In this example, the UserObject definition in Jamrules
859	allows *.rc files to be handle as regular Main and Library
860	sources. The lock.rc file is compiled into lock.obj
861	by the "rc" command, and lock.obj is archived into a library
862	with other compiled objects.
863	<H4>
864	LibraryFromObjects Rule
865	</H4>
866	Sometimes the Library rule's straightforward compiling of
867	source into object modules to be archived isn't flexible
868	enough. The LibraryFromObjects rule does the archiving
869	(and deleting) job of the Library rule, but not the compiling.
870	The user can make use of the Objects or Object
871	rule for that. For example:
872	<PRE>
873	LibraryFromObjects libfoo.a : max.o min.o ;
874	Object max.o : maxmin.c ;
875	Object min.o : maxmin.c ;
876	ObjectCcFlags max.o : -DUSEMAX ;
877	ObjectCcFlags min.o : -DUSEMIN ;
878	</PRE>
879	This Unix-specific example compiles the same source file into
880	two different
881	objects, with different compile flags, and archives them.
882	(The ObjectCcFlags rule is described shortly.)
883	Unfortunately, the portable and robust implementation of the
884	above example is not as pleasant to read:
885	<PRE>
886	SubDir TOP foo bar ;
887	LibraryFromObjects libfoo$(SUFLIB) : <foo!bar>max$(SUFOBJ)
888	<foo!bar>min$(SUFOBJ) ;
889	Object <foo!bar>min$(SUFOBJ) : <foo!bar>maxmin.c ;
890	Object <foo!bar>max$(SUFOBJ) : <foo!bar>maxmin.c ;
891	ObjectCcFlags <foo!bar>min$(SUFOBJ) : -DUSEMIN ;
892	ObjectCcFlags <foo!bar>max$(SUFOBJ) : -DUSEMAX ;
893	</PRE>
894	Note that, among other things, you must supply the library
895	file suffix when using the LibraryFromObjects rule.
896	<P>
897	<H4>
898	MainFromObjects Rule
899	</H4>
900	Similar to LibraryFromObjects, MainFromObjects does the
901	linking part of the Main rule, but not the compiling.
902	MainFromObjects can be used when there are no
903	objects at all, and everything is to be loaded from
904	libraries. For example:
905	<PRE>
906	MainFromObjects testprog ;
907	LinkLibraries testprog : libprog ;
908	Library libprog : main.c util.c ;
909	</PRE>
910	On Unix, say, this generates a link command that looks like:
911	<PRE>
912	cc -o testprog libprog.a
913	</PRE>
914	Linking purely from libraries is something that doesn't
915	work everywhere: it depends on the symbol "main" being
916	undefined when the linker encounters the library that contains
917	the definition of "main".
918	<P>
919	<H4>
920	Variables Used in Compiling
921	</H4>
922	The following variables control the compiling of source
923	files:
924	<P>
925	<CENTER>
926	<TABLE>
927	<TR><TD VALIGN=TOP>
928	C++
929	<TD><TD>The C++ compiler command
930	<TR><TD VALIGN=TOP>
931	CC
932	<TD><TD>The C compiler command
933	<TR><TD VALIGN=TOP>
934	C++FLAGS
935	<BR>
936	CCFLAGS
937	<TD VALIGN=TOP><TD VALIGN=TOP>Compile flags, used to
938	create or update compiled objects
939	<TR><TD>
940	SUBDIRC++FLAGS
941	<BR>
942	SUBDIRCCFLAGS
943	<TD VALIGN=TOP><TD VALIGN=TOP>Additonal compile flags
944	for source files in this directory.
945	<TR><TD VALIGN=TOP>
946	OPTIM
947	<TD><TD>Compiler optimization flag. The Cc and C++
948	actions use this as well as C++FLAGS or CCFLAGS.
949	<TR><TD VALIGN=TOP>
950	HDRS
951	<TD VALIGN=TOP><TD>Non-standard header directories; i.e.,
952	the directories the compiler will not look in
953	by default and which therefore must be supplied
954	to the compile command. These directories are
955	also used by <b>jam</b> to scan for include files.
956	<TR><TD VALIGN=TOP>
957	STDHDRS
958	<TD VALIGN=TOP><TD>Standard header directories, i.e., the
959	directories the compiler searches automatically.
960	These are not passed to the compiler, but they
961	are used by <b>jam</b> to scan for include files.
962	<TR><TD>
963	SUBDIRHDRS
964	<TD><TD>Additional paths to add to HDRS for source files
965	in this directory.
966	<TR><TD>
967	LEX
968	<TD><TD>The lex(1) command
969	<TR><TD>
970	YACC
971	<TD><TD>The yacc(1) command
972	</TABLE>
973	</CENTER>
974	<P>
975	The Cc rule sets a target-specific $(CCFLAGS) to the current
976	value of $(CCFLAGS) and $(SUBDIRCCFLAGS). Similarly
977	for the C++ rule. The Object rule sets a target-specific
978	$(HDRS) to the current value of $(HDRS) and $(SUBDDIRHDRS).
979
980	<P>
981	$(CC), $(C++), $(CCFLAGS), $(C++FLAGS), $(OPTIM), and
982	$(HDRS) all affect the compiling of C and C++ files.
983	$(OPTIM) is separate from $(CCFLAGS) and $(C++FLAGS) so
984	they can be set independently.
985	<P>
986	$(HDRS) lists the directories to search for header files,
987	and it is used in two ways: first, it is passed to the C
988	compiler (with the flag -I prepended); second, it is used
989	by HdrRule to locate the header files whose names were
990	found when scanning source files. $(STDHDRS) lists the
991	header directories that the C compiler already knows
992	about. It does not need passing to the C compiler, but is
993	used by HdrRule.
994	<P>
995	Note that these variables, if set as target-specific variables,
996	must be set on the target, not the source file.
997	The target file in this case is the object file to be generated.
998	For example:
999	<PRE>
1000	Library libximage : xtiff.c xjpeg.c xgif.c ;
1001
1002	HDRS on xjpeg$(SUFOBJ) = /usr/local/src/jpeg ;
1003	CCFLAGS on xtiff$(SUFOBJ) = -DHAVE_TIFF ;
1004	</PRE>
1005	This can be done more easily with the rules that follow.
1006	<P>
1007	<H4>
1008	ObjectCcFlags, ObjectC++Flags, ObjectHdrs Rules
1009	</H4>
1010	$(CCFLAGS), $(C++FLAGS) and $(HDRS) can be set on object file
1011	targets
1012	directly, but there are rules that allow these variables
1013	to be set by referring to the original source file name,
1014	rather than to the derived object file name. ObjectCcFlags
1015	adds object-specific flags to the $(CCFLAGS) variable,
1016	ObjectC++Flags adds object-specific flags to the
1017	$(C++FLAGS) variable, and ObjectHdrs add object-specific
1018	directories to the $(HDRS) variable. For example:
1019	<PRE>
1020	#In Jamrules:
1021	if $(NT) { CCFLAGS_X = /DXVERSION ;
1022	HDRS_X = \\\\SPARKY\\X11\\INCLUDE\\X11 ;
1023	}
1024
1025	#In Jamfile:
1026	Main xviewer : viewer.c ;
1027	ObjectCcFlags viewer.c : $(CCFLAGS_X) ;
1028	ObjectHdrs viewer.c : $(HDRS_X) ;
1029	</PRE>
1030	The ObjectCcFlags and ObjectHdrs rules take .c files
1031	as targets, but actually set $(CCFLAGS) and $(HDRS) values
1032	on the .obj (or .o) files. As a result, the action
1033	that updates the target .obj file uses the target-specific
1034	values of $(CCFLAGS) and $(HDRS).
1035	<P>
1036	<H4>
1037	SubDirCcFlags, SubDirC++Flags, SubDirHdrs Rules
1038	</H4>
1039	These rules set the values of $(SUBDIRCCFLAGS), $(SUBDIRC++FLAGS)
1040	and $(SUBDIRHDRS), which are used by the Cc,
1041	C++, and Object rules when setting the target-specific
1042	values for $(CCFLAGS), $(C++FLAGS) and $(HDRS). The SubDir
1043	rule clears these variables out, and thus they provide
1044	directory-specific values of $(CCFLAGS), $(C++FLAGS) and
1045	$(HDRS). For example:
1046	<PRE>
1047	#In Jamrules:
1048	GZHDRS = $(TOP)/src/gz/include ;
1049	GZFLAG = -DGZ ;
1050
1051	#In Jamfile:
1052	SubDir TOP src gz utils ;
1053
1054	SubDirHdrs $(GZHDRS) ;
1055	SubDirCcFlags $(GZFLAG) ;
1056
1057	Library libgz : gizmo.c ;
1058	Main gizmo : main.c ;
1059	LinkLibraries gizmo : libgz ;
1060	</PRE>
1061	All .c files in this directory files will be compiled with
1062	$(GZFLAG) as well as the default $(CCFLAG), and the include
1063	paths used on the compile command will be $(GZHDRS) as well
1064	as the default $(HDRS).
1065	<H2>
1066	Header File Processing
1067	</H2>
1068	One of the functions of the Object rule is set up
1069	scanning of source
1070	files for (C style) header file inclusions. To do so, it
1071	sets the special variables $(HDRSCAN) and $(HDRRULE)
1072	as target-specific variables on the source file. The
1073	presence of these variables triggers a special mechanism
1074	in <B>jam</B> for scanning a file for header file inclusions and
1075	invoking a rule with the results of the scan. The
1076	$(HDRSCAN) variable is set to an egrep(1) pattern that
1077	matches "#include" statements in C source files, and the
1078	$(HDRRULE) variable is set to the name of the rule that
1079	gets invoked as such:
1080	<PRE>
1081	$(HDRRULE) source-file : included-files ;
1082	</PRE>
1083	This rule is supposed to set up the dependencies between
1084	the source file and the included files. The Object rule
1085	uses HdrRule to do the job. HdrRule itself expects
1086	another variable, $(HDRSEARCH), to be set to the list of
1087	directories where the included files can be found. Object
1088	does this as well, setting $(HDRSEARCH) to $(HDRS) and
1089	$(STDHDRS).
1090	<P>
1091	The header file scanning occurs during the "file binding"
1092	phase of <b>jam</b>, which means that the target-specific
1093	variables (for the source file) are in effect. To accomodate
1094	nested includes, one of the HdrRule's jobs is to pass
1095	the target-specific values of $(HDRRULE), $(HDRSCAN), and
1096	$(HDRSEARCH) onto the included files, so that they will be
1097	scanned as well.
1098	<P>
1099	<H4>
1100	HdrRule Rule
1101	</H4>
1102	Normally, HdrRule is not invoked directly; the Object rule
1103	(called by Main and Library) invokes it.
1104	<P>
1105	If there are special dependencies that need to be set,
1106	and which are not set by HdrRule itself, you can define
1107	another rule and let it invoke HdrRule. For example:
1108
1109	<PRE>
1110	#In Jamrules:
1111	rule BuiltHeaders
1112	{
1113	DEPENDS $(>) : mkhdr$(SUFEXE) ;
1114	HdrRule $(<) : $(>) ;
1115	}
1116
1117	#In Jamfile:
1118	Main mkhdr : mkhdr.c ;
1119	Main ugly : ugly.c ;
1120
1121	HDRRULE on ugly.c = BuiltHeaders ;
1122
1123	</PRE>
1124	This example just says that the files included by "ugly.c"
1125	are generated by the program "mkhdr", which can be built
1126	from "mkhdr.c". During the binding phase, <b>jam</b> will
1127	scan ugly.c, and if it finds an include file, ughdr.h,
1128	for example, it will automatically invoke the rule:
1129	<PRE>
1130	BuiltHeaders ugly.c : ughdr.h ;
1131	</PRE>
1132	By calling HdrRule at the end of BuiltHeaders,
1133	all the gadgetry of HdrRule takes effect and it
1134	doesn't need to be duplicated.
1135	<P>
1136	<H4>
1137	Variables Used for Header Scanning
1138	</H4>
1139	<CENTER>
1140	<TABLE>
1141	<TR><TD VALIGN=TOP>
1142	HDRPATTERN
1143	<TD><TD>Default scan pattern for "include" lines.
1144	<TR><TD VALIGN=TOP>
1145	HDRSCAN
1146	<TD><TD>Scan pattern to use.
1147	This is a special variable: during binding, if
1148	both HDRSCAN and HDRRULE are set, scanning is activated
1149	on the target being bound.
1150	The HdrRule and Object rules sets this
1151	to $(HDRPATTERN) on their source targets.
1152	<TR><TD VALIGN=TOP>
1153	HDRRULE
1154	<TD><TD>Name of rule to invoked on files found in header
1155	scan. The HdrRule and Object rules set this to "HdrRule"
1156	on their source targets. This is also a special variable;
1157	it's the only <b>jam</b> variable that can hold the
1158	name of a rule to be invoked.
1159	<TR><TD VALIGN=TOP>
1160	HDRSEARCH
1161	<TD><TD>Search paths for files found during header scanning.
1162	This is set from $(HDRS) and $(STDHDRS), which are
1163	described in the Compiling section.
1164	<b>jam</b> will search $(HDRSEARCH) directories for
1165	the files found by header scans.
1166	</TABLE>
1167	</CENTER>
1168	<P>
1169	The Object rule sets HDRRULE and HDRSCAN specifically for
1170	the source files to be scanned, rather than globally. If
1171	they were set globally, jam would attempt to scan all
1172	files, even library archives and executables, for header
1173	file inclusions. That would be slow and probably not
1174	yield desirable results.
1175	<P>
1176	<H2>
1177	Copying Files
1178	</H2>
1179	<H4>
1180	File Rule
1181	</H4>
1182	The File rule copies one file to another. The target name
1183	needn't be the same as the source name. For
1184	example:
1185	<PRE>
1186	switch $(OS)
1187	{
1188	case NT* : File config.h : confignt.h ;
1189	case * : File config.h : configunix.h ;
1190	}
1191	LOCATE on config.h = $(LOCATE_SOURCE) ;
1192	</PRE>
1193	This creates a config.h file from either confignt.h or
1194	configunix.h, depending on the current build platform.
1195	<P>
1196	The File rule does not
1197	use the LOCATE_SOURCE variable set by the
1198	SubDir rule (although it does use SEARCH_SOURCE), which
1199	means you have to set the copied file's output directory
1200	yourself. That's done by setting the special
1201	LOCATE variable on the target, as shown above,
1202	or with the MakeLocate rule described below.
1203	<H4>
1204	Bulk Rule
1205	</H4>
1206	The Bulk rule is a shorthand for many invocations of the
1207	File rule when all files are going to the same directory.
1208	For example:
1209	<PRE>
1210	#In Jamrules:
1211	DISTRIB_GROB = d:\\distrib\\grob ;
1212
1213	#In Jamfile:
1214	Bulk $(DISTRIB_GROB) : grobvals.txt grobvars.txt ;
1215	</PRE>
1216	This causes gobvals.txt and grobvars.txt to be copied
1217	into the $(DISTRIB_GROB) directory.
1218	<H4>
1219	HardLink Rule
1220	</H4>
1221	The Unix-only HardLink rule makes a hard link (using ln(1)) from the
1222	source to the target, if there isn't one already. For
1223	example:
1224	<PRE>
1225	HardLink config.h : configunix.h ;
1226	</PRE>
1227	<H4>
1228	Shell Rule
1229	</H4>
1230	The Shell rule is like the File rule, except that on Unix it makes
1231	sure the first line of the target is "#!/bin/sh" and sets
1232	the permission to make the file executable. For example:
1233	<PRE>
1234	Shell /usr/local/bin/add : add.sh ;
1235	</PRE>
1236	<P>
1237	You can also use $(SHELLHEADER) to dictate
1238	what the first line of the copied file will be.
1239	For
1240	example:
1241	<PRE>
1242	Shell /usr/local/bin/add : add.awk ;
1243	SHELLHEADER on /usr/local/bin/add = "#!/bin/awk -f" ;
1244	</PRE>
1245	This installs an awk(1) script.
1246	<P>
1247	<H4>
1248	Variables Used When Copying Files
1249	</H4>
1250	<CENTER>
1251	<TABLE>
1252	<TR><TD VALIGN=TOP>
1253	FILEMODE
1254	<TD><TD>Default file permissions for copied files
1255	<TR><TD VALIGN=TOP>
1256	SHELLMODE
1257	<TD><TD>Default file permissions for Shell rule targets
1258	<TR><TD VALIGN=TOP>
1259	MODE
1260	<TD><TD>File permissions set on files copied by
1261	File, Bulk, and Shell rules.
1262	File and Shell sets a target-specific MODE to the current
1263	value of $(FILEMODE) or $(SHELLMODE), respectively.
1264	<TR><TD VALIGN=TOP>
1265	SHELLHEADER
1266	<TD><TD>String to write in first line of Shell targets
1267	(default is #!/bin/sh).
1268
1269	</TABLE>
1270	</CENTER>
1271	<P>
1272
1273	<H2>
1274	Installing Files
1275	</H2>
1276	Jambase provides a set of Install* rules to copy files
1277	into an destination directory and set permissions on them.
1278	On Unix, the install(1) program is used.
1279	If the destination directory does not exist, <b>jam</b>
1280	creates it first.
1281	<P>
1282	All files copied with the Install* rules are dependencies
1283	of the <i>install</i> pseudotarget, which means that the
1284	command "jam install" will cause the installed copies to
1285	be updated. Also, "jam uninstall" will cause the installed
1286	copies to be removed.
1287	<P>
1288	The Install* rules are:
1289	<CENTER>
1290	<TABLE>
1291	<TR><TD VALIGN=TOP><B>InstallBin</B>
1292	<TD VALIGN=TOP>Copies file and sets its permission to $(EXEMODE).
1293	You must specify the suffixed executable name. E.g.:
1294	<PRE>InstallBin $(BINDIR) : thing$(SUFEXE) ;
1295	</PRE>
1296
1297	<TR><TD VALIGN=TOP><B>InstallFile</B>
1298	<TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE). E.g.:
1299	<PRE>InstallFile $(DESTDIR) : readme.txt ;
1300	</PRE>
1301
1302	<TR><TD VALIGN=TOP><B>InstallLib</B>
1303	<TD VALIGN=TOP>Copies file and sets its permission to $(FILEMODE).
1304	You must specify the suffixed library name. E.g.:
1305	<PRE>InstallLib $(LIBDIR) : libzoo$(SUFLIB) ;
1306	</PRE>
1307
1308	<TR><TD VALIGN=TOP><B>InstallMan</B>
1309	<TD VALIGN=TOP>Copies file into the man<i>n</i>
1310	subdirectory of the target directory
1311	and sets its permission to $(FILEMODE). E.g.,
1312	this copies foo.5 into the $(DESTDIR)/man5 directory:
1313	<PRE>InstallMan $(DESTDIR) : foo.5 ;
1314	</PRE>
1315
1316	<TR><TD VALIGN=TOP><B>InstallShell</B>
1317	<TD VALIGN=TOP>Copies file and sets its permission to $(SHELLMODE). E.g.:
1318	<PRE>InstallShell $(DESTDIR) : startup ;
1319	</PRE>
1320
1321	</TABLE>
1322	</CENTER>
1323	<P>
1324	<P>
1325	<H4>
1326	Variables
1327	</H4>
1328	The following variables control the installation rules:
1329	<P>
1330	<CENTER>
1331	<TABLE>
1332	<TR><TD>
1333	INSTALL
1334	<TD><TD>The install program (Unix only)
1335	<TR><TD>
1336	FILEMODE
1337	<TD><TD>Default file permissions on readable files.
1338	<TR><TD>
1339	EXEMODE
1340	<TD><TD>Default file permission executable files.
1341	<TR><TD>
1342	SHELLMODE
1343	<TD><TD>Default file permission on shell script files.
1344	<TR><TD>
1345	MODE
1346	<TD><TD>Target-specific file permissions
1347	</TABLE>
1348	</CENTER>
1349	<P>
1350	<P>
1351	The Install rules set a target-specific MODE to the current
1352	value of $(FILEMODE), $(EXEMODE), or $(SHELLMODE),
1353	depending on which Install rule was invoked.
1354	<P>
1355	The directory variables are just defined for convenience:
1356	they must be passed as the target to the appropriate
1357	Install rule. The $(INSTALL) and mode variables must be
1358	set (globally) before calling the Install rules in order
1359	to take effect.
1360	<P>
1361	<H2>
1362	Miscellaneous Rules
1363	</H2>
1364	<H4>
1365	Clean Rule
1366	</H4>
1367	<P>
1368	The Clean rule defines files to be removed when you run "jam clean".
1369	Any site-specific build rules defined in your Jamrules should invoke
1370	Clean so that outputs can be removed. E.g.,
1371	<PRE>
1372	rule ResourceCompiler
1373	{
1374	DEPENDS $(<) : $(>) ;
1375	Clean clean : $(<) ;
1376	}
1377	</PRE>
1378	<P>
1379	<P>
1380	Most Jambase rules invoke the Clean rule on their built targets,
1381	so "jam clean" will remove all compiled objects, libraries,
1382	executables, etc.
1383	<P>
1384	<H4>
1385	MakeLocate Rule
1386	</H4>
1387	MakeLocate is a single convenient rule that creates a directory,
1388	sets LOCATE on a target to that directory, and makes the directory
1389	a dependency of the target. It is used by many Jambase rules,
1390	and can be invoked directly, e.g.:
1391	<PRE>
1392	GenFile data.tbl : hxtract data.h ;
1393	MakeLocate data.tbl : $(TABLEDIR) ;
1394	</PRE>
1395	In this example, the File rule creates data.tbl from data.h.
1396	The MakeLocate causes data.tbl to be written into the $(TABLEDIR)
1397	directory; and if the directory doesn't exist, it is created first.
1398	<P>
1399	The MakeLocate rule invokes another Jambase rule, MkDir,
1400	to (recursively) create
1401	directories. MkDir uses the $(MKDIR) variable to determine the
1402	platform-specific command that creates directories.
1403	<P>
1404	<H4>
1405	RmTemps Rule
1406	</H4>
1407	Some intermediate files are meant to be temporary.
1408	The RmTemps rule can be used to cause
1409	<b>jam</b> to delete them after they are used.
1410	<P>
1411	RmTemps must be:
1412	<UL>
1413	<LI>
1414	the last rule
1415	invoked on the permanent file that uses
1416	the temporary file(s)
1417	<LI>
1418	invoked with the permanent file as the output
1419	target and the temporary file(s) as the input target
1420	<LI>
1421	invoked with the exact target identifiers of
1422	the permanent file and the temporary file(s)
1423	</UL>
1424	For
1425	example:
1426	<PRE>
1427	SubDir TOP src big ;
1428	GenFile big.y : joinfiles part1.y part2.y part3.y ;
1429	Main bigworld : main.c big.y ;
1430	RmTemps bigworld$(SUFEXE) : <src!big>big.y ;
1431	</PRE>
1432	This causes big.y to be deleted after it has been used to create
1433	the bigworld executable.
1434	The exact target identifier of big.y is <src!big>big.y
1435	(the GenFile and Main rules tack on the grist automatically);
1436	the exact target identifier of the bigworld executable
1437	is bigworld$(SUFEXE).
1438	<P>
1439	<HR>
1440	<A HREF="#TOP">Back to top.</A>
1441	<P>
1442	Copyright 1997, 2000 Perforce Software, Inc.
1443	<BR>
1444	Comments to <A HREF="mailto:info@perforce.com">info@perforce.com</A>
1445	<BR>
1446	Last updated: Dec 31, 2000
1447	<BR>
1448	$Id: Jamfile.html,v 1.4 2002/04/07 00:22:45 david_abrahams Exp $
1449	</BODY>
1450	</HTML>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: