contrib/STANDARDS

   1 Proposed contrib standard, $Revision$
   2
   3 The SBCL contrib mechanism provides 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, it doesn't follow that we'd
  25 _necessarily_ offer you CVS access to the SBCL tree: each application
  26 is considered individually.  We often do, though.
  27
  28 ** Release cycle
  29
  30 During the development cycle, changes to the core system may break
  31 contrib modules.  This may indicate bugs in SBCL (which we will
  32 probably want to fix before release anyway) or that the contrib uses
  33 deprecated features or internal symbols.
  34
  35 During the end-of-month freeze, core developers should avoid
  36 committing anything that breaks a previously working contrib module.
  37 Contrib maintainers should checkout the frozen SBCL version and
  38 submit patches where their contribs are broken.
  39
  40 Contrib modules that still don't work at release time will not be
  41 installed.
  42
  43 * Packaging
  44
  45 Each contrib package lives in $ROOT/contrib/packagename, and will
  46 install into $(SBCL_HOME)/packagename
  47
  48 A contrib package must contain a Makefile.  This is to have three targets
  49
  50 all:     # do whatever compilation is necessary
  51 test:    # run the package tests
  52 install: # copy all necessary files into $(BUILD_ROOT)$(INSTALL_DIR)
  53
  54 If the contrib package involves more than one file, you are encouraged
  55 to use ASDF to build it and load it.  A version of asdf is bundled as
  56 an SBCL contrib, which knows to look in $SBCL_HOME/systems/ for asd
  57 files - your install target should create an appropriate symlink there
  58 to the installed location of the system file.  Look in
  59 sb-bsd-sockets/Makefile for an example of an asdf-using contrib.
  60
  61 $(BUILD_ROOT)$(INSTALL_DIR) will have been created by the system
  62 before your install target is called.  You do not need to make it
  63 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 Each package should provide documentation in Texinfo format.  For the
  75 documentation to be included in the sbcl manual, the following must
  76 hold:
  77
  78 - Each Texinfo file must have the extension `.texinfo' so the
  79   automatic manual builder will find it.
  80
  81 - It must contain one @node - @section pair at the top and only
  82   @subsection (or lower) sectioning commands within, e.g.
  83
  84 @node Sample Contrib
  85 @section Sample Contrib
  86 ...
  87
  88   so that the contrib menu can be created automatically.
  89
  90 Take care to choose unique node names.
  91
  92 [ make install should copy the documentation somewhere that the user
  93 can find it ]
  94
  95 * Lisp-level requirements
  96
  97 An sbcl contrib should attempt to avoid stamping on sbcl internals or
  98 redefining symbols in CL, CL-USER.  Sometimes this is the only way to do
  99 something, though: individual cases will be considered on their
 100 merits.  A package that hacks undocumented(sic) interfaces may be
 101 accepted for contrib, but it does not follow from that that the
 102 interface is now published or will be preserved in future SBCL
 103 versions - contrib authors are encouraged instead to submit patches to
 104 SBCL that provide clean documented APIs which reasonably can be
 105 preserved.  If in doubt, seek consensus on the sbcl-devel list
 106
 107 A contrib must load into its own Lisp package(s) instead of polluting
 108 CL-USER or one of the system packages.  The Lisp package names should
 109 begin with "SB-".  Ask the sbcl-devel list for a suitable name.