docs/native_exec.pod

   1 # Copyright (C) 2001-2004, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/native_exec.pod - Parrot Native Object Execution Subsystem
   7
   8 =head1 Overview
   9
  10 On supported platforms, Parrot can use the JIT subsystem to assemble a native
  11 executable binary from a Parrot program.  This method wraps the VM runtime
  12 engine and a precompiled Parrot program into a single binary.
  13
  14 =head1 Generating a native executable
  15
  16 Generating a native executable is done in three steps: building a packfile,
  17 assembling a native object, and then linking the native executable.
  18
  19 The packfile is generated in the standard way from .pir or .pasm source by IMCC.
  20 For a program in myprog.pasm:
  21
  22     ./parrot -o myprog.pbc myprog.pasm
  23
  24 This generates the myprog.pbc packfile.  The native object is generated
  25 similarly:
  26
  27     ./parrot -o myprog.o myprog.pbc
  28
  29 This creates a native object called myprog.o.  Assembly of the executable is
  30 done by the "exec" target in the root Makefile like so:
  31
  32     make EXEC=myprog exec
  33
  34 This generates the "myprog" executable, which runs equivalently to
  35
  36     ./parrot -j myprog.pbc
  37
  38 minus the time required to JIT-compile the bytecode.
  39
  40 The "hello" target of the root Makefile demonstrates this method
  41 for a "Hello world" program.
  42
  43 =head1 Details
  44
  45 =head2 Platform support
  46
  47 The exec subsystem is enabled if support is determined automatically by
  48 config/auto/jit.pl, or if the option --execcapable is explicitly specified to
  49 Configure.pl.  The platform must support the JIT core, and some additional
  50 scaffold in the exec* sources must be provided.  Implementation of such is
  51 beyond the scope of this document.
  52
  53 =head2 Native object generation
  54
  55 Native objects are generated by the "exec" run core.  This core uses the JIT
  56 subsystem to compile a packfile to native instructions, then serializes it to
  57 the platform's native object format. This object is then loaded at runtime and
  58 executed using the normal JIT core.
  59
  60 Unlike the standard cores (switch, computed goto, etc.) which are activated by
  61 command-line switch, the exec core is invoked by IMCC when the output file
  62 specified by the -o option has a .o extension.  When creating a native object
  63 this way, IMCC requires that the input be a packfile.  This process therefore
  64 must be performed in two steps, building the packfile and assembling the native
  65 object, as demonstrated above.
  66
  67 =head2 Executable generation
  68
  69 A native executable is generated by linking a native object against the parrot
  70 library and the loader in exec_start.c.  The "exec" target in the root Makefile
  71 does this with the compile flags used to build parrot itself.  Alternatively it
  72 may be done by hand, e.g.
  73
  74     gcc -o myprog myprog.o src/exec_start.o blib/lib/libparrot.a
  75
  76 Additional libraries may need to be included as appropriate for the platform.
  77