INSTALL

INSTALLATION OVERVIEW

To install Links, you'll need:

  * OCaml version 3.09.X
  * A webserver that can run CGI programs.

If you want to use a database, you should have the database as well as
the OCaml bindings for it. Database systems currently supported by
Links are PostgreSQL, MySQL, and SQLite.

SYSTEM REQUIREMENTS

If you can run OCaml, you should be able to compile and run Links. It
is known to build from source with OCaml versions 3.09.X on Linux,
Cygwin, and MacOS X.

Eventually we will provide a Links binary for Windows. It may be
possible to use the MinGW version of OCaml, though this requires
Cygwin to be installed, and linking to external database libraries is
somewhat involved.

INSTALLING OCAML

Visit http://caml.inria.fr/ and look for a "Download" link. Download
the OCaml 3.09 package and follow the instructions provided
with the OCaml for installing it on your platform.

BUILDING LINKS

To build, move to the Links source directory (wherever this INSTALL
file is) and run the following:

  $ make nc

If this fails, try:

  $ make 

This builds the byte-code version of Links, which should work on more
platforms than the other (native-code) version.

Now you should have an executable in the current directory called
`links'.

RUNNING LINKS

Start up the interactive interpreter using:

  $ ./links

You should see a Links prompt like this:

  links> _

Try evaluating some simple expressions. See the manual for more info
on writing Links expressions. Use 

  links> @quit; 

to exit the interactive interpreter.

To run Links web applications, see RUNNING WEB APPLICATIONS, below.

RUNNING THE TESTS

Note: make requires a unix-like environment in
order to run (this includes Cygwin and MinGW on Windows).

To check whether Links is working under your platform, try running the
automated tests as follows:

  $ make test-raw

This should give you a lot of output.

RUNNING WEB APPLICATIONS

Note: the install-demos script requires a unix-like environment in
order to run (this includes Cygwin on Windows).

Links works as an ordinary interpreter for CGI programs. To run a
Links web program, first make sure you have a working web server
that's configured to run CGI programs. Most web servers are configured
to do so by default. Refer to the documentation for your web server to
find out where to install CGI programs. Here, we'll call this
directory the cgi-bin directory, although it may not be called that on
your system; this is fine: just use the name of that directory
whenever we refer to `the cgi-bin directory'. 

To install the Links examples in your web directory and configure them
for your Links interpreter, just run

  $ ./install-examples

in the links directory. This will ask a number of questions about
where to install the examples. It installs:

 - the examples in your CGI directory,
 - the javascript library in the specified directory,
 - the sources and an HTML file in the specified directory, and
 - a configuration file in the CGI directory.

Now point your web browser at one of these examples. The URL for the
program will depend on your web server configuration and the place
where the demo was installed. Refer to your web server documentation
to find out how URLs on your server are formed. It may be something
such as

    http://localhost/cgi-bin/draggable.cgi

You should see the example right away. Have fun playing with it!

When you write your own Links programs, to use them under your web
server, you'll have to add a "shebang" line as the first line of your
program. The shebang line looks like this:

  #!/home/ezra/links/links --config=config

Where /home/ezra/links/links is the path to your Links interpreter,
and config is a configuration file.

The configuration file can contain a number of name=value pairs. It
is important that jsliburl is set to the base url for the javascript
library. Each setting must appear on a separate line, and white space
is significant.

DATABASE SUPPORT

To use a database with Links, you'll need to have one of the following
database systems, and the associated OCaml bindings for that database:

  * MySQL
  * PostgreSQL
  * SQLite

To build Links with database support, follow these steps:

  1. Copy Makefile.sample.config to Makefile.config, and fill in the
     path to the appropriate OCaml database library (this refers to
     the OCaml bindings, not the library that came with the
     database). For example:

       POSTGRESQL_LIBDIR=/usr/lib/ocaml/postgreqsql

  2. If you need to link against the database libraries themselves,
     you can add these to the EXTRA_LIBDIRS line in Makefile.
     
     For example, on MacOS X, I use this setting to include the 
     PostgreSQL libraries:
     
       EXTRA_LIBDIRS=/usr/local/pgsql/lib

  3. Rebuild links with:

       make nc

  4. Set up a configuration file to point Links at your database
     instance. Normally this is called 'links-config' and consists of a
     list of settings such as

       database_driver=postgresql

     To configure database access, the settings 'database_driver' and
     'database_args' should be set. 'database_driver' can take the
     values:

       postgresql, mysql or sqlite

      'database_args' is only relevant for postgres and mysql. It
      takes the form
 
        <host>:<port>:<user>:<password>

      To invoke Links using a particular config file, use the --config
      option, like so:

        ./links --config=<config-file> <source-file>

INSTALLING OCAML-MYSQL FOR CYGWIN

Download the ocaml-mysql package from:

  http://raevnos.pennmush.org/code/ocaml-mysql/

Run the configure script:

  ./configure

The generated Makefile doesn't do the right thing. Replace the
following lines:

  CLIBS=$(foreach lib, -lz , $(subst -l,,${lib}))
  export OCAMLMKLIB_FLAGS=-L/usr/local/lib/mysql

with:

  CLIBS=mysqlclient z
  INCDIRS=/usr/lib /usr/local/lib/mysql
  LIBDIRS=/usr/lib /usr/local/lib/mysql

To build it:

  make
  make opt

To install it. If you have ocamlfind, then

  make install

If you don't have ocamlfind, then try:

  mkdir /usr/local/lib/ocaml/mysql
  cp mysql.mli mysql.cmi mysql.cma mysql.cmx mysql.cmxa libmysql_stubs.a mysql.a /usr/local/lib/ocaml/mysql/

Finally, to build links with MySQL support, add the following line to
Makefile.config:

  MYSQL_LIBDIR=/usr/local/lib/ocaml/mysql


QUESTIONS

To learn more about Links, get help with installing or using Links, or
connect with other Links programmers, join the links-users mailing
list. Just send a message containing the word "subscribe" to this
address:

  links-users@inf.ed.ac.uk