blob: 63083cb13d1e7b16c74d3bd09ee8f85424d5e899 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3=========================
4Yocto Project Quick Build
5=========================
6
7Welcome!
8========
9
10This short document steps you through the process for a typical
11image build using the Yocto Project. The document also introduces how to
12configure a build for specific hardware. You will use Yocto Project to
13build 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060023 :ref:`dev-manual/start:setting up to use cross platforms (crops)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050024 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060037 See the :ref:`dev-manual/start:setting up to use windows
Andrew Geisslerc9f78652020-09-18 14:11:35 -050038 subsystem for linux (wslv2)` section in the Yocto Project Development
39 Tasks Manual for more information.
40
41If you want more conceptual or background information on the Yocto
Andrew Geissler09209ee2020-12-13 08:44:15 -060042Project, see the :doc:`/overview-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043
44Compatible Linux Distribution
45=============================
46
47Make sure your :term:`Build Host` meets the
48following 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
Andrew Geissler09209ee2020-12-13 08:44:15 -060055 :ref:`ref-manual/system-requirements:supported linux distributions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050056 section in the Yocto Project Reference Manual. For detailed
57 information on preparing your build host, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060058 :ref:`dev-manual/start:preparing the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059 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
68If your build host does not meet any of these three listed version
69requirements, you can take steps to prepare the system so that you
70can still use the Yocto Project. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -060071:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072section in the Yocto Project Reference Manual for information.
73
74Build Host Packages
75===================
76
77You must install essential host packages on your build host. The
78following command installs the host packages based on an Ubuntu
79distribution:
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,
Andrew Geissler09209ee2020-12-13 08:44:15 -060088 see the :ref:`ref-manual/system-requirements:required packages for the build host`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089 section in the Yocto Project Reference Manual.
90
91Use Git to Clone Poky
92=====================
93
94Once you complete the setup instructions for your machine, you need to
95get a copy of the Poky repository on your build host. Use the following
96commands 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
109Move 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
133For 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
141The previous Git checkout command creates a local branch named
142``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly
143match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development
144branch at the time of the Yocto Project &DISTRO_REL_TAG; release.
145
146For more options and information about accessing Yocto Project related
147repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600148:ref:`dev-manual/start:locating yocto project source files`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149section in the Yocto Project Development Tasks Manual.
150
151Building Your Image
152===================
153
154Use the following steps to build your image. The build process creates
155an 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600168 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500169 page of the Yocto Project Wiki.
170
171#. **Initialize the Build Environment:** From within the ``poky``
Andrew Geissler09209ee2020-12-13 08:44:15 -0600172 directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500180 $ source oe-init-build-env
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600247 :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248 Concepts Manual, or see the ":ref:`BitBake Command
Andrew Geissler09209ee2020-12-13 08:44:15 -0600249 <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600260 :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261 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
266Customizing Your Build for Specific Hardware
267============================================
268
269So far, all you have done is quickly built an image suitable for
270emulation only. This section shows you how to customize your build for
271specific hardware by adding a hardware layer into the Yocto Project
272development environment.
273
274In general, layers are repositories that contain related sets of
275instructions and configurations that tell the Yocto Project what to do.
276Isolating related metadata into functionally specific layers facilitates
277modular 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
283Follow 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600349 :ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500350 section.
351
352Completing these steps has added the ``meta-altera`` layer to your Yocto
353Project 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
362Creating Your Own General Layer
363===============================
364
365Maybe you have an application or specific set of behaviors you need to
366isolate. You can create your own general layer using the
367``bitbake-layers create-layer`` command. The tool automates layer
368creation by setting up a subdirectory with a ``layer.conf``
369configuration file, a ``recipes-example`` subdirectory that contains an
370``example.bb`` recipe, a licensing file, and a ``README``.
371
372The 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
382For more information
383on layers and how to create them, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600384:ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385section in the Yocto Project Development Tasks Manual.
386
387Where To Go Next
388================
389
390Now that you have experienced using the Yocto Project, you might be
391asking yourself "What now?". The Yocto Project has many sources of
392information 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 -
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600400 New Developer Screencast Tutorial <https://vimeo.com/36450321>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500401 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600407 :doc:`/overview-manual/index` is a great
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500408 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