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.rst201
1 files changed, 94 insertions, 107 deletions
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
index f158c244ab..d06d6ec6b5 100644
--- a/documentation/sdk-manual/appendix-obtain.rst
+++ b/documentation/sdk-manual/appendix-obtain.rst
@@ -4,8 +4,22 @@
4Obtaining the SDK 4Obtaining the SDK
5***************** 5*****************
6 6
7Working with the SDK components directly in a Yocto build
8=========================================================
9
10Please refer to section
11":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`"
12
13Note that to use this feature effectively either a powerful build
14machine, or a well-functioning sstate cache infrastructure is required:
15otherwise significant time could be spent waiting for components to be built
16by BitBake from source code.
17
18Working with standalone SDK Installers
19======================================
20
7Locating Pre-Built SDK Installers 21Locating Pre-Built SDK Installers
8================================= 22---------------------------------
9 23
10You can use existing, pre-built toolchains by locating and running an 24You can use existing, pre-built toolchains by locating and running an
11SDK installer script that ships with the Yocto Project. Using this 25SDK installer script that ships with the Yocto Project. Using this
@@ -14,39 +28,31 @@ and then run the script to hand-install the toolchain.
14 28
15Follow these steps to locate and hand-install the toolchain: 29Follow these steps to locate and hand-install the toolchain:
16 30
171. *Go to the Installers Directory:* Go to 31#. *Go to the Installers Directory:* Go to
18 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` 32 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/`
19 33
202. *Open the Folder for Your Build Host:* Open the folder that matches 34#. *Open the Folder for Your Build Host:* Open the folder that matches
21 your :term:`Build Host` (i.e. 35 your :term:`Build Host` (i.e.
22 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). 36 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
23 37
243. *Locate and Download the SDK Installer:* You need to find and 38#. *Locate and Download the SDK Installer:* You need to find and
25 download the installer appropriate for your build host, target 39 download the installer appropriate for your build host, target
26 hardware, and image type. 40 hardware, and image type.
27 41
28 The installer files (``*.sh``) follow this naming convention: 42 The installer files (``*.sh``) follow this naming convention:
29 :: 43 ``poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh``:
30 44
31 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh 45 - ``host_system``: string representing your development system: ``i686`` or ``x86_64``
32 46
33 Where: 47 - ``type``: string representing the image: ``sato`` or ``minimal``
34 host_system is a string representing your development system:
35 "i686" or "x86_64"
36 48
37 type is a string representing the image: 49 - ``arch``: string representing the target architecture such as ``cortexa57-qemuarm64``
38 "sato" or "minimal"
39 50
40 arch is a string representing the target architecture: 51 - ``release``: version of the Yocto Project.
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 52
53 .. note::
54 The standard SDK installer does not have the ``-ext`` string as
55 part of the filename.
50 56
51 The toolchains provided by the Yocto 57 The toolchains provided by the Yocto
52 Project are based off of the ``core-image-sato`` and 58 Project are based off of the ``core-image-sato`` and
@@ -54,39 +60,37 @@ Follow these steps to locate and hand-install the toolchain:
54 developing against those images. 60 developing against those images.
55 61
56 For example, if your build host is a 64-bit x86 system and you need 62 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`` 63 an extended SDK for a 64-bit core2 QEMU target, go into the ``x86_64``
58 folder and download the following installer: 64 folder and download the following installer::
59 ::
60 65
61 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 66 poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
62 67
634. *Run the Installer:* Be sure you have execution privileges and run 68#. *Run the Installer:* Be sure you have execution privileges and run
64 the installer. Following is an example from the ``Downloads`` 69 the installer. Here is an example from the ``Downloads``
65 directory: 70 directory::
66 ::
67 71
68 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 72 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
69 73
70 During execution of the script, you choose the root location for the 74 During execution of the script, you choose the root location for the
71 toolchain. See the "`Installed Standard SDK Directory 75 toolchain. See the
72 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 76 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
73 section and the "`Installed Extensible SDK Directory 77 section and the
74 Structure <#sdk-installed-extensible-sdk-directory-structure>`__" 78 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
75 section for more information. 79 section for more information.
76 80
77Building an SDK Installer 81Building an SDK Installer
78========================= 82-------------------------
79 83
80As an alternative to locating and downloading an SDK installer, you can 84As an alternative to locating and downloading an SDK installer, you can
81build the SDK installer. Follow these steps: 85build the SDK installer. Follow these steps:
82 86
831. *Set Up the Build Environment:* Be sure you are set up to use BitBake 87#. *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 88 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 89 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 90 to get a build host ready that is either a native Linux machine or a
87 machine that uses CROPS. 91 machine that uses CROPS.
88 92
892. *Clone the ``poky`` Repository:* You need to have a local copy of the 93#. *Clone the ``poky`` Repository:* You need to have a local copy of the
90 Yocto Project :term:`Source Directory` 94 Yocto Project :term:`Source Directory`
91 (i.e. a local 95 (i.e. a local
92 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and 96 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
@@ -96,56 +100,52 @@ build the SDK installer. Follow these steps:
96 how to clone the ``poky`` repository and check out the appropriate 100 how to clone the ``poky`` repository and check out the appropriate
97 branch for your work. 101 branch for your work.
98 102
993. *Initialize the Build Environment:* While in the root directory of 103#. *Initialize the Build Environment:* While in the root directory of
100 the Source Directory (i.e. ``poky``), run the 104 the Source Directory (i.e. ``poky``), run the
101 :ref:`structure-core-script` environment 105 :ref:`structure-core-script` environment
102 setup script to define the OpenEmbedded build environment on your 106 setup script to define the OpenEmbedded build environment on your
103 build host. 107 build host::
104 ::
105 108
106 $ source oe-init-build-env 109 $ source oe-init-build-env
107 110
108 Among other things, the script 111 Among other things, the script creates the :term:`Build Directory`, which
109 creates the :term:`Build Directory`, 112 is ``build`` in this case and is located in the Source Directory. After
110 which is 113 the script runs, your current working directory is set to the ``build``
111 ``build`` in this case and is located in the Source Directory. After 114 directory.
112 the script runs, your current working directory is set to the 115
113 ``build`` directory. 116#. *Make Sure You Are Building an Installer for the Correct Machine:*
114 117 Check to be sure that your :term:`MACHINE` variable in the ``local.conf``
1154. *Make Sure You Are Building an Installer for the Correct Machine:* 118 file in your :term:`Build Directory` matches the architecture
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. 119 for which you are building.
120 120
1215. *Make Sure Your SDK Machine is Correctly Set:* If you are building a 121#. *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 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 123 current development host machine (i.e. the build host), be sure that
124 the :term:`SDKMACHINE` variable 124 the :term:`SDKMACHINE` variable in the ``local.conf`` file in your
125 in the ``local.conf`` file in your Build Directory is correctly set. 125 :term:`Build Directory` is correctly set.
126 126
127 .. note:: 127 .. note::
128 128
129 If you are building an SDK installer for the Extensible SDK, the 129 If you are building an SDK installer for the Extensible SDK, the
130 SDKMACHINE 130 :term:`SDKMACHINE` value must be set for the architecture of the
131 value must be set for the architecture of the machine you are 131 machine you are using to build the installer. If :term:`SDKMACHINE`
132 using to build the installer. If
133 SDKMACHINE
134 is not set appropriately, the build fails and provides an error 132 is not set appropriately, the build fails and provides an error
135 message similar to the following: 133 message similar to the following::
136 ::
137 134
138 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is 135 The extensible SDK can currently only be built for the same
139 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). 136 architecture as the machine being built on - SDK_ARCH
140 Unable to continue. 137 is set to i686 (likely via setting SDKMACHINE) which is
138 different from the architecture of the build machine (x86_64).
139 Unable to continue.
141 140
142 141
1436. *Build the SDK Installer:* To build the SDK installer for a standard 142#. *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 143 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"): $ 144 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 145
147 SDK using this command form: 146 $ bitbake image -c populate_sdk
148 :: 147
148 You can do the same for the extensible SDK using this command form::
149 149
150 $ bitbake image -c populate_sdk_ext 150 $ bitbake image -c populate_sdk_ext
151 151
@@ -153,7 +153,7 @@ build the SDK installer. Follow these steps:
153 that matches your target root filesystem. 153 that matches your target root filesystem.
154 154
155 When the ``bitbake`` command completes, the SDK installer will be in 155 When the ``bitbake`` command completes, the SDK installer will be in
156 ``tmp/deploy/sdk`` in the Build Directory. 156 ``tmp/deploy/sdk`` in the :term:`Build Directory`.
157 157
158 .. note:: 158 .. note::
159 159
@@ -165,22 +165,21 @@ build the SDK installer. Follow these steps:
165 variable inside your ``local.conf`` file before building the 165 variable inside your ``local.conf`` file before building the
166 SDK installer. Doing so ensures that the eventual SDK 166 SDK installer. Doing so ensures that the eventual SDK
167 installation process installs the appropriate library packages 167 installation process installs the appropriate library packages
168 as part of the SDK. Following is an example using ``libc`` 168 as part of the SDK. Here is an example using ``libc``
169 static development libraries: TOOLCHAIN_TARGET_TASK_append = " 169 static development libraries: TOOLCHAIN_TARGET_TASK:append = "
170 libc-staticdev" 170 libc-staticdev"
171 171
1727. *Run the Installer:* You can now run the SDK installer from 172#. *Run the Installer:* You can now run the SDK installer from
173 ``tmp/deploy/sdk`` in the Build Directory. Following is an example: 173 ``tmp/deploy/sdk`` in the :term:`Build Directory`. Here is an example::
174 ::
175 174
176 $ cd ~/poky/build/tmp/deploy/sdk 175 $ cd poky/build/tmp/deploy/sdk
177 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 176 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
178 177
179 During execution of the script, you choose the root location for the 178 During execution of the script, you choose the root location for the
180 toolchain. See the "`Installed Standard SDK Directory 179 toolchain. See the
181 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 180 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
182 section and the "`Installed Extensible SDK Directory 181 section and the
183 Structure <#sdk-installed-extensible-sdk-directory-structure>`__" 182 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
184 section for more information. 183 section for more information.
185 184
186Extracting the Root Filesystem 185Extracting the Root Filesystem
@@ -198,7 +197,7 @@ separately extract a root filesystem:
198 197
199Follow these steps to extract the root filesystem: 198Follow these steps to extract the root filesystem:
200 199
2011. *Locate and Download the Tarball for the Pre-Built Root Filesystem 200#. *Locate and Download the Tarball for the Pre-Built Root Filesystem
202 Image File:* You need to find and download the root filesystem image 201 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 202 file that is appropriate for your target system. These files are kept
204 in machine-specific folders in the 203 in machine-specific folders in the
@@ -210,22 +209,14 @@ Follow these steps to extract the root filesystem:
210 also contain flattened root filesystem image files (``*.ext4``), 209 also contain flattened root filesystem image files (``*.ext4``),
211 which you can use with QEMU directly. 210 which you can use with QEMU directly.
212 211
213 The pre-built root filesystem image files follow these naming 212 The pre-built root filesystem image files follow the
214 conventions: 213 ``core-image-profile-machine.tar.bz2`` naming convention:
215 ::
216 214
217 core-image-profile-arch.tar.bz2 215 - ``profile``: filesystem image's profile, such as ``minimal``,
216 ``minimal-dev`` or ``sato``. For information on these types of image
217 profiles, see the "Images" chapter in the Yocto Project Reference Manual.
218 218
219 Where: 219 - ``machine``: same string as the name of the parent download directory.
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 220
230 The root filesystems 221 The root filesystems
231 provided by the Yocto Project are based off of the 222 provided by the Yocto Project are based off of the
@@ -233,37 +224,34 @@ Follow these steps to extract the root filesystem:
233 224
234 For example, if you plan on using a BeagleBone device as your target 225 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 226 hardware and your image is a ``core-image-sato-sdk`` image, you can
236 download the following file: 227 download the following file::
237 ::
238 228
239 core-image-sato-sdk-beaglebone-yocto.tar.bz2 229 core-image-sato-sdk-beaglebone-yocto.tar.bz2
240 230
2412. *Initialize the Cross-Development Environment:* You must ``source`` 231#. *Initialize the Cross-Development Environment:* You must ``source``
242 the cross-development environment setup script to establish necessary 232 the cross-development environment setup script to establish necessary
243 environment variables. 233 environment variables.
244 234
245 This script is located in the top-level directory in which you 235 This script is located in the top-level directory in which you
246 installed the toolchain (e.g. ``poky_sdk``). 236 installed the toolchain (e.g. ``poky_sdk``).
247 237
248 Following is an example based on the toolchain installed in the 238 Here is an example based on the toolchain installed in the
249 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: 239 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
250 ::
251 240
252 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux 241 $ source poky_sdk/environment-setup-core2-64-poky-linux
253 242
2543. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` 243#. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
255 command and provide the root filesystem image. 244 command and provide the root filesystem image.
256 245
257 Following is an example command that extracts the root filesystem 246 Here is an example command that extracts the root filesystem
258 from a previously built root filesystem image that was downloaded 247 from a previously built root filesystem image that was downloaded
259 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`. 248 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`.
260 This command extracts the root filesystem into the ``core2-64-sato`` 249 This command extracts the root filesystem into the ``core2-64-sato``
261 directory: 250 directory::
262 ::
263 251
264 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato 252 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
265 253
266 You could now point to the target sysroot at ``beablebone-sato``. 254 You could now point to the target sysroot at ``beaglebone-sato``.
267 255
268Installed Standard SDK Directory Structure 256Installed Standard SDK Directory Structure
269========================================== 257==========================================
@@ -273,8 +261,7 @@ install the Standard SDK by running the ``*.sh`` SDK installation
273script: 261script:
274 262
275.. image:: figures/sdk-installed-standard-sdk-directory.png 263.. image:: figures/sdk-installed-standard-sdk-directory.png
276 :scale: 80% 264 :scale: 100%
277 :align: center
278 265
279The installed SDK consists of an environment setup script for the SDK, a 266The installed SDK consists of an environment setup script for the SDK, a
280configuration file for the target, a version file for the target, and 267configuration file for the target, a version file for the target, and