next up previous contents
Next: 6.2.7 Dir Up: 6.2 Built-in tools Previous: 6.2.5 Make   Contents


6.2.6 Noweb

The noweb class handles sources written for Ramsey's noweb literate programming facility [Ram94]. Files ending with suffix .nw are automatically recognized as belonging to this class.

The list of targets that are to be extracted from a noweb file must be specified using tool options. A target can then have a variety of its own options. Each target is specified by a separate tool option labelled target. The option usually has the form of a sub-option list. Recognized sub-options are:

name
the name of the target
root
the (optional) root tag for the target (given to the -R command line switch for the notangle command); if root is missing, name is used instead
class
the (optional) class of the target
options
(optional) options for the tool that handles the target's class
lineformat
a string that will be passed to the -L command line option of notangle

Example:


  project.nw (target:(name:main.sml options:(private))
              target:(name:grammar class:mlyacc)
              target:(name:parse.sml))

In place of the sub-option list there can be a single string option which will be used for name or even an unnamed parameter (i.e., without the target label). If no targets are specified, the tool will assume two default targets by stripping the .nw suffix (if present) from the source name and adding .sig as well as .sml.

The following four examples are all equivalent:


  foo.nw (target:(name:foo.sig) target:(name:foo.sml))
  foo.nw (target:foo.sig target:foo.sml)
  foo.nw (foo.sig foo.sml)
  foo.nw

If lineformat is missing, then a default based on the target class is used. Currently only the sml and cm classes are known to CM; other classes can be added or removed by using the NowebTool.lineNumbering controller function exported from library $/noweb-tool.cm:


  val lineNumbering: string -> { get: unit -> string option,
                                 set: string option -> unit }

The noweb class accepts two other parameter besides target:

subdir
specifies a sub-option that is used to specify a directory where derived files (i.e., target files and witness files as far as they have been specified using relative path names) are created. If the subdir option is missing, its value defaults to NW.
witness
specifies an auxiliary derived file whose time stamp is used by CM to avoid recompiling extracted files whose contents have not changed. If witness has not been specified, then CM uses time stamps on extracted files directly to determine whether notangle needs to be run. Thus, with no witness, any change to the master file causes time stamps on all extracted files to be updated as well. If a witness was specified, then CM will write over extracted files, causing their time stamps to change, only if their contents have also changed. The subdir specification also applies to the name of the witness file.

Example:


  foo.nw (subdir:NOWEBFILES
          witness:foo.wtn
          target:(name:main.sml))

Here, the files named main.sml and foo.wtn will be created as


  NOWEBFILES/main.sml
  NOWEBFILES/foo.wtn
while without the subdir-option it would have been

  NW/main.sml
  NW/foo.wtn
To avoid the creation of such a sub-directory, one can use the current arc `` .'' and write:

  foo.nw (subdir:.
          witness:foo.wtn
          target:(name:main.sml))


next up previous contents
Next: 6.2.7 Dir Up: 6.2 Built-in tools Previous: 6.2.5 Make   Contents
Matthias Blume
2001-07-19