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.

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.

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 arg₁ arg₂ ... arg_n

executes the compiled code contained in a.out, passing it as arguments the character strings arg₁ to arg_n.

On most Unix systems, the file produced by the linking phase can be run directly, as in:

        ./a.out arg₁ arg₂ ... arg_n

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 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. 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.