7.8.6.2 Compile–time library file locator

The compile–time library locator must be selected explicitly with the command line option --library-locator compile-time or by setting the parameter current-library-locator to compile-time-library-locator; it is meant to be used from the build directory of a package while compiling libraries for development or future installation. The reference scenario for the compile–time library locator is this:

1. We install the package Vicare Scheme, compiling bundled libraries and putting them in some system directory; the libraries might be installed with pathnames like:
   /usr/local/lib/vicare-scheme/vicare/posix.fasl
2. We install additional packages, compiling distributed libraries and putting them in some system directory; the libraries might be installed with pathnames like:
   /usr/local/lib/vicare-scheme/vicare/something.fasl
3. We unpack the distribution tarball of a package providing even more libraries. We have the source libraries under:

   $(srcdir)/lib/vicare/this.sls
   $(srcdir)/lib/vicare/that.sls
   

   we want to compile them under the build directory:

   $(builddir)/lib/vicare/this.fasl
   $(builddir)/lib/vicare/that.fasl
   

   and then install them in a system directory:

   /usr/local/lib/vicare-scheme/vicare/this.fasl
   /usr/local/lib/vicare-scheme/vicare/that.fasl
   

   In the package’s building infrastructure (for example a Makefile managed by the GNU Autotools) we need to write appropriate invocations of vicare to build the libraries locally and pick the appropriate source libraries and compiled libraries.

4. It may be that the libraries in the source tree need to load installed libraries and also have local dependencies:

   (library (vicare this)
     (export)
     (import (vicare)
       (vicare that))
     ---)
   
   (library (vicare that)
     (export)
     (import (vicare)
       (prefix (vicare posix) px.)
       (vicare something))
     ---)
   

5. It may be that an older version of the package is already installed, so there already exist installed binary libraries:

   /usr/local/lib/vicare-scheme/vicare/this.fasl
   /usr/local/lib/vicare-scheme/vicare/that.fasl
   

   we want the libraries under $(builddir)/lib to take precedence over the libraries under /usr/local/lib/vicare-scheme. It may be that there exist installed source libraries:

   /usr/local/lib/vicare-scheme/vicare/this.sls
   /usr/local/lib/vicare-scheme/vicare/that.sls
   

   we want the libraries under $(srcdir)/lib to take precedence over the libraries under /usr/local/lib/vicare-scheme.

At the Scheme level we want the following:

• Configure the library source search path to include only the local source directory:

  (library-source-search-path)
  ⇒ ("$(srcdir)/lib")
  

• Configure the library binary search path to include the system directory:

  (library-binary-search-path)
  ⇒ (... "/usr/local/lib/vicare-scheme" ...)
  

• Configure the build directory to reference the local build directory:

  (compiled-libraries-build-directory)
  ⇒ "$(builddir)/lib
  

• Configure the library binary file scanner parameter:

  (current-library-binary-search-path-scanner
     default-library-binary-search-path-scanner)
  

  which will scan the search path returned by (library-binary-search-path).

• Configure the library source file scanner parameter:

  (current-library-source-search-path-scanner
     default-library-source-search-path-scanner)
  

  which will scan the search path returned by (library-source-search-path).

• Configure the library locator parameter:

  (current-library-locator compile-time-library-locator)
  

  which implements the appropriate policy.

Assuming Makefiles generated by GNU Automake: to achieve the desired result, we have two options:

1. For every library to be compiled locally, we write in the Makefile an explicit dependency rule:

   lib/vicare/that.fasl: lib/vicare/that.sls
           VICARE_SOURCE_PATH=; export VICARE_SOURCE_PATH;    \
           vicare --library-locator compile-time              \
              --library-path    /usr/local/lib/vicare-scheme  \
              --source-path     $(srcdir)/lib                 \
              --build-directory $(builddir)/lib               \
              -o $@ -c $<
   
   lib/vicare/this.fasl: lib/vicare/this.sls lib/vicare/that.fasl
           VICARE_SOURCE_PATH=; export VICARE_SOURCE_PATH;    \
           vicare --library-locator compile-time              \
              --library-path    /usr/local/lib/vicare-scheme  \
              --source-path     $(srcdir)/lib                 \
              --build-directory $(builddir)/lib               \
              -o $@ -c $<
   

   this is the solution to prefer, because it allows parallel builds.

2. We write a script compile-all.sps that imports at least the local libraries that are leaves in the local package dependency tree:

   (import (only (vicare that))
           (only (vicare this)))
   

   write a single Makefile rule that compiles in the build directory all the dependencies of the script:

   .PHONY: vfasl
   
   vfasl:
           VICARE_SOURCE_PATH=; export VICARE_SOURCE_PATH;    \
           vicare --library-locator compile-time              \
              --library-path    /usr/local/lib/vicare-scheme  \
              --source-path     $(srcdir)/lib                 \
              --build-directory $(builddir)/lib               \
              --compile-dependencies compile-all.sps
   

The following bindings are exported by the library (vicare libraries).

Function: compile-time-library-locator libref

Possible value for the parameter current-library-locator; this function is meant to be used to search for libraries to be compiled for installation.

Given a R6RS library reference: return a thunk to be used to start the search for a matching library. The search for source libraries is performed using the library source file scanner in current-library-source-search-path-scanner. The search for compiled libraries is performed using the library binary file scanner in current-library-binary-search-path-scanner.

The returned thunk does the following:

1. Ask the library source file scanner for the next matching source file.
2. If a matching source is found: look for an already compiled library file in the compiled-libraries-build-directory:
   1. If no compiled file exists or it if exists but it is older than the source file: accept the source file as matching.
   2. If a compiled file exists and it is newer than the source file: accept the compiled file as matching.
   3. Return to the caller the matching file pathname.
   4. If the caller rejects the binary file pathname: return to the caller the source file pathname.
   5. If the caller rejects the source file: loop to 1.
3. If no source file exists: loop to 1.

Remember that the binary file can be rejected if it has been compiled by another boot image or it has the wrong library UID.

When successful (a source or binary file matching libref is found) the returned thunk returns 2 values:

1. An input port. If the port is binary: a compiled library can be read from it. If the port is textual: a source library can be read from it. It is responsibility of the caller to close the returned port when no more needed.
2. A thunk to be called to continue the search. This thunk allows the caller to reject a library if it does not meet some additional constraint; for example: if its version number does not conform to libref.

When no matching library is found: the returned thunk returns #f and #f.