From 12972c3cf44efc6a068d0c92b5e6565f8646ea59 Mon Sep 17 00:00:00 2001 From: Reini Urban Date: Sat, 13 Aug 2011 12:28:36 +0200 Subject: [PATCH] remove the rest of pod/perlcompile.pod perlcompile.pod is now maintained with B::C, and much more complete there. [Subsequent build and test fixes by the committer] --- MANIFEST | 1 - pod.lst | 2 - pod/perl.pod | 2 - pod/perlcompile.pod | 293 ----------------------------------------- pod/perlexperiment.pod | 2 - win32/pod.mak | 4 - 6 files changed, 304 deletions(-) delete mode 100644 pod/perlcompile.pod diff --git a/MANIFEST b/MANIFEST index 98593a1ead..a81d4ace24 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4420,7 +4420,6 @@ pod/perlcall.pod Perl calling conventions from C pod/perlcheat.pod Perl cheat sheet pod/perlclib.pod Internal replacements for standard C library functions pod/perlcommunity.pod Perl community information -pod/perlcompile.pod Perl compiler suite intro pod/perldata.pod Perl data structures pod/perldbmfilter.pod Perl DBM filters pod/perldebguts.pod Perl debugging guts and tips diff --git a/pod.lst b/pod.lst index b6729895a8..f7c65b4ec0 100644 --- a/pod.lst +++ b/pod.lst @@ -97,8 +97,6 @@ g perlmodlib Perl modules: how to write and use perlutil utilities packaged with the Perl distribution - perlcompile Perl compiler suite intro - perlfilter Perl source filters perldtrace Perl's support for DTrace diff --git a/pod/perl.pod b/pod/perl.pod index 84a04c501f..25e9996585 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -120,8 +120,6 @@ For ease of access, the Perl manual has been split up into several sections. perlutil utilities packaged with the Perl distribution - perlcompile Perl compiler suite intro - perlfilter Perl source filters perldtrace Perl's support for DTrace diff --git a/pod/perlcompile.pod b/pod/perlcompile.pod deleted file mode 100644 index dc829f45ef..0000000000 --- a/pod/perlcompile.pod +++ /dev/null @@ -1,293 +0,0 @@ -=head1 NAME - -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), 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 module provides access to the parse tree, and other modules -("back ends") do things with the tree. Some write it out as -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 back -end 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 module and its associated back ends 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? - -This document covers the use of the Perl compiler: which modules -it comprises, how to use the most important of the back end modules, -what problems there are, and how to work around them. - -=head2 Layout - -The compiler back ends are in the C hierarchy, and the front-end -(the module that you, the user of the compiler, will sometimes -interact with) is the O module. - -Here are the important back ends to know about, with their status -expressed as a number from 0 (outline for later implementation) to -10 (if there's a bug in it, we're very surprised): - -=over 4 - -=item B::Lint - -Complains if it finds dubious constructs in your source code. Status: -6 (it works adequately, but only has a very limited number of areas -that it checks). - -=item B::Deparse - -Recreates the Perl source, making an attempt to format it coherently. -Status: 8 (it works nicely, but a few obscure things are missing). - -=item B::Xref - -Reports on the declaration and use of subroutines and variables. -Status: 8 (it works nicely, but still has a few lingering bugs). - -=back - -=head1 Using The Back Ends - -The following sections describe how to use the various compiler back -ends. They're presented roughly in order of maturity, so that the -most stable and proven back ends are described first, and the most -experimental and incomplete back ends are described last. - -The O module automatically enabled the B<-c> flag to Perl, which -prevents Perl from executing your code once it has been compiled. -This is why all the back ends print: - - myperlprogram syntax OK - -before producing any other output. - -=head2 The Cross-Referencing Back End - -The cross-referencing back end (B::Xref) produces a report on your program, -breaking down declarations and uses of subroutines and variables (and -formats) by file and subroutine. For instance, here's part of the -report from the I program that comes with Perl: - - Subroutine clear_noremap - Package (lexical) - $ready_to_print i1069, 1079 - Package main - $& 1086 - $. 1086 - $0 1086 - $1 1087 - $2 1085, 1085 - $3 1085, 1085 - $ARGV 1086 - %HTML_Escapes 1085, 1085 - -This shows the variables used in the subroutine C. The -variable C<$ready_to_print> is a my() (lexical) variable, -Bntroduced (first declared with my()) on line 1069, and used on -line 1079. The variable C<$&> from the main package is used on 1086, -and so on. - -A line number may be prefixed by a single letter: - -=over 4 - -=item i - -Lexical variable introduced (declared with my()) for the first time. - -=item & - -Subroutine or method call. - -=item s - -Subroutine defined. - -=item r - -Format defined. - -=back - -The most useful option the cross referencer has is to save the report -to a separate file. For instance, to save the report on -I to the file I: - - $ perl -MO=Xref,-oreport myperlprogram - -=head2 The Decompiling Back End - -The Deparse back end turns your Perl source back into Perl source. It -can reformat along the way, making it useful as a deobfuscator. The -most basic way to use it is: - - $ perl -MO=Deparse myperlprogram - -You'll notice immediately that Perl has no idea of how to paragraph -your code. You'll have to separate chunks of code from each other -with newlines by hand. However, watch what it will do with -one-liners: - - $ perl -MO=Deparse -e '$op=shift||die "usage: $0 - code [...]";chomp(@ARGV=<>)unless@ARGV; for(@ARGV){$was=$_;eval$op; - die$@ if$@; rename$was,$_ unless$was eq $_}' - -e syntax OK - $op = shift @ARGV || die("usage: $0 code [...]"); - chomp(@ARGV = ) unless @ARGV; - foreach $_ (@ARGV) { - $was = $_; - eval $op; - die $@ if $@; - rename $was, $_ unless $was eq $_; - } - -The decompiler has several options for the code it generates. For -instance, you can set the size of each indent from 4 (as above) to -2 with: - - $ perl -MO=Deparse,-si2 myperlprogram - -The B<-p> option adds parentheses where normally they are omitted: - - $ perl -MO=Deparse -e 'print "Hello, world\n"' - -e syntax OK - print "Hello, world\n"; - $ perl -MO=Deparse,-p -e 'print "Hello, world\n"' - -e syntax OK - print("Hello, world\n"); - -See L for more information on the formatting options. - -=head2 The Lint Back End - -The lint back end (B::Lint) inspects programs for poor style. One -programmer's bad style is another programmer's useful tool, so options -let you select what is complained about. - -To run the style checker across your source code: - - $ perl -MO=Lint myperlprogram - -To disable context checks and undefined subroutines: - - $ perl -MO=Lint,-context,-undefined-subs myperlprogram - -See L for information on the options. - -=head1 Module List for the Compiler Suite - -=over 4 - -=item B - -This module is the introspective ("reflective" in Java terms) -module, which allows a Perl program to inspect its innards. The -back end modules all use this module to gain access to the compiled -parse tree. You, the user of a back end module, will not need to -interact with B. - -=item O - -This module is the front-end to the compiler's back ends. Normally -called something like this: - - $ perl -MO=Deparse myperlprogram - -This is like saying C in your Perl program. - -=item B::Concise - -This module prints a concise (but complete) version of the Perl parse -tree. Its output is more customizable than the one of B::Terse or -B::Debug (and it can emulate them). This module is useful for people who -are writing their own back end, or who are learning about the Perl -internals. It's not useful to the average programmer. - -=item B::Debug - -This module dumps the Perl parse tree in verbose detail to STDOUT. -It's useful for people who are writing their own back end, or who -are learning about the Perl internals. It's not useful to the -average programmer. - -=item B::Deparse - -This module produces Perl source code from the compiled parse tree. -It is useful in debugging and deconstructing other people's code, -also as a pretty-printer for your own source. See -L for details about usage. - -=item B::Lint - -This module inspects the compiled form of your source code for things -which, while some people frown on them, aren't necessarily bad enough -to justify a warning. For instance, use of an array in scalar context -without explicitly saying C is something that Lint -can identify. See L for details about usage. - -=item B::Showlex - -This module prints out the my() variables used in a function or a -file. To get a list of the my() variables used in the subroutine -mysub() defined in the file myperlprogram: - - $ perl -MO=Showlex,mysub myperlprogram - -To get a list of the my() variables used in the file myperlprogram: - - $ perl -MO=Showlex myperlprogram - -[BROKEN] - -=item B::Terse - -This module prints the contents of the parse tree, but without as much -information as B::Debug. For comparison, C -produced 96 lines of output from B::Debug, but only 6 from B::Terse. - -This module is useful for people who are writing their own back end, -or who are learning about the Perl internals. It's not useful to the -average programmer. - -=item B::Xref - -This module prints a report on where the variables, subroutines, and -formats are defined and used within a program and the modules it -loads. See L for details about -usage. - -=back - -=head1 KNOWN PROBLEMS - -BEGIN{} blocks are executed while 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{}. - -=head1 AUTHOR - -This document was originally written by Nathan Torkington, and is now -maintained by the perl5-porters mailing list -I. - -=cut diff --git a/pod/perlexperiment.pod b/pod/perlexperiment.pod index 7efabb7c29..f304120bc6 100644 --- a/pod/perlexperiment.pod +++ b/pod/perlexperiment.pod @@ -80,8 +80,6 @@ Introduced in Perl 5.005 Removed in Perl 5.9.0 -See also L - =item C can now have an experimental optional attribute C Introduced in Perl 5.8.0 diff --git a/win32/pod.mak b/win32/pod.mak index 5cc65730d2..a21500a7b2 100644 --- a/win32/pod.mak +++ b/win32/pod.mak @@ -80,7 +80,6 @@ POD = perl.pod \ perlcheat.pod \ perlclib.pod \ perlcommunity.pod \ - perlcompile.pod \ perldata.pod \ perldbmfilter.pod \ perldebguts.pod \ @@ -228,7 +227,6 @@ MAN = perl.man \ perlcheat.man \ perlclib.man \ perlcommunity.man \ - perlcompile.man \ perldata.man \ perldbmfilter.man \ perldebguts.man \ @@ -376,7 +374,6 @@ HTML = perl.html \ perlcheat.html \ perlclib.html \ perlcommunity.html \ - perlcompile.html \ perldata.html \ perldbmfilter.html \ perldebguts.html \ @@ -524,7 +521,6 @@ TEX = perl.tex \ perlcheat.tex \ perlclib.tex \ perlcommunity.tex \ - perlcompile.tex \ perldata.tex \ perldbmfilter.tex \ perldebguts.tex \ -- 2.34.1