Permalink
Browse files

improve pods

git-svn-id: http://perl-compiler.googlecode.com/svn/trunk@1155 ed534f1a-1453-0410-ab30-dfc593a8b23c
  • Loading branch information...
1 parent e95233c commit 3c1ce403e01e423ded4e2da9ea5a98328b7030f4 @rurban committed Sep 30, 2011
Showing with 72 additions and 97 deletions.
  1. +9 −6 Changes
  2. +1 −0 MANIFEST
  3. +43 −74 perlcompile.pod
  4. +19 −17 perloptree.pod
View
@@ -24,15 +24,18 @@
* CC (1.11): allow debugging without -MOd=CC
Try to jump from last to unknown label, put labels also onto cxstack.
Fixed cc_last.t test 4, jump out of anonsub, but not across C
- functions yet (this is disallowed in C, need to split)
- * C.xs: added B::REGEXP::EXTFLAGS (missing from B)
+ functions yet (this is disallowed in C, need to split).
+ * C.xs: added B::REGEXP::EXTFLAGS (missing from B).
* t/cc_last.t: Fixed test 2. This works compiled and uncompiled,
but the returned errcode is not compared. Skip if so.
- * t/TESTS: add all 5 possible method/sub calls to test 35 => 01234
- * ramblings/*.patches: CORE patches added and recommended in README.
- * ramblings/blogs-debugging-article[1-4].pod: added to MANIFEST
+ * t/TESTS: add all 5 possible method/sub calls to test 35 =>
+ 01234. See http://blogs.perl.org/users/rurban/2011/06/how-perl-calls-subs-and-methods.html
* t/stash.t: fixed 5.8.8 stashes (overload, threads, ...)
- * t/issue71.t: added
+ * t/issue71.t: added, but not fixed yet
+ * ramblings/*.patches: CORE patches added and recommended in README.
+ * ramblings/blogs-debugging-article[1-4].pod: added to MANIFEST.
+ * perlcompile.pod, perloptree.pod: improved.
+ * ramblings/yapceu_2010.pod: added.
1.34 2011-06-12 rurban
* Makefile.PL: fixed make install < 5.13.7
View
@@ -74,6 +74,7 @@ ramblings/reg.alloc
ramblings/revert-B-load-BEGIN.patch
ramblings/runtime.porting
ramblings/yapc_bratislava08.pod
+ramblings/yapceu_2010.pod
regen_lib.pl
script/assemble
script/cc_harness
View
@@ -5,53 +5,32 @@ perlcompile - Introduction to the Perl Compiler-Translator
=head1 DESCRIPTION
Perl has always had a compiler: your source is compiled into an
-internal form (a parse tree) which is then optimized before being
-run. Since version 5.005, Perl has shipped with a module
-capable of inspecting the optimized parse tree (C<B>), and this has
-been used to write many useful utilities, including a module that lets
-you turn your Perl into C source code that can be compiled into a
-native executable.
-
-The C<B> module provides access to the parse tree, and other modules
-("backends") do things with the tree. Some write it out as
-bytecode, C source code, or a semi-human-readable text. Another
-traverses the parse tree to build a cross-reference of which
-subroutines, formats, and variables are used where. Another checks
-your code for dubious constructs. Yet another backend dumps the
-parse tree back out as Perl source, acting as a source code beautifier
-or deobfuscator.
+internal form (a parse tree, "optree") which is then optimized before
+being run. Since version 5.005, Perl has shipped with a module
+capable of inspecting the optimized optree (L<B>), and this has been
+used to write many useful utilities, including the L<B::C> and
+L<B::CC> modules that lets you turn your Perl into C source code that
+can be compiled into a native executable.
+
+The C<B> module provides access to the optree, and other modules
+("backends") do things with the tree. Some write it out as bytecode
+L<B::Bytecode>, C source code L<B::C>, or a semi-human-readable text.
+Another L<B::Xref> traverses the parse tree to build a cross-reference
+of which subroutines, formats, and variables are used where. Another
+L<B::Lint> checks your code for dubious constructs. L<B::Deparse>
+dumps the parse tree back out as Perl source, acting as a source code
+beautifier or deobfuscator.
Because its original purpose was to be a way to produce C code
corresponding to a Perl program, and in turn a native executable, the
-C<B> module and its associated backends are known as "the
-compiler", even though they don't really compile anything.
-Different parts of the compiler are more accurately a "translator",
-or an "inspector", but people want Perl to have a "compiler
-option" not an "inspector gadget". What can you do?
+C<B> module and its associated backends, mainly L<B::C>, L<B::CC> and
+L<B::Bytecode> are known as "the compiler", even though they don't
+really compile anything.
This document covers the use of the Perl compiler: which modules
it comprises, how to use the most important of the backend modules,
what problems there are, and how to work around them.
-=head2 Other perl to exe compilers
-
-Maybe you want to look for the free L<PAR> module or some commercial
-products, like C<perl2exe> at L<http://www.indigostar.com/perl2exe.htm>
-and C<perlapp> as C<PerlDevKit> from ActiveState at
-L<http://www.activestate.com/Products/perl_dev_kit/>
-
-These are technically no compilers, just source packagers with a
-simple native code unpacker. Run-time behaviour is actually slower
-than with a normal perl source or real compiler, because of the
-additional unpacking and check steps. It's just convenient to have
-single file applications.
-
-The simpliest windows I<"compiler"> would be then F<pl2exe.pl>
-in L<C::DynaLib>.
-
-Several years ago the C<undump> functionality used to work on several
-platforms. See L<perlrun> for C<-u>.
-
=head2 Layout
The compiler backends are in the C<B::> hierarchy, and the front-end
@@ -681,43 +660,46 @@ usage.
=head1 KNOWN PROBLEMS
BEGIN{} blocks are executed before compiling your code. Any external
-state that is initialized in BEGIN{}, such as opening files, initiating
-database connections etc., do not behave properly. To work around
-this, Perl has an INIT{} block that corresponds to code being executed
-before your program begins running but after your program has finished
-being compiled. Execution order: BEGIN{}, (possible save of state
-through compiler back-end), INIT{}, program runs, END{}.
+state that is initialized in BEGIN{}, such as main code in use'd
+modules, opening files, initiating database connections etc., do not
+behave properly. To work around this, Perl has an INIT{} block that
+corresponds to code being executed before your program begins running
+but after your program has finished being compiled. Execution order:
+BEGIN{}, (possible save of state through compiler back-end), INIT{},
+program runs, END{}.
CC backend: goto, sort with non-default comparison. last for non-loop blocks.
-improve XSUB handling (both static and dynamic)
-
-sv_magic can do SvREFCNT_inc(obj) which messes up precalculated refcounts.
-
-allocation of XPV[INAHC]V structures needs fixing: Perl tries to free
- them, whereas the compiler expects them to be linked to a xpv[inahc]v_root
-
-list the same as X[IPR]V structures.
-
ref counts
perl_parse replacement
fix cstring for long strings
-compile-time initialisation of AvARRAYs
-
signed/unsigned problems with NV (and IV?) initialisation and elsewhere?
CvOUTSIDE for ordinary subs
-DATA filehandle for standalone Bytecode program (easy)
+See F<STATUS>
+
+=head2 Other perl to exe compilers
+
+Maybe you want to look for the free L<PAR> module or some commercial
+products, like C<perl2exe> at L<http://www.indigostar.com/perl2exe.htm>
+and C<perlapp> as C<PerlDevKit> from ActiveState at
+L<http://www.activestate.com/Products/perl_dev_kit/>
-DATA filehandle for multiple bytecode-compiled modules (harder)
+These are technically no compilers, just B<source packagers> with a
+simple native code unpacker. Run-time behaviour is actually slower
+than with a normal perl source or real compiler, because of the
+additional unpacking and check steps. It's just convenient to have
+single file applications.
-DATA filehandle for C-compiled program (yet harder)
+The simpliest windows I<"compiler"> would be then F<pl2exe.pl>
+in L<C::DynaLib>.
-pad panics since 5.10
+Several years ago the C<undump> functionality used to work on several
+platforms. See L<perlrun> for C<-u>. Work is planned to revive C<undump>.
=head1 AUTHOR
@@ -730,19 +712,6 @@ compiler module, maintained by Reini Urban I<rurban@cpan.org>.
=head1 SEE ALSO
-L<perlguts>
-
-L<http://books.simon-cozens.org/index.php/Perl_5_Internals>
-with a simplier version at L<http://www.faqs.org/docs/perl5int/>.
-
-"Hacking the Optree for Fun..." at L<http://www.perl.com/pub/a/2002/05/07/optree.html>,
-the next step by Simon Cozens.
-
-Joshua ben Jore wrote a 50 minute presentation on
-"Perl 5 VM" guts at L<http://diotalevi.isa-geek.net/~josh/Presentations/Perl%205%20VM/>
-focusing on the optree for SPUG, the Seattle Perl User's Group.
-
-The attempt for a new L<perloptreeguts> manual at
-L<http://www.perlfoundation.org/perl5/index.cgi?optree_guts>
+L<perlguts>, L<illguts>, L<perloptree>
=cut
View
@@ -8,11 +8,11 @@ Various material about the internal Perl compilation representation
during parsing and optimization, before the actual execution
begins, represented as C<B> objects, the B<"B" op tree>.
-The well-known L<perlguts.pod> focuses more on the internal
+The well-known L<perlguts>.pod focuses more on the internal
representation of the variables, but not so on the structure, the
sequence and the optimization of the basic operations, the ops.
-And we have L<perlhack.pod>, which shows e.g. ways to hack into
+And we have L<perlhack>.pod, which shows e.g. ways to hack into
the op tree structure within the debugger. It focuses on getting
people to start patching and hacking on the CORE, not
understanding or writing compiler backends or optimizations,
@@ -44,7 +44,7 @@ of the following to be called (oversimplifying a bit):
newBINOP(OP_MULTIPLY, flags, newSVREF($b), newSVREF($c))
)
-See also L<perlhack.pod#Op Trees>
+See also L<perlhack#Op Trees>
The simpliest type of an op structure is C<OP>, a L</BASEOP>: this
has no children. Unary operators, L</UNOP>s, have one child, and
@@ -1117,10 +1117,10 @@ subname(args...) =>
=head2 Call a method
Here we have several combinations to define the package and the method name, either
-compile-time (static as constant string), or dynamic as B<GV> (subname) or
-B<GVSV>/B<PADSV> (package name).
+compile-time (static as constant string), or dynamic as B<GV> (for the method name) or
+B<PADSV> (package name).
-B<method_named> holds the method name as C<sv> if know at compile time.
+B<method_named> holds the method name as C<sv> if known at compile time.
If not B<gv> (of the name) and B<method> is used.
The package name is at the top of the stack.
A call stack is added with B<pushmark>.
@@ -1130,27 +1130,27 @@ A call stack is added with B<pushmark>.
Class->subname(args...) =>
pushmark
- const PV => "Class"
+ const => PV "Class"
args ...
- method_named => "subname"
+ method_named => PV "subname"
entersub
2. Run-time package ("object") and compile-time method:
-$obj->subname(args...) =>
+$obj->meth(args...) =>
pushmark
- padsv/gvsv => *packagename
+ padsv => GV *packagename
args ...
- method_named => "subname"
+ method_named => PV "meth"
entersub
3. Run-time package and run-time method:
$obj->$meth(args...) =>
pushmark
- padsv/gvsv => *packagename
+ padsv => GV *packagename
args ...
gvsv => GV *meth
method
@@ -1161,7 +1161,7 @@ $obj->$meth(args...) =>
Class->$meth(args...) =>
pushmark
- const PV => "Class"
+ const => PV "Class"
args ...
gvsv => GV *meth
method
@@ -1230,7 +1230,7 @@ manipulate these values array.
Malcom Beattie's B modules hooked into the early op tree stages to
represent the internal ops as perl objects and added the perl compiler
-backends. See L<B> and L<perlcompile.pod>.
+backends. See L<B> and L<perlcompile>.
The three main compiler backends are still B<Bytecode>, B<C> and B<CC>.
@@ -1268,7 +1268,9 @@ op tree, and can be therefore converted outside of the CHECK block,
which means you can easier debug the conversion (= compilation)
process. To debug the CHECK block in the B backends you have to
use the L<B::Debugger> B<Od> or B<Od_o> modules, which defer the
-CHECK to INIT.
+CHECK to INIT. Debugging the highly recursive data is not easy,
+and often problems can not be reproduced in the B debugger because
+the B debugger influences the optree.
B<kurila> L<http://search.cpan.org/dist/kurila/> uses MAD to convert
Perl 5 source to the kurila dialect.
@@ -1398,11 +1400,11 @@ So this is about 30% of the basic op tree information so far. Not speaking about
the guts. Simon Cozens and Scott Walters have more 30%, in the source are more
10% to copy&paste, and in the compilers and run-time information is the rest. I
hope with the help of some hackers we'll get it done, so that some people will
-begin poking around in the B backends. And write the wonderful new dump/undump
+begin poking around in the B backends. And write the wonderful new C<dump>/C<undump>
functionality (which actually worked in the early years on Solaris) to
save-image and load-image at runtime as in LISP, analyse and optimize the
output, output PIR (parrot code), emit LLVM or another JIT optimized code or
even write assemblers. I have a simple one at home. :)
Written 2008 on the perl5 wiki with socialtext and pod in parallel
-by Reini Urban, CPAN ID rurban.
+by Reini Urban, CPAN ID C<rurban>.

0 comments on commit 3c1ce40

Please sign in to comment.