JamPlus works out of the box with C/C++ compilation for Visual C++ compilers, GCC, MinGW, and others. It can also generate workspaces for Visual Studio 20xx, Visual C++ 6, Xcode, and CodeBlocks.
When the Jam executable is run, it reads a file called Jamfile.jam in the current working directory. The Jamfile contains a description of how to build the current project. In the tutorials below, we'll talk about how to properly set up a Jamfile build description.
For this tutorial, we are going to make a basic helloworld application. You will find the source code presented below in the samples/tutorials/01-helloworld/ directory in the JamPlus source distribution.
First, we need to create a basic main.c. It will do nothing more than print Hello, world! to the user.
/* main.c */ #include <stdio.h> int main() { printf("Hello, world!\n"); return 0; }
In the same directory as main.c, we need to create Jamfile.jam with the description of how to build the basic helloworld application.
# This file is Jamfile.jam. # # Please note that Jam tokens are whitespace separated. Even the semicolon # delineating the end of statements has whitespace before it. SubDir TOP ; # ^ Space here C.Application helloworld : main.c ;
Compiling the helloworld application is simple. Assuming the Jam executable is in your PATH, run the following from the 01-helloworld tutorial directory:
jam
That's it. Jam will detect your OS and then the appropriate compilers for your platform. On Windows, Jam looks for Visual Studio 2010, then 2008, and so on until Visual C++ 6. If it can't find any of those, it looks for a MinGW installation in the c:/mingw/ and d:/mingw/ directories. On Mac OS X, Jam looks for gcc. When a compiler is found, the helloworld application's Debug configuration is built. The resultant filename will be helloworld.debug.exe on Windows or helloworld.debug on other platforms.
Building the helloworld application Release configuration is performed with a command line flag. In this case, the built executable will be helloworld.release.exe (without the .exe on other platforms).
jam CONFIG=release
If you would like to run with another compiler by default, such as MinGW, an additional command line flag must be provided.
jam COMPILER=mingw
After a build, you may notice there are a number of extra files in the directory that weren't there before. These are generally compiler intermediates, and we'll soon learn how to redirect them elsewhere.
For now, instead of leaving behind various junk files, Jam can clean up after itself using the clean target. Targets on the Jam command line are specified after the command line flags. Various examples follow:
rem Cleans the Debug build. jam clean rem Cleans the Debug build, too. jam CONFIG=debug clean rem Cleans the Release build, too. jam CONFIG=release clean
One of the exciting features of JamPlus is its ability to build IDE workspaces for Visual Studio or Xcode or others. It does so with a set of scripts that ship in the JamPlus binary package. These scripts create an out-of-source build tree optimized for best performance within JamPlus. By being out-of-source, the source tree remains pristine, and all compiler intermediates are stored in a separate location.
For the helloworld application, let's build a Visual Studio 2008 solution.
jam --workspace --gen=vs2008 Jamfile.jam build
On Mac OS X, you may want to build an Xcode workspace:
jam --workspace --gen=xcode Jamfile.jam build
In just a quick moment, the new out-of-source work area will have been created. Inside the generated 01-helloworld/build/_workspace.vs2008_/ directory, you'll find a helloworld.sln. Open this file in Visual Studio to proceed.
When Visual Studio has loaded the helloworld.sln, you'll find it contains the helloworld project within the Solution Explorer. If the helloworld project is not already the active project, right click on it and choose Set as StartUp Project.
On Mac OS X, you'll find the appropriate .xcodeproj as 01-helloworld/build/_workspace.xcode_/helloworld.workspace.xcodeproj. Open this project file in Xcode.
At this point, build as you normally would. Change between the Debug and Release configurations if you'd like. In fact, you can even debug as if the project were manually created!
This tutorial is nearly identical to Tutorial 1, except we are going to statically link the C runtime.