Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 253 lines (196 sloc) 10.653 kB
5c404cb [README] tweak the build and install instructions
Martin Berends authored
1 =head1 Rakudo Perl 6
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
2
5c404cb [README] tweak the build and install instructions
Martin Berends authored
3 This is Rakudo Perl, a Perl 6 compiler for the Parrot virtual machine.
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
4
6fc7264 @pmichaud Update copyright date.
pmichaud authored
5 Rakudo Perl is Copyright (C) 2008-2010, The Perl Foundation.
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
6 Rakudo Perl is distributed under the terms of the Artistic License 2.0.
7 For more details, see the full text of the license in the file LICENSE.
a93b241 @moritz [README] update to reflect current status
moritz authored
8
ec2f831 @Daenyth README: Added section about Rakudo packages, and a link to the Arch L…
Daenyth authored
9 =head2 Installing with your package manager
10
11 Rakudo is currently available for Arch Linux users in the AUR at
924e4f3 mention FreeBSD port in README
Moritz Lenz authored
12 (L<http://aur.archlinux.org/packages.php?ID=29068>).
ec2f831 @Daenyth README: Added section about Rakudo packages, and a link to the Arch L…
Daenyth authored
13
924e4f3 mention FreeBSD port in README
Moritz Lenz authored
14 FreeBSD users may find the Rakudo port at
15 L<http://rakudoport.sourceforge.net/> useful.
16
17 Windows users can download binary builds from
1f16505 @moritz [README] mention win32 builds
moritz authored
18 L<http://sourceforge.net/projects/parrotwin32/files/> and need the
19 I<parrotwin32 setup> and the matching version of
20 I<parrot-rakudo addon>.
21
ec2f831 @Daenyth README: Added section about Rakudo packages, and a link to the Arch L…
Daenyth authored
22 =head2 Build requirements (Installing from source)
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
23
48f6de1 @moritz remove trailing ws in README
moritz authored
24 For building Rakudo you need at least a C compiler, a C<make> utility,
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
25 and Perl 5.8 or newer. To automatically obtain and build Parrot
26 or the spectest suite you may also need a subversion (svn) client.
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
27
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
28 In order to fully support Unicode, you'll also want to have the
48f6de1 @moritz remove trailing ws in README
moritz authored
29 ICU library installed (L<http://site.icu-project.org/>).
30 Rakudo can run without ICU, but some Unicode-related features
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
31 may not work properly.
32
48f6de1 @moritz remove trailing ws in README
moritz authored
33 As an example, on Debian GNU/Linux or Ubuntu Linux the necessary
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
34 components for building Rakudo can be installed via the command
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
35
6ba717c [README] the package is called libicu-dev in lenny, celeon++
Moritz Lenz authored
36 aptitude install build-essential libicu-dev subversion
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
37
38 (Perl is installed by default already). To enable parallel testing you
93f2fce @moritz [README] document TEST_JOBS, KyleHa++
moritz authored
39 also need the CPAN module L<Test::Harness> in version 3.16 or newer;
40 you can control the number of parallel jobs with the C<TEST_JOBS>
41 environment variable.
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
42
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
43 =head2 Building and invoking Rakudo
a93b241 @moritz [README] update to reflect current status
moritz authored
44
f4d2486 @pmichaud More README improvements.
pmichaud authored
45 Because Rakudo is under rapid development, we generally recommend
46 downloading Rakudo directly from github and building from there:
a93b241 @moritz [README] update to reflect current status
moritz authored
47
48 $ git clone git://github.com/rakudo/rakudo.git
f4d2486 @pmichaud More README improvements.
pmichaud authored
49
48f6de1 @moritz remove trailing ws in README
moritz authored
50 If you don't have git installed, you can get a tarball or zip of Rakudo
51 from github by visiting http://github.com/rakudo/rakudo/tree/master
f4d2486 @pmichaud More README improvements.
pmichaud authored
52 and clicking "Download". Then unpack the tarball or zip.
53
54 Once you have a copy of Rakudo, build it as follows:
55
56 $ cd rakudo
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
57 $ perl Configure.pl --gen-parrot
58 $ make
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
59
fd0a184 @mberends [alpha] update README with Subversion->Github moves, tweak test_summa…
mberends authored
60 Note: this no longer works. See "Loss of the Subversion Repositories"
61 below for a workaround.
62
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
63 This will create a "perl6" or "perl6.exe" executable in the
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
64 current (rakudo) directory. Programs can then be run from
65 the build directory using a command like:
66
67 $ ./perl6 hello.pl
a93b241 @moritz [README] update to reflect current status
moritz authored
68
48f6de1 @moritz remove trailing ws in README
moritz authored
69 The C<--gen-parrot> above option tells Configure.pl to automatically
70 download and build the most appropriate version of Parrot into
81e46d5 @pmichaud Update the README a bit more to explain build+installation process.
pmichaud authored
71 a local "parrot/" subdirectory, install that Parrot into
72 the "parrot_install/" subdirectory, and use that for building
48f6de1 @moritz remove trailing ws in README
moritz authored
73 Rakudo. It's okay to use the C<--gen-parrot> option on later
74 invocations of Configure.pl; the configure system will re-build
75 Parrot only if a newer version is needed for whatever version
81e46d5 @pmichaud Update the README a bit more to explain build+installation process.
pmichaud authored
76 of Rakudo you're working with.
77
5c404cb [README] tweak the build and install instructions
Martin Berends authored
78 You can use C<--parrot-config=/path/to/parrot_config> instead
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
79 of C<--gen-parrot> to use an already installed Parrot for building
80 Rakudo. This installed Parrot must include its development
c0ba847 @moritz [README] "make install" in parrot is now sufficient
moritz authored
81 environment; typically this is done via Parrot's C<make install>
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
82 target or by installing prebuilt C<parrot-devel> and/or C<libparrot-dev>
83 packages. The version of the already installed Parrot must satisfy a
84 minimum specified by the Rakudo being built -- Configure.pl will
48f6de1 @moritz remove trailing ws in README
moritz authored
85 verify this for you. Released versions of Rakudo always build
86 against the latest release of Parrot; checkouts of the HEAD revision
87 from github often require a version of Parrot that is newer than
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
88 the most recent Parrot monthly release.
89
48f6de1 @moritz remove trailing ws in README
moritz authored
90 Once built, Rakudo's C<make install> target will install Rakudo
91 and its libraries into the Parrot installation that was used to
92 create it. Until this step is performed, the "perl6" executable
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
93 created by C<make> above can only be reliably run from the root of
94 Rakudo's build directory. After C<make install> is performed
48f6de1 @moritz remove trailing ws in README
moritz authored
95 the executable can be run from any directory (as long as the
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
96 Parrot installation that was used to create it remains intact).
5c404cb [README] tweak the build and install instructions
Martin Berends authored
97
2dceda5 @particle [rakudo]: conversion from 'perl6' to 'Rakudo'
particle authored
98 If the Rakudo compiler is invoked without an explicit script to
48f6de1 @moritz remove trailing ws in README
moritz authored
99 run, it enters a small interactive mode that allows Perl 6 statements
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
100 to be executed from the command line. Each line entered is treated
a827258 @moritz [rakudo] fixed some typos in docs and actions.pm, added small clarifi…
moritz authored
101 as a separate compilation unit, however (which means that subroutines
102 are preserved after they are defined, but variables are not).
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
103
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
104 =head2 Running the test suite
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
105
48f6de1 @moritz remove trailing ws in README
moritz authored
106 Entering C<make test> will run a small test suite that comes
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
107 bundled with Rakudo. This is a simple suite of tests, designed
2dceda5 @particle [rakudo]: conversion from 'perl6' to 'Rakudo'
particle authored
108 to make sure that the Rakudo compiler is basically working and that
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
109 it's capable of running a simple test harness.
c13e960 @pmichaud [Perl6]:
pmichaud authored
110
0c7475a [README] changed some quotes to C<...> POD markup
Moritz Lenz authored
111 Running C<make spectest> will import the official Perl 6 test suite
48f6de1 @moritz remove trailing ws in README
moritz authored
112 from the Pugs repository L<http://svn.pugscode.org/pugs/t/spec/>
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
113 and run all of these tests that are currently known to pass.
b451480 @pmichaud [rakudo]:
pmichaud authored
114
836c8c8 @moritz mention spectest_smolder in README and ChangeLog
moritz authored
115 If you want to automatically submit the results of your spectest run
116 to a central server, use C<make spectest_smolder> instead. You need
117 the Perl 5 module L<TAP::Harness::Archive> and an active internet
118 connection for that. The smoke results are collected at
119 L<http://smolder.plusthree.com/app/public_projects/details/18>.
120
b451480 @pmichaud [rakudo]:
pmichaud authored
121 At present we do not have any plans to directly store the
2dceda5 @particle [rakudo]: conversion from 'perl6' to 'Rakudo'
particle authored
122 official test suite as part of the Rakudo/Parrot repository,
123 but will continue to fetch it from the Pugs repository.
bcd1fc0 @pmichaud [perl6]
pmichaud authored
124
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
125 You can also use "make" to run an individual test from the command line:
5bdb16d @moritz [rakudo] Update README with instructions on how to run individual tests.
moritz authored
126
127 $ make t/spec/S29-str/ucfirst.t
48f6de1 @moritz remove trailing ws in README
moritz authored
128 t/spec/S29-str/ucfirst.rakudo ..
5bdb16d @moritz [rakudo] Update README with instructions on how to run individual tests.
moritz authored
129 1..4
130 ok 1 - simple
131 ok 2 - empty string
132 ok 3 - # SKIP unicode
133 ok 4 - # SKIP unicode
134 # FUDGED!
135 ok
136 All tests successful.
137 Files=1, Tests=4, 1 wallclock secs ( 0.02 usr 0.00 sys + 0.57 cusr 0.06 csys = 0.65 CPU)
138 Result: PASS
139
27f0c01 @moritz document requirements for parallel testing
moritz authored
140 If you want to run the tests in parallel, you need to install a
141 fairly recent version of the Perl 5 module L<Test::Harness> (3.16
142 works for sure).
143
fd0a184 @mberends [alpha] update README with Subversion->Github moves, tweak test_summa…
mberends authored
144 =head3 Loss of the Subversion Repositories
145
146 Since early 2010, Parrot and the Perl 6 test suite have moved from their
147 respective Subversion repositories to Github. The Subversion servers
148 are offline, so Rakudo's Configure.pl --gen-parrot and make testable
149 procedures in Rakudo/alpha no longer work. Patches are welcome to adapt
150 them to Git. In the meantime those wanting to build Rakudo/alpha should
151 download a tarball from https://github.com/rakudo/rakudo/downloads or
152 manually performs steps such as the following.
153
154 git clone git://github.com/rakudo/rakudo.git alpha
155 cd alpha
156 git checkout -b alpha --track remotes/origin/alpha
157 # The last Parrot 2.0.0 revision on which Rakudo/alpha was developed
158 # is r43487 from https://svn.parrot.org/parrot/trunk (now offline)
159 # which mapped to commit 8ebe2eaef15fc7724d67b953e7886f5d3db388ea
160 # according to the git log from https://github.com/parrot/parrot.
161 git clone git://github.com/parrot/parrot.git parrot
162 cd parrot
163 git reset --hard 8ebe2eaef15fc7724d67b953e7886f5d3db388ea
164 perl Configure.pl --prefix=`cd ..;pwd`/parrot_install
165 make install # Parrot
166 cd ..
167 perl Configure.pl --parrot-config=parrot_install/bin/parrot_config
168 make install # Rakudo
169 # The last Perl 6 spec tests on Rakudo/alpha were rev 29188 from
170 # http://svn.pugscode.org/pugs/t/spec (now offline) which mapped to
171 # commit 99adbfb2c7ddf7837994d59c48e18aafaee666ee according to the
172 # git log from https://github.com/perl6/roast.
173 git clone git://github.com/perl6/roast t/spec
174 cd t/spec
175 git reset --hard 99adbfb2c7ddf7837994d59c48e18aafaee666ee
176 cd ../..
177 # Optionally do some spectesting and benchmarking
178 time perl tools/test_summary.pl --timing
179
61781cb @pmichaud [perl6]:
pmichaud authored
180 =head2 Where to get help or answers to questions
181
182 There are several mailing lists, IRC channels, and wikis available
0d52048 @moritz [README] spell "Perl 6" with non-breaking space
moritz authored
183 with help for Perl 6 and Rakudo on Parrot. Figuring out the right
61781cb @pmichaud [perl6]:
pmichaud authored
184 one to use is often the biggest battle. Here are some rough
185 guidelines:
186
0d52048 @moritz [README] spell "Perl 6" with non-breaking space
moritz authored
187 If you have a question about Perl 6 syntax or the right way to
188 approach a problem using Perl 6, you probably want the
61781cb @pmichaud [perl6]:
pmichaud authored
189 C<perl6-users@perl.org> mailing list. This list is primarily
0d52048 @moritz [README] spell "Perl 6" with non-breaking space
moritz authored
190 for the people who want to I<use> Perl 6 to write programs, as
191 opposed to those who are implementing or developing the Perl 6
61781cb @pmichaud [perl6]:
pmichaud authored
192 language itself.
193
2dceda5 @particle [rakudo]: conversion from 'perl6' to 'Rakudo'
particle authored
194 Questions about the Rakudo compiler for Parrot and the Parrot
61781cb @pmichaud [perl6]:
pmichaud authored
195 compiler tools can go to C<perl6-compiler@perl.org>. Discussion
a93b241 @moritz [README] update to reflect current status
moritz authored
196 about Parrot itself generally takes place on
197 C<parrot-dev@lists.parrot.org>.
61781cb @pmichaud [perl6]:
pmichaud authored
198
2cf2dfe @pmichaud Update README with latest news on building Rakudo.
pmichaud authored
199 The Rakudo and Parrot development teams tend to hang out on IRC a fair
200 bit, either on C<irc.freenode.net/#perl6> or C<irc.perl.org/#parrot>.
61781cb @pmichaud [perl6]:
pmichaud authored
201
79aba97 @moritz [README] reworked paragraph on rakudo.org
moritz authored
202 Rakudo's official web site is L<http://rakudo.org/>, where you can
203 find useful information for developers and users alike. There's also
204 a Parrot blog at L<http://parrotblog.org/>, most Perl 6 related news is
a5aea15 @moritz mention perl6-projects.org in README
moritz authored
205 assembled at L<http://planetsix.perl.org/>. Links to many other
206 resources can be found on L<http://perl6-projects.org/>.
61781cb @pmichaud [perl6]:
pmichaud authored
207
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
208 =head2 Reporting bugs
bcd1fc0 @pmichaud [perl6]
pmichaud authored
209
50e3524 @pmichaud [rakudo]:
pmichaud authored
210 Bug reports should be sent to C<rakudobug@perl.org> with the moniker
61781cb @pmichaud [perl6]:
pmichaud authored
211 [BUG] (including the brackets) at the start of the subject so that
a827258 @moritz [rakudo] fixed some typos in docs and actions.pm, added small clarifi…
moritz authored
212 it gets appropriately tagged in the RT system (https://rt.perl.org/rt3/).
61781cb @pmichaud [perl6]:
pmichaud authored
213 Please include or attach any sample source code that exhibits the
ab367f6 @moritz [README] information on how to obtain git SHA-1
moritz authored
214 bug, and include either the release name/date or the git commit
48f6de1 @moritz remove trailing ws in README
moritz authored
215 identifier. You find that identifier in the first output line of
c9d76a9 @pmichaud Formatting fix.
pmichaud authored
216 the C<git log> command. There's no need to cc: the perl6-compiler
61781cb @pmichaud [perl6]:
pmichaud authored
217 mailing list, as the RT system will handle this on its own.
c13e960 @pmichaud [Perl6]:
pmichaud authored
218
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
219 =head2 Submitting patches
c13e960 @pmichaud [Perl6]:
pmichaud authored
220
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
221 If you have a patch that fixes a bug or adds a new feature, please
50e3524 @pmichaud [rakudo]:
pmichaud authored
222 submit it to C<rakudobug@perl.org> with the moniker [PATCH]
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
223 (including the brackets) at the start of the subject line. We'll
224 generally accept patches in any form if we can get them to work,
a93b241 @moritz [README] update to reflect current status
moritz authored
225 but unified diff from the C<git> command is greatly preferred. In
226 general this means that in the C<languages/rakudo/> directory you make your
227 changes, and then type
e9a06c1 @petdance Added explanation of how to get Rakudo without git. Minor punctuation…
petdance authored
228
a93b241 @moritz [README] update to reflect current status
moritz authored
229 git commit -m 'Your commit message'
0cdcc88 fixes typo in README file, 'git-format-patch' is actually 'git format…
Bob Kuo authored
230 git format-patch HEAD^
a93b241 @moritz [README] update to reflect current status
moritz authored
231
232 This will generate a file called C<001-your-commit-message.patch>, or more of
233 them if you made multiple commits; please attach these to your email.
234
235 (Note to the maintainers: you can apply these patches with the
236 C<git-am> command; it preserves meta information like author).
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
237
beac378 @moritz [README] link to Chris Dolan's "steps to create a patch".
moritz authored
238 Other ways to create and submit patches are discussed here:
239 L<http://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.
240
11c9755 @pmichaud [perl6]: Update the README file.
pmichaud authored
241 =head2 How the compiler works
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
242
61781cb @pmichaud [perl6]:
pmichaud authored
243 See F<docs/compiler_overview.pod>.
45bbd9c @coke [perl6] provide mechanism to get a copy of the official test suite. F…
coke authored
244
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
245 =head1 AUTHOR
246
e9a06c1 @petdance Added explanation of how to get Rakudo without git. Minor punctuation…
petdance authored
247 Patrick Michaud C<pmichaud@pobox.com> is the primary author and
5c404cb [README] tweak the build and install instructions
Martin Berends authored
248 maintainer for Rakudo Perl 6 on Parrot.
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
249
250 =cut
f34a54a @particle [perl6] svn and vim metadata, whitespace cleanup
particle authored
251
a93b241 @moritz [README] update to reflect current status
moritz authored
252 ## vim: expandtab sw=4 ft=pod tw=70:
Something went wrong with that request. Please try again.