Getting Started

back to codeshop /  to wiki

After downloading the libraries, you might wonder where to start ...

---

Boost Build

Code Shop uses the Boost Build System (version 2), which, basically, is a make replacement without the hassle of make. It's very portable and comes packaged with settings for all kinds of platforms (windows/mac/*nix etc). In it's own words:

• A simple target description language
• Build with your choice (or multiple) toolsets from a single command invocation
• Build your choice of basic variants (e.g. debug, release, profile...) and subvariant modifications (e.g. inlining off) from a single command invocation
• Feature Normalization allows target configurations to be described independently from the toolset used
• Modular toolset description files allow build instructions for different toolsets to be described independently
• Multiple subproject support
• Automatic building of subproject dependencies

Introduction

A very good introduction to the boost build system can be found  here:

http://www.boost.org/doc/html/bbv2.html

Another good description can be found inside the boost libraries, the boost.python library:

http://www.boost.org/libs/python/doc/tutorial/doc/html/python/hello.html

But please note, this is for boost.build v1 not v2.

Build

The following describes the steps you should take in order to get the libraries to work:

• download the source (see the download section:
• run bjam

Let's jam!

Here is the minimalist jamfile from src/example:

# 
project example
  : source-location .
  : usage-requirements <include>.
  ;

lib example
  :
    example.cpp
  :
    <define>BUILDING_EXAMPLE
  ;
  
unit-test example_unit_test 
  : 
    example_unit_test.cpp 
    example
  ;

As yo can see, there are 3 sections defined: project, lib and unit-test (there are more targets, for example 'exe', but see the bjam docs mentioned earlier).

This does the following: its creates

example.dll
example_unit_test.exe

on windows, and

example.so
example_unit_test

on linux (or any *nix) and calls the unit-test, printing the status:

[f:\codeshop\open\trunk\src\example]bjam
warning: toolset gcc initialization: can't find tool g++
warning: initialized from
...found 27 targets...
...updating 14 targets...
MkDir1 bin
MkDir1 bin\msvc-7.1
MkDir1 bin\msvc-7.1\debug
MkDir1 bin\msvc-7.1\debug\threading-multi
msvc.compile.c++ bin\msvc-7.1\debug\threading-multi\example.obj
example.cpp
msvc.link.dll bin\msvc-7.1\debug\threading-multi\example.dll bin\msvc-7.1\debug\threading-multi\example.lib
   Creating library bin\msvc-7.1\debug\threading-multi\example.lib and object bin\msvc-7.1\debug\threading-multi\example.exp
msvc.compile.c++ bin\msvc-7.1\debug\threading-multi\example_unit_test.obj
example_unit_test.cpp
msvc.link bin\msvc-7.1\debug\threading-multi\example_unit_test.exe
testing.unit-test bin\msvc-7.1\debug\threading-multi\example_unit_test.passed
test(s) successfull
...updated 14 targets...

As you can see, there is a lot happening here:

• directories are created
• code is compiled and linked
• a unit-tester is build, linked and run
• and a report is printed (when the unittest fails, it's quite visible :)

And you get all this from a few lines in a jamfile, not bad now, is it?

Running bjam

Bjam is run using your operating system's command line interpreter.

So start up your shell, cmd or 4nt or cygwin or ...

[f:\]cd codeshop\projects\open\trunk\src\example
[f:\codeshop\projects\open\trunk\src\example]bjam

Bjam then looks for a jamfile.v2 file with your project definition - et voila.

(Bjam can be found inside trunk/bin - if you need to compile it for your platfrom, please visit the docs mentioned above (bjam sources are distributed with the boost distribution)).

Make sure that the environment is set so that we can invoke the C++ compiler. With MSVC, that would mean running the vcvars32.bat batch file. For instance:

C:\Program Files\Microsoft Visual Studio .NET 2005\Common7\Tools\vsvars32.bat

note: vsvars32 calls vcvars32; this wat added in .net 2003/5

Locations like the above can be put into your own copy of trunk\settings.bat (on windows), or in .bashrc - etc.

All the compiler settings are taken from bin/build.v11 - but if yo need anything special, please visit the docs mentioned above.

This should be all to get you up and running.

But of course - feel free to place the code from our libs into your own build environment, if this suites you better.