diff --git a/website/source/getting-started.mmd b/website/source/getting-started.mmd index ea6522ac95b54ef114d61e3e9def71d372fcf528..abeb9bdad3becc9198724059df57623128e30b62 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 35483d2b2170e0a1fc4b742ce1720f719dc4b639..66eaf557105f132a04bb55b6501c5755ad8bcc5e 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 b821b4f8bee8268c93dc9951c56f16b3582db947..207fb3e895058fc2fd0523788bef037c42854e5d 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 8ed6f51d6180e70421862ad298bdce144c1065c8..f99ce7de3d4ce92c9b1e3676ccdb296a29674508 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 8d993d678e6a938d7db2a544ae048dbe22411b9f..7e35df5a148fb5c1a7c6c8ee6761296d077e7aec 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