1 files changed, 155 insertions, 0 deletions
diff --git a/docs/guides/windows-msi.pod b/docs/guides/windows-msi.pod
new file mode 100644
index 0000000..8674c22
--- /dev/null
+++ b/docs/guides/windows-msi.pod
@@ -0,0 +1,155 @@
+=head1 Guide to build MSI 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 MSI 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 MSI package
+
+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 Step 0
+
+Download and install WiX Toolset, if needed adjust the PATH environment
+variable to point to its bin directory. The tools C<heat>, C<candle> and C<light>
+should be available now.
+
+Install ActivePerl and make sure it is in C<PATH>. C<perl -V> should give a
+sensible output.
+
+If you do not have the C compiler C<cl> installed yet, install the Microsoft
+Visual C++ Express for version 2010 or perhaps newer.
+
+Finally, install the Windows Software Development Kit (SDK) for your Windows
+version.
+
+An alternative to ActivePerl and the Microsoft toolchain is to use Strawberry
+Perl which ships with GCC and a mingw toolchain.  Run these tools under C<cmd.exe>
+and replace all following references to C<nmake> by C<gmake>.
+
+=item Step 1
+
+Make sure there is no C<C:\rakudo> directory, as this will be our installation
+target.  If there is one, remove it, perhaps after creating backup.
+
+=item Step 2
+
+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 3
+
+Run the Command Line for Visual Studio from the start menu. Alternatively you
+can run C<cmd.exe> followed by C<vcvars32.bat>.
+
+In either case, this should return a valid path:
+
+  echo %VSINSTALLDIR%
+
+=item Step 4
+
+Change the path to the directory created in step 2, and run:
+
+  perl Configure.pl --prefix=C:\rakudo --gen-moar
+
+This will create a Makefile and will start to compile the MoarVM backend.
+
+=item Step 5
+
+Compile NQP and Rakudo by doing:
+
+  nmake install
+
+This will also precompile all modules and install binaries like C<zef>.
+
+=item Step 6
+
+Finally create the MSI package.
+
+  nmake msi
+
+(Note if you are using Strawberry Perl's GCC use C<build_msi> at this point)
+
+Depending on your architecture you either rename that msi to:
+
+  rakudo-star-YYYY.MM-x86 (no JIT).msi
+
+or:
+
+  rakudo-star-YYYY.MM-x86_64 (JIT).msi
+
+
+=item Step 7
+
+Delete your C<C:\rakudo> folder and make sure it got deleted. Then run the just
+created installer, and do some sanity tests:
+
+  perl6 -e "say $*KERNEL.bits"
+  zef list --installed
+  zef install openssl
+
+If you are using Strawberry Perl then move its directory temporarily to a
+different name in order to check all DDLs are correctly installed in the
+C<C:\rakudo> folder.
+
+=item Step 8
+
+Stop the release process if step 7 failed. Post any issues to the irc channel
+or mailing list.
+
+=item Step 9
+
+Generate a SHA256 sum eg.
+
+ $ sha256sum "rakudo-star-YYYY.MM-x86_64 (JIT).msi" | cut -f1 -d" " > "rakudo-star-YYYY.MM-x86_64 (JIT).msi.sha256.txt"
+
+=item Step 10
+
+Upload the msi package to L<http://rakudo.org/downloads/star> and L<https://rakudo.perl6.org/downloads/star/>:
+
+ scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" rakudo@rakudo.org:public_html/downloads/star
+ scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" 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.
+
+Also upload the sha256 sum eg. C<rakudo-star-YYYY.MM-x86_64 (JIT).msi.sha256.txt>
+
+=item Step 11
+
+Publicize the msi packages in the appropriate places.  These include:
+
+=over 4
+
+=item * rakudo.org
+
+=item * #perl6
+
+=back
+
+=item Step 12
+
+You're done!  Celebrate with the appropriate amount of fun.
+
+=back
+
+=cut