Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 448 lines (316 sloc) 14.616 kb
d0733de @ayardley Added DESCRIPTION
ayardley authored
1 # Copyright (C) 2001-2012, Parrot Foundation.
9b4e5d0 Fixups to make parrotcode.org's autogenerated pages happier
Dan Sugalski authored
2
9d8cce4 a bit more tidying up
Michael Scott authored
3 =head1 NAME
4
5 docs/intro.pod - The Parrot Primer
9b4e5d0 Fixups to make parrotcode.org's autogenerated pages happier
Dan Sugalski authored
6
d0733de @ayardley Added DESCRIPTION
ayardley authored
7 =head1 DESCRIPTION
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
8
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
9 This document provides a gentle introduction to the Parrot virtual machine for
10 anyone considering writing code for Parrot by hand, writing a compiler that
11 targets Parrot, getting involved with Parrot development or simply wondering
12 what on earth Parrot is.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
13
d0733de @ayardley Added DESCRIPTION
ayardley authored
14 =head1 WHAT IS PARROT?
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
15
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
16 =head2 Virtual Machines
163977e @jnthn Fix POD slip-up I made in intro.pod.
jnthn authored
17
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
18 Parrot is a virtual machine. To understand what a virtual machine is, consider
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
19 what happens when you write a program in a language such as Perl, then run it
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
20 with the applicable interpreter (in the case of Perl, the perl executable).
21 First, the program you have written in a high level language is turned into
22 simple instructions, for example I<fetch the value of the variable named x>,
23 I<add 2 to this value>, I<store this value in the variable named y>, etc. A
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
24 single line of code in a high level language may be converted into tens of
25 these simple instructions. This stage is called I<compilation>.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
26
27 The second stage involves executing these simple instructions. Some languages
28 (for example, C) are often compiled to instructions that are understood by the
29 CPU and as such can be executed by the hardware. Other languages, such as Perl,
30 Python and Java, are usually compiled to CPU-independent instructions. A
31 I<virtual machine> (sometimes known as an I<interpreter>) is required to
32 execute those instructions.
33
34 While the central role of a virtual machine is to efficiently execute
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
35 instructions, it also performs a number of other functions. One of these is to
36 abstract away the details of the hardware and operating system that a program
37 is running on. Once a program has been compiled to run on a virtual machine, it
38 will run on any platform that the VM has been implemented on. VMs may also
39 provide security by allowing more fine-grained limitations to be placed on a
40 program, memory management functionality and support for high level language
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
41 features (such as objects, data structures, types, subroutines, etc).
42
43 =head2 Design goals
44
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
45 Parrot is designed with the needs of dynamically typed languages (such as Perl
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
46 and Python) in mind, and should be able to run programs written in these
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
47 languages more efficiently than VMs developed with static languages in mind
48 (JVM, .NET). Parrot is also designed to provide interoperability between
49 languages that compile to it. In theory, you will be able to write a class in
50 Perl, subclass it in Python and then instantiate and use that subclass in a Tcl
51 program.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
52
53 Historically, Parrot started out as the runtime for Perl 6. Unlike Perl 5, the
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
54 Perl 6 compiler and runtime (VM) are to be much more clearly separated. The
55 name I<Parrot> was chosen after the 2001 April Fool's Joke which had Perl and
56 Python collaborating on the next version of their languages. The name reflects
57 the intention to build a VM to run not just Perl 6, but also many other
58 languages.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
59
60
61 =head1 Parrot concepts and jargon
62
63 =head2 Instruction formats
64
65 Parrot can currently accept instructions to execute in four forms. PIR (Parrot
66 Intermediate Representation) is designed to be written by people and generated
67 by compilers. It hides away some low-level details, such as the way parameters
68 are passed to functions. PASM (Parrot Assembly) is a level below PIR - it is
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
69 still human readable/writable and can be generated by a compiler, but the
70 author has to take care of details such as calling conventions and register
1d0b9b7 fix some pods WRT 32 registers
Leopold Toetsch authored
71 allocation. PAST (Parrot Abstract Syntax Tree) enables Parrot to accept an
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
72 abstract syntax tree style input - useful for those writing compilers.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
73
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
74 All of the above forms of input are automatically converted inside Parrot to
75 PBC (Parrot Bytecode). This is much like machine code, but understood by the
76 Parrot interpreter. It is not intended to be human-readable or human-writable,
77 but unlike the other forms execution can start immediately, without the need
78 for an assembly phase. Parrot bytecode is platform independent.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
79
80 =head2 The instruction set
81
82 The Parrot instruction set includes arithmetic and logical operators, compare
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
83 and branch/jump (for implementing loops, if...then constructs, etc), finding
84 and storing global and lexical variables, working with classes and objects,
85 calling subroutines and methods along with their parameters, I/O, threads and
86 more.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
87
88 =head2 Registers and fundamental data types
89
90 The Parrot VM is register based. This means that, like a hardware CPU, it has a
91 number of fast-access units of storage called registers. There are 4 types of
92 register in Parrot: integers (I), numbers (N), strings (S) and PMCs (P). There
1d0b9b7 fix some pods WRT 32 registers
Leopold Toetsch authored
93 are N of each of these, named I0,I1,..N0.., etc. Integer registers are the
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
94 same size as a word on the machine Parrot is running on and number registers
95 also map to a native floating point type.
1d0b9b7 fix some pods WRT 32 registers
Leopold Toetsch authored
96 The amount of registers needed is determined per subroutine at compile-time.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
97
98 =head2 PMCs
99
976ec68 @allisonrandal [doc] More conversions for PMC backronym.
allisonrandal authored
100 PMC stands for Polymorphic Container. PMCs represent any complex data structure
1772034 @jhoblitt reformat all Pod files under docs with podtidy except for docs/pdds
jhoblitt authored
101 or type, including aggregate data types (arrays, hash tables, etc). A PMC can
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
102 implement its own behavior for arithmetic, logical and string operations
103 performed on it, allowing for language-specific behavior to be introduced. PMCs
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
104 can be built in to the Parrot executable or dynamically loaded when they are
105 needed.
106
107 =head2 Garbage Collection
108
aa1287e @jkeenan Small grammatical corrections in two places in POD.
jkeenan authored
109 Parrot provides garbage collection, meaning that Parrot programs do not need
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
110 to free memory explicitly; it will be freed when it is no longer in use (that
111 is, no longer referenced) whenever the garbage collector runs.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
112
113
114 =head1 Obtaining, building and testing Parrot
115
116 =head2 Where to get Parrot
117
bd7fed8 @coke docs cleanup
coke authored
118 See L<http://www.parrot.org/download> for several ways to get a recent
119 version of parrot.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
120
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
121 =head2 Building Parrot
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
122
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
123 The first step to building Parrot is to run the F<Configure.pl> program, which
124 looks at your platform and decides how Parrot should be built. This is done by
125 typing:
73dcdd6 div changes; add 99beer.pasm by Douglas Hunter
Leopold Toetsch authored
126
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
127 perl Configure.pl
b393bee Lots of updates
Dan Sugalski authored
128
bd7fed8 @coke docs cleanup
coke authored
129 Once this is complete, run the C<make> program C<Configure.pl> prompts you
130 with. When this completes, you will have a working C<parrot> executable.
7d4ba24 release 0.1.0 preparation
Leopold Toetsch authored
131
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
132 Please report any problems that you encounter while building Parrot so the
bd7fed8 @coke docs cleanup
coke authored
133 developers can fix them. You can do this by creating a login and opening
4b038fb @moritz more doc updates
moritz authored
134 a new ticket at L<https://github.com/parrot/parrot/issues/new>. Please
135 include the F<myconfig> file that was generated as part of the build
136 process and any errors that you observed.
7d4ba24 release 0.1.0 preparation
Leopold Toetsch authored
137
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
138 =head2 The Parrot test suite
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
139
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
140 Parrot has an extensive regression test suite. This can be run by typing:
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
141
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
142 make test
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
143
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
144 Substituting make for the name of the make program on your platform. The output
145 will look something like this:
b393bee Lots of updates
Dan Sugalski authored
146
fd48868 @jkeenan Remove '--running-make-test' in all its spellings per http://trac.parrot...
jkeenan authored
147 C:\Perl\bin\perl.exe t\harness --gc-debug
67c929f @ambs While discussion continues on p2, pod files should be at most
ambs authored
148 t\library\*.t t\op\*.t t\pmc\*.t t\run\*.t t\native_pbc\*.t
149 imcc\t\*\*.t t\dynpmc\*.t t\p6rules\*.t t\src\*.t t\perl\*.t
150 t\library\dumper...............ok
151 t\library\getopt_long..........ok
152 ...
153 All tests successful, 4 test and 71 subtests skipped.
154 Files=163, Tests=2719, 192 wallclock secs ( 0.00 cusr + 0.00 csys = 0.00 CPU)
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
155
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
156 It is possible that a number of tests may fail. If this is a small number, then
157 it is probably little to worry about, especially if you have the latest Parrot
fe1f244 @jkeenan Remove references to svn or svn.parrot.org. Replace with git references...
jkeenan authored
158 sources from the Git repository. However, please do not let this discourage you
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
159 from reporting test failures, using the same method as described for reporting
160 build problems.
dfbc675 Add a section on "Reporting Problems" to docs/intro.pod, and refer to
Andy Dougherty authored
161
162
d0733de @ayardley Added DESCRIPTION
ayardley authored
163 =head1 SOME SIMPLE PARROT PROGRAMS
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
164
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
165 =head2 Hello world!
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
166
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
167 Create a file called F<hello.pir> that contains the following code.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
168
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
169 =begin PIR
170
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
171 .sub main
bd7fed8 @coke docs cleanup
coke authored
172 say "Hello world!"
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
173 .end
174
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
175 =end PIR
176
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
177 Then run it by typing:
178
179 parrot hello.pir
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
180
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
181 As expected, this will display the text C<Hello world!> on the console,
bd7fed8 @coke docs cleanup
coke authored
182 followed by a new line.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
183
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
184 Let's take the program apart. C<.sub main> states that the instructions that
185 follow make up a subroutine named C<main>, until a C<.end> is encountered. The
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
186 second line contains the C<print> instruction. In this case, we are calling the
187 variant of the instruction that accepts a constant string. The assembler takes
7483031 @coke [docs]
coke authored
188 care of deciding which variant of the instruction to use for us.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
189
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
190 =head2 Using registers
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
191
bd7fed8 @coke docs cleanup
coke authored
192 We can modify hello.pir to first store the string C<Hello world!> in a
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
193 register and then use that register with the print instruction.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
194
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
195 =begin PIR
196
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
197 .sub main
bd7fed8 @coke docs cleanup
coke authored
198 $S0 = "Hello world!"
199 say $S0
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
200 .end
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
201
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
202 =end PIR
203
81e6540 @cotto [docs] PIR docs clarification, courtesy of lucs++
cotto authored
204 PIR does not allow us to set a register directly. We need to prefix the
205 register name with C<$> when referring to a register. The compiler will map $S0
206 to one of the available string registers, for example S0, and set the value.
207 This example also uses the syntactic sugar provided by the C<=> operator. C<=>
208 is simply a more readable way of using the C<set> opcode.
209
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
210 To make PIR even more readable, named registers can be used. These are later
211 mapped to real numbered registers.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
212
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
213 =begin PIR
214
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
215 .sub main
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
216 .local string hello
bd7fed8 @coke docs cleanup
coke authored
217 hello = "Hello world!"
218 say hello
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
219 .end
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
220
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
221 =end PIR
222
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
223 The C<.local> directive indicates that the named register is only needed inside
782e5b0 @coke RT #49001 - update some uses of 'compilation unit' to 'subroutine'
coke authored
224 the current subroutine (that is, between C<.sub> and C<.end>). Following
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
225 C<.local> is a type. This can be C<int> (for I registers), C<float> (for N
226 registers), C<string> (for S registers), C<pmc> (for P registers) or the name
227 of a PMC type.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
228
ae3a641 @bschmalhofer Move the example 'hello.pasm' from assembly to pasm.
bschmalhofer authored
229 =head2 PIR vs. PASM
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
230
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
231 PASM does not handle register allocation or provide support for named
232 registers. It also does not have the C<.sub> and C<.end> directives, instead
233 replacing them with a label at the start of the instructions.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
234
235 =head2 Summing squares
236
237 This example introduces some more instructions and PIR syntax. Lines starting
238 with a C<#> are comments.
239
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
240 =begin PIR
241
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
242 .sub main
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
243 # State the number of squares to sum.
244 .local int maxnum
245 maxnum = 10
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
246
aa1287e @jkeenan Small grammatical corrections in two places in POD.
jkeenan authored
247 # We'll use some named registers. Note that we can declare many
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
248 # registers of the same type on one line.
249 .local int i, total, temp
250 total = 0
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
251
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
252 # Loop to do the sum.
253 i = 1
254 loop:
255 temp = i * i
256 total += temp
257 inc i
258 if i <= maxnum goto loop
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
259
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
260 # Output result.
261 print "The sum of the first "
262 print maxnum
263 print " squares is "
264 print total
265 print ".\n"
266 .end
267
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
268 =end PIR
269
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
270 PIR provides a bit of syntactic sugar that makes it look more high level than
271 assembly. For example:
272
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
273 =begin PIR_FRAGMENT
274
275 .local pmc temp, i
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
276 temp = i * i
277
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
278 =end PIR_FRAGMENT
279
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
280 Is just another way of writing the more assembly-ish:
281
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
282 =begin PIR_FRAGMENT
283
284 .local pmc temp, i
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
285 mul temp, i, i
286
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
287 =end PIR_FRAGMENT
288
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
289 And:
290
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
291 =begin PIR_FRAGMENT
292
293 .local pmc i, maxnum
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
294 if i <= maxnum goto loop
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
295 # ...
296 loop:
297
298 =end PIR_FRAGMENT
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
299
300 Is the same as:
301
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
302 =begin PIR_FRAGMENT
303
304 .local pmc i, maxnum
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
305 le i, maxnum, loop
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
306 # ...
307 loop:
308
309 =end PIR_FRAGMENT
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
310
311 And:
312
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
313 =begin PIR_FRAGMENT
314
315 .local pmc temp, total
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
316 total += temp
317
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
318 =end PIR_FRAGMENT
319
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
320 Is the same as:
321
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
322 =begin PIR_FRAGMENT
323
324 .local pmc temp, total
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
325 add total, temp
326
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
327 =end PIR_FRAGMENT
328
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
329 As a rule, whenever a Parrot instruction modifies the contents of a register,
330 that will be the first register when writing the instruction in assembly form.
331
332 As is usual in assembly languages, loops and selection are implemented in terms
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
333 of conditional branch statements and labels, as shown above. Assembly
334 programming is one place where using goto is not bad form!
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
335
336 =head2 Recursively computing factorial
337
338 In this example we define a factorial function and recursively call it to
339 compute factorial.
340
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
341 =begin PIR
342
9ee28ed @jnthn Fix factorial example in intro.pod
jnthn authored
343 .sub factorial
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
344 # Get input parameter.
345 .param int n
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
346
9ee28ed @jnthn Fix factorial example in intro.pod
jnthn authored
347 # return (n > 1 ? n * factorial(n - 1) : 1)
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
348 .local int result
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
349
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
350 if n > 1 goto recurse
351 result = 1
352 goto return
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
353
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
354 recurse:
355 $I0 = n - 1
9ee28ed @jnthn Fix factorial example in intro.pod
jnthn authored
356 result = factorial($I0)
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
357 result *= n
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
358
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
359 return:
360 .return (result)
361 .end
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
362
363
68a593e @jnthn Update parrot.pod so as not to suggest intro.pod is horribly out of date...
jnthn authored
364 .sub main :main
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
365 .local int f, i
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
366
ca906e1 @ambs Fixed typo.
ambs authored
367 # We'll do factorial 0 to 10.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
368 i = 0
369 loop:
9ee28ed @jnthn Fix factorial example in intro.pod
jnthn authored
370 f = factorial(i)
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
371
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
372 print "Factorial of "
373 print i
374 print " is "
375 print f
376 print ".\n"
afc981d @chromatic Fixed some POD formatting errors.
chromatic authored
377
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
378 inc i
379 if i <= 10 goto loop
380 .end
381
e880843 @coke [docs/t] add more PIR targets so this code is eventually validated.
coke authored
382 =end PIR
383
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
384 The first line, C<.param int n>, specifies that this subroutine takes one
c36bac8 @bschmalhofer Fix typos in intro.pod.
bschmalhofer authored
385 integer parameter and that we'd like to refer to the register it was passed in
386 by the name C<n> for the rest of the sub.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
387
388 Much of what follows has been seen in previous examples, apart from the line
389 reading:
390
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
391 =begin PIR_FRAGMENT
392
b81b9b9 @coke sync snippet with main source, thanks to ekiru++
coke authored
393 .local int result
9ee28ed @jnthn Fix factorial example in intro.pod
jnthn authored
394 result = factorial($I0)
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
395
fb24eb9 @coke [docs] mark & test more PIR/PASM samples
coke authored
396 =end PIR_FRAGMENT
397
398 The last line of PIR actually represents a few lines of PASM. The assembler
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
399 builds a PMC that describes the signature, including which register the
400 arguments are held in. A similar process happens for providing the registers
401 that the return values should be placed in. Finally, the C<factorial> sub is
402 invoked.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
403
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
404 Right before the C<.end> of the C<factorial> sub, a C<.return> directive is
405 used to specify that the value held in the register named C<result> is to be
406 copied to the register that the caller is expecting the return value in.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
407
bdf3a96 @jnthn Other tweaks to intro.pod to explain the new calling conventions rather ...
jnthn authored
408 The call to C<factorial> in main works in just the same was as the recursive
409 call to C<factorial> within the sub C<factorial> itself. The only remaining
410 bit of new syntax is the C<:main>, written after C<.sub main>. By default,
411 PIR assumes that execution begins with the first sub in the file. This
412 behavior can be changed by marking the sub to start in with C<:main>.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
413
414 =head2 Compiling to PBC
415
416 To compile PIR to bytecode, use the C<-o> flag and specify an output file with
417 the extension F<.pbc>.
418
419 parrot -o factorial.pbc factorial.pir
420
d0733de @ayardley Added DESCRIPTION
ayardley authored
421 =head1 WHERE NEXT?
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
422
423 =head2 Documentation
424
425 What documentation you read next depends upon what you are looking to do with
05a7e7b @bschmalhofer This patch is huge because of all the whitespace reformatting. This was
bschmalhofer authored
426 Parrot. The opcodes reference and built-in PMCs reference are useful to dip
427 into for pretty much everyone. If you intend to write or compile to PIR then
428 there are a number of documents about PIR that are worth a read. For compiler
429 writers, the Compiler FAQ is essential reading. If you want to get involved
430 with Parrot development, the PDDs (Parrot Design Documents) contain some
431 details of the internals of Parrot; a few other documents fill in the gaps. One
432 way of helping Parrot development is to write tests, and there is a document
433 entitled I<Testing Parrot> that will help with this.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
434
435 =head2 The Parrot Mailing List
436
ac517aa @chipdude From: Chris Dolan <chris@chrisdolan.net>
chipdude authored
437 Much Parrot development and discussion takes place on the
66ddda2 @Infinoid [docs] Fix up old references to submitting/subscribing/archives for the ...
Infinoid authored
438 parrot-dev mailing list. You can subscribe by filling out the form at
439 L<http://lists.parrot.org/mailman/listinfo/parrot-dev> or read the NNTP
440 archive at L<http://groups.google.com/group/parrot-dev/>.
d2d2fc2 @jnthn Rewrote intro.pod doc so it's up to date with where Parrot is at now. So...
jnthn authored
441
442 =head2 IRC
443
5a52434 @allisonrandal [cage] Update all references for irc.perl.org to irc.parrot.org.
allisonrandal authored
444 The Parrot IRC channel is hosted on irc.parrot.org and is named C<#parrot>.
93e37ff @bschmalhofer Mention irc.pobox.com and irc.rhizomatic.net in intro.pod.
bschmalhofer authored
445 Alternative IRC servers are at irc.pobox.com and irc.rhizomatic.net.
9bc8687 @simoncozens Documentation! Added the "Some Assembly Required" article with minor
simoncozens authored
446
447 =cut
Something went wrong with that request. Please try again.