gencgc: Simpler conservative root validation on non-x86oids.

[sbcl.git] / contrib / STANDARDS

diff --git a/contrib/STANDARDS b/contrib/STANDARDS
index f5b9598..c66f77b 100644 (file)
--- 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
 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
 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
 
 
 ** 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
 
 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
 
 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
 
 
 * Tests
 

@@ -71,31 +71,39 @@ good place to test that they still exist, etc.
 
 * Documentation
 
 
 * 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.