[Caml-list] ocamlre: O'Caml Runtime Environment

[Gerd Stolpmann <gerd@gerd-stolpmann.de>]

Hi list,

recently I have extracted the runtime system from the O'Caml distribution, and
built a new tarball from it. Furthermore, I included a dynamic loader for system
libraries (as discussed on this list some time ago). The resulting interpreter
can now execute _all_ O'Caml bytecode executables, and it is dynamically
extensible.

The goal of ocamlre is to establish O'Caml as a platform-independent language
(in the same way as Java). As executables are already platform-independent, the
missing component was a separate interpreter (you need not to download, compile
and install the full O'Caml distribution to run an application). In order to
make the usage of the interpreter simpler, I added the dynamic linking features
(note that there were several patches on this list, so I'm not the first one
implementing this).

Currently, I am able to compile ocamlre on Linux; I did not test other
operating systems. A Unix-style operating system is required (I don't know
enough about Windows and Mac). I know that Cygwin does not work yet, because
the creation of dynamic libraries seems to be rather complicated.

If you also think that a separate O'Caml Runtime Environment is useful, I would
like you to test it, especially on other operating systems, and to make it
really portable.

The rest of the message is the README file of ocamlre.

Gerd



PS: You can download ocamlre here:
http://www.ocaml-programming.de/packages/ocamlre-3.01-1.tar.gz

--

----------------------------------------------------------------------
This is the O'Caml Runtime Environment
----------------------------------------------------------------------

This distribution contains a subset of the O'Caml language, namely
the runtime environment. The runtime system has been slightly modified
and extended in order to allow dynamic loading of system libraries.
This means that the ocamlre interpreter is able to run any O'Caml 
executable that uses the following libraries:

- bigarray
- dbm
- graph
- labltk
- num
- str
- threads (only bytecode threads are supported)
- unix
- dynlink

The libraries are only loaded when needed.

EXAMPLE:

- Build your application using ocamlc as usual. However, the last step
  must be changed into a "-use-runtime" linker invocation:

  ocamlc -o my-executable -use-runtime my-interpreter module.cmo ...

  Here, my-interpreter has been previously built by

  ocamlc -o my-interpreter -make-runtime libxxx.cma ...

- Test: Try to run your application with your custom interpreter:

  my-interpreter my-executable ...

- Finally, you can throw away my-interpreter and start your application
  using ocamlre:

  ocamlre my-executable

Note that my-interpreter is only necessary because we need a reference
interpreter.

----------------------------------------------------------------------
This is an alpha release!
----------------------------------------------------------------------

ocamlre is currently a one-day hack, and there was up to now not very
much time to test it. I've been able to compile it on my Linux box
and to run several applications; however:

- I have not tried it under different operating systems
- I have not tried all libraries

So be prepared that there may be problems.


----------------------------------------------------------------------
Compiling ocamlre
----------------------------------------------------------------------

First call ./configure. This is almost the same configure script as
distributed with the O'Caml compiler, and the same arguments apply
(see INSTALL.ocaml).

EXAMPLE:

./configure -bindir /opt/ocaml-3.01/bin -libdir /opt/ocaml-3.01/ocamlre

Note that -with-pthread is not supported.

Then do:

	make

If everything works well, there is now the ocamlre executable in the 
top level directory.

Now a

	make install

installs the following files:

	ocamlre			into the binary directory
	lib*.so, lib*.prims	into the library directory

Note that "ocamlre" is not relocatable, i.e. you cannot change the directories
after the compilation.

----------------------------------------------------------------------
How it works
----------------------------------------------------------------------

You may have noticed that ocamlre is very small (usually < 20 kB). It loads
everything it needs from the shared libraries. The first step is that
libocamlrun.so is loaded, the core interpreter.

Now ocamlre tries to find out which additional libraries are needed.
For every library libxxx.so there is a corresponding list of primitives,
libxxx.prims. The executable to run contains a list of needed primitives.
ocamlre searches these primitives in the libxxx.prims files, and loads
the associated libraries.

Note that this approach of handling dynamic linking has the fundamental
disadvantage that libraries with overlapping sets of primitives cannot
be distinguished. For example, it is impossible to install both
camltk and labltk at the same time, as many primitives have equal
names.

-----------------------------------------------------------------------
How to install additional libraries
---------------------------------------------------------------------

- Make sure that the object files only contain position-independent code.

- Create a shared object libxxx.so

- Enumerate all your primitive names in a text file libxxx.prims,
  simply one primitive per line

- Install both libxxx.so and libxxx.prims in the configured library
  directory

That's all.

----------------------------------------------------------------------
PATCHED FILES
----------------------------------------------------------------------

The ocamlre package contains a subset of the full O'Caml distribution.
Most files are unmodified, except of the following:

configure
byterun/startup.c

The modified lines/regions have been marked as PATCHED.

-- 
----------------------------------------------------------------------------
Gerd Stolpmann      Telefon: +49 6151 997705 (privat)
Viktoriastr. 45             
64293 Darmstadt     EMail:   gerd@gerd-stolpmann.de
Germany                     
----------------------------------------------------------------------------
-------------------
Bug reports: http://caml.inria.fr/bin/caml-bugs  FAQ: http://caml.inria.fr/FAQ/
To unsubscribe, mail caml-list-request@inria.fr  Archives: http://caml.inria.fr