# New Ticket Created by Jan Ingvoldstad # Please include the string: [perl #76626] # in the subject line of all future correspondence about this issue. # <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=76626 >
>From 5b4ca87007d4b7b6bc08ff2e57d110b7b55c1477 Mon Sep 17 00:00:00 2001 From: Jan Ingvoldstad <jani+perl6-2...@ifi.uio.no> Date: Wed, 21 Jul 2010 14:49:09 +0200 Subject: [PATCH] Generate plaintext README from README.pod --- README | 217 ----------------------------------------------------- README.pod | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++ build/Makefile.in | 9 ++- 3 files changed, 224 insertions(+), 219 deletions(-) delete mode 100644 README create mode 100644 README.pod diff --git a/README b/README deleted file mode 100644 index 6a9e0c2..0000000 --- a/README +++ /dev/null @@ -1,217 +0,0 @@ -=head1 Rakudo Perl 6 - -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. - -=head2 Installing with your package manager - -There are binary packages available for these operating systems: -various Windows versions, FreeBSD, Arch Linx, Fedora, OpenSuSE, CRUX. - -Please refer to L<http://rakudo.org/how-to-get-rakudo> for links to -the individual packages. - -=head2 Build requirements (Installing from source) - -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. - -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 -may not work properly. - -As an example, on Debian GNU/Linux or Ubuntu Linux the necessary -components for building Rakudo can be installed via the command - - aptitude install build-essential libicu-dev subversion - -(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. - -=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 github by visiting http://github.com/rakudo/rakudo/tree/master -and clicking "Download". Then unpack the tarball or zip. - -Once you have a 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. 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 "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. Each line entered is treated -as a separate compilation unit, however (which means that subroutines -are preserved after they are defined, but variables are not). - -=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-us...@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-compi...@perl.org>. Discussion -about Parrot itself generally takes place on -C<parrot-...@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-projects.org/>. - -=head2 Reporting bugs - -Bug reports should be sent to C<rakudo...@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 identifier in the first output line of -the C<git log> command. 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<rakudo...@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<languages/rakudo/> directory you make your -changes, and then type - - git commit -m 'Your commit message' - 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> 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<pmich...@pobox.com> is the primary author and -maintainer for Rakudo Perl 6 on Parrot. - -=cut - -## vim: expandtab sw=4 ft=pod tw=70: diff --git a/README.pod b/README.pod new file mode 100644 index 0000000..6a9e0c2 --- /dev/null +++ b/README.pod @@ -0,0 +1,217 @@ +=head1 Rakudo Perl 6 + +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. + +=head2 Installing with your package manager + +There are binary packages available for these operating systems: +various Windows versions, FreeBSD, Arch Linx, Fedora, OpenSuSE, CRUX. + +Please refer to L<http://rakudo.org/how-to-get-rakudo> for links to +the individual packages. + +=head2 Build requirements (Installing from source) + +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. + +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 +may not work properly. + +As an example, on Debian GNU/Linux or Ubuntu Linux the necessary +components for building Rakudo can be installed via the command + + aptitude install build-essential libicu-dev subversion + +(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. + +=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 github by visiting http://github.com/rakudo/rakudo/tree/master +and clicking "Download". Then unpack the tarball or zip. + +Once you have a 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. 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 "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. Each line entered is treated +as a separate compilation unit, however (which means that subroutines +are preserved after they are defined, but variables are not). + +=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-us...@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-compi...@perl.org>. Discussion +about Parrot itself generally takes place on +C<parrot-...@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-projects.org/>. + +=head2 Reporting bugs + +Bug reports should be sent to C<rakudo...@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 identifier in the first output line of +the C<git log> command. 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<rakudo...@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<languages/rakudo/> directory you make your +changes, and then type + + git commit -m 'Your commit message' + 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> 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<pmich...@pobox.com> is the primary author and +maintainer for Rakudo Perl 6 on Parrot. + +=cut + +## vim: expandtab sw=4 ft=pod tw=70: diff --git a/build/Makefile.in b/build/Makefile.in index c19af17..b8c0729 100644 --- a/build/Makefile.in +++ b/build/Makefile.in @@ -241,7 +241,9 @@ PMC_SOURCES = \ OPS_SOURCE = perl6.ops -DOCS = README CREDITS LICENSE docs/* +README = README.pod README + +DOCS = $(README) CREDITS LICENSE docs/* CLEANUPS = \ *.manifest \ @@ -281,7 +283,7 @@ HARNESS_WITH_FUDGE_JOBS = $(HARNESS_WITH_FUDGE) --jobs STAGESTATS = @stagestats@ # the default target, TODO: make libraries in 'lib' a variable. -all: $(PERL6_EXE) Test.pir lib/DateTime/strftime.pir +all: $(PERL6_EXE) $(README) Test.pir lib/DateTime/strftime.pir # the install target install: all @@ -308,6 +310,9 @@ install: all xmas: $(PERL6_EXE) +README: README.pod + pod2text README.pod > README + ## targets for building a standalone perl6. $(PERL6_EXE): $(PERL6_PBC) $(PBC_TO_EXE) $(PERL6_PBC) -- 1.5.4.3
