diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-intro.rst')
-rw-r--r-- | documentation/sdk-manual/sdk-intro.rst | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst new file mode 100644 index 0000000000..f2641b7ade --- /dev/null +++ b/documentation/sdk-manual/sdk-intro.rst | |||
@@ -0,0 +1,223 @@ | |||
1 | ************ | ||
2 | Introduction | ||
3 | ************ | ||
4 | |||
5 | .. _sdk-manual-intro: | ||
6 | |||
7 | Introduction | ||
8 | ============ | ||
9 | |||
10 | Welcome to the Yocto Project Application Development and the Extensible | ||
11 | Software Development Kit (eSDK) manual. This manual provides information | ||
12 | that explains how to use both the Yocto Project extensible and standard | ||
13 | SDKs to develop applications and images. | ||
14 | |||
15 | .. note:: | ||
16 | |||
17 | Prior to the 2.0 Release of the Yocto Project, application | ||
18 | development was primarily accomplished through the use of the | ||
19 | Application Development Toolkit (ADT) and the availability of | ||
20 | stand-alone cross-development toolchains and other tools. With the | ||
21 | 2.1 Release of the Yocto Project, application development has | ||
22 | transitioned to within a tool-rich extensible SDK and the more | ||
23 | traditional standard SDK. | ||
24 | |||
25 | All SDKs consist of the following: | ||
26 | |||
27 | - *Cross-Development Toolchain*: This toolchain contains a compiler, | ||
28 | debugger, and various miscellaneous tools. | ||
29 | |||
30 | - *Libraries, Headers, and Symbols*: The libraries, headers, and | ||
31 | symbols are specific to the image (i.e. they match the image). | ||
32 | |||
33 | - *Environment Setup Script*: This ``*.sh`` file, once run, sets up the | ||
34 | cross-development environment by defining variables and preparing for | ||
35 | SDK use. | ||
36 | |||
37 | Additionally, an extensible SDK has tools that allow you to easily add | ||
38 | new applications and libraries to an image, modify the source of an | ||
39 | existing component, test changes on the target hardware, and easily | ||
40 | integrate an application into the `OpenEmbedded build | ||
41 | system <&YOCTO_DOCS_REF_URL;#build-system-term>`__. | ||
42 | |||
43 | You can use an SDK to independently develop and test code that is | ||
44 | destined to run on some target machine. SDKs are completely | ||
45 | self-contained. The binaries are linked against their own copy of | ||
46 | ``libc``, which results in no dependencies on the target system. To | ||
47 | achieve this, the pointer to the dynamic loader is configured at install | ||
48 | time since that path cannot be dynamically altered. This is the reason | ||
49 | for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` | ||
50 | archives. | ||
51 | |||
52 | Another feature for the SDKs is that only one set of cross-compiler | ||
53 | toolchain binaries are produced for any given architecture. This feature | ||
54 | takes advantage of the fact that the target hardware can be passed to | ||
55 | ``gcc`` as a set of compiler options. Those options are set up by the | ||
56 | environment script and contained in variables such as | ||
57 | ```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__ and | ||
58 | ```LD`` <&YOCTO_DOCS_REF_URL;#var-LD>`__. This reduces the space needed | ||
59 | for the tools. Understand, however, that every target still needs a | ||
60 | sysroot because those binaries are target-specific. | ||
61 | |||
62 | The SDK development environment consists of the following: | ||
63 | |||
64 | - The self-contained SDK, which is an architecture-specific | ||
65 | cross-toolchain and matching sysroots (target and native) all built | ||
66 | by the OpenEmbedded build system (e.g. the SDK). The toolchain and | ||
67 | sysroots are based on a `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ | ||
68 | configuration and extensions, which allows you to cross-develop on | ||
69 | the host machine for the target hardware. Additionally, the | ||
70 | extensible SDK contains the ``devtool`` functionality. | ||
71 | |||
72 | - The Quick EMUlator (QEMU), which lets you simulate target hardware. | ||
73 | QEMU is not literally part of the SDK. You must build and include | ||
74 | this emulator separately. However, QEMU plays an important role in | ||
75 | the development process that revolves around use of the SDK. | ||
76 | |||
77 | In summary, the extensible and standard SDK share many features. | ||
78 | However, the extensible SDK has powerful development tools to help you | ||
79 | more quickly develop applications. Following is a table that summarizes | ||
80 | the primary differences between the standard and extensible SDK types | ||
81 | when considering which to build: | ||
82 | |||
83 | +-----------------------+-----------------------+-----------------------+ | ||
84 | | *Feature* | *Standard SDK* | *Extensible SDK* | | ||
85 | +=======================+=======================+=======================+ | ||
86 | | Toolchain | Yes | Yes\* | | ||
87 | +-----------------------+-----------------------+-----------------------+ | ||
88 | | Debugger | Yes | Yes\* | | ||
89 | +-----------------------+-----------------------+-----------------------+ | ||
90 | | Size | 100+ MBytes | 1+ GBytes (or 300+ | | ||
91 | | | | MBytes for minimal | | ||
92 | | | | w/toolchain) | | ||
93 | +-----------------------+-----------------------+-----------------------+ | ||
94 | | ``devtool`` | No | Yes | | ||
95 | +-----------------------+-----------------------+-----------------------+ | ||
96 | | Build Images | No | Yes | | ||
97 | +-----------------------+-----------------------+-----------------------+ | ||
98 | | Updateable | No | Yes | | ||
99 | +-----------------------+-----------------------+-----------------------+ | ||
100 | | Managed Sysroot*\* | No | Yes | | ||
101 | +-----------------------+-----------------------+-----------------------+ | ||
102 | | Installed Packages | No**\* | Yes***\* | | ||
103 | +-----------------------+-----------------------+-----------------------+ | ||
104 | | Construction | Packages | Shared State | | ||
105 | +-----------------------+-----------------------+-----------------------+ | ||
106 | |||
107 | \* Extensible SDK contains the toolchain and debugger if | ||
108 | ```SDK_EXT_TYPE`` <&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE>`__ is "full" | ||
109 | or | ||
110 | ```SDK_INCLUDE_TOOLCHAIN`` <&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN>`__ | ||
111 | is "1", which is the default. \*\* Sysroot is managed through the use of | ||
112 | ``devtool``. Thus, it is less likely that you will corrupt your SDK | ||
113 | sysroot when you try to add additional libraries. \**\* You can add | ||
114 | runtime package management to the standard SDK but it is not supported | ||
115 | by default. \***\* You must build and make the shared state available to | ||
116 | extensible SDK users for "packages" you want to enable users to install. | ||
117 | |||
118 | The Cross-Development Toolchain | ||
119 | ------------------------------- | ||
120 | |||
121 | The `Cross-Development | ||
122 | Toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__ consists | ||
123 | of a cross-compiler, cross-linker, and cross-debugger that are used to | ||
124 | develop user-space applications for targeted hardware. Additionally, for | ||
125 | an extensible SDK, the toolchain also has built-in ``devtool`` | ||
126 | functionality. This toolchain is created by running a SDK installer | ||
127 | script or through a `Build | ||
128 | Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ that is based on | ||
129 | your metadata configuration or extension for your targeted device. The | ||
130 | cross-toolchain works with a matching target sysroot. | ||
131 | |||
132 | .. _sysroot: | ||
133 | |||
134 | Sysroots | ||
135 | -------- | ||
136 | |||
137 | The native and target sysroots contain needed headers and libraries for | ||
138 | generating binaries that run on the target architecture. The target | ||
139 | sysroot is based on the target root filesystem image that is built by | ||
140 | the OpenEmbedded build system and uses the same metadata configuration | ||
141 | used to build the cross-toolchain. | ||
142 | |||
143 | The QEMU Emulator | ||
144 | ----------------- | ||
145 | |||
146 | The QEMU emulator allows you to simulate your hardware while running | ||
147 | your application or image. QEMU is not part of the SDK but is made | ||
148 | available a number of different ways: | ||
149 | |||
150 | - If you have cloned the ``poky`` Git repository to create a `Source | ||
151 | Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ and you have | ||
152 | sourced the environment setup script, QEMU is installed and | ||
153 | automatically available. | ||
154 | |||
155 | - If you have downloaded a Yocto Project release and unpacked it to | ||
156 | create a Source Directory and you have sourced the environment setup | ||
157 | script, QEMU is installed and automatically available. | ||
158 | |||
159 | - If you have installed the cross-toolchain tarball and you have | ||
160 | sourced the toolchain's setup environment script, QEMU is also | ||
161 | installed and automatically available. | ||
162 | |||
163 | SDK Development Model | ||
164 | ===================== | ||
165 | |||
166 | Fundamentally, the SDK fits into the development process as follows: The | ||
167 | SDK is installed on any machine and can be used to develop applications, | ||
168 | images, and kernels. An SDK can even be used by a QA Engineer or Release | ||
169 | Engineer. The fundamental concept is that the machine that has the SDK | ||
170 | installed does not have to be associated with the machine that has the | ||
171 | Yocto Project installed. A developer can independently compile and test | ||
172 | an object on their machine and then, when the object is ready for | ||
173 | integration into an image, they can simply make it available to the | ||
174 | machine that has the Yocto Project. Once the object is available, the | ||
175 | image can be rebuilt using the Yocto Project to produce the modified | ||
176 | image. | ||
177 | |||
178 | You just need to follow these general steps: | ||
179 | |||
180 | 1. *Install the SDK for your target hardware:* For information on how to | ||
181 | install the SDK, see the "`Installing the | ||
182 | SDK <#sdk-installing-the-sdk>`__" section. | ||
183 | |||
184 | 2. *Download or Build the Target Image:* The Yocto Project supports | ||
185 | several target architectures and has many pre-built kernel images and | ||
186 | root filesystem images. | ||
187 | |||
188 | If you are going to develop your application on hardware, go to the | ||
189 | ```machines`` <&YOCTO_MACHINES_DL_URL;>`__ download area and choose a | ||
190 | target machine area from which to download the kernel image and root | ||
191 | filesystem. This download area could have several files in it that | ||
192 | support development using actual hardware. For example, the area | ||
193 | might contain ``.hddimg`` files that combine the kernel image with | ||
194 | the filesystem, boot loaders, and so forth. Be sure to get the files | ||
195 | you need for your particular development process. | ||
196 | |||
197 | If you are going to develop your application and then run and test it | ||
198 | using the QEMU emulator, go to the | ||
199 | ```machines/qemu`` <&YOCTO_QEMU_DL_URL;>`__ download area. From this | ||
200 | area, go down into the directory for your target architecture (e.g. | ||
201 | ``qemux86_64`` for an Intel-based 64-bit architecture). Download the | ||
202 | kernel, root filesystem, and any other files you need for your | ||
203 | process. | ||
204 | |||
205 | .. note:: | ||
206 | |||
207 | To use the root filesystem in QEMU, you need to extract it. See | ||
208 | the " | ||
209 | Extracting the Root Filesystem | ||
210 | " section for information on how to extract the root filesystem. | ||
211 | |||
212 | 3. *Develop and Test your Application:* At this point, you have the | ||
213 | tools to develop your application. If you need to separately install | ||
214 | and use the QEMU emulator, you can go to `QEMU Home | ||
215 | Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about | ||
216 | the emulator. See the "`Using the Quick EMUlator | ||
217 | (QEMU) <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__" chapter in the | ||
218 | Yocto Project Development Tasks Manual for information on using QEMU | ||
219 | within the Yocto Project. | ||
220 | |||
221 | The remainder of this manual describes how to use the extensible and | ||
222 | standard SDKs. Information also exists in appendix form that describes | ||
223 | how you can build, install, and modify an SDK. | ||