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