[PATCH v2 0/2] gendwarfksyms: Document build dependencies

[PATCH v2 0/2] gendwarfksyms: Document build dependencies

[Jihan LIN via B4 Relay]

Hi,

I found there is no documentation for build dependencies in gendwarfksyms
while digging into Rust drivers. Though Yuli added libdw-dev to the build
dependencies for packaging [1], it seems that there is no documentation
about it.

This series documents the build dependencies of gendwarfksyms, adds a few
examples for installing these dependencies on some distributions and
introduces indentation style cleanup as suggested.

[1]: https://lore.kernel.org/all/79C925DCE2E963FF+20250422104927.144252-1-wangyuli@uniontech.com/

Signed-off-by: Jihan LIN <linjh22s@gmail.com>
---
Changes in v2:
- Fix style for section 'Dependencies'.
- Introduce a new patch to clean up indentation in gendwarfksyms.rst.
- Link to v1: https://lore.kernel.org/r/20260108-documents_gendwarfksyms-v1-1-52b1f9c38c70@gmail.com

---
Jihan LIN (2):
      Documentation/kbuild: Document gendwarfksyms build dependencies
      Documentation/kbuild: gendwarfksyms: Style cleanup

 Documentation/kbuild/gendwarfksyms.rst | 123 +++++++++++++++++++--------------
 1 file changed, 73 insertions(+), 50 deletions(-)
---
base-commit: b71e635feefc852405b14620a7fc58c4c80c0f73
change-id: 20260105-documents_gendwarfksyms-9f88e4a7ad2f

Best regards,
-- 
Jihan LIN <linjh22s@gmail.com>

[PATCH v2 1/2] Documentation/kbuild: Document gendwarfksyms build dependencies

[Jihan LIN via B4 Relay]

From: Jihan LIN <linjh22s@gmail.com>

Although dependencies for gendwarfksyms were recently added to the
packaging rules [1-2], the corresponding documentation was missing.

Document the required build dependencies for gendwarfksyms, and
include a few examples for installing these dependencies on some
distributions.

[1] commit 657f96cb7c06 ("kbuild: deb-pkg: Add libdw-dev:native to
Build-Depends-Arch")
[2] commit 5bd6bdd0f76e ("kbuild: rpm-pkg: Add (elfutils-devel or
libdw-devel) to BuildRequires")
Signed-off-by: Jihan LIN <linjh22s@gmail.com>
---
 Documentation/kbuild/gendwarfksyms.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
index ed366250a54eac3a72c2f529da94a9e803704ae4..0e153d13b052da6edcf65950739730c123cd49db 100644
--- a/Documentation/kbuild/gendwarfksyms.rst
+++ b/Documentation/kbuild/gendwarfksyms.rst
@@ -14,6 +14,29 @@ selected, **gendwarfksyms** is used instead to calculate symbol versions
 from the DWARF debugging information, which contains the necessary
 details about the final module ABI.
 
+Dependencies
+------------
+
+libelf, libdw and zlib are dependencies of gendwarfksyms.
+
+Here are a few examples for installing these dependencies:
+
+* Arch Linux and derivatives::
+
+	sudo pacman --needed -S zlib libelf
+
+* Debian, Ubuntu, and derivatives::
+
+	sudo apt install libelf-dev libdw-dev zlib1g-dev
+
+* Fedora and derivatives::
+
+	sudo dnf install elfutils-libelf-devel elfutils-devel zlib-devel
+
+* openSUSE and derivatives::
+
+	sudo zypper install libelf-devel libdw-devel zlib-devel
+
 Usage
 -----
 

-- 
2.51.0

[PATCH v2 2/2] Documentation/kbuild: gendwarfksyms: Style cleanup

[Jihan LIN via B4 Relay]

From: Jihan LIN <linjh22s@gmail.com>

The indentation in gendwarfksyms.rst currently uses a mix of tabs and
spaces.
Convert all indentation to tabs, and match the usage output and code
examples with theirs references.

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Jihan LIN <linjh22s@gmail.com>
---
 Documentation/kbuild/gendwarfksyms.rst | 100 ++++++++++++++++-----------------
 1 file changed, 50 insertions(+), 50 deletions(-)

diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
index 0e153d13b052da6edcf65950739730c123cd49db..fea8e87e14c62f579d320da5c2bfe139d50cd5a6 100644
--- a/Documentation/kbuild/gendwarfksyms.rst
+++ b/Documentation/kbuild/gendwarfksyms.rst
@@ -43,17 +43,17 @@ Usage
 gendwarfksyms accepts a list of object files on the command line, and a
 list of symbol names (one per line) in standard input::
 
-        Usage: gendwarfksyms [options] elf-object-file ... < symbol-list
+	Usage: gendwarfksyms [options] elf-object-file ... < symbol-list
 
-        Options:
-          -d, --debug          Print debugging information
-              --dump-dies      Dump DWARF DIE contents
-              --dump-die-map   Print debugging information about die_map changes
-              --dump-types     Dump type strings
-              --dump-versions  Dump expanded type strings used for symbol versions
-          -s, --stable         Support kABI stability features
-          -T, --symtypes file  Write a symtypes file
-          -h, --help           Print this message
+	Options:
+	  -d, --debug          Print debugging information
+	      --dump-dies      Dump DWARF DIE contents
+	      --dump-die-map   Print debugging information about die_map changes
+	      --dump-types     Dump type strings
+	      --dump-versions  Dump expanded type strings used for symbol versions
+	  -s, --stable         Support kABI stability features
+	  -T, --symtypes file  Write a symtypes file
+	  -h, --help           Print this message
 
 
 Type information availability
@@ -69,9 +69,9 @@ TU where symbols are actually exported, gendwarfksyms adds a pointer
 to exported symbols in the `EXPORT_SYMBOL()` macro using the following
 macro::
 
-        #define __GENDWARFKSYMS_EXPORT(sym)                             \
-                static typeof(sym) *__gendwarfksyms_ptr_##sym __used    \
-                        __section(".discard.gendwarfksyms") = &sym;
+	#define __GENDWARFKSYMS_EXPORT(sym)				\
+		static typeof(sym) *__gendwarfksyms_ptr_##sym __used	\
+			__section(".discard.gendwarfksyms") = &sym;
 
 
 When a symbol pointer is found in DWARF, gendwarfksyms can use its
@@ -94,14 +94,14 @@ either a type reference or a symbol name. Type references have a
 one-letter prefix followed by "#" and the name of the type. Four
 reference types are supported::
 
-        e#<type> = enum
-        s#<type> = struct
-        t#<type> = typedef
-        u#<type> = union
+	e#<type> = enum
+	s#<type> = struct
+	t#<type> = typedef
+	u#<type> = union
 
 Type names with spaces in them are wrapped in single quotes, e.g.::
 
-        s#'core::result::Result<u8, core::num::error::ParseIntError>'
+	s#'core::result::Result<u8, core::num::error::ParseIntError>'
 
 The rest of the line contains a type string. Unlike with genksyms that
 produces C-style type strings, gendwarfksyms uses the same simple parsed
@@ -151,8 +151,8 @@ the rules. The fields are as follows:
 The following helper macros, for example, can be used to specify rules
 in the source code::
 
-	#define ___KABI_RULE(hint, target, value)			    \
-		static const char __PASTE(__gendwarfksyms_rule_,	     \
+	#define ___KABI_RULE(hint, target, value)                            \
+		static const char __PASTE(__gendwarfksyms_rule_,             \
 					  __COUNTER__)[] __used __aligned(1) \
 			__section(".discard.gendwarfksyms.kabi_rules") =     \
 				"1\0" #hint "\0" target "\0" value
@@ -273,18 +273,18 @@ The rule fields are expected to be as follows:
 
 Using the `__KABI_RULE` macro, this rule can be defined as::
 
-        #define KABI_BYTE_SIZE(fqn, value) \
-                __KABI_RULE(byte_size, fqn, value)
+	#define KABI_BYTE_SIZE(fqn, value) \
+		__KABI_RULE(byte_size, fqn, value)
 
 Example usage::
 
 	struct s {
-                /* Unchanged original members */
+		/* Unchanged original members */
 		unsigned long a;
-                void *p;
+		void *p;
 
-                /* Appended new members */
-                KABI_IGNORE(0, unsigned long n);
+		/* Appended new members */
+		KABI_IGNORE(0, unsigned long n);
 	};
 
 	KABI_BYTE_SIZE(s, 16);
@@ -353,21 +353,21 @@ reserved member needs a unique name, but as the actual purpose is usually
 not known at the time the space is reserved, for convenience, names that
 start with `__kabi_` are left out when calculating symbol versions::
 
-        struct s {
-                long a;
-                long __kabi_reserved_0; /* reserved for future use */
-        };
+	struct s {
+		long a;
+		long __kabi_reserved_0; /* reserved for future use */
+	};
 
 The reserved space can be taken into use by wrapping the member in a
 union, which includes the original type and the replacement member::
 
-        struct s {
-                long a;
-                union {
-                        long __kabi_reserved_0; /* original type */
-                        struct b b; /* replaced field */
-                };
-        };
+	struct s {
+		long a;
+		union {
+			long __kabi_reserved_0; /* original type */
+			struct b b; /* replaced field */
+		};
+	};
 
 If the `__kabi_` naming scheme was used when reserving space, the name
 of the first member of the union must start with `__kabi_reserved`. This
@@ -392,11 +392,11 @@ Predicting which structures will require changes during the support
 timeframe isn't always possible, in which case one might have to resort
 to placing new members into existing alignment holes::
 
-        struct s {
-                int a;
-                /* a 4-byte alignment hole */
-                unsigned long b;
-        };
+	struct s {
+		int a;
+		/* a 4-byte alignment hole */
+		unsigned long b;
+	};
 
 
 While this won't change the size of the data structure, one needs to
@@ -405,14 +405,14 @@ to reserved fields, this can be accomplished by wrapping the added
 member to a union where one of the fields has a name starting with
 `__kabi_ignored`::
 
-        struct s {
-                int a;
-                union {
-                        char __kabi_ignored_0;
-                        int n;
-                };
-                unsigned long b;
-        };
+	struct s {
+		int a;
+		union {
+			char __kabi_ignored_0;
+			int n;
+		};
+		unsigned long b;
+	};
 
 With **--stable**, both versions produce the same symbol version. The
 examples include a `KABI_IGNORE` macro to simplify the code.

-- 
2.51.0

Re: [PATCH v2 1/2] Documentation/kbuild: Document gendwarfksyms build dependencies

[Petr Pavlu]

On 1/14/26 12:47 PM, Jihan LIN via B4 Relay wrote:
> From: Jihan LIN <linjh22s@gmail.com>
> 
> Although dependencies for gendwarfksyms were recently added to the
> packaging rules [1-2], the corresponding documentation was missing.
> 
> Document the required build dependencies for gendwarfksyms, and
> include a few examples for installing these dependencies on some
> distributions.
> 
> [1] commit 657f96cb7c06 ("kbuild: deb-pkg: Add libdw-dev:native to
> Build-Depends-Arch")
> [2] commit 5bd6bdd0f76e ("kbuild: rpm-pkg: Add (elfutils-devel or
> libdw-devel) to BuildRequires")
> Signed-off-by: Jihan LIN <linjh22s@gmail.com>
> ---
>  Documentation/kbuild/gendwarfksyms.rst | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
> index ed366250a54eac3a72c2f529da94a9e803704ae4..0e153d13b052da6edcf65950739730c123cd49db 100644
> --- a/Documentation/kbuild/gendwarfksyms.rst
> +++ b/Documentation/kbuild/gendwarfksyms.rst
> @@ -14,6 +14,29 @@ selected, **gendwarfksyms** is used instead to calculate symbol versions
>  from the DWARF debugging information, which contains the necessary
>  details about the final module ABI.
>  
> +Dependencies
> +------------
> +
> +libelf, libdw and zlib are dependencies of gendwarfksyms.
> +
> +Here are a few examples for installing these dependencies:
> +
> +* Arch Linux and derivatives::
> +
> +	sudo pacman --needed -S zlib libelf
> +
> +* Debian, Ubuntu, and derivatives::
> +
> +	sudo apt install libelf-dev libdw-dev zlib1g-dev
> +
> +* Fedora and derivatives::
> +
> +	sudo dnf install elfutils-libelf-devel elfutils-devel zlib-devel
> +
> +* openSUSE and derivatives::
> +
> +	sudo zypper install libelf-devel libdw-devel zlib-devel
> +

Nit: I suggest slightly adjusting the text to something like:

"""
Gendwarfksyms depends on the libelf, libdw, and zlib libraries.

Here are a few examples of how to install these dependencies:
"""

.. and swap the items on the pacman line to 'libelf zlib' so the order
is always libelf, libdw, zlib.

Looks ok to me nonetheless, the list is consistent with similar examples
in Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst.

Reviewed-by: Petr Pavlu <petr.pavlu@suse.com>

-- 
Thanks,
Petr

Re: [PATCH v2 2/2] Documentation/kbuild: gendwarfksyms: Style cleanup

[Petr Pavlu]

On 1/14/26 12:47 PM, Jihan LIN via B4 Relay wrote:
> From: Jihan LIN <linjh22s@gmail.com>
> 
> The indentation in gendwarfksyms.rst currently uses a mix of tabs and
> spaces.
> Convert all indentation to tabs, and match the usage output and code
> examples with theirs references.
> 
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Signed-off-by: Jihan LIN <linjh22s@gmail.com>

Reviewed-by: Petr Pavlu <petr.pavlu@suse.com>

-- 
Thanks,
Petr

Re: [PATCH v2 1/2] Documentation/kbuild: Document gendwarfksyms build dependencies

[Nathan Chancellor]

On Tue, Jan 20, 2026 at 01:17:48PM +0100, Petr Pavlu wrote:
> Nit: I suggest slightly adjusting the text to something like:
> 
> """
> Gendwarfksyms depends on the libelf, libdw, and zlib libraries.
> 
> Here are a few examples of how to install these dependencies:
> """
> 
> .. and swap the items on the pacman line to 'libelf zlib' so the order
> is always libelf, libdw, zlib.

I applied the following diff to this change and applied these to
kbuild-next.

diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
index 0e153d13b052..c5e4617b4b41 100644
--- a/Documentation/kbuild/gendwarfksyms.rst
+++ b/Documentation/kbuild/gendwarfksyms.rst
@@ -17,13 +17,13 @@ details about the final module ABI.
 Dependencies
 ------------
 
-libelf, libdw and zlib are dependencies of gendwarfksyms.
+gendwarfksyms depends on the libelf, libdw, and zlib libraries.
 
-Here are a few examples for installing these dependencies:
+Here are a few examples of how to install these dependencies:
 
 * Arch Linux and derivatives::
 
-	sudo pacman --needed -S zlib libelf
+	sudo pacman --needed -S libelf zlib
 
 * Debian, Ubuntu, and derivatives::
 

Re: [PATCH v2 0/2] gendwarfksyms: Document build dependencies

[Nathan Chancellor]

On Wed, 14 Jan 2026 19:47:43 +0800, Jihan LIN wrote:
> I found there is no documentation for build dependencies in gendwarfksyms
> while digging into Rust drivers. Though Yuli added libdw-dev to the build
> dependencies for packaging [1], it seems that there is no documentation
> about it.
> 
> This series documents the build dependencies of gendwarfksyms, adds a few
> examples for installing these dependencies on some distributions and
> introduces indentation style cleanup as suggested.
> 
> [...]

Applied to

  https://git.kernel.org/pub/scm/linux/kernel/git/kbuild/linux.git kbuild-next

Thanks!

[1/2] Documentation/kbuild: Document gendwarfksyms build dependencies
      https://git.kernel.org/kbuild/c/983233ac2ef1b
[2/2] Documentation/kbuild: gendwarfksyms: Style cleanup
      https://git.kernel.org/kbuild/c/301a02d405a3a

Please look out for regression or issue reports or other follow up
comments, as they may result in the patch/series getting dropped or
reverted. Patches applied to an "unstable" branch are accepted pending
wider testing in -next and any post-commit review; they will generally
be moved to the main branch in a week if no issues are found.

Best regards,
-- 
Nathan Chancellor <nathan@kernel.org>