visus
/
toolchain-gcc-arm-embedded
Watch 1
Star 0
Fork 0
Code Issues 0 Pull Requests 0 Releases 0 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 Commits
1 Branch
Branch: main
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'main'
${ noResults }
toolchain-gcc-arm-embedded/share/doc/gcc-arm-none-eabi/html/gdb/Commands-In-Guile.html

415 lines
18KB
Raw Permalink Blame History 

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

  2. <html>

  3. <!-- Copyright (C) 1988-2020 Free Software Foundation, Inc.

  4. 

  5. Permission is granted to copy, distribute and/or modify this document

  6. under the terms of the GNU Free Documentation License, Version 1.3 or

  7. any later version published by the Free Software Foundation; with the

  8. Invariant Sections being "Free Software" and "Free Software Needs

  9. Free Documentation", with the Front-Cover Texts being "A GNU Manual,"

  10. and with the Back-Cover Texts as in (a) below.

  11. 

  12. (a) The FSF's Back-Cover Text is: "You are free to copy and modify

  13. this GNU Manual.  Buying copies from GNU Press supports the FSF in

  14. developing GNU and promoting software freedom." -->

  15. <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->

  16. <head>

  17. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

  18. <title>Commands In Guile (Debugging with GDB)</title>

  19. 

  20. <meta name="description" content="Commands In Guile (Debugging with GDB)">

  21. <meta name="keywords" content="Commands In Guile (Debugging with GDB)">

  22. <meta name="resource-type" content="document">

  23. <meta name="distribution" content="global">

  24. <meta name="Generator" content="makeinfo">

  25. <link href="index.html#Top" rel="start" title="Top">

  26. <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">

  27. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">

  28. <link href="Guile-API.html#Guile-API" rel="up" title="Guile API">

  29. <link href="Parameters-In-Guile.html#Parameters-In-Guile" rel="next" title="Parameters In Guile">

  30. <link href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" rel="prev" title="Writing a Guile Pretty-Printer">

  31. <style type="text/css">

  32. <!--

  33. a.summary-letter {text-decoration: none}

  34. blockquote.indentedblock {margin-right: 0em}

  35. blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}

  36. blockquote.smallquotation {font-size: smaller}

  37. div.display {margin-left: 3.2em}

  38. div.example {margin-left: 3.2em}

  39. div.lisp {margin-left: 3.2em}

  40. div.smalldisplay {margin-left: 3.2em}

  41. div.smallexample {margin-left: 3.2em}

  42. div.smalllisp {margin-left: 3.2em}

  43. kbd {font-style: oblique}

  44. pre.display {font-family: inherit}

  45. pre.format {font-family: inherit}

  46. pre.menu-comment {font-family: serif}

  47. pre.menu-preformatted {font-family: serif}

  48. pre.smalldisplay {font-family: inherit; font-size: smaller}

  49. pre.smallexample {font-size: smaller}

  50. pre.smallformat {font-family: inherit; font-size: smaller}

  51. pre.smalllisp {font-size: smaller}

  52. span.nolinebreak {white-space: nowrap}

  53. span.roman {font-family: initial; font-weight: normal}

  54. span.sansserif {font-family: sans-serif; font-weight: normal}

  55. ul.no-bullet {list-style: none}

  56. -->

  57. </style>

  58. 

  59. 

  60. </head>

  61. 

  62. <body lang="en">

  63. <a name="Commands-In-Guile"></a>

  64. <div class="header">

  65. <p>

  66. Next: <a href="Parameters-In-Guile.html#Parameters-In-Guile" accesskey="n" rel="next">Parameters In Guile</a>, Previous: <a href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" accesskey="p" rel="prev">Writing a Guile Pretty-Printer</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>

  67. </div>

  68. <hr>

  69. <a name="Commands-In-Guile-1"></a>

  70. <h4 class="subsubsection">23.3.3.11 Commands In Guile</h4>

  71. 

  72. <a name="index-commands-in-guile"></a>

  73. <a name="index-guile-commands-1"></a>

  74. <p>You can implement new <small>GDB</small> CLI commands in Guile.  A CLI

  75. command object is created with the <code>make-command</code> Guile function,

  76. and added to <small>GDB</small> with the <code>register-command!</code> Guile function.

  77. This two-step approach is taken to separate out the side-effect of adding

  78. the command to <small>GDB</small> from <code>make-command</code>.

  79. </p>

  80. <p>There is no support for multi-line commands, that is commands that

  81. consist of multiple lines and are terminated with <code>end</code>.

  82. </p>

  83. <dl>

  84. <dt><a name="index-_0028make_002dcommand"></a>Scheme Procedure: <strong>(make-command</strong> <em>name <span class="roman">[</span>#:invoke invoke] <span class="roman">[</span>#:command-class command-class<span class="roman">]</span> <span class="roman">[</span>#:completer-class completer] <span class="roman">[</span>#:prefix? prefix<span class="roman">]</span> <span class="roman">[</span>#:doc doc-string])</em></dt>

  85. <dd>

  86. <p>The argument <var>name</var> is the name of the command.  If <var>name</var> consists of

  87. multiple words, then the initial words are looked for as prefix

  88. commands.  In this case, if one of the prefix commands does not exist,

  89. an exception is raised.

  90. </p>

  91. <p>The result is the <code>&lt;gdb:command&gt;</code> object representing the command.

  92. The command is not usable until it has been registered with <small>GDB</small>

  93. with <code>register-command!</code>.

  94. </p>

  95. <p>The rest of the arguments are optional.

  96. </p>

  97. <p>The argument <var>invoke</var> is a procedure of three arguments: <var>self</var>,

  98. <var>args</var> and <var>from-tty</var>.  The argument <var>self</var> is the

  99. <code>&lt;gdb:command&gt;</code> object representing the command.

  100. The argument <var>args</var> is a string representing the arguments passed to

  101. the command, after leading and trailing whitespace has been stripped.

  102. The argument <var>from-tty</var> is a boolean flag and specifies whether the

  103. command should consider itself to have been originated from the user

  104. invoking it interactively.  If this function throws an exception,

  105. it is turned into a <small>GDB</small> <code>error</code> call.

  106. Otherwise, the return value is ignored.

  107. </p>

  108. <p>The argument <var>command-class</var> is one of the &lsquo;<samp>COMMAND_</samp>&rsquo; constants

  109. defined below.  This argument tells <small>GDB</small> how to categorize the

  110. new command in the help system.  The default is <code>COMMAND_NONE</code>.

  111. </p>

  112. <p>The argument <var>completer</var> is either <code>#f</code>, one of the &lsquo;<samp>COMPLETE_</samp>&rsquo;

  113. constants defined below, or a procedure, also defined below.

  114. This argument tells <small>GDB</small> how to perform completion

  115. for this command.  If not provided or if the value is <code>#f</code>,

  116. then no completion is performed on the command.

  117. </p>

  118. <p>The argument <var>prefix</var> is a boolean flag indicating whether the new

  119. command is a prefix command; sub-commands of this command may be

  120. registered.

  121. </p>

  122. <p>The argument <var>doc-string</var> is help text for the new command.

  123. If no documentation string is provided, the default value &ldquo;This command is

  124. not documented.&rdquo; is used.

  125. </p></dd></dl>

  126. 

  127. <dl>

  128. <dt><a name="index-register_002dcommand_0021"></a>Scheme Procedure: <strong>register-command!</strong> <em>command</em></dt>

  129. <dd><p>Add <var>command</var>, a <code>&lt;gdb:command&gt;</code> object, to <small>GDB</small>&rsquo;s

  130. list of commands.

  131. It is an error to register a command more than once.

  132. The result is unspecified.

  133. </p></dd></dl>

  134. 

  135. <dl>

  136. <dt><a name="index-command_003f"></a>Scheme Procedure: <strong>command?</strong> <em>object</em></dt>

  137. <dd><p>Return <code>#t</code> if <var>object</var> is a <code>&lt;gdb:command&gt;</code> object.

  138. Otherwise return <code>#f</code>.

  139. </p></dd></dl>

  140. 

  141. <a name="index-don_0027t-repeat-Guile-command"></a>

  142. <dl>

  143. <dt><a name="index-dont_002drepeat"></a>Scheme Procedure: <strong>dont-repeat</strong></dt>

  144. <dd><p>By default, a <small>GDB</small> command is repeated when the user enters a

  145. blank line at the command prompt.  A command can suppress this

  146. behavior by invoking the <code>dont-repeat</code> function.  This is similar

  147. to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>.

  148. </p></dd></dl>

  149. 

  150. <dl>

  151. <dt><a name="index-string_002d_003eargv"></a>Scheme Procedure: <strong>string-&gt;argv</strong> <em>string</em></dt>

  152. <dd><p>Convert a string to a list of strings split up according to

  153. <small>GDB</small>&rsquo;s argv parsing rules.

  154. It is recommended to use this for consistency.

  155. Arguments are separated by spaces and may be quoted.

  156. Example:

  157. </p>

  158. <div class="smallexample">

  159. <pre class="smallexample">scheme@(guile-user)&gt; (string-&gt;argv &quot;1 2\\ \\\&quot;3 '4 \&quot;5' \&quot;6 '7\&quot;&quot;)

  160. $1 = (&quot;1&quot; &quot;2 \&quot;3&quot; &quot;4 \&quot;5&quot; &quot;6 '7&quot;)

  161. </pre></div>

  162. </dd></dl>

  163. 

  164. <dl>

  165. <dt><a name="index-throw_002duser_002derror"></a>Scheme Procedure: <strong>throw-user-error</strong> <em>message . args</em></dt>

  166. <dd><p>Throw a <code>gdb:user-error</code> exception.

  167. The argument <var>message</var> is the error message as a format string, like the 

  168. <var>fmt</var> argument to the <code>format</code> Scheme function.

  169. See <a href="http://www.gnu.org/software/guile/manual/html_node/Formatted-Output.html#Formatted-Output">Formatted Output</a> in <cite>GNU Guile Reference Manual</cite>.

  170. The argument <var>args</var> is a list of the optional arguments of <var>message</var>.

  171. </p>

  172. <p>This is used when the command detects a user error of some kind,

  173. say a bad command argument.

  174. </p>

  175. <div class="smallexample">

  176. <pre class="smallexample">(gdb) guile (use-modules (gdb))

  177. (gdb) guile

  178. (register-command! (make-command &quot;test-user-error&quot;

  179.   #:command-class COMMAND_OBSCURE

  180.   #:invoke (lambda (self arg from-tty)

  181.     (throw-user-error &quot;Bad argument ~a&quot; arg))))

  182. end

  183. (gdb) test-user-error ugh

  184. ERROR: Bad argument ugh

  185. </pre></div>

  186. </dd></dl>

  187. 

  188. <a name="index-completion-of-Guile-commands"></a>

  189. <dl>

  190. <dt><a name="index-self"></a>completer: <strong>self</strong> <em>text word</em></dt>

  191. <dd><p>If the <var>completer</var> option to <code>make-command</code> is a procedure,

  192. it takes three arguments: <var>self</var> which is the <code>&lt;gdb:command&gt;</code>

  193. object, and <var>text</var> and <var>word</var> which are both strings.

  194. The argument <var>text</var> holds the complete command line up to the cursor&rsquo;s

  195. location.  The argument <var>word</var> holds the last word of the command line;

  196. this is computed using a word-breaking heuristic.

  197. </p>

  198. <p>All forms of completion are handled by this function, that is,

  199. the <tt class="key">TAB</tt> and <tt class="key">M-?</tt> key bindings (see <a href="Completion.html#Completion">Completion</a>),

  200. and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>).

  201. </p>

  202. <p>This procedure can return several kinds of values:

  203. </p>

  204. <ul>

  205. <li> If the return value is a list, the contents of the list are used as the

  206. completions.  It is up to <var>completer</var> to ensure that the

  207. contents actually do complete the word.  An empty list is

  208. allowed, it means that there were no completions available.  Only

  209. string elements of the list are used; other elements in the

  210. list are ignored.

  211. 

  212. </li><li> If the return value is a <code>&lt;gdb:iterator&gt;</code> object, it is iterated over to

  213. obtain the completions.  It is up to <code>completer-procedure</code> to ensure

  214. that the results actually do complete the word.  Only

  215. string elements of the result are used; other elements in the

  216. sequence are ignored.

  217. 

  218. </li><li> All other results are treated as though there were no available

  219. completions.

  220. </li></ul>

  221. </dd></dl>

  222. 

  223. <p>When a new command is registered, it will have been declared as a member of

  224. some general class of commands.  This is used to classify top-level

  225. commands in the on-line help system; note that prefix commands are not

  226. listed under their own category but rather that of their top-level

  227. command.  The available classifications are represented by constants

  228. defined in the <code>gdb</code> module:

  229. </p>

  230. <dl compact="compact">

  231. <dt><code>COMMAND_NONE</code>

  232. <a name="index-COMMAND_005fNONE-1"></a>

  233. </dt>

  234. <dd><p>The command does not belong to any particular class.  A command in

  235. this category will not be displayed in any of the help categories.

  236. This is the default.

  237. </p>

  238. </dd>

  239. <dt><code>COMMAND_RUNNING</code>

  240. <a name="index-COMMAND_005fRUNNING-1"></a>

  241. </dt>

  242. <dd><p>The command is related to running the inferior.  For example,

  243. <code>start</code>, <code>step</code>, and <code>continue</code> are in this category.

  244. Type <kbd>help running</kbd> at the <small>GDB</small> prompt to see a list of

  245. commands in this category.

  246. </p>

  247. </dd>

  248. <dt><code>COMMAND_DATA</code>

  249. <a name="index-COMMAND_005fDATA-1"></a>

  250. </dt>

  251. <dd><p>The command is related to data or variables.  For example,

  252. <code>call</code>, <code>find</code>, and <code>print</code> are in this category.  Type

  253. <kbd>help data</kbd> at the <small>GDB</small> prompt to see a list of commands

  254. in this category.

  255. </p>

  256. </dd>

  257. <dt><code>COMMAND_STACK</code>

  258. <a name="index-COMMAND_005fSTACK-1"></a>

  259. </dt>

  260. <dd><p>The command has to do with manipulation of the stack.  For example,

  261. <code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this

  262. category.  Type <kbd>help stack</kbd> at the <small>GDB</small> prompt to see a

  263. list of commands in this category.

  264. </p>

  265. </dd>

  266. <dt><code>COMMAND_FILES</code>

  267. <a name="index-COMMAND_005fFILES-1"></a>

  268. </dt>

  269. <dd><p>This class is used for file-related commands.  For example,

  270. <code>file</code>, <code>list</code> and <code>section</code> are in this category.

  271. Type <kbd>help files</kbd> at the <small>GDB</small> prompt to see a list of

  272. commands in this category.

  273. </p>

  274. </dd>

  275. <dt><code>COMMAND_SUPPORT</code>

  276. <a name="index-COMMAND_005fSUPPORT-1"></a>

  277. </dt>

  278. <dd><p>This should be used for &ldquo;support facilities&rdquo;, generally meaning

  279. things that are useful to the user when interacting with <small>GDB</small>,

  280. but not related to the state of the inferior.  For example,

  281. <code>help</code>, <code>make</code>, and <code>shell</code> are in this category.  Type

  282. <kbd>help support</kbd> at the <small>GDB</small> prompt to see a list of

  283. commands in this category.

  284. </p>

  285. </dd>

  286. <dt><code>COMMAND_STATUS</code>

  287. <a name="index-COMMAND_005fSTATUS-1"></a>

  288. </dt>

  289. <dd><p>The command is an &lsquo;<samp>info</samp>&rsquo;-related command, that is, related to the

  290. state of <small>GDB</small> itself.  For example, <code>info</code>, <code>macro</code>,

  291. and <code>show</code> are in this category.  Type <kbd>help status</kbd> at the

  292. <small>GDB</small> prompt to see a list of commands in this category.

  293. </p>

  294. </dd>

  295. <dt><code>COMMAND_BREAKPOINTS</code>

  296. <a name="index-COMMAND_005fBREAKPOINTS-1"></a>

  297. </dt>

  298. <dd><p>The command has to do with breakpoints.  For example, <code>break</code>,

  299. <code>clear</code>, and <code>delete</code> are in this category.  Type <kbd>help

  300. breakpoints</kbd> at the <small>GDB</small> prompt to see a list of commands in

  301. this category.

  302. </p>

  303. </dd>

  304. <dt><code>COMMAND_TRACEPOINTS</code>

  305. <a name="index-COMMAND_005fTRACEPOINTS-1"></a>

  306. </dt>

  307. <dd><p>The command has to do with tracepoints.  For example, <code>trace</code>,

  308. <code>actions</code>, and <code>tfind</code> are in this category.  Type

  309. <kbd>help tracepoints</kbd> at the <small>GDB</small> prompt to see a list of

  310. commands in this category.

  311. </p>

  312. </dd>

  313. <dt><code>COMMAND_USER</code>

  314. <a name="index-COMMAND_005fUSER-1"></a>

  315. </dt>

  316. <dd><p>The command is a general purpose command for the user, and typically

  317. does not fit in one of the other categories.

  318. Type <kbd>help user-defined</kbd> at the <small>GDB</small> prompt to see

  319. a list of commands in this category, as well as the list of gdb macros

  320. (see <a href="Sequences.html#Sequences">Sequences</a>).

  321. </p>

  322. </dd>

  323. <dt><code>COMMAND_OBSCURE</code>

  324. <a name="index-COMMAND_005fOBSCURE-1"></a>

  325. </dt>

  326. <dd><p>The command is only used in unusual circumstances, or is not of

  327. general interest to users.  For example, <code>checkpoint</code>,

  328. <code>fork</code>, and <code>stop</code> are in this category.  Type <kbd>help

  329. obscure</kbd> at the <small>GDB</small> prompt to see a list of commands in this

  330. category.

  331. </p>

  332. </dd>

  333. <dt><code>COMMAND_MAINTENANCE</code>

  334. <a name="index-COMMAND_005fMAINTENANCE-1"></a>

  335. </dt>

  336. <dd><p>The command is only useful to <small>GDB</small> maintainers.  The

  337. <code>maintenance</code> and <code>flushregs</code> commands are in this category.

  338. Type <kbd>help internals</kbd> at the <small>GDB</small> prompt to see a list of

  339. commands in this category.

  340. </p></dd>

  341. </dl>

  342. 

  343. <p>A new command can use a predefined completion function, either by

  344. specifying it via an argument at initialization, or by returning it

  345. from the <code>completer</code> procedure.  These predefined completion

  346. constants are all defined in the <code>gdb</code> module:

  347. </p>

  348. <dl compact="compact">

  349. <dt><code>COMPLETE_NONE</code>

  350. <a name="index-COMPLETE_005fNONE-1"></a>

  351. </dt>

  352. <dd><p>This constant means that no completion should be done.

  353. </p>

  354. </dd>

  355. <dt><code>COMPLETE_FILENAME</code>

  356. <a name="index-COMPLETE_005fFILENAME-1"></a>

  357. </dt>

  358. <dd><p>This constant means that filename completion should be performed.

  359. </p>

  360. </dd>

  361. <dt><code>COMPLETE_LOCATION</code>

  362. <a name="index-COMPLETE_005fLOCATION-1"></a>

  363. </dt>

  364. <dd><p>This constant means that location completion should be done.

  365. See <a href="Specify-Location.html#Specify-Location">Specify Location</a>.

  366. </p>

  367. </dd>

  368. <dt><code>COMPLETE_COMMAND</code>

  369. <a name="index-COMPLETE_005fCOMMAND-1"></a>

  370. </dt>

  371. <dd><p>This constant means that completion should examine <small>GDB</small>

  372. command names.

  373. </p>

  374. </dd>

  375. <dt><code>COMPLETE_SYMBOL</code>

  376. <a name="index-COMPLETE_005fSYMBOL-1"></a>

  377. </dt>

  378. <dd><p>This constant means that completion should be done using symbol names

  379. as the source.

  380. </p>

  381. </dd>

  382. <dt><code>COMPLETE_EXPRESSION</code>

  383. <a name="index-COMPLETE_005fEXPRESSION-1"></a>

  384. </dt>

  385. <dd><p>This constant means that completion should be done on expressions.

  386. Often this means completing on symbol names, but some language

  387. parsers also have support for completing on field names.

  388. </p></dd>

  389. </dl>

  390. 

  391. <p>The following code snippet shows how a trivial CLI command can be

  392. implemented in Guile:

  393. </p>

  394. <div class="smallexample">

  395. <pre class="smallexample">(gdb) guile

  396. (register-command! (make-command &quot;hello-world&quot;

  397.   #:command-class COMMAND_USER

  398.   #:doc &quot;Greet the whole world.&quot;

  399.   #:invoke (lambda (self args from-tty) (display &quot;Hello, World!\n&quot;))))

  400. end

  401. (gdb) hello-world

  402. Hello, World!

  403. </pre></div>

  404. 

  405. <hr>

  406. <div class="header">

  407. <p>

  408. Next: <a href="Parameters-In-Guile.html#Parameters-In-Guile" accesskey="n" rel="next">Parameters In Guile</a>, Previous: <a href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" accesskey="p" rel="prev">Writing a Guile Pretty-Printer</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>

  409. </div>

  410. 

  411. 

  412. 

  413. </body>

  414. </html>