From 09f664a6d15530fad396eb5874a9b4d930dd579d Mon Sep 17 00:00:00 2001
From: Gary King <gwking@franz.com>
Date: Sun, 13 Sep 2009 15:16:12 -0400
Subject: [PATCH] added ABL information to website

---
 website/source/getting-started.mmd        | 77 +++++++++++++++++++++++
 website/source/git.mmd                    | 20 +++---
 website/source/index.mmd                  | 13 ++--
 website/source/manual.mmd                 | 30 +++++++++
 website/source/resources/shared-header.md |  1 +
 5 files changed, 126 insertions(+), 15 deletions(-)

diff --git a/website/source/getting-started.mmd b/website/source/getting-started.mmd
index ea6522ac..abeb9bda 100644
--- a/website/source/getting-started.mmd
+++ b/website/source/getting-started.mmd
@@ -88,6 +88,83 @@ or you can tell ASDF where to look to find them using the
 
 You'll need to set this variable up to match your system setup and will probably want to include it in your Lisp's startup script.
 
+## Controlling where ASDF saves compiled files
+
+Each Common Lisp implementation has its own format for
+compiled files (fasls for short). If you use multiple
+implementations (or multiple versions of the same
+implementation), you'll soon find your source directories
+littered with various `DFSL`s, `FASL`s, `CFSL`s and so on.
+Worse yet, some implementations use the same file extension
+or change formats from version to version which means that
+you'll have to recompile binaries as you switch from one
+implementation to the next. 
+
+As of version 1.365, ASDF includes [ASDF-binary-locations][asdf-binary-locations] to mitigate the problem. 
+ 
+#### Default Locations
+
+The default binary location for each Lisp implementation is a subdirectory of each source directory. To account for different Lisps, Operating Systems, Implementation versions, and so on, ASDF borrows code from [SLIME][] to create reasonable custom directory names. Here are some examples:
+
+ * SBCL, version 1.0 on Mac OS X for intel: sbcl-1.0-darwin-x86
+ 
+ * Franz Allegro, version 8.0, ANSI Common Lisp:  allegro-8.0a-macosx-x86
+ 
+ * Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: allegro-8.1m-macosx-x86
+ 
+If you want to keep `FASL` files out of source tree entirely \*centralize-lisp-binaries\*  to put compiled files into sub-directories of a single central location (see 
+
+ [cbl]: #centralize-lisp-binaries
+ 
+Here is a summary of the variables that control ASDF's source-to-binary mappings: 
+
+  * \*place-binaries-in-implementation-specific-directories\*:
+    If false, then ASDF will place binaries in the same
+    directory as the source. If true, then ASDF will move the
+    binaries using the rest of the configuration. Defaults to
+    `nil`.
+
+  * \*centralize-lisp-binaries\*: If true, compiled lisp
+    files without an explicit mapping (see
+    \*source-to-target-mappings\*) will be placed in
+    subdirectories of \*default-toplevel-directory\*. If
+    false, then compiled lisp files without an explicit
+    mapping will be placed in subdirectories of their
+    sources. Defaults to `nil`.
+
+  * \*default-toplevel-directory\*. If
+    \*centralize-lisp-binaries\* is true, then compiled lisp
+    files without an explicit mapping (see
+    \*source-to-target-mappings\*) will be placed in
+    subdirectories of \*default-toplevel-directory\*.
+    Defaults to a sub-directory named `.fasls` in the current
+    user's home directory.
+
+  * \*include-per-user-information\*. specifies whether or
+    not to include user information in the directory. Only
+    used when \*centralize-lisp-binaries\* is true. Defaults
+    to `nil`.
+
+  * \*map-all-source-files\*. If true, then all source files
+    will be mapped by ASDF. If `nil`, then only Common
+    Lisp Source Files (i.e., instances of cl-source-file or
+    its subclasses) will be. Defaults to `nil`.
+
+  * \*source-to-target-mappings\*. This specifies mappings
+    from source to target. If the target is nil, then it
+    means to *not* map the source to anything. I.e., to leave
+    it as is. This has the effect of turning off
+    ASDF-Binary-Locations for the given source directory. The
+    default depends on the Lisp implementation.
+
+These variables are used by
+`output-files-for-system-and-operation` to determine where to
+place a source file's binary. You can further customize ABL
+by writing additional methods on the generic function
+`output-files-for-system-and-operation`.
+
+See the [manual][binary-locations] for more details.
+
 ## Summary
 
 To use ASDF:
diff --git a/website/source/git.mmd b/website/source/git.mmd
index 35483d2b..66eaf557 100644
--- a/website/source/git.mmd
+++ b/website/source/git.mmd
@@ -1,17 +1,15 @@
 ## git recipes
 
-
- 
- > Alternatively, would someone please provide simple recipes for dealing
- > with git?  It's really far more complex than CVS, and I don't see
- > obvious patterns of interaction to do simple things like restore
- > synchronization with the central repo.
-
- git fetch origin
-  downloads latest commits
- git reset --hard origin/master 
-  nukes all local changes, synchronizing with the remote repo
+### sychronize with the central repository
  
+    # downloads the latest commits from CL.net
+    git fetch origin
+
+    # removes any local changes and synchronizes with 
+    # what we just downloaded from the remote repo
+    git reset --hard origin/master 
+
+
 ## git resources
 
 Here are a few links that might be helpful to people learning
diff --git a/website/source/index.mmd b/website/source/index.mmd
index b821b4f8..207fb3e8 100644
--- a/website/source/index.mmd
+++ b/website/source/index.mmd
@@ -45,7 +45,8 @@ can:
 
 ### Contributing
 
-We're still working out the details. For now, send email to
+We're still working out the details but you should take a look at our [git resources][git-resources].
+For now, send email to
 gwking@metabang.com or the project [mailing-list][asdf-devel]
 with questions or patches.
 
@@ -54,10 +55,14 @@ with questions or patches.
 
 ### What is happening
 
- * Saturday; June 6, 2009 - updated website and added [oos][]
-   shortcuts like [load-system][].
+Sunday; September 13, 2009
+: Added documentation for ASDF-Binary-Locations
 
- * Sunday; May 3, 2009 - moving towards git and Common-Lisp.net
+Saturday; June 6, 2009 
+: updated website and added [oos][] shortcuts like [load-system][].
+
+Sunday; May 3, 2009 
+: moving towards git and Common-Lisp.net
 
 
 </div>
diff --git a/website/source/manual.mmd b/website/source/manual.mmd
index 8ed6f51d..f99ce7de 100644
--- a/website/source/manual.mmd
+++ b/website/source/manual.mmd
@@ -791,6 +791,36 @@ way:
           ...
          )
 
+{anchor binary-locations}
+
+## Controlling where ASDF saves compiled files
+
+ASDF includes code to control where the binaries files are places. The location depends on the the Common Lisp implementation and platform. The getting-started guides summaries the variables that control the mapping. The details for each variable can be found below:
+
+#### Customization
+
+{anchor centralize-lisp-binaries}
+
+{docs *centralize-lisp-binaries*}
+
+{docs *default-toplevel-directory*}
+
+{docs *include-per-user-information*}
+
+{docs *map-all-source-files*}
+
+{docs *place-binaries-in-implementation-specific-directories*}
+
+{docs *source-to-target-mappings*}
+
+{docs implementation-specific-directory-name}
+
+{docs output-files-for-system-and-operation}
+
+### Notes and Issues
+
+ * SBCL ships with several included ASDF libraries which used to confuse ABL because it would try to recompile the `FASL`s and then run into directory permission problems. ASDF knows about these and uses a mapping like `/usr/local/lib/sbcl` to `nil` so that the `FASL`s are not relocated. 
+
 ## Special variables
 
 {docs *asdf-revision*}
diff --git a/website/source/resources/shared-header.md b/website/source/resources/shared-header.md
index 8d993d67..7e35df5a 100644
--- a/website/source/resources/shared-header.md
+++ b/website/source/resources/shared-header.md
@@ -16,6 +16,7 @@
  [FAQ]: faq.html
  [tests]: test-results.html
  [git-browse]: http://common-lisp.net/gitweb?p=projects/asdf/asdf.git;a=summary
+ [git-resources]: git.html
   
  [asdf-devel]: http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
  [asdf-announce]: http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-announce
-- 
GitLab