Commit 98a32bf0 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

3.0.1: tweak version-satisfies for compatibility with quicklisp.

Also, better document the entire version business.
This is an incompatible change, but the previous behavior was not documented,
wasn't fully working until rather recently and looks like it wasn't relied upon,
so this should be OK.
parent a925fdf8
...@@ -74,7 +74,7 @@ ...@@ -74,7 +74,7 @@
:licence "MIT" :licence "MIT"
:description "Another System Definition Facility" :description "Another System Definition Facility"
:long-description "ASDF builds Common Lisp software organized into defined systems." :long-description "ASDF builds Common Lisp software organized into defined systems."
:version "3.0.0" ;; to be automatically updated by make bump-version :version "3.0.1" ;; to be automatically updated by make bump-version
:depends-on () :depends-on ()
#+asdf3 :encoding #+asdf3 :utf-8 #+asdf3 :encoding #+asdf3 :utf-8
;; For most purposes, asdf itself specially counts as a builtin system. ;; For most purposes, asdf itself specially counts as a builtin system.
......
...@@ -198,6 +198,7 @@ ...@@ -198,6 +198,7 @@
(assert (first pv)) (assert (first pv))
(assert (second pv)) (assert (second pv))
(unless (third pv) (appendf pv (list 0))) (unless (third pv) (appendf pv (list 0)))
(unless (fourth pv) (appendf pv (list 0)))
(incf (car (last pv))) (incf (car (last pv)))
(unparse-version pv))) (unparse-version pv)))
......
...@@ -272,7 +272,7 @@ another pathname in a degenerate way.")) ...@@ -272,7 +272,7 @@ another pathname in a degenerate way."))
(version-satisfies (component-version c) version)) (version-satisfies (component-version c) version))
(defmethod version-satisfies ((cver string) version) (defmethod version-satisfies ((cver string) version)
(version-compatible-p cver version))) (version<= version cver)))
;;; all sub-components (of a given type) ;;; all sub-components (of a given type)
......
cl-asdf (2:3.0.1-1) unstable; urgency=low
ASDF 3.0.1 is an emergency release for better compatibility with Quicklisp.
* version-satisfies now uses uiop:version<= for comparison,
and does not check for a same major version number,
like version-compatible-p does, which was the
undocumented behavior since ASDF 1.
-- Francois-Rene Rideau <fare@tunes.org> Mon, 16 May 2013 19:20:28 -0400
cl-asdf (2:3.0.0-1) unstable; urgency=low cl-asdf (2:3.0.0-1) unstable; urgency=low
ASDF 3.0.0 is the first official release of ASDF 3; ASDF 3.0.0 is the first official release of ASDF 3;
...@@ -18,7 +29,7 @@ cl-asdf (2:3.0.0-1) unstable; urgency=low ...@@ -18,7 +29,7 @@ cl-asdf (2:3.0.0-1) unstable; urgency=low
* Build cleanup so make and concatenate-source-op create the same asdf.lisp * Build cleanup so make and concatenate-source-op create the same asdf.lisp
-- Francois-Rene Rideau <fare@tunes.org> Mon, 05 May 2013 23:57:22 -0400 -- Francois-Rene Rideau <fare@tunes.org> Mon, 15 May 2013 23:57:22 -0400
cl-asdf (2:2.33-1) unstable; urgency=low cl-asdf (2:2.33-1) unstable; urgency=low
......
This diff is collapsed.
Tweaks-for-a-debian-release-of-3.0.0
...@@ -863,22 +863,24 @@ without having to edit the system definition. ...@@ -863,22 +863,24 @@ without having to edit the system definition.
@c defsystem grammar, but the cross-referencing is so broken by @c defsystem grammar, but the cross-referencing is so broken by
@c insufficient node breakdown that I have not put one in. @c insufficient node breakdown that I have not put one in.
@item @item
Make sure you know how the @code{:version} numbers will be parsed! They Make sure you know how the @code{:version} numbers will be parsed!
are parsed as period-separated lists of integers. I.e., in the example, They are parsed as period-separated lists of integers.
@code{0.2.1} is to be interpreted, roughly speaking, as @code{(0 2 1)}. I.e., in the example, @code{0.2.1} is to be interpreted,
In particular, version @code{0.2.1} is interpreted the same as roughly speaking, as @code{(0 2 1)}.
@code{0.0002.1} and is strictly version-less-than version @code{0.20.1}, In particular, version @code{0.2.1}
is interpreted the same as @code{0.0002.1} and
is strictly version-less-than version @code{0.20.1},
even though the two are the same when interpreted as decimal fractions. even though the two are the same when interpreted as decimal fractions.
Instead of a string representing the version, Instead of a string representing the version,
the @code{:version} argument can be an expression that is resolved to the @code{:version} argument can be an expression that is resolved to
such a string using the following trivial domain-specific language: such a string using the following trivial domain-specific language:
in addition to being a literal string, it can be an expression of the form in addition to being a literal string, it can be an expression of the form
@code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)}, @code{(:read-file-form <pathname-or-string> :at <access-at-specifier>)},
which will be resolved by reading a form which will be resolved by reading a form in the specified pathname
in the specified pathname
(read as a subpathname of the current system if relative or a unix-namestring). (read as a subpathname of the current system if relative or a unix-namestring).
You may use an access-at specifier with the (optional) :at keyword, You may use a @code{uiop:access-at} specifier
by default the specifier is 0, meaning the first form is returned. with the (optional) @code{:at} keyword,
by default the specifier is @code{0}, meaning the first form is returned.
@cindex :version @cindex :version
...@@ -1182,15 +1184,19 @@ be forced upon you if you were specifying a string. ...@@ -1182,15 +1184,19 @@ be forced upon you if you were specifying a string.
@cindex version specifiers @cindex version specifiers
@cindex :version @cindex :version
Version specifiers are parsed as period-separated lists of integers. I.e., in the example, Version specifiers are strings to be parsed as period-separated lists of integers.
@code{0.2.1} is to be interpreted, roughly speaking, as @code{(0 2 1)}. I.e., in the example, @code{"0.2.1"} is to be interpreted,
In particular, version @code{0.2.1} is interpreted the same as roughly speaking, as @code{(0 2 1)}.
@code{0.0002.1} and is strictly version-less-than version @code{0.20.1}, In particular, version @code{"0.2.1"} is interpreted the same as @code{"0.0002.1"},
even though the two are the same when interpreted as decimal fractions. though the latter is not canonical and may lead to a warning being issued.
Also, @code{"1.3"} and @code{"1.4"} are both strictly @code{uiop:version<} to @code{"1.30"},
quite unlike what would have happened
had the version strings been interpreted as decimal fractions.
System definers are encouraged to use version identifiers of the form System definers are encouraged to use version identifiers of the form
@var{x}.@var{y}.@var{z} for major version, minor version (compatible @var{x}.@var{y}.@var{z} for
API) and patch level. major version, minor version and patch level,
where significant API incompatibilities are signaled by an increased major number.
@xref{Common attributes of components}. @xref{Common attributes of components}.
...@@ -1342,10 +1348,15 @@ Please use the @code{if-feature} option instead. ...@@ -1342,10 +1348,15 @@ Please use the @code{if-feature} option instead.
Files containing @code{defsystem} forms Files containing @code{defsystem} forms
are regular Lisp files that are executed by @code{load}. are regular Lisp files that are executed by @code{load}.
Consequently, you can put whatever Lisp code you like into these files Consequently, you can put whatever Lisp code you like into these files.
(e.g., code that examines the compile-time environment However, it is recommended to keep such forms to a minimal,
and adds appropriate features to @code{*features*}). and to instead define @code{defsystem} extensions
However, some conventions should be followed, that you use with @code{:defsystem-depends-on}.
If however, you might insist on including code in the @code{.asd} file itself,
e.g., to examine and adjust the compile-time environment,
possibly adding appropriate features to @code{*features*}.
If so, here are some conventions we recommend you follow,
so that users can control certain details of execution so that users can control certain details of execution
of the Lisp in @file{.asd} files: of the Lisp in @file{.asd} files:
...@@ -1646,43 +1657,6 @@ itself descended from @code{asdf-ecl}. ...@@ -1646,43 +1657,6 @@ itself descended from @code{asdf-ecl}.
@end deffn @end deffn
@c @deffn Operation test-system-version @Akey minimum
@c Asks the system whether it satisfies a version requirement.
@c The default method accepts a string, which is expected to contain of a
@c number of integers separated by #\. characters. The method is not
@c recursive. The component satisfies the version dependency if it has
@c the same major number as required and each of its sub-versions is
@c greater than or equal to the sub-version number required.
@c @lisp
@c (defun version-satisfies (x y)
@c (labels ((bigger (x y)
@c (cond ((not y) t)
@c ((not x) nil)
@c ((> (car x) (car y)) t)
@c ((= (car x) (car y))
@c (bigger (cdr x) (cdr y))))))
@c (and (= (car x) (car y))
@c (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
@c @end lisp
@c If that doesn't work for your system, you can override it. I hope
@c you have as much fun writing the new method as @verb{|#lisp|} did
@c reimplementing this one.
@c @end deffn
@c @deffn Operation feature-dependent-op
@c An instance of @code{feature-dependent-op} will ignore any components
@c which have a @code{features} attribute, unless the feature combination
@c it designates is satisfied by @code{*features*}. This operation is
@c not intended to be instantiated directly, but other operations may
@c inherit from it.
@c @end deffn
@node Creating new operations, , Predefined operations of ASDF, Operations @node Creating new operations, , Predefined operations of ASDF, Operations
@comment node-name, next, previous, up @comment node-name, next, previous, up
@subsection Creating new operations @subsection Creating new operations
...@@ -1876,47 +1850,44 @@ to a Unix-style syntax. ...@@ -1876,47 +1850,44 @@ to a Unix-style syntax.
@findex version-satisfies @findex version-satisfies
@cindex :version @cindex :version
This optional attribute is used by the generic function This optional attribute specifies a version for the current component.
@code{version-satisfies}, which tests to see if @code{:version} The version should typically be a string of integers separated by dots,
dependencies are satisfied.
the version should be a string of integers separated by dots,
for example @samp{1.0.11}. for example @samp{1.0.11}.
For more information on the semantics of version specifiers, see @ref{The defsystem grammar}. For more information on version specifiers, see @ref{The defsystem grammar}.
@c This optional attribute is intended to be used by the @code{test-system-version} operation.
@c @xref{Predefined operations of ASDF}.
@c @emph{Nota Bene}:
@c This operation, planned for ASDF 1,
@c is still not implemented yet as of ASDF 3.
@c Don't hold your breath.
A version may then be queried by the generic function @code{version-satisfies},
to see if @code{:version} dependencies are satisfied,
and when specifying dependencies, a constraint of minimal version to satisfy
can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
Note that in the wild, we typically see version numbering
only on components of type @code{system}.
Presumably it is much less useful within a given system,
wherein the library author is responsible to keep the various files in synch.
@subsubsection Required features @subsubsection Required features
@emph{FIXME: This subsection seems to contradict the Traditionally defsystem users have used @code{#+} reader conditionals
@code{defsystem} grammar subsection,
which doesn't provide any obvious way to specify required features.
Furthermore, in 2009, discussions on the
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
suggested that the specification of required features may be broken,
and that no one may have been using them for a while.
Please contact the
@url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel,asdf-devel mailing list}
if you are interested in getting this features feature fixed.}
Traditionally defsystem users have used reader conditionals
to include or exclude specific per-implementation files. to include or exclude specific per-implementation files.
This means that any single implementation cannot read the entire system, This means that any single implementation cannot read the entire system,
which becomes a problem if it doesn't wish to compile it, which becomes a problem if it doesn't wish to compile it,
but instead for example to create an archive file containing all the sources, but instead for example to create an archive file containing all the sources,
as it will omit to process the system-dependent sources for other systems. as it will omit to process the system-dependent sources for other systems.
Each component in an asdf system may therefore specify features using Each component in an asdf system may therefore specify using @code{:if-feature}
the same syntax as @code{#+} does, and it will (somehow) be ignored for a feature expression using the same syntax as @code{#+} does,
certain operations unless the feature conditional is a member of such that any reference to the component will be ignored
@code{*features*}. during compilation, loading and/or linking if the expression evaluates to false.
Since the expression is read by the normal reader,
you must explicitly prefix your symbols with @code{:} so they be read as keywords;
this is as contrasted with the @code{#+} syntax
that implicitly reads symbols in the keyword package by default.
For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
the given component is only to be compiled and loaded
when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
You can not write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
since the symbols would presumably fail to be read as keywords.
@subsubsection Dependencies @subsubsection Dependencies
...@@ -1999,8 +1970,11 @@ If you have the time for some CLISP hacking, ...@@ -1999,8 +1970,11 @@ If you have the time for some CLISP hacking,
I'm sure they'd welcome your fixes. I'm sure they'd welcome your fixes.
@c Doesn't CLISP now support LIST method combination? @c Doesn't CLISP now support LIST method combination?
See the discussion of the semantics of @code{:version} in the defsystem A minimal version can be specified for a component you depend on
grammar. (typically another system), by specifying @code{(:version "other-system" "1.2.3")}
instead of simply @code{"other-system"} as the dependency.
See the discussion of the semantics of @code{:version}
in the defsystem grammar.
@c FIXME: Should have cross-reference to "Version specifiers" in the @c FIXME: Should have cross-reference to "Version specifiers" in the
@c defsystem grammar, but the cross-referencing is so broken by @c defsystem grammar, but the cross-referencing is so broken by
...@@ -2166,16 +2140,33 @@ The new component type is used in a @code{defsystem} form in this way: ...@@ -2166,16 +2140,33 @@ The new component type is used in a @code{defsystem} form in this way:
@deffn version-satisfies @var{version} @var{version-spec} @deffn version-satisfies @var{version} @var{version-spec}
Does @var{version} satisfy the @var{version-spec}. A generic function. Does @var{version} satisfy the @var{version-spec}. A generic function.
ASDF provides built-in methods for @var{version} being a ASDF provides built-in methods for @var{version} being a @code{component} or @code{string}.
@code{component} or @code{string}. @var{version-spec} should be a @var{version-spec} should be a string.
string. If it's a component, its version is extracted as a string before further processing.
In the wild, we typically see version numbering only on components of A version string satisfies the version-spec if after parsing,
type @code{system}. the former is no older than the latter.
Therefore @code{"1.9.1"}, @code{"1.9.2"} and @code{"1.10"} all satisfy @code{"1.9.1"},
For more information about how @code{version-satisfies} interprets but @code{"1.8.4"} or @code{"1.9"} do not.
version strings and specifications, @pxref{The defsystem grammar} and For more information about how @code{version-satisfies} parses and interprets
version strings and specifications,
@pxref{The defsystem grammar} (version specifiers) and
@ref{Common attributes of components}. @ref{Common attributes of components}.
Note that in versions of ASDF prior to 3.0.1,
including the entire ASDF 1 and ASDF 2 series,
@code{version-satisfies} would also require that the version and the version-spec
have the same major version number (the first integer in the list);
if the major version differed, the version would be considered as not matching the spec.
But that feature was not documented, therefore presumably not relied upon,
whereas it was a nuisance to several users.
Starting with ASDF 3.0.1,
@code{version-satisfies} does not treat the major version number specially,
and returns T simply if the first argument designates a version that isn't older
than the one specified as a second argument.
If needs be, the @code{(:version ...)} syntax for specifying dependencies
could be in the future extended to specify an exclusive upper bound for compatible versions
as well as an inclusive lower bound.
@end deffn @end deffn
@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top @node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
......
;;; -*- mode: Common-Lisp; Base: 10 ; Syntax: ANSI-Common-Lisp -*- ;;; -*- mode: Common-Lisp; Base: 10 ; Syntax: ANSI-Common-Lisp -*-
;;; This is ASDF 3.0.0: Another System Definition Facility. ;;; This is ASDF 3.0.1: Another System Definition Facility.
;;; ;;;
;;; Feedback, bug reports, and patches are all welcome: ;;; Feedback, bug reports, and patches are all welcome:
;;; please mail to <asdf-devel@common-lisp.net>. ;;; please mail to <asdf-devel@common-lisp.net>.
......
...@@ -36,7 +36,7 @@ ...@@ -36,7 +36,7 @@
(assert (assert
(version-satisfies (asdf-version) "3.0")) (version-satisfies (asdf-version) "3.0"))
(assert (assert
(not (version-satisfies (asdf-version) "2.0"))) (version-satisfies (asdf-version) "2.0"))
(assert (assert
(version<= "2.0" (asdf-version))) (version<= "2.0" (asdf-version)))
(assert (assert
......
...@@ -52,7 +52,7 @@ You can compare this string with e.g.: (ASDF:VERSION-SATISFIES (ASDF:ASDF-VERSIO ...@@ -52,7 +52,7 @@ You can compare this string with e.g.: (ASDF:VERSION-SATISFIES (ASDF:ASDF-VERSIO
;; "3.4.5.67" would be a development version in the official upstream of 3.4.5. ;; "3.4.5.67" would be a development version in the official upstream of 3.4.5.
;; "3.4.5.0.8" would be your eighth local modification of official release 3.4.5 ;; "3.4.5.0.8" would be your eighth local modification of official release 3.4.5
;; "3.4.5.67.8" would be your eighth local modification of development version 3.4.5.67 ;; "3.4.5.67.8" would be your eighth local modification of development version 3.4.5.67
(asdf-version "3.0.0") (asdf-version "3.0.1")
(existing-version (asdf-version))) (existing-version (asdf-version)))
(setf *asdf-version* asdf-version) (setf *asdf-version* asdf-version)
(when (and existing-version (not (equal asdf-version existing-version))) (when (and existing-version (not (equal asdf-version existing-version)))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment