wiki:MacBuild

Version 65 (modified by charlief, 14 years ago) (diff)

--

Building BOINC Client and Manager on Macintosh OS X

Last updated 10/7/10

This document applies to BOINC version 6.11.9 and later. It has instructions for building the BOINC Client and Manager for Macintosh OS X. For information on building science project applications to run under BOINC on Macintosh OSX, see BuildMacApp.

Note: the information in this document changes from time to time for different versions of BOINC. For any version of BOINC source files, the corresponding version of this document can be found in the source tree at:

boinc/mac_build/HowToBuildBOINC_XCode.rtf

Contents of this document:

  1. Building BOINC Client and Manager on Macintosh OS X
    1. Important requirements for building BOINC software for the Mac
    2. Cross-Platform Development
    3. Building BOINC Manager with embedded Core Client
    4. Building BOINC Manager Installer
    5. Debugging and BOINC security
    6. Debugging into wxWidgets

Important requirements for building BOINC software for the Mac

Building BOINC 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 does not support 64-bit PowerPC applications for the Mac.

Although BOINC supports 64-bit Intel project applications on Mac OS 10.5.0 and above, the only part of the BOINC client package built as a 64-bit executable is the screensaver coordinator for OS 10.6.x. The BOINC libraries also include a 64-bit build so that they can be linked with 64-bit project applications.

You need to take certain steps to ensure that you use only APIs that are available in all the OS versions BOINC supports for each architecture. The best way to accomplish this is to use a single development system running OS 10.6.x and cross-compile for the various platforms. The remainder of this document describes that process.

The above requirements apply not only BOINC itself, but also the WxWidgets, JPEG, c-ares and cURL libraries, as well as all project applications. Only theJPEG library must be built for the x86_64 architecture, since it is used by the libboinc_graphics_api library.

Be sure to follow the directions in this document to ensure that these requirements are met.

Starting with version 6.1.0, the BOINC Client supports only Mac OS X 10.3.9 and later; support for OS 10.3.0 through 10.3.8 has been discontinued. This allows us to build the BOINC Client and Manager using only GCC 4.0, which offers a number of advantages.

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, which does not support the Mac OS 10.3.9 SDK.

Cross-Platform Development

Apple provides the tools necessary to cross-compile for all three BOINC Mac platform on any Mac running OS 10.6.x.

You get these tools, including the GCC compilers and system library header files, by installing the XCode Tools package. Building BOINC and the library packages on which it depends requires XCode 3.2 or later running under OS 10.6.x or later. If you have the OS 10.6 installation DVD for your system, you can install XCode Tools at the time you install the OS, or you can install it later by opening the file Optional Installs/XCode Tools/XCodeTools.mpkg.

Otherwise, you can download it from Apple's web site (it is large: 1.1 GB). You must be a member of the Apple Developer Connection to download the software, but you can join for free at: http://connect.apple.com

Building BOINC now requires XCode Tools version 3.2 or later. Note that the MacOS10.4u SDK is not automatically included unless you customize the installation; click the Customize button in the Installation type step when you run the XCode Tools installe. The MacOS10.4u SDK is required to build wxWidgets (wxMac-2.8.10).

Source files are now archived using Subversion. You can download svnX, a free GUI application for running Subversion from either http://www.apple.com/downloads/macosx/development_tools/svnx.html or http://www.lachoseinteractive.net/en/community/subversion/svnx/.

You also need to install Subversion itself in the /usr/local/bin/ directory. By default, OS X and XCode install it in /usr/bin/. To copy it into /usr/local/bin/, enter the following in the Terminal utility application:

cd /usr/bin
sudo cp -p svn* /usr/local/bin

Enter your administrator password when prompted to do so.

Building BOINC Manager with embedded Core Client

BOINC depends on four third-party libraries: wxMac-2.8.10, c-ares-1.6.0, curl-7.19.4, and jpeg-6b. You can obtain these from the following URLs:

wxMac-2.8.10 (needed only if you are building the BOINC Manager):

http://www.wxwidgets.org

http://prdownloads.sourceforge.net/wxwindows/wxMac-2.8.10.tar.gz

http://downloads.sourceforge.net/wxwindows/wxMac-2.8.10.tar.bz2

curl-7.19.4:

http://curl.haxx.se

http://curl.haxx.se/download/curl-7.19.4.tar.gz

c-ares-1.6.0 (used by curl):

http://daniel.haxx.se/projects/c-ares/

http://daniel.haxx.se/projects/c-ares/c-ares-1.6.0.tar.gz

jpeg-6b (needed only if you are building the BOINC libboinc_graphics2.a library):

http://www.ijg.org

http://dir.filewatcher.com/d/GNU/Other/jpegsrc.v6b.tar.gz.613261.html

XCode will automatically check compatibility back to OS 10.3 if the following are defined during compilation:

MAC_OS_X_VERSION_MAX_ALLOWED=1030
MAC_OS_X_VERSION_MIN_REQUIRED=1030

These are not done by either the XCode projects which come with wxMac-2.8.10, nor the AutoMake scripts supplied with wxMac-2.8.10, c-ares-1.6.0, curl-7.19.4, or jpeg-6b. So be sure to use our special scripts to build these packages.

  1. 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.
  2. Put the following 3 directories inside the BOINC_dev folder (omit any you don't need):
    c-ares-1.6.0
    curl-7.19.4
    jpeg-6b
    wxMac-2.8.10
    
    Important: do not change the names of any of these 3 directories.
  3. Get the BOINC source tree from SVN, and put it in the same BOINC_dev folder. To do this, type the following in Terminal:
    cd {path}/BOINC_dev/
    svn co http://boinc.berkeley.edu/svn/trunk/boinc
    
    (You may change the name of the boinc directory to anything you wish.) Hint: if you have trouble getting this to work, try using https instead of http.

The command above retrieves the source code from the HEAD (TRUNK) or development branch of the SVN repository. See more information on getting the BOINC source code?.

  1. Run the script to build the c-ares, curl, jpeg and wxMac libraries as follows:
    cd {path}/BOINC_dev/boinc/mac_build/
    source setupForBoinc.sh -clean
    
    If you don't wish to force a full rebuild of everything, omit the -clean argument.

Note: this script builds c-ares and curl first, followed by jpeg and finally wxMac. If you haven't downloaded wxMac because you aren't building the BOINC Manager, the script will build c-ares, curl and jpeg. Likewise, if you downloaded only c-ares and curl because you need neither graphics nor the BOINC Manager, the script will build c-ares and curl before quitting.

  1. Build BOINC 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:

cd {path}/BOINC_dev/boinc/mac_build/
source BuildMacBOINC.sh

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 binaries: ppc, i386 and x86_64).
-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 three libraries: libboinc_api.a, libboinc_graphics2.a, libboinc.a
-client
build two targets: BOINC client and command-line utility boinc_cmd? (also builds libboinc.a, since boinc_cmd requires it.)

Both -lib and -client may be specified to build five targets (no BOINC Manager.)

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.

The standard release of BOINC version 6.10.58 and later contains a universal binary of the BOINC Client containing builds for two architectures: ppc and i386. The Mac OS automatically chooses the appropriate architecture as follows:

  • On a PowerPC Mac, it runs the ppc executable.
  • On an Intel Mac, it runs the i386 executable.

Building BOINC Manager Installer

In order to execute BOINC Manager, you have to install it using BOINC Manager Installer. Otherwise, you will encounter an error prompting for improper installation.

To build the Installer for the BOINC Manager, you must be logged in as an administrator. If you are building BOINC version number x.y.z, type the following in Terminal, then enter your administrator password when prompted by the script:

cd {path}/BOINC_dev/boinc/
source {path}/BOINC_dev/boinc/mac_installer/release_boinc.sh x y z

Substitute the 3 parts of the BOINC version number for x y and z in the above. For example, to build the installer for BOINC version 5.5.4, the command would be

source {path}/BOINC_dev/boinc/mac_installer/release_boinc.sh 5 5 4

This will create a directory 'BOINC_Installer/New_Release_5_5_4' in the BOINC_dev directory.

The installer is located in 'BOINC_Installer/New_Release_x_y_z/boinc_x.y.z_macOSX_universal'.

Debugging and BOINC security

Version 5.5.4 of BOINC Manager for the Macintosh introduced new, stricter security measures. For details, please see the file boinc/mac_installer/Readme.rtf and web pages Sandbox Design and Sandbox User.

The GDB debugger can't attach to applications which are running as a different user or group so it ignores the S_ISUID and S_ISGID permission bits when launching an application. To work around this, the BOINC Development build does not use the special boinc_master or boinc_project users or groups, and so can be run under the debugger from XCode.

The Development build only of the BOINC Manager allows you to change the ownership and permission settings of the BOINC Data and executables by entering an administrator user name and password. This also streamlines the development cycle by avoiding the need to run the installer for every change.

To restore the standard ownerships and permissions, run the installer.

For information on interpreting crash dumps and backtraces, see Mac Backtrace.

Debugging into wxWidgets

The BOINC XCode project normally links the BOINC Manager with the non-debugging (Deployment) build of wxWidgets, even for the Development build configuration of the Manager. However, there may be times when you wish to link the Development build of the Manager to the Development build of wxWidgets for debugging, as when you want to step into internal wxWidgets code or put breakpoints in wxWidgets.

You can find instructions for doing this in the comments in the file boinc/clientgui/mac/MacGUI.pch.