| 14 | | [[PageOutline(1-10,,inline)]] |
| 15 | | |
| 16 | | == Important requirements for building BOINC software for the Mac == |
| 17 | | |
| 18 | | Building BOINC for Macintosh OS X is complicated by the fact that Mac OS X is actually 2 different platforms: |
| 19 | | * '''i686-apple-darwin''': 32-bit Intel processors running OS 10.4.0 and above |
| 20 | | * '''x86_64-apple-darwin''': 64-bit Intel processors running OS 10.5.0 and above |
| 21 | | As of version 6.13.0, BOINC does not support Macintosh PowerPC processors. |
| 22 | | |
| 23 | | Although BOINC supports 64-bit Intel project applications on Mac OS 10.5.0 and above, the only parts of the BOINC client package built as 64-bit executables are the portion of the screensaver coordinator for OS 10.6.x and later, and the BOINC client itself. The BOINC libraries also include a 64-bit build so that they can be linked with 64-bit project applications. |
| 24 | | |
| 25 | | 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.8.x or later and cross-compile for the various platforms. The remainder of this document describes that process. |
| 26 | | |
| 27 | | '''The above requirements apply not only to BOINC itself, but also to the !WxWidgets, c-ares, cURL, openSSL, freetype, ftgl and SQLite3 libraries, as well as all project applications.''' |
| 28 | | |
| 29 | | Be sure to follow the directions in this document to ensure that these requirements are met. |
| 30 | | |
| 31 | | Starting with version 7.3.0, the BOINC Client supports only Mac OS X 10.5.0 and later. |
| 32 | | |
| 33 | | |
| 34 | | == Cross-Platform Development == |
| 35 | | |
| 36 | | Apple provides the tools necessary to cross-compile for both BOINC Mac platforms on any Mac running OS 10.8.x or later. |
| 37 | | |
| 38 | | You get these tools, including the GCC compilers and system library header files, by installing the XCode Tools package. |
| 39 | | |
| 40 | | '''Building BOINC now requires Xcode Tools version 4.6 or later.''' Build with Xcode 5.1.1 or earlier to fully support OS X back to OS 10.5. Xcode 6 or later will build a screensaver which requires OS 10.6 or later, but all other built components will work with OS 10.5 or later. |
| 41 | | |
| 42 | | You can download Xcode 4.6 or later from Apple's App Store (it is large: about 2 GB). If you are a member of Apple's Mac Developer Program, you can also download it from Apple's web site: http://developer.apple.com. |
| 43 | | |
| 44 | | Source files are now archived within the [SourceCodeGit BOINC repository]. |
| 45 | | |
| 46 | | == Building BOINC Manager with embedded BOINC Client == |
| 47 | | |
| 48 | | Note: building BOINC Manager 7.3.0 and later requires the OS 10.8 SDK or later. |
| 49 | | |
| 50 | | BOINC depends on seven third-party libraries: wxWidgets-3.0.0, c-ares-1.10.0, curl-7.39.0, openssl-1.0.1j, freetype-2.4.10, ftgl-2.1.3~rc5 and sqlite-3.8.3. You can obtain the source files from the following URLs. Clicking on the first URL of each pair will download the tar file. The second URL will open the third party’s home web page. On Mac OS X the tar file will usually be downloaded into the Downloads folder. You will need to expand the tar files by double-clicking on them, which will create a folder and place the appropriate files into that folder. You will need to move these folders later. |
| 51 | | |
| 52 | | wxWidgets-3.0.0 (needed only if you are building the BOINC Manager): |
| 53 | | |
| 54 | | [http://sourceforge.net/projects/wxwindows/files/3.0.0/wxWidgets-3.0.0.tar.bz2/] |
| 55 | | [http://www.wxwidgets.org] |
| 56 | | |
| 57 | | sqlite-3.8.3 (needed only if you are building the BOINC Manager): |
| 58 | | |
| 59 | | [http://www.sqlite.org/2014/sqlite-autoconf-3080300.tar.gz] |
| 60 | | [http://www.sqlite.org/] |
| 61 | | |
| 62 | | curl-7.39.0: |
| 63 | | |
| 64 | | [http://curl.haxx.se/download/curl-7.39.0.tar.gz] |
| 65 | | [http://curl.haxx.se] |
| 66 | | |
| 67 | | c-ares-1.10.0 (used by curl): |
| 68 | | |
| 69 | | [http://c-ares.haxx.se/download/c-ares-1.10.0.tar.gz] |
| 70 | | [http://daniel.haxx.se/projects/c-ares/] |
| 71 | | |
| 72 | | openssl-1.0.1j: |
| 73 | | |
| 74 | | [http://www.openssl.org/source/openssl-1.0.1j.tar.gz] |
| 75 | | [http://www.openssl.org/] |
| 76 | | |
| 77 | | freetype-2.4.10 (needed only if you are building the BOINC default screensaver or a project screensaver): |
| 78 | | |
| 79 | | [http://sourceforge.net/projects/freetype/files/freetype2/2.4.10/freetype-2.4.10.tar.bz2] |
| 80 | | [http://www.freetype.org/] |
| 81 | | |
| 82 | | ftgl-2.1.3~rc5 (needed only if you are building the BOINC default screensaver or a project screensaver): |
| 83 | | |
| 84 | | [http://sourceforge.net/projects/ftgl/files/FTGL%20Source/2.1.3%7Erc5/ftgl-2.1.3-rc5.tar.gz] |
| 85 | | [http://sourceforge.net/projects/ftgl] |
| 86 | | |
| 87 | | XCode will automatically check compatibility back to OS 10.5 if the following are defined during compilation: |
| 88 | | {{{ |
| 89 | | MAC_OS_X_VERSION_MAX_ALLOWED=1050 |
| 90 | | MAC_OS_X_VERSION_MIN_REQUIRED=1050 |
| 91 | | }}} |
| 92 | | These are not done automatically by either the Xcode projects which come with wxWidgets-3.0.0, nor the !AutoMake scripts supplied with wxWidgets-3.0.0, c-ares-1.10.0, curl-7.39.0, openssl-1.0.1j, freetype-2.4.10, ftgl-2.1.3~rc5 and sqlite-3.8.3. So be sure to use our special scripts to build these packages. |
| 93 | | |
| 94 | | 1. Make sure you are logged into the Mac using an account with administrator privileges. 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. |
| 95 | | |
| 96 | | 2. Move the following 7 directories from the Downloads folder into the BOINC_dev folder (omit any you don't need): |
| 97 | | {{{ |
| 98 | | c-ares-1.10.0 |
| 99 | | curl-7.39.0 |
| 100 | | openssl-1.0.1j |
| 101 | | wxWidgets-3.0.0 |
| 102 | | freetype-2.4.10 |
| 103 | | ftgl-2.1.3~rc5 |
| 104 | | sqlite-3.8.3 |
| 105 | | }}} |
| 106 | | Important: do not change the names of any of these 6 directories. |
| 107 | | |
| 108 | | 3. If you have not yet done so, install Xcode and launch it once to accept the license agreement and complete the installation. |
| 109 | | |
| 110 | | 4. Get the BOINC source tree from the repository, and put it in the same BOINC_dev folder. To do this, type the following in Terminal: |
| 111 | | {{{ |
| 112 | | cd {path}/BOINC_dev/ |
| 113 | | git clone http://boinc.berkeley.edu/git/boinc-v2.git boinc |
| 114 | | }}} |
| 115 | | (You may change the name of the `boinc` directory to anything you wish.) |
| 116 | | |
| 117 | | If the above method does not work try the following alternate method: |
| 118 | | {{{ |
| 119 | | git clone git://boinc.berkeley.edu/boinc-v2.git boinc |
| 120 | | }}} |
| 121 | | |
| 122 | | |
| 123 | | The command above retrieves the source code from the HEAD / MASTER (TRUNK) or development branch of the git repository. See more information on [SourceCodeGit getting the BOINC source code]. |
| 124 | | |
| 125 | | 5. Run the script to build the c-ares, curl, openssl, wxWidgets, freetype, ftgl and sqlite3 libraries as follows: |
| 126 | | {{{ |
| 127 | | cd {path}/BOINC_dev/boinc/mac_build/ |
| 128 | | source setupForBoinc.sh -clean |
| 129 | | }}} |
| 130 | | If you don't wish to force a full rebuild of everything, omit the -clean argument. |
| 131 | | |
| 132 | | '''Note 1:''' Be sure to run the script using the `source` command. Do not double-click on the scripts or use the `sh` command to run them. |
| 133 | | |
| 134 | | '''Note 2:''' This script tries to build all seven third-party libraries: wxWidgets-3.0.0, c-ares-1.10.0, curl-7.39.0, openssl-1.0.1j, freetype-2.4.10, ftgl-2.1.3~rc5 and sqlite-3.8.3. When the script finishes, it will display a warning about any libraries it was unable to build (for example, if you have not downloaded them.) To make it easier to find the error messages, clear the Terminal display and run the script again without -clean. |
| 135 | | |
| 136 | | '''Note 3:''' The {path} must not contain any space characters. |
| 137 | | |
| 138 | | '''Hint:''' You don't need to type the path to a file or folder into Terminal; just drag the file or folder icon from a Finder window onto the Terminal window. |
| 139 | | |
| 140 | | '''Note 4:''' To be compatible with OS 10.6 and OS 10.7 (in addition to later versions of OS X), the screensaver must be built with Garbage Collection supported (and without Automatic Reference Counting) and so must be built using Xcode 5.x or earlier. If you build with Xcode 6 or later, Xcode will force a conversion to ARC, and the screensaver will still work with OS 10.8 or later. |
| 141 | | |
| 142 | | 6. Build BOINC as follows: |
| 143 | | |
| 144 | | 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: |
| 145 | | |
| 146 | | {{{ |
| 147 | | cd {path}/BOINC_dev/boinc/mac_build/ |
| 148 | | source BuildMacBOINC.sh |
| 149 | | }}} |
| 150 | | |
| 151 | | The complete syntax for this script is |
| 152 | | |
| 153 | | {{{ |
| 154 | | source BuildMacBOINC.sh [-dev] [-noclean] [-all] [-lib] [-client] [-help] |
| 155 | | }}} |
| 156 | | |
| 157 | | The options for BuildMacBOINC.sh are: |
| 158 | | |
| 159 | | -dev:: |
| 160 | | build the development (debug) build (native architecture only). Default is deployment (release) build (universal binary: i386 and x86_64). |
| 161 | | -noclean:: |
| 162 | | don't do a 'clean' of each target before building. Default is to clean all first. |
| 163 | | |
| 164 | | The following arguments determine which targets to build |
| 165 | | |
| 166 | | -all:: |
| 167 | | build all targets (i.e. target 'Build_All' -- this is the default) |
| 168 | | -lib:: |
| 169 | | build the six libraries: libboinc_api.a, libboinc_graphics_api.a, libboinc.a, libboinc_opencl.a, libboinc_zip.a, jpeglib.a |
| 170 | | -client:: |
| 171 | | build two targets: BOINC client and command-line utility [http://boinc.berkeley.edu/wiki/Boinccmd_tool boinccmd] (also builds libboinc.a, since boinc_cmd requires it.) |
| 172 | | |
| 173 | | Both -lib and -client may be specified to build eight targets (no BOINC Manager or screensaver.) |
| 174 | | |
| 175 | | '''Note 1: boinc.xcodeproj''' in the `BOINC_dev/boinc/mac_build/` directory 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. |
| 176 | | |
| 177 | | '''Note 2:''' To perform a release build under Xcode 4.6 when not using the BuildMacBOINC.sh script, select "Build for archiving" or "Build for Profiling" from Xcode's Product menu. Under Xcode 5.0 or later, select "Build for Profiling." To save disk space, do '''not''' select "Archive." |
| 178 | | |
| 179 | | '''Note 3:'''Using the BuildMacBOINC.sh script is generally easier than building directly in Xcode. The script will place the built products in the directory `BOINC_dev/boinc/mac_build/build/Deployment/` or `BOINC_dev/boinc/mac_build/build/Development/` where they are easy to find. Building directly in Xcode places the built products in a somewhat obscure location; you would normally need to determine this location using Xcode's Organizer window. |
| 180 | | |
| 181 | | '''Hint:''' You can install multiple versions of Xcode on the same Mac, either by putting them in different directories or by renaming Xcode.app of different versions. You can then specify which version the BuildMacBOINC.sh script should use by setting the `DEVELOPER_DIR` environment variable using the `env` command. For example, if you have installed Xcode 5.0.2 in the Applications directory and renamed `Xcode.app` to `Xcode_5_0_2.app`, you can invoke the script with: |
| 182 | | {{{ |
| 183 | | env DEVELOPER_DIR=/Applications/Xcode_5_0_2.app/Contents/Developer sh BuildMacBOINC.sh |
| 184 | | }}} |
| 185 | | |
| 186 | | The BOINC Xcode project has built-in scripts which create a text file with the path to the built products at either `BOINC_dev/boinc/mac_build/Build_Deployment_Dir` or `BOINC_dev/boinc/mac_build/Build_Development_Dir`. These files are used by the release_boinc.sh script, but you can also use them to access the built products directly as follows; open the file with !TextEdit and copy the path, then enter command-shift-G in the Finder and paste the path into the Finder's dialog. |
| 187 | | |
| 188 | | The standard release of BOINC version 7.4.42and later builds only for Macintosh computers with Intel processors. Most of the executables are built only for the i386 architecture, except the BOINC client which is built only for the x86_64 architecture. The BOINC libraries and the screensaver are built as universal binaries containing builds for two architectures: i386 and x86_64. |
| 189 | | |
| 190 | | |
| 191 | | == Building BOINC Manager Installer == |
| 192 | | |
| 193 | | In order to execute BOINC Manager, you must install it using BOINC Manager Installer. Otherwise, you will encounter an error prompting for proper installation. |
| 194 | | |
| 195 | | 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: |
| 196 | | |
| 197 | | {{{ |
| 198 | | cd {path}/BOINC_dev/boinc/ |
| 199 | | source {path}/BOINC_dev/boinc/mac_installer/release_boinc.sh x y z |
| 200 | | }}} |
| 201 | | |
| 202 | | 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 7.4.42, the command would be |
| 203 | | |
| 204 | | {{{ |
| 205 | | source {path}/BOINC_dev/boinc/mac_installer/release_boinc.sh 7 4 42 |
| 206 | | }}} |
| 207 | | |
| 208 | | This will create a directory `BOINC_Installer/New_Release_7_4_42` in the `BOINC_dev` directory, and the installer will be located in `{path}/BOINC_dev/BOINC_Installer/New_Release_7_4_42/boinc_7.4.42_macOSX_x86_64`. |
| 209 | | |
| 210 | | The installer script uses the deployment (release) build of BOINC; it won't work with a development (debug) build. |
| 211 | | |
| 212 | | You can find the current version number in the file {path}/BOINC_dev/boinc/version.h |
| 213 | | |
| 214 | | == Code Signing the BOINC Manager Installer and Uninstaller == |
| 215 | | |
| 216 | | Mac OS 10.8 introduces a security feature called Gatekeeper, whose default settings won't allow a user to run applications or installers downloaded from the Internet unless they are signed by a registered Apple Developer. The `release_boinc.sh` script looks for a file `~/BOINCCodeSignIdentity.txt` containing the name of a valid code signing identity stored in the user's Keychain. If this is found, the script will automatically sign the BOINC installer and BOINC uninstaller using that identity. For example, if your user name is John Smith, the first line of `~/BOINCCodeSignIdentity.txt` would be something like the following: |
| 217 | | {{{ |
| 218 | | Developer ID Application: John Smith |
| 219 | | }}} |
| 220 | | |
| 221 | | If there is no `~/BOINCCodeSignIdentity.txt` file, then the script will not sign the installer or uninstaller. Code signing is not necessary if you won't be transferring the built software over the Internet. For more information on code signing identities see the documentation for the [https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/codesign.1.html `codesign`] utility and Apple's [https://developer.apple.com/library/mac/documentation/Security/Conceptual/CodeSigningGuide/ Code Signing Guide]. |
| 222 | | |
| 223 | | |
| 224 | | == Debugging and BOINC security == |
| 225 | | |
| 226 | | Version 5.5.4 of BOINC Manager for the Macintosh introduced new, stricter security measures. For details, please see the file `BOINC_dev/boinc/mac_installer/Readme.rtf` and web pages [//sandbox.php Sandbox Design] and [SandboxUser Sandbox User]. |
| 227 | | |
| 228 | | 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. |
| 229 | | |
| 230 | | 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 generate the development build under Xcode 4.6, choose "Build" from the product menu, or enter command-B on the keyboard.) |
| 231 | | |
| 232 | | To restore the standard ownerships and permissions, run the installer. |
| 233 | | |
| 234 | | For information on interpreting crash dumps and backtraces, see [MacBacktrace Mac Backtrace]. |
| 235 | | |
| 236 | | |
| 237 | | == Debugging into wxWidgets == |
| 238 | | |
| 239 | | 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. |
| 240 | | |
| 241 | | You can find instructions for doing this in the comments in the file `BOINC_dev/boinc/clientgui/mac/MacGUI.pch`. |
| 242 | | |
| 243 | | |
| 244 | | == Installing and setting up Xcode == |
| 245 | | |
| 246 | | If Xcode is obtained from the Apple Store then it will be installed automatically into the Applications folder. Double-click on the installed Xcode icon to run Xcode. Xcode will display a dialog allowing you to finish the installation; you must do this before running BOINC's build scripts. (Some versions of Xcode may not display this dialog until you open a file with Xcode.) |
