From 62477889fd9f82b00003ce468cf8aad832f146e4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 26 Jan 2016 14:57:15 -0800 Subject: sdk-manual: Applied some "red" text formatting to indicate notes I am using "red" text to indicate sections of the manual that are my development notes. (From yocto-docs rev: 95b432d852ac3248874a2a958d4a80e59187f062) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../sdk-manual/sdk-appendix-customizing.xml | 4 +- documentation/sdk-manual/sdk-appendix-obtain.xml | 6 +- documentation/sdk-manual/sdk-extensible.xml | 24 +-- documentation/sdk-manual/sdk-using.xml | 230 +++++++++++++++++++-- 4 files changed, 229 insertions(+), 35 deletions(-) diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml index c2cb4aa005..2068143df3 100644 --- a/documentation/sdk-manual/sdk-appendix-customizing.xml +++ b/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -6,14 +6,14 @@ Customizing the SDK - + This chapter is going to cover the details on extending the SDK through user customizations. I am not sure if this is possible for both the standard and extensible SDK or what. - + I do not have a feel for what sub-topics need to be covered here. I need to get this information from Paul. diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml index baf5dfd42f..eada4cc8ed 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -9,18 +9,18 @@
Manual Development Notes for Scott and Paul - + This chapter is going to cover details about the installed SDK and perhaps stuff on locating it (e.g. the naming scheme used to identify the .sh installation script. - + The idea here is to gather all the current information in the regular YP doc set that describes how to locate, download, or build out the SDK. - + One thing that needs discussed is any differences between getting the standard SDK as compared to the extended SDK. Do we have pre-build extensible SDKs laying around? diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index a04164a413..c238dee382 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -6,7 +6,7 @@ Using the Extensible SDK - + This chapter describes what you need on your machine in order to use an extensible SDK. The chapter does not repeat information that also applies to using the @@ -26,30 +26,30 @@
Setting Up to Use the Extensible SDK - + Here is a list of items I think need addressed in this section: - Cover differences in the development + Cover differences in the development that might be impacted because they are using an extensible SDK - Presumably, the various development scenarios are + Presumably, the various development scenarios are covered regarding setup in the previous chapter. Are these impacted because the developer is going to now be using an extensible SDK? If so, what are the implications? - What new recommendations exist now that + What new recommendations exist now that the developer is going to be using an extensible SDK? - We should cover the most common development scenarios + We should cover the most common development scenarios that apply when using an extensible SDK. Is there a recommended development flow we want to present when using an extensible SDK? What conditions in a development scenario warrant use of the extensible SDK as compared to the standard SDK? - What procedures do we want to cover to set + What procedures do we want to cover to set up the extensible SDK? - Is it just a matter of building out the SDK using + Is it just a matter of building out the SDK using bitbake -c populate_sdk_ext? Is there a pre-built extensible SDK laying around they can find and download if they are using a machine that does not @@ -63,7 +63,7 @@
Using the Extensible SDK to <replaceable>item 1</replaceable> - + Describe the specific task you are going to accomplish with the extensible SDK. Provide a diagram showing the rough flow of the task. @@ -75,7 +75,7 @@
Using the Extensible SDK to <replaceable>item-2</replaceable> - + Describe the specific task you are going to accomplish with the extensible SDK. Provide a diagram showing the rough flow of the task. @@ -87,7 +87,7 @@
Using the Extensible SDK to <replaceable>item-3</replaceable> - + Describe the specific task you are going to accomplish with the extensible SDK. Provide a diagram showing the rough flow of the task. @@ -99,7 +99,7 @@
Using the Extensible SDK to <replaceable>item-x</replaceable> - + Describe the specific task you are going to accomplish with the extensible SDK. Provide a diagram showing the rough flow of the task. diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml index e3dc6e22a1..66f2c0ed9d 100644 --- a/documentation/sdk-manual/sdk-using.xml +++ b/documentation/sdk-manual/sdk-using.xml @@ -7,9 +7,9 @@ Using the Standard SDK - This chapter describes how to use a standard SDK. - Information covers installing the SDK and task-based procedures common - for developing with a standard SDK. + This chapter describes the standard SDK and how to use it. + Information covers the pieces of the SDK, how to install it, and presents + several task-based procedures common for developing with a standard SDK. The tasks you can perform using a standard SDK are also applicable when you are using an extensible SDK. @@ -20,34 +20,50 @@ -
- Setting Up to Use the Standard SDK +
+ Why use the Standard SDK and What is in It? - - Here is a list of items I think need addressed in this section: + + MANUAL DEVELOPMENT NOTES: + This paragraph describes why you use the Standard SDK. + Probably need to compare that against why you would not be interested + in the extensible SDK here as well. + According to Paul, the most interest lies in the extensible SDK. + So providing this comparison would be helpful. + Currently, my understanding boils down to this: The only reason to use + the Standard SDK is if you want to build and debug source code that + you have. + That pretty much sums it up. + If there is more detail, I need to know about it. + + + + MANUAL DEVELOPMENT NOTES: + Here is a list of items I think need addressed in these early + sections: - What is your situation? - In other words, is the developer on a machine that + What is your situation? + In other words, is the developer on a machine that has YP on it? Are they on a machine that does not? Is the image they are developing against available as a pre-built, down-loadable image and can they get it? - Depending on the scenario, there are different ways + Depending on the scenario, there are different ways to make sure the machine they are using is ready to use a standard SDK. I think we need to cover the various situations in this section. - What are the recommendations? - What is the most common development scenario? + What are the recommendations? + What is the most common development scenario? Is there a recommended development flow we want to present when using a standard SDK? What conditions in a development scenario warrant use of just the standard SDK as compared to the extensible SDK? - What procedures do we want to cover to set up + What procedures do we want to cover to set up the standard SDK? - There is a ton of setup information in the + There is a ton of setup information in the current ADT manual regarding getting, building, and installing an SDK. We would ignore the stuff about the ADT installer script @@ -60,12 +76,190 @@ + + + The installed Standard SDK consists of several files and directories. + Basically, it contains an SDK environment setup script, some + configuration files, and host and target root filesystems to support + usage. + You can see the directory structure in the + "Installed Standard SDK Directory Structure" + section. + + You can also find information on how the Yocto Project + OpenEmbedded build system creates an SDK image by looking at the + "SDK Generation" + section in the Yocto Project Reference Manual. + + +
+ +
+ Installing the SDK + + + The first thing you need to do is install the SDK on your host + development machine by running the .sh + installation script. + + + + You can download a tarball installer, which includes the + pre-built toolchain, the runqemu + script, and support files from the appropriate directory under + . + Toolchains are available for 32-bit and 64-bit x86 development + systems from the i686 and + x86_64 directories, respectively. + The toolchains the Yocto Project provides are based off the + core-image-sato image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + + + + The names of the tarball installer scripts are such that a + string representing the host system appears first in the + filename and then is immediately followed by a string + representing the target architecture. + + poky-glibc-host_system-image_type-arch-toolchain-release_version.sh + + Where: + host_system is a string representing your development system: + + i686 or x86_64. + + image_type is a string representing the image you wish to + develop a SDK for use against. The Yocto Project builds + installers for standard SDKs using the following BitBake + command: + + bitbake core-image-sato -c populate_sdk + + arch is a string representing the tuned target architecture: + + i586, x86_64, powerpc, mips, armv7a or armv5te + + release_version is a string representing the release number of the + Yocto Project: + + &DISTRO;, &DISTRO;+snapshot + + For example, the following toolchain installer is for a 64-bit + development host system and a i586-tuned target architecture + based off the SDK for core-image-sato and + using the current &DISTRO; snapshot: + + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + + + + + The SDK and toolchains are self-contained and by default are installed + into /opt/poky. + However, when you run the SDK installer, you can choose an + installation directory. + + + + The following command shows how to run the installer given a + toolchain tarball for a 64-bit x86 development host system and + a 32-bit x86 target architecture. + When you run the installer, the script prompts you for a + system password so that you permissions can change enabling + you to run the installer script. + The example assumes the toolchain installer is located in + ~/Downloads/. + + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot + ======================================================================== + Enter target directory for SDK (default: /opt/poky/2.1+snapshot): + You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y + [sudo] password for scottrif: + Extracting SDK.......................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux + + + + + Again, reference the + "Installed Standard SDK Directory Structure" + section for more details on the resulting directory structure of + the installed SDK. + +
+ +
+ Running the SDK Environment Setup Script + + + Once you have the SDK installed, you must run the SDK environment + setup script before you can actually use it. + This setup script resides in the directory you chose when you installed + the SDK. + For information on where this setup script can reside, see the + "Obtaining the SDK" + Appendix. + + + + Before running the script, be sure it is the one that matches the + architecture for which you are developing. + Environment setup scripts begin with the string + "environment-setup" and include as part of their + name the tuned target architecture. + For example, the setup script for an IA-based target machine using + i586 tuning and located in the default SDK installation + directory is as follows: + + $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux + + When you run the setup script, many environment variables are + defined: + + SDKTARGETSYSROOT - The path to the sysroot used for cross-compilation + PKG_CONFIG_PATH - The path to the target pkg-config files + CONFIG_SITE - A GNU autoconf site file preconfigured for the target + CC - The minimal command and arguments to run the C compiler + CXX - The minimal command and arguments to run the C++ compiler + CPP - The minimal command and arguments to run the C preprocessor + AS - The minimal command and arguments to run the assembler + LD - The minimal command and arguments to run the linker + GDB - The minimal command and arguments to run the GNU Debugger + STRIP - The minimal command and arguments to run 'strip', which strips symbols + RANLIB - The minimal command and arguments to run 'ranlib' + OBJCOPY - The minimal command and arguments to run 'objcopy' + OBJDUMP - The minimal command and arguments to run 'objdump' + AR - The minimal command and arguments to run 'ar' + NM - The minimal command and arguments to run 'nm' + TARGET_PREFIX - The toolchain binary prefix for the target tools + CROSS_COMPILE - The toolchain binary prefix for the target tools + CONFIGURE_FLAGS - The minimal arguments for GNU configure + CFLAGS - Suggested C flags + CXXFLAGS - Suggested C++ flags + LDFLAGS - Suggested linker flags when you use CC to link + CPPFLAGS - Suggested preprocessor flags + +
Using the SDK to <replaceable>item 1</replaceable> - + Describe the specific task you are going to accomplish with the SDK. Provide a diagram showing the rough flow of the task. Provide specific steps using a real example that works through the @@ -76,7 +270,7 @@
Using the SDK to <replaceable>item-2</replaceable> - + Describe the specific task you are going to accomplish with the SDK. Provide a diagram showing the rough flow of the task. Provide specific steps using a real example that works through the @@ -87,7 +281,7 @@
Using the SDK to <replaceable>item-3</replaceable> - + Describe the specific task you are going to accomplish with the SDK. Provide a diagram showing the rough flow of the task. Provide specific steps using a real example that works through the @@ -98,7 +292,7 @@
Using the SDK to <replaceable>item-x</replaceable> - + Describe the specific task you are going to accomplish with the SDK. Provide a diagram showing the rough flow of the task. Provide specific steps using a real example that works through the -- cgit 1.2.3-korg