[yocto] [PATCH] deprecated.bbclass: Document PNDEPRECATED variable
Joe MacDonald
joe_macdonald at mentor.com
Fri Mar 3 06:01:35 PST 2017
Based on the blacklist behaviour, recipes can be tagged as deprecated.
Such recipes will produce a warning message when included in a build but
unlike blacklisted recipes, the build will continue. Update the
documentation to support this new variable.
Signed-off-by: Joe MacDonald <joe_macdonald at mentor.com>
---
This should only be added if or when the bbclass is merged into meta/
-J.
documentation/ref-manual/ref-classes.xml | 28 ++++++++++++++++++++++++++++
documentation/ref-manual/ref-variables.xml | 28 ++++++++++++++++++++++++++++
2 files changed, 56 insertions(+)
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index f7b1126..6088b44 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -632,6 +632,34 @@
</para>
</section>
+<section id='ref-classes-deprecated'>
+ <title><filename>deprecated.bbclass</filename></title>
+
+ <para>
+ The <filename>deprecated</filename> class identifies recipes
+ that for one reason or another are being considered for removal
+ from their current layer. It may be due to persistent, known
+ issues with the package, that there are newer, more feature-rich
+ alternatives available in the same layer or that the recipe is
+ no longer needed. The recipe should provide a reason for the
+ depercation and a suggestion to consumers of the recipe as to how
+ to proceed.
+ To use this class, inherit the class globally and set
+ <link linkend='var-PNDEPRECATED'><filename>PNDEPRECATED</filename></link>
+ for each recipe you intend to deprecate.
+ Specify the <link linkend='var-PN'><filename>PN</filename></link>
+ value as a variable flag (varflag) and provide a reason, which is
+ reported, if the package is requested to be built as the value.
+ For example, if you want to deprecate a recipe called "exoticware",
+ you add the following to your <filename>local.conf</filename>
+ or distribution configuration:
+ <literallayout class='monospaced'>
+ INHERIT += "deprecated"
+ PNDEPRECATED[exoticware] = "'exoticware' is considered obsolete and has been replaced by 'standardware'. 'exoticware' may not appear in future releases."
+ </literallayout>
+ </para>
+</section>
+
<section id='ref-classes-devshell'>
<title><filename>devshell.bbclass</filename></title>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index f79cdd2..629d167 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9920,6 +9920,34 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef>
</glossentry>
+ <glossentry id='var-PNDEPRECATED'><glossterm>PNDEPRECATED</glossterm>
+ <info>
+ PNDEPRECATED[doc] = "Lists recipes that may be removed in a future release or have more actively maintained alternatives."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Lists recipes that may be removed in a future release or
+ have more actively maintained alternatives.
+ This variable works in conjunction with the
+ <link linkend='ref-classes-deprecated'><filename>deprecated</filename></link>
+ class, which the recipe must inherit globally.
+ </para>
+
+ <para>
+ To identify a recipe as deprecated, inherit the class
+ globally and use the variable in your
+ <filename>local.conf</filename> file.
+ Here is an example that will show a warning when
+ <filename>myrecipe</filename> is included in a project:
+ <literallayout class='monospaced'>
+ INHERIT += "deprecated"
+ PNDEPRECATED[myrecipe] = "Recipe is no longer actively maintained, you should consider using 'mynewrecipe' as an alternative."
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
<info>
POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."
--
1.9.1
More information about the yocto
mailing list