contributing to tcl/parrot

A brief overview on how to help out, if you're interested. In general, it's ok to send patches for tcl to the RT system for anything that isn't "BIG STUFF" - those, please bounce off the MAINTAINERS first. We'd prefer diff -u patches, but are happy to take complete files as well.

Since partcl is bundled with the parrot source, svn access is handled via the same mechanism as for parrot itself.

BIG STUFF

Writing Builtins

partcl is a compiler. Given a section of tcl code, it translates that code into an AST (in the form of a Tcl* object from lib/*). Once a section of code has been translated, the object's compile method is invoked, which then generates PIR which can be compiled by parrot.

The commands themselves are all dispatched at runtime. These are all written in PIR, and can be found, e.g. in runtime/builtins/while.pir. These variants take a variable number of already compiled arguments at runtime.

speed

We're currently slow, compared to tclsh. It's not worth worrying about this in terms of specific numbers until we can run tcltest natively. That said, any patches that improve speed without harming maintainability will of course be applied.

features

We're currently missing some things that require support from parrot. See hacks.pod for a list. In general, though, a lot of what we need to do is possible with parrot.

If you're looking for something to to do, see TODO one level up.

DOCUMENTATION

pod

Every PIR .sub that's defined should probably have some POD to go along with it to document the arguments and return values. Only exceptions to this should be subs which correspond directly to Tcl builtins -- those are already documented at http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm

PIR

Missing Commands

Every builtin command corresponds to an appropriately named file in src/builtin or runtime/builtin. Use a similar command as a template

If the return value would be TCL_OK, then simply .return the value from the sub. For a standard error, just use parrot's die opcode. For any other contrl flow type, use one of the custom ops defined in "ops/tcl.ops" in src, e.g.: tcl_break

Before adding new functionality, add a test (or a test in an existing) file in t/ - tests for puts, for example, go in t/cmd_puts.t. We are in the process of transitioning all our tests from the perl based Parrot::Test to a tcl-based version that generates TAP output. All new tests should be written using the tcl-based version. See t/cmd_expr.t for an example.

Our final goal will be to pass (most of) the tcl test suite: run make spectest to checkout the latest version of of the tcl test suite and run it. Warning: slow...

Long term goal is remove any tests in t/ that are testing things that are already tested in the official tcl suite. Partcl's checked in test suite should just be checking partcl-specific functionality.