Add ASDF tutorial

[pnathan]

ASDF was a pain in the butt to bootstrap myself with quickly.

Add a tutorial and a sample ASDF system (CC0 license).

[fare]

I recommend relying on the source-registry, that automatically scans sub-directories.

These days, good implementations come with ASDF 3.1, which include ~/common-lisp/ in its source-registry by default, so you don't need to configure ASDF at all. Just put your software there.

The old school way of maintaining a symlink farm and having it in the central-registry is considered not user-friendly.

Advanced users who have a lot of systems and nevertheless want faster startup should use asdf/tools/cl-source-registry-cache.lisp

Also, I recommend no asdf: package qualifier in the .asd file, and strings for canonical representation of component names (systems, modules, files), as in

(defsystem "cl-yahoo-finance" :depends-on ("drakma" ...) ...)

[pnathan]

Interesting. Suppose I want to keep my Lisp source in ~/projects/foo/bar/baz/blah/lisp-project1 - is there a straightfoward process with relation to ~/common-lisp (i.e., a symlink under ~/common-lisp) to handling that (common) case?

Thanks for the recommendations.

[fare]

The CL filesystem access primitives suck badly, and it is is not guaranteed whether symlinks will be traversed or not when you recursely search directories for .asd files. Therefore it is NOT recommended to insert symlinks in ~/common-lisp/. Instead, you should "just" register the suitable directories in a file in your ~/.config/common-lisp/source-registry.conf.d/ — see the ASDF manual for details.

[fare]

Oh, and please make the system names lower-case, otherwise you will make things hard for users. Same goes with the names of your components and modules: unless you really have to, don't use uppercase, and really don't use files with names that'd clash on case-insensitive filesystems.

@pnathan do you consider the current ASDF stuff to be sufficient to close this or do we need to write more about it?

[fare]

Old style and not very colloquial all that ASDF tutorial.

1- the central registry is deprecated for newbies. You can rely on ~/common-lisp/ being in the default source-registry since ASDF 3.1 (available on all Lisps by default except CLISP, which is stuck at 2.33). If there's a page on installing CLISP, I'd recommend explaining how to upgrade its ASDF. OK, the downside to the source-registry is you need to (asdf:initialize-source-registry) when you create new .asd files during a session.

2- (asdf:defsystem ...) is redundant. Just (defsystem ...) is recommended. The canonical representation of system names is lower-case strings, not #:symbols.

[fare]

In 2017, all implementations have provided ASDF 3.1 for a long time, including CLISP, so you may advertise ~/common-lisp/ as the default place under which to drop CL source code, no configuration needed.

[fare]

As for adding ~/projects/foo/bar/, do:

mkdir -p ~/.config/common-lisp/source-registry.conf.d/
echo '(:tree (:home "projects/foo/bar"))' > ~/.config/common-lisp/source-registry.conf.d/10-projects-foo-bar.conf