root/v6/v6-KindaPerl6/docs/FAQ.pod

=head1 NAME

KindaPerl6 - Frequent Asked Questions.

=head1 DEVELOPMENT

Development of KindaPerl6 is coordinated almost via the #perl6 IRC channel on
irc.freenode.net. If you want to contribute join the channel and ask for a
commit bit (see L<http://dev.pugscode.org/wiki/>).

=head2 Useful links

These are perl6 links, that I believe would be useful for new people to the
KindaPerl6 project.

L<http://dev.pugscode.org/browser> Trac interface for Perl6 code

L<http://svn.pugscode.org/pugs/> SVN Repository

L<http://feather.perl6.nl/syn/> Official Perl6 Documentation

L<http://sial.org/pbot/perl6> Paste Bot for #perl6

L<http://irclog.perlgeek.de/perl6/today> IRC Chat history for #perl6

L<http://www.cse.unsw.edu.au/~dons/lambdabot/COMMANDS> Commands for lambdabot in #perl6

L<http://dev.pugscode.org/timeline> Recent Commits

L<http://dev.pugscode.org/browser/v6/v6-KindaPerl6/TODO> KP6 TODO

=head2 mp6/kp6 FAQ

=head2 Overview - What is mp6/kp6/v6?

v6 is a perl6-on-perl6 project:  L<http://dev.pugscode.org/browser/v6>

This is not the perl5 v6-alpha, see perl5/Pugs-Compiler-Perl6 for that.

The current plan is to bootstrap full-p6 using kp6.

There are 4 subprojects under v6/:

=over

=item MiniPerl6 aka mp6

v6-MiniPerl6 (mp6) is a subset of Perl 6 used to bootstrap the full Perl 6.
v6-MiniPerl6 is bootstrapped with perl5.

=item KindaPerl6 aka kp6

v6-KindaPerl6 is a reimplementation of mp6 with a very flexible compiler
workflow.  kp6 uses plugins in order to implement perl6 semantics over several
backends.  kp6 is currently being bootstrapped - kp6 is compiled with the mp6
compiler.

=item Yet Another Perl6 aka yap6

A pure C implementation of KindaPerl6 runtime

=item Onion

Next iteration of the kp6 project
I<This project was a shortlived experiment.Work on the bootstap is now going inside kp6.The name is reserved for perl6 on parrot>

=item v6.pm

v6.pm is a plain translation of the perl5 v6.pm compiler, such that the modules
could be interchangeable. This project is currently abandoned.
I<This project has been removed.>

=item v6-Compiler

v6-Compiler (full-p6) is meant as a more advanced compiler, but the process is
more  difficult to bootstrap because v6-Compiler needs a more complete Perl 6
compiler.
I<This project has been removed.>

=item pugs - the Haskell implementation

PUGS is the root: L<http://dev.pugscode.org/browser> .  There are several
different perl6 implementations in progress.  PUGS is one of them.

=back

=head2 How can I help?

=head3 Prerequisite reading.

Perl6 is implementing several features I have not heard of before.  Before
you read the perl6 documentation, these documents are good to read.

- Prototyped based programming: L<http://en.wikipedia.org/wiki/Prototype-based_programming>

The perl5 code that implements Prototyped classes: L<http://search.cpan.org/dist/Class-Prototyped/lib/Class/Prototyped.pm>

- Objects (Autoboxing is interesting): L<http://en.wikipedia.org/wiki/Autoboxing#Autoboxing>

=head3 What do you need?

 - Perl5 (Perl 5.10.RC2 and Perl 5.8.8 worked with the kp6 test cases.)
 - Coro.pm : L<http://search.cpan.org/~mlehmann/Coro-4.13/Coro.pm>
   Required for t/kp6/internals/02-gather.t
 - Subversion client.
 - Commit bit: Ask on #perl6 irc.freenode.net.

=head3 Customs and Traditions.

- (new comers) When you get your commit bit, Update the AUTHORS file to make sure everything (SVN) is ok.

- Commit code in doubt, revert if wrong.<br>

L<http://irclog.perlgeek.de/perl6/2007-10-31#i_135203>

- Please prefix your kp6 svn commits with [kp6]

L<http://irclog.perlgeek.de/perl6/2007-11-01#i_136077>

Example:

 [kp6] I have refactored subroutine XXX for clarity and updated the documentation.

=head3 Seeing an intermediate step.

Sometimes you want to see how kp6 "saw" the code.  This is seen by running the
code though AST backend.

 perl script/kp6 -Cast -e ' "a" eq "b" '

=head3 Cannot see the forest for the trees. / Boot strapping

One of the problems I had when I started working on kp6 was I could not see
how everything worked together.

mp6.pl (miniperl6) is used to compile/translate the AST/Grammar/Visitor perl6
libraires/code into perl5 code that can be used by kp6 to parse new perl6 code.

AST/Grammar/Visitor code is responsible for converting perl6 code into perl5
code or some other backend (Parrot/Lisp/Perl5).

Once the kp6 is sufficently working, you can use kp6 to compile the AST/Grammer/Visitor
perl6 code to produce NEWER, better, libraries.  The new libraries replace the
existing libraries/code produced by mp6.  Ergo, miniperl6 is no longer needed;
kp6 has just bootstrapped itself.

The mp6.pl files are:

 src/KindaPerl6/Ast.pm
                Grammar.pm
                Traverse.pm

 src/KindaPerl6/Grammer/*

 src/KindaPerl6/Visitor/*

kp6 provides a Runtime enviroment for perl6 code with src/KindaPerl6/Runtime/*
so that we can execute perl6 code that has been translated to perl5.

=head2 What subset of Perl 6 is covered by mp6?

  (from miniperl6-spec.pod)

=over

=item

A program is organized in compilation units. All statements must be inside a
'class' declaration: class X { ... }

=item

All statements finish with semicolon.

=item

Only allow one feed of positional arguments.

=item

In Signature, disallow "is slurpy", "is optional", "is named" (*@bad) ($bad?)
(:$bad)

=item

But we do allow Hash and Array and Tree unpacking:

 sub foo ([$a, $b, $c], {:$x, :$y}, ::Tree $top (:$left, :$right)) { ... }

 foo([1, 2, 3], { x => 1, y => 2 }, ::Tree( left => 1, right => 2 ));

 # This compiles to:
 sub foo {
     my perl6::Tree $top;
     my ($a, $b, $c, $top, $x, $y, $left, $right);
     ($a, $b, $c)  = @_[0];
     ($x, $y)      = @_[1]{'x', 'y'};
     $top          = @_[2];
     ($left, $right) = ($top.left, $top.right);
     ...
 }

 foo([1, 2, 3], { x => 1, y => 2 });

=item

As a consequence, object constructor calls must be written in coercion form:

 ::Foo( x => 1, y => 2 );   # NOT Foo.new

=item

Only allow item context.

=item

No laziness; all List are Sequences.

=item

No subtyping (inheritance) or role mixings.

=item

No first-class Capture and Signature objects, which means no \$x nor :(foo)

=item

No assignment, only bindings, but do not panic:

 $x := $x + 1;   # name = IntOp(named(Int))
 # $x = $x + 1

The reason is we have to eliminate one of them to avoid dealing with:

 $x := $y;
 $x = 123;

Because assignment always involve box(unbox()), so emitting the binding to Perl
5 is much more straightforward as $x is always just a Int in ($x := $x + 1),
never SomePossiblyTiedScalarContainerType that needs to have special FETCH magic
associated with $x.

Also it (WHAT IS "IT"?) is inevitable with eliminating list context, because:
 ($x, $y, $z) := (1, 2); # compile-time error.
 ($x, $y, $z) = (1, 2);  # list-context-undef-fill that we do not want to deal with.

Because infix:<=> almost always imply slurpiness with LHS is not a simple
scalar, eliminating it is consistent with eliminating list context.

=item

Annotations are preserved in Perl 5 emitted code using simple Typed vars:

 # MiniPerl6
 my Int $x;
 my perl5:CGI $x;

 # Compiled Perl 5
 my perl6::Int $x;
 my CGI $x;

The compiler adds no extra assertions, there for using types will not degrade
performance in MiniPerl6 land.

=item

No coroutines. No continuations

=item

Categories and precedence levels

=item

; no BEGIN blocks!

=back

=head2 Can mp6 be run in perl5?

Yes.  Perl5 is currently the only fully working backend.

=head2 Can mp6 be run in pugs?

We are not aware of anyone who has tried.  Please let us know, if someone has
tried.

=head2 Can mp6 be run in parrot?

There is an implementation of a parrot emitter, but the emitter cannot run
full-mp6 yet.

The implementation of the PAST emitter was also under way.

=head2 Can mp6 be run in ruby/javascript/c#/c/d ?

There is some work done for a D implementation.

Ruby and Javascript can probably reuse some work that was done for redsix and pil2js.

=head2 Running mp6

There are control scripts for compiling mp6 to several backends:

Perl 5:

 perl mp6-perl5-boot.pl < source.pl > dest.pl

Parrot:

 perl mp6-parrot.pl < source.pl > dest.pir

Parrot-PAST:

 perl mp6-past.pl < source.pl > dest.past

=over

=item Bootstrapping mp6-perl5:

This script rebuilds the lib5 directory. It creates a directory named lib5-new:

  cd pugs/v6/v6-MiniPerl6
  perl util/build-perl5.sh
  mv lib5 lib5-old
  mv lib5-new lib5

=item What subset of Perl 6 is covered by kp6?

kp6 reuses the mp6 grammar.  The main differences are not visible - kp6 adds an
extra (Abstract Syntax Tree) AST processing step.
kp6 adds:

 - lexical subs
 - metamodel interface
 - lexical classes (planned, not implemented)
 - begin blocks
 - containers

=item Running kp6

kp6 works by creating a parse tree, which is then submitted to a list of AST
processors called "Visitors" (namespace C<KindaPerl6::Visitor::*>).  Which is
then handed off to the KindaPerl6/Visitor/Emit/Perl5.pm to be translated into
perl5.

script/kp6 is one of the possible compiler 'workflows' that can be built with
kp6.  You can specify other workflows such as lisp by specifying a different
backend with -B, perldoc script/kp6 for more info.

perl script/kp6 -o dest.pm source.pm

 perl script/kp6 -e 'say 42;'
 ---
 42

To execute a Perl 6 script directly type

 perl script/kp6 source.p6

=item Compiling kp6

As of this writing, kp6 is not bootstrapped (in progress though).

The kp6 source files can be compiled with mp6 (whith the exception of the
KindaPerl6::Runtime::Perl6::* files, which are compiled wih kp6). There
is a 'mp6.pl' script in kp6 directory:

Please use the make file to compile these.

 make forcerecompile
 make
 make test

These will force compilation of various files.

Example:

 perl mp6.pl < lib/KindaPerl6/Visitor/EmitPerl5.pm > lib5/KindaPerl6/Visitor/EmitPerl5.pm
 -or-
 perl mp6.pl -o lib5/KindaPerl6/Visitor/EmitPerl5.pm lib/KindaPerl6/Visitor/EmitPerl5.pm

=back

=head2 How much of the test suite passes?

A few tests pass.

In mp6, you can pass t/01-sanity/01-tap.t by preprocess by removing of
"use v6-alpha;" and wrapping the input in "class Main {...}". See pugs/project_planning/TALK.
Some tests pass for kp6. See end of file in v6/v6-KindaPerl6/scripts/run_test.pl

=head2 How much of the test suite will eventually pass?

Passing tests depends on improving the grammar and the runtime.
Instead, kp6 focus is now on bootstraping.


=head2 Why does parsing take so much time?

The parser is recursive-descent.

 "Ziggy6" pasted "Total Elapsed Time = 20.53264"
 Total Elapsed Time = 20.53264 Seconds
 User+System Time = 19.45264 Seconds
 Exclusive Times
 %Time ExclSec CumulS #Calls sec/call Csec/c  Name
 42.7   8.307  8.446 253776   0.0000 0.0000  MiniPerl6::Perl5::Match::new
 30.4   5.918  5.876 150690   0.0000 0.0000  MiniPerl6::Perl5::Match::to
 15.0   2.919 11.171  36356   0.0001 0.0003  MiniPerl6::Grammar::ws
 8.58   1.669  1.688 253776   0.0000 0.0000  MiniPerl6::Perl5::Match::DESTROY
 5.58   1.085  1.037 259216   0.0000 0.0000  MiniPerl6::Perl5::Match::__ANON__
 5.36   1.042 12.035  20975   0.0000 0.0006  MiniPerl6::Grammar::opt_ws
 4.67   0.909  2.824  36400   0.0000 0.0001  MiniPerl6::Grammar::newline
 ...

The code generated by the parser makes several method calls on each
character - this can be optimized with inlining (not planned for mp6).
A MiniPerl6::Perl5::Match is created for every character.

=head2 Why isn't kp6 self-hosting?

kp6 will be self-hosting. The process depends on a fast enough parse engine and porting
thing using the mp6 calling conventions.

=head2  What is the plan for kp6?

=over

=item Provide a minimal bootstrapped language implementation for bootstrapping p6-on-p6.

Extra features over mp6 - allow the implementation of BEGIN blocks, flexible grammar.

=item Implement a flexible/pluggable compiler engine.

This is currently done with a Visitor pattern for AST transforms.

=item Lexical subs

Allows operator redefinition:

my multi infix:<+> { ... }

But note that 'multi' is not part of the kp6 spec.

=item Lexical classes / first-class classes.

Better support for grammar mutability:

 $?GRAMMAR   Which grammar am I in? (from S02)
 @?GRAMMAR   Which nested grammars am I in?

Update: Lexical classes will not be implemented.

=item Metamodel interface

Allow pluggable object models.

=item BEGIN blocks

BEGIN blocks are needed to seperate compile-time from run-time.

=item Containers

This is needed to implement assignment - MP6 only supported binding.

=back

=head2 Is kp6 needed for bootstrapping perl 6 on perl 6?

No. perl 6 on perl 6 can also be bootstrapped with:

 - Parrot
 - Pugs
 - v6.pm
 - Plain mp6
 - Redsix L<http://dev.pugscode.org/browser/misc/pX/Common/redsix>

=head2 How to use kp6 to compile everything.

TODO: make KP6-BOOT

=head2 How to: make / compile / test  -  kp6

=over

=item Download KindaPerl6.

 svn co http://svn.pugscode.org/pugs/

=item To compile KP6.

 perl Makefile.PL
 make -j 3 test

I<-j 3 means do 3 jobs at once, great for systems with SMP>

=item To re-compile KP6.

 make clean
 perl Makefile.PL
 make -j 3 test

=item Force re-compilation of everything.

 make forcerecompile
 setenv PERL5LIB "./inc/v6-MiniPerl6-lib5" (XXX can this step be removed?)
 make

I<WARNING: Do NOT use -j when forcing a recompile!, this will cause the Makefile
to crash.  The make process will attempt to use code that has not yet been
compiled.>

=item To execute a script.

 perl scripts/kp6 [perl6 file]


=item To compile a perl6 script and view resulting source:

 perl scripts/kp6 -o [outputfile.pl] [source perl6 file]

=item To debug perl6 in perl5 code scripts.

 setenv PERL5LIB compiled/perl5-kp6-mp6/lib
 perl -d (some script)
 DB> $DB::deep = 500;

I<Do to the recurisve nature of the code, you're likely to hit 100 pertty fast.>

=back

=head2 Miscellaneous Notes

L<http://irclog.perlgeek.de/perl6/2007-01-22#i_-60765>

fglock: hmm - maybe for mp6; need to find a way to do eval() to

L<http://cataclysm.cx/2006/08/19/closures-in-c/>

 Closures in C
 By: eaten by a grue

=head2 See Also

A Two-Dimensional Separation of Concerns for Compiler Construction

L<http://www.cis.uab.edu/gray/Pubs/sac-2005-carl.pdf>

- Compares the visitor pattern (used by kp6) with other approaches

=head1 AUTHORS

The Pugs Team E<lt>perl6-compiler@perl.orgE<gt>.

=head1 SEE ALSO

The Perl 6 homepage at L<http://dev.perl.org/perl6>.

The Pugs homepage at L<http://pugscode.org/>.

=head1 COPYRIGHT

Copyright 2007 by Flavio Soibelmann Glock and others.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut