From nobody Sun Oct 5 20:17:13 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 4A457296158; Tue, 29 Jul 2025 16:44:05 +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=1753807445; cv=none; b=hq7FIL3G5NB0Op9s2nZ7NaR3is7u1rXAdxCUTR1IUNjIddrLMcc5CfUchbCm2HqIqjNKilEj02vuZL+hqfz4UtRN4LLfVqWjKUBr8wYmpbRduI79TvvcLnWwG1sURtu/J536GbuRXFbGyIVQ9SeH+Omdiz7IaWdEfKlxsn/6gXk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753807445; c=relaxed/simple; bh=TsMpcACiWzSB16cKLBwRJj3t0mcIuiGGTbXT+qc7vZo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=deHaAYNzWWKRmJlvP9dbmzS/atrSYaKF+8brRSDOQ166jt5eXuAMLsHXZVEjwSkS4GZFc15NKS64hHtiT+2AErqIsr7rC1xv7o599yhT94uCVOtHkngLNZmnYNBOyozPyZ88p63/t5vNDbIVep2TwuM1snMzA3CB+7yzg4nApxo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iQu/MNa1; 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="iQu/MNa1" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DB9B3C4CEEF; Tue, 29 Jul 2025 16:44:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1753807444; bh=TsMpcACiWzSB16cKLBwRJj3t0mcIuiGGTbXT+qc7vZo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iQu/MNa1/AGU2UynK49ZkWo/BLqXvKoM8/hFXH5zf8+gizu8vsiwakY2ukSSTeXxn s/1nvxH6aEdgHQ1L4qZR58jGG3YTOUHO56PBVWL8I1P7+9qLpu3PSulkP6PydLh0Qy SHvEOSQuazYdieysUZjbEDwMDg6eIENDxEi0mLemYb0CKycyKOPlliTAurX+OOg+OK M/3ksJzew1ZRkaPug9ADVQsjjwOj3r4gYl0OOaQ3xxS9oYWMi+7EnQEpitH83AvVDC KDik8bDoFrWJb37u3+CSbgqCJjht5vpYCVRytFAvtnGetDSE69qPFBuG/pGpNKiZ83 /4S4IWuTGL51g== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1ugnQo-00000000Liw-1Z1s; Tue, 29 Jul 2025 18:44:02 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 1/2] docs: kernel-doc: avoid script crash on ancient Python Date: Tue, 29 Jul 2025 18:43:03 +0200 Message-ID: <87d55e76b0b1391cb7a83e3e965dbddb83fa9786.1753806485.git.mchehab+huawei@kernel.org> 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 3.2 minimal requirement is due to argparse. The minimal version I could check was version 3.4 (using anaconda). Anaconda doesn't support 3.2 or 3.3 anymore, and 3.2 doesn't even compile (I tested compiling Python 3.2 on Fedora 42 and on Fedora 32 - no show). With 3.4, the script didn't crash and emitted the right warning: $ 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) Supporting 2.7 is out of scope, as it is EOL for 5 years, and changing shebang to point to "python" instead of "python3" would have a wider impact. I did some extra checks about the differences from 3.2 and 3.4, and didn't find anything that would cause troubles: grep -rE "yield from|asyncio|pathlib|async|await|enum" scripts/kernel-doc Also, it doesn't use "@" operator. So, I'm confident that it should run (producing the exit warning) since Python 3.2. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index fc3d46ef519f..d9fe2bcbd39c 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -2,8 +2,17 @@ # 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 should work with Python 3.2+ (tested with 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 +116,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 +279,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 +322,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 20:17:13 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 4A3EA295DBD; Tue, 29 Jul 2025 16:44:05 +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=1753807445; cv=none; b=qYYI5Yo0mVEHUI4xHXg8+bQMfrTZqOTFsv6B+Ggv2zKB+ZDKln9+NpfbfowRAmrrm6R474ZdHDpQOlnx13gNtg5xTPzA1Df2cVxZXFtL+YVm8Km/a9+UkHh2Vr+CGoCO0htUxrQqUOlzBcpD7ddXUEeRxMRmx0ZR24BGJN8geZk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1753807445; c=relaxed/simple; bh=lOU+N6iFtUxmqWL6eqLxeLa6+vrLLwnK+Ndej65rQCk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UDJnOAJ23N0p14UUayMTfSXv5A0M41vSveAQtrFvG+tJXZrjhbElFjipMXoc1Ph1puIPqmuExEuAqjMS6nq0I7Ph8t98YTkMuTuvlOJNalMwHyhpTh3zexTGk40q2+pWKNLvcc9gKQmlDGQbEHI+GXPvQUNMA+LUHkw74hzUsWM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=S2z2aTR0; 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="S2z2aTR0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E9469C4CEF5; Tue, 29 Jul 2025 16:44:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1753807445; bh=lOU+N6iFtUxmqWL6eqLxeLa6+vrLLwnK+Ndej65rQCk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=S2z2aTR0ykKrDlA70tWXjh22sefKXYcctAXlQbLqXv+QhgVyANlVEEb69tPCNJjaE jG+q7zpAT+3Gr2HdQE7YAHOzDfW7VPMD/4NzKMm/D9f+n3LjRbHZp0EgZkho7g9KeZ Qm7/soE9Mptjt18kwAx/jdPZ90gRkQhldAybOPMYI0yjOtKaEKO8yf69HD4nr//q+e ABEyMZ+qyyYutK6j3oMX2tH1gT0/XIcWdZx4y6KuUVc8iPk7q3wML4L/iaq/qCEcgD bePU0mD8htFGw4ieiXXLviEB/o+IJXxy77w1tSdIARlYEN+tLgvtPlR/EP2K92rARp uqJNq+iuOUpeg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1ugnQo-00000000Liz-1dmP; Tue, 29 Jul 2025 18:44:02 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, workflows@vger.kernel.org Subject: [PATCH v2 2/2] docs: changes: better document Python needs Date: Tue, 29 Jul 2025 18:43:04 +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) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig needs it due to DRM_MSM dependencies; 2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o; 3) kernel-doc is called during compilation when some DRM options like CONFIG_DRM_I915_WERROR are enabled; 4) allyesconfig/allmodconfig will enable CONFIG_* dependencies that needs it; 5) besides DRM, other subsystems seem to have logic calling *.py scripts. So, better document that and change the dependency from optional to mandatory to reflect the current needs. Signed-off-by: Mauro Carvalho Chehab Acked-by: Akira Yokosawa Acked-by: Rob Herring (Arm) --- Documentation/process/changes.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/process/changes.rst b/Documentation/process/chan= ges.rst index bccfa19b45df..4c9088e429c8 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,13 @@ 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 +------ + +Several config options require it: it is required for arm/arm64 +default configs, CONFIG_LTO_CLANG, some DRM optional configs, +the kernel-doc tool, and docs build (Sphinx), among others. + BC -- =20 --=20 2.49.0