Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 223 lines (172 sloc) 10.089 kB
fe29cde @coke README should be in text, not POD.
coke authored
1 Rakudo Perl 6
2 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
3
fe29cde @coke README should be in text, not POD.
coke authored
4 Rakudo Perl is Copyright (C) 2008-2010, The Perl Foundation. Rakudo Perl
5 is distributed under the terms of the Artistic License 2.0. For more
6 details, see the full text of the license in the file LICENSE.
1b6cbf6 @pmichaud First draft of a perl 6 parser in p6 rules and pir.
pmichaud authored
7
fe29cde @coke README should be in text, not POD.
coke authored
8 Installing with your package manager
9 There are binary packages available for these operating systems: various
10 Windows versions, FreeBSD, Arch Linx, Fedora, OpenSuSE, CRUX.
a93b241 @moritz [README] update to reflect current status
moritz authored
11
fe29cde @coke README should be in text, not POD.
coke authored
12 Please refer to <http://rakudo.org/how-to-get-rakudo> for links to the
13 individual packages.
ec2f831 @Daenyth README: Added section about Rakudo packages, and a link to the Arch L…
Daenyth authored
14
fe29cde @coke README should be in text, not POD.
coke authored
15 Build requirements (Installing from source)
16 For building Rakudo you need at least a C compiler, a "make" utility,
17 and Perl 5.8 or newer. To automatically obtain and build Parrot or the
18 spectest suite you may also need a subversion (svn) client.
ec2f831 @Daenyth README: Added section about Rakudo packages, and a link to the Arch L…
Daenyth authored
19
fe29cde @coke README should be in text, not POD.
coke authored
20 In order to fully support Unicode, you'll also want to have the ICU
21 library installed (<http://site.icu-project.org/>). Rakudo can run
22 without ICU, but some Unicode-related features do not work properly.
1f16505 @moritz [README] mention win32 builds
moritz authored
23
fe29cde @coke README should be in text, not POD.
coke authored
24 As an example, on Debian GNU/Linux or Ubuntu Linux, the necessary
25 components for building Rakudo can be installed via the command
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
26
fe29cde @coke README should be in text, not POD.
coke authored
27 aptitude install build-essential libicu-dev subversion
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
28
fe29cde @coke README should be in text, not POD.
coke authored
29 (Perl is installed by default already). To enable parallel testing you
30 also need the CPAN module Test::Harness in version 3.16 or newer; you
31 can control the number of parallel jobs with the "TEST_JOBS" environment
32 variable.
42d8ebd @pmichaud Some README refactorings.
pmichaud authored
33
fe29cde @coke README should be in text, not POD.
coke authored
34 Building and invoking Rakudo
35 Because Rakudo is under rapid development, we generally recommend
36 downloading Rakudo directly from github and building from there:
37
38 $ git clone git://github.com/rakudo/rakudo.git
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
39
fe29cde @coke README should be in text, not POD.
coke authored
40 If you don't have git installed, you can get a tarball or zip of Rakudo
41 from <http://github.com/rakudo/rakudo/downloads>. Then unpack the
42 tarball or zip.
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
43
fe29cde @coke README should be in text, not POD.
coke authored
44 If you already have cloned Rakudo from github, you can get (pull) the
45 most recent version from github like this:
705ecc2 @moritz [README] paragraph on build dependencies
moritz authored
46
fe29cde @coke README should be in text, not POD.
coke authored
47 $ cd rakudo
48 $ git pull
49
50 Once you have an updated copy of Rakudo, build it as follows:
51
52 $ cd rakudo
53 $ perl Configure.pl --gen-parrot
54 $ make
55
56 This will create a "perl6" or "perl6.exe" executable in the current
57 (rakudo) directory. Note that if you have multiple (Perl 5) "perl"s in
58 your path, you may need to use a fully qualified path to the appropriate
59 executable (or update your PATH environment variable).
60
61 Programs can then be run from the build directory using a command like:
62
63 $ ./perl6 hello.pl
64
65 Important: To run Rakudo from outside the build directory, you must run
66
67 $ make install
68
69 This will install the "perl6" (or "perl6.exe" binary on windows) into
70 the "parrot_install/bin" directory locally, no additional root
71 privileges necessary.
72
73 The "--gen-parrot" above option tells Configure.pl to automatically
74 download and build the most appropriate version of Parrot into a local
75 "parrot/" subdirectory, install that Parrot into the "parrot_install/"
76 subdirectory, and use that for building Rakudo. It's okay to use the
77 "--gen-parrot" option on later invocations of Configure.pl; the
78 configure system will re-build Parrot only if a newer version is needed
79 for whatever version of Rakudo you're working with.
80
81 You can use "--parrot-config=/path/to/parrot_config" instead of
82 "--gen-parrot" to use an already installed Parrot for building Rakudo.
83 This installed Parrot must include its development environment;
84 typically this is done via Parrot's "make install" target or by
85 installing prebuilt "parrot-devel" and/or "libparrot-dev" packages. The
86 version of the already installed Parrot must satisfy a minimum specified
87 by the Rakudo being built -- Configure.pl will verify this for you.
88 Released versions of Rakudo always build against the latest release of
89 Parrot; checkouts of the HEAD revision from github often require a
90 version of Parrot that is newer than the most recent Parrot monthly
91 release.
92
93 Once built, Rakudo's "make install" target will install Rakudo and its
94 libraries into the Parrot installation that was used to create it. Until
95 this step is performed, the "perl6" executable created by "make" above
96 can only be reliably run from the root of Rakudo's build directory.
97 After "make install" is performed, the installed executable can be run
98 from any directory (as long as the Parrot installation that was used to
99 create it remains intact).
100
101 If the Rakudo compiler is invoked without an explicit script to run, it
102 enters a small interactive mode that allows Perl 6 statements to be
103 executed from the command line.
104
105 Build/install problems
106 Occasionally, there may be problems when building/installing Rakudo.
107 Make sure you have a backup of any custom changes you have done to the
108 source tree before performing the following steps:
109
110 Try to remove the "parrot_install" subdirectory:
111
112 $ cd rakudo
113 $ rm -r parrot_install
114 $ git pull
115 $ perl Configure.pl --gen-parrot
116 $ make
117
118 Or, in case you are really stuck, start with a fresh source tree:
119
120 $ rm -r rakudo
121 $ git clone git://github.com/rakudo/rakudo.git
122
123 Running the test suite
124 Entering "make test" will run a small test suite that comes bundled with
125 Rakudo. This is a simple suite of tests, designed to make sure that the
126 Rakudo compiler is basically working and that it's capable of running a
127 simple test harness.
128
129 Running "make spectest" will import the official Perl 6 test suite from
130 the Pugs repository <http://svn.pugscode.org/pugs/t/spec/> and run all
131 of these tests that are currently known to pass.
132
133 If you want to automatically submit the results of your spectest run to
134 a central server, use "make spectest_smolder" instead. You need the
135 Perl 5 module TAP::Harness::Archive and an active internet connection
136 for that. The smoke results are collected at
137 <http://smolder.plusthree.com/app/public_projects/details/18>.
138
139 At present we do not have any plans to directly store the official test
140 suite as part of the Rakudo/Parrot repository, but will continue to
141 fetch it from the Pugs repository.
142
143 You can also use "make" to run an individual test from the command line:
144
145 $ make t/spec/S29-str/ucfirst.t
146 t/spec/S29-str/ucfirst.rakudo ..
147 1..4
148 ok 1 - simple
149 ok 2 - empty string
150 ok 3 - # SKIP unicode
151 ok 4 - # SKIP unicode
152 # FUDGED!
153 ok
154 All tests successful.
155 Files=1, Tests=4, 1 wallclock secs ( 0.02 usr 0.00 sys + 0.57 cusr 0.06 csys = 0.65 CPU)
156 Result: PASS
157
158 If you want to run the tests in parallel, you need to install a fairly
159 recent version of the Perl 5 module Test::Harness (3.16 works for sure).
160
161 Where to get help or answers to questions
162 There are several mailing lists, IRC channels, and wikis available with
163 help for Perl 6 and Rakudo on Parrot. Figuring out the right one to use
164 is often the biggest battle. Here are some rough guidelines:
165
166 If you have a question about Perl 6 syntax or the right way to approach
167 a problem using Perl 6, you probably want the "perl6-users@perl.org"
168 mailing list. This list is primarily for the people who want to *use*
169 Perl 6 to write programs, as opposed to those who are implementing or
170 developing the Perl 6 language itself.
171
172 Questions about the Rakudo compiler for Parrot and the Parrot compiler
173 tools can go to "perl6-compiler@perl.org". Discussion about Parrot
174 itself generally takes place on "parrot-dev@lists.parrot.org".
175
176 The Rakudo and Parrot development teams tend to hang out on IRC a fair
177 bit, either on "irc.freenode.net/#perl6" or "irc.perl.org/#parrot".
178
179 Rakudo's official web site is <http://rakudo.org/>, where you can find
180 useful information for developers and users alike. There's also a Parrot
181 blog at <http://parrotblog.org/>, most Perl 6 related news is assembled
182 at <http://planetsix.perl.org/>. Links to many other resources can be
183 found on <http://perl6.org/>.
184
185 Reporting bugs
186 Bug reports should be sent to "rakudobug@perl.org" with the moniker
187 [BUG] (including the brackets) at the start of the subject so that it
188 gets appropriately tagged in the RT system (https://rt.perl.org/rt3/).
189 Please include or attach any sample source code that exhibits the bug,
190 and include either the release name/date or the git commit identifier.
191 You find that information in the output from "perl6 --version" (or in
192 the first line of "git log", if Rakudo fails to build). There's no need
193 to cc: the perl6-compiler mailing list, as the RT system will handle
194 this on its own.
195
196 Submitting patches
197 If you have a patch that fixes a bug or adds a new feature, please
198 submit it to "rakudobug@perl.org" with the moniker [PATCH] (including
199 the brackets) at the start of the subject line. We'll generally accept
200 patches in any form if we can get them to work, but unified diff from
201 the "git" command is greatly preferred. In general this means that in
202 the "rakudo" directory you make your changes, and then type
203
204 git commit -m 'Your commit message' changed/filename.pm
205 git format-patch HEAD^
206
207 This will generate a file called "001-your-commit-message.patch", or
208 more of them if you made multiple commits; please attach these to your
209 email.
210
211 (Note to the maintainers: you can apply these patches with the "git-am
212 -s" command; it preserves meta information like author).
213
214 Other ways to create and submit patches are discussed here:
215 <http://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.
216
217 How the compiler works
218 See docs/compiler_overview.pod.
219
220 AUTHOR
221 Patrick Michaud "pmichaud@pobox.com" is the primary author and
222 maintainer for Rakudo Perl 6 on Parrot. See CREDITS for further authors.
Something went wrong with that request. Please try again.