Skip to content

Commit 7eb9c88

Browse files
committed
doc: mention how drgn can be used with Jupyter
Briefly mention the synergy between drgn and Jupyter, and showcase an example. Also, mention the web-based mode of Jupyter (aka Jupyter notebook), and some of its feature that drgn users might be interested in. Signed-off-by: Shung-Hsi Yu <[email protected]>
1 parent 8019b75 commit 7eb9c88

File tree

1 file changed

+56
-0
lines changed

1 file changed

+56
-0
lines changed

docs/user_guide.rst

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,62 @@ explicitly::
396396
int counter;
397397
} atomic_t
398398

399+
Jupyter
400+
^^^^^^^
401+
402+
drgn can also be use in `Jupyter <https://jupyter.org>`_ with the `IPython
403+
kernel <https://ipython.org>`_, where the former provides the follows features,
404+
similar to `Interactive Mode`_:
405+
406+
* History
407+
* Tab completion
408+
* Pretty printing of objects and types
409+
* Helpers
410+
* Saving session ``%save``
411+
* Running shell command ``!``
412+
* `and more
413+
<https://ipython.readthedocs.io/en/stable/interactive/magics.html>`_
414+
415+
It shares much of the same features as `Interactive Mode`_ plus `a few extra
416+
tricks <https://ipython.readthedocs.io/en/stable/interactive/magics.html>`_,
417+
albeit much more heavy-weight compaired to the built-in counterpart.
418+
419+
Similarly, ``str()`` is used instead of ``repr()`` to save one from having to
420+
call ``print()`` for objects and types.::
421+
422+
$ pip install ipython
423+
...
424+
425+
$ ipython
426+
IPython 8.4.0 -- An enhanced Interactive Python. Type '?' for help.
427+
428+
In [1]: import drgn
429+
In [2]: prog = drgn.Program()
430+
In [3]: !ps aux | grep bash | head -n1 # Run shell command
431+
drgn 2022 0.0 0.0 20000 10000 pts/1 Ss Aug16 0:00 /bin/bash
432+
In [4]: prog.set_pid(2022)
433+
In [5]: prog.load_default_debug_info()
434+
In [6]: %save session.py # Save the session inside a .py file
435+
The following commands were written to file `session.py`:
436+
...
437+
In [7]: exit
438+
439+
$ ipython
440+
IPython 8.4.0 -- An enhanced Interactive Python. Type '?' for help.
441+
442+
In [1]: %run -i drgn_session.py # Re-execute all previous statements
443+
In [2]: prog['main']
444+
Out[2]: (int (int argc, char **argv, char **env))<absent>
445+
446+
For a fully-fledges Jupyter experience, it is recommended to use `Jupyter
447+
notebook
448+
<https://jupyter.org/try-jupyter/retro/notebooks/?path=notebooks/Intro.ipynb>`_,
449+
which is a web-based interactive programming interface that supports richer
450+
formats such as `Markdown
451+
<https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html>`_
452+
and can be `easily shared
453+
<https://github.blog/2015-05-07-github-jupyter-notebooks-3/>`_.
454+
399455
Next Steps
400456
----------
401457

0 commit comments

Comments
 (0)