=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