Commit Graph

303 Commits

Author SHA1 Message Date
Jim Ingham 483ec136da Use internal_dict everywhere we refer to the python session dict in docs. 2021-02-09 17:48:47 -08:00
Jim Ingham 365b186c24 Add documentation for the extra_args parameter to breakpoint commands.
Differential Revision: https://reviews.llvm.org/D96368
2021-02-09 15:33:36 -08:00
xgupta 94fac81fcc [Branch-Rename] Fix some links
According to the [[ https://foundation.llvm.org/docs/branch-rename/ | status of branch rename ]], the master branch of the LLVM repository is removed on 28 Jan 2021.

Reviewed By: mehdi_amini

Differential Revision: https://reviews.llvm.org/D95766
2021-02-01 16:43:21 +05:30
Raphael Isemann 2939d2e1b4 [lldb][docs] Attempt to disable the generated GitHub button on the LLDB website
For unknown reasons the alabaster theme on the docs server is always generating
a GitHub link in the side bar. Beside the privacy problems of having an iframe
to some third-party service, we never configured any GitHub integration so
this button just links to the GitHub main site.

The button generation should be disabled by default, but as that's apparently
not true in the alabaster theme on the server, this patch tries working around
the issue by just explicitly turning off the GitHub integration.
2021-02-01 09:47:39 +01:00
Raphael Isemann b3c260d8fa [lldb][docs] Expand CSS fix for LLDB doc tables
Apparently the sphinx version on the server doesn't place <p> tags in the
table cells, so the previous fix from commit 7fce3b240b
didn't fix the bug for that sphinx version. Just expand the CSS workaround
to all <td> tags.
2021-01-20 10:30:00 +01:00
Raphael Isemann 3c69ff4b03 [lldb][docs] Filter out 'thisown' attribute and inheritance boilerplate
This patch implements a filter that post-processes some of the generated RST sources
of the Python API docs. I mainly want to avoid two things:

1. Filter out all the inheritance boilerplate that just keeps mentioning for
every class that it inherits from the builtin 'object'. There is no inheritance
in the SB API.

2. More importantly, removes the SWIG generated `thisown` attribute from the
public documentation. I don't think we want users to mess with that attribute
and this is probably causing more confusion than it would help anyone. It also
makes the documentation for some smaller classes more verbose than necessary.

This patch just uses the sphinx event for reading source and removes the parts
that we don't want in documentation.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94967
2021-01-20 09:07:36 +01:00
Raphael Isemann 7fce3b240b [lldb][docs] Remove -webkit-hyphens in table cells so that table widths are correct on Safari
The tables in the new LLDB documentation currently are less wide than their
contents. The reason for that seems to be the `-webkit-hyphens: auto` property
that sphinx is setting for all `p` tags. The `p` tags in the generated Python
documentation seem to trigger some Safari layout issue, so Safari is calculating
the cell width to be smaller than it should be (which ends up looking like this
{F15104344} ).

This patch just sets that property back to the browser default `manual`. Not
sure if that's the proper workaround, but I clicked around on the website with
the changed CSS and nothing looked funny (which is I believe how webdev unit
testing works).

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94991
2021-01-20 09:05:28 +01:00
Raphael Isemann 2f80995090 [lldb][docs] Update .htaccess to redirect from old SB API documentation to new one
This is mostly SEO so that the new API can take over the old API when people
search for the different SB* classes. Sadly epydoc decided to throw in a -class
prefix behind all the class file names, so we can't just overwrite the old files
with the newly generated ones.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94900
2021-01-19 18:58:43 +01:00
Raphael Isemann 3cae8b3329 [lldb][docs] Add a doc page for enums and constants
Enums and constants are currently missing in the new LLDB Python API docs.

In theory we could just let them be autogenerated like the SB API classes, but sadly the generated documentation
suffers from a bunch of problems. Most of these problems come from the way SWIG is representing enums, which is
done by translating every single enum case into its own constant. This has a bunch of nasty effects:

* Because SWIG throws away the enum types, we can't actually reference the enum type itself in the API. Also because automodapi is impossible to script, this can't be fixed in post (at least without running like sed over the output files).
* The lack of enum types also causes that every enum *case* has its own full doc page. Having a full doc page that just shows a single enum case is pointless and it really slows down sphinx.
* There is no SWIG code for the enums, so there is also no place to write documentation strings for them. Also there is no support for copying the doxygen strings (which would be in the wrong format, but better than nothing) for enums (let alone our defines), so we can't really document all this code.
* Because the enum cases are just forwards to the native lldb module (which we mock), automodapi actually takes the `Mock` docstrings and adds it to every single enum case.

I don't see any way to solve this via automodapi or SWIG. The most reasonable way to solve this is IMHO to write a simple Clang tool
that just parses our enum/constant headers and emits an *.rst file that we check in. This way we can do all the LLDB-specific enum case and constant
grouping that we need to make a readable documentation page.

As we're without any real documentation until I get around to write that tool, I wrote a doc page for the enums/constants as a stop gap measure.
Most of this is done by just grepping our enum header and then manually cleaning up all the artifacts and copying the few doc strings we have.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94959
2021-01-19 18:54:05 +01:00
Raphael Isemann a58aceffad [lldb][docs] Use 'any' as the default role in LLDB's sphinx project
sphinx processes text in backticks depending on what 'role' it has (e.g.,
`:code:\`blub\`` -> role is `code`). If no role is provided, the default role is
taken which is right now using the default value of `content`. `content` only
really makes the text cursive which isn't really useful for anything right now.

Sphinx recommends using the `any` role by default [1] as that turns text in
backticks without an explicit roles into some kind of smart reference. If we did
this in LLDB, then we could just reference SB API classes by doing `\`SBValue\``
instead of typing out the rather verbose `:py:class:`/`:py:func:`/... role
before each reference. This would be especially nice when writing the SB API
docs itself as we constantly have to reference other classes.

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94899
2021-01-18 19:08:19 +01:00
Raphael Isemann 6e75ee6b65 [lldb][docs] Use inline literals for code/paths instead of rendering it with the default role
Right now we're using the 'content' role as default which will just render
these things as cursive (which isn't really useful for code examples). It also
prevents us from assigning a more useful default role in the future.
2021-01-18 11:10:19 +01:00
Raphael Isemann e7bc6c594b Reland [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference
The build server should now have the missing dependencies.

Original summary:

Currently LLDB uses epydoc to generate the Python API reference for the website.
epydoc however is unmaintained since more than a decade and no longer works with
Python 3. Also whatever setup we had once for generating the documentation on
the website server no longer seems to work, so the current website documentation
has been stale since more than a year.

This patch replaces epydoc with sphinx and its automodapi plugin that can
generate Python API references. LLVM already uses sphinx for the rest of the
documentation, so this way we are more consistent with the rest of LLVM. The
only new dependency is the automodapi plugin for sphinx.

This patch effectively does the following things:
* Remove the epydoc code.
* Make a new dummy Python API page in our website that just calls the Sphinx
  command for generated the API documentation.
* Add a mock _lldb module that is only used when generating the Python API.
 This way we don't have to build all of LLDB to generate the API reference.

Some notes:
* The long list of skips is necessary due to boilerplate functions that SWIG
  is generating. Sadly automodapi is not really scriptable from what I can see,
  so we have to blacklist this stuff manually.
* The .gitignore change because automodapi wants a subfolder of our
  documentation directory to place generated documentation files there. The path
  is also what is used on the website, so we can't really workaround this
  (without copying the whole `docs` dir somewhere else when we build).
* We have to use environment variables to pass our build path to our sphinx
  configuration. Sphinx doesn't support passing variables onto that script.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94489
2021-01-17 12:13:01 +01:00
Raphael Isemann 9d2053f61a Revert "[lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference"
This reverts commit bab121a1b6. It seems the
docs buildbot doesn't have the required Python headers.
2021-01-15 14:07:45 +01:00
Raphael Isemann bab121a1b6 [lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference
Currently LLDB uses epydoc to generate the Python API reference for the website.
epydoc however is unmaintained since more than a decade and no longer works with
Python 3. Also whatever setup we had once for generating the documentation on
the website server no longer seems to work, so the current website documentation
has been stale since more than a year.

This patch replaces epydoc with sphinx and its automodapi plugin that can
generate Python API references. LLVM already uses sphinx for the rest of the
documentation, so this way we are more consistent with the rest of LLVM. The
only new dependency is the automodapi plugin for sphinx.

This patch effectively does the following things:
* Remove the epydoc code.
* Make a new dummy Python API page in our website that just calls the Sphinx
  command for generated the API documentation.
* Add a mock _lldb module that is only used when generating the Python API.
 This way we don't have to build all of LLDB to generate the API reference.

Some notes:
* The long list of skips is necessary due to boilerplate functions that SWIG
  is generating. Sadly automodapi is not really scriptable from what I can see,
  so we have to blacklist this stuff manually.
* The .gitignore change because automodapi wants a subfolder of our
  documentation directory to place generated documentation files there. The path
  is also what is used on the website, so we can't really workaround this
  (without copying the whole `docs` dir somewhere else when we build).
* We have to use environment variables to pass our build path to our sphinx
  configuration. Sphinx doesn't support passing variables onto that script.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94489
2021-01-15 13:26:42 +01:00
Jonas Devlieghere cb6d53ccdc [lldb] Bump the required SWIG version to 3
Bump the required SWIG version to 3. If my memory serves me well we last
bumped the required SWIG version to 2 for Python 3. At that time SWIG 3
had already been around for a while so everyone I know was already using
that.

It appears that SWIG 3 is the only version that officially supports
C++11 which we're using in the typemap. SWIG 3 was released in 2014 so I
think it's reasonable to make that the minimum required version.

https://bugs.llvm.org/show_bug.cgi?id=48685

Differential revision: https://reviews.llvm.org/D94244
2021-01-08 08:47:21 -08:00
serge-sans-paille 5e31e226b5 Remove Python2 fallback and only advertise Python3 in the doc
Differential Revision: https://www.youtube.com/watch?v=RsL0cipURA0
2020-12-17 15:40:16 +01:00
Michał Górny 25c40a4599 [lldb] [docs] Add a manpage for lldb-server
Differential Revision: https://reviews.llvm.org/D92872
2020-12-10 15:02:25 +01:00
Jan Kratochvil b9f0713f73 [lldb/Docs] Fix lldb-x86_64-fedora URL as it is still a silent bot 2020-12-10 13:52:10 +01:00
David Spickett 32541685b2 [lldb][AArch64/Linux] Show memory tagged memory regions
This extends the "memory region" command to
show tagged regions on AArch64 Linux when the MTE
extension is enabled.

(lldb) memory region the_page
[0x0000fffff7ff8000-0x0000fffff7ff9000) rw-
memory tagging: enabled

This is done by adding an optional "flags" field to
the qMemoryRegion packet. The only supported flag is
"mt" but this can be extended.

This "mt" flag is read from /proc/{pid}/smaps on Linux,
other platforms will leave out the "flags" field.

Where this "mt" flag is received "memory region" will
show that it is enabled. If it is not or the target
doesn't support memory tagging, the line is not shown.
(since majority of the time tagging will not be enabled)

Testing is added for the existing /proc/{pid}/maps
parsing and the new smaps parsing.
Minidump parsing has been updated where needed,
though it only uses maps not smaps.

Target specific tests can be run with QEMU and I have
added MTE flags to the existing helper scripts.

Reviewed By: labath

Differential Revision: https://reviews.llvm.org/D87442
2020-11-20 11:21:59 +00:00
Walter Erquinigo 21555fff4d [intel-pt][trace] Implement a "get supported trace type" packet
Depends on D89283.

The goal of this packet (jTraceGetSupportedType) is to be able to query the gdb-server for the tracing technology that can work for the current debuggeer, which can make the user experience simpler but allowing the user to simply type

  thread trace start

to start tracing the current thread without even telling the debugger to use "intel-pt", for example. Similarly, `thread trace start [args...]` would accept args beloging to the working trace type.

Also, if the user typed

  help thread trace start

We could directly show the help information of the trace type that is supported for the target, or mention instead that no tracing is supported, if that's the case.

I added some simple tests, besides, when I ran this on my machine with intel-pt support, I got

  $ process plugin packet send "jTraceSupportedType"
    packet: jTraceSupportedType
  response: {"description":"Intel Processor Trace","pluginName":"intel-pt"}

On a machine without intel-pt support, I got

  $ process plugin packet send "jTraceSupportedType"
    packet: jTraceSupportedType
  response: E00;

Reviewed By: clayborg, labath

Differential Revision: https://reviews.llvm.org/D90490
2020-11-11 10:35:58 -08:00
Pedro Gonnet 43e451f9f3 Fix gendered documentation
Changed two references to developers as "he" or "him" to the more neutral "they".

Reviewed By: JDevlieghere, sylvestre.ledru

Differential Revision: https://reviews.llvm.org/D78807
2020-10-31 12:17:19 +01:00
David Spickett f8a3b9b06c [lldb] Correct vFile:pread/pwrite packet docs
The statement that lldb-server can handle
decimal and hex numbers is misleading.
(it can only handle hex with 0x prefix)

Mentioning non decimal numbers at all
is just creating more confusion for anyone
who tries to use them with lldb-server.

Differential Revision: https://reviews.llvm.org/D89383
2020-10-27 11:47:35 +00:00
Jonas Devlieghere de6f3d1c71 [lldb] Add a page to the docs with (external) links on how to use LLDB
In a discussion with Jim last week we came to the realization that often
we get asked about things that might not be documented on the website,
but that have been pretty well explained elsewhere. In those situations
it's often easier to quickly answer the question than searching for that
presentation you gave 3 years ago if you remember at all.

This often results in us having to answer the same questions over and
over again. We could add the questions and their answer to the website,
but that means we (1) have to duplicate the work and (2) now have to
maintain it.

A more efficient solution is to add a page with external resources with
the caveat that they might be outdated. That's exactly the purpose of
this patch.

I've added a few links that came to mind, but I don't want to be the
arbiter of what should and should not be included. I'd hope that over
time the community can crowd-source the best resources.

Differential revision: https://reviews.llvm.org/D89215
2020-10-20 11:43:31 -07:00
Jason Molenda 32021eeff0 Un-indent the section on 'Writing Target Stop-Hooks in Python'
it was ending up in a code block from the previous section,
instead of being its own section.
2020-10-16 23:23:25 -07:00
David Spickett 2d1ee7cae9 [lldb] Note difference in vFile:pread/pwrite format for lldb
https://sourceware.org/gdb/current/onlinedocs/gdb/Host-I_002fO-Packets.html

States that all numbers should be hexidecimal but lldb
uses decimals in vFile:pread and vFile:pwrite.

lldb-server can accept either since it ends up using
strtoull which will detect the base being used.

Reviewed By: labath

Differential Revision: https://reviews.llvm.org/D89227
2020-10-12 15:09:49 +01:00
Jonas Devlieghere 5d501096ca [lldb] Update docs with new buildbot URLs
Buildbot got upgraded and now the (LLDB) builders have different URLs.
2020-10-09 10:57:39 -07:00
Pavel Labath 029290f1a6 [lldb/docs] Clarify python/swig version incompatibility
The problematic combo is a debug python>=3.7 && swig<4.0.

Differential Revision: https://reviews.llvm.org/D88906
2020-10-07 15:29:29 +02:00
Muhammad Omair Javaid 3dffec03b0 [LLDB] Add QEMU testing environment setup guide for SVE testing
This patch adds a HowTo document to lldb docs which gives instruction for
setting up a virtual environment based on QEMU emulator for LLDB testing.

Instruction in this document are tested on Arm and AArch64 targets but
can easily be duplicated for other targets supported by QEMU.

This helps test LLDB in absence for modern AArch64 features not released
in publicly available hardware till date.

Reviewed By: labath

Differential Revision: https://reviews.llvm.org/D82064
2020-10-06 12:35:08 +05:00
Jonas Devlieghere 128e999d63 [lldb] Add a "design" section to the documentation.
Create a "Design" section for the LLDB documentation. The goal is to
have design documents that describe how the LLDB internals work.

Currently similar pages  are mixed together under the "Development". The
existing pages describing the architecture, the reproducers, the
structured data plugins, and the SB API could be housed here. I hope
we'd see more pages being added here in the future.

Differential revision: https://reviews.llvm.org/D88516
2020-10-02 13:07:31 -07:00
Dave Lee 5d19eb542d [lldb/docs] Remove manual codesigning documentation
The `macos-setup-codesign.sh` script has been in place for over two years. If there are no known issues, it's a good time to drop the manual steps from the docs.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D88257
2020-09-29 12:50:45 -07:00
Jim Ingham 1b1d981598 Revert "Revert "Add the ability to write target stop-hooks using the ScriptInterpreter.""
This reverts commit f775fe5964.

I fixed a return type error in the original patch that was causing a test failure.
Also added a REQUIRES: python to the shell test so we'll skip this for
people who build lldb w/o Python.
Also added another test for the error printing.
2020-09-29 12:01:14 -07:00
Jonas Devlieghere 974551d37d [lldb] Add print_function import 2020-09-28 13:51:11 -07:00
Jonas Devlieghere 8b95bd3310 [lldb] Enable markdown support for documentation
This enables support for writing LLDB documentation in markdown in
addition to reStructured text. We already had documentation written in
markdown (StructuredDataPlugins and DarwinLog) which will now also be
available on the website.
2020-09-28 12:51:15 -07:00
Jonas Devlieghere f775fe5964 Revert "Add the ability to write target stop-hooks using the ScriptInterpreter."
This temporarily reverts commit b65966cff6
while Jim figures out why the test is failing on the bots.
2020-09-28 09:04:32 -07:00
Jim Ingham b65966cff6 Add the ability to write target stop-hooks using the ScriptInterpreter.
Differential Revision: https://reviews.llvm.org/D88123
2020-09-25 15:44:55 -07:00
Dave Lee 447ba60a22 [lldb/Docs] Correct LLDB_ENABLE_TESTS to LLDB_INCLUDE_TESTS
Fix references to LLDB_ENABLE_TESTS.

Differential Revision: https://reviews.llvm.org/D87345
2020-09-09 11:07:57 -07:00
Raphael Isemann 4e4a3feecd [lldb][doc] Mention python3-dev instead of python2.7-dev in build docs 2020-09-09 09:31:27 +02:00
Med Ismail Bennani 0224738c1a [lldb/interpreter] Improve REPL init file compatibility
This patch changes the command interpreter sourcing logic for the REPL
init file. Instead of looking for a arbitrary file name, it standardizes
the REPL init file name to match to following scheme:

                          `.lldbinit-<language>-repl`

This will make the naming more homogenous and the sourcing logic future-proof.

rdar://65836048

Differential Revision: https://reviews.llvm.org/D86987

Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-09-02 01:21:22 +02:00
Gongyu Deng 3cd8d7b172 [lldb] Remote disk file/directory completion for platform commands
1. Extended the gdb-remote communication related classes with disk file/directory
   completion functions;
2. Added two common completion functions RemoteDiskFiles and
   RemoteDiskDirectories based on the functions above;
3. Added completion for these commands:
   A. platform get-file <remote-file> <local-file>;
   B. platform put-file <local-file> <remote-file>;
   C. platform get-size <remote-file>;
   D. platform settings -w <remote-dir>;
   E. platform open file <remote-file>.
4. Added related tests for client and server;
5. Updated docs/lldb-platform-packets.txt.

Reviewed By: labath

Differential Revision: https://reviews.llvm.org/D85284
2020-08-24 17:55:54 +02:00
Med Ismail Bennani 868b45b5b3 [lldb/interpreter] Add REPL-specific init file
This patch adds the infrastructure to have language specific REPL init
files. It's the foundation work to a following patch that will introduce
Swift REPL init file.

When lldb is launched with the `--repl` option, it will look for a REPL
init file in the home directory and source it. This overrides the
default `~/.lldbinit`, which content might make the REPL behave
unexpectedly. If the REPL init file doesn't exists, lldb will fall back
to the default init file.

rdar://65836048

Differential Revision: https://reviews.llvm.org/D86242

Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-08-20 00:36:32 +02:00
Jonas Devlieghere c135744b1d [lldb/CMake] Separate CMake code for Lua and Python (NFC)
Separate the CMake logic for Lua and Python to clearly distinguish
between code specific to either scripting language and the code shared
by both.

What this patch does is:

 - Move Python specific code into the bindings/python subdirectory.
 - Move the Lua specific code into the bindings/lua subdirectory.
 - Add the _python suffix to Python specific functions/targets.
 - Fix a dependency issue that would check the binding instead of
   whether the scripting language is enabled.

Note that this patch also changes where the bindings are generated,
which might affect downstream projects that check them in.

Differential revision: https://reviews.llvm.org/D85708
2020-08-11 09:04:18 -07:00
Jonas Devlieghere 02c1bba670 [lldb/Docs] Remove stale bot on GreenDragon and add reproducer one
- Remove the link to the Python 3 job which no longer exists.
 - Add a link to the reproducer job.
2020-07-30 13:51:16 -07:00
Jonas Devlieghere 8c1a31d833 [lldb/Docs] Add lldb-arm-ubuntu to the list of bots 2020-07-30 13:47:21 -07:00
Adrian Prantl 9726dc4d07 Updated the list of supported platforms in LLDB to include Apple silicon. 2020-07-08 15:33:00 -07:00
Jonas Devlieghere 2bdd41b8c0 [lldb/Docs] Add more details to the issues with custom Python installs on macOS
Although this issue is not specific to macOS, Python (in)compatibility
comes up quite often and we've been linking users to this page. This
just adds more details for this particular scenario.

Differential revision: https://reviews.llvm.org/D82507
2020-06-25 10:53:30 -07:00
Konrad Kleine 4bfa43809f [lldb] fix typo in docs: withing -> within 2020-06-24 05:19:47 -04:00
Jonas Devlieghere 18e356b75d [lldb/Docs] Reword paragraph and omit 'build slave' 2020-06-15 18:25:57 -07:00
Jonas Devlieghere ac1dc1336a [Docs] Correct description of lldbinit behavior
Jim pointed out that "every time somebody has touched the documentation
on startup files they have stated that we source the application one and
then the global one, even though in actual fact we’ve never done that."

Indeed, when we read the application specific .lldbinit file, the global
one is not read. This patch updates the man page to reflect that.
2020-05-28 13:10:33 -07:00
Jonas Devlieghere b950c261d9 [lldb/Reproducers] Add top-level-target check-lldb-reproducers
This adds a new target `check-lldb-reproducers` that replaces the old
`check-lldb-repro`. The latter would only run the shell tests, while
`check-lldb-reproducers` includes the API tests as well. The new target
will be used on GreenDragon.

It's still possible to run just the shell tests with reproducers,
although now that requires crafting the lit invocation yourself. The
parameters haven't changed and are the shame for the API and shell
tests:

  --param lldb-run-with-repro=capture
  --param lldb-run-with-repro=replay

This patch also updates the reproducer documentation.
2020-05-28 10:48:16 -07:00
Jonas Devlieghere 40c4ecabc2 [lldb/Docs] Add the application speicfic lldbinit to the man page
This used to be part of the man page but got lost when we moved to
generating it with Sphinx.
2020-05-26 17:34:09 -07:00