Permalink
Browse files

README should be in text, not POD.

  • Loading branch information...
1 parent 3fbd628 commit fe29cde77e63c798bc7cf2a8c764d9ed012f2d27 @coke coke committed Jul 28, 2010
Showing with 210 additions and 233 deletions.
  1. +210 −233 README
View
443 README
@@ -1,245 +1,222 @@
-=head1 Rakudo Perl 6
+Rakudo Perl 6
+ This is Rakudo Perl, a Perl 6 compiler for the Parrot virtual machine.
-This is Rakudo Perl, a Perl 6 compiler for the Parrot virtual machine.
+ Rakudo Perl is Copyright (C) 2008-2010, The Perl Foundation. Rakudo Perl
+ is distributed under the terms of the Artistic License 2.0. For more
+ details, see the full text of the license in the file LICENSE.
-Rakudo Perl is Copyright (C) 2008-2010, The Perl Foundation.
-Rakudo Perl is distributed under the terms of the Artistic License 2.0.
-For more details, see the full text of the license in the file LICENSE.
+ Installing with your package manager
+ There are binary packages available for these operating systems: various
+ Windows versions, FreeBSD, Arch Linx, Fedora, OpenSuSE, CRUX.
-=head2 Installing with your package manager
+ Please refer to <http://rakudo.org/how-to-get-rakudo> for links to the
+ individual packages.
-There are binary packages available for these operating systems:
-various Windows versions, FreeBSD, Arch Linx, Fedora, OpenSuSE, CRUX.
+ Build requirements (Installing from source)
+ For building Rakudo you need at least a C compiler, a "make" utility,
+ and Perl 5.8 or newer. To automatically obtain and build Parrot or the
+ spectest suite you may also need a subversion (svn) client.
-Please refer to L<http://rakudo.org/how-to-get-rakudo> for links to
-the individual packages.
+ In order to fully support Unicode, you'll also want to have the ICU
+ library installed (<http://site.icu-project.org/>). Rakudo can run
+ without ICU, but some Unicode-related features do not work properly.
-=head2 Build requirements (Installing from source)
+ As an example, on Debian GNU/Linux or Ubuntu Linux, the necessary
+ components for building Rakudo can be installed via the command
-For building Rakudo you need at least a C compiler, a C<make> utility,
-and Perl 5.8 or newer. To automatically obtain and build Parrot
-or the spectest suite you may also need a subversion (svn) client.
+ aptitude install build-essential libicu-dev subversion
-In order to fully support Unicode, you'll also want to have the
-ICU library installed (L<http://site.icu-project.org/>).
-Rakudo can run without ICU, but some Unicode-related features
-do not work properly.
+ (Perl is installed by default already). To enable parallel testing you
+ also need the CPAN module Test::Harness in version 3.16 or newer; you
+ can control the number of parallel jobs with the "TEST_JOBS" environment
+ variable.
-As an example, on Debian GNU/Linux or Ubuntu Linux, the necessary
-components for building Rakudo can be installed via the command
+ Building and invoking Rakudo
+ Because Rakudo is under rapid development, we generally recommend
+ downloading Rakudo directly from github and building from there:
+
+ $ git clone git://github.com/rakudo/rakudo.git
- aptitude install build-essential libicu-dev subversion
+ If you don't have git installed, you can get a tarball or zip of Rakudo
+ from <http://github.com/rakudo/rakudo/downloads>. Then unpack the
+ tarball or zip.
-(Perl is installed by default already). To enable parallel testing you
-also need the CPAN module L<Test::Harness> in version 3.16 or newer;
-you can control the number of parallel jobs with the C<TEST_JOBS>
-environment variable.
+ If you already have cloned Rakudo from github, you can get (pull) the
+ most recent version from github like this:
-=head2 Building and invoking Rakudo
-
-Because Rakudo is under rapid development, we generally recommend
-downloading Rakudo directly from github and building from there:
-
- $ git clone git://github.com/rakudo/rakudo.git
-
-If you don't have git installed, you can get a tarball or zip of Rakudo
-from L<http://github.com/rakudo/rakudo/downloads>.
-Then unpack the tarball or zip.
-
-If you already have cloned Rakudo from github, you can get (pull) the
-most recent version from github like this:
-
- $ cd rakudo
- $ git pull
-
-Once you have an updated copy of Rakudo, build it as follows:
-
- $ cd rakudo
- $ perl Configure.pl --gen-parrot
- $ make
-
-This will create a "perl6" or "perl6.exe" executable in the
-current (rakudo) directory. Note that if you have multiple (Perl 5)
-C<perl>s in your path, you may need to use a fully qualified path
-to the appropriate executable (or update your PATH environment variable).
-
-Programs can then be run from the build directory using a command like:
-
- $ ./perl6 hello.pl
-
-B<Important>: To run Rakudo from outside the build directory, you
-B<must> run
-
- $ make install
-
-This will install the C<perl6> (or C<perl6.exe> binary on windows)
-into the C<parrot_install/bin> directory locally, no additional root
-privileges necessary.
-
-The C<--gen-parrot> above option tells Configure.pl to automatically
-download and build the most appropriate version of Parrot into
-a local "parrot/" subdirectory, install that Parrot into
-the C<parrot_install/> subdirectory, and use that for building
-Rakudo. It's okay to use the C<--gen-parrot> option on later
-invocations of Configure.pl; the configure system will re-build
-Parrot only if a newer version is needed for whatever version
-of Rakudo you're working with.
-
-You can use C<--parrot-config=/path/to/parrot_config> instead
-of C<--gen-parrot> to use an already installed Parrot for building
-Rakudo. This installed Parrot must include its development
-environment; typically this is done via Parrot's C<make install>
-target or by installing prebuilt C<parrot-devel> and/or C<libparrot-dev>
-packages. The version of the already installed Parrot must satisfy a
-minimum specified by the Rakudo being built -- Configure.pl will
-verify this for you. Released versions of Rakudo always build
-against the latest release of Parrot; checkouts of the HEAD revision
-from github often require a version of Parrot that is newer than
-the most recent Parrot monthly release.
-
-Once built, Rakudo's C<make install> target will install Rakudo
-and its libraries into the Parrot installation that was used to
-create it. Until this step is performed, the "perl6" executable
-created by C<make> above can only be reliably run from the root of
-Rakudo's build directory. After C<make install> is performed,
-the installed executable can be run from any directory (as long as
-the Parrot installation that was used to create it remains intact).
-
-If the Rakudo compiler is invoked without an explicit script to
-run, it enters a small interactive mode that allows Perl 6 statements
-to be executed from the command line.
-
-=head3 Build/install problems
-
-Occasionally, there may be problems when building/installing Rakudo.
-Make sure you have a backup of any custom changes you have done to the
-source tree before performing the following steps:
-
-Try to remove the C<parrot_install> subdirectory:
-
- $ cd rakudo
- $ rm -r parrot_install
- $ git pull
- $ perl Configure.pl --gen-parrot
- $ make
-
-Or, in case you are really stuck, start with a fresh source tree:
-
- $ rm -r rakudo
- $ git clone git://github.com/rakudo/rakudo.git
-
-=head2 Running the test suite
-
-Entering C<make test> will run a small test suite that comes
-bundled with Rakudo. This is a simple suite of tests, designed
-to make sure that the Rakudo compiler is basically working and that
-it's capable of running a simple test harness.
-
-Running C<make spectest> will import the official Perl 6 test suite
-from the Pugs repository L<http://svn.pugscode.org/pugs/t/spec/>
-and run all of these tests that are currently known to pass.
-
-If you want to automatically submit the results of your spectest run
-to a central server, use C<make spectest_smolder> instead. You need
-the Perl 5 module L<TAP::Harness::Archive> and an active internet
-connection for that. The smoke results are collected at
-L<http://smolder.plusthree.com/app/public_projects/details/18>.
-
-At present we do not have any plans to directly store the
-official test suite as part of the Rakudo/Parrot repository,
-but will continue to fetch it from the Pugs repository.
-
-You can also use "make" to run an individual test from the command line:
-
- $ make t/spec/S29-str/ucfirst.t
- t/spec/S29-str/ucfirst.rakudo ..
- 1..4
- ok 1 - simple
- ok 2 - empty string
- ok 3 - # SKIP unicode
- ok 4 - # SKIP unicode
- # FUDGED!
- ok
- All tests successful.
- Files=1, Tests=4, 1 wallclock secs ( 0.02 usr 0.00 sys + 0.57 cusr 0.06 csys = 0.65 CPU)
- Result: PASS
-
-If you want to run the tests in parallel, you need to install a
-fairly recent version of the Perl 5 module L<Test::Harness> (3.16
-works for sure).
-
-=head2 Where to get help or answers to questions
-
-There are several mailing lists, IRC channels, and wikis available
-with help for Perl 6 and Rakudo on Parrot. Figuring out the right
-one to use is often the biggest battle. Here are some rough
-guidelines:
-
-If you have a question about Perl 6 syntax or the right way to
-approach a problem using Perl 6, you probably want the
-C<perl6-users@perl.org> mailing list. This list is primarily
-for the people who want to I<use> Perl 6 to write programs, as
-opposed to those who are implementing or developing the Perl 6
-language itself.
-
-Questions about the Rakudo compiler for Parrot and the Parrot
-compiler tools can go to C<perl6-compiler@perl.org>. Discussion
-about Parrot itself generally takes place on
-C<parrot-dev@lists.parrot.org>.
-
-The Rakudo and Parrot development teams tend to hang out on IRC a fair
-bit, either on C<irc.freenode.net/#perl6> or C<irc.perl.org/#parrot>.
-
-Rakudo's official web site is L<http://rakudo.org/>, where you can
-find useful information for developers and users alike. There's also
-a Parrot blog at L<http://parrotblog.org/>, most Perl 6 related news is
-assembled at L<http://planetsix.perl.org/>. Links to many other
-resources can be found on L<http://perl6.org/>.
-
-=head2 Reporting bugs
-
-Bug reports should be sent to C<rakudobug@perl.org> with the moniker
-[BUG] (including the brackets) at the start of the subject so that
-it gets appropriately tagged in the RT system (https://rt.perl.org/rt3/).
-Please include or attach any sample source code that exhibits the
-bug, and include either the release name/date or the git commit
-identifier. You find that information in the output from
-C<perl6 --version> (or in the first line of C<git log>, if Rakudo
-fails to build). There's no need to cc: the perl6-compiler
-mailing list, as the RT system will handle this on its own.
-
-=head2 Submitting patches
-
-If you have a patch that fixes a bug or adds a new feature, please
-submit it to C<rakudobug@perl.org> with the moniker [PATCH]
-(including the brackets) at the start of the subject line. We'll
-generally accept patches in any form if we can get them to work,
-but unified diff from the C<git> command is greatly preferred. In
-general this means that in the C<rakudo> directory you make your
-changes, and then type
-
- git commit -m 'Your commit message' changed/filename.pm
- git format-patch HEAD^
-
-This will generate a file called C<001-your-commit-message.patch>, or more of
-them if you made multiple commits; please attach these to your email.
-
-(Note to the maintainers: you can apply these patches with the
-C<git-am -s> command; it preserves meta information like author).
-
-Other ways to create and submit patches are discussed here:
-L<http://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.
-
-=head2 How the compiler works
-
-See F<docs/compiler_overview.pod>.
-
-=head1 AUTHOR
-
-Patrick Michaud C<pmichaud@pobox.com> is the primary author and
-maintainer for Rakudo Perl 6 on Parrot. See F<CREDITS> for further
-authors.
-
-=cut
-
-## vim: expandtab sw=4 ft=pod tw=70:
+ $ cd rakudo
+ $ git pull
+
+ Once you have an updated copy of Rakudo, build it as follows:
+
+ $ cd rakudo
+ $ perl Configure.pl --gen-parrot
+ $ make
+
+ This will create a "perl6" or "perl6.exe" executable in the current
+ (rakudo) directory. Note that if you have multiple (Perl 5) "perl"s in
+ your path, you may need to use a fully qualified path to the appropriate
+ executable (or update your PATH environment variable).
+
+ Programs can then be run from the build directory using a command like:
+
+ $ ./perl6 hello.pl
+
+ Important: To run Rakudo from outside the build directory, you must run
+
+ $ make install
+
+ This will install the "perl6" (or "perl6.exe" binary on windows) into
+ the "parrot_install/bin" directory locally, no additional root
+ privileges necessary.
+
+ The "--gen-parrot" above option tells Configure.pl to automatically
+ download and build the most appropriate version of Parrot into a local
+ "parrot/" subdirectory, install that Parrot into the "parrot_install/"
+ subdirectory, and use that for building Rakudo. It's okay to use the
+ "--gen-parrot" option on later invocations of Configure.pl; the
+ configure system will re-build Parrot only if a newer version is needed
+ for whatever version of Rakudo you're working with.
+
+ You can use "--parrot-config=/path/to/parrot_config" instead of
+ "--gen-parrot" to use an already installed Parrot for building Rakudo.
+ This installed Parrot must include its development environment;
+ typically this is done via Parrot's "make install" target or by
+ installing prebuilt "parrot-devel" and/or "libparrot-dev" packages. The
+ version of the already installed Parrot must satisfy a minimum specified
+ by the Rakudo being built -- Configure.pl will verify this for you.
+ Released versions of Rakudo always build against the latest release of
+ Parrot; checkouts of the HEAD revision from github often require a
+ version of Parrot that is newer than the most recent Parrot monthly
+ release.
+
+ Once built, Rakudo's "make install" target will install Rakudo and its
+ libraries into the Parrot installation that was used to create it. Until
+ this step is performed, the "perl6" executable created by "make" above
+ can only be reliably run from the root of Rakudo's build directory.
+ After "make install" is performed, the installed executable can be run
+ from any directory (as long as the Parrot installation that was used to
+ create it remains intact).
+
+ If the Rakudo compiler is invoked without an explicit script to run, it
+ enters a small interactive mode that allows Perl 6 statements to be
+ executed from the command line.
+
+ Build/install problems
+ Occasionally, there may be problems when building/installing Rakudo.
+ Make sure you have a backup of any custom changes you have done to the
+ source tree before performing the following steps:
+
+ Try to remove the "parrot_install" subdirectory:
+
+ $ cd rakudo
+ $ rm -r parrot_install
+ $ git pull
+ $ perl Configure.pl --gen-parrot
+ $ make
+
+ Or, in case you are really stuck, start with a fresh source tree:
+
+ $ rm -r rakudo
+ $ git clone git://github.com/rakudo/rakudo.git
+
+ Running the test suite
+ Entering "make test" will run a small test suite that comes bundled with
+ Rakudo. This is a simple suite of tests, designed to make sure that the
+ Rakudo compiler is basically working and that it's capable of running a
+ simple test harness.
+
+ Running "make spectest" will import the official Perl 6 test suite from
+ the Pugs repository <http://svn.pugscode.org/pugs/t/spec/> and run all
+ of these tests that are currently known to pass.
+
+ If you want to automatically submit the results of your spectest run to
+ a central server, use "make spectest_smolder" instead. You need the
+ Perl 5 module TAP::Harness::Archive and an active internet connection
+ for that. The smoke results are collected at
+ <http://smolder.plusthree.com/app/public_projects/details/18>.
+
+ At present we do not have any plans to directly store the official test
+ suite as part of the Rakudo/Parrot repository, but will continue to
+ fetch it from the Pugs repository.
+
+ You can also use "make" to run an individual test from the command line:
+
+ $ make t/spec/S29-str/ucfirst.t
+ t/spec/S29-str/ucfirst.rakudo ..
+ 1..4
+ ok 1 - simple
+ ok 2 - empty string
+ ok 3 - # SKIP unicode
+ ok 4 - # SKIP unicode
+ # FUDGED!
+ ok
+ All tests successful.
+ Files=1, Tests=4, 1 wallclock secs ( 0.02 usr 0.00 sys + 0.57 cusr 0.06 csys = 0.65 CPU)
+ Result: PASS
+
+ If you want to run the tests in parallel, you need to install a fairly
+ recent version of the Perl 5 module Test::Harness (3.16 works for sure).
+
+ Where to get help or answers to questions
+ There are several mailing lists, IRC channels, and wikis available with
+ help for Perl 6 and Rakudo on Parrot. Figuring out the right one to use
+ is often the biggest battle. Here are some rough guidelines:
+
+ If you have a question about Perl 6 syntax or the right way to approach
+ a problem using Perl 6, you probably want the "perl6-users@perl.org"
+ mailing list. This list is primarily for the people who want to *use*
+ Perl 6 to write programs, as opposed to those who are implementing or
+ developing the Perl 6 language itself.
+
+ Questions about the Rakudo compiler for Parrot and the Parrot compiler
+ tools can go to "perl6-compiler@perl.org". Discussion about Parrot
+ itself generally takes place on "parrot-dev@lists.parrot.org".
+
+ The Rakudo and Parrot development teams tend to hang out on IRC a fair
+ bit, either on "irc.freenode.net/#perl6" or "irc.perl.org/#parrot".
+
+ Rakudo's official web site is <http://rakudo.org/>, where you can find
+ useful information for developers and users alike. There's also a Parrot
+ blog at <http://parrotblog.org/>, most Perl 6 related news is assembled
+ at <http://planetsix.perl.org/>. Links to many other resources can be
+ found on <http://perl6.org/>.
+
+ Reporting bugs
+ Bug reports should be sent to "rakudobug@perl.org" with the moniker
+ [BUG] (including the brackets) at the start of the subject so that it
+ gets appropriately tagged in the RT system (https://rt.perl.org/rt3/).
+ Please include or attach any sample source code that exhibits the bug,
+ and include either the release name/date or the git commit identifier.
+ You find that information in the output from "perl6 --version" (or in
+ the first line of "git log", if Rakudo fails to build). There's no need
+ to cc: the perl6-compiler mailing list, as the RT system will handle
+ this on its own.
+
+ Submitting patches
+ If you have a patch that fixes a bug or adds a new feature, please
+ submit it to "rakudobug@perl.org" with the moniker [PATCH] (including
+ the brackets) at the start of the subject line. We'll generally accept
+ patches in any form if we can get them to work, but unified diff from
+ the "git" command is greatly preferred. In general this means that in
+ the "rakudo" directory you make your changes, and then type
+
+ git commit -m 'Your commit message' changed/filename.pm
+ git format-patch HEAD^
+
+ This will generate a file called "001-your-commit-message.patch", or
+ more of them if you made multiple commits; please attach these to your
+ email.
+
+ (Note to the maintainers: you can apply these patches with the "git-am
+ -s" command; it preserves meta information like author).
+
+ Other ways to create and submit patches are discussed here:
+ <http://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.
+
+ How the compiler works
+ See docs/compiler_overview.pod.
+
+AUTHOR
+ Patrick Michaud "pmichaud@pobox.com" is the primary author and
+ maintainer for Rakudo Perl 6 on Parrot. See CREDITS for further authors.

0 comments on commit fe29cde

Please sign in to comment.