;;; -*- Mode: LISP; Syntax: Common-Lisp; Package: USER; Base: 10 -*- The Genworks Bootstrap Utilities ================================ These utilities allow you to compile, incrementally compile, and load your applications. We give an overview of the expected directory structure and available control files, followed by a reference for each of the functions included in the bootstrap module. 1 Directory Structure ===================== You should structure your applications in a modular fashion, with the directories containing actual Lisp sources called "source." You may have subdirectories which themselves contain "source" directories. We recommend keeping your codebase directories relatively flat, however. Here is an example application directory, with three source files: apps/yoyodyne/booster-rocket/source/assembly.lisp apps/yoyodyne/booster-rocket/source/package.lisp apps/yoyodyne/booster-rocket/source/parameters.lisp apps/yoyodyne/booster-rocket/source/rules.lisp 2 Source Files within a source/ subdirectory ============================================ 2.1 Enforcing ordering ====================== Within a source subdirectory, you may have a file called "file-ordering.isc" to enforce a certain ordering on the files. Here is the contents of an example for the above application: ("package" "parameters") This will force package.lisp to be compiled/loaded first, and parameters.lisp to be compiled/loaded next. The ordering on the rest of the files should not matter (although it will default to lexigraphical ordering). Now our sample application directory looks like this: apps/yoyodyne/booster-rocket/source/assembly.lisp apps/yoyodyne/booster-rocket/source/file-ordering.isc apps/yoyodyne/booster-rocket/source/package.lisp apps/yoyodyne/booster-rocket/source/parameters.lisp apps/yoyodyne/booster-rocket/source/rules.lisp 2.2 Ignoring some source files ============================== You may specify source files to be ignored with ignore-list.isc. For example, say our application contains a test-parts.lisp file which should not be processed as part of a normal build. You can exclude test-parts.lisp from normal builds by adding a file called ignore-list.isc at the appropriate level. Here are the contents of an example ignore-list.isc: ("test-parts") Now our sample application directory look like this: apps/yoyodyne/booster-rocket/source/assembly.lisp apps/yoyodyne/booster-rocket/source/file-ordering.isc apps/yoyodyne/booster-rocket/source/ignore-list.isc apps/yoyodyne/booster-rocket/source/package.lisp apps/yoyodyne/booster-rocket/source/parameters.lisp apps/yoyodyne/booster-rocket/source/rules.lisp 3 Multiple application modules ============================== You may have multiple modules within a common parent directory, as per the following example: apps/yoyodyne/main-rocket/ apps/yoyodyne/booster-rocket/ apps/yoyodyne/cockpit/ Presumably each of these modules has its own source/ subdirectory, and probably its own package.lisp and file-ordering.isc file. 3.1 Enforcing ordering ====================== You can enforce ordering on the modules themselves with a system-ordering.isc file; here are some sample contents of a system-ordering.isc file: ("main-rocket" "booster-rocket") Now our sample application directory look like this: apps/yoyodyne/booster-rocket/ apps/yoyodyne/cockpit/ apps/yoyodyne/main-rocket/ apps/yoyodyne/system-ordering.isc This will ensure that main-rocket gets processed first, followed by booster-rocket. The ordering on the rest of the subdirectories should not matter (although it will default to lexigraphical ordering). 3.2 Ignoring some subdirectories ================================ You may specify subdirectories to be ignored with ignore-list.isc. For example, say our application contains a test-parts/ directory which should not be loaded as part of a normal build. You can exclude test-parts/ from normal builds by adding a file called ignore-list.isc at the appropriate level. Here are the contents of an example ignore-list.isc: ("test-parts") Now our sample application directory look like this: apps/yoyodyne/booster-rocket/ apps/yoyodyne/cockpit/ apps/yoyodyne/ignore-list.isc apps/yoyodyne/main-rocket/ apps/yoyodyne/system-ordering.isc apps/yoyodyne/test-parts/ 4 Revision Control ================== The bootstrap utilities operate on plain files; they do not support operating directly on revision controlled repository files (e.g. RCS ",v" files). We recommend using a revision control system such as CVS, with which the user works with plain files in the home directory as the working codebase. All builds will then be done from the working files, rather than directly on the master repository files. The presence of CVS/ subdirectories (or any other subdirectories containing non-lisp files) will be ignored by the bootstrap utilities. 5 Reference =========== The utilities are all in the :genworks package. If you want to use them from another package, do: (use-package :genworks ). Otherwise you can simply prepend "genworks:" to the name of each function when calling it. 5.1 cl-lite =========== This is the main function used to compile and load a directory. (defun cl-lite (pathname &key create-fasl?) " Traverses pathname in an alphabetical depth-first order, compiling and loading any lisp files found in source/ subdirectories. A lisp source file will only be compiled if it is newer than the corresponding compiled fasl binary file, or if the corresponding compiled fasl binary file does not exist. A bin/source/ will be created, as a sibling to each source/ subdirectory, to contain the compiled fasl files. If the :create-fasl? keyword argument is specified as non-NIL, a concatenated fasl file, named after the last directory component of pathname, will be created in " ) 5.2 cl-patch ============ Can be used to patch large systems (e.g. server apps) without forcing a reload of the entire system. (defun cl-patch (pathname) " Traverses pathname in a manner identical to cl-lite, but only those files for which the source is newer than the corresponding fasl binary file (or for which the corresponding fasl binary file does not exist) will be loaded. Use this for incremental updates where the unmodified source files do not depend on the modified source files.")