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.
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 :
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.
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
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.
Man(1) output converted with
man2html