13.3.11 Pitfalls of the transition to ASDF 2

The main pitfalls in upgrading to ASDF 2 seem to be related to the output translation mechanism.

• Output translations is enabled by default. This may surprise some users, most of them in pleasant way (we hope), a few of them in an unpleasant way. It is trivial to disable output translations. See “How can I wholly disable the compiler output cache?”.
• Some systems in the large have been known not to play well with output translations. They were relatively easy to fix. Once again, it is also easy to disable output translations, or to override its configuration.
• The new ASDF output translations are incompatible with ASDF-Binary-Locations. They replace A-B-L, and there is compatibility mode to emulate your previous A-B-L configuration. See enable-asdf-binary-locations-compatibility in see Backward Compatibility. But thou shalt not load ABL on top of ASDF 2.

Other issues include the following:

• ASDF pathname designators are now specified in places where they were unspecified, and a few small adjustments have to be made to some non-portable defsystems. Notably, in the :pathname argument to a defsystem and its components, a logical pathname (or implementation-dependent hierarchical pathname) must now be specified with #p syntax where the namestring might have previously sufficed; moreover when evaluation is desired #. must be used, where it wasn’t necessary in the toplevel :pathname argument (but necessary in other :pathname arguments).
• There is a slight performance bug, notably on SBCL, when initially searching for asd files, the implicit (directory "/configured/path/**/*.asd") for every configured path (:tree "/configured/path/") in your source-registry configuration can cause a slight pause. Try to (time (asdf:initialize-source-registry)) to see how bad it is or isn’t on your system. If you insist on not having this pause, you can avoid the pause by overriding the default source-registry configuration and not use any deep :tree entry but only :directory entries or shallow :tree entries. Or you can fix your implementation to not be quite that slow when recursing through directories. Update: This performance bug fixed the hard way in 2.010.
• On Windows, only LispWorks supports proper default configuration pathnames based on the Windows registry. Other implementations make do with environment variables, that you may have to define yourself if you’re using an older version of Windows. Windows support is somewhat less tested than Unix support. Please help report and fix bugs. Update: As of ASDF 2.21, all implementations should now use the same proper default configuration pathnames and they should actually work, though they haven’t all been tested.
• The mechanism by which one customizes a system so that Lisp files may use a different extension from the default .lisp has changed. Previously, the pathname for a component was lazily computed when operating on a system, and you would (defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo)))) (declare (ignorable component system)) "lis"). Now, the pathname for a component is eagerly computed when defining the system, and instead you will (defclass cl-source-file.lis (cl-source-file) ((type :initform "lis"))) and use :default-component-class cl-source-file.lis as argument to defsystem, as detailed in a see How do I create a system definition where all the source files have a .cl extension? below. source-file-type is deprecated. To access a component’s file-type, use file-type, instead. source-file-type will be removed.