FT JAM ENHANCEMENTS |
Introduction Builtins Jambase Other | Homepage |
Table of contentsIntroductionFT Jam is an enhanced version of the Jam build tool. This document lists the differences between these two programs. Note that these changes come from the need of real-world cases that can't be compiled correctly with classic Jam's limitations. Note that FT Jam is, and will always be, fully backwards compatible with the regular Jam tool. It thus can be used as a drop-in replacement for existing Jam users. If you find something that breaks a classic Jamfile when used with FT Jam, please send a copy to the FreeType developers' mailing list so that it can be fixed as soon as possible. New Built-in RulesFT Jam has introduced several new built-in rules. HDRMACRO – Header File Macro InclusionJam is capable of scanning C source files to automatically determine header file dependencies. It does so through the following scheme.
ISO C allows macro expansion to occur in a #include directive, as long as the resulting value is a correct header file name. The following is thus valid, but is not parsed adequately by Jam. #define MYFILE_H "myfile.h" #include MYFILE_H FT Jam can parse such files normally by its HDRMACRO built-in rule whose syntax is HDRMACRO filename ; where filename is the name of a file that contains the definitions of macros that is used in inclusion directives. When you invoke this built-in, it does the following automatically.
Later on, when FT Jam finds a macro inclusion directive, like #include MYFILE_H, it searches its macro dictionary to see if it can expand it. If so, it performs the expansion inline and updates the dependency tree. Otherwise it simply ignores the line. Note that you should always use the HDRMACRO built-in before other dependency rules (like Cc or C++), in order to record the macro definitions before header file scanning occurs SUBST – Regular Expression ReplacementThis new built-in must be used as a function and performs regular expression matching and replacement. Its syntax is RESULT = [ SUBST source pattern replacement ] ; where source is the source string, pattern is a regular expression pattern that is searched in the source string, and replacement is the replacement for the first pattern match. Of course, RESULT is a variable that contains the match's result. Note that the character ‘$’ is used as an escape $character, with $1, $2, $3, etc., corresponding to the first matched sub-expression, the second one, the third one, etc. Here is a small example. The following Jamfile fragment XX_TGZ = packagename-2.0.2.tar.gz ; PATTERN = "([A-Za-z][A-Za-a0-9_]*)-(.*)\.tar\.gz" ; XX_TBZ2 = [ SUBST $(XX_TGZ) "(.*)\.tar\.gz" "$1.tar.bz2" ] ; XX_TAR = [ SUBST $(XX_TGZ) "(.*)\.gz" "$1" ] ; XX_NAME = [ SUBST $(XX_TGZ) $(PATTERN) "$1" ] ; XX_VER = [ SUBST $(XX_TGZ) $(PATTERN) "$2" ] ; ECHO $XX_TBZ2 ; ECHO $XX_TAR ; ECHO $XX_NAME ; ECHO $XX_VER ; prints as packagename-2.0.2.tar.bz2 packagename-2.0.2.tar packagename 2.0.2 Indirect Rule InvocationWell, that is not exactly a new built-in, but is sufficiently close to it to deserve this classification. FT Jam allows you to use macro expansion to determine which rule to invoke in a function call. For example, the following code fragment is not valid in classic Jam but runs with FT Jam: rule MyFunc { return "Boo!" $(<) ; } FUNC = MyFunc ; BOO = [ $(FUNC) "Ahh!" ] ; ECHO $(BOO) ; Of course, it prints ‘Boo! Ahh!’. Note also that during debug output, the expansion is dumped (e.g., ‘MyFunc’ and not ‘$(FUNC)’). Note that this rule invocation method must be used carefully, since the whole variable expansion is used to determine which rule to use, including any spaces. The following thus fails. rule MyFunc { return "Boo!" $(<) ; } FUNC = MyFunc "Ahh!" ; BOO = [ $(FUNC) ] ; ECHO $(BOO) ; The reason is that there is no rule named ‘MyFunc Ahh!’. FAIL_EXPECTED – Action Result InversionDo not use this built-in without a very good reason. Its purpose is to invert the result of a given build action.
As you might probably guess, this built-in is only useful in very specific cases (e.g., testing system features as in a configure script). You probably don't need it in your Jamfiles, so better keep your hands off of it. It is actually an ‘experimental’ feature of FT Jam and could be renamed or modified heavily in the future, so don't rely on it unless you are in close contact with the FT Jam author(s). Jambase EnhancementsThe Jambase is a file containing all default rules and actions used by the Jamfiles. It is written in normal Jam syntax and is compiled within the ‘jam’ executable by default. New Windows and OS/2 Toolset Selection SchemeIn classic Jam, toolset selection on Windows and OS/2 is performed by setting specific environment variables corresponding to the compiler you want to use.
Note that the first variable in the list that is detected is used by the classic Jambase to determine which toolset to use. This is very annoying when you need to switch frequently between toolsets on the same machine (e.g., you have to unset a variable before setting the previous one, and you have to retype an installation path on each switch). The FT Jam Jambase provides a more flexible scheme that allows you to switch between toolsets very easily, using one additional level of indirection.
For example, here is how to use the Borland C++ compiler. set BORLANDC=path\to\borland\install set JAM_TOOLSET=BORLANDC jam And here is how to use the Visual C++ compiler. set VISUALC=path\to\visualc\install set JAM_TOOLSET=VISUALC jam You can also change the value of JAM_TOOLSET anytime you want to switch between the toolsets automatically. set BORLANDC=path\to\borland\install set VISUALC=path\to\visualc\install set JAM_TOOLSET=BORLANDC jam jam clean set JAM_TOOLSET=VISUALC jam jam clean The biggest advantage of this scheme is that you only need to define toolset-specific variables once, then later use JAM_TOOLSET to switch between them. This generally allows you to put all variable definitions into a batch file and forget about their exact values. When using a large number of toolsets, this can be really helpful. New Windows and OS/2 Toolsets SupportedNew toolsets have been added to the FT Jam Jambase for Windows and OS/2. The best way to see them is simply to invoke ‘jam’ when JAM_TOOLSET isn't defined. This dumps a message containing the list of currently supported toolsets for your platform. On Windows, you get output like this. Jam cannot be run because you didn't indicate which compilation toolset to use. To do so, follow these simple instructions: - define one of the following environment variable, with the appropriate value according to this list: Variable Toolset Description BORLANDC Borland C++ BC++ install path VISUALC Microsoft Visual C++ VC++ install path VISUALC16 Microsoft Visual C++ 16 bit VC++ 16 bit install INTELC Intel C/C++ IC++ install path WATCOM Watcom C/C++ Watcom install path MINGW MinGW (gcc) MinGW install path LCC Win32-LCC LCC-Win32 install path - define the JAM_TOOLSET environment variable with the *name* of the toolset variable you want to use. e.g.: set VISUALC=C:Visual6 set JAM_TOOLSET=VISUALC Here the output on OS/2. Jam cannot be run because you didn't indicate which compilation toolset to use. To do so, follow these simple instructions: - define one of the following environment variable, with the appropriate value according to this list: Variable Toolset Description WATCOM Watcom C/C++ Watcom install path EMX EMX (gcc) EMX install path VISUALAGE IBM Visual Age C/C++ VisualAge install path - define the JAM_TOOLSET environment variable with the *name* of the toolset variable you want to use. e.g.: set WATCOM=C:\WATCOM set JAM_TOOLSET=WATCOM Other ImprovementsFT Jam also provides other important or minor improvements to the original Jam sources. Runs on Windows 9xThe classic Jam is not capable of running on Windows 95 and 98 systems. That is mainly because it relies on the Windows NT command line processor named cmd.exe, while Win9x systems only come with the infamous command.com which isn't capable of returning valid exit codes for most commands. FT Jam provides an improved execution backend that is capable of detecting Win9x systems at runtime, and take special measures to deal with their limitation. To date, we haven't encountered a Jamfile that works on NT and fails on Win9x with FT Jam. Please send these to the FreeType developers' mailing list in case you have one. Cosmetic EnhancementsThere are also some cosmetic enhancements that might be useful.
About the AuthorDavid Turner is best known as the author of the open-source FreeType library. He specializes in writing highly portable code for embedded systems. The source code of FT Jam is stored on the Perforce Public Depot (peek at //guest/david_turner/jam/src). |
Introduction Builtins Jambase Other | Homepage |