<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">NOTE: Substitute the appropriate path for [wxpath] and [boincpath] throughout this document.<spanclass="Apple-converted-space"></span>Typically, [boincpath] will end in "/boinc" or /boinc_public", and [wxpath] will end in "/wxMac-2.6.1".</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="p5"><br></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, all BOINC software <b>must</b> be compiled using GCC version 3.3. <spanclass="Apple-converted-space"></span></p>
<pclass="p2"><br></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 the wxWidgets library for the Macintosh, wxMac-2.6.1.<spanclass="Apple-converted-space"></span>This 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 (5) below.</p>
<pclass="p2"><br></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 requires 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">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="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="p2"><br></p>
<pclass="p6">-redirectio</p>
<pclass="p2"><br></p>
<pclass="p4">These arguments will be used only when running the BOINC Core Client from XCode using XCode's Run or Debug commands.</p>
<pclass="p2"><br></p>
<pclass="p2"><br></p>
<pclass="p3"><b>Building the installer</b></p>
<pclass="p2"><br></p>
<pclass="p4">After creating the <b>deployment</b> build of all targets using Build_All, use the Finder to do the following:</p>
<pclass="p4">(1) In a convenient place on disk, create a directory "Installer_Resources".<spanclass="Apple-converted-space"></span>Copy the following items into this directory:</p>
<pclass="p4">NOTE: the file extensions (such as .app and .saver) may be hidden by the Finder.<spanclass="Apple-converted-space"></span>You can check an item's extension by selecting it in the Finder and using Get Info function from the Finder's File menu.</p>
<pclass="p2"><br></p>
<pclass="p4">(2) Create another directory "Pkg_Root", and inside that create two more directories "Applications" and"Library".<spanclass="Apple-converted-space"></span>Create:</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- a "Screen Savers" directory inside your new Library directory,</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- an "Application Support" directory inside your new Library directory,</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- a "BOINC Data" directory inside your new Application Support directory,</p>
<pclass="p4"><spanclass="Apple-converted-space"></span>- a "locale" directory inside your new BOINC Data directory <spanclass="Apple-converted-space"></span></p>
<pclass="p4">Correct spelling of these names is critical.</p>
<pclass="p2"><br></p>
<pclass="p4">(3) Copy [boincpath]/mac_build/build/BOINCManager.app into your<spanclass="Apple-converted-space"></span></p>
<pclass="p4">(5) Copy the <b>contents</b><b>of</b> boincpath]/locale/client/ into your<spanclass="Apple-converted-space"></span></p>
<pclass="p4">"Pkg_Root/Library/Application Support/BOINC Data/locale" directory.<spanclass="Apple-converted-space"></span>(You may optionally exclude the CVS subdirectories to save space.)</p>
<pclass="p2"><br></p>
<pclass="p4">You will now have the following directory structure:</p>
<pclass="p4">(6) From the Finder, open [boincpath]/mac_installer/BOINC.pmproj (if running OS 10.3, use BOINC.pmsp).<spanclass="Apple-converted-space"></span>it will open in the PackageMaker application.<spanclass="Apple-converted-space"></span>In the Files tab, set the path to your Pkg_Root directory.<spanclass="Apple-converted-space"></span>in the Resources tab, set the path to your Installer_Resources directory. <spanclass="Apple-converted-space"></span>Update the<spanclass="Apple-converted-space"></span>version number in multiple places in the Description and Version tabs.</p>
<pclass="p2"><br></p>
<pclass="p4">(7) Select "Create Package" from PackageMaker's File menu.<spanclass="Apple-converted-space"></span>You can give any name you wish to the installer package when you create it, but do <b>not</b> change the package name <b>after</b> it is created.</p>
<pclass="p2"><br></p>
<pclass="p4">(8) Quit PackageMaker.</p>
<pclass="p2"><br></p>
<pclass="p3"><b>Package BOINC installer for distribution</b></p>
<pclass="p2"><br></p>
<pclass="p4">(1) Create a directory and name it appropriately, e.g. "boinc_4.37_macOSX".<spanclass="Apple-converted-space"></span>Copy the installer package and the ReadMe file into the directory.</p>
<pclass="p2"><br></p>
<pclass="p4">(2)After selecting the directory you just created and populated, select <spanclass="s1">Create archive</span> from the Finder's File menu.<spanclass="Apple-converted-space"></span>This will zip the file.<spanclass="Apple-converted-space"></span>(Note: if you want to stuff the file instead of zipping it, be sure to uncheck "stuff originals instead of aliases" in DropStuff's preferences.)</p>
<pclass="p2"><br></p>
<pclass="p4">(3) Rename the zip file as appropriate to show the version number; for example, boinc_4.37_macOSX<spanclass="s2">.zip</span><spanclass="Apple-converted-space"></span></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="p8"><br></p>
<pclass="p6">export PROJECTDIR=[setipath]</p>
<pclass="p8"><br></p>
<pclass="p6">export BOINCDIR=[boincpath]</p>
<pclass="p2"><br></p>
<pclass="p4">If your autoconf and automake are in /usr/local/bin/:</p>
<pclass="p2"><br></p>
<pclass="p6">export PATH=/usr/local/bin:$PATH</p>
<pclass="p2"><br></p>
<pclass="p4">(2) Run Configure to create the correct config.h file:</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>
