contrib/STANDARDS

   1 Proposed contrib standard, version $Revision$
   2
   3 The SBCL contrib mechanism is intended to provide a mechanism to
   4 manage code which does not form part of SBCL itself, but which is
   5 sufficiently closely associated with it that it would not be sensible
   6 to run it as a completely separate project.  For example, alternative
   7 top-levels, foreign-function glue for calling out to libraries, editor
   8 support, etc.  Portable ANSI code would not usually be considered for
   9 the contrib mechanism, unless it does something that is only useful in
  10 the context of SBCL.
  11
  12 * Responsibilities
  13
  14 The contrib directory is offered for code which is aimed primarily at
  15 SBCL users, and which has release cycles attuned with those of SBCL
  16 itself, but which the SBCL maintainers do not consider to be part of
  17 the core system.  This being so, the primary responsibility for
  18 maintaining it remains with the provider of the system; the only
  19 commitment that SBCL maintainers make with respect to contrib code is
  20 to not install stale contrib code: a contrib that fails its test suite
  21 against a given version of SBCL will not be installed in that release.
  22
  23 Note that despite leaving you the contrib maintainer with the
  24 responsibility of maintenance, we don't _necessarily_ (although we
  25 quite possibly would) offer you CVS access to the SBCL tree.  This is
  26 because we can't do that without letting you write to the rest of the
  27 tree as well (at least as far as I know, at sourceforge).
  28
  29 ** Release cycle
  30
  31 During the development cycle, changes to the core system may break
  32 contrib modules.  This may indicate bugs in SBCL (which we will
  33 probably want to fix before release anyway) or that the contrib uses
  34 deprecated features or internal symbols.
  35
  36 During the end-of-month freeze, core developers should avoid
  37 committing anything that breaks a previously working contrib module.
  38 Contrib maintainers should checkout the frozen SBCL version and
  39 submit patches where their contribs are broken.
  40
  41 Contrib modules that still don't work at release time will not be
  42 installed.
  43
  44 * Packaging
  45
  46 Each contrib package lives in $ROOT/contrib/packagename, and will
  47 install into $(SBCL_HOME)/packagename
  48
  49 A contrib package must contain a Makefile.  This is to have three targets
  50
  51 all:     # do whatever compilation is necessary
  52 test:    # run the package tests
  53 install: # copy all necessary files into $(INSTALL_DIR)
  54
  55 If the contrib package involves more than one file, you are encouraged
  56 to use ASDF to build it and load it.  A version of asdf is bundled as
  57 an SBCL contrib, which knows to look in $SBCL_HOME/systems/ for asd
  58 files - your install target should create an appropriate symlink there
  59 to the installed location of the system file.  Look in bsd-sockets/Makefile
  60 for an example of an asdf-using contrib
  61
  62 $(INSTALL_DIR) will have been created by the system before your
  63 install target is called.  You do not need to make it yourself.
  64
  65 * Tests
  66
  67 You must provide a 'test' target in your package Makefile.  This will
  68 be called to test whether your package is OK for installation, so if
  69 you have used SBCL internal interfaces or similar, this would be a
  70 good place to test that they still exist, etc.
  71
  72 * Documentation
  73
  74 [ Would be at least nice.  My tendency is to say plain text or HTML,
  75 and optionally your choice of source format which can generate either
  76 of the preceding.  Document formats not available on typical
  77 well-endowed-with-free-stuff Unix systems are discouraged.  DocBook
  78 is fine, as the SBCL manual is DocBook anyway ]
  79
  80 [ install.sh should copy the documentation somewhere that the user can
  81 find it ]
  82
  83 * Lisp-level requirements
  84
  85 An sbcl contrib should not stamp on sbcl internals or redefine symbols
  86 in CL, CL-USER.  Sometimes this is the only way to do something,
  87 though: individual cases will be considered on their merits.  A
  88 package that hacks undocumented(sic) interfaces may be accepted for
  89 contrib, but it does not follow from that that the interface is now
  90 published or will be preserved in future SBCL versions - contrib
  91 authors are encouraged instead to submit patches to SBCL that provide
  92 clean documented APIs which reasonably can be preserved.  If in doubt,
  93 seek consensus on the sbcl-devel list
  94
  95 A contrib must load into its own Lisp package(s) instead of polluting
  96 CL-USER or one of the system packages.  The Lisp package name should
  97 be chosen in some way that has reasonable expectation of being unique.
  98 [We could potentially keep a registry of contrib archive name =>
  99 package name(s)]
 100
 101