Version française
Home     About     Download     Resources     Contact us    
Browse thread
[Caml-list] O'Caml Runtime Environment (2)
[ Home ] [ Index: by date | by threads ]
[ Search: ]

[ Message by date: previous | next ] [ Message in thread: previous | next ] [ Thread: previous | next ]
Date: -- (:)
From: Gerd Stolpmann <info@g...>
Subject: [Caml-list] O'Caml Runtime Environment (2)
Hi list,

The O'Caml Runtime Environment bases now on GNU libtool, and it is now more
independent from the operating system (see my previous posting:
http://caml.inria.fr/archives/200106/msg00158.html). However, it currently only
works for ELF-based systems (but a class of systems is better than a single
system).

The URL is now 
http://www.ocaml-programming.de/packages/ocamlre/

You'll find the sources and an RPM for Linux there.

The rest of this message is the README of the distribution.
----------------------------------------------------------------------------

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

Run any bytecode file f using:

  ocamlre f <arg> ...

You can also prepend a #! /location/of/ocamlre line to the bytecode file f:

  echo "#! /location/of/ocamlre" >aux
  cat aux f >f_new
  chmod a+x f_new

Then, ./f_new automatically uses ocamlre to execute the bytecode.


ERROR DIAGNOSTICS:

If you get the message:

  ocamlre: Primitive xyz not found

a library is missing. You can check which libraries ocamlre includes
by just calling

  ocamlre

without arguments.


HOW TO BUILD AN APPLICATION FOR OCAMLRE:

- Build your application using ocamlc as usual. However, the last step
  should 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 ...

  If you do not change the last step, the resulting executable may be
  larger than necessary (because another runtime engine may be included
  into the file).

- 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 two-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 many operating systems (see below)
- I have not tried all libraries

So be prepared that there may be problems.

----------------------------------------------------------------------
Operating Systems
----------------------------------------------------------------------

Currently, an ELF-based operating system is required. I was able
to build ocamlre on Linux and Solaris, and because I am using
GNU libtool I expect that it is possible to build ocamlre on any
other ELF-based system. (Perhaps you need some minor modifications;
please let me know in these cases.)

(Note: ELF is a file format for binary executables and libraries
in the Unix world. ELF-based systems are: Linux, all BSD variants,
Solaris, OSF/1 and later, ...)

I tried hard to build ocamlre on Cygwin, but I failed. The reason
is that Windows DLLs are more restricted than ELF libraries. In
particular I had the problem to access global variables across
DLL boundaries. I do not think there is a simple solution, as
such variables are very frequent.

I tried to build ocamlre on AIX (4.2), but I failed. I had not
yet enough time to figure out the exact reason, but I fear that
.so dynamic objects are not allowed to be dependent on .a dynamic
objects. (Background: There is a "traditional" kind of shared libraries
in AIX, and a "modern" kind. The traditional .a objects cannot be
loaded by dlopen, but are used for all system libraries. The modern
.so objects can be loaded, but have a "dependency problem"; you have
to load all dependent objects yourself.)

I am now going to implement an alternative loading scheme which
does not use dlopen, but simply selects the appropriate executable
and execs it. 

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

Into the -bindir directory the runtime engine "ocamlre" will be installed.
The -libdir directory will contain the shared libraries. Do not specify
a system-wide library directory such as /usr/lib or /usr/local/lib, but
a private directory only for ocamlre.

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. The "ocamlre" binary contains the path of the
library directory hard-coded (such that you do not need to set the
LD_LIBRARY_PATH variable, or to enable the directory by other means).

----------------------------------------------------------------------
Deployment
----------------------------------------------------------------------

A bytecode executable created by O'Caml 3.01 can only be executed by
ocamlre-3.01, i.e. the ocaml and ocamlre versions must be the same.
For system-wide, non-experimental installations I recommend to 
include the version number into the library directory. 

Example: 

A hypothetical installation of ocamlre-3.01 and ocamlre-3.02:

/usr/local/bin/ocamlre:              symlink to ocamlre-3.02
/usr/local/bin/ocamlre-3.01          interpreter for version 3.01
/usr/local/bin/ocamlre-3.02          interpreter for version 3.02
/usr/local/lib/ocamlre-3.01/...      libraries for version 3.01
/usr/local/lib/ocamlre-3.02/...      libraries for version 3.02

A bytecode executable for version 3.01 would begin with
#! /usr/local/bin/ocamlre-3.01

and an executable for version 3.02 would begin with
#! /usr/local/bin/ocamlre-3.02

The symlink /usr/local/bin/ocamlre indicates the default version. It
must not occur in executables.

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

The ocamlre build process bases now on GNU libtool. To see how libtool
is called, look into the Makefiles, especially those named Makefile.ocamlre.


----------------------------------------------------------------------
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
otherlibs/unix/access.c            (because of a cygwin problem)

The modified lines/regions have been marked as PATCHED.

The toplevel directory contains additional files (libltdl, loader.c etc).
Furthermore, there is in every directory a Makefile.ocamlre that includes
the original Makefile, and that defines the additional rules dealing with
libtool.

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