PERLCC(1)

📦 version 1.57, in nixos 26.05, nixpkgs unstable

💖 PERLCC(1) — perlcc is literally that girl 💖

okay so welcome to the perlcc manual, bestie. this is the whole page for PERLCC(1), and we're gonna get through it together because you deserve to understand it. no cap. 💅

🌸 NAME 🌸

perlcc — generate executables from Perl programs.

periodt. that's the name.

✨ SYNOPSIS ✨

bestie, here's the whole mood board of invocations. every line is a real example, so keep the spelling exactly as shown:

           perlcc hello.pl            # Compiles into executable 'a.out'
           perlcc -o hello hello.pl   # Compiles into executable 'hello'

           perlcc -O file.pl          # Compiles using the optimised CC backend
           perlcc -O3 file.pl         # Compiles with C, using -O3 optimizations
           perlcc -B file.pl          # Compiles using the bytecode backend
           perlcc -B -m file.pm       # Compiles a module to file.pmc

           perlcc -c file.pl          # Creates a C file, 'file.c'
           perlcc -S -o hello file.pl # Keep C file
           perlcc -c out.c file.pl    # Creates a C file, 'out.c' from 'file'
           perlcc --staticxs -r -o hello hello.pl # Compiles,links and runs with
                                      # XS modules static/dynaloaded

           perlcc -e 'print q//'      # Compiles a one-liner into 'a.out'
           perlcc -c -e 'print q//'   # Creates a C file 'a.out.c'

           perlcc -I /foo hello       # extra headers for C
           perlcc -L /foo hello       # extra libraries for C
           perlcc --Wb=-Dsp           # extra perl compiler options
           perlcc -fno-delete-pkg     # extra perl compiler options
           perlcc --Wc=-fno-openmp    # extra C compiler options
           perlcc --Wl=-s             # extra C linker options

           perlcc -uIO::Socket        # force saving IO::Socket
           perlcc -UB                 # "unuse" B, compile without any B symbols

           perlcc -r hello            # compiles 'hello' into 'a.out', runs 'a.out'
           perlcc -r hello a b c      # compiles 'hello' into 'a.out', runs 'a.out'
                                      # with arguments 'a b c'

           perlcc hello -log c.log    # compiles 'hello' into 'a.out', log into 'c.log'

           perlcc -h                  # help, only SYNOPSIS
           perlcc -v2 -h              # verbose help, also DESCRIPTION and OPTIONS
           perlcc --version           # prints internal perlcc and the B-C release version

💅 DESCRIPTION 💅

okay so perlcc creates standalone executables from Perl programs, using the code generators provided by the B module. at present, you may either create executable Perl bytecode, using the -B option, or generate and compile C files using the standard and 'optimised' C backends. that's the whole deal. 💖

now the serious part, bestie: the code generated in this way is not guaranteed to work. the whole codegen suite (perlcc included) should be considered very experimental. use for production purposes is strongly discouraged. like, fr fr, do not ship this to prod and expect main character energy. 😭

🎀 OPTIONS 🎀

  • -LC library directories — adds the given directories to the library search path when C code is passed to your C compiler. for multiple paths use multiple -L options.
  • -IC include directories — adds the given directories to the include file search path when C code is passed to your C compiler; when using the Perl bytecode option, adds the given directories to Perl's include path. for multiple paths use multiple -I options.
  • -o output file name — specifies the file name for the final compiled executable.

without a given output file name we use the base of the input file, or with -e a.out resp. a.exe and a randomized intermediate C filename. if the input file is an absolute path on a non-windows system use the basename.

  • -c C file name — create C file only; do not compile and link to a standalone binary.
  • -e perl code — compile a one-liner, much the same as perl -e '...'
  • --check — pass -c flag to the backend, prints all backend warnings to STDOUT and exits before generating and compiling code. similar to perl -c.
  • --cross pathto/config.sh — use a different %B::C::Config from another config.sh for cross-compilation. passes -cross=path to the backend.
  • -S — "Keep source". do not delete generated C code after compilation.
  • -B — use the Perl bytecode code generator.
  • --debug or -D — shortcut for --Wb=-Dfull -S to enable all debug levels and also preserve source code; also view --Wb to enable some specific debugging options.
  • -O — use the 'optimised' C code generator B::CC. this is more experimental than everything else put together, and the code created is not guaranteed to compile in finite time and memory, or indeed, at all. 💀
  • -O1-4 — pass the numeric optimisation option to the compiler backend. shortcut for -Wb=-On.

this does not enforce B::CC.

  • -v 0-6 — set verbosity of output from 0 to max. 6.
  • -r — run the resulting compiled script after compiling it.
  • --log logfile — log the output of compiling to a file rather than to stdout.
  • -f<option> or --f=<option> — pass the options to the compiler backend, such as -fstash or -fno-delete-pkg.
  • --Wb=options — pass the options to the compiler backend, such as --Wb=-O2,-v.
  • --Wc=options — pass comma-seperated options to cc.
  • --Wl=options — pass comma-seperated options to ld.
  • -T or -t — run the backend using perl -T or -t.
  • -A — allow perl options to be passed to the executable first, like -D....

adds -DALLOW_PERL_OPTIONS which omits -- from being added to the options handler.

  • -u package — add package(s) to compiler and force linking to it.
  • -U package — skip package(s). do not compile and link the package and its sole dependencies.
  • --stash — detect external packages automatically via B::Stash.
  • --static — link to static libperl.a.
  • --staticxs — link to static XS if available. if the XS libs are only available as shared libs link to those (prelink).

systems without rpath (windows, cygwin) must extend LD_LIBRARY_PATH/PATH at run-time. together with -static, purely static modules and no run-time eval or require this will gain no external dependencies.

  • --shared — link to shared libperl.
  • --sharedxs — link shared XSUBs if the linker supports it. no DynaLoader needed. this will still require the shared XSUB libraries to be installed at the client, modification of @INC in the source is probably required. (Not yet implemented)
  • -m / --sharedlib [Modulename] — create a module, resp. a shared library. currently only enabled for Bytecode and CC. (not yet tested)
  • --testsuite — tries to be nice to Test:: modules, like preallocating the file handles 4 and 5, and munge the output of BEGIN.
perlcc -r --testsuite t/harness
  • --time — benchmark the different phases c (B::* compilation), cc (cc compile + link), and r (runtime).
  • --no-spawn — do not spawn subprocesses for compilation, because broken shells might not be able to kill its children.

okay that's the whole page, bestie — brought to you by perl v5.42.3, dated 2019-05-07, and the manual name is PERLCC(1). mwah 💋

📦 where this page comes from