Using Boost Libraries in Windows Store and Phone Applications

Boost contains a lot of high quality cross platform C++ libraries. Some of the libraries in Boost use APIs that aren’t available in Windows Store and Phone applications. To help improve the experience Microsoft’s been working on enabling some of the Boost libraries.

We’ve made improvements to the Boost build system to support targeting the Windows Runtime for Windows Store and Phone. Also we’ve made changes to make the following Boost libraries work for Windows Store and Phone: system, chrono, date_time, smart_ptr, signals2, and thread. In addition to these Boost libraries, many others don’t use any banned APIs and work fine. This post shows how you can build and utilize portions of Boost in your Windows applications.

Download and Setup Boost Sources

Here are the steps to download and setup the Boost sources for building. Boost has moved over to GitHub, now using Git submodules. More detailed information about modular Boost can be located here.

• Clone Boost and setup for building. Please note this is a one-time operation that will take some time as it brings down all of the Boost sources. Throughout this post it is assumed you cloned into C:\boost.

•  git clone –recursive https://github.com/boostorg/boost.git boost
•  cd boost
•  .\bootstrap
•  .\b2 headers

• Add the build tool, b2, to your Path environment variable. If you are using PowerShell something like following works.

•  $env:Path += “;C:\boost”;

• A few of the changes for enabling the Windows Runtime haven’t migrated to into the ‘master’ branches or are still pending a merge. For these you will need to checkout the ‘develop’ branch or pull from my private branch containing the necessary changes.

Boost.Build

•  cd C:\boost\tools\build
•  git checkout develop

Boost.Config

•  cd C:\boost\libs\config
•  git remote add winrt_fork https://github.com/MSOpenTech/config.git
•  git fetch winrt_fork winrt
•  git checkout winrt

Boost.Thread – optional only needed if going to use thread or a library that depends on it

•  cd C:\boost\libs\thread
•  git remote add winrt_fork https://github.com/MSOpenTech/thread.git
•  git fetch winrt_fork winrt2
•  git checkout winrt2

Building for Windows Store and Phone

With the latest Boost sources and your repositories setup you are now ready for building. If the Boost library/libraries you are interested in using are header file only, like Boost.Signals2 for example, then you don’t need to build and can entirely skip this step. Of the libraries we’ve enabled and verified, system, chrono, thread, and date_time are the only ones that require building.

To enable easily targeting the Windows Runtime a new feature called ‘windows-api’ has been added to the Boost build system. It accepts the values ‘store’, ‘phone’, and defaults to ‘desktop’ if not specified.

To build go to the build directory under the library you wish to use, for example to build Boost.Thread 32 bit debug for Windows 8.1 Store for static linking use the following command:

•  cd C:\boost\libs\thread\build
•  b2 toolset=msvc-12.0 link=static windows-api=store

About toolsets and targeting, the toolset you specify determines which Windows version you are targeting:

•  Windows 8.0:                toolset=msvc-11.0 windows-api=store
•  Windows 8.1:                toolset=msvc-12.0 windows-api=store
•  Windows Phone 8.0:     toolset=msvc-11.0 windows-api=phone
•  Windows Phone 8.1:     toolset=msvc-12.0 windows-api=phone

The built-in Boost features variant, address-model, architecture, link can be used to produce debug/release, x86/x64/arm, and static/shared binaries. For example the following builds the release configuration, with static linking for the ARM architecture:

b2 toolset=msvc-12.0 variant=release link=static architecture=arm windows-api=store

More detailed information can be found in the Boost.Build documentation.

Once built, the binaries are output under the bin.v2 folder. The exact location is dependent on the options used and the name of the library built. For the command from before used to build Boost.Thread the binaries are located under:

C:\boost\bin.v2\libs\thread\build\msvc-12.0\debug\link-static\threading-multi\windows-api-store\

Please note Visual Studio 2013 didn’t include vcvarsphone setup scripts so you won’t be able to target Phone 8.1 out of the box. With this blog post I’ve included phone setup scripts that can be used when targeting Windows Phone 8.1. To setup them up create the folders called WPSDK\WP81 under the VC Visual Studio installation directory, C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\, and copy the phone setup script files in.

How to use in an Application

With all the setup and building complete, using in an application is just the same as with any other C++ library. Setup the include path by adding C:\boost\. If the Boost library you’re using isn’t header file only then link to the lib and add the dll to the project (if not using static linking), making sure to set the ‘Content’ property to true so it is picked up for application deployment.

To help illustrate how to setup and use in an application, at the end of this post, I’ve included a simple sample Windows 8.1 Store application that utilizes the thread and signal2 libraries. The sample creates a simple signal with multiple slots using Boost threads in different ways. The sample assumes you cloned Boost into the C:\boost directory and built static linking for Boost.Thread, Boost.Date_Time, Boost.Chrono, and Boost.System, if this isn’t the case then you will need to update the include and library paths. Included with the sample also are the vcvars setup scripts for targeting Windows Phone 8.1.

Feedback and How to Enable More Boost Libraries

For your next Windows Store and Phone application try using and let us know how it goes. Several individuals are already trying it out and Spotify is using several of the libraries in their Windows Phone application.

Not all of the libraries in Boost work yet in Windows Store and Phone, but the work we’ve done makes it easier to build and replace or update banned APIs. If one of the Boost libraries you want to use doesn’t work, depending on the banned API it might be easy to replace. We’ve added several new Boost.Predef, macros. By including <boost/predef/platform.h> you can use the BOOST_PLAT_WINDOWS_DESKTOP and BOOST_PLAT_WINDOWS_RUNTIME macros to test which platform is being targeted. For example if a call to WaitForSingleObject (only allowed in desktop) is used, you could replace it with WaitForSingleObjectEx by checking the macro for the Windows Runtime:

#include <boost/predef/platform.h>
…
#if BOOST_PLAT_WINDOWS_RUNTIME
    WaitForSingleObjectEx(handle, INFINITE, FALSE);
#else
    WaitForSingleObject(handle, INFINITE);
#endif

For more complex examples of API replacement you can take a look at the changes I made for Boost.Thread.

We are interested in hearing your feedback. What Boost libraries do you care about or what to use in your Windows Store and Phone applications?

 

BoostSample .zip