Difference between revisions of "BoostWindowsQuickRef"

From Code::Blocks
(Updated for Boost 1.36.0)
(fix path change commands)
 
(28 intermediate revisions by 8 users not shown)
Line 6: Line 6:
 
'''Important Requirements:'''
 
'''Important Requirements:'''
 
* '''Windows compiler''' - You need to have correctly installed the free [http://www.mingw.org/ MinGW/GCC] compiler or one of [http://msdn.microsoft.com/vstudio/ Microsoft's compilers] (the [http://msdn.microsoft.com/vstudio/express/ Express editions] are free, but you must also install the [http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb Platform SDK]). The [https://www.codeblocks.org/downloads/5#windows latest stable release of Code::Blocks] includes a MinGW-bundled version which includes all necessary packages; or, if you install it by hand, you need at least the gcc-core, gcc-g++, binutils, w32api, and mingw32-make packages. Also, ensure that the folder containing the compiler executables (typically C:\Program Files\CodeBlocks\bin) is in your [http://vlaurie.com/computers2/Articles/environment.htm#editing Windows PATH environment variable].
 
* '''Windows compiler''' - You need to have correctly installed the free [http://www.mingw.org/ MinGW/GCC] compiler or one of [http://msdn.microsoft.com/vstudio/ Microsoft's compilers] (the [http://msdn.microsoft.com/vstudio/express/ Express editions] are free, but you must also install the [http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb Platform SDK]). The [https://www.codeblocks.org/downloads/5#windows latest stable release of Code::Blocks] includes a MinGW-bundled version which includes all necessary packages; or, if you install it by hand, you need at least the gcc-core, gcc-g++, binutils, w32api, and mingw32-make packages. Also, ensure that the folder containing the compiler executables (typically C:\Program Files\CodeBlocks\bin) is in your [http://vlaurie.com/computers2/Articles/environment.htm#editing Windows PATH environment variable].
* '''Recent version of Code::Blocks''' - You need to have successfully installed and run a recent version of Code::Blocks -- either [https://www.codeblocks.org/downloads/5#windows the latest stable release] or [/index.php/board,20.0.html a recent nightly build].
+
* '''Recent version of Code::Blocks''' - You need to have successfully installed and run a recent version of Code::Blocks either [https://www.codeblocks.org/downloads/5#windows the latest stable release] or [/index.php/board,20.0.html a recent nightly build].
  
  
Line 13: Line 13:
  
 
=== Boost Source Code ===
 
=== Boost Source Code ===
The Boost libraries are distributed as source code archived in .7z, .tar.bz2, .tar.gz, or .zip format; choose whichever archive format is easiest for you to unpack. The current stable release of Boost is '''1.36.0'''. [http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=619445 Click here to browse the Boost 1.36.0 downloadable files]. You can check [http://www.boost.org/users/download/ the Boost download page] to see if a newer stable version is available.
+
The Boost libraries are distributed as source code archived in .7z, .tar.bz2, .tar.gz, or .zip format; choose whichever archive format is easiest for you to unpack. The current stable release of Boost is '''1.47.0'''. [http://www.boost.org/users/news/version_1_47_0 Click here to browse the Boost 1.47.0 version info and files]. You can check the Boost home page at [http://www.boost.org/ boost.org] to see if a newer stable version is available.
  
You also need to download Boost Jam in order to build Boost. The current stable release of Boost Jam is '''3.1.16'''. [http://downloads.sourceforge.net/boost/boost-jam-3.1.16-1-ntx86.zip Click here to download Boost Jam for Windows] (boost-jam-3.1.16-1-ntx86.zip; 115 KB).
+
You also need to download Boost Jam in order to build Boost. The current stable release of Boost Jam is '''3.1.18'''. [http://sourceforge.net/projects/boost/files/boost-jam/3.1.18/boost-jam-3.1.18-1-ntx86.zip Click here to download Boost Jam for Windows] (boost-jam-3.1.18-1-ntx86.zip; 121.4 KB).
  
'''It is highly recommended that you unpack the sources to a path without spaces.''' You should choose a volume with at least XXX MB of free space. Typically, the Boost sources and Boost Jam are unpacked in separate locations, ending up with "<path>\boost_1_36_0" and "<path>\boost-jam-3.1.16-1-ntx86".
+
Note: Downloading precompiled bjam seems to be an outdated method.
 +
To build bjam from source, use bootstrap.bat from Boost base directory.
 +
Bootstrap.bat assumes you are using msvc compiler, to use Gcc, type "bootstrap.bat gcc"
 +
 
 +
'''It is highly recommended that you unpack both archives to paths without spaces.''' You should choose a volume with at least 1.5 GB of free space. Typically, the Boost sources and Boost Jam are unpacked in separate locations, ending up with "<path>\boost_1_47_0" and "<path>\boost-jam-3.1.18-1-ntx86".
  
 
=== Boost Installer for MSVC 2003 (7.1) or later ===
 
=== Boost Installer for MSVC 2003 (7.1) or later ===
BoostPro Computing distributes a free web-based installer that will download and install prebuilt versions of the Boost libraries for MSVC. [http://www.boostpro.com/products/free Click here to browse the BoostPro Free Downloads]. The amount of space used by the installation varies depending on which libraries and variants you choose.
+
BoostPro Computing distributes a free web-based installer that will download and install prebuilt versions of the Boost libraries for MSVC. [http://www.boostpro.com/download Click here to browse the BoostPro Free Downloads]. The amount of space used by the installation varies depending on which libraries and variants you choose.
  
  
Line 28: Line 32:
 
* Open up a command prompt for building. If you are using MinGW/GCC, simply use the standard Windows command shell (open the Start menu, click "Run...", enter "cmd" and hit OK). If you are using MSVC, you should use the special command shell which sets up the correct environment variables for you. If you use a version of MSVC which required you to download the Platform SDK separately, ensure that whichever command environment you use includes the Platform SDK tools and paths as well as the standard compiler tools and paths.
 
* Open up a command prompt for building. If you are using MinGW/GCC, simply use the standard Windows command shell (open the Start menu, click "Run...", enter "cmd" and hit OK). If you are using MSVC, you should use the special command shell which sets up the correct environment variables for you. If you use a version of MSVC which required you to download the Platform SDK separately, ensure that whichever command environment you use includes the Platform SDK tools and paths as well as the standard compiler tools and paths.
 
* Ensure that Boost Jam is in the PATH environment variable (where <path> is the path you unpacked Boost Jam to):
 
* Ensure that Boost Jam is in the PATH environment variable (where <path> is the path you unpacked Boost Jam to):
  set PATH=<path>\boost-jam-3.1.16-1-ntx86;%PATH%
+
  PATH <path>\boost-jam-3.1.18-1-ntx86;%PATH%
 +
* Ensure that the compiler is in the PATH environment variable:
 +
PATH C:\Program Files (x86)\CodeBlocks\MinGW\bin;%PATH%
 
* Change to the Boost sources directory (where <path> is the path you unpacked the Boost sources to):
 
* Change to the Boost sources directory (where <path> is the path you unpacked the Boost sources to):
  cd <path>\boost_1_36_0
+
  cd /D <path>\boost_1_47_0
 +
''Note: the ''<code>/D</code>'' flag after ''<code>cd</code>'' may be omitted from the command; it simply allows command prompt to change drives if necessary.''
 
* Execute the build command. The recommended command to use for '''MinGW/GCC''' is (where <installpath> is where you want the Boost headers and libraries; typically C:\Program Files\CodeBlocks):
 
* Execute the build command. The recommended command to use for '''MinGW/GCC''' is (where <installpath> is where you want the Boost headers and libraries; typically C:\Program Files\CodeBlocks):
 
  bjam --toolset=gcc "--prefix=<installpath>" install
 
  bjam --toolset=gcc "--prefix=<installpath>" install
Line 37: Line 44:
 
* This step will generally take 5-20 minutes, depending on the capabilities of your PC.
 
* This step will generally take 5-20 minutes, depending on the capabilities of your PC.
 
* The above commands will build release, multithreaded, DLL versions of the Boost libraries. If you want other variants, add --build-type=complete to the command line. This will take a much longer amount of time to build.
 
* The above commands will build release, multithreaded, DLL versions of the Boost libraries. If you want other variants, add --build-type=complete to the command line. This will take a much longer amount of time to build.
 
  
 
== Add Boost to an existing project in Code::Blocks ==
 
== Add Boost to an existing project in Code::Blocks ==
Line 43: Line 49:
  
 
=== Set up a Code::Blocks global variable for Boost ===
 
=== Set up a Code::Blocks global variable for Boost ===
This step only needs to be performed once, after which the global variable you've created will be available for any project.
+
This step only needs to be performed once, after which the [[Global compiler variables|global variable]] you've created will be available for any project.
 
* Open the Settings menu and select "Global variables..."
 
* Open the Settings menu and select "Global variables..."
 
* Click the "New" button next to the Current variable list, specify a name like "boost", and hit OK
 
* Click the "New" button next to the Current variable list, specify a name like "boost", and hit OK
 
* In the "base" field of the Builtin fields section, browse for the base of your Boost installation -- the path you specified in the --prefix option of the build command
 
* In the "base" field of the Builtin fields section, browse for the base of your Boost installation -- the path you specified in the --prefix option of the build command
* In the "include" field, browse for the "include\boost-1_36" subfolder of your Boost installation -- it should be the path in the "base" field with "\include\boost-1_36" tacked on.
+
<!-- * In the "include" field, browse for the "include\boost-1_47" subfolder of your Boost installation -- it should be the path in the "base" field with "\include\boost-1_42" tacked on. Not valid anymore. -->
 +
* In the "lib" field, browse for the "stage\lib" subfolder of your Boost installation -- it should be the path in the "base" field with "\stage\lib" tacked on. (This is the folder that contains either multiple <tt>lib*.a</tt> or <tt>*.lib</tt> files.)
 
* Hit the Close button to save your global variable
 
* Hit the Close button to save your global variable
  
Line 54: Line 61:
 
* Highlight the root of your project in the tree on the left side of the Project build options window
 
* Highlight the root of your project in the tree on the left side of the Project build options window
 
* Select the "Search directories" tab
 
* Select the "Search directories" tab
* With the "Compiler" subtab selected, click the Add button, enter "$(#boost.include)" (without the quotes), and hit OK
+
* With the "Compiler" subtab selected, click the Add button, enter "<tt>$(#boost.include)</tt>" (without the quotes), and hit OK
 
''If you are using the bundled version of MinGW with Code::Blocks, and you used your C::B installation in the --prefix option as recommended, the following step is unnecessary''
 
''If you are using the bundled version of MinGW with Code::Blocks, and you used your C::B installation in the --prefix option as recommended, the following step is unnecessary''
* With the "Linker" subtab selected, click the Add button, enter "$(#boost.lib)" (without the quotes), and hit OK
+
* With the "Linker" subtab selected, click the Add button, enter "<tt>$(#boost.lib)</tt>" (without the quotes), and hit OK
  
 
=== Include Boost headers and link with Boost libraries ===
 
=== Include Boost headers and link with Boost libraries ===
 
Your project is now ready to use the Boost libraries. For each library you want to use, do the following:
 
Your project is now ready to use the Boost libraries. For each library you want to use, do the following:
* #include <boost/*.hpp> in your source file
+
* <tt>#include <boost/*.hpp></tt> in your source file
* In your project's build options, highlight the root of your project, select the "Linker settings" tab, and add "boost_*-mgw34-mt-1_36" to your Link libraries
+
* In your project's build options, highlight the root of your project, select the "Linker settings" tab, and add "<tt>boost_*-mgwXX-mt-1_47</tt>" to your Link libraries
For examle, use "#include <boost/filesystem.hpp>" and "boost_filesystem-mgw34-mt-1_36" to use boost.filesystem.
+
For example, use "<tt>#include <boost/filesystem.hpp></tt>", "<tt>boost_filesystem-mgw45-mt-1_47</tt>" and "<tt>boost_system-mgw45-mt-1_47</tt>" to use boost.filesystem.
 +
 
 +
settings compiler & debugger linker settings add
 +
 
 +
examples: (order does matter)
 +
F:\CodeBlocks\lib\libboost_regex-mgw44-1_51.a
 +
F:\CodeBlocks\lib\libboost_thread-mgw44-mt-1_51.a
 +
F:\CodeBlocks\lib\libboost_chrono-mgw44-1_51.a
 +
f:\codeblocks\lib\*.a
 +
 
 +
== Test boost installation==
 +
After the installation, you can use these [http://beans.seartipy.com/2006/03/16/how-to-test-c-boost-installation/ two examples]  to test whether your boost installation and the configuration of your Code::Blocks are successful. If it fails, [/index.php/topic,15164.0.html this post] may have some useful information.
  
 
== Frequently Asked Questions ==
 
== Frequently Asked Questions ==
  
No Frequently Asked Questions (or Frequently Given Answers) have been entered yet.
+
'''Do I need to link with a library for every Boost component I use?'''
 +
 
 +
No. Only some of the Boost components require pre-compilation and additional linked-in code. You can even skip building Boost altogether, if you'll only need components without a link-time library. If you want to know whether a specific component requires a pre-built library, just try including the header(s) without making any linker additions. If you get undefined reference errors, you'll need to add the component's library. Boost maintains a [http://www.boost.org/doc/libs/1_47_0/more/getting_started/windows.html#header-only-libraries list] of which libraries require pre-compilation. (An undefined reference error including <tt>WSA</tt> requires the windows sockets libraries, <tt>ws2_32</tt> and <tt>wsock32</tt>.)

Latest revision as of 15:33, 6 April 2014

A beginner's quick reference for setting up Boost with Code::Blocks in Windows
Supported compilers: MinGW or MSVC


Important Requirements:

  • Windows compiler - You need to have correctly installed the free MinGW/GCC compiler or one of Microsoft's compilers (the Express editions are free, but you must also install the Platform SDK). The latest stable release of Code::Blocks includes a MinGW-bundled version which includes all necessary packages; or, if you install it by hand, you need at least the gcc-core, gcc-g++, binutils, w32api, and mingw32-make packages. Also, ensure that the folder containing the compiler executables (typically C:\Program Files\CodeBlocks\bin) is in your Windows PATH environment variable.
  • Recent version of Code::Blocks - You need to have successfully installed and run a recent version of Code::Blocks – either the latest stable release or [/index.php/board,20.0.html a recent nightly build].


Download Boost

You can download the Boost source code and compile it yourself, or, only if you are using MSVC 2003 (7.1) or later, you can use a web-based installer to download pre-built libraries.

Boost Source Code

The Boost libraries are distributed as source code archived in .7z, .tar.bz2, .tar.gz, or .zip format; choose whichever archive format is easiest for you to unpack. The current stable release of Boost is 1.47.0. Click here to browse the Boost 1.47.0 version info and files. You can check the Boost home page at boost.org to see if a newer stable version is available.

You also need to download Boost Jam in order to build Boost. The current stable release of Boost Jam is 3.1.18. Click here to download Boost Jam for Windows (boost-jam-3.1.18-1-ntx86.zip; 121.4 KB).

Note: Downloading precompiled bjam seems to be an outdated method. To build bjam from source, use bootstrap.bat from Boost base directory. Bootstrap.bat assumes you are using msvc compiler, to use Gcc, type "bootstrap.bat gcc"

It is highly recommended that you unpack both archives to paths without spaces. You should choose a volume with at least 1.5 GB of free space. Typically, the Boost sources and Boost Jam are unpacked in separate locations, ending up with "<path>\boost_1_47_0" and "<path>\boost-jam-3.1.18-1-ntx86".

Boost Installer for MSVC 2003 (7.1) or later

BoostPro Computing distributes a free web-based installer that will download and install prebuilt versions of the Boost libraries for MSVC. Click here to browse the BoostPro Free Downloads. The amount of space used by the installation varies depending on which libraries and variants you choose.


Build Boost

This step is unnecessary if you are using the BoostPro installer

  • Open up a command prompt for building. If you are using MinGW/GCC, simply use the standard Windows command shell (open the Start menu, click "Run...", enter "cmd" and hit OK). If you are using MSVC, you should use the special command shell which sets up the correct environment variables for you. If you use a version of MSVC which required you to download the Platform SDK separately, ensure that whichever command environment you use includes the Platform SDK tools and paths as well as the standard compiler tools and paths.
  • Ensure that Boost Jam is in the PATH environment variable (where <path> is the path you unpacked Boost Jam to):
PATH <path>\boost-jam-3.1.18-1-ntx86;%PATH%
  • Ensure that the compiler is in the PATH environment variable:
PATH C:\Program Files (x86)\CodeBlocks\MinGW\bin;%PATH%
  • Change to the Boost sources directory (where <path> is the path you unpacked the Boost sources to):
cd /D <path>\boost_1_47_0

Note: the /D flag after cd may be omitted from the command; it simply allows command prompt to change drives if necessary.

  • Execute the build command. The recommended command to use for MinGW/GCC is (where <installpath> is where you want the Boost headers and libraries; typically C:\Program Files\CodeBlocks):
bjam --toolset=gcc "--prefix=<installpath>" install
  • The recommended command to use for MSVC is (where <installpath> is where you want the Boost headers and libraries):
bjam --toolset=msvc "--prefix=<installpath>" install
  • This step will generally take 5-20 minutes, depending on the capabilities of your PC.
  • The above commands will build release, multithreaded, DLL versions of the Boost libraries. If you want other variants, add --build-type=complete to the command line. This will take a much longer amount of time to build.

Add Boost to an existing project in Code::Blocks

The Boost libraries are usable in nearly any Code::Blocks project. You can create a new project that will use Boost or open an existing project. With your project open, perform these steps.

Set up a Code::Blocks global variable for Boost

This step only needs to be performed once, after which the global variable you've created will be available for any project.

  • Open the Settings menu and select "Global variables..."
  • Click the "New" button next to the Current variable list, specify a name like "boost", and hit OK
  • In the "base" field of the Builtin fields section, browse for the base of your Boost installation -- the path you specified in the --prefix option of the build command
  • In the "lib" field, browse for the "stage\lib" subfolder of your Boost installation -- it should be the path in the "base" field with "\stage\lib" tacked on. (This is the folder that contains either multiple lib*.a or *.lib files.)
  • Hit the Close button to save your global variable

Add Boost search directories to your project

  • Right-click your project's name in the Projects section of the Management window and select "Build options..."
  • Highlight the root of your project in the tree on the left side of the Project build options window
  • Select the "Search directories" tab
  • With the "Compiler" subtab selected, click the Add button, enter "$(#boost.include)" (without the quotes), and hit OK

If you are using the bundled version of MinGW with Code::Blocks, and you used your C::B installation in the --prefix option as recommended, the following step is unnecessary

  • With the "Linker" subtab selected, click the Add button, enter "$(#boost.lib)" (without the quotes), and hit OK

Include Boost headers and link with Boost libraries

Your project is now ready to use the Boost libraries. For each library you want to use, do the following:

  • #include <boost/*.hpp> in your source file
  • In your project's build options, highlight the root of your project, select the "Linker settings" tab, and add "boost_*-mgwXX-mt-1_47" to your Link libraries

For example, use "#include <boost/filesystem.hpp>", "boost_filesystem-mgw45-mt-1_47" and "boost_system-mgw45-mt-1_47" to use boost.filesystem.

settings compiler & debugger linker settings add

examples: (order does matter) F:\CodeBlocks\lib\libboost_regex-mgw44-1_51.a F:\CodeBlocks\lib\libboost_thread-mgw44-mt-1_51.a F:\CodeBlocks\lib\libboost_chrono-mgw44-1_51.a f:\codeblocks\lib\*.a

Test boost installation

After the installation, you can use these two examples to test whether your boost installation and the configuration of your Code::Blocks are successful. If it fails, [/index.php/topic,15164.0.html this post] may have some useful information.

Frequently Asked Questions

Do I need to link with a library for every Boost component I use?

No. Only some of the Boost components require pre-compilation and additional linked-in code. You can even skip building Boost altogether, if you'll only need components without a link-time library. If you want to know whether a specific component requires a pre-built library, just try including the header(s) without making any linker additions. If you get undefined reference errors, you'll need to add the component's library. Boost maintains a list of which libraries require pre-compilation. (An undefined reference error including WSA requires the windows sockets libraries, ws2_32 and wsock32.)