Previous Up Next

Chapter 11  Cameleon

11.1  Introduction

The Cameleon tool is the glue between the other tools, to provide an integrated development environment. Files are managed with CVS, it includes various editors and a documentation browser. Plug-ins can be loaded to add functionalities.

11.2  Start

11.2.1  Launch command

The following command launches Cameleon :
cameleon [options] [dir1] ... [dirn]
You can use cameleon.opt instead of cameleon if the native code vers ion is available on your system, but then you won't be able to use plug-ins. The dir1 ...dirn arguments are a list of directories, each one being called a root directory, usually the root directory of one of your project. If you don't specify any directory, the current working directory becomes the only root directory. Note that you must use CVS[1] for the configuration management of your files in order to be able to use Cameleon.

The available options are:
-v
Display the version number and exit.
-norep
Use this option when the CVS repository is not available (for example when you are not connected to the network). You can then access your files through Cameleon but you cannot perfom any CVS action on it.
-com <command>
Make Cameleon execute the given <command> at launch time. Commands are described in section 11.4. This option can be used several times to perform several commands, in the order they appear on the command line.
-expand_dirs_at_start <true|false>
Indicate whether the directory trees in the tree view of the main window must be expanded at start or not. The default value is the one in your $HOME/.cameleon/gui configuration file (see section 11.5).
-check_edited_files_delay nb
When you edit files from Cameleon using Efuns or Xemacs, Cameleon check whether these files are still being edited, every nb miliseconds. You can change the delay here. The default value is the one in your $HOME/.cameleon/gui configuration file (see section 11.5).

11.3  Main window

The main window of Cameleon is shown on figure 11.1. The left part of this window shows directory trees, starting from the root directories. The right part of the window displays the list of files handled by CVS in the selected directory. The toolbar below the menu can be configured.



Figure 11.1: Cameleon main window.



11.4  Commands

Cameleon's functionalities are accessed through internal commands. We will write a command in red bold font. Since menus are totally customizable, we will refer to commands rather than menu entries to indicate the command used to perform an action.

In addition to Cameleon internal commands, external commands can be used. These commands are shell commands.

An internal command is a string, used as identificator to get the associated callback. This string must not begin with the character # and must not containt blanks, simple-quotes or double-quotes.

An external command is a string beginning with the character #. The command which gets executed is the string after the first #. In these commands, you can use some expressions to refer to the current state of Cameleon : All file and directory names are “quoted”, with the Filename.quote function of the OCaml standard library.

Commands can be launched through menu entries, buttons in the toolbar, or keyboard shortcuts.

Some internal commands are defined in Cameleon but more commands can be made available by loading plug-ins (see 11.16).

At last, internal commands can take parameters, the same way as shell commands in a shell, i.e. the arguments are separated by blanks and quotes can be used when an argument contains one or more blanks.

11.5  Configuration

The configuration of Cameleon is performed through the config command which opens the configuration window.

11.5.1  File types

A file type is defined by: The file types can be defined in the “File types” tab of the configuration window, as shown in figure 11.2.



Figure 11.2: Edition of file types.



When looking for the type of a file according to its name, Cameleon tries each regular expression in the order they appear in the list, and stops with the first regular expression matching the filename.
Note : The given regular expressions are used to match against the complete name of a file, starting from the root node name.

11.5.2  Documentation

The available documentation is defined as a list of doc-files (see 11.11). This list can be edited in the “Documentation files” tab of the configuration window.

11.5.3  Toolbar

You can customize the toolbar in the main window (see 11.3), by adding your own buttons, associated to the commands of your choice (internal or external, see 11.4). This is done through the “Custom toolbar” tab of the configuration window.

Each button of the toolbar is defined by : Note: Associating an internal command which is not available to a button will disable the button.

11.5.4  Menus

Menus and menu entries can be configured, through the “Menus” tab of the configuration window, shown on figure 11.3.



Figure 11.3: Edition of menus.



You can create menus, menu commands and separators. Menu commands are defined by a label (which will appear in the menu) and a command (internal of external, see 11.4). Activating a menu command launches the associated internal of external command.

Note: Associating an internal command which is not available to a menu command will disable the menu command.

While editing menus, you will have to mark one of them as the Doc menu, used to dynamically add entries, depending on the available doc-files (see 11.11).

11.5.5  Colors and fonts

The “Colors and fonts” tab lets you choose the colors and fonts used in the documentation browser (see section 11.10), the modules view (see section 11.9.2) and the background command execution window.

11.5.6  Keyboard shortcuts

The keyboard shortcuts can be configured to bind a key combination to a command (internal or external, see 11.4). You can also set the key bindings of the documentation browser (see 11.10).

The edition of key bindings is done in the “Key bindings” tab of the configuration window.

11.5.7  Plug-ins

With the bytecode executable cameleon, you can load plug-ins, to define new commands, new editors, new views, ...

The selected plug-ins are loaded at launch time.

There are two lists of available plug-ins: the shared plug-ins (in the shared plug-ins directory, see 11.15) and the personal plug-ins, in your $HOME/.cameleon/plugins directory.

In the “Plug-ins” tab of the configuration window you can select which plug-ins you want to load, among the list of available plug-ins.

The selected plug-ins are then loaded when you close the configuration window with the “Ok” button. Plug-ins already loaded are not loaded again.

11.5.8  Custom configuration tabs

The configuration window may contain other tabs. Indeed, a plug-in can add a configuration tab when it offers some configuration possibilities. See 11.16 for details.

11.6  CVS management

CVS actions can be performed from the main window with the following internal commands : add_dir, update_dir, commit_dir, tag_dir, add_file, add_binary_file, commit_files, tag_files, tags_of_file, remove_files, last_diff, diff_with, diff_between, resolve_conflicts.

The contextual menu which appears when you click with the third mouse button on a file of the files view (see section 11.9) or a directory gives access to these commands, as does the default CVS menu.

Note: You can use the $HOME/.ocamlcvsrc file to configure the CVS commands used in background (see chapter 7).

11.7  Editors

Editing a file is made with the edit command, or with the contextual menu which appears when you click with the third mouse button on a file. A file can be edited by various editors. The used editor depends on the type of each file. See 11.5.1 about associating an editor to a file type.
Currently, six editors are supported by Cameleon : Efuns[2], Emacs[3], XEmacs[5], DBForge, Report, Zoggy. A custom editor can also be associated to each file type to use another editor.

11.7.1  Efuns

In order to use Efuns as editor, efuns must be running as a server on the same machine. Cameleon communicates with the efuns process through sockets. When a file is edited, Cameleon asks to the efuns process to open this file. Cameleon can also ask Efuns if a file is saved, for example when a file is about to be commited. If the file is not saved, the user is asked whether he wants to save the file before committing or not.

11.7.2  Emacs and XEmacs

Emacs (respectively XEmacs) can be used as editor if an emacs (resp. xemacs) ser ver is running on the same machine. Cameleon communicates with Emacs (resp. XEmacs) through the emacsclient (resp. gnuclient) command. Cameleon can only ask to Emacs to open a file, so the user must take care himself about saving files before commiting, etc ... On the other hand, Cameleon can ask XEmacs if a file is being edited, if a file changed, ...

11.7.3  DBForge

The DBForge editor can be used to edit DBForge schema descriptions. See chapter 5 for details about these files. When a schema file is edited with DBForge, a window appears with the same graphical interface as the stand-alone DBForge tool. Closing this window closes the file. When using the DBForge editor, Cameleon can ask the user to save the edited file before committing, the same way as with Efuns.

11.7.4  Report

The Report editor can be used to edit Report XML document descriptions. See chapter 3 for details. The Report editor in Cameleon works the same way as the DBforge editor (see above).

11.7.5  Zoggy

The Zoggy editor can be used to edit Zoggy graphical interface descriptions. See chapter 4 for details. The Zoggy editor in Cameleon works the same way as the DBforge editor (see above).

11.7.6  Custom editors

If none of the predefined editors fit the user's needs, a custom editor can be defined and associated to a file type. Custom editors are defined by plug-ins (see 11.16). This is the case for the Omom editor (see chapter 10).

11.8  The directory tree

The directory tree shows the directories handled by CVS. You can perform CVS actions on the selected directory using the right commands (see section 11.6).

To choose whether the trees are expanded at start or not, you can use the expand_dirs_at_start command line option (see section 11.2.1).

11.9  The views

The right pane of the main window contains a notebook with different views of the selected directory. Two views are defined by default but more views can be added by plug-ins (see section 11.16).

11.9.1  The files view

The files view shows the files handled by CVS, in the selected directory. In this view you can perform CVS actions like commit, add file, ... The files are displayed according to their associated file type (see section 11.5.1).

11.9.2  The modules view

The modules view show the OCaml modules in the selected directory. To do so, it looks for a file dump.odoc in the selected directory. This file must be an OCamldoc dump file. It should contain information on the modules in the selected directory but you can put information on the modules you want in that file.

If the file does not exist, Cameleon try a make dump.odoc to create the file. If it does not work, and there is not dump.odoc file available, nothing is displayed.

When information is found, you can see the modules and classes trees on the left of the view, and selecting a module, module type, class or class type shows its elements on the right of the view. You can click with the right button of an element in the tree or the list to create a menu letting you edit the corresponding file at the line corresponding to the element definition. You can choose to open the implementation or the inferface file, depending of whether the documentation was created from the implementation file or the interface file, or both.

You can change the colors in this view in the configuration window (see section 11.5.5).

The “Refresh” button launch the make dump.odoc command and read the dump.odoc file to update the view.

11.10  The documentation browser

The documentation which can be accessed from Cameleon consist in information on OCaml modules. The user can choose these modules. Let's see how to choose these modules and browse their documentation.

11.11  Available documentation

The available documentation is defined by the user (see 11.5.2) as a list of doc-files. A doc-file contains information on toplevel modules, and must have been produced by the -dump option of ocamldoc (see [4]).

Each specified doc-file is loaded when Cameleon is launched. If the doc-file does not exist, a warning message points this out. All toplevel modules in the doc-files are sorted and the Doc menu is built from these modules (see 11.5.4).

In order to avoid too big menus, menus are cascaded. When a module is chosen in the Doc menu, its documentation is displayed in a documentation browser, described in 11.10.

At last, a label and an action can be associated to each doc-file (see 11.5.2). For each of these pairs of label and action, an entry is added to the Doc menu, with the given label. When the menu entry is activated, the given action is triggered. This action usually updates the corresponding doc-file. When the action is over, the Doc menu is updated according to the doc-file modifications.

11.12  Accessing the documentation

You can access the documentation on a module by selecting it in the Doc menu. It opens the documentation browser on this module.

The Doc menu also contains two entries, Exact search and Regexp search which allow the user to search for elements (as defined in [4]) by name, with the exact name or a regular expression. The search is performed on complete names, so you will find the iter function of the List module by using, for example, the Exact search command with the “List.iter” string.

If only one element matched the search, the documentation browser is open on this element, else a window appears showing all the results, and selecting one opens the documentation browser on this element.

The display_modules_box command can be used to show the list of available toplevel modules (it is created at launch time, but you can close it). In this window, called the doc modules box, you can double-click on a module to browse its documentation. You can walk through the list with the up and down arrows or use the 'A' .. 'Z' keys to go directly to the modules beginning with the letter corresponding to the key you hit. The “Return” key opens the selected module.

You can also use the top field to enter a string and perform an exact search on this string with the button below.

This field is a combo box, where you can add predefined strings. These predefined strings are bookmarks: you select a bookmark and then click the “Exact Search” button to go to the element (or the list of elements mathcing the search). To add a bookmark, use the add_bookmark command in the documentation browser.

11.13  Browsing the documentation

The documentation browser is a window showing the interface of a module or a class, with the comments of the source. It uses the information read from OCamldoc dump files.

You can click on some text to follow the link, for example you can click on a type name to go to its definition if it is available, like in a HTML document.

The following actions can be performed in the browser window:
next_element
Go to the next element or link in the window, from the current position.
previous_element
Go to the previous element or link in the window, from the current position.
follow_link
Follow the link on which we are.
follow_link_in_new
Open a new browser window to follow the link on which we are.
close
Close the browser window.
search
Search for a string in the window. You type the string in the field at the bottom of the window. Can be called several times to go to the next elements matchting the searched string.
back_search
Same as search but search backward instead of forward.
back
Go back to the previous page (like in a web browser).
add_bookmark
Add the element which was used to open the current page to the list of predefined strings in the search field of the doc modules box.
home
Go to the beginning of the page.
end
Go to the end of the page.
menu
Pop up a contextual menu.
These action are bound to keys, and you can edit these bindings in the configuration window (see section 11.5.6).

The contextual menu, which appears with the menu command or a click with the right button on an element, allow you to browse the follow a link in a new window, or open the file from which the documentation was created, by using the associated editor. The file is open as the right line where the element is defined.

Colors and fonts of the browser can be changed in the configuration window (see section 11.5.5).

11.14  The standalone browser

The docbrowser command (or docbrowser.opt if the native code version is installed) is a standalone documentation browser that you can launch without using Cameleon. It takes as arguments the OCamldoc dump files you want to browse. The colors, fonts and shortcuts are the ones defined in Cameleon (same configuration file).

11.15  The cam-config utility

The cam-config utility can be (and must be) used to get information on the installation of Cameleon, in the Makefiles of your own Cameleon plug-ins or your tools using the Cameleon tools and libraries.

It supports the following options:
-l
Print the directory of the Cameleon libraries.
-b
Print the directory of the Cameleon executables.
-m
Print the directory of the Cameleon man pages.
-t
Print the directory of the Cameleon templates.
-p
Print the directory of the Cameleon plugins.
-q
Print the directory of the Cameleon pixmaps.
-v
Print the version of Cameleon.

11.16  Plug-ins

Cameleon (bytecode version) can load plug-ins in the form of OCaml object-files (.cmo or .cma files).

Plug-ins can add: Some default plug-ins are available and are detailed below. To develop new plug-ins, you must use the Cam_plug module of Cameleon, as explained in subsection 11.21.

11.16.1  Shared/Personal plug-ins

There are two kinds of plug-ins: shared and personal. Shared plug-ins are available for everyone and are installed in the Cameleon shared plug-ins directory. This directory is printed by the following command:
cam-config -p
Personal plug-ins are in the user's $HOME/.cameleon/plugins directory.

Here are the default installed shared plug-ins. Do not forget that you can choose which plug-ins you want to use (see section 11.5.7).

11.16.2  The utils plug-in

This is a simple plug-in defining commands.

Commands

CommandDescription
execMake the user give a Cameleon command name and execute it. This comment is associated to the following command, thanks to our custom ocamldoc generator.
mozillaMake the user give an url and launch mozilla with this url. If no url is given, make the user type it. In this case, the default url begins with http:// or file:///, depending on whether a directory is selected or not.

11.16.3  The editors plug-in

This plug-in define additionnal editors for some file types.

Editors

EditorDescription
epeireLaunch epeire (the one installed with Cameleon) on the given Epeire configuration file.
gimpLaunch gimp on the given file.
gladeLaunch glade on the given file.
gvLaunch gv on the given file.
gvimLaunch a gvim serveur named "CAMELEON_GVIM" or connect to the existing one, if any.
xfigLaunch xfig on the given file.

11.16.4  The make plug-in

This plug-in defines the make internal command which launches the make utility on the given arguments, in the selected directory.

Commands

CommandDescription
makeRun make in the selected directory, on the given targets.

11.16.5  The omom plug-in

This plug-in adds an editor to edit OCamlmake-o-matic files.

Commands

CommandDescription
omomomom template target uses the selected OCamlmake-o-matic file to generate the given template in the given target file. omom does the same after having asked the template and the target file to the user.

Editors

EditorDescription
omomEdit OCamlmake-o-matic files in the graphical editor.

11.17  Developing your own plug-ins

To develop a Cameleon plug-in, you will have to use the Cam_Plug module, installed with Cameleon. This module defines functions to add editors, embedded applications, internal commands. Some functions are used to retrieve information on Cameleon current state (selected files, ...), and some utilities functions are also provided.

11.17.1  The Cam_plug module

Here is the interface of the Cam_plug module.

11.17.2  Example

Here is the code of a simple plug-in:

(*                                                                        *)
(*      This program is distributed in the hope that it will be useful,   *)
(*      but WITHOUT ANY WARRANTY; without even the implied warranty of    *)
(*      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     *)
(*      GNU General Public License for more details.                      *)
(*                                                                        *)
(*      You should have received a copy of the GNU General Public License  *)
(*      along with this program; if not, write to the Free Software       *)
(*      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA          *)
(*      02111-1307  USA                                                   *)
(*                                                                        *)
(*      Contact: Maxence.Guesdon@inria.fr                                *)
(**************************************************************************)


(** Utils plugin. This plugin provides some basic commands to show how to create your own plugin.*)


open Cam_plug

(** Make the user give a Cameleon command name and execute it. This comment is associated to the following command, thanks to our custom ocamldoc generator. @command exec *)

let exec args =
  match args with
  | [] ->
      (
       let coms = Cam_plug.available_commands () in
       let com = ref (try List.hd coms with _ -> ""in
       let p = Configwin.combo
           ~f: (fun s -> com := s)
           ~new_allowed: true
           ~blank_allowed: false
           "Command : "
           coms
           !com
       in
       match Configwin.simple_get "execute" [p] with
         Configwin.Return_cancel | Configwin.Return_apply -> ()
       | Configwin.Return_ok -> Cam_plug.eval !com ()
      )
  | l ->
      let com = String.concat " " l in
      Cam_plug.eval com ()


(** Make the user give an url and launch mozilla with this url. If no url is given, make the user type it. In this case, the default url begins with http:// or file:///, depending on whether a directory is selected or not. @command mozilla *)

let mozilla args =
  let url_opt = 
    match args with
      url :: _ -> Some url
    | [] ->
        GToolbox.input_string ~title: "mozilla" 
          ~text: (match selected_dir() with None -> "http://" | Some s -> "file:///"^s) 
          "url: " 
  in
  match url_opt with
    None -> ()
  | Some s -> ignore (Sys.command ("mozilla "^(Filename.quote s)^" &"))

let _ = add_command "exec" "execute a prompted command" exec 
let _ = add_command "mozilla" "launch mozilla on a given url" mozilla

You can compile it with the following command:
ocamlc -c -I +cameleon plugin.ml
Then place the resulting .cmo file in the shared plug-ins directory or your personal plug-ins directory. Cameleon will let you choose this new plug-in to load, in the “Plug-ins” tab of the configuration window (see section 11.5.7). If you develop such plug-ins and want to distribute them, please e-mail maxence.guesdon@inria.fr, so your plug-ins can be referenced on a Cameleon plug-ins page.
Previous Up Next