1README for gdb/guile 2==================== 3 4This file contains important notes for gdb/guile developers. 5["gdb/guile" refers to the directory you found this file in] 6 7Nomenclature: 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 16Co-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 28Importing 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 38Implementation/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 67Coding 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 84General 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 102Comments: 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 112Smob 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 129Type naming: 130 131 - smob structs are typedefs named foo_smob 132 133Variable 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 145Function 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 212Doc 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 ..." 230