Creating an Apple Disk Image to Distribute BOINCHere is how to create an Apple Disk Image for distributing BOINC to users of Mac OS X, and how to add it to your BOINC project.
The instructions given here allow you to create an Apple Disk Image (.dmg file) containing a "Personal" BOINC distribution and an installation script to automatically add BOINC to a user's account.
Last modified: 9 April 2010
- First, create a prototype folder called BOINC containing the executable file compiled for MacOS X, along with a few other supporting files. This folder will be copied to the user's Library folder to become their working folder for BOINC. The current test of the installer uses the following files:The particular files used may change, but the idea is to collect all the files into one folder and then copy that to the user's account as their working directory for BOINC.
- The executable file for the core client. I've used 4.19 for testing but newer versions can be used, and other supporting files included with it as needed. Strip the executable to make it smaller, and note the file size for Step 2 below.
- When this file is opened with Terminal.app it will open a shell window and then run the shell command run-boinc.sh to start BOINC. Double click on this file to start BOINC by hand, or add this file to the Startup Items for your account to run BOINC whenever you log in. (The installer script can do both of these for you.)
- Shell script used by Run_BOINC.term to run the BOINC executable, collecting output logs in the files boinc.log and error.log in the BOINC folder.
- Shell script to stop any running boinc executable. In future the start and stop scripts may be merged into one standard start/stop script that can also be used for a "daemon" installation.
Note that you can associate a particular icon image with a file as follows: Select the file in the Finder and pull down File --> Get Info. Open the icon image file you wish to use (eg. in Preview) and copy the icon image to the clipboard (highlight the image and then Edit --> Copy). Then highlight the icon position in the file info pane and select Edit --> Paste. To delete an icon highlight the existing icon and press the Delete key.
- The prototype BOINC folder and the installation script, and possibly other files or folders, are all packed up on a Disk Image, a virtual volume which can be mounted on the Desktop. Create and mount a new Disk Image using the Disk Utility program, as follows:
- Run Disk Utility (Applications --> Utitlities --> Disk Utility)
- Press "New Image" and specify the following information:
- Image name ("Save As"): Install_BOINC
At least for now this name is required because that is what the installation script looks for. A smarter installation script may be able to figure out it's own name, but not right now.
- Location for the .dmg file ("Where"): wherever you want it, it doesn't really matter.
- Size: pull down to "Custom" and enter a size in MB. As an example, with the stripped core client of size 0.54MB a size of 1.0MB worked well. do not strip the executable you will need at least 7.0MB! Remember, the larger the image is the harder it is for users to download. You cannot change the size of the volume later, so pick a size that is just large enough to contain the files to be delivered, and not much more. But if you make it too small you won't be able to add things to it and you will have to start over.
- Encryption: none (or your users won't be able to read it)
- Format: read/write disk image (for now)
The disk image will show up on the desktop as a mounted volume, while the image file (.dmg file) will show up in the folder you specified under "Where:". You can then exit Disk Utility.
- Open the disk image on the desktop and drag to it the prototype BOINC folder created above.
- Open the installation script (for example, Install_BOINC.applescript) with Script Editor (Applications-->AppleScript --> Script Editor) and press the "Compile" button. Then select "Save As..." and save to top level folder of the mounted Install_BIONC volume. Save with the name Install_BOINC.app in file format "Application", not as text, and check the "run only" box.
- Add the background image to the top level folder of the disk image as follows:
The background image will be displayed in the "icon" view, which should be the default when the disk image is opened up (if you save the folder that way!) but not always. If a user has checked the Finder preference "Default to list view" then that is what is shown instead. Oh well...
- First, drag the background image you wish to use to the open folder for the volume. An example is Install_BOINC.jpg. You must include the image with the volume or it won't be available when the user mounts the volume on their own machine.
- With the top level folder active in the Finder pull down View --> Show View Options. At the top, select the button "this window only". At the bottom, in the "set background" area, press the "picture" button and select the background image you just put on the volume.
Move the BOINC folder and installation script to wherever you want them to appear when the user mounts the volume. For example, the background can tell the user to double-click the installation script to start the installation, so move the script so that it's in the right position for these instructions.
Move the whole open folder so that it is near the upper left corner of the screen, so that this is where it will appear when opened on the client's screen. If you are preparing the folder on a screen with a higher resolution than the client then it may open up down in the lower right screen, confusing the new user.
In general, you set up everything the way you want it for the user when she or he mounts the installation volume.
- Unmount the mounted disk image volume by closing the folder and then dragging the volume on the dektop to the trash. This will save the current setup and contents in the .dmg file wherever you initially created it.
- Make a read-only copy of the disk image with the proper BOINC filename as follows:
- Run Disk Utility (Applications --> Utitlities --> Disk Utility)
- Highlight the disk image file you just created (eg. Install_BOINC.dmg) and then pull down Images --> Convert
- Save As: boinc_4.36_powerpc-apple-darwin.dmg (with the right version number, of course)
Image Format: read-only
and press "Save" to create the read-only version of the .dmg
- Sign this file using the private signing key for your project. You might allow update_versions (below) to sign a test version, but in production you should sign the file on a separate computer not connected to the Internet.
- Copy the .dmg file and associated digital signature (.sig file) to your project area, PROJECT/apps/boinc.
- Run the BOINC utility update_versions to add this to your running project. Note that you have to use a newer version of this utility which recognizes the .dmg extension (or modify your version to do so, which is straightforward if you know something about regular expressions).
- Test it! Download the new core client from your project and go through the installation on a test machine to verify that it all works as intended and that it is understandable to a new user.
Please send corrections or suggestions for improvement to firstname.lastname@example.org
Last modified: 09 April 2010 Copyright © 2010 by Spy Hill Research http://spy-hill.net /help/boinc/apple-install-image.html