Using Oug from an IDE

The Oug distribution includes a server based on Odb-server, giving access to Oug functionalities from a development environment, through a socket.

The Odb "project" tool is used by the "Oug" tool to know the source files to analyze, and the compilation options needed (includes, ...) for each one.

Set up

The Odb server the client IDE connects to is the main Odb server. The "Oug" Odb tool can be in this main server, or in a secondary server (a server being client of the main server). In this latter case, the main server acts as a proxy for queries regarding the Oug tool.

The oug-odb program can be launched as main Odb server or secondary server. When launched as main server, it includes the "project" tool included in the Odb-server distribution. It only requires the following command to launch the server:

# oug-odb &

The -c option allows to launch a secondary server. It may be needed to use the -p option to make the server listen on port different from the default port, used by the main server. The sequence of commands used to launch the main server then the secondary server will be for example:

# odb-server &
# oug-odb -c -p 14000 &

the, the first thing to do is to make the "project" tool load the project file. This can be done on the command line (with the odb-client program) or from the client IDE with the command "load <project_file>". A simple way to launch the necessary servers and load the project file consists in placing all these instructions in a script launched at the beginning of a development session:

odb-server &
sleep 1
oug-odb -c -p 14000 &
odb-client "project: load myproject.odb"

Or, with oug-odb as main server:

oug-odb &
sleep 1
odb-client "project: load myproject.odb"

The commands provided by the Oug Odb tool are listed here with, for memory purpose, the ones of the "server" and "project" tools.

The Chamo plugin

If the Chamo plugin has been compiled (see file INSTALL), it can be used to communicate with the Oug tool in the Odb server, through new commands in Chamo.

To do so, one must either create a native code executable containing this module and adding commands to the editor, or either load this module in the bytecode version of the editor (chamo.byte).

Creating a native code Chamo

To create a native code Chamo with Oug features, one can simply use the make_my_chamo tool, by giving the additional libraries to include:

# make_my_chamo -o ougchamo.x dynlink.cmxa -I +odb-server -I +oug \
  odb.cmxa oug.cmxa oug_chamo.cmx ~/.cameleon2/

Then, one can launch the newly created editor ougchamo.x.

Loading Oug features in bytecode version of Chamo

Adding Oug features in Chamo is done by loading the modules oug.cma and oug_chamo.cmo installed with the other Oug files. There are various ways to do so:

  • Launch chamo.byte and enter the following command (use Meta-X to get the prompt to enter the command):
    eval "#directory \"+odb-server\" ;; #directory \"+oug\";; #load \"dynlink.cma\";; #load \"odb.cma\" ;; #load \"oug.cma\";; #load \"oug_chamo.cmo\";;"
  • Use the same command as above but on the command line used to launch Chamo:
    # chamo.byte -e 'eval #directory \"+odb-server\" ;; "#directory \"+oug\";; \
      #load \"dynlink.cma\";; #load \"odb.cma\" ;; #load \"oug.cma\";; \
      #load \"oug_chamo.cmo\";;"'
  • Write a file, for example, containing the following code:
    #directory "+odb-server";;
    #directory "+oug";;
    #load "dynlink.cma";;
    #load "odb.cma";;
    #load "oug.cma";;
    #load "oug_chamo.cmo";;
    Evaluate the code of this file, either from Chamo using the command
    or either by evaluating this file when launching Chamo:
    # chamo.byte -e "eval_file"
Using Oug features

Commands provided by the Chamo plugin send in background commands supported by the Oug tool, and use results to display information and navigate in the code.

Building the graph

The first thing to do is to build the graph corresponding to the source files. This is achieved using the Chamo command oug_reload_all.

The command oug_reload_all ask the "project" tool for the list of source files. These must be stored in a variable called srcfiles in the project file.

Using filters

The oug_filter_box command allows to list the elements matching a filter given in parameter, for example all the types:

Querying the graph

The elements selected by the filter are listed in a new window:

Displaying the filtered elements

Double-clicking on an element or pressing Enter in the list opens the corresponding source file at the location of the definition of the selected element.

The oug_filter_popup command works the same way but results are displayed in a popup menu instead of a window.

Browsing your code

In a .ml file, when the insertion cursor is located on an identifier,the oug_goto_pred command searches for the elements refering to this element and pops up a menu to select one of these. The corresponding source file is then open at the location of the selected element. The filter used in this case consider only -use-> and -create-> edges:

Querying referenced elements

Jumping to referenced elements

The function oug_goto_succ works the same way but looks for elements referenced by the element defined at the cursor position.

At last, the oug_goto_def command on an element moves the cursor to the position where the element is defined.