summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/faq.rst
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-14 22:48:44 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:35 +0100
commit292598164a304a3da3288e6fb8963f13045d1e7f (patch)
treeefedbbdc16cb2e0978a4d40e6a6294e32b0e496f /documentation/ref-manual/faq.rst
parentd313d972bf592de77f2af13cb3fc4226247cb1a1 (diff)
downloadpoky-292598164a304a3da3288e6fb8963f13045d1e7f.tar.gz
sphinx: ref-manual links fixes and many other cleanups to import
(From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/faq.rst')
-rw-r--r--documentation/ref-manual/faq.rst129
1 files changed, 81 insertions, 48 deletions
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 @@
4FAQ 4FAQ
5*** 5***
6 6
7**Q:** How does Poky differ from `OpenEmbedded <&OE_HOME_URL;>`__? 7**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__?
8 8
9**A:** The term "`Poky <#>`__" refers to the specific reference build 9**A:** The term ``Poky`` refers to the specific reference build
10system that the Yocto Project provides. Poky is based on 10system that the Yocto Project provides. Poky is based on
11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the 11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
12generic term used here for the build system is the "OpenEmbedded build 12generic term used here for the build system is the "OpenEmbedded build
@@ -44,11 +44,10 @@ steps on how to update your build tools.
44 44
45**A:** Support for an additional board is added by creating a Board 45**A:** Support for an additional board is added by creating a Board
46Support Package (BSP) layer for it. For more information on how to 46Support Package (BSP) layer for it. For more information on how to
47create a BSP layer, see the "`Understanding and Creating 47create a BSP layer, see the
48Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" 48":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
49section in the Yocto Project Development Tasks Manual and the `Yocto 49section in the Yocto Project Development Tasks Manual and the
50Project Board Support Package (BSP) Developer's 50:doc:`../bsp-guide/bsp-guide`.
51Guide <&YOCTO_DOCS_BSP_URL;>`__.
52 51
53Usually, if the board is not completely exotic, adding support in the 52Usually, if the board is not completely exotic, adding support in the
54Yocto Project is fairly straightforward. 53Yocto Project is fairly straightforward.
@@ -73,8 +72,8 @@ device.
73**Q:** How do I add my package to the Yocto Project? 72**Q:** How do I add my package to the Yocto Project?
74 73
75**A:** To add a package, you need to create a BitBake recipe. For 74**A:** To add a package, you need to create a BitBake recipe. For
76information on how to create a BitBake recipe, see the "`Writing a New 75information on how to create a BitBake recipe, see the
77Recipe <&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe>`__" 76":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`"
78section in the Yocto Project Development Tasks Manual. 77section in the Yocto Project Development Tasks Manual.
79 78
80**Q:** Do I have to reflash my entire board with a new Yocto Project 79**Q:** Do I have to reflash my entire board with a new Yocto Project
@@ -126,12 +125,18 @@ file.
126 125
127Following is the applicable code for setting various proxy types in the 126Following is the applicable code for setting various proxy types in the
128``.wgetrc`` file. By default, these settings are disabled with comments. 127``.wgetrc`` file. By default, these settings are disabled with comments.
129To use them, remove the comments: # You can set the default proxies for 128To use them, remove the comments: ::
130Wget to use for http, https, and ftp. # They will override the value in 129
131the environment. #https_proxy = http://proxy.yoyodyne.com:18023/ 130 # You can set the default proxies for Wget to use for http, https, and ftp.
132#http_proxy = http://proxy.yoyodyne.com:18023/ #ftp_proxy = 131 # They will override the value in the environment.
133http://proxy.yoyodyne.com:18023/ # If you do not want to use proxy at 132 #https_proxy = http://proxy.yoyodyne.com:18023/
134all, set this to off. #use_proxy = on The Yocto Project also includes a 133 #http_proxy = http://proxy.yoyodyne.com:18023/
134 #ftp_proxy = http://proxy.yoyodyne.com:18023/
135
136 # If you do not want to use proxy at all, set this to off.
137 #use_proxy = on
138
139The Yocto Project also includes a
135``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS 140``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS
136and Git proxy servers if needed. For more information on setting up 141and Git proxy servers if needed. For more information on setting up
137various proxy types and configuring proxy servers, see the 142various proxy types and configuring proxy servers, see the
@@ -167,8 +172,12 @@ always been traced back to hardware or virtualization issues.
167**A:** If you get an error message that indicates GNU ``libiconv`` is 172**A:** If you get an error message that indicates GNU ``libiconv`` is
168not in use but ``iconv.h`` has been included from ``libiconv``, you need 173not in use but ``iconv.h`` has been included from ``libiconv``, you need
169to check to see if you have a previously installed version of the header 174to check to see if you have a previously installed version of the header
170file in ``/usr/local/include``. #error GNU libiconv not in use but 175file in ``/usr/local/include``.
171included iconv.h is from libiconv If you find a previously installed 176::
177
178 #error GNU libiconv not in use but included iconv.h is from libiconv
179
180If you find a previously installed
172file, you should either uninstall it or temporarily rename it and try 181file, you should either uninstall it or temporarily rename it and try
173the build again. 182the build again.
174 183
@@ -189,20 +198,21 @@ and also any configuration information about how that package was
189configured and built. 198configured and built.
190 199
191You can find more information on licensing in the 200You can find more information on licensing in the
192"`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" section in the Yocto 201":ref:`overview-manual/overview-manual-development-environment:licensing`"
193Project Overview and Concepts Manual and also in the "`Maintaining Open 202section in the Yocto
194Source License Compliance During Your Product's 203Project Overview and Concepts Manual and also in the
195Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" 204":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
196section in the Yocto Project Development Tasks Manual. 205section in the Yocto Project Development Tasks Manual.
197 206
198**Q:** How do I disable the cursor on my touchscreen device? 207**Q:** How do I disable the cursor on my touchscreen device?
199 208
200**A:** You need to create a form factor file as described in the 209**A:** You need to create a form factor file as described in the
201"`Miscellaneous BSP-Specific Recipe 210":ref:`bsp-filelayout-misc-recipes`" section in
202Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
203the Yocto Project Board Support Packages (BSP) Developer's Guide. Set 211the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
204the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: 212the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
205HAVE_TOUCHSCREEN=1 213::
214
215 HAVE_TOUCHSCREEN=1
206 216
207**Q:** How do I make sure connected network interfaces are brought up by 217**Q:** How do I make sure connected network interfaces are brought up by
208default? 218default?
@@ -210,14 +220,14 @@ default?
210**A:** The default interfaces file provided by the netbase recipe does 220**A:** The default interfaces file provided by the netbase recipe does
211not automatically bring up network interfaces. Therefore, you will need 221not automatically bring up network interfaces. Therefore, you will need
212to add a BSP-specific netbase that includes an interfaces file. See the 222to add a BSP-specific netbase that includes an interfaces file. See the
213"`Miscellaneous BSP-Specific Recipe 223":ref:`bsp-filelayout-misc-recipes`" section in
214Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
215the Yocto Project Board Support Packages (BSP) Developer's Guide for 224the Yocto Project Board Support Packages (BSP) Developer's Guide for
216information on creating these types of miscellaneous recipe files. 225information on creating these types of miscellaneous recipe files.
217 226
218For example, add the following files to your layer: 227For example, add the following files to your layer: ::
219meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces 228
220meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend 229 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
230 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
221 231
222**Q:** How do I create images with more free space? 232**Q:** How do I create images with more free space?
223 233
@@ -260,7 +270,7 @@ controls which ``tcmode-*.inc`` file to include from the
260The default value of ``TCMODE`` is "default", which tells the 270The default value of ``TCMODE`` is "default", which tells the
261OpenEmbedded build system to use its internally built toolchain (i.e. 271OpenEmbedded build system to use its internally built toolchain (i.e.
262``tcmode-default.inc``). However, other patterns are accepted. In 272``tcmode-default.inc``). However, other patterns are accepted. In
263particular, "external-*" refers to external toolchains. One example is 273particular, "external-\*" refers to external toolchains. One example is
264the Sourcery G++ Toolchain. The support for this toolchain resides in 274the Sourcery G++ Toolchain. The support for this toolchain resides in
265the separate ``meta-sourcery`` layer at 275the separate ``meta-sourcery`` layer at
266http://github.com/MentorEmbedded/meta-sourcery/. 276http://github.com/MentorEmbedded/meta-sourcery/.
@@ -290,11 +300,13 @@ fail.
290 300
291As an example, you could add a specific server for the build system to 301As an example, you could add a specific server for the build system to
292attempt before any others by adding something like the following to the 302attempt before any others by adding something like the following to the
293``local.conf`` configuration file: PREMIRRORS_prepend = "\\ git://.*/.\* 303``local.conf`` configuration file: ::
294http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* 304
295http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* 305 PREMIRRORS_prepend = "\
296http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 306 git://.*/.* http://www.yoctoproject.org/sources/ \n \
297http://www.yoctoproject.org/sources/ \\n" 307 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
308 http://.*/.* http://www.yoctoproject.org/sources/ \n \
309 https://.*/.* http://www.yoctoproject.org/sources/ \n"
298 310
299These changes cause the build system to intercept Git, FTP, HTTP, and 311These changes cause the build system to intercept Git, FTP, HTTP, and
300HTTPS requests and direct them to the ``http://`` sources mirror. You 312HTTPS 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
302as well. 314as well.
303 315
304Aside from the previous technique, these options also exist: 316Aside from the previous technique, these options also exist:
305BB_NO_NETWORK = "1" This statement tells BitBake to issue an error 317::
318
319 BB_NO_NETWORK = "1"
320
321This statement tells BitBake to issue an error
306instead of trying to access the Internet. This technique is useful if 322instead of trying to access the Internet. This technique is useful if
307you want to ensure code builds only from local sources. 323you want to ensure code builds only from local sources.
308 324
309Here is another technique: BB_FETCH_PREMIRRORONLY = "1" This statement 325Here is another technique:
326::
327
328 BB_FETCH_PREMIRRORONLY = "1"
329
330This statement
310limits the build system to pulling source from the ``PREMIRRORS`` only. 331limits the build system to pulling source from the ``PREMIRRORS`` only.
311Again, this technique is useful for reproducing builds. 332Again, this technique is useful for reproducing builds.
312 333
313Here is another technique: BB_GENERATE_MIRROR_TARBALLS = "1" This 334Here is another technique:
335::
336
337 BB_GENERATE_MIRROR_TARBALLS = "1"
338
339This
314statement tells the build system to generate mirror tarballs. This 340statement tells the build system to generate mirror tarballs. This
315technique is useful if you want to create a mirror server. If not, 341technique is useful if you want to create a mirror server. If not,
316however, the technique can simply waste time during the build. 342however, the technique can simply waste time during the build.
317 343
318Finally, consider an example where you are behind an HTTP-only firewall. 344Finally, consider an example where you are behind an HTTP-only firewall.
319You could make the following changes to the ``local.conf`` configuration 345You could make the following changes to the ``local.conf`` configuration
320file as long as the ``PREMIRRORS`` server is current: PREMIRRORS_prepend 346file as long as the ``PREMIRRORS`` server is current: ::
321= "\\ ftp://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ 347
322http://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 348 PREMIRRORS_prepend = "\
323http://www.yoctoproject.org/sources/ \\n" BB_FETCH_PREMIRRORONLY = "1" 349 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
350 http://.*/.* http://www.yoctoproject.org/sources/ \n \
351 https://.*/.* http://www.yoctoproject.org/sources/ \n"
352 BB_FETCH_PREMIRRORONLY = "1"
353
324These changes would cause the build system to successfully fetch source 354These changes would cause the build system to successfully fetch source
325over HTTP and any network accesses to anything other than the 355over HTTP and any network accesses to anything other than the
326``PREMIRRORS`` would fail. 356``PREMIRRORS`` would fail.
@@ -384,18 +414,21 @@ that program is never installed directly to the build machine's root
384file system. Consequently, the build system uses paths within the Build 414file system. Consequently, the build system uses paths within the Build
385Directory for ``DESTDIR``, ``bindir`` and related variables. To better 415Directory for ``DESTDIR``, ``bindir`` and related variables. To better
386understand this, consider the following two paths where the first is 416understand this, consider the following two paths where the first is
387relatively normal and the second is not: 417relatively normal and the second is not: ::
418
419 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
420 1.2.8-r0/sysroot-destdir/usr/bin
421
422 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
423 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
424 build/tmp/sysroots/x86_64-linux/usr/bin
388 425
389.. note:: 426.. note::
390 427
391 Due to these lengthy examples, the paths are artificially broken 428 Due to these lengthy examples, the paths are artificially broken
392 across lines for readability. 429 across lines for readability.
393 430
394/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 431Even if the paths look unusual,
3951.2.8-r0/sysroot-destdir/usr/bin
396/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
397zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
398build/tmp/sysroots/x86_64-linux/usr/bin Even if the paths look unusual,
399they both are correct - the first for a target and the second for a 432they both are correct - the first for a target and the second for a
400native recipe. These paths are a consequence of the ``DESTDIR`` 433native recipe. These paths are a consequence of the ``DESTDIR``
401mechanism and while they appear strange, they are correct and in 434mechanism and while they appear strange, they are correct and in