RFC: stop advising to build from the source directory
PATCH 1/1 RFC: stop advising to build from the source directory
From: Michael Opdenacker <[email protected]>
Recommending to build typically from the parent directory in which poky was cloned, or another directory.
---
I'm proposing to guide users to avoid building from the source directory. That's already recommended in dev-manual/common-tasks.rst:
In any event, it's typically cleaner to locate the build directory somewhere outside of your source directory.
I've only made quick changes so far, but if we agree to go in this direction, I will cautiously adapt the instructions so that they look natural (not asking to run "cd poky/.." for example).
What do you think? Wouldn't it be cleaner?
--- documentation/brief-yoctoprojectqs/index.rst | 12 +++++------- documentation/bsp-guide/bsp.rst | 6 +++--- documentation/dev-manual/common-tasks.rst | 5 ++--- documentation/dev-manual/qemu.rst | 3 +-- documentation/kernel-dev/common.rst | 10 +++++----- documentation/profile-manual/usage.rst | 4 ++-- documentation/ref-manual/structure.rst | 4 ++-- documentation/ref-manual/terms.rst | 8 -------- documentation/sdk-manual/appendix-obtain.rst | 4 ++-- documentation/toaster-manual/setup-and-use.rst | 12 ++++++------ 10 files changed, 28 insertions(+), 40 deletions(-)
documentation/brief-yoctoprojectqs/index.rst +5 -7
@@ -184,16 +184,14 @@ an entire Linux distribution, including the toolchain, from source. ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" page of the Yocto Project Wiki. -#. **Initialize the Build Environment:** From within the ``poky`` - directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` - environment - setup script to define Yocto Project's build environment on your +#. **Initialize the Build Environment:** From within the parent directory of + the ``poky`` directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` + environment setup script to define Yocto Project's build environment on your build host. .. code-block:: shell - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env You had no conf/local.conf file. This configuration file has therefore been created for you with some default values. You may wish to edit it to, for example, select a different MACHINE (target hardware). See conf/local.conf
@@ -361,7 +359,7 @@ Follow these steps to add a hardware layer: .. code-block:: shell - $ cd poky/build + $ cd build $ bitbake-layers add-layer ../meta-altera NOTE: Starting bitbake server... Parsing recipes: 100% |##################################################################| Time: 0:00:32
documentation/bsp-guide/bsp.rst +3 -3
@@ -228,13 +228,13 @@ section. Resolving deltas: 100% (2447/2447), done. Checking connectivity... done. -#. *Initialize the Build Environment:* While in the root directory of - the Source Directory (i.e. ``poky``), run the +#. *Initialize the Build Environment:* Outside of the the Source Directory + (i.e. ``poky``), for example in the parent directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment setup script to define the OpenEmbedded build environment on your build host. :: - $ source oe-init-build-env + $ source poky/oe-init-build-env Among other things, the script creates the :term:`Build Directory`, which is ``build`` in this case and is located in the :term:`Source Directory`. After
documentation/dev-manual/common-tasks.rst +2 -3
@@ -3022,8 +3022,7 @@ The following steps describe how to set up the AUH utility: script to create a fresh build directory that you use exclusively for running the AUH utility:: - $ cd poky - $ source oe-init-build-env your_AUH_build_directory + $ source poky/oe-init-build-env your_AUH_build_directory Re-using an existing build directory and its configurations is not recommended as existing settings could cause AUH to fail or behave
@@ -3667,7 +3666,7 @@ The following figure and list overviews the build process: by sourcing the build environment script (i.e. :ref:`structure-core-script`):: - $ source oe-init-build-env [build_dir] + $ source poky/oe-init-build-env [build_dir] When you use the initialization script, the OpenEmbedded build system uses ``build`` as the default :term:`Build Directory` in your current work
documentation/dev-manual/qemu.rst +1 -2
@@ -57,8 +57,7 @@ available. Follow these general steps to run QEMU: unpacked a Yocto Project release tarball, you can source the build environment script (i.e. :ref:`structure-core-script`):: - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env - If you installed a cross-toolchain, you can run the script that initializes the toolchain. For example, the following commands run
documentation/kernel-dev/common.rst +5 -5
@@ -56,8 +56,7 @@ section: you need to initialize the BitBake build environment by sourcing the build environment script (i.e. :ref:`structure-core-script`):: - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env .. note::
@@ -177,7 +176,8 @@ section: $ git branch master * &DISTRO_NAME_NO_CAP; - $ source oe-init-build-env + $ cd .. + $ source poky/oe-init-build-env .. note::
@@ -1074,8 +1074,8 @@ The following commands initialize the BitBake environment, run the task, and launch ``menuconfig``. These commands assume the Source Directory's top-level folder is ``poky``:: - $ cd poky - $ source oe-init-build-env + $ cd poky/.. + $ source poky/oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c menuconfig
documentation/profile-manual/usage.rst +2 -2
@@ -1907,8 +1907,8 @@ Running a Script on a Target Once you've done that, you should be able to run a systemtap script on the target:: - $ cd /path/to/yocto - $ source oe-init-build-env + $ cd /path/to/poky/.. + $ source poky/oe-init-build-env ### Shell environment set up for builds. ###
documentation/ref-manual/structure.rst +2 -2
@@ -158,7 +158,7 @@ directory becomes the Build Directory, and you are presented with some simple suggestions as to what to do next, including a list of some possible targets to build. Here is an example:: - $ source oe-init-build-env + $ source poky/oe-init-build-env ### Shell environment set up for builds. ###
@@ -189,7 +189,7 @@ you direct the OpenEmbedded build system to create a Build Directory of your choice. For example, the following command creates a Build Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: - $ source oe-init-build-env ~/mybuilds + $ source poky/oe-init-build-env ~/mybuilds The OpenEmbedded build system uses the template configuration files, which are found by default in the ``meta-poky/conf/templates/default`` directory in the Source
documentation/ref-manual/terms.rst +0 -8
@@ -70,14 +70,6 @@ universal, the list includes them just in case: Following are some examples that show how to create the directory. The examples assume your :term:`Source Directory` is named ``poky``: - - Create the Build Directory inside your Source Directory and let - the name of the Build Directory default to ``build``: - - .. code-block:: shell - - $ cd poky - $ source oe-init-build-env - - Create the Build Directory inside your home directory and specifically name it ``test-builds``:
documentation/sdk-manual/appendix-obtain.rst +2 -2
@@ -107,14 +107,14 @@ build the SDK installer. Follow these steps: how to clone the ``poky`` repository and check out the appropriate branch for your work. -3. *Initialize the Build Environment:* While in the root directory of +3. *Initialize the Build Environment:* While in the parent directory of the Source Directory (i.e. ``poky``), run the :ref:`structure-core-script` environment setup script to define the OpenEmbedded build environment on your build host. :: - $ source oe-init-build-env + $ source poky/oe-init-build-env Among other things, the script creates the :term:`Build Directory`,
documentation/toaster-manual/setup-and-use.rst +6 -6
@@ -14,14 +14,14 @@ dependencies as described in the ":ref:`toaster-manual/start:Preparing to Use Toaster`" chapter, you are ready to start Toaster. -Navigate to the root of your +Navigate to the parent directory of the root of your :term:`Source Directory` (e.g. ``poky``):: - $ cd poky + $ cd poky/.. Once in that directory, source the build environment script:: - $ source oe-init-build-env + $ source poky/oe-init-build-env Next, from the build directory (e.g. ``poky/build``), start Toaster using this command::
@@ -437,9 +437,9 @@ Perform the following steps to install Toaster: #export http_proxy=http://proxy.host.com:8080 #export https_proxy=http://proxy.host.com:8080 #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy - cd poky/ - source ./oe-init-build-env build - source ../bitbake/bin/toaster $1 noweb + cd poky/.. + source poky/oe-init-build-env build + source ../poky/bitbake/bin/toaster $1 noweb [ "$1" == 'start' ] && /bin/bash #. Run the service::
Signature · 1 line
2.34.1
I would wait until the proposed oe-setup-build tool lands in master, and then adjust the documentation to recommend that to set up builds.
The tool already does what you suggest, e.g. makes sensible choices for build directories, and without requiring users to make those decisions.
Do you have a moment to review that?
Alex
Quoted 285 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
Recommending to build typically from the parent directory in which poky was cloned, or another directory.
---
I'm proposing to guide users to avoid building from the source directory. That's already recommended in
dev-manual/common-tasks.rst:In any event, it's typically cleaner to locate the build directory somewhere outside of your source directory.
I've only made quick changes so far, but if we agree to go in this direction, I will cautiously adapt the instructions so that they look natural (not asking to run "cd poky/.." for example).
What do you think? Wouldn't it be cleaner?
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/brief-yoctoprojectqs/index.rst | 12 +++++------- documentation/bsp-guide/bsp.rst | 6 +++--- documentation/dev-manual/common-tasks.rst | 5 ++--- documentation/dev-manual/qemu.rst | 3 +-- documentation/kernel-dev/common.rst | 10 +++++----- documentation/profile-manual/usage.rst | 4 ++-- documentation/ref-manual/structure.rst | 4 ++-- documentation/ref-manual/terms.rst | 8 -------- documentation/sdk-manual/appendix-obtain.rst | 4 ++-- documentation/toaster-manual/setup-and-use.rst | 12 ++++++------ 10 files changed, 28 insertions(+), 40 deletions(-)documentation/brief-yoctoprojectqs/index.rst +5
-7@@ -184,16 +184,14 @@ an entire Linux distribution, including the toolchain, from source. ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" page of the Yocto Project Wiki. -#. **Initialize the Build Environment:** From within the ``poky`` - directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` - environment - setup script to define Yocto Project's build environment on your +#. **Initialize the Build Environment:** From within the parent directory of + the ``poky`` directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` + environment setup script to define Yocto Project's build environment on your build host. .. code-block:: shell - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env You had no conf/local.conf file. This configuration file has therefore been created for you with some default values. You may wish to edit it to, for example, select a different MACHINE (target hardware). See conf/local.conf@@ -361,7 +359,7 @@ Follow these steps to add a hardware layer: .. code-block:: shell - $ cd poky/build + $ cd build $ bitbake-layers add-layer ../meta-altera NOTE: Starting bitbake server... Parsing recipes: 100% |##################################################################| Time: 0:00:32documentation/bsp-guide/bsp.rst +3
-3@@ -228,13 +228,13 @@ section. Resolving deltas: 100% (2447/2447), done. Checking connectivity... done. -#. *Initialize the Build Environment:* While in the root directory of - the Source Directory (i.e. ``poky``), run the +#. *Initialize the Build Environment:* Outside of the the Source Directory + (i.e. ``poky``), for example in the parent directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment setup script to define the OpenEmbedded build environment on your build host. :: - $ source oe-init-build-env + $ source poky/oe-init-build-env Among other things, the script creates the :term:`Build Directory`, which is ``build`` in this case and is located in the :term:`Source Directory`. Afterdocumentation/dev-manual/common-tasks.rst +2
-3@@ -3022,8 +3022,7 @@ The following steps describe how to set up the AUH utility: script to create a fresh build directory that you use exclusively for running the AUH utility:: - $ cd poky - $ source oe-init-build-env your_AUH_build_directory + $ source poky/oe-init-build-env your_AUH_build_directory Re-using an existing build directory and its configurations is not recommended as existing settings could cause AUH to fail or behave@@ -3667,7 +3666,7 @@ The following figure and list overviews the build process: by sourcing the build environment script (i.e. :ref:`structure-core-script`):: - $ source oe-init-build-env [build_dir] + $ source poky/oe-init-build-env [build_dir] When you use the initialization script, the OpenEmbedded build system uses ``build`` as the default :term:`Build Directory` in your current workdocumentation/dev-manual/qemu.rst +1
-2@@ -57,8 +57,7 @@ available. Follow these general steps to run QEMU: unpacked a Yocto Project release tarball, you can source the build environment script (i.e. :ref:`structure-core-script`):: - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env - If you installed a cross-toolchain, you can run the script that initializes the toolchain. For example, the following commands rundocumentation/kernel-dev/common.rst +5
-5@@ -56,8 +56,7 @@ section: you need to initialize the BitBake build environment by sourcing the build environment script (i.e. :ref:`structure-core-script`):: - $ cd poky - $ source oe-init-build-env + $ source poky/oe-init-build-env .. note::@@ -177,7 +176,8 @@ section: $ git branch master * &DISTRO_NAME_NO_CAP; - $ source oe-init-build-env + $ cd .. + $ source poky/oe-init-build-env .. note::@@ -1074,8 +1074,8 @@ The following commands initialize the BitBake environment, run the task, and launch ``menuconfig``. These commands assume the Source Directory's top-level folder is ``poky``:: - $ cd poky - $ source oe-init-build-env + $ cd poky/.. + $ source poky/oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c menuconfigdocumentation/profile-manual/usage.rst +2
-2@@ -1907,8 +1907,8 @@ Running a Script on a Target Once you've done that, you should be able to run a systemtap script on the target:: - $ cd /path/to/yocto - $ source oe-init-build-env + $ cd /path/to/poky/.. + $ source poky/oe-init-build-env ### Shell environment set up for builds. ###documentation/ref-manual/structure.rst +2
-2@@ -158,7 +158,7 @@ directory becomes the Build Directory, and you are presented with some simple suggestions as to what to do next, including a list of some possible targets to build. Here is an example:: - $ source oe-init-build-env + $ source poky/oe-init-build-env ### Shell environment set up for builds. ###@@ -189,7 +189,7 @@ you direct the OpenEmbedded build system to create a Build Directory of your choice. For example, the following command creates a Build Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:: - $ source oe-init-build-env ~/mybuilds + $ source poky/oe-init-build-env ~/mybuilds The OpenEmbedded build system uses the template configuration files, which are found by default in the ``meta-poky/conf/templates/default`` directory in the Sourcedocumentation/ref-manual/terms.rst +0
-8@@ -70,14 +70,6 @@ universal, the list includes them just in case: Following are some examples that show how to create the directory. The examples assume your :term:`Source Directory` is named ``poky``: - - Create the Build Directory inside your Source Directory and let - the name of the Build Directory default to ``build``: - - .. code-block:: shell - - $ cd poky - $ source oe-init-build-env - - Create the Build Directory inside your home directory and specifically name it ``test-builds``:documentation/sdk-manual/appendix-obtain.rst +2
-2@@ -107,14 +107,14 @@ build the SDK installer. Follow these steps: how to clone the ``poky`` repository and check out the appropriate branch for your work. -3. *Initialize the Build Environment:* While in the root directory of +3. *Initialize the Build Environment:* While in the parent directory of the Source Directory (i.e. ``poky``), run the :ref:`structure-core-script` environment setup script to define the OpenEmbedded build environment on your build host. :: - $ source oe-init-build-env + $ source poky/oe-init-build-env Among other things, the script creates the :term:`Build Directory`,documentation/toaster-manual/setup-and-use.rst +6
-7@@ -14,14 +14,14 @@ dependencies as described in the ":ref:`toaster-manual/start:Preparing to Use Toaster`" chapter, you are ready to start Toaster. -Navigate to the root of your +Navigate to the parent directory of the root of your :term:`Source Directory` (e.g. ``poky``):: - $ cd poky + $ cd poky/.. Once in that directory, source the build environment script:: - $ source oe-init-build-env + $ source poky/oe-init-build-env Next, from the build directory (e.g. ``poky/build``), start Toaster using this command::@@ -437,9 +437,9 @@ Perform the following steps to install Toaster: #export http_proxy=http://proxy.host.com:8080 #export https_proxy=http://proxy.host.com:8080 #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy - cd poky/ - source ./oe-init-build-env build - source ../bitbake/bin/toaster $1 noweb + cd poky/.. + source poky/oe-init-build-env build + source ../poky/bitbake/bin/toaster $1 noweb [ "$1" == 'start' ] && /bin/bash #. Run the service:: --2.34.1
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#3360): https://lists.yoctoproject.org/g/docs/message/3360
Mute This Topic: https://lists.yoctoproject.org/mt/94300257/1686489
Group Owner: [email protected]
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [[email protected]]
-=-=-=-=-=-=-=-=-=-=-=-
Hi Alex,
Quoted 8 lines · Alexander Kanavin
I would wait until the proposed oe-setup-build tool lands in master, and then adjust the documentation to recommend that to set up builds.
The tool already does what you suggest, e.g. makes sensible choices for build directories, and without requiring users to make those decisions.
Do you have a moment to review that?
https://git.yoctoproject.org/poky-contrib/commit/?h=akanavin/package-version-updates&id=7659896ce5ea0bfea3a2c04b83915a48f70a5af9
Thanks for these details. Then the timing is perfect.
I missed these interesting discussions and I'm excited to test what will land in master and propose updates to the documentation.
Thanks again!
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com