Next: , Previous: , Up: Top   [Contents][Index]

Appendix D Building and Modifying Roan

Since Roan is written in Lisp there really is no build process: your Lisp implementation, under the direction of Quicklisp and ASDF, will happily just compile and load it.

However, the documentation does have a slightly complex build process. And if you are modifying Roan you really should make friends with the unit tests.


Next: , Up: Building and Modifying Roan   [Contents][Index]

D.1 Building the documentation

This manual is written using Texinfo. Depending upon how your environment is already configured you may have to download and install Texinfo software, TeX and/or LaTeX.

There is a file included in the source tree, though not a part of Roan per se, extract-documentation.lisp, that is used to extract the documentation strings associated with symbols exported from the roan package. This is done using the roan/doc:extract-documentation function. For each exported symbol it writes a small .texi file in the doc/inc directory with its documentation string, augmented with some further Texinfo commands. The documentation strings in the Roan sources are themselves infested with appropriate Texinfo commands. Most of these small files are then @included into the main Texinfo file, roan.texi, to document the various functions, macros and types. In addition to roan.texi, there is also a small collection of style information used by the HTML versions of the documentation in roan.css.

After the documentation strings have been extracted makeinfo needs to be called for each of the four versions of the documentation that are produced:

So long as CCL (Clozure Common Lisp) is installed, the Makefile in the source hierarchy should do all this for you. If preferred, it should be straightforward to modify the Makefile to use a different Lisp implementation to run extract-documentation.

If a public function is added to Roan, it should include a suitable documentation string, and roan.texi should be revised to give it an appropriate home, where the corresponding inc/*-function.texi file is @included. So long as you export its name from the roan package it should be picked up by when building the documentation. Then, run make documentation and if all goes well1, all four kinds of documentation will be nicely produced a few seconds later.

Of course, most of the time, all won’t go well. Besides looking carefully at the rather noisy output from makeinfo, here are a few other things to bear in mind:


Previous: , Up: Building and Modifying Roan   [Contents][Index]

D.2 Running unit tests

The Roan source tree contains a collection unit tests. If you are making changes to Roan it is highly recommended that you make friends with them and use them early and often. Unless run on an unusally slow machine or Lisp implementation it takes less than a minute to run the full collection, and in the long run they will save you a lot of time.

The unit tests live in their own package, roan/test, and make use of a further library not included in Roan itself, lisp-unit2. After running (ql:quickload :roan) once, run (ql:quickload :roan/test) once as well. Once that has been done, assuming Roan has been installed where ASDF can find it, it should be possible to run all the unit tests by simply evaluating (asdf:test-system :roan). If the unit tests all succeed it will report the success of about 13,000 assertions with no failures. Otherwise, you’ll have some debugging to do.

One caveat: a few of the tests, related to upgrading the methods library, require access to the internet. If it is not available, there will be a failures reported.

If you make changes to Roan I suggest you run the unit tests frequently. If you care about portability, run them at least occasionally on as many different Lisp implementations as you have access to. And if you add functions to Roan, add unit tests for them, too.

Writing decent, reusable tests is often harder and more time consuming than writing code; but it’s a lot easier and less time consuming than debugging things days, weeks, months or years after they were first written. This is especially true for a relatively low-level library such as Roan.


Footnotes

(1)

“If all goes well” is reputed to have been a favorite expression of the sea captain Edward Smith.


Previous: , Up: Building and Modifying Roan   [Contents][Index]