HACKING

   1 SBCL Hacking Guide
   2
   3   (This is not a most actively maintained file, but recommended
   4   reading anyways.)
   5
   6 Table of Contests
   7
   8 * Modifying
   9 * Patch Submissions
  10 * Coding Style
  11   * Reader Conditionals
  12   * Comments and Documentation
  13   * Syntax-related Conventions
  14   * Error and Warning Messages
  15   * Format Strings
  16 * Writing Tests
  17
  18 Modifying
  19 =========
  20
  21 To change the code at run-time the :SB-DEVEL feature is almost always
  22 necessary, otherwise a lot of macros, functions, and variables do not
  23 survive in the final image.
  24
  25 Patch Submissions
  26 =================
  27
  28 Preferred patch format is output from "git format-patch", including
  29 the commit message.
  30
  31 The commit message should explain the why and how of the change. See
  32 existing commit messages for examples -- for a truly trivial changes
  33 little is needed, but in most cases more is better.
  34
  35 Please include test-cases in your patch if at all possible: if you're
  36 not sure which file in tests/ to put your test case in, just pick one
  37 that seems vaguely appropriate. See the "Writing Tests" section for
  38 more information.
  39
  40 Please format your submission for ease of reading: unless the change
  41 is whitespace only, avoid re-indenting code you are not touching, etc.
  42
  43 Unless your change is large and best understood as a series of
  44 sequential changes, please send it in as single patch.
  45
  46 If your patch includes algorithmic changes, explain them. If your
  47 patch uses a published algorithm, please include a link to the paper.
  48 We aren't always as well-educated as we'd like to be...
  49
  50 Ready-to-apply patches should be submitted via Launchpad: please add
  51 the tag "review" to the associated bug (create new bug with name if
  52 there isn't one about the issue yet.)
  53
  54 Patches requiring more widespread discussion and feedback should be
  55 sent to the sbcl-devel mailing list.
  56
  57 If you have any questions, feel free to ask them on sbcl-devel,
  58 or the IRC channel #sbcl@irc.libera.chat.
  59
  60 Coding Style
  61 ============
  62
  63 See also PRINCIPLES and TLA files.
  64
  65 Most of the style hints in the Lisp FAQ apply.
  66
  67 When porting code we prefer code which factors dependencies into a set
  68 of interface functions and constants and includes implementations of
  69 the interface for the different systems.
  70
  71 Reader conditionals are frowed upon. Sometimes they're the least
  72 of all evils, but think thrice.
  73
  74 grammatical fussiness:
  75   Phrases are not capitalized.
  76   Sentences are capitalized.
  77   Periods terminate sentences.
  78   Periods separate phrases from succeeding sentences, e.g.
  79     ;;; the maximum number of transformations we'll make before
  80     ;;; concluding we're in an infinite loop and bailing. This can
  81     ;;; be changed, but it is an error to change it while we're
  82     ;;; solving a system.
  83     (defvar *max-n-transformations* 10)
  84   Lisp in comments is capitalized.
  85   Symbol names are capitalized.
  86
  87 usage fussiness:
  88   Function documentation can be a description of what the function
  89     does, e.g.
  90         ;;; Parse the arguments for a BDEFSTRUCT call, and return
  91         ;;;   (VALUES NAME DEFSTRUCT-ARGS MAKE-LOAD-FORM-FUN BDEFSTRUCT-STYPE),
  92         ;;; where NAME is the name of the new type, DEFSTRUCT-ARGS is the
  93         ;;; munged result suitable for passing on to DEFSTRUCT,
  94         ;;; MAKE-LOAD-FORM-FUN is the make load form function, or NIL if
  95         ;;; there's none, and BDEFSTRUCT-SUPERTYPE is the direct supertype
  96         ;;; of the type if it is another BDEFSTRUCT-defined type, or NIL
  97         ;;; otherwise.
  98         (defun parse-bdefstruct-args (nameoid &rest rest)
  99           ..)
 100     or a remark about the function, e.g.
 101         ;;; a helper function for BDEFSTRUCT in the #+XC-HOST case
 102         (defun uncross-defstruct-args (defstruct-args)
 103           ..)
 104     If you're talking about what the function does, ordinarily you
 105     should just say what the function does, e.g.
 106         ;;; Return the first prime number greater than or equal to X.
 107         (defun primify (x) ..)
 108     instead of telling the reader that you're going to tell him what
 109     the function does, e.g.
 110         ;;; PRIMIFY returns the first prime number greater than or
 111         ;;; equal to X.
 112         (defun primify (x) ..)
 113     or
 114         ;;; When you call this function on X, you get back the first
 115         ;;; prime number greater than or equal to X.
 116         (defun primify (x) ..)
 117   Documentation for public functions belongs in a docstring.
 118   Documentation for internal functions belongs mostly in a comment.
 119
 120 In general, if you can express it in the code instead of the comments,
 121 do so. E.g. the old CMUCL code has many comments above functions foo
 122 that say things like
 123         ;;; FOO -- interface
 124 If we were going to do something like that, we would prefer to do it by
 125 writing
 126         (EXPORT 'FOO)
 127 (Instead, for various other reasons, we centralize all the exports
 128 in package declarations.) The old "FOO -- interface" comments are bad
 129 style because they duplicate information (and they illustrate one
 130 of the evils of duplicating information by the way that they have
 131 drifted out of sync with the code).
 132
 133 Writing Tests
 134 =============
 135
 136 As mentioned in the "Patch Submissions" section, new features as well
 137 as bug fixes should always be accompanied by smoke, unit or regression
 138 tests as appropriate.
 139
 140 New tests should be added in the appropriate file in the "tests"
 141 directory. Files named TOPIC.pure.lisp contain tests which do not have
 142 side effects such as modifying the environment, defining functions or
 143 variables or starting new threads while files named TOPIC.impure.lisp
 144 contain test which do (impure test files are run each in a separate
 145 SBCL process).
 146
 147 All tests should use the WITH-TEST macro to associate a unique name
 148 with each test (see below) and prevent a whole test file from going up
 149 in smoke without an adequate description of the problem. The basic
 150 syntax is
 151
 152   (with-test (:name NAME)
 153     BODY)
 154
 155 where NAME is either a symbol or a list of symbols. All of these
 156 symbols have to be in one of the packages KEYWORD, CL or SB-* to make
 157 test names READable in SBCL images that did not read the test
 158 files. For tests associated to Launchpad bugs (because a feature
 159 requested in the LP bug has been implemented or a bug has been fixed),
 160 the LP bug number should be a part of the test name:
 161
 162   (with-test (:name (coerce :invalid-target-type :bug-12345))
 163     …)
 164
 165 When a test can be associated to a name in the CL package or one of
 166 the SB-* packages, that name should appear as a separate component in
 167 the test name, like COERCE in the example above. This may be useful in
 168 order to automatically associate functions and tests.
 169
 170 If possible, tests should not signal warnings during compilation or
 171 runtime and should not produce output in order to not clutter the
 172 output of the test runner and make real problems easier to identify.
 173
 174 Misc
 175 ----
 176
 177 There are a number of style practices on display in the code
 178 which are not good examples to follow:
 179   * using conditional compilation to support different architectures,
 180     instead of factoring the dependencies into interfaces and providing
 181     implementations of the interface for different architectures;
 182   * in conditional compilation, using a common subexpression over and
 183     over again, e.g. #+(OR X86 X86-64), when the important thing is
 184     that the platform supports single-instruction CAS. If you have to
 185     do something like that, define a new FOO feature, write #+FOO in
 186     many places, and arrange for the FOO feature to be set once and
 187     only once -- probably in make-config.sh. (That way future
 188     maintainers won't curse you.)
 189   * putting the defined symbol, and information about whether it's
 190     exported or not, into the comments around the definition of the symbol;
 191   * naming anything DO-FOO if it isn't an iteration macro
 192   * not using a consistent abbreviation style in global names (e.g.
 193     naming some things DEFINE-FOO and other things DEF-BAR, with
 194     no rule to determine whether the abbreviation is used).
 195   * using lots of single-colon package prefixes (distracting and hard
 196     to read, and obstacles to reaching package nirvana where
 197     package dependencies are a directed acyclic graph) or even
 198     double-colon package prefixes (hard to understand and hard
 199     to maintain). (One exception: I've sometimes been tempted to
 200     add a CL: prefix to the definition of every CL symbol (e.g.
 201     (DEFUN CL:CADDDR (..) ..) as reminders that they're required by
 202     ANSI and can't be deleted no matter how obscure and useless some
 203     of them might look.:-)
 204 Many of these are common in the code inherited from CMUCL. We've
 205 eliminated them in some places, but there's a *lot* of code inherited
 206 from CMUCL..