1 files changed, 142 insertions, 0 deletions
diff --git a/docs/guides/mac-dmg.pod b/docs/guides/mac-dmg.pod
new file mode 100644
index 0000000..7ebc64a
--- /dev/null
+++ b/docs/guides/mac-dmg.pod
@@ -0,0 +1,142 @@
+=head1 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 C<.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 any 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 Step 0
+
+Download and install C<Xcode> from Apple if you don't already have the C<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 Step 1
+
+Use your browser to download the latest star release, replace YYYY.MM by year and month:
+https://rakudo.perl6.org/downloads/star/rakudo-star-YYYY.MM.tar.gz
+
+Unpack this C<.tar.gz> to your hard disk. You will get a folder C<rakudo-star-YYYY.MM>, again
+YYYY.MM is year and month of the star release.
+
+=item Step 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 C<.dmg>
+
+In theory this all that needs doing and you can jump to step 4 below.
+
+=item Step 3
+
+Watch the scrollback for errors.
+
+If the build is interrupted you will have to manually C<make clean> in the top
+level directory before rerunning the previous step.
+
+Note the C<--build> option will automatically delete the binary destination
+directory of C</Applications/Rakudo> if it exists before running but leaves it in
+place after finishing.
+
+Omitting the C<--build> option will just rebuild the C<.dmg> from C</Applications/Rakudo> which is useful when debugging the final stage of C<.dmg> build since it's much faster.
+
+=item Step 4
+
+A correct build will create C<ports/darwin_dmg/Temp_build/Rakudo-Star-YYYY-MM.dmg>
+
+To sanity test
+
+  open Temp_build/Rakudo-Star-YYYY-MM.dmg
+
+This should automount C</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 C<.dmg>.
+
+ rm -rf /Applications/Rakudo
+
+Now dragging the C<Rakudo> folder to the Applications Link folder (with arrow)
+should repopulate C</Applications/Rakudo>.
+
+Append your C<PATH> as suggested in the C<README.txt> and look for reasonable output
+from the following kind of commands.
+
+  perl6 -e "say 'hello'"
+  zef list --installed
+  p6doc -l
+
+=item Step 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 Step 6
+
+Generate a SHA256 sum:
+
+  sha256sum rakudo-star-YYYY.MM.dmg | cut -f1 -d" " > rakudo-star-YYYY.MM.dmg.sha256.txt
+
+=item Step 7
+
+Generate a GPG signature for the DMG file:
+
+  gpg --armor --detach-sig rakudo-star-YYYY.MM.dmg
+
+This will create C<rakudo-star-YYYY.MM.dmg.asc>.
+
+=item Step 8
+
+Upload the dmg and SHA256 to L<https://rakudo.perl6.org/downloads/star>:
+
+ rsync -avz rakudo-star-YYYY.MM.dmg* rakudo@www.p6c.org:public_html/downloads/star
+
+If you don't have permission to do this step, please ask one(pmichaud, jnthn,
+masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you.
+
+=item Step 9
+
+Publicize the dmg packages in the appropriate places.  These include:
+
+=over 4
+
+=item * rakudo.org
+
+=item * #perl6
+
+=back
+
+=item Step 10
+
+You're done!  Celebrate with the appropriate amount of fun.
+
+=back
+
+=cut