diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-obtain.rst')
-rw-r--r-- | documentation/sdk-manual/sdk-appendix-obtain.rst | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst new file mode 100644 index 0000000000..97ab9169ea --- /dev/null +++ b/documentation/sdk-manual/sdk-appendix-obtain.rst | |||
@@ -0,0 +1,321 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ***************** | ||
4 | Obtaining the SDK | ||
5 | ***************** | ||
6 | |||
7 | .. _sdk-locating-pre-built-sdk-installers: | ||
8 | |||
9 | Locating Pre-Built SDK Installers | ||
10 | ================================= | ||
11 | |||
12 | You can use existing, pre-built toolchains by locating and running an | ||
13 | SDK installer script that ships with the Yocto Project. Using this | ||
14 | method, you select and download an architecture-specific SDK installer | ||
15 | and then run the script to hand-install the toolchain. | ||
16 | |||
17 | Follow these steps to locate and hand-install the toolchain: | ||
18 | |||
19 | 1. *Go to the Installers Directory:* Go to | ||
20 | :yocto_dl:`/releases/yocto/yocto-3.1.2/toolchain/` | ||
21 | |||
22 | 2. *Open the Folder for Your Build Host:* Open the folder that matches | ||
23 | your :term:`Build Host` (i.e. | ||
24 | ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). | ||
25 | |||
26 | 3. *Locate and Download the SDK Installer:* You need to find and | ||
27 | download the installer appropriate for your build host, target | ||
28 | hardware, and image type. | ||
29 | |||
30 | The installer files (``*.sh``) follow this naming convention: | ||
31 | :: | ||
32 | |||
33 | poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh | ||
34 | |||
35 | Where: | ||
36 | host_system is a string representing your development system: | ||
37 | "i686" or "x86_64" | ||
38 | |||
39 | type is a string representing the image: | ||
40 | "sato" or "minimal" | ||
41 | |||
42 | arch is a string representing the target architecture: | ||
43 | "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", | ||
44 | "mips64", or "ppc7400" | ||
45 | |||
46 | release is the version of Yocto Project. | ||
47 | |||
48 | NOTE: | ||
49 | The standard SDK installer does not have the "-ext" string as | ||
50 | part of the filename. | ||
51 | |||
52 | |||
53 | The toolchains provided by the Yocto | ||
54 | Project are based off of the ``core-image-sato`` and | ||
55 | ``core-image-minimal`` images and contain libraries appropriate for | ||
56 | developing against those images. | ||
57 | |||
58 | For example, if your build host is a 64-bit x86 system and you need | ||
59 | an extended SDK for a 64-bit core2 target, go into the ``x86_64`` | ||
60 | folder and download the following installer: | ||
61 | :: | ||
62 | |||
63 | poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh | ||
64 | |||
65 | 4. *Run the Installer:* Be sure you have execution privileges and run | ||
66 | the installer. Following is an example from the ``Downloads`` | ||
67 | directory: | ||
68 | :: | ||
69 | |||
70 | $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh | ||
71 | |||
72 | During execution of the script, you choose the root location for the | ||
73 | toolchain. See the "`Installed Standard SDK Directory | ||
74 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" | ||
75 | section and the "`Installed Extensible SDK Directory | ||
76 | Structure <#sdk-installed-extensible-sdk-directory-structure>`__" | ||
77 | section for more information. | ||
78 | |||
79 | Building an SDK Installer | ||
80 | ========================= | ||
81 | |||
82 | As an alternative to locating and downloading an SDK installer, you can | ||
83 | build the SDK installer. Follow these steps: | ||
84 | |||
85 | 1. *Set Up the Build Environment:* Be sure you are set up to use BitBake | ||
86 | in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section | ||
87 | in the Yocto Project Development Tasks Manual for information on how | ||
88 | to get a build host ready that is either a native Linux machine or a | ||
89 | machine that uses CROPS. | ||
90 | |||
91 | 2. *Clone the ``poky`` Repository:* You need to have a local copy of the | ||
92 | Yocto Project :term:`Source Directory` | ||
93 | (i.e. a local | ||
94 | ``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and | ||
95 | possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and | ||
96 | ":ref:`checkout-out-by-tag-in-poky`" sections | ||
97 | all in the Yocto Project Development Tasks Manual for information on | ||
98 | how to clone the ``poky`` repository and check out the appropriate | ||
99 | branch for your work. | ||
100 | |||
101 | 3. *Initialize the Build Environment:* While in the root directory of | ||
102 | the Source Directory (i.e. ``poky``), run the | ||
103 | :ref:`structure-core-script` environment | ||
104 | setup script to define the OpenEmbedded build environment on your | ||
105 | build host. | ||
106 | :: | ||
107 | |||
108 | $ source oe-init-build-env | ||
109 | |||
110 | Among other things, the script | ||
111 | creates the :term:`Build Directory`, | ||
112 | which is | ||
113 | ``build`` in this case and is located in the Source Directory. After | ||
114 | the script runs, your current working directory is set to the | ||
115 | ``build`` directory. | ||
116 | |||
117 | 4. *Make Sure You Are Building an Installer for the Correct Machine:* | ||
118 | Check to be sure that your | ||
119 | :term:`MACHINE` variable in the | ||
120 | ``local.conf`` file in your Build Directory matches the architecture | ||
121 | for which you are building. | ||
122 | |||
123 | 5. *Make Sure Your SDK Machine is Correctly Set:* If you are building a | ||
124 | toolchain designed to run on an architecture that differs from your | ||
125 | current development host machine (i.e. the build host), be sure that | ||
126 | the :term:`SDKMACHINE` variable | ||
127 | in the ``local.conf`` file in your Build Directory is correctly set. | ||
128 | |||
129 | .. note:: | ||
130 | |||
131 | If you are building an SDK installer for the Extensible SDK, the | ||
132 | SDKMACHINE | ||
133 | value must be set for the architecture of the machine you are | ||
134 | using to build the installer. If | ||
135 | SDKMACHINE | ||
136 | is not set appropriately, the build fails and provides an error | ||
137 | message similar to the following: | ||
138 | :: | ||
139 | |||
140 | The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is | ||
141 | set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). | ||
142 | Unable to continue. | ||
143 | |||
144 | |||
145 | 6. *Build the SDK Installer:* To build the SDK installer for a standard | ||
146 | SDK and populate the SDK image, use the following command form. Be | ||
147 | sure to replace image with an image (e.g. "core-image-sato"): $ | ||
148 | bitbake image -c populate_sdk You can do the same for the extensible | ||
149 | SDK using this command form: | ||
150 | :: | ||
151 | |||
152 | $ bitbake image -c populate_sdk_ext | ||
153 | |||
154 | These commands produce an SDK installer that contains the sysroot | ||
155 | that matches your target root filesystem. | ||
156 | |||
157 | When the ``bitbake`` command completes, the SDK installer will be in | ||
158 | ``tmp/deploy/sdk`` in the Build Directory. | ||
159 | |||
160 | .. note:: | ||
161 | |||
162 | - By default, the previous BitBake command does not build static | ||
163 | binaries. If you want to use the toolchain to build these types | ||
164 | of libraries, you need to be sure your SDK has the appropriate | ||
165 | static development libraries. Use the | ||
166 | :term:`TOOLCHAIN_TARGET_TASK` | ||
167 | variable inside your ``local.conf`` file before building the | ||
168 | SDK installer. Doing so ensures that the eventual SDK | ||
169 | installation process installs the appropriate library packages | ||
170 | as part of the SDK. Following is an example using ``libc`` | ||
171 | static development libraries: TOOLCHAIN_TARGET_TASK_append = " | ||
172 | libc-staticdev" | ||
173 | |||
174 | 7. *Run the Installer:* You can now run the SDK installer from | ||
175 | ``tmp/deploy/sdk`` in the Build Directory. Following is an example: | ||
176 | :: | ||
177 | |||
178 | $ cd ~/poky/build/tmp/deploy/sdk | ||
179 | $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh | ||
180 | |||
181 | During execution of the script, you choose the root location for the | ||
182 | toolchain. See the "`Installed Standard SDK Directory | ||
183 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" | ||
184 | section and the "`Installed Extensible SDK Directory | ||
185 | Structure <#sdk-installed-extensible-sdk-directory-structure>`__" | ||
186 | section for more information. | ||
187 | |||
188 | Extracting the Root Filesystem | ||
189 | ============================== | ||
190 | |||
191 | After installing the toolchain, for some use cases you might need to | ||
192 | separately extract a root filesystem: | ||
193 | |||
194 | - You want to boot the image using NFS. | ||
195 | |||
196 | - You want to use the root filesystem as the target sysroot. | ||
197 | |||
198 | - You want to develop your target application using the root filesystem | ||
199 | as the target sysroot. | ||
200 | |||
201 | Follow these steps to extract the root filesystem: | ||
202 | |||
203 | 1. *Locate and Download the Tarball for the Pre-Built Root Filesystem | ||
204 | Image File:* You need to find and download the root filesystem image | ||
205 | file that is appropriate for your target system. These files are kept | ||
206 | in machine-specific folders in the | ||
207 | :yocto_dl:`Index of Releases </releases/yocto/yocto-3.1.2/machines/>` | ||
208 | in the "machines" directory. | ||
209 | |||
210 | The machine-specific folders of the "machines" directory contain | ||
211 | tarballs (``*.tar.bz2``) for supported machines. These directories | ||
212 | also contain flattened root filesystem image files (``*.ext4``), | ||
213 | which you can use with QEMU directly. | ||
214 | |||
215 | The pre-built root filesystem image files follow these naming | ||
216 | conventions: | ||
217 | :: | ||
218 | |||
219 | core-image-profile-arch.tar.bz2 | ||
220 | |||
221 | Where: | ||
222 | profile is the filesystem image's profile: | ||
223 | lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs, | ||
224 | sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on | ||
225 | these types of image profiles, see the "Images" chapter in | ||
226 | the Yocto Project Reference Manual. | ||
227 | |||
228 | arch is a string representing the target architecture: | ||
229 | beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb, | ||
230 | genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*. | ||
231 | |||
232 | The root filesystems | ||
233 | provided by the Yocto Project are based off of the | ||
234 | ``core-image-sato`` and ``core-image-minimal`` images. | ||
235 | |||
236 | For example, if you plan on using a BeagleBone device as your target | ||
237 | hardware and your image is a ``core-image-sato-sdk`` image, you can | ||
238 | download the following file: | ||
239 | :: | ||
240 | |||
241 | core-image-sato-sdk-beaglebone-yocto.tar.bz2 | ||
242 | |||
243 | 2. *Initialize the Cross-Development Environment:* You must ``source`` | ||
244 | the cross-development environment setup script to establish necessary | ||
245 | environment variables. | ||
246 | |||
247 | This script is located in the top-level directory in which you | ||
248 | installed the toolchain (e.g. ``poky_sdk``). | ||
249 | |||
250 | Following is an example based on the toolchain installed in the | ||
251 | ":ref:`sdk-locating-pre-built-sdk-installers`" section: | ||
252 | :: | ||
253 | |||
254 | $ source ~/poky_sdk/environment-setup-core2-64-poky-linux | ||
255 | |||
256 | 3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` | ||
257 | command and provide the root filesystem image. | ||
258 | |||
259 | Following is an example command that extracts the root filesystem | ||
260 | from a previously built root filesystem image that was downloaded | ||
261 | from the :yocto_dl:`Index of Releases </releases/yocto/yocto-3.1.2/machines/>`. | ||
262 | This command extracts the root filesystem into the ``core2-64-sato`` | ||
263 | directory: | ||
264 | :: | ||
265 | |||
266 | $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato | ||
267 | |||
268 | You could now point to the target sysroot at ``beablebone-sato``. | ||
269 | |||
270 | Installed Standard SDK Directory Structure | ||
271 | ========================================== | ||
272 | |||
273 | The following figure shows the resulting directory structure after you | ||
274 | install the Standard SDK by running the ``*.sh`` SDK installation | ||
275 | script: | ||
276 | |||
277 | .. image:: figures/sdk-installed-standard-sdk-directory.png | ||
278 | :scale: 80% | ||
279 | :align: center | ||
280 | |||
281 | The installed SDK consists of an environment setup script for the SDK, a | ||
282 | configuration file for the target, a version file for the target, and | ||
283 | the root filesystem (``sysroots``) needed to develop objects for the | ||
284 | target system. | ||
285 | |||
286 | Within the figure, italicized text is used to indicate replaceable | ||
287 | portions of the file or directory name. For example, install_dir/version | ||
288 | is the directory where the SDK is installed. By default, this directory | ||
289 | is ``/opt/poky/``. And, version represents the specific snapshot of the | ||
290 | SDK (e.g. 3.1.2). Furthermore, target represents the target architecture | ||
291 | (e.g. ``i586``) and host represents the development system's | ||
292 | architecture (e.g. ``x86_64``). Thus, the complete names of the two | ||
293 | directories within the ``sysroots`` could be ``i586-poky-linux`` and | ||
294 | ``x86_64-pokysdk-linux`` for the target and host, respectively. | ||
295 | |||
296 | Installed Extensible SDK Directory Structure | ||
297 | ============================================ | ||
298 | |||
299 | The following figure shows the resulting directory structure after you | ||
300 | install the Extensible SDK by running the ``*.sh`` SDK installation | ||
301 | script: | ||
302 | |||
303 | .. image:: figures/sdk-installed-extensible-sdk-directory.png | ||
304 | :scale: 80% | ||
305 | :align: center | ||
306 | |||
307 | The installed directory structure for the extensible SDK is quite | ||
308 | different than the installed structure for the standard SDK. The | ||
309 | extensible SDK does not separate host and target parts in the same | ||
310 | manner as does the standard SDK. The extensible SDK uses an embedded | ||
311 | copy of the OpenEmbedded build system, which has its own sysroots. | ||
312 | |||
313 | Of note in the directory structure are an environment setup script for | ||
314 | the SDK, a configuration file for the target, a version file for the | ||
315 | target, and log files for the OpenEmbedded build system preparation | ||
316 | script run by the installer and BitBake. | ||
317 | |||
318 | Within the figure, italicized text is used to indicate replaceable | ||
319 | portions of the file or directory name. For example, install_dir is the | ||
320 | directory where the SDK is installed, which is ``poky_sdk`` by default, | ||
321 | and target represents the target architecture (e.g. ``i586``). | ||