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