Next: Documentation Index, Previous: History, Up: Top [Contents][Index]
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.
• Building the documentation | ||
• Running unit tests |
Next: Running unit tests, Up: Building and Modifying Roan [Contents][Index]
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 @include
d 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 @include
d. 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:
fill-paragraph
command is careful about that on your behalf.
Previous: Building the documentation, Up: Building and Modifying Roan [Contents][Index]
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.
“If all goes well” is reputed to have been a favorite expression of the sea captain Edward Smith.
Previous: Building the documentation, Up: Building and Modifying Roan [Contents][Index]