cvsuser 04/02/24 02:25:20
Modified: . MANIFEST
config/gen/makefiles root.in
Added: config/gen/platform/win32 signal.c
docs native_exec.pod
Log:
Attached patch adds user documentation for the native object execution
mechanism and fixes up associated bits of the Makefile. There might be minor
errors since I'm not very familiar with the internals, so anyone who is may
want to make corrections.
Courtesy of Adam Thomason
Revision Changes Path
1.565 +2 -0 parrot/MANIFEST
Index: MANIFEST
===================================================================
RCS file: /cvs/public/parrot/MANIFEST,v
retrieving revision 1.564
retrieving revision 1.565
diff -u -w -r1.564 -r1.565
--- MANIFEST 24 Feb 2004 00:04:47 -0000 1.564
+++ MANIFEST 24 Feb 2004 10:25:02 -0000 1.565
@@ -168,6 +168,7 @@
config/gen/platform/win32/io.h []
config/gen/platform/win32/misc.c []
config/gen/platform/win32/misc.h []
+config/gen/platform/win32/signal.c []
config/gen/platform/win32/signal.h []
config/gen/platform/win32/time.c []
config/init/data.pl []
@@ -215,6 +216,7 @@
docs/jit.pod [main]doc
docs/memory_internals.pod [main]doc
docs/mmd.pod [main]doc
+docs/native_exec.pod [main]doc
docs/overview.pod [main]doc
docs/parrot.pod [main]doc
docs/parrotbyte.pod [main]doc
1.1 parrot/config/gen/platform/win32/signal.c
Index: signal.c
===================================================================
/*
* empty to prevent inclusion of generic/signal.c
*/
1.1 parrot/docs/native_exec.pod
Index: native_exec.pod
===================================================================
=head1 TITLE
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.
1.183 +4 -4 parrot/config/gen/makefiles/root.in
Index: root.in
===================================================================
RCS file: /cvs/public/parrot/config/gen/makefiles/root.in,v
retrieving revision 1.182
retrieving revision 1.183
diff -u -w -r1.182 -r1.183
--- root.in 21 Feb 2004 15:36:14 -0000 1.182
+++ root.in 24 Feb 2004 10:25:19 -0000 1.183
@@ -1,4 +1,4 @@
-# $Id: root.in,v 1.182 2004/02/21 15:36:14 leo Exp $
+# $Id: root.in,v 1.183 2004/02/24 10:25:19 leo Exp $
###############################################################################
#
@@ -1096,7 +1096,7 @@
$(LINK) ${ld_out}$(EXEC) $(LINKFLAGS) $(EXEC)$(O) $(SRC)/exec_start$(O)
$(LIBPARROT) $(C_LIBS)
exec_so : $(SRC)/exec_start$(O) blib/lib/libparrot$(SO)
- $(LINK) ${ld_out}$(EXEC) $(LINKFLAGS) $(EXEC)$(O) $(SRC)/exec_start$(O)
-lparrot $(C_LIBS) -pthread
+ $(LINK) ${ld_out}$(EXEC) $(LINKFLAGS) $(EXEC)$(O) $(SRC)/exec_start$(O)
-lparrot $(C_LIBS)
###### OS depend targets ##########
# libnci.so used by t/pmc/nci.t
@@ -1130,10 +1130,10 @@
echo 'end' >> hello.pasm
hello.pbc: hello.pasm
- parrot -o hello.pbc hello.pasm
+ ./parrot -o hello.pbc hello.pasm
hello$(O): hello.pbc
- parrot -o hello$(O) hello.pbc
+ ./parrot -o hello$(O) hello.pbc
hello: hello$(O)
$(MAKE) EXEC=hello exec
