X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/f64a6365a4321eb92de65e5c2074b53cd29e0ca6..817141f86f1dbef361684d7f42ab71cb4b9efe75:/README diff --git a/README b/README index 4e4ed25..e69b0ec 100644 --- a/README +++ b/README @@ -1,325 +1,131 @@ - Perl Compiler Kit, Version alpha4 +Perl is Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, +2013, 2014, 2015 by Larry Wall and others. All rights reserved. - Copyright (c) 1996, 1997, Malcolm Beattie - This program is free software; you can redistribute it and/or modify - it under the terms of either: + +ABOUT PERL +========== + +Perl is a general-purpose programming language originally developed for +text manipulation and now used for a wide range of tasks including +system administration, web development, network programming, GUI +development, and more. + +The language is intended to be practical (easy to use, efficient, +complete) rather than beautiful (tiny, elegant, minimal). Its major +features are that it's easy to use, supports both procedural and +object-oriented (OO) programming, has powerful built-in support for text +processing, and has one of the world's most impressive collections of +third-party modules. + +For an introduction to the language's features, see pod/perlintro.pod. + +For a discussion of the important changes in this release, see +pod/perldelta.pod. + +There are also many Perl books available, covering a wide variety of topics, +from various publishers. See pod/perlbook.pod for more information. + + +INSTALLATION +============ + +If you're using a relatively modern operating system and want to +install this version of Perl locally, run the following commands: + + ./Configure -des -Dprefix=$HOME/localperl + make test + make install + +This will configure and compile perl for your platform, run the regression +tests, and install perl in a subdirectory "localperl" of your home directory. + +If you run into any trouble whatsoever or you need to install a customized +version of Perl, you should read the detailed instructions in the "INSTALL" +file that came with this distribution. Additionally, there are a number of +"README" files with hints and tips about building and using Perl on a wide +variety of platforms, some more common than others. + +Once you have Perl installed, a wealth of documentation is available to you +through the 'perldoc' tool. To get started, run this command: + + perldoc perl + + +IF YOU RUN INTO TROUBLE +======================= + +Perl is a large and complex system that's used for everything from +knitting to rocket science. If you run into trouble, it's quite +likely that someone else has already solved the problem you're +facing. Once you've exhausted the documentation, please report bugs to us +using the 'perlbug' tool. For more information about perlbug, either type +'perldoc perlbug' or just 'perlbug' on a line by itself. + +While it was current when we made it available, Perl is constantly evolving +and there may be a more recent version that fixes bugs you've run into or +adds new features that you might find useful. + +You can always find the latest version of perl on a CPAN (Comprehensive Perl +Archive Network) site near you at http://www.cpan.org/src/ + +If you want to submit a simple patch to the perl source, see the "SUPER +QUICK PATCH GUIDE" in pod/perlhack.pod. + +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. + + +LICENSING +========= + +This program is free software; you can redistribute it and/or modify +it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or - 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 + 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, 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., 51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, 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. -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