diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/index.rst')
-rw-r--r-- | documentation/brief-yoctoprojectqs/index.rst | 430 |
1 files changed, 430 insertions, 0 deletions
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 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ========================= | ||
4 | Yocto Project Quick Build | ||
5 | ========================= | ||
6 | |||
7 | Welcome! | ||
8 | ======== | ||
9 | |||
10 | This short document steps you through the process for a typical | ||
11 | image build using the Yocto Project. The document also introduces how to | ||
12 | configure a build for specific hardware. You will use Yocto Project to | ||
13 | build a reference embedded OS called Poky. | ||
14 | |||
15 | .. note:: | ||
16 | |||
17 | - The examples in this paper assume you are using a native Linux | ||
18 | system running a recent Ubuntu Linux distribution. If the machine | ||
19 | you want to use Yocto Project on to build an image | ||
20 | (:term:`Build Host`) is not | ||
21 | a native Linux system, you can still perform these steps by using | ||
22 | CROss PlatformS (CROPS) and setting up a Poky container. See the | ||
23 | :ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)` | ||
24 | section | ||
25 | in the Yocto Project Development Tasks Manual for more | ||
26 | information. | ||
27 | |||
28 | - You may use Windows Subsystem For Linux v2 to set up a build host | ||
29 | using Windows 10. | ||
30 | |||
31 | .. note:: | ||
32 | |||
33 | The Yocto Project is not compatible with WSLv1, it is | ||
34 | compatible but not officially supported nor validated with | ||
35 | WSLv2, if you still decide to use WSL please upgrade to WSLv2. | ||
36 | |||
37 | See the :ref:`dev-manual/dev-manual-start:setting up to use windows | ||
38 | subsystem for linux (wslv2)` section in the Yocto Project Development | ||
39 | Tasks Manual for more information. | ||
40 | |||
41 | If you want more conceptual or background information on the Yocto | ||
42 | Project, see the :doc:`../overview-manual/index`. | ||
43 | |||
44 | Compatible Linux Distribution | ||
45 | ============================= | ||
46 | |||
47 | Make sure your :term:`Build Host` meets the | ||
48 | following requirements: | ||
49 | |||
50 | - 50 Gbytes of free disk space | ||
51 | |||
52 | - Runs a supported Linux distribution (i.e. recent releases of Fedora, | ||
53 | openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux | ||
54 | distributions that support the Yocto Project, see the | ||
55 | :ref:`ref-manual/ref-system-requirements:supported linux distributions` | ||
56 | section in the Yocto Project Reference Manual. For detailed | ||
57 | information on preparing your build host, see the | ||
58 | :ref:`dev-manual/dev-manual-start:preparing the build host` | ||
59 | section in the Yocto Project Development Tasks Manual. | ||
60 | |||
61 | - | ||
62 | |||
63 | - Git 1.8.3.1 or greater | ||
64 | - tar 1.28 or greater | ||
65 | - Python 3.5.0 or greater. | ||
66 | - gcc 5.0 or greater. | ||
67 | |||
68 | If your build host does not meet any of these three listed version | ||
69 | requirements, you can take steps to prepare the system so that you | ||
70 | can still use the Yocto Project. See the | ||
71 | :ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions` | ||
72 | section in the Yocto Project Reference Manual for information. | ||
73 | |||
74 | Build Host Packages | ||
75 | =================== | ||
76 | |||
77 | You must install essential host packages on your build host. The | ||
78 | following command installs the host packages based on an Ubuntu | ||
79 | distribution: | ||
80 | |||
81 | .. code-block:: shell | ||
82 | |||
83 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; | ||
84 | |||
85 | .. note:: | ||
86 | |||
87 | For host package requirements on all supported Linux distributions, | ||
88 | see the :ref:`ref-manual/ref-system-requirements:required packages for the build host` | ||
89 | section in the Yocto Project Reference Manual. | ||
90 | |||
91 | Use Git to Clone Poky | ||
92 | ===================== | ||
93 | |||
94 | Once you complete the setup instructions for your machine, you need to | ||
95 | get a copy of the Poky repository on your build host. Use the following | ||
96 | commands to clone the Poky repository. | ||
97 | |||
98 | .. code-block:: shell | ||
99 | |||
100 | $ git clone git://git.yoctoproject.org/poky | ||
101 | Cloning into 'poky'... | ||
102 | remote: Counting | ||
103 | objects: 432160, done. remote: Compressing objects: 100% | ||
104 | (102056/102056), done. remote: Total 432160 (delta 323116), reused | ||
105 | 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. | ||
106 | Resolving deltas: 100% (323116/323116), done. | ||
107 | Checking connectivity... done. | ||
108 | |||
109 | Move to the ``poky`` directory and take a look at the tags: | ||
110 | |||
111 | .. code-block:: shell | ||
112 | |||
113 | $ cd poky | ||
114 | $ git fetch --tags | ||
115 | $ git tag | ||
116 | 1.1_M1.final | ||
117 | 1.1_M1.rc1 | ||
118 | 1.1_M1.rc2 | ||
119 | 1.1_M2.final | ||
120 | 1.1_M2.rc1 | ||
121 | . | ||
122 | . | ||
123 | . | ||
124 | yocto-2.5 | ||
125 | yocto-2.5.1 | ||
126 | yocto-2.5.2 | ||
127 | yocto-2.6 | ||
128 | yocto-2.6.1 | ||
129 | yocto-2.6.2 | ||
130 | yocto-2.7 | ||
131 | yocto_1.5_M5.rc8 | ||
132 | |||
133 | For this example, check out the branch based on the | ||
134 | ``&DISTRO_REL_TAG;`` release: | ||
135 | |||
136 | .. code-block:: shell | ||
137 | |||
138 | $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; | ||
139 | Switched to a new branch 'my-&DISTRO_REL_TAG;' | ||
140 | |||
141 | The previous Git checkout command creates a local branch named | ||
142 | ``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly | ||
143 | match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development | ||
144 | branch at the time of the Yocto Project &DISTRO_REL_TAG; release. | ||
145 | |||
146 | For more options and information about accessing Yocto Project related | ||
147 | repositories, see the | ||
148 | :ref:`dev-manual/dev-manual-start:locating yocto project source files` | ||
149 | section in the Yocto Project Development Tasks Manual. | ||
150 | |||
151 | Building Your Image | ||
152 | =================== | ||
153 | |||
154 | Use the following steps to build your image. The build process creates | ||
155 | an entire Linux distribution, including the toolchain, from source. | ||
156 | |||
157 | .. note:: | ||
158 | |||
159 | - If you are working behind a firewall and your build host is not | ||
160 | set up for proxies, you could encounter problems with the build | ||
161 | process when fetching source code (e.g. fetcher failures or Git | ||
162 | failures). | ||
163 | |||
164 | - If you do not know your proxy settings, consult your local network | ||
165 | infrastructure resources and get that information. A good starting | ||
166 | point could also be to check your web browser settings. Finally, | ||
167 | you can find more information on the | ||
168 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" | ||
169 | page of the Yocto Project Wiki. | ||
170 | |||
171 | #. **Initialize the Build Environment:** From within the ``poky`` | ||
172 | directory, run the :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` | ||
173 | environment | ||
174 | setup script to define Yocto Project's build environment on your | ||
175 | build host. | ||
176 | |||
177 | .. code-block:: shell | ||
178 | |||
179 | $ cd ~/poky | ||
180 | $ source oe-init-build-env | ||
181 | You had no conf/local.conf file. This configuration file has therefore been | ||
182 | created for you with some default values. You may wish to edit it to, for | ||
183 | example, select a different MACHINE (target hardware). See conf/local.conf | ||
184 | for more information as common configuration options are commented. | ||
185 | |||
186 | You had no conf/bblayers.conf file. This configuration file has therefore | ||
187 | been created for you with some default values. To add additional metadata | ||
188 | layers into your configuration please add entries to conf/bblayers.conf. | ||
189 | |||
190 | The Yocto Project has extensive documentation about OE including a reference | ||
191 | manual which can be found at: | ||
192 | http://yoctoproject.org/documentation | ||
193 | |||
194 | For more information about OpenEmbedded see their website: | ||
195 | http://www.openembedded.org/ | ||
196 | |||
197 | ### Shell environment set up for builds. ### | ||
198 | |||
199 | You can now run 'bitbake <target>' | ||
200 | |||
201 | Common targets are: | ||
202 | core-image-minimal | ||
203 | core-image-sato | ||
204 | meta-toolchain | ||
205 | meta-ide-support | ||
206 | |||
207 | You can also run generated qemu images with a command like 'runqemu qemux86-64' | ||
208 | |||
209 | Among other things, the script creates the :term:`Build Directory`, which is | ||
210 | ``build`` in this case and is located in the :term:`Source Directory`. After | ||
211 | the script runs, your current working directory is set to the Build | ||
212 | Directory. Later, when the build completes, the Build Directory contains all the | ||
213 | files created during the build. | ||
214 | |||
215 | #. **Examine Your Local Configuration File:** When you set up the build | ||
216 | environment, a local configuration file named ``local.conf`` becomes | ||
217 | available in a ``conf`` subdirectory of the Build Directory. For this | ||
218 | example, the defaults are set to build for a ``qemux86`` target, | ||
219 | which is suitable for emulation. The package manager used is set to | ||
220 | the RPM package manager. | ||
221 | |||
222 | .. tip:: | ||
223 | |||
224 | You can significantly speed up your build and guard against fetcher | ||
225 | failures by using mirrors. To use mirrors, add these lines to your | ||
226 | local.conf file in the Build directory: :: | ||
227 | |||
228 | SSTATE_MIRRORS = "\ | ||
229 | file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ | ||
230 | file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ | ||
231 | file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ | ||
232 | " | ||
233 | |||
234 | |||
235 | The previous examples showed how to add sstate paths for Yocto Project | ||
236 | &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development | ||
237 | area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/. | ||
238 | |||
239 | #. **Start the Build:** Continue with the following command to build an OS | ||
240 | image for the target, which is ``core-image-sato`` in this example: | ||
241 | |||
242 | .. code-block:: shell | ||
243 | |||
244 | $ bitbake core-image-sato | ||
245 | |||
246 | For information on using the ``bitbake`` command, see the | ||
247 | :ref:`overview-manual/overview-manual-concepts:bitbake` section in the Yocto Project Overview and | ||
248 | Concepts Manual, or see the ":ref:`BitBake Command | ||
249 | <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. | ||
250 | |||
251 | #. **Simulate Your Image Using QEMU:** Once this particular image is | ||
252 | built, you can start QEMU, which is a Quick EMUlator that ships with | ||
253 | the Yocto Project: | ||
254 | |||
255 | .. code-block:: shell | ||
256 | |||
257 | $ runqemu qemux86-64 | ||
258 | |||
259 | If you want to learn more about running QEMU, see the | ||
260 | :ref:`dev-manual/dev-manual-qemu:using the quick emulator (qemu)` chapter in | ||
261 | the Yocto Project Development Tasks Manual. | ||
262 | |||
263 | #. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing | ||
264 | ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU. | ||
265 | |||
266 | Customizing Your Build for Specific Hardware | ||
267 | ============================================ | ||
268 | |||
269 | So far, all you have done is quickly built an image suitable for | ||
270 | emulation only. This section shows you how to customize your build for | ||
271 | specific hardware by adding a hardware layer into the Yocto Project | ||
272 | development environment. | ||
273 | |||
274 | In general, layers are repositories that contain related sets of | ||
275 | instructions and configurations that tell the Yocto Project what to do. | ||
276 | Isolating related metadata into functionally specific layers facilitates | ||
277 | modular development and makes it easier to reuse the layer metadata. | ||
278 | |||
279 | .. note:: | ||
280 | |||
281 | By convention, layer names start with the string "meta-". | ||
282 | |||
283 | Follow these steps to add a hardware layer: | ||
284 | |||
285 | #. **Find a Layer:** Lots of hardware layers exist. The Yocto Project | ||
286 | :yocto_git:`Source Repositories <>` has many hardware layers. | ||
287 | This example adds the | ||
288 | `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer. | ||
289 | |||
290 | #. **Clone the Layer:** Use Git to make a local copy of the layer on your | ||
291 | machine. You can put the copy in the top level of the copy of the | ||
292 | Poky repository created earlier: | ||
293 | |||
294 | .. code-block:: shell | ||
295 | |||
296 | $ cd ~/poky | ||
297 | $ git clone https://github.com/kraj/meta-altera.git | ||
298 | Cloning into 'meta-altera'... | ||
299 | remote: Counting objects: 25170, done. | ||
300 | remote: Compressing objects: 100% (350/350), done. | ||
301 | remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 | ||
302 | Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. | ||
303 | Resolving deltas: 100% (13385/13385), done. | ||
304 | Checking connectivity... done. | ||
305 | |||
306 | The hardware layer now exists | ||
307 | with other layers inside the Poky reference repository on your build | ||
308 | host as ``meta-altera`` and contains all the metadata needed to | ||
309 | support hardware from Altera, which is owned by Intel. | ||
310 | |||
311 | .. note:: | ||
312 | |||
313 | It is recommended for layers to have a branch per Yocto Project release. | ||
314 | Please make sure to checkout the layer branch supporting the Yocto Project | ||
315 | release you're using. | ||
316 | |||
317 | #. **Change the Configuration to Build for a Specific Machine:** The | ||
318 | :term:`MACHINE` variable in the | ||
319 | ``local.conf`` file specifies the machine for the build. For this | ||
320 | example, set the ``MACHINE`` variable to ``cyclone5``. These | ||
321 | configurations are used: | ||
322 | https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf. | ||
323 | |||
324 | .. note:: | ||
325 | |||
326 | See the "Examine Your Local Configuration File" step earlier for more | ||
327 | information on configuring the build. | ||
328 | |||
329 | #. **Add Your Layer to the Layer Configuration File:** Before you can use | ||
330 | a layer during a build, you must add it to your ``bblayers.conf`` | ||
331 | file, which is found in the | ||
332 | :term:`Build Directory` ``conf`` | ||
333 | directory. | ||
334 | |||
335 | Use the ``bitbake-layers add-layer`` command to add the layer to the | ||
336 | configuration file: | ||
337 | |||
338 | .. code-block:: shell | ||
339 | |||
340 | $ cd ~/poky/build | ||
341 | $ bitbake-layers add-layer ../meta-altera | ||
342 | NOTE: Starting bitbake server... | ||
343 | Parsing recipes: 100% |##################################################################| Time: 0:00:32 | ||
344 | Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, | ||
345 | 123 skipped, 0 masked, 0 errors. | ||
346 | |||
347 | You can find | ||
348 | more information on adding layers in the | ||
349 | :ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script` | ||
350 | section. | ||
351 | |||
352 | Completing these steps has added the ``meta-altera`` layer to your Yocto | ||
353 | Project development environment and configured it to build for the | ||
354 | ``cyclone5`` machine. | ||
355 | |||
356 | .. note:: | ||
357 | |||
358 | The previous steps are for demonstration purposes only. If you were | ||
359 | to attempt to build an image for the ``cyclone5`` machine, you should | ||
360 | read the Altera ``README``. | ||
361 | |||
362 | Creating Your Own General Layer | ||
363 | =============================== | ||
364 | |||
365 | Maybe you have an application or specific set of behaviors you need to | ||
366 | isolate. You can create your own general layer using the | ||
367 | ``bitbake-layers create-layer`` command. The tool automates layer | ||
368 | creation by setting up a subdirectory with a ``layer.conf`` | ||
369 | configuration file, a ``recipes-example`` subdirectory that contains an | ||
370 | ``example.bb`` recipe, a licensing file, and a ``README``. | ||
371 | |||
372 | The following commands run the tool to create a layer named | ||
373 | ``meta-mylayer`` in the ``poky`` directory: | ||
374 | |||
375 | .. code-block:: shell | ||
376 | |||
377 | $ cd ~/poky | ||
378 | $ bitbake-layers create-layer meta-mylayer | ||
379 | NOTE: Starting bitbake server... | ||
380 | Add your new layer with 'bitbake-layers add-layer meta-mylayer' | ||
381 | |||
382 | For more information | ||
383 | on layers and how to create them, see the | ||
384 | :ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script` | ||
385 | section in the Yocto Project Development Tasks Manual. | ||
386 | |||
387 | Where To Go Next | ||
388 | ================ | ||
389 | |||
390 | Now that you have experienced using the Yocto Project, you might be | ||
391 | asking yourself "What now?". The Yocto Project has many sources of | ||
392 | information including the website, wiki pages, and user manuals: | ||
393 | |||
394 | - **Website:** The :yocto_home:`Yocto Project Website <>` provides | ||
395 | background information, the latest builds, breaking news, full | ||
396 | development documentation, and access to a rich Yocto Project | ||
397 | Development Community into which you can tap. | ||
398 | |||
399 | - **Developer Screencast:** The `Getting Started with the Yocto Project - | ||
400 | New Developer Screencast Tutorial <http://vimeo.com/36450321>`__ | ||
401 | provides a 30-minute video created for users unfamiliar with the | ||
402 | Yocto Project but familiar with Linux build hosts. While this | ||
403 | screencast is somewhat dated, the introductory and fundamental | ||
404 | concepts are useful for the beginner. | ||
405 | |||
406 | - **Yocto Project Overview and Concepts Manual:** The | ||
407 | :doc:`../overview-manual/index` is a great | ||
408 | place to start to learn about the Yocto Project. This manual | ||
409 | introduces you to the Yocto Project and its development environment. | ||
410 | The manual also provides conceptual information for various aspects | ||
411 | of the Yocto Project. | ||
412 | |||
413 | - **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>` | ||
414 | provides additional information on where to go next when ramping up | ||
415 | with the Yocto Project, release information, project planning, and QA | ||
416 | information. | ||
417 | |||
418 | - **Yocto Project Mailing Lists:** Related mailing lists provide a forum | ||
419 | for discussion, patch submission and announcements. Several mailing | ||
420 | lists exist and are grouped according to areas of concern. See the | ||
421 | :ref:`ref-manual/resources:mailing lists` | ||
422 | section in the Yocto Project Reference Manual for a complete list of | ||
423 | Yocto Project mailing lists. | ||
424 | |||
425 | - **Comprehensive List of Links and Other Documentation:** The | ||
426 | :ref:`ref-manual/resources:links and related documentation` | ||
427 | section in the Yocto Project Reference Manual provides a | ||
428 | comprehensive list of all related links and other user documentation. | ||
429 | |||
430 | .. include:: /boilerplate.rst | ||