From 292598164a304a3da3288e6fb8963f13045d1e7f Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Mon, 14 Sep 2020 22:48:44 +0200 Subject: sphinx: ref-manual links fixes and many other cleanups to import (From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e) Signed-off-by: Richard Purdie --- documentation/ref-manual/faq.rst | 129 ++++++++++++++++++++++++--------------- 1 file changed, 81 insertions(+), 48 deletions(-) (limited to 'documentation/ref-manual/faq.rst') diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index e25f0b278c..04066e9202 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -4,9 +4,9 @@ FAQ *** -**Q:** How does Poky differ from `OpenEmbedded <&OE_HOME_URL;>`__? +**Q:** How does Poky differ from `OpenEmbedded `__? -**A:** The term "`Poky <#>`__" refers to the specific reference build +**A:** The term ``Poky`` refers to the specific reference build system that the Yocto Project provides. Poky is based on :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the generic term used here for the build system is the "OpenEmbedded build @@ -44,11 +44,10 @@ steps on how to update your build tools. **A:** Support for an additional board is added by creating a Board Support Package (BSP) layer for it. For more information on how to -create a BSP layer, see the "`Understanding and Creating -Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" -section in the Yocto Project Development Tasks Manual and the `Yocto -Project Board Support Package (BSP) Developer's -Guide <&YOCTO_DOCS_BSP_URL;>`__. +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`. Usually, if the board is not completely exotic, adding support in the Yocto Project is fairly straightforward. @@ -73,8 +72,8 @@ device. **Q:** How do I add my package to the Yocto Project? **A:** To add a package, you need to create a BitBake recipe. For -information on how to create a BitBake recipe, see the "`Writing a New -Recipe <&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe>`__" +information on how to create a BitBake recipe, see the +":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`" section in the Yocto Project Development Tasks Manual. **Q:** Do I have to reflash my entire board with a new Yocto Project @@ -126,12 +125,18 @@ file. Following is the applicable code for setting various proxy types in the ``.wgetrc`` file. By default, these settings are disabled with comments. -To use them, remove the comments: # You can set the default proxies for -Wget to use for http, https, and ftp. # They will override the value in -the environment. #https_proxy = http://proxy.yoyodyne.com:18023/ -#http_proxy = http://proxy.yoyodyne.com:18023/ #ftp_proxy = -http://proxy.yoyodyne.com:18023/ # If you do not want to use proxy at -all, set this to off. #use_proxy = on The Yocto Project also includes a +To use them, remove the comments: :: + + # You can set the default proxies for Wget to use for http, https, and ftp. + # They will override the value in the environment. + #https_proxy = http://proxy.yoyodyne.com:18023/ + #http_proxy = http://proxy.yoyodyne.com:18023/ + #ftp_proxy = http://proxy.yoyodyne.com:18023/ + + # If you do not want to use proxy at all, set this to off. + #use_proxy = on + +The Yocto Project also includes a ``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS and Git proxy servers if needed. For more information on setting up various proxy types and configuring proxy servers, see the @@ -167,8 +172,12 @@ always been traced back to hardware or virtualization issues. **A:** If you get an error message that indicates GNU ``libiconv`` is not in use but ``iconv.h`` has been included from ``libiconv``, you need to check to see if you have a previously installed version of the header -file in ``/usr/local/include``. #error GNU libiconv not in use but -included iconv.h is from libiconv If you find a previously installed +file in ``/usr/local/include``. +:: + + #error GNU libiconv not in use but included iconv.h is from libiconv + +If you find a previously installed file, you should either uninstall it or temporarily rename it and try the build again. @@ -189,20 +198,21 @@ and also any configuration information about how that package was configured and built. You can find more information on licensing in the -"`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" section in the Yocto -Project Overview and Concepts Manual and also in the "`Maintaining Open -Source License Compliance During Your Product's -Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" +":ref:`overview-manual/overview-manual-development-environment:licensing`" +section in the Yocto +Project Overview and Concepts Manual and also in the +":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. **Q:** How do I disable the cursor on my touchscreen device? **A:** You need to create a form factor file as described in the -"`Miscellaneous BSP-Specific Recipe -Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in +":ref:`bsp-filelayout-misc-recipes`" section in the Yocto Project Board Support Packages (BSP) Developer's Guide. Set the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: -HAVE_TOUCHSCREEN=1 +:: + + HAVE_TOUCHSCREEN=1 **Q:** How do I make sure connected network interfaces are brought up by default? @@ -210,14 +220,14 @@ default? **A:** The default interfaces file provided by the netbase recipe does not automatically bring up network interfaces. Therefore, you will need to add a BSP-specific netbase that includes an interfaces file. See the -"`Miscellaneous BSP-Specific Recipe -Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in +":ref:`bsp-filelayout-misc-recipes`" section in the Yocto Project Board Support Packages (BSP) Developer's Guide for information on creating these types of miscellaneous recipe files. -For example, add the following files to your layer: -meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces -meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend +For example, add the following files to your layer: :: + + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend **Q:** How do I create images with more free space? @@ -260,7 +270,7 @@ controls which ``tcmode-*.inc`` file to include from the The default value of ``TCMODE`` is "default", which tells the OpenEmbedded build system to use its internally built toolchain (i.e. ``tcmode-default.inc``). However, other patterns are accepted. In -particular, "external-*" refers to external toolchains. One example is +particular, "external-\*" refers to external toolchains. One example is the Sourcery G++ Toolchain. The support for this toolchain resides in the separate ``meta-sourcery`` layer at http://github.com/MentorEmbedded/meta-sourcery/. @@ -290,11 +300,13 @@ fail. As an example, you could add a specific server for the build system to attempt before any others by adding something like the following to the -``local.conf`` configuration file: PREMIRRORS_prepend = "\\ git://.*/.\* -http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* -http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* -http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* -http://www.yoctoproject.org/sources/ \\n" +``local.conf`` configuration file: :: + + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" These changes cause the build system to intercept Git, FTP, HTTP, and HTTPS requests and direct them to the ``http://`` sources mirror. You @@ -302,25 +314,43 @@ can use ``file://`` URLs to point to local directories or network shares as well. Aside from the previous technique, these options also exist: -BB_NO_NETWORK = "1" This statement tells BitBake to issue an error +:: + + BB_NO_NETWORK = "1" + +This statement tells BitBake to issue an error instead of trying to access the Internet. This technique is useful if you want to ensure code builds only from local sources. -Here is another technique: BB_FETCH_PREMIRRORONLY = "1" This statement +Here is another technique: +:: + + BB_FETCH_PREMIRRORONLY = "1" + +This statement limits the build system to pulling source from the ``PREMIRRORS`` only. Again, this technique is useful for reproducing builds. -Here is another technique: BB_GENERATE_MIRROR_TARBALLS = "1" This +Here is another technique: +:: + + BB_GENERATE_MIRROR_TARBALLS = "1" + +This statement tells the build system to generate mirror tarballs. This technique is useful if you want to create a mirror server. If not, however, the technique can simply waste time during the build. Finally, consider an example where you are behind an HTTP-only firewall. You could make the following changes to the ``local.conf`` configuration -file as long as the ``PREMIRRORS`` server is current: PREMIRRORS_prepend -= "\\ ftp://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ -http://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* -http://www.yoctoproject.org/sources/ \\n" BB_FETCH_PREMIRRORONLY = "1" +file as long as the ``PREMIRRORS`` server is current: :: + + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + These changes would cause the build system to successfully fetch source over HTTP and any network accesses to anything other than the ``PREMIRRORS`` would fail. @@ -384,18 +414,21 @@ that program is never installed directly to the build machine's root file system. Consequently, the build system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` and related variables. To better understand this, consider the following two paths where the first is -relatively normal and the second is not: +relatively normal and the second is not: :: + + /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ + 1.2.8-r0/sysroot-destdir/usr/bin + + /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ + zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ + build/tmp/sysroots/x86_64-linux/usr/bin .. note:: Due to these lengthy examples, the paths are artificially broken across lines for readability. -/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ -1.2.8-r0/sysroot-destdir/usr/bin -/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ -zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ -build/tmp/sysroots/x86_64-linux/usr/bin Even if the paths look unusual, +Even if the paths look unusual, they both are correct - the first for a target and the second for a native recipe. These paths are a consequence of the ``DESTDIR`` mechanism and while they appear strange, they are correct and in -- cgit v1.2.3-54-g00ecf