JamPlus manual
Changelog

Version 1.0

New features for 1.0:

  • The Mac OS X build is much more functional than past releases of JamPlus with support for Xcode workspace generation, Lua scripts, multiple OS X SDKS (10.4 to 10.6), and application bundles (including automatic creation of the PkgInfo and Info.plist files). Additionally, iPhone, iPhone Simulator, iPad, and iPad Simulator applications can be built and run.
  • Initial Android NDK support provided by Steven Craft.
  • Linux support added. No Linux workspace generation support is available yet, although the CodeBlocks support may work.
  • Visual Studio 2010 support has been added by Philipp Teschner.
  • Visual C++ 6 compiler support works much better, and Visual C++ 6 .dsw and .dsp files can be generated.
  • C/C++ build rules have been separated into their own Jam module called 'c'. This module is automatically loaded on any Jam invocation. As a result, most rules are now namespaced with a C.. That is, you'll use C.Application instead of just Application. To use the old names, you can attempt to IncludeModule c-deprecated. None of this is guaranteed to work.
    • With the new C module, it is easy to add additional platforms, configurations, and compilers. See the tests/platform/groovyplatform/ example to see this in action.
    • Renamed the following Jam modules:
      • c/directx: Renamed from DirectX.
      • c/dotnet: Renamed from DotNet.
      • c/mfc: Renamed from MFC. Access it as C.UseMFC.
      • c/midl: Renamed from Midl. Access it as C.Midl*.
      • c/wxwidgets: Renamed from WxWidgets. Access it as C.UseWxWidgets.
    • Created a c/win32resource module with the ResourceCompiler rules.
  • The Jam binaries have been moved from the jamplus/bin/ directory to jamplus/bin/$(PLATFORM). On Windows, this ends up being jamplus/bin/win32/. On Mac OS X, the directory is jamplus/bin/macosx32/. All associated scripts have been moved to this directory, as has the Lua directory structure. This new structure allows for multiple platform binaries to exist side by side. See Building Overview for more information.
  • Automated tests have been added consisting of over 50 categoric test suites made of nearing 500 individual tests. The suite is run by ensuring JamPlus's bin/platform/ directory is in the PATH and then running tests/runtests.bat (on Windows) or tests/runtests-macosxx64 on Mac OS X or tests/tuntests-linux32 on Linux.

Bootstrapping/Building:

  • Added a bootstrapping .xcodeproj as src/jam.xcodeproj to debug Mac OS X Jam issues in. This project is currently only set up for Debug mode; the Release configuration does not work. Use make macosx to build a high performance Release build.
  • If the environment variable LUA_BIN is set, the appropriate Lua files are copied to the appropriate platform binary directory during the Jam executable build. See Building Overview for more information.
  • Support for building jam0 on FreeBSD. Thanks to Arseny Kapoulkine for the update.
  • Turn on the Visual Studio 2010 support in jmake.cmd.
  • Add jam.VS2010.sln/.vcxproj.
  • Jam executable can be built under Visual C++ 6.0.

Technical Details:

  • The Visual Studio 2005 solution and project files, src/jam.VS2005.sln and src/jam.VS2005.vcproj, have been removed. Only a Visual Studio 2008 and 2010 versions are included for this release. The Visual Studio solution is available only for debug purposes. The link time code generated Visual C++ Release LTCG build built by the bootstrapped Jam is far faster than the Release build provided by the jam.VS2008.vcproj file.
  • Jambase-j.c is properly generated from Jambase-j during the bootstrapping run.
  • Intermediate files are built to an intermediate folder instead of littering the extra files in the src/ directory.
  • The Mac OS X bootstrapped build uses the 10.4 SDK and GCC 4.0 to build. The SDK can be changed near the top of the src/Jamfile.jam.

Jam Executable:

  • Built-in rules:
    • Added a PRIORITY parameter to QueueJamfile. By default, queued Jamfiles are processed in the order they are queued. There may be cases where the queued order does not allow for proper processing of the Jamfiles. In the event the Jamfile order matters for the upcoming pass, the PRIORITY will affect queueing order.
    • Added rule ScanContents. When ScanContents is specified for a source target (even a generated one) and if the timestamp differs, the contents of the source target are compared against the last run. If they differ, the build proceeds as normal. If they are the same, no further building is necessary.
    • Added rule Shell, used for executing shell commands and retrieving their output.
    • Added built-in rule GroupByVar, a high speed version of the oft-called Jambase rule used by the C module's helper rule MultiCppCompile. (Made available through #define OPT_BUILTIN_GROUPBYVAR_EXT.)
    • Added built-in rule Split. (Made available through #define OPT_BUILTIN_SPLIT_EXT.)
    • Added built-in rule ExpandFileList which takes a list of files, including glob-capable wildcards, and expands them, returning the list to the user.
    • Added rule SubstLiteralize, a helper function to hand a literal string to the Subst rule.
    • Added rule DependsList which returns a list of child dependencies for a given target.
  • Actions:
    • Added a new action modifier, screenoutput. Normally, actions collect all output before displaying it to the user in order to avoid interleaving the output from different processes. 'screenoutput' may be used to display the output as it happens.
    • Support a third parameter to an action for autosettings. This takes any settings assigned to the autosettings target and makes them active during the course of the action.
    • Added a new actions modifier keyword, removeemptydirs, intended to be used with the various Clean actions. For any sources sent to a Clean action, any empty directories associated with the source target location are removed. #ifdef'ed as OPT_REMOVE_EMPTY_DIRS_EXT.
  • Added support for misplaced semicolon and colon detection in the parser. If a semicolon or colon is the first or last character of an identifier, it may be missing its surrounding whitespace, and a parser error is reported. You may need to quote strings that didn't need to be quoted before. See Lexical Features for additional information. #ifdef'ed as OPT_FIND_BAD_SEMICOLON_USAGE_EXT.
  • Support for new Jam command line options, specified in the form jam –helperscript .... jam –workspace builds a workspace, jam –folderstojamfile converts folders to a Jamfile, and jam –vcprojtojamfile converts the contents of a .vcproj to a Jamfile. These command line options replace the old calls to JamToWorkspace and other helper scripts.
  • Simplify the -s command line flag (which is still available) by parsing KEY=VALUE pairs off the command line. That is, 'jam -sCONFIG=debug all' and 'jam CONFIG=debug all' mean the same thing. See Usage for more information. (Made available through #define OPT_KEY_EQUALS_VALUE_DEFINES_EXT.)
  • Added a way of accessing the targets specified on the command line from within Jam through the global variable JAM_COMMAND_LINE_TARGETS. One method of using this variable is to filter sections of the Jam script to save build time. See Miscellaneous Variables for additional information. (Made available through #define OPT_SET_JAMCOMMANDLINETARGETS_EXT.)
  • Added a new missing rule "silence" command line option: -S. When specified, any rules called that have not been defined are skipped without warning. jam –workspace makes extensive use of it. This command line option will mask problems with your Jamfiles, so it is recommended you don't use it. See Usage for more information.
  • Added the ability to escape paths in a platform specific way with the string expansion modifier :C. For example, if a Windows filename has spaces in it, using the :C modifier will result in the filename being quoted. #ifdef'ed as OPT_EXPAND_ESCAPE_PATH_EXT.
  • Defaulted DEPCACHE to equal standard. This does not automatically turn on a dependency cache. There is still need to set it up with DEPCACHE.standard = .depcache or some equivalent. See Dependency Cache Usage for additional information.
  • Fixed the variable expansion modifier :X= when used without a :I=.
  • Added :W=remove_text as another form of the wildcard variable expansion modifier. Removes remote_text characters from the beginning of the found wildcard.
  • Set the header cache max age to 0. This should prevent the current frequent rebuilds every 100 Jam runs.
  • Add support for the new Jamfile variable JAM_NUM_JOBS. This allows the user to override the -j command line option via a variable in one of the Jamfiles (possibly even altered on a subsequent pass).
  • Add the ability to search file extensions for a target.
  • :T expansion now uses settings directly from the target and supports EXPAND_TEXT.
  • Fix KEY-VALUE pairs on the command to work after the target list. Uses an alternate approach mostly adopted from ftjam.
  • Add built-in rule: [ ListSort LIST : CASE_SENSITIVE:1/0 ].Add built-in rule: [ ListSort LIST : CASE_SENSITIVE:1/0 ].
  • When scanning for headers (or restoring them from the header cache), prepend the target's HDREXTRA to the list. This is where force includes can be added.
  • Support for querying 64 bit registry values.
  • Ability to read DWORD values from the registry

Technical Details:

  • Allow for the failure of an actions lua block at runtime.
  • Multipass support:
    • Multipass support past 2 passes was broken. It is fixed now. See Multiple Passes for more information.
    • In multipass builds where the NoCare flag has been applied to a target that is missing, the build will not attempt to move the missing file's build to the next pass. It will now be properly processed in the current pass.
    • Fixed a couple of multipass issues illustrated in tests/multipass_error where an error occurs during the action on the first pass, and anything dependent on the 'errored' file on a subsequent pass should abort. This fix also covers the case where the action fails in the first pass but succeeds in the second pass, letting dependent targets process successfully.
    • When a target is missing and there are queued Jamfiles, the actions of that target are now shifted into the next pass.
  • Fixed an issue where Jam did not properly handle a generated source/header when there were multiple targets applied to an action.
  • Altered the OPT_UPDATED_CHILD_FIX from http://maillist.perforce.com/pipermail/jamming/2006-May/002676.html to handle the case where an child target's includes target has a fate of anything greater than T_FATE_STABLE. This specifically guards against the case where T_FATE_MISSING is applied to one of the children, and it doesn't build in the current Jam execution.
  • OPT_PERCENT_DONE_EXT is turned off for now. It provided faulty percentages due to all of the patches that JamPlus employs.
  • Applied a registry scanning bug fix from Philipp Teschner. Previous to the fix, W32_GETREG only worked with HKEY_LOCAL_MACHINE. If the Jam script used anything else, it would infinitely loop.
  • Turned off the OPT_CHILD_UPDATED patch in make.c. It does not work properly with certain combinations of assets, and in truth, I'm not sure what problem it is really trying to solve or even if another patch solves it already.
  • Fixed a bug in the glob expansion directory matching: **