Chapter 8 The compiler (jcc), advanced usage This chapter describes the advanced usage of the join-calculus compiler.
Advanced usage is linking together join-calculus and Objective Caml
code, producing both bytecode executable files and ``custom'' runtimes
to execute them.
Custom runtimes come in two flavors. Basically, a join-calculus
runtime is a program written in Objective Caml. Thus, it can be
compiled into Objective Caml bytecode (by using ocamlc) or into
native code (by using ocamlopt).
Bytecode runtimes favor compilation speed, while native code runtime
favor execution speed.
The join-calculus system can be either installed in ``native'' mode (when
both ocamlc and ocamlopt exist on your machine) or installed in
``bytecode'' mode (when ocamlopt is not available).
The native installation will produce native runtimes, wheras the
bytecode installation will produce bytecode runtimes.
8.1 When should I use custom runtimes ?Whenever you want to link together join-calculus and Caml code that
is not available in the standard join-calculus runtime.
Your custom runtime will be the standard join-calculus runtime linked
together with your own Caml code.
8.2 Advanced compiler argumentsThe join calculus compiler decodes the following additional arguments.
The output of the advanced linking phase is
a bytecode executable (let us say a.out) and a
custom runtime (let us say myjcrun).
Arguments ending in .jio are compiled interfaces. They contain
definitions for externals (i.e., join calculus names that are in fact
Objective Caml expressions). These definitions are used for producing custom
runtimes with a custom external table that includes library
externals and user defined externals.
Arguments ending in .ji are taken to be source files for
compilation unit interfaces. These are compiled into a .jio file and
used for producing custom runtimes.
Arguments ending in a caml suffix (i.e., .mli, .ml, .cmo, .cmi, .cma, .cmx or .cmax) are taken to be caml files. They are
passed to the Objective Caml compiler while building custom runtimes.
Arguments ending in .c are passed to the C compiler, which generates
a .o object file. This object file is linked with the
custom runtime. Note that this is very advanced usage.
Arguments ending in .o or .a are assumed to be C
object files and
libraries. They are passed to the Objective Caml linker that passes
them to the Unix linker when producing ultra-custom runtimes.
myjcrun a.out arg1 arg2 ... argn
executes the compiled code contained in a.out, passing it as
arguments the character strings arg1 to argn.
On most Unix systems, the file produced by the linking
phase can be run directly, as in:
./a.out arg1 arg2 ... argn
The produced file has the executable bit set, and it manages to launch
the appropriate bytecode interpreter by itself. Some errors occurs at
the Unix level when the operating system cannot find myjcrun. An
error is flagged by myjcrun when its external tables does not allow
the execution of a.out.
8.3 Advanced compiler optionsThe following advanced command-line options are recognized by jcc.
- -custom exec-name
Generate a custom runtime of the given name. This custom runtime is
built from the appropriate join-calculus compiled interface .jio
files and from Objective Caml or C object files or libraries.
- -jcrun exec-name
When generating join-calculus bytecode, the linker will use the
external table of exec-name which must exist and be executable.
The join-calculus executable will run on exec-name or on any
runtime that is compatible with it.
- -camlopt option
- Add option as an option to the
Objective Caml compiler, while building a custom runtime. For
instance, -camlopt "-I dir" causes
the Objective Caml compiler to add directory dir in its search path.
- -cclib -llibname
Pass the -llibname option to the C linker when linking in
``custom runtime'' mode. This causes the
given C library to be linked with the program.
- -ccopt option
Pass the given option to the C compiler and linker, when linking in
``custom runtime'' mode (see the -custom option). For instance,
-ccopt -Ldir causes the C linker to search for C libraries in
8.4 Common errorsErrors while generating custom runtimes may come from the Object Caml
compiler, which in turn may report errors from the C compiler. This
complicates correcting such errors.
A few errors are generated by jcc:
All other errors are bugs, either in the compiler or
documentation. Please report them.
Cannot create directory for temp files
The join-calculus compiler cannot create a subdirectory in the /tmp
to hold its temporary files, while generating a custom runtime. Fix:
usually /tmp is full, clean it and try again.
- Customize failed
The join-calculus compiler cannot execute runtime-name to
extract the external table from the runtime given by the -jcrun
runtime-name option, while generating custom bytecode to be
executed by runtime-name. Fix: make sure that
runtime-name is a valid invocation of an existing runtime. This
may require installing runtime-name in your execution path or
specifying runtime-name as an absolute file name.
- Cannot read config file
The join-calculus compiler successfully executed runtime-name to
extract the external table from the runtime given by the -jcrun
runtime-name option, but was then unable to read it. Fix:
difficult, something may be wrong in your join-calculus
installation or /tmp may be full.
- Custom runtime generation failed
The invocation of ocamlc or ocamlopt failed, while generating a
custom runtime. Fix: difficult, have a look at what jcc did by
reissuing your compilation command with the -v flag set and refer to
the Objective Caml documentation.
Such errors may arise, for instance, when the type of an external, as
specified in a .ji file, does not correspond with its type, as
inferred by the Objective Caml compiler.
- Error in externals: in mod, cannot find external: name
The join-calculus linker cannot find the external name in
module mod, while producing custom bytecode. That is, the
external mod.name does not exist in the runtime
runtime-name, as specified by the option -jcrun runtime-name. Fix: probably, runtime-name is not the right
runtime, or some .ji file was missing or incomplete at the time
runtime-name was built.
- Error in externals: double definition of external: mod.name
The external mod.name is defined more than once in the
the custom runtime runtime-name, as specified by the option -jcrun runtime-name.
this error is flagged a bit late, while attempting to generate
join-calculus executables intended to run on runtime-name.