| 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 ..." |