# Copyright (C) 2006-2012, Parrot Foundation.

=pod

=head1 DESCRIPTION

This is a build directory for custom PMCs with a sample foo.pmc
providing the Foo PMC class.

=head1 CREATING A DYNAMIC PMC

=over 4

=item 1

Edit/create your foo.pmc source - For details on creating PMCs, see
F<tools/dev/gen_class.pl>

There are some differences you have to be aware of when creating dynamic PMCs.

When declaring the dynamic PMC, you must specify  the C<dynpmc> flag, as in:

    pmclass TclString extends TclObject dynpmc ... { ... }

Note that regular (non-dynamic) PMCs have a type id
C<enum_class_PMCNAME>, but dynamic PMCs obviously cannot use the same
thing. Instead, a dynamically-chosen value is assigned at runtime -
so, when you refer to the type of the class , you must dynamically
determine the PMC type. So, while C<scalar> (a builtin) has the
luxury of knowing at compile time what the class number of its child
C<String> is -- for example:

    if (type == enum_class_String) { ...

a dynamic PMC such as C<TclInt> must instead perform a runtime lookup
of its corresponding C<TclString> PMC, resulting in the more complicated:

  static INTVAL dynpmc_TclString;

  pmclass TclInt extends TclObject extends Integer dynpmc group tcl_group {

    void class_init() {
      if (pass) {
        dynpmc_TclString = Parrot_pmc_get_type_str(interp,
          Parrot_str_new(interp, "TclString", 0));
      }
    }
  }

Finally, if you have a group of PMCs that are interdependent, use the
C<group GROUPNAME> syntax to trigger a group library to be built. You
will use the group name as the name of the library to load using the
PASM op C<loadlib>.

        pmclass Match extends Hash dynpmc group match_group { ... }

and then in your .pir or .pasm file:

        loadlib $P0, "match_group"

=item 2

Edit C<src/dynpmc/Defines.in> and C<src/dynpmc/Rules.in>, appending your PMC(s)
to the build target. These files are processed by Configure.pl to create the
real makefile fragments.
Next invoke the configure script, then make:

    $ perl Configure.pl
    $ make

=item 3

If anything changes inside parrot, be sure to:

    $ make dynpmc-clean

=back
