import mac binary installer pod

1 files changed, 129 insertions, 0 deletions

diff --git a/tools/star/mac-dmg.pod b/tools/star/mac-dmg.pod
new file mode 100644
index 0000000..604f933
--- /dev/null
+++ b/tools/star/mac-dmg.pod
@@ -0,0 +1,129 @@
+=head1 mac-dmg.pod - guide to building DMG packages
+
+Rakudo Star releases are based on Rakudo compiler releases.
+Since some time is often needed for module updates and testing
+after each Rakudo compiler release, the timing of Star releases
+varies from one release to the next. The dmg packages are based
+on these Star releases.
+
+Also, while the Rakudo compiler issues monthly releases; Star
+releases are free to choose a longer release cycle.  Star releases
+are also free to choose older releases of the compiler, NQP, and/or
+MoarVM.  The goal is to balance end-user stability needs with
+progress being made on the compiler, modules, and other runtime
+components. 
+
+=head2 Steps to create an DMG package
+
+A ".dmg" is a file extension used for an Apple Disk Image which is the most
+popular way of running an installer on the Mac desktop
+
+If this is your first time releasing, B<read the whole guide before
+starting>. That way you can ask questions and clear up and confusions before
+you're in the thick of it.
+
+If you have done this before, you might want to check for and read any changes
+to this release guide since your last run.
+
+=over 4
+
+=item 0.
+
+Download and install Xcode from Apple if you don't already have the clang C
+compiler installed. This process was tested on OS X 10.11.x as a build system
+using clang-700.1.76 and the result is known to run on as least far back as OS
+X 10.9 (and probably further). 
+
+=item 1.
+
+Use your browser to download the latest star release, replace YYYY.MM by year and month:
+http://rakudo.org/downloads/star/rakudo-star-YYYY.MM.tar.gz
+
+Unpack this .tar.gz to your hard disk. You will get a folder rakudo-star-YYYY.MM, again
+YYYY.MM is year and month of the star release.
+
+=item 2.
+
+Change the path to the directory created in the previous step, and run:
+
+  cd ports/darwin_dmg
+  perl package_darwin_dmg.pl --build -v YYYY MM 
+
+This should automatically compile the MoarVM version of star and all modules and create the .dmg
+
+In theory this all that needs doing and you can jump to step 4 below.
+
+=item 3.
+
+Watch the scrollback for errors.
+
+If the build is interrupted you will have to manually 'make clean' in the top
+level directory before rerunning the previous step. 
+
+Note the '--build' option will automatically delete the binary destination
+directory of '/Applications/Rakudo' if it exists before running but leaves it in
+place after finishing.
+
+Omitting the '--build' option will just rebuild the .dmg from '/Applications/Rakudo' which is useful when debugging the final stage of .dmg build since it's much faster.
+
+=item 4.
+
+A correct build will create 'ports/darwin_dmg/Temp_build/Rakudo-Star-YYYY-MM.dmg'
+
+To sanity test
+
+  open Temp_build/Rakudo-Star-YYYY-MM.dmg
+
+This should automount '/Volumes/Rakudo' and open a Finder window with a
+background image of Camelia and "Drag the Rakudo Folder to Applications"
+containing a README.txt, a Rakudo folder, Docs folder and a folder representing
+a sym link to Applications.
+
+Delete the directory used to create the .dmg.
+
+ rm -rf /Applications/Rakudo 
+
+Now dragging the 'Rakudo' folder to the Applications Link folder (with arrow)
+should repopulate '/Applications/Rakudo'. 
+
+Append your PATH as suggested in the 'README.txt' and look for reasonable output
+from the following kind of commands.
+
+  perl6 -e "say 'hello'"
+  panda --installed list
+  p6doc -l
+
+=item 5.
+
+Stop the release process if you see serious issues with no obvious fix and post
+them to the IRC channel or mailing list. If you alter scripts recommit them.
+
+=item 6.
+
+Upload the dmg package to L<http://rakudo.org/downloads/star>:
+
+ scp "rakudo-star-YYYY.MM.dmg" rakudo@rakudo.org:public_html/downloads/star
+
+If you don't have permission to do this step, please ask one(pmichaud, jnthn,
+masak, PerlJam, tadzik, moritz) on #perl6 to do it for you.
+
+=item 7.
+
+Publicize the dmg packages in the appropriate places.  These include:
+
+=over 4
+
+=item * rakudo.org
+
+=item * #perl6
+
+=back
+
+=item 11.
+
+You're done!  Celebrate with the appropriate amount of fun.
+
+=back
+
+=cut
+