forked from rakudo/rakudo
/
README
225 lines (175 loc) · 10 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
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.
This directory contains only the Rakudo Perl 6 compiler itself; it
does not contain any of the modules, documentation, or other items
that would normally come with a full Perl 6 distribution. If you're
after more than just the bare compiler, please download the latest
Rakudo Star package from http://github.com/rakudo/star/downloads .
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 you
may also need a a git client, which is also needed for fetching the
test suite.
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.
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 git-core
(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.
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 <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 up-to-date 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.
See the manual page ("docs/running.pod") for more about command-line
options.
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 "roast" repository <http://github.com/perl6/roast/> 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.parrot.org/app/projects/smoke_reports/5>
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 roast 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.