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