[gentoo-dev] [PATCH 1/1] kernel-2.eclass: Document variables, minor style clean-up

[gentoo-dev] [PATCH 1/1] kernel-2.eclass: Document variables, minor style clean-up

[Mike Pagano]

[-- Attachment #1.1.1: Type: text/plain, Size: 11744 bytes --]

Document variables in the eclass, reorder alphabetically.
Make spacing consistent in comment lines.

Bug: https://bugs.gentoo.org/833188

Signed-off-by: Mike Pagano <mpagano@gentoo.org>
---
  eclass/kernel-2.eclass | 238 +++++++++++++++++++++++++++--------------
  1 file changed, 158 insertions(+), 80 deletions(-)

diff --git a/eclass/kernel-2.eclass b/eclass/kernel-2.eclass
index f1c27a36d..352eb35d6 100644
--- a/eclass/kernel-2.eclass
+++ b/eclass/kernel-2.eclass
@@ -17,164 +17,233 @@
  # added functionality:
  # unipatch		- a flexible, singular method to extract, add and remove patches.
  
-# @ECLASS-VARIABLE: K_USEPV
+# @ECLASS-VARIABLE: CTARGET
+# @INTERNAL
+# @DESCRIPTION:
+# Utilized for 32-bit userland on ppc64.
+
+# @ECLASS-VARIABLE: CKV
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# When setting the EXTRAVERSION variable, it should
-# add PV to the end.
-# this is useful for things like wolk. IE:
-# EXTRAVERSION would be something like : -wolk-4.19-r1
+# Used as a comparison kernel version, which is used when
+# PV doesnt reflect the genuine kernel version.
+# This gets set to the portage style versioning. ie:
+# CKV=2.6.11_rc4
  
-# @ECLASS-VARIABLE:  K_NODRYRUN
+# @ECLASS-VARIABLE: EXTRAVERSION
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if this is set then patch --dry-run will not
-# be run. Certain patches will fail with this parameter
-# See bug #507656
+# The additional version appended to OKV (-gentoo/-gentoo-r1)
  
-# @ECLASS-VARIABLE:  K_NOSETEXTRAVERSION
+# @ECLASS-VARIABLE: H_SUPPORTEDARCH
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if this is set then EXTRAVERSION will not be
-# automatically set within the kernel Makefile
+# this should be a space separated list of ARCH's which
+# can be supported by the headers ebuild
  
-# @ECLASS-VARIABLE: K_NOUSENAME
+# @ECLASS-VARIABLE: K_BASE_VER
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if this is set then EXTRAVERSION will not include the
-# first part of ${PN} in EXTRAVERSION
+# for git-sources, declare the base version this patch is
+# based off of.
  
-# @ECLASS-VARIABLE: K_NOUSEPR
+# @ECLASS-VARIABLE: K_DEBLOB_AVAILABLE
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if this is set then EXTRAVERSION will not include the
-# anything based on ${PR}.
+# A value of "0" will disable all of the optional deblob
+# code. If empty, will be set to "1" if deblobbing is
+# possible. Test ONLY for "1".
  
-# @ECLASS-VARIABLE: K_PREPATCHED
+# @ECLASS-VARIABLE: K_DEBLOB_TAG
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if the patchset is prepatched (ie: pf-sources,
-# zen-sources etc) it will use PR (ie: -r5) as the
-# patchset version for and not use it as a true package
-# revision
+# This will be the version of deblob script. It's a upstream SVN tag
+# such asw -gnu or -gnu1.
  
-# @ECLASS-VARIABLE:  K_EXTRAEINFO
+# @ECLASS-VARIABLE: K_DEFCONFIG
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Allow specifying a different defconfig target.
+# If length zero, defaults to "defconfig".
+
+# @ECLASS-VARIABLE: K_EXP_GENPATCHES_PULL
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If set, we pull "experimental" regardless of the USE FLAG
+# but expect the ebuild maintainer to use K_EXP_GENPATCHES_LIST.
+
+# @ECLASS-VARIABLE: K_EXP_GENPATCHES_NOUSE
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If set, no USE flag will be provided for "experimental";
+# as a result the user cannot choose to apply those patches.
+
+# @ECLASS-VARIABLE: K_EXP_GENPATCHES_LIST
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# A list of patches to pick from "experimental" to apply when
+# the USE flag is unset and K_EXP_GENPATCHES_PULL is set.
+
+# @ECLASS-VARIABLE: K_EXTRAEINFO
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # this is a new-line seperated list of einfo displays in
  # postinst and can be used to carry additional postinst
  # messages
  
-# @ECLASS-VARIABLE:  K_EXTRAELOG
+# @ECLASS-VARIABLE: K_EXTRAELOG
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # same as K_EXTRAEINFO except using elog instead of einfo
  
-# @ECLASS-VARIABLE:  K_EXTRAEWARN
+# @ECLASS-VARIABLE: K_EXTRAEWARN
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # same as K_EXTRAEINFO except using ewarn instead of einfo
  
-# @ECLASS-VARIABLE:  K_SYMLINK
+# @ECLASS-VARIABLE: K_FROM_GIT
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# if this is set, then forcably create symlink anyway
+# If set, this variable signals that the kernel sources derives
+# from a git tree and special handling will be applied so that
+# any patches that are applied will actually apply.
  
-# @ECLASS-VARIABLE:  K_BASE_VER
+# @ECLASS-VARIABLE: K_GENPATCHES_VER
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# for git-sources, declare the base version this patch is
-# based off of.
+# The version of the genpatches tarball(s) to apply.
+# A value of "5" would apply genpatches-2.6.12-5 to
+# my-sources-2.6.12.ebuild
  
-# @ECLASS-VARIABLE:  K_DEFCONFIG
+# @ECLASS-VARIABLE: K_LONGTERM
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# Allow specifying a different defconfig target.
-# If length zero, defaults to "defconfig".
+# If set, the eclass will search for the kernel source
+# in the long term directories on the upstream servers
+# as the location has been changed by upstream
  
-# @ECLASS-VARIABLE:  K_WANT_GENPATCHES
+# @ECLASS-VARIABLE: K_NODRYRUN
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# Apply genpatches to kernel source. Provide any
-# combination of "base", "extras" or "experimental".
+# if this is set then patch --dry-run will not
+# be run. Certain patches will fail with this parameter
+# See bug #507656
  
-# @ECLASS-VARIABLE:  K_EXP_GENPATCHES_PULL
+# @ECLASS-VARIABLE: K_NOSETEXTRAVERSION
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# If set, we pull "experimental" regardless of the USE FLAG
-# but expect the ebuild maintainer to use K_EXP_GENPATCHES_LIST.
+# if this is set then EXTRAVERSION will not be
+# automatically set within the kernel Makefile
  
-# @ECLASS-VARIABLE:  K_EXP_GENPATCHES_NOUSE
+# @ECLASS-VARIABLE: K_NOUSENAME
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# If set, no USE flag will be provided for "experimental";
-# as a result the user cannot choose to apply those patches.
+# if this is set then EXTRAVERSION will not include the
+# first part of ${PN} in EXTRAVERSION
  
-# @ECLASS-VARIABLE:  K_EXP_GENPATCHES_LIST
+# @ECLASS-VARIABLE: K_NOUSEPR
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# A list of patches to pick from "experimental" to apply when
-# the USE flag is unset and K_EXP_GENPATCHES_PULL is set.
+# if this is set then EXTRAVERSION will not include the
+# anything based on ${PR}.
  
-# @ECLASS-VARIABLE:  K_FROM_GIT
+# @ECLASS-VARIABLE: K_PREDEBLOBBED
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# If set, this variable signals that the kernel sources derives
-# from a git tree and special handling will be applied so that
-# any patches that are applied will actually apply.
+# This kernel was already deblobbed elsewhere.
+# If false, either optional deblobbing will be available
+# or the license will note the inclusion of linux-firmware code.
  
-# @ECLASS-VARIABLE:  K_GENPATCHES_VER
+# @ECLASS-VARIABLE: K_PREPATCHED
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# The version of the genpatches tarball(s) to apply.
-# A value of "5" would apply genpatches-2.6.12-5 to
-# my-sources-2.6.12.ebuild
+# if the patchset is prepatched (ie: pf-sources,
+# zen-sources etc) it will use PR (ie: -r5) as the
+# patchset version for and not use it as a true package
+# revision
  
-# @ECLASS-VARIABLE:  K_SECURITY_UNSUPPORTED
+# @ECLASS-VARIABLE: K_SECURITY_UNSUPPORTED
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # If set, this kernel is unsupported by Gentoo Security
  # to the current eclass maintainer :)
  
-# @ECLASS-VARIABLE:  K_DEBLOB_AVAILABLE
+# @ECLASS-VARIABLE: K_SYMLINK
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# A value of "0" will disable all of the optional deblob
-# code. If empty, will be set to "1" if deblobbing is
-# possible. Test ONLY for "1".
+# if this is set, then forcably create symlink anyway
  
-# @ECLASS-VARIABLE:  K_DEBLOB_TAG
+# @ECLASS-VARIABLE: K_USEPV
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# This will be the version of deblob script. It's a upstream SVN tag
-# such asw -gnu or -gnu1.
+# When setting the EXTRAVERSION variable, it should
+# add PV to the end.
+# this is useful for things like wolk. IE:
+# EXTRAVERSION would be something like : -wolk-4.19-r1
  
-# @ECLASS-VARIABLE:  K_PREDEBLOBBED
+# @ECLASS-VARIABLE: K_WANT_GENPATCHES
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# This kernel was already deblobbed elsewhere.
-# If false, either optional deblobbing will be available
-# or the license will note the inclusion of linux-firmware code.
+# Apply genpatches to kernel source. Provide any
+# combination of "base", "extras" or "experimental".
  
-# @ECLASS-VARIABLE:  K_LONGTERM
+# @ECLASS-VARIABLE: KERNEL_URI
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# If set, the eclass will search for the kernel source
-# in the long term directories on the upstream servers
-# as the location has been changed by upstream
+# Upstream kernel src URI
  
-# @ECLASS-VARIABLE:  H_SUPPORTEDARCH
+# @ECLASS-VARIABLE: KV
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# this should be a space separated list of ARCH's which
-# can be supported by the headers ebuild
+# Kernel Version (2.6.0-gentoo/2.6.0-test11-gentoo-r1)
  
-# @ECLASS-VARIABLE:  UNIPATCH_LIST
+# @ECLASS-VARIABLE: KV_FULL
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# space delimetered list of patches to be applied to the kernel
+# Kernel full version
+
+# @ECLASS-VARIABLE: KV_MAJOR
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Kernel major version from <KV_MAJOR>.<KV_MINOR>.<KV_PATCH
+
+# @ECLASS-VARIABLE: KV_MINOR
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Kernel minor version from <KV_MAJOR>.<KV_MINOR>.<KV_PATCH
+
+# @ECLASS-VARIABLE: KV_PATCH
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Kernel patch version from <KV_MAJOR>.<KV_MINOR>.<KV_PATCH
+
+# @ECLASS-VARIABLE: LINUX_HOSTCFLAGS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Default cflags if not already set
+
+# @ECLASS-VARIABLE: OKV
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Original Kernel Version (2.6.0/2.6.0-test11)
+
+# @ECLASS-VARIABLE: RELEASE
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Representative of the kernel release tag (-rc3/-git3)
+
+# @ECLASS-VARIABLE: RELEASETYPE
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# The same as RELEASE but with its numerics stripped (-rc/-git)
  
-# @ECLASS-VARIABLE:  UNIPATCH_EXCLUDE
+# @ECLASS-VARIABLE: UNIPATCH_DOCS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# space delimemeted list of docs to be installed to
+# the doc dir
+
+# @ECLASS-VARIABLE: UNIPATCH_EXCLUDE
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # An addition var to support exlusion based completely
@@ -182,13 +251,22 @@
  # this should _NOT_ be used from the ebuild as this is
  # reserved for end users passing excludes from the cli
  
-# @ECLASS-VARIABLE:  UNIPATCH_DOCS
+# @ECLASS-VARIABLE: UNIPATCH_LIST
  # @DEFAULT_UNSET
  # @DESCRIPTION:
-# space delimemeted list of docs to be installed to
-# the doc dir
+# space delimetered list of patches to be applied to the kernel
+
+# @ECLASS-VARIABLE: UNIPATCH_LIST_DEFAULT
+# @INTERNAL
+# @DESCRIPTION:
+# Upstream kernel patch archive
+
+# @ECLASS-VARIABLE: UNIPATCH_LIST_GENPATCHES
+# @INTERNAL
+# @DESCRIPTION:
+# List of genpatches archives to apply to the kernel
  
-# @ECLASS-VARIABLE:  UNIPATCH_STRICTORDER
+# @ECLASS-VARIABLE: UNIPATCH_STRICTORDER
  # @DEFAULT_UNSET
  # @DESCRIPTION:
  # if this is set places patches into directories of
-- 
2.34.1

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 14179 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

Re: [gentoo-dev] [PATCH 1/1] kernel-2.eclass: Document variables, minor style clean-up

[Mike Gilbert]

On Fri, Feb 18, 2022 at 1:01 PM Mike Pagano <mpagano@gentoo.org> wrote:
>
> Document variables in the eclass, reorder alphabetically.
> Make spacing consistent in comment lines.

For review purposes, I wish you had split this into two commits: one
to reorder/reformat the existing vars, and one to add the new ones.

Anyway, I think the kernel version vars (KV_*) should be tagged with
@OUTPUT_VARIABLE.