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.
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).
To install, follow the instructions in the INSTALL file coming with the distribution archive.
These are required to compile Odb-server:
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:
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" includesThe format of options is not yet specified.
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:
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 "project" tool uses a project description file to know the source files and the compilation options associated to each file. An example of such a file is here.
The distribution includes a toy tool called "ocamlwc" usable as a starting base to create your own tools.
The code is here.
# 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, ...