From fe80141de5af361388072707443b9f7bd8f38983 Mon Sep 17 00:00:00 2001 From: privet-kitty Date: Fri, 5 Oct 2018 07:21:11 +0200 Subject: [PATCH 1/3] Use UTF-8 in the manual --- doc/asdf.texinfo | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index fbf0b492..02bf1661 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 -- GitLab From 7437858be9d53c6981f6df86cade643bab78978f Mon Sep 17 00:00:00 2001 From: privet-kitty Date: Fri, 5 Oct 2018 07:25:18 +0200 Subject: [PATCH 2/3] Doc: Make the example of package-inferred-system more consistent --- doc/asdf.texinfo | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 02bf1661..ebace6c0 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -1969,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" @@ -1989,32 +1991,29 @@ 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, a file @file{interface/order.lisp} under the @code{my-lib} +hierarchy will start with the following form, dependencies being +trivially computed from the @code{:use} and @code{:mix} clauses: @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). ASDF also detects dependencies from @code{:import-from} clauses. @@ -2037,6 +2036,25 @@ 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. +In @code{my-lib} example above, @file{my-lib/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 +done with @code{:use-reexport}: + +@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. + 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} -- GitLab From 356c662f0278771ecb75484cdcb0aa8cdf13320c Mon Sep 17 00:00:00 2001 From: privet-kitty Date: Fri, 5 Oct 2018 17:42:52 +0200 Subject: [PATCH 3/3] Doc: Modify the explanation about ASDF traversing dependencies of package-inferred-system --- doc/asdf.texinfo | 60 ++++++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index ebace6c0..f0ae56fe 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -1999,9 +1999,10 @@ 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, a file @file{interface/order.lisp} under the @code{my-lib} -hierarchy will start 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 :my-lib/interface/order @@ -2016,6 +2017,35 @@ ASDF can tell that this file depends on system @code{closer-mop} (registered abo @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,30 +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. - -In @code{my-lib} example above, @file{my-lib/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 -done with @code{:use-reexport}: - -@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. - 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} -- GitLab