Table of Contents
- Building BOINC Project Applications for Macintosh OS X
Building BOINC Project Applications for Macintosh OS X
Last updated 7/17/12
This document applies to BOINC libraries 7.0.32 and later. It has instructions for building science project applications to run under BOINC on Macintosh OSX. Information for building the BOINC Client and Manager for Macintosh OSX can be found here.
Contents of this document:
General Considerations
Building applications for Macintosh OS X is complicated by the fact that Mac OS X is actually 3 different platforms:
- powerpc-apple-darwin: PowerPC processors running OS 10.3.0 and above
- i686-apple-darwin: 32-bit intel processors running OS 10.4.0 and above
- x86_64-apple-darwin: 64-bit intel processors running OS 10.5.0 and above
BOINC no longer supports PowerPC applications for the Mac.
Of course, you can choose to support only some of these platforms. For example, you may not need a 64-bit version. If your project does not support the x86_64-apple-darwin platform, BOINC will automatically request your i686-apple-darwin application.
Starting with version 6.10.58, the BOINC Client supports only Mac OS X 10.4.0 and later. This allows it to be built with XCode 3.2 under OS 10.6.x and later.
The libraries supplied with different versions of OS X support different APIs. You need to take certain steps to ensure that you use only APIs that are available in all the OS versions you plan to support. There are two basic ways to accomplish this:
- Build each platform on a system running the oldest OS you need to support:
- An Intel development system running OS 10.4.x
- A 64-bit development Intel system running OS 10.5.x or later (The original Intel Macs used an Intel Core Duo processor which was 32-bit only. You must have an Intel Core 2 Duo or newer processor to run 64-bit applications.)
- Use a single development system running OS 10.7.x or later and cross-compile for the various platforms. The remainder of this document describes that process.
Note: This issue applies mainly to Mac-specific APIs; support for standard UNIX functions rarely changes over different Mac OS versions. However, the version numbers of some UNIX libraries do change over time, and applications which dynamically link to them may fail to load on older systems if they are built on a newer system. If this happens, the best solution is to build a static version of the UNIX library yourself and static link it to your application. Most UNIX libraries are open source, so you can get the source files and build them yourself. Many are available from http://opensource.apple.com/.
You will also need to build the BOINC libraries on each platform and any other libraries your application needs. You can use the Makefiles supplied in the BOINC source repository to build the BOINC libraries with this approach, or build them as Universal Binaries using the BOINC XCode project, as described later in this document.
Cross-Platform Development
Apple provides the tools necessary to cross-compile for both BOINC Mac platforms on any Mac running OS 10.7.x or OS 10.8.x. You get these tools, including the GCC compilers and system library header files, by installing the Xcode Tools package.
You can download Xcode 4.3 or Xcode 4.4 from Apple's App Store (it is large: about 2 GB). If you are a member of Apple's Mac Developer Program, you can also download it from Apple's web site: http://developer.apple.com. You can also register for free access to Apple developer tools at: https://developer.apple.com/programs/register/. See the section Installing and setting up Xcode for further information.
XCode will automatically check compatibility back to OS 10.4 if the following are defined during compilation:
MAC_OS_X_VERSION_MAX_ALLOWED=1040
MAC_OS_X_VERSION_MIN_REQUIRED=1040
The example_app found in boinc/samples has examples of 3 different ways to build the application for all 3 platforms using cross-development:
- Create an XCode project
- Use a generic Makefile with a custom shell script
- Use a custom Makefile
The basic requirements for building each platform are:
- Specify the architecture: i386 or x86_64
- Specify the compiler to use.
- Specify an appropriate SDK. It is OK to use the latest SDK even if building for older versions of OS X.
- Specify the Mac OSX Deployment Target, which is the minimum target OS X version on which you want your to application run.
- Add the definitions of MAC_OS_X_VERSION_MAX_ALLOWED and MAC_OS_X_VERSION_MIN_REQUIRED to the C or C++ compiler flags. This also specifies the minimum target OS X version. It tells the compiler to reject any attempts to use APIs not available in that version of OS X.
Important: set the value of MAC_OS_X_VERSION_MAX_ALLOWED to be the same as the value of MAC_OS_X_VERSION_MIN_REQUIRED. Possible values for the C compiler flags are:
-DMAC_OS_X_VERSION_MAX_ALLOWED=1040 -DMAC_OS_X_VERSION_MIN_REQUIRED=1040
-DMAC_OS_X_VERSION_MAX_ALLOWED=1050 -DMAC_OS_X_VERSION_MIN_REQUIRED=1050
These specify that the executable should be able to run on systems back to OS 10.4 and OS 10.5, respectively.
You can find examples in the following files in the BOINC sourcecode:
boinc/mac_build/buildc-ares.sh
boinc/mac_build/buildcurl.sh
boinc/mac_build/buildopenssl.sh
boinc/samples/example_app/MakeMacExample.sh
boinc/samples/example_app/Makefile_mac2
boinc/samples/example_app/Makefile_mac
boinc/samples/wrapper/Makefile_mac
boinc/samples/vboxwrapper/Makefile_mac
boinc/samples/vboxwrapper/BuildMacVboxWrapper.sh
boinc/samples/vboxwrapper/Makefile_mac
Preparing To Build
Create a parent directory within which to work. In this description , we will call it BOINC_dev, but you can name it anything you wish. This parent directory will contain the BOINC source files, your application project, and any other library projects you will use.
Source files are archived in the BOINC repository.
Get the BOINC source from the repository, and put it in the same BOINC_dev folder. To do this, type the following in Terminal:
cd {path}/BOINC_dev/
git clone git://boinc.berkeley.edu/boinc-v2.git boinc
(You may change the name of the boinc directory to anything you wish.) See more information on getting the BOINC source code.
Build the BOINC libraries as follows:
BOINC itself is built using the boinc.xcodeproj file. You can either build directly in XCode (more information below) or run the BuildMacBOINC.sh script. Note: this script requires OS 10.6 or later. Run the script as follows:
cd {path}/BOINC_dev/boinc/mac_build/
source BuildMacBOINC.sh -lib
The complete syntax for this script is
source BuildMacBOINC.sh [-dev] [-noclean] [-all] [-lib] [-client] [-help]
The options for BuildMacBOINC.sh are:
-dev
build the development (debug) version (native architecture only). Default is deployment (release) version (universal binary: i386 and x86_64); when you link your application with these libraries, the linker will automatically select the architecture matching your application.
-noclean
don't do a 'clean' of each target before building. default is to clean all first.
The following arguments determine which targets to build
-all
build all targets (i.e. target 'Build_All' -- this is the default)
-lib
build the five libraries: libboinc_api.a, libboinc_graphics_api.a, libboinc.a, libboinc_opencl.a, jpeglib.a.
-client
build two targets: BOINC client and command-line utility boinccmd (also builds libboinc.a, since boinc_cmd requires it.)
Both -lib and -client may be specified to build seven targets (no BOINC Manager.)
For more information on this script, please see here.
Note: You may find two XCode projects in the BOINC_dev/boinc/mac_build/ directory:
- wxMac-BOINC.xcodeproj was needed for building older versions of the wxMac library in conjunction with the older versions of the setupForBoinc.sh or buildWxMac.sh scripts. It is not used for BOINC 5.9.2 or later.
- boinc.xcodeproj builds BOINC. It can be used either with the BuildMacBOINC.sh script or as a stand-alone project. The Development build configuration builds only the native architecture and is used for debugging. The Deployment build configuration builds a universal binary and is suitable for release builds. If there are any other build configurations, they should not be used as they are obsolete.
Note: To perform a release build under Xcode 4.3 when not using the BuildMacBOINC.sh script, select "Build for archiving" from Xcode's "Product" menu; do not select "Archive." To generate the development build under Xcode 4.3, choose "Build" from the product menu, or enter command-B on the keyboard.
Build Any Other Needed Libraries
If you are building a third-party library, you will need to take the steps listed above in the section Cross-Platform Development. See the files listed above for examples of how to accomplish this.
Build Your Application Using Cross-Development
We will use the example_app to illustrate the 3 methods of cross-compiling.
Using an XCode Project
Double-click on the project file boinc/samples/mac_build/UpperCase2.xcodeproj. At the top of the main window, select Build_All for the scheme, then select "Build for Archiving" from the Build menu.) Note: Do not select "Archive" from the Build menu.
Use the example XCode project as a guide or a starting point to create an XCode project for your own application. Pay special attention to the XCode build settings.
Note: By default, Xcode puts built products in an obscure location. You can determine that location using Xcode's "Organizer" window. To avoid this issue, the UpperCase2.xcodeproj and vboxwrapper.xcodeproj each have a "Run script" build phase which copies the built applications (as well as the symbol tables for the release builds) to a local ./build/ directory.
For more information on using XCode, see Xcode 4 User Guide.
Also note that you can use the program xcodebuild to build XCode projects from the command-line (e.g. in a Terminal window or shell script). There are various flags for building particular builds within a project, and for overriding default variables as well (check man xcodebuild in a Terminal window for the options). You can find an examples of this approach in the files boinc/mac_build/BuildMacBOINC.sh and boinc/mac_build/buildWxMac.sh
Using a Generic Makefile With a Custom Shell Script
Type the following in Terminal:
cd {path}/BOINC_dev/boinc/samples/example_app/
sh MakeMacExample.sh -clean
Again, you can use this shell script as a guide or starting point to create one for your application. Let's examine the details:
If your application uses an autoconf file, you can set the various environment variables for configure directly. For examples, see the scripts buildc-ares.sh, buildcurl.sh and buildopenssl.sh in the directory {path}/BOINC_dev/boinc/mac_build/.
In this case, there is no autoconf file, so we had to modify the generic Makefile slightly; the shell script uses Makefile_mac. The most significant change was to add the variable VARIANTFLAGS to the list of arguments in CXXFLAGS. The remaining changes were to ensure that the search paths included the needed BOINC headers and libraries.
Here are the elements of our script:
GCCPATH=`xcrun -find gcc`
GPPPATH=`xcrun -find g++`
MAKEPATH=`xcrun -find make`
TOOLSPATH1=${MAKEPATH%/make}
ARPATH=`xcrun -find ar`
TOOLSPATH2=${ARPATH%/ar}
export PATH="${TOOLSPATH1}":"${TOOLSPATH2}":/usr/local/bin:$PATH
By default, the basic installation of Xcode 4.3 puts many of the command-line tools in unusual places. The above lines allow the Make file to find what it needs. Note: If you installed the full command-line tool set from Xcode (as described in the section Installing and setting up Xcode), then the standard tools will be in their normal locations and you may not need the above lines.
If you installed any additional command-line tools yourself, they may be in the '/usr/local/bin/' directory.
None of these examples require running _autosetup. If you are building other libraries or utilities that do have _autosetup , you may also need to install pkg-config.
SDKPATH=`xcodebuild -version -sdk macosx Path`
This gets the path to the current Mac OSX SDK, which contains the standard headers needed by most builds.
export CC="${GCCPATH}";export CXX="${GPPPATH}"
Specifies which compiler to use. (If you have installed the command-line tools in their standard locations, then this line could simply be export CC=gcc;export CXX=g++)
export LDFLAGS="-Wl,-syslibroot,${SDKPATH},-arch,i386"
Specifies the appropriate SDK to use and the architecture for the linker.
export VARIANTFLAGS="-isysroot ${SDKPATH} -arch i386 -DMAC_OS_X_VERSION_MAX_ALLOWED=1040 -DMAC_OS_X_VERSION_MIN_REQUIRED=1040 -fvisibility=hidden -fvisibility-inlines-hidden"
Specifies the SDK to use and the architecture for the compiler. MAC_OS_X_VERSION_MAX_ALLOWED and MAC_OS_X_VERSION_MIN_REQUIRED tell the compiler to generate an error if you are using any APIs not yet available in that version of the Mac OS.
export SDKROOT="${SDKPATH}"
Another way of specifying the SDK to use.
export MACOSX_DEPLOYMENT_TARGET=10.4
Specifies the Mac OSX Deployment Target, which is the minimum target OS X version on which you want your to application run. This sets certain symbol variants which determine the UNIX standard to be followed. For details, see this page. We recommend the following values for the MACOSX_DEPLOYMENT_TARGET:
- For 32-bit Intel builds: 10.4
- For 64-bit Intel builds: 10.5
Using a Custom Makefile
Type the following in Terminal:
cd {path}/BOINC_dev/boinc/samples/example_app/
make -f Makefile_mac2 clean all
Note: You must have installed the full command-line tool set from Xcode (as described in the section Installing and setting up Xcode) to use this method.
The elements of our custom Makefile correspond to those described in our script, except that no SDK need be specified. Installing the full command-line tool set from Xcode installs all headers either to their standard locations or to the frameworks at /System/Library/Frameworks, and the compilers default to use these headers and the standard libraries.
Upgrading applications for version 6 graphics
One of the major changes in BOINC for version 6 was that applications are now expected to generate graphics in a separate executable. The graphics application typically communicates with the worker application using shared memory.
For additional information, please see the Graphics API page.
Adding a Finder icon to your graphics application
There is an optional API setMacIcon() in the libboinc_api.a library. This allows science graphics applications to display an application icon in the Dock and in the Finder. (The icon does not appear in the Dock until the application displays graphics.) To implement this, do the following:
- Use the
Icon Composerapplication to create a xxx.icns file. (Use any name you wish instead of xxx.) To access this application, control-click on the Xcode icon in Finder and select "Show package contents" from the contextual menu. Then browse toContents/Applications/Icon Composer.app. - Convert the xxx.icns file to an app_icon.h file as follows: in Terminal, run:
{path}/MakeAppIcon_h {source_file_path}/xxx.icns {dest_file_path}/app_icon.h
(The MakeAppIcon_h command-line utility is built by the Mac boinc XCode project in the 'boinc/mac_build/build/' directory.) Add the app_icon.h file to your graphics application's project.
- In the graphics application's main(), add
#include "app_icon.h"
and call:
setMacIcon(argv[0], MacAppIconData, sizeof(MacAppIconData));
- The graphics application must link with Carbon.framework to use setMacIcon().
Installing and setting up Xcode
Versions of Xcode prior to Xcode 4.3 have an installer package. After downloading Xcode, mount the disk image file by double-clicking on it, then double-click the installer package.
Starting with Xcode 4.3, the disk image contains a copy of Xcode itself. After mounting the disk image, drag the Xcode icon to the folder where you wish it to reside. In most cases, this will be the /Applications/ folder. Unmount the disk image by dragging it to the trash. Finally, double-click on the installed Xcode icon to run Xcode. Xcode will display a dialog allowing you to finish the installation; you must do this before running BOINC's build scripts. (Some versions of Xcode may not display this dialog until you open a file with Xcode.)
Once you have done this, you will be able to build applications using Xcode projects and shell scripts as described earlier in this document. If you wish to be able to build directly using the UNIX tools configure and make, you must also install the full command-line tool set from Xcode as follows:
- Launch Xcode.
- Select "Preferences..." from the "Xcode" menu.
- Click on the "Downloads" icon at the top of the Preferences dialog.
- Click on the "Install" button next to "command-line tools."
You can find more details here.
Additional References
http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/
http://developer.apple.com/legacy/mac/library/#documentation/MacOSX/Conceptual/universal_binary