CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• ENVIRONMENT
• FILES
• BUGS

#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 standalone 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 controlling.

#OPTIONS

#-L < library_directories >

Adds directories in library_directories to the compilation command.

#-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 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 executable 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.

#-regex <rename_regex>

Gives a rule rename_regex - which is a legal perl regular 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 verbose_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 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 version 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.

#-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 executables. 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 characters in its name.

#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

perlcc currently cannot compile shared objects on Win32. This should be fixed by perl5.005.

Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via the GitHub issue tracker or email regarding any issues with the site itself, search, or rendering of documentation.

The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via the Perl issue tracker, the mailing list, or IRC to report any issues with the contents or format of the documentation.