src/dynpmc/README.pod

   1 =pod
   2
   3 =head1 OVERVIEW
   4
   5 This is a build directory for custom PMCs with a sample foo.pmc
   6 providing the Foo PMC class.
   7
   8 =head1 CREATING A DYNAMIC PMC
   9
  10 =over 4
  11
  12 =item 1
  13
  14 Edit/create your foo.pmc source - For details on creating PMCs, see
  15 F<tools/dev/gen_class.pl>
  16
  17 There are some differences you have to be aware of when creating dynamic PMCs.
  18
  19 When declaring the dynamic PMC, you must specify  the C<dynpmc> flag, as in:
  20
  21         pmclass TclString extends TclObject dynpmc ... { ... }
  22
  23 Note that regular (non-dynamic) PMCs have a type id
  24 C<enum_class_PMCNAME>, but dynamic PMCs obviously cannot use the same
  25 thing. Instead, a dynamically-chosen value is assigned at runtime -
  26 so, when you refer to the type of the class , you must dynamically
  27 determine the PMC type. So, while C<scalar> (a builtin) has the
  28 luxury of knowing at compile time what the class number of its child
  29 C<String> is -- for example:
  30
  31         if (type == enum_class_String) { ...
  32
  33 a dynamic PMC such as C<TclInt> must instead perform a runtime lookup
  34 of its corresponding C<TclString> PMC, resulting in the more complicated:
  35
  36   static INTVAL dynpmc_TclString;
  37
  38   pmclass TclInt extends TclObject extends Integer dynpmc group tcl_group {
  39
  40     void class_init() {
  41       if (pass) {
  42         dynpmc_TclString = Parrot_PMC_typenum(interp,"TclString");
  43       }
  44     }
  45   }
  46
  47 Finally, if you have a group of PMCs that are interdependent, use the
  48 C<group GROUPNAME> syntax to trigger a group library to be built. You
  49 will use the group name as the name of the library to load using the
  50 PASM op C<loadlib>.
  51
  52         pmclass Match extends Hash dynpmc group match_group { ... }
  53
  54 and then in your .pir or .pasm file:
  55
  56         loadlib $P0, "match_group"
  57
  58 =item 2
  59
  60 Edit C<../../config/gen/makefiles/dynpmc.in> and append your PMC(s) to
  61 the build target. The dynpmc.in file is processed by Configure.pl to
  62 create the real makefiles. So, invoke the configure script, then make:
  63
  64         $ perl Configure.pl
  65         $ make
  66
  67 =item 3
  68
  69 If anything changes inside parrot, be sure to:
  70
  71         $ make dynpmc-clean
  72
  73 =back