7.8.6.3 Source library file locator

The source library locator must be selected explicitly with the command line option --library-locator source or by setting the parameter current-library-locator to source-library-locator; it is meant to be used to search for source libraries first and then for compiled ones. The reference scenario for the source 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 checkout the source tree of a package repository to develop 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.

   This is the gist: we want to automatically generate an include Makefile holding the compilation and installation recipes correctly describing the dependencies among libraries. For this we need to load all the source libraries in the package’s source tree.

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 these installed libraries to be ignored. 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 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 source-library-locator)
  

  which implements the appropriate policy.

To achieve the desired result, in the Makefile we write rules as follows:

.PHONY: dependencies

DEPSCRIPT = $(srcdir)/scripts/build-makefile-rules.sps

dependencies:
        VICARE_SOURCE_PATH=; export VICARE_SOURCE_PATH; \
        vicare --library-locator source                 \
          --library-path /usr/local/lib/vicare-scheme   \
          --source-path  $(srcdir)/lib                  \
          --r6rs-script  $(DEPSCRIPT) --                \
          $(slsdir)/libraries.scm >$(slsdir)/dependencies.make

where the executed Scheme script generates the Makefile rules automatically.

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

Function: source-library-locator libref

Possible value for the parameter current-library-locator; this function is meant to be used to search for source libraries first and for binary libraries later.

Given a R6RS library reference: return a thunk to be used to start the search for a matching library. The returned thunk uses the current source library scanner referenced by current-library-source-search-path-scanner, with the purpose of finding a library file that matches a given R6RS library reference. If no source library is found: the current binary library scanner referenced by current-library-binary-search-path-scanner is used.

When successful the returned thunk returns 2 values:

1. An input port. If it is a textual input port: a source library can be read from it. If it is a binary input port: a binary 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.