Re: [Boost-build] bjam and Windows

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.

   Debugging/Command:
$(TargetPath)

   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)"

   NMake/Output:
$(ProjectDir)$(OutDir)/sjDevelopment.exe

   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 http://www.boost.org/LICENSE_1_0.txt)
::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::
:: 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
setlocal ENABLEEXTENSIONS


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

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

set PARAM__ACTION=%~1
set PARAM__TARGET_DIR=%~f2
set PARAM__VISUAL_STUDIO_CONFIGURATION_NAME=%~3
set PARAM__TARGET_NAME=%~4

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
set LOCAL__TEMP=

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.

cd "%BUILD_SYSTEM_FOLDER%"

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

set LOCAL__BJAM_RETURN_CODE=%ERRORLEVEL%

:end
    :: 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.
::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:appendBoostBuildParameter
    set BJAM_OPTIONS=%BJAM_OPTIONS% %*
    exit /b 0


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

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

:error__missing_target_name
    echo.    Missing target name.
    goto :end