diff options
Diffstat (limited to 'documentation/sdk-manual/appendix-obtain.rst')
-rw-r--r-- | documentation/sdk-manual/appendix-obtain.rst | 201 |
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 @@ | |||
4 | Obtaining the SDK | 4 | Obtaining the SDK |
5 | ***************** | 5 | ***************** |
6 | 6 | ||
7 | Working with the SDK components directly in a Yocto build | ||
8 | ========================================================= | ||
9 | |||
10 | Please refer to section | ||
11 | ":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`" | ||
12 | |||
13 | Note that to use this feature effectively either a powerful build | ||
14 | machine, or a well-functioning sstate cache infrastructure is required: | ||
15 | otherwise significant time could be spent waiting for components to be built | ||
16 | by BitBake from source code. | ||
17 | |||
18 | Working with standalone SDK Installers | ||
19 | ====================================== | ||
20 | |||
7 | Locating Pre-Built SDK Installers | 21 | Locating Pre-Built SDK Installers |
8 | ================================= | 22 | --------------------------------- |
9 | 23 | ||
10 | You can use existing, pre-built toolchains by locating and running an | 24 | You can use existing, pre-built toolchains by locating and running an |
11 | SDK installer script that ships with the Yocto Project. Using this | 25 | SDK 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 | ||
15 | Follow these steps to locate and hand-install the toolchain: | 29 | Follow these steps to locate and hand-install the toolchain: |
16 | 30 | ||
17 | 1. *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 | ||
20 | 2. *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 | ||
24 | 3. *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 | ||
63 | 4. *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 | ||
77 | Building an SDK Installer | 81 | Building an SDK Installer |
78 | ========================= | 82 | ------------------------- |
79 | 83 | ||
80 | As an alternative to locating and downloading an SDK installer, you can | 84 | As an alternative to locating and downloading an SDK installer, you can |
81 | build the SDK installer. Follow these steps: | 85 | build the SDK installer. Follow these steps: |
82 | 86 | ||
83 | 1. *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 | ||
89 | 2. *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 | ||
99 | 3. *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`` | |
115 | 4. *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 | ||
121 | 5. *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 | ||
143 | 6. *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 | ||
172 | 7. *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 | ||
186 | Extracting the Root Filesystem | 185 | Extracting the Root Filesystem |
@@ -198,7 +197,7 @@ separately extract a root filesystem: | |||
198 | 197 | ||
199 | Follow these steps to extract the root filesystem: | 198 | Follow these steps to extract the root filesystem: |
200 | 199 | ||
201 | 1. *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 | ||
241 | 2. *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 | ||
254 | 3. *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 | ||
268 | Installed Standard SDK Directory Structure | 256 | Installed Standard SDK Directory Structure |
269 | ========================================== | 257 | ========================================== |
@@ -273,8 +261,7 @@ install the Standard SDK by running the ``*.sh`` SDK installation | |||
273 | script: | 261 | script: |
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 | ||
279 | The installed SDK consists of an environment setup script for the SDK, a | 266 | The installed SDK consists of an environment setup script for the SDK, a |
280 | configuration file for the target, a version file for the target, and | 267 | configuration file for the target, a version file for the target, and |