doc/CHANGES.FTJAM

   1 Changes between FT-Jam 2.5.2 and 2.5.1:
   2 =======================================
   3
   4 I. Engine Improvement:
   5
   6   Integration of Kai Backman's fix to dependency computations. When an
   7   included file is newer than the file including it, the later must also
   8   be part of the list of 'updated' actions.
   9
  10
  11 II. Installation fixes:
  12
  13   On Unix, building Jam will not longer complain that 'bin.unix' was
  14   skipped. This generally needed to 'make' or 'jam' invokation to properly
  15   generate the binary
  16
  17   Also, the binary is now automatically stripped on Unix systems
  18
  19   'jam package' now works correctly to generate package files on Unix
  20
  21 Changes between FT-Jam 2.5.1 and Jam 2.5:
  22 =========================================
  23
  24 I. Building Jam:
  25 ----------------
  26
  27  On Unix, FTJam can now be built with the traditionnal mantra, that is:
  28
  29    ./configure --prefix=<yourprefix>
  30    make
  31    make install
  32
  33  some simple Makefiles are also provided for a small number of selected
  34  platforms (mainly Windows and OS/2). For more information, please read
  35  the INSTALL file.
  36
  37
  38 II. Command line processing:
  39 ----------------------------
  40
  41  command line options can now be placed anywhere. In classic Jam, they
  42  must always appear before the target names.
  43
  44  additionnally, if a command line argument includes, but doesn't start with
  45  a '=', it it treated as an implicit '-s' option (variable definition).
  46
  47  this means that you can write things like:
  48
  49    jam install DEFINES=DEBUG
  50
  51  instead of:
  52
  53    jam -sDEFINES=DEBUG install
  54
  55
  56
  57
  58 III. Engine improvements:
  59 -----------------------
  60
  61 III.1. The JAMCMDARGS:
  62
  63   A new builting variable has been defined. When FT-Jam start, it defines
  64   the variable JAMCMDARGS which contains the list of targets used on the
  65   command line when Jam was invoked.
  66
  67   This is useful to provide richer control flow in the Jambase depending
  68   on command line arguments.
  69
  70
  71 III.1. Expansion Modifiers:
  72
  73   A new modifier 'Q' has been added in order to quote the result of
  74   an expansion. This basically replaces \ by \\ in expansions.
  75
  76   this is mainly useful within Actions block to prevent shells from
  77   doing stupid things to your parameters when they contain a back-slash.
  78
  79 III.2. HdrMacro built-in rule:
  80
  81   Jam's automatic header inclusion scanner now supports the current
  82   ISO C89 construct:
  83
  84     #include  MY_HEADER_H
  85
  86   to do this, you need to use the new HdrMacro built-in, and give it
  87   the name of one or more header files containing the definition of
  88   MY_HEADER_H. This will only record those definitions that look like
  89   valid header inclusion paths, like:
  90
  91     #define  MY_HEADER_H   <mypath/myheader.h>
  92     #define  MY_HEADER_H   "myheader.h"
  93
  94   These macro definitions are recorded by Jam, and used later during
  95   the header scanning process to add the corresponding file(s) to the
  96   dependency graph.
  97
  98 III.3. Variable import:
  99
 100   When Jam starts, it begins by importing all variables from the environment.
 101   Classic Jam had a bug that made it crash when very long variables where
 102   defined in Unix.
 103
 104   Additionnaly, variables whose content begins with "()" are ignored since
 105   they correspond to function variables in Unix shells like BASH, and don't
 106   have any meaning in the context of Jam
 107
 108 III.4. mkjambase now supports DOS text files:
 109
 110   the 'mkjambase' file didn't support DOS text files well. It created
 111   a corrupted image of the Jambase within the Jam executable.
 112
 113
 114 III.5. Library scanning bug fix:
 115
 116   Jam couldn't see object files with long file names within library files
 117   on Windows when they were generated with Mingw. This caused the
 118   corresponding object files to always be re-built.
 119
 120 IV. Jambase improvements:
 121 -------------------------
 122
 123 IV.1. Compiler selection through the JAM_TOOLSET:
 124 -------------------------------------------------
 125
 126 on Windows and OS/2 only, FTJam selects the compiler like Classic Jam
 127 by exploring the environment, looking for specific variables.
 128
 129 However, it none is found, it looks for the JAM_TOOLSET variable and
 130 use it to select the toolset being used. This list is displayed by Jam
 131 when JAM_TOOLSET is undefined or set to an unsupported value (see next
 132 chapter).
 133
 134 Nothing is changed on Unix and other platforms.
 135
 136
 137 IV.2. Improved compiler support:
 138 ---------------------------------
 139
 140 FTJam supports a lot more compiler than Classic Jam. Here's a table
 141 that maps values of JAM_TOOLSET to the corresponding compiler on Windows:
 142
 143      JAM_TOOLSET  Toolset Description
 144
 145      BORLANDC     Borland C++
 146      VISUALC      Microsoft Visual C++
 147      VISUALC16    Microsoft Visual C++ 16 bit
 148      INTELC       Intel C/C++
 149      WATCOM       Watcom C/C++
 150      MINGW        MinGW (gcc)
 151      LCC          Win32-LCC
 152      DIGITALMARS  Digital Mars C/C++
 153      PELLESC      Pelles C
 154
 155 the same table for OS/2 is:
 156
 157      WATCOM      Watcom C/C++
 158      EMX         EMX (gcc)
 159
 160 Nothing is changed for other paltforms. on Unix, including Cygwin, selection
 161 is performed through the CC environment variable, which defaults to 'cc'.
 162
 163 IMPORTANT: if you're using a Unix emulation layer like Cygwin or MSys, you
 164 should use a version of FTJam specially compiled for them, which will act
 165 exactly like the Unix version.
 166
 167
 168 IV.3. Support for building and linking shared libraries & DLLs:
 169 ----------------------------------------------------------------
 170
 171 Some new rules have been defined to be able to build and link with
 172 shared libraries (on Unix) and DLLs (on Windows only). NOTE THAT THIS
 173 SUPPORT IS STILL EXPERIMENTAL AT THE MOMENT. These rules are:
 174
 175   SharedLibrary  library : sources : import : def ;
 176
 177     Compiles 'sources' and generates a shared 'library' (i.e. DLL on Windows,
 178     or shared object on Unix). Calls SharedObjects and
 179     SharedLibraryFromObjects
 180
 181     If SharedLibrary is invoked with no suffix on 'library', then
 182     $(SUFLIBSHR) suffix is used (.so on Unix, .dll on Windows)
 183
 184     'import' is the name of the corresponding import library for Windows
 185     and OS/2 platforms (ignored otherwise). If it is not defined, it will
 186     default to 'library' with the $(SUFLIB) suffix.
 187
 188     'def' is the name of the corresponding definition file used to generate
 189     the library on Windows and OS/2 (ignored otherwise).
 190
 191
 192   SharedLibraryFromObjects  library : objects : import : defs
 193
 194     Equivalent to LibraryFromObjects for shared libraries and DLLs. See
 195     above for the description of parameters
 196
 197   LinkSharedLibraries  program : library ;
 198
 199     Used to link a program to a shared library generated through
 200     'SharedLibrary'. Equivalent to 'LinkLibraries'.
 201
 202 NOTICE THAT IT IS NOT CURRENTLY POSSIBLE TO BUILD BOTH A NORMAL AND
 203 A SHARED LIBRARY WITH THE SAME NAME. We'll try to fix this in a later
 204 release.
 205
 206
 207 IV.4. Experimental Package Management:
 208 ---------------------------------------
 209
 210 The end of our Jambase contains the definitions of several new rules
 211 that can be used to define independent software packages and manage
 212 their installation, deinstallation and dependencies on various platforms.
 213
 214 This code is highly experimental at the moment and we will not describe
 215 it here in detail. If you're interested, look at the end of the Jambase
 216 for rules whose name begin in Pkg (e.g. PkgBegin, PkgEnd, PkgUses, etc...)