docs/compiler_faq.pod

   1 # Copyright (C) 2001-2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/compiler_faq.pod - Parrot FAQ for compiler writers in PIR
   7
   8 =head1 General Questions
   9
  10 =head2 Which C compilers can I use with Parrot?
  11
  12 Whoa, there--you're looking at the wrong FAQ.  This document is for people
  13 writing compilers that target Parrot.
  14
  15 To answer your question, though, Parrot should theoretically work with any
  16 C89-compliant C compiler. See the F<README> files in the root directory for
  17 more information about building Parrot.
  18
  19 =head2 How can I implement a compiler to use as a compiler object from within
  20 Parrot?
  21
  22 See L<http://www.parrotblog.org/2008/03/targeting-parrot-vm.html>.
  23
  24 =head2 How do I embed source locations in my code for debugging?
  25
  26 Use C<.line 42 "file.pir"> for this.
  27
  28 =head1 Subroutines
  29
  30 =head2 How do I generate a sub call in PIR?
  31
  32 This looks like a function call in many HLLs:
  33
  34 =begin PIR_FRAGMENT
  35
  36    $P0( $P1, $P2, $P3 )
  37
  38 =end PIR_FRAGMENT
  39
  40 where $P0 is the function object, and $P1, $P2, and $P3 are its
  41 parameters. You can also use a function's name in place of the
  42 object, as long as it's in the same namespace.
  43
  44 =begin PIR_FRAGMENT
  45
  46    somefunctionlabel( $P1, $P2, $P3 )
  47
  48 =end PIR_FRAGMENT
  49
  50 You can also get return value(s):
  51
  52 =begin PIR_FRAGMENT
  53
  54   ($P1,$P2) = $P0( $P1, $P2, $P3 )
  55
  56 =end PIR_FRAGMENT
  57
  58 If the function name might collide with a Parrot opcode, quote it:
  59
  60 =begin PIR_FRAGMENT
  61
  62    .local int i
  63    i = 'new'(42)
  64
  65 =end PIR_FRAGMENT
  66
  67 You can also use the full PCC for these calls. See
  68 L<docs/pdd19_pir.pod/Parameter Passing and Getting Flags> and other
  69 questions below for more information.
  70
  71 =head2 How do I generate a method call in PIR?
  72
  73 Similar to function calls, just append C<.> and the method name to the object.
  74 You should quote a literal method name to avoid confusion.
  75
  76 =begin PIR_FRAGMENT
  77
  78   .local pmc ret_val, some_obj, arg
  79   ret_val = some_obj.'some_meth'(arg)
  80
  81 =end PIR_FRAGMENT
  82
  83 The method name may also be a string variable representing a method name:
  84
  85 =begin PIR_FRAGMENT
  86
  87   .local string m
  88   .local pmc curses_obj
  89   m = 'bold'
  90   curses_obj.m()
  91
  92 =end PIR_FRAGMENT
  93
  94 =head2 How do I locate or create a subroutine object?
  95
  96 There are several ways to achieve this, depending on the location of
  97 the subroutine.
  98
  99 If the sub is in the same compilation unit use a Sub constant:
 100
 101 =begin PIR_FRAGMENT
 102
 103   .const 'Sub' foo = 'foo'
 104   # ...
 105   foo()
 106
 107 =end PIR_FRAGMENT
 108
 109 A more dynamic way is:
 110
 111 =begin PIR_FRAGMENT
 112
 113   .local pmc foo
 114   foo = find_name 'foo'
 115
 116 =end PIR_FRAGMENT
 117
 118 This searches for a subroutine 'foo' in the current lexical pad, in
 119 the current namespace, in the global, and in the builtin namespace in
 120 that order. This opcode is generated, if I<foo()> is used, but the
 121 compiler can't figure out, where the function is.
 122
 123 If the subroutine is in a different namespace, use the
 124 C<get_hll_global> or C<get_root_global> opcodes:
 125
 126 =begin PIR_FRAGMENT
 127
 128   .local pmc foo
 129   foo = get_root_global ['Foo'], 'foo'
 130
 131 =end PIR_FRAGMENT
 132
 133 This fetches the sub C<foo> in the C<Foo> namespace.
 134
 135 =head2 How do I create a Closure or Coroutine?
 136
 137 Closure and Coroutine carry both a dynamic state.
 138 Therefore you need to perform two steps.
 139 First use one of the above ways to locate the Sub object.
 140 Then use the op C<newclosure> to capture the environment.
 141
 142 =begin PIR_FRAGMENT
 143
 144   .local pmc coro
 145   coro = find_name 'my_coro'
 146   coro = newclosure coro
 147
 148 =end PIR_FRAGMENT
 149
 150 Any subroutine that contains a C<.yield> directive is automatically
 151 created as a Coroutine PMC:
 152
 153 =begin PIR
 154
 155   .sub my_coro             # automagically a Coroutine PMC
 156      .param pmc result
 157      #...
 158      .yield (result)
 159      #...
 160   .end
 161
 162 =end PIR
 163
 164 =head2 How do I generate a tail call in PIR?
 165
 166 =begin PIR
 167
 168   .sub foo
 169       # ...
 170       .tailcall bar(42)           # tail call sub bar
 171   .end
 172
 173   .sub bar
 174       .param int answer
 175       inc answer
 176       .return(answer)
 177   .end
 178
 179 =end PIR
 180
 181 The sub C<bar> will return to the caller of C<foo>. (Warning! This fails
 182 in some cases. XXX Find the RT ticket and reference it here.)
 183
 184 =head2 How do I generate a sub call with a variable-length parameter
 185 list in PIR?
 186
 187 If you have a variable amounts of arguments in an array, you can
 188 pass all items of that array with the C<:flat> directive.
 189
 190 =begin PIR_FRAGMENT
 191
 192   .local pmc ar, foo
 193   ar = new 'ResizablePMCArray'
 194   push ar, "arg 1\n"
 195   push ar, "arg 2\n"
 196   #...
 197   foo(ar :flat)
 198   #...
 199
 200 =end PIR_FRAGMENT
 201
 202 =head2 How to I retrieve the contents of a variable-length parameter
 203 list being passed to me?
 204
 205 Use a slurpy array:
 206
 207 =begin PIR
 208
 209   .sub mysub
 210     .param pmc argv      :slurpy
 211     .local int argc
 212     argc = argv
 213     #...
 214   .end
 215
 216 =end PIR
 217
 218 If you have a few fixed parameters too, you can use a slurpy array
 219 to get the rest of the arguments
 220
 221 =begin PIR
 222
 223   .sub mysub
 224     .param pmc arg0
 225     .param pmc arg1
 226     .param pmc varargs   :slurpy
 227     .local int num_varargs
 228     num_varargs = varargs
 229     # ...
 230   .end
 231
 232 =end PIR
 233
 234 =head2 How do I pass optional arguments?
 235
 236 Use the C<:optional> and C<:opt_flag> pragmas:
 237
 238 =begin PIR
 239
 240   .sub foo
 241      .param pmc arg1       :optional
 242      .param int has_arg1   :opt_flag
 243      .param pmc arg2       :optional
 244      .param int has_arg2   :opt_flag
 245
 246      if has_arg1 goto got_arg1
 247      #...
 248   .end
 249
 250 =end PIR
 251
 252 =head2 How do I create nested subroutines?
 253
 254 Please refer to
 255 L<docs/pdds/pdd20_lexical_vars.pod/Nested Subroutines Have Outies; the ":outer" attribute>
 256 for details.
 257
 258 =head1 Variables
 259
 260 =head2 How do I fetch a variable from the global namespace?
 261
 262 Use the C<get_root_global> or C<get_hll_global> op:
 263
 264 =begin PIR_FRAGMENT
 265
 266     get_hll_global $P0, ['name'; 'space'], 'name_of_the_global'
 267     get_hll_global $P1, 'name_of_the_global'
 268
 269 =end PIR_FRAGMENT
 270
 271 =head2 How can I delete a global?
 272
 273 You can retrieve the namespace hash and use the C<delete> opcode.
 274
 275 =begin PIR
 276
 277     .sub main :main
 278     $P0 = new 'Integer'
 279     $P0 = 42
 280     set_hll_global 'foo', $P0
 281     set_hll_global ['Bar'], 'baz', $P0
 282     show_baz()
 283     .local pmc ns, Bar_ns
 284     ns = get_hll_namespace
 285     delete ns['foo']              # delete from top level
 286     Bar_ns = ns['Bar']            # get Bar namespace
 287     delete Bar_ns['baz']
 288     show_baz()
 289     .end
 290     .sub show_baz
 291     $P0 = get_hll_global ['Bar'], 'baz'
 292     print "'baz' is "
 293     if null $P0 goto is_null
 294     print $P0
 295     print ".\n"
 296     .return ()
 297     is_null:
 298     print "null.\n"
 299     .end
 300
 301 =end PIR
 302
 303 =head2 How do I use lexical pads to have both a function scope and a
 304 global scope?
 305
 306 Please refer to L<docs/pdds/pdd20_lexical_vars.pod> for details.
 307
 308 =head2 How can I delete a lexical variable?
 309
 310 You can't.  You can store a PMCNULL as the value though, which will catch all
 311 further access to that variable and throw an exception. (You can create
 312 a PMCNULL with the C<null> opcode.)
 313
 314 =head2 How do I resolve a variable name?
 315
 316 Use C<find_name>:
 317
 318 =begin PIR_FRAGMENT
 319
 320     $P0 = find_name '$x'
 321     find_name $P0, 'foo'    # same thing
 322
 323 =end PIR_FRAGMENT
 324
 325 This will find the name C<foo> in the lexical, global, or builtin namespace, in
 326 that order, and store it in C<$P0>.
 327
 328 =head2 How do I fetch a variable from the current lexical pad?
 329
 330 =begin PIR_FRAGMENT
 331
 332     find_lex $P0, 'foo'
 333
 334 =end PIR_FRAGMENT
 335
 336 or much better, if possible just use the variable defined along with
 337 the C<.lex> definition of C<foo>.
 338
 339 =head2 How do I fetch a variable from any nesting depth?
 340
 341 That is still the same:
 342
 343 =begin PIR_FRAGMENT
 344
 345     find_lex $P0, 'foo'
 346
 347 =end PIR_FRAGMENT
 348
 349 This finds a C<foo> variable at any B<outer> depth starting from the top.
 350
 351 If your language looks up variables differently, you have to walk the
 352 'caller' chain. See also F<t/dynpmc/dynlexpad.t>.
 353
 354 =head2 How can I produce more efficient code for lexicals?
 355
 356 Don't emit C<store_lex> at all. Use C<find_lex> only if the compiler
 357 doesn't know the variable. You can always just use the register that was
 358 defined in the C<.lex> directive as an alias to that lexical, if you are in
 359 the same scope.
 360
 361 =head1 Modules, Classes, and Objects
 362
 363 =head2 How do I create a module?
 364
 365 XXX
 366
 367 =head2 How do I create a class?
 368
 369 With the C<newclass> op:
 370
 371 =begin PIR_FRAGMENT
 372
 373     newclass $P0, 'Animal'
 374
 375 =end PIR_FRAGMENT
 376
 377 =head2 How do I add instance variables/attributes?
 378
 379 Each class knows which attributes its objects can have. You can add attributes
 380 to a class (not to individual objects) like so:
 381
 382 =begin PIR_FRAGMENT
 383
 384     addattribute $P0, 'legs'
 385
 386 =end PIR_FRAGMENT
 387
 388 =head2 How do I add instance methods to a class?
 389
 390 Methods are declared as functions in the class namespace with the C<:method>
 391 keyword appended to the function declaration:
 392
 393 =begin PIR
 394
 395   .namespace [ 'Animal' ]
 396
 397   .sub run :method
 398      print "slow and steady\n"
 399   .end
 400
 401 =end PIR
 402
 403 =head2 How do I override a vtable on a class?
 404
 405 As with methods, but note the new keyword. The vtable name specified B<must>
 406 be an existing vtable slot.
 407
 408 =begin PIR
 409
 410   .namespace [ 'NearlyPi' ]
 411
 412   .sub get_string :vtable
 413      .return ('three and a half')
 414   .end
 415
 416 =end PIR
 417
 418 Now, given an instance of NearlyPi in $P0
 419
 420 =begin PIR_FRAGMENT
 421
 422   $S0 = $P0
 423   say $S0  # prints 'three and a half'
 424
 425 =end PIR_FRAGMENT
 426
 427 =head2 How do I access attributes?
 428
 429 You can access attributes by a short name:
 430
 431 =begin PIR_FRAGMENT_INVALID
 432
 433   $P0 = getattribute self, 'legs'
 434   assign $P0, 4                   # set attribute's value
 435
 436 =end PIR_FRAGMENT_INVALID
 437
 438 =head2 When should I use properties vs. attributes?
 439
 440 Properties aren't inherited. If you have some additional data that
 441 don't fit into the class's hierarchy, you could use properties.
 442
 443 =head2 How do I create a class that is a subclass of another class?
 444
 445 You first have to get the class PMC of the class you want to subclass.
 446 Either you use the PMC returned by the C<newclass> op if you created
 447 the class, or use the C<get_class> op:
 448
 449 =begin PIR_FRAGMENT
 450
 451     get_class $P0, 'Animal'
 452
 453 =end PIR_FRAGMENT
 454
 455 Then you can use the C<subclass> op to create a new class that is a
 456 subclass of this class:
 457
 458 =begin PIR_FRAGMENT
 459
 460     subclass $P1, $P0, 'Dog'
 461
 462 =end PIR_FRAGMENT
 463
 464 This stores the newly created class PMC in $P1.
 465
 466 =head2 How do I create a class that has more than one parent class?
 467
 468 First, create a class without a parent class using C<newclass> (or
 469 with only one subclass, see previous question). Then add the other
 470 parent classes to it.  Please refer to the next question for an
 471 example.
 472
 473 =head2 How do I add another parent class to my class?
 474
 475 If you have a class PMC (created with C<newclass> or by C<subclass>),
 476 you can add more parent classes to it with the C<addparent> op:
 477
 478 =begin PIR_FRAGMENT
 479
 480     get_class $P1, 'Dog'
 481     subclass $P2, $P1, 'SmallDog'
 482     get_class $P3, 'Pet'
 483     addparent $P2, $P3  # make "SmallDog" also a "Pet"
 484
 485 =end PIR_FRAGMENT
 486
 487 =head2 How can I specify the constructor of a class?
 488
 489 Just override the init vtable for that class.
 490
 491 =begin PIR
 492
 493     .sub _ :main
 494       newclass $P0, 'Dog'         # create a class named Dog
 495     .end
 496
 497     .namespace ['Dog']
 498
 499     .sub init :vtable
 500       # ...
 501     .end
 502
 503 =end PIR
 504
 505 Or you can specify the constructor method by setting the BUILD
 506 property of the class PMC:
 507
 508 =begin PIR_FRAGMENT
 509
 510     newclass $P0, 'Dog'         # create a class named Dog
 511     new $P1, 'String'           # create a string
 512     set $P1, 'initialise'       # set it to the name of the constructor method
 513     setprop $P0, 'BUILD', $P1   # set the BUILD property
 514
 515 =end PIR_FRAGMENT
 516
 517 =head2 How do I instantiate a class?
 518
 519 You can do so either with the class name:
 520
 521 =begin PIR_FRAGMENT
 522
 523     new $P0, 'Dog'
 524
 525 =end PIR_FRAGMENT
 526
 527 or with the class object:
 528
 529 =begin PIR_FRAGMENT
 530
 531     $P1 = get_class 'Dog'   # find the 'Dog' class
 532     unless null $P1 goto have_dog_class
 533     printerr "Oops; can't find the 'Dog' class.\n"
 534     .return ()
 535   have_dog_class:
 536     new $P0, $P1    # creates a Dog object and stores it in register $P0
 537
 538 =end PIR_FRAGMENT
 539
 540 The chief difference is that using a string constant will produce the
 541 specific error "Class 'Dog' not found" if that happens to be the case;
 542 the other code has to check explicitly.
 543
 544 During the C<new> opcode the constructor is called.
 545
 546 =head2 How can I pass arguments to a constructor?
 547
 548 You can pass only a single argument to a constructor.  By convention,
 549 a hash PMC is passed to the constructor that contains the arguments as
 550 key/value pairs:
 551
 552 =begin PIR_FRAGMENT
 553
 554     new $P0, 'Hash'
 555     set $P0['greeting'], 'hello'
 556     set $P0['size'], 1.23
 557
 558     new $P1, 'Alien', $P0       # create an Alien object and pass
 559                                 # the hash to the constructor
 560
 561 =end PIR_FRAGMENT
 562
 563 =head2 How do I add module/class methods?
 564
 565 XXX
 566
 567 =head2 How do I access module/class variables?
 568
 569 XXX
 570
 571 =head1 Exceptions
 572
 573 =head2 How do I throw an exception in PIR?
 574
 575 The easiest way is the perl-like
 576
 577 =begin PIR_FRAGMENT
 578
 579     die 'Eeeek!'
 580
 581 =end PIR_FRAGMENT
 582
 583 You can also explicitly create an exception object and throw it:
 584
 585 =begin PIR_FRAGMENT
 586
 587     $P0 = new 'Exception'
 588     $P0 = 'something happened'
 589     throw $P0
 590
 591 =end PIR_FRAGMENT
 592
 593 =head2 How do I catch an exception in PIR?
 594
 595 Use C<push_eh> to push an exception handler onto the stack. End the set of
 596 instructions that might throw the exception you're interested in with
 597 C<pop_eh>.
 598
 599 =begin PIR_FRAGMENT
 600
 601     push_eh handler
 602       die 'whoops'  # or any other code that might throw an exception...
 603     pop_eh
 604     # ok
 605
 606 =end PIR_FRAGMENT
 607
 608 An exception handler is called with one argument, which is the exception object.
 609 The message of the exception can be easily extracted, as follows:
 610
 611 =begin PIR_FRAGMENT
 612
 613   handler: # exception
 614     .get_results ($P0)
 615     print 'Exception caught:'
 616     $S0 = $P0['message']
 617     say $S0
 618
 619 =end PIR_FRAGMENT
 620
 621 =head2 How do I let exceptions from C<exit> pass through my handler?
 622
 623 Rethrow the exception if it has a severity of C<EXCEPT_EXIT>.
 624
 625 =begin PIR_FRAGMENT
 626
 627   .include 'except_severity.pasm'
 628   # ...
 629   handler:
 630     .get_results ($P0)
 631     $I0 = $P0['severity']
 632     if $I0 == .EXCEPT_EXIT goto handle_exit
 633     say 'Exception caught!'
 634     # ...
 635
 636   handle_exit:
 637     rethrow $P0 # let the next handler deal with it.
 638
 639 =end PIR_FRAGMENT
 640
 641 Exception example:
 642
 643 =begin PIR_FRAGMENT
 644
 645     push_eh handler
 646     $P0 = new 'Exception'
 647     $P0 = 'something happened'
 648     throw $P0
 649     pop_eh
 650     exit 0
 651
 652   handler:
 653     .local pmc exception
 654     .local string message
 655     .get_results (exception)
 656     print 'Exception: '
 657     message = exception['message']
 658     print message
 659     print "\n"
 660     exit 1
 661
 662 =end PIR_FRAGMENT
 663
 664 =head1 C Extensions
 665
 666 =head2 How do I create PMCs for my compiler?
 667
 668 Parrot supports dynamic PMCs, loadable at runtime, to allow compiler writers
 669 to extend Parrot with additional types. For more information about writing
 670 PMCs, see L<tools/build/pmc2c.pl> and L<docs/pmc.pod>.
 671
 672 To build dynamic PMCs, add something like the following to your Makefile:
 673
 674   PERL     = /usr/bin/perl
 675   PMCBUILD = $(PERL) /path/to/parrot/tools/build/dynpmc.pl
 676   DESTDIR  = /path/to/parrot/runtime/parrot/dynext
 677   LOAD_EXT = .so
 678
 679   PMCDIR    = pmc
 680   PMCS      = MyInteger MyFloat MyString MyObject
 681   PMC_FILES = MyInteger.pmc MyFloat.pmc MyString.pmc MyObject.pmc
 682
 683   dynpmcs : $(PMC_FILES)
 684       @cd $(PMCDIR) && $(PMCBUILD) generate $(PMCS)
 685       @cd $(PMCDIR) && $(PMCBUILD) compile $(PMCS)
 686       @cd $(PMCDIR) && $(PMCBUILD) linklibs $(PMCS)
 687       @cd $(PMCDIR) && $(PMCBUILD) copy "--destination=$(DESTDIR)" $(PMCS)
 688
 689 =head2 How do I add another op to Parrot?
 690
 691 Parrot supports dynamic op libraries. These allow for ops specific to one
 692 language to be used without having to place them into the Parrot core itself.
 693 For examples of dynamic op libraries, see L<src/dynoplibs>.
 694
 695 =head2 How do I use the Native Calling Interface (NCI)?
 696
 697 Using the NCI you can invoke functions written in C from a Parrot script.
 698 To every NCI invocation, there are two parts: the native function to be invoked,
 699 and the PIR code to do the invocation.
 700
 701 First the native function, to be written in C.  On Windows, it is necessary
 702 to do a DLL export specification of the NCI function:
 703
 704   /* foo.c */
 705
 706   /* specify the function prototype */
 707   #ifdef __WIN32
 708   __declspec(dllexport) void foo(void);
 709   #else
 710   void foo(void);
 711   #endif
 712
 713   void foo(void) {
 714     printf("Hello Parrot!\n");
 715   }
 716
 717 Then, after having compiled the file as a shared library, the PIR code looks
 718 like this:
 719
 720 =begin PIR
 721
 722   .sub main :main
 723      .local pmc lib, func
 724
 725      # load the shared library
 726      lib = loadlib "hello" # no extension, .so or .dll is assumed
 727
 728      # get a reference to the function from the library just
 729      # loaded, called "foo", and signature "void" (and no arguments)
 730      func = dlfunc lib, "foo", "v"
 731
 732      # invoke
 733      func()
 734
 735   .end
 736
 737 =end PIR
 738
 739 If you embedded a Parrot in your C file and you want to invoke another function
 740 in that same C file, you should pass a null string to loadlib. Do that as follows:
 741
 742 =begin PIR_FRAGMENT
 743
 744  .local pmc lib
 745  .local string libname
 746  null libname
 747
 748  lib = loadlib libname
 749
 750 =end PIR_FRAGMENT
 751
 752 Under Linux, the .c file must then be linked with the -export-dynamic option.
 753
 754 =head1 Misc
 755
 756 =head2 How can I access a program's environment?
 757
 758 Create a new C<Env> PMC and access it like a hash.
 759
 760 =begin PIR_FRAGMENT
 761
 762     .local pmc e
 763     e = new 'Env'
 764     $P0 = e['USER']      # lt
 765
 766 =end PIR_FRAGMENT
 767
 768 =head2 How can I access Parrot's configuration?
 769
 770 =begin PIR_FRAGMENT
 771
 772     .include 'iglobals.pasm'
 773     .local pmc interp, cfg
 774     interp = getinterp
 775     cfg = interp[.IGLOBALS_CONFIG_HASH]
 776     $S0 = cfg['VERSION']    # "0.3.0"
 777
 778 =end PIR_FRAGMENT
 779
 780 See F<config_lib.pasm> for all the keys in the config hash - or iterate over
 781 the config hash.
 782
 783 =head1 Languages
 784
 785 =head2 What files do I need to modify to add my new language compiler?
 786
 787 Aside from the files in your new language directory, you must modify
 788
 789     CREDITS
 790     MANIFEST
 791     config/gen/languages.pm
 792     config/gen/makefiles/languages.in
 793
 794 Inside your language dir, you may consider adding the following:
 795
 796     LICENSE
 797     MAINTAINER
 798     README
 799     STATUS
 800
 801 Look to existing languages for some examples.