Whilst the "docs" documentation map is linked in the navigation bar, users may scroll down and lose sight of this, so also place at the bottom of the "Quick Links" section. Signed-off-by: Tim Small <tim(a)seoss.co.uk&gt; --- docs/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index d55c4bb94d..0782034e02 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,8 @@ Quick Links Read further community contributed content `Knowledge base <kbase/index.html>`__ Learn more about libvirt through knowledge base +`Documentation <docs.html>`__ + Comprehensive documentation map Blog Planet ----------- -- 2.39.2

There are two guides to contributing: `hacking.rst` is focused on code contributions, and `contributing.rst` is more general. Clarify scope of `hacking.rst` and link to the general guide in its references. Signed-off-by: Tim Small <tim(a)seoss.co.uk&gt; --- docs/hacking.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/hacking.rst b/docs/hacking.rst index 1be9daab80..8dc9b37475 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -3,7 +3,7 @@ Contributing ============ These are the basics steps you need to follow to contribute to -libvirt. +libvirt software development. Repositories and external resources =================================== @@ -75,3 +75,4 @@ you also take a look at the following documents: - `Advanced test suite usage <advanced-tests.html>`__ - `Adoption of GLib APIs <glib-adoption.html>`__ - `Committer guidelines <committer-guidelines.html>`__ +- `Contributing to libvirt <contribute.html>`__ -- 2.39.2

In build environments which use gcc as the default compiler, use of the clangd LSP server (for enhanced code editing and navigation etc.) with libvirt requires some additional configuration. Detail this and link from `hacking.rst`. Signed-off-by: Tim Small <tim(a)seoss.co.uk&gt; --- docs/clangd.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/hacking.rst | 3 +++ docs/meson.build | 1 + 3 files changed, 55 insertions(+) create mode 100644 docs/clangd.rst diff --git a/docs/clangd.rst b/docs/clangd.rst new file mode 100644 index 0000000000..93570ae178 --- /dev/null +++ b/docs/clangd.rst @@ -0,0 +1,51 @@ +========================= +Using Clangd with Libvirt +========================= + +`clangd <https://clangd.llvm.org/>`__ is an implementation of the +`language server protocol +<https://en.wikipedia.org/wiki/Language_Server_Protocol>`__ for C +and C++. + +When paired with an LSP-compatible editor or IDE (e.g. emacs, +vim, vscode), ``clangd`` can helpful when working with libvirt's +C sources e.g. navigating the code base. + +Whilst other C LSPs are available, ``clangd`` should work +correctly with the libvirt because clang is a supported compiler +for libvirt, and ``clangd`` is part of the same code base as +clang. + +If clang is the default compiler on your system, then ``clangd`` +can be used as soon as ``meson setup`` has been run. + +If gcc is your build environment's default compiler, then +additional steps are required to use ``clangd``: + +``clangd`` looks for a ``compile_commands.json`` file in the top +level directory of the project and also in the ``build/`` +subdirectory to discover which include paths, compiler flags etc. +should be used when it parses each source file. + +Meson creates a ``compile_commands.json`` in the build directory. +Meson defaults to the system's default C compiler. When the +default compiler is gcc, its ``compile_commands.json`` output +cannot be used with ``clangd`` due to differences in compiler +invocation flags when building libvirt. + +Create a separate build directory with a ``clangd`` compatible +``compile_commands.json`` as follows: + +:: + + CC=clang CXX=clang++ meson setup build-clang + +Point ``clangd`` (v12 or later) at the correct +``compile_commands.json`` by placing the following into a +``.clangd`` file in the root of the project: + +:: + + --- + CompileFlags: + CompilationDatabase: "build-clang" diff --git a/docs/hacking.rst b/docs/hacking.rst index a04da9cb58..11cd21223a 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -28,6 +28,9 @@ The `"Git checkout" section <compiling.html#git-checkout>`__ of the libvirt installation instructions give an overview of the compilation process. +Optionally, `Clangd with libvirt <clangd.html>`__ can be used to +navigate the code base etc. within most code editors (and IDEs). + Preparing patches ================= diff --git a/docs/meson.build b/docs/meson.build index 201fd4c984..70d271ec6e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,6 +32,7 @@ docs_rst_files = [ 'ci', 'ci-dashboard', 'ci-runners', + 'clangd', 'coding-style', 'committer-guidelines', 'compiling', -- 2.39.2

In the preparing patches section, note that it is possible to run CI tests via gitlab prior to submitting patches. Signed-off-by: Tim Small <tim(a)seoss.co.uk&gt; --- docs/hacking.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/hacking.rst b/docs/hacking.rst index 85918c9176..c2e79e4501 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -58,6 +58,14 @@ adding a new feature or changing the output of a program, and don't forget to update the `release notes <news.html>`__ if your changes are significant and user-visible. +To test across a variety of build platforms prior to submitting +your changes, you may create your own fork of the project on +gitlab. This will give you access to (a subset of) libvirt's +`continuous integration <ci.html>`__ test suite. + +Please note that you should still follow the instructions below, +rather than following gitlab's prompts to open a "merge request". + Submitting patches ================== -- 2.39.2

Use the explicit meson "setup" command instead of the deprecated implicit invocation. The implied setup usage generates a warning with meson version 1.0.1: WARNING: Running the setup command as `meson [options]` instead of `meson setup [options]` is ambiguous and deprecated. Additionally the implicit command is likely to be confusing to those unfamiliar with Meson - the `build` argument in `meson build` resembles an action rather than an arbitrary path. Signed-off-by: Tim Small <tim(a)seoss.co.uk&gt; --- docs/compiling.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/compiling.rst b/docs/compiling.rst index 2a740ad76e..c03238b114 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -68,7 +68,7 @@ of the build directory which will be created. :: - $ meson build [options] + $ meson setup build [options] To get the complete list of the options run the following command: @@ -83,7 +83,7 @@ normal OS vendor prefixes, use :: - $ meson build -Dsystem=true + $ meson setup build -Dsystem=true Explicitly enabling required functionality ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -99,7 +99,7 @@ libvirt project with support for the **qemu** driver use the following options: :: - $ meson build -Dsystem=true -Ddriver_qemu=enabled + $ meson setup build -Dsystem=true -Ddriver_qemu=enabled Notes: ~~~~~~ -- 2.39.2