diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2022-12-06 11:43:22 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2022-12-08 10:52:00 +0000 |
commit | 3155eb565fb1758ba426ab7f5ea710004ccbeb58 (patch) | |
tree | 973f3ff2d72d435a50810e00282fce0fdace9b19 | |
parent | fb5a8ed05e8bb1aa3a73b192a6e761f706ed31c0 (diff) | |
download | poky-3155eb565fb1758ba426ab7f5ea710004ccbeb58.tar.gz |
dev-manual: update session about multiconfig
Aligning with contents from the "master" branch.
[YOCTO #14980]
(From yocto-docs rev: 4961ddc9848f6569307107c10ff132532944ccaa)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Paul Barker <paul@pbarker.dev>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.rst | 68 |
1 files changed, 31 insertions, 37 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst index 9dcafb2783..8ee386a678 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.rst +++ b/documentation/dev-manual/dev-manual-common-tasks.rst | |||
@@ -3854,7 +3854,7 @@ Setting Up and Running a Multiple Configuration Build | |||
3854 | 3854 | ||
3855 | To accomplish a multiple configuration build, you must define each | 3855 | To accomplish a multiple configuration build, you must define each |
3856 | target's configuration separately using a parallel configuration file in | 3856 | target's configuration separately using a parallel configuration file in |
3857 | the :term:`Build Directory`, and you | 3857 | the :term:`Build Directory` or configuration directory within a layer, and you |
3858 | must follow a required file hierarchy. Additionally, you must enable the | 3858 | must follow a required file hierarchy. Additionally, you must enable the |
3859 | multiple configuration builds in your ``local.conf`` file. | 3859 | multiple configuration builds in your ``local.conf`` file. |
3860 | 3860 | ||
@@ -3862,47 +3862,47 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3862 | 3862 | ||
3863 | - *Create Separate Configuration Files*: You need to create a single | 3863 | - *Create Separate Configuration Files*: You need to create a single |
3864 | configuration file for each build target (each multiconfig). | 3864 | configuration file for each build target (each multiconfig). |
3865 | Minimally, each configuration file must define the machine and the | 3865 | The configuration definitions are implementation dependent but often |
3866 | temporary directory BitBake uses for the build. Suggested practice | 3866 | each configuration file will define the machine and the |
3867 | dictates that you do not overlap the temporary directories used | 3867 | temporary directory BitBake uses for the build. Whether the same |
3868 | during the builds. However, it is possible that you can share the | 3868 | temporary directory (:term:`TMPDIR`) can be shared will depend on what is |
3869 | temporary directory | 3869 | similar and what is different between the configurations. Multiple MACHINE |
3870 | (:term:`TMPDIR`). For example, | 3870 | targets can share the same (:term:`TMPDIR`) as long as the rest of the |
3871 | consider a scenario with two different multiconfigs for the same | 3871 | configuration is the same, multiple DISTRO settings would need separate |
3872 | (:term:`TMPDIR`) directories. | ||
3873 | |||
3874 | For example, consider a scenario with two different multiconfigs for the same | ||
3872 | :term:`MACHINE`: "qemux86" built | 3875 | :term:`MACHINE`: "qemux86" built |
3873 | for two distributions such as "poky" and "poky-lsb". In this case, | 3876 | for two distributions such as "poky" and "poky-lsb". In this case, |
3874 | you might want to use the same ``TMPDIR``. | 3877 | you would need to use the different :term:`TMPDIR`. |
3875 | 3878 | ||
3876 | Here is an example showing the minimal statements needed in a | 3879 | Here is an example showing the minimal statements needed in a |
3877 | configuration file for a "qemux86" target whose temporary build | 3880 | configuration file for a "qemux86" target whose temporary build |
3878 | directory is ``tmpmultix86``: | 3881 | directory is ``tmpmultix86``:: |
3879 | :: | ||
3880 | 3882 | ||
3881 | MACHINE = "qemux86" | 3883 | MACHINE = "qemux86" |
3882 | TMPDIR = "${TOPDIR}/tmpmultix86" | 3884 | TMPDIR = "${TOPDIR}/tmpmultix86" |
3883 | 3885 | ||
3884 | The location for these multiconfig configuration files is specific. | 3886 | The location for these multiconfig configuration files is specific. |
3885 | They must reside in the current build directory in a sub-directory of | 3887 | They must reside in the current :term:`Build Directory` in a sub-directory of |
3886 | ``conf`` named ``multiconfig``. Following is an example that defines | 3888 | ``conf`` named ``multiconfig`` or within a layer's ``conf`` directory |
3889 | under a directory named ``multiconfig``. Following is an example that defines | ||
3887 | two configuration files for the "x86" and "arm" multiconfigs: | 3890 | two configuration files for the "x86" and "arm" multiconfigs: |
3888 | 3891 | ||
3889 | .. image:: figures/multiconfig_files.png | 3892 | .. image:: figures/multiconfig_files.png |
3890 | :align: center | 3893 | :align: center |
3894 | :width: 50% | ||
3891 | 3895 | ||
3892 | The reason for this required file hierarchy is because the ``BBPATH`` | 3896 | The usual :term:`BBPATH` search path is used to locate multiconfig files in |
3893 | variable is not constructed until the layers are parsed. | 3897 | a similar way to other conf files. |
3894 | Consequently, using the configuration file as a pre-configuration | ||
3895 | file is not possible unless it is located in the current working | ||
3896 | directory. | ||
3897 | 3898 | ||
3898 | - *Add the BitBake Multi-configuration Variable to the Local | 3899 | - *Add the BitBake Multi-configuration Variable to the Local |
3899 | Configuration File*: Use the | 3900 | Configuration File*: Use the |
3900 | :term:`BBMULTICONFIG` | 3901 | :term:`BBMULTICONFIG` |
3901 | variable in your ``conf/local.conf`` configuration file to specify | 3902 | variable in your ``conf/local.conf`` configuration file to specify |
3902 | each multiconfig. Continuing with the example from the previous | 3903 | each multiconfig. Continuing with the example from the previous |
3903 | figure, the ``BBMULTICONFIG`` variable needs to enable two | 3904 | figure, the :term:`BBMULTICONFIG` variable needs to enable two |
3904 | multiconfigs: "x86" and "arm" by specifying each configuration file: | 3905 | multiconfigs: "x86" and "arm" by specifying each configuration file:: |
3905 | :: | ||
3906 | 3906 | ||
3907 | BBMULTICONFIG = "x86 arm" | 3907 | BBMULTICONFIG = "x86 arm" |
3908 | 3908 | ||
@@ -3916,13 +3916,11 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3916 | with "". | 3916 | with "". |
3917 | 3917 | ||
3918 | - *Launch BitBake*: Use the following BitBake command form to launch | 3918 | - *Launch BitBake*: Use the following BitBake command form to launch |
3919 | the multiple configuration build: | 3919 | the multiple configuration build:: |
3920 | :: | ||
3921 | 3920 | ||
3922 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] | 3921 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] |
3923 | 3922 | ||
3924 | For the example in this section, the following command applies: | 3923 | For the example in this section, the following command applies:: |
3925 | :: | ||
3926 | 3924 | ||
3927 | $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base | 3925 | $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base |
3928 | 3926 | ||
@@ -3937,7 +3935,7 @@ Follow these steps to set up and execute multiple configuration builds: | |||
3937 | Support for multiple configuration builds in the Yocto Project &DISTRO; | 3935 | Support for multiple configuration builds in the Yocto Project &DISTRO; |
3938 | (&DISTRO_NAME;) Release does not include Shared State (sstate) | 3936 | (&DISTRO_NAME;) Release does not include Shared State (sstate) |
3939 | optimizations. Consequently, if a build uses the same object twice | 3937 | optimizations. Consequently, if a build uses the same object twice |
3940 | in, for example, two different ``TMPDIR`` | 3938 | in, for example, two different :term:`TMPDIR` |
3941 | directories, the build either loads from an existing sstate cache for | 3939 | directories, the build either loads from an existing sstate cache for |
3942 | that build at the start or builds the object fresh. | 3940 | that build at the start or builds the object fresh. |
3943 | 3941 | ||
@@ -3958,38 +3956,34 @@ essentially that the | |||
3958 | 3956 | ||
3959 | To enable dependencies in a multiple configuration build, you must | 3957 | To enable dependencies in a multiple configuration build, you must |
3960 | declare the dependencies in the recipe using the following statement | 3958 | declare the dependencies in the recipe using the following statement |
3961 | form: | 3959 | form:: |
3962 | :: | ||
3963 | 3960 | ||
3964 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | 3961 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" |
3965 | 3962 | ||
3966 | To better show how to use this statement, consider the example scenario | 3963 | To better show how to use this statement, consider the example scenario |
3967 | from the first paragraph of this section. The following statement needs | 3964 | from the first paragraph of this section. The following statement needs |
3968 | to be added to the recipe that builds the ``core-image-sato`` image: | 3965 | to be added to the recipe that builds the ``core-image-sato`` image:: |
3969 | :: | ||
3970 | 3966 | ||
3971 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" | 3967 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" |
3972 | 3968 | ||
3973 | In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The | 3969 | In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The |
3974 | task on which the ``do_image`` task in the recipe depends is the | 3970 | task on which the :ref:`ref-tasks-image` task in the recipe depends is the |
3975 | ``do_rootfs`` task from the ``core-image-minimal`` recipe associated | 3971 | :ref:`ref-tasks-rootfs` task from the ``core-image-minimal`` recipe associated |
3976 | with the "arm" multiconfig. | 3972 | with the "arm" multiconfig. |
3977 | 3973 | ||
3978 | Once you set up this dependency, you can build the "x86" multiconfig | 3974 | Once you set up this dependency, you can build the "x86" multiconfig |
3979 | using a BitBake command as follows: | 3975 | using a BitBake command as follows:: |
3980 | :: | ||
3981 | 3976 | ||
3982 | $ bitbake mc:x86:core-image-sato | 3977 | $ bitbake mc:x86:core-image-sato |
3983 | 3978 | ||
3984 | This command executes all the tasks needed to create the | 3979 | This command executes all the tasks needed to create the |
3985 | ``core-image-sato`` image for the "x86" multiconfig. Because of the | 3980 | ``core-image-sato`` image for the "x86" multiconfig. Because of the |
3986 | dependency, BitBake also executes through the ``do_rootfs`` task for the | 3981 | dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for the |
3987 | "arm" multiconfig build. | 3982 | "arm" multiconfig build. |
3988 | 3983 | ||
3989 | Having a recipe depend on the root filesystem of another build might not | 3984 | Having a recipe depend on the root filesystem of another build might not |
3990 | seem that useful. Consider this change to the statement in the | 3985 | seem that useful. Consider this change to the statement in the |
3991 | ``core-image-sato`` recipe: | 3986 | ``core-image-sato`` recipe:: |
3992 | :: | ||
3993 | 3987 | ||
3994 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" | 3988 | do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" |
3995 | 3989 | ||