bug#10326: Need to document %load-path, %load-compiled-path, and add %search-load-compiled-path and load-compiled-from-path to API

[Ian Hulin <ian@hulin.org.uk>]

Hi Ian,
On 23/12/11 23:46, Ian Price wrote:
> Ian Hulin <ian@hulin.org.uk> writes:
> 
>> Section 6.17.6 of the manual could do with a sections for
>> %load-path and %load-compiled-path.
>> 
>> e.g. — Variable: %load-path
>> 
>> The list of directories which will currently be searched by 
>> load-from-path, primitive-load-path and %search-load-path to
>> locate a scheme file.
>> 
>> - Variable: %load-compiled-path
>> 
>> The list of directories which will currently be searched by 
>> load-compiled-from-path and %search-load-compiled-path to locate
>> a compiled scheme file.
> 
> %load-path is already documented in 2.0, in section 6.22.1, 6.17.6
> may be a better place for it though, as that is where e.g.
> %search-load-path, %load-hook etc. are.
> 
Or a cross-ref,or move it from 6.22 and put the cross-ref in here,
depending on Guile's documentation policies.
> %load-compiled-path seems to be only indirectly referred to in the 
> %documentation for GUILE_LOAD_COMPILED_PATH and
> compiled-file-name.
> 
>> Also, Guile really needs to provide a %search-load-compiled-path
>> and a load-compiled-from-path, it would have been useful in
>> LilyPond code, and Manual Section 4.7 (discussing site locations
>> says)
> 
> I don't see a %search-load-compiled-path or load-compiled-from-path
> in guile 2.0's stable branch. Where these removed? Or have I missed
> them?
> 
I don't think they were ever implemented.
>> "As with Scheme files, Guile searches a path to find compiled
>> .go files, the %load-compiled-path. By default, this path has two
>> entries: a path for Guile's files, and a path for site packages.
>> You should install your .go files into the latter. Currently
>> there is no procedure to get at this path, which is probably a
>> bug."
>> 
>> 
>> — Scheme Procedure: %search-load-compiled-path filename — C
>> Function: scm_sys_search_load_compiled_path (filename)
>> 
>> Search %load-compiled-path for the file named filename, which
>> must be readable by the current user. If filename is found in the
>> list of paths to search or is an absolute pathname, return its
>> full pathname. Otherwise, return #f.
> 
> Unless you meant %search-load-compiled-path, this sounds similar to
> the documented procedure 'compiled-file-name'
No: compiled-file-name does more and different things which are
intimately linked in to --auto-compile and its related cache.

If you're compiling things to locations outside of this cache (as we
need to do for LilyPond) you need to set a directory as an entry in
%load-compiled-path and pass this explicitly to compile-file (guild
compile if your doing this from within a build environment).

We then need to have custom code to load the compiled files during
startup. This is because the built-in things in load-from-path et al.
rely on compiled-file-name which don't do the right thing if you're
compiling to a location outside the --auto-compile cache.

So. . . if we want to load our compiled scheme files, possibly
produced from guild compile in a build, outside of the --auto-compile
cache, we have to use load-compiled, which explicitly says "Load the
compiled file named /filename/.  The load paths are not searched."

>> 
>> — Scheme Procedure: load-compiled-from-path filename
>> 
>> Similar to load-compiled, but searches for filename in the 
>> compiled load paths.
> If the above is correct, this is just (compose load-compiled
> compiled-file-name), yes?
No.  See above
> Might be useful for symmetry with 'load-from-path'
> 
Yes.

Cheers,
Ian Hulin