This is bigloo.info, produced by makeinfo version 4.5 from bigloo.texi.

  This file documents Bigloo, an implementation of an extended version
of the Scheme programming language.

  Copyright (C) 1992-99, 2000-02 Manuel Serrano

     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
     
     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.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* bigloo: (bigloo).            The Bigloo Scheme compiler
END-INFO-DIR-ENTRY


File: bigloo.info,  Node: Bee,  Next: Global Index,  Prev: User Extensions,  Up: Top

Bigloo Development Environment
******************************

  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:
   * `afile': a Module access file generator (*note Module Access
     File::).

   * `bmake': a Makefile creator.

   * `bdepend': a that creates Bigloo dependencies in makefiles.

   * `bpp': a pretty printer.

   * `bprof': a profiler

   * `btags': 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.

* Menu:

* Installing the Bee::
* Entering the Bee::
* The Bee Root Directory::
* Building a Makefile::
* Compiling::
* Interpreting::
* Pretty Printing::
* Expansing::
* On-line documentation::
* Searching for source code::
* Importing and Exporting::
* Debugging::
* Profiling::
* Revision control::
* Literate Programming::


File: bigloo.info,  Node: Installing the Bee,  Next: Entering the Bee,  Prev: Bee,  Up: Bee

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.


File: bigloo.info,  Node: Entering the Bee,  Next: The Bee Root Directory,  Prev: Installing the Bee,  Up: Bee

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'.


File: bigloo.info,  Node: The Bee Root Directory,  Next: Building a Makefile,  Prev: Entering the Bee,  Up: Bee

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.


File: bigloo.info,  Node: Building a Makefile,  Next: Compiling,  Prev: The Bee Root Directory,  Up: Bee

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.


File: bigloo.info,  Node: Compiling,  Next: Interpreting,  Prev: Building a Makefile,  Up: Bee

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.


File: bigloo.info,  Node: Interpreting,  Next: Pretty Printing,  Prev: Compiling,  Up: Bee

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.


File: bigloo.info,  Node: Pretty Printing,  Next: Expansing,  Prev: Interpreting,  Up: Bee

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.


File: bigloo.info,  Node: Expansing,  Next: On-line documentation,  Prev: Pretty Printing,  Up: Bee

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.


File: bigloo.info,  Node: On-line documentation,  Next: Searching for source code,  Prev: Expansing,  Up: Bee

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.


File: bigloo.info,  Node: Searching for source code,  Next: Importing and Exporting,  Prev: On-line documentation,  Up: Bee

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.


File: bigloo.info,  Node: Importing and Exporting,  Next: Debugging,  Prev: Searching for source code,  Up: Bee

Importing and Exporting
=======================

  Bigloo bindings (functions and variables) may be automatically
inserted in an export module clause (*note 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.


File: bigloo.info,  Node: Debugging,  Next: Profiling,  Prev: Importing and Exporting,  Up: Bee

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.


File: bigloo.info,  Node: Profiling,  Next: Revision control,  Prev: Debugging,  Up: Bee

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 `bprof' to get the profile and this will pops up a
window displaying the profile informations.


File: bigloo.info,  Node: Revision control,  Next: Literate Programming,  Prev: Profiling,  Up: Bee

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.


File: bigloo.info,  Node: Literate Programming,  Prev: Revision control,  Up: Bee

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.

