From 3676115cf25f045ee892cf3e1605ae465301288c Mon Sep 17 00:00:00 2001 From: Naoum Hankache Date: Sat, 1 Dec 2018 13:19:39 +0200 Subject: Sanitize Pod Docs --- tools/star/mac-dmg.pod | 61 +++++++++++++++--------------- tools/star/release-guide.pod | 89 ++++++++++++++++++++++---------------------- tools/star/windows-msi.pod | 54 +++++++++++++-------------- 3 files changed, 101 insertions(+), 103 deletions(-) diff --git a/tools/star/mac-dmg.pod b/tools/star/mac-dmg.pod index 5eead08..732fec3 100644 --- a/tools/star/mac-dmg.pod +++ b/tools/star/mac-dmg.pod @@ -1,4 +1,4 @@ -=head1 mac-dmg.pod - guide to building DMG packages +=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 @@ -11,11 +11,11 @@ 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. +components. =head2 Steps to create an DMG package -A ".dmg" is a file extension used for an Apple Disk Image which is the most +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 from Apple if you don't already have the C 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). +X 10.9 (and probably further). -=item 1. +=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 .tar.gz to your hard disk. You will get a folder rakudo-star-YYYY.MM, again +Unpack this C<.tar.gz> to your hard disk. You will get a folder C, again YYYY.MM is year and month of the star release. -=item 2. +=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 + 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 +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 3. +=item Step 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. +If the build is interrupted you will have to manually C 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 +Note the C<--build> option will automatically delete the binary destination +directory of C 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. +Omitting the C<--build> option will just rebuild the C<.dmg> from C which is useful when debugging the final stage of C<.dmg> build since it's much faster. -=item 4. +=item Step 4 -A correct build will create 'ports/darwin_dmg/Temp_build/Rakudo-Star-YYYY-MM.dmg' +A correct build will create C To sanity test open Temp_build/Rakudo-Star-YYYY-MM.dmg -This should automount '/Volumes/Rakudo' and open a Finder window with a +This should automount C 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. +Delete the directory used to create the C<.dmg>. - rm -rf /Applications/Rakudo + rm -rf /Applications/Rakudo -Now dragging the 'Rakudo' folder to the Applications Link folder (with arrow) -should repopulate '/Applications/Rakudo'. +Now dragging the C folder to the Applications Link folder (with arrow) +should repopulate C. -Append your PATH as suggested in the 'README.txt' and look for reasonable output +Append your C as suggested in the C and look for reasonable output from the following kind of commands. perl6 -e "say 'hello'" zef list --installed p6doc -l -=item 5. +=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 6. +=item Step 6 Upload the dmg package to L: scp "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 #perl6 to do it for you. +masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you. -=item 7. +=item Step 7 Publicize the dmg packages in the appropriate places. These include: @@ -119,11 +119,10 @@ Publicize the dmg packages in the appropriate places. These include: =back -=item 11. +=item Step 11 You're done! Celebrate with the appropriate amount of fun. =back =cut - diff --git a/tools/star/release-guide.pod b/tools/star/release-guide.pod index a46eb16..8529603 100644 --- a/tools/star/release-guide.pod +++ b/tools/star/release-guide.pod @@ -1,15 +1,15 @@ -=head1 release_guide.pod - guide to Rakudo Star releases +=head1 Guide to Rakudo Star releases -Rakudo Star releases are based on Rakudo compiler releases. -Since some time is often needed for module updates and testing +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. 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, or -MoarVM. The goal is to balance end-user stability needs with -progress being made on the compiler, modules, and other runtime +MoarVM. The goal is to balance end-user stability needs with +progress being made on the compiler, modules, and other runtime components. Currently, Star is on a quarterly release cycle. =head2 Steps to create a release @@ -26,13 +26,13 @@ wish to do so. Step 8 will make sure you do this regardless. =over 4 -=item 0. +=item Step 0 Make sure you have a working C binary in your C<$PATH>. Refer to L for how to do that. The exact version isn't very important at the moment, it just shouldn't be a year out of date. -=item 1. +=item Step 1 Clone the git@github.com:rakudo/star repository. @@ -52,7 +52,7 @@ Verify that reports a clean repository. -=item 2. +=item Step 2 Change to the star repository directory and edit the first three lines of F to indicate the desired releases of @@ -66,9 +66,9 @@ release. $ cd star $ vi tools/star/Makefile -=item 3. +=item Step 3 -Run "make -f tools/star/Makefile" to populate the star directory +Run C to populate the star directory with the needed tarballs and module repositories for building Rakudo Star: $ make -f tools/star/Makefile @@ -79,22 +79,22 @@ Assuming the Makefile ran successfully, you should now commit your changes. $ git commit tools -=item 4. +=item Step 4 -If there are any new modules to be added, use "git submodule" to add -its repo to the modules/ directory. Also add the module directory -name to the modules/MODULES.txt file. +If there are any new modules to be added, use C to add +its repo to the modules/ directory. Also add the module directory +name to the C file. $ git submodule add git@github.com:user/acme-example modules/acme-example $ echo acme-example >>modules/MODULES.txt $ git commit . -m "Added acme-example to installed modules." -=item 5. +=item Step 5 Verify that all of the git submodules are at the desired commit for the Star release. To bring all modules up to the current -'master' branch, one can do: - +C branch, one can do: + # pull master in each submodule dir $ git submodule foreach git pull origin master @@ -108,10 +108,10 @@ Then you may commit your update of the submodules: # commit submodules state to star repo $ git commit modules -=item 6. +=item Step 6 If one doesn't already exist, create a release announcement in -docs/announce/YYYY.MM.md. You can often use the previous release's +C. You can often use the previous release's file as a starting point, updating the release number, version information, name, etc., as appropriate. Be sure to pay attention to any changes listed in Rakudo's ChangeLog. @@ -128,14 +128,14 @@ feedback on your announcement while you do other steps. $ git push -=item 7. +=item Step 7 -Update the release number in the README and Makefile.in files. +Update the release number in the C and C files. $ vi README tools/build/Makefile.in $ git commit README tools/build/Makefile.in -=item 8. +=item Step 8 Make sure any locally modified files have been pushed back to github. @@ -143,16 +143,16 @@ back to github. $ git status $ git push -=item 9. +=item Step 9 Create a candidate release tarball: $ make -f tools/star/Makefile release VERSION=2012.08 -This will create a tarball rakudo-star-2012.08.tar.gz in the +This will create a tarball C in the current directory. -=item 10. +=item Step 10 Unpack the tarball somewhere else, and do a test build/install: @@ -166,15 +166,15 @@ Unpack the tarball somewhere else, and do a test build/install: $ make rakudo-spectest $ make modules-test -If there are failures in any of rakudo-test, rakudo-spectest, or -modules-test, then do your best to fix them and return to step 8. +If there are failures in any of C, C, or +C, then do your best to fix them and return to step 8. -STOP THE RELEASE PROCESS (i.e., do not issue a release) if there -are any errors that you're unable to fix. File issue tickets +STOP THE RELEASE PROCESS (i.e., do not issue a release) if there +are any errors that you're unable to fix. File issue tickets (https://github.com/rakudo/star/issues) for failing tests -and report them to #perl6. +and report them to C<#perl6>. -=item 11. +=item Step 11 Tag the release by its release month ("YYYY.MM"). @@ -191,28 +191,28 @@ L. Should that prove impossible, you can omit the C<-s> from the command line. Also sign the release tarball with GPG and a suitable key -eg. gpg --armor --detach-sig rakudo-star-2018.01.tar.gz +eg. C -Generate a SHA256 sum -eg. sha256sum rakudo-star-2018.01.tar.gz | cut -f1 -d" " > rakudo-star-2018.01.tar.gz.sha256.txt +Generate a SHA256 sum eg. + sha256sum rakudo-star-2018.01.tar.gz | cut -f1 -d" " > rakudo-star-2018.01.tar.gz.sha256.txt -=item 12. +=item Step 12 Upload the release tarball to L and L: $ scp rakudo-star-2012.08.tar.gz rakudo@rakudo.org:public_html/downloads/star -Also upload the detached signature eg. rakudo-star-2018.01.tar.gz.asc -and sha256 sum eg. rakudo-star-2018.01.tar.gz.sha256.txt +Also upload the detached signature eg. C +and sha256 sum eg. C -If you don't have permission to do this step, please ask one of the core devs -(pmichaud, jnthn, masak, PerlJam/perlpilot, tadzik, or moritz) on #perl6 to do +If you don't have permission to do this step, please ask one of the core devs +(pmichaud, jnthn, masak, PerlJam/perlpilot, tadzik, or moritz) on C<#perl6> to do it for you. -=item 13. +=item Step 13 Commit announcement to the rakudo.org repo automatically by running the following -command. You will need perl6 in the PATH and to "zef install WWW" if you don't +command. You will need C in the C and to C if you don't have it. You can also make and commit the post manually, but if you do, be sure @@ -222,7 +222,7 @@ to add C<%% title:> and C<%% date:> metadate to the top of the file: git clone git@github.com:perl6/rakudo.org/. && ./push-latest-rakudo-star-announcement.p6 2018.01 -You will also have to bump versions manually in "templates/files.html.ep" in +You will also have to bump versions manually in C in the rakudo.org repo. Publicize the release in the appropriate places. These include: @@ -261,7 +261,7 @@ and L =back -=item 14 +=item Step 14 Add this release and your name to the list of releases at the end of this document (F). @@ -270,7 +270,7 @@ document (F). $ git add tools/star/release-guide.pod $ git commit -m 'note YYYY.MM release in release-guide.pod -=item 15. +=item Step 15 You're done! Celebrate with the appropriate amount of fun. @@ -347,4 +347,3 @@ You're done! Celebrate with the appropriate amount of fun. 2019.01 Apply within =cut - diff --git a/tools/star/windows-msi.pod b/tools/star/windows-msi.pod index d1b9875..d4f8b63 100644 --- a/tools/star/windows-msi.pod +++ b/tools/star/windows-msi.pod @@ -1,4 +1,4 @@ -=head1 windows-msi.pod - guide to build MSI packages +=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 @@ -24,48 +24,48 @@ to this release guide since your last run. =over 4 -=item 0. +=item Step 0 Download and install WiX Toolset, if needed adjust the PATH environment -variable to point to its bin directory. The tools `heat`, `candle` and `light` +variable to point to its bin directory. The tools C, C and C should be available now. -Install ActivePerl and make sure it is in PATH. `perl -V` should give a +Install ActivePerl and make sure it is in C. C should give a sensible output. -If you do not have the C compiler "cl" installed yet, install the Microsoft +If you do not have the C compiler C 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 cmd.exe -and replace all following references to "nmake" by "gmake". +Perl which ships with GCC and a mingw toolchain. Run these tools under C +and replace all following references to C by C. -=item 1. +=item Step 1 -Make sure there is no C:\rakudo directory, as this will be our installation +Make sure there is no C directory, as this will be our installation target. If there is one, remove it, perhaps after creating backup. -=item 2. +=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 .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. +Unpack this C<.tar.gz> to your hard disk. You will get a folder +C, again YYYY.MM is year and month of the star release. -=item 3. +=item Step 3 Run the Command Line for Visual Studio from the start menu. Alternatively you -can run cmd.exe followed by vcvars32.bat. +can run C followed by C. In either case, this should return a valid path: echo %VSINSTALLDIR% -=item 4. +=item Step 4 Change the path to the directory created in step 2, and run: @@ -73,21 +73,21 @@ Change the path to the directory created in step 2, and run: This will create a Makefile and will start to compile the MoarVM backend. -=item 5. +=item Step 5 Compile NQP and Rakudo by doing: nmake install -This will also precompile all modules and install binaries like `panda`. +This will also precompile all modules and install binaries like C. -=item 6. +=item Step 6 Finally create the MSI package. nmake msi -(Note if you are using Strawberry Perl's GCC use 'build_msi' at this point) +(Note if you are using Strawberry Perl's GCC use C at this point) Depending on your architecture you either rename that msi to: @@ -98,9 +98,9 @@ or: rakudo-star-YYYY.MM-x86_64 (JIT).msi -=item 7. +=item Step 7 -Delete your C:\rakudo folder and make sure it got deleted. Then run the just +Delete your C folder and make sure it got deleted. Then run the just created installer, and do some sanity tests: perl6 -e "say $*KERNEL.bits" @@ -109,14 +109,14 @@ created installer, and do some sanity tests: 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:\rakudo folder. +C folder. -=item 8. +=item Step 8 Stop the release process if step 7 failed. Post any issues to the irc channel or mailing list. -=item 9. +=item Step 9 Upload the msi package to L and L: @@ -124,9 +124,9 @@ Upload the msi package to L and L to do it for you. -=item 10. +=item Step 10 Publicize the msi packages in the appropriate places. These include: @@ -138,7 +138,7 @@ Publicize the msi packages in the appropriate places. These include: =back -=item 11. +=item Step 11 You're done! Celebrate with the appropriate amount of fun. -- cgit v1.1