1 # Copyright (C) 2001-2004, Parrot Foundation.
6 docs/native_exec.pod - Parrot Native Object Execution Subsystem
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.
14 =head1 Generating a native executable
16 Generating a native executable is done in three steps: building a packfile,
17 assembling a native object, and then linking the native executable.
19 The packfile is generated in the standard way from .pir or .pasm source by IMCC.
20 For a program in myprog.pasm:
22 ./parrot -o myprog.pbc myprog.pasm
24 This generates the myprog.pbc packfile. The native object is generated
27 ./parrot -o myprog.o myprog.pbc
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:
34 This generates the "myprog" executable, which runs equivalently to
36 ./parrot -R jit myprog.pbc
38 minus the time required to JIT-compile the bytecode.
40 The "hello" target of the root Makefile demonstrates this method
41 for a "Hello world" program.
45 =head2 Platform support
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.
53 =head2 Native object generation
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.
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.
67 =head2 Executable generation
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.
74 gcc -o myprog myprog.o src/exec_start.o blib/lib/libparrot.a
76 Additional libraries may need to be included as appropriate for the platform.