Starting Up
GBBopen is packaged with its own module system
that supports compiling and loading GBBopen components. The Module Manager
Facility is designed for ease of use and for simplicity in porting to Common
Lisp implementations. For example, to compile all GBBopen modules,
you only need to evaluate the following forms within your Common Lisp
environment. First load GBBopen's
<install-directory>/initiate.lisp file:
cl-user> (load "<install-dir>/initiate.lisp")
;; Loading <install-dir>/initiate.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
;; Loading <install-dir>/extended-repl.lisp
;; Loading <install-dir>/commands.lisp
;; Loading <install-dir>/gbbopen-modules-directory.lisp
;; No shared module command definitions were found in <install-dir>/gbbopen-modules/.
;; No personal module command definitions were found in <homedir>/gbbopen-modules/.
#P"<install-dir>/initiate.lisp"
cl-user>
Notice that some additional GBBopen initialization files have been loaded by
this file as well as GBBopen's top level read-eval-print loop (REPL)
command definitions.
| Windows users |
If you are running GBBopen on Windows, note that backslash is the
escape character in the standard Common Lisp reader; it causes the
next character to treated as a normal character rather than as having
any special syntactic characteristics. So, each backslash in a
file-name string must be entered as two backslash characters.
For example:
> (load "c:\\GBBopen\\initiate.lisp")
Many Common Lisp implementations also support Unix-style regular slashes in
Windows file names (e.g., "c:/GBBopen/initiate.lisp"), which can
be particularly convenient when typing file names in the REPL.
| |
Top-level REPL commands
The files loaded by <install-directory>/initiate.lisp
add some handy REPL keyword commands when running
Allegro CL,
Clozure CL,
CMUCL,
ECL,
LispWorks,
SBCL, and
Scieneer CL
users. Some interaction interfaces, such as
SLIME, use their own REPL
rather than the top-level listener provided by the Common Lisp implementation
and, therefore, may not support keyword REPL command
processing. GBBopen provides a Swank extension to the
SLIME REPL that supports
REPL keyword commands.
Built-in and GBBopen REPL commands are defined in the file
<install-directory>/commands.lisp.
REPL commands, including those that have arguments, are specified
using a non-list (“spread”) representation. For example:
> :gbbopen-test :propagate :create-dirs
...
>
Some Common Lisp implementations (Clozure
CL,
LispWorks, and
SBCL) and the
SLIME REPL interface, also
support REPL commands in non-spread (list) form in addition to the
spread notation. For example:
> (:gbbopen-test :propagate :create-dirs)
...
>
Equivalent functions in the :common-lisp-user package are always
defined for each REPL command, and these functions can be used in
place of REPL keyword-command processing.
Compiling all GBBopen modules
Once <install-dir>/initiate.lisp, all GBBopen
modules can be compiled by entering the following REPL command:
cl-user> :compile-gbbopen
;; Loading <install-dir>/startup.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
;; Loading <install-dir>/source/module-manager/module-manager-loader.lisp
;; Loading <install-dir>/<platform-dir>/module-manager/module-manager.lisp
...
;; Loading <install-dir>/modules.lisp
;; No shared module definitions were found in <install-dir>/gbbopen-modules/.
;; No personal module definitions were found in <homedir>/gbbopen-modules/.
...
;;; GBBopen modules compilation completed.
[Common Lisp will exit]
GBBopen should compile all GBBopen modules and then exit Common Lisp without
error.
As can be seen from the file-loading messages, the startup.lisp
file that is loaded by the :compile-gbbopen command loads a bootstrap
loader file for the Module Manager Facility (the
file source/module-manager/module-manager-loader.lisp). This
bootstrap file then loads the Module Manager files
(source/module-manager/module-manager.lisp and
source/module-manager/module-manager-user.lisp) followed by the
module definitions for all GBBopen modules (contained in the file
source/modules.lisp). Then the Module Manager is used to
compile all GBBopen modules.
| ASDF, clbuild, and Quicklisp users |
GBBopen's Module Manager Facility provides an interface that allows
ASDF (and therefore
clbuild and
Quicklisp) to play nice with Module
Manager. If you installed GBBopen using clbuild or Quicklisp, ASDF has been
informed of GBBopen's <install-dir>/gbbopen.asd
system-definition file. Otherwise, to use ASDF to set up GBBopen, you must
add the gbbopen.asd file to ASDF's Registry manually. Then,
instead of loading the <install-dir>/initiate.lisp
file, the Module Manager and GBBopen module definitions can be loaded using
ASDF by entering:
cl-user> (asdf:operate 'asdf:load-op :gbbbopen)
;; Loading <install-dir>/initiate.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
...
;; Loading <install-dir>/startup.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
;; Loading <install-dir>/source/module-manager/module-manager-loader.lisp
;; Loading <install-dir>/<platform-dir>/module-manager/module-manager.lisp
...
;; Loading <install-dir>/modules.lisp
;; No shared module definitions were found in <install-dir>/gbbopen-modules/.
;; No personal module definitions were found in <homedir>/gbbopen-modules/.
...
;; Defining an ASDF defsystem for each Module Manager module...
cl-user>
or when ASDF is integrated with Common Lisp's require:
cl-user> (require :gbbopen)
;; Loading <install-dir>/initiate.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
...
;; Loading <install-dir>/startup.lisp
;; GBBopen is installed in <install-dir>
;; Your "home" directory is <homedir>
;; Loading <install-dir>/source/module-manager/module-manager-loader.lisp
;; Loading <install-dir>/<platform-dir>/module-manager/module-manager.lisp
...
;; Loading <install-dir>/modules.lisp
;; No shared module definitions were found in <install-dir>/gbbopen-modules/.
;; No personal module definitions were found in <homedir>/gbbopen-modules/.
...
;; Defining an ASDF defsystem for each Module Manager module...
cl-user>
Notice that loading the <install-dir>/initiate.lisp file
loaded only GBBopen's REPL command processing extensions, global REPL command
definitions, and module-directory processing into Common Lisp–the Module
Manager is not loaded until it is needed (such as when we performed the
:gbbopen-user REPL command). The ASDF :gbbopen
“system” start up, on the other hand, must also load the Module Manager and
module definitions, as they are required in order to define an ASDF system for
each Module Manager module.
| |
Personal gbbopen-init.lisp file
If a gbbopen-init.lisp file (source or compiled) is present in
the user's “home” directory (as defined by
user-homedir-pathname), it is loaded by the
<install-directory>/startup.lisp file after the
Module Manager Facility and definitions have
been loaded. A personal <homedir>/gbbopen-init.lisp
file is a handy mechanism for defining user-specific modules, application
modules, GBBopen parameters, and other personalizations.
Here is a simple example of a personal
<homedir>/gbbopen-init.lisp file that defines a root
directory named :my-app-root and the module
:my-app:
;;;; -*- Mode:Common-Lisp; Package:CL-USER -*-
(in-package :cl-user)
(module-manager:define-root-directory :my-app-root
(make-pathname :directory "~/my-app"))
(module-manager:define-module :my-app
(:requires :gbbopen-user)
(:directory :my-app-root)
(:files "my-file"))
;;; ===============================================
;;; End of File
;;; ===============================================
For shared or more substantial application modules, we recommend a
packaging convention that mirrors that of GBBopen. This will be discussed
shortly in conjunction with using a personal
gbbopen-modules
directory.
Personal gbbopen-commands.lisp file
You can create your own REPL commands by defining them in a personal
gbbopen-commands.lisp file. If a gbbopen-commands
file (source or compiled) is present in the user's “homedir” home directory
(as defined by user-homedir-pathname), it is loaded
automatically by GBBopen's initiate.lisp file. For example, the
following personal gbbopen-commands.lisp file defines a
REPL command (named :my-app) and an equivalent
function (cl-user::my-app) for compiling and loading the
:my-app module that was defined above:
;;;; -*- Mode:Common-Lisp; Package:CL-USER -*-
(in-package :cl-user)
(define-repl-command :my-app (&rest options)
"Compile and load my GBBopen application module"
(startup-module :my-app options :gbbopen-user))
;;; ===============================================
;;; End of File
;;; ===============================================
Personal gbbopen-modules directory
Although a personal gbbopen-init.lisp file can be used to define
the module :my-app, GBBopen provides an alternative
mechanism that is even more convenient if you develop, share, or use a number
of modules or applications.
If a gbbopen-modules directory is present in the user's home
directory (as defined by user-homedir-pathname), it is expected
to consist of directories each containing an individual GBBopen application or
library. Although these application directories can be placed directly in the
gbbopen-modules directory, it is generally more convenient to
use a symbolic link (or a “pseudo symbolic-link file” on Windows) to point
to the actual application directory, where ever it is located. For example,
an application can be provided to a number of users by creating a symbolic
link to the actual application directory in each user's
gbbopen-modules directory.
Each application directory contains:
- a
modules.lisp file that contains module definitions
(loaded after the personal gbbopen-init.lisp file if there is
one in the user's “homedir”)
- a directory named
source containing all the source files for the
module or application
- an optional
commands.lisp file that specifies
REPL commands for the module (loaded after the personal
gbbopen-commands.lisp file if there is one in the user's
“homedir”)
- any additional directories or files useful to the application
We highly recommend following this packaging convention, which mirrors that of
GBBopen itself. It is very easy to create, use, and share modules
defined in this way by placing symbolic links to the module directories in
your personal gbbopen-modules directory. Windows, unfortunately, is
the exception to this as Windows does not provide symbolic links. GBBopen
users running on Windows must create a text file with the file extension
.sym (that contains the target directory path as its sole line) as a
stand-in for the symbolic link.
Installation-wide shared-gbbopen-modules directory
There is also an
<install-directory>/shared-gbbopen-modules directory.
As with a user's gbbopen-modules directory (discussed above),
the shared-gbbopen-modules directory is assumed to contain
symbolic links (or “pseudo-symbolic-link” files on Windows) to individual
GBBopen module directory trees.
This is the recommended mechanism for installation-wide managing and sharing
of modules and applications.
GBBopen Hyperdoc
Convenient access to a local copy of the GBBopen Hyperdoc manual from Common
Lisp is available by using the browse-hyperdoc
function; part of the :os-interface
module. The browser used by browse-hyperdoc
is specified by the value of *preferred-browser*. A
different value can be specified in either your Common Lisp initialization
file or, preferably, in your personal gbbopen-init.lisp file.
Changing the default setting in GBBopen's startup.lisp is not
recommended.
Emacs access to the
GBBopen Hyperdoc is provided by
<install-directory>/browse-hyperdoc.el. This file
defines the interactive Emacs command browse-hyperdoc and
binds it to META-?. To enable this command, load
<install-directory>/browse-hyperdoc.el from your
.emacs initialization file.
If you already use the
hyperspec.el
utility (included with
SLIME and
ILISP distributions, but
usable on its own), the Emacs browse-hyperdoc command will
automatically defer to the Common Lisp
HyperSpec when given a
non-GBBopen entity. You can also download and install a local copy of the
Common Lisp HyperSpec for use without a network connection. In this case, set
the value of common-lisp-hyperspec-root in your .emacs
initialization file to point to your local copy of the HyperSpec. For
example:
(setf common-lisp-hyperspec-root "file:/usr/local/CLHS/")
Highly recommended!
Entities
The GBBopen Project
