87844Updated OS X build process
- Sep 30, 2005After getting a copy of the Mac OS X build process, I went through and
cleaned it up some and sent a copy to Conor. It doesn't look like he's
been around, so I'll post it to the list (and upload a copy):
NOTE: I don't know if any PCGen code improvements have been made to
get it to run under OS X 10.4 from the time I wrote this. If so, let
me know and I'll update this.
PART 1: Get everything you need
A) Run Software Update to make sure that you have the latest fixes and
B) If they are not already installed, you will need the OS X Developer
tools. If they didn't come with your computer or OS X boxed set, then
you can set up a free Apple Developer Connection account
(http://www.apple.com/developer) and download them from there. Make
sure you get XCode 1.5 or greater; as of this writing, an XCode 2.1
preview is available -- however, it only runs on OS X 10.4 or greater.
C) You will need the "archive" folder that is included in any recent
version of the Mac OS X distribution of PCGen. A copy is available at
D) Download the full version of PCGen from SourceForge. Get the latest
non-OS specific version; the Mac OS X distributions are distributed as
a mac installer, and are already packaged as a Mac OS application.
E) If you are using OS X 10.4 or later, you must download and install
the Java 2 SE 5.0 Release 1 from the ADC site; PGCen will not
currently run on OS X 10.4 under Java 1.4.2.
Now that we have all the parts and pieces, we can start to assemble.
If you need me to go back and clarify anything let me know.
PART 2: Converting PCGen to be an OS X application bundle
A) Launch /Developer/Applications/Java Tools/Jar Bundler
B) On the "Build Information" tab, click the Choose button to the
right of the Main Class field. Navigate to the pcgen.jar file in the
PCGen distribution folder.
C) Make sure the "Use Macintosh Menu Bar", "Anti-Alias Text",
"Anti-alias Graphics", and "Growbox Intrudes" checkboxes are all checked.
D) Make sure the JVM version is "1.4+". If you're running OS X 10.4,
you MUST hand-edit this to be "1.5*" -- note that this creates a build
that will ONLY run under 10.4 or later, and ONLY if Java 5 is installed.
E) Under the Custom Icon preview, click Choose Icon, navigate to "new
icon.icns" in the archive folder.
F) Switch to the "Classpath and Files" tab. Under "Additional Files
and Resources", click the Add button and navigate to the lib directory
in the PCGen distribution folder. Add all of the .jar files that
reside in the lib directory; Jar Builder will create the appropriate
classpath entries under "Additions to Classpath".
G) Switch to the Properties tab. In the Type field, verify that it is
AAPL. In the Signature Field, enter "PCGn" (without the quotes).
H) In the Identifier field, enter "com.codemonkey.pcgen" (without quotes)
I) Enter relevant information into the Version, Get-Info String, and
Short Version fields.
J) In the Bundle Name field, enter "PCGen" (without quotes)
K) In the VM Options field, enter "-Xms128m -Xmx256m" (without
quotes). This causes PCGen to reserve a minimum of 128MB of RAM and a
maximum of 256MB for its operation, which can be useful if you're
developing datasets or running with a large number of datasets loaded.
NOTE: You may want to experiment to find settings that work for you if
you don't have a large amount of memory available; "-Xms" sets the
initial size of the memory allocation pool (default is 2 MB), and
"-Xmx" sets the maximum size of the allocation pool (default is 64 MB).
L) Switch back to the Build Information tab -- if you don't do this,
Jar Bundler doesn't paste the icon for the app correctly, I don't know
why -- and click the Create Application button. Save the application
as PCGen.app into the PCGen distribution folder.
This will encapsulate the PCGen jar file into an OS X application.
After that, we can clean up the PCGen distribution folder, removing
all those ugly Windows & Unix/Linux files :-P
PART 3: Cleaning up the PCGen folder
A) Delete pcgen_high_mem.bat, pcgen.bat, and pcgen.sh files. They are
B) Delete the lib directory and pcgen.jar, as they are included in the
application bundle. (You might want to copy the license files from the
lib directory into the Contents/Resources/Java directory.)
C) Copy the text from release notes into ReadMe.rtf in the
English.proj subfolder in the archive folder. Once the content is in
the .rtf file, you can delete the HTML release notes.
D) Rename the folder for PCGen into "PCGen x.x.xx" (without quotes),
with the current version number.
We now have a pristine folder for PCGen; at this point you can run the
application by clicking on the PCGen icon. You might want to move your
PCGen folder into your Applications folder, but note that if you move
PCGen after running it for the first time, it may lose many of your
settings. (You can hand-edit the options.ini and filepaths.ini files
in the PCGen directory to point to the new location, but it's easier
to put PCGen where you want to keep it and then run PCGen for the
If you want to save this distribution to be reinstalled, or installed
on multiple computers, you should create an OS X Installer package for
it. You will want to do this BEFORE you run PCGen for the first time,
so your custom .ini files don't get included by mistake.
PART 4: Creating an Installer package
A) Move the archive folder from a previous OS X PCGen distribution
into your PCGen distribution folder.
B) If you've already run PCGen, delete the filter.ini, options.ini and
C) Close the Finder window for the PCGen folder and empty your Trash.
D) If you have one, use a utility that deletes resource forks. (Do a
Google search for "Remove MacOS Junk" for a small freeware utility
that does this.)
E) Launch Terminal, and enter the following commands. Where you see
the text "<drag PCGen folder>", do just that -- drag the PCGen
distribution folder into the terminal window and the path to it will
be entered for you.
find <drag PCGen folder> -name .DS_Store -delete
find <drag PCGen folder> -name .Trashes -delete (when the first
command finishes executing)
These terminal commands will delete certain system files that the
Finder puts in the folder -- .DS_Store holds information on the
current folder view, custom icon for the folder, etc. while .Trashes
tells the Finder what files in that folder are to be deleted when the
Trash is emptied. Once you execute these two terminal commands, DO NOT
reopen your PCGen folder in the Finder or those files will be
recreated, and you'll have to repeat this step.
F) Create a new folder in Finder, and put the PCGen distribution
folder in it. You don't need to rename the folder or anything; all
that matters is that it is new and contains nothing but the PCGen
G) Launch /Developer/Applications/Utilities/PackageMaker
H) On the Description tab, fill in relevant information for the Title,
Version, and Description fields (I usually just grab the PCGen
boilerplate information from http://www.pcgen.com/ for the Description
field). We can leave the Delete Warning field blank.
I) On the Files tab, click on the Choose button to the right of the
Root field. Navigate to the folder you have the PCGen distribution
folder in. Make sure that the Compress Archive folder is checked.
J) On the Resources tab, click on the Choose button to the right of
the Resources field. Navigate to the English.proj folder that is in
the archive subfolder of PCGen.
K) On the Info tab, enter "/Applications" (without quotes) in the
Default Location field.
L) Set the Post-Install Action to "No Restart Required". Set the
Authorization Action to "No Authorization Required".
M) Check the checkboxes for "Allow Revert to Previous Version", and
"Relocatable". All of the other checkboxes should be off.
N) On the Version tab, in the Display Name, enter "PCGen" (without
quotes). In the Identifier field, enter "com.codemonkey.pcgen"
O) Enter the relevant version information in the Get-Info String and
Short Version fields. Enter the first version numeral in the Major
field (currently "5"), and the number after the first decimal in the
minor field (currently "8")
P) From the file menu, choose Create Package. Save the file as
PCGenXXX.pkg (where "XXX" is the version number; currently, that would
be "580"). If you have not done step D above and deleted the resource
forks, you may get a message here saying that Pacakge Maker wants to
split the resource forks off. Click Split Forks.
We now have a nicely bundled Installer package. You should test your
creation by double-clicking on the PCGenXXX.pkg file; Installer should
launch and, once you follow the prompts, it should create a PCGen
folder in your Applications folder and locate all of the files in the
correct place. You might want to launch PCGen from your
newly-installed folder to make sure it works.
The only problem with your Installer package is that the internet is
not friendly to .pkg files since they are really just specially named
and configured folders. You can use a compression utility to create a
Stuffit (.sit) or zipfile (.zip) archive; personally, I think disk
image files (.dmgs) are much handier.
PART 6: Creating a .dmg (disk image) file
A) Launch /Applications/Utilities/Disk Utility. Click on the New
Image button in the toolbar of the main window. Name this image
"PCGen for OS X.dmg" (without quotes).
B) Mount the disk image by double-clicking on it and copy the
PCGenXXX.pkg to it. You might also want to put an additional copy of
the ReadMe/Release Notes for this version on the disk image.
C) Unmount the disk image by dragging the virtual disk icon to the
D) In Disk Utility, select the disk image in the left sidebar of the
main window. From the Images menu above, select Convert.
E) In the Save As: Field, enter a file name of
"pcgenXXX_mac_install.dmg" (without quotes, where "XXX" is the version
number; currently, that would be "580").
F) Select "Compressed" from the Image Format menu towards the bottom
of this sheet and click Save.
You now have a disk image file that can be uploaded to your favorite
(Special thanks goes to Conor Schutzman for writing the original version)
- Next post in topic >>