# Copyright (C) 2001-2004, The Perl Foundation.
# $Id: embed.pod 14308 2006-08-22 17:14:31Z ambs $

=head1 NAME

embed.pod - Parrot embedding system

=head1 SYNOPSIS

    #include "parrot/embed.h"

    int main(int argc, char *argv[]) {
        Parrot_Interp interp;
        Parrot_PackFile pf;
        char * bcfile = "program.pbc";

        argc--; argv++; /* skip the program name */

        interp=Parrot_new(NULL);

        if(PARROT_JIT_CAPABLE) {
            Parrot_set_run_core(interp, PARROT_JIT_CORE);  /* activate JIT */
        }

        pf = Parrot_readbc(interp, bcfile);
        Parrot_loadbc(interp, pf);

        /* argc and argv as seen by the bytecode file */
        Parrot_runcode(interp, argc, argv);

        Parrot_destroy(interp);

        return 0;
    }

=head1 FILES

=over 4

=item F<include/parrot/embed.h>

=item F<embed.c>

=back

=head1 DESCRIPTION

Parrot's embedding system is designed with one guiding principle in mind:
encapsulation.  Users of Parrot shouldn't have to know what the insides of a
C<Parrot_Interp> structure look like or how to load a packfile.  They should
just know a few functions and constants.  The embedding system is designed to
do just that.

=head2 Data Structures

=over 4

=item C<Parrot_Interp>

This typedef represents (a pointer to) an actual Parrot interpreter.

=item C<Parrot_PackFile>

This structure represents (a pointer to) a 'packfile'--a Parrot bytecode file.

=item C<Parrot_Interp_flag>

An interpreter flag.

=item C<Parrot_Interp_flag_val>

The value passed in with an interpreter flag.  Unused at the moment--just pass
in C<NULL>.

=item C<Parrot_Int>

=item C<Parrot_UInt>

=item C<Parrot_Float>

=item C<Parrot_Opcode>

Various Parrot internal types; most are chosen at Configure time.

=back

=head2 Constants

B<interpreter core setting> is done by a call of C<Parrot_set_run_core()> like:

  Parrot_set_run_core(interp, PARROT_JIT_CORE);

See F</include/parrot/interpreter.h> for a list of available cores beside
PARROT_PREDEREF_CORE, PARROT_JIT_CORE.

=over

=item C<PARROT_PREDEREF_CORE>

This flag turns on predereferencing.  Parrot will transform many offsets in the
opcode stream to absolute pointers.

=item C<PARROT_JIT_CORE>

This flag turns on just-in-time compilation.  Parrot will convert the bytecode
file into native machine code and run it, usually resulting in substantial
speedup.

=back

B<Interpreter flags setting> is done by a call of C<Parrot_set_flag()> like>:

    Parrot_set_flag(interp, PARROT_TRACE_FLAG, NULL);

See F</include/parrot/interpreter.h> for an up to date list.

=over 4

=item C<PARROT_DEBUG_FLAG>

This flag turns on debugging mode.  Debugging mode basically means that
Parrot's core prints out diagnostic messages.  This flag does not take any
parameters.

=item C<PARROT_TRACE_FLAG>

This flag turns on opcode tracing.  Parrot will print out each opcode and the
parameters passed to it as it is called.  This flag does not take any
parameters.

=item C<PARROT_BOUNDS_FLAG>

This flag turns on bounds checking.  Parrot will make sure that all addresses
returned by an opcode function are within the boundaries of the bytecode block.
This flag does not take any parameters.

=item C<PARROT_PROFILE_FLAG>

This flag turns on profiling.  Parrot will print out a list of each opcode
called, the number of times it was called, the average time it took to run, and
the total time it took over the life of the program.  This flag does not take
any parameters.

=item C<PARROT_THR_TYPE_1>, C<PARROT_THR_TYPE_2>, C<PARROT_THR_TYPE_3>

This flags control the threading behavior. With C<PARROT_THR_TYPE_1>, threads
runs without sharing variables and do not communicate, With
C<PARROT_THR_TYPE_2>, threads shares no variables and communicate by sending
messages. With C<PARROT_THR_TYPE_3>, threads share variables. See
F<t/pmc/threads.t> for examples.

=back

B<Other constants:>

=over 4

=item C<PARROT_VERSION>

This constant contains a string representation of Parrot's version number.

=item C<PARROT_MAJOR_VERSION>

This constant contains the first part of Parrot's version number.

=item C<PARROT_MINOR_VERSION>

This constant contains the second part of Parrot's version number.

=item C<PARROT_PATCH_VERSION>

This constant contains the third part of Parrot's version number.

=item C<PARROT_CONFIG_DATE>

This constant contains the date that Configure was run to generate config.h.

=item C<PARROT_JIT_CAPABLE>

This constant is true if Parrot supports JIT on this platform, false otherwise.

=item C<PARROT_ARCHNAME>

This constant contains a string representation of the Parrot JIT's name for the
current architecture.

=item C<PARROT_CPU_ARCH>

This constant contains the name of your processor (as the JIT sees it).

=item C<PARROT_OS_NAME>

This constant contains the name of your operating system (as the JIT sees it).

=back

=head2 Functions

=over 4

=item C<Parrot_Interp Parrot_new(Parrot_Interp parent)>

Allocates and returns a new Parrot interpreter. C<parent> is NULL for the main
interpreter that will be destroyed last.

=item C<void Parrot_setflags(Parrot_Interp, Parrot_Interp_flag,
Parrot_Interp_flag_val)>

Sets a flag in the Parrot interpreter.

=item C<Parrot_PackFile Parrot_readbc(Parrot_Interp, char *filename)>

Reads in a bytecode file and returns a packfile structure for it.

=item C<void Parrot_loadbc(Parrot_Interp, Parrot_PackFile)>

Loads a packfile into a Parrot interpreter.

=item C<void Parrot_runcode(Parrot_Interp, int argc, char *argv[])>

Runs the bytecode associated with a Parrot interpreter.  C<argc> and C<argv>
are the parameters the bytecode should receive.

=item C<void Parrot_destroy(Parrot_Interp)>

Deallocates all memory associated with a Parrot interpreter.

B<XXX> At the moment, it just leaks most of it.

=back

=head1 COMPILING

Note: This section is aimed at you if you are writing an application
external to parrot which links against an installed parrot library.

Your application will need to include the appropriate header files and
link against parrot and its dependencies.

Since the location of these files can vary from platform to platform,
and build to build, a general method is provided to find out the
necessary flags to use.

pkg-config is a helper tool, now common on many platforms,
which many packages have adopted to provide the necessary compiler and
linker flags required to build against a library. parrot will install
a file called parrot.pc which can be queried using pkg-config.

To start with, let's find out what version of parrot is installed
by running pkg-config with the --modversion flag. If this command fails
with an error, skip to the bottom of this section.

  pkg-config --modversion parrot

To find out the necessary -I flags, use --cflags

  pkg-config --cflags parrot

and to find the necessary -L and -l flags, use --libs

  pkg-config --libs parrot

Where both compiling and linking are performed in one step, both sets
of flags can be queries with

  pkg-config --cflags --libs parrot

The pkg-config command can be incorporated with a compile as shown here.

  cc src/disassemble.c `pkg-config --cflags --libs parrot`

Most applications will probably choose to run pkg-config as part of a
configure script, so if you are using autoconf you could use a test
such as this.

  PARROT_REQUIRED_VERSION=0.4.1
  AC_SUBST(PARROT_REQUIRED_VERSION)
  PKG_CHECK_MODULES(PARROT, parrot >= $PARROT_REQUIRED_VERSION,
                    [AC_DEFINE([HAVE_PARROT], 1, [define if have parrot])])
  AC_SUBST(PARROT_LIBS)
  AC_SUBST(PARROT_CFLAGS)

If parrot has been installed system-wide, then any of the previous
lines should have returned the relevant flags. If it is not installed
in one of the standard places that pkg-config looks, then you will get
an error message.

  pkg-config --libs parrot
  Package parrot was not found in the pkg-config search path.
  Perhaps you should add the directory containing `parrot.pc'
  to the PKG_CONFIG_PATH environment variable
  No package 'parrot' found

As stated in the error message, an environment variable can be used to
make pkg-config look in more locations.

  export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

The last part of the variable will almost certainly be
.../lib/pkgconfig. This variable will have to be set in your login
scripts if you need it to be available in future.

=head1 SEE ALSO

F<embed.c> and F<embed.h> for the implementation.

F<src/test_main.c> for Parrot's use of the embedding system.

L<http://pkgconfig.freedesktop.org/wiki/> A pkg-config page

=cut