Upgrading/Installation Instructions Clarification

[Eric Timmons]

> On 18 Jan 2021, at 17:37, Wilfredo Velazquez wrote:
>
>> To reiterate, I believe that the instructions in
>> https://common-lisp.net/project/asdf/asdf/Upgrading-ASDF.html 
>> 'Upgrading
>> ASDF' could use some clarification.
>>
>> I am attempting to run a newer version of ASDF than that provided by 
>> my
>> impl. The text I'm having issue with is:
>>
>>> If your implementation already provides ASDF 3 or later (and it 
>>> should),
>>> but you want a more recent ASDF version than your implementation 
>>> provides,
>>> then you just need to ensure the more recent ASDF is installed in a
>>> configured path, like any other system. We recommend you download an
>>> official tarball or checkout a release from git into 
>>> ~/common-lisp/asdf/.
>>> Once the source code for ASDF is installed, you don’t need any 
>>> extra step
>>> to load it beyond the usual (require "asdf"): ASDF 3 will 
>>> automatically
>>> look whether an updated version of itself is available amongst the
>>> regularly configured systems, before it compiles anything else.

Personally I've never really been a fan of installing ASDF this way
since a) it requires loading ASDF twice: the implementation built-in and
then the upgrade and b) it requires that ~/common-lisp/ be on ASDF's
search path (I mess around with CL_SOURCE_REGISTRY envvar quite a bit
and frequently end up excluding ~/common-lisp/). I tend to replace the
implementation's built-in version
<https://common-lisp.net/project/asdf/asdf.html#Replacing-your-implementation_0027s-ASDF>. But
do note, I have seen this method occasionally break and I fall back to
the ~/common-lisp/asdf/ apprach when it does. But I'm pretty sure it
works in the latest release on at least SBCL, ECL, and CCL.

> As far as I can tell, if you put a directory tree into `~/common-lisp/`, 
> ASDF will traverse it looking for system definitions, and there is 
> nothing you can do to override this.  I have come to dislike the 
> `~/common-lisp/` solution for this reason.

That's not quite right. It could definitely be more friendly, but there
are a few ways to better control it.

To completely prevent ~/common-lisp/ from being traversed you could put
an :ignore-inherited-configuration directive somewhere in the
CL_SOURCE_REGISTRY envvar or
$XDG_CONFIG_DIRS/common-lisp/source-registry.conf. But that approach
also would prevent the files in
$XDG_CONFIG_DIRS/common-lisp/source-registry.conf.d from being parsed
(as well as any system level config). It might be nice to allow an
inheritance config directive to be specified in the configuration
directory parsing if it isn't already (there's an implicit
:inherit-configuration tacked on the end of the directory based config).

Another option is to drop a .cl-source-registry.cache file in
~/common-lisp/ or one of the sub directories.
<https://common-lisp.net/project/asdf/asdf.html#Caching-Results>. ASDF
will stop recursing if it finds that file and just use the info it
contains.

-Eric