Jam Workspace Generator

Overview

JamPlus has a built-in workspace generator that reads a project's Jamfiles and exports an IDE workspace. The workspace may then be loaded in the appropriate IDE and represents a read-only view of the contents of the Jamfiles. Updates to the Jamfiles do not appear automatically in the IDE workspace, although correct Jam builds will continue to function. JamPlus provides a facility to manually regenerate the workspace when Jamfiles change.

JamPlus generates a completely out-of-source build structure. This means that all intermediate files, output files, IDE project files, and other miscellaneous Jam related files exist in a directory external to the source code itself. Since the entire build tree is generated, merely removing the out-of-source build directory will destroy all evidence of the build.

Out of source build trees also contain special instructions to make the build run faster. Among other things, the dependency cache is set up. The dependency cache is used to track 'include' dependencies, but it is also used to store MD5 command lines and MD5 contents information.

Usage

Generation of a new IDE workspace is performed by running the command line:

    jam --workspace [options] [[<source-jamfile>] <path-to-destination>]

Running jam –workspace –help will list the help.

jam --workspace
    [ -gen=GENERATOR ]
    [ -platform=PLATFORM ]
    [ -config=CONFIG ]
    [ -compiler=COMPILER ]
    [ -jambaseflags=KEY=VALUE ]
    [ -jamfileflags=KEY=VALUE ]
    [ -jamexepath=JAMEXEPATH ]
    [ -jambase=JAMBASEFULLPATH ]
    [ source-jamfile ]
    [ path-to-destination ]

jam –workspace may be invoked with the following options:

-gen=GENERATOR	(optional) Sets an IDE workspace and project generator. GENERATOR may be one of the following: codeblocks - Generates CodeBlocks workspaces and projects. none (default) - Do not generate a workspace. vc6 - Generates Visual C++ 6.0 workspaces and projects. vs2003 - Generates Visual Studio 2003 solutions and projects. vs2005 - Generates Visual Studio 2005 solutions and projects. vs2008 - Generates Visual Studio 2008 solutions and projects. vs2010 - Generates Visual Studio 2010 solutions and projects. vs2012 - Generates Visual Studio 2012 solutions and projects. vs2013 - Generates Visual Studio 2013 solutions and projects. vs2015 - (default on Windows) Generates Visual Studio 2015 solutions and projects. xcode - (default on macOS) Generates Xcode workspaces and projects.
-compiler=COMPILER	Sets the default compiler used to build with. If not specified, the compiler will be set according to the Jambase auto detection capabilities, with Visual Studio taking precedence. COMPILER may be one of the following: vs2015 - Visual Studio 2015. vs2013 - Visual Studio 2013. vs2012 - Visual Studio 2012. vs2010 - Visual Studio 2010. vs2008 - Visual Studio 2008. vs2005 - Visual Studio 2005. vs2003 - Visual Studio 2003. vc6 - Visual C++ 6. mingw - MinGW. clang - Clang. gcc - GCC.
-platform=PLATFORM	A list of platforms to generate the workspace for. List each additional platform with another -platform option. Corresponds to Config.Platforms.
-config=CONFIG	Provides various configuration options to Jam's workspace generator. CONFIG is the name of the configuration file.
-jambaseflags=KEY=VALUE	Provides additional configuration options when generating the out of source build's redirection Jambase.jam. KEY is the name of a variable known to Jam, such as CSC_COMPILER. VALUE is the value to set that Jam variable to. Examples: CSC_COMPILER=mono (or vs2005 or vs2008)
-jamfileflags=KEY=VALUE	Provides additional configuration options when generating the out of source build's redirection Jamfile.jam.
-jambase=JAMBASEFULLPATH	Overrides the default Jambase.jam that is automatically found near the executable with a user-provided version. JAMBASEFULLPATH must be the full path, filename included, of the alternate Jambase.jam. jam --workspace -jambase=c:/myapp/build/jam/NewJambase.jam ...
source-jamfile	(optional) The path to the Jamfile to start building the workspace from. If this option isn't provided or only the directory is specified, then Jam attempts to load a file named Jamfile.jam from the given directory. If source-jamfile is a directory with filename, such as ../Game/Pong.jam, then the specified Jamfile is loaded.
path-to-destination	(optional) If path-to-destination is specified, then the build tree will be generated into path-to-destination. If path-to-destination is not specified, the build tree is generated off of the current working directory in a directory called .build/.

Assuming a source tree of:

• helloworld/
  • Jamfile.jam
  • src/
    • helperlib/
      • helper.cpp
      • Jamfile.jam
    • main/
      • helloworld.cpp
      • Jamfile.jam

Running JamToWorkspace from the helloworld/ root with the following command line creates an out of source build directory in helloworld/build/.

jam --workspace -gen=vs2008 Jamfile.jam build

From here on out, all Jam executions should be run from within the generated build/ directory.

Generated Files

TODO: This part of the documentation is out of date.

• build/
  • workspace.ide/
    • targetinfo/ - Information files dumped by Jam and used to construct the workspace.
    • DumpJamTargetInfo.jam - A helper redirect script used by updateworkspace.bat.
    • Other assorted files.
    • workspacename.sln/workspacename.xcodeproj/etc - The generated workspace file containing.
    • updateworkspace.bat - Used to update any workspace/project files based on changes to the Jamfiles.
  • temp-PLATFORM-CONFIG/ - All intermediate and output files are built into this directory. Files generated by the Jamfiles likely go into here, too. The directory structure mirrors the source structure.
  • buildenvironment.config - A copy of the configuration passed in through -config.
  • customsettings.jam - Put your own Jam settings here. The file is included before including the Jamfile at the root of your project.
  • jam.bat - A helper batch file containing the absolute path to the Jam executable that should be used for builds.
  • Jambase.jam - The Jam executable searches for a Jambase.jam, and when run from within the build/ directory, this Jambase.jam acts as a redirect to the real Jambase.jam sitting side by side with the Jam executable. Before it redirects, it changes any necessary global settings, such as the default COMPILER, according to the jam –workspace command line.
  • Jamfile.jam - The first Jamfile read by Jam. Contains necessary instructions for setting the intermediate/output location via ALL_LOCATE_TARGET, turning on of the dependency cache through DEPCACHE to speed builds, including the usersettings.jam, and SubInclude statements based on where the source-jamfile was specified and any additional SubIncludes from the .config file.
  • updatebuildenvironment.bat - Regenerates the out of source build root workspace according to settings stored within buildenvironment.config. IDE projects are not updated through this script. Use workspace.vs2008/updateworkspace.bat instead.