[racket-dev] change to `raco setup' doc builds and SQLite

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Fri Nov 23 22:09:17 EST 2012

When `raco setup' builds documentation, it now puts cross-reference
keys and dependency information into an SQLite database. So, building
documentation now requires that SQLite is installed (on Unixes; SQLite
is installed by default on Mac OS X, and Racket includes SQLite on

The changes are all under the hood, but you may notice the difference:

 * DrRacket's initial footprint is about 50 MB smaller for a 64-bit

   The savings come from not loading all cross-reference information
   into memory. When you ask for documentation on `cons', DrRacket now
   consults the database to determine which document might have
   information on `cons', and so on.

   Ultimately, cross-reference information must be deserialized from
   the same kind of "out.sxref" file as before. A large document like
   the Reference can have multiple "out.sxref" files, however, so
   DrRacket doesn't have to deserialize all of the Reference's
   cross-references to show information `cons'.

 * When you have a simple Scribble document like

     #lang scribble/base

   and click "Scribble HTML", the result is closer to instantaneous.

   Scribble doesn't have to load (another copy of) all cross-reference
   information into memory before rendering the document.

   You get the same improvement when using `raco scribble ++xref-in
   setup/xref load-collections-xref'.

 * The document-rendering part of `raco setup' uses a little less
   memory and runs a little faster.

   Besides reducing the need to load and re-load cross-reference
   information, dependency and global duplicate-definition checking is
   now handled by a database query, so it should scale better.

There will almost certainly be some problems, so keep an eye out for
broken or suspicious `raco setup' or documentation behavior.

Posted on the dev mailing list.