This patch add docs/running.pod, which lists the various executables Parrot currently includes, examples of running them, and mentions of where they fail to work. It's more of a cry for help than a useful reference. :-) I've been having trouble recently when making changes in figuring out whether I broke anything, because any non-default way of running the system seems to be already broken. I can't tell what brokenness is expected and what isn't.
Index: MANIFEST =================================================================== RCS file: /home/perlcvs/parrot/MANIFEST,v retrieving revision 1.95 diff -a -u -r1.95 MANIFEST --- MANIFEST 14 Jan 2002 20:03:52 -0000 1.95 +++ MANIFEST 15 Jan 2002 17:20:35 -0000 @@ -57,6 +58,7 @@ docs/parrot.pod docs/parrot_assembly.pod docs/parrotbyte.pod +docs/running.pod docs/strings.pod docs/tests.pod docs/vtables.pod Index: docs/parrot.pod =================================================================== RCS file: /home/perlcvs/parrot/docs/parrot.pod,v retrieving revision 1.2 diff -a -u -r1.2 parrot.pod --- docs/parrot.pod 4 Jan 2002 16:53:22 -0000 1.2 +++ docs/parrot.pod 15 Jan 2002 17:20:35 -0000 @@ -22,6 +22,11 @@ An overview of the Parrot architecture and design. +=item F<running.pod> + +Brief descriptions of the different executables constructed and how to +run them. + =item F<core_ops.pod> A description of the core operations in the Parrot assembly language. --- /dev/null Tue May 5 13:32:27 1998 +++ docs/running.pod Tue Jan 15 09:14:53 2002 @@ -0,0 +1,75 @@ +=head1 Running Parrot code + +This file briefly describes the current set of executables and what +they're for. But mostly, it mentions all the restrictions and +incomplete bits of these commands, in the hopes that people will fix +them and modify this document accordingly. + +=over 3 + +=item C<assemble.pl> + +Converts a Parrot Assembly file to Parrot ByteCode. + + assemble.pl foo.pasm > foo.pbc + +Usage information: no usage message available. There is some amount of +malformed POD visible by running C<perldoc -F Parrot/Assembler.pm>. + +=item C<test_parrot> + +Interprets a Parrot ByteCode file. + + test_parrot <filename>.pbc + +C<test_parrot> has two alternate modes of operation: prederef mode +(C<test_parrot -P>) and jit mode (C<test_parrot -j>). + +Jit mode works for the mops.pasm test, but doesn't work for many other +things. The reason why is unknown. + +Prederef mode only works as a shared library. For example, on most +Unix platforms: + + make clean + make shared + LD_LIBRARY_PATH=blib/lib ./test_parrot -P <filename>.pbc + +You will not be able to use any of the automatic testing targets after +running C<make shared>. + +C<test_parrot> also has several debugging and tracing flags; see the +usage description (currently, a comment in test_main.c) for details. + +=item C<optimizer.pl> + +Does something. Use it by running + + something + +Usage information: none available. + +=item C<pdump> + +Does something. Use it by running + + something + +Usage information: none available. + +=item C<pbc2c.pl> + +Converts a bytecode file to a native .c file. + + perl pbc2c.pl foo.pbc > foo.c + +Usage information: C<perldoc -F pbc2c.pl> + +No documentation is available for compiling the .c file to a binary. +This works, but produces a binary that crashes: + + ./assemble.pl examples/assembly/life.pasm > life.pbc + perl pbc2c.pl life.pbc > life.c + ls **/*.o | egrep -v 'pdump|test_main' | xargs gcc -Iinclude -o life life.c -lm -ldl + +=back
