|
| 1 | +# SOME DESCRIPTIVE TITLE. |
| 2 | +# Copyright (C) 2001-2024, Python Software Foundation |
| 3 | +# This file is distributed under the same license as the Python package. |
| 4 | +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. |
| 5 | +# |
| 6 | +#, fuzzy |
| 7 | +msgid "" |
| 8 | +msgstr "" |
| 9 | +"Project-Id-Version: Python 3.12\n" |
| 10 | +"Report-Msgid-Bugs-To: \n" |
| 11 | +"POT-Creation-Date: 2024-02-24 00:03+0000\n" |
| 12 | +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" |
| 13 | +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" |
| 14 | +" Language-Team: LANGUAGE <[email protected]>\n" |
| 15 | +"Language: zh_TW\n" |
| 16 | +"MIME-Version: 1.0\n" |
| 17 | +"Content-Type: text/plain; charset=UTF-8\n" |
| 18 | +"Content-Transfer-Encoding: 8bit\n" |
| 19 | + |
| 20 | +#: ../../howto/gdb_helpers.rst:5 |
| 21 | +msgid "Debugging C API extensions and CPython Internals with GDB" |
| 22 | +msgstr "" |
| 23 | + |
| 24 | +#: ../../howto/gdb_helpers.rst:9 |
| 25 | +msgid "" |
| 26 | +"This document explains how the Python GDB extension, ``python-gdb.py``, can " |
| 27 | +"be used with the GDB debugger to debug CPython extensions and the CPython " |
| 28 | +"interpreter itself." |
| 29 | +msgstr "" |
| 30 | + |
| 31 | +#: ../../howto/gdb_helpers.rst:13 |
| 32 | +msgid "" |
| 33 | +"When debugging low-level problems such as crashes or deadlocks, a low-level " |
| 34 | +"debugger, such as GDB, is useful to diagnose and correct the issue. By " |
| 35 | +"default, GDB (or any of its front-ends) doesn't support high-level " |
| 36 | +"information specific to the CPython interpreter." |
| 37 | +msgstr "" |
| 38 | + |
| 39 | +#: ../../howto/gdb_helpers.rst:18 |
| 40 | +msgid "" |
| 41 | +"The ``python-gdb.py`` extension adds CPython interpreter information to GDB. " |
| 42 | +"The extension helps introspect the stack of currently executing Python " |
| 43 | +"functions. Given a Python object represented by a :c:expr:`PyObject *` " |
| 44 | +"pointer, the extension surfaces the type and value of the object." |
| 45 | +msgstr "" |
| 46 | + |
| 47 | +#: ../../howto/gdb_helpers.rst:23 |
| 48 | +msgid "" |
| 49 | +"Developers who are working on CPython extensions or tinkering with parts of " |
| 50 | +"CPython that are written in C can use this document to learn how to use the " |
| 51 | +"``python-gdb.py`` extension with GDB." |
| 52 | +msgstr "" |
| 53 | + |
| 54 | +#: ../../howto/gdb_helpers.rst:29 |
| 55 | +msgid "" |
| 56 | +"This document assumes that you are familiar with the basics of GDB and the " |
| 57 | +"CPython C API. It consolidates guidance from the `devguide <https://devguide." |
| 58 | +"python.org>`_ and the `Python wiki <https://wiki.python.org/moin/" |
| 59 | +"DebuggingWithGdb>`_." |
| 60 | +msgstr "" |
| 61 | + |
| 62 | +#: ../../howto/gdb_helpers.rst:36 |
| 63 | +msgid "Prerequisites" |
| 64 | +msgstr "" |
| 65 | + |
| 66 | +#: ../../howto/gdb_helpers.rst:38 |
| 67 | +msgid "You need to have:" |
| 68 | +msgstr "" |
| 69 | + |
| 70 | +#: ../../howto/gdb_helpers.rst:40 |
| 71 | +msgid "" |
| 72 | +"GDB 7 or later. (For earlier versions of GDB, see ``Misc/gdbinit`` in the " |
| 73 | +"sources of Python 3.11 or earlier.)" |
| 74 | +msgstr "" |
| 75 | + |
| 76 | +#: ../../howto/gdb_helpers.rst:42 |
| 77 | +msgid "" |
| 78 | +"GDB-compatible debugging information for Python and any extension you are " |
| 79 | +"debugging." |
| 80 | +msgstr "" |
| 81 | + |
| 82 | +#: ../../howto/gdb_helpers.rst:44 |
| 83 | +msgid "The ``python-gdb.py`` extension." |
| 84 | +msgstr "" |
| 85 | + |
| 86 | +#: ../../howto/gdb_helpers.rst:46 |
| 87 | +msgid "" |
| 88 | +"The extension is built with Python, but might be distributed separately or " |
| 89 | +"not at all. Below, we include tips for a few common systems as examples. " |
| 90 | +"Note that even if the instructions match your system, they might be outdated." |
| 91 | +msgstr "" |
| 92 | + |
| 93 | +#: ../../howto/gdb_helpers.rst:52 |
| 94 | +msgid "Setup with Python built from source" |
| 95 | +msgstr "" |
| 96 | + |
| 97 | +#: ../../howto/gdb_helpers.rst:54 |
| 98 | +msgid "" |
| 99 | +"When you build CPython from source, debugging information should be " |
| 100 | +"available, and the build should add a ``python-gdb.py`` file to the root " |
| 101 | +"directory of your repository." |
| 102 | +msgstr "" |
| 103 | + |
| 104 | +#: ../../howto/gdb_helpers.rst:58 |
| 105 | +msgid "" |
| 106 | +"To activate support, you must add the directory containing ``python-gdb.py`` " |
| 107 | +"to GDB's \"auto-load-safe-path\". If you haven't done this, recent versions " |
| 108 | +"of GDB will print out a warning with instructions on how to do this." |
| 109 | +msgstr "" |
| 110 | + |
| 111 | +#: ../../howto/gdb_helpers.rst:65 |
| 112 | +msgid "" |
| 113 | +"If you do not see instructions for your version of GDB, put this in your " |
| 114 | +"configuration file (``~/.gdbinit`` or ``~/.config/gdb/gdbinit``)::" |
| 115 | +msgstr "" |
| 116 | + |
| 117 | +#: ../../howto/gdb_helpers.rst:70 |
| 118 | +msgid "You can also add multiple paths, separated by ``:``." |
| 119 | +msgstr "" |
| 120 | + |
| 121 | +#: ../../howto/gdb_helpers.rst:74 |
| 122 | +msgid "Setup for Python from a Linux distro" |
| 123 | +msgstr "" |
| 124 | + |
| 125 | +#: ../../howto/gdb_helpers.rst:76 |
| 126 | +msgid "" |
| 127 | +"Most Linux systems provide debug information for the system Python in a " |
| 128 | +"package called ``python-debuginfo``, ``python-dbg`` or similar. For example:" |
| 129 | +msgstr "" |
| 130 | + |
| 131 | +#: ../../howto/gdb_helpers.rst:80 |
| 132 | +msgid "Fedora:" |
| 133 | +msgstr "" |
| 134 | + |
| 135 | +#: ../../howto/gdb_helpers.rst:87 |
| 136 | +msgid "Ubuntu:" |
| 137 | +msgstr "" |
| 138 | + |
| 139 | +#: ../../howto/gdb_helpers.rst:93 |
| 140 | +msgid "" |
| 141 | +"On several recent Linux systems, GDB can download debugging symbols " |
| 142 | +"automatically using *debuginfod*. However, this will not install the " |
| 143 | +"``python-gdb.py`` extension; you generally do need to install the debug info " |
| 144 | +"package separately." |
| 145 | +msgstr "" |
| 146 | + |
| 147 | +#: ../../howto/gdb_helpers.rst:100 |
| 148 | +msgid "Using the Debug build and Development mode" |
| 149 | +msgstr "" |
| 150 | + |
| 151 | +#: ../../howto/gdb_helpers.rst:102 |
| 152 | +msgid "For easier debugging, you might want to:" |
| 153 | +msgstr "" |
| 154 | + |
| 155 | +#: ../../howto/gdb_helpers.rst:104 |
| 156 | +msgid "" |
| 157 | +"Use a :ref:`debug build <debug-build>` of Python. (When building from " |
| 158 | +"source, use ``configure --with-pydebug``. On Linux distros, install and run " |
| 159 | +"a package like ``python-debug`` or ``python-dbg``, if available.)" |
| 160 | +msgstr "" |
| 161 | + |
| 162 | +#: ../../howto/gdb_helpers.rst:107 |
| 163 | +msgid "Use the runtime :ref:`development mode <devmode>` (``-X dev``)." |
| 164 | +msgstr "" |
| 165 | + |
| 166 | +#: ../../howto/gdb_helpers.rst:109 |
| 167 | +msgid "" |
| 168 | +"Both enable extra assertions and disable some optimizations. Sometimes this " |
| 169 | +"hides the bug you are trying to find, but in most cases they make the " |
| 170 | +"process easier." |
| 171 | +msgstr "" |
| 172 | + |
| 173 | +#: ../../howto/gdb_helpers.rst:115 |
| 174 | +msgid "Using the ``python-gdb`` extension" |
| 175 | +msgstr "" |
| 176 | + |
| 177 | +#: ../../howto/gdb_helpers.rst:117 |
| 178 | +msgid "" |
| 179 | +"When the extension is loaded, it provides two main features: pretty printers " |
| 180 | +"for Python values, and additional commands." |
| 181 | +msgstr "" |
| 182 | + |
| 183 | +#: ../../howto/gdb_helpers.rst:121 |
| 184 | +msgid "Pretty-printers" |
| 185 | +msgstr "" |
| 186 | + |
| 187 | +#: ../../howto/gdb_helpers.rst:123 |
| 188 | +msgid "" |
| 189 | +"This is what a GDB backtrace looks like (truncated) when this extension is " |
| 190 | +"enabled::" |
| 191 | +msgstr "" |
| 192 | + |
| 193 | +#: ../../howto/gdb_helpers.rst:142 |
| 194 | +msgid "" |
| 195 | +"Notice how the dictionary argument to ``PyDict_GetItemString`` is displayed " |
| 196 | +"as its ``repr()``, rather than an opaque ``PyObject *`` pointer." |
| 197 | +msgstr "" |
| 198 | + |
| 199 | +#: ../../howto/gdb_helpers.rst:145 |
| 200 | +msgid "" |
| 201 | +"The extension works by supplying a custom printing routine for values of " |
| 202 | +"type ``PyObject *``. If you need to access lower-level details of an " |
| 203 | +"object, then cast the value to a pointer of the appropriate type. For " |
| 204 | +"example::" |
| 205 | +msgstr "" |
| 206 | + |
| 207 | +#: ../../howto/gdb_helpers.rst:168 |
| 208 | +msgid "" |
| 209 | +"Note that the pretty-printers do not actually call ``repr()``. For basic " |
| 210 | +"types, they try to match its result closely." |
| 211 | +msgstr "" |
| 212 | + |
| 213 | +#: ../../howto/gdb_helpers.rst:171 |
| 214 | +msgid "" |
| 215 | +"An area that can be confusing is that the custom printer for some types look " |
| 216 | +"a lot like GDB's built-in printer for standard types. For example, the " |
| 217 | +"pretty-printer for a Python ``int`` (:c:expr:`PyLongObject *`) gives a " |
| 218 | +"representation that is not distinguishable from one of a regular machine-" |
| 219 | +"level integer::" |
| 220 | +msgstr "" |
| 221 | + |
| 222 | +#: ../../howto/gdb_helpers.rst:183 |
| 223 | +msgid "" |
| 224 | +"The internal structure can be revealed with a cast to :c:expr:`PyLongObject " |
| 225 | +"*`:" |
| 226 | +msgstr "" |
| 227 | + |
| 228 | +#: ../../howto/gdb_helpers.rst:185 |
| 229 | +msgid "" |
| 230 | +"(gdb) p *(PyLongObject*)some_python_integer $5 = {ob_base = {ob_base = " |
| 231 | +"{ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1}, ob_digit = {42}}" |
| 232 | +msgstr "" |
| 233 | + |
| 234 | +#: ../../howto/gdb_helpers.rst:189 |
| 235 | +msgid "" |
| 236 | +"A similar confusion can arise with the ``str`` type, where the output looks " |
| 237 | +"a lot like gdb's built-in printer for ``char *``::" |
| 238 | +msgstr "" |
| 239 | + |
| 240 | +#: ../../howto/gdb_helpers.rst:195 |
| 241 | +msgid "" |
| 242 | +"The pretty-printer for ``str`` instances defaults to using single-quotes (as " |
| 243 | +"does Python's ``repr`` for strings) whereas the standard printer for ``char " |
| 244 | +"*`` values uses double-quotes and contains a hexadecimal address::" |
| 245 | +msgstr "" |
| 246 | + |
| 247 | +#: ../../howto/gdb_helpers.rst:202 |
| 248 | +msgid "" |
| 249 | +"Again, the implementation details can be revealed with a cast to :c:expr:" |
| 250 | +"`PyUnicodeObject *`::" |
| 251 | +msgstr "" |
| 252 | + |
| 253 | +#: ../../howto/gdb_helpers.rst:210 |
| 254 | +msgid "``py-list``" |
| 255 | +msgstr "" |
| 256 | + |
| 257 | +#: ../../howto/gdb_helpers.rst:212 |
| 258 | +msgid "" |
| 259 | +"The extension adds a ``py-list`` command, which lists the Python source code " |
| 260 | +"(if any) for the current frame in the selected thread. The current line is " |
| 261 | +"marked with a \">\"::" |
| 262 | +msgstr "" |
| 263 | + |
| 264 | +#: ../../howto/gdb_helpers.rst:229 |
| 265 | +msgid "" |
| 266 | +"Use ``py-list START`` to list at a different line number within the Python " |
| 267 | +"source, and ``py-list START,END`` to list a specific range of lines within " |
| 268 | +"the Python source." |
| 269 | +msgstr "" |
| 270 | + |
| 271 | +#: ../../howto/gdb_helpers.rst:234 |
| 272 | +msgid "``py-up`` and ``py-down``" |
| 273 | +msgstr "" |
| 274 | + |
| 275 | +#: ../../howto/gdb_helpers.rst:236 |
| 276 | +msgid "" |
| 277 | +"The ``py-up`` and ``py-down`` commands are analogous to GDB's regular ``up`` " |
| 278 | +"and ``down`` commands, but try to move at the level of CPython frames, " |
| 279 | +"rather than C frames." |
| 280 | +msgstr "" |
| 281 | + |
| 282 | +#: ../../howto/gdb_helpers.rst:240 |
| 283 | +msgid "" |
| 284 | +"GDB is not always able to read the relevant frame information, depending on " |
| 285 | +"the optimization level with which CPython was compiled. Internally, the " |
| 286 | +"commands look for C frames that are executing the default frame evaluation " |
| 287 | +"function (that is, the core bytecode interpreter loop within CPython) and " |
| 288 | +"look up the value of the related ``PyFrameObject *``." |
| 289 | +msgstr "" |
| 290 | + |
| 291 | +#: ../../howto/gdb_helpers.rst:246 |
| 292 | +msgid "They emit the frame number (at the C level) within the thread." |
| 293 | +msgstr "" |
| 294 | + |
| 295 | +#: ../../howto/gdb_helpers.rst:248 ../../howto/gdb_helpers.rst:320 |
| 296 | +msgid "For example::" |
| 297 | +msgstr "" |
| 298 | + |
| 299 | +#: ../../howto/gdb_helpers.rst:261 |
| 300 | +msgid "so we're at the top of the Python stack." |
| 301 | +msgstr "" |
| 302 | + |
| 303 | +#: ../../howto/gdb_helpers.rst:263 |
| 304 | +msgid "" |
| 305 | +"The frame numbers correspond to those displayed by GDB's standard " |
| 306 | +"``backtrace`` command. The command skips C frames which are not executing " |
| 307 | +"Python code." |
| 308 | +msgstr "" |
| 309 | + |
| 310 | +#: ../../howto/gdb_helpers.rst:267 |
| 311 | +msgid "Going back down::" |
| 312 | +msgstr "" |
| 313 | + |
| 314 | +#: ../../howto/gdb_helpers.rst:289 |
| 315 | +msgid "and we're at the bottom of the Python stack." |
| 316 | +msgstr "" |
| 317 | + |
| 318 | +#: ../../howto/gdb_helpers.rst:291 |
| 319 | +msgid "" |
| 320 | +"Note that in Python 3.12 and newer, the same C stack frame can be used for " |
| 321 | +"multiple Python stack frames. This means that ``py-up`` and ``py-down`` may " |
| 322 | +"move multiple Python frames at once. For example::" |
| 323 | +msgstr "" |
| 324 | + |
| 325 | +#: ../../howto/gdb_helpers.rst:315 |
| 326 | +msgid "``py-bt``" |
| 327 | +msgstr "" |
| 328 | + |
| 329 | +#: ../../howto/gdb_helpers.rst:317 |
| 330 | +msgid "" |
| 331 | +"The ``py-bt`` command attempts to display a Python-level backtrace of the " |
| 332 | +"current thread." |
| 333 | +msgstr "" |
| 334 | + |
| 335 | +#: ../../howto/gdb_helpers.rst:336 |
| 336 | +msgid "" |
| 337 | +"The frame numbers correspond to those displayed by GDB's standard " |
| 338 | +"``backtrace`` command." |
| 339 | +msgstr "" |
| 340 | + |
| 341 | +#: ../../howto/gdb_helpers.rst:340 |
| 342 | +msgid "``py-print``" |
| 343 | +msgstr "" |
| 344 | + |
| 345 | +#: ../../howto/gdb_helpers.rst:342 |
| 346 | +msgid "" |
| 347 | +"The ``py-print`` command looks up a Python name and tries to print it. It " |
| 348 | +"looks in locals within the current thread, then globals, then finally " |
| 349 | +"builtins::" |
| 350 | +msgstr "" |
| 351 | + |
| 352 | +#: ../../howto/gdb_helpers.rst:356 |
| 353 | +msgid "" |
| 354 | +"If the current C frame corresponds to multiple Python frames, ``py-print`` " |
| 355 | +"only considers the first one." |
| 356 | +msgstr "" |
| 357 | + |
| 358 | +#: ../../howto/gdb_helpers.rst:360 |
| 359 | +msgid "``py-locals``" |
| 360 | +msgstr "" |
| 361 | + |
| 362 | +#: ../../howto/gdb_helpers.rst:362 |
| 363 | +msgid "" |
| 364 | +"The ``py-locals`` command looks up all Python locals within the current " |
| 365 | +"Python frame in the selected thread, and prints their representations::" |
| 366 | +msgstr "" |
| 367 | + |
| 368 | +#: ../../howto/gdb_helpers.rst:370 |
| 369 | +msgid "" |
| 370 | +"If the current C frame corresponds to multiple Python frames, locals from " |
| 371 | +"all of them will be shown::" |
| 372 | +msgstr "" |
| 373 | + |
| 374 | +#: ../../howto/gdb_helpers.rst:390 |
| 375 | +msgid "Use with GDB commands" |
| 376 | +msgstr "" |
| 377 | + |
| 378 | +#: ../../howto/gdb_helpers.rst:392 |
| 379 | +msgid "" |
| 380 | +"The extension commands complement GDB's built-in commands. For example, you " |
| 381 | +"can use a frame numbers shown by ``py-bt`` with the ``frame`` command to go " |
| 382 | +"a specific frame within the selected thread, like this::" |
| 383 | +msgstr "" |
| 384 | + |
| 385 | +#: ../../howto/gdb_helpers.rst:411 |
| 386 | +msgid "" |
| 387 | +"The ``info threads`` command will give you a list of the threads within the " |
| 388 | +"process, and you can use the ``thread`` command to select a different one::" |
| 389 | +msgstr "" |
| 390 | + |
| 391 | +#: ../../howto/gdb_helpers.rst:419 |
| 392 | +msgid "" |
| 393 | +"You can use ``thread apply all COMMAND`` or (``t a a COMMAND`` for short) to " |
| 394 | +"run a command on all threads. With ``py-bt``, this lets you see what every " |
| 395 | +"thread is doing at the Python level::" |
| 396 | +msgstr "" |
0 commit comments