Boost logo

Boost-Build :

From: Jurko Gospodnetić (jurko.gospodnetic_at_[hidden])
Date: 2008-05-25 08:02:55

   Hi Andrej.

> I am using bjam happily on Linux for a few years now.
> At this point I am starting a project that requires me
> to build a multi-platform (Linux, Windows and AIX)
> application. Now I am wondering how bjam is invoked on
> Windows. In particular, can I use bjam in Visual
> Studio to drive the build process? Is there a
> recommended way to work with bjam on Windows?

   We are very happy using it from Visual Studio via a Visual Studio's
makefile project. Then you can specify its build, rebuild & clean
command lines.

   We do two other things in our projects:

   * We also add an additional layer of indirection and actually call a
batch script which then configures and calls bjam as we find it easier
to tweak all Boost Build call parameters in that single file then by
editing them in the Visual Studio's project properties.

   * We made our Boost Build Jamfiles take an additional --target-path
parameter which can be used to specify from the outside where to install
built targets. This is then used by Visual Studio to make Boost Build
copy all the needed files and folders into its Debug/Release/whatever
build folders. Alternative would be to configure Visual Studio with as
many configurations as there are property combinations you plan on using
and then configure each to look for the built executable in the
corresponding Boost Build folder. We chose not to do it this way as when
we work in Visual Studio we generally build with only a single Boost
Build property set and copying over results of a different build when
you change the properties is a really quick operation anyway since all
intermediate build results are kept in separate Boost Build folders and
so we do not have to rebuild them.

   I'm attaching a sample batch file that you can use as a template. To
use it set Microsoft Visual Studio project settings for each of your
configurations similar to the following ones.


   NMake/Build Command Line:
"$(SolutionDir)/../../../../BuildSystem/visualStudioBuild.cmd" build
"$(TargetDir)" "$(ConfigurationName)" "$(ProjectName)"

   NMake/Rebuild All Command Line:
"$(SolutionDir)/../../../../BuildSystem/visualStudioBuild.cmd" rebuild
"$(TargetDir)" "$(ConfigurationName)" "$(ProjectName)"

   NMake/Clean Command Line:
"$(SolutionDir)/../../../../BuildSystem/visualStudioBuild.cmd" clean
"$(TargetDir)" "$(ConfigurationName)" "$(ProjectName)"


   That is of course assuming you are installing your built projects
into Visual Studio's $(ProjectDir)$(OutDir) folder (Project/Debug,
Project/Release, etc...).

   The $(TargetDir) and $(TargetPath) variables will be set
automatically based on what you enter into the NMake/Output
configuration setting.

   You will also have to modify the path to the visualStudioBuild.cmd
script depending on where you place it.

   Hope this helps.

   Best regards,
     Jurko Gospodnetić

:: Sample script for running a Boost Build based project build system from
:: Microsoft Visual Studio.
:: Parameters:
:: * %1 ... Build action to perform (build, rebuild, clean).
:: * %2 ... Visual Studio solution folder.
:: * %3 ... Target folder.
:: * %4 ... Visual Studio configuration name (Debug, Release, ...).
:: * %5 ... Target name.
:: Used global variables:
:: None.
:: Return values:
:: * 0 ... Always returned.
:: Copyright (C) Docte, 2008.
:: Distributed under the Boost Software License, Version 1.0.
:: (See
:: Implementation notes:
:: This batch file assumes that the bjam utility is on the path and that all
:: environment variables needed for Visual Studio utilities to operate normally
:: are set. One way to achive this is to run this script from the Visual Studio
:: Command Prompt or from the Visual Studio IDE.
:: (06.03.2008.) (Zoran)

@echo off

:: ---------------------
:: Parameter processing.
:: ---------------------

for %%i in ("%~f0\..") do set BUILD_SYSTEM_FOLDER=%%~fi


set LOCAL__TEMP=%1
if not defined LOCAL__TEMP goto :error__invalid_parameters
set LOCAL__TEMP=%2
if not defined LOCAL__TEMP goto :error__invalid_parameters
set LOCAL__TEMP=%3
if not defined LOCAL__TEMP goto :error__invalid_parameters
set LOCAL__TEMP=%4
if not defined LOCAL__TEMP goto :error__invalid_parameters

if not defined PARAM__TARGET_NAME goto :error__missing_target_name

:: -----------------------
:: Boost build parameters.
:: -----------------------

:: Boost Build toolset specification.
call :appendBoostBuildParameter toolset=msvc

:: Boost Build build variant specification.
if "%PARAM__VISUAL_STUDIO_CONFIGURATION_NAME%"=="Debug" call :appendBoostBuildParameter debug
if "%PARAM__VISUAL_STUDIO_CONFIGURATION_NAME%"=="Release" call :appendBoostBuildParameter release

:: Main target name.
call :appendBoostBuildParameter %PARAM__TARGET_NAME%

:: Folder into which to install the built targets.
for %%i in ("%PARAM__TARGET_DIR%\.") do set PARAM__TARGET_DIR=%%~fi
call :appendBoostBuildParameter --target-path="%PARAM__TARGET_DIR%"

:: Folder where intermediate build files are placed.
if defined BUILD_FOLDER call :appendBoostBuildParameter --build-dir="%BUILD_FOLDER%"

:: How many build actions is Boost Build allowed to run in parallel.
if defined NUMBER_OF_PROCESSORS call :appendBoostBuildParameter -j %NUMBER_OF_PROCESSORS%

:: --------------------------------
:: Additional Boost Build tweaking.
:: --------------------------------

:: Uncomment to have Boost Build stop when the first error is encountered.
::call :appendBoostBuildParameter -q

:: Uncomment to disable precompiled header usage.
::call :appendBoostBuildParameter pch=off

:: Uncomment to have Boost Build only display the commands it would run
:: without actually running them.
::call :appendBoostBuildParameter -n

:: Uncomment & set to an appropriate bjam debug logging level for more verbose
:: Boost Build output, e.g. +2 displays the executed action commands. See bjam
:: --help-options for more detailed information.
::call :appendBoostBuildParameter -d+2

:: Uncomment to make Boost Build use shorter generated target folder names.
::call :appendBoostBuildParameter --abbreviate-paths

:: Uncomment to have Boost Build display some additional build debugging
:: information such as for example, actual properties used for each built
:: target. Note that this may cause Visual Studio to parse the Boost Build
:: output incorrectly and treat some of the output lines as build error reports.
::call :appendBoostBuildParameter --debug-building

:: Start bjam.


if "%PARAM__ACTION%"=="build" bjam %BJAM_OPTIONS%
if "%PARAM__ACTION%"=="rebuild" bjam -a %BJAM_OPTIONS%
if "%PARAM__ACTION%"=="clean" bjam %BJAM_OPTIONS% clean


    :: Implementation note:
    :: The following text must be output so that Visual Studio detects a build
    :: error. Batch file return code returned using 'exit /b' is ignored. If
    :: exit without the /b option is used then Visual Studio recognizes the
    :: error but its error message are more cryptic and the script also causes
    :: the calling shell to terminate when run manually from the command line.
    :: (29.04.2008.) (Juraj)
    if not "%LOCAL__BJAM_RETURN_CODE%"=="0" echo BJAM : fatal error : : return code '%LOCAL__BJAM_RETURN_CODE%'
    exit /b

:: appendBoostBuildParameter()
:: ---------------------------
:: Everything passed to this function gets appended to the BJAM_OPTIONS
:: environment variable.
:: Parameters:
:: * Any.
:: Used global variables:
:: * BJAM_OPTIONS (write).
:: Return values:
:: * 0 ... Always returned.

    exit /b 0

:: ---------------
:: Error handling.
:: ---------------

    echo. Invalid Visual Studio build script command line parameters.
    echo. Usage: %~nx0 (buildAction) (solutionFolder) (targetFolder) (configurationName) (targetName)
    echo. See the script comments for more detailed information.
    goto :end

    echo. Missing target name.
    goto :end

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at