Odb-server provides services to code editors and integrated development environments (IDEs) to get information about OCaml code being edited. In fact, Odb-server can be used to provide any service, but it was developped originally to make Oug able to provide services to code editors. A library is also included to add services to the server.

Project page on OCaml ForgeCode on GithubObjective-Caml

Odb-server is downloadable here.

You can also access the Git repository:

# git clone git://github.com/zoggy/odb-serv.git

Latest release is 0.1 (2011-11-09).

First release.

To install, follow the instructions in the INSTALL file coming with the distribution archive.

These are required to compile Odb-server:

• OCaml 3.12.0 or above,
• make.

Odb-server is distributed under the GPL license version 2.

Odb-server is about having a server the developer's IDE (emacs, chamo, vi, ...) connects to. Each provided service is composed of a tool name (a string) and a command.

Commands have the same form as shell commands, that is a command name followed by arguments, with these arguments separated by blanks; quotes can be used to specify an argument containing blanks.

Communication with the server uses sockets and a textual protocol.

The basic server contains the "server" and "project" tools, each one supporting various commands. More tools can be added, in two ways:

1. either with a plug-in given on the command-line when launching the server,
2. either by a secondary server connecting to the main server and indicating that it provides an additional tool, let's call it X. In this case, the main server acts as a proxy for the X tool: When the main server receives a query (1) concerning the X tool, it fowards the query to the secondary server (2) providing the services of this tool; the response obtained from the secondary server (3) is then forwarded to the client (4). The following figure illustrates this:
   
   
   The secondary server can also send queries to the main server, for example to retrieve information about the project.

So a development environment could include various tools provided by a main server and several secondary servers, each providing one or several tools. The load of a secondary server would not block other secondary servers.

The protocol used to exchange queries and responses is very simple.

Queries have the following form:

<tool> [options]
<command>

For example, to retrieve the contents of the includes variable for the file /home/foo/test.ml, the client will send the following query to the server, concerning the project tool:

project
attribute "/home/foo/test.ml" includes

The format of the responses is as simple:

<tool> <code> <len>
<contents
eventually on
more than one line, of length len>

Here is an exemple of possible response to the query above:

project 0 12
-I +lablgtk2

The Odb_comm module provides functions bo create, send and receive queries and responses.

The main server is launched with the command odb-server (or odb-server.byte for the bytecode version). From now on, we will talk only about the native code version, but the correspondance of filenames for the bytecode version is obvious.

It is possible to load plug-ins when launching the server. These plug-ins are OCaml object files. So the foo.cmxs plug-in will be loaded the following way:

# odb-server foo.cmxs &

The -h option prints the list of available options.

One can create another server, either to launch it as a main server, or either to launch it as secondary server. In both cases, several tools can be added to provide more services to the client.

The creation of a new server is quite simple; the code must perform the following actions:

1. Create one or more tools (see this section),
2. In the case of a secondary server, register this of these tools to the main server, using the function Odb_client.register_to_server,
3. Enter the loop handling queries with the function Odb_server.start_server.

The code of the Oug server can be used as example.

The basic (Odb-)server provides two tools, "server" and "project".

The "doc" command of the "server" tool generates a HTML page containing the documentation of available commands for each tool. Each tool must provide a "doc" command returning the HTML fragment describing its commands. One will use functions of the Odb_doc module to generate this documentation with correct format. The "doc" command of the "server" tool calls the "doc" command of each other tool and aggregates the results in a HTML page returned in the response. The page generated for the default tools is here.

This page can easily be obtained with the following command, which launches the server and uses the client program odb-client to retrieve the documentation page, redirected into a file:

# odb-server &
# odb-client "server: doc" > foo.html

The distribution includes a toy tool called "ocamlwc" usable as a starting base to create your own tools.

The code is here.

To compile:

# ocamlopt -g -shared -o ocamlwc.cmxs -thread ocamlwc.ml

To test, we launch the server by giving on the command line the plug-in to load:

# odb-server ocamlwc.cmxs &

Then, we can use the client to test. The first command calls the "comments" command of the "ocamlwc" tools on the "ocamlwc.ml" file. The second one generates the documentation of the available tools:

# ./odb-client "ocamlwc: comments ocamlwc.ml"
response header: ocamlwc 0 1
8
# ./odb-client "server: doc" > /tmp/t.html

The Odb_tools module contains the definition of tools, registration functions, ...

Maxence Guesdon.