7 <a href=http://www.perforce.com/jam/jam.html
>
17 Jambase is a base set of Jam rules which
18 provide roughly make(
1)-like functionality for
19 <a href=
"Jam.html"><b>jam
</b></A>, the Jam executable program.
20 This document, which started out as the Jambase(
5) man page,
21 is a reference guide to the
22 <A href=
"#RULES">rules
</A>,
23 <A href=
"#PSEUDOTARGETS">pseudotargets
</A>,
24 and
<A href=
"#VARS">variables
</A>
25 defined in Jambase for use in Jamfiles.
27 For further information see:
30 <a href=
"Jamfile.html">Using Jamfiles and Jambase
</A>
32 <a href=
"Jam.html">The Jam Executable Program
</A>
35 Jam documentation and source are available from the
36 <A HREF=http://public.perforce.com/public/index.html
>Perforce Public Depot
</a>.
37 For detailed information about any of the rules summarized below,
39 <A HREF=http://public.perforce.com/public/jam/src/Jambase
>Jambase
</a>
48 <B>As
</B> <I>obj.o
</I> :
<I>source.s
</I> ;
50 Assemble the file
<I>source.s.
</I> Called by the Object
53 <B>Bulk
</B> <I>directory
</I> :
<I>sources
</I> ;
55 Copies
<I>sources
</I> into
<I>directory.
</I>
57 <B>Cc
</B> <I>object
</I> :
<I>source
</I> ;
59 Compile the file
<I>source
</I> into
<I>object,
</I> using the C
60 compiler $(CC), its flags $(CCFLAGS) and $(OPTIM),
61 and the header file directories $(HDRS). Called by
64 <B>C++
</B> <I>obj.o
</I> :
<I>source.cc
</I> ;
66 Compile the C++ source file
<I>source.cc.
</I> Called by
69 <B>Chmod
</B> <I>target
</I> ;
71 <I>(Unix and VMS only.)
</I>
72 Change file permissions on
<I>target
</I> to
73 target-specific $(MODE) value set by Link, File,
74 Install*, and Shell rules.
77 <B>Clean
</B> <I>clean
</I> :
<I>targets
</I> ;
79 Removes existing
<I>targets
</I> when
<I>clean
</I> is built.
80 clean is not a dependency of all, and must be built
81 explicitly for targets to be removed.
83 <B>FDefines
</B> <I>defines
</I> ;
<BLOCKQUOTE>
84 Expands a list of definitions into a list of compiler
85 (or preprocessor) switches (such as
86 -D
<I>symbol
</I>=
<I>val
</I> on Unix)
87 to pass the definitions.
89 <B>File
</B> <I>target
</I> :
<I>source
</I> ;
91 Copies
<I>source
</I> into
<I>target.
</I>
93 <B>FIncludes
</B> <I>dirs
</I> ;
<BLOCKQUOTE>
94 Expands a list of directories into a list of compiler
95 (or preprocessor) switches (such as -I
<I>dir
</I> on Unix)
96 to add the directories to the header inclusion search path.
98 <B>Fortran
</B> <I>obj.o
</I> :
<I>source.f
</I> ;
100 Compile the Fortran source file
<I>source.f.
</I> Called
103 <B>FQuote
</B> <I>files
</I> ;
<BLOCKQUOTE>
104 Returns each of
<I>files
</I> suitably quoted so as to hide shell
105 metacharacters (such as whitespace and filename matching wildcards)
109 <B>GenFile
</B> <I>target
</I> :
<I>image
</I> <I>sources
</I> ;
111 Runs the command
"<I>image</I> <I>target</I> <I>sources</I>"
112 to create
<I>target
</I> from
<I>sources
</I> and
113 <I>image
</I>. (where
<I>image
</I> is an
114 executable built by the Main rule.)
116 <B>HardLink
</B> <I>target
</I> :
<I>source
</I> ;
118 Makes
<I>target
</I> a hard link to
<I>source,
</I> if it isn't one
119 already. (Unix only.)
121 <B>HdrRule
</B> <I>source
</I> :
<I>headers
</I> ;
123 Arranges the proper dependencies when the file
124 <I>source
</I> includes the files
<I>headers
</I> through the
125 "#include" C preprocessor directive.
127 This rule is not intended to be called explicitly.
128 It is called automatically during header scanning on
129 sources handled by the Object rule (e.g., sources in
130 Main or Library rules).
132 <B>InstallBin
</B> <I>dir
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
133 Copy
<I>sources
</I> into
<I>dir
</I> with mode
136 <B>InstallLib
</B> <I>dir
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
137 Copy
<I>sources
</I> into
<I>dir
</I> with mode
140 <B>InstallMan
</B> <I>dir
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
141 Copy
<I>sources
</I> into the appropriate subdirectory
142 of
<I>dir
</I> with mode $(FILEMODE). The subdirectory
143 is man
<I>s,
</I> where
<I>s
</I> is the suffix of
146 <B>InstallShell
</B> <I>dir
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
147 Copy
<I>sources
</I> into
<I>dir
</I> with mode
150 <B>Lex
</B> <I>source.c
</I> :
<I>source.l
</I> ;
<BLOCKQUOTE>
151 Process the lex(
1) source file
<I>source.l
</I> and
152 rename the lex.yy.c to
<I>source.c.
</I> Called by
155 <B>Library
</B> <I>library
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
156 Compiles
<I>sources
</I> and archives them into
157 <I>library.
</I> The intermediate
<I>objects
</I>
158 are deleted. Calls Objects and LibraryFromObjects.
160 If Library is invoked with no suffix on
<I>library
</I>,
161 the $(SUFLIB) suffix is used.
163 <B>LibraryFromObjects
</B> <I>library
</I> :
<I>objects
</I> ;
165 Archives
<I>objects
</I> into
<I>library.
</I> The
166 <I>objects
</I> are then deleted.
168 If
<I>library
</I> has no suffix, the $(SUFLIB) suffix is used.
170 <B>Link
</B> <I>image
</I> :
<I>objects
</I> ;
172 Links
<I>image
</I> from
<I>objects
</I> and sets
173 permissions on
<I>image
</I> to $(EXEMODE).
174 <I>Image
</I> must be actual filename; suffix is not
179 <B>LinkLibraries
</B> <I>image
</I> :
<I>libraries
</I> ;
181 Makes
<I>image
</I> depend on
<I>libraries
</I> and
182 includes them during the linking.
184 <I>Image
</I> may be referenced without a suffix in this
185 rule invocation; LinkLibraries supplies the suffix.
187 <B>Main
</B> <I>image
</I> :
<I>sources
</I> ;
189 Compiles
<I>sources
</I> and links them into
<I>image.
</I>
190 Calls Objects and MainFromObjects.
192 <I>Image
</I> may be referenced without a suffix in this
193 rule invocation; Main supplies the suffix.
195 <B>MainFromObjects
</B> <I>image
</I> :
<I>objects
</I> ;
197 Links
<I>objects
</I> into
<I>image.
</I> Dependency
198 of exe. MainFromObjects supplies the suffix on
<I>image
</I>
201 <B>MakeLocate
</B> <I>target
</I> :
<I>dir
</I> ;
203 Creates
<I>dir
</I> and causes
<I>target
</I> to be built
206 <B>MkDir
</B> <I>dir
</I> ;
208 Creates
<I>dir
</I> and its parent directories.
210 <B>Object
</B> <I>object
</I> :
<I>source
</I> ;
212 Compiles a
<I>single
</I> source file source into
213 <I>object.
</I> The Main and Library rules use
214 this rule to compile source files.
216 Causes
<I>source
</I> to be scanned for
"#include"
217 directives and calls HdrRule to make all included
218 files dependedencies of
<I>object
</I>.
220 Calls one of the following rules to do the actual
221 compiling, depending on the suffix of source:
232 <B>ObjectC++Flags
</B> <I>source
</I> :
<I>flags
</I> ;
234 <B>ObjectCcFlags
</B> <I>source
</I> :
<I>flags
</I> ;
236 Add
<I>flags
</I> to the source-specific
237 value of $(CCFLAGS) or $(C++FLAGS) when compiling
<I>source.
</I>
238 Any file suffix on
<I>source
</I> is ignored.
240 <B>ObjectDefines
</B> <I>object
</I> :
<I>defines
</I> ;
<BLOCKQUOTE>
241 Adds preprocessor symbol definitions to the (gristed)
242 target-specific $(CCDEFS) for the
<I>object
</i>.
244 <B>ObjectHdrs
</B> <I>source
</I> :
<I>dirs
</I> ;
<BLOCKQUOTE>
245 Add
<I>dirs
</I> to the source-specific value of
246 $(HDRS) when scanning and compiling
<I>source.
</I>
247 Any file suffix on
<I>source
</I> is ignored.
249 <B>Objects
</B> <I>sources
</I> ;
<BLOCKQUOTE>
250 For each source file in
<I>sources,
</I> calls
251 Object to compile the source file into a similarly
254 <B>RmTemps
</B> <I>targets
</I> :
<I>sources
</I> ;
<BLOCKQUOTE>
255 Marks
<I>sources
</I> as temporary with the TEMPORARY
256 rule, and deletes
<I>sources
</I> once
<I>targets
</I>
257 are built. Must be the last rule invoked on
258 <I>targets.
</I> Used internally by LibraryFromObjects rule.
260 <B>Setuid
</B> <I>images
</I> ;
<BLOCKQUOTE>
261 Sets the setuid bit on each of
<I>images
</I> after
262 linking. (Unix only.)
265 <B>SoftLink
</B> <I>target
</I> :
<I>source
</I> ;
267 Makes
<I>target
</I> a symbolic link to
<I>source,
</I> if it isn't one
268 already. (Unix only.)
270 <B>SubDir
</B> <I>TOP d1 ... dn
</I> ;
272 Sets up housekeeping for the source files located
273 in
<I><CODE>$(TOP)/d1/.../dn
</CODE></I>:
275 <LI>Reads in rules file associated with
<I>TOP
</I>,
276 if it hasn't already been read.
277 <LI>Initializes variables for search paths,
278 output directories, compiler
279 flags, and grist, using
<I>d1 ... dn
</I> tokens.
282 <I>TOP
</I> is the name of a variable;
283 <I>d1
</I> thru
<I>dn
</I> are elements
286 <B>SubDirC++Flags
</B> <I>flags
</I> ;
288 <B>SubDirCcFlags
</B> <I>flags
</I> ;
290 Adds
<I>flags
</I> to the compiler flags for source files
291 in SubDir's directory.
293 <B>SubDirHdrs
</B> <I>d1 ... dn
</I> ;
295 Adds the path
<I>d1/.../dn/
</I> to the header search paths for
296 source files in SubDir's directory.
<I>d1
</I> through
<I>dn
</I>
297 are elements of a directory path.
299 <B>SubInclude
</B> <I>VAR d1 ... dn
</I> ;
301 Reads the Jamfile in
<I><CODE>$(VAR)/d1/.../dn/
</CODE></I>.
303 <B>Shell
</B> <I>image
</I> :
<I>source
</I> ;
<BLOCKQUOTE>
304 Copies
<I>source
</I> into the executable sh(
1)
305 script
<I>image.
</I> Ensures that the first line of
306 the script is $(SHELLHEADER) (default #!/bin/sh).
308 <B>Undefines
</B> <I>images
</I> :
<I>symbols
</I> ;
<BLOCKQUOTE>
309 Adds flags to mark
<I>symbols
</I> as undefined
310 on link command for
<I>images
</I>.
311 <I>Images
</I> may be referenced unsuffixed; the
312 Undefines rule supplies the suffix.
314 <B>UserObject
</B> <I>object
</I> :
<I>source
</I> ;
<BLOCKQUOTE>
315 This rule is called by Object for source
316 files with unknown suffixes, and should be defined
318 with a user-provided rule to handle the source file
319 types not handled by the Object rule.
320 The Jambase UserObject rule merely issues a
321 complaint when it encounters
<I>source
</I> with
322 files suffixes it does not recognize.
324 <B>Yacc
</B> <I>source.c
</I> :
<I>source.y
</I> ;
<BLOCKQUOTE>
325 Process the yacc(
1) file
<I>source.y
</I> and renamed
326 the resulting y.tab.c and y.tab.h to
<I>source.c.
</I>
327 Produces a y.tab.h and renames it to
<I>source.h.
</I>
328 Called by the
<B>Object
</B> rule.
332 <A NAME=
"PSEUDOTARGETS">
334 Jambase Pseudotargets
338 There are two kinds of Jam targets: file targets and pseudotargets.
339 File targets are objects that can be found in the filesystem.
340 Pseudotargets are symbolic, and usually represent other targets.
341 Most Jambase rules that define file targets also define pseudotargets
342 which are dependent on types of file targets. The Jambase pseudotargets
345 <TABLE CELLPADDING=
5%
>
347 <TD>Executables linked by the Main or MainFromObjects rules
350 <TD>Libraries created by the Library or LibraryFromObjects rules
353 <TD>Compiled objects used to create Main or Library targets
356 <TD>Directories where target files are written
359 <TD>Files copied by File and Bulk rules
362 <TD>Files copied by Shell rule
365 <TD>Removal of built targets (except files copied by Install* rules)
368 <TD>Files copied by Install* rules
371 <TD>Removal of targets copied by Install* rules
376 In addition, Jambase makes the
<b>jam
</b> default target
"all"
377 depend on
"exe",
"lib",
"obj",
"files", and
"shell".
387 Most of the following variables have default values for
388 each platform; refer to the Jambase file to see what those
393 Alternative location of built targets. By default,
394 Jambase rules locate built targets in the source
395 tree. By setting $(ALL_LOCATE_TARGET)
396 in Jamrules, you can cause
<b>jam
</b>
397 to write built targets to a location outside
404 The archive command used to update Library
405 and LibraryFromObjects targets.
409 The assembler for As rule targets.
415 Flags handed to the assembler for As.
421 The name of awk interpreter, used when copying a
422 shell script for the Shell rule.
427 Selects Borland compile and link actions on NT.
435 (I.e., used only for backward compatibility with the
436 obsolete INSTALLBIN rule.)
442 C compiler used for Cc rule targets.
448 Compile flags for Cc rule targets.
449 The Cc rule sets target-specific $(CCFLAGS)
450 values on its targets.
456 C++ compiler used for C++ rule targets.
462 Compile flags for C++ rule targets.
463 The C++ rule sets target-specific $(C++FLAGS)
464 values on its targets.
470 Program (usually chmod(
1)) used to set file
471 permissions for Chmod rule.
477 The file copy program, used by File and Install* rules.
483 If set, causes the Library rule to invoke the CreLib
484 rule on the target library before attempting to archive
485 any members, so that the library can be created if
492 On Macintosh, the root of the Code Warrior Pro
5 directory.
498 Preprocessor symbol definitions for Cc and C++ rule targets.
499 The Cc and C++ rules set target-specific $(CCDEFS)
500 values on their targets, based on $(DEFINES). (The
501 "indirection" here is required to support compilers,
502 like VMS, with baroque command line syntax for
509 The operating system-specific name for the current directory.
515 The operating system-specific name for the parent directory.
521 Permissions for executables linked with Link, Main,
522 and MainFromObjects, on platforms with a Chmod action.
528 Permissions for files copied by File or Bulk,
529 on platforms with a Chmod action.
535 The Fortran compiler used by Fortran rule.
541 Fortran compiler flags for Fortran rule targets.
548 The group owner for Install* rule targets.
554 If set, used by the HdrRule to distinguish header files
555 with the same name in diffrent directories.
561 A regular expression pattern that matches
562 C preprocessor
"#include" directives in source files
563 and returns the name of the included file.
569 Name of the rule to invoke with the results of header file
570 scanning. Default is
"HdrRule".
572 This is a jam-special variable. If both HDRRULE and HDRSCAN
574 that target will be scanned for lines
575 matching $(HDRSCAN), and $(HDDRULE) will be
576 invoked on included files found in the matching $(HDRSCAN) lines.
582 Directories to be searched for header files.
583 This is used by the Object rule to:
585 <LI>set up search paths for finding files returned
587 <LI>add -I flags on compile commands
595 Regular expression pattern to use for header file
596 scanning. The Object rule sets this to $(HDRPATTERN).
597 This is a jam-special variable; see HDRRULE.
603 Used by the HdrRule to fix the list of directories where
604 header files can be found for a given source file.
610 Used by the Install* rules to grist paths to installed
611 files; defaults to
"installed".
617 Default is
"Jamfile"; the name of the user-written
618 rules file found in each source directory.
624 Default is
"Jamrules"; the name of a rule definition
625 file to be read in at the first SubDir rule invocation.
631 If set, tells the LibraryFromObjects rule not to delete
632 object files once they are archived.
638 The lex(
1) command and flags.
645 (I.e., used only for backward compatibility with the
646 obsolete INSTALLLIB rule.)
652 The linker. Defaults to $(CC).
658 Flags handed to the linker. Defaults to $(CCFLAGS).
664 List of external libraries to link with. The target image
665 does not depend on these libraries.
671 The hard link command for HardLink rule.
676 Used to set the location of generated source files.
677 The Yacc, Lex, and GenFile rules set LOCATE on
678 their targets to $(LOCATE_SOURCE).
679 $(LOCATE_SOURCE) is initialized by the SubDir rule
680 to the source directory itself.
681 (Also, see ALL_LOCATE_TARGET.)
686 Used to set the location of built binary targets.
687 The Object rule, and hence the Main and Library rules,
688 set LOCATE on their targets to $(LOCATE_TARGET).
689 $(LOCATE_TARGET) is initialized by the
690 SubDir rule to the source directory itself.
691 (See ALL_LOCATE_TARGET.)
699 (I.e., used only for backward compatibility with the
700 obsolete INSTALLMAN rule.)
706 The 'create directory' command used for the MkDir
713 The target-specific file mode (permissions) for targets
714 of the Shell, Setuid, Link, and Install* rules.
715 Used by the Chmod action; hence relevant to NT and VMS
721 Selects Microsoft Visual C
16-bit compile & link
727 Selects Microsoft Visual C NT
5.0 and earlier compile
728 & link actions on NT.
733 Selects Microsoft Visual C NT
6.0 and later compile
734 & link actions on NT. These are identical to versions
735 5.0 and earlier -- it just seems Microsoft changed the
736 name of the variable.
743 The file rename command and options.
749 The list of libraries used when linking an executable.
750 Used by the Link rule.
756 If set, indicates that library members' timestamps can't
757 be found, and prevents the individual objects from being
758 deleted, so that their timestamps can be used instead.
764 If set, indicates that libraries can't be updated, but only
771 The C compiler flag for optimization, used by Cc and C++
778 The concatenation of $(OS)$(OSVER)$(OSPLAT), used when jam
779 builds itself to determine the target binary directory.
780 $(OS) and $(OSPLAT) are determined by jam at its compile
781 time (in jam.h). $(OSVER) can optionally be set by the user.
788 The owner of installed files. Used by Install* rules.
794 The name of the ranlib command. If set, causes
795 the Ranlib action to be applied after the
796 Archive action to targets of the Library rule.
802 If set, tells the Cc rule to move the output object
803 file to its target directory because the cc command
804 has a broken -o option.
810 The command and options to remove a file.
816 The directory to find sources listed with Main,
817 Library, Object, Bulk, File, Shell, InstallBin,
818 InstallLib, and InstallMan rules. This works by
819 setting the jam-special variable SEARCH to the
820 value of $(SEARCH_SOURCE) for each of the rules'
821 sources. The SubDir rule initializes SEARCH_SOURCE
828 A string inserted to the first line of every file
829 created by the Shell rule.
835 Permissions for files installed by Shell rule.
841 Set by the SubDir to a value derived from the
842 directory name, and used by Objects and related
843 rules as 'grist' to perturb file names.
849 Directories where headers can be found without
850 resorting to using the flag to the C compiler.
851 The $(STDHDRS) directories are used to find
852 headers during scanning, but are not passed to the
853 compiler commands as -I paths.
859 The path from the current directory to the directory
860 last named by the SubDir rule.
866 The path from the current directory to the directory
867 that has the Jamrules file. Used by the SubDir rule.
873 The suffix for executable files, if none provided.
874 Used by the Main rule.
880 The suffix for libraries. Used by the Library and
887 The suffix for object files. Used by the Objects
894 The flag prefixed to each symbol for the Undefines
895 rule (i.e., the compiler flag for undefined symbols).
900 Selects Watcom compile and link actions on OS2.
912 The base filename generated by yacc(
1).
918 The yacc(
1) command flags.
924 The suffix used on generated yacc(
1) output.
929 <A HREF=
"#TOP">Back to top.
</A>
931 Copyright
1993-
2002 Christopher Seiwald and Perforce Software, Inc.
933 Comments to
<A HREF=
"mailto:info@perforce.com">info@perforce.com
</A>
935 Last updated: Dec
31,
2000
937 $Id: //public/jam/src/Jambase.html#
10 $