From nobody Sun Oct 5 23:37:50 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 98A2826772C; Mon, 28 Jul 2025 14:54:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753714477; cv=none; b=hKz6HirDB1sG5JahJj/ho1a6/B3Ot6AO0cAbS45uIzvbV5uXRVErKRynZdOTj1MLZyCK+oifuAjI0IwaVL3DN6K4ukKOS8GEAArRHfJPuSgZKPzuOhx6XqzIg/nU8B44oKT/bhaaeZ9rtKW0SpXOMw5agU3s7vqQ56rSyZsK3VY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753714477; c=relaxed/simple; bh=LcqYflMiuNR1BpY/hEp2KEpN+DgVGr4KsB6ZUt4m8+s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Vn7YQPDwrBz6ASgZyb0/euBtKLIB9Wsqc1wSVLKoIjqVjA5zgjO+NLFk7zfvgn+QCE8ZWkW8qYVjlt0ZErWONfjcQCc92/xN8GkDPH+9EdnzVwWgyjB72extsqsITr4ma0E1Cj4poANIvjTUmE23d/B8NGm8ZkoySqZM/ykQXPI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=eq24yJpo; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="eq24yJpo" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2FDB1C4CEE7; Mon, 28 Jul 2025 14:54:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1753714477; bh=LcqYflMiuNR1BpY/hEp2KEpN+DgVGr4KsB6ZUt4m8+s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=eq24yJpoEdA4ZgGZrIOuuyPJI9VpBHVGOGzHavDQxrWEyJtse04fO2UGWBqA5pJnR 3w08tkoTYqtuX5L3WFJZErHXjzFvwbz9u2mYvAVikpDNoF80vyYC/+sRl0FbmrVxf3 TN6MDodlxUVOknhgxmMXJ8UAst2vonqtam7bMGiY40OhZN1mKG6t/tefHE5fnhyULE kiTKpKzH8Aj4Z0b8CrxqBxJtuNkLtbTsW+i20LWMgfgSNKl41bRk6uv3pD2ICutOsl Wz3WbDLpTH3cYUBcnGFdWFaEr0O9dzrFF0yzQEviQGwKLP8GS5s8sSsK0GrHAfclUw Qk5t2DSsAtAfA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1ugPFK-00000000G5Q-2Z8y; Mon, 28 Jul 2025 16:54:34 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , linux-kernel@vger.kernel.org Subject: [PATCH 1/2] docs: kernel-doc: avoid script crash on ancient Python Date: Mon, 28 Jul 2025 16:54:28 +0200 Message-ID: X-Mailer: git-send-email 2.49.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" While we do need at least 3.6 for kernel-doc to work, and at least 3.7 for it to output functions and structs with parameters at the right order, let the python binary be compatible with legacy versions. The rationale is that the Kernel build nowadays calls kernel-doc with -none on some places. Better not to bail out when older versions are found. With that, potentially this will run with python 2.7 and 3.2+, according with vermin: $ vermin --no-tips -v ./scripts/kernel-doc Detecting python files.. Analyzing using 24 processes.. 2.7, 3.2 /new_devel/v4l/docs/scripts/kernel-doc Minimum required versions: 2.7, 3.2 I actually tested it with versions 2.7 and 3.4 using anaconda (version 3 < 3.4 was not available there). For both, the script didn't crash and emitted the right warning: $ conda create -n py27 python=3D2.7 $ conda activate py27 $ python ./scripts/kernel-doc --none include/media Error: Python 3.6 or later is required by kernel-doc $ conda deactivate $ conda create -n py34 python=3D3.4 $ conda activate py34 python --version Python 3.4.5 $ python ./scripts/kernel-doc --none include/media Error: Python 3.6 or later is required by kernel-doc $ conda deactivate $ python --version Python 3.13.5 $ python ./scripts/kernel-doc --none include/media (no warnings and script ran properly) Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index fc3d46ef519f..d4f9188d6a19 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -1,9 +1,19 @@ -#!/usr/bin/env python3 +#!/usr/bin/env python +# -*- coding: utf-8 -*- # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab . # -# pylint: disable=3DC0103,R0915 -# +# pylint: disable=3DC0103,R0912,R0914,R0915 + +# NOTE: While kernel-doc requires at least version 3.6 to run, the +# command line explicitly supports Python 2,7 and 3.4+. +# The rationale is that it shall fail gracefully during Kernel +# compilation with older Kernel versions. Due to that: +# - encoding line is needed here; +# - no f-strings can be used on this file. +# - the libraries that require newer versions can only be included +# after Python version is checked. + # Converted from the kernel-doc script originally written in Perl # under GPLv2, copyrighted since 1998 by the following authors: # @@ -107,9 +117,6 @@ SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 -from kdoc_files import KernelFiles # pylint: disable= =3DC0413 -from kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0413 - DESC =3D """ Read C language source or header FILEs, extract embedded documentation com= ments, and print formatted documentation to standard output. @@ -273,14 +280,22 @@ def main(): =20 python_ver =3D sys.version_info[:2] if python_ver < (3,6): - logger.warning("Python 3.6 or later is required by kernel-doc") + # Depending on Kernel configuration, kernel-doc --none is called at + # build time. As we don't want to break compilation due to the + # usage of an old Python version, return 0 here. + if args.none: + logger.error("Python 3.6 or later is required by kernel-doc. s= kipping checks") + sys.exit(0) =20 - # Return 0 here to avoid breaking compilation - sys.exit(0) + sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.= ") =20 if python_ver < (3,7): logger.warning("Python 3.7 or later is required for correct result= s") =20 + # Import kernel-doc libraries only after checking Python version + from kdoc_files import KernelFiles # pylint: disable= =3DC0415 + from kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0415 + if args.man: out_style =3D ManFormat(modulename=3Dargs.modulename) elif args.none: @@ -308,11 +323,11 @@ def main(): sys.exit(0) =20 if args.werror: - print(f"{error_count} warnings as errors") + print("%s warnings as errors" % error_count) # pylint: disable= =3DC0209 sys.exit(error_count) =20 if args.verbose: - print(f"{error_count} errors") + print("%s errors" % error_count) # pylint: disable= =3DC0209 =20 if args.none: sys.exit(0) --=20 2.49.0 From nobody Sun Oct 5 23:37:50 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id CC3D126FA5A; Mon, 28 Jul 2025 14:54:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753714477; cv=none; b=jWb4Zutm5u9A/K4fbiIUzVmkIsgw593xxwfjcIPLPPdC+i0KL9TLsv+y4/x+GKTxHRkr5krWqkb3Djt+dmWJkeo0/uurNPdAioDrGNUKQl+UbqjlYKJJW9jvUAJE8+n6oAmb6CnjYNCpgW8rUjjTZAexKdoyISeapuYrZuTJhMg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753714477; c=relaxed/simple; bh=nij+y+Cb9IleH2KdiWnocENo17uAg8rZIjz77rKHtVw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=HXDdnOTGwZLDVFEHc0pqCfwy63o1LVs9EII4nA9YStg7bYbQU2u095mLCOc/CftGu2jGtdHyCf7g1xBdkzBOwrDJqN8ch6SjAadSG829sdXRCr73KGuw7cEcjjTn/XgCwEtmA9f0w2RCzk+ACaMNwpWUekjImv/ViiBtZwnNXjI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hebo2XbC; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="hebo2XbC" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 75859C4CEF9; Mon, 28 Jul 2025 14:54:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1753714477; bh=nij+y+Cb9IleH2KdiWnocENo17uAg8rZIjz77rKHtVw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hebo2XbCIms51ZBDi0JaGbLYeTPzbuVx852oP9PI0qYoad6X76agNeJzAOFehZE6P WIOHhzSB4RKenmeKJSS46Ht+j0jk2//noOo5HCIg7muFaDFARSfk4PeavBon4IL5RS eOOx0Q3EH0xlRitkQ3BWTQlhuhAXs/LQcgdl61mJj98uUVmjfzYT2h8ujtqCkSdEY/ rQQe2qlnnRQkO4GaODdUcoX0wrPcVXUkJIglepN3i4Esz4CL9zeDb5ILPzQhMIhk/l Crj12JsAaqoFsivlEgQrFAi+h4LFHKSVO+XZWN3ySevgff6UCcLRO9HGVaBMtMdezu ZDxx9udA3V+XA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1ugPFK-00000000G5T-2db7; Mon, 28 Jul 2025 16:54:34 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , linux-kernel@vger.kernel.org, workflows@vger.kernel.org Subject: [PATCH 2/2] docs: changes: better document Python needs Date: Mon, 28 Jul 2025 16:54:29 +0200 Message-ID: X-Mailer: git-send-email 2.49.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Python is listed as an optional dependency, but this is not true, as: 1) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o; 2) kernel-doc is called during compilation when some DRM options like CONFIG_DRM_I915_WERROR are enabled; 3) allyesconfig/allmodconfig will enable both. So, better document that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/process/changes.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/Documentation/process/changes.rst b/Documentation/process/chan= ges.rst index bccfa19b45df..f6abecf6da86 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -61,7 +61,7 @@ Sphinx\ [#f1]_ 3.4.3 sphinx-build --ve= rsion GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version mkimage (optional) 2017.01 mkimage --version -Python (optional) 3.9.x python3 --version +Python 3.9.x python3 --version GNU AWK (optional) 5.1.0 gawk --version =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 @@ -154,6 +154,17 @@ Perl You will need perl 5 and the following modules: ``Getopt::Long``, ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kerne= l. =20 +Python +------ + +CONFIG_LTO_CLANG requires python 2.7 or 3.0+; some DRM config options like +CONFIG_DRM_I915_WERROR require at least Python 2.7 or 3.4+. + +The kernel-doc tool and docs build require at least 3.6, but they depend on +dict changes that happened on 3.7 to produce valid results. + +Other tools within the Kernel tree require newer versions. + BC -- =20 --=20 2.49.0