[libvirt PATCH 00/10] A set of minor doc updates for new contributors
As a prospective contributor, whilst the documentation is generally very helpful, I found a few minor gaps and inconsistencies. I thought I would strike while the iron was hot, and attempt to make some improvements. The changes are mostly minor clarifications, and additional internal references between articles. The only new material is a guide to using clangd with the libvirt code base (since clangd has become a common programming tool, and is particularly useful for navigating unfamiliar code bases). On build hosts where gcc is the default compiler, some manual steps are necessary before clangd will work with the libvirt code, and I thought these were worth documenting. Tim Small (10): docs: Link to main docs directory from Quick Links docs: Missing "full-stop"/"period" on some bullet items docs: Link main "contributing" from programming-specific guide docs: Point to compiling guide from code contribution guide docs: Add config instructions for clangd with libvirt docs: Reword "Preparing Patches" to clarify docs: Advise running CI tests prior to submission docs: Point to mailing list archives from submitting-patches docs: Fix deprecated use of implicit meson "setup" command docs: Reword ninja invocation note to clarify build directory docs/clangd.rst | 51 +++++++++++++++++++++++++++++++++++++ docs/compiling.rst | 14 +++++----- docs/contribute.rst | 6 ++--- docs/hacking.rst | 29 ++++++++++++++++++--- docs/index.rst | 2 ++ docs/meson.build | 1 + docs/submitting-patches.rst | 5 ++++ 7 files changed, 96 insertions(+), 12 deletions(-) create mode 100644 docs/clangd.rst -- 2.39.2
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@seoss.co.uk> --- 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
Signed-off-by: Tim Small <tim@seoss.co.uk> --- docs/contribute.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 6ed5426b8a..c1d57a8584 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -25,19 +25,19 @@ to libvirt. If you have ideas for other contributions feel free to follow them. written in Python, Perl, Java, Ruby, Php, OCaml and Go. There are also higher level wrappers mapping libvirt into other object frameworks, such GLib, CIM and SNMP. For those interested in working on the core parts of libvirt, the - `contributor guidelines <hacking.html>`__ are mandatory reading + `contributor guidelines <hacking.html>`__ are mandatory reading. - **Translation**. All the libvirt modules aim to support translations where appropriate. All translation is handling outside of the normal libvirt review process, using the `Fedora instance <https://translate.fedoraproject.org/projects/libvirt/libvirt>`__ of the Weblate tool. Thus people wishing to contribute to translation should - join the Fedora translation team + join the Fedora translation team. - **Documentation**. There are docbook guides on various aspects of libvirt, particularly application development guides for the C library and Python, and a virsh command reference. There is thus scope for work by people who are familiar with using or developing against libvirt, to write further content for these guides. There is also a need for people to review existing content - for copy editing and identifying gaps in the docs + for copy editing and identifying gaps in the docs. - **Website / wiki curation**. The bulk of the website is maintained in the primary GIT repository, while the wiki site uses mediawiki. In both cases there is a need for people to both write new content and curate existing -- 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@seoss.co.uk> --- 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
The "hacking" doc details where to find the code, but not how to compile it - link to the instructions contained in `compiling.rst`. Signed-off-by: Tim Small <tim@seoss.co.uk> --- docs/hacking.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/hacking.rst b/docs/hacking.rst index 8dc9b37475..a04da9cb58 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -19,6 +19,15 @@ If you want to contribute to translations of libvirt, join the appropriate language team in Weblate. Translation updates to libvirt will be merged during the feature freeze window. +Working with the code +===================== + +In general you should base your work upon the git master branch. + +The `"Git checkout" section <compiling.html#git-checkout>`__ +of the libvirt installation instructions give an overview of the +compilation process. + Preparing patches ================= -- 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@seoss.co.uk> --- 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
Clarify that patches should apply cleanly to the master branch. Give guidance for typical bug fix process for existing releases. Signed-off-by: Tim Small <tim@seoss.co.uk> --- docs/hacking.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/hacking.rst b/docs/hacking.rst index 11cd21223a..85918c9176 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -34,8 +34,10 @@ navigate the code base etc. within most code editors (and IDEs). Preparing patches ================= -Make sure your patches apply against libvirt git. Developers -only follow git and don't care much about released versions. +Make sure your patches apply against the libvirt git master +branch. The backporting of changes to existing releases is +typically carried out by downstream users at their discretion +after code is merged into the upstream git. Run the automated tests on your code before submitting any changes. That is: -- 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@seoss.co.uk> --- 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
Suggest that new contributors should review past patch submissions for typical style, feedback etc. prior to submitting. Link to archives. Signed-off-by: Tim Small <tim@seoss.co.uk> --- docs/submitting-patches.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/submitting-patches.rst b/docs/submitting-patches.rst index 7a8743b8d0..5b857f9111 100644 --- a/docs/submitting-patches.rst +++ b/docs/submitting-patches.rst @@ -8,6 +8,11 @@ tool. All libvirt-related repositories contain a config file that tells git-publish to use the correct mailing list and subject prefix. +If you are a first-time contributor, you may wish to read some +patch submission threads from the `mailing list archive +<contact.html#mailing-lists>`__ of the mailing list from the +``.gitpublish`` file. + Alternatively, you may send patches using ``git send-email``. The usual workflow of libvirt developer is: -- 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@seoss.co.uk> --- 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
Minor rewording to clarify purpose of the -C flag in the ninja invocation, whilst retaining previous meaning. Signed-off-by: Tim Small <tim@seoss.co.uk> --- docs/compiling.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/compiling.rst b/docs/compiling.rst index c03238b114..800264d2f9 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -116,14 +116,16 @@ checked in the top level ``meson.build`` file in the ``meson_version`` field. Compiling the sources --------------------- -To build the configured project run (note that ``-C build`` is a path to the -build directory): +Compilation can be carried out by ``ninja``: :: $ ninja -C build -The ``build`` directory now contains the built binaries. +"``build``" is the path to a directory which must match a path previously given +to ``meson setup``. + +Binaries and other resulting files can be found within the build directory. Additionally you can also run the test suite: -- 2.39.2
On 7/13/23 12:59, Tim Small wrote:
As a prospective contributor, whilst the documentation is generally very helpful, I found a few minor gaps and inconsistencies. I thought I would strike while the iron was hot, and attempt to make some improvements. The changes are mostly minor clarifications, and additional internal references between articles.
The only new material is a guide to using clangd with the libvirt code base (since clangd has become a common programming tool, and is particularly useful for navigating unfamiliar code bases).
On build hosts where gcc is the default compiler, some manual steps are necessary before clangd will work with the libvirt code, and I thought these were worth documenting.
Tim Small (10): docs: Link to main docs directory from Quick Links docs: Missing "full-stop"/"period" on some bullet items docs: Link main "contributing" from programming-specific guide docs: Point to compiling guide from code contribution guide docs: Add config instructions for clangd with libvirt docs: Reword "Preparing Patches" to clarify docs: Advise running CI tests prior to submission docs: Point to mailing list archives from submitting-patches docs: Fix deprecated use of implicit meson "setup" command docs: Reword ninja invocation note to clarify build directory
docs/clangd.rst | 51 +++++++++++++++++++++++++++++++++++++ docs/compiling.rst | 14 +++++----- docs/contribute.rst | 6 ++--- docs/hacking.rst | 29 ++++++++++++++++++--- docs/index.rst | 2 ++ docs/meson.build | 1 + docs/submitting-patches.rst | 5 ++++ 7 files changed, 96 insertions(+), 12 deletions(-) create mode 100644 docs/clangd.rst
Thank you! Yeah, our docs are written by developers and it shows. Reviewed-by: Michal Privoznik <mprivozn@redhat.com> and merged. Congratulations on your first libvirt contribution. Michal
participants (2)
-
Michal Prívozník -
Tim Small