X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2FSTANDARDS;h=c66f77b57904a776d27d849e5f8ed17cc1e0b1cf;hb=062283b901155792f65775491aea51481c56faaa;hp=f5b9598c3dd459a9f7b927abd2afa4139e5a2616;hpb=edc8da40fb17de047e290ed6bd819e096e435dc9;p=sbcl.git diff --git a/contrib/STANDARDS b/contrib/STANDARDS index f5b9598..c66f77b 100644 --- a/contrib/STANDARDS +++ b/contrib/STANDARDS @@ -1,6 +1,6 @@ -Proposed contrib standard, version $Revision$ +Proposed contrib standard, $Revision$ -The SBCL contrib mechanism is intended to provide a mechanism to +The SBCL contrib mechanism provides a mechanism to manage code which does not form part of SBCL itself, but which is sufficiently closely associated with it that it would not be sensible to run it as a completely separate project. For example, alternative @@ -21,10 +21,9 @@ to not install stale contrib code: a contrib that fails its test suite against a given version of SBCL will not be installed in that release. Note that despite leaving you the contrib maintainer with the -responsibility of maintenance, we don't _necessarily_ (although we -quite possibly would) offer you CVS access to the SBCL tree. This is -because we can't do that without letting you write to the rest of the -tree as well (at least as far as I know, at sourceforge). +responsibility of maintenance, it doesn't follow that we'd +_necessarily_ offer you CVS access to the SBCL tree: each application +is considered individually. We often do, though. ** Release cycle @@ -50,17 +49,18 @@ A contrib package must contain a Makefile. This is to have three targets all: # do whatever compilation is necessary test: # run the package tests -install: # copy all necessary files into $(INSTALL_DIR) +install: # copy all necessary files into $(BUILD_ROOT)$(INSTALL_DIR) If the contrib package involves more than one file, you are encouraged to use ASDF to build it and load it. A version of asdf is bundled as an SBCL contrib, which knows to look in $SBCL_HOME/systems/ for asd files - your install target should create an appropriate symlink there -to the installed location of the system file. Look in bsd-sockets/Makefile -for an example of an asdf-using contrib +to the installed location of the system file. Look in +sb-bsd-sockets/Makefile for an example of an asdf-using contrib. -$(INSTALL_DIR) will have been created by the system before your -install target is called. You do not need to make it yourself. +$(BUILD_ROOT)$(INSTALL_DIR) will have been created by the system +before your install target is called. You do not need to make it +yourself. * Tests @@ -71,31 +71,39 @@ good place to test that they still exist, etc. * Documentation -[ Would be at least nice. My tendency is to say plain text or HTML, -and optionally your choice of source format which can generate either -of the preceding. Document formats not available on typical -well-endowed-with-free-stuff Unix systems are discouraged. DocBook -is fine, as the SBCL manual is DocBook anyway ] +Each package should provide documentation in Texinfo format. For the +documentation to be included in the sbcl manual, the following must +hold: -[ install.sh should copy the documentation somewhere that the user can -find it ] +- Each Texinfo file must have the extension `.texinfo' so the + automatic manual builder will find it. -* Lisp-level requirements +- It must contain one @node - @section pair at the top and only + @subsection (or lower) sectioning commands within, e.g. -An sbcl contrib should not stamp on sbcl internals or redefine symbols -in CL, CL-USER. Sometimes this is the only way to do something, -though: individual cases will be considered on their merits. A -package that hacks undocumented(sic) interfaces may be accepted for -contrib, but it does not follow from that that the interface is now -published or will be preserved in future SBCL versions - contrib -authors are encouraged instead to submit patches to SBCL that provide -clean documented APIs which reasonably can be preserved. If in doubt, -seek consensus on the sbcl-devel list +@node Sample Contrib +@section Sample Contrib +... -A contrib must load into its own Lisp package(s) instead of polluting -CL-USER or one of the system packages. The Lisp package name should -be chosen in some way that has reasonable expectation of being unique. -[We could potentially keep a registry of contrib archive name => -package name(s)] + so that the contrib menu can be created automatically. +Take care to choose unique node names. +[ make install should copy the documentation somewhere that the user +can find it ] + +* Lisp-level requirements + +An sbcl contrib should attempt to avoid stamping on sbcl internals or +redefining symbols in CL, CL-USER. Sometimes this is the only way to do +something, though: individual cases will be considered on their +merits. A package that hacks undocumented(sic) interfaces may be +accepted for contrib, but it does not follow from that that the +interface is now published or will be preserved in future SBCL +versions - contrib authors are encouraged instead to submit patches to +SBCL that provide clean documented APIs which reasonably can be +preserved. If in doubt, seek consensus on the sbcl-devel list + +A contrib must load into its own Lisp package(s) instead of polluting +CL-USER or one of the system packages. The Lisp package names should +begin with "SB-". Ask the sbcl-devel list for a suitable name.