### 1.6 Compiling Scheme ¶

To use Scheme compilers effectively with SLIB the compiler needs to know which SLIB modules are to be compiled and which symbols are exported from those modules.

The procedures in this section automate the extraction of this information from SLIB modules. They are guaranteed to work on SLIB modules; to use them on other sources, those sources should follow SLIB conventions.

#### 1.6.1 Module Conventions ¶

- All the top-level `require` commands have one quoted argument and are positioned before other Scheme definitions and expressions in the file.
- Any conditionally `require`d SLIB modules 2 also appear at the beginning of their files conditioned on the feature `compiling` using `require-if` (see require-if).

      (require 'logical)
      (require 'multiarg/and-)
      (require-if 'compiling 'sort)
      (require-if 'compiling 'ciexyz)

- Schmooz-style comments preceding a definition, identify that definition as an exported identifier (see Schmooz). For non-schmooz files, putting ‘`;@`’ at the beginning of the line immediately preceding the definition (`define`, `define-syntax`, or `defmacro`) suffices.

      ;@
      (define (identity <obj>) <obj>)

- Syntax (macro) definitions are grouped at the end of a module file.
- Modules defining macros do not invoke those macros. SLIB macro implementations are exempt from this rule.

  An example of how to expand macro invocations is:

      (require 'macros-that-work)
      (require 'yasos)
      (require 'pprint-file)
      (pprint-filter-file "collect.scm" macwork:expand)

#### 1.6.2 Module Manifests ¶

`(require 'manifest)`

In some of these examples, slib:catalog is the SLIB part of the catalog; it is free of compiled and implementation-specific entries. It would be defined by:

    (define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*)))

Function: file->requires file provided? catalog ¶

  Returns a list of the features `require`d by file assuming the predicate provided? and association-list catalog.

    (define (provided+? . features)
      (lambda (feature)
        (or (memq feature features) (provided? feature))))

    (file->requires "obj2str.scm" (provided+? 'compiling) '())
            ⇒ (string-port generic-write)

    (file->requires "obj2str.scm" provided? '())
            ⇒ (string-port)

Function: feature->requires feature provided? catalog ¶

  Returns a list of the features `require`d by feature assuming the predicate provided? and association-list catalog.

    (feature->requires 'batch (provided+? 'compiling) *catalog*)
            ⇒ (tree line-i/o databases parameters string-port
                       pretty-print common-list-functions posix-time)

    (feature->requires 'batch provided? *catalog*)
            ⇒ (tree line-i/o databases parameters string-port
                       pretty-print common-list-functions)

    (feature->requires 'batch provided? '((batch . "batch")))
            ⇒ (tree line-i/o databases parameters string-port
                       pretty-print common-list-functions)

Function: feature->requires* feature provided? catalog ¶

  Returns a list of the features transitively `require`d by feature assuming the predicate provided? and association-list catalog.

Function: file->requires* file provided? catalog ¶

  Returns a list of the features transitively `require`d by file assuming the predicate provided? and association-list catalog.

Function: file->loads file ¶

  Returns a list of strings naming existing files loaded (load slib:load slib:load-source macro:load defmacro:load syncase:load synclo:load macwork:load) by file or any of the files it loads.

    (file->loads (in-vicinity (library-vicinity) "scainit.scm"))
            ⇒ ("/usr/local/lib/slib/scaexpp.scm"
                "/usr/local/lib/slib/scaglob.scm"
                "/usr/local/lib/slib/scaoutp.scm")

Function: load->path exp ¶

  Given a `(load '<expr>)`, where <expr> is a string or vicinity stuff), `(load->path <expr>)` figures a path to the file. `load->path` returns that path if it names an existing file; otherwise #f.

    (load->path '(in-vicinity (library-vicinity) "mklibcat"))
            ⇒ "/usr/local/lib/slib/mklibcat.scm"

Function: file->definitions file definer … ¶

  Returns a list of the identifier symbols defined by SLIB (or SLIB-style) file file. The optional arguments definers should be symbols signifying a defining form. If none are supplied, then the symbols `define-operation`, `define`, `define-syntax`, and `defmacro` are captured.

    (file->definitions "random.scm")
            ⇒ (*random-state* make-random-state
               seed->random-state copy-random-state random
               random:chunk)

Function: file->exports file definer … ¶

  Returns a list of the identifier symbols exported (advertised) by SLIB (or SLIB-style) file file. The optional arguments definers should be symbols signifying a defining form. If none are supplied, then the symbols `define-operation`, `define`, `define-syntax`, and `defmacro` are captured.

    (file->exports "random.scm")
            ⇒ (make-random-state seed->random-state
                copy-random-state random)

    (file->exports "randinex.scm")
            ⇒ (random:solid-sphere! random:hollow-sphere!
                random:normal-vector! random:normal
                random:exp random:uniform)

Function: feature->export-alist feature catalog ¶

  Returns a list of lists; each sublist holding the name of the file implementing feature, and the identifier symbols exported (advertised) by SLIB (or SLIB-style) feature feature, in catalog.

Function: feature->exports feature catalog ¶

  Returns a list of all exports of feature.

In the case of `aggregate` features, more than one file may have export lists to report:

    (feature->export-alist 'r5rs slib:catalog))
            ⇒ (("/usr/local/lib/slib/values.scm"
                 call-with-values values)
                ("/usr/local/lib/slib/mbe.scm"
                 define-syntax macro:expand
                 macro:load macro:eval)
                ("/usr/local/lib/slib/eval.scm"
                 eval scheme-report-environment
                 null-environment interaction-environment))

    (feature->export-alist 'stdio *catalog*)
            ⇒ (("/usr/local/lib/slib/scanf.scm"
                 fscanf sscanf scanf scanf-read-list)
                ("/usr/local/lib/slib/printf.scm"
                 sprintf printf fprintf)
                ("/usr/local/lib/slib/stdio.scm"
                 stderr stdout stdin))

    (feature->exports 'stdio slib:catalog)
            ⇒ (fscanf sscanf scanf scanf-read-list
                 sprintf printf fprintf stderr stdout stdin)

#### 1.6.3 Module Semantics ¶

For the purpose of compiling Scheme code, each top-level `require` makes the identifiers exported by its feature’s module `defined` (or defmacroed or defined-syntaxed) within the file (being compiled) headed with those requires.

Top-level occurrences of `require-if` make defined the exports from the module named by the second argument if the feature-expression first argument is true in the target environment. The target feature `compiling` should be provided during this phase of compilation.

Non-top-level SLIB occurences of `require` and `require-if` of quoted features can be ignored by compilers. The SLIB modules will all have top-level constructs for those features.

Note that aggregate catalog entries import more than one module. Implementations of `require` may or may not be transitive; code which uses module exports without requiring the providing module is in error.

In the SLIB modules `modular`, `batch`, `hash`, `common-lisp-time`, `commutative-ring`, `charplot`, `logical`, `common-list-functions`, `coerce` and `break` there is code conditional on features being `provided?`. Most are testing for the presence of features which are intrinsic to implementations (inexacts, bignums, ...).

In all cases these `provided?` tests can be evaluated at compile-time using `feature-eval` (see feature-eval). The simplest way to compile these constructs may be to treat `provided?` as a macro.

#### 1.6.4 Top-level Variable References ¶

`(require 'top-refs)`

These procedures complement those in Module Manifests by finding the top-level variable references in Scheme source code. They work by traversing expressions and definitions, keeping track of bindings encountered. It is certainly possible to foil these functions, but they return useful information about SLIB source code.

Function: top-refs obj ¶

  Returns a list of the top-level variables referenced by the Scheme expression obj.

Function: top-refs<-file filename ¶

  filename should be a string naming an existing file containing Scheme source code. `top-refs<-file` returns a list of the top-level variable references made by expressions in the file named by filename.

  Code in modules which filename `require`s is not traversed. Code in files loaded from top-level is traversed if the expression argument to `load`, `slib:load`, `slib:load-source`, `macro:load`, `defmacro:load`, `synclo:load`, `syncase:load`, or `macwork:load` is a literal string constant or composed of combinations of vicinity functions and string literal constants; and the resulting file exists (possibly with ".scm" appended).

The following function parses an Info Index. 3

Function: exports<-info-index file n … ¶

  n … must be an increasing series of positive integers. `exports<-info-index` returns a list of all the identifiers appearing in the nth … (info) indexes of file. The identifiers have the case that the implementation’s `read` uses for symbols. Identifiers containing spaces (eg. `close-base on base-table`) are not included. #f is returned if the index is not found.

  Each info index is headed by a ‘`* Menu:`’ line. To list the symbols in the first and third info indexes do:

      (exports<-info-index "slib.info" 1 3)

#### 1.6.5 Module Analysis ¶

`(require 'vet)`

Function: vet-slib file1 … ¶

  Using the procedures in the `top-refs` and `manifest` modules, `vet-slib` analyzes each SLIB module and file1, …, reporting about any procedure or macro defined whether it is:

  orphaned

    defined, not called, not exported;

  missing

    called, not defined, and not exported by its `require`d modules;

  undocumented-export

    Exported by module, but no index entry in `slib.info`;

  And for the library as a whole:

  documented-unexport

    Index entry in `slib.info`, but no module exports it.

  This straightforward analysis caught three full days worth of never-executed branches, transitive require assumptions, spelling errors, undocumented procedures, missing procedures, and cyclic dependencies in SLIB.

  The optional arguments file1, … provide a simple way to vet prospective SLIB modules.

#### Footnotes

##### (2)

There are some functions with internal `require` calls to delay loading modules until they are needed. While this reduces startup latency for interpreters, it can produce headaches for compilers.

##### (3)

Although it will work on large info files, feeding it an excerpt is much faster; and has less chance of being confused by unusual text in the info file. This command excerpts the SLIB index into `slib-index.info`:

    info -f slib2d6.info -n "Index" -o slib-index.info