<pclass="p4">This document has instructions for building BOINC for Macintosh OSX, plus information for building science projects to run under BOINC Macintosh OSX.</p>
<pclass="p2"><br></p>
<pclass="p1"><b>Building BOINC Manager with embedded Core Client plus libraries libboinc.a and libboinc_graphics_api.a</b></p>
<pclass="p4">Substitute the appropriate path for [boincparent] throughout this document.<spanclass="Apple-converted-space"></span>This is the parent directory containing the boinc/ tree.<spanclass="Apple-converted-space"></span>If used, the following three directories must also be at the top level of [boincparent]/:</p>
<pclass="p4">wxMac-2.6.1/, curl-7.14.0 and jpeg-6b.<spanclass="Apple-converted-space"></span>If you wish to keep these directories elsewhere or to give them different names, you can create a UNIX symbolic link to the actual directory using the command, for example:<spanclass="Apple-converted-space"></span></p>
<pclass="p4">These directions are for building under OS X version 10.4.x (Tiger) using XCode Developer Tools version 2.0, or OS X version 10.3.9 (Panther) using XCode 1.5. <spanclass="Apple-converted-space"></span></p>
<pclass="p2"><br></p>
<pclass="p4">If you are building under OS 10.4, you must first install XCode's optional Cross-Development SDK for system 10.3.9 from the XCode Tools CD.<spanclass="Apple-converted-space"></span>This guarantees that all builds are backward compatible to OS 10.3.9.<spanclass="Apple-converted-space"></span>This is not necessary for building under OS 10.3.</p>
<pclass="p4">If you are building with XCode 2.0 under OS 10.4, the default compiler is GCC 4.0.<spanclass="Apple-converted-space"></span>Software compiled with GCC 4.0 cannot run on systems earlier than OS 10.3.9.<spanclass="Apple-converted-space"></span>To ensure compatibility back to OS 10.3.0, <b>all</b> BOINC software <b>must</b> be compiled using GCC version 3.3, <b>including the WxWidgets and cURL libraries</b>.</p>
<pclass="p2"><br></p>
<pclass="p4">Beware of using the wrong compiler!<spanclass="Apple-converted-space"></span>Apple's release notes for GCC 4.0 say:</p>
<pclass="p4"><i>If your application must support versions of Mac OS X prior to 10.3.9, you must not use the GCC 4.0 compiler. Instead, build your project using the GCC 3.3 compiler</i></p>
<pclass="p2"><br></p>
<pclass="p4">Elsewhere on Apple's web site is the warning:</p>
<pclass="p4"><i>Do not link C++ modules compiled with one of these compilers against modules compiled with the other. Even if the modules appear to link correctly, C++ ABI differences may still cause problems that will not manifest themselves until run time.</i></p>
<pclass="p4">The BOINC XCode project is already set up to use GCC 3.3.<spanclass="Apple-converted-space"></span>For builds from the command-line under OS 10.4, you must set the environment variables CC and CXX.<spanclass="Apple-converted-space"></span>For the bash shell:</p>
<pclass="p4">To make sure that other XCode projects (such as client science applications) use GCC 3.0, do the following:</p>
<pclass="p2"><br></p>
<pclass="p4">In the XCode project, select your target under the Groups & Files column.<spanclass="Apple-converted-space"></span>Press command-I to open the info window for the target, and select the "Rules" tab.<spanclass="Apple-converted-space"></span>Press the "+" at the bottom of the window twice to create two new rules.<spanclass="Apple-converted-space"></span>Set one rule for C sources to use GCC 3.3, set the other rule for C++ sources to use GCC 3.3.<spanclass="Apple-converted-space"></span>Close the window.<spanclass="Apple-converted-space"></span>Repeat this for each target in the project.</p>
<pclass="p2"><br></p>
<pclass="p4">If you are building under OS 10.3.9, the default compiler is GCC 3.3, so these steps are not necessary (but they won't do any harm).</p>
<pclass="p4">If you are building a science project to run under BOINC Macintosh OSX, be sure to read the last section of this document, titled "Building the BOINC SETI client application."</p>
<pclass="p4">This section describes building two libraries needed by BOINC: wxWidgets for the Macintosh, wxMac-2.6.1, and curl-7.14.0. <spanclass="Apple-converted-space"></span></p>
<pclass="p4"><i>XCode 1.5 installs autoconf version 2.57 and automake 1.63.<spanclass="Apple-converted-space"></span>XCode 2.0 installs autoconf 2.59 and automake 1.63.</i><spanclass="Apple-converted-space"></span><i>To determine the version number, type "autoconf --version" or "automake --version" .<spanclass="Apple-converted-space"></span>Building wxMac-2.6.1 and curl-7.14.0 require autoconf 2.59 and automake 1.93 or later.<spanclass="Apple-converted-space"></span>Building the BOINC SETI application also requires these.</i></p>
<pclass="p4"><i>Upgrades for autoconf and automake are available from www.gnu.org.<spanclass="Apple-converted-space"></span>XCode installed these utilities in the /usr/bin/ directory, but the upgrades by default will install in /usr/local/bin/.<spanclass="Apple-converted-space"></span>If you install there, you must also set your PATH environment variable to include that location before proceeding with any of the steps below; type the following at the start of your terminal session:</i></p>
<pclass="p4">The wxWidgets library is needed only by the BOINC Manager.<spanclass="Apple-converted-space"></span>If you are not building the BOINC Manager, you can skip ahead to step 2 below.</p>
<pclass="p4">You will need to set the environment variables CPPFLAGS and LDFLAGS as described below.<spanclass="Apple-converted-space"></span>These commands are for the bash shell; use the equivalent commands if you are running a different UNIX shell.<spanclass="Apple-converted-space"></span>Some of these environment variables allow the application to be built using the OS 10.3.9 compatibility SDK.</p>
<pclass="p7"><br></p>
<pclass="p4">First set the CPPFlags environment variable. If you are building under OS 10.4:</p>
<pclass="p4">(2) The cURL library is needed only by the BOINC Core Client.<spanclass="Apple-converted-space"></span>If you are not building either the BOINC Manager or the Core Client, you can skip ahead to step 3 below (The BOINC Manager includes the Core Client in its application bundle).</p>
<pclass="p4">Download curl-7.14.0 from http://curl.haxx.se/download.html into your [boincparent] directory. <spanclass="Apple-converted-space"></span></p>
<pclass="p2"><br></p>
<pclass="p4">Open a new terminal window to reset your session environment variables and set the working directory:</p>
<pclass="p4">If you are building under OS 10.4, set the CPPFlags and LDFlags environment variables <b>after</b> the configure but <b>before</b> the make:</p>
<pclass="p4">This will create the static library at [boincparent]/curl-7.14.0/lib/.libs/libcurl.a.<spanclass="Apple-converted-space"></span>The Finder hides file and directory names which begin with a period, so you must use the Terminal tool to see or manipulate this file.</p>
<pclass="p4">(3) Building the BOINC graphics library libboinc_graphics.a uses jpeglib.h.<spanclass="Apple-converted-space"></span>If you aren't building this library, you can skip this step.</p>
<pclass="p4">Download jpeg-6b from www.ijg.org into your [boincparent] directory.<spanclass="Apple-converted-space"></span>You don't need to configure or build this library; BOINC only uses the jpeglib.h header file, and expects it to be at the path [boincparent]/ jpeg-6b/jpeglib.h.</p>
<pclass="p3"><b>Building the BOINC Manager with embedded Core Client, plus<spanclass="Apple-converted-space"></span></b></p>
<pclass="p3"><b>BOINC libraries, screensaver and helper applications</b></p>
<pclass="p2"><br></p>
<pclass="p4">(1) Double-click on [boincpath]/mac_build/boinc.pbproj to launch the XCode development IDE with the BOINC project.</p>
<pclass="p2"><br></p>
<pclass="p4">(2) Select the appropriate cross-development sdk as follows:</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- select the boinc project icon at the top of the Groups & Files column</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- press command-i to open the Project "boinc" info window.</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- In the "General" tab, set the popup menu "Cross-Develop Using Target SDK." <spanclass="Apple-converted-space"></span>For OS 10.4, select "MacOSX10.3.9.sdk"; for OS 10.3 select "current Mac OS".</p>
<pclass="p2"><br></p>
<pclass="p4">(3) In the Active Target popup, select mgr_boinc or Build_All.<spanclass="Apple-converted-space"></span>Build_All also builds the three libraries libboinc_api.a, libboinc_graphics_api.a and libboinc.a, which are used to build science applications such as SETI@home.<spanclass="Apple-converted-space"></span>These libraries are not needed by the BOINC Manager or Core Client.<spanclass="Apple-converted-space"></span>In addition, Build_All builds the screensaver BOINCSaver.saver and the installer helper application Postinstall.app.</p>
<pclass="p4">(4) In the Active Build Style popup, choose Development (for debugging) or Deployment (for release builds.)</p>
<pclass="p2"><br></p>
<pclass="p4">(5) If you have switched Build Style, be sure to do a "Clean All Targets" from the Build menu; otherwise object files from the old build style will not be rebuilt in the new build style.</p>
<pclass="p2"><br></p>
<pclass="p4">(6) If you are building the screensaver, be sure to unstuff the file:<spanclass="Apple-converted-space"></span></p>
<pclass="p4">(7) Select Build from the Build menu.<spanclass="Apple-converted-space"></span>I suggest you also open the Detailed Build Results window from the Build menu.<spanclass="Apple-converted-space"></span>Wait a long<spanclass="Apple-converted-space"></span>time while it compiles.</p>
<pclass="p2"><br></p>
<pclass="p4">(8) In addition to the BOINC Manager BOINC.app and Core Client boinc, the mgr_boinc target will also build the SystemMenu.bundle framework and a small helper utility SetVersion. <spanclass="Apple-converted-space"></span></p>
<pclass="p2"><br></p>
<pclass="p4">(9) SetVersion is run automatically as part of the build process to update the following Mac version information files using the contents of version.h:</p>
<pclass="p4">(10) The boinc-client, SystemMenu.bundle and InfoPlist.strings will all be embedded automatically inside the BOINC.app application bundle as part of the build process.</p>
<pclass="p2"><br></p>
<pclass="p4">(11) If you wish to run the Core Client under the debugger, you will need to set up the command-line arguments.<spanclass="Apple-converted-space"></span>In the Groups & Files column of the XCode project window, select "BOINC_Client" under Executables.<spanclass="Apple-converted-space"></span>Then click on the round blue "info" button at the top of the project window to open the info window.<spanclass="Apple-converted-space"></span>In the info window's Arguments tab, add the following line to the Argument list:</p>
<pclass="p4">Normally, stdio and stderr output will be sent to XCode's console.<spanclass="Apple-converted-space"></span>If you want stdio and stderr to be redirected to files as BOINC normally does, add a second line to the Argument list:</p>
<pclass="p4">After creating the <b>deployment</b> build of all targets using Build_All, do the following in Terminal.<spanclass="Apple-converted-space"></span>Set the current directory to the root directory of the boinc tree:</p>
<pclass="p4">Invoke the release_boinc.sh script with the three parts of version number as arguments.<spanclass="Apple-converted-space"></span>For example, if the version is 3.2.1:</p>
<pclass="p4">(This will create a director "BOINC_Installer" in the parent directory of the current directory.<spanclass="Apple-converted-space"></span>Inside that will be three directories and two zip files. <spanclass="Apple-converted-space"></span></p>
<pclass="p4">If the version is 3.2.1, the zip files will be boinc_3.2.1_macOSX.zip and boinc_3.2.1_powerpc-apple-darwin.zip, and the directories will have the same names as their zipped counterparts.<spanclass="Apple-converted-space"></span></p>
<pclass="p4">An additional directory named SymbolTables contains the executables with full debugging symbols; these are useful when interpreting stack dumps in error reports.</p>
<pclass="p4"><i>Please see the discussion about versions<spanclass="Apple-converted-space"></span>of autconf and automake in the section "ONE_TIME SETUP for BOINC Manager and embedded Core Client" above.<spanclass="Apple-converted-space"></span>If you install upgrades for these in /usr/local/bin/, type the following at the start of your terminal session:</i></p>
<pclass="p4">(2) You will need to set some environment variables as described below.<spanclass="Apple-converted-space"></span>These commands are for the bash shell; use the equivalent commands if you are running a different UNIX shell. <spanclass="Apple-converted-space"></span></p>
<pclass="p4">There is an optional api setMacIcon() in the libboinc_api.a library.<spanclass="Apple-converted-space"></span>This allows science applications to display an application icon in the Dock) and in the Finder. <spanclass="Apple-converted-space"></span>(The icon does not appear in the Dock until the application displays graphics.)<spanclass="Apple-converted-space"></span>To implement this, do the following:</p>
<pclass="p4">(1)Use "/Developer/Applications/utilities/Icon Composer.app" to create a xxx.icns file.<spanclass="Apple-converted-space"></span>(Use any name you wish instead of xxx.)</p>
<pclass="p2"><br></p>
<pclass="p4">(2) Convert the xxx.icns file to an app_icon.h file as follows: in Terminal, run:<spanclass="Apple-converted-space"></span></p>
<pclass="p4">(The MakeAppIcon_h command-line utility is built by the Mac boinc XCode project iin the "boinc/mac_build/build/" directory.)<spanclass="Apple-converted-space"></span>Add the app_icon.h file to your science application's project.</p>
<pclass="p2"><br></p>
<pclass="p4">(3) In the science application's main(), add<spanclass="Apple-converted-space"></span></p>
