diff options
Diffstat (limited to 'poky/documentation')
| -rw-r--r-- | poky/documentation/dev-manual/common-tasks.rst | 220 | ||||
| -rw-r--r-- | poky/documentation/kernel-dev/common.rst | 12 | ||||
| -rw-r--r-- | poky/documentation/overview-manual/concepts.rst | 4 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/classes.rst | 15 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/faq.rst | 7 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/features.rst | 43 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/structure.rst | 81 | ||||
| -rw-r--r-- | poky/documentation/ref-manual/variables.rst | 69 |
8 files changed, 254 insertions, 197 deletions
diff --git a/poky/documentation/dev-manual/common-tasks.rst b/poky/documentation/dev-manual/common-tasks.rst index b08a55331d..559709d6f3 100644 --- a/poky/documentation/dev-manual/common-tasks.rst +++ b/poky/documentation/dev-manual/common-tasks.rst @@ -653,39 +653,6 @@ For help on the BitBake layer management tool, use the following command:: $ bitbake-layers --help - NOTE: Starting bitbake server... - usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ... - - BitBake layers utility - - optional arguments: - -d, --debug Enable debug output - -q, --quiet Print only errors - -F, --force Force add without recipe parse verification - --color COLOR Colorize output (where COLOR is auto, always, never) - -h, --help show this help message and exit - - subcommands: - <subcommand> - layerindex-fetch Fetches a layer from a layer index along with its - dependent layers, and adds them to conf/bblayers.conf. - layerindex-show-depends - Find layer dependencies from layer index. - add-layer Add one or more layers to bblayers.conf. - remove-layer Remove one or more layers from bblayers.conf. - flatten flatten layer configuration into a separate output - directory. - show-layers show current configured layers. - show-overlayed list overlayed recipes (where the same recipe exists - in another layer) - show-recipes list available recipes, showing the layer they are - provided by - show-appends list bbappend files and recipe files they apply to - show-cross-depends Show dependencies between recipes that cross layer - boundaries. - create-layer Create a basic layer - - Use bitbake-layers <subcommand> --help to get help on a specific command The following list describes the available commands: @@ -759,8 +726,18 @@ The following list describes the available commands: - ``layerindex-show-depends``: Finds layer dependencies from the layer index. +- ``save-build-conf``: Saves the currently active build configuration + (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. + This template can later be used for setting up builds via :term:``TEMPLATECONF``. + For information about saving and using configuration templates, see + ":ref:`dev-manual/common-tasks:creating a custom template configuration directory`". + - ``create-layer``: Creates a basic layer. +- ``create-layers-setup``: Writes out a configuration file and/or a script that + can replicate the directory structure and revisions of the layers in a current build. + For more information, see ":ref:`dev-manual/common-tasks:saving and restoring the layers setup`". + Creating a General Layer Using the ``bitbake-layers`` Script ------------------------------------------------------------ @@ -880,6 +857,62 @@ enables the build system to locate the layer during the build. During a build, the OpenEmbedded build system looks in the layers from the top of the list down to the bottom in that order. +Saving and restoring the layers setup +------------------------------------- + +Once you have a working build with the correct set of layers, it is beneficial +to capture the layer setup --- what they are, which repositories they come from +and which SCM revisions they're at --- into a configuration file, so that this +setup can be easily replicated later, perhaps on a different machine. Here's +how to do this:: + + $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/ + NOTE: Starting bitbake server... + NOTE: Created /srv/work/alex/meta-alex/setup-layers.json + NOTE: Created /srv/work/alex/meta-alex/setup-layers + +The tool needs a single argument which tells where to place the output, consisting +of a json formatted layer configuration, and a ``setup-layers`` script that can use that configuration +to restore the layers in a different location, or on a different host machine. The argument +can point to a custom layer (which is then deemed a "bootstrap" layer that needs to be +checked out first), or into a completely independent location. + +The replication of the layers is performed by running the ``setup-layers`` script provided +above: + +1. Clone the bootstrap layer or some other repository to obtain + the json config and the setup script that can use it. + +2. Run the script directly with no options:: + + alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers + Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. + + Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master + Running 'git init -q /srv/work/alex/my-build/meta-intel' + Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/meta-intel' in /srv/work/alex/my-build/meta-intel + Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel + Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel + + Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers + Running 'git init -q /srv/work/alex/my-build/poky' + Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/poky' in /srv/work/alex/my-build/poky + Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky + Running 'git remote remove poky-contrib > /dev/null 2>&1; git remote add poky-contrib ssh://git@push.yoctoproject.org/poky-contrib' in /srv/work/alex/my-build/poky + Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky + Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky + +.. note:: + This will work to update an existing checkout as well. + +.. note:: + The script is self-sufficient and requires only python3 + and git on the build machine. + +.. note:: + Both the ``create-layers-setup`` and the ``setup-layers`` provided several additional options + that customize their behavior - you are welcome to study them via ``--help`` command line parameter. + Customizing Images ================== @@ -2577,7 +2610,7 @@ chapter of the BitBake User Manual. S = "${WORKDIR}/postfix-${PV}" CFLAGS += "-DNO_ASM" - SRC_URI:append = " file://fixup.patch" + CFLAGS:append = " --enable-important-feature" - *Functions:* Functions provide a series of actions to be performed. You usually use functions to override the default implementation of a @@ -2708,19 +2741,21 @@ in the BitBake User Manual. to existing variables. This operator does not add any additional space. Also, the operator is applied after all the ``+=``, and ``=+`` operators have been applied and after all ``=`` assignments have - occurred. + occurred. This means that if ``:append`` is used in a recipe, it can + only be overridden by another layer using the special ``:remove`` + operator, which in turn will prevent further layers from adding it back. The following example shows the space being explicitly added to the start to ensure the appended value is not merged with the existing value:: - SRC_URI:append = " file://fix-makefile.patch" + CFLAGS:append = " --enable-important-feature" You can also use the ``:append`` operator with overrides, which results in the actions only being performed for the specified target or machine:: - SRC_URI:append:sh4 = " file://fix-makefile.patch" + CFLAGS:append:sh4 = " --enable-important-sh4-specific-feature" - *Prepending (:prepend):* Use the ``:prepend`` operator to prepend values to existing variables. This operator does not add any @@ -3560,6 +3595,9 @@ functions:: pydevshell> bb.build.exec_func("do_unpack", d) pydevshell> +See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`" +section in the BitBake User Manual for details about available functions. + The commands execute just as if the OpenEmbedded build system were executing them. Consequently, working this way can be helpful when debugging a build or preparing software to be used with the @@ -6431,71 +6469,51 @@ Creating a Custom Template Configuration Directory ================================================== If you are producing your own customized version of the build system for -use by other users, you might want to customize the message shown by the -setup script or you might want to change the template configuration -files (i.e. ``local.conf`` and ``bblayers.conf``) that are created in a -new build directory. - -The OpenEmbedded build system uses the environment variable -:term:`TEMPLATECONF` to locate the directory from which it gathers -configuration information that ultimately ends up in the -:term:`Build Directory` ``conf`` directory. -By default, :term:`TEMPLATECONF` is set as follows in the ``poky`` -repository:: +use by other users, you might want to provide a custom build configuration +that includes all the necessary settings and layers (i.e. ``local.conf`` and +``bblayers.conf`` that are created in a new build directory) and a custom +message that is shown when setting up the build. This can be done by +creating one or more template configuration directories in your +custom distribution layer. - TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} +This can be done by using ``bitbake-layers save-build-conf``:: -This is the -directory used by the build system to find templates from which to build -some key configuration files. If you look at this directory, you will -see the ``bblayers.conf.sample``, ``local.conf.sample``, and -``conf-notes.txt`` files. The build system uses these files to form the -respective ``bblayers.conf`` file, ``local.conf`` file, and display the -list of BitBake targets when running the setup script. - -To override these default configuration files with configurations you -want used within every new Build Directory, simply set the -:term:`TEMPLATECONF` variable to your directory. The :term:`TEMPLATECONF` -variable is set in the ``.templateconf`` file, which is in the top-level -:term:`Source Directory` folder -(e.g. ``poky``). Edit the ``.templateconf`` so that it can locate your -directory. + $ bitbake-layers save-build-conf ../../meta-alex/ test-1 + NOTE: Starting bitbake server... + NOTE: Configuration template placed into /srv/work/alex/meta-alex/conf/templates/test-1 + Please review the files in there, and particularly provide a configuration description in /srv/work/alex/meta-alex/conf/templates/test-1/conf-notes.txt + You can try out the configuration with + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 -Best practices dictate that you should keep your template configuration -directory in your custom distribution layer. For example, suppose you -have a layer named ``meta-mylayer`` located in your home directory and -you want your template configuration directory named ``myconf``. -Changing the ``.templateconf`` as follows causes the OpenEmbedded build -system to look in your directory and base its configuration files on the -``*.sample`` configuration files it finds. The final configuration files -(i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in -your Build Directory, but they are based on your ``*.sample`` files. -:: +The above command takes the config files from the currently active build directory under ``conf``, +replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies +the config files into a specified layer under a specified template name. - TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} +To use those saved templates as a starting point for a build, users should point +to one of them with :term:`TEMPLATECONF` environment variable:: -Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` -also resides in the default ``meta-poky/conf`` directory. The script -that sets up the build environment (i.e. -:ref:`structure-core-script`) uses this file to -display BitBake targets as part of the script output. Customizing this -``conf-notes.txt`` file is a good way to make sure your list of custom -targets appears as part of the script's output. + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 -Here is the default list of targets displayed as a result of running -either of the setup scripts:: +The OpenEmbedded build system uses the environment variable +:term:`TEMPLATECONF` to locate the directory from which it gathers +configuration information that ultimately ends up in the +:term:`Build Directory` ``conf`` directory. - You can now run 'bitbake <target>' +If :term:`TEMPLATECONF` is not set, the default value is obtained +from ``.templateconf`` file that is read from the same directory as +``oe-init-build-env`` script. For the Poky reference distribution this +would be:: - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-ide-support + TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf/templates/default} -Changing the listed common targets is as easy as editing your version of -``conf-notes.txt`` in your custom template configuration directory and -making sure you have :term:`TEMPLATECONF` set to your directory. +If you look at a configuration template directory, you will +see the ``bblayers.conf.sample``, ``local.conf.sample``, and +``conf-notes.txt`` files. The build system uses these files to form the +respective ``bblayers.conf`` file, ``local.conf`` file, and show +users a note about the build they're setting up +when running the ``oe-init-build-env`` setup script. These can be +edited further if needed to improve or change the build configurations +available to the users. Conserving Disk Space ===================== @@ -11417,12 +11435,12 @@ example: # clean up the .git repos $ find . -name ".git" -type d -exec rm -rf {} \; -One -thing a development organization might want to consider for end-user -convenience is to modify ``meta-poky/conf/bblayers.conf.sample`` to -ensure that when the end user utilizes the released build system to -build an image, the development organization's layers are included in -the ``bblayers.conf`` file automatically:: +One thing a development organization might want to consider for end-user +convenience is to modify +``meta-poky/conf/templates/default/bblayers.conf.sample`` to ensure that when +the end user utilizes the released build system to build an image, the +development organization's layers are included in the ``bblayers.conf`` file +automatically:: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly @@ -11451,9 +11469,9 @@ The spdx module has been integrated to a layer named meta-spdxscanner. meta-spdxscanner provides several kinds of scanner. If you want to enable this function, you have to follow the following steps: -1. Add meta-spdxscanner layer into ``bblayers.conf``. +1. Add meta-spdxscanner layer into ``bblayers.conf``. -2. Refer to the README in meta-spdxscanner to setup the environment (e.g, +2. Refer to the README in meta-spdxscanner to setup the environment (e.g, setup a fossology server) needed for the scanner. 3. Meta-spdxscanner provides several methods within the bbclass to create spdx files. diff --git a/poky/documentation/kernel-dev/common.rst b/poky/documentation/kernel-dev/common.rst index 16ef6453bd..fb8d7cd029 100644 --- a/poky/documentation/kernel-dev/common.rst +++ b/poky/documentation/kernel-dev/common.rst @@ -360,9 +360,9 @@ home directory: FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - SRC_URI:append = " file://patch-file-one.patch" - SRC_URI:append = " file://patch-file-two.patch" - SRC_URI:append = " file://patch-file-three.patch" + SRC_URI += "file://patch-file-one.patch" + SRC_URI += "file://patch-file-two.patch" + SRC_URI += "file://patch-file-three.patch" The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements enable the OpenEmbedded build system to find patch files. For more @@ -1002,7 +1002,7 @@ Section. contents:: FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch" + SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch" The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements enable the OpenEmbedded build system to find the patch file. @@ -1875,7 +1875,7 @@ build. 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the recipe's :term:`SRC_URI` statement:: - SRC_URI:append = " file://test.scc" + SRC_URI += "file://test.scc" The leading space before the path is important as the path is appended to the existing path. @@ -1884,7 +1884,7 @@ build. :term:`KERNEL_FEATURES` statement to specify the feature as a kernel feature:: - KERNEL_FEATURES:append = " test.scc" + KERNEL_FEATURES += "test.scc" The OpenEmbedded build system processes the kernel feature when it builds the kernel. diff --git a/poky/documentation/overview-manual/concepts.rst b/poky/documentation/overview-manual/concepts.rst index 83339da98f..8e0303f0e0 100644 --- a/poky/documentation/overview-manual/concepts.rst +++ b/poky/documentation/overview-manual/concepts.rst @@ -269,7 +269,7 @@ The ``local.conf`` file provides many basic variables that define a build environment. Here is a list of a few. To see the default configurations in a ``local.conf`` file created by the build environment script, see the -:yocto_git:`local.conf.sample </poky/tree/meta-poky/conf/local.conf.sample>` +:yocto_git:`local.conf.sample </poky/tree/meta-poky/conf/templates/default/local.conf.sample>` in the ``meta-poky`` layer: - *Target Machine Selection:* Controlled by the @@ -1006,7 +1006,7 @@ data files are deleted from the root filesystem. As part of the final stage of package installation, post installation scripts that are part of the packages are run. Any scripts that fail to run on the build host are run on the target when the target system is first booted. If you are -using a +using a :ref:`read-only root filesystem <dev-manual/common-tasks:creating a read-only root filesystem>`, all the post installation scripts must succeed on the build host during the package installation phase since the root filesystem on the target diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 424c505715..11e0d472e8 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/classes.rst @@ -580,8 +580,8 @@ Finally, here is an example that sets the root password:: .. note:: From a security perspective, hardcoding a default password is not - generally a good idea or even legal in some jurisdictions. It is - recommended that you do not do this if you are building a production + generally a good idea or even legal in some jurisdictions. It is + recommended that you do not do this if you are building a production image. @@ -792,7 +792,7 @@ The class stages directories with symlinks from ``gcc`` and ``g++`` to ``icecc``, for both native and cross compilers. Depending on each configure or compile, the OpenEmbedded build system adds the directories at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and -``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` +``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` compilers, respectively. For the cross compiler, the class creates a ``tar.gz`` file that @@ -800,8 +800,8 @@ contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which is the version of the cross-compiler used in the cross-development toolchain, accordingly. -The class handles all three different compile stages (i.e native -,cross-kernel and target) and creates the necessary environment +The class handles all three different compile stages (i.e native, +cross-kernel and target) and creates the necessary environment ``tar.gz`` file to be used by the remote machines. The class also supports SDK generation. @@ -811,12 +811,13 @@ using ``which``. If :term:`ICECC_ENV_EXEC` is set in your ``local.conf`` file, the variable should point to the ``icecc-create-env`` script provided by the user. If you do not point to a user-provided script, the build system uses the default script -provided by the recipe ``icecc-create-env-native.bb``. +provided by the recipe :oe_git:`icecc-create-env_0.1.bb +</openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`. .. note:: This script is a modified version and not the one that comes with - icecc. + ``icecream``. If you do not want the Icecream distributed compile support to apply to specific recipes or classes, you can ask them to be ignored by Icecream diff --git a/poky/documentation/ref-manual/faq.rst b/poky/documentation/ref-manual/faq.rst index 2fcbf7da96..61049523a0 100644 --- a/poky/documentation/ref-manual/faq.rst +++ b/poky/documentation/ref-manual/faq.rst @@ -137,9 +137,10 @@ To use them, remove the comments:: #use_proxy = on The Yocto Project also includes a -``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS -and Git proxy servers if needed. For more information on setting up -various proxy types and configuring proxy servers, see the +``meta-poky/conf/templates/default/site.conf.sample`` file that shows +how to configure CVS and Git proxy servers if needed. For more +information on setting up various proxy types and configuring proxy +servers, see the ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" Wiki page. diff --git a/poky/documentation/ref-manual/features.rst b/poky/documentation/ref-manual/features.rst index 8dfe29d66a..5e853caa2c 100644 --- a/poky/documentation/ref-manual/features.rst +++ b/poky/documentation/ref-manual/features.rst @@ -113,10 +113,15 @@ configuration level. See the information. This list only represents features as shipped with the Yocto Project -metadata: +metadata, as extra layers can define their own: -- *alsa:* Include ALSA support (OSS compatibility kernel modules - installed if available). +- *3g:* Include support for cellular data. + +- *acl:* Include + `Access Control List <https://en.wikipedia.org/wiki/Access-control_list>`__ support. + +- *alsa:* Include `Advanced Linux Sound Architecture <https://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture>`__ + support (OSS compatibility kernel modules installed if available). - *api-documentation:* Enables generation of API documentation during recipe builds. The resulting documentation is added to SDK tarballs @@ -129,6 +134,10 @@ metadata: - *cramfs:* Include CramFS support. +- *debuginfod:* Include support for getting ELF debugging information through + a :ref:`debuginfod <dev-manual/common-tasks:using the debuginfod server method>` + server. + - *directfb:* Include DirectFB support. - *ext2:* Include tools for supporting for devices with internal @@ -136,14 +145,25 @@ metadata: - *ipsec:* Include IPSec support. +- *ipv4:* Include IPv4 support. + - *ipv6:* Include IPv6 support. - *keyboard:* Include keyboard support (e.g. keymaps will be loaded during boot). +- *largefile:* Enable building applications with + `argefile support <https://en.wikipedia.org/wiki/Large-file_support>`__. + +- *multiarch:* Enable building applications with multiple architecture + support. + - *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the target. +- *nfc:* Include support for + `Near Field Communication <https://en.wikipedia.org/wiki/Near-field_communication>`__. + - *nfs:* Include NFS client support (for mounting NFS exports on device). @@ -162,6 +182,11 @@ metadata: ":ref:`dev-manual/common-tasks:testing packages with ptest`" section in the Yocto Project Development Tasks Manual. +- *seccomp:* Enables building applications with + `seccomp <https://en.wikipedia.org/wiki/Seccomp>`__ support, to + allow them to strictly restrict the system calls that they are allowed + to invoke. + - *smbfs:* Include SMB networks client support (for mounting Samba/Microsoft Windows shares on device). @@ -180,6 +205,12 @@ metadata: directories into their respective counterparts in the ``/usr`` directory to provide better package and application compatibility. +- *vfat:* Include `FAT filesystem <https://en.wikipedia.org/wiki/File_Allocation_Table>`__ + support. + +- *vulkan:* Include support for the + `Vulkan API <https://en.wikipedia.org/wiki/Vulkan>`__. + - *wayland:* Include the Wayland display server protocol and the library that supports it. @@ -187,6 +218,12 @@ metadata: - *x11:* Include the X server and libraries. +- *xattr:* Include support for + `extended file attributes <https://en.wikipedia.org/wiki/Extended_file_attributes>`__. + +- *zeroconf:* Include support for + `zero configuration networking <https://en.wikipedia.org/wiki/Zero-configuration_networking>`__. + .. _ref-features-image: Image Features diff --git a/poky/documentation/ref-manual/structure.rst b/poky/documentation/ref-manual/structure.rst index bdcffc1947..429f81e14c 100644 --- a/poky/documentation/ref-manual/structure.rst +++ b/poky/documentation/ref-manual/structure.rst @@ -68,6 +68,9 @@ information on separating output from your local Source Directory files (commonly described as an "out of tree" build), see the ":ref:`structure-core-script`" section. +See the ":ref:`The Build Directory --- build/ <structure-build>`" section for details +about the contents of the :term:`Build Directory`. + .. _handbook: ``documentation/`` @@ -189,7 +192,7 @@ Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: $ source oe-init-build-env ~/mybuilds The OpenEmbedded build system uses the template configuration files, which -are found by default in the ``meta-poky/conf/`` directory in the Source +are found by default in the ``meta-poky/conf/templates/default`` directory in the Source Directory. See the ":ref:`dev-manual/common-tasks:creating a custom template configuration directory`" section in the Yocto Project Development Tasks Manual for more @@ -237,6 +240,18 @@ subdirectories. For information on the build history feature, see the ":ref:`dev-manual/common-tasks:maintaining build output quality`" section in the Yocto Project Development Tasks Manual. +.. _structure-build-cache: + +``build/cache/`` +---------------- + +This directory contains several internal files used by the OpenEmbedded +build system. + +It also contains ``sanity_info``, a text file keeping track of important +build information such as the values of :term:`TMPDIR`, :term:`SSTATE_DIR`, +as well as the name and version of the host distribution. + .. _structure-build-conf-local.conf: ``build/conf/local.conf`` @@ -261,15 +276,15 @@ OpenEmbedded build system creates it from ``local.conf.sample`` when you :ref:`structure-core-script`. The source ``local.conf.sample`` file used depends on the -:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/`` +:term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto Project development environment, -and to ``meta/conf/`` when you are building from the OpenEmbedded-Core +and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``local.conf.sample`` file, this implies that you can configure your build environment from any layer by setting the variable in the top-level build environment setup script as follows:: - TEMPLATECONF=your_layer/conf + TEMPLATECONF=your_layer/conf/templates/your_template_name Once the build process gets the sample file, it uses ``sed`` to substitute final @@ -281,7 +296,7 @@ file, it uses ``sed`` to substitute final You can see how the :term:`TEMPLATECONF` variable is used by looking at the ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. You can find the Yocto Project version of the ``local.conf.sample`` file in - the ``meta-poky/conf`` directory. + the ``meta-poky/conf/templates/default`` directory. .. _structure-build-conf-bblayers.conf: @@ -301,14 +316,14 @@ you ``source`` the top-level build environment setup script (i.e. As with the ``local.conf`` file, the source ``bblayers.conf.sample`` file used depends on the :term:`TEMPLATECONF` script variable, which -defaults to ``meta-poky/conf/`` when you are building from the Yocto -Project development environment, and to ``meta/conf/`` when you are +defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto +Project development environment, and to ``meta/conf/templates/default`` when you are building from the OpenEmbedded-Core environment. Because the script variable points to the source of the ``bblayers.conf.sample`` file, this implies that you can base your build from any layer by setting the variable in the top-level build environment setup script as follows:: - TEMPLATECONF=your_layer/conf + TEMPLATECONF=your_layer/conf/templates/your_template_name Once the build process gets the sample file, it uses ``sed`` to substitute final ``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. @@ -317,17 +332,9 @@ Once the build process gets the sample file, it uses ``sed`` to substitute final You can see how the :term:`TEMPLATECONF` variable is defined by the ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`. You can find the Yocto Project - version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/`` + version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default`` directory. -.. _structure-build-conf-sanity_info: - -``build/cache/sanity_info`` ---------------------------- - -This file indicates the state of the sanity checks and is created during -the build. - .. _structure-build-downloads: ``build/downloads/`` @@ -366,14 +373,14 @@ remove the ``build/sstate-cache`` directory. .. _structure-build-tmp-buildstats: ``build/tmp/buildstats/`` -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ This directory stores the build statistics. .. _structure-build-tmp-cache: ``build/tmp/cache/`` --------------------- +~~~~~~~~~~~~~~~~~~~~ When BitBake parses the metadata (recipes and configuration files), it caches the results in ``build/tmp/cache/`` to speed up future builds. @@ -389,7 +396,7 @@ cache is reused. If the file has changed, it is reparsed. .. _structure-build-tmp-deploy: ``build/tmp/deploy/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This directory contains any "end result" output from the OpenEmbedded build process. The :term:`DEPLOY_DIR` variable points @@ -402,7 +409,7 @@ Project Overview and Concepts Manual. .. _structure-build-tmp-deploy-deb: ``build/tmp/deploy/deb/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives any ``.deb`` packages produced by the build process. The packages are sorted into feeds for different architecture @@ -411,7 +418,7 @@ types. .. _structure-build-tmp-deploy-rpm: ``build/tmp/deploy/rpm/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives any ``.rpm`` packages produced by the build process. The packages are sorted into feeds for different architecture @@ -420,14 +427,14 @@ types. .. _structure-build-tmp-deploy-ipk: ``build/tmp/deploy/ipk/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives ``.ipk`` packages produced by the build process. .. _structure-build-tmp-deploy-licenses: ``build/tmp/deploy/licenses/`` ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This directory receives package licensing information. For example, the directory contains sub-directories for ``bash``, ``busybox``, and @@ -440,7 +447,7 @@ section in the Yocto Project Development Tasks Manual. .. _structure-build-tmp-deploy-images: ``build/tmp/deploy/images/`` ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This directory is populated with the basic output objects of the build (think of them as the "generated artifacts" of the build process), @@ -467,7 +474,7 @@ the kernel files:: .. _structure-build-tmp-deploy-sdk: ``build/tmp/deploy/sdk/`` -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ The OpenEmbedded build system creates this directory to hold toolchain installer scripts which, when executed, install the sysroot that matches @@ -479,7 +486,7 @@ Software Development Kit (eSDK) manual. .. _structure-build-tmp-sstate-control: ``build/tmp/sstate-control/`` ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OpenEmbedded build system uses this directory for the shared state manifest files. The shared state code uses these files to record the @@ -492,7 +499,7 @@ another. .. _structure-build-tmp-sysroots-components: ``build/tmp/sysroots-components/`` ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This directory is the location of the sysroot contents that the task :ref:`ref-tasks-prepare_recipe_sysroot` @@ -507,7 +514,7 @@ should be automatic, and recipes should not directly reference .. _structure-build-tmp-sysroots: ``build/tmp/sysroots/`` ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Previous versions of the OpenEmbedded build system used to create a global shared sysroot per machine along with a native sysroot. Since @@ -525,7 +532,7 @@ recipe-specific :term:`WORKDIR` directories. Thus, the .. _structure-build-tmp-stamps: ``build/tmp/stamps/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This directory holds information that BitBake uses for accounting purposes to track what tasks have run and when they have run. The @@ -545,7 +552,7 @@ section in the Yocto Project Overview and Concepts Manual. .. _structure-build-tmp-log: ``build/tmp/log/`` ------------------- +~~~~~~~~~~~~~~~~~~ This directory contains general logs that are not otherwise placed using the package's :term:`WORKDIR`. Examples of logs are the output from the @@ -555,7 +562,7 @@ necessarily mean this directory is created. .. _structure-build-tmp-work: ``build/tmp/work/`` -------------------- +~~~~~~~~~~~~~~~~~~~ This directory contains architecture-specific work sub-directories for packages built by BitBake. All tasks execute from the appropriate work @@ -587,7 +594,7 @@ install" places its output that is then split into sub-packages within .. _structure-build-tmp-work-tunearch-recipename-version: ``build/tmp/work/tunearch/recipename/version/`` ------------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The recipe work directory --- ``${WORKDIR}``. @@ -645,7 +652,7 @@ Here are key subdirectories within each recipe work directory: .. _structure-build-work-shared: ``build/tmp/work-shared/`` --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ For efficiency, the OpenEmbedded build system creates and uses this directory to hold recipes that share a work directory with other @@ -695,7 +702,7 @@ distribution configuration file. .. _structure-meta-conf-machine: ``meta/conf/machine/`` ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ This directory contains all the machine configuration files. If you set ``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a @@ -706,7 +713,7 @@ support for a new machine to the Yocto Project, look in this directory. .. _structure-meta-conf-distro: ``meta/conf/distro/`` ---------------------- +~~~~~~~~~~~~~~~~~~~~~ The contents of this directory controls any distribution-specific configurations. For the Yocto Project, the ``defaultsetup.conf`` is the @@ -718,7 +725,7 @@ file mainly inherits its configuration from Poky. .. _structure-meta-conf-machine-sdk: ``meta/conf/machine-sdk/`` --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ The OpenEmbedded build system searches this directory for configuration files that correspond to the value of diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index cf817e9540..2971654531 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -135,7 +135,6 @@ system and gives an overview of their function and contents. appear in :term:`DISTRO_FEATURES` within the current configuration, then the recipe will be skipped, and if the build system attempts to build the recipe then an error will be triggered. - :term:`APPEND` An override list of append strings for each target specified with @@ -729,22 +728,6 @@ system and gives an overview of their function and contents. ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" section in the Yocto Project Development Tasks Manual. - :term:`BBPATH` - Used by BitBake to locate ``.bbclass`` and configuration files. This - variable is analogous to the ``PATH`` variable. - - .. note:: - - If you run BitBake from a directory outside of the - :term:`Build Directory`, you must be sure to set :term:`BBPATH` - to point to the Build Directory. Set the variable as you would any - environment variable and then run BitBake:: - - $ BBPATH = "build_directory" - $ export BBPATH - $ bitbake target - - :term:`BBSERVER` If defined in the BitBake environment, :term:`BBSERVER` points to the BitBake remote server. @@ -2386,8 +2369,8 @@ system and gives an overview of their function and contents. .. note:: From a security perspective, hardcoding a default password is not - generally a good idea or even legal in some jurisdictions. It is - recommended that you do not do this if you are building a production + generally a good idea or even legal in some jurisdictions. It is + recommended that you do not do this if you are building a production image. Additionally there is a special ``passwd-expire`` command that will @@ -2967,8 +2950,10 @@ system and gives an overview of their function and contents. If you do not point to a script that you provide, the OpenEmbedded build system uses the default script provided by the - ``icecc-create-env.bb`` recipe, which is a modified version and not - the one that comes with ``icecc``. + :oe_git:`icecc-create-env_0.1.bb + </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>` + recipe, which is a modified version and not the one that comes with + ``icecream``. :term:`ICECC_PARALLEL_MAKE` Extra options passed to the ``make`` command during the @@ -3690,10 +3675,10 @@ system and gives an overview of their function and contents. to "core-image-minimal-initramfs". You can also find more information by referencing the - ``meta-poky/conf/local.conf.sample.extended`` configuration file in - the Source Directory, the :ref:`image <ref-classes-image>` class, - and the :ref:`kernel <ref-classes-kernel>` class to see how to use - the :term:`INITRAMFS_IMAGE` variable. + ``meta-poky/conf/templates/default/local.conf.sample.extended`` + configuration file in the Source Directory, the :ref:`image + <ref-classes-image>` class, and the :ref:`kernel <ref-classes-kernel>` + class to see how to use the :term:`INITRAMFS_IMAGE` variable. If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no initramfs image is built. @@ -3752,7 +3737,7 @@ system and gives an overview of their function and contents. configuration file. You cannot set the variable in a recipe file. See the - :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>` + :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` file for additional information. Also, for information on creating an initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in the Yocto Project Development Tasks Manual. @@ -3984,11 +3969,10 @@ system and gives an overview of their function and contents. KCONFIG_MODE = "alldefconfig" - :term:`KERNEL_ALT_IMAGETYPE` Specifies an alternate kernel image type for creation in addition to - the kernel image type specified using the - :term:`KERNEL_IMAGETYPE` variable. + the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and + :term:`KERNEL_IMAGETYPES` variables. :term:`KERNEL_ARTIFACT_NAME` Specifies the name of all of the build artifacts. You can change the @@ -4172,9 +4156,12 @@ system and gives an overview of their function and contents. when building the kernel and is passed to ``make`` as the target to build. - If you want to build an alternate kernel image type in addition to that - specified by :term:`KERNEL_IMAGETYPE`, use the :term:`KERNEL_ALT_IMAGETYPE` - variable. + To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`. + + :term:`KERNEL_IMAGETYPES` + Lists additional types of kernel images to build for a device in addition + to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the + machine configuration files. :term:`KERNEL_MODULE_AUTOLOAD` Lists kernel modules that need to be auto-loaded during boot. @@ -6075,9 +6062,9 @@ system and gives an overview of their function and contents. :term:`PRSERV_HOST` The network based :term:`PR` service host and port. - The ``conf/local.conf.sample.extended`` configuration file in the - :term:`Source Directory` shows how the - :term:`PRSERV_HOST` variable is set:: + The ``conf/templates/default/local.conf.sample.extended`` configuration + file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` + variable is set:: PRSERV_HOST = "localhost:0" @@ -6588,7 +6575,7 @@ system and gives an overview of their function and contents. :term:`SDK_CUSTOM_TEMPLATECONF` When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to - "1" and a ``conf/templateconf.conf`` file exists in the build directory + "1" and a ``conf/templateconf.cfg`` file exists in the build directory (:term:`TOPDIR`) then this will be copied into the SDK. :term:`SDK_DEPLOY` @@ -7973,6 +7960,12 @@ system and gives an overview of their function and contents. toolchain. You can use ``meta-sourcery`` as a template for adding support for other external toolchains. + :term:`TC_CXX_RUNTIME` + Specifies the C/C++ STL and runtime variant to use during + the build process. Default value is 'gnu' + + You can select "gnu", "llvm", or "android". + :term:`TEMPLATECONF` Specifies the directory used by the build system to find templates from which to build the ``bblayers.conf`` and ``local.conf`` files. @@ -8666,7 +8659,8 @@ system and gives an overview of their function and contents. USER_CLASSES ?= "buildstats" For more information, see - ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. + ``meta-poky/conf/templates/default/local.conf.sample`` in the + :term:`Source Directory`. :term:`USERADD_ERROR_DYNAMIC` If set to ``error``, forces the OpenEmbedded build system to produce @@ -8924,4 +8918,3 @@ system and gives an overview of their function and contents. On systems where many tasks run in parallel, setting a limit to this can be helpful in controlling system resource usage. - |