- Perl Compiler Kit, Version alpha4
- Copyright (c) 1996, 1997, Malcolm Beattie
+ Perl Kit, Version 5.0
+
+ Copyright 1989-2000, Larry Wall
+ All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of either:
Software Foundation; either version 1, or (at your option) any
later version, or
- b) the "Artistic License" which comes with this kit.
+ b) the "Artistic License" which comes with this Kit.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
the GNU General Public License or the Artistic License for more details.
- You should have received a copy of the Artistic License with this kit,
- in the file named "Artistic". If not, you can get one from the Perl
- distribution. You should also have received a copy of the GNU General
- Public License, in the file named "Copying". If not, you can get one
- from the Perl distribution or else write to the Free Software
- Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-CHANGES
-
-New since alpha3
- Anonymous subs work properly with C and CC.
- Heuristics for forcing compilation of apparently unused subs/methods.
- Subs which use the AutoLoader module are forcibly loaded at compile-time.
- Slightly faster compilation.
- Handles slightly more complex code within a BEGIN { }.
- Minor bug fixes.
-
-New since alpha2
- CC backend now supports ".." and s//e.
- Xref backend generates cross-reference reports
- Cleanups to fix benign but irritating "-w" warnings
- Minor cxstack fix
-New since alpha1
- Working CC backend
- Shared globs and pre-initialised hash support
- Some XSUB support
- Assorted bug fixes
-
-INSTALLATION
-
-(1) You need perl5.002 or later.
-
-(2) If you want to compile and run programs with the C or CC backends
-which undefine (or redefine) subroutines, then you need to apply a
-one-line patch to perl itself. One or two of the programs in perl's
-own test suite do this. The patch is in file op.patch. It prevents
-perl from calling free() on OPs with the magic sequence number (U16)-1.
-The compiler declares all OPs as static structures and uses that magic
-sequence number.
-
-(3) Type
- perl Makefile.PL
-to write a personalised Makefile for your system. If you want the
-bytecode modules to support reading bytecode from strings (instead of
-just from files) then add the option
- -DINDIRECT_BGET_MACROS
-into the middle of the definition of the CCCMD macro in the Makefile.
-Your C compiler may need to be able to cope with Standard C for this.
-I haven't tested this option yet with an old pre-Standard compiler.
-
-(4) If your platform supports dynamic loading then just type
- make
-and you can then use
- perl -Iblib/arch -MO=foo bar
-to use the compiler modules (see later for details).
-If you need/want instead to make a statically linked perl which
-contains the appropriate modules, then type
- make perl
- make byteperl
-and you can then use
- ./perl -MO=foo bar
-to use the compiler modules.
-In both cases, the byteperl executable is required for running standalone
-bytecode programs. It is *not* a standard perl+XSUB perl executable.
-
-USAGE
-
-As of the alpha3 release, the Bytecode, C and CC backends are now all
-functional enough to compile almost the whole of the main perl test
-suite. In the case of the CC backend, any failures are all due to
-differences and/or known bugs documented below. See the file TESTS.
-In the following examples, you'll need to replace "perl" by
- perl -Iblib/arch
-if you have built the extensions for a dynamic loading platform but
-haven't installed the extensions completely. You'll need to replace
-"perl" by
- ./perl
-if you have built the extensions into a statically linked perl binary.
-
-(1) To compile perl program foo.pl with the C backend, do
- perl -MO=C,-ofoo.c foo.pl
-Then use the cc_harness perl program to compile the resulting C source:
- perl cc_harness -O2 -o foo foo.c
-
-If you are using a non-ANSI pre-Standard C compiler that can't handle
-pre-declaring static arrays, then add -DBROKEN_STATIC_REDECL to the
-options you use:
- perl cc_harness -O2 -o foo -DBROKEN_STATIC_REDECL foo.c
-If you are using a non-ANSI pre-Standard C compiler that can't handle
-static initialisation of structures with union members then add
--DBROKEN_UNION_INIT to the options you use. If you want command line
-arguments passed to your executable to be interpreted by perl (e.g. -Dx)
-then compile foo.c with -DALLOW_PERL_OPTIONS. Otherwise, all command line
-arguments passed to foo will appear directly in @ARGV. The resulting
-executable foo is the compiled version of foo.pl. See the file NOTES for
-extra options you can pass to -MO=C.
-
-There are some constraints on the contents on foo.pl if you want to be
-able to compile it successfully. Some problems can be fixed fairly easily
-by altering foo.pl; some problems with the compiler are known to be
-straightforward to solve and I'll do so soon. The file Todo lists a
-number of known problems. See the XSUB section lower down for information
-about compiling programs which use XSUBs.
-
-(2) To compile foo.pl with the CC backend (which generates actual
-optimised C code for the execution path of your perl program), use
- perl -MO=CC,-ofoo.c foo.pl
-
-and proceed just as with the C backend. You should almost certainly
-use an option such as -O2 with the subsequent cc_harness invocation
-so that your C compiler uses optimisation. The C code generated by
-the Perl compiler's CC backend looks ugly to humans but is easily
-optimised by C compilers.
-
-To make the most of this compiler backend, you need to tell the
-compiler when you're using int or double variables so that it can
-optimise appropriately (although this part of the compiler is the most
-buggy). You currently do that by naming lexical variables ending in
-"_i" for ints, "_d" for doubles, "_ir" for int "register" variables or
-"_dr" for double "register" variables. Here "register" is a promise
-that you won't pass a reference to the variable into a sub which then
-modifies the variable. The compiler ought to catch attempts to use
-"\$i" just as C compilers catch attempts to do "&i" for a register int
-i but it doesn't at the moment. Bugs in the CC backend may make your
-program fail in mysterious ways and give wrong answers rather than just
-crash in boring ways. But, hey, this is an alpha release so you knew
-that anyway. See the XSUB section lower down for information about
-compiling programs which use XSUBs.
-
-If your program uses classes which define methods (or other subs which
-are not exported and not apparently used until runtime) then you'll
-need to use -u compile-time options (see the NOTES file) to force the
-subs to be compiled. Future releases will probably default the other
-way, do more auto-detection and provide more fine-grained control.
-
-Since compiled executables need linking with libperl, you may want
-to turn libperl.a into a shared library if your platform supports
-it. For example, with Digital UNIX, do something like
- ld -shared -o libperl.so -all libperl.a -none -lc
-and with Linux/ELF, rebuild the perl .c files with -fPIC (and I
-also suggest -fomit-frame-pointer for Linux on Intel architetcures),
-do "make libperl.a" and then do
- gcc -shared -Wl,-soname,libperl.so.5 -o libperl.so.5.3 `ar t libperl.a`
-and then
- # cp libperl.so.5.3 /usr/lib
- # cd /usr/lib
- # ln -s libperl.so.5.3 libperl.so.5
- # ln -s libperl.so.5 libperl.so
- # ldconfig
-When you compile perl executables with cc_harness, append -L/usr/lib
-otherwise the -L for the perl source directory will override it. For
-example,
- perl -Iblib/arch -MO=CC,-O2,-ofoo3.c foo3.bench
- perl cc_harness -o foo3 -O2 foo3.c -L/usr/lib
- ls -l foo3
- -rwxr-xr-x 1 mbeattie xzdg 11218 Jul 1 15:28 foo3
-You'll probably also want to link your main perl executable against
-libperl.so; it's nice having an 11K perl executable.
-
-(3) To compile foo.pl into bytecode do
- perl -MO=Bytecode,-ofoo foo.pl
-To run the resulting bytecode file foo as a standalone program, you
-use the program byteperl which should have been built along with the
-extensions.
- ./byteperl foo
-Any extra arguments are passed in as @ARGV; they are not interpreted
-as perl options. If you want to load chunks of bytecode into an already
-running perl program then use the -m option and investigate the
-byteload_fh and byteload_string functions exported by the B module.
-See the NOTES file for details of these and other options (including
-optimisation options and ways of getting at the intermediate "assembler"
-code that the Bytecode backend uses).
-
-(3) There are little Bourne shell scripts and perl programs to aid with
-some common operations: assemble, disassemble, run_bytecode_test,
-run_test, cc_harness, test_harness, test_harness_bytecode.
-
-(4) Walk the op tree in execution order printing terse info about each op
- perl -MO=Terse,exec foo.pl
-
-(5) Walk the op tree in syntax order printing lengthier debug info about
-each op. You can also append ",exec" to walk in execution order, but the
-formatting is designed to look nice with Terse rather than Debug.
- perl -MO=Debug foo.pl
-
-(6) Produce a cross-reference report of the line numbers at which all
-variables, subs and formats are defined and used.
- perl -MO=Xref foo.pl
-
-XSUBS
-
-The C and CC backends can successfully compile some perl programs which
-make use of XSUB extensions. [I'll add more detail to this section in a
-later release.] As a prerequisite, such extensions must not need to do
-anything in their BOOT: section which needs to be done at runtime rather
-than compile time. Normally, the only code in the boot_Foo() function is
-a list of newXS() calls which xsubpp puts there and the compiler handles
-saving those XS subs itself. For each XSUB used, the C and CC compiler
-will generate an initialiser in their C output which refers to the name
-of the relevant C function (XS_Foo_somesub). What is not yet automated
-is the necessary commands and cc command-line options (e.g. via
-"perl cc_harness") which link against the extension libraries. For now,
-you need the XSUB extension to have installed files in the right format
-for using as C libraries (e.g. Foo.a or Foo.so). As the Foo.so files (or
-your platform's version) aren't suitable for linking against, you will
-have to reget the extension source and rebuild it as a static extension
-to force the generation of a suitable Foo.a file. Then you need to make
-a symlink (or copy or rename) of that file into a libFoo.a suitable for
-cc linking. Then add the appropriate -L and -l options to your
-"perl cc_harness" command line to find and link against those libraries.
-You may also need to fix up some platform-dependent environment variable
-to ensure that linked-against .so files are found at runtime too.
-
-DIFFERENCES
-
-The result of running a compiled Perl program can sometimes be different
-from running the same program with standard perl. Think of the compiler
-as having a slightly different implementation of the language Perl.
-Unfortunately, since Perl has had a single implementation until now,
-there are no formal standards or documents defining what behaviour is
-guaranteed of Perl the language and what just "happens to work".
-Some of the differences below are almost impossible to change because of
-the way the compiler works. Others can be changed to produce "standard"
-perl behaviour if it's deemed proper and the resulting performance hit
-is accepted. I'll use "standard perl" to mean the result of running a
-Perl program using the perl executable from the perl distribution.
-I'll use "compiled Perl program" to mean running an executable produced
-by this compiler kit ("the compiler") with the CC backend.
-
-Loops
- Standard perl calculates the target of "next", "last", and "redo"
- at run-time. The compiler calculates the targets at compile-time.
- For example, the program
-
- sub skip_on_odd { next NUMBER if $_[0] % 2 }
- NUMBER: for ($i = 0; $i < 5; $i++) {
- skip_on_odd($i);
- print $i;
- }
-
- produces the output
- 024
- with standard perl but gives a compile-time error with the compiler.
-
-Context of ".."
- The context (scalar or array) of the ".." operator determines whether
- it behaves as a range or a flip/flop. Standard perl delays until
- runtime the decision of which context it is in but the compiler needs
- to know the context at compile-time. For example,
- @a = (4,6,1,0,0,1);
- sub range { (shift @a)..(shift @a) }
- print range();
- while (@a) { print scalar(range()) }
- generates the output
- 456123E0
- with standard Perl but gives a compile-time error with compiled Perl.
-
-Arithmetic
- Compiled Perl programs use native C arithemtic much more frequently
- than standard perl. Operations on large numbers or on boundary
- cases may produce different behaviour.
-
-Deprecated features
- Features of standard perl such as $[ which have been deprecated
- in standard perl since version 5 was released have not been
- implemented in the compiler.
-
-Others
- I'll add to this list as I remember what they are.
-
-BUGS
-
-Here are some things which may cause the compiler problems.
-
-The following render the compiler useless (without serious hacking):
-* Use of the DATA filehandle (via __END__ or __DATA__ tokens)
-* Operator overloading with %OVERLOAD
-* The (deprecated) magic array-offset variable $[ does not work
-* The following operators are not yet implemented for CC
- goto
- sort with a non-default comparison (i.e. a named sub or inline block)
-* You can't use "last" to exit from a non-loop block.
-
-The following may give significant problems:
-* BEGIN blocks containing complex initialisation code
-* Code which is only ever referred to at runtime (e.g. via eval "..." or
- via method calls): see the -u option for the C and CC backends.
-* Run-time lookups of lexical variables in "outside" closures
-
-The following may cause problems (not thoroughly tested):
-* Dependencies on whether values of some "magic" Perl variables are
- determined at compile-time or runtime.
-* For the C and CC backends: compile-time strings which are longer than
- your C compiler can cope with in a single line or definition.
-* Reliance on intimate details of global destruction
-* For the Bytecode backend: high -On optimisation numbers with code
- that has complex flow of control.
-* Any "-w" option in the first line of your perl program is seen and
- acted on by perl itself before the compiler starts. The compiler
- itself then runs with warnings turned on. This may cause perl to
- print out warnings about the compiler itself since I haven't tested
- it thoroughly with warnings turned on.
-
-There is a terser but more complete list in the Todo file.
-
-Malcolm Beattie
-2 September 1996
+ You should have received a copy of the Artistic License with this
+ Kit, in the file named "Artistic". If not, I'll be glad to provide one.
+
+ You should also have received a copy of the GNU General Public License
+ along with this program in the file named "Copying". If not, write to the
+ Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ 02111-1307, USA or visit their web page on the internet at
+ http://www.gnu.org/copyleft/gpl.html.
+
+ For those of you that choose to use the GNU General Public License,
+ my interpretation of the GNU General Public License is that no Perl
+ script falls under the terms of the GPL unless you explicitly put
+ said script under the terms of the GPL yourself. Furthermore, any
+ object code linked with perl does not automatically fall under the
+ terms of the GPL, provided such object code only adds definitions
+ of subroutines and variables, and does not otherwise impair the
+ resulting interpreter from executing any standard Perl script. I
+ consider linking in C subroutines in this manner to be the moral
+ equivalent of defining subroutines in the Perl language itself. You
+ may sell such an object file as proprietary provided that you provide
+ or offer to provide the Perl source, as specified by the GNU General
+ Public License. (This is merely an alternate way of specifying input
+ to the program.) You may also sell a binary produced by the dumping of
+ a running Perl script that belongs to you, provided that you provide or
+ offer to provide the Perl source as specified by the GPL. (The
+ fact that a Perl interpreter and your code are in the same binary file
+ is, in this case, a form of mere aggregation.) This is my interpretation
+ of the GPL. If you still have concerns or difficulties understanding
+ my intent, feel free to contact me. Of course, the Artistic License
+ spells all this out for your protection, so you may prefer to use that.
+
+--------------------------------------------------------------------------
+
+Perl is a language that combines some of the features of C, sed, awk
+and shell. See the manual page for more hype. There are also many Perl
+books available, covering a wide variety of topics, from various publishers.
+See pod/perlbook.pod for more information.
+
+Please read all the directions below before you proceed any further, and
+then follow them carefully.
+
+After you have unpacked your kit, you should have all the files listed
+in MANIFEST.
+
+Installation
+
+1) Detailed instructions are in the file "INSTALL", which you should
+read if you are either installing on a system resembling Unix
+or porting perl to another platform. For non-Unix platforms, see the
+corresponding README.
+
+2) Read the manual entries before running perl.
+
+3) IMPORTANT! Help save the world! Communicate any problems and suggested
+patches to perlbug@perl.com so we can keep the world in sync.
+If you have a problem, there's someone else out there who either has had
+or will have the same problem. It's usually helpful if you send the
+output of the "myconfig" script in the main perl directory.
+
+If you've succeeded in compiling perl, the perlbug script in the "utils"
+subdirectory can be used to help mail in a bug report.
+
+If possible, send in patches such that the patch program will apply them.
+Context diffs are the best, then normal diffs. Don't send ed scripts--
+I've probably changed my copy since the version you have.
+
+The latest versions of perl are always available on the various CPAN
+(Comprehensive Perl Archive Network) sites around the world.
+See <URL:http://www.perl.com/CPAN/src/>.
+
+
+Just a personal note: I want you to know that I create nice things like this
+because it pleases the Author of my story. If this bothers you, then your
+notion of Authorship needs some revision. But you can use perl anyway. :-)
+
+ The author.