Skip to content
Snippets Groups Projects
Commit b064304a authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

More README.md tweaks for both asdf and uiop.

parent cb7be4c1
No related branches found
No related tags found
No related merge requests found
...@@ -8,7 +8,7 @@ ASDF is the de facto standard build facility for Common Lisp. ...@@ -8,7 +8,7 @@ ASDF is the de facto standard build facility for Common Lisp.
Your Lisp implementation probably contains a copy of ASDF, Your Lisp implementation probably contains a copy of ASDF,
which you can load using `(require "asdf")`. which you can load using `(require "asdf")`.
If you come from the C/C++ world, the ASDF covers a bit of what each of If you come from the C/C++ world, ASDF covers a bit of what each of
make, autoconf, dlopen and libc do for C programs: make, autoconf, dlopen and libc do for C programs:
it orchestrates the compilation and dependency management, it orchestrates the compilation and dependency management,
handles some of the portability issues, dynamically finds and loads code, handles some of the portability issues, dynamically finds and loads code,
...@@ -25,15 +25,15 @@ will get you started as a simple user. ...@@ -25,15 +25,15 @@ will get you started as a simple user.
If you want to define your own systems, further read the section If you want to define your own systems, further read the section
Defining systems with defsystem. Defining systems with defsystem.
The manual is also in the doc/ subdirectory, and can be prepared with: The manual is also in the [doc/](doc/) subdirectory, and can be prepared with:
make doc make doc
ASDF 3 now includes an extensive runtime support library: ASDF 3 now includes an extensive runtime support library:
UIOP, the Utilities for Implementation- and OS- Portability. [UIOP, the Utilities for Implementation- and OS- Portability](uiop/).
Its documentation unhappily lies mainly in the source code and docstrings. Its documentation unhappily lies mainly in the source code and docstrings.
See [`uiop/README.md`](uiop/README.md) for an introduction. See [uiop/README.md](uiop/README.md) for an introduction.
More information and additional links can be found on ASDF's home page at: More information and additional links can be found on ASDF's home page at:
<http://common-lisp.net/project/asdf/> <http://common-lisp.net/project/asdf/>
...@@ -62,7 +62,7 @@ or, assuming your implementation provides ASDF 3.1 or later: ...@@ -62,7 +62,7 @@ or, assuming your implementation provides ASDF 3.1 or later:
~/common-lisp/asdf/ ~/common-lisp/asdf/
If you cloned our git repository, bootstrap a copy of build/asdf.lisp with: If you cloned our git repository, bootstrap a copy of `build/asdf.lisp` with:
make make
...@@ -98,7 +98,7 @@ choose your most elaborate installed system $S, and try: ...@@ -98,7 +98,7 @@ choose your most elaborate installed system $S, and try:
Debugging tip Debugging tip
------------- -------------
To load ASDF in such a way that M-. will work, install the source code, and run: To load ASDF in such a way that `M-.` will work, install the source code, and run:
(asdf:load-system :uiop) ;; loading uiop is simple (asdf:load-system :uiop) ;; loading uiop is simple
(map () 'load ;; loading asdf/defsystem is tricky (map () 'load ;; loading asdf/defsystem is tricky
...@@ -121,72 +121,73 @@ the `git log` for a detailed description of each commit. ...@@ -121,72 +121,73 @@ the `git log` for a detailed description of each commit.
How do I navigate this source directory? How do I navigate this source directory?
---------------------------------------- ----------------------------------------
* `asdf.asd` * [asdf.asd](asdf.asd)
* The system definition for building ASDF with ASDF. * The system definition for building ASDF with ASDF.
* `*.lisp` * `*.lisp`
* The source code files for asdf/defsystem. * The source code files for `asdf/defsystem`.
See asdf.asd for the order in which they are loaded. See [asdf.asd](asdf.asd) for the order in which they are loaded.
* `uiop/` * [uiop/](uiop/)
* Utilities of Implementation- and OS- Portability, * Utilities of Implementation- and OS- Portability,
the portability layer of ASDF. It has its own `README`, the portability layer of ASDF. It has its own [README](uiop/README.md),
and functions all have docstrings. and functions all have docstrings.
* `Makefile` * [Makefile](Makefile)
* a minimal Makefile for bootstrapping purposes. * a minimal `Makefile` for bootstrapping purposes.
Most of the logic is in the asdf-tools system Most of the logic is in the [asdf-tools](tools/asdf-tools.asd) system.
* `tools/` * [tools/](tools/)
* Some scripts to help ASDF users * Some scripts to help ASDF users
* `load-asdf.lisp` -- a build script to load, configure and use ASDF * [load-asdf.lisp](tools/load-asdf.lisp) -- a build script to load, configure and use ASDF
* `install-asdf.lisp` -- replace and update an implementation's ASDF * [install-asdf.lisp](install-asdf.lisp) -- replace and update an implementation's ASDF
* `cl-source-registry-cache.lisp` -- update a cache for the source-registry * [cl-source-registry-cache.lisp](cl-source-registry-cache.lisp) -- update a cache for the source-registry
* `build.xcvb` * [build.xcvb](build.xcvb)
* The system definition for building ASDF with XCVB. * The system definition for building ASDF with XCVB.
It hasn't been tested or maintained for years and has bitrotten. It hasn't been tested or maintained for years and has bitrotten.
* `version.lisp-expr` * [version.lisp-expr](version.lisp-expr)
* The current version. Bumped up every time the code changes, using: * The current version. Bumped up every time the code changes, using:
./tools/asdf-builder bump ./tools/asdf-builder bump
* `doc/` * [doc/](doc/)
* documentation for ASDF, including: * documentation for ASDF, including:
* `index.html` -- the web page for <http://common-lisp.net/project/asdf/> * [index.html](doc/index.html) -- the web page for <http://common-lisp.net/project/asdf/>
* `asdf.texinfo` -- our manual * [asdf.texinfo](doc/asdf.texinfo) -- our manual
* `Makefile` -- how to build the manual * [Makefile](doc/Makefile) -- how to build the manual
* `cclan.png` `lisp-logo120x80.png` `style.css` `favicon.ico` * [cclan.png](doc/cclan.png) [lisp-logo120x80.png](doc/lisp-logo120x80.png)
-- auxiliaries of `index.html` [style.css](doc/style.css) [favicon.ico](doc/favicon.ico)
-- auxiliaries of [index.html](doc/index.html)
* `test/`
* [test/](test/)
* regression test scripts (and ancillary files) for developers to check * regression test scripts (and ancillary files) for developers to check
that they don't unintentionally break any of the functionality of ASDF. that they don't unintentionally break any of the functionality of ASDF.
Far from covering all of ASDF. Far from covering all of ASDF.
* `contrib/` * [contrib/](contrib/)
* a few contributed files that show case how to use ASDF. * a few contributed files that show case how to use ASDF.
* `debian/` * [debian/](debian/)
files for packaging on debian, ubuntu, etc. files for packaging on debian, ubuntu, etc.
* `build/` * [build/](build/)
* where the Makefile and asdf-tools store their output files, including * where the `Makefile` and `asdf-tools` store their output files, including
* `asdf.lisp` -- the current one-file deliverable of ASDF * `asdf.lisp` -- the current one-file deliverable of ASDF
* `asdf-XXX.lisp` -- for upgrade test purposes, old versions * `asdf-XXX.lisp` -- for upgrade test purposes, old versions
* `results/` -- logs of tests that have been run * `results/` -- logs of tests that have been run
* `fasls/` -- output files while running tests. * `fasls/` -- output files while running tests.
* `ext/` * [ext/](ext/)
* external dependencies, that can be populated with `make ext` * external dependencies, that can be populated with `make ext`
or equivalently with `git submodule update --init`. or equivalently with `git submodule update --init`.
* `README` * [README.md](README.md)
* this file * this file
* `TODO` * [TODO](TODO)
* plenty of ideas for how to further improve ASDF. * plenty of ideas for how to further improve ASDF.
Last updated Sunday, March 22nd, 2015. Last updated Wednesday, May 6th, 2015.
...@@ -93,13 +93,13 @@ At this time, the interface is not great: it isn't obvious at all that you can i ...@@ -93,13 +93,13 @@ At this time, the interface is not great: it isn't obvious at all that you can i
use a scrollbar on the right of the top left side panel to navigate the many packages; use a scrollbar on the right of the top left side panel to navigate the many packages;
once you click on the package you're interested in, you can see its defined symbols: once you click on the package you're interested in, you can see its defined symbols:
* [http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html](http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html) * <http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html>
Another automated documentation tool is quickdocs, but unhappily, at the time of this writing, Another automated documentation tool is quickdocs, but unhappily, at the time of this writing,
it only extracts information from the first package it only extracts information from the first package
(see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)): (see [bug #24](https://github.com/fukamachi/quickdocs/issues/24)):
* [http://quickdocs.org/uiop/api](http://quickdocs.org/uiop/api) * <http://quickdocs.org/uiop/api>
Help wanted extracting working documentation from UIOP's docstrings. Help wanted extracting working documentation from UIOP's docstrings.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment