diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-obtain.xml')
-rw-r--r-- | documentation/sdk-manual/sdk-appendix-obtain.xml | 256 |
1 files changed, 241 insertions, 15 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml index eada4cc8ed..8b245615c9 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/documentation/sdk-manual/sdk-appendix-obtain.xml | |||
@@ -6,26 +6,210 @@ | |||
6 | 6 | ||
7 | <title>Obtaining the SDK</title> | 7 | <title>Obtaining the SDK</title> |
8 | 8 | ||
9 | <section id='sdk-appendix-obtain-manual-development-notes'> | 9 | <section id='sdk-locating-pre-built-sdk-installers'> |
10 | <title>Manual Development Notes for Scott and Paul</title> | 10 | <title>Locating Pre-Built SDK Installers</title> |
11 | 11 | ||
12 | <para role='writernotes'> | 12 | <para> |
13 | This chapter is going to cover details about the installed SDK and perhaps | 13 | You can use existing, pre-built toolchains by locating and running |
14 | stuff on locating it (e.g. the naming scheme used to identify the | 14 | an SDK installer script that ships with the Yocto Project. |
15 | <filename>.sh</filename> installation script. | 15 | Using this method, you select and download an architecture-specific |
16 | toolchain installer and then run the script to hand-install the | ||
17 | toolchain. | ||
18 | </para> | ||
19 | |||
20 | <para> | ||
21 | You can find SDK installers here: | ||
22 | <itemizedlist> | ||
23 | <listitem><para><emphasis>Standard SDK Installers</emphasis> | ||
24 | Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> | ||
25 | and find the folder that matches your host development system | ||
26 | (i.e. <filename>i686</filename> for 32-bit machines or | ||
27 | <filename>x86_64</filename> for 64-bit machines).</para> | ||
28 | |||
29 | <para>Go into that folder and download the toolchain installer | ||
30 | whose name includes the appropriate target architecture. | ||
31 | The toolchains provided by the Yocto Project are based off of | ||
32 | the <filename>core-image-sato</filename> image and contain | ||
33 | libraries appropriate for developing against that image. | ||
34 | For example, if your host development system is a 64-bit x86 | ||
35 | system and you are going to use your cross-toolchain for a | ||
36 | 32-bit x86 target, go into the <filename>x86_64</filename> | ||
37 | folder and download the following installer: | ||
38 | <literallayout class='monospaced'> | ||
39 | poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh | ||
40 | </literallayout> | ||
41 | </para></listitem> | ||
42 | <listitem><para><emphasis>Extensible SDK Installers</emphasis> | ||
43 | Installers for the extensible SDK are in | ||
44 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. | ||
45 | </para></listitem> | ||
46 | </itemizedlist> | ||
47 | </para> | ||
48 | </section> | ||
49 | |||
50 | <section id='sdk-optionally-building-a-toolchain-installer'> | ||
51 | <title>Optionally Building a Toolchain Installer</title> | ||
52 | |||
53 | <para> | ||
54 | As an alternative to locating and downloading a toolchain installer, | ||
55 | you can build the toolchain installer if you have a | ||
56 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
57 | <note> | ||
58 | Although not the preferred method, it is also possible to use | ||
59 | <filename>bitbake meta-toolchain</filename> to build the toolchain | ||
60 | installer. | ||
61 | If you do use this method, you must separately install and extract | ||
62 | the target sysroot. | ||
63 | For information on how to install the sysroot, see the | ||
64 | "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" | ||
65 | section. | ||
66 | </note> | ||
67 | </para> | ||
68 | |||
69 | <para> | ||
70 | To build the toolchain installer for a standard SDK and populate | ||
71 | the SDK image, use the following command: | ||
72 | <literallayout class='monospaced'> | ||
73 | $ bitbake <replaceable>image</replaceable> -c populate_sdk | ||
74 | </literallayout> | ||
75 | You can do the same for the extensible SDK using this command: | ||
76 | <literallayout class='monospaced'> | ||
77 | $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext | ||
78 | </literallayout> | ||
79 | These commands result in a toolchain installer that contains the sysroot | ||
80 | that matches your target root filesystem. | ||
81 | </para> | ||
82 | |||
83 | <para> | ||
84 | Another powerful feature is that the toolchain is completely | ||
85 | self-contained. | ||
86 | The binaries are linked against their own copy of | ||
87 | <filename>libc</filename>, which results in no dependencies | ||
88 | on the target system. | ||
89 | To achieve this, the pointer to the dynamic loader is | ||
90 | configured at install time since that path cannot be dynamically | ||
91 | altered. | ||
92 | This is the reason for a wrapper around the | ||
93 | <filename>populate_sdk</filename> and | ||
94 | <filename>populate_sdk_ext</filename> archives. | ||
16 | </para> | 95 | </para> |
17 | 96 | ||
18 | <para role='writernotes'> | 97 | <para> |
19 | The idea here is to gather all the current information in the regular | 98 | Another feature is that only one set of cross-canadian toolchain |
20 | YP doc set that describes how to locate, download, or build out the SDK. | 99 | binaries are produced per architecture. |
100 | This feature takes advantage of the fact that the target hardware can | ||
101 | be passed to <filename>gcc</filename> as a set of compiler options. | ||
102 | Those options are set up by the environment script and contained in | ||
103 | variables such as | ||
104 | <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> | ||
105 | and | ||
106 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. | ||
107 | This reduces the space needed for the tools. | ||
108 | Understand, however, that a sysroot is still needed for every target | ||
109 | since those binaries are target-specific. | ||
110 | </para> | ||
111 | |||
112 | <para> | ||
113 | Remember, before using any BitBake command, you | ||
114 | must source the build environment setup script | ||
115 | (i.e. | ||
116 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
117 | or | ||
118 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) | ||
119 | located in the Source Directory and you must make sure your | ||
120 | <filename>conf/local.conf</filename> variables are correct. | ||
121 | In particular, you need to be sure the | ||
122 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
123 | variable matches the architecture for which you are building and that | ||
124 | the | ||
125 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> | ||
126 | variable is correctly set if you are building a toolchain designed to | ||
127 | run on an architecture that differs from your current development host | ||
128 | machine (i.e. the build machine). | ||
21 | </para> | 129 | </para> |
22 | 130 | ||
23 | <para role='writernotes'> | 131 | <para> |
24 | One thing that needs discussed is any differences between getting the | 132 | When the <filename>bitbake</filename> command completes, the toolchain |
25 | standard SDK as compared to the extended SDK. | 133 | installer will be in |
26 | Do we have pre-build extensible SDKs laying around? | 134 | <filename>tmp/deploy/sdk</filename> in the Build Directory. |
27 | Where do we get any pre-built SDKs from? | 135 | <note> |
28 | Show the methods by which the user builds out the SDK? | 136 | By default, this toolchain does not build static binaries. |
137 | If you want to use the toolchain to build these types of libraries, | ||
138 | you need to be sure your image has the appropriate static | ||
139 | development libraries. | ||
140 | Use the | ||
141 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> | ||
142 | variable inside your <filename>local.conf</filename> file to | ||
143 | install the appropriate library packages. | ||
144 | Following is an example using <filename>glibc</filename> static | ||
145 | development libraries: | ||
146 | <literallayout class='monospaced'> | ||
147 | IMAGE_INSTALL_append = " glibc-staticdev" | ||
148 | </literallayout> | ||
149 | </note> | ||
150 | </para> | ||
151 | </section> | ||
152 | |||
153 | <section id='sdk-extracting-the-root-filesystem'> | ||
154 | <title>Extracting the Root Filesystem</title> | ||
155 | |||
156 | <para> | ||
157 | After installing the toolchain or building it using BitBake, | ||
158 | you need a root filesystem, which you need to separately extract. | ||
159 | </para> | ||
160 | |||
161 | <para> | ||
162 | Here are some cases where you need to extract the root filesystem: | ||
163 | <itemizedlist> | ||
164 | <listitem><para>You want to boot the image using NFS. | ||
165 | </para></listitem> | ||
166 | <listitem><para>You want to use the root filesystem as the | ||
167 | target sysroot. | ||
168 | For example, the Eclipse IDE environment with the Eclipse | ||
169 | Yocto Plug-in installed allows you to use QEMU to boot | ||
170 | under NFS.</para></listitem> | ||
171 | <listitem><para>You want to develop your target application | ||
172 | using the root filesystem as the target sysroot. | ||
173 | </para></listitem> | ||
174 | </itemizedlist> | ||
175 | </para> | ||
176 | |||
177 | <para> | ||
178 | To extract the root filesystem, first <filename>source</filename> | ||
179 | the cross-development environment setup script to establish | ||
180 | necessary environment variables. | ||
181 | If you built the toolchain in the Build Directory, you will find | ||
182 | the toolchain environment script in the | ||
183 | <filename>tmp</filename> directory. | ||
184 | If you installed the toolchain by hand, the environment setup | ||
185 | script is located in <filename>/opt/poky/&DISTRO;</filename>. | ||
186 | </para> | ||
187 | |||
188 | <para> | ||
189 | After sourcing the environment script, use the | ||
190 | <filename>runqemu-extract-sdk</filename> command and provide the | ||
191 | filesystem image. | ||
192 | </para> | ||
193 | |||
194 | <para> | ||
195 | Following is an example. | ||
196 | The second command sets up the environment. | ||
197 | In this case, the setup script is located in the | ||
198 | <filename>/opt/poky/&DISTRO;</filename> directory. | ||
199 | The third command extracts the root filesystem from a previously | ||
200 | built filesystem that is located in the | ||
201 | <filename>~/Downloads</filename> directory. | ||
202 | Furthermore, this command extracts the root filesystem into the | ||
203 | <filename>qemux86-sato</filename> directory: | ||
204 | <literallayout class='monospaced'> | ||
205 | $ cd ~ | ||
206 | $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux | ||
207 | $ runqemu-extract-sdk \ | ||
208 | ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ | ||
209 | $HOME/qemux86-sato | ||
210 | </literallayout> | ||
211 | You could now point to the target sysroot at | ||
212 | <filename>qemux86-sato</filename>. | ||
29 | </para> | 213 | </para> |
30 | </section> | 214 | </section> |
31 | 215 | ||
@@ -70,6 +254,48 @@ | |||
70 | </para> | 254 | </para> |
71 | </section> | 255 | </section> |
72 | 256 | ||
257 | <section id='sdk-installed-extensible-sdk-directory-structure'> | ||
258 | <title>Installed Extensible SDK Directory Structure</title> | ||
259 | |||
260 | <para> | ||
261 | The following figure shows the resulting directory structure after | ||
262 | you install the Extensible SDK by running the <filename>.sh</filename> | ||
263 | SDK installation script: | ||
264 | </para> | ||
265 | |||
266 | <para> | ||
267 | <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="60" align="center" /> | ||
268 | </para> | ||
269 | |||
270 | <para> | ||
271 | The installed directory structure for the extensible SDK is quite | ||
272 | different than the installed structure for the standard SDK. | ||
273 | The extensible SDK does not separate host and target parts in the | ||
274 | same manner as does the standard SDK. | ||
275 | The extensible SDK uses an embedded copy of the build system, which | ||
276 | has its own sysroots. | ||
277 | </para> | ||
278 | |||
279 | <para> | ||
280 | Of note in the directory structure are an environment setup script | ||
281 | for the SDK, a configuration file for the target, a version file for | ||
282 | the target, and a log file for the build system preparation script run | ||
283 | by the installer. | ||
284 | </para> | ||
285 | |||
286 | <para> | ||
287 | Within the figure, italicized text is used to indicate replaceable | ||
288 | portions of the file or directory name. | ||
289 | For example, | ||
290 | <replaceable>install_dir</replaceable> is the directory where the SDK | ||
291 | is installed, which is <filename>poky_sdk</filename> by default. | ||
292 | <replaceable>target</replaceable> represents the target | ||
293 | architecture (e.g. <filename>i586</filename>) and | ||
294 | <replaceable>host</replaceable> represents the development system's | ||
295 | architecture (e.g. <filename>x86_64</filename>). | ||
296 | </para> | ||
297 | </section> | ||
298 | |||
73 | </appendix> | 299 | </appendix> |
74 | <!-- | 300 | <!-- |
75 | vim: expandtab tw=80 ts=4 | 301 | vim: expandtab tw=80 ts=4 |