BiglooA ``practical Scheme compiler''User manual for version 3.1aMay 2008

30. Bigloo A ``practical Scheme compiler'' User manual for version 3.1a May 2008 -- Bigloo Development Environment

main page

top: | Bigloo A ``practical Scheme compiler'' User manual for version 3.1a May 2008

Bigloo Development Environment

Chapters

Bigloo release 2.0 or more recent contains an Integrated Development Environment. This environment proposes some services:

- Automatic Makefile creation and update.
- Code browsing.
- Revision control.
- Symbol debugging.
- Profiling.
- On-line documentation.
- Source code interpretation.
- Source code expansion.
- Literate programming.

The environment relies on Bigloo tools:

- `bglafile`: a Module access file generator (see Module Access File).
- `bglmake`: a Makefile creator.
- `bgldepend`: a that creates Bigloo dependencies in makefiles.
- `bglpp`: a pretty printer.
- `bglprof`: a profiler
- `bgltags`: a generator of tag file for Emacs.

Each of these tools comes with a dedicated manual page and are not described in this documentation.
Extra tools are required for the environment to go its full speed:

- `Emacs` version 21 (or more recent) (http://www.emacs.org/) or `Xemacs` version 20.4 (or more recent) (http://www.xemacs.org/).
- `prcs` version 1.2.1 or more recent (http://prcs.sourceforge.net/).
- `gdb` version 4.17 or more recent (http://www.cygnus.com/gdb/).
- `gprof` (ftp:/prep.ai.mit.edu:pub/gnu/).
- `texinfo` (ftp:/prep.ai.mit.edu:pub/gnu/).
- `gmake` (ftp:/prep.ai.mit.edu:pub/gnu/).

The following document describes the Bee, the Bigloo Emacs Environment.

### 30.1 Installing the Bee

The standard procedure for installing Bigloo handles the compilation of all tools required by the Bee. Additional Emacs-lisp code have to be appended to your `.emacs` file:

    (autoload 'bdb "bdb" "bdb mode" t)
    (autoload 'bee-mode "bee-mode" "bee mode" t)

    (setq auto-mode-alist
          (append '(("\\.scm$" . bee-mode)
                    ("\\.sch$" . bee-mode)
                    ("\\.scme$" . bee-mode)
                    ("\\.bgl$" . bee-mode)
                    ("\\.bee$" . bee-mode))
                  auto-mode-alist))

This code will force `emacs` to switch to Bee mode when editing Scheme source files.

### 30.2 Entering the Bee

Once, your `.emacs` is updated, to start the Bee you just need to edit a file suffixed with one of the suffix listed in `auto-mode-alist` with Emacs. You may either enter the Bee within Emacs with `ESC-X: bee-mode`.

### 30.3 The Bee Root Directory

The Bee Root Directory is the directory that contains information files that describe a project. When editing a file, the Bee tries to automatically setup the Bee Root Directory. For that, it seeks one of the following file: `Makefile`, `.afile` or `.etags`. This search unwind directories until the root directory is reached or until the number of scanned directories is more than the value of the list variable `bee-root-search-depth`.
An alternative Bee Root Directory may be set. This is done clicking on the `Root` of the tool bar icon.

### 30.4 Building a Makefile

Once, the Bee Root Directory has been setup (it is printed on the left part to the Emacs modeline), a `Makefile` can be automatically produced. It can be achieved clicking on the `Mkmf` icon of the tool bar, using the popup menu (`button-3`) entries, or using one of the two keyboard bindings `C-c C-c C-a` or `C-c C-c C-l`. When creating a `Makefile`, you will be asked to give a file name. This file must be the one that is the main entry point of your program or the one that implements an library heap file.
When the `Makefile` already exists, using the same bindings update Makefile, re-generate `.afile` and `.etags` files.

### 30.5 Compiling

Once a `Makefile` exists, it is possible to compile a program (or a library). Use either the tool bar icon `Compile`, the popup menu entry or `C-c C-c C-c`. If no `Makefile` exists, the Bee will emit a single file compilation.

### 30.6 Interpreting

Scheme source code may be interpreted within the Bee instead of been compiled prior to be executed. This facility could be convenient for fast prototyping. A Read eval print loop (henceforth Repl) could be spawned using the `Repl` icon of the tool bar, using the popup menu entry or using the `C-c C-r C-r` binding.
Parts or the whole buffer may be sent to repl.

- `C-c C-r b` sends the whole buffer.
- `C-c C-r d` sends the define form the cursor is in.
- `C-c C-r l` sends the s-expression that preceeds the cursor.
- `C-c C-r t` sends the top level s-expression the cursor is in.
- `C-c C-r r` sends the marked region.

### 30.7 Pretty Printing

The whole buffer may be pretty printed (long source lines are split) using the `Lisp` icon of the tool bar, using the popup menu entry of using `C-c C-i `tab``.
Parts or the buffer may be indented (no line is split).

- `C-c C-i d` indents the define form the cursor is in.
- `C-c C-i l` indents the s-expression that preceeds the cursor.
- `C-c C-i t` indents the top level s-expression the cursor is in.

### 30.8 Expansing

For debug purposes, result of the source code macro expansion may be checked within the Bee.
Parts or the whole buffer may be sent to repl.

- `C-c C-e C-e` expands the whole buffer.
- `C-c C-e C-d` expands the define form the cursor is in.
- `C-c C-e C-l` expands the s-expression that preceeds the cursor.
- `C-c C-e C-t` expands the top level s-expression the cursor is in.
- `C-c C-e C-r` expands the marked region.

When a part of the buffer is expanded (by opposition to the whole buffer), the buffer is scan for macro definitions. These macros will be used for expanding the requested form.

### 30.9 On-line Documentation

On-line documentation may be popped up. This is always done, clicking on the `Info` icon of the tool bar or `C-c C-d i`. If an emacs region is active, the documentation about that region will be popped up. If the cursor is at a Scheme identifier, the documentation of that identifier will be printed. Otherwise, the user will be prompted for the Section of the documentation to be printed.
Clicking on the `?` icon tool bar, pops up a short description of the Bigloo compiler options.
The Bee uses `info` files for printing On-line documentation. It always search the standard documentation and the standard definition of Scheme. It is possible to add extra `info` files to be searched. The Bee always checks for a directory `info` in the Bee Root Directory. If such a directory exists, contained file will be considered for the search of a document.

### 30.10 Searching for Source Code

Searching for source (variable declaration, module definition, variable usage) is supported by the Bee. Clicking on the `Find` icon of the tool bar will pops up the definition of the variable the cursor is in or the definition of the module the cursor is in. These two operations may be requested using `C-x 5 .` for searching a variable definition, `C-c C-d m` for a module definition.
Information and usages of a variable may be printed using either the `Doc` icon of the tool bar or the `C-c C-d u` key binding.

### 30.11 Importing and Exporting

Bigloo bindings (functions and variables) may be automatically inserted in an export module clause (see Modules). Bring the cursor to an identifier of a binding that has to be exported then, either click on the `Export` tool bar icon or use the `C-c C-m b` key binding.
Bigloo bindings may be automatically inserted in an import module clause. Bring the cursor to an identifier of a binding that has to be imported. Either click on the `Import` tool bar icon or use the `C-c C-m i` key binding. The Bee, will search the modules for the wanted binding.
Foreign bindings (e.g. C variables and C functions) may be automatically inserted in the file module clause. Click on the `Extern` tool bar icon or use the key binding `C-c C-m c` to import whole the definition of an extern file. You will, be prompted an extern file name to be imported. This operation automatically updates the `Makefile` for reflecting that the extern file is required in the compilation.

### 30.12 Debugging

The Bigloo symbolic Debugger may be spawned either clicking on the `Bdb` tool bar icon or using the key binding `C-c C-b C-b`. Once the debugger is not is possible to connect the current buffer to the debugger. This is done using the tool bar icon `Connect` or the key binding `C-c C-b c`. This enables breakpoints to be inserted using mouse clicks.

### 30.13 Profiling

Automatically produced `Makefile` provides entry for profiling. In order to get a profile you must first compile your application for profiling. This is done using a popup menu entry or the `C-c C-p c` key binding. Once your program compiled you can run for profile using a popup menu entry of the `C-c C-p r` key binding. This last will run your program, run `bglprof` to get the profile and this will pops up a window displaying the profile informations.

### 30.14 Revision Control

Submitting a new revision is done using `C-c C-v i` or using an menu bar entry. This builds an new revision for the entire project. The file that compose the project are listed in the `pop` entry of the Bee Root Directory `Makefile`.
Checking out an older version of the file currently edited is done using the key binding `C-c C-v C-o`. This is not a retrieval of the entire project. Global check out may be performed manually.
Comparing the version of the file currently edited with older one is done using `C-c C-v d`. A diff of the two buffers will be popped up.
With both checking out and comparison of versions. A window presenting all the available version will be popped up to let you choose which version you would like to inspect.

### 30.15 Literate Programming

The Bee does not provide real Literate Programming. The reason is that we think that when editing documentation we want to benefit the full power of context-sensitive editors and we don't want to edit the documentation is the same editor mode as the one we use when editing source code. Nevertheless it is possible to place anchors within the source file to the corresponding documentation file. Then, by the means of simple mouse clicks, it becomes possible to edit the documentation of peace of codes. The current Bee literate programming system only supports the Texinfo file format.
For that purpose three anchors are available: `path`, `node` and `deffn`. All anchor have to be delimited with `@` characters.

- `path`: this anchor set the path to the file containing the documentation. Thus,

      (module foo
         ;; @path manuals/foo.texi@
         ...)

  Tells the Bee that the documentation for the module `foo` is located in the file named `manuals/foo.texi`.
- `node`: sets the name of the node that documents this particular source file code.

      (module foo
         ;; @path manuals/foo.texi@
         ;; @node Foo@
         ...)

- `deffn`: each variable binding may point to its documentation. For that, it suffices to use the `deffn` anchor just before the variable definition or within the s-expression that defines the variable.

      ;; @deffn foo@
      (define (foo . chars)
         ...)

  or

      (define (foo . chars)
         ;; @deffn foo@
         ...)

  When clicking on that anchor, the Bee will search the documentation file named by the `path` anchor and within that file, will search for a texinfo `deffn` command that defines the variable named in the anchor.

This Html page has been produced by Skribe.
Last update Wed May 28 08:36:19 2008.