diff options
Diffstat (limited to 'documentation/ref-manual/faq.rst')
-rw-r--r-- | documentation/ref-manual/faq.rst | 626 |
1 files changed, 309 insertions, 317 deletions
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 34b26ee3ef..bab284bbfd 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst | |||
@@ -4,9 +4,15 @@ | |||
4 | FAQ | 4 | FAQ |
5 | *** | 5 | *** |
6 | 6 | ||
7 | **Q:** How does Poky differ from :oe_home:`OpenEmbedded <>`? | 7 | .. contents:: |
8 | 8 | ||
9 | **A:** The term ``Poky`` refers to the specific reference build | 9 | General questions |
10 | ================= | ||
11 | |||
12 | How does Poky differ from OpenEmbedded? | ||
13 | --------------------------------------- | ||
14 | |||
15 | The term ``Poky`` refers to the specific reference build | ||
10 | system that the Yocto Project provides. Poky is based on | 16 | system that the Yocto Project provides. Poky is based on |
11 | :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the | 17 | :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the |
12 | generic term used here for the build system is the "OpenEmbedded build | 18 | generic term used here for the build system is the "OpenEmbedded build |
@@ -15,19 +21,10 @@ OpenEmbedded, with changes always being merged to OE-Core or BitBake | |||
15 | first before being pulled back into Poky. This practice benefits both | 21 | first before being pulled back into Poky. This practice benefits both |
16 | projects immediately. | 22 | projects immediately. |
17 | 23 | ||
18 | **Q:** My development system does not meet the required Git, tar, and | 24 | How can you claim Poky / OpenEmbedded-Core is stable? |
19 | Python versions. In particular, I do not have Python 3.5.0 or greater. | 25 | ----------------------------------------------------- |
20 | Can I still use the Yocto Project? | ||
21 | |||
22 | **A:** You can get the required tools on your host development system a | ||
23 | couple different ways (i.e. building a tarball or downloading a | ||
24 | tarball). See the | ||
25 | ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" | ||
26 | section for steps on how to update your build tools. | ||
27 | |||
28 | **Q:** How can you claim Poky / OpenEmbedded-Core is stable? | ||
29 | 26 | ||
30 | **A:** There are three areas that help with stability; | 27 | There are three areas that help with stability; |
31 | 28 | ||
32 | - The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and | 29 | - The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and |
33 | focused, containing around 830 recipes as opposed to the thousands | 30 | focused, containing around 830 recipes as opposed to the thousands |
@@ -37,95 +34,110 @@ section for steps on how to update your build tools. | |||
37 | - The Yocto Project team runs manual and automated tests using a small, | 34 | - The Yocto Project team runs manual and automated tests using a small, |
38 | fixed set of reference hardware as well as emulated targets. | 35 | fixed set of reference hardware as well as emulated targets. |
39 | 36 | ||
40 | - The Yocto Project uses an autobuilder, which provides continuous | 37 | - The Yocto Project uses an :yocto_ab:`autobuilder <>`, which provides |
41 | build and integration tests. | 38 | continuous build and integration tests. |
42 | 39 | ||
43 | **Q:** How do I get support for my board added to the Yocto Project? | 40 | Are there any products built using the OpenEmbedded build system? |
41 | ----------------------------------------------------------------- | ||
44 | 42 | ||
45 | **A:** Support for an additional board is added by creating a Board | 43 | See :yocto_wiki:`Products that use the Yocto Project |
46 | Support Package (BSP) layer for it. For more information on how to | 44 | </Project_Users#Products_that_use_the_Yocto_Project>` in the Yocto Project |
47 | create a BSP layer, see the | 45 | Wiki. Don't hesitate to contribute to this page if you know other such |
48 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 46 | products. |
49 | section in the Yocto Project Development Tasks Manual and the | ||
50 | :doc:`/bsp-guide/index`. | ||
51 | 47 | ||
52 | Usually, if the board is not completely exotic, adding support in the | 48 | Building environment |
53 | Yocto Project is fairly straightforward. | 49 | ==================== |
54 | 50 | ||
55 | **Q:** Are there any products built using the OpenEmbedded build system? | 51 | Missing dependencies on the development system? |
52 | ----------------------------------------------- | ||
56 | 53 | ||
57 | **A:** The software running on the `Vernier | 54 | If your development system does not meet the required Git, tar, and |
58 | LabQuest <https://vernier.com/labquest/>`__ is built using the | 55 | Python versions, you can get the required tools on your host development |
59 | OpenEmbedded build system. See the `Vernier | 56 | system in different ways (i.e. building a tarball or downloading a |
60 | LabQuest <https://www.vernier.com/products/interfaces/labq/>`__ website | 57 | tarball). See the ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" |
61 | for more information. There are a number of pre-production devices using | 58 | section for steps on how to update your build tools. |
62 | the OpenEmbedded build system and the Yocto Project team announces them | ||
63 | as soon as they are released. | ||
64 | 59 | ||
65 | **Q:** What does the OpenEmbedded build system produce as output? | 60 | How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server? |
61 | ----------------------------------------------------------------------------------------- | ||
66 | 62 | ||
67 | **A:** Because you can use the same set of recipes to create output of | 63 | The way the build system obtains source code is highly |
68 | various formats, the output of an OpenEmbedded build depends on how you | 64 | configurable. You can setup the build system to get source code in most |
69 | start it. Usually, the output is a flashable image ready for the target | 65 | environments if HTTP transport is available. |
70 | device. | ||
71 | 66 | ||
72 | **Q:** How do I add my package to the Yocto Project? | 67 | When the build system searches for source code, it first tries the local |
68 | download directory. If that location fails, Poky tries | ||
69 | :term:`PREMIRRORS`, the upstream source, and then | ||
70 | :term:`MIRRORS` in that order. | ||
73 | 71 | ||
74 | **A:** To add a package, you need to create a BitBake recipe. For | 72 | Assuming your distribution is "poky", the OpenEmbedded build system uses |
75 | information on how to create a BitBake recipe, see the | 73 | the Yocto Project source :term:`PREMIRRORS` by default for SCM-based |
76 | ":ref:`dev-manual/common-tasks:writing a new recipe`" | 74 | sources, upstreams for normal tarballs, and then falls back to a number |
77 | section in the Yocto Project Development Tasks Manual. | 75 | of other mirrors including the Yocto Project source mirror if those |
76 | fail. | ||
77 | |||
78 | As an example, you could add a specific server for the build system to | ||
79 | attempt before any others by adding something like the following to the | ||
80 | ``local.conf`` configuration file:: | ||
78 | 81 | ||
79 | **Q:** Do I have to reflash my entire board with a new Yocto Project | 82 | PREMIRRORS:prepend = "\ |
80 | image when recompiling a package? | 83 | git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
84 | ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ | ||
85 | http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ | ||
86 | https://.*/.* &YOCTO_DL_URL;/mirror/sources/" | ||
81 | 87 | ||
82 | **A:** The OpenEmbedded build system can build packages in various | 88 | These changes cause the build system to intercept Git, FTP, HTTP, and |
83 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | 89 | HTTPS requests and direct them to the ``http://`` sources mirror. You |
84 | then upgrade the packages using the package tools on the device, much | 90 | can use ``file://`` URLs to point to local directories or network shares |
85 | like on a desktop distribution such as Ubuntu or Fedora. However, | 91 | as well. |
86 | package management on the target is entirely optional. | ||
87 | 92 | ||
88 | **Q:** I see the error | 93 | Another option is to set:: |
89 | '``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is | ||
90 | wrong? | ||
91 | 94 | ||
92 | **A:** You are probably running the build on an NTFS filesystem. Use | 95 | BB_NO_NETWORK = "1" |
93 | ``ext2``, ``ext3``, or ``ext4`` instead. | ||
94 | 96 | ||
95 | **Q:** I see lots of 404 responses for files when the OpenEmbedded build | 97 | This statement tells BitBake to issue an error |
96 | system is trying to download sources. Is something wrong? | 98 | instead of trying to access the Internet. This technique is useful if |
99 | you want to ensure code builds only from local sources. | ||
97 | 100 | ||
98 | **A:** Nothing is wrong. The OpenEmbedded build system checks any | 101 | Here is another technique:: |
99 | configured source mirrors before downloading from the upstream sources. | 102 | |
100 | The build system does this searching for both source archives and | 103 | BB_FETCH_PREMIRRORONLY = "1" |
101 | pre-checked out versions of SCM-managed software. These checks help in | ||
102 | large installations because it can reduce load on the SCM servers | ||
103 | themselves. The address above is one of the default mirrors configured | ||
104 | into the build system. Consequently, if an upstream source disappears, | ||
105 | the team can place sources there so builds continue to work. | ||
106 | 104 | ||
107 | **Q:** I have machine-specific data in a package for one machine only | 105 | This statement limits the build system to pulling source from the |
108 | but the package is being marked as machine-specific in all cases, how do | 106 | :term:`PREMIRRORS` only. Again, this technique is useful for reproducing |
109 | I prevent this? | 107 | builds. |
110 | 108 | ||
111 | **A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file | 109 | Here is yet another technique:: |
112 | but make sure the package is manually marked as machine-specific for the | ||
113 | case that needs it. The code that handles | ||
114 | ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the | ||
115 | ``meta/classes/base.bbclass`` file. | ||
116 | 110 | ||
117 | **Q:** I'm behind a firewall and need to use a proxy server. How do I do | 111 | BB_GENERATE_MIRROR_TARBALLS = "1" |
118 | that? | 112 | |
113 | This statement tells the build system to generate mirror tarballs. This | ||
114 | technique is useful if you want to create a mirror server. If not, | ||
115 | however, the technique can simply waste time during the build. | ||
119 | 116 | ||
120 | **A:** Most source fetching by the OpenEmbedded build system is done by | 117 | Finally, consider an example where you are behind an HTTP-only firewall. |
118 | You could make the following changes to the ``local.conf`` configuration | ||
119 | file as long as the :term:`PREMIRRORS` server is current:: | ||
120 | |||
121 | PREMIRRORS:prepend = "\ | ||
122 | git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ | ||
123 | ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ | ||
124 | http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ | ||
125 | https://.*/.* &YOCTO_DL_URL;/mirror/sources/" | ||
126 | BB_FETCH_PREMIRRORONLY = "1" | ||
127 | |||
128 | These changes would cause the build system to successfully fetch source | ||
129 | over HTTP and any network accesses to anything other than the | ||
130 | :term:`PREMIRRORS` would fail. | ||
131 | |||
132 | Most source fetching by the OpenEmbedded build system is done by | ||
121 | ``wget`` and you therefore need to specify the proxy settings in a | 133 | ``wget`` and you therefore need to specify the proxy settings in a |
122 | ``.wgetrc`` file, which can be in your home directory if you are a | 134 | ``.wgetrc`` file, which can be in your home directory if you are a |
123 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user | 135 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user |
124 | file. | 136 | file. |
125 | 137 | ||
126 | Following is the applicable code for setting various proxy types in the | 138 | Here is the applicable code for setting various proxy types in the |
127 | ``.wgetrc`` file. By default, these settings are disabled with comments. | 139 | ``.wgetrc`` file. By default, these settings are disabled with comments. |
128 | To use them, remove the comments: :: | 140 | To use them, remove the comments:: |
129 | 141 | ||
130 | # You can set the default proxies for Wget to use for http, https, and ftp. | 142 | # You can set the default proxies for Wget to use for http, https, and ftp. |
131 | # They will override the value in the environment. | 143 | # They will override the value in the environment. |
@@ -136,24 +148,53 @@ To use them, remove the comments: :: | |||
136 | # If you do not want to use proxy at all, set this to off. | 148 | # If you do not want to use proxy at all, set this to off. |
137 | #use_proxy = on | 149 | #use_proxy = on |
138 | 150 | ||
151 | The build system also accepts ``http_proxy``, ``ftp_proxy``, ``https_proxy``, | ||
152 | and ``all_proxy`` set as to standard shell environment variables to redirect | ||
153 | requests through proxy servers. | ||
154 | |||
139 | The Yocto Project also includes a | 155 | The Yocto Project also includes a |
140 | ``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS | 156 | ``meta-poky/conf/templates/default/site.conf.sample`` file that shows |
141 | and Git proxy servers if needed. For more information on setting up | 157 | how to configure CVS and Git proxy servers if needed. |
142 | various proxy types and configuring proxy servers, see the | ||
143 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" | ||
144 | Wiki page. | ||
145 | 158 | ||
146 | **Q:** What's the difference between target and target\ ``-native``? | 159 | .. note:: |
147 | 160 | ||
148 | **A:** The ``*-native`` targets are designed to run on the system being | 161 | You can find more information on the |
149 | used for the build. These are usually tools that are needed to assist | 162 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" |
150 | the build in some way such as ``quilt-native``, which is used to apply | 163 | Wiki page. |
151 | patches. The non-native version is the one that runs on the target | 164 | |
152 | device. | 165 | Using the OpenEmbedded Build system |
166 | =================================== | ||
167 | |||
168 | How do I use an external toolchain? | ||
169 | ----------------------------------- | ||
170 | |||
171 | See the ":ref:`dev-manual/external-toolchain:optionally using an external toolchain`" | ||
172 | section in the Development Task manual. | ||
173 | |||
174 | Why do I get chmod permission issues? | ||
175 | ------------------------------------- | ||
153 | 176 | ||
154 | **Q:** I'm seeing random build failures. Help?! | 177 | If you see the error |
178 | ``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``, | ||
179 | you are probably running the build on an NTFS filesystem. Instead, | ||
180 | run the build system on a partition with a modern Linux filesystem such as | ||
181 | ``ext4``, ``btrfs`` or ``xfs``. | ||
155 | 182 | ||
156 | **A:** If the same build is failing in totally different and random | 183 | I see many 404 errors trying to download sources. Is anything wrong? |
184 | -------------------------------------------------------------------- | ||
185 | |||
186 | Nothing is wrong. The OpenEmbedded build system checks any | ||
187 | configured source mirrors before downloading from the upstream sources. | ||
188 | The build system does this searching for both source archives and | ||
189 | pre-checked out versions of SCM-managed software. These checks help in | ||
190 | large installations because it can reduce load on the SCM servers | ||
191 | themselves. This can also allow builds to continue to work if an | ||
192 | upstream source disappears. | ||
193 | |||
194 | Why do I get random build failures? | ||
195 | ----------------------------------- | ||
196 | |||
197 | If the same build is failing in totally different and random | ||
157 | ways, the most likely explanation is: | 198 | ways, the most likely explanation is: |
158 | 199 | ||
159 | - The hardware you are running the build on has some problem. | 200 | - The hardware you are running the build on has some problem. |
@@ -166,222 +207,139 @@ causes lots of network, disk and CPU activity and is sensitive to even | |||
166 | single-bit failures in any of these areas. True random failures have | 207 | single-bit failures in any of these areas. True random failures have |
167 | always been traced back to hardware or virtualization issues. | 208 | always been traced back to hardware or virtualization issues. |
168 | 209 | ||
169 | **Q:** When I try to build a native recipe, the build fails with | 210 | Why does the build fail with ``iconv.h`` problems? |
170 | ``iconv.h`` problems. | 211 | -------------------------------------------------- |
171 | 212 | ||
172 | **A:** If you get an error message that indicates GNU ``libiconv`` is | 213 | When you try to build a native recipe, you may get an error message that |
173 | not in use but ``iconv.h`` has been included from ``libiconv``, you need | 214 | indicates that GNU ``libiconv`` is not in use but ``iconv.h`` has been |
174 | to check to see if you have a previously installed version of the header | 215 | included from ``libiconv``:: |
175 | file in ``/usr/local/include``. | ||
176 | :: | ||
177 | 216 | ||
178 | #error GNU libiconv not in use but included iconv.h is from libiconv | 217 | #error GNU libiconv not in use but included iconv.h is from libiconv |
179 | 218 | ||
180 | If you find a previously installed | 219 | When this happens, you need to check whether you have a previously |
181 | file, you should either uninstall it or temporarily rename it and try | 220 | installed version of the header file in ``/usr/local/include/``. |
182 | the build again. | 221 | If that's the case, you should either uninstall it or temporarily rename |
222 | it and try the build again. | ||
183 | 223 | ||
184 | This issue is just a single manifestation of "system leakage" issues | 224 | This issue is just a single manifestation of "system leakage" issues |
185 | caused when the OpenEmbedded build system finds and uses previously | 225 | caused when the OpenEmbedded build system finds and uses previously |
186 | installed files during a native build. This type of issue might not be | 226 | installed files during a native build. This type of issue might not be |
187 | limited to ``iconv.h``. Be sure that leakage cannot occur from | 227 | limited to ``iconv.h``. Make sure that leakage cannot occur from |
188 | ``/usr/local/include`` and ``/opt`` locations. | 228 | ``/usr/local/include`` and ``/opt`` locations. |
189 | 229 | ||
190 | **Q:** What do we need to ship for license compliance? | 230 | Why don't other recipes find the files provided by my ``*-native`` recipe? |
191 | 231 | -------------------------------------------------------------------------- | |
192 | **A:** This is a difficult question and you need to consult your lawyer | ||
193 | for the answer for your specific case. It is worth bearing in mind that | ||
194 | for GPL compliance, there needs to be enough information shipped to | ||
195 | allow someone else to rebuild and produce the same end result you are | ||
196 | shipping. This means sharing the source code, any patches applied to it, | ||
197 | and also any configuration information about how that package was | ||
198 | configured and built. | ||
199 | |||
200 | You can find more information on licensing in the | ||
201 | ":ref:`overview-manual/development-environment:licensing`" | ||
202 | section in the Yocto | ||
203 | Project Overview and Concepts Manual and also in the | ||
204 | ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
205 | section in the Yocto Project Development Tasks Manual. | ||
206 | |||
207 | **Q:** How do I disable the cursor on my touchscreen device? | ||
208 | |||
209 | **A:** You need to create a form factor file as described in the | ||
210 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
211 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
212 | the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: | ||
213 | :: | ||
214 | |||
215 | HAVE_TOUCHSCREEN=1 | ||
216 | |||
217 | **Q:** How do I make sure connected network interfaces are brought up by | ||
218 | default? | ||
219 | |||
220 | **A:** The default interfaces file provided by the netbase recipe does | ||
221 | not automatically bring up network interfaces. Therefore, you will need | ||
222 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
223 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
224 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
225 | information on creating these types of miscellaneous recipe files. | ||
226 | |||
227 | For example, add the following files to your layer: :: | ||
228 | |||
229 | meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces | ||
230 | meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend | ||
231 | |||
232 | **Q:** How do I create images with more free space? | ||
233 | |||
234 | **A:** By default, the OpenEmbedded build system creates images that are | ||
235 | 1.3 times the size of the populated root filesystem. To affect the image | ||
236 | size, you need to set various configurations: | ||
237 | |||
238 | - *Image Size:* The OpenEmbedded build system uses the | ||
239 | :term:`IMAGE_ROOTFS_SIZE` variable to define | ||
240 | the size of the image in Kbytes. The build system determines the size | ||
241 | by taking into account the initial root filesystem size before any | ||
242 | modifications such as requested size for the image and any requested | ||
243 | additional free disk space to be added to the image. | ||
244 | |||
245 | - *Overhead:* Use the | ||
246 | :term:`IMAGE_OVERHEAD_FACTOR` variable | ||
247 | to define the multiplier that the build system applies to the initial | ||
248 | image size, which is 1.3 by default. | ||
249 | |||
250 | - *Additional Free Space:* Use the | ||
251 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
252 | variable to add additional free space to the image. The build system | ||
253 | adds this space to the image after it determines its | ||
254 | ``IMAGE_ROOTFS_SIZE``. | ||
255 | |||
256 | **Q:** Why don't you support directories with spaces in the pathnames? | ||
257 | |||
258 | **A:** The Yocto Project team has tried to do this before but too many | ||
259 | of the tools the OpenEmbedded build system depends on, such as | ||
260 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
261 | situation changes, the team will not support spaces in pathnames. | ||
262 | |||
263 | **Q:** How do I use an external toolchain? | ||
264 | |||
265 | **A:** The toolchain configuration is very flexible and customizable. It | ||
266 | is primarily controlled with the ``TCMODE`` variable. This variable | ||
267 | controls which ``tcmode-*.inc`` file to include from the | ||
268 | ``meta/conf/distro/include`` directory within the :term:`Source Directory`. | ||
269 | |||
270 | The default value of ``TCMODE`` is "default", which tells the | ||
271 | OpenEmbedded build system to use its internally built toolchain (i.e. | ||
272 | ``tcmode-default.inc``). However, other patterns are accepted. In | ||
273 | particular, "external-\*" refers to external toolchains. One example is | ||
274 | the Sourcery G++ Toolchain. The support for this toolchain resides in | ||
275 | the separate ``meta-sourcery`` layer at | ||
276 | https://github.com/MentorEmbedded/meta-sourcery/. | ||
277 | |||
278 | In addition to the toolchain configuration, you also need a | ||
279 | corresponding toolchain recipe file. This recipe file needs to package | ||
280 | up any pre-built objects in the toolchain such as ``libgcc``, | ||
281 | ``libstdcc++``, any locales, and ``libc``. | ||
282 | |||
283 | **Q:** How does the OpenEmbedded build system obtain source code and | ||
284 | will it work behind my firewall or proxy server? | ||
285 | 232 | ||
286 | **A:** The way the build system obtains source code is highly | 233 | Files provided by your native recipe could be missing from the native |
287 | configurable. You can setup the build system to get source code in most | 234 | sysroot, your recipe could also be installing to the wrong place, or you |
288 | environments if HTTP transport is available. | 235 | could be getting permission errors during the :ref:`ref-tasks-install` |
289 | 236 | task in your recipe. | |
290 | When the build system searches for source code, it first tries the local | ||
291 | download directory. If that location fails, Poky tries | ||
292 | :term:`PREMIRRORS`, the upstream source, and then | ||
293 | :term:`MIRRORS` in that order. | ||
294 | |||
295 | Assuming your distribution is "poky", the OpenEmbedded build system uses | ||
296 | the Yocto Project source ``PREMIRRORS`` by default for SCM-based | ||
297 | sources, upstreams for normal tarballs, and then falls back to a number | ||
298 | of other mirrors including the Yocto Project source mirror if those | ||
299 | fail. | ||
300 | 237 | ||
301 | As an example, you could add a specific server for the build system to | 238 | This situation happens when the build system used by a package does not |
302 | attempt before any others by adding something like the following to the | 239 | recognize the environment variables supplied to it by :term:`BitBake`. The |
303 | ``local.conf`` configuration file: :: | 240 | incident that prompted this FAQ entry involved a Makefile that used an |
241 | environment variable named ``BINDIR`` instead of the more standard | ||
242 | variable ``bindir``. The makefile's hardcoded default value of | ||
243 | "/usr/bin" worked most of the time, but not for the recipe's ``-native`` | ||
244 | variant. For another example, permission errors might be caused by a | ||
245 | Makefile that ignores ``DESTDIR`` or uses a different name for that | ||
246 | environment variable. Check the build system of the package to see if | ||
247 | these kinds of issues exist. | ||
304 | 248 | ||
305 | PREMIRRORS_prepend = "\ | 249 | Can I get rid of build output so I can start over? |
306 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | 250 | -------------------------------------------------- |
307 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
308 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
309 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
310 | 251 | ||
311 | These changes cause the build system to intercept Git, FTP, HTTP, and | 252 | Yes --- you can easily do this. When you use BitBake to build an |
312 | HTTPS requests and direct them to the ``http://`` sources mirror. You | 253 | image, all the build output goes into the directory created when you run |
313 | can use ``file://`` URLs to point to local directories or network shares | 254 | the build environment setup script (i.e. :ref:`structure-core-script`). |
314 | as well. | 255 | By default, this :term:`Build Directory` is named ``build`` but can be named |
256 | anything you want. | ||
315 | 257 | ||
316 | Aside from the previous technique, these options also exist: | 258 | Within the :term:`Build Directory`, is the ``tmp`` directory. To remove all the |
317 | :: | 259 | build output yet preserve any source code or downloaded files from |
260 | previous builds, simply remove the ``tmp`` directory. | ||
318 | 261 | ||
319 | BB_NO_NETWORK = "1" | 262 | Customizing generated images |
263 | ============================ | ||
320 | 264 | ||
321 | This statement tells BitBake to issue an error | 265 | What does the OpenEmbedded build system produce as output? |
322 | instead of trying to access the Internet. This technique is useful if | 266 | ---------------------------------------------------------- |
323 | you want to ensure code builds only from local sources. | ||
324 | 267 | ||
325 | Here is another technique: | 268 | Because you can use the same set of recipes to create output of |
326 | :: | 269 | various formats, the output of an OpenEmbedded build depends on how you |
270 | start it. Usually, the output is a flashable image ready for the target | ||
271 | device. | ||
327 | 272 | ||
328 | BB_FETCH_PREMIRRORONLY = "1" | 273 | How do I make the Yocto Project support my board? |
274 | ------------------------------------------------- | ||
329 | 275 | ||
330 | This statement | 276 | Support for an additional board is added by creating a Board |
331 | limits the build system to pulling source from the ``PREMIRRORS`` only. | 277 | Support Package (BSP) layer for it. For more information on how to |
332 | Again, this technique is useful for reproducing builds. | 278 | create a BSP layer, see the |
279 | ":ref:`dev-manual/layers:understanding and creating layers`" | ||
280 | section in the Yocto Project Development Tasks Manual and the | ||
281 | :doc:`/bsp-guide/index`. | ||
333 | 282 | ||
334 | Here is another technique: | 283 | Usually, if the board is not completely exotic, adding support in the |
335 | :: | 284 | Yocto Project is fairly straightforward. |
336 | 285 | ||
337 | BB_GENERATE_MIRROR_TARBALLS = "1" | 286 | How do I make the Yocto Project support my package? |
287 | --------------------------------------------------- | ||
338 | 288 | ||
339 | This | 289 | To add a package, you need to create a BitBake recipe. For |
340 | statement tells the build system to generate mirror tarballs. This | 290 | information on how to create a BitBake recipe, see the |
341 | technique is useful if you want to create a mirror server. If not, | 291 | ":ref:`dev-manual/new-recipe:writing a new recipe`" |
342 | however, the technique can simply waste time during the build. | 292 | section in the Yocto Project Development Tasks Manual. |
343 | 293 | ||
344 | Finally, consider an example where you are behind an HTTP-only firewall. | 294 | What do I need to ship for license compliance? |
345 | You could make the following changes to the ``local.conf`` configuration | 295 | ---------------------------------------------- |
346 | file as long as the ``PREMIRRORS`` server is current: :: | ||
347 | 296 | ||
348 | PREMIRRORS_prepend = "\ | 297 | This is a difficult question and you need to consult your lawyer |
349 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | 298 | for the answer for your specific case. It is worth bearing in mind that |
350 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | 299 | for GPL compliance, there needs to be enough information shipped to |
351 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | 300 | allow someone else to rebuild and produce the same end result you are |
352 | BB_FETCH_PREMIRRORONLY = "1" | 301 | shipping. This means sharing the source code, any patches applied to it, |
302 | and also any configuration information about how that package was | ||
303 | configured and built. | ||
353 | 304 | ||
354 | These changes would cause the build system to successfully fetch source | 305 | You can find more information on licensing in the |
355 | over HTTP and any network accesses to anything other than the | 306 | ":ref:`overview-manual/development-environment:licensing`" |
356 | ``PREMIRRORS`` would fail. | 307 | section in the Yocto Project Overview and Concepts Manual and also in the |
308 | ":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" | ||
309 | section in the Yocto Project Development Tasks Manual. | ||
357 | 310 | ||
358 | The build system also honors the standard shell environment variables | 311 | Do I have to make a full reflash after recompiling one package? |
359 | ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to | 312 | --------------------------------------------------------------- |
360 | redirect requests through proxy servers. | ||
361 | 313 | ||
362 | .. note:: | 314 | The OpenEmbedded build system can build packages in various |
315 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | ||
316 | then upgrade only the modified packages using the package tools on the device, | ||
317 | much like on a desktop distribution such as Ubuntu or Fedora. However, | ||
318 | package management on the target is entirely optional. | ||
363 | 319 | ||
364 | You can find more information on the | 320 | How to prevent my package from being marked as machine specific? |
365 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" | 321 | ---------------------------------------------------------------- |
366 | Wiki page. | ||
367 | 322 | ||
368 | **Q:** Can I get rid of build output so I can start over? | 323 | If you have machine-specific data in a package for one machine only |
324 | but the package is being marked as machine-specific in all cases, | ||
325 | you can set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file. | ||
326 | However, but make sure the package is manually marked as machine-specific for the | ||
327 | case that needs it. The code that handles :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` | ||
328 | is in the ``meta/classes-global/base.bbclass`` file. | ||
369 | 329 | ||
370 | **A:** Yes - you can easily do this. When you use BitBake to build an | 330 | What's the difference between ``target`` and ``target-native``? |
371 | image, all the build output goes into the directory created when you run | 331 | --------------------------------------------------------------- |
372 | the build environment setup script (i.e. | ||
373 | :ref:`structure-core-script`). By default, this :term:`Build Directory` | ||
374 | is named ``build`` but can be named | ||
375 | anything you want. | ||
376 | 332 | ||
377 | Within the Build Directory, is the ``tmp`` directory. To remove all the | 333 | The ``*-native`` targets are designed to run on the system being |
378 | build output yet preserve any source code or downloaded files from | 334 | used for the build. These are usually tools that are needed to assist |
379 | previous builds, simply remove the ``tmp`` directory. | 335 | the build in some way such as ``quilt-native``, which is used to apply |
336 | patches. The non-native version is the one that runs on the target | ||
337 | device. | ||
380 | 338 | ||
381 | **Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for | 339 | Why do ``${bindir}`` and ``${libdir}`` have strange values for ``-native`` recipes? |
382 | ``-native`` recipes? | 340 | ----------------------------------------------------------------------------------- |
383 | 341 | ||
384 | **A:** Executables and libraries might need to be used from a directory | 342 | Executables and libraries might need to be used from a directory |
385 | other than the directory into which they were initially installed. | 343 | other than the directory into which they were initially installed. |
386 | Complicating this situation is the fact that sometimes these executables | 344 | Complicating this situation is the fact that sometimes these executables |
387 | and libraries are compiled with the expectation of being run from that | 345 | and libraries are compiled with the expectation of being run from that |
@@ -408,20 +366,13 @@ system of that image. Thus, the build system provides a value of | |||
408 | forth. | 366 | forth. |
409 | 367 | ||
410 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. | 368 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. |
411 | However, when the recipe builds a | 369 | However, when the recipe builds a native program (i.e. one that is |
412 | native program (i.e. one that is intended to run on the build machine), | 370 | intended to run on the build machine), that program is never installed |
413 | that program is never installed directly to the build machine's root | 371 | directly to the build machine's root file system. Consequently, the build |
414 | file system. Consequently, the build system uses paths within the Build | 372 | system uses paths within the Build Directory for ``DESTDIR``, ``bindir`` |
415 | Directory for ``DESTDIR``, ``bindir`` and related variables. To better | 373 | and related variables. To better understand this, consider the following |
416 | understand this, consider the following two paths where the first is | 374 | two paths (artificially broken across lines for readability) where the |
417 | relatively normal and the second is not: | 375 | first is relatively normal and the second is not:: |
418 | |||
419 | .. note:: | ||
420 | |||
421 | Due to these lengthy examples, the paths are artificially broken | ||
422 | across lines for readability. | ||
423 | |||
424 | :: | ||
425 | 376 | ||
426 | /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ | 377 | /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ |
427 | 1.2.8-r0/sysroot-destdir/usr/bin | 378 | 1.2.8-r0/sysroot-destdir/usr/bin |
@@ -430,35 +381,76 @@ relatively normal and the second is not: | |||
430 | zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ | 381 | zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ |
431 | build/tmp/sysroots/x86_64-linux/usr/bin | 382 | build/tmp/sysroots/x86_64-linux/usr/bin |
432 | 383 | ||
433 | Even if the paths look unusual, | 384 | Even if the paths look unusual, they both are correct --- the first for |
434 | they both are correct - the first for a target and the second for a | 385 | a target and the second for a native recipe. These paths are a consequence |
435 | native recipe. These paths are a consequence of the ``DESTDIR`` | 386 | of the ``DESTDIR`` mechanism and while they appear strange, they are correct |
436 | mechanism and while they appear strange, they are correct and in | 387 | and in practice very effective. |
437 | practice very effective. | ||
438 | 388 | ||
439 | **Q:** The files provided by my ``*-native`` recipe do not appear to be | 389 | How do I create images with more free space? |
440 | available to other recipes. Files are missing from the native sysroot, | 390 | -------------------------------------------- |
441 | my recipe is installing to the wrong place, or I am getting permissions | ||
442 | errors during the do_install task in my recipe! What is wrong? | ||
443 | 391 | ||
444 | **A:** This situation results when a build system does not recognize the | 392 | By default, the OpenEmbedded build system creates images that are |
445 | environment variables supplied to it by :term:`BitBake`. The | 393 | 1.3 times the size of the populated root filesystem. To affect the image |
446 | incident that prompted this FAQ entry involved a Makefile that used an | 394 | size, you need to set various configurations: |
447 | environment variable named ``BINDIR`` instead of the more standard | 395 | |
448 | variable ``bindir``. The makefile's hardcoded default value of | 396 | - *Image Size:* The OpenEmbedded build system uses the |
449 | "/usr/bin" worked most of the time, but not for the recipe's ``-native`` | 397 | :term:`IMAGE_ROOTFS_SIZE` variable to define |
450 | variant. For another example, permissions errors might be caused by a | 398 | the size of the image in Kbytes. The build system determines the size |
451 | Makefile that ignores ``DESTDIR`` or uses a different name for that | 399 | by taking into account the initial root filesystem size before any |
452 | environment variable. Check the the build system to see if these kinds | 400 | modifications such as requested size for the image and any requested |
453 | of issues exist. | 401 | additional free disk space to be added to the image. |
454 | 402 | ||
455 | **Q:** I'm adding a binary in a recipe but it's different in the image, what is | 403 | - *Overhead:* Use the |
456 | changing it? | 404 | :term:`IMAGE_OVERHEAD_FACTOR` variable |
457 | 405 | to define the multiplier that the build system applies to the initial | |
458 | **A:** The first most obvious change is the system stripping debug symbols from | 406 | image size, which is 1.3 by default. |
459 | it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being stripped and/or | 407 | |
460 | :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols being split into a separate | 408 | - *Additional Free Space:* Use the |
461 | file will ensure the binary is unchanged. The other less obvious thing that can | 409 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` |
462 | happen is prelinking of the image. This is set by default in local.conf via | 410 | variable to add additional free space to the image. The build system |
463 | :term:`USER_CLASSES` which can contain 'image-prelink'. If you remove that, the | 411 | adds this space to the image after it determines its |
464 | image will not be prelinked meaning the binaries would be unchanged. | 412 | :term:`IMAGE_ROOTFS_SIZE`. |
413 | |||
414 | Why aren't spaces in path names supported? | ||
415 | ------------------------------------------ | ||
416 | |||
417 | The Yocto Project team has tried to do this before but too many | ||
418 | of the tools the OpenEmbedded build system depends on, such as | ||
419 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
420 | situation changes, the team will not support spaces in pathnames. | ||
421 | |||
422 | I'm adding a binary in a recipe. Why is it different in the image? | ||
423 | ------------------------------------------------------------------ | ||
424 | |||
425 | The first most obvious change is the system stripping debug symbols from | ||
426 | it. Setting :term:`INHIBIT_PACKAGE_STRIP` to stop debug symbols being | ||
427 | stripped and/or :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` to stop debug symbols | ||
428 | being split into a separate file will ensure the binary is unchanged. | ||
429 | |||
430 | Issues on the running system | ||
431 | ============================ | ||
432 | |||
433 | How do I disable the cursor on my touchscreen device? | ||
434 | ----------------------------------------------------- | ||
435 | |||
436 | You need to create a form factor file as described in the | ||
437 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
438 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
439 | the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:: | ||
440 | |||
441 | HAVE_TOUCHSCREEN=1 | ||
442 | |||
443 | How to always bring up connected network interfaces? | ||
444 | ---------------------------------------------------- | ||
445 | |||
446 | The default interfaces file provided by the netbase recipe does | ||
447 | not automatically bring up network interfaces. Therefore, you will need | ||
448 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
449 | ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in | ||
450 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
451 | information on creating these types of miscellaneous recipe files. | ||
452 | |||
453 | For example, add the following files to your layer:: | ||
454 | |||
455 | meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces | ||
456 | meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend | ||