The instructions for running single tests in the LLDB test suite used an
older directory structure from before the LLVM project became a
monorepo. This commit updates the references to these directories.
This patch updates the documentation to match recent changes and make it
more clear. More specifically, the process for installing sphinx has
changed with the transition to myst with the requirements.txt in
llvm/docs being the preferred method for installation now. In addition,
the docs-lldb-html target is never generated if swig isn't installed, so
having something expliti in the documentation section (even if it is
mentioned as a dependency of lldb itself above) probably doesn't hurt.
Bridge network means that you can get to any port on the VM,
from the host, which is great. However it is quite involved to
setup in some cases, and I've certainly messed it up in the past.
An alternative is forwarding a block of ports and using some
hidden options to lldb-server to limit what it uses. This
commit documents that and the pitfall that the port list isn't shared.
The theory also works for Arm's FVP (which inspired me to write
this up) but since QEMU is the preferred option upstream, it goes
in that document.
Along the way I fixed a link to the QEMU page that used the URL
not a relative link to the document.
Running:
$ clang-format -i $(find -regex "\./lldb/.*\.c") $(find -regex
"\./lldb/.*\.cpp") $(find -regex "\./lldb/.*\.h")
Resulted in:
1602 files changed, 25090 insertions(+), 25849 deletions(-)
(note: this includes tests which we wouldn't format, just using this as
an example)
The vast majority of which were whitespace changes. So as far as
formatting we're not deviating from llvm for any reason other than not
churning old code.
Formatting aside, the major features of lldb (single line if, early
return) are all reflected in llvm's style. We differ mainly on variable
naming (proposed to change in
https://llvm.org/docs/Proposals/VariableNames.html anyway) and use of
asserts. Which was already documented.
This is a (rough) port of architecture/varformats.html page that got
lost during the migration to RST in edb874b. I'm not sure how much of
its content is still relevant today. However, the page is pretty
extensive and seems like it's worth preserving.
Neither actually linked anywhere, but I did find a good target for the
introduction.
For the architecture side I don't see a page that would fit, so I've
just removed the sentence.
The testing page already has some page about debugging failures.
I'm not linking directly to that section because:
* The earlier sections about running single tests and such
are just as useful for debugging in general.
* The new theme has a nice sidebar on the right that makes
it really easy to find what you want once on the page.
* We'll probably add more content to the testing page later.
Adds the following:
* A note that you can use attaching to debug the right lldb-server
process, though there are drawbacks.
* A section on debugging the remote protocol.
* Reducing bugs, including reducing ptrace bugs to remove the need for
LLDB.
I've added a standlone ptrace program to the examples folder because:
* There's no better place to put it.
* Adding it to the page seems like wasting space, and would be harder to
update.
* I link to Eli Bendersky's classic blog on the subject, but we are
safer with our own example as well.
* Eli's example is for 32 bit Intel, AArch64 is more common these days.
* It's easier to show the software breakpoint steps in code than explain
it (though I still do that in the text).
* It was living on my laptop not helping anyone so I think it's good to
have it upstream for others, including future me.
We have docs about how to use lldb on other programs, this tells you how
to use lldb on ldlb and lldb-server.
Lacking any Mac experience I've not included any debugserver information
apart from stating it will be similar but not the same.
I plan for this page to include sections on debugging tests and other
things but this initial commit is purely about the two main binaries
involved.
The main way I cross build lldb is to point CMake at an existing host
build to get the native tablegen tools. This is what we had documented
before.
There is another option where you start from scratch and the host tools
are built for you. This patch documents that and explains which one to
choose.
Added another arm64 example which uses this. So the frst one is the
"automatic" build and the second is the traditional approach.
For ease of copy paste and understanding, I've kept the full command in
each section and noted the one difference between them.
Along the way I updated some of the preamble to explain the two
approaches and updated some language e.g. removing "just ...". Eveyone's
"just" is different, doubly so when cross-compiling.
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch reverts the lldb website revamp (eea8874) since the `furo` theme
that we use is not installed on the publisher bot. The prevents other
website from getting there documentation updated.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
To address https://github.com/llvm/llvm-project/issues/64616, this change
does the following:
* Links back to the "Optional Dependencies" section from the cross
compilation instructions where we talk about removing libraries.
In the reported issue, the host libXML was found by CMAke somehow and
disabling libXML fixed it, so this link should encourage users
to try as many of those options as needed.
* Removes the use of CMAKE_CROSS_COMPILING. In older CMake versions
it seems you could set this manually but now the advice is to set
CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR then let CMake figure
it out.
There is also CMAKE_SYSTEM_VERSION which the docs say you have to
set too, but I can only find examples of Windows and Android builds
using this. It might be needed to "cross" compile from one version
of AArch64 Linux to another, but I can't confirm that.
* Removes the tablegen tools paths in favour of DLLVM_NATIVE_TOOL_DIR.
This one setting deals with all build tools in llvm that must be host
versions.
* Updates the explanations of the common options and orders them
in some rough order of relevance with the "might be needed" later.
Reviewed By: JDevlieghere, bulbazord
Differential Revision: https://reviews.llvm.org/D158085
Feedback I hear regularly is that the LLDB website is hard to navigate.
This patch is an attempt to simplify things by breaking the website up
in 3 major areas: "Using LLDB", "Scripting LLDB" and "Developing LLDB".
- The majority of the "project" pages were eliminated. The projects
page was moved under "Developing LLDB". The releases page was
replaced with a link under "External links". The other pages (goals,
features and status) were pretty outdated and while they probably
made sense in the past, they don't feel all that relevant anymore
now that LLDB is an established debugger.
- "USE & EXTENSION" was renamed to "Using LLDB". Besides that, this
section remained mostly unchanged. The exception are the Python
pages which were moved under "Scripting LLDB".
- "Development" was renamed to "Developing LLDB" and now houses all the
resources for LLDB developers. The old "Design" section (which only
contained two pages) was moved back under here too.
Differential revision: https://reviews.llvm.org/D158023
SWIG 4 was released in 2019 and has been the de-facto standard for a
while now. All bots are running SWIG 4.0 or later.
This was motivated by #64279 which discovered that 662548c broke the
LLDB build with SWIG 3 on Windows.
Differential revision: https://reviews.llvm.org/D156804
Whether assertions are enabled or not is orthogonal to the build type
which could lead to surprising behavior for lldbassert. Previously, when
doing a debug build with assertions disabled, lldbassert would become a
NOOP, rather than printing an error like it does in a release build. By
definining lldbassert in terms of NDEBUG, it behaves like a regular
assert when assertions are enabled, and like a soft assert.
Differential revision: https://reviews.llvm.org/D150639
Update the documentation to reference lldbassert rather than
lldb_assert. The latter is the implementation, which shouldn't be used
directly. Instead, users should use lldbassert which is the macro that
expands to assert or lldb_assert depending on the build type.
The current doc has people just do "ninja lldb" which is
not incorrect, it does build lldb. However it does not build lldb-server.
So you can't just "lldb some-binary" and expect it to work.
I've updated the instructions to reflect that most of the time
you'll want both lldb and lldb-server.
Though there is a use case for building just lldb. I'm assuming
Mac OS (where you have debugserver) and if you only wanted to do
remote debug.
Fixes#59575
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D140385
Currently, by default LLDB runs an API test with 3 variants,
one of which, depending on platform, is `gmodules`. However,
most tests don't actually make use of any specific `gmodules`
feature since they compile a single `main.cpp` file without
imporint types from other modules.
Instead of running all tests an extra time with `-gmodules`
enabled, we plan to test `gmodules` features with dedicated
API tests that explicitly opt-into compiling with `-gmodules`.
One of the main benefits of this will be a reduction in total
API test-suite run-time (by around 1/3).
This patch adds a flag to `debug_info_categories` that indicates
whether a category is eligible to be replicated by `lldbtest`.
Keeping `gmodules` a debug-info category is desirable because
`builder.py` knows how to inject the appropriate Makefile flags
into the build command for debug-info categories already. Whereas
for non-debug-info categories we'd have to teach it how to. The
category is inferred from the test-name debug-info suffix currently.
Differential Revision: https://reviews.llvm.org/D134524
This commit adds a new page to the LLDB HTML documentation for the LLDB
fuzzers. The page primarily explains what the fuzzers are as well as how
to build them, run them and investigate and reproduce bugs.
Differential revision: https://reviews.llvm.org/D132148
Add a function to make it easier to debug a test failure caused by an
unexpected stop reason. This is similar to the assertState helper that
was added in ce825e4674.
Before:
self.assertEqual(stop_reason, lldb.eStopReasonInstrumentation)
AssertionError: 5 != 10
After:
self.assertStopReason(stop_reason, lldb.eStopReasonInstrumentation)
AssertionError: signal (5) != instrumentation (10)
Differential revision: https://reviews.llvm.org/D131083
As raised here: https://lists.llvm.org/pipermail/llvm-dev/2021-November/153881.html
Now that VS2022 is on general release, LLVM is expected to build on VS2017, VS2019 and VS2022, which is proving hazardous to maintain due to changes in behaviour including preprocessor and constexpr changes. Plus of the few developers that work with VS, many have already moved to VS2019/22.
This patch proposes to raise the minimum supported version to VS2019 (16.x) - I've made the hard limit 16.0 or later, with the soft limit VS2019 16.7 - older versions of VS2019 are "allowed" (at your own risk) via the LLVM_FORCE_USE_OLD_TOOLCHAIN cmake flag.
Differential Revision: https://reviews.llvm.org/D114639
The existing instructions for lldb on Windows can be more explicit. This adds a few details on how to install various components and the easiest way to get to a working build.
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D118425
This file contain some old reference to files those are now either renamed or replaced.
Also this .txt file didn't generate to html during the sphnix documentation build so I send its contents to resources/test.rst file.
Signed-off-by: Shivam Gupta <shivam98.tkg@gmail.com>
Reviewed By: teemperor, mgorny, JDevlieghere
Differential Revision: https://reviews.llvm.org/D108812
This patch specifies a few guidelines that our API tests should follow.
The motivations for this are twofold:
1. API tests have unexpected pitfalls that especially new contributors run into
when writing tests. To prevent the frustration of letting people figure those
pitfalls out by trial-and-error, let's just document them briefly in one place.
2. It prevents some arguing about what is the right way to write tests. I really
like to have fast and reliable API test suite, but I also don't want to be the
bogeyman that has to insist in every review that the test should be rewritten to
not launch a process for no good reason. It's much easier to just point to a
policy document.
I omitted some guidelines that I think could be controversial (e.g., the whole
"should assert message describe failure or success").
Reviewed By: shafik
Differential Revision: https://reviews.llvm.org/D101153
Debugging tests sometimes involves debugging the Python source. This adds a paragraph to
the "Debugging Test Failures" section about using `pdb`, and also describes how to run
lldb commands from pdb.
Differential Revision: https://reviews.llvm.org/D99744
