


PERLCC(1)        Perl Programmers Reference Guide       PERLCC(1)


NAME
       perlcc - frontend for perl compiler

SYNOPSIS
           %prompt  perlcc a.p        # compiles into executable 'a'

           %prompt  perlcc A.pm       # compile into 'A.so'

           %prompt  perlcc a.p -o execute  # compiles 'a.p' into 'execute'.

           %prompt  perlcc a.p -o execute -run # compiles 'a.p' into execute, runs on
                                               # the fly

           %prompt  perlcc a.p -o execute -run -argv 'arg1 arg2 arg3'
                                               # compiles into execute, runs with
                                               # arg1 arg2 arg3 as @ARGV

           %prompt perlcc a.p b.p c.p -regex 's/\.p/\.exe'
                                               # compiles into 'a.exe','b.exe','c.exe'.

           %prompt perlcc a.p -log compilelog  # compiles into 'a', saves compilation
                                               # info into compilelog, as well
                                               # as mirroring to screen

           %prompt perlcc a.p -log compilelog -verbose cdf
                                               # compiles into 'a', saves compilation
                                               # info into compilelog, being silent
                                               # on screen.

           %prompt perlcc a.p -C a.c -gen      # generates C code (into a.c) and
                                               # stops without compile.

           %prompt perlcc a.p -L ../lib a.c
                                               # Compiles with the perl libraries
                                               # inside ../lib included.


DESCRIPTION
       'perlcc' is the frontend into the perl compiler. Typing
       'perlcc a.p' compiles the code inside a.p into a stan-
       dalone executable, and perlcc A.pm will compile into a
       shared object, A.so, suitable for inclusion into a perl
       program via "use A".

       There are quite a few flags to perlcc which help with such
       issues as compiling programs in bulk, testing compiled
       programs for compatibility with the interpreter, and con-
       trolling.

OPTIONS
       -L < library_directories >
           Adds directories in library_directories to the compi-
           lation command.




2000-11-02                 perl v5.6.0                          1





PERLCC(1)        Perl Programmers Reference Guide       PERLCC(1)


       -I  < include_directories >
           Adds directories inside include_directories to the
           compilation command.

       -C   < c_code_name >
           Explicitly gives the name c_code_name to the generated
           file containing the C code which is to be compiled.
           Can only be used if compiling one file on the command
           line.

       -o   < executable_name >
           Explicitly gives the name executable_name to the exe-
           cutable which is to be compiled. Can only be used if
           compiling one file on the command line.

       -e   < perl_line_to_execute>
           Compiles 'one liners', in the same way that perl -e
           runs text strings at the command line. Default is to
           have the 'one liner' be compiled, and run all in one
           go (see -run); giving the -o flag saves the resultant
           executable, rather than throwing it away. Use '-argv'
           to pass arguments to the executable created.

       -b  Generates bytecode instead of C code.

       -opt
           Uses the optimized C backend (`B::CC')rather than the
           simple C backend (`B::C').  Beware that the optimized
           C backend creates very large switch structures and
           structure initializations.  Many C compilers find it a
           challenge to compile the resulting output in finite
           amounts of time.  Many Perl features such as `goto
           LABEL' are also not supported by the optimized C back-
           end.  The simple C backend should work in more
           instances, but can only offer modest speed increases.

       -regex   <rename_regex>
           Gives a rule rename_regex - which is a legal perl reg-
           ular expression - to create executable file names.

       -verbose <verbose_level>
           Show exactly what steps perlcc is taking to compile
           your code. You can change the verbosity level ver-
           bose_level much in the same way that the `-D' switch
           changes perl's debugging level, by giving either a
           number which is the sum of bits you want or a list of
           letters representing what you wish to see. Here are
           the verbosity levels so far :









2000-11-02                 perl v5.6.0                          2





PERLCC(1)        Perl Programmers Reference Guide       PERLCC(1)


               Bit 1(g):      Code Generation Errors to STDERR
               Bit 2(a):      Compilation Errors to STDERR
               Bit 4(t):      Descriptive text to STDERR
               Bit 8(f):      Code Generation Errors to file (B<-log> flag needed)
               Bit 16(c):     Compilation Errors to file (B<-log> flag needed)
               Bit 32(d):     Descriptive text to file (B<-log> flag needed)

           If the -log tag is given, the default verbose level is
           63 (ie: mirroring all of perlcc's output to both the
           screen and to a log file). If no -log tag is given,
           then the default verbose level is 7 (ie: outputting
           all of perlcc's output to STDERR).

           NOTE: Because of buffering concerns, you CANNOT shadow
           the output of '-run' to both a file, and to the
           screen! Suggestions are welcome on how to overcome
           this difficulty, but for now it simply does not work
           properly, and hence will only go to the screen.

       -log <logname>
           Opens, for append, a logfile to save some or all of
           the text for a given compile command. No rewrite ver-
           sion is available, so this needs to be done manually.

       -argv <arguments>
           In combination with `-run' or `-e', tells perlcc to
           run the resulting executable with the string arguments
           as @ARGV.

       -sav
           Tells perl to save the intermediate C code. Usually,
           this C code is the name of the perl code, plus '.c';
           'perlcode.p' gets generated in 'perlcode.p.c', for
           example. If used with the `-e' operator, you need to
           tell perlcc where to save resulting executables.

       -gen
           Tells perlcc to only create the intermediate C code,
           and not compile the results. Does an implicit -sav,
           saving the C code rather than deleting it.

       -run
           Immediately run the perl code that has been generated.
           NOTE: IF YOU GIVE THE -run FLAG TO perlcc, THEN THE
           REST OF @ARGV WILL BE INTERPRETED AS ARGUMENTS TO THE
           PROGRAM THAT YOU ARE COMPILING.

       -prog
           Indicate that the programs at the command line are
           programs, and should be compiled as such. perlcc will
           automatically determine files to be programs if they
           have .p, .pl, .bat extensions.





2000-11-02                 perl v5.6.0                          3





PERLCC(1)        Perl Programmers Reference Guide       PERLCC(1)


       -mod
           Indicate that the programs at the command line are
           modules, and should be compiled as such. perlcc will
           automatically determine files to be modules if they
           have the extension .pm.

ENVIRONMENT
       Most of the work of perlcc is done at the command line.
       However, you can change the heuristic which determines
       what is a module and what is a program.  As indicated
       above, perlcc assumes that the extensions:

       .p$, .pl$, and .bat$

       indicate a perl program, and:

       .pm$

       indicate a library, for the purposes of creating executa-
       bles. And furthermore, by default, these extensions will
       be replaced (and dropped) in the process of creating an
       executable.

       To change the extensions which are programs, and which are
       modules, set the environmental variables:

       PERL_SCRIPT_EXT PERL_MODULE_EXT

       These two environmental variables take colon-separated,
       legal perl regular expressions, and are used by perlcc to
       decide which objects are which.  For example:

       setenv PERL_SCRIPT_EXT  '.prl$:.perl$' prompt%   perlcc
       sample.perl

       will compile the script 'sample.perl' into the executable
       'sample', and

       setenv PERL_MODULE_EXT  '.perlmod$:.perlmodule$'

       prompt%   perlcc sample.perlmod

       will  compile the module 'sample.perlmod' into the shared
       object 'sample.so'

       NOTE: the '.' in the regular expressions for
       PERL_SCRIPT_EXT and PERL_MODULE_EXT is a literal '.', and
       not a wild-card. To get a true wild-card, you need to
       backslash the '.'; as in:

       setenv PERL_SCRIPT_EXT '\.\.\.\.\.'

       which would have the effect of compiling ANYTHING (except
       what is in PERL_MODULE_EXT) into an executable with 5 less



2000-11-02                 perl v5.6.0                          4





PERLCC(1)        Perl Programmers Reference Guide       PERLCC(1)


       characters in its name.

       The PERLCC_OPTS environment variable can be set to the
       default flags that must be used by the compiler.

       The PERLCC_TIMEOUT environment variable can be set to the
       number of seconds to wait for the backends before giving
       up.  This is sometimes necessary to avoid some compilers
       taking forever to compile the generated output.  May not
       work on Windows and similar platforms.

FILES
       'perlcc' uses a temporary file when you use the -e option
       to evaluate text and compile it. This temporary file is
       'perlc$$.p'. The temporary C code is perlc$$.p.c, and the
       temporary executable is perlc$$.

       When you use '-run' and don't save your executable, the
       temporary executable is perlc$$

BUGS
       The whole compiler suite (`perlcc' included) should be
       considered very experimental.  Use for production purposes
       is strongly discouraged.

       perlcc currently cannot compile shared objects on Win32.
       This should be fixed in future.

       Bugs in the various compiler backends still exist, and are
       perhaps too numerous to list here.



























2000-11-02                 perl v5.6.0                          5


