INSTALL - Build instructions for WDialog

Build instructions for the WDialog core

The following text describes how to compile and install the core of WDialog. Later you will find instructions for the Perl bindings.

Prerequisites

In general, a UNIX-conforming operating system is required. The UNIX tools like sed, grep, etc. are needed to build WDialog; furthermore, some parts of the software rely on the strict and well-known semantics of a UNIX operating system. (Linux and the BSD variants are counted as UNIX, here.)
The build system uses the GNU make tool. It is unlikely that other versions of the make tool work.
You need Objective Caml version 3.04 or later. The minimal requirement is the bytecode compiler, the native-code compiler is optional (not needed for the Perl bindings). It is recommended to enable dynamic loading of shared libraries (if supported on your platform; this is a requirement for the Perl bindings). Don't delete the source tree after installation if you want to make the Perl bindings.
Once you have Caml, don't forget to add the bin directory to your PATH, so the compiler can be found.
Next, you need the findlib library, available on Gerd Stolpmann's site about Caml. Use the latest version.
Next, you need Markus Mottl's bindings of Philip Hazel's PCRE library. Download both here. Important: Build the library with "make NO_CUSTOM=y", especially if you want to make the Perl bindings, too.
Next, you need the Ocamlnet library. The library parts "netstring" and "cgi" are required.
Next, you need Alain Frisch's ulex lexer generator.
Next, you need PXP, the XML parser for Caml. It is available on Gerd Stolpmann's site about Caml, too. Version 1.1.3 or later is required.

You should now be able to compile WDialog.

Configuration

There is a configure script in the distribution. If you only want to make the Caml library, just call

./configure

and see what it finds out. You can get a list of all options by running

./configure -help

However, options are normally not necessary because the tool findlib provides an automatic way to locate the prerequisites.

For the Perl bindings, you also have to specify -with-perl, and you must pass the path of the directory ocaml-3.04 containing the Caml sources:

-ocamltree /path/to/ocaml-3.04

Furthermore, you can specify a directory that will contain dynamically loaded libraries (default is /usr/local/libexec/wdialog):

-perl-libdir /path/to/dir

Compile

To make the bytecode version of the libraries and the tools, run

make all

from the top-level directory of the distribution. If you have ocamlopt, the native-code compiler, you can additionally run

make opt

and compile Wdialog to native machine code. It is not possible to leave the bytecode libraries out.

If you have configured the Perl bindings, these will not be made by one of these commands!

Install

Now run

make install

to install one or both versions of the libraries and tools. You may wonder where they are installed. This is determined by findlib, and you can run

ocamlfind printconf

to view the configuration of findlib. Look under "Packages will be installed in/removed from:". This directory will contain a subsdirectory for every major part that is installed (wdialog, wdialog-p4, wdialog-perlguts, wd-xmlcompiler, ocamlrun-dso, potentially more). "make install" is quite verbose, so just look at its output to get the details.

Uninstall

If you are totally disappointed, you can get rid of WDialog by removing all parts:

make uninstall

- or by running

ocamlfind remove name-of-part

for the individual parts.

Build instructions for the Perl Bindings

Prerequisities

It is required that the WDialog core is compiled and installed. Furthermore, it is strictly required that WDialog can be dynamically loaded. You can test this by running (the paths may differ on your system):

ocaml
        Objective Caml version 3.04

# #use "findlib";;
Findlib has been successfully loaded. Additional directives:
  #require "package";;      to load a package
  #list;;                   to list the available packages
  #camlp4o;;                to load camlp4 (standard syntax)
  #camlp4r;;                to load camlp4 (revised syntax)
  Topfind.reset();;         to force that packages will be reloaded

- : unit = ()
# #require "wdialog";;
Loading /opt/ocaml-3.04/site-lib/pcre/pcre.cma
Loading /opt/ocaml-3.04/lib/unix.cma
Loading /opt/ocaml-3.04/site-lib/netstring/netstring.cma
Loading /opt/ocaml-3.04/site-lib/netstring/netmappings_iso.cmo
Loading /opt/ocaml-3.04/site-lib/netstring/netmappings_other.cmo
Loading /opt/ocaml-3.04/site-lib/netstring/netstring_top.cmo
Loading /opt/ocaml-3.04/site-lib/pxp-engine/pxp_engine.cma
Loading /opt/ocaml-3.04/site-lib/cgi/cgi.cma
Loading /opt/ocaml-3.04/site-lib/pxp-lex-iso88591/pxp_lex_iso88591.cma
Loading /opt/ocaml-3.04/site-lib/pxp-lex-iso88591/pxp_lex_link_iso88591.cmo
Loading /opt/ocaml-3.04/site-lib/pxp-lex-utf8/pxp_lex_utf8.cma
Loading /opt/ocaml-3.04/site-lib/pxp-lex-utf8/pxp_lex_link_utf8.cmo
Loading /opt/ocaml-3.04/site-lib/wdialog/wdialog.cma
# #quit;;

It is important that you do not get any error message.

The build system currently requires a GNU environment (gcc). It is possible to port it to another type of operating system. Furthermore, it is required that the linker honours LD_RUN_PATH (and that gcc does not delete LD_RUN_PATH; some versions do).
I have tested it on Linux and Solaris, and with Perl 5.6.1.
Wdialog must have been configured with the options -with-perl, and -ocamltree. Note that -with-perl implies -with-wdialog-perlguts, and that a dynamically loadable version of the Caml bytecode interpreter will be compiled. So "make all" will additionally build the components "wdialog-perlguts" and "ocamlrun-dso".
You need camlidl, available on the Caml homepage. Follow the special instructions below to compile and install it.
Note that "make install" will install libraries in the directory specified by -perl-libdir.

Compile

Just enter

make perlapi

This will create a directory hierarchy under src/UI/blib.

Install

Run

make install-perlapi

to install it as Perl package. Furthermore, this command installs a number of O'Caml stub libraries into the -perl-libdir directory, in addition to the libraries that can already be found there. The Perl modules are dependent on these libraries, so make sure this directory is available when running Perl programs. The Perl installation is independent of the O'Caml installation.

Special instructions for camlidl (1.02)

Important: Version 1.04 of camlidl does not work (yet).

After unpacking the tar archive, do:

cd config
cp Makefile.unix Makefile

Edit the Makefile, and set the following variables properly: OCAMLLIB (to the output of "ocamlc -where"), BINDIR (where the tool camlidl will be installed; in doubt use the same directory as for "ocamlc").

Create a file runtime/dummies.c with the one-line contents:

int IID_IUnknown;

Change the "OBJS=" line in runtime/Makefile.unix to

OBJS=idlalloc.o comintf.o comerror.o dummies.o

You can now do (in the top-level directory of the distribution):

make all

- but this does not suffice, because this only builds the static version of the library. Do:

cd runtime
ocamlmklib -o camlidl idlalloc.o comintf.o comerror.o dummies.o
cd ../lib
ocamlmklib -o com -oc camlidl com.cmo
ocamlmklib -o com -oc camlidl com.cmx

Installation: Go back to the top-level directory, and create a file called META with the following contents:

requires = ""
version = "1.02"
directory = "^"
browse_interfaces = "Com"
archive(byte) = "com.cma"
archive(native) = "com.cmxa"

Install with

make install

(installs in the standard library directory of Caml), followed by

(O'Caml 3.04:) cp runtime/dllcamlidl.so $OCAMLLIB
(O'Caml 3.06:) cp runtime/dllcamlidl.so $OCAMLLIB/stublibs

(replace $OCAMLLIB by the path you entered in the Makefile), followed by

ocamlfind install camlidl META

such that findlib knows about camlidl.

WDialog