From ffb83f173c200a02eb839f012f7ff250356dabf9 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <tunes@google.com> Date: Thu, 10 Apr 2014 20:28:20 -0400 Subject: [PATCH] Clarifications for asdf/package-system. --- doc/asdf.texinfo | 85 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 26 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 468ad44f..87cf8140 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -1715,7 +1715,8 @@ of output from ASDF operations. Starting with release 3.1.1, ASDF supports a one-package-per-file style of programming, whereby each file is its own system, -and dependencies are deduced from the @code{defpackage} form. +and dependencies are deduced from the @code{defpackage} form +(or its variant @code{uiop:define-package}). In this style, packages refer to a same-named system (downcased), unless specially registered. @@ -1723,9 +1724,9 @@ If a system is defined with @code{:class :package-system}, then system names that start with that name (using the slash @code{/} separator) refer to files under the filesystem hierarchy where the system is defined. -For instance, if system @code{my-lib} is defined in -@file{/foo/bar/my-lib/my-lib.asd}, then package @code{my-lib/src/utility} -will be found in file @file{/foo/bar/my-lib/src/utility.lisp}. +For instance, if system @code{lil} is defined in +@file{/home/tunes/cl/lisp-interface-library/lil.asd}, then package @code{lil/interface/order} +will be found in file @file{/home/tunes/cl/lisp-interface-library/interface/order.lisp}. This style was made popular by @code{faslpath} and @code{quick-build} before (@pxref{Bibliography}). @@ -1742,26 +1743,40 @@ and by @code{lisp-interface-library}, to the great satisfaction of the author (FRR). Others who have tried it before also expressed similar results. -To use this style, choose a toplevel system name, e.g. @code{my-lib}, -and create a file @file{my-lib.asd} -with the @code{:class :package-system} option in its @code{defsystem}. -For instance: +Thus, for instance, in @code{lisp-interface-library}, +the file @file{lil.asd} contains the following incantations (elided): + @example -#-asdf3 (error "my-lib requires ASDF 3") -(defsystem my-lib +#-asdf3 (error "LIL requires ASDF 3 or later. Please upgrade your ASDF.") + +(defsystem lil + :description "LIL: Lisp Interface Library" ... :class :package-system :defsystem-depends-on (:asdf-package-system) - :depends-on (:my-lib/src/all) - :in-order-to ((test-op (load-op :my-lib/test/all))) - :perform (test-op (o c) (symbol-call :my-lib/test/all :test-suite))) -(register-system-packages :closer-mop - '(:c2mop :closer-common-lisp :c2cl - :closer-common-lisp-user :c2cl-user)) + :depends-on (:lil/interface/all + :lil/pure/all + :lil/stateful/all + :lil/transform/all) + :in-order-to ((test-op (load-op :lil/test/all))) + :perform (test-op (o c) (symbol-call :lil/test/all :test-suite))) + +(defsystem :lil/test :depends-on (:lil/test/all)) + +(register-system-packages :lil/interface/all '(:interface)) +(register-system-packages :lil/pure/all '(:pure)) +(register-system-packages :lil/stateful/all '(:stateful)) +(register-system-packages :lil/transform/classy '(:classy)) +(register-system-packages :lil/transform/posh '(:posh)) +(register-system-packages :lil/test/all '(:lil/test)) + +(register-system-packages + :closer-mop + '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user)) @end example In the code above, the @code{:defsystem-depends-on (:asdf-package-system)} is -for compatibility with older versions of ASDF 3 (ASDF 2 not supported), +for compatibility with older versions of ASDF 3 (ASDF 2 is not supported), and requires the @code{asdf-package-system} library to be present (it is implicitly provided by ASDF starting with release 3.1.1, which can be detected with the feature @code{:asdf3.1}). @@ -1771,21 +1786,39 @@ packages used or provided by your system and its components where the name of the system that provides the package is not the downcase of the package name. -File @file{my-lib/src/utility.lisp} might start with: +Then, file @file{interface/order.lisp} under the @code{lil} hierarchy, +that defines abstract interfaces for order comparisons, +starts with the following form, +dependencies being trivially computed from the @code{:use} and @code{:mix} clauses: @example -(defpackage :my-lib/src/utility - (:use :closer-common-lisp :my-lib/src/macros :my-lib/src/variables) - (:import-from :cl-ppcre #:register-groups-bind) - (:export #:foo #:bar)) +(uiop:define-package :lil/interface/order + (:use :closer-common-lisp + :lil/interface/definition + :lil/interface/base + :lil/interface/eq :lil/interface/group) + (:mix :fare-utils :uiop :alexandria) + (:export ...)) @end example -And from the @code{:use} and @code{:import-from} clauses, -ASDF could tell that you depend on systems @code{closer-mop} (registered above), -@code{cl-ppcre} (package and system names match), and -@code{my-lib/src/macros} and @code{my-lib/src/variables} +ASDF can tell that this file depends on system @code{closer-mop} (registered above), +@code{lil/interface/definition}, @code{lil/interface/base}, +@code{lil/interface/eq}, and @code{lil/interface/group} (package and system names match, and they will be looked up hierarchically). +ASDF also detects dependencies from @code{:import-from} clauses. +To depend on a system without using a package or importing any symbol from it +(because you'll fully qualify them when used), +you may thus use an @code{:import-from} clause with an empty list of symbols, as in: + +@example +(defpackage :foo/bar + (:use :cl) + (:import-from :foo/baz #:sym1 #:sym2) + (:import-from :foo/quux) + (:export ...)) +@end example + The form @code{uiop:define-package} is supported as well as @code{defpackage}, and has many options that prove useful in this context, such as @code{:use-reexport} and @code{:mix-reexport} -- GitLab