gdb/guile/README

   1 README for gdb/guile
   2 ====================
   3
   4 This file contains important notes for gdb/guile developers.
   5 ["gdb/guile" refers to the directory you found this file in]
   6
   7 Nomenclature:
   8
   9   In the implementation we use "Scheme" or "Guile" depending on context.
  10   And sometimes it doesn't matter.
  11   Guile is Scheme, and for the most part this is what we present to the user
  12   as well.  However, to highlight the fact that it is Guile, the GDB commands
  13   that invoke Scheme functions are named "guile" and "guile-repl",
  14   abbreviated "gu" and "gr" respectively.
  15
  16 Co-existence with Python:
  17
  18   Keep the user interfaces reasonably consistent, but don't shy away from
  19   providing a clearer (or more Scheme-friendly/consistent) user interface
  20   where appropriate.
  21
  22   Additions to Python support or Scheme support don't require corresponding
  23   changes in the other scripting language.
  24
  25   Scheme-wrapped breakpoints are created lazily so that if the user
  26   doesn't use Scheme s/he doesn't pay any cost.
  27
  28 Importing the gdb module into Scheme:
  29
  30   To import the gdb module:
  31   (gdb) guile (use-modules (gdb))
  32
  33   If you want to add a prefix to gdb module symbols:
  34   (gdb) guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
  35   This gives every symbol a "gdb:" prefix which is a common convention.
  36   OTOH it's more to type.
  37
  38 Implementation/Hacking notes:
  39
  40   Don't use scm_is_false.
  41   For this C function, () == #f (a la Lisp) and it's not clear how treating
  42   them as equivalent for truth values will affect the GDB interface.
  43   Until the effect is clear avoid them.
  44   Instead use gdbscm_is_false, gdbscm_is_true, gdbscm_is_bool.
  45   There are macros in guile-internal.h to enforce this.
  46
  47   Use gdbscm_foo as the name of functions that implement Scheme procedures
  48   to provide consistent naming in error messages.  The user can see "gdbscm"
  49   in the name and immediately know where the function came from.
  50
  51   All smobs contain gdb_smob or chained_gdb_smob as the first member.
  52   This provides a mechanism for extending them in the Scheme side without
  53   tying GDB to the details.
  54
  55   The lifetime of a smob, AIUI, is decided by the containing SCM.
  56   When there is no longer a reference to the containing SCM then the
  57   smob can be GC'd.  Objects that have references from outside of Scheme,
  58   e.g., breakpoints, need to be protected from GC.
  59
  60   Don't do something that can cause a Scheme exception inside a TRY_CATCH,
  61   and, in code that can be called from Scheme, don't do something that can
  62   cause a GDB exception outside a TRY_CATCH.
  63   This makes the code a little tricky to write sometimes, but it is a
  64   rule imposed by the programming environment.  Bugs often happen because
  65   this rule is broken.  Learn it, follow it.
  66 \f
  67 Coding style notes:
  68
  69   - If you find violations to these rules, let's fix the code.
  70     Some attempt has been made to be consistent, but it's early.
  71     Over time we want things to be more consistent, not less.
  72
  73   - None of this really needs to be read.  Instead, do not be creative:
  74     Monkey-See-Monkey-Do hacking should generally Just Work.
  75
  76   - Absence of the word "typically" means the rule is reasonably strict.
  77
  78   - The gdbscm_initialize_foo function (e.g., gdbscm_initialize_values)
  79     is the last thing to appear in the file, immediately preceded by any
  80     tables of exported variables and functions.
  81
  82   - In addition to these of course, follow GDB coding conventions.
  83
  84 General naming rules:
  85
  86   - The word "object" absent any modifier (like "GOOPS object") means a
  87     Scheme object (of any type), and is never used otherwise.
  88     If you want to refer to, e.g., a GOOPS object, say "GOOPS object".
  89
  90   - Do not begin any function, global variable, etc. name with scm_.
  91     That's what the Guile implementation uses.
  92     (kinda obvious, just being complete).
  93
  94   - The word "invalid" carries a specific connotation.  Try not to use it
  95     in a different way.  It means the underlying GDB object has disappeared.
  96     For example, a <gdb:objfile> smob becomes "invalid" when the underlying
  97     objfile is removed from GDB.
  98
  99   - We typically use the word "exception" to mean Scheme exceptions,
 100     and we typically use the word "error" to mean GDB errors.
 101
 102 Comments:
 103
 104   - function comments for functions implementing Scheme procedures begin with
 105     a description of the Scheme usage.  Example:
 106     /* (gsmob-aux gsmob) -> object */
 107
 108   - the following comment appears after the copyright header:
 109     /* See README file in this directory for implementation notes, coding
 110        conventions, et.al.  */
 111
 112 Smob naming:
 113
 114   - gdb smobs are named, internally, "gdb:foo"
 115   - in Guile they become <gdb:foo>, that is the convention for naming classes
 116     and smobs have rudimentary GOOPS support (they can't be inherited from,
 117     but generics can work with them)
 118   - in comments use the Guile naming for smobs,
 119     i.e., <gdb:foo> instead of gdb:foo.
 120     Note: This only applies to smobs.  Exceptions are also named gdb:foo,
 121     but since they are not "classes" they are not wrapped in <>.
 122   - smob names are stored in a global, and for simplicity we pass this
 123     global as the "expected type" parameter to SCM_ASSERT_TYPE, thus in
 124     this instance smob types are printed without the <>.
 125     [Hmmm, this rule seems dated now.  Plus I18N rules in GDB are not always
 126     clear, sometimes we pass the smob name through _(), however it's not
 127     clear that's actually a good idea.]
 128
 129 Type naming:
 130
 131   - smob structs are typedefs named foo_smob
 132
 133 Variable naming:
 134
 135   - "scm" by itself is reserved for arbitrary Scheme objects
 136
 137   - variables that are pointers to smob structs are named <char>_smob or
 138     <char><char>_smob, e.g., f_smob for a pointer to a frame smob
 139
 140   - variables that are gdb smob objects are typically named <char>_scm or
 141     <char><char>_scm, e.g., f_scm for a <gdb:frame> object
 142
 143   - the name of the first argument for method-like functions is "self"
 144
 145 Function naming:
 146
 147   General:
 148
 149   - all non-static functions have a prefix,
 150     either gdbscm_ or <char><char>scm_ [or <char><char><char>scm_]
 151
 152   - all functions that implement Scheme procedures have a gdbscm_ prefix,
 153     this is for consistency and readability of Scheme exception text
 154
 155   - static functions typically have a prefix
 156     - the prefix is typically <char><char>scm_ where the first two letters
 157       are unique to the file or class the function works with.
 158       E.g., the scm-arch.c prefix is arscm_.
 159       This follows something used in gdb/python in some places,
 160       we make it formal.
 161
 162   - if the function is of a general nature, or no other prefix works,
 163     use gdbscm_
 164
 165   Conversion functions:
 166
 167   - the from/to in function names follows from libguile's existing style
 168   - conversions from/to Scheme objects are named:
 169       prefix_scm_from_foo: converts from foo to scm
 170       prefix_scm_to_foo: converts from scm to foo
 171
 172   Exception handling:
 173
 174   - functions that may throw a Scheme exception have an _unsafe suffix
 175     - This does not apply to functions that implement Scheme procedures.
 176     - This does not apply to functions whose explicit job is to throw
 177       an exception.  Adding _unsafe to gdbscm_throw is kinda superfluous. :-)
 178   - functions that can throw a GDB error aren't adorned with _unsafe
 179
 180   - "_safe" in a function name means it will never throw an exception
 181     - Generally unnecessary, since the convention is to mark the ones that
 182       *can* throw an exception.  But sometimes it's useful to highlight the
 183       fact that the function is safe to call without worrying about exception
 184       handling.
 185
 186   - except for functions that implement Scheme procedures, all functions
 187     that can throw exceptions (GDB or Scheme) say so in their function comment
 188
 189   - functions that don't throw an exception, but still need to indicate to
 190     the caller that one happened (i.e., "safe" functions), either return
 191     a <gdb:exception> smob as a result or pass it back via a parameter.
 192     For this reason don't pass back <gdb:exception> smobs for any other
 193     reason.  There are functions that explicitly construct <gdb:exception>
 194     smobs.  They're obviously the, umm, exception.
 195
 196   Internal functions:
 197
 198   - internal Scheme functions begin with "%" and are intentionally undocumented
 199     in the manual
 200
 201   Standard Guile/Scheme conventions:
 202
 203   - predicates that return Scheme values have the suffix _p and have suffix "?"
 204     in the Scheme procedure's name
 205   - functions that implement Scheme procedures that modify state have the
 206     suffix _x and have suffix "!" in the Scheme procedure's name
 207   - object predicates that return a C truth value are named prefix_is_foo
 208   - functions that set something have "set" at the front (except for a prefix)
 209     write this: gdbscm_set_gsmob_aux_x implements (set-gsmob-aux! ...)
 210     not this: gdbscm_gsmob_set_aux_x implements (gsmob-set-aux! ...)
 211
 212 Doc strings:
 213
 214   - there are lots of existing examples, they should be pretty consistent,
 215     use them as boilerplate/examples
 216   - begin with a one line summary (can be multiple lines if necessary)
 217   - if the arguments need description:
 218     - blank line
 219     - "  Arguments: arg1 arg2"
 220       "    arg1: blah ..."
 221       "    arg2: blah ..."
 222   - if the result requires more description:
 223     - blank line
 224     - "  Returns:"
 225       "    Blah ..."
 226   - if it's important to list exceptions that can be thrown:
 227     - blank line
 228     - "  Throws:"
 229       "    exception-name: blah ..."