Previous Contents Next

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 arguments

The 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).
        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 options

The 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 directory dir.

8.4   Common errors

Errors 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:

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 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:
The external is defined more than once in the the custom runtime runtime-name, as specified by the option -jcrun runtime-name. Note that this error is flagged a bit late, while attempting to generate join-calculus executables intended to run on runtime-name.
All other errors are bugs, either in the compiler or documentation. Please report them.
Previous Contents Next