diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index fbf0b492314408cfb1a6c5aa40ba225388eaa58a..f0ae56fe58d451caf6e66a727b82dc9ed31325f6 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -1,5 +1,6 @@ -\input texinfo @c -*- texinfo -*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @c %**start of header +@documentencoding UTF-8 @setfilename asdf.info @settitle ASDF Manual @syncodeindex tp fn @@ -1968,7 +1969,9 @@ and create a file @file{my-lib.asd} with the @code{:class :package-inferred-system} option in its @code{defsystem}. For instance: @example -#-asdf3.1 (error "my-lib requires ASDF 3.1") +;; This example is based on lil.asd of LISP-INTERFACE-LIBRARY. + +#-asdf3.1 (error "MY-LIB requires ASDF 3.1 or later.") (defsystem "my-lib" :class :package-inferred-system :depends-on ("my-lib/interface/all" @@ -1988,34 +1991,61 @@ For instance: '(:c2mop :closer-common-lisp :c2cl :closer-common-lisp-user :c2cl-user)) @end example -In the code above, the first line checks that we are using ASDF 3.1, -which provides @code{package-inferred-system}. +In the code above, the first form checks that we are using ASDF 3.1 or +later, which provides @code{package-inferred-system}. The function @code{register-system-packages} has to be called to register 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. -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: +Then, each file under the @code{my-lib} hierarchy will start with a +package definition, dependencies being trivially computed from the +@code{:use} and @code{:mix} clauses. Take a file +@file{interface/order.lisp} as an example: @example -(uiop:define-package :lil/interface/order +(uiop:define-package :my-lib/interface/order (:use :closer-common-lisp - :lil/interface/definition - :lil/interface/base - :lil/interface/eq :lil/interface/group) + :my-lib/interface/definition + :my-lib/interface/base) (:mix :fare-utils :uiop :alexandria) (:export ...)) @end example 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} +@code{my-lib/interface/definition}, @code{my-lib/interface/base} (package and system names match, and they will be looked up hierarchically). +How can ASDF find the file @file{interface/order.lisp} from the +toplevel system @code{my-lib}, however? In the example above, +@file{interface/all.lisp} (and other @code{all.lisp}) will reexport +all the symbols at once from the packages at the same or lower levels +of the hierarchy. This can be easily done with +@code{uiop:define-package}: + +@example +(uiop:define-package :my-lib/interface/all + (:nicknames :my-lib-interface) + (:use :closer-common-lisp) + (:mix :fare-utils :uiop :alexandria) + (:use-reexport + :my-lib/interface/definition + :my-lib/interface/base + :my-lib/interface/order + :my-lib/interface/monad/continuation)) +@end example + +And thus you have only to refer to each @code{my-lib/.../all} system +in the toplevel system because ASDF detects +@file{interface/order.lisp} and all other dependencies from +@code{:use-reexport} clause. + +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} that +allow for ``inheritance'' of symbols being exported. + ASDF also detects dependencies from @code{:import-from} clauses. You may thus import a well-defined set of symbols from an existing package as loaded from suitably named system; @@ -2031,11 +2061,6 @@ via an @code{:import-from} clause with an empty list of symbols, as in: (: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} -that allow for ``inheritance'' of symbols being exported. - Note that starting with ASDF 3.1.5.6 only, ASDF will look for source files under the @code{component-pathname} as specified via the @code{:pathname} option, whereas earlier versions ignore this option and use the @code{system-source-directory}