summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/migration-guides/migration-4.0.rst10
-rw-r--r--documentation/ref-manual/classes.rst74
-rw-r--r--documentation/ref-manual/variables.rst89
-rw-r--r--documentation/sdk-manual/appendix-customizing.rst4
4 files changed, 9 insertions, 168 deletions
diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst
index 0e9e741458..c8c2b856d9 100644
--- a/documentation/migration-guides/migration-4.0.rst
+++ b/documentation/migration-guides/migration-4.0.rst
@@ -33,11 +33,11 @@ The following variables have changed their names:
33- ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS`` 33- ``BB_SETSCENE_ENFORCE_WHITELIST`` became ``BB_SETSCENE_ENFORCE_IGNORE_TASKS``
34- ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE` 34- ``CVE_CHECK_PN_WHITELIST`` became :term:`CVE_CHECK_SKIP_RECIPE`
35- ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE` 35- ``CVE_CHECK_WHITELIST`` became :term:`CVE_CHECK_IGNORE`
36- ``ICECC_USER_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` 36- ``ICECC_USER_CLASS_BL`` became ``ICECC_CLASS_DISABLE``
37- ``ICECC_SYSTEM_CLASS_BL`` became :term:`ICECC_CLASS_DISABLE` 37- ``ICECC_SYSTEM_CLASS_BL`` became ``ICECC_CLASS_DISABLE``
38- ``ICECC_USER_PACKAGE_WL`` became :term:`ICECC_RECIPE_ENABLE` 38- ``ICECC_USER_PACKAGE_WL`` became ``ICECC_RECIPE_ENABLE``
39- ``ICECC_USER_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` 39- ``ICECC_USER_PACKAGE_BL`` became ``ICECC_RECIPE_DISABLE``
40- ``ICECC_SYSTEM_PACKAGE_BL`` became :term:`ICECC_RECIPE_DISABLE` 40- ``ICECC_SYSTEM_PACKAGE_BL`` became ``ICECC_RECIPE_DISABLE``
41- ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED` 41- ``LICENSE_FLAGS_WHITELIST`` became :term:`LICENSE_FLAGS_ACCEPTED`
42- ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED` 42- ``MULTI_PROVIDER_WHITELIST`` became :term:`BB_MULTI_PROVIDER_ALLOWED`
43- ``PNBLACKLIST`` became :term:`SKIP_RECIPE` 43- ``PNBLACKLIST`` became :term:`SKIP_RECIPE`
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 7c2b4fb278..748f0395c2 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1143,80 +1143,6 @@ The :ref:`ref-classes-gzipnative` class enables the use of different native vers
1143``gzip`` and ``pigz`` rather than the versions of these tools from the 1143``gzip`` and ``pigz`` rather than the versions of these tools from the
1144build host. 1144build host.
1145 1145
1146.. _ref-classes-icecc:
1147
1148``icecc``
1149=========
1150
1151The :ref:`ref-classes-icecc` class supports
1152`Icecream <https://github.com/icecc/icecream>`__, which facilitates
1153taking compile jobs and distributing them among remote machines.
1154
1155The class stages directories with symlinks from ``gcc`` and ``g++`` to
1156``icecc``, for both native and cross compilers. Depending on each
1157configure or compile, the OpenEmbedded build system adds the directories
1158at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
1159``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
1160compilers, respectively.
1161
1162For the cross compiler, the class creates a ``tar.gz`` file that
1163contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
1164is the version of the cross-compiler used in the cross-development
1165toolchain, accordingly.
1166
1167The class handles all three different compile stages (i.e native,
1168cross-kernel and target) and creates the necessary environment
1169``tar.gz`` file to be used by the remote machines. The class also
1170supports SDK generation.
1171
1172If :term:`ICECC_PATH` is not set in your
1173``local.conf`` file, then the class tries to locate the ``icecc`` binary
1174using ``which``. If :term:`ICECC_ENV_EXEC` is set
1175in your ``local.conf`` file, the variable should point to the
1176``icecc-create-env`` script provided by the user. If you do not point to
1177a user-provided script, the build system uses the default script
1178provided by the recipe :oe_git:`icecc-create-env_0.1.bb
1179</openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`.
1180
1181.. note::
1182
1183 This script is a modified version and not the one that comes with
1184 ``icecream``.
1185
1186If you do not want the Icecream distributed compile support to apply to
1187specific recipes or classes, you can ask them to be ignored by Icecream
1188by listing the recipes and classes using the
1189:term:`ICECC_RECIPE_DISABLE` and
1190:term:`ICECC_CLASS_DISABLE` variables,
1191respectively, in your ``local.conf`` file. Doing so causes the
1192OpenEmbedded build system to handle these compilations locally.
1193
1194Additionally, you can list recipes using the
1195:term:`ICECC_RECIPE_ENABLE` variable in
1196your ``local.conf`` file to force ``icecc`` to be enabled for recipes
1197using an empty :term:`PARALLEL_MAKE` variable.
1198
1199Inheriting the :ref:`ref-classes-icecc` class changes all sstate signatures.
1200Consequently, if a development team has a dedicated build system that
1201populates :term:`SSTATE_MIRRORS` and they want to
1202reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
1203system need to either inherit the :ref:`ref-classes-icecc` class or nobody should.
1204
1205At the distribution level, you can inherit the :ref:`ref-classes-icecc` class to be
1206sure that all builders start with the same sstate signatures. After
1207inheriting the class, you can then disable the feature by setting the
1208:term:`ICECC_DISABLED` variable to "1" as follows::
1209
1210 INHERIT_DISTRO:append = " icecc"
1211 ICECC_DISABLED ??= "1"
1212
1213This practice
1214makes sure everyone is using the same signatures but also requires
1215individuals that do want to use Icecream to enable the feature
1216individually as follows in your ``local.conf`` file::
1217
1218 ICECC_DISABLED = ""
1219
1220.. _ref-classes-image: 1146.. _ref-classes-image:
1221 1147
1222``image`` 1148``image``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index a6962bb9d4..d8e6a81ea7 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9,7 +9,7 @@ system and gives an overview of their function and contents.
9 9
10:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>` 10:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>`
11:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FAKEROOT>` 11:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FAKEROOT>`
12:term:`G <GCCPIE>` :term:`H <HGDIR>` :term:`I <ICECC_CLASS_DISABLE>` 12:term:`G <GCCPIE>` :term:`H <HGDIR>` :term:`I <IMAGE_BASENAME>`
13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>` 13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P` 14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
15:term:`Q <QA_EMPTY_DIRS>` :term:`R <RANLIB>` :term:`S` :term:`T` 15:term:`Q <QA_EMPTY_DIRS>` :term:`R <RANLIB>` :term:`S` :term:`T`
@@ -2686,7 +2686,7 @@ system and gives an overview of their function and contents.
2686 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the 2686 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
2687 default value:: 2687 default value::
2688 2688
2689 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc" 2689 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory"
2690 2690
2691 Some classes are not generally applicable within the extensible SDK 2691 Some classes are not generally applicable within the extensible SDK
2692 context. You can use this variable to disable those classes. 2692 context. You can use this variable to disable those classes.
@@ -3818,91 +3818,6 @@ system and gives an overview of their function and contents.
3818 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can 3818 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
3819 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. 3819 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
3820 3820
3821 :term:`ICECC_CLASS_DISABLE`
3822 Identifies user classes that you do not want the Icecream distributed
3823 compile support to consider. This variable is used by the
3824 :ref:`ref-classes-icecc` class. You set this variable in
3825 your ``local.conf`` file.
3826
3827 When you list classes using this variable, the recipes inheriting
3828 those classes will not benefit from distributed compilation across
3829 remote hosts. Instead they will be built locally.
3830
3831 :term:`ICECC_DISABLED`
3832 Disables or enables the ``icecc`` (Icecream) function. For more
3833 information on this function and best practices for using this
3834 variable, see the ":ref:`ref-classes-icecc`"
3835 section.
3836
3837 Setting this variable to "1" in your ``local.conf`` disables the
3838 function::
3839
3840 ICECC_DISABLED ??= "1"
3841
3842 To enable the function, set the variable as follows::
3843
3844 ICECC_DISABLED = ""
3845
3846 :term:`ICECC_ENV_EXEC`
3847 Points to the ``icecc-create-env`` script that you provide. This
3848 variable is used by the :ref:`ref-classes-icecc` class. You
3849 set this variable in your ``local.conf`` file.
3850
3851 If you do not point to a script that you provide, the OpenEmbedded
3852 build system uses the default script provided by the
3853 :oe_git:`icecc-create-env_0.1.bb
3854 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`
3855 recipe, which is a modified version and not the one that comes with
3856 ``icecream``.
3857
3858 :term:`ICECC_PARALLEL_MAKE`
3859 Extra options passed to the ``make`` command during the
3860 :ref:`ref-tasks-compile` task that specify parallel
3861 compilation. This variable usually takes the form of "-j x", where x
3862 represents the maximum number of parallel threads ``make`` can run.
3863
3864 .. note::
3865
3866 The options passed affect builds on all enabled machines on the
3867 network, which are machines running the ``iceccd`` daemon.
3868
3869 If your enabled machines support multiple cores, coming up with the
3870 maximum number of parallel threads that gives you the best
3871 performance could take some experimentation since machine speed,
3872 network lag, available memory, and existing machine loads can all
3873 affect build time. Consequently, unlike the
3874 :term:`PARALLEL_MAKE` variable, there is no
3875 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
3876 performance.
3877
3878 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
3879 use it (i.e. the system does not detect and assign the number of
3880 cores as is done with :term:`PARALLEL_MAKE`).
3881
3882 :term:`ICECC_PATH`
3883 The location of the ``icecc`` binary. You can set this variable in
3884 your ``local.conf`` file. If your ``local.conf`` file does not define
3885 this variable, the :ref:`ref-classes-icecc` class attempts
3886 to define it by locating ``icecc`` using ``which``.
3887
3888 :term:`ICECC_RECIPE_DISABLE`
3889 Identifies user recipes that you do not want the Icecream distributed
3890 compile support to consider. This variable is used by the
3891 :ref:`ref-classes-icecc` class. You set this variable in
3892 your ``local.conf`` file.
3893
3894 When you list recipes using this variable, you are excluding them
3895 from distributed compilation across remote hosts. Instead they will
3896 be built locally.
3897
3898 :term:`ICECC_RECIPE_ENABLE`
3899 Identifies user recipes that use an empty
3900 :term:`PARALLEL_MAKE` variable that you want to
3901 force remote distributed compilation on using the Icecream
3902 distributed compile support. This variable is used by the
3903 :ref:`ref-classes-icecc` class. You set this variable in
3904 your ``local.conf`` file.
3905
3906 :term:`IMAGE_BASENAME` 3821 :term:`IMAGE_BASENAME`
3907 The base name of image output files. This variable defaults to the 3822 The base name of image output files. This variable defaults to the
3908 recipe name (``${``\ :term:`PN`\ ``}``). 3823 recipe name (``${``\ :term:`PN`\ ``}``).
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index 61091d83ba..e08630dce0 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -48,8 +48,8 @@ build system applies them against ``local.conf`` and ``auto.conf``:
48 :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using 48 :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using
49 :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical 49 :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical
50 method to disable classes that are problematic or unnecessary in the SDK 50 method to disable classes that are problematic or unnecessary in the SDK
51 context. The default value disables the 51 context. The default value disables the :ref:`ref-classes-buildhistory`
52 :ref:`ref-classes-buildhistory` and :ref:`ref-classes-icecc` classes. 52 class.
53 53
54Additionally, the contents of ``conf/sdk-extra.conf``, when present, are 54Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
55appended to the end of ``conf/local.conf`` within the produced SDK, 55appended to the end of ``conf/local.conf`` within the produced SDK,