languages/tcl/docs/howto.pod

   1 =head1 contributing to tcl/parrot
   2
   3 A brief overview on how to help out, if you're interested. In general,
   4 it's ok to send patches for tcl to the RT system for anything that isn't
   5 "BIG STUFF" - those, please bounce off the MAINTAINERS first.
   6 We'd prefer C<diff -u> patches, but are happy to take complete files as well.
   7
   8 Since partcl is bundled with the parrot source, svn access is handled via
   9 the same mechanism as for parrot itself.
  10
  11 =head1 BIG STUFF
  12
  13 =over 4
  14
  15 =item Writing Builtins
  16
  17 partcl is a compiler. Given a section of tcl code, it translates that code
  18 into an AST (in the form of a Tcl* object from lib/*). Once a section of code
  19 has been translated, the object's C<compile> method is invoked, which then
  20 generates PIR which can be compiled by parrot.
  21
  22 The commands themselves are all dispatched at runtime. These are all written
  23 in PIR, and can be found, e.g. in F<runtime/builtins/while.pir>. These variants
  24 take a variable number of already compiled arguments at runtime.
  25
  26 =item speed
  27
  28 We're currently slow, compared to tclsh. It's not worth worrying about
  29 this in terms of specific numbers until we can run C<tcltest> natively. That
  30 said, any patches that improve speed without harming maintainability will of
  31 course be applied.
  32
  33 =item features
  34
  35 We're currently missing some things that require support from parrot. See
  36 L<hacks.pod> for a list. In general, though, a lot of what we need to do is
  37 possible with parrot.
  38
  39 If you're looking for something to to do, see L<TODO> one level up.
  40
  41 =back
  42
  43 =head1 DOCUMENTATION
  44
  45 =over 4
  46
  47 =item pod
  48
  49 Every PIR .sub that's defined should probably have some POD to go along
  50 with it to document the arguments and return values. Only exceptions to
  51 this should be subs which correspond directly to Tcl builtins -- those
  52 are already documented at L<http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm>
  53
  54 =back
  55
  56 =head1 PIR
  57
  58 =over 4
  59
  60 =item Missing Commands
  61
  62 Every builtin command corresponds to an appropriately named file in
  63 C<src/builtin> or C<runtime/builtin>. Use a similar command as a
  64 template
  65
  66 If the return value would be TCL_OK, then simply C<.return> the value from the
  67 sub. For a standard error, just use parrot's C<die> opcode. For any other
  68 contrl flow type, use one of the custom ops defined in
  69 L<src/ops/tcl.ops>, e.g.: C<tcl_break>
  70
  71 Before adding new functionality, add a test (or a test in an existing) file
  72 in C<t/> - tests for C<puts>, for example, go in C<t/cmd_puts.t>. We are in the
  73 process of transitioning all our tests from the perl based Parrot::Test to a
  74 tcl-based version that generates TAP output. All new tests should be written
  75 using the tcl-based version. See C<t/cmd_expr.t> for an example.
  76
  77 Our final goal will be to pass (most of) the tcl test suite: run
  78 C<make spectest> to checkout the latest version of of the tcl test suite
  79 and run it. Warning: slow...
  80
  81 Long term goal is remove any tests in C<t/> that are testing things that are
  82 already tested in the official tcl suite.  Partcl's checked in test suite
  83 should just be checking partcl-specific functionality.
  84
  85 =back
  86
  87 =cut