-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
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
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
* 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.
projects / sbcl.git / blobdiff