---

13.4.2 “I’m a Common Lisp implementation vendor. When and how should I upgrade ASDF?”

Since ASDF 2, it should always be a good time to upgrade to a recent version of ASDF. You may consult with the maintainer for which specific version they recommend, but the latest release should be correct. Though we do try to test ASDF releases against all implementations that we can, we may not be testing against all variants of your implementation, and we may not be running enough tests; we trust you to thoroughly test it with your own implementation before you release it. If there are any issues with the current release, it’s a bug that you should report upstream and that we will fix ASAP.

As to how to include ASDF, we recommend the following:

• If ASDF isn’t loaded yet, then (require "asdf") should load the version of ASDF that is bundled with your system. If possible so should (require "ASDF"). You may have it load some other version configured by the user, if you allow such configuration.
• If your system provides a mechanism to hook into cl:require, then it would be nice to add ASDF to this hook the same way that ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it. Please send us appropriate code to this end.
• You may, like SBCL since 1.1.13 or MKCL since 1.1.9, have ASDF create bundle FASLs that are provided as modules by your Lisp distribution. You may also, but we don’t recommend that anymore, as in SBCL up until 1.1.12, have ASDF be implicitly used to cl:require these modules that are provided by your Lisp distribution; if you do, you should add these modules in the beginning of both wrapping-source-registry and wrapping-output-translations.
• If you have magic systems as above, like SBCL used to do, then we explicitly ask you to NOT distribute asdf.asd as part of those magic systems. You should still include the file asdf.lisp in your source distribution and precompile it in your binary distribution, but asdf.asd if included at all, should be secluded from the magic systems, in a separate file hierarchy. Alternatively, you may provide the system after renaming it and its .asd file to e.g. asdf-ecl and asdf-ecl.asd, or sb-asdf and sb-asdf.asd. Indeed, if you made asdf.asd a magic system, then users would no longer be able to upgrade ASDF using ASDF itself to some version of their preference that they maintain independently from your Lisp distribution.
• If you do not have any such magic systems, or have other non-magic systems that you want to bundle with your implementation, then you may add them to the wrapping-source-registry, and you are welcome to include asdf.asd amongst them. Non-magic systems should be at the back of the wrapping-source-registry while magic systems are at the front. If they are precompiled, they should also be in the wrapping-output-translations.
• Since ASDF 3, the library UIOP comes transcluded in ASDF. But if you want to be nice to users who care for UIOP but not for ASDF, you may package UIOP separately, so that one may (require "uiop") and not load ASDF, or one may (require "asdf") which would implicitly require and load the former.
• Please send us upstream any patches you make to ASDF itself, so we can merge them back in for the benefit of your users when they upgrade to the upstream version.