Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
A
asdf
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Container registry
Model registry
Operate
Environments
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
GitLab community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
Peter Housel
asdf
Commits
9a4203dc
Commit
9a4203dc
authored
Oct 8, 2017
by
Francois-Rene Rideau
Browse files
Options
Downloads
Patches
Plain Diff
Small tweaks to README and best_practices
parent
361d218f
Branches
Branches containing commit
Tags
Tags containing commit
No related merge requests found
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
README.md
+11
-6
11 additions, 6 deletions
README.md
doc/best_practices.md
+10
-8
10 additions, 8 deletions
doc/best_practices.md
with
21 additions
and
14 deletions
README.md
+
11
−
6
View file @
9a4203dc
...
...
@@ -4,10 +4,13 @@ ASDF: Another System Definition Facility
For general information about ASDF, consult the web page:
<https://common-lisp.net/project/asdf/>
For
instructions on how to use it
, read the manual:
For
some reference documentation
, read the manual:
<https://common-lisp.net/project/asdf/asdf.html>
Below is a guide for ASDF developers; it is not meant for ASDF users.
For a guide on how to use it, read our "best practices" document:
<https://github.com/fare/asdf/blob/master/doc/best_practices.md>
Below is a guide for ASDF developers. It is not meant for ASDF users.
[TOC]
...
...
@@ -198,7 +201,8 @@ How do I navigate this source tree?
*
[
uiop/
](
uiop/
)
*
Utilities of Implementation- and OS- Portability,
the portability layer of ASDF. It has its own
[
README
](
uiop/README.md
)
,
and functions all have docstrings.
and exported functions should all have docstrings and other ones comment,
or once again it's a bug.
*
[
Makefile
](
Makefile
)
*
The classical
`Makefile`
used for development purposes.
...
...
@@ -209,9 +213,9 @@ How do I navigate this source tree?
*
[
bin/
](
bin/
)
*
[
bump-version
](
bin/bump-version
)
--
a script to bump the version of ASDF, used by the classic
`Makefile`
.
Use it with e.g.
`./bin/bump-version 3.
3.0
`
Use it with e.g.
`./bin/bump-version 3.
4.5
`
to test with the next version number before you release.
NB: ASDF's version number notably affect the behavior of ASDF
NB: ASDF's version number notably affect
s
the behavior of ASDF
with respect to deprecated functions.
*
[
tools/
](
tools/
)
...
...
@@ -224,6 +228,7 @@ How do I navigate this source tree?
system definition for asdf-tools
*
`*.lisp`
-- the source code for the
`asdf-tools`
system,
except for the few files below.
Check the
`.asd`
file for the order in which to read them.
*
Also a couple scripts to help ASDF users:
*
[
load-asdf.lisp
](
tools/load-asdf.lisp
)
--
a working example script to load, configure and use ASDF
...
...
This diff is collapsed.
Click to expand it.
doc/best_practices.md
+
10
−
8
View file @
9a4203dc
...
...
@@ -177,8 +177,8 @@ Two years seems to be the time it takes for a release of ASDF
to become ubiquitously available by default on all implementations;
and, remember, if a user must use an older implementation,
he can always trivially install a newer ASDF on top of it.
Thus, by 2019, people should not be shy about
dropping support for ASDF versions older than
3.2 or
3.3.
Thus, by
October
2019, people should not be shy about
dropping support for ASDF versions older than 3.3.
And even before then, if you need a recent ASDF, just document it,
and tell your users to upgrade their implementation and/or
install a recent ASDF on top of their implementation's.
...
...
@@ -441,8 +441,9 @@ instead of less documented or less portable alternatives.
You MUST NOT use
`asdf:run-shell-command`
,
`asdf:system-definition-pathname`
,
or other deprecated functions that were once recommended in the time of ASDF 1.
They will be removed in the near future (one to two year horizon).
ASDF 3.2 will issue a
`style-warning`
when you do, and ASDF 3.3 will issue a full
`warning`
,
which will break the SBCL build.
ASDF 3.2 or 3.3 will issue a
`style-warning`
when you do, and
some future version of ASDF will issue a full
`warning`
,
which will then break the SBCL build.
See
`backward-interface.lisp`
for a list of deprecated function — or just heed the damn warnings.
### Simple Testing
...
...
@@ -616,7 +617,7 @@ As ASDF maintainer, I now consider this in bad taste:
*
Third, it interferes with ASDF's capacity to detect legitimate vs illegitimate
recursive uses of
`operate`
at places that defeat tracking of dependencies.
*
Fourth, it adds a lot of complexity for dubious gain: at a time you had to type
`(asdf:operate 'load-op :foo)`
,
`(require :foo)`
may have been a nice short-hand,
`(asdf:operate '
asdf:
load-op :foo)`
,
`(require :foo)`
may have been a nice short-hand,
but it isn't such a great gain over
`(asdf:make :foo)`
.
*
Fifth, SBCL now uses ASDF 3's
`compile-bundle-op`
to create a fasl
during the build of SBCL itself, and that fasl can latter be loaded at runtime without ASDF.
...
...
@@ -625,7 +626,7 @@ As ASDF maintainer, I now consider this in bad taste:
Similarly, in ASDF 2.21 I added a function
`require-system`
that used to called
`load-system`
with
`:force-not (already-loaded-systems)`
,
which was a nice hack at the time, that I latter used as part of the
`cl:require`
hook.
That was all a big mistake, as
`:force-not`
interfere with the ability to keep a coherent plan
That was all a big mistake, as
`:force-not`
interfere
s
with the ability to keep a coherent plan
across recursive uses of
`asdf:operate`
as required by builds that involve
`:defsystem-depends-on`
and other ASDF extensions.
These days, this function only checks whether the requested component is already loaded,
...
...
@@ -790,14 +791,15 @@ You MUST NOT call `asdf:clear-system` or in any way interfere with the build
while in a
`perform`
method.
You SHOULD NOT define methods on
`asdf:operate`
--- most of the time it's totally the wrong thing
because users would be "operating" on your system, but on their system that depends on it.
because users would
*not*
be "operating" on
*
your
*
system, but on
*
their
*
system that depends on it.
Instead you SHOULD define methods on
`asdf:perform`
,
`asdf:component-depends-on`
, etc.
### Defining ASDF Extensions
#### Source File Types
You MUST NOT define methods on
`source-file-type`
. This bad ASDF 1 interface must die.
You MUST NOT define methods on
`source-file-type`
.
This bad ASDF 1 interface must die and will be removed in a future version of ASDF.
Instead, override the slot
`type`
for your file class and provide a proper
`:initform`
, as in:
(defclass cl-source-file.l (cl-source-file) ((type :initform "l")))
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment