Building boost locale on iOS

Boost logo

There are three main aspects in the Core SDK where boost is used: XML parsing, file system and unicode handling. Getting boost to compile correctly for iOS is already something that requires some custom sh scripts but getting “locale” (the library that does unicode handling) to compile is a headache for many people on the net. So here is a summary of all the problems and the final solution on how to compile boost (V1.61.0) for iOS with locale support using the iconv library.

Boost Locale’s iconv Detection Mechanism

Most people use a script original created by Pete Goodliffe to build boost into an iOS framework package. There are a couple of variants from various people but I found this one to work the best for me. The problem is that locale requires

  1. some cpp code to be compiled (despite what many people think, boost is not a header-only thing for some library)
  2. locale requires either iconv or icu to work.

What happens for a number of people is that adding locale to the list of boost libraries one wants to compile is not enough because the iconv detection fails for iOS builds. After a lot of trial and error as well as digging through the boost build system, I discovered that


contained a number of compilation errors. Apparently boost locale checks the compiler infrastructure by trying to compile various little test programs and seeing if they fail to compile or not. In the case of locale, it tries to compile


which simply includes iconv and calls one iconv call. What happened with all the variants of the script I found is that all of the compilation tests failed with

-ftemplate-depth-128 unknown command

(the path to the compiler is missing).

Manipulating user-config.jam

The source problem is the method updateBoost() in the script. It adds some using-statements to the user-config.jam which are used to tell boost where to find the compiler and setting some parameter. However, the syntax used in the script is incorrect as it uses a extra “:” . According to the official documentation, the syntax is:

using <compiler_name> : <target/version> : <path_to_compiler> : <optional_arguments> ;

The scripts had another : and some arguments which apparently worked in some cases but not for the build-feature detection code. After fixing this, at least some of the tests worked but iconv was still not detected.

Detecting iconv

Coming back to has_iconv.cpp, there were a couple of problems that needed to be adressed:

  1. The boost build system needs to know where the header and lib for the iOS platform are located. This can be addressed by adding the search paths to the compiler statement in user-config.jam. Note in the code below I did this in a very sloppy way and there will be compilation warnings that I pass a -L statement to the non-linking stages. In theory one should be able to use <instruction-set> as well as <compilerflags> & <linkflags> but for some reason those didn’t seem to have an effect.
  2. It needs to build for the architectures armv7, armv7s, arm64 but not other arm architectures. The build system causes the compiler statement to include “-arch arm” which will make the compiler try to build for armv4t which the iOS libraries do not support. I found no elegant way to solve this and had to edit the darwin.jam file and replace “-arch arm” with “-arch armv7” to get rid of it.

The compilation errors explain why passing -sICONV_PATH as a number of people tried has no effect: The path may very well get down to the compilation statement, but the test simply does not compile at all.

Modified Script

Here is the source of the script as I have used it. The credit goes to the original author, I simply did some workarounds to fix my problem. Use at own risk. Modifications I did:

  1. Change boost version to 1.61.0
  2. Remove armv6 support
  3. Add “locale” to BOOST_LIBS
  4. Fix/extend using statements in updateBoost()

Note that for this to work the darwin.jam has to be adjusted as described in the previous section!

# Filename:
# Author:    Pete Goodliffe
# Copyright: (c) Copyright 2009 Pete Goodliffe
# Licence:   Please feel free to use this, with attribution
# Modified version
# Builds a Boost framework for the iPhone.
# Creates a set of universal libraries that can be used on an iPhone and in the
# iPhone simulator. Then creates a pseudo-framework to make using boost in Xcode
# less painful.
# To configure the script, define:
#    BOOST_LIBS:        which libraries to build
#    IPHONE_SDKVERSION: iPhone SDK version (e.g. 5.1)
# Then go get the source of the boost you want to build, shove it in the
# same directory as this script, and run "./". Grab a cuppa. And voila.

: ${BOOST_LIBS:="random regex graph random chrono thread signals filesystem system date_time locale"}
: ${IPHONE_SDKVERSION:=`xcodebuild -showsdks | grep iphoneos | egrep "[[:digit:]]+\.[[:digit:]]+" -o | tail -1`}
: ${OSX_SDKVERSION:=10.10}
: ${XCODE_ROOT:=`xcode-select -print-path`}

# The EXTRA_CPPFLAGS definition works around a thread race issue in
# shared_ptr. I encountered this historically and have not verified that
# the fix is no longer required. Without using the posix thread primitives
# an invalid compare-and-swap ARM instruction (non-thread-safe) was used for the
# shared_ptr use count causing nasty and subtle bugs.
# Should perhaps also consider/use instead: -BOOST_SP_USE_PTHREADS

: ${TARBALLDIR:=`pwd`}
: ${SRCDIR:=`pwd`/src}
: ${IOSBUILDDIR:=`pwd`/ios/build}
: ${OSXBUILDDIR:=`pwd`/osx/build}
: ${PREFIXDIR:=`pwd`/ios/prefix}
: ${IOSFRAMEWORKDIR:=`pwd`/ios/framework}
: ${OSXFRAMEWORKDIR:=`pwd`/osx/framework}
: ${COMPILER:="clang++"}

: ${BOOST_VERSION:=1.61.0}
: ${BOOST_VERSION2:=1_61_0}


ARM_DEV_CMD="xcrun --sdk iphoneos"
SIM_DEV_CMD="xcrun --sdk iphonesimulator"
OSX_DEV_CMD="xcrun --sdk macosx"



# Functions

    echo "Aborted: $@"
    exit 1

    echo "================================================================="
    echo "Done"


    echo Cleaning everything before we start to build...

    rm -rf iphone-build iphonesim-build osx-build
    rm -rf $IOSBUILDDIR
    rm -rf $OSXBUILDDIR
    rm -rf $PREFIXDIR



    if [ ! -s $TARBALLDIR/boost_${BOOST_VERSION2}.tar.bz2 ]; then
        echo "Downloading boost ${BOOST_VERSION}"
        curl -L -o $TARBALLDIR/boost_${BOOST_VERSION2}.tar.bz2${BOOST_VERSION}/boost_${BOOST_VERSION2}.tar.bz2/download



    [ -f "$BOOST_TARBALL" ] || abort "Source tarball missing."

    echo Unpacking boost into $SRCDIR...

    [ -d $SRCDIR ]    || mkdir -p $SRCDIR
    [ -d $BOOST_SRC ] || ( cd $SRCDIR; tar xfj $BOOST_TARBALL )
    [ -d $BOOST_SRC ] && echo "    ...unpacked as $BOOST_SRC"



    cp $BOOST_SRC/tools/build/src/user-config.jam-bk $BOOST_SRC/tools/build/src/user-config.jam


    echo Updating boost into $BOOST_SRC...

    cp $BOOST_SRC/tools/build/src/user-config.jam $BOOST_SRC/tools/build/src/user-config.jam-bk

    cat >> $BOOST_SRC/tools/build/src/user-config.jam <<EOF
using darwin : ${IPHONE_SDKVERSION}~iphone
: $XCODE_ROOT/Toolchains/XcodeDefault.xctoolchain/usr/bin/$COMPILER -arch armv7 -arch armv7s -arch arm64 -fvisibility=hidden -fvisibility-inlines-hidden $EXTRA_CPPFLAGS -isysroot $XCODE_ROOT/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS${IOS_SDK_VERSION}.sdk -I$XCODE_ROOT/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS${IOS_SDK_VERSION}.sdk/usr/include/ -L$XCODE_ROOT/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS${IOS_SDK_VERSION}.sdk/usr/lib/
: <striper> <root>$XCODE_ROOT/Platforms/iPhoneOS.platform/Developer <architecture>arm <target-os>iphone
using darwin : ${IPHONE_SDKVERSION}~iphonesim
: $XCODE_ROOT/Toolchains/XcodeDefault.xctoolchain/usr/bin/$COMPILER -arch i386 -arch x86_64 -fvisibility=hidden -fvisibility-inlines-hidden $EXTRA_CPPFLAGS
: <striper> <root>$XCODE_ROOT/Platforms/iPhoneSimulator.platform/Developer <architecture>x86 <target-os>iphone



    # These files are missing in the ARM iPhoneOS SDK, but they are in the simulator.
    # They are supported on the device, so we copy them from x86 SDK to a staging area
    # to use them on ARM, too.
    echo Invent missing headers

    cp $XCODE_ROOT/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator${IPHONE_SDKVERSION}.sdk/usr/include/{crt_externs,bzlib}.h $BOOST_SRC


    cd $BOOST_SRC

    BOOST_LIBS_COMMA=$(echo $BOOST_LIBS | sed -e "s/ /,/g")
    echo "Bootstrapping (with libs $BOOST_LIBS_COMMA)"
    ./ --with-libraries=$BOOST_LIBS_COMMA



    cd $BOOST_SRC

    # Install this one so we can copy the includes for the frameworks...
    ./bjam -j16 --build-dir=iphone-build --stagedir=iphone-build/stage --prefix=$PREFIXDIR toolset=darwin architecture=arm target-os=iphone macosx-version=iphone-${IPHONE_SDKVERSION} define=_LITTLE_ENDIAN link=static stage
    ./bjam -j16 --build-dir=iphone-build --stagedir=iphone-build/stage --prefix=$PREFIXDIR toolset=darwin architecture=arm target-os=iphone macosx-version=iphone-${IPHONE_SDKVERSION} define=_LITTLE_ENDIAN link=static install

    ./bjam -j16 --build-dir=iphonesim-build --stagedir=iphonesim-build/stage --toolset=darwin-${IPHONE_SDKVERSION}~iphonesim architecture=x86 target-os=iphone macosx-version=iphonesim-${IPHONE_SDKVERSION} link=static stage

    ./b2 -j16 --build-dir=osx-build --stagedir=osx-build/stage toolset=clang cxxflags="-std=c++11 -stdlib=libc++ -arch i386 -arch x86_64" linkflags="-stdlib=libc++" link=static threading=multi stage


    cd $BOOST_SRC

    mkdir -p $IOSBUILDDIR/armv7/obj
    mkdir -p $IOSBUILDDIR/armv7s/obj
    mkdir -p $IOSBUILDDIR/arm64/obj
    mkdir -p $IOSBUILDDIR/i386/obj
    mkdir -p $IOSBUILDDIR/x86_64/obj

    mkdir -p $OSXBUILDDIR/i386/obj
    mkdir -p $OSXBUILDDIR/x86_64/obj


    echo Splitting all existing fat binaries...

    for NAME in $BOOST_LIBS; do
        ALL_LIBS="$ALL_LIBS libboost_$NAME.a"

        $ARM_DEV_CMD lipo "iphone-build/stage/lib/libboost_$NAME.a" -thin armv7 -o $IOSBUILDDIR/armv7/libboost_$NAME.a
        $ARM_DEV_CMD lipo "iphone-build/stage/lib/libboost_$NAME.a" -thin armv7s -o $IOSBUILDDIR/armv7s/libboost_$NAME.a
        $ARM_DEV_CMD lipo "iphone-build/stage/lib/libboost_$NAME.a" -thin arm64 -o $IOSBUILDDIR/arm64/libboost_$NAME.a

        $ARM_DEV_CMD lipo "iphonesim-build/stage/lib/libboost_$NAME.a" -thin i386 -o $IOSBUILDDIR/i386/libboost_$NAME.a
        $ARM_DEV_CMD lipo "iphonesim-build/stage/lib/libboost_$NAME.a" -thin x86_64 -o $IOSBUILDDIR/x86_64/libboost_$NAME.a

        $ARM_DEV_CMD lipo "osx-build/stage/lib/libboost_$NAME.a" -thin i386 -o $OSXBUILDDIR/i386/libboost_$NAME.a
        $ARM_DEV_CMD lipo "osx-build/stage/lib/libboost_$NAME.a" -thin x86_64 -o $OSXBUILDDIR/x86_64/libboost_$NAME.a

    echo "Decomposing each architectures .a files"

    for NAME in $ALL_LIBS; do
        echo Decomposing $NAME...
        (cd $IOSBUILDDIR/armv7/obj; ar -x ../$NAME );
        (cd $IOSBUILDDIR/armv7s/obj; ar -x ../$NAME );
        (cd $IOSBUILDDIR/arm64/obj; ar -x ../$NAME );
        (cd $IOSBUILDDIR/i386/obj; ar -x ../$NAME );
        (cd $IOSBUILDDIR/x86_64/obj; ar -x ../$NAME );

        (cd $OSXBUILDDIR/i386/obj; ar -x ../$NAME );
        (cd $OSXBUILDDIR/x86_64/obj; ar -x ../$NAME );

    echo "Linking each architecture into an uberlib ($ALL_LIBS => libboost.a )"

    rm $IOSBUILDDIR/*/libboost.a
    echo ...armv7
    (cd $IOSBUILDDIR/armv7; $ARM_DEV_CMD ar crus libboost.a obj/*.o; )
    echo ...armv7s
    (cd $IOSBUILDDIR/armv7s; $ARM_DEV_CMD ar crus libboost.a obj/*.o; )
    echo ...arm64
    (cd $IOSBUILDDIR/arm64; $ARM_DEV_CMD ar crus libboost.a obj/*.o; )
    echo ...i386
    (cd $IOSBUILDDIR/i386;  $SIM_DEV_CMD ar crus libboost.a obj/*.o; )
    echo ...x86_64
    (cd $IOSBUILDDIR/x86_64;  $SIM_DEV_CMD ar crus libboost.a obj/*.o; )

    rm $OSXBUILDDIR/*/libboost.a
    echo ...osx-i386
    (cd $OSXBUILDDIR/i386;  $SIM_DEV_CMD ar crus libboost.a obj/*.o; )

    echo ...x86_64
    (cd $OSXBUILDDIR/x86_64;  $SIM_DEV_CMD ar crus libboost.a obj/*.o; )

    : ${1:?}



    echo "Framework: Building $FRAMEWORK_BUNDLE from $BUILDDIR..."


    echo "Framework: Setting up directories..."
    mkdir -p $FRAMEWORK_BUNDLE
    mkdir -p $FRAMEWORK_BUNDLE/Versions
    mkdir -p $FRAMEWORK_BUNDLE/Versions/$FRAMEWORK_VERSION/Resources
    mkdir -p $FRAMEWORK_BUNDLE/Versions/$FRAMEWORK_VERSION/Headers
    mkdir -p $FRAMEWORK_BUNDLE/Versions/$FRAMEWORK_VERSION/Documentation

    echo "Framework: Creating symlinks..."
    ln -s $FRAMEWORK_VERSION               $FRAMEWORK_BUNDLE/Versions/Current
    ln -s Versions/Current/Headers         $FRAMEWORK_BUNDLE/Headers
    ln -s Versions/Current/Resources       $FRAMEWORK_BUNDLE/Resources
    ln -s Versions/Current/Documentation   $FRAMEWORK_BUNDLE/Documentation


    echo "Lipoing library into $FRAMEWORK_INSTALL_NAME..."
    $ARM_DEV_CMD lipo -create $BUILDDIR/*/libboost.a -o "$FRAMEWORK_INSTALL_NAME" || abort "Lipo $1 failed"

    echo "Framework: Copying includes..."
    cp -r $PREFIXDIR/include/boost/*  $FRAMEWORK_BUNDLE/Headers/

    echo "Framework: Creating plist..."
    cat > $FRAMEWORK_BUNDLE/Resources/Info.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">


# Execution starts here


cleanEverythingReadyToStart #may want to comment if repeatedly running during dev

echo "BOOST_LIBS:        $BOOST_LIBS"
echo "BOOST_SRC:         $BOOST_SRC"
echo "PREFIXDIR:         $PREFIXDIR"
echo "XCODE_ROOT:        $XCODE_ROOT"
echo "COMPILER:          $COMPILER"



echo "Completed successfully"




  1. Cliffs

    Hi, thanks for the information. I have been trying to build boost.locale for iOS for a few days but still no luck. I’ve already built a universal libiconv for iOS and simulator, and added -sICONV_PATH to the bjam command, tried your script but still can’t find iconv while building for iOS devices.

    Performing configuration checks

    - 32-bit : no
    - 64-bit : no
    - arm : yes
    - symlinks supported : yes
    - iconv (libc) : no
    - iconv (separate) : no
    - icu : no
    - icu (lib64) : no
    - Boost.Locale needs either iconv or ICU library to be built.

    Any suggestion? Thanks in advance.

    • alex

      Have you changed the darwin.jam file as described in point 2. in the section “Detecting iconv”? The fact that your configuration detected something (e.g. “arm”) looks like the compiler stuff now works but it is simply a iconv link problem. Have a log at config.log and find the part where it tries to compile has_iconv.cpp and it will tell you exactly what is the problem (headers not found, symbols not, etc). Without the darwin.jam modification it will say something about missing architecture.

      P.S.: You shouldn’t be needing to build a custom iconv, there is an iconv.tbd (‘.tbd’ is a “.a” replacement by Apple) in the iOS platform SDK.

  2. SCaptain

    It doesn’t work for me too. Do you mean change the darwin.jam file which under the boostXXX/tools/build/src/tools ? I adjust it but it doesn’t work.

    You said 》 The path may very well get down to the compilation statement, but the test simply does not compile at all.

    So I try to modify the fount-iconv method in the location: boost_1_62_0/libs/locale/build

    Directly to modify the file “Jamfile.v2” on the line 229,
    set found-iconv variable always true, like:
    found-iconv = true ;

    It seems work for me.

    • alex

      Yes, that’s the darwin.jam I meant. I basically backtracked the problem: Following the detection mechanism I found the has_iconv.cpp and the exact command line boost tries to compile it with. Then I tried to compile it manually using that command line and then figured out what needs to be changed.

      I just tried it again and indeed it fails. My guess it’s due to updating XCode and/or MacOS in the meantime. I re-checked the config.log and now it complains about “-lcrt1.3.1.o ” missing which seems to be related to the deployment target, see here:

      Unfortunately I don’t have much time to look into it right now, hope that helps you to find out what the problem is!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>