1 # Copyright (C) 2001-2009, Parrot Foundation.
6 README.txt - Readme file for PIRC compiler.
10 PIRC is a fresh implementation of the PIR language using Bison and Flex.
11 Its main features are:
15 =item * thread-safety, so it is reentrant.
17 =item * strength reduction, implemented in the parser.
19 =item * constant folding, implemented in the parser.
21 =item * checks for proper use of op arguments in PIR syntax (disallowing, e.g.: $S0 = print)
23 =item * allow multiple heredocs in subroutine invocations (like: foo(<<'A', <<'B', <<'C') )
25 =item * register usage optimization
29 =head2 Compiling and Running
31 =head3 Windows using Microsoft Visual Studio
33 To compile PIRC on windows using MSVC:
37 When running PIRC, it needs the shared library C<libparrot>; an easy way to do
38 this is copy C<libparrot.dll> in the Parrot root directory to C<compilers/pirc/src>.
40 Running PIRC is as easy as:
44 See 'pirc -h' for help.
46 =head3 Linux using GCC
48 The Makefile should work fine on Linux:
50 cd compilers/pirc && make
52 When running PIRC, it needs the shared library C<libparrot>; in order to let
53 PIRC find it, set the path as follows:
55 export LD_LIBRARY_PATH=../../../blib/lib
57 Running is as easy as:
63 The new Bison/Flex based implementation of the PIR compiler is designed
64 as a two-stage compiler:
68 =item 1. Heredoc preprocessor
74 =head2 Heredoc preprocessing
76 The heredoc preprocessor takes the input as written by the PIR programmer,
77 and flattens out all heredoc strings. An example is shown below to illustrate
84 This is a heredoc string
95 $S0 = "This is a heredoc string\n divided\n over\n five\n lines.\n"
98 In order to allow C<.include>d file to have heredoc strings, the heredoc preprocessor
99 also handles the C<.include> directive, even though logically this is a macro function.
100 See the discussion below for how the C<.include> directive works.
104 The PIR compiler parses the output of the heredoc preprocessor. PIRC's lexer also
107 The macro layer basically implements text replacements. The following directives are handled:
113 =item C<.macro_const>
115 =item C<.macro_local>
117 =item C<.macro_label>
123 The C<.include> directive takes a string argument, which is the name of a file. The
124 contents of this file are inserted at the point where the C<.include> directive
125 is written. To illustrate this, consider the following example:
128 ========================
135 ========================
138 ========================
142 ========================
144 This will result in the following output:
158 The macro directive starts a macro definition. The macro preprocessor
159 implements the expansion of macros. For instance, given the following input:
170 will result in this output:
177 =head3 C<.macro_const>
179 The C<.macro_const> directive is similar to the C<.macro> directive, except
180 that a C<.macro_const> is just a simplified C<.macro>; it merely gives a name
186 print "PI is approximately: "
191 This will result in the output:
194 print "PI is approximately: "
202 As Parrot instructions are polymorphic, the PIR compiler is responsible for
203 selecting the right variant of the instruction. The selection is based on the
204 types of the operands. For instance:
208 will select the C<set_i_ic> instruction: this is the C<set> instruction, taking
209 an integer (i) result operand and an integer constant (ic) operand. Other examples
212 $P0[1] = 42 --> set_p_kic_ic # kic = key integer constant
213 $I0 = $P0["hi"] --> set_i_p_kc # kc = key constant from constant table
214 $P1 = new "Hash" --> new_p_sc # sc = string constant
216 =head3 Constant folding
218 Expressions that can be evaluated at compile-time are pre-evaluated, saving
219 calculations during runtime. Some constant-folding is required, as Parrot
220 depends on this. For instance:
224 is not a valid Parrot instruction; there is no C<add_i_ic_ic> instruction.
225 Instead, this will be translated to:
229 which, as was explained earlier, will select the C<set_i_ic> instruction.
231 The conditional branch instructions are also pre-evaluated, if possible. For
232 instance, consider the following statement:
236 It is clear during compile time, that 1 is smaller than 2; so instead of
237 evaluating this during runtime, we know for sure that the branch to label
238 C<L1> will be made, effectively replacing the above statement by:
242 Likewise, if it's clear that certain instructions don't have any effect,
243 they can be removed altogether:
245 if 1 > 2 goto L1 --> nop # nop is no opcode.
246 $I0 = $I0 + 0 --> nop
248 Another type of optimization is the selection of (slightly) more efficient
249 variants of instructions. For instance, consider the following instruction:
253 which is actually syntactic sugar for:
257 In C one would write (ignoring the fact that $I0 and $I0 are not a valid C
262 which is in fact valid PIR as well. When the PIR parser sees an instruction
263 of this form, it will automatically select the variant with 2 operands
264 instead of the 3-operand variant. So:
266 add $I0, $I0, $1 # $I0 is an out operand
268 will be optimized, as if you had written:
270 add $I0, $I1 # $I0 is an in/out operand
272 The PIR parser can do even more improvements, if it sees opportunity to do so.
273 Consider the following statement:
277 or, in Parrot assembly syntax:
281 Again, in C one would write (again ignoring the valid identifier issue): C<$I0++>,
282 or in other words, C<incrementing> the given identifier. Parrot has C<inc> and C<dec>
283 instructions built-in as well, so that the above statement C<$I0 = $I0 + 1> can be
288 =head3 Vanilla Register Allocator
290 The PIR compiler implements a vanilla register allocator. This means that each
291 declared C<.local> or C<.param> symbol, and each PIR register ($Px, $Sx, $Ix, $Nx)
292 is assigned a unique PASM register, that is associated with the original symbol
293 or PIR register throughout the subroutine.
295 PIRC has a register optimizer, which can optimize the register usage. Run PIRC
296 with the C<-r> option to activate this. The register optimizer is implemented
297 using a Linear Scan Register allocator.
299 The implementation of the vanilla register allocator is done in the PIR symbol
300 management module (C<pirsymbol.c>).
302 =head2 Register optimizer
304 PIRC has a register optimizer, which uses a Linear Scan Register algorithm.
305 For each symbolic register, a live-interval object is created, which has
306 an I<start> and I<end> point, indicating the first and last usage of that
307 symbolic register in the sub. The register optimizer figures out when
308 symbolic registers don't overlap, in which case they can use the same
309 register (assuming they're of the same type).
313 Bytecode generation is done, but there is the occasional bug. These
314 are reported in trac.parrot.org.
317 =head1 IMPLEMENTATION
319 The directory compilers/pirc has a number of subdirectories:
323 =item doc - contains documentation.
325 =item heredoc - contains the implementation of the heredoc preprocessor. This is now
326 integrated with pirc/src. It now only has a driver program to build a stand-alone
327 heredoc preprocessor.
329 =item src - contains the Bison/Flex implementation of PIRC
331 =item t - for tests. Tests input is fed into Parrot after compilation,
332 which will run the code.
334 =item macro - contains the old implementation of the macro preprocessor. This is now
335 integrated with pirc/src. These files are kept as a reference until the macro
336 preprocessor in pirc/src is completed.
340 =head1 MAKING CHANGES
342 If you want to make changes to the lexer of parser files, you will need the Flex
343 and/or Bison programs. There are ports available for Windows, but I don't know
344 whether they're any good. I use Cygwin's tools.
346 =head2 Updating the lexer
348 The heredoc preprocessor is implemented in C<hdocprep.l>, and can be regenerated
351 cd compilers/pirc/src
354 PIRC's normal lexer is implemented in C<pir.l>, and can be regenerated using:
356 cd compilers/pirc/src
359 =head2 Updating the parser
361 The parser is implemented in C<pir.y>, and can be regenerated using:
363 cd compilers/pirc/src
369 =head2 Cygwin processable lexer spec.
371 The file C<pir.l> from which the lexer is generated is I<not> processable by Cygwin's
372 default version of Flex. In order to make a reentrant lexer, a newer version is needed,
373 which can be downloaded from the link below.
375 L<http://sourceforge.net/project/downloading.php?groupname=flex&filename=flex-2.5.33.tar.gz&use_mirror=belnet>
382 Then make sure to overwrite the supplied flex binary.
386 Having a look at this implementation would be greatly appreciated, and any resulting
387 feedback even more :-). Please post bug reports in trac.parrot.org.
396 =item * C<languages/PIR> for a PGE based implementation.
398 =item * C<compilers/imcc>, the current I<standard> PIR implementation.
400 =item * C<docs/imcc/syntax.pod> for a description of PIR syntax.
402 =item * C<docs/imcc/> for more documentation about the PIR language.
404 =item * C<docs/pdds/pdd19_pir.pod> for the PIR design document.