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