# Cinder

# Cinder & the Boost Libraries

## Introduction

The Boost libraries are a collection of peer-reviewed open source C++ libraries. These libraries are some of the highest quality on the planet. In fact they are so good, several have gone on to become part of the C++ standard itself. Many of the developers who work on Boost are members of the C++ committee.

Cinder makes use of a few key Boost libraries, primarily while we wait for our supported compilers to provide implementations of these features. In particular, Cinder makes use of the Boost smart pointers library and the Boost threads library. Both of these have been accepted as standard C++ and eventually Cinder will phase out the Boost implementations in favor of compiler-provided ones.

## Setting up Boost

If you have downloaded one of the pre-built packages from the Cinder website, Boost is already included - you're all set. However if you are building Cinder yourself from github, or you would like to upgrade your copy of Boost from the included version, these instructions will guide you through the process.

If you want to download the same version as the one we're using in Cinder (which we'd generally recommend), grab version 1.42. You can do so from this site: www.boost.org/users/download/
Now you'll need to put Boost inside your Cinder folder, and rename it boost. Your cinder directory should be laid out similarly to the screenshot below. At this point you should be all done if you are using Boost version 1.42, which is the version Cinder is currently built against. If you are moving to a different version of Boost, follow the build instructions below.

## Using Boost in Cinder

For the most part, Boost is used behind-the-scenes in Cinder automatically. In cinder/Cinder.h you will find the declaration of `cinder::shared_ptr` which presently maps to `boost::shared_ptr`. This is a reference-counted pointer implementation which has been accepted as standard C++ and will be available in all compilers soon. Cinder makes use of `shared_ptr` in its internals, but it's rare that users must create `shared_ptr`s manually. That said, if you are not yet using `shared_ptr`s in your own code, you owe it to yourself to check them out. They are arguably one of the most important recent developments in the language. There are many introductions on the topic, but this is a reasonable one published in Dr. Dobbs.

In addition to `shared_ptr`, Cinder makes use of the `thread` class in Boost. This is promoted to the `std::` namespace in cinder/Thread.h. Much like `shared_ptr`, Boost's `thread` class has been accepted into the official C++ specification, and will be availabe in all conformant compilers soon. In the meantime however, Cinder makes use of Boost's implementation. This means you can write cross-platform multithreaded code easily in Cinder, using classes which are future-proof. If you are not already familiar with it, there are also several tutorials on the `thread` class as well. You might start with this article in Dr. Dobb's, followed by its update article.

The `shared_ptr` library, like many Boost libraries, is a header-only library and consequently has no link dependencies. However `thread` does require users to link against both `libboost_thread` and `libboost_date_time`. On Mac OS X, these libraries are statically linked into Cinder itself, so users don't need to worry about explicitly linking against them once Cinder has been built. Under Windows, things aren't too different - the libraries use Visual C++'s autolinking mechanism to find the libraries automatically, so they don't need to be added to your project explicitly. As a convenience to users, Cinder's link dependencies are shipped with the downloadable archives in addition to being stored as binaries in the github repository. They are located in cinder/lib/macosx and cinder/lib/msw.

## Building Boost (Advanced Users)

If you would like to use a different version of Boost from the one that ships with Cinder, or use a compiler we don't directly support, you'll need to build two Boost libraries yourself. In order to do so you'll want to download Boost.Jam for your platform. This is a command line tool similar to CMake. After decompressing the zip file, move the bjam program into your boost directory. Now let's do some compiling.
Mac OS X:
`cd cinder/boost
./bjam --toolset=darwin --link=static --with-date_time --with-thread architecture=x86 address-model=32_64 macosx-version=10.5 macosx-version-min=10.5 stage
cp stage/lib/*.a ../lib/macosx
`
Windows:
`cd cinder\boost
bjam --toolset=msvc --with-date_time --with-thread runtime-link=static link=static variant=release stage
bjam --toolset=msvc --with-date_time --with-thread runtime-link=static link=static variant=debug stage
copy stage\lib\*.lib ..\lib\msw
`