From bd1789261122c25d62b8e8e7f7d5647249e8d8ff Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Thu, 3 Dec 2020 22:38:34 +0100 Subject: sphinx: rename top level document in each manual It is more common to call the top level document index.rst. This is what this patch is doing, along with all required references fixup. (From yocto-docs rev: 2cea7fbba9210479fc0387d7e1b80da9885558f0) Signed-off-by: Nicolas Dechesne Signed-off-by: Richard Purdie --- .../brief-yoctoprojectqs/brief-yoctoprojectqs.rst | 430 --------------------- documentation/brief-yoctoprojectqs/index.rst | 430 +++++++++++++++++++++ documentation/bsp-guide/bsp-guide.rst | 16 - documentation/bsp-guide/index.rst | 16 + .../dev-manual/dev-manual-common-tasks.rst | 6 +- documentation/dev-manual/dev-manual-intro.rst | 6 +- documentation/dev-manual/dev-manual-start.rst | 2 +- documentation/dev-manual/dev-manual.rst | 19 - documentation/dev-manual/index.rst | 19 + documentation/index.rst | 20 +- documentation/kernel-dev/index.rst | 21 + documentation/kernel-dev/kernel-dev-advanced.rst | 2 +- documentation/kernel-dev/kernel-dev-common.rst | 2 +- documentation/kernel-dev/kernel-dev-intro.rst | 4 +- documentation/kernel-dev/kernel-dev.rst | 21 - documentation/overview-manual/index.rst | 19 + .../overview-manual/overview-manual-concepts.rst | 6 +- .../overview-manual-development-environment.rst | 6 +- .../overview-manual/overview-manual-intro.rst | 10 +- .../overview-manual/overview-manual-yp-intro.rst | 10 +- documentation/overview-manual/overview-manual.rst | 19 - documentation/profile-manual/index.rst | 19 + documentation/profile-manual/profile-manual.rst | 19 - documentation/ref-manual/faq.rst | 2 +- documentation/ref-manual/index.rst | 31 ++ documentation/ref-manual/migration-2.1.rst | 2 +- documentation/ref-manual/ref-features.rst | 4 +- documentation/ref-manual/ref-manual.rst | 31 -- documentation/ref-manual/ref-structure.rst | 2 +- .../ref-manual/ref-system-requirements.rst | 6 +- documentation/ref-manual/ref-terms.rst | 12 +- documentation/ref-manual/ref-variables.rst | 4 +- documentation/ref-manual/resources.rst | 16 +- documentation/sdk-manual/index.rst | 22 ++ documentation/sdk-manual/sdk-manual.rst | 22 -- documentation/test-manual/index.rst | 18 + documentation/test-manual/test-manual.rst | 18 - documentation/toaster-manual/index.rst | 19 + documentation/toaster-manual/toaster-manual.rst | 19 - .../transitioning-to-a-custom-environment.rst | 2 +- documentation/what-i-wish-id-known.rst | 14 +- 41 files changed, 681 insertions(+), 685 deletions(-) delete mode 100644 documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst create mode 100644 documentation/brief-yoctoprojectqs/index.rst delete mode 100644 documentation/bsp-guide/bsp-guide.rst create mode 100644 documentation/bsp-guide/index.rst delete mode 100644 documentation/dev-manual/dev-manual.rst create mode 100644 documentation/dev-manual/index.rst create mode 100644 documentation/kernel-dev/index.rst delete mode 100644 documentation/kernel-dev/kernel-dev.rst create mode 100644 documentation/overview-manual/index.rst delete mode 100644 documentation/overview-manual/overview-manual.rst create mode 100644 documentation/profile-manual/index.rst delete mode 100644 documentation/profile-manual/profile-manual.rst create mode 100644 documentation/ref-manual/index.rst delete mode 100644 documentation/ref-manual/ref-manual.rst create mode 100644 documentation/sdk-manual/index.rst delete mode 100644 documentation/sdk-manual/sdk-manual.rst create mode 100644 documentation/test-manual/index.rst delete mode 100644 documentation/test-manual/test-manual.rst create mode 100644 documentation/toaster-manual/index.rst delete mode 100644 documentation/toaster-manual/toaster-manual.rst (limited to 'documentation') diff --git a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst deleted file mode 100644 index 8772812ebd..0000000000 --- a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -========================= -Yocto Project Quick Build -========================= - -Welcome! -======== - -This short document steps you through the process for a typical -image build using the Yocto Project. The document also introduces how to -configure a build for specific hardware. You will use Yocto Project to -build a reference embedded OS called Poky. - -.. note:: - - - The examples in this paper assume you are using a native Linux - system running a recent Ubuntu Linux distribution. If the machine - you want to use Yocto Project on to build an image - (:term:`Build Host`) is not - a native Linux system, you can still perform these steps by using - CROss PlatformS (CROPS) and setting up a Poky container. See the - :ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)` - section - in the Yocto Project Development Tasks Manual for more - information. - - - You may use Windows Subsystem For Linux v2 to set up a build host - using Windows 10. - - .. note:: - - The Yocto Project is not compatible with WSLv1, it is - compatible but not officially supported nor validated with - WSLv2, if you still decide to use WSL please upgrade to WSLv2. - - See the :ref:`dev-manual/dev-manual-start:setting up to use windows - subsystem for linux (wslv2)` section in the Yocto Project Development - Tasks Manual for more information. - -If you want more conceptual or background information on the Yocto -Project, see the :doc:`../overview-manual/overview-manual`. - -Compatible Linux Distribution -============================= - -Make sure your :term:`Build Host` meets the -following requirements: - -- 50 Gbytes of free disk space - -- Runs a supported Linux distribution (i.e. recent releases of Fedora, - openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux - distributions that support the Yocto Project, see the - :ref:`ref-manual/ref-system-requirements:supported linux distributions` - section in the Yocto Project Reference Manual. For detailed - information on preparing your build host, see the - :ref:`dev-manual/dev-manual-start:preparing the build host` - section in the Yocto Project Development Tasks Manual. - -- - - - Git 1.8.3.1 or greater - - tar 1.28 or greater - - Python 3.5.0 or greater. - - gcc 5.0 or greater. - -If your build host does not meet any of these three listed version -requirements, you can take steps to prepare the system so that you -can still use the Yocto Project. See the -:ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions` -section in the Yocto Project Reference Manual for information. - -Build Host Packages -=================== - -You must install essential host packages on your build host. The -following command installs the host packages based on an Ubuntu -distribution: - -.. code-block:: shell - - $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; - -.. note:: - - For host package requirements on all supported Linux distributions, - see the :ref:`ref-manual/ref-system-requirements:required packages for the build host` - section in the Yocto Project Reference Manual. - -Use Git to Clone Poky -===================== - -Once you complete the setup instructions for your machine, you need to -get a copy of the Poky repository on your build host. Use the following -commands to clone the Poky repository. - -.. code-block:: shell - - $ git clone git://git.yoctoproject.org/poky - Cloning into 'poky'... - remote: Counting - objects: 432160, done. remote: Compressing objects: 100% - (102056/102056), done. remote: Total 432160 (delta 323116), reused - 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. - Resolving deltas: 100% (323116/323116), done. - Checking connectivity... done. - -Move to the ``poky`` directory and take a look at the tags: - -.. code-block:: shell - - $ cd poky - $ git fetch --tags - $ git tag - 1.1_M1.final - 1.1_M1.rc1 - 1.1_M1.rc2 - 1.1_M2.final - 1.1_M2.rc1 - . - . - . - yocto-2.5 - yocto-2.5.1 - yocto-2.5.2 - yocto-2.6 - yocto-2.6.1 - yocto-2.6.2 - yocto-2.7 - yocto_1.5_M5.rc8 - -For this example, check out the branch based on the -``&DISTRO_REL_TAG;`` release: - -.. code-block:: shell - - $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; - Switched to a new branch 'my-&DISTRO_REL_TAG;' - -The previous Git checkout command creates a local branch named -``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly -match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development -branch at the time of the Yocto Project &DISTRO_REL_TAG; release. - -For more options and information about accessing Yocto Project related -repositories, see the -:ref:`dev-manual/dev-manual-start:locating yocto project source files` -section in the Yocto Project Development Tasks Manual. - -Building Your Image -=================== - -Use the following steps to build your image. The build process creates -an entire Linux distribution, including the toolchain, from source. - -.. note:: - - - If you are working behind a firewall and your build host is not - set up for proxies, you could encounter problems with the build - process when fetching source code (e.g. fetcher failures or Git - failures). - - - If you do not know your proxy settings, consult your local network - infrastructure resources and get that information. A good starting - point could also be to check your web browser settings. Finally, - you can find more information on the - ":yocto_wiki:`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/ref-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 - 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 - for more information as common configuration options are commented. - - You had no conf/bblayers.conf file. This configuration file has therefore - been created for you with some default values. To add additional metadata - layers into your configuration please add entries to conf/bblayers.conf. - - The Yocto Project has extensive documentation about OE including a reference - manual which can be found at: - http://yoctoproject.org/documentation - - For more information about OpenEmbedded see their website: - http://www.openembedded.org/ - - ### Shell environment set up for builds. ### - - You can now run 'bitbake ' - - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-ide-support - - You can also run generated qemu images with a command like 'runqemu qemux86-64' - - 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 - the script runs, your current working directory is set to the Build - Directory. Later, when the build completes, the Build Directory contains all the - files created during the build. - -#. **Examine Your Local Configuration File:** When you set up the build - environment, a local configuration file named ``local.conf`` becomes - available in a ``conf`` subdirectory of the Build Directory. For this - example, the defaults are set to build for a ``qemux86`` target, - which is suitable for emulation. The package manager used is set to - the RPM package manager. - - .. tip:: - - You can significantly speed up your build and guard against fetcher - failures by using mirrors. To use mirrors, add these lines to your - local.conf file in the Build directory: :: - - SSTATE_MIRRORS = "\ - file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ - " - - - The previous examples showed how to add sstate paths for Yocto Project - &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development - area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. - -#. **Start the Build:** Continue with the following command to build an OS - image for the target, which is ``core-image-sato`` in this example: - - .. code-block:: shell - - $ bitbake core-image-sato - - For information on using the ``bitbake`` command, see the - :ref:`overview-manual/overview-manual-concepts:bitbake` section in the Yocto Project Overview and - Concepts Manual, or see the ":ref:`BitBake Command - `" section in the BitBake User Manual. - -#. **Simulate Your Image Using QEMU:** Once this particular image is - built, you can start QEMU, which is a Quick EMUlator that ships with - the Yocto Project: - - .. code-block:: shell - - $ runqemu qemux86-64 - - If you want to learn more about running QEMU, see the - :ref:`dev-manual/dev-manual-qemu:using the quick emulator (qemu)` chapter in - the Yocto Project Development Tasks Manual. - -#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing - ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. - -Customizing Your Build for Specific Hardware -============================================ - -So far, all you have done is quickly built an image suitable for -emulation only. This section shows you how to customize your build for -specific hardware by adding a hardware layer into the Yocto Project -development environment. - -In general, layers are repositories that contain related sets of -instructions and configurations that tell the Yocto Project what to do. -Isolating related metadata into functionally specific layers facilitates -modular development and makes it easier to reuse the layer metadata. - -.. note:: - - By convention, layer names start with the string "meta-". - -Follow these steps to add a hardware layer: - -#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project - :yocto_git:`Source Repositories <>` has many hardware layers. - This example adds the - `meta-altera `__ hardware layer. - -#. **Clone the Layer:** Use Git to make a local copy of the layer on your - machine. You can put the copy in the top level of the copy of the - Poky repository created earlier: - - .. code-block:: shell - - $ cd ~/poky - $ git clone https://github.com/kraj/meta-altera.git - Cloning into 'meta-altera'... - remote: Counting objects: 25170, done. - remote: Compressing objects: 100% (350/350), done. - remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 - Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. - Resolving deltas: 100% (13385/13385), done. - Checking connectivity... done. - - The hardware layer now exists - with other layers inside the Poky reference repository on your build - host as ``meta-altera`` and contains all the metadata needed to - support hardware from Altera, which is owned by Intel. - - .. note:: - - It is recommended for layers to have a branch per Yocto Project release. - Please make sure to checkout the layer branch supporting the Yocto Project - release you're using. - -#. **Change the Configuration to Build for a Specific Machine:** The - :term:`MACHINE` variable in the - ``local.conf`` file specifies the machine for the build. For this - example, set the ``MACHINE`` variable to ``cyclone5``. These - configurations are used: - https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. - - .. note:: - - See the "Examine Your Local Configuration File" step earlier for more - information on configuring the build. - -#. **Add Your Layer to the Layer Configuration File:** Before you can use - a layer during a build, you must add it to your ``bblayers.conf`` - file, which is found in the - :term:`Build Directory` ``conf`` - directory. - - Use the ``bitbake-layers add-layer`` command to add the layer to the - configuration file: - - .. code-block:: shell - - $ cd ~/poky/build - $ bitbake-layers add-layer ../meta-altera - NOTE: Starting bitbake server... - Parsing recipes: 100% |##################################################################| Time: 0:00:32 - Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, - 123 skipped, 0 masked, 0 errors. - - You can find - more information on adding layers in the - :ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` - section. - -Completing these steps has added the ``meta-altera`` layer to your Yocto -Project development environment and configured it to build for the -``cyclone5`` machine. - -.. note:: - - The previous steps are for demonstration purposes only. If you were - to attempt to build an image for the ``cyclone5`` machine, you should - read the Altera ``README``. - -Creating Your Own General Layer -=============================== - -Maybe you have an application or specific set of behaviors you need to -isolate. You can create your own general layer using the -``bitbake-layers create-layer`` command. The tool automates layer -creation by setting up a subdirectory with a ``layer.conf`` -configuration file, a ``recipes-example`` subdirectory that contains an -``example.bb`` recipe, a licensing file, and a ``README``. - -The following commands run the tool to create a layer named -``meta-mylayer`` in the ``poky`` directory: - -.. code-block:: shell - - $ cd ~/poky - $ bitbake-layers create-layer meta-mylayer - NOTE: Starting bitbake server... - Add your new layer with 'bitbake-layers add-layer meta-mylayer' - -For more information -on layers and how to create them, see the -:ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` -section in the Yocto Project Development Tasks Manual. - -Where To Go Next -================ - -Now that you have experienced using the Yocto Project, you might be -asking yourself "What now?". The Yocto Project has many sources of -information including the website, wiki pages, and user manuals: - -- **Website:** The :yocto_home:`Yocto Project Website <>` provides - background information, the latest builds, breaking news, full - development documentation, and access to a rich Yocto Project - Development Community into which you can tap. - -- **Developer Screencast:** The `Getting Started with the Yocto Project - - New Developer Screencast Tutorial `__ - provides a 30-minute video created for users unfamiliar with the - Yocto Project but familiar with Linux build hosts. While this - screencast is somewhat dated, the introductory and fundamental - concepts are useful for the beginner. - -- **Yocto Project Overview and Concepts Manual:** The - :doc:`../overview-manual/overview-manual` is a great - place to start to learn about the Yocto Project. This manual - introduces you to the Yocto Project and its development environment. - The manual also provides conceptual information for various aspects - of the Yocto Project. - -- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>` - provides additional information on where to go next when ramping up - with the Yocto Project, release information, project planning, and QA - information. - -- **Yocto Project Mailing Lists:** Related mailing lists provide a forum - for discussion, patch submission and announcements. Several mailing - lists exist and are grouped according to areas of concern. See the - :ref:`ref-manual/resources:mailing lists` - section in the Yocto Project Reference Manual for a complete list of - Yocto Project mailing lists. - -- **Comprehensive List of Links and Other Documentation:** The - :ref:`ref-manual/resources:links and related documentation` - section in the Yocto Project Reference Manual provides a - comprehensive list of all related links and other user documentation. - -.. include:: /boilerplate.rst diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst new file mode 100644 index 0000000000..e8912f07ca --- /dev/null +++ b/documentation/brief-yoctoprojectqs/index.rst @@ -0,0 +1,430 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +========================= +Yocto Project Quick Build +========================= + +Welcome! +======== + +This short document steps you through the process for a typical +image build using the Yocto Project. The document also introduces how to +configure a build for specific hardware. You will use Yocto Project to +build a reference embedded OS called Poky. + +.. note:: + + - The examples in this paper assume you are using a native Linux + system running a recent Ubuntu Linux distribution. If the machine + you want to use Yocto Project on to build an image + (:term:`Build Host`) is not + a native Linux system, you can still perform these steps by using + CROss PlatformS (CROPS) and setting up a Poky container. See the + :ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)` + section + in the Yocto Project Development Tasks Manual for more + information. + + - You may use Windows Subsystem For Linux v2 to set up a build host + using Windows 10. + + .. note:: + + The Yocto Project is not compatible with WSLv1, it is + compatible but not officially supported nor validated with + WSLv2, if you still decide to use WSL please upgrade to WSLv2. + + See the :ref:`dev-manual/dev-manual-start:setting up to use windows + subsystem for linux (wslv2)` section in the Yocto Project Development + Tasks Manual for more information. + +If you want more conceptual or background information on the Yocto +Project, see the :doc:`../overview-manual/index`. + +Compatible Linux Distribution +============================= + +Make sure your :term:`Build Host` meets the +following requirements: + +- 50 Gbytes of free disk space + +- Runs a supported Linux distribution (i.e. recent releases of Fedora, + openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux + distributions that support the Yocto Project, see the + :ref:`ref-manual/ref-system-requirements:supported linux distributions` + section in the Yocto Project Reference Manual. For detailed + information on preparing your build host, see the + :ref:`dev-manual/dev-manual-start:preparing the build host` + section in the Yocto Project Development Tasks Manual. + +- + + - Git 1.8.3.1 or greater + - tar 1.28 or greater + - Python 3.5.0 or greater. + - gcc 5.0 or greater. + +If your build host does not meet any of these three listed version +requirements, you can take steps to prepare the system so that you +can still use the Yocto Project. See the +:ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions` +section in the Yocto Project Reference Manual for information. + +Build Host Packages +=================== + +You must install essential host packages on your build host. The +following command installs the host packages based on an Ubuntu +distribution: + +.. code-block:: shell + + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; + +.. note:: + + For host package requirements on all supported Linux distributions, + see the :ref:`ref-manual/ref-system-requirements:required packages for the build host` + section in the Yocto Project Reference Manual. + +Use Git to Clone Poky +===================== + +Once you complete the setup instructions for your machine, you need to +get a copy of the Poky repository on your build host. Use the following +commands to clone the Poky repository. + +.. code-block:: shell + + $ git clone git://git.yoctoproject.org/poky + Cloning into 'poky'... + remote: Counting + objects: 432160, done. remote: Compressing objects: 100% + (102056/102056), done. remote: Total 432160 (delta 323116), reused + 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. + Resolving deltas: 100% (323116/323116), done. + Checking connectivity... done. + +Move to the ``poky`` directory and take a look at the tags: + +.. code-block:: shell + + $ cd poky + $ git fetch --tags + $ git tag + 1.1_M1.final + 1.1_M1.rc1 + 1.1_M1.rc2 + 1.1_M2.final + 1.1_M2.rc1 + . + . + . + yocto-2.5 + yocto-2.5.1 + yocto-2.5.2 + yocto-2.6 + yocto-2.6.1 + yocto-2.6.2 + yocto-2.7 + yocto_1.5_M5.rc8 + +For this example, check out the branch based on the +``&DISTRO_REL_TAG;`` release: + +.. code-block:: shell + + $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; + Switched to a new branch 'my-&DISTRO_REL_TAG;' + +The previous Git checkout command creates a local branch named +``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly +match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development +branch at the time of the Yocto Project &DISTRO_REL_TAG; release. + +For more options and information about accessing Yocto Project related +repositories, see the +:ref:`dev-manual/dev-manual-start:locating yocto project source files` +section in the Yocto Project Development Tasks Manual. + +Building Your Image +=================== + +Use the following steps to build your image. The build process creates +an entire Linux distribution, including the toolchain, from source. + +.. note:: + + - If you are working behind a firewall and your build host is not + set up for proxies, you could encounter problems with the build + process when fetching source code (e.g. fetcher failures or Git + failures). + + - If you do not know your proxy settings, consult your local network + infrastructure resources and get that information. A good starting + point could also be to check your web browser settings. Finally, + you can find more information on the + ":yocto_wiki:`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/ref-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 + 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 + for more information as common configuration options are commented. + + You had no conf/bblayers.conf file. This configuration file has therefore + been created for you with some default values. To add additional metadata + layers into your configuration please add entries to conf/bblayers.conf. + + The Yocto Project has extensive documentation about OE including a reference + manual which can be found at: + http://yoctoproject.org/documentation + + For more information about OpenEmbedded see their website: + http://www.openembedded.org/ + + ### Shell environment set up for builds. ### + + You can now run 'bitbake ' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + meta-ide-support + + You can also run generated qemu images with a command like 'runqemu qemux86-64' + + 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 + the script runs, your current working directory is set to the Build + Directory. Later, when the build completes, the Build Directory contains all the + files created during the build. + +#. **Examine Your Local Configuration File:** When you set up the build + environment, a local configuration file named ``local.conf`` becomes + available in a ``conf`` subdirectory of the Build Directory. For this + example, the defaults are set to build for a ``qemux86`` target, + which is suitable for emulation. The package manager used is set to + the RPM package manager. + + .. tip:: + + You can significantly speed up your build and guard against fetcher + failures by using mirrors. To use mirrors, add these lines to your + local.conf file in the Build directory: :: + + SSTATE_MIRRORS = "\ + file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ + file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ + file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ + " + + + The previous examples showed how to add sstate paths for Yocto Project + &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development + area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. + +#. **Start the Build:** Continue with the following command to build an OS + image for the target, which is ``core-image-sato`` in this example: + + .. code-block:: shell + + $ bitbake core-image-sato + + For information on using the ``bitbake`` command, see the + :ref:`overview-manual/overview-manual-concepts:bitbake` section in the Yocto Project Overview and + Concepts Manual, or see the ":ref:`BitBake Command + `" section in the BitBake User Manual. + +#. **Simulate Your Image Using QEMU:** Once this particular image is + built, you can start QEMU, which is a Quick EMUlator that ships with + the Yocto Project: + + .. code-block:: shell + + $ runqemu qemux86-64 + + If you want to learn more about running QEMU, see the + :ref:`dev-manual/dev-manual-qemu:using the quick emulator (qemu)` chapter in + the Yocto Project Development Tasks Manual. + +#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing + ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. + +Customizing Your Build for Specific Hardware +============================================ + +So far, all you have done is quickly built an image suitable for +emulation only. This section shows you how to customize your build for +specific hardware by adding a hardware layer into the Yocto Project +development environment. + +In general, layers are repositories that contain related sets of +instructions and configurations that tell the Yocto Project what to do. +Isolating related metadata into functionally specific layers facilitates +modular development and makes it easier to reuse the layer metadata. + +.. note:: + + By convention, layer names start with the string "meta-". + +Follow these steps to add a hardware layer: + +#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project + :yocto_git:`Source Repositories <>` has many hardware layers. + This example adds the + `meta-altera `__ hardware layer. + +#. **Clone the Layer:** Use Git to make a local copy of the layer on your + machine. You can put the copy in the top level of the copy of the + Poky repository created earlier: + + .. code-block:: shell + + $ cd ~/poky + $ git clone https://github.com/kraj/meta-altera.git + Cloning into 'meta-altera'... + remote: Counting objects: 25170, done. + remote: Compressing objects: 100% (350/350), done. + remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 + Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. + Resolving deltas: 100% (13385/13385), done. + Checking connectivity... done. + + The hardware layer now exists + with other layers inside the Poky reference repository on your build + host as ``meta-altera`` and contains all the metadata needed to + support hardware from Altera, which is owned by Intel. + + .. note:: + + It is recommended for layers to have a branch per Yocto Project release. + Please make sure to checkout the layer branch supporting the Yocto Project + release you're using. + +#. **Change the Configuration to Build for a Specific Machine:** The + :term:`MACHINE` variable in the + ``local.conf`` file specifies the machine for the build. For this + example, set the ``MACHINE`` variable to ``cyclone5``. These + configurations are used: + https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. + + .. note:: + + See the "Examine Your Local Configuration File" step earlier for more + information on configuring the build. + +#. **Add Your Layer to the Layer Configuration File:** Before you can use + a layer during a build, you must add it to your ``bblayers.conf`` + file, which is found in the + :term:`Build Directory` ``conf`` + directory. + + Use the ``bitbake-layers add-layer`` command to add the layer to the + configuration file: + + .. code-block:: shell + + $ cd ~/poky/build + $ bitbake-layers add-layer ../meta-altera + NOTE: Starting bitbake server... + Parsing recipes: 100% |##################################################################| Time: 0:00:32 + Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, + 123 skipped, 0 masked, 0 errors. + + You can find + more information on adding layers in the + :ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` + section. + +Completing these steps has added the ``meta-altera`` layer to your Yocto +Project development environment and configured it to build for the +``cyclone5`` machine. + +.. note:: + + The previous steps are for demonstration purposes only. If you were + to attempt to build an image for the ``cyclone5`` machine, you should + read the Altera ``README``. + +Creating Your Own General Layer +=============================== + +Maybe you have an application or specific set of behaviors you need to +isolate. You can create your own general layer using the +``bitbake-layers create-layer`` command. The tool automates layer +creation by setting up a subdirectory with a ``layer.conf`` +configuration file, a ``recipes-example`` subdirectory that contains an +``example.bb`` recipe, a licensing file, and a ``README``. + +The following commands run the tool to create a layer named +``meta-mylayer`` in the ``poky`` directory: + +.. code-block:: shell + + $ cd ~/poky + $ bitbake-layers create-layer meta-mylayer + NOTE: Starting bitbake server... + Add your new layer with 'bitbake-layers add-layer meta-mylayer' + +For more information +on layers and how to create them, see the +:ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` +section in the Yocto Project Development Tasks Manual. + +Where To Go Next +================ + +Now that you have experienced using the Yocto Project, you might be +asking yourself "What now?". The Yocto Project has many sources of +information including the website, wiki pages, and user manuals: + +- **Website:** The :yocto_home:`Yocto Project Website <>` provides + background information, the latest builds, breaking news, full + development documentation, and access to a rich Yocto Project + Development Community into which you can tap. + +- **Developer Screencast:** The `Getting Started with the Yocto Project - + New Developer Screencast Tutorial `__ + provides a 30-minute video created for users unfamiliar with the + Yocto Project but familiar with Linux build hosts. While this + screencast is somewhat dated, the introductory and fundamental + concepts are useful for the beginner. + +- **Yocto Project Overview and Concepts Manual:** The + :doc:`../overview-manual/index` is a great + place to start to learn about the Yocto Project. This manual + introduces you to the Yocto Project and its development environment. + The manual also provides conceptual information for various aspects + of the Yocto Project. + +- **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>` + provides additional information on where to go next when ramping up + with the Yocto Project, release information, project planning, and QA + information. + +- **Yocto Project Mailing Lists:** Related mailing lists provide a forum + for discussion, patch submission and announcements. Several mailing + lists exist and are grouped according to areas of concern. See the + :ref:`ref-manual/resources:mailing lists` + section in the Yocto Project Reference Manual for a complete list of + Yocto Project mailing lists. + +- **Comprehensive List of Links and Other Documentation:** The + :ref:`ref-manual/resources:links and related documentation` + section in the Yocto Project Reference Manual provides a + comprehensive list of all related links and other user documentation. + +.. include:: /boilerplate.rst diff --git a/documentation/bsp-guide/bsp-guide.rst b/documentation/bsp-guide/bsp-guide.rst deleted file mode 100644 index a4394a85ed..0000000000 --- a/documentation/bsp-guide/bsp-guide.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -===================================================== -Yocto Project Board Support Package Developer's Guide -===================================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - bsp - history - -.. include:: /boilerplate.rst diff --git a/documentation/bsp-guide/index.rst b/documentation/bsp-guide/index.rst new file mode 100644 index 0000000000..a4394a85ed --- /dev/null +++ b/documentation/bsp-guide/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +===================================================== +Yocto Project Board Support Package Developer's Guide +===================================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + bsp + history + +.. include:: /boilerplate.rst diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst index 891fd9b001..e22bcd50ec 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.rst +++ b/documentation/dev-manual/dev-manual-common-tasks.rst @@ -3644,7 +3644,7 @@ build host running Linux. - For information on how to build an image using :term:`Toaster`, see the - :doc:`../toaster-manual/toaster-manual`. + :doc:`../toaster-manual/index`. - For information on how to use ``devtool`` to build images, see the ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`" @@ -3653,7 +3653,7 @@ build host running Linux. - For a quick example on how to build an image using the OpenEmbedded build system, see the - :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. + :doc:`../brief-yoctoprojectqs/index` document. The build process creates an entire Linux distribution from source and places it in your :term:`Build Directory` under @@ -3728,7 +3728,7 @@ The following figure and list overviews the build process: kernels built by the OpenEmbedded build system are placed in the Build Directory in ``tmp/deploy/images``. For information on how to run pre-built images such as ``qemux86`` and ``qemuarm``, see the - :doc:`../sdk-manual/sdk-manual` manual. For + :doc:`../sdk-manual/index` manual. For information about how to install these images, see the documentation for your particular board or machine. diff --git a/documentation/dev-manual/dev-manual-intro.rst b/documentation/dev-manual/dev-manual-intro.rst index 9bbac9610c..94c481b7d8 100644 --- a/documentation/dev-manual/dev-manual-intro.rst +++ b/documentation/dev-manual/dev-manual-intro.rst @@ -31,13 +31,13 @@ This manual provides the following: This manual does not provide the following: - Redundant Step-by-step Instructions: For example, the - :doc:`../sdk-manual/sdk-manual` manual contains detailed + :doc:`../sdk-manual/index` manual contains detailed instructions on how to install an SDK, which is used to develop applications for target hardware. - Reference or Conceptual Material: This type of material resides in an appropriate reference manual. For example, system variables are - documented in the :doc:`../ref-manual/ref-manual`. + documented in the :doc:`../ref-manual/index`. - Detailed Public Information Not Specific to the Yocto Project: For example, exhaustive information on how to use the Source Control @@ -52,7 +52,7 @@ supplemental information is recommended for full comprehension. For introductory information on the Yocto Project, see the :yocto_home:`Yocto Project Website <>`. If you want to build an image with no knowledge of Yocto Project as a way of quickly testing it out, see the -:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. +:doc:`../brief-yoctoprojectqs/index` document. For a comprehensive list of links and other documentation, see the ":ref:`ref-manual/resources:links and related documentation`" diff --git a/documentation/dev-manual/dev-manual-start.rst b/documentation/dev-manual/dev-manual-start.rst index 1c2314c430..053f09cdcd 100644 --- a/documentation/dev-manual/dev-manual-start.rst +++ b/documentation/dev-manual/dev-manual-start.rst @@ -344,7 +344,7 @@ going to use BitBake, see the section. If you are going to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto Project Application Development and the Extensible Software Development -Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use +Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/index`. If you are going to use Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" section in the Toaster User Manual. diff --git a/documentation/dev-manual/dev-manual.rst b/documentation/dev-manual/dev-manual.rst deleted file mode 100644 index 8f09224fe8..0000000000 --- a/documentation/dev-manual/dev-manual.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -====================================== -Yocto Project Development Tasks Manual -====================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - dev-manual-intro - dev-manual-start - dev-manual-common-tasks - dev-manual-qemu - history - -.. include:: /boilerplate.rst diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst new file mode 100644 index 0000000000..8f09224fe8 --- /dev/null +++ b/documentation/dev-manual/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +====================================== +Yocto Project Development Tasks Manual +====================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + dev-manual-intro + dev-manual-start + dev-manual-common-tasks + dev-manual-qemu + history + +.. include:: /boilerplate.rst diff --git a/documentation/index.rst b/documentation/index.rst index 2891a98621..9f41daf4b4 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -14,7 +14,7 @@ Welcome to the Yocto Project Documentation :maxdepth: 1 :caption: Introduction and Overview - Quick Build + Quick Build what-i-wish-id-known transitioning-to-a-custom-environment Yocto Project Software Overview @@ -25,15 +25,15 @@ Welcome to the Yocto Project Documentation :maxdepth: 1 :caption: Manuals - Overview and Concepts Manual - Reference Manual - Board Support Package (BSP) Developer's guide - Development Tasks Manual - Linux Kernel Development Manual - Profile and Tracing Manual - Application Development and the Extensible SDK (eSDK) - Toaster Manual - Test Environment Manual + Overview and Concepts Manual + Reference Manual + Board Support Package (BSP) Developer's guide + Development Tasks Manual + Linux Kernel Development Manual + Profile and Tracing Manual + Application Development and the Extensible SDK (eSDK) + Toaster Manual + Test Environment Manual Bitbake User Manual .. toctree:: diff --git a/documentation/kernel-dev/index.rst b/documentation/kernel-dev/index.rst new file mode 100644 index 0000000000..55b42ed992 --- /dev/null +++ b/documentation/kernel-dev/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +============================================= +Yocto Project Linux Kernel Development Manual +============================================= + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + kernel-dev-intro + kernel-dev-common + kernel-dev-advanced + kernel-dev-concepts-appx + kernel-dev-maint-appx + kernel-dev-faq + history + +.. include:: /boilerplate.rst diff --git a/documentation/kernel-dev/kernel-dev-advanced.rst b/documentation/kernel-dev/kernel-dev-advanced.rst index db0a1eb2e5..cc48343257 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.rst +++ b/documentation/kernel-dev/kernel-dev-advanced.rst @@ -474,7 +474,7 @@ supported kernel type. This section overviews the BSP description structure, the aggregation concepts, and presents a detailed example using a BSP supported by the Yocto Project (i.e. BeagleBone Board). For complete information on BSP -layer file hierarchy, see the :doc:`../bsp-guide/bsp-guide`. +layer file hierarchy, see the :doc:`../bsp-guide/index`. Description Overview ~~~~~~~~~~~~~~~~~~~~ diff --git a/documentation/kernel-dev/kernel-dev-common.rst b/documentation/kernel-dev/kernel-dev-common.rst index 5115f65f40..c57025c67c 100644 --- a/documentation/kernel-dev/kernel-dev-common.rst +++ b/documentation/kernel-dev/kernel-dev-common.rst @@ -502,7 +502,7 @@ your layer in the following area: .. note:: If you are working on a new machine Board Support Package (BSP), be - sure to refer to the :doc:`../bsp-guide/bsp-guide`. + sure to refer to the :doc:`../bsp-guide/index`. As an example, consider the following append file used by the BSPs in ``meta-yocto-bsp``: diff --git a/documentation/kernel-dev/kernel-dev-intro.rst b/documentation/kernel-dev/kernel-dev-intro.rst index 309c65b4d5..a2961d864d 100644 --- a/documentation/kernel-dev/kernel-dev-intro.rst +++ b/documentation/kernel-dev/kernel-dev-intro.rst @@ -79,9 +79,9 @@ facilitate the process of working with the kernel recipes. If you find you need some additional background, please be sure to review and understand the following documentation: -- :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. +- :doc:`../brief-yoctoprojectqs/index` document. -- :doc:`../overview-manual/overview-manual`. +- :doc:`../overview-manual/index`. - :ref:`devtool workflow ` diff --git a/documentation/kernel-dev/kernel-dev.rst b/documentation/kernel-dev/kernel-dev.rst deleted file mode 100644 index 55b42ed992..0000000000 --- a/documentation/kernel-dev/kernel-dev.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -============================================= -Yocto Project Linux Kernel Development Manual -============================================= - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - kernel-dev-intro - kernel-dev-common - kernel-dev-advanced - kernel-dev-concepts-appx - kernel-dev-maint-appx - kernel-dev-faq - history - -.. include:: /boilerplate.rst diff --git a/documentation/overview-manual/index.rst b/documentation/overview-manual/index.rst new file mode 100644 index 0000000000..f20b20e328 --- /dev/null +++ b/documentation/overview-manual/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +========================================== +Yocto Project Overview and Concepts Manual +========================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + overview-manual-intro + overview-manual-yp-intro + overview-manual-development-environment + overview-manual-concepts + history + +.. include:: /boilerplate.rst diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst index 1b522910d2..d79dacbfb8 100644 --- a/documentation/overview-manual/overview-manual-concepts.rst +++ b/documentation/overview-manual/overview-manual-concepts.rst @@ -481,7 +481,7 @@ The BSP Layer provides machine configurations that target specific hardware. Everything in this layer is specific to the machine for which you are building the image or the SDK. A common structure or form is defined for BSP layers. You can learn more about this structure in the -:doc:`../bsp-guide/bsp-guide`. +:doc:`../bsp-guide/index`. .. note:: @@ -1366,7 +1366,7 @@ can initialize the environment before using the tools. section. - For information on setting up a cross-development environment, see - the :doc:`../sdk-manual/sdk-manual` manual. + the :doc:`../sdk-manual/index` manual. All the output files for an SDK are written to the ``deploy/sdk`` folder inside the :term:`Build Directory` as @@ -1446,7 +1446,7 @@ The Yocto Project does most of the work for you when it comes to creating :ref:`sdk-manual/sdk-intro:the cross-development toolchain`. This section provides some technical background on how cross-development toolchains are created and used. For more information on toolchains, you -can also see the :doc:`../sdk-manual/sdk-manual` manual. +can also see the :doc:`../sdk-manual/index` manual. In the Yocto Project development environment, cross-development toolchains are used to build images and applications that run on the diff --git a/documentation/overview-manual/overview-manual-development-environment.rst b/documentation/overview-manual/overview-manual-development-environment.rst index 5baf08946b..36a2462134 100644 --- a/documentation/overview-manual/overview-manual-development-environment.rst +++ b/documentation/overview-manual/overview-manual-development-environment.rst @@ -103,7 +103,7 @@ methods exist for you to do work in the Yocto Project environment: hardware. To development BSPs, you need to take some additional steps beyond what was described in setting up a development host. - The :doc:`../bsp-guide/bsp-guide` provides BSP-related development + The :doc:`../bsp-guide/index` provides BSP-related development information. For specifics on development host preparation, see the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" section in the Yocto Project Board Support Package (BSP) Developer's @@ -114,7 +114,7 @@ methods exist for you to do work in the Yocto Project environment: using ``devtool`` makes kernel development quicker by reducing iteration cycle times. - The :doc:`../kernel-dev/kernel-dev` provides kernel-related + The :doc:`../kernel-dev/index` provides kernel-related development information. For specifics on development host preparation, see the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" @@ -130,7 +130,7 @@ methods exist for you to do work in the Yocto Project environment: For steps that show you how to set up your development host to use Toaster and on how to use Toaster in general, see the - :doc:`../toaster-manual/toaster-manual`. + :doc:`../toaster-manual/index`. Yocto Project Source Repositories ================================= diff --git a/documentation/overview-manual/overview-manual-intro.rst b/documentation/overview-manual/overview-manual-intro.rst index f69824da99..c6fb53ca20 100644 --- a/documentation/overview-manual/overview-manual-intro.rst +++ b/documentation/overview-manual/overview-manual-intro.rst @@ -37,17 +37,17 @@ This manual does not give you the following: - *Step-by-step Instructions for Development Tasks:* Instructional procedures reside in other manuals within the Yocto Project - documentation set. For example, the :doc:`../dev-manual/dev-manual` + documentation set. For example, the :doc:`../dev-manual/index` provides examples on how to perform various development tasks. As another example, the - :doc:`../sdk-manual/sdk-manual` manual contains detailed + :doc:`../sdk-manual/index` manual contains detailed instructions on how to install an SDK, which is used to develop applications for target hardware. - *Reference Material:* This type of material resides in an appropriate reference manual. For example, system variables are documented in the - :doc:`../ref-manual/ref-manual`. As another - example, the :doc:`../bsp-guide/bsp-guide` contains reference information on + :doc:`../ref-manual/index`. As another + example, the :doc:`../bsp-guide/index` contains reference information on BSPs. - *Detailed Public Information Not Specific to the Yocto Project:* For @@ -63,7 +63,7 @@ supplemental information is recommended for full comprehension. For additional introductory information on the Yocto Project, see the :yocto_home:`Yocto Project Website <>`. If you want to build an image with no knowledge of Yocto Project as a way of quickly testing it out, -see the :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. +see the :doc:`../brief-yoctoprojectqs/index` document. For a comprehensive list of links and other documentation, see the ":ref:`Links and Related Documentation `" diff --git a/documentation/overview-manual/overview-manual-yp-intro.rst b/documentation/overview-manual/overview-manual-yp-intro.rst index 2b9ea91490..bf12a673bb 100644 --- a/documentation/overview-manual/overview-manual-yp-intro.rst +++ b/documentation/overview-manual/overview-manual-yp-intro.rst @@ -251,7 +251,7 @@ accomplish this through a recipe that is a BitBake append .. note:: For general information on BSP layer structure, see the - :doc:`../bsp-guide/bsp-guide` + :doc:`../bsp-guide/index` . The :term:`Source Directory` @@ -339,12 +339,12 @@ applications using the Yocto Project: experience supplemented with the powerful set of ``devtool`` commands tailored for the Yocto Project environment. - For information on the eSDK, see the :doc:`../sdk-manual/sdk-manual` Manual. + For information on the eSDK, see the :doc:`../sdk-manual/index` Manual. - *Toaster:* Toaster is a web interface to the Yocto Project OpenEmbedded build system. Toaster allows you to configure, run, and view information about builds. For information on Toaster, see the - :doc:`../toaster-manual/toaster-manual`. + :doc:`../toaster-manual/index`. Production Tools ---------------- @@ -650,7 +650,7 @@ Project. configure and start builds on multiple remote build servers. For information about and how to use Toaster, see the - :doc:`../toaster-manual/toaster-manual`. + :doc:`../toaster-manual/index`. Reference Embedded Distribution (Poky) ====================================== @@ -812,7 +812,7 @@ helpful for getting started: application developers. This eSDK allows developers to incorporate their library and programming changes back into the image to make their code available to other application developers. For information - on the eSDK, see the :doc:`../sdk-manual/sdk-manual` manual. + on the eSDK, see the :doc:`../sdk-manual/index` manual. - *Layer:* A collection of related recipes. Layers allow you to consolidate related metadata to customize your build. Layers also diff --git a/documentation/overview-manual/overview-manual.rst b/documentation/overview-manual/overview-manual.rst deleted file mode 100644 index f20b20e328..0000000000 --- a/documentation/overview-manual/overview-manual.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -========================================== -Yocto Project Overview and Concepts Manual -========================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - overview-manual-intro - overview-manual-yp-intro - overview-manual-development-environment - overview-manual-concepts - history - -.. include:: /boilerplate.rst diff --git a/documentation/profile-manual/index.rst b/documentation/profile-manual/index.rst new file mode 100644 index 0000000000..5ec5b9e759 --- /dev/null +++ b/documentation/profile-manual/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +========================================== +Yocto Project Profiling and Tracing Manual +========================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + profile-manual-intro + profile-manual-arch + profile-manual-usage + profile-manual-examples + history + +.. include:: /boilerplate.rst diff --git a/documentation/profile-manual/profile-manual.rst b/documentation/profile-manual/profile-manual.rst deleted file mode 100644 index 5ec5b9e759..0000000000 --- a/documentation/profile-manual/profile-manual.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -========================================== -Yocto Project Profiling and Tracing Manual -========================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - profile-manual-intro - profile-manual-arch - profile-manual-usage - profile-manual-examples - history - -.. include:: /boilerplate.rst diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 3ffc1f2c41..747561e061 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -47,7 +47,7 @@ Support Package (BSP) layer for it. For more information on how to create a BSP layer, see the ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" section in the Yocto Project Development Tasks Manual and the -:doc:`../bsp-guide/bsp-guide`. +:doc:`../bsp-guide/index`. Usually, if the board is not completely exotic, adding support in the Yocto Project is fairly straightforward. diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst new file mode 100644 index 0000000000..033f4ba28c --- /dev/null +++ b/documentation/ref-manual/index.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +============================== +Yocto Project Reference Manual +============================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + ref-system-requirements + ref-terms + ref-release-process + migration + ref-structure + ref-classes + ref-tasks + ref-devtool-reference + ref-kickstart + ref-qa-checks + ref-images + ref-features + ref-variables + ref-varlocality + faq + resources + history + +.. include:: /boilerplate.rst diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst index 0220221e01..8ea1aa7f0a 100644 --- a/documentation/ref-manual/migration-2.1.rst +++ b/documentation/ref-manual/migration-2.1.rst @@ -234,7 +234,7 @@ functionality almost completely overlapped with the :ref:`standard SDK ` and the :ref:`extensible SDK `. For information on these SDKs and how to build and use them, see the -:doc:`../sdk-manual/sdk-manual` manual. +:doc:`../sdk-manual/index` manual. .. note:: diff --git a/documentation/ref-manual/ref-features.rst b/documentation/ref-manual/ref-features.rst index a16460e91c..c9223e4131 100644 --- a/documentation/ref-manual/ref-features.rst +++ b/documentation/ref-manual/ref-features.rst @@ -261,7 +261,7 @@ these valid features is as follows: - *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and ``LTTng``. For general information on user-space tools, see the - :doc:`../sdk-manual/sdk-manual` manual. + :doc:`../sdk-manual/index` manual. - *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. @@ -275,7 +275,7 @@ these valid features is as follows: ``gdb``. For information on GDB, see the ":ref:`dev-manual/dev-manual-common-tasks:debugging with the gnu project debugger (gdb) remotely`" section in the Yocto Project Development Tasks Manual. For information on - tracing and profiling, see the :doc:`../profile-manual/profile-manual`. + tracing and profiling, see the :doc:`../profile-manual/index`. - *tools-sdk:* Installs a full SDK that runs on the device. diff --git a/documentation/ref-manual/ref-manual.rst b/documentation/ref-manual/ref-manual.rst deleted file mode 100644 index 033f4ba28c..0000000000 --- a/documentation/ref-manual/ref-manual.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -============================== -Yocto Project Reference Manual -============================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - ref-system-requirements - ref-terms - ref-release-process - migration - ref-structure - ref-classes - ref-tasks - ref-devtool-reference - ref-kickstart - ref-qa-checks - ref-images - ref-features - ref-variables - ref-varlocality - faq - resources - history - -.. include:: /boilerplate.rst diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst index 5d17f0e5c4..a172a0b71c 100644 --- a/documentation/ref-manual/ref-structure.rst +++ b/documentation/ref-manual/ref-structure.rst @@ -104,7 +104,7 @@ metadata to define the Poky reference distribution. This directory contains the Yocto Project reference hardware Board Support Packages (BSPs). For more information on BSPs, see the -:doc:`../bsp-guide/bsp-guide`. +:doc:`../bsp-guide/index`. .. _structure-meta-selftest: diff --git a/documentation/ref-manual/ref-system-requirements.rst b/documentation/ref-manual/ref-system-requirements.rst index af8663a5b2..937cd0c707 100644 --- a/documentation/ref-manual/ref-system-requirements.rst +++ b/documentation/ref-manual/ref-system-requirements.rst @@ -20,9 +20,9 @@ chapter in the Yocto Project Overview and Concepts Manual. If you want to use the Yocto Project to quickly build an image without having to understand concepts, work through the -:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to" -information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview -and conceptual information in the :doc:`../overview-manual/overview-manual`. +:doc:`../brief-yoctoprojectqs/index` document. You can find "how-to" +information in the :doc:`../dev-manual/index`. You can find Yocto Project overview +and conceptual information in the :doc:`../overview-manual/index`. .. note:: diff --git a/documentation/ref-manual/ref-terms.rst b/documentation/ref-manual/ref-terms.rst index f59aaf2788..3c12a2470c 100644 --- a/documentation/ref-manual/ref-terms.rst +++ b/documentation/ref-manual/ref-terms.rst @@ -58,8 +58,7 @@ universal, the list includes them just in case: :term:`Board Support Package (BSP)` A group of drivers, definitions, and other components that provide support for a specific hardware configuration. For more information on BSPs, see - the :ref:`bsp-guide/bsp-guide:Yocto Project Board Support Package - Developer's Guide`. + the :doc:`/bsp-guide/index`. :term:`Build Directory` This term refers to the area used by the OpenEmbedded build system for @@ -164,17 +163,14 @@ universal, the list includes them just in case: ":ref:`overview-manual/overview-manual-concepts:Cross-Development Toolchain Generation`" section in the Yocto Project Overview and Concepts Manual. You can also find more information on using the relocatable - toolchain in the :ref:`sdk-manual/sdk-manual:Yocto Project Application - Development and the Extensible Software Development Kit (eSDK)` manual. + toolchain in the :doc:`/sdk-manual/index` manual. :term:`Extensible Software Development Kit (eSDK)` A custom SDK for application developers. This eSDK allows developers to incorporate their library and programming changes back into the image to make their code available to other application developers. - For information on the eSDK, see the :ref:`sdk-manual/sdk-manual:Yocto - Project Application Development and the Extensible Software Development - Kit (eSDK)` manual. + For information on the eSDK, see the :doc:`/sdk-manual/index` manual. :term:`Image` An image is an artifact of the BitBake build process given a collection of @@ -384,7 +380,7 @@ universal, the list includes them just in case: The interface enables you to configure and run your builds. Information about builds is collected and stored in a database. For information on Toaster, see the - :doc:`../toaster-manual/toaster-manual`. + :doc:`../toaster-manual/index`. :term:`Upstream` A reference to source code or repositories that are not diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst index f8cd5416d9..5a52833e84 100644 --- a/documentation/ref-manual/ref-variables.rst +++ b/documentation/ref-manual/ref-variables.rst @@ -8154,7 +8154,7 @@ system and gives an overview of their function and contents. ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" section in the Yocto Project Overview and Concepts Manual. For information on setting up a cross-development environment, see the - :doc:`../sdk-manual/sdk-manual` manual. + :doc:`../sdk-manual/index` manual. :term:`TOOLCHAIN_OUTPUTNAME` This variable defines the name used for the toolchain output. The @@ -8184,7 +8184,7 @@ system and gives an overview of their function and contents. ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" section in the Yocto Project Overview and Concepts Manual. For information on setting up a cross-development environment, see the - :doc:`../sdk-manual/sdk-manual` manual. + :doc:`../sdk-manual/index` manual. :term:`TOPDIR` The top-level :term:`Build Directory`. BitBake diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst index 70ba8e7be5..e41ce95cf0 100644 --- a/documentation/ref-manual/resources.rst +++ b/documentation/ref-manual/resources.rst @@ -125,18 +125,18 @@ Here is a list of resources you might find helpful: guide to the BitBake tool. If you want information on BitBake, see this manual. -- :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` *:* This +- :doc:`../brief-yoctoprojectqs/index` *:* This short document lets you experience building an image using the Yocto Project without having to understand any concepts or details. -- :doc:`../overview-manual/overview-manual` *:* This manual provides overview +- :doc:`../overview-manual/index` *:* This manual provides overview and conceptual information about the Yocto Project. -- :doc:`../dev-manual/dev-manual` *:* This manual is a "how-to" guide +- :doc:`../dev-manual/index` *:* This manual is a "how-to" guide that presents procedures useful to both application and system developers who use the Yocto Project. -- :doc:`../sdk-manual/sdk-manual` *manual :* This +- :doc:`../sdk-manual/index` *manual :* This guide provides information that lets you get going with the standard or extensible SDK. An SDK, with its cross-development toolchains, allows you to develop projects inside or outside of the Yocto Project @@ -146,12 +146,12 @@ Here is a list of resources you might find helpful: for BSP components. Having a commonly understood structure encourages standardization. -- :doc:`../kernel-dev/kernel-dev` *:* This manual describes +- :doc:`../kernel-dev/index` *:* This manual describes how to work with Linux Yocto kernels as well as provides a bit of conceptual information on the construction of the Yocto Linux kernel tree. -- :doc:`../ref-manual/ref-manual` *:* This +- :doc:`../ref-manual/index` *:* This manual provides reference material such as variable, task, and class descriptions. @@ -161,11 +161,11 @@ Here is a list of resources you might find helpful: which you can easily search for phrases and terms used in the Yocto Project documentation set. -- :doc:`../profile-manual/profile-manual` *:* This manual presents a set of +- :doc:`../profile-manual/index` *:* This manual presents a set of common and generally useful tracing and profiling schemes along with their applications (as appropriate) to each tool. -- :doc:`../toaster-manual/toaster-manual` *:* This manual +- :doc:`../toaster-manual/index` *:* This manual introduces and describes how to set up and use Toaster. Toaster is an Application Programming Interface (API) and web-based interface to the :term:`OpenEmbedded Build System`, which uses diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst new file mode 100644 index 0000000000..177826edf3 --- /dev/null +++ b/documentation/sdk-manual/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +======================================================================================== +Yocto Project Application Development and the Extensible Software Development Kit (eSDK) +======================================================================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + sdk-intro + sdk-extensible + sdk-using + sdk-working-projects + sdk-appendix-obtain + sdk-appendix-customizing + sdk-appendix-customizing-standard + history + +.. include:: /boilerplate.rst diff --git a/documentation/sdk-manual/sdk-manual.rst b/documentation/sdk-manual/sdk-manual.rst deleted file mode 100644 index 177826edf3..0000000000 --- a/documentation/sdk-manual/sdk-manual.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -======================================================================================== -Yocto Project Application Development and the Extensible Software Development Kit (eSDK) -======================================================================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - sdk-intro - sdk-extensible - sdk-using - sdk-working-projects - sdk-appendix-obtain - sdk-appendix-customizing - sdk-appendix-customizing-standard - history - -.. include:: /boilerplate.rst diff --git a/documentation/test-manual/index.rst b/documentation/test-manual/index.rst new file mode 100644 index 0000000000..2891f06d81 --- /dev/null +++ b/documentation/test-manual/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +===================================== +Yocto Project Test Environment Manual +===================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + test-manual-intro + test-manual-test-process + test-manual-understand-autobuilder + history + +.. include:: /boilerplate.rst diff --git a/documentation/test-manual/test-manual.rst b/documentation/test-manual/test-manual.rst deleted file mode 100644 index 2891f06d81..0000000000 --- a/documentation/test-manual/test-manual.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -===================================== -Yocto Project Test Environment Manual -===================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - test-manual-intro - test-manual-test-process - test-manual-understand-autobuilder - history - -.. include:: /boilerplate.rst diff --git a/documentation/toaster-manual/index.rst b/documentation/toaster-manual/index.rst new file mode 100644 index 0000000000..b003f1ceaa --- /dev/null +++ b/documentation/toaster-manual/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +=================== +Toaster User Manual +=================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + toaster-manual-intro + toaster-manual-start + toaster-manual-setup-and-use + toaster-manual-reference + history + +.. include:: /boilerplate.rst diff --git a/documentation/toaster-manual/toaster-manual.rst b/documentation/toaster-manual/toaster-manual.rst deleted file mode 100644 index b003f1ceaa..0000000000 --- a/documentation/toaster-manual/toaster-manual.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -=================== -Toaster User Manual -=================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - toaster-manual-intro - toaster-manual-start - toaster-manual-setup-and-use - toaster-manual-reference - history - -.. include:: /boilerplate.rst diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst index b87fec6893..3663f53364 100644 --- a/documentation/transitioning-to-a-custom-environment.rst +++ b/documentation/transitioning-to-a-custom-environment.rst @@ -8,7 +8,7 @@ Transitioning to a custom environment for systems development .. note:: - So you've finished the :doc:`brief-yoctoprojectqs/brief-yoctoprojectqs` and + So you've finished the :doc:`brief-yoctoprojectqs/index` and glanced over the document :doc:`what-i-wish-id-known`, the latter contains important information learned from other users. You're well prepared. But now, as you are starting your own project, it isn't exactly straightforward what diff --git a/documentation/what-i-wish-id-known.rst b/documentation/what-i-wish-id-known.rst index afc1263829..3f9fdea5fa 100644 --- a/documentation/what-i-wish-id-known.rst +++ b/documentation/what-i-wish-id-known.rst @@ -49,7 +49,7 @@ contact us with other suggestions. their silicon. These layers have names such as "meta-intel" or "meta-ti". Try not to build layers from scratch. If you do have custom silicon, use one of these layers as a guide or template and familiarize yourself with the - :doc:`bsp-guide/bsp-guide`. + :doc:`bsp-guide/index`. #. **Do not put everything into one layer:** Use different layers to logically separate information in your build. As an @@ -126,7 +126,7 @@ contact us with other suggestions. You can build and run a specific task for a specific package (including devshell) or even a single recipe. When developers first start using the Yocto Project, the instructions found in the - :doc:`brief-yoctoprojectqs/brief-yoctoprojectqs` show how to create an image + :doc:`brief-yoctoprojectqs/index` show how to create an image and then run or flash that image. However, you can actually build just a single recipe. Thus, if some dependency or recipe isn't working, you can just say "bitbake foo" where "foo" is the name for a specific recipe. As you @@ -190,7 +190,7 @@ contact us with other suggestions. contains procedural information grouped to help you get set up, work with layers, customize images, write new recipes, work with libraries, and use QEMU. The information is task-based and spans the breadth of the Yocto - Project. See the :doc:`../dev-manual/dev-manual`. + Project. See the :doc:`../dev-manual/index`. * **Look Through the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual**: This manual describes how to use @@ -201,17 +201,17 @@ contact us with other suggestions. for more information. * **Learn About Kernel Development**: If you want to see how to work with the - kernel and understand Yocto Linux kernels, see the :doc:`../kernel-dev/kernel-dev`. + kernel and understand Yocto Linux kernels, see the :doc:`../kernel-dev/index`. This manual provides information on how to patch the kernel, modify kernel recipes, and configure the kernel. * **Learn About Board Support Packages (BSPs)**: If you want to learn about - BSPs, see the :doc:`../bsp-guide/bsp-guide`. This manual also provides an + BSPs, see the :doc:`../bsp-guide/index`. This manual also provides an example BSP creation workflow. See the :doc:`../bsp-guide/bsp` section. * **Learn About Toaster**: Toaster is a web interface to the Yocto Project's OpenEmbedded build system. If you are interested in using this type of - interface to create images, see the :doc:`../toaster-manual/toaster-manual`. + interface to create images, see the :doc:`../toaster-manual/index`. * **Have Available the Yocto Project Reference Manual**: Unlike the rest of the Yocto Project manual set, this manual is comprised of material suited @@ -219,7 +219,7 @@ contact us with other suggestions. look at how the pieces of the Yocto Project development environment work together, information on various technical details, guidance on migrating to a newer Yocto Project release, reference material on the directory - structure, classes, and tasks. The :doc:`../ref-manual/ref-manual` also + structure, classes, and tasks. The :doc:`../ref-manual/index` also contains a fairly comprehensive glossary of variables used within the Yocto Project. -- cgit v1.2.3-54-g00ecf