diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst')
-rw-r--r-- | documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst | 360 |
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 | ========================= | ||
2 | Yocto Project Quick Build | ||
3 | ========================= | ||
4 | |||
5 | Welcome! | ||
6 | ======== | ||
7 | |||
8 | Welcome! This short document steps you through the process for a typical | ||
9 | image build using the Yocto Project. The document also introduces how to | ||
10 | configure a build for specific hardware. You will use Yocto Project to | ||
11 | build 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 | |||
39 | If you want more conceptual or background information on the Yocto | ||
40 | Project, see the `Yocto Project Overview and Concepts | ||
41 | Manual <&YOCTO_DOCS_OM_URL;>`__. | ||
42 | |||
43 | Compatible Linux Distribution | ||
44 | ============================= | ||
45 | |||
46 | Make sure your `build | ||
47 | host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ 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 "`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 | |||
79 | Build Host Packages | ||
80 | =================== | ||
81 | |||
82 | You must install essential host packages on your build host. The | ||
83 | following command installs the host packages based on an Ubuntu | ||
84 | distribution: | ||
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 | |||
95 | Use Git to Clone Poky | ||
96 | ===================== | ||
97 | |||
98 | Once you complete the setup instructions for your machine, you need to | ||
99 | get a copy of the Poky repository on your build host. Use the following | ||
100 | commands to clone the Poky repository. $ git clone | ||
101 | git://git.yoctoproject.org/poky Cloning into 'poky'... remote: Counting | ||
102 | objects: 432160, done. remote: Compressing objects: 100% | ||
103 | (102056/102056), done. remote: Total 432160 (delta 323116), reused | ||
104 | 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 | ||
105 | MiB \| 8.54 MiB/s, done. Resolving deltas: 100% (323116/323116), done. | ||
106 | Checking connectivity... done. Move to the ``poky`` directory and take a | ||
107 | look at the tags: $ cd poky $ git fetch --tags $ git tag 1.1_M1.final | ||
108 | 1.1_M1.rc1 1.1_M1.rc2 1.1_M2.final 1.1_M2.rc1 . . . yocto-2.5 | ||
109 | yocto-2.5.1 yocto-2.5.2 yocto-2.6 yocto-2.6.1 yocto-2.6.2 yocto-2.7 | ||
110 | yocto_1.5_M5.rc8 For this example, check out the branch based on the | ||
111 | DISTRO_REL_TAG release: $ git checkout tags/DISTRO_REL_TAG -b | ||
112 | my-DISTRO_REL_TAG Switched to a new branch 'my-DISTRO_REL_TAG' The | ||
113 | previous Git checkout command creates a local branch named | ||
114 | my-DISTRO_REL_TAG. The files available to you in that branch exactly | ||
115 | match the repository's files in the "DISTRO_NAME_NO_CAP" development | ||
116 | branch at the time of the Yocto Project DISTRO_REL_TAG release. | ||
117 | |||
118 | For more options and information about accessing Yocto Project related | ||
119 | repositories, see the "`Locating Yocto Project Source | ||
120 | Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" | ||
121 | section in the Yocto Project Development Tasks Manual. | ||
122 | |||
123 | Building Your Image | ||
124 | =================== | ||
125 | |||
126 | Use the following steps to build your image. The build process creates | ||
127 | an 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 | |||
143 | 1. *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 | |||
171 | 2. *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 | |||
199 | 3. *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 | |||
209 | 4. *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 | |||
216 | 5. *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 | |||
220 | Customizing Your Build for Specific Hardware | ||
221 | ============================================ | ||
222 | |||
223 | So far, all you have done is quickly built an image suitable for | ||
224 | emulation only. This section shows you how to customize your build for | ||
225 | specific hardware by adding a hardware layer into the Yocto Project | ||
226 | development environment. | ||
227 | |||
228 | In general, layers are repositories that contain related sets of | ||
229 | instructions and configurations that tell the Yocto Project what to do. | ||
230 | Isolating related metadata into functionally specific layers facilitates | ||
231 | modular 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 | |||
237 | Follow these steps to add a hardware layer: | ||
238 | |||
239 | 1. *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 | |||
244 | 2. *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 | |||
257 | 3. *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 | |||
270 | 4. *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 | |||
287 | Completing these steps has added the ``meta-altera`` layer to your Yocto | ||
288 | Project 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 | |||
299 | Creating Your Own General Layer | ||
300 | =============================== | ||
301 | |||
302 | Maybe you have an application or specific set of behaviors you need to | ||
303 | isolate. You can create your own general layer using the | ||
304 | ``bitbake-layers create-layer`` command. The tool automates layer | ||
305 | creation by setting up a subdirectory with a ``layer.conf`` | ||
306 | configuration file, a ``recipes-example`` subdirectory that contains an | ||
307 | ``example.bb`` recipe, a licensing file, and a ``README``. | ||
308 | |||
309 | The following commands run the tool to create a layer named | ||
310 | ``meta-mylayer`` in the ``poky`` directory: $ cd ~/poky $ bitbake-layers | ||
311 | create-layer meta-mylayer NOTE: Starting bitbake server... Add your new | ||
312 | layer with 'bitbake-layers add-layer meta-mylayer' For more information | ||
313 | on layers and how to create them, see the "`Creating a General Layer | ||
314 | Using the ``bitbake-layers`` | ||
315 | Script <&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script>`__" | ||
316 | section in the Yocto Project Development Tasks Manual. | ||
317 | |||
318 | Where To Go Next | ||
319 | ================ | ||
320 | |||
321 | Now that you have experienced using the Yocto Project, you might be | ||
322 | asking yourself "What now?" The Yocto Project has many sources of | ||
323 | information 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. | ||