summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-14 13:34:34 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:35 +0100
commitde89b5a0b6ecb9a5b6a3e5a862cf4cee32dc8a94 (patch)
tree9851be19b42edfb032ff83308d77bd863b11159d
parent688e49bb5e6e61b5c0dbbe6b2c3bdf1c5a4bef8d (diff)
downloadpoky-de89b5a0b6ecb9a5b6a3e5a862cf4cee32dc8a94.tar.gz
sphinx: sdk-manual: Various URL, code block and other fixes to imported data
(From yocto-docs rev: 12f5e9cb36409b813ffef9242ce9a042f08acf69) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.rst72
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.rst137
-rw-r--r--documentation/sdk-manual/sdk-extensible.rst303
-rw-r--r--documentation/sdk-manual/sdk-intro.rst26
-rw-r--r--documentation/sdk-manual/sdk-using.rst73
-rw-r--r--documentation/sdk-manual/sdk-working-projects.rst294
6 files changed, 623 insertions, 282 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst
index 3bb6ef3a19..7743e3c004 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.rst
+++ b/documentation/sdk-manual/sdk-appendix-customizing.rst
@@ -18,8 +18,7 @@ build system applies them against ``local.conf`` and ``auto.conf``:
18 18
19- Variables whose values start with "/" are excluded since the 19- Variables whose values start with "/" are excluded since the
20 assumption is that those values are paths that are likely to be 20 assumption is that those values are paths that are likely to be
21 specific to the `build 21 specific to the :term:`Build Host`.
22 host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__.
23 22
24- Variables listed in 23- Variables listed in
25 :term:`SDK_LOCAL_CONF_BLACKLIST` 24 :term:`SDK_LOCAL_CONF_BLACKLIST`
@@ -57,8 +56,8 @@ OpenEmbedded build system used to create the SDK.
57Adjusting the Extensible SDK to Suit Your Build Host's Setup 56Adjusting the Extensible SDK to Suit Your Build Host's Setup
58============================================================ 57============================================================
59 58
60In most cases, the extensible SDK defaults should work with your `build 59In most cases, the extensible SDK defaults should work with your :term:`Build
61host's <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ setup. 60Host`'s setup.
62However, some cases exist for which you might consider making 61However, some cases exist for which you might consider making
63adjustments: 62adjustments:
64 63
@@ -87,8 +86,8 @@ adjustments:
87 opposed to being called explicitly), then you need to do one of the 86 opposed to being called explicitly), then you need to do one of the
88 following: 87 following:
89 88
90 - After ensuring the tasks are `shared 89 - After ensuring the tasks are :ref:`shared
91 state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ tasks (i.e. the 90 state <overview-manual/overview-manual-concepts:shared state cache>` tasks (i.e. the
92 output of the task is saved to and can be restored from the shared 91 output of the task is saved to and can be restored from the shared
93 state cache) or ensuring the tasks are able to be produced quickly 92 state cache) or ensuring the tasks are able to be produced quickly
94 from a task that is a shared state task, add the task name to the 93 from a task that is a shared state task, add the task name to the
@@ -124,7 +123,7 @@ adjustments:
124 123
125- If your OpenEmbedded build system setup uses a different environment 124- If your OpenEmbedded build system setup uses a different environment
126 setup script other than 125 setup script other than
127 ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must 126 :ref:`structure-core-script`, then you must
128 set 127 set
129 :term:`OE_INIT_ENV_SCRIPT` 128 :term:`OE_INIT_ENV_SCRIPT`
130 to point to the environment setup script you use. 129 to point to the environment setup script you use.
@@ -152,8 +151,10 @@ from the :term:`DISTRO` variable.
152The 151The
153:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 152:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
154class defines the default value of the ``SDK_TITLE`` variable as 153class defines the default value of the ``SDK_TITLE`` variable as
155follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or 154follows:
156d.getVar('DISTRO')} SDK" 155::
156
157 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
157 158
158While several ways exist to change this variable, an efficient method is 159While several ways exist to change this variable, an efficient method is
159to set the variable in your distribution's configuration file. Doing so 160to set the variable in your distribution's configuration file. Doing so
@@ -163,7 +164,10 @@ an example, assume you have your own layer for your distribution named
163does the default "poky" distribution. If so, you could update the 164does the default "poky" distribution. If so, you could update the
164``SDK_TITLE`` variable in the 165``SDK_TITLE`` variable in the
165``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following 166``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
166form: SDK_TITLE = "your_title" 167form:
168::
169
170 SDK_TITLE = "your_title"
167 171
168Providing Updates to the Extensible SDK After Installation 172Providing Updates to the Extensible SDK After Installation
169========================================================== 173==========================================================
@@ -193,8 +197,12 @@ the installed SDKs to update the installed SDKs by using the
1933. Build the extensible SDK normally (i.e., use the 1973. Build the extensible SDK normally (i.e., use the
194 ``bitbake -c populate_sdk_ext`` imagename command). 198 ``bitbake -c populate_sdk_ext`` imagename command).
195 199
1964. Publish the SDK using the following command: $ oe-publish-sdk 2004. Publish the SDK using the following command:
197 some_path/sdk-installer.sh path_to_shared_http_directory You must 201 ::
202
203 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
204
205 You must
198 repeat this step each time you rebuild the SDK with changes that you 206 repeat this step each time you rebuild the SDK with changes that you
199 want to make available through the update mechanism. 207 want to make available through the update mechanism.
200 208
@@ -213,7 +221,12 @@ installation directory for the SDK is based on the
213:term:`SDKEXTPATH` variables from 221:term:`SDKEXTPATH` variables from
214within the 222within the
215:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 223:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
216class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can 224class as follows:
225::
226
227 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
228
229You can
217change this default installation directory by specifically setting the 230change this default installation directory by specifically setting the
218``SDKEXTPATH`` variable. 231``SDKEXTPATH`` variable.
219 232
@@ -226,7 +239,10 @@ assume you have your own layer for your distribution named
226does the default "poky" distribution. If so, you could update the 239does the default "poky" distribution. If so, you could update the
227``SDKEXTPATH`` variable in the 240``SDKEXTPATH`` variable in the
228``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following 241``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
229form: SDKEXTPATH = "some_path_for_your_installed_sdk" 242form:
243::
244
245 SDKEXTPATH = "some_path_for_your_installed_sdk"
230 246
231After building your installer, running it prompts the user for 247After building your installer, running it prompts the user for
232acceptance of the some_path_for_your_installed_sdk directory as the 248acceptance of the some_path_for_your_installed_sdk directory as the
@@ -260,8 +276,11 @@ source, you need to do a number of things:
2603. Set the appropriate configuration so that the produced SDK knows how 2763. Set the appropriate configuration so that the produced SDK knows how
261 to find the configuration. The variable you need to set is 277 to find the configuration. The variable you need to set is
262 :term:`SSTATE_MIRRORS`: 278 :term:`SSTATE_MIRRORS`:
263 SSTATE_MIRRORS = "file://.\* 279 ::
264 http://example.com/some_path/sstate-cache/PATH" You can set the 280
281 SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
282
283 You can set the
265 ``SSTATE_MIRRORS`` variable in two different places: 284 ``SSTATE_MIRRORS`` variable in two different places:
266 285
267 - If the mirror value you are setting is appropriate to be set for 286 - If the mirror value you are setting is appropriate to be set for
@@ -271,8 +290,10 @@ source, you need to do a number of things:
271 side, and its contents will not interfere with the build), then 290 side, and its contents will not interfere with the build), then
272 you can set the variable in your ``local.conf`` or custom distro 291 you can set the variable in your ``local.conf`` or custom distro
273 configuration file. You can then "whitelist" the variable through 292 configuration file. You can then "whitelist" the variable through
274 to the SDK by adding the following: SDK_LOCAL_CONF_WHITELIST = 293 to the SDK by adding the following:
275 "SSTATE_MIRRORS" 294 ::
295
296 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
276 297
277 - Alternatively, if you just want to set the ``SSTATE_MIRRORS`` 298 - Alternatively, if you just want to set the ``SSTATE_MIRRORS``
278 variable's value for the SDK alone, create a 299 variable's value for the SDK alone, create a
@@ -296,7 +317,11 @@ This bundling can lead to an SDK installer file that is a Gigabyte or
296more in size. If the size of this file causes a problem, you can build 317more in size. If the size of this file causes a problem, you can build
297an SDK that has just enough in it to install and provide access to the 318an SDK that has just enough in it to install and provide access to the
298``devtool command`` by setting the following in your configuration: 319``devtool command`` by setting the following in your configuration:
299SDK_EXT_TYPE = "minimal" Setting 320::
321
322 SDK_EXT_TYPE = "minimal"
323
324Setting
300:term:`SDK_EXT_TYPE` to 325:term:`SDK_EXT_TYPE` to
301"minimal" produces an SDK installer that is around 35 Mbytes in size, 326"minimal" produces an SDK installer that is around 35 Mbytes in size,
302which downloads and installs quickly. You need to realize, though, that 327which downloads and installs quickly. You need to realize, though, that
@@ -314,9 +339,12 @@ information enables the ``devtool search`` command to return useful
314results. 339results.
315 340
316To facilitate this wider range of information, you would need to set the 341To facilitate this wider range of information, you would need to set the
317following: SDK_INCLUDE_PKGDATA = "1" See the 342following:
318:term:`SDK_INCLUDE_PKGDATA` 343::
319variable for additional information. 344
345 SDK_INCLUDE_PKGDATA = "1"
346
347See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
320 348
321Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" 349Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
322target to be built so that information for all of the recipes included 350target to be built so that information for all of the recipes included
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst
index ed460c78ea..ffaed9deef 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.rst
+++ b/documentation/sdk-manual/sdk-appendix-obtain.rst
@@ -17,10 +17,10 @@ and then run the script to hand-install the toolchain.
17Follow these steps to locate and hand-install the toolchain: 17Follow these steps to locate and hand-install the toolchain:
18 18
191. *Go to the Installers Directory:* Go to 191. *Go to the Installers Directory:* Go to
20 ` <&YOCTO_TOOLCHAIN_DL_URL;>`__ 20 :yocto_dl:`releases/yocto/yocto-3.1.2/toolchain/`
21 21
222. *Open the Folder for Your Build Host:* Open the folder that matches 222. *Open the Folder for Your Build Host:* Open the folder that matches
23 your `build host <&YOCTO_DOCS_REF_URL;#build-system-term>`__ (i.e. 23 your :term:`Build Host` (i.e.
24 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). 24 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
25 25
263. *Locate and Download the SDK Installer:* You need to find and 263. *Locate and Download the SDK Installer:* You need to find and
@@ -28,14 +28,29 @@ Follow these steps to locate and hand-install the toolchain:
28 hardware, and image type. 28 hardware, and image type.
29 29
30 The installer files (``*.sh``) follow this naming convention: 30 The installer files (``*.sh``) follow this naming convention:
31 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh 31 ::
32 Where: host_system is a string representing your development system: 32
33 "i686" or "x86_64" type is a string representing the image: "sato" or 33 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
34 "minimal" arch is a string representing the target architecture: 34
35 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", 35 Where:
36 "mips32r2", "mips64", or "ppc7400" release is the version of Yocto 36 host_system is a string representing your development system:
37 Project. NOTE: The standard SDK installer does not have the "-ext" 37 "i686" or "x86_64"
38 string as part of the filename. The toolchains provided by the Yocto 38
39 type is a string representing the image:
40 "sato" or "minimal"
41
42 arch is a string representing the target architecture:
43 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
44 "mips64", or "ppc7400"
45
46 release is the version of Yocto Project.
47
48 NOTE:
49 The standard SDK installer does not have the "-ext" string as
50 part of the filename.
51
52
53 The toolchains provided by the Yocto
39 Project are based off of the ``core-image-sato`` and 54 Project are based off of the ``core-image-sato`` and
40 ``core-image-minimal`` images and contain libraries appropriate for 55 ``core-image-minimal`` images and contain libraries appropriate for
41 developing against those images. 56 developing against those images.
@@ -43,12 +58,17 @@ Follow these steps to locate and hand-install the toolchain:
43 For example, if your build host is a 64-bit x86 system and you need 58 For example, if your build host is a 64-bit x86 system and you need
44 an extended SDK for a 64-bit core2 target, go into the ``x86_64`` 59 an extended SDK for a 64-bit core2 target, go into the ``x86_64``
45 folder and download the following installer: 60 folder and download the following installer:
46 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh 61 ::
62
63 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
47 64
484. *Run the Installer:* Be sure you have execution privileges and run 654. *Run the Installer:* Be sure you have execution privileges and run
49 the installer. Following is an example from the ``Downloads`` 66 the installer. Following is an example from the ``Downloads``
50 directory: $ 67 directory:
51 ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh 68 ::
69
70 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
71
52 During execution of the script, you choose the root location for the 72 During execution of the script, you choose the root location for the
53 toolchain. See the "`Installed Standard SDK Directory 73 toolchain. See the "`Installed Standard SDK Directory
54 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 74 Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -63,8 +83,7 @@ As an alternative to locating and downloading an SDK installer, you can
63build the SDK installer. Follow these steps: 83build the SDK installer. Follow these steps:
64 84
651. *Set Up the Build Environment:* Be sure you are set up to use BitBake 851. *Set Up the Build Environment:* Be sure you are set up to use BitBake
66 in a shell. See the "`Preparing the Build 86 in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section
67 Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section
68 in the Yocto Project Development Tasks Manual for information on how 87 in the Yocto Project Development Tasks Manual for information on how
69 to get a build host ready that is either a native Linux machine or a 88 to get a build host ready that is either a native Linux machine or a
70 machine that uses CROPS. 89 machine that uses CROPS.
@@ -72,21 +91,23 @@ build the SDK installer. Follow these steps:
722. *Clone the ``poky`` Repository:* You need to have a local copy of the 912. *Clone the ``poky`` Repository:* You need to have a local copy of the
73 Yocto Project :term:`Source Directory` 92 Yocto Project :term:`Source Directory`
74 (i.e. a local 93 (i.e. a local
75 ``poky`` repository). See the "`Cloning the ``poky`` 94 ``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and
76 Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__" and 95 possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and
77 possibly the "`Checking Out by Branch in 96 ":ref:`checkout-out-by-tag-in-poky`" sections
78 Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__" and
79 "`Checking Out by Tag in
80 Poky <&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky>`__" sections
81 all in the Yocto Project Development Tasks Manual for information on 97 all in the Yocto Project Development Tasks Manual for information on
82 how to clone the ``poky`` repository and check out the appropriate 98 how to clone the ``poky`` repository and check out the appropriate
83 branch for your work. 99 branch for your work.
84 100
853. *Initialize the Build Environment:* While in the root directory of 1013. *Initialize the Build Environment:* While in the root directory of
86 the Source Directory (i.e. ``poky``), run the 102 the Source Directory (i.e. ``poky``), run the
87 ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment 103 :ref:`structure-core-script` environment
88 setup script to define the OpenEmbedded build environment on your 104 setup script to define the OpenEmbedded build environment on your
89 build host. $ source OE_INIT_FILE Among other things, the script 105 build host.
106 ::
107
108 $ source oe-init-build-env
109
110 Among other things, the script
90 creates the :term:`Build Directory`, 111 creates the :term:`Build Directory`,
91 which is 112 which is
92 ``build`` in this case and is located in the Source Directory. After 113 ``build`` in this case and is located in the Source Directory. After
@@ -119,13 +140,17 @@ build the SDK installer. Follow these steps:
119 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is 140 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
120 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). 141 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
121 Unable to continue. 142 Unable to continue.
122 143
123 144
1246. *Build the SDK Installer:* To build the SDK installer for a standard 1456. *Build the SDK Installer:* To build the SDK installer for a standard
125 SDK and populate the SDK image, use the following command form. Be 146 SDK and populate the SDK image, use the following command form. Be
126 sure to replace image with an image (e.g. "core-image-sato"): $ 147 sure to replace image with an image (e.g. "core-image-sato"): $
127 bitbake image -c populate_sdk You can do the same for the extensible 148 bitbake image -c populate_sdk You can do the same for the extensible
128 SDK using this command form: $ bitbake image -c populate_sdk_ext 149 SDK using this command form:
150 ::
151
152 $ bitbake image -c populate_sdk_ext
153
129 These commands produce an SDK installer that contains the sysroot 154 These commands produce an SDK installer that contains the sysroot
130 that matches your target root filesystem. 155 that matches your target root filesystem.
131 156
@@ -147,9 +172,12 @@ build the SDK installer. Follow these steps:
147 libc-staticdev" 172 libc-staticdev"
148 173
1497. *Run the Installer:* You can now run the SDK installer from 1747. *Run the Installer:* You can now run the SDK installer from
150 ``tmp/deploy/sdk`` in the Build Directory. Following is an example: $ 175 ``tmp/deploy/sdk`` in the Build Directory. Following is an example:
151 cd ~/poky/build/tmp/deploy/sdk $ 176 ::
152 ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh 177
178 $ cd ~/poky/build/tmp/deploy/sdk
179 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
180
153 During execution of the script, you choose the root location for the 181 During execution of the script, you choose the root location for the
154 toolchain. See the "`Installed Standard SDK Directory 182 toolchain. See the "`Installed Standard SDK Directory
155 Structure <#sdk-installed-standard-sdk-directory-structure>`__" 183 Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -176,7 +204,7 @@ Follow these steps to extract the root filesystem:
176 Image File:* You need to find and download the root filesystem image 204 Image File:* You need to find and download the root filesystem image
177 file that is appropriate for your target system. These files are kept 205 file that is appropriate for your target system. These files are kept
178 in machine-specific folders in the 206 in machine-specific folders in the
179 :yocto_dl:`Index of Releases <releases/yocto/yocto-&DISTRO;/machines/>` 207 :yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`
180 in the "machines" directory. 208 in the "machines" directory.
181 209
182 The machine-specific folders of the "machines" directory contain 210 The machine-specific folders of the "machines" directory contain
@@ -185,22 +213,32 @@ Follow these steps to extract the root filesystem:
185 which you can use with QEMU directly. 213 which you can use with QEMU directly.
186 214
187 The pre-built root filesystem image files follow these naming 215 The pre-built root filesystem image files follow these naming
188 conventions: core-image-profile-arch.tar.bz2 Where: profile is the 216 conventions:
189 filesystem image's profile: lsb, lsb-dev, lsb-sdk, minimal, 217 ::
190 minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk, 218
191 sato-sdk-ptest. For information on these types of image profiles, see 219 core-image-profile-arch.tar.bz2
192 the ":ref:`ref-manual/ref-images:Images`" chapter in the 220
193 Yocto Project Reference Manual. arch is a string representing the 221 Where:
194 target architecture: beaglebone-yocto, beaglebone-yocto-lsb, 222 profile is the filesystem image's profile:
195 edgerouter, edgerouter-lsb, genericx86, genericx86-64, 223 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
196 genericx86-64-lsb, genericx86-lsb and qemu*. The root filesystems 224 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
225 these types of image profiles, see the "Images" chapter in
226 the Yocto Project Reference Manual.
227
228 arch is a string representing the target architecture:
229 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
230 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
231
232 The root filesystems
197 provided by the Yocto Project are based off of the 233 provided by the Yocto Project are based off of the
198 ``core-image-sato`` and ``core-image-minimal`` images. 234 ``core-image-sato`` and ``core-image-minimal`` images.
199 235
200 For example, if you plan on using a BeagleBone device as your target 236 For example, if you plan on using a BeagleBone device as your target
201 hardware and your image is a ``core-image-sato-sdk`` image, you can 237 hardware and your image is a ``core-image-sato-sdk`` image, you can
202 download the following file: 238 download the following file:
203 core-image-sato-sdk-beaglebone-yocto.tar.bz2 239 ::
240
241 core-image-sato-sdk-beaglebone-yocto.tar.bz2
204 242
2052. *Initialize the Cross-Development Environment:* You must ``source`` 2432. *Initialize the Cross-Development Environment:* You must ``source``
206 the cross-development environment setup script to establish necessary 244 the cross-development environment setup script to establish necessary
@@ -210,21 +248,24 @@ Follow these steps to extract the root filesystem:
210 installed the toolchain (e.g. ``poky_sdk``). 248 installed the toolchain (e.g. ``poky_sdk``).
211 249
212 Following is an example based on the toolchain installed in the 250 Following is an example based on the toolchain installed in the
213 "`Locating Pre-Built SDK 251 ":ref:`sdk-locating-pre-built-sdk-installers`" section:
214 Installers <#sdk-locating-pre-built-sdk-installers>`__" section: $ 252 ::
215 source ~/poky_sdk/environment-setup-core2-64-poky-linux 253
254 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
216 255
2173. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` 2563. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
218 command and provide the root filesystem image. 257 command and provide the root filesystem image.
219 258
220 Following is an example command that extracts the root filesystem 259 Following is an example command that extracts the root filesystem
221 from a previously built root filesystem image that was downloaded 260 from a previously built root filesystem image that was downloaded
222 from the `Index of Releases <&YOCTO_DOCS_OM_URL;#index-downloads>`__. 261 from the :yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`.
223 This command extracts the root filesystem into the ``core2-64-sato`` 262 This command extracts the root filesystem into the ``core2-64-sato``
224 directory: $ runqemu-extract-sdk 263 directory:
225 ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 264 ::
226 ~/beaglebone-sato You could now point to the target sysroot at 265
227 ``beablebone-sato``. 266 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
267
268 You could now point to the target sysroot at ``beablebone-sato``.
228 269
229Installed Standard SDK Directory Structure 270Installed Standard SDK Directory Structure
230========================================== 271==========================================
@@ -246,7 +287,7 @@ Within the figure, italicized text is used to indicate replaceable
246portions of the file or directory name. For example, install_dir/version 287portions of the file or directory name. For example, install_dir/version
247is the directory where the SDK is installed. By default, this directory 288is the directory where the SDK is installed. By default, this directory
248is ``/opt/poky/``. And, version represents the specific snapshot of the 289is ``/opt/poky/``. And, version represents the specific snapshot of the
249SDK (e.g. ````). Furthermore, target represents the target architecture 290SDK (e.g. 3.1.2). Furthermore, target represents the target architecture
250(e.g. ``i586``) and host represents the development system's 291(e.g. ``i586``) and host represents the development system's
251architecture (e.g. ``x86_64``). Thus, the complete names of the two 292architecture (e.g. ``x86_64``). Thus, the complete names of the two
252directories within the ``sysroots`` could be ``i586-poky-linux`` and 293directories within the ``sysroots`` could be ``i586-poky-linux`` and
diff --git a/documentation/sdk-manual/sdk-extensible.rst b/documentation/sdk-manual/sdk-extensible.rst
index 5836bd8549..1ad5c46bea 100644
--- a/documentation/sdk-manual/sdk-extensible.rst
+++ b/documentation/sdk-manual/sdk-extensible.rst
@@ -45,14 +45,13 @@ functionality.
45Installing the Extensible SDK 45Installing the Extensible SDK
46============================= 46=============================
47 47
48The first thing you need to do is install the SDK on your `Build 48The first thing you need to do is install the SDK on your :term:`Build
49Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the 49Host` by running the ``*.sh`` installation script.
50``*.sh`` installation script.
51 50
52You can download a tarball installer, which includes the pre-built 51You can download a tarball installer, which includes the pre-built
53toolchain, the ``runqemu`` script, the internal build system, 52toolchain, the ``runqemu`` script, the internal build system,
54``devtool``, and support files from the appropriate 53``devtool``, and support files from the appropriate
55`toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within the Index of 54:yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within the Index of
56Releases. Toolchains are available for several 32-bit and 64-bit 55Releases. Toolchains are available for several 32-bit and 64-bit
57architectures with the ``x86_64`` directories, respectively. The 56architectures with the ``x86_64`` directories, respectively. The
58toolchains the Yocto Project provides are based off the 57toolchains the Yocto Project provides are based off the
@@ -64,17 +63,33 @@ representing the host system appears first in the filename and then is
64immediately followed by a string representing the target architecture. 63immediately followed by a string representing the target architecture.
65An extensible SDK has the string "-ext" as part of the name. Following 64An extensible SDK has the string "-ext" as part of the name. Following
66is the general form: 65is the general form:
67poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh 66::
68Where: host_system is a string representing your development system: 67
69i686 or x86_64. image_type is the image for which the SDK was built: 68 poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
70core-image-sato or core-image-minimal arch is a string representing the 69
71tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2, 70 Where:
72mips64, ppc7400, or cortexa8hf-neon release_version is a string 71 host_system is a string representing your development system:
73representing the release number of the Yocto Project: DISTRO, 72
74DISTRO+snapshot For example, the following SDK installer is for a 64-bit 73 i686 or x86_64.
74
75 image_type is the image for which the SDK was built:
76
77 core-image-sato or core-image-minimal
78
79 arch is a string representing the tuned target architecture:
80
81 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
82
83 release_version is a string representing the release number of the Yocto Project:
84
85 3.1.2, 3.1.2+snapshot
86
87For example, the following SDK installer is for a 64-bit
75development host system and a i586-tuned target architecture based off 88development host system and a i586-tuned target architecture based off
76the SDK for ``core-image-sato`` and using the current DISTRO snapshot: 89the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
77poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh 90::
91
92 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh
78 93
79.. note:: 94.. note::
80 95
@@ -102,28 +117,26 @@ architecture. The example assumes the SDK installer is located in
102 that case, set up the proper permissions in the directory and run the 117 that case, set up the proper permissions in the directory and run the
103 installer again. 118 installer again.
104 119
105$ 120::
106./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh 121
107Poky (Yocto Project Reference Distro) Extensible SDK installer version 122 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
1082.5 123 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
109========================================================================== 124 ==========================================================================
110Enter target directory for SDK (default: ~/poky_sdk): You are about to 125 Enter target directory for SDK (default: ~/poky_sdk):
111install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y 126 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
112Extracting SDK..............done Setting it up... Extracting 127 Extracting SDK..............done
113buildtools... Preparing build system... Parsing recipes: 100% 128 Setting it up...
114\|##################################################################\| 129 Extracting buildtools...
115Time: 0:00:52 Initialising tasks: 100% 130 Preparing build system...
116\|###############################################################\| 131 Parsing recipes: 100% |##################################################################| Time: 0:00:52
117Time: 0:00:00 Checking sstate mirror object availability: 100% 132 Initialising tasks: 100% |###############################################################| Time: 0:00:00
118\|#######################################\| Time: 0:00:00 Loading cache: 133 Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
119100% 134 Loading cache: 100% |####################################################################| Time: 0:00:00
120\|####################################################################\| 135 Initialising tasks: 100% |###############################################################| Time: 0:00:00
121Time: 0:00:00 Initialising tasks: 100% 136 done
122\|###############################################################\| 137 SDK has been successfully set up and is ready to be used.
123Time: 0:00:00 done SDK has been successfully set up and is ready to be 138 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
124used. Each time you wish to use the SDK in a new shell session, you need 139 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
125to source the environment setup script e.g. $ .
126/home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
127 140
128.. _sdk-running-the-extensible-sdk-environment-setup-script: 141.. _sdk-running-the-extensible-sdk-environment-setup-script:
129 142
@@ -142,10 +155,14 @@ begin with the string "``environment-setup``" and include as part of
142their name the tuned target architecture. As an example, the following 155their name the tuned target architecture. As an example, the following
143commands set the working directory to where the SDK was installed and 156commands set the working directory to where the SDK was installed and
144then source the environment setup script. In this example, the setup 157then source the environment setup script. In this example, the setup
145script is for an IA-based target machine using i586 tuning: $ cd 158script is for an IA-based target machine using i586 tuning:
146/home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux 159::
147SDK environment now set up; additionally you may now run devtool to 160
148perform development tasks. Run devtool --help for further details. 161 $ cd /home/scottrif/poky_sdk
162 $ source environment-setup-core2-64-poky-linux
163 SDK environment now set up; additionally you may now run devtool to perform development tasks.
164 Run devtool --help for further details.
165
149Running the setup script defines many environment variables needed in 166Running the setup script defines many environment variables needed in
150order to use the SDK (e.g. ``PATH``, 167order to use the SDK (e.g. ``PATH``,
151:term:`CC`, 168:term:`CC`,
@@ -172,7 +189,7 @@ system.
172 part of an image built using the build system. 189 part of an image built using the build system.
173 190
174The ``devtool`` command line is organized similarly to 191The ``devtool`` command line is organized similarly to
175`Git <&YOCTO_DOCS_OM_URL;#git>`__ in that it has a number of 192:ref:`overview-manual/overview-manual-development-environment:git` in that it has a number of
176sub-commands for each function. You can run ``devtool --help`` to see 193sub-commands for each function. You can run ``devtool --help`` to see
177all the commands. 194all the commands.
178 195
@@ -188,12 +205,12 @@ all the commands.
188Three ``devtool`` subcommands exist that provide entry-points into 205Three ``devtool`` subcommands exist that provide entry-points into
189development: 206development:
190 207
191- *``devtool add``*: Assists in adding new software to be built. 208- *devtool add*: Assists in adding new software to be built.
192 209
193- *``devtool modify``*: Sets up an environment to enable you to modify 210- *devtool modify*: Sets up an environment to enable you to modify
194 the source of an existing component. 211 the source of an existing component.
195 212
196- *``devtool upgrade``*: Updates an existing recipe so that you can 213- *devtool upgrade*: Updates an existing recipe so that you can
197 build it for an updated set of source files. 214 build it for an updated set of source files.
198 215
199As with the build system, "recipes" represent software packages within 216As with the build system, "recipes" represent software packages within
@@ -248,8 +265,12 @@ command:
248 to be extracted. In this situation, the source code is extracted 265 to be extracted. In this situation, the source code is extracted
249 to the default workspace - you do not want the files in some 266 to the default workspace - you do not want the files in some
250 specific location outside of the workspace. Thus, everything you 267 specific location outside of the workspace. Thus, everything you
251 need will be located in the workspace: $ devtool add recipe 268 need will be located in the workspace:
252 fetchuri With this command, ``devtool`` extracts the upstream 269 ::
270
271 $ devtool add recipe fetchuri
272
273 With this command, ``devtool`` extracts the upstream
253 source files into a local Git repository within the ``sources`` 274 source files into a local Git repository within the ``sources``
254 folder. The command then creates a recipe named recipe and a 275 folder. The command then creates a recipe named recipe and a
255 corresponding append file in the workspace. If you do not provide 276 corresponding append file in the workspace. If you do not provide
@@ -269,7 +290,12 @@ command:
269 Furthermore, the first positional argument srctree in this case 290 Furthermore, the first positional argument srctree in this case
270 identifies where the ``devtool add`` command will locate the 291 identifies where the ``devtool add`` command will locate the
271 extracted code outside of the workspace. You need to specify an 292 extracted code outside of the workspace. You need to specify an
272 empty directory: $ devtool add recipe srctree fetchuri In summary, 293 empty directory:
294 ::
295
296 $ devtool add recipe srctree fetchuri
297
298 In summary,
273 the source code is pulled from fetchuri and extracted into the 299 the source code is pulled from fetchuri and extracted into the
274 location defined by srctree as a local Git repository. 300 location defined by srctree as a local Git repository.
275 301
@@ -281,7 +307,11 @@ command:
281 ``devtool`` workspace. 307 ``devtool`` workspace.
282 308
283 The following command provides a new recipe name and identifies 309 The following command provides a new recipe name and identifies
284 the existing source tree location: $ devtool add recipe srctree 310 the existing source tree location:
311 ::
312
313 $ devtool add recipe srctree
314
285 The command examines the source code and creates a recipe named 315 The command examines the source code and creates a recipe named
286 recipe for the code and places the recipe into the workspace. 316 recipe for the code and places the recipe into the workspace.
287 317
@@ -294,7 +324,12 @@ command:
294 324
2952. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the 3252. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
296 editor as defined by the ``$EDITOR`` environment variable and modify 326 editor as defined by the ``$EDITOR`` environment variable and modify
297 the file: $ devtool edit-recipe recipe From within the editor, you 327 the file:
328 ::
329
330 $ devtool edit-recipe recipe
331
332 From within the editor, you
298 can make modifications to the recipe that take affect when you build 333 can make modifications to the recipe that take affect when you build
299 it later. 334 it later.
300 335
@@ -302,13 +337,18 @@ command:
302 depends on what you are going to do with the new code. 337 depends on what you are going to do with the new code.
303 338
304 If you need to eventually move the build output to the target 339 If you need to eventually move the build output to the target
305 hardware, use the following ``devtool`` command: $ devtool build 340 hardware, use the following ``devtool`` command:
306 recipe 341 :;
342
343 $ devtool build recipe
307 344
308 On the other hand, if you want an image to contain the recipe's 345 On the other hand, if you want an image to contain the recipe's
309 packages from the workspace for immediate deployment onto a device 346 packages from the workspace for immediate deployment onto a device
310 (e.g. for testing purposes), you can use the ``devtool build-image`` 347 (e.g. for testing purposes), you can use the ``devtool build-image``
311 command: $ devtool build-image image 348 command:
349 ::
350
351 $ devtool build-image image
312 352
3134. *Deploy the Build Output*: When you use the ``devtool build`` command 3534. *Deploy the Build Output*: When you use the ``devtool build`` command
314 to build out your recipe, you probably want to see if the resulting 354 to build out your recipe, you probably want to see if the resulting
@@ -336,7 +376,10 @@ command:
336 creates any patches corresponding to commits in the local Git 376 creates any patches corresponding to commits in the local Git
337 repository, moves the new recipe to a more permanent layer, and then 377 repository, moves the new recipe to a more permanent layer, and then
338 resets the recipe so that the recipe is built normally rather than 378 resets the recipe so that the recipe is built normally rather than
339 from the workspace. $ devtool finish recipe layer 379 from the workspace.
380 ::
381
382 $ devtool finish recipe layer
340 383
341 .. note:: 384 .. note::
342 385
@@ -401,7 +444,12 @@ command:
401 outside the workspace (i.e. ``meta-``\ layername). 444 outside the workspace (i.e. ``meta-``\ layername).
402 445
403 The following command identifies the recipe and, by default, 446 The following command identifies the recipe and, by default,
404 extracts the source files: $ devtool modify recipe Once 447 extracts the source files:
448 ::
449
450 $ devtool modify recipe
451
452 Once
405 ``devtool``\ locates the recipe, ``devtool`` uses the recipe's 453 ``devtool``\ locates the recipe, ``devtool`` uses the recipe's
406 :term:`SRC_URI` statements to 454 :term:`SRC_URI` statements to
407 locate the source code and any local patch files from other 455 locate the source code and any local patch files from other
@@ -435,7 +483,10 @@ command:
435 The following command tells ``devtool`` the recipe with which to 483 The following command tells ``devtool`` the recipe with which to
436 work and, in this case, identifies a local area for the extracted 484 work and, in this case, identifies a local area for the extracted
437 source files that exists outside of the default ``devtool`` 485 source files that exists outside of the default ``devtool``
438 workspace: $ devtool modify recipe srctree 486 workspace:
487 ::
488
489 $ devtool modify recipe srctree
439 490
440 .. note:: 491 .. note::
441 492
@@ -466,7 +517,10 @@ command:
466 The following command tells ``devtool`` the recipe with which to 517 The following command tells ``devtool`` the recipe with which to
467 work, uses the "-n" option to indicate source does not need to be 518 work, uses the "-n" option to indicate source does not need to be
468 extracted, and uses srctree to point to the previously extracted 519 extracted, and uses srctree to point to the previously extracted
469 source files: $ devtool modify -n recipe srctree 520 source files:
521 ::
522
523 $ devtool modify -n recipe srctree
470 524
471 If an ``oe-local-files`` subdirectory happens to exist and it 525 If an ``oe-local-files`` subdirectory happens to exist and it
472 contains non-patch files, the files are used. However, if the 526 contains non-patch files, the files are used. However, if the
@@ -487,8 +541,10 @@ command:
487 depends on what you are going to do with the new code. 541 depends on what you are going to do with the new code.
488 542
489 If you need to eventually move the build output to the target 543 If you need to eventually move the build output to the target
490 hardware, use the following ``devtool`` command: $ devtool build 544 hardware, use the following ``devtool`` command:
491 recipe 545 ::
546
547 $ devtool build recipe
492 548
493 On the other hand, if you want an image to contain the recipe's 549 On the other hand, if you want an image to contain the recipe's
494 packages from the workspace for immediate deployment onto a device 550 packages from the workspace for immediate deployment onto a device
@@ -509,8 +565,12 @@ command:
509 development machine. 565 development machine.
510 566
511 You can deploy your build output to that target hardware by using the 567 You can deploy your build output to that target hardware by using the
512 ``devtool deploy-target`` command: $ devtool deploy-target recipe 568 ``devtool deploy-target`` command:
513 target The target is a live target machine running as an SSH server. 569 ::
570
571 $ devtool deploy-target recipe target
572
573 The target is a live target machine running as an SSH server.
514 574
515 You can, of course, use other methods to deploy the image you built 575 You can, of course, use other methods to deploy the image you built
516 using the ``devtool build-image`` command to actual hardware. 576 using the ``devtool build-image`` command to actual hardware.
@@ -522,8 +582,10 @@ command:
522 repository, updates the recipe to point to them (or creates a 582 repository, updates the recipe to point to them (or creates a
523 ``.bbappend`` file to do so, depending on the specified destination 583 ``.bbappend`` file to do so, depending on the specified destination
524 layer), and then resets the recipe so that the recipe is built 584 layer), and then resets the recipe so that the recipe is built
525 normally rather than from the workspace. $ devtool finish recipe 585 normally rather than from the workspace.
526 layer 586 ::
587
588 $ devtool finish recipe layer
527 589
528 .. note:: 590 .. note::
529 591
@@ -600,8 +662,12 @@ The following diagram shows the common development flow used with the
600 A common situation is where third-party software has undergone a 662 A common situation is where third-party software has undergone a
601 revision so that it has been upgraded. The recipe you have access to 663 revision so that it has been upgraded. The recipe you have access to
602 is likely in your own layer. Thus, you need to upgrade the recipe to 664 is likely in your own layer. Thus, you need to upgrade the recipe to
603 use the newer version of the software: $ devtool upgrade -V version 665 use the newer version of the software:
604 recipe By default, the ``devtool upgrade`` command extracts source 666 ::
667
668 $ devtool upgrade -V version recipe
669
670 By default, the ``devtool upgrade`` command extracts source
605 code into the ``sources`` directory in the 671 code into the ``sources`` directory in the
606 :ref:`devtool-the-workspace-layer-structure`. 672 :ref:`devtool-the-workspace-layer-structure`.
607 If you want the code extracted to any other location, you need to 673 If you want the code extracted to any other location, you need to
@@ -648,13 +714,18 @@ The following diagram shows the common development flow used with the
648 depends on what you are going to do with the new code. 714 depends on what you are going to do with the new code.
649 715
650 If you need to eventually move the build output to the target 716 If you need to eventually move the build output to the target
651 hardware, use the following ``devtool`` command: $ devtool build 717 hardware, use the following ``devtool`` command:
652 recipe 718 ::
719
720 $ devtool build recipe
653 721
654 On the other hand, if you want an image to contain the recipe's 722 On the other hand, if you want an image to contain the recipe's
655 packages from the workspace for immediate deployment onto a device 723 packages from the workspace for immediate deployment onto a device
656 (e.g. for testing purposes), you can use the ``devtool build-image`` 724 (e.g. for testing purposes), you can use the ``devtool build-image``
657 command: $ devtool build-image image 725 command:
726 ::
727
728 $ devtool build-image image
658 729
6594. *Deploy the Build Output*: When you use the ``devtool build`` command 7304. *Deploy the Build Output*: When you use the ``devtool build`` command
660 or ``bitbake`` to build your recipe, you probably want to see if the 731 or ``bitbake`` to build your recipe, you probably want to see if the
@@ -690,8 +761,10 @@ The following diagram shows the common development flow used with the
690 761
691 If you specify a destination layer that is the same as the original 762 If you specify a destination layer that is the same as the original
692 source, then the old version of the recipe and associated files are 763 source, then the old version of the recipe and associated files are
693 removed prior to adding the new version. $ devtool finish recipe 764 removed prior to adding the new version.
694 layer 765 ::
766
767 $ devtool finish recipe layer
695 768
696 .. note:: 769 .. note::
697 770
@@ -770,8 +843,12 @@ name and version, just the name, or just the version as part of the
770command line. 843command line.
771 844
772Sometimes the name or version determined from the source tree might be 845Sometimes the name or version determined from the source tree might be
773incorrect. For such a case, you must reset the recipe: $ devtool reset 846incorrect. For such a case, you must reset the recipe:
774-n recipename After running the ``devtool reset`` command, you need to 847::
848
849 $ devtool reset -n recipename
850
851After running the ``devtool reset`` command, you need to
775run ``devtool add`` again and provide the name or the version. 852run ``devtool add`` again and provide the name or the version.
776 853
777.. _sdk-dependency-detection-and-mapping: 854.. _sdk-dependency-detection-and-mapping:
@@ -793,8 +870,10 @@ the ``DEPENDS`` variable in the original recipe to include the new
793recipe. 870recipe.
794 871
795If you need to add runtime dependencies, you can do so by adding the 872If you need to add runtime dependencies, you can do so by adding the
796following to your recipe: RDEPENDS_${PN} += "dependency1 dependency2 873following to your recipe:
797..." 874::
875
876 RDEPENDS_${PN} += "dependency1 dependency2 ..."
798 877
799.. note:: 878.. note::
800 879
@@ -881,7 +960,11 @@ mind:
881 :term:`EXTRA_OEMAKE` or 960 :term:`EXTRA_OEMAKE` or
882 :term:`PACKAGECONFIG_CONFARGS` 961 :term:`PACKAGECONFIG_CONFARGS`
883 within the recipe. Here is an example using ``EXTRA_OEMAKE``: 962 within the recipe. Here is an example using ``EXTRA_OEMAKE``:
884 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example, 963 ::
964
965 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
966
967 In the above example,
885 single quotes are used around the variable settings as the values are 968 single quotes are used around the variable settings as the values are
886 likely to contain spaces because required default options are passed 969 likely to contain spaces because required default options are passed
887 to the compiler. 970 to the compiler.
@@ -903,8 +986,8 @@ mind:
903Adding Native Tools 986Adding Native Tools
904------------------- 987-------------------
905 988
906Often, you need to build additional tools that run on the `build 989Often, you need to build additional tools that run on the :term:`Build
907host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ as opposed to 990Host` as opposed to
908the target. You should indicate this requirement by using one of the 991the target. You should indicate this requirement by using one of the
909following methods when you run ``devtool add``: 992following methods when you run ``devtool add``:
910 993
@@ -935,8 +1018,12 @@ You can use the ``devtool add`` command two different ways to add
935Node.js modules: 1) Through ``npm`` and, 2) from a repository or local 1018Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
936source. 1019source.
937 1020
938Use the following form to add Node.js modules through ``npm``: $ devtool 1021Use the following form to add Node.js modules through ``npm``:
939add "npm://registry.npmjs.org;name=forever;version=0.15.1" The name and 1022::
1023
1024 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
1025
1026The name and
940version parameters are mandatory. Lockdown and shrinkwrap files are 1027version parameters are mandatory. Lockdown and shrinkwrap files are
941generated and pointed to by the recipe in order to freeze the version 1028generated and pointed to by the recipe in order to freeze the version
942that is fetched for the dependencies according to the first time. This 1029that is fetched for the dependencies according to the first time. This
@@ -956,8 +1043,12 @@ these behaviors ensure the reproducibility and integrity of the build.
956 1043
957As mentioned earlier, you can also add Node.js modules directly from a 1044As mentioned earlier, you can also add Node.js modules directly from a
958repository or local source tree. To add modules this way, use 1045repository or local source tree. To add modules this way, use
959``devtool add`` in the following form: $ devtool add 1046``devtool add`` in the following form:
960https://github.com/diversario/node-ssdp In this example, ``devtool`` 1047::
1048
1049 $ devtool add https://github.com/diversario/node-ssdp
1050
1051In this example, ``devtool``
961fetches the specified Git repository, detects the code as Node.js code, 1052fetches the specified Git repository, detects the code as Node.js code,
962fetches dependencies using ``npm``, and sets 1053fetches dependencies using ``npm``, and sets
963:term:`SRC_URI` accordingly. 1054:term:`SRC_URI` accordingly.
@@ -984,7 +1075,7 @@ build progresses as follows:
984 1075
985For recipes in the workspace, fetching and unpacking is disabled as the 1076For recipes in the workspace, fetching and unpacking is disabled as the
986source tree has already been prepared and is persistent. Each of these 1077source tree has already been prepared and is persistent. Each of these
987build steps is defined as a function (task), usually with a "do_" prefix 1078build steps is defined as a function (task), usually with a "do\_" prefix
988(e.g. :ref:`ref-tasks-fetch`, 1079(e.g. :ref:`ref-tasks-fetch`,
989:ref:`ref-tasks-unpack`, and so 1080:ref:`ref-tasks-unpack`, and so
990forth). These functions are typically shell scripts but can instead be 1081forth). These functions are typically shell scripts but can instead be
@@ -1069,8 +1160,8 @@ reference.
1069Sharing Files Between Recipes 1160Sharing Files Between Recipes
1070----------------------------- 1161-----------------------------
1071 1162
1072Recipes often need to use files provided by other recipes on the `build 1163Recipes often need to use files provided by other recipes on the
1073host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. For example, 1164:term:`Build Host`. For example,
1074an application linking to a common library needs access to the library 1165an application linking to a common library needs access to the library
1075itself and its associated headers. The way this access is accomplished 1166itself and its associated headers. The way this access is accomplished
1076within the extensible SDK is through the sysroot. One sysroot exists per 1167within the extensible SDK is through the sysroot. One sysroot exists per
@@ -1142,11 +1233,19 @@ need to restore the original files that existed prior to running the
1142``devtool deploy-target`` command. Because the ``devtool deploy-target`` 1233``devtool deploy-target`` command. Because the ``devtool deploy-target``
1143command backs up any files it overwrites, you can use the 1234command backs up any files it overwrites, you can use the
1144``devtool undeploy-target`` command to restore those files and remove 1235``devtool undeploy-target`` command to restore those files and remove
1145any other files the recipe deployed. Consider the following example: $ 1236any other files the recipe deployed. Consider the following example:
1146devtool undeploy-target lighttpd root@192.168.7.2 If you have deployed 1237::
1238
1239 $ devtool undeploy-target lighttpd root@192.168.7.2
1240
1241If you have deployed
1147multiple applications, you can remove them all using the "-a" option 1242multiple applications, you can remove them all using the "-a" option
1148thus restoring the target device to its original state: $ devtool 1243thus restoring the target device to its original state:
1149undeploy-target -a root@192.168.7.2 Information about files deployed to 1244::
1245
1246 $ devtool undeploy-target -a root@192.168.7.2
1247
1248Information about files deployed to
1150the target as well as any backed up files are stored on the target 1249the target as well as any backed up files are stored on the target
1151itself. This storage, of course, requires some additional space on the 1250itself. This storage, of course, requires some additional space on the
1152target machine. 1251target machine.
@@ -1175,14 +1274,26 @@ populated on-demand. Sometimes you must explicitly install extra items
1175into the SDK. If you need these extra items, you can first search for 1274into the SDK. If you need these extra items, you can first search for
1176the items using the ``devtool search`` command. For example, suppose you 1275the items using the ``devtool search`` command. For example, suppose you
1177need to link to libGL but you are not sure which recipe provides libGL. 1276need to link to libGL but you are not sure which recipe provides libGL.
1178You can use the following command to find out: $ devtool search libGL 1277You can use the following command to find out:
1179mesa A free implementation of the OpenGL API Once you know the recipe 1278::
1180(i.e. ``mesa`` in this example), you can install it: $ devtool 1279
1181sdk-install mesa By default, the ``devtool sdk-install`` command assumes 1280 $ devtool search libGL mesa
1281
1282A free implementation of the OpenGL API Once you know the recipe
1283(i.e. ``mesa`` in this example), you can install it:
1284::
1285
1286 $ devtool sdk-install mesa
1287
1288By default, the ``devtool sdk-install`` command assumes
1182the item is available in pre-built form from your SDK provider. If the 1289the item is available in pre-built form from your SDK provider. If the
1183item is not available and it is acceptable to build the item from 1290item is not available and it is acceptable to build the item from
1184source, you can add the "-s" option as follows: $ devtool sdk-install -s 1291source, you can add the "-s" option as follows:
1185mesa It is important to remember that building the item from source 1292::
1293
1294 $ devtool sdk-install -s mesa
1295
1296It is important to remember that building the item from source
1186takes significantly longer than installing the pre-built artifact. Also, 1297takes significantly longer than installing the pre-built artifact. Also,
1187if no recipe exists for the item you want to add to the SDK, you must 1298if no recipe exists for the item you want to add to the SDK, you must
1188instead add the item using the ``devtool add`` command. 1299instead add the item using the ``devtool add`` command.
@@ -1196,8 +1307,12 @@ If you are working with an installed extensible SDK that gets
1196occasionally updated (e.g. a third-party SDK), then you will need to 1307occasionally updated (e.g. a third-party SDK), then you will need to
1197manually "pull down" the updates into the installed SDK. 1308manually "pull down" the updates into the installed SDK.
1198 1309
1199To update your installed SDK, use ``devtool`` as follows: $ devtool 1310To update your installed SDK, use ``devtool`` as follows:
1200sdk-update The previous command assumes your SDK provider has set the 1311::
1312
1313 $ devtool sdk-update
1314
1315The previous command assumes your SDK provider has set the
1201default update URL for you through the 1316default update URL for you through the
1202:term:`SDK_UPDATE_URL` 1317:term:`SDK_UPDATE_URL`
1203variable as described in the "`Providing Updates to the Extensible SDK 1318variable as described in the "`Providing Updates to the Extensible SDK
diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst
index 215889f390..2e01cf1365 100644
--- a/documentation/sdk-manual/sdk-intro.rst
+++ b/documentation/sdk-manual/sdk-intro.rst
@@ -6,8 +6,8 @@ Introduction
6 6
7.. _sdk-manual-intro: 7.. _sdk-manual-intro:
8 8
9Introduction 9eSDK Introduction
10============ 10=================
11 11
12Welcome to the Yocto Project Application Development and the Extensible 12Welcome to the Yocto Project Application Development and the Extensible
13Software Development Kit (eSDK) manual. This manual provides information 13Software Development Kit (eSDK) manual. This manual provides information
@@ -109,18 +109,23 @@ when considering which to build:
109:term:`SDK_EXT_TYPE` is "full" 109:term:`SDK_EXT_TYPE` is "full"
110or 110or
111:term:`SDK_INCLUDE_TOOLCHAIN` 111:term:`SDK_INCLUDE_TOOLCHAIN`
112is "1", which is the default. \*\* Sysroot is managed through the use of 112is "1", which is the default.
113
114\*\* Sysroot is managed through the use of
113``devtool``. Thus, it is less likely that you will corrupt your SDK 115``devtool``. Thus, it is less likely that you will corrupt your SDK
114sysroot when you try to add additional libraries. \**\* You can add 116sysroot when you try to add additional libraries.
117
118\*\*\* You can add
115runtime package management to the standard SDK but it is not supported 119runtime package management to the standard SDK but it is not supported
116by default. \***\* You must build and make the shared state available to 120by default.
121
122\*\*\*\* You must build and make the shared state available to
117extensible SDK users for "packages" you want to enable users to install. 123extensible SDK users for "packages" you want to enable users to install.
118 124
119The Cross-Development Toolchain 125The Cross-Development Toolchain
120------------------------------- 126-------------------------------
121 127
122The `Cross-Development 128The :term:`Cross-Development Toolchain` consists
123Toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__ consists
124of a cross-compiler, cross-linker, and cross-debugger that are used to 129of a cross-compiler, cross-linker, and cross-debugger that are used to
125develop user-space applications for targeted hardware. Additionally, for 130develop user-space applications for targeted hardware. Additionally, for
126an extensible SDK, the toolchain also has built-in ``devtool`` 131an extensible SDK, the toolchain also has built-in ``devtool``
@@ -190,7 +195,7 @@ You just need to follow these general steps:
190 root filesystem images. 195 root filesystem images.
191 196
192 If you are going to develop your application on hardware, go to the 197 If you are going to develop your application on hardware, go to the
193 ```machines`` <&YOCTO_MACHINES_DL_URL;>`__ download area and choose a 198 :yocto_dl:`machines <releases/yocto/yocto-3.1.2/machines/>` download area and choose a
194 target machine area from which to download the kernel image and root 199 target machine area from which to download the kernel image and root
195 filesystem. This download area could have several files in it that 200 filesystem. This download area could have several files in it that
196 support development using actual hardware. For example, the area 201 support development using actual hardware. For example, the area
@@ -200,7 +205,7 @@ You just need to follow these general steps:
200 205
201 If you are going to develop your application and then run and test it 206 If you are going to develop your application and then run and test it
202 using the QEMU emulator, go to the 207 using the QEMU emulator, go to the
203 ```machines/qemu`` <&YOCTO_QEMU_DL_URL;>`__ download area. From this 208 :yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu>` download area. From this
204 area, go down into the directory for your target architecture (e.g. 209 area, go down into the directory for your target architecture (e.g.
205 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the 210 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
206 kernel, root filesystem, and any other files you need for your 211 kernel, root filesystem, and any other files you need for your
@@ -217,8 +222,7 @@ You just need to follow these general steps:
217 tools to develop your application. If you need to separately install 222 tools to develop your application. If you need to separately install
218 and use the QEMU emulator, you can go to `QEMU Home 223 and use the QEMU emulator, you can go to `QEMU Home
219 Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about 224 Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about
220 the emulator. See the "`Using the Quick EMUlator 225 the emulator. See the ":doc:`../dev-manual/dev-manual-qemu`" chapter in the
221 (QEMU) <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__" chapter in the
222 Yocto Project Development Tasks Manual for information on using QEMU 226 Yocto Project Development Tasks Manual for information on using QEMU
223 within the Yocto Project. 227 within the Yocto Project.
224 228
diff --git a/documentation/sdk-manual/sdk-using.rst b/documentation/sdk-manual/sdk-using.rst
index b240f9174a..cd57f07eeb 100644
--- a/documentation/sdk-manual/sdk-using.rst
+++ b/documentation/sdk-manual/sdk-using.rst
@@ -42,13 +42,12 @@ Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
42Installing the SDK 42Installing the SDK
43================== 43==================
44 44
45The first thing you need to do is install the SDK on your `Build 45The first thing you need to do is install the SDK on your :term:`Build
46Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the 46Host` by running the ``*.sh`` installation script.
47``*.sh`` installation script.
48 47
49You can download a tarball installer, which includes the pre-built 48You can download a tarball installer, which includes the pre-built
50toolchain, the ``runqemu`` script, and support files from the 49toolchain, the ``runqemu`` script, and support files from the
51appropriate `toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within 50appropriate :yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within
52the Index of Releases. Toolchains are available for several 32-bit and 51the Index of Releases. Toolchains are available for several 32-bit and
5364-bit architectures with the ``x86_64`` directories, respectively. The 5264-bit architectures with the ``x86_64`` directories, respectively. The
54toolchains the Yocto Project provides are based off the 53toolchains the Yocto Project provides are based off the
@@ -58,17 +57,33 @@ libraries appropriate for developing against that image.
58The names of the tarball installer scripts are such that a string 57The names of the tarball installer scripts are such that a string
59representing the host system appears first in the filename and then is 58representing the host system appears first in the filename and then is
60immediately followed by a string representing the target architecture. 59immediately followed by a string representing the target architecture.
61poky-glibc-host_system-image_type-arch-toolchain-release_version.sh 60::
62Where: host_system is a string representing your development system: 61
63i686 or x86_64. image_type is the image for which the SDK was built: 62 poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
64core-image-minimal or core-image-sato. arch is a string representing the 63
65tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2, 64 Where:
66mips64, ppc7400, or cortexa8hf-neon. release_version is a string 65 host_system is a string representing your development system:
67representing the release number of the Yocto Project: DISTRO, 66
68DISTRO+snapshot For example, the following SDK installer is for a 64-bit 67 i686 or x86_64.
68
69 image_type is the image for which the SDK was built:
70
71 core-image-minimal or core-image-sato.
72
73 arch is a string representing the tuned target architecture:
74
75 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
76
77 release_version is a string representing the release number of the Yocto Project:
78
79 3.1.2, 3.1.2+snapshot
80
81For example, the following SDK installer is for a 64-bit
69development host system and a i586-tuned target architecture based off 82development host system and a i586-tuned target architecture based off
70the SDK for ``core-image-sato`` and using the current DISTRO snapshot: 83the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
71poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh 84::
85
86 poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
72 87
73.. note:: 88.. note::
74 89
@@ -96,16 +111,18 @@ architecture. The example assumes the SDK installer is located in
96 that case, set up the proper permissions in the directory and run the 111 that case, set up the proper permissions in the directory and run the
97 installer again. 112 installer again.
98 113
99$ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh 114::
100Poky (Yocto Project Reference Distro) SDK installer version DISTRO 115
101=============================================================== Enter 116 $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-3.1.2.sh
102target directory for SDK (default: /opt/poky/DISTRO): You are about to 117 Poky (Yocto Project Reference Distro) SDK installer version 3.1.2
103install the SDK to "/opt/poky/DISTRO". Proceed [Y/n]? Y Extracting 118 ===============================================================
104SDK........................................ 119 Enter target directory for SDK (default: /opt/poky/3.1.2):
105..............................done Setting it up...done SDK has been 120 You are about to install the SDK to "/opt/poky/3.1.2". Proceed [Y/n]? Y
106successfully set up and is ready to be used. Each time you wish to use 121 Extracting SDK........................................ ..............................done
107the SDK in a new shell session, you need to source the environment setup 122 Setting it up...done
108script e.g. $ . /opt/poky/DISTRO/environment-setup-i586-poky-linux 123 SDK has been successfully set up and is ready to be used.
124 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
125 $ . /opt/poky/3.1.2/environment-setup-i586-poky-linux
109 126
110Again, reference the "`Installed Standard SDK Directory 127Again, reference the "`Installed Standard SDK Directory
111Structure <#sdk-installed-standard-sdk-directory-structure>`__" section 128Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
@@ -120,7 +137,7 @@ Running the SDK Environment Setup Script
120Once you have the SDK installed, you must run the SDK environment setup 137Once you have the SDK installed, you must run the SDK environment setup
121script before you can actually use the SDK. This setup script resides in 138script before you can actually use the SDK. This setup script resides in
122the directory you chose when you installed the SDK, which is either the 139the directory you chose when you installed the SDK, which is either the
123default ``/opt/poky/DISTRO`` directory or the directory you chose during 140default ``/opt/poky/3.1.2`` directory or the directory you chose during
124installation. 141installation.
125 142
126Before running the script, be sure it is the one that matches the 143Before running the script, be sure it is the one that matches the
@@ -129,8 +146,12 @@ begin with the string "``environment-setup``" and include as part of
129their name the tuned target architecture. As an example, the following 146their name the tuned target architecture. As an example, the following
130commands set the working directory to where the SDK was installed and 147commands set the working directory to where the SDK was installed and
131then source the environment setup script. In this example, the setup 148then source the environment setup script. In this example, the setup
132script is for an IA-based target machine using i586 tuning: $ source 149script is for an IA-based target machine using i586 tuning:
133/opt/poky/DISTRO/environment-setup-i586-poky-linux When you run the 150::
151
152 $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
153
154When you run the
134setup script, the same environment variables are defined as are when you 155setup script, the same environment variables are defined as are when you
135run the setup script for an extensible SDK. See the "`Running the 156run the setup script for an extensible SDK. See the "`Running the
136Extensible SDK Environment Setup 157Extensible SDK Environment Setup
diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst
index df216175c9..2c20a1ec57 100644
--- a/documentation/sdk-manual/sdk-working-projects.rst
+++ b/documentation/sdk-manual/sdk-working-projects.rst
@@ -10,8 +10,7 @@ projects.
10Autotools-Based Projects 10Autotools-Based Projects
11======================== 11========================
12 12
13Once you have a suitable `cross-development 13Once you have a suitable :ref:`sdk-manual/sdk-intro:the cross-development toolchain`
14toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__
15installed, it is very easy to develop a project using the `GNU 14installed, it is very easy to develop a project using the `GNU
16Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__ 15Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
17workflow, which is outside of the :term:`OpenEmbedded Build System`. 16workflow, which is outside of the :term:`OpenEmbedded Build System`.
@@ -33,24 +32,51 @@ project:
33 32
341. *Create a Working Directory and Populate It:* Create a clean 331. *Create a Working Directory and Populate It:* Create a clean
35 directory for your project and then make that directory your working 34 directory for your project and then make that directory your working
36 location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After 35 location.
37 setting up the directory, populate it with files needed for the flow. 36 ::
37
38 $ mkdir $HOME/helloworld
39 $ cd $HOME/helloworld
40
41 After setting up the directory, populate it with files needed for the flow.
38 You need a project source file, a file to help with configuration, 42 You need a project source file, a file to help with configuration,
39 and a file to help create the Makefile, and a README file: 43 and a file to help create the Makefile, and a README file:
40 ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``, 44 ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
41 respectively. 45 respectively.
42 46
43 Use the following command to create an empty README file, which is 47 Use the following command to create an empty README file, which is
44 required by GNU Coding Standards: $ touch README Create the remaining 48 required by GNU Coding Standards:
49 ::
50
51 $ touch README
52
53 Create the remaining
45 three files as follows: 54 three files as follows:
46 55
47 - *``hello.c``:* #include <stdio.h> main() { printf("Hello 56 - ``hello.c``:
48 World!\n"); } 57 ::
58
59 #include <stdio.h>
49 60
50 - *``configure.ac``:* AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign]) 61 main()
51 AC_PROG_CC AC_CONFIG_FILES(Makefile) AC_OUTPUT 62 {
63 printf("Hello World!\n");
64 }
52 65
53 - *``Makefile.am``:* bin_PROGRAMS = hello hello_SOURCES = hello.c 66 - ``configure.ac``:
67 ::
68
69 AC_INIT(hello,0.1)
70 AM_INIT_AUTOMAKE([foreign])
71 AC_PROG_CC
72 AC_CONFIG_FILES(Makefile)
73 AC_OUTPUT
74
75 - ``Makefile.am``:
76 ::
77
78 bin_PROGRAMS = hello
79 hello_SOURCES = hello.c
54 80
552. *Source the Cross-Toolchain Environment Setup File:* As described 812. *Source the Cross-Toolchain Environment Setup File:* As described
56 earlier in the manual, installing the cross-toolchain creates a 82 earlier in the manual, installing the cross-toolchain creates a
@@ -60,12 +86,19 @@ project:
60 the string "environment-setup" and contains the machine architecture, 86 the string "environment-setup" and contains the machine architecture,
61 which is followed by the string "poky-linux". For this example, the 87 which is followed by the string "poky-linux". For this example, the
62 command sources a script from the default SDK installation directory 88 command sources a script from the default SDK installation directory
63 that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto 89 that uses the 32-bit Intel x86 Architecture and the 3.1.2 Yocto
64 Project release: $ source 90 Project release:
65 /opt/poky/DISTRO/environment-setup-i586-poky-linux 91 ::
92
93 $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
66 94
673. *Create the ``configure`` Script:* Use the ``autoreconf`` command to 953. *Create the configure Script:* Use the ``autoreconf`` command to
68 generate the ``configure`` script. $ autoreconf The ``autoreconf`` 96 generate the ``configure`` script.
97 ::
98
99 $ autoreconf
100
101 The ``autoreconf``
69 tool takes care of running the other Autotools such as ``aclocal``, 102 tool takes care of running the other Autotools such as ``aclocal``,
70 ``autoconf``, and ``automake``. 103 ``autoconf``, and ``automake``.
71 104
@@ -83,7 +116,12 @@ project:
83 the cross-compiler. The 116 the cross-compiler. The
84 :term:`CONFIGURE_FLAGS` 117 :term:`CONFIGURE_FLAGS`
85 environment variable provides the minimal arguments for GNU 118 environment variable provides the minimal arguments for GNU
86 configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based 119 configure:
120 ::
121
122 $ ./configure ${CONFIGURE_FLAGS}
123
124 For an Autotools-based
87 project, you can use the cross-toolchain by just passing the 125 project, you can use the cross-toolchain by just passing the
88 appropriate host option to ``configure.sh``. The host option you use 126 appropriate host option to ``configure.sh``. The host option you use
89 is derived from the name of the environment setup script found in the 127 is derived from the name of the environment setup script found in the
@@ -92,12 +130,17 @@ project:
92 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the 130 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
93 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the 131 script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
94 following command works to update your project and rebuild it using 132 following command works to update your project and rebuild it using
95 the appropriate cross-toolchain tools: $ ./configure 133 the appropriate cross-toolchain tools:
96 --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir 134 ::
135
136 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
97 137
985. *Make and Install the Project:* These two commands generate and 1385. *Make and Install the Project:* These two commands generate and
99 install the project into the destination directory: $ make $ make 139 install the project into the destination directory:
100 install DESTDIR=./tmp 140 ::
141
142 $ make
143 $ make install DESTDIR=./tmp
101 144
102 .. note:: 145 .. note::
103 146
@@ -110,14 +153,19 @@ project:
110 This next command is a simple way to verify the installation of your 153 This next command is a simple way to verify the installation of your
111 project. Running the command prints the architecture on which the 154 project. Running the command prints the architecture on which the
112 binary file can run. This architecture should be the same 155 binary file can run. This architecture should be the same
113 architecture that the installed cross-toolchain supports. $ file 156 architecture that the installed cross-toolchain supports.
114 ./tmp/usr/local/bin/hello 157 ::
158
159 $ file ./tmp/usr/local/bin/hello
115 160
1166. *Execute Your Project:* To execute the project, you would need to run 1616. *Execute Your Project:* To execute the project, you would need to run
117 it on your target hardware. If your target hardware happens to be 162 it on your target hardware. If your target hardware happens to be
118 your build host, you could run the project as follows: $ 163 your build host, you could run the project as follows:
119 ./tmp/usr/local/bin/hello As expected, the project displays the 164 ::
120 "Hello World!" message. 165
166 $ ./tmp/usr/local/bin/hello
167
168 As expected, the project displays the "Hello World!" message.
121 169
122Makefile-Based Projects 170Makefile-Based Projects
123======================= 171=======================
@@ -137,7 +185,7 @@ variables and Makefile variables during development.
137The main point of this section is to explain the following three cases 185The main point of this section is to explain the following three cases
138regarding variable behavior: 186regarding variable behavior:
139 187
140- *Case 1 - No Variables Set in the ``Makefile`` Map to Equivalent 188- *Case 1 - No Variables Set in the Makefile Map to Equivalent
141 Environment Variables Set in the SDK Setup Script:* Because matching 189 Environment Variables Set in the SDK Setup Script:* Because matching
142 variables are not specifically set in the ``Makefile``, the variables 190 variables are not specifically set in the ``Makefile``, the variables
143 retain their values based on the environment setup script. 191 retain their values based on the environment setup script.
@@ -163,8 +211,8 @@ regarding variable behavior:
163 , the variables from the SDK setup script take precedence: 211 , the variables from the SDK setup script take precedence:
164 :: 212 ::
165 213
166 $ make -e target 214 $ make -e target
167 215
168 216
169The remainder of this section presents a simple Makefile example that 217The remainder of this section presents a simple Makefile example that
170demonstrates these variable behaviors. 218demonstrates these variable behaviors.
@@ -172,21 +220,36 @@ demonstrates these variable behaviors.
172In a new shell environment variables are not established for the SDK 220In a new shell environment variables are not established for the SDK
173until you run the setup script. For example, the following commands show 221until you run the setup script. For example, the following commands show
174a null value for the compiler variable (i.e. 222a null value for the compiler variable (i.e.
175:term:`CC`). $ echo ${CC} $ Running the 223:term:`CC`).
224::
225
226 $ echo ${CC}
227
228 $
229
230Running the
176SDK setup script for a 64-bit build host and an i586-tuned target 231SDK setup script for a 64-bit build host and an i586-tuned target
177architecture for a ``core-image-sato`` image using the current DISTRO 232architecture for a ``core-image-sato`` image using the current 3.1.2
178Yocto Project release and then echoing that variable shows the value 233Yocto Project release and then echoing that variable shows the value
179established through the script: $ source 234established through the script:
180/opt/poky/DISTRO/environment-setup-i586-poky-linux $ echo ${CC} 235::
181i586-poky-linux-gcc -m32 -march=i586 236
182--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux 237 $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
238 $ echo ${CC}
239 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/3.1.2/sysroots/i586-poky-linux
183 240
184To illustrate variable use, work through this simple "Hello World!" 241To illustrate variable use, work through this simple "Hello World!"
185example: 242example:
186 243
1871. *Create a Working Directory and Populate It:* Create a clean 2441. *Create a Working Directory and Populate It:* Create a clean
188 directory for your project and then make that directory your working 245 directory for your project and then make that directory your working
189 location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After 246 location.
247 ::
248
249 $ mkdir $HOME/helloworld
250 $ cd $HOME/helloworld
251
252 After
190 setting up the directory, populate it with files needed for the flow. 253 setting up the directory, populate it with files needed for the flow.
191 You need a ``main.c`` file from which you call your function, a 254 You need a ``main.c`` file from which you call your function, a
192 ``module.h`` file to contain headers, and a ``module.c`` that defines 255 ``module.h`` file to contain headers, and a ``module.c`` that defines
@@ -194,13 +257,32 @@ example:
194 257
195 Create the three files as follows: 258 Create the three files as follows:
196 259
197 - *``main.c``:* #include "module.h" void sample_func(); int main() { 260 - ``main.c``:
198 sample_func(); return 0; } 261 ::
262
263 #include "module.h"
264 void sample_func();
265 int main()
266 {
267 sample_func();
268 return 0;
269 }
270
271 - ``module.h``:
272 ::
199 273
200 - *``module.h``:* #include <stdio.h> void sample_func(); 274 #include <stdio.h>
275 void sample_func();
201 276
202 - *``module.c``:* #include "module.h" void sample_func() { 277 - ``module.c``:
203 printf("Hello World!"); printf("\n"); } 278 ::
279
280 #include "module.h"
281 void sample_func()
282 {
283 printf("Hello World!");
284 printf("\n");
285 }
204 286
2052. *Source the Cross-Toolchain Environment Setup File:* As described 2872. *Source the Cross-Toolchain Environment Setup File:* As described
206 earlier in the manual, installing the cross-toolchain creates a 288 earlier in the manual, installing the cross-toolchain creates a
@@ -211,38 +293,62 @@ example:
211 which is followed by the string "poky-linux". For this example, the 293 which is followed by the string "poky-linux". For this example, the
212 command sources a script from the default SDK installation directory 294 command sources a script from the default SDK installation directory
213 that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto 295 that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
214 Project release: $ source 296 Project release:
215 /opt/poky/DISTRO/environment-setup-i586-poky-linux 297 ::
298
299 $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux
216 300
2173. *Create the ``Makefile``:* For this example, the Makefile contains 3013. *Create the Makefile:* For this example, the Makefile contains
218 two lines that can be used to set the ``CC`` variable. One line is 302 two lines that can be used to set the ``CC`` variable. One line is
219 identical to the value that is set when you run the SDK environment 303 identical to the value that is set when you run the SDK environment
220 setup script, and the other line sets ``CC`` to "gcc", the default 304 setup script, and the other line sets ``CC`` to "gcc", the default
221 GNU compiler on the build host: # CC=i586-poky-linux-gcc -m32 305 GNU compiler on the build host:
222 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux # 306 ::
223 CC="gcc" all: main.o module.o ${CC} main.o module.o -o target_bin 307
224 main.o: main.c module.h ${CC} -I . -c main.c module.o: module.c 308 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
225 module.h ${CC} -I . -c module.c clean: rm -rf \*.o rm target_bin 309 # CC="gcc"
310 all: main.o module.o
311 ${CC} main.o module.o -o target_bin
312 main.o: main.c module.h
313 ${CC} -I . -c main.c
314 module.o: module.c
315 module.h ${CC} -I . -c module.c
316 clean:
317 rm -rf *.o
318 rm target_bin
226 319
2274. *Make the Project:* Use the ``make`` command to create the binary 3204. *Make the Project:* Use the ``make`` command to create the binary
228 output file. Because variables are commented out in the Makefile, the 321 output file. Because variables are commented out in the Makefile, the
229 value used for ``CC`` is the value set when the SDK environment setup 322 value used for ``CC`` is the value set when the SDK environment setup
230 file was run: $ make i586-poky-linux-gcc -m32 -march=i586 323 file was run:
231 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c 324 ::
232 i586-poky-linux-gcc -m32 -march=i586 325
233 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c 326 $ make
234 i586-poky-linux-gcc -m32 -march=i586 327 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
235 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o 328 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
236 target_bin From the results of the previous command, you can see that 329 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
330
331 From the results of the previous command, you can see that
237 the compiler used was the compiler established through the ``CC`` 332 the compiler used was the compiler established through the ``CC``
238 variable defined in the setup script. 333 variable defined in the setup script.
239 334
240 You can override the ``CC`` environment variable with the same 335 You can override the ``CC`` environment variable with the same
241 variable as set from the Makefile by uncommenting the line in the 336 variable as set from the Makefile by uncommenting the line in the
242 Makefile and running ``make`` again. $ make clean rm -rf \*.o rm 337 Makefile and running ``make`` again.
243 target_bin # # Edit the Makefile by uncommenting the line that sets 338 ::
244 CC to "gcc" # $ make gcc -I . -c main.c gcc -I . -c module.c gcc 339
245 main.o module.o -o target_bin As shown in the previous example, the 340 $ make clean
341 rm -rf *.o
342 rm target_bin
343 #
344 # Edit the Makefile by uncommenting the line that sets CC to "gcc"
345 #
346 $ make
347 gcc -I . -c main.c
348 gcc -I . -c module.c
349 gcc main.o module.o -o target_bin
350
351 As shown in the previous example, the
246 cross-toolchain compiler is not used. Rather, the default compiler is 352 cross-toolchain compiler is not used. Rather, the default compiler is
247 used. 353 used.
248 354
@@ -250,36 +356,62 @@ example:
250 variable as part of the command line. Go into the Makefile and 356 variable as part of the command line. Go into the Makefile and
251 re-insert the comment character so that running ``make`` uses the 357 re-insert the comment character so that running ``make`` uses the
252 established SDK compiler. However, when you run ``make``, use a 358 established SDK compiler. However, when you run ``make``, use a
253 command-line argument to set ``CC`` to "gcc": $ make clean rm -rf 359 command-line argument to set ``CC`` to "gcc":
254 \*.o rm target_bin # # Edit the Makefile to comment out the line 360 ::
255 setting CC to "gcc" # $ make i586-poky-linux-gcc -m32 -march=i586 361
256 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c 362 $ make clean
257 i586-poky-linux-gcc -m32 -march=i586 363 rm -rf *.o
258 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c 364 rm target_bin
259 i586-poky-linux-gcc -m32 -march=i586 365 #
260 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o 366 # Edit the Makefile to comment out the line setting CC to "gcc"
261 target_bin $ make clean rm -rf \*.o rm target_bin $ make CC="gcc" gcc 367 #
262 -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o target_bin 368 $ make
369 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
370 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
371 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
372 $ make clean
373 rm -rf *.o
374 rm target_bin
375 $ make CC="gcc"
376 gcc -I . -c main.c
377 gcc -I . -c module.c
378 gcc main.o module.o -o target_bin
379
263 In the previous case, the command-line argument overrides the SDK 380 In the previous case, the command-line argument overrides the SDK
264 environment variable. 381 environment variable.
265 382
266 In this last case, edit Makefile again to use the "gcc" compiler but 383 In this last case, edit Makefile again to use the "gcc" compiler but
267 then use the "-e" option on the ``make`` command line: $ make clean 384 then use the "-e" option on the ``make`` command line:
268 rm -rf \*.o rm target_bin # # Edit the Makefile to use "gcc" # $ make 385 ::
269 gcc -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o 386
270 target_bin $ make clean rm -rf \*.o rm target_bin $ make -e 387 $ make clean
271 i586-poky-linux-gcc -m32 -march=i586 388 rm -rf *.o
272 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c 389 rm target_bin
273 i586-poky-linux-gcc -m32 -march=i586 390 #
274 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c 391 # Edit the Makefile to use "gcc"
275 i586-poky-linux-gcc -m32 -march=i586 392 #
276 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o 393 $ make
277 target_bin In the previous case, the "-e" option forces ``make`` to 394 gcc -I . -c main.c
395 gcc -I . -c module.c
396 gcc main.o module.o -o target_bin
397 $ make clean
398 rm -rf *.o
399 rm target_bin
400 $ make -e
401 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
402 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
403 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
404
405 In the previous case, the "-e" option forces ``make`` to
278 use the SDK environment variables regardless of the values in the 406 use the SDK environment variables regardless of the values in the
279 Makefile. 407 Makefile.
280 408
2815. *Execute Your Project:* To execute the project (i.e. ``target_bin``), 4095. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
282 use the following command: $ ./target_bin Hello World! 410 use the following command:
411 ::
412
413 $ ./target_bin
414 Hello World!
283 415
284 .. note:: 416 .. note::
285 417