Starting Up

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 core GBBopen modules and execute a basic trip-tests file, you only need to evaluate the following forms within your Common Lisp environment:

  > (load "<install-dir>/startup.lisp")
  ;; 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>/source/module-manager/module-manager.lisp
  ;;     Loading <install-dir>/source/module-manager/module-manager-user.lisp
  ;;  Loading <install-dir>/source/modules.lisp
  ;; No shared module definitions were found in <install-dir>/shared-gbbopen-modules/.
  ;; No personal module definitions were found in <homedir>/gbbopen-modules/.
  T
  > (module-manager:compile-module :gbbopen-test :propagate :create-dirs)
  ;; Compiling <install-dir>/source/module-manager/module-manager.lisp
       ...
  ;; Running basic GBBopen tests...
       ...
  >

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-specification string must be entered as two backslash characters. For example:

  > (load "c:\\GBBopen\\startup.lisp")

The :propagate option to compile-module causes any file in the required modules to be compiled if its binary file does not exist or is not up to date. The :create-dirs option automatically creates any directories that are missing in the compiled-file directory tree.

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.

Next, we show how to add convenient GBBopen keyword commands to the top level read-eval-print loop (REPL) in your Common Lisp environment and how to define a personal REPL command that makes it easy to compile and load the :my-app module—even if GBBopen has not yet been loaded into your Common Lisp image.

Top-level REPL commands

To make GBBopen's REPL commands available, simply load <install-directory>/initiate.lisp from your personal Common Lisp initialization file. (You should not explicitly load the <install-directory>/startup.lisp file when using <install-directory>/initiate.lisp—it will handle the <install-directory>/startup.lisp file loading for you at the appropriate time.)

Built-in and GBBopen REPL commands are defined in the file <install-directory>/commands.lisp. In many Common Lisp implementations and in the SLIME REPL interface, REPL commands that have arguments can be specified using either a list or a spread representation. For example:

  > (:gbbopen-test :create-dirs)
       ...
  >

  > :gbbopen-test :create-dirs
       ...
  >

Equivalent functions in the :common-lisp-user package are always defined for each REPL command, and these functions can be used when REPL keyword-command processing is not fully supported.

Personal gbbopen-commands.lisp file

  ;;;; -*- 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
  ;;; ===============================================

The macro define-repl-command and the function startup-module that are used in this example are both defined in the file <install-directory>/initiate.lisp. Experienced GBBopen users prefer to have their Common Lisp initialization file load <install-directory>/initiate.lisp rather than <install-directory>/startup.lisp in order to use the standard REPL commands for GBBopen—as well as their own, personalized extensions—in the Lisp listener. See the “Enhancing Your Development Environment” exercise in the GBBopen Tutorial for details.

Personal gbbopen-modules directory

Previously, we showed a simple example of using a personal gbbopen-init.lisp file to define the module :my-app. If you develop or use a number of modules or applications, GBBopen provides an alternative mechanism that is even more convenient.

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. Although the 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. For example, an application can be provided to a number of users by creating a symbolic link to the application directory in each user's gbbopen-modules directory.

Each application directory can contain:

• 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”)

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

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

• *ignored-gbbopen-modules-directory-subdirectories*
• *gbbopen-modules-directory-verbose*
• *preferred-browser*
• *sym-file-verbose*
• define-repl-command
• funcall-in-package
• startup-module
• with-system-name

Starting Up