summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-03-02 08:48:50 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-03-23 21:56:07 +0000
commit0bb6e48a334d8ab7bedb7da9444a3a1b812ef996 (patch)
treee9d613f7153b7453fd2e7606278378258a8e8ddc /documentation
parent5a647013e52a25843aef17947c442cdbfb794fd3 (diff)
downloadpoky-0bb6e48a334d8ab7bedb7da9444a3a1b812ef996.tar.gz
sdk-manual: WIP on the book.
(From yocto-docs rev: 140577dd1f91c096152354e711709efe64bbcd0e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.xml256
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml566
-rw-r--r--documentation/sdk-manual/sdk-using.xml297
3 files changed, 998 insertions, 121 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<!--
75vim: expandtab tw=80 ts=4 301vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index c238dee382..bc9ccd28d3 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -6,69 +6,537 @@
6 6
7<title>Using the Extensible SDK</title> 7<title>Using the Extensible SDK</title>
8 8
9<para role='writernotes'> 9<para>
10 This chapter describes what you need on your machine in order to use 10 This chapter describes the extensible SDK and how to use it.
11 an extensible SDK. 11 The extensible SDK makes it easy to add new applications and libraries
12 The chapter does not repeat information that also applies to using the 12 to an image, modify the source for an existing component, test
13 standard SDK. 13 changes on the target hardware, and ease integration into the rest
14 The chapter also includes procedures of tasks you can perform using 14 of the build system.
15 an extensible SDK.
16 <note>
17 The tasks you can perform using a standard SDK are also available
18 using an extensible SDK.
19 For information on using the standard SDK, see the
20 "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
21 chapter.
22 </note>
23</para> 15</para>
24 16
17<para>
18 Information in this chapter covers features that are not part of the
19 standard SDK.
20 In other words, the chapter presents information unique to the
21 extensible SDK only.
22 For information on how to use the standard SDK, see the
23 "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
24 chapter.
25</para>
25 26
26<section id='sdk-setting-up-to-use-the-extensible-sdk'> 27<section id='sdk-setting-up-to-use-the-extensible-sdk'>
27 <title>Setting Up to Use the Extensible SDK</title> 28 <title>Setting Up to Use the Extensible SDK</title>
28 29
29 <para role='writernotes'> 30 <para>
30 Here is a list of items I think need addressed in this section: 31 Getting set up to use the extensible SDK is identical to getting set
32 up to use the standard SDK.
33 You still need to locate and run the installer and then run the
34 environment setup script.
35 See the
36 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
37 and the
38 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
39 sections for general information.
40 The following items highlight the only differences between getting
41 set up to use the extensible SDK as compared to the standard SDK:
31 <itemizedlist> 42 <itemizedlist>
32 <listitem><para role='writernotes'><emphasis>Cover differences in the development 43 <listitem><para><emphasis>Default Installation Directory:</emphasis>
33 that might be impacted because they are using an extensible 44 By default, the extensible SDK installs into the
34 SDK</emphasis></para> 45 <filename>poky_sdk</filename> folder of your home directory.
35 <para role='writernotes'>Presumably, the various development scenarios are 46 As with the standard SDK, you can choose to install the
36 covered regarding setup in the previous chapter. 47 extensible SDK in any location when you run the installer.
37 Are these impacted because the developer is going to now be
38 using an extensible SDK?
39 If so, what are the implications?
40 </para></listitem> 48 </para></listitem>
41 <listitem><para role='writernotes'><emphasis>What new recommendations exist now that 49 <listitem><para><emphasis>Build Tools and Build System:</emphasis>
42 the developer is going to be using an extensible SDK?</emphasis></para> 50 The extensible SDK installer performs additional tasks as
43 <para role='writernotes'>We should cover the most common development scenarios 51 compared to the standard SDK installer.
44 that apply when using an extensible SDK. 52 The extensible SDK installer extracts build tools specific
45 Is there a recommended development flow we want to present 53 to the SDK and the installer also prepares the build system.
46 when using an extensible SDK? 54 Here is example output for running the extensible SDK
47 What conditions in a development scenario warrant use of 55 installer:
48 the extensible SDK as compared to the standard SDK? 56 <literallayout class='monospaced'>
49 </para></listitem> 57 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh
50 <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set 58 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot
51 up the extensible SDK?</emphasis></para> 59 ===================================================================================
52 <para role='writernotes'>Is it just a matter of building out the SDK using 60 Enter target directory for SDK (default: ~/poky_sdk):
53 <filename>bitbake -c populate_sdk_ext</filename>? 61 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
54 Is there a pre-built extensible SDK laying around they can 62 Extracting SDK......................................................................done
55 find and download if they are using a machine that does not 63 Setting it up...
56 have YP installed, which would prevent them from building their 64 Extracting buildtools...
57 own SDK? 65 Preparing build system...
66 done
67 SDK has been successfully set up and is ready to be used.
68 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
69 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
70 </literallayout>
58 </para></listitem> 71 </para></listitem>
59 </itemizedlist> 72 </itemizedlist>
60 </para> 73 </para>
74
75 <para>
76 After installing the SDK, you need to run the SDK environment setup
77 script.
78 Here is the output:
79 <literallayout class='monospaced'>
80 $ source environment-setup-core2-64-poky-linux
81 SDK environment now set up; additionally you may now run devtool to perform development tasks.
82 Run devtool --help for further details.
83 </literallayout>
84 Once you run the environment setup script, you have
85 <filename>devtool</filename> available.
86 </para>
61</section> 87</section>
62 88
63<section id='sdk-using-the-extensible-sdk-to-task-1'> 89<section id='sdk-use-devtool-to-add-an-application'>
64 <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title> 90 <title>Use <filename>devtool add</filename> to Add an Application</title>
65 91
66 <para role='writernotes'> 92 <para>
67 Describe the specific task you are going to accomplish with the 93 The <filename>devtool add</filename> command generates
68 extensible SDK. 94 a new recipe based on existing source code.
69 Provide a diagram showing the rough flow of the task. 95 This command takes advantage of the
70 Provide specific steps using a real example that works through the 96 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
71 task. 97 layer that many <filename>devtool</filename> commands
98 use.
99 The command is flexible enough to allow you to extract source
100 code into both the workspace or a separate local Git repository
101 and to use existing code that does not need to be extracted.
102 </para>
103
104 <para>
105 Depending on your particular scenario, the arguments and options
106 you use with <filename>devtool add</filename> form different
107 combinations.
108 The following diagram shows common development flows
109 you would use with the <filename>devtool add</filename>
110 command:
111 </para>
112
113 <para>
114 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
115 </para>
116
117 <para>
118 <orderedlist>
119 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
120 The top part of the flow shows three scenarios by which
121 you could use <filename>devtool add</filename> to
122 generate a recipe based on existing source code.</para>
123
124 <para>In a shared development environment, it is
125 typical where other developers are responsible for
126 various areas of source code.
127 As a developer, you are probably interested in using
128 that source code as part of your development using
129 the Yocto Project.
130 All you need is access to the code, a recipe, and a
131 controlled area in which to do your work.</para>
132
133 <para>Within the diagram, three possible scenarios
134 feed into the <filename>devtool add</filename> workflow:
135 <itemizedlist>
136 <listitem><para><emphasis>Left</emphasis>:
137 The left scenario represents a common situation
138 where the source code does not exist locally
139 and needs to be extracted.
140 In this situation, you just let it get
141 extracted to the default workspace - you do not
142 want it in some specific location outside of the
143 workspace.
144 Thus, everything you need will be located in the
145 workspace:
146 <literallayout class='monospaced'>
147 $ devtool add <replaceable>recipe fetchuri</replaceable>
148 </literallayout>
149 With this command, <filename>devtool</filename>
150 creates a recipe and an append file in the
151 workspace as well as extracts the upstream
152 source files into a local Git repository also
153 within the <filename>sources</filename> folder.
154 </para></listitem>
155 <listitem><para><emphasis>Middle</emphasis>:
156 The middle scenario also represents a situation where
157 the source code does not exist locally.
158 In this case, the code is again upstream
159 and needs to be extracted to some
160 local area - this time outside of the default
161 workspace.
162 As always, if required <filename>devtool</filename> creates
163 a Git repository locally during the extraction.
164 Furthermore, the first positional argument
165 <replaceable>srctree</replaceable> in this case
166 identifies where the
167 <filename>devtool add</filename> command
168 will locate the extracted code outside of the
169 workspace:
170 <literallayout class='monospaced'>
171 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
172 </literallayout>
173 In summary, the source code is pulled from
174 <replaceable>fetchuri</replaceable> and extracted
175 into the location defined by
176 <replaceable>srctree</replaceable> as a local
177 Git repository.</para>
178
179 <para>Within workspace, <filename>devtool</filename>
180 creates both the recipe and an append file
181 for the recipe.
182 </para></listitem>
183 <listitem><para><emphasis>Right</emphasis>:
184 The right scenario represents a situation
185 where the source tree (srctree) has been
186 previously prepared outside of the
187 <filename>devtool</filename> workspace.
188 </para>
189
190 <para>The following command names the recipe
191 and identifies where the existing source tree
192 is located:
193 <literallayout class='monospaced'>
194 $ devtool add <replaceable>recipe srctree</replaceable>
195 </literallayout>
196 The command examines the source code and creates
197 a recipe for it placing the recipe into the
198 workspace.</para>
199
200 <para>Because the extracted source code already exists,
201 <filename>devtool</filename> does not try to
202 relocate it into the workspace - just the new
203 the recipe is placed in the workspace.</para>
204
205 <para>Aside from a recipe folder, the command
206 also creates an append folder and places an initial
207 <filename>*.bbappend</filename> within.
208 </para></listitem>
209 </itemizedlist>
210 </para></listitem>
211 <listitem><para><emphasis>Edit the Recipe</emphasis>:
212 At this point, you can use <filename>devtool edit-recipe</filename>
213 to open up the editor as defined by the
214 <filename>$EDITOR</filename> environment variable
215 and modify the file:
216 <literallayout class='monospaced'>
217 $ devtool edit-recipe <replaceable>recipe</replaceable>
218 </literallayout>
219 From within the editor, you can make modifications to the
220 recipe that take affect when you build it later.
221 </para></listitem>
222 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
223 At this point in the flow, the next step you
224 take depends on what you are going to do with
225 the new code.</para>
226 <para>If you need to take the build output and eventually
227 move it to the target hardware, you would use
228 <filename>devtool build</filename>:
229 <note>
230 You could use <filename>bitbake</filename> to build
231 the recipe as well.
232 </note>
233 <literallayout class='monospaced'>
234 $ devtool build <replaceable>recipe</replaceable>
235 </literallayout></para>
236 <para>On the other hand, if you want an image to
237 contain the recipe's packages for immediate deployment
238 onto a device (e.g. for testing purposes), you can use
239 the <filename>devtool build-image</filename> command:
240 <literallayout class='monospaced'>
241 $ devtool build-image <replaceable>image</replaceable>
242 </literallayout>
243 </para></listitem>
244 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
245 When you use the <filename>devtool build</filename>
246 command to build out your recipe, you probably want to
247 see if the resulting build output works as expected on target
248 hardware.
249 <note>
250 This step assumes you have a previously built
251 image that is already either running in QEMU or
252 running on actual hardware.
253 Also, it is assumed that for deployment of the image
254 to the target, SSH is installed in the image and if
255 the image is running on real hardware that you have
256 network access to and from your development machine.
257 </note>
258 You can deploy your build output to that target hardware by
259 using the <filename>devtool deploy-target</filename> command:
260 <literallayout class='monospaced'>
261 $ devtool deploy-target <replaceable>recipe target</replaceable>
262 </literallayout>
263 The <replaceable>target</replaceable> is a live target machine
264 running as an SSH server.</para>
265
266 <para>You can, of course, also deploy the image you build
267 using the <filename>devtool build-image</filename> command
268 to actual hardware.
269 However, <filename>devtool</filename> does not provide a
270 specific command that allows you to do this.
271 </para></listitem>
272 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
273 Once you are satisfied with the recipe, if you have made
274 any changes to the source tree that you want to have
275 applied by the recipe, you need to generate patches
276 from those changes.
277 You do this before moving the recipe
278 to its final layer and cleaning up the workspace area
279 <filename>devtool</filename> uses.
280 This optional step is especially relevant if you are
281 using or adding third-party software.</para>
282 <para>To convert commits created using Git to patch files,
283 use the <filename>devtool update-recipe</filename> command.
284 <note>
285 Any changes you want to turn into patches must be
286 committed to the Git repository in the source tree.
287 </note>
288 <literallayout class='monospaced'>
289 $ devtool update-recipe <replaceable>recipe</replaceable>
290 </literallayout>
291 </para></listitem>
292 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
293 Before cleaning up the workspace, you need to move the
294 final recipe to its permanent layer.
295 You must do this before using the
296 <filename>devtool reset</filename> command if you want to
297 retain the recipe.
298 </para></listitem>
299 <listitem><para><emphasis>Reset the Recipe</emphasis>:
300 As a final step, you can restore the state such that
301 standard layers and the upstream source is used to build
302 the recipe rather than data in the workspace.
303 To reset the recipe, use the <filename>devtool reset</filename>
304 command:
305 <literallayout class='monospaced'>
306 $ devtool reset <replaceable>recipe</replaceable>
307 </literallayout>
308 </para></listitem>
309 </orderedlist>
310 </para>
311</section>
312
313<section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
314 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
315
316 <para>
317 The <filename>devtool modify</filename> command prepares the
318 way to work on existing code that already has a recipe in
319 place.
320 The command is flexible enough to allow you to extract code,
321 specify the existing recipe, and keep track of and gather any
322 patch files from other developers that are
323 associated with the code.
324 </para>
325
326 <para>
327 Depending on your particular scenario, the arguments and options
328 you use with <filename>devtool modify</filename> form different
329 combinations.
330 The following diagram shows common development flows
331 you would use with the <filename>devtool modify</filename>
332 command:
333 </para>
334
335 <para>
336 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
337 </para>
338
339 <para>
340 <orderedlist>
341 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
342 The top part of the flow shows three scenarios by which
343 you could use <filename>devtool modify</filename> to
344 prepare to work on source files.
345 Each scenario assumes the following:
346 <itemizedlist>
347 <listitem><para>The recipe exists in some layer external
348 to the <filename>devtool</filename> workspace.
349 </para></listitem>
350 <listitem><para>The source files exist upstream in an
351 un-extracted state or locally in a previously
352 extracted state.
353 </para></listitem>
354 </itemizedlist>
355 The typical situation is where another developer has
356 created some layer for use with the Yocto Project and
357 their recipe already resides in that layer.
358 Furthermore, their source code is readily available
359 either upstream or locally.
360 <itemizedlist>
361 <listitem><para><emphasis>Left</emphasis>:
362 The left scenario represents a common situation
363 where the source code does not exist locally
364 and needs to be extracted.
365 In this situation, the source is extracted
366 into the default workspace location.
367 The recipe, in this scenario, is in its own
368 layer outside the workspace
369 (i.e.
370 <filename>meta-</filename><replaceable>layername</replaceable>).
371 </para>
372
373 <para>The following command identifies the recipe
374 and by default extracts the source files:
375 <literallayout class='monospaced'>
376 $ devtool modify <replaceable>recipe</replaceable>
377 </literallayout>
378 Once <filename>devtool</filename>locates the recipe,
379 it uses the
380 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
381 variable to locate the source code and
382 any local patch files from other developers are
383 located.
384 <note>
385 You cannot provide an URL for
386 <replaceable>srctree</replaceable> when using the
387 <filename>devtool modify</filename> command.
388 </note>
389 With this scenario, however, since no
390 <replaceable>srctree</replaceable> argument exists, the
391 <filename>devtool modify</filename> command by default
392 extracts the source files to a Git structure.
393 Furthermore, the location for the extracted source is the
394 default area within the workspace.
395 The result is that the command sets up both the source
396 code and an append file within the workspace with the
397 recipe remaining in its original location.
398 </para></listitem>
399 <listitem><para><emphasis>Middle</emphasis>:
400 The middle scenario represents a situation where
401 the source code also does not exist locally.
402 In this case, the code is again upstream
403 and needs to be extracted to some
404 local area as a Git repository.
405 The recipe, in this scenario, is again in its own
406 layer outside the workspace.</para>
407
408 <para>The following command tells
409 <filename>devtool</filename> what recipe with
410 which to work and, in this case, identifies a local
411 area for the extracted source files that is outside
412 of the default workspace:
413 <literallayout class='monospaced'>
414 $ devtool modify <replaceable>recipe srctree</replaceable>
415 </literallayout>
416 As with all extractions, the command uses
417 the recipe's <filename>SRC_URI</filename> to locate the
418 source files.
419 Once the files are located, the command by default
420 extracts them.
421 Providing the <replaceable>srctree</replaceable>
422 argument instructs <filename>devtool</filename> where
423 place the extracted source.</para>
424
425 <para>Within workspace, <filename>devtool</filename>
426 creates an append file for the recipe.
427 The recipe remains in its original location but
428 the source files are extracted to the location you
429 provided with <replaceable>srctree</replaceable>.
430 </para></listitem>
431 <listitem><para><emphasis>Right</emphasis>:
432 The right scenario represents a situation
433 where the source tree
434 (<replaceable>srctree</replaceable>) exists as a
435 previously extracted Git structure outside of
436 the <filename>devtool</filename> workspace.
437 In this example, the recipe also exists
438 elsewhere in its own layer.
439 </para>
440
441 <para>The following command tells
442 <filename>devtool</filename> the recipe
443 with which to work, uses the "-n" option to indicate
444 source does not need to be extracted, and uses
445 <replaceable>srctree</replaceable> to point to the
446 previously extracted source files:
447 <literallayout class='monospaced'>
448 $ devtool modify -n <replaceable>recipe srctree</replaceable>
449 </literallayout>
450 </para>
451
452 <para>Once the command finishes, it creates only
453 an append file for the recipe in the workspace.
454 The recipe and the source code remain in their
455 original locations.
456 </para></listitem>
457 </itemizedlist>
458 </para></listitem>
459 <listitem><para><emphasis>Edit the Source</emphasis>:
460 Once you have used the <filename>devtool modify</filename>
461 command, you are free to make changes to the source
462 files.
463 You can use any editor you like to make and save
464 your source code modifications.
465 </para></listitem>
466 <listitem><para><emphasis>Build the Recipe</emphasis>:
467 Once you have updated the source files, you can build
468 the recipe.
469 You can either use <filename>devtool build</filename> or
470 <filename>bitbake</filename>.
471 Either method produces build output that is stored
472 in
473 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
474 </para></listitem>
475 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
476 When you use the <filename>devtool build</filename>
477 command or <filename>bitbake</filename> to build out your
478 recipe, you probably want to see if the resulting build
479 output works as expected on target hardware.
480 <note>
481 This step assumes you have a previously built
482 image that is already either running in QEMU or
483 running on actual hardware.
484 Also, it is assumed that for deployment of the image
485 to the target, SSH is installed in the image and if
486 the image is running on real hardware that you have
487 network access to and from your development machine.
488 </note>
489 You can deploy your build output to that target hardware by
490 using the <filename>devtool deploy-target</filename> command:
491 <literallayout class='monospaced'>
492 $ devtool deploy-target <replaceable>recipe target</replaceable>
493 </literallayout>
494 The <replaceable>target</replaceable> is a live target machine
495 running as an SSH server.</para>
496
497 <para>You can, of course, also deploy the image you build
498 using the <filename>devtool build-image</filename> command
499 to actual hardware.
500 However, <filename>devtool</filename> does not provide a
501 specific command that allows you to do this.
502 </para></listitem>
503 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
504 After you have debugged your changes, you can
505 use <filename>devtool update-recipe</filename> to
506 generate patch files for all the commits you have
507 made.
508 <note>
509 Patch files are generated only for changes
510 you have committed.
511 </note>
512 <literallayout class='monospaced'>
513 $ devtool update-recipe <replaceable>recipe</replaceable>
514 </literallayout>
515 By default, the
516 <filename>devtool update-recipe</filename> command
517 creates the patch files in a folder named the same
518 as the recipe beneath the folder in which the recipe
519 resides, and updates the recipe's
520 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
521 statement to point to the generated patch files.
522 <note>
523 You can use the
524 "--append <replaceable>LAYERDIR</replaceable>"
525 option to cause the command to create append files
526 in a specific layer rather than the default
527 recipe layer.
528 </note>
529 </para></listitem>
530 <listitem><para><emphasis>Restore the Workspace</emphasis>:
531 The <filename>devtool reset</filename> restores the
532 state so that standard layers and upstream sources are
533 used to build the recipe rather than what is in the
534 workspace.
535 <literallayout class='monospaced'>
536 $ devtool reset <replaceable>recipe</replaceable>
537 </literallayout>
538 </para></listitem>
539 </orderedlist>
72 </para> 540 </para>
73</section> 541</section>
74 542
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index 66f2c0ed9d..f2acaa7fc4 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -23,8 +23,9 @@
23<section id='sdk-standard-sdk-intro'> 23<section id='sdk-standard-sdk-intro'>
24 <title>Why use the Standard SDK and What is in It?</title> 24 <title>Why use the Standard SDK and What is in It?</title>
25 25
26 <para role='writernotes'> 26 <para>
27 <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis> 27 Fundamentally, the standard SDK exists so that you can access
28 cross-development tools.
28 This paragraph describes why you use the Standard SDK. 29 This paragraph describes why you use the Standard SDK.
29 Probably need to compare that against why you would not be interested 30 Probably need to compare that against why you would not be interested
30 in the extensible SDK here as well. 31 in the extensible SDK here as well.
@@ -37,46 +38,6 @@
37 If there is more detail, I need to know about it. 38 If there is more detail, I need to know about it.
38 </para> 39 </para>
39 40
40 <para role='writernotes'>
41 <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
42 Here is a list of items I think need addressed in these early
43 sections:
44 <itemizedlist>
45 <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
46 <para role='writernotes'>In other words, is the developer on a machine that
47 has YP on it?
48 Are they on a machine that does not?
49 Is the image they are developing against available as a
50 pre-built, down-loadable image and can they get it?</para>
51 <para role='writernotes'>Depending on the scenario, there are different ways
52 to make sure the machine they are using is ready to use a
53 standard SDK.
54 I think we need to cover the various situations in this
55 section.
56 </para></listitem>
57 <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
58 <para role='writernotes'>What is the most common development scenario?
59 Is there a recommended development flow we want to present
60 when using a standard SDK?
61 What conditions in a development scenario warrant use of
62 just the standard SDK as compared to the extensible SDK?
63 </para></listitem>
64 <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
65 the standard SDK?</emphasis></para>
66 <para role='writernotes'>There is a ton of setup information in the
67 current ADT manual regarding getting, building, and installing
68 an SDK.
69 We would ignore the stuff about the ADT installer script
70 since I presume that is going away.
71 But, there are steps to download and existing
72 <filename>.sh</filename> install script, build out the
73 toolchains assuming your system has YP on it and you can run
74 BitBake, getting the root filesystem, getting an image so you
75 run QEMU on your system, etc.
76 </para></listitem>
77 </itemizedlist>
78 </para>
79
80 <para> 41 <para>
81 The installed Standard SDK consists of several files and directories. 42 The installed Standard SDK consists of several files and directories.
82 Basically, it contains an SDK environment setup script, some 43 Basically, it contains an SDK environment setup script, some
@@ -161,15 +122,16 @@
161 into <filename>/opt/poky</filename>. 122 into <filename>/opt/poky</filename>.
162 However, when you run the SDK installer, you can choose an 123 However, when you run the SDK installer, you can choose an
163 installation directory. 124 installation directory.
125 <note>
126 You must change the permissions on the toolchain
127 installer script so that it is executable.
128 </note>
164 </para> 129 </para>
165 130
166 <para> 131 <para>
167 The following command shows how to run the installer given a 132 The following command shows how to run the installer given a
168 toolchain tarball for a 64-bit x86 development host system and 133 toolchain tarball for a 64-bit x86 development host system and
169 a 32-bit x86 target architecture. 134 a 32-bit x86 target architecture.
170 When you run the installer, the script prompts you for a
171 system password so that you permissions can change enabling
172 you to run the installer script.
173 The example assumes the toolchain installer is located in 135 The example assumes the toolchain installer is located in
174 <filename>~/Downloads/</filename>. 136 <filename>~/Downloads/</filename>.
175 <note> 137 <note>
@@ -180,17 +142,16 @@
180 run the installer again. 142 run the installer again.
181 </note> 143 </note>
182 <literallayout class='monospaced'> 144 <literallayout class='monospaced'>
183 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 145 $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
184 Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot 146 Poky (Yocto Project Reference Distro) SDK installer version 2.0
185 ======================================================================== 147 ===============================================================
186 Enter target directory for SDK (default: /opt/poky/2.1+snapshot): 148 Enter target directory for SDK (default: /opt/poky/2.1):
187 You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y 149 You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y
188 [sudo] password for scottrif: 150 Extracting SDK.......................................................................done
189 Extracting SDK.......................done
190 Setting it up...done 151 Setting it up...done
191 SDK has been successfully set up and is ready to be used. 152 SDK has been successfully set up and is ready to be used.
192 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 153 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
193 $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux 154 $ . /opt/poky/2.1/environment-setup-i586-poky-linux
194 </literallayout> 155 </literallayout>
195 </para> 156 </para>
196 157
@@ -221,11 +182,11 @@
221 Environment setup scripts begin with the string 182 Environment setup scripts begin with the string
222 "<filename>environment-setup</filename>" and include as part of their 183 "<filename>environment-setup</filename>" and include as part of their
223 name the tuned target architecture. 184 name the tuned target architecture.
224 For example, the setup script for an IA-based target machine using 185 For example, the command to source a setup script for an IA-based
225 i586 tuning and located in the default SDK installation 186 target machine using i586 tuning and located in the default SDK
226 directory is as follows: 187 installation directory is as follows:
227 <literallayout class='monospaced'> 188 <literallayout class='monospaced'>
228 $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux 189 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
229 </literallayout> 190 </literallayout>
230 When you run the setup script, many environment variables are 191 When you run the setup script, many environment variables are
231 defined: 192 defined:
@@ -256,6 +217,228 @@
256 </para> 217 </para>
257</section> 218</section>
258 219
220<section id='autotools-based-projects'>
221 <title>Autotools-Based Projects</title>
222
223 <para>
224 Once you have a suitable cross-toolchain installed, it is very easy to
225 develop a project outside of the OpenEmbedded build system.
226 This section presents a simple "Helloworld" example that shows how
227 to set up, compile, and run the project.
228 </para>
229
230 <section id='creating-and-running-a-project-based-on-gnu-autotools'>
231 <title>Creating and Running a Project Based on GNU Autotools</title>
232
233 <para>
234 Follow these steps to create a simple Autotools-based project:
235 <orderedlist>
236 <listitem><para><emphasis>Create your directory:</emphasis>
237 Create a clean directory for your project and then make
238 that directory your working location:
239 <literallayout class='monospaced'>
240 $ mkdir $HOME/helloworld
241 $ cd $HOME/helloworld
242 </literallayout></para></listitem>
243 <listitem><para><emphasis>Populate the directory:</emphasis>
244 Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
245 and <filename>configure.in</filename> files as follows:
246 <itemizedlist>
247 <listitem><para>For <filename>hello.c</filename>, include
248 these lines:
249 <literallayout class='monospaced'>
250 #include &lt;stdio.h&gt;
251
252 main()
253 {
254 printf("Hello World!\n");
255 }
256 </literallayout></para></listitem>
257 <listitem><para>For <filename>Makefile.am</filename>,
258 include these lines:
259 <literallayout class='monospaced'>
260 bin_PROGRAMS = hello
261 hello_SOURCES = hello.c
262 </literallayout></para></listitem>
263 <listitem><para>For <filename>configure.in</filename>,
264 include these lines:
265 <literallayout class='monospaced'>
266 AC_INIT(hello.c)
267 AM_INIT_AUTOMAKE(hello,0.1)
268 AC_PROG_CC
269 AC_PROG_INSTALL
270 AC_OUTPUT(Makefile)
271 </literallayout></para></listitem>
272 </itemizedlist></para></listitem>
273 <listitem><para><emphasis>Source the cross-toolchain
274 environment setup file:</emphasis>
275 Installation of the cross-toolchain creates a cross-toolchain
276 environment setup script in the directory that the ADT
277 was installed.
278 Before you can use the tools to develop your project, you must
279 source this setup script.
280 The script begins with the string "environment-setup" and contains
281 the machine architecture, which is followed by the string
282 "poky-linux".
283 Here is an example that sources a script from the
284 default ADT installation directory that uses the
285 32-bit Intel x86 Architecture and the
286 &DISTRO_NAME; Yocto Project release:
287 <literallayout class='monospaced'>
288 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
289 </literallayout></para></listitem>
290 <listitem><para><emphasis>Generate the local aclocal.m4
291 files and create the configure script:</emphasis>
292 The following GNU Autotools generate the local
293 <filename>aclocal.m4</filename> files and create the
294 configure script:
295 <literallayout class='monospaced'>
296 $ aclocal
297 $ autoconf
298 </literallayout></para></listitem>
299 <listitem><para><emphasis>Generate files needed by GNU
300 coding standards:</emphasis>
301 GNU coding standards require certain files in order for the
302 project to be compliant.
303 This command creates those files:
304 <literallayout class='monospaced'>
305 $ touch NEWS README AUTHORS ChangeLog
306 </literallayout></para></listitem>
307 <listitem><para><emphasis>Generate the configure
308 file:</emphasis>
309 This command generates the <filename>configure</filename>:
310 <literallayout class='monospaced'>
311 $ automake -a
312 </literallayout></para></listitem>
313 <listitem><para><emphasis>Cross-compile the project:</emphasis>
314 This command compiles the project using the cross-compiler.
315 The
316 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
317 environment variable provides the minimal arguments for
318 GNU configure:
319 <literallayout class='monospaced'>
320 $ ./configure ${CONFIGURE_FLAGS}
321 </literallayout></para></listitem>
322 <listitem><para><emphasis>Make and install the project:</emphasis>
323 These two commands generate and install the project into the
324 destination directory:
325 <literallayout class='monospaced'>
326 $ make
327 $ make install DESTDIR=./tmp
328 </literallayout></para></listitem>
329 <listitem><para><emphasis>Verify the installation:</emphasis>
330 This command is a simple way to verify the installation
331 of your project.
332 Running the command prints the architecture on which
333 the binary file can run.
334 This architecture should be the same architecture that
335 the installed cross-toolchain supports.
336 <literallayout class='monospaced'>
337 $ file ./tmp/usr/local/bin/hello
338 </literallayout></para></listitem>
339 <listitem><para><emphasis>Execute your project:</emphasis>
340 To execute the project in the shell, simply enter the name.
341 You could also copy the binary to the actual target hardware
342 and run the project there as well:
343 <literallayout class='monospaced'>
344 $ ./hello
345 </literallayout>
346 As expected, the project displays the "Hello World!" message.
347 </para></listitem>
348 </orderedlist>
349 </para>
350 </section>
351
352 <section id='passing-host-options'>
353 <title>Passing Host Options</title>
354
355 <para>
356 For an Autotools-based project, you can use the cross-toolchain by just
357 passing the appropriate host option to <filename>configure.sh</filename>.
358 The host option you use is derived from the name of the environment setup
359 script found in the directory in which you installed the cross-toolchain.
360 For example, the host option for an ARM-based target that uses the GNU EABI
361 is <filename>armv5te-poky-linux-gnueabi</filename>.
362 You will notice that the name of the script is
363 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
364 Thus, the following command works to update your project and
365 rebuild it using the appropriate cross-toolchain tools:
366 <literallayout class='monospaced'>
367 $ ./configure --host=armv5te-poky-linux-gnueabi \
368 --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
369 </literallayout>
370 <note>
371 If the <filename>configure</filename> script results in problems recognizing the
372 <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
373 regenerate the script to enable the support by doing the following and then
374 run the script again:
375 <literallayout class='monospaced'>
376 $ libtoolize --automake
377 $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
378 [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
379 $ autoconf
380 $ autoheader
381 $ automake -a
382 </literallayout>
383 </note>
384 </para>
385 </section>
386</section>
387
388<section id='makefile-based-projects'>
389 <title>Makefile-Based Projects</title>
390
391 <para>
392 For Makefile-based projects, the cross-toolchain environment variables
393 established by running the cross-toolchain environment setup script
394 are subject to general <filename>make</filename> rules.
395 </para>
396
397 <para>
398 To illustrate this, consider the following four cross-toolchain
399 environment variables:
400 <literallayout class='monospaced'>
401 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
402 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
403 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
404 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
405 </literallayout>
406 Now, consider the following three cases:
407 <itemizedlist>
408 <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
409 Because these variables are not specifically set in the
410 <filename>Makefile</filename>, the variables retain their
411 values based on the environment.
412 </para></listitem>
413 <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
414 Specifically setting variables in the
415 <filename>Makefile</filename> during the build results in the
416 environment settings of the variables being overwritten.
417 </para></listitem>
418 <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
419 Executing the <filename>Makefile</filename> from the command
420 line results in the variables being overwritten with
421 command-line content regardless of what is being set in the
422 <filename>Makefile</filename>.
423 In this case, environment variables are not considered unless
424 you use the "-e" flag during the build:
425 <literallayout class='monospaced'>
426 $ make -e <replaceable>file</replaceable>
427 </literallayout>
428 If you use this flag, then the environment values of the
429 variables override any variables specifically set in the
430 <filename>Makefile</filename>.
431 </para></listitem>
432 </itemizedlist>
433 <note>
434 For the list of variables set up by the cross-toolchain environment
435 setup script, see the
436 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
437 section.
438 </note>
439 </para>
440</section>
441
259<section id='sdk-using-the-sdk-to-task-1'> 442<section id='sdk-using-the-sdk-to-task-1'>
260 <title>Using the SDK to <replaceable>item 1</replaceable></title> 443 <title>Using the SDK to <replaceable>item 1</replaceable></title>
261 444
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-05 19:03:18 +0000