Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Update debugger docs with () and 'cy set'

  • Loading branch information...
commit 19ca6b53dbd3742f0bc919012bf8093b6edc6fef 1 parent b18cf63
Mark Florisson markflorisson88 authored

Showing 1 changed file with 29 additions and 19 deletions. Show diff stats Hide diff stats

  1. +29 19 src/userguide/debugging.rst
48 src/userguide/debugging.rst
Source Rendered
@@ -71,7 +71,7 @@ You can also pass additional arguments to gdb::
71 71 $ cygdb /path/to/build/directory/ GDBARGS
72 72
73 73 i.e.::
74   -
  74 +
75 75 $ cygdb . --args python-dbg mainscript.py
76 76
77 77 To tell cygdb not to import any debug information, supply ``--`` as the first
@@ -87,7 +87,7 @@ stack inspection, source code listing, stepping, stepping over, etc. Most
87 87 of these commands are analogous to their respective gdb command.
88 88
89 89 .. function:: cy break breakpoints...
90   -
  90 +
91 91 Break in a Python, Cython or C function. First it will look for a Cython
92 92 function with that name, if cygdb doesn't know about a function (or method)
93 93 with that name, it will set a (pending) C breakpoint. The ``-p`` option can
@@ -115,7 +115,7 @@ of these commands are analogous to their respective gdb command.
115 115
116 116 .. note:: Python breakpoints only work in Python builds where the Python frame
117 117 information can be read from the debugger. To ensure this, use a
118   - Python debug build or a non-stripped build compiled with debug
  118 + Python debug build or a non-stripped build compiled with debug
119 119 support.
120 120
121 121 .. function:: cy step
@@ -129,10 +129,10 @@ of these commands are analogous to their respective gdb command.
129 129 Step over Python, Cython or C code.
130 130
131 131 .. function:: cy run
132   -
  132 +
133 133 Run the program. The default interpreter is the interpreter that was used
134 134 to build your extensions with, or the interpreter ``cygdb`` is run with
135   - in case the "don't import debug information" option was in effect.
  135 + in case the "don't import debug information" option was in effect.
136 136 The interpreter can be overridden using gdb's ``file`` command.
137 137
138 138 .. function:: cy cont
@@ -146,7 +146,7 @@ of these commands are analogous to their respective gdb command.
146 146
147 147 .. function:: cy finish
148 148
149   - Execute until an upward relevant frame is met or something halts
  149 + Execute until an upward relevant frame is met or something halts
150 150 execution.
151 151
152 152 .. function:: cy bt
@@ -163,19 +163,23 @@ of these commands are analogous to their respective gdb command.
163 163
164 164 .. function:: cy print varname
165 165
166   - Print a local or global Cython, Python or C variable (depending on the
  166 + Print a local or global Cython, Python or C variable (depending on the
167 167 context). Variables may also be dereferenced::
168 168
169 169 (gdb) cy print x
170 170 x = 1
171 171 (gdb) cy print *x
172 172 *x = (PyObject) {
173   - _ob_next = 0x93efd8,
174   - _ob_prev = 0x93ef88,
175   - ob_refcnt = 65,
  173 + _ob_next = 0x93efd8,
  174 + _ob_prev = 0x93ef88,
  175 + ob_refcnt = 65,
176 176 ob_type = 0x83a3e0
177 177 }
178   -
  178 +
  179 +.. function:: cy set cython_variable = value
  180 +
  181 + Set a Cython variable on the Cython stack to value.
  182 +
179 183 .. function:: cy list
180 184
181 185 List the source code surrounding the current line.
@@ -193,14 +197,14 @@ of these commands are analogous to their respective gdb command.
193 197 .. function:: cy exec code
194 198
195 199 Execute code in the current Python or Cython frame. This works like
196   - Python's interactive interpreter.
  200 + Python's interactive interpreter.
197 201
198 202 For Python frames it uses the globals and locals from the Python frame,
199 203 for Cython frames it uses the dict of globals used on the Cython module
200 204 and a new dict filled with the local Cython variables.
201 205
202 206 .. note:: ``cy exec`` modifies state and executes code in the debuggee and is
203   - therefore potentially dangerous.
  207 + therefore potentially dangerous.
204 208
205 209 Example::
206 210
@@ -228,29 +232,35 @@ gdb expression.
228 232
229 233 Returns the value of a Cython variable.
230 234
  235 +.. function:: cy_eval(expression)
  236 +
  237 + Evaluates Python code in the nearest Python or Cython frame and returns
  238 + the result of the expression as a gdb value. This gives a new reference
  239 + if successful, NULL on error.
  240 +
231 241 .. function:: cy_lineno()
232 242
233 243 Returns the current line number in the selected Cython frame.
234 244
235   -
236 245 Example::
237 246
238 247 (gdb) print $cy_cname("x")
239 248 $1 = "__pyx_v_x"
240 249 (gdb) watch $cy_cvalue("x")
241 250 Hardware watchpoint 13: $cy_cvalue("x")
  251 + (gdb) cy set my_cython_variable = $cy_eval("{'spam': 'ham'}")
242 252 (gdb) print $cy_lineno()
243 253 $2 = 12
244 254
245   -
  255 +
246 256 Configuring the Debugger
247 257 ========================
248   -A few aspects of the debugger are configurable with gdb parameters. For
249   -instance, colors can be disabled, the terminal background color
  258 +A few aspects of the debugger are configurable with gdb parameters. For
  259 +instance, colors can be disabled, the terminal background color
250 260 and breakpoint autocompletion can be configured.
251 261
252 262 .. c:macro:: cy_complete_unqualified
253   -
  263 +
254 264 Tells the Cython debugger whether ``cy break`` should also complete
255 265 plain function names, i.e. not prefixed by their module name.
256 266 E.g. if you have a function named ``spam``,
@@ -266,7 +276,7 @@ and breakpoint autocompletion can be configured.
266 276 .. c:macro:: cy_terminal_background_color
267 277
268 278 Tells the debugger about the terminal background color, which affects
269   - source code coloring. The default is "dark", another valid option is
  279 + source code coloring. The default is "dark", another valid option is
270 280 "light".
271 281
272 282 This is how these parameters can be used::

0 comments on commit 19ca6b5

Please sign in to comment.
Something went wrong with that request. Please try again.