=pod

=head1 OVERVIEW

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_typenum(INTERP,"TclString");
      }
    }
  }

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<../../config/gen/makefiles/dynpmc.in> and append your PMC(s) to
the build target. The dynpmc.in file is processed by Configure.pl to 
create the real makefiles. So, invoke the configure script, then make:
		
	$ perl Configure.pl
	$ make

=item 3

If anything changes inside parrot, be sure to:

	$ make dynpmc-clean

=back
