aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNaoum Hankache <naoum88@gmail.com>2018-12-01 13:19:39 +0200
committerNaoum Hankache <naoum88@gmail.com>2018-12-01 13:19:39 +0200
commit3676115cf25f045ee892cf3e1605ae465301288c (patch)
tree06a2fd787e22baa1cb65b5499269d245535d1042
parent871d564847f7cc063f892fd76880c1686307fc4f (diff)
Sanitize Pod Docs
-rw-r--r--tools/star/mac-dmg.pod61
-rw-r--r--tools/star/release-guide.pod89
-rw-r--r--tools/star/windows-msi.pod54
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<read the whole guide before
@@ -27,87 +27,87 @@ to this release guide since your last run.
=over 4
-=item 0.
+=item Step 0
-Download and install Xcode from Apple if you don't already have the clang C
+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).
+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<rakudo-star-YYYY.MM>, 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<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
+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 '--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</Applications/Rakudo> 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<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
+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 .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<Rakudo> folder to the Applications Link folder (with arrow)
+should repopulate C</Applications/Rakudo>.
-Append your PATH as suggested in the 'README.txt' and look for reasonable output
+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 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<https://rakudo.perl6.org/downloads/star>:
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<perl6> binary in your C<$PATH>. Refer to
L<http://rakudo.org/how-to-get-rakudo/> 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<tools/star/Makefile> 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<make -f tools/star/Makefile> 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<git submodule> to add
+its repo to the modules/ directory. Also add the module directory
+name to the C<modules/MODULES.txt> 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<master> 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<docs/announce/YYYY.MM.md>. 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<README> and C<Makefile.in> 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<rakudo-star-2012.08.tar.gz> 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<rakudo-test>, C<rakudo-spectest>, or
+C<modules-test>, 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<create one first|https://fedoraproject.org/wiki/Creating_GPG_Keys>. 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<gpg --armor --detach-sig rakudo-star-2018.01.tar.gz>
-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<http://rakudo.org/downloads/star> and L<https://rakudo.perl6.org/downloads/star/>:
$ 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<rakudo-star-2018.01.tar.gz.asc>
+and sha256 sum eg. C<rakudo-star-2018.01.tar.gz.sha256.txt>
-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<perl6> in the C<PATH> and to C<zef install WWW> 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<templates/files.html.ep> in
the rakudo.org repo.
Publicize the release in the appropriate places. These include:
@@ -261,7 +261,7 @@ and L<r/programming|https://www.reddit.com/r/programming/>
=back
-=item 14
+=item Step 14
Add this release and your name to the list of releases at the end of this
document (F<tools/star/release-guide.pod>).
@@ -270,7 +270,7 @@ document (F<tools/star/release-guide.pod>).
$ 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<heat>, C<candle> and C<light>
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<PATH>. C<perl -V> 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<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 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<cmd.exe>
+and replace all following references to C<nmake> by C<gmake>.
-=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<C:\rakudo> 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<rakudo-star-YYYY.MM>, 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<cmd.exe> followed by C<vcvars32.bat>.
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<zef>.
-=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<build_msi> 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<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"
@@ -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<C:\rakudo> 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<http://rakudo.org/downloads/star> and L<https://rakudo.perl6.org/downloads/star/>:
@@ -124,9 +124,9 @@ Upload the msi package to L<http://rakudo.org/downloads/star> and L<https://raku
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 #perl6 to do it for you.
+masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> 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.