wiki:BuildMacApp

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

--

  1. Building BOINC Project Applications for Macintosh OS X
    1. General Considerations
    2. Cross-Platform Development
    3. Preparing To Build
    4. Build Any Other Needed Libraries
    5. Build Your Application Using Cross-Development
      1. Using an XCode Project
      2. Using a Generic Makefile With a Custom Shell Script
      3. Using a Custom Makefile
    6. Upgrading applications for version 6 graphics
    7. Adding a Finder icon to your graphics application
    8. Additional References

Building BOINC Project Applications for Macintosh OS X

Last updated 10/11/10

This document applies to BOINC libraries 6.11.9 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:

  1. Building BOINC Project Applications for Macintosh OS X
    1. General Considerations
    2. Cross-Platform Development
    3. Preparing To Build
    4. Build Any Other Needed Libraries
    5. Build Your Application Using Cross-Development
      1. Using an XCode Project
      2. Using a Generic Makefile With a Custom Shell Script
      3. Using a Custom Makefile
    6. Upgrading applications for version 6 graphics
    7. Adding a Finder icon to your graphics application
    8. Additional References

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 does not support 64-bit 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. And / or you may choose not to support the powerpc-apple-darwin platform.

Although BOINC version 6.1.0 supports only Mac OS X 10.3.9 and later, earlier versions supported all versions back to OS 10.3.0. The GCC compiler version 4.0 was introduced in OS 10.3.9. OS 10.3.0 through 10.3.8 can't run applications built with GCC 4.0. Also, 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.

You have 2 choices if you want to support PowerPC (G3, G4 and G5) processors:

  • Build your PowerPC application with GCC 4.0 and distribute it only to Macs running 10.3.9 (or 10.4.0) or later.
  • Build your PowerPC application with GCC 3.3.

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:
    • A PowerPC development system running OS 10.3.0 through 10.3.8 (or 10.3.9 or 10.4.0 if you won't support the older systems)
    • 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.5.x or later and cross-compile for the various platforms. The remainder of this document describes that process.

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 Subversion tree 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 all three BOINC Mac platform on any Mac running OS 10.5.x. If you don't need to support the x86_64-apple-darwin platform, you can also cross-compile on OS 10.4.x.

Apple provides Software Developer Kits (SDKs) for OS 10.3.9, OS 10.4, OS 10.5 and OS 10.6. These include all the header files and stub libraries appropriate to the corresponding versions of OS X. However, the OS 10.3.9 cannot be used with XCode 3.2 under OS 10.6.

You get these tools, including the GCC compilers and system library header files, by installing the XCode Tools package. We recommend running OS 10.6.x and installing XCode Tools 3.2 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

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

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 installer.

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: ppc, i386 or x86_64
  • Specify the compiler to use (we recommend GCC-4.0).
  • 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=1030 -DMAC_OS_X_VERSION_MIN_REQUIRED=1030
-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.3, OS 10.4 and OS 10.5, respectively.

You can find examples in the following files in the BOINC SVN trunk:
boinc/mac_build/buildc-ares.sh
boinc/mac_build/buildcurl.sh
boinc/mac_build/buildjpeg.sh
boinc/samples/example_app/MakeMacExample.sh
boinc/samples/example_app/Makefile_mac2
boinc/samples/example_app/Makefile_mac
boinc/samples/wrapper/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 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. One place to get it is: ​http://www.codingmonkeys.de/mbo/.

If you are running OS X 10.6 and XCode 3.2, a recent version of Subversion is already installed 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

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 or development branch of the SVN repository. 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 XCode 3.2 running under OS 10.6.x. 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 binaries containing three architectures: ppc, 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 three libraries: libboinc_api.a, libboinc_graphics_api.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.)

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.

The standard release of BOINC version 6.1.0 and later contains a universal binary of the BOINC libraries containing builds for three architectures: ppc, i386 and x86_64.

Build Any Other Needed Libraries

If you are building a third-party library (such as JPEG), 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 Active Target, and ppc_Deployment for the Active Build Configuration. Then click on the Build icon (or select Build from the Build menu.) Repeat for Active Build Configurations i386_Deployment and x86_64_Deployment.

Note: you may see the following warning when building the PowerPC executable. You may safely ignore it: 

ld: warning: object file compiled with -mlong-branch which is no longer needed. 
To remove this warning, recompile without -mlong-branch

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. For more information on using XCode, see ​XCode Workspace 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 example of this approach in the file 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 buildjpeg.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 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: 

export PATH=/usr/local/bin:$PATH

XCode 2.4.1 installs autoconf 2.59 and automake 1.6.3. XCode 3.x installs autoconf 2.61 and automake 1.10. To determine the version number, type autoconf --version or automake --version. If you installed a later version of either or both, they will be in the '/usr/local/bin/' directory. This line ensures that the system will look there first.

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. 

export CC=/usr/bin/gcc-4.0;export CXX=/usr/bin/g++-4.0

Specifies which compiler to use. 

export MACOSX_DEPLOYMENT_TARGET=10.3

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 PowerPC builds: 10.3
  • For 32-bit Intel builds: 10.4
  • For 64-bit Intel builds: 10.5 
export LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk,-arch,ppc"

Specifies the appropriate SDK to use and the architecture for the linker. 

export VARIANTFLAGS="-arch ppc -DMAC_OS_X_VERSION_MAX_ALLOWED=1030 -DMAC_OS_X_VERSION_MIN_REQUIRED=1030 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -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.

We recommend the following values for the SDK:

  • For PowerPC builds: MacOSX10.4u.sdk
  • For 32-bit Intel builds: MacOSX10.4u.sdk
  • For 64-bit Intel builds: MacOSX10.5.sdk

Using a Custom Makefile

Type the following in Terminal: 

cd {path}/BOINC_dev/boinc/samples/example_app/
make -f Makefile_mac2 clean all

The elements of our custom Makefile correspond to those described in our script.

Upgrading applications for version 6 graphics

One of the major changes in BOINC for version 6 is 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 '/Developer/Applications?/utilities/Icon Composer.app' to create a xxx.icns file. (Use any name you wish instead of xxx.)
  • 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().

Additional References

​http://developer.apple.com/technotes/tn2005/tn2137.html
​http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/
​http://developer.apple.com/releasenotes/DeveloperTools/RN-GCC4/
​http://developer.apple.com/library/mac/#documentation/Porting/Conceptual/PortingUnix/intro/intro.html
​http://developer.apple.com/legacy/mac/library/#documentation/MacOSX/Conceptual/universal_binary
​http://developer.apple.com/releasenotes/DeveloperTools/GCC40PortingReleaseNotes/index.html