# Copyright: 2001-2004 The Perl Foundation.  All Rights Reserved.
# $Id: native_exec.pod 5463 2004-02-28 00:30:43Z mikescott $

=head1 NAME

docs/native_exec.pod - Parrot Native Object Execution Subsystem

=head1 Overview

On supported platforms, Parrot can use the JIT subsystem to assemble a
native executable binary from a Parrot program.  This method wraps the
VM runtime engine and a precompiled Parrot program into a single binary.

=head1 Generating a native executable

Generating a native executable is done in three steps: building a
packfile, assembling a native object, and then linking the native
executable.  The packfile is generated in the standard way from .imc or
.pasm source by IMCC.  For a program in myprog.pasm:

    ./parrot -o myprog.pbc myprog.pasm

This generates the myprog.pbc packfile.  The native object is generated
similarly:

    ./parrot -o myprog.o myprog.pbc

This creates a native object called myprog.o.  Assembly of the
executable is done by the "exec" target in the root Makefile like so:

    make EXEC=myprog exec

This generates the "myprog" executable, which runs equivalently to

    ./parrot -j myprog.pbc

minus the time required to JIT-compile the bytecode.
    
The "testexec" Makefile target demonstrates this method for a "Hello
world" program.

=head1 Details

=head2 Platform support

The exec subsystem is enabled if support is determined automatically by
config/auto/jit.pl, or if --execcapable is explicitly specified to
Configure.pl.  The platform must support the JIT core, and some
additional scaffold in the exec* sources must be provided.
Implementation of such is beyond the scope of this document.

=head2 Native object generation

Native objects are generated by the "exec" run core.  This core uses the
JIT subsystem to compile a packfile to native instructions, then
serializes it to the platform's native object format.  This object is
then loaded at runtime and executed using the normal JIT core.

Unlike the standard cores (switch, computed goto, etc.) which are
activated by command-line switch, the exec core is invoked by IMCC when
the output file specified by the -o option has a .o extension.  When
creating a native object this way, IMCC requires that the input be a
packfile.  This process therefore must be performed in two steps,
building the packfile and assembling the native object, as demonstrated
above.

=head2 Executable generation

A native executable is generated by linking a native object against the
parrot library and the loader in exec_start.c.  The "exec" target in the
root Makefile does this with the compile flags used to build parrot
itself.  Alternatively it may be done by hand, e.g.

    gcc -o myprog myprog.o src/exec_start.o blib/lib/libparrot.a

Additional libraries may need to be included as appropriate for the
platform.
