Changes between Version 8 and Version 9 of MacBuild


Ignore:
Timestamp:
Jul 21, 2007, 10:57:53 AM (17 years ago)
Author:
Nicolas
Comment:

Lots of cleanup; fixed typos, formatting, added some links...

Legend:

Unmodified
Added
Removed
Modified

  • MacBuild

    v8 v9  
    11= Building BOINC Clients and Applications on Macintosh OS X =
    2 === Last updated 7/21/07 ===
    3        
     2'''Last updated 7/21/07'''
     3
    44This document applies to BOINC version 5.10.14 and later. It has instructions for building BOINC for Macintosh OS X, plus information for building science project applications to run under BOINC on Macintosh OS X.
    55
    … …  
    1212Contents of this document:
    1313
    14     * Important requirements for building BOINC software for the Mac.
    15     * Building BOINC libraries to link with project applications.
    16     * Building BOINC Manager, BOINC Client and BOINC libraries.
    17     * Building BOINC Manager Installer.
    18     * Debugging and BOINC security.
    19     * Building project applications.
    20     * Upgrading applications for Macs with Intel processors.
    21     * Adding a Finder icon to your application
     14[[PageOutline(1-9,,inline)]]
    2215
    2316== Important requirements for building BOINC software for the Mac ==
    2417
    25 All BOINC software for Power PC Macs must be built using GCC 3.3 and MacOS10.3.9 SDK to assure backward compatibility with OS 10.3. All BOINC software for Intel Macs must be built using GCC 4.0 and MacOS10.4.u SDK to allow cross-compiling. '''This includes not only BOINC itself, but also the !WxWidgets, JPEG and cURL libraries, as well as all project applications.'''
     18All BOINC software for Power PC Macs must be built using GCC 3.3 and MacOS10.3.9 SDK to assure backward compatibility with OS 10.3. All BOINC software for Intel Macs must be built using GCC 4.0 and MacOS 10.4.u SDK to allow cross-compiling. '''This includes not only BOINC itself, but also the !WxWidgets, JPEG and cURL libraries, as well as all project applications.'''
    2619
    2720Beware of using the wrong compiler! Apple's release notes for GCC 4.0 say:
    … …  
    4336== Building BOINC libraries to link with project applications ==
    4437
    45 If you are building a project application to be run by BOINC, you only need to build the boinc libraries libboinc_api.a, ibboinc.a, and (if you want graphics) libboinc_graphics_api.a. There are two ways to do this:
     38If you are building a project application to be run by BOINC, you only need to build the BOINC libraries `libboinc_api.a`, `libboinc.a`, and (if you want graphics) `libboinc_graphics_api.a`. There are two ways to do this:
    4639
    4740  1. Use the BOINC autoconf / automake scripts to build these libraries and the jpeg and curl libraries on which they depend. You must do all of this twice: once on a PowerPC Mac running OS 10.3.x (do NOT use OS 10.4), and once on an Intel Mac running OS 10.4.x.
    … …  
    5649== Building BOINC Manager with embedded Core Client plus libraries libboinc.a and libboinc_graphics_api.a ==
    5750
    58 BOINC depends on three third-party libraries: wxMac-2.8.0, curl-7.16.4, and jpeg-6b.  (We have reverted to using wxMac-2.8.0 because we have found several bugs in later versions of wxMac.) You can obtain these from the following URLs:
     51BOINC depends on three third-party libraries: wxMac-2.8.0, curl-7.16.4, and jpeg-6b. (We have reverted to using wxMac-2.8.0 because we have found several bugs in later versions of wxMac.) You can obtain these from the following URLs:
    5952
    6053wxMac-2.8.0 (needed only if you are building the BOINC Manager):
    … …  
    8679http://ftp.gnu.org/gnu/automake/automake-1.9.3.tar.gz
    8780
    88 ''XCode installed these utilities in the /usr/bin/ directory, but the upgrades by default will install in /usr/local/bin/. If you install there, you must also set your PATH environment variable to include that location. The scripts referenced below do this automatically.''
     81''XCode installed these utilities in the `/usr/bin/` directory, but the upgrades by default will install in `/usr/local/bin/`. If you install there, you must also set your PATH environment variable to include that location. The scripts referenced below do this automatically.''
    8982
    9083As stated above, all BOINC software for Power PC Macs must be built using GCC 3.3 and MacOS10.3.9 SDK to assure backward compatibility with OS 10.3. All BOINC software for Intel Macs must be built using GCC 4.0 and MacOS10.4.u SDK to allow cross-compiling.
    … …  
    9891
    9992{{{
    100       curl-7.16.4
    101       jpeg-6b
    102       wxMac-2.8.0
     93curl-7.16.4
     94jpeg-6b
     95wxMac-2.8.0
    10396}}}
    10497
    … …  
    107100
    108101{{{
    109       cd {path}/BOINC_dev/
    110       svn co http://boinc.berkeley.edu/svn/trunk/boinc
     102cd {path}/BOINC_dev/
     103svn co http://boinc.berkeley.edu/svn/trunk/boinc
    111104}}}
    112105
    … …  
    117110
    118111{{{
    119       cd {path}/BOINC_dev/boinc/mac_build/
    120       source setupForBoinc.sh -clean
     112cd {path}/BOINC_dev/boinc/mac_build/
     113source setupForBoinc.sh -clean
    121114}}}
    122115
    … …  
    127120
    128121{{{
    129       cd {path}/BOINC_dev/boinc/mac_build/
    130       source BuildMacBOINC.sh
     122cd {path}/BOINC_dev/boinc/mac_build/
     123source BuildMacBOINC.sh
    131124}}}
    132125
    … …  
    134127
    135128{{{
    136       source BuildMacBOINC.sh [-dev] [-noclean] [-all] [-lib] [-client]
     129source BuildMacBOINC.sh [-dev] [-noclean] [-all] [-lib] [-client]
    137130}}}
    138131
    139132      The options for BuildMacBOINC.sh are:
    140133
    141       -dev
     134      -dev::
    142135          build the development (debug) version (native architecture only). default is deployment (release) version (universal binaries: ppc and i386).
    143       -noclean
     136      -noclean::
    144137          don't do a 'clean' of each target before building. default is to clean all first.
    145138
    146139      The following arguments determine which targets to build
    147140
    148       -all
     141      -all::
    149142          build all targets (i.e. target 'Build_All' -- this is the default)
    150       -lib
     143      -lib::
    151144          build the three libraries: libboinc_api.a, libboinc_graphics_api.a, libboinc.a
    152       -client
    153           build two targets: boinc client and command-line utility boinc_cmd (also builds libboinc.a, since boinc_cmd requires it.)
     145      -client::
     146          build two targets: BOINC client and command-line utility [BoincCmd boinc_cmd] (also builds libboinc.a, since boinc_cmd requires it.)
    154147
    155148      Both -lib and -client may be specified to build five targets (no BOINC Manager.)
    … …  
    189182== Debugging and BOINC security ==
    190183
    191 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 [http://boinc.berkeley.edu/sandbox.php Sandbox Design] and [SandboxUser Sandbox User].
    192 
    193 The GDB debugger can't attach to applications which are running as a diferent user or group so it ignores the S_ISUID and S_ISGID permisison bits when launching an application. To work around this, BOINC does not use the special boinc_master or boinc_project users or groups when run from XCode.
     184Version 5.5.4 of BOINC Manager for the Macintosh introduced new, stricter security measures. For details, please see the file [source:trunk/boinc/mac_installer/Readme.rtf Readme.rtf] and web pages [http://boinc.berkeley.edu/sandbox.php Sandbox Design] and [SandboxUser Sandbox User].
     185
     186The 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, BOINC does not use the special boinc_master or boinc_project users or groups when run from XCode.
    194187
    195188The 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.
    … …  
    203196Apple began shipping Macs with Intel processors on January 10, and Apple expects to convert all its lines of computers to Intel by the end of 2006.
    204197
    205 All future releases of BOINC will include 'universal binary' builds for the Macintosh of BOINC Manager, command-line BOINC client and the boinc_cmd command-line tool. (Universal binaries contain both PowerPC and Intel executables in one file; the Macintosh OS automatically selects the appropriate one for that computer.)
     198All future releases of BOINC will include 'universal binary' builds for the Macintosh of BOINC Manager, command-line BOINC client and the [BoincCmd boinc_cmd] command-line tool. (Universal binaries contain both PowerPC and Intel executables in one file; the Macintosh OS automatically selects the appropriate one for that computer.)
    206199
    207200The advantage of 'universal binaries' is that you only need to have one copy of the application, and it will run on either PowerPC or Intel Macs, so users don't need to choose between two options. Since BOINC participants manually download BOINC from the web site, we will be providing BOINC in 'universal binary' form.
    … …  
    209202However, participants do not manually download project applications; this is done automatically by BOINC. So there would be no advantage to combining the Intel and PowerPC versions in a single 'universal binary' file, but doing so would double the size of the download.
    210203
    211 So BOINC treats Intel Macs as a new, separate platform. BOINC previously directly supported four platforms: PowerPC Macs (powerpc-apple-darwin), Intel Linux (i686-pc-linux-gnu), Windows (windows-intelx86) and Solaris (sparc-sun-solaris2.7).
     204So BOINC treats Intel Macs as a new, separate platform. BOINC previously directly supported four platforms: PowerPC Macs (`powerpc-apple-darwin`), Intel Linux (`i686-pc-linux-gnu`), Windows (`windows_intelx86`) and Solaris (`sparc-sun-solaris2.7`).
    212205
    213206'''We have now added a fifth platform for Intel Macs (i686-apple-darwin).'''
    214207
    215 As a '''temporary''' measure, projects can set their servers to deliver a copy of their current PowerPC application (renamed for the new platform) under the new i686-apple-darwin platform. The OS will run it in compatibility mode, emulating a PowerPC. (Apple calls this compatibility mode Rosetta, which of course has nothing to do with the Rosetta BOINC project.)
     208As a '''temporary''' measure, projects can set their servers to deliver a copy of their current PowerPC application (renamed for the new platform) under the new `i686-apple-darwin platform`. The OS will run it in compatibility mode, emulating a PowerPC. (Apple calls this compatibility mode "Rosetta", which of course has nothing to do with the Rosetta BOINC project.)
    216209
    217210If you do this, be sure to give your native Intel application a higher version number when you do release it, so that clients will download it.
    … …  
    220213
    221214    * Screensaver graphics do not work.
    222     * Since it is running under emulation, your application will run at reduced efficiency. But the benchmarks are based on running native Intel applications. This may cause scheduler problems, such as uncompleted deadlines and inadequate credit for participants.
    223 
    224 So it is important to make a native Intel application available as soon as possible.
    225 
    226 It is very easy to add a new platform to your server with the xadd utility. For directions on how to do this, see these web pages:
    227 [BoincPlatforms Boinc Platforms] and [XaddTool Xadd Tool]
     215    * Since it is running under emulation, your application will run at reduced efficiency. But the benchmarks are based on running native Intel applications. This may cause scheduler problems, such as uncompleted deadlines and inadequate credit for participants.
     216
     217So it is important to make a native Intel application available as soon as possible. It is very easy to add a new [BoincPlatforms platform] to your server with the [XaddTool xadd utility].
    228218
    229219BOINC supports all PowerPC Macs running OS 10.3.0 or later, and all Intel Macs. (The Intel Macs themselves require OS 10.4.4 or later.)
    230220
    231 The easiest way to build your application for these two platforms is to build each one on its native platform. In other words, do your powerpc-apple-darwin build on a PowerPC Mac running OS 10.3.9, and your i686-apple-darwin build on an Intel Mac.
     221The easiest way to build your application for these two platforms is to build each one on its native platform. In other words, do your `powerpc-apple-darwin` build on a PowerPC Mac running OS 10.3.9, and your i686-apple-darwin build on an Intel Mac.
    232222
    233223But Apple provides the tools to allow you to cross-compile your application on any Mac (PowerPC or Intel) running OS 10.4 or later. Here is how:
    234224
    235 All BOINC software for Power PC Macs must be built using GCC 3.3 and MacOS10.3.9 SDK to assure backward compatibility with OS 10.3. If building a PowerPC application on an Intel Mac, you must also specify '-arch ppc' in the compiler and linker flags.
    236 
    237 All BOINC software for Intel Macs must be built using GCC 4.0 and MacOS10.4.u SDK to allow cross-compiling. If building an Intel application on a PowerPC Mac, you must also specify '-arch i386' in the compiler and linker flags.
    238 
    239 You can find examples of how to do this for two different kinds of configure / make scripts in the HEAD branch of the BOINC SVN tree at boinc/mac_build/buildcurl.sh and boinc/mac_build/buildjpeg.sh.
    240 
    241 The lipo utility is used at the end of each of these scripts to combine the two binaries into a single 'Universal Binary' file. You won't need to do that with you project applications, since you will be distributing them separately under the two platforms. But if you prefer, you can create a Universal Binary and distribute the same file for both i686-apple-darwin and powerpc-apple-darwin platforms.
     225All BOINC software for Power PC Macs must be built using GCC 3.3 and MacOS 10.3.9 SDK to assure backward compatibility with OS 10.3. If building a PowerPC application on an Intel Mac, you must also specify '-arch ppc' in the compiler and linker flags.
     226
     227All BOINC software for Intel Macs must be built using GCC 4.0 and MacOS 10.4.u SDK to allow cross-compiling. If building an Intel application on a PowerPC Mac, you must also specify '-arch i386' in the compiler and linker flags.
     228
     229You can find examples of how to do this for two different kinds of configure / make scripts in the HEAD branch of the BOINC SVN tree at [source:trunk/boinc/mac_build/buildcurl.sh boinc/mac_build/buildcurl.sh] and [source:trunk/boinc/mac_build/buildjpeg.sh boinc/mac_build/buildjpeg.sh].
     230
     231The lipo utility is used at the end of each of these scripts to combine the two binaries into a single 'Universal Binary' file. You won't need to do that with you project applications, since you will be distributing them separately under the two platforms. But if you prefer, you can create a Universal Binary and distribute the same file for both `i686-apple-darwin` and `powerpc-apple-darwin` platforms.
    242232
    243233Note that the BOINC libraries (and any third-party libraries) which you link with your applications must be built with the same configuration as the application itself. Follow the instructions earlier in this document to build the needed libraries.
    … …  
    254244=== Adding a Finder icon to your application ===
    255245
    256 There is an optional api setMacIcon() in the libboinc_api.a library. This allows science 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:
     246There is an optional API `setMacIcon()` in the `libboinc_api.a` library. This allows science 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:
    257247
    258248    * Use '/Developer/Applications/utilities/Icon Composer.app' to create a xxx.icns file. (Use any name you wish instead of xxx.)
    … …  
    260250
    261251{{{
    262       {path}/MakeAppIcon_h {source_file_path}/xxx.icns {dest_file_path}/app_icon.h
     252{path}/MakeAppIcon_h {source_file_path}/xxx.icns {dest_file_path}/app_icon.h
    263253}}}
    264254
    … …  
    267257
    268258{{{
    269       #include "app_icon.h"
     259#include "app_icon.h"
    270260}}}
    271261
    … …  
    273263
    274264{{{
    275       setMacIcon(argv[0], MacAppIconData, sizeof(MacAppIconData));
     265setMacIcon(argv[0], MacAppIconData, sizeof(MacAppIconData));
    276266}}}
    277267    * The science application must link with Carbon.framework to use setMacIcon().