mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-01-29 21:08:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

sphinx: sdk-manual: Various URL, code block and other fixes to imported data

Browse Source 
(From yocto-docs rev: 12f5e9cb36409b813ffef9242ce9a042f08acf69)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
2020-09-14 13:34:34 +01:00
parent 688e49bb5e
commit de89b5a0b6
6 changed files with 623 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
documentation/sdk-manual/sdk-appendix-customizing.rst
View File

@@ -18,8 +18,7 @@ build system applies them against ``local.conf`` and ``auto.conf``:
- Variables whose values start with "/" are excluded since the
assumption is that those values are paths that are likely to be
specific to the `build
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__.
specific to the :term:`Build Host`.
- Variables listed in
:term:`SDK_LOCAL_CONF_BLACKLIST`
@@ -57,8 +56,8 @@ OpenEmbedded build system used to create the SDK.
Adjusting the Extensible SDK to Suit Your Build Host's Setup
============================================================
In most cases, the extensible SDK defaults should work with your `build
host's <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ setup.
In most cases, the extensible SDK defaults should work with your :term:`Build
Host`'s setup.
However, some cases exist for which you might consider making
adjustments:
@@ -87,8 +86,8 @@ adjustments:
opposed to being called explicitly), then you need to do one of the
following:
- After ensuring the tasks are `shared
state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ tasks (i.e. the
- After ensuring the tasks are :ref:`shared
state <overview-manual/overview-manual-concepts:shared state cache>` tasks (i.e. the
output of the task is saved to and can be restored from the shared
state cache) or ensuring the tasks are able to be produced quickly
from a task that is a shared state task, add the task name to the
@@ -124,7 +123,7 @@ adjustments:
- If your OpenEmbedded build system setup uses a different environment
setup script other than
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must
:ref:`structure-core-script`, then you must
set
:term:`OE_INIT_ENV_SCRIPT`
to point to the environment setup script you use.
@@ -152,8 +151,10 @@ from the :term:`DISTRO` variable.
The
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
class defines the default value of the ``SDK_TITLE`` variable as
follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or
d.getVar('DISTRO')} SDK"
follows:
::
SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
While several ways exist to change this variable, an efficient method is
to 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
does the default "poky" distribution. If so, you could update the
``SDK_TITLE`` variable in the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form: SDK_TITLE = "your_title"
form:
::
SDK_TITLE = "your_title"
Providing Updates to the Extensible SDK After Installation
==========================================================
@@ -193,8 +197,12 @@ the installed SDKs to update the installed SDKs by using the
3. Build the extensible SDK normally (i.e., use the
``bitbake -c populate_sdk_ext`` imagename command).
4. Publish the SDK using the following command: $ oe-publish-sdk
some_path/sdk-installer.sh path_to_shared_http_directory You must
4. Publish the SDK using the following command:
::
$ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
You must
repeat this step each time you rebuild the SDK with changes that you
want to make available through the update mechanism.
@@ -213,7 +221,12 @@ installation directory for the SDK is based on the
:term:`SDKEXTPATH` variables from
within the
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can
class as follows:
::
SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
You can
change this default installation directory by specifically setting the
``SDKEXTPATH`` variable.
@@ -226,7 +239,10 @@ assume you have your own layer for your distribution named
does the default "poky" distribution. If so, you could update the
``SDKEXTPATH`` variable in the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form: SDKEXTPATH = "some_path_for_your_installed_sdk"
form:
::
SDKEXTPATH = "some_path_for_your_installed_sdk"
After building your installer, running it prompts the user for
acceptance of the some_path_for_your_installed_sdk directory as the
@@ -260,8 +276,11 @@ source, you need to do a number of things:
3. Set the appropriate configuration so that the produced SDK knows how
to find the configuration. The variable you need to set is
:term:`SSTATE_MIRRORS`:
SSTATE_MIRRORS = "file://.\*
http://example.com/some_path/sstate-cache/PATH" You can set the
::
SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
You can set the
``SSTATE_MIRRORS`` variable in two different places:
- 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:
side, and its contents will not interfere with the build), then
you can set the variable in your ``local.conf`` or custom distro
configuration file. You can then "whitelist" the variable through
to the SDK by adding the following: SDK_LOCAL_CONF_WHITELIST =
"SSTATE_MIRRORS"
to the SDK by adding the following:
::
SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
- Alternatively, if you just want to set the ``SSTATE_MIRRORS``
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
more in size. If the size of this file causes a problem, you can build
an SDK that has just enough in it to install and provide access to the
``devtool command`` by setting the following in your configuration:
SDK_EXT_TYPE = "minimal" Setting
::
SDK_EXT_TYPE = "minimal"
Setting
:term:`SDK_EXT_TYPE` to
"minimal" produces an SDK installer that is around 35 Mbytes in size,
which downloads and installs quickly. You need to realize, though, that
@@ -314,9 +339,12 @@ information enables the ``devtool search`` command to return useful
results.
To facilitate this wider range of information, you would need to set the
following: SDK_INCLUDE_PKGDATA = "1" See the
:term:`SDK_INCLUDE_PKGDATA`
variable for additional information.
following:
::
SDK_INCLUDE_PKGDATA = "1"
See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
target to be built so that information for all of the recipes included

137
documentation/sdk-manual/sdk-appendix-obtain.rst
View File

@@ -17,10 +17,10 @@ and then run the script to hand-install the toolchain.
Follow these steps to locate and hand-install the toolchain:
1. *Go to the Installers Directory:* Go to
` <&YOCTO_TOOLCHAIN_DL_URL;>`__
:yocto_dl:`releases/yocto/yocto-3.1.2/toolchain/`
2. *Open the Folder for Your Build Host:* Open the folder that matches
your `build host <&YOCTO_DOCS_REF_URL;#build-system-term>`__ (i.e.
your :term:`Build Host` (i.e.
``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
3. *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:
hardware, and image type.
The installer files (``*.sh``) follow this naming convention:
poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
Where: host_system is a string representing your development system:
"i686" or "x86_64" type is a string representing the image: "sato" or
"minimal" arch is a string representing the target architecture:
"aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586",
"mips32r2", "mips64", or "ppc7400" release is the version of Yocto
Project. NOTE: The standard SDK installer does not have the "-ext"
string as part of the filename. The toolchains provided by the Yocto
::
poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
Where:
host_system is a string representing your development system:
"i686" or "x86_64"
type is a string representing the image:
"sato" or "minimal"
arch is a string representing the target architecture:
"aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
"mips64", or "ppc7400"
release is the version of Yocto Project.
NOTE:
The standard SDK installer does not have the "-ext" string as
part of the filename.
The toolchains provided by the Yocto
Project are based off of the ``core-image-sato`` and
``core-image-minimal`` images and contain libraries appropriate for
developing against those images.
@@ -43,12 +58,17 @@ Follow these steps to locate and hand-install the toolchain:
For example, if your build host is a 64-bit x86 system and you need
an extended SDK for a 64-bit core2 target, go into the ``x86_64``
folder and download the following installer:
poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
::
poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
4. *Run the Installer:* Be sure you have execution privileges and run
the installer. Following is an example from the ``Downloads``
directory: $
~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
directory:
::
$ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
During execution of the script, you choose the root location for the
toolchain. See the "`Installed Standard SDK Directory
Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -63,8 +83,7 @@ As an alternative to locating and downloading an SDK installer, you can
build the SDK installer. Follow these steps:
1. *Set Up the Build Environment:* Be sure you are set up to use BitBake
in a shell. See the "`Preparing the Build
Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section
in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section
in the Yocto Project Development Tasks Manual for information on how
to get a build host ready that is either a native Linux machine or a
machine that uses CROPS.
@@ -72,21 +91,23 @@ build the SDK installer. Follow these steps:
2. *Clone the ``poky`` Repository:* You need to have a local copy of the
Yocto Project :term:`Source Directory`
(i.e. a local
``poky`` repository). See the "`Cloning the ``poky``
Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__" and
possibly the "`Checking Out by Branch in
Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__" and
"`Checking Out by Tag in
Poky <&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky>`__" sections
``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and
possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and
":ref:`checkout-out-by-tag-in-poky`" sections
all in the Yocto Project Development Tasks Manual for information on
how to clone the ``poky`` repository and check out the appropriate
branch for your work.
3. *Initialize the Build Environment:* While in the root directory of
the Source Directory (i.e. ``poky``), run the
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment
:ref:`structure-core-script` environment
setup script to define the OpenEmbedded build environment on your
build host. $ source OE_INIT_FILE Among other things, the script
build host.
::
$ source oe-init-build-env
Among other things, the script
creates the :term:`Build Directory`,
which is
``build`` in this case and is located in the Source Directory. After
@@ -119,13 +140,17 @@ build the SDK installer. Follow these steps:
The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
Unable to continue.
6. *Build the SDK Installer:* To build the SDK installer for a standard
SDK and populate the SDK image, use the following command form. Be
sure to replace image with an image (e.g. "core-image-sato"): $
bitbake image -c populate_sdk You can do the same for the extensible
SDK using this command form: $ bitbake image -c populate_sdk_ext
SDK using this command form:
::
$ bitbake image -c populate_sdk_ext
These commands produce an SDK installer that contains the sysroot
that matches your target root filesystem.
@@ -147,9 +172,12 @@ build the SDK installer. Follow these steps:
libc-staticdev"
7. *Run the Installer:* You can now run the SDK installer from
``tmp/deploy/sdk`` in the Build Directory. Following is an example: $
cd ~/poky/build/tmp/deploy/sdk $
./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
``tmp/deploy/sdk`` in the Build Directory. Following is an example:
::
$ cd ~/poky/build/tmp/deploy/sdk
$ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
During execution of the script, you choose the root location for the
toolchain. See the "`Installed Standard SDK Directory
Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -176,7 +204,7 @@ Follow these steps to extract the root filesystem:
Image File:* You need to find and download the root filesystem image
file that is appropriate for your target system. These files are kept
in machine-specific folders in the
:yocto_dl:`Index of Releases <releases/yocto/yocto-&DISTRO;/machines/>`
:yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`
in the "machines" directory.
The machine-specific folders of the "machines" directory contain
@@ -185,22 +213,32 @@ Follow these steps to extract the root filesystem:
which you can use with QEMU directly.
The pre-built root filesystem image files follow these naming
conventions: core-image-profile-arch.tar.bz2 Where: profile is the
filesystem image's profile: lsb, lsb-dev, lsb-sdk, minimal,
minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk,
sato-sdk-ptest. For information on these types of image profiles, see
the ":ref:`ref-manual/ref-images:Images`" chapter in the
Yocto Project Reference Manual. arch is a string representing the
target architecture: beaglebone-yocto, beaglebone-yocto-lsb,
edgerouter, edgerouter-lsb, genericx86, genericx86-64,
genericx86-64-lsb, genericx86-lsb and qemu*. The root filesystems
conventions:
::
core-image-profile-arch.tar.bz2
Where:
profile is the filesystem image's profile:
lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
these types of image profiles, see the "Images" chapter in
the Yocto Project Reference Manual.
arch is a string representing the target architecture:
beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
The root filesystems
provided by the Yocto Project are based off of the
``core-image-sato`` and ``core-image-minimal`` images.
For example, if you plan on using a BeagleBone device as your target
hardware and your image is a ``core-image-sato-sdk`` image, you can
download the following file:
core-image-sato-sdk-beaglebone-yocto.tar.bz2
::
core-image-sato-sdk-beaglebone-yocto.tar.bz2
2. *Initialize the Cross-Development Environment:* You must ``source``
the cross-development environment setup script to establish necessary
@@ -210,21 +248,24 @@ Follow these steps to extract the root filesystem:
installed the toolchain (e.g. ``poky_sdk``).
Following is an example based on the toolchain installed in the
"`Locating Pre-Built SDK
Installers <#sdk-locating-pre-built-sdk-installers>`__" section: $
source ~/poky_sdk/environment-setup-core2-64-poky-linux
":ref:`sdk-locating-pre-built-sdk-installers`" section:
::
$ source ~/poky_sdk/environment-setup-core2-64-poky-linux
3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
command and provide the root filesystem image.
Following is an example command that extracts the root filesystem
from a previously built root filesystem image that was downloaded
from the `Index of Releases <&YOCTO_DOCS_OM_URL;#index-downloads>`__.
from the :yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`.
This command extracts the root filesystem into the ``core2-64-sato``
directory: $ runqemu-extract-sdk
~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2
~/beaglebone-sato You could now point to the target sysroot at
``beablebone-sato``.
directory:
::
$ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
You could now point to the target sysroot at ``beablebone-sato``.
Installed Standard SDK Directory Structure
==========================================
@@ -246,7 +287,7 @@ Within the figure, italicized text is used to indicate replaceable
portions of the file or directory name. For example, install_dir/version
is the directory where the SDK is installed. By default, this directory
is ``/opt/poky/``. And, version represents the specific snapshot of the
SDK (e.g. ````). Furthermore, target represents the target architecture
SDK (e.g. 3.1.2). Furthermore, target represents the target architecture
(e.g. ``i586``) and host represents the development system's
architecture (e.g. ``x86_64``). Thus, the complete names of the two
directories within the ``sysroots`` could be ``i586-poky-linux`` and

303
documentation/sdk-manual/sdk-extensible.rst
View File

@@ -45,14 +45,13 @@ functionality.
Installing the Extensible SDK
=============================
The first thing you need to do is install the SDK on your `Build
Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
``*.sh`` installation script.
The first thing you need to do is install the SDK on your :term:`Build
Host` by running the ``*.sh`` installation script.
You can download a tarball installer, which includes the pre-built
toolchain, the ``runqemu`` script, the internal build system,
``devtool``, and support files from the appropriate
`toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within the Index of
:yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within the Index of
Releases. Toolchains are available for several 32-bit and 64-bit
architectures with the ``x86_64`` directories, respectively. The
toolchains the Yocto Project provides are based off the
@@ -64,17 +63,33 @@ representing the host system appears first in the filename and then is
immediately followed by a string representing the target architecture.
An extensible SDK has the string "-ext" as part of the name. Following
is the general form:
poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
Where: host_system is a string representing your development system:
i686 or x86_64. image_type is the image for which the SDK was built:
core-image-sato or core-image-minimal arch is a string representing the
tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2,
mips64, ppc7400, or cortexa8hf-neon release_version is a string
representing the release number of the Yocto Project: DISTRO,
DISTRO+snapshot For example, the following SDK installer is for a 64-bit
::
poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
Where:
host_system is a string representing your development system:
i686 or x86_64.
image_type is the image for which the SDK was built:
core-image-sato or core-image-minimal
arch is a string representing the tuned target architecture:
aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
release_version is a string representing the release number of the Yocto Project:
3.1.2, 3.1.2+snapshot
For example, the following SDK 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-ext-DISTRO.sh
::
poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh
.. note::
@@ -102,28 +117,26 @@ architecture. The example assumes the SDK installer is located in
that case, set up the proper permissions in the directory and run the
installer again.
$
./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
Poky (Yocto Project Reference Distro) Extensible SDK installer version
2.5
==========================================================================
Enter target directory for SDK (default: ~/poky_sdk): You are about to
install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
Extracting SDK..............done Setting it up... Extracting
buildtools... Preparing build system... Parsing recipes: 100%
\|##################################################################\|
Time: 0:00:52 Initialising tasks: 100%
\|###############################################################\|
Time: 0:00:00 Checking sstate mirror object availability: 100%
\|#######################################\| Time: 0:00:00 Loading cache:
100%
\|####################################################################\|
Time: 0:00:00 Initialising tasks: 100%
\|###############################################################\|
Time: 0:00:00 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. $ .
/home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
::
$ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
==========================================================================
Enter target directory for SDK (default: ~/poky_sdk):
You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
Extracting SDK..............done
Setting it up...
Extracting buildtools...
Preparing build system...
Parsing recipes: 100% |##################################################################| Time: 0:00:52
Initialising tasks: 100% |###############################################################| Time: 0:00:00
Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
Loading cache: 100% |####################################################################| Time: 0:00:00
Initialising tasks: 100% |###############################################################| Time: 0:00:00
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.
$ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
.. _sdk-running-the-extensible-sdk-environment-setup-script:
@@ -142,10 +155,14 @@ begin with the string "``environment-setup``" and include as part of
their name the tuned target architecture. As an example, the following
commands set the working directory to where the SDK was installed and
then source the environment setup script. In this example, the setup
script is for an IA-based target machine using i586 tuning: $ cd
/home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to
perform development tasks. Run devtool --help for further details.
script is for an IA-based target machine using i586 tuning:
::
$ cd /home/scottrif/poky_sdk
$ source environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
Running the setup script defines many environment variables needed in
order to use the SDK (e.g. ``PATH``,
:term:`CC`,
@@ -172,7 +189,7 @@ system.
part of an image built using the build system.
The ``devtool`` command line is organized similarly to
`Git <&YOCTO_DOCS_OM_URL;#git>`__ in that it has a number of
:ref:`overview-manual/overview-manual-development-environment:git` in that it has a number of
sub-commands for each function. You can run ``devtool --help`` to see
all the commands.
@@ -188,12 +205,12 @@ all the commands.
Three ``devtool`` subcommands exist that provide entry-points into
development:
- *``devtool add``*: Assists in adding new software to be built.
- *devtool add*: Assists in adding new software to be built.
- *``devtool modify``*: Sets up an environment to enable you to modify
- *devtool modify*: Sets up an environment to enable you to modify
the source of an existing component.
- *``devtool upgrade``*: Updates an existing recipe so that you can
- *devtool upgrade*: Updates an existing recipe so that you can
build it for an updated set of source files.
As with the build system, "recipes" represent software packages within
@@ -248,8 +265,12 @@ command:
to be extracted. In this situation, the source code is extracted
to the default workspace - you do not want the files in some
specific location outside of the workspace. Thus, everything you
need will be located in the workspace: $ devtool add recipe
fetchuri With this command, ``devtool`` extracts the upstream
need will be located in the workspace:
::
$ devtool add recipe fetchuri
With this command, ``devtool`` extracts the upstream
source files into a local Git repository within the ``sources``
folder. The command then creates a recipe named recipe and a
corresponding append file in the workspace. If you do not provide
@@ -269,7 +290,12 @@ command:
Furthermore, the first positional argument srctree in this case
identifies where the ``devtool add`` command will locate the
extracted code outside of the workspace. You need to specify an
empty directory: $ devtool add recipe srctree fetchuri In summary,
empty directory:
::
$ devtool add recipe srctree fetchuri
In summary,
the source code is pulled from fetchuri and extracted into the
location defined by srctree as a local Git repository.
@@ -281,7 +307,11 @@ command:
``devtool`` workspace.
The following command provides a new recipe name and identifies
the existing source tree location: $ devtool add recipe srctree
the existing source tree location:
::
$ devtool add recipe srctree
The command examines the source code and creates a recipe named
recipe for the code and places the recipe into the workspace.
@@ -294,7 +324,12 @@ command:
2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
editor as defined by the ``$EDITOR`` environment variable and modify
the file: $ devtool edit-recipe recipe From within the editor, you
the file:
::
$ devtool edit-recipe recipe
From within the editor, you
can make modifications to the recipe that take affect when you build
it later.
@@ -302,13 +337,18 @@ command:
depends on what you are going to do with the new code.
If you need to eventually move the build output to the target
hardware, use the following ``devtool`` command: $ devtool build
recipe
hardware, use the following ``devtool`` command:
:;
$ devtool build recipe
On the other hand, if you want an image to contain the recipe's
packages from the workspace for immediate deployment onto a device
(e.g. for testing purposes), you can use the ``devtool build-image``
command: $ devtool build-image image
command:
::
$ devtool build-image image
4. *Deploy the Build Output*: When you use the ``devtool build`` command
to build out your recipe, you probably want to see if the resulting
@@ -336,7 +376,10 @@ command:
creates any patches corresponding to commits in the local Git
repository, moves the new recipe to a more permanent layer, and then
resets the recipe so that the recipe is built normally rather than
from the workspace. $ devtool finish recipe layer
from the workspace.
::
$ devtool finish recipe layer
.. note::
@@ -401,7 +444,12 @@ command:
outside the workspace (i.e. ``meta-``\ layername).
The following command identifies the recipe and, by default,
extracts the source files: $ devtool modify recipe Once
extracts the source files:
::
$ devtool modify recipe
Once
``devtool``\ locates the recipe, ``devtool`` uses the recipe's
:term:`SRC_URI` statements to
locate the source code and any local patch files from other
@@ -435,7 +483,10 @@ command:
The following command tells ``devtool`` the recipe with which to
work and, in this case, identifies a local area for the extracted
source files that exists outside of the default ``devtool``
workspace: $ devtool modify recipe srctree
workspace:
::
$ devtool modify recipe srctree
.. note::
@@ -466,7 +517,10 @@ command:
The following command tells ``devtool`` the recipe with which to
work, uses the "-n" option to indicate source does not need to be
extracted, and uses srctree to point to the previously extracted
source files: $ devtool modify -n recipe srctree
source files:
::
$ devtool modify -n recipe srctree
If an ``oe-local-files`` subdirectory happens to exist and it
contains non-patch files, the files are used. However, if the
@@ -487,8 +541,10 @@ command:
depends on what you are going to do with the new code.
If you need to eventually move the build output to the target
hardware, use the following ``devtool`` command: $ devtool build
recipe
hardware, use the following ``devtool`` command:
::
$ devtool build recipe
On the other hand, if you want an image to contain the recipe's
packages from the workspace for immediate deployment onto a device
@@ -509,8 +565,12 @@ command:
development machine.
You can deploy your build output to that target hardware by using the
``devtool deploy-target`` command: $ devtool deploy-target recipe
target The target is a live target machine running as an SSH server.
``devtool deploy-target`` command:
::
$ devtool deploy-target recipe target
The target is a live target machine running as an SSH server.
You can, of course, use other methods to deploy the image you built
using the ``devtool build-image`` command to actual hardware.
@@ -522,8 +582,10 @@ command:
repository, updates the recipe to point to them (or creates a
``.bbappend`` file to do so, depending on the specified destination
layer), and then resets the recipe so that the recipe is built
normally rather than from the workspace. $ devtool finish recipe
layer
normally rather than from the workspace.
::
$ devtool finish recipe layer
.. note::
@@ -600,8 +662,12 @@ The following diagram shows the common development flow used with the
A common situation is where third-party software has undergone a
revision so that it has been upgraded. The recipe you have access to
is likely in your own layer. Thus, you need to upgrade the recipe to
use the newer version of the software: $ devtool upgrade -V version
recipe By default, the ``devtool upgrade`` command extracts source
use the newer version of the software:
::
$ devtool upgrade -V version recipe
By default, the ``devtool upgrade`` command extracts source
code into the ``sources`` directory in the
:ref:`devtool-the-workspace-layer-structure`.
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
depends on what you are going to do with the new code.
If you need to eventually move the build output to the target
hardware, use the following ``devtool`` command: $ devtool build
recipe
hardware, use the following ``devtool`` command:
::
$ devtool build recipe
On the other hand, if you want an image to contain the recipe's
packages from the workspace for immediate deployment onto a device
(e.g. for testing purposes), you can use the ``devtool build-image``
command: $ devtool build-image image
command:
::
$ devtool build-image image
4. *Deploy the Build Output*: When you use the ``devtool build`` command
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
If you specify a destination layer that is the same as the original
source, then the old version of the recipe and associated files are
removed prior to adding the new version. $ devtool finish recipe
layer
removed prior to adding the new version.
::
$ devtool finish recipe layer
.. note::
@@ -770,8 +843,12 @@ name and version, just the name, or just the version as part of the
command line.
Sometimes the name or version determined from the source tree might be
incorrect. For such a case, you must reset the recipe: $ devtool reset
-n recipename After running the ``devtool reset`` command, you need to
incorrect. For such a case, you must reset the recipe:
::
$ devtool reset -n recipename
After running the ``devtool reset`` command, you need to
run ``devtool add`` again and provide the name or the version.
.. _sdk-dependency-detection-and-mapping:
@@ -793,8 +870,10 @@ the ``DEPENDS`` variable in the original recipe to include the new
recipe.
If you need to add runtime dependencies, you can do so by adding the
following to your recipe: RDEPENDS_${PN} += "dependency1 dependency2
..."
following to your recipe:
::
RDEPENDS_${PN} += "dependency1 dependency2 ..."
.. note::
@@ -881,7 +960,11 @@ mind:
:term:`EXTRA_OEMAKE` or
:term:`PACKAGECONFIG_CONFARGS`
within the recipe. Here is an example using ``EXTRA_OEMAKE``:
EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example,
::
EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
In the above example,
single quotes are used around the variable settings as the values are
likely to contain spaces because required default options are passed
to the compiler.
@@ -903,8 +986,8 @@ mind:
Adding Native Tools
-------------------
Often, you need to build additional tools that run on the `build
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ as opposed to
Often, you need to build additional tools that run on the :term:`Build
Host` as opposed to
the target. You should indicate this requirement by using one of the
following methods when you run ``devtool add``:
@@ -935,8 +1018,12 @@ You can use the ``devtool add`` command two different ways to add
Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
source.
Use the following form to add Node.js modules through ``npm``: $ devtool
add "npm://registry.npmjs.org;name=forever;version=0.15.1" The name and
Use the following form to add Node.js modules through ``npm``:
::
$ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
The name and
version parameters are mandatory. Lockdown and shrinkwrap files are
generated and pointed to by the recipe in order to freeze the version
that 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.
As mentioned earlier, you can also add Node.js modules directly from a
repository or local source tree. To add modules this way, use
``devtool add`` in the following form: $ devtool add
https://github.com/diversario/node-ssdp In this example, ``devtool``
``devtool add`` in the following form:
::
$ devtool add https://github.com/diversario/node-ssdp
In this example, ``devtool``
fetches the specified Git repository, detects the code as Node.js code,
fetches dependencies using ``npm``, and sets
:term:`SRC_URI` accordingly.
@@ -984,7 +1075,7 @@ build progresses as follows:
For recipes in the workspace, fetching and unpacking is disabled as the
source tree has already been prepared and is persistent. Each of these
build steps is defined as a function (task), usually with a "do_" prefix
build steps is defined as a function (task), usually with a "do\_" prefix
(e.g. :ref:`ref-tasks-fetch`,
:ref:`ref-tasks-unpack`, and so
forth). These functions are typically shell scripts but can instead be
@@ -1069,8 +1160,8 @@ reference.
Sharing Files Between Recipes
-----------------------------
Recipes often need to use files provided by other recipes on the `build
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. For example,
Recipes often need to use files provided by other recipes on the
:term:`Build Host`. For example,
an application linking to a common library needs access to the library
itself and its associated headers. The way this access is accomplished
within 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
``devtool deploy-target`` command. Because the ``devtool deploy-target``
command backs up any files it overwrites, you can use the
``devtool undeploy-target`` command to restore those files and remove
any other files the recipe deployed. Consider the following example: $
devtool undeploy-target lighttpd root@192.168.7.2 If you have deployed
any other files the recipe deployed. Consider the following example:
::
$ devtool undeploy-target lighttpd root@192.168.7.2
If you have deployed
multiple applications, you can remove them all using the "-a" option
thus restoring the target device to its original state: $ devtool
undeploy-target -a root@192.168.7.2 Information about files deployed to
thus restoring the target device to its original state:
::
$ devtool undeploy-target -a root@192.168.7.2
Information about files deployed to
the target as well as any backed up files are stored on the target
itself. This storage, of course, requires some additional space on the
target machine.
@@ -1175,14 +1274,26 @@ populated on-demand. Sometimes you must explicitly install extra items
into the SDK. If you need these extra items, you can first search for
the items using the ``devtool search`` command. For example, suppose you
need to link to libGL but you are not sure which recipe provides libGL.
You can use the following command to find out: $ devtool search libGL
mesa A free implementation of the OpenGL API Once you know the recipe
(i.e. ``mesa`` in this example), you can install it: $ devtool
sdk-install mesa By default, the ``devtool sdk-install`` command assumes
You can use the following command to find out:
::
$ devtool search libGL mesa
A free implementation of the OpenGL API Once you know the recipe
(i.e. ``mesa`` in this example), you can install it:
::
$ devtool sdk-install mesa
By default, the ``devtool sdk-install`` command assumes
the item is available in pre-built form from your SDK provider. If the
item is not available and it is acceptable to build the item from
source, you can add the "-s" option as follows: $ devtool sdk-install -s
mesa It is important to remember that building the item from source
source, you can add the "-s" option as follows:
::
$ devtool sdk-install -s mesa
It is important to remember that building the item from source
takes significantly longer than installing the pre-built artifact. Also,
if no recipe exists for the item you want to add to the SDK, you must
instead add the item using the ``devtool add`` command.
@@ -1196,8 +1307,12 @@ If you are working with an installed extensible SDK that gets
occasionally updated (e.g. a third-party SDK), then you will need to
manually "pull down" the updates into the installed SDK.
To update your installed SDK, use ``devtool`` as follows: $ devtool
sdk-update The previous command assumes your SDK provider has set the
To update your installed SDK, use ``devtool`` as follows:
::
$ devtool sdk-update
The previous command assumes your SDK provider has set the
default update URL for you through the
:term:`SDK_UPDATE_URL`
variable as described in the "`Providing Updates to the Extensible SDK

26
documentation/sdk-manual/sdk-intro.rst
View File

@@ -6,8 +6,8 @@ Introduction
.. _sdk-manual-intro:
Introduction
============
eSDK Introduction
=================
Welcome to the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual. This manual provides information
@@ -109,18 +109,23 @@ when considering which to build:
:term:`SDK_EXT_TYPE` is "full"
or
:term:`SDK_INCLUDE_TOOLCHAIN`
is "1", which is the default. \*\* Sysroot is managed through the use of
is "1", which is the default.
\*\* Sysroot is managed through the use of
``devtool``. Thus, it is less likely that you will corrupt your SDK
sysroot when you try to add additional libraries. \**\* You can add
sysroot when you try to add additional libraries.
\*\*\* You can add
runtime package management to the standard SDK but it is not supported
by default. \***\* You must build and make the shared state available to
by default.
\*\*\*\* You must build and make the shared state available to
extensible SDK users for "packages" you want to enable users to install.
The Cross-Development Toolchain
-------------------------------
The `Cross-Development
Toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__ consists
The :term:`Cross-Development Toolchain` consists
of a cross-compiler, cross-linker, and cross-debugger that are used to
develop user-space applications for targeted hardware. Additionally, for
an extensible SDK, the toolchain also has built-in ``devtool``
@@ -190,7 +195,7 @@ You just need to follow these general steps:
root filesystem images.
If you are going to develop your application on hardware, go to the
```machines`` <&YOCTO_MACHINES_DL_URL;>`__ download area and choose a
:yocto_dl:`machines <releases/yocto/yocto-3.1.2/machines/>` download area and choose a
target machine area from which to download the kernel image and root
filesystem. This download area could have several files in it that
support development using actual hardware. For example, the area
@@ -200,7 +205,7 @@ You just need to follow these general steps:
If you are going to develop your application and then run and test it
using the QEMU emulator, go to the
```machines/qemu`` <&YOCTO_QEMU_DL_URL;>`__ download area. From this
:yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu>` download area. From this
area, go down into the directory for your target architecture (e.g.
``qemux86_64`` for an Intel-based 64-bit architecture). Download the
kernel, root filesystem, and any other files you need for your
@@ -217,8 +222,7 @@ You just need to follow these general steps:
tools to develop your application. If you need to separately install
and use the QEMU emulator, you can go to `QEMU Home
Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about
the emulator. See the "`Using the Quick EMUlator
(QEMU) <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__" chapter in the
the emulator. See the ":doc:`../dev-manual/dev-manual-qemu`" chapter in the
Yocto Project Development Tasks Manual for information on using QEMU
within the Yocto Project.

73
documentation/sdk-manual/sdk-using.rst
View File

@@ -42,13 +42,12 @@ Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
Installing the SDK
==================
The first thing you need to do is install the SDK on your `Build
Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
``*.sh`` installation script.
The first thing you need to do is install the SDK on your :term:`Build
Host` 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 `toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within
appropriate :yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within
the Index of Releases. Toolchains are available for several 32-bit and
64-bit architectures with the ``x86_64`` directories, respectively. The
toolchains the Yocto Project provides are based off the
@@ -58,17 +57,33 @@ libraries appropriate for developing against that image.
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 the image for which the SDK was built:
core-image-minimal or core-image-sato. arch is a string representing the
tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2,
mips64, ppc7400, or cortexa8hf-neon. release_version is a string
representing the release number of the Yocto Project: DISTRO,
DISTRO+snapshot For example, the following SDK installer is for a 64-bit
::
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 the image for which the SDK was built:
core-image-minimal or core-image-sato.
arch is a string representing the tuned target architecture:
aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
release_version is a string representing the release number of the Yocto Project:
3.1.2, 3.1.2+snapshot
For example, the following SDK 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
::
poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
.. note::
@@ -96,16 +111,18 @@ architecture. The example assumes the SDK installer is located in
that case, set up the proper 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 DISTRO
=============================================================== Enter
target directory for SDK (default: /opt/poky/DISTRO): You are about to
install the SDK to "/opt/poky/DISTRO". Proceed [Y/n]? Y 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/DISTRO/environment-setup-i586-poky-linux
::
$ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-3.1.2.sh
Poky (Yocto Project Reference Distro) SDK installer version 3.1.2
===============================================================
Enter target directory for SDK (default: /opt/poky/3.1.2):
You are about to install the SDK to "/opt/poky/3.1.2". Proceed [Y/n]? Y
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/3.1.2/environment-setup-i586-poky-linux
Again, reference the "`Installed Standard SDK Directory
Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
@@ -120,7 +137,7 @@ 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 the SDK. This setup script resides in
the directory you chose when you installed the SDK, which is either the
default ``/opt/poky/DISTRO`` directory or the directory you chose during
default ``/opt/poky/3.1.2`` directory or the directory you chose during
installation.
Before 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
their name the tuned target architecture. As an example, the following
commands set the working directory to where the SDK was installed and
then source the environment setup script. In this example, the setup
script is for an IA-based target machine using i586 tuning: $ source
/opt/poky/DISTRO/environment-setup-i586-poky-linux When you run the
script is for an IA-based target machine using i586 tuning:
::
$ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
When you run the
setup script, the same environment variables are defined as are when you
run the setup script for an extensible SDK. See the "`Running the
Extensible SDK Environment Setup

294
documentation/sdk-manual/sdk-working-projects.rst
View File

@@ -10,8 +10,7 @@ projects.
Autotools-Based Projects
========================
Once you have a suitable `cross-development
toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__
Once you have a suitable :ref:`sdk-manual/sdk-intro:the cross-development toolchain`
installed, it is very easy to develop a project using the `GNU
Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
workflow, which is outside of the :term:`OpenEmbedded Build System`.
@@ -33,24 +32,51 @@ project:
1. *Create a Working Directory and Populate It:* Create a clean
directory for your project and then make that directory your working
location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
setting up the directory, populate it with files needed for the flow.
location.
::
$ mkdir $HOME/helloworld
$ cd $HOME/helloworld
After setting up the directory, populate it with files needed for the flow.
You need a project source file, a file to help with configuration,
and a file to help create the Makefile, and a README file:
``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
respectively.
Use the following command to create an empty README file, which is
required by GNU Coding Standards: $ touch README Create the remaining
required by GNU Coding Standards:
::
$ touch README
Create the remaining
three files as follows:
- *``hello.c``:* #include <stdio.h> main() { printf("Hello
World!\n"); }
- ``hello.c``:
::
- *``configure.ac``:* AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign])
AC_PROG_CC AC_CONFIG_FILES(Makefile) AC_OUTPUT
#include <stdio.h>
- *``Makefile.am``:* bin_PROGRAMS = hello hello_SOURCES = hello.c
main()
{
printf("Hello World!\n");
}
- ``configure.ac``:
::
AC_INIT(hello,0.1)
AM_INIT_AUTOMAKE([foreign])
AC_PROG_CC
AC_CONFIG_FILES(Makefile)
AC_OUTPUT
- ``Makefile.am``:
::
bin_PROGRAMS = hello
hello_SOURCES = hello.c
2. *Source the Cross-Toolchain Environment Setup File:* As described
earlier in the manual, installing the cross-toolchain creates a
@@ -60,12 +86,19 @@ project:
the string "environment-setup" and contains the machine architecture,
which is followed by the string "poky-linux". For this example, the
command sources a script from the default SDK installation directory
that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
Project release: $ source
/opt/poky/DISTRO/environment-setup-i586-poky-linux
that uses the 32-bit Intel x86 Architecture and the 3.1.2 Yocto
Project release:
::
3. *Create the ``configure`` Script:* Use the ``autoreconf`` command to
generate the ``configure`` script. $ autoreconf The ``autoreconf``
$ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
3. *Create the configure Script:* Use the ``autoreconf`` command to
generate the ``configure`` script.
::
$ autoreconf
The ``autoreconf``
tool takes care of running the other Autotools such as ``aclocal``,
``autoconf``, and ``automake``.
@@ -83,7 +116,12 @@ project:
the cross-compiler. The
:term:`CONFIGURE_FLAGS`
environment variable provides the minimal arguments for GNU
configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based
configure:
::
$ ./configure ${CONFIGURE_FLAGS}
For an Autotools-based
project, you can use the cross-toolchain by just passing the
appropriate host option to ``configure.sh``. The host option you use
is derived from the name of the environment setup script found in the
@@ -92,12 +130,17 @@ project:
``armv5te-poky-linux-gnueabi``. You will notice that the name of the
script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
following command works to update your project and rebuild it using
the appropriate cross-toolchain tools: $ ./configure
--host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
the appropriate cross-toolchain tools:
::
$ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
5. *Make and Install the Project:* These two commands generate and
install the project into the destination directory: $ make $ make
install DESTDIR=./tmp
install the project into the destination directory:
::
$ make
$ make install DESTDIR=./tmp
.. note::
@@ -110,14 +153,19 @@ project:
This next command is a simple way to verify the installation of your
project. Running the command prints the architecture on which the
binary file can run. This architecture should be the same
architecture that the installed cross-toolchain supports. $ file
./tmp/usr/local/bin/hello
architecture that the installed cross-toolchain supports.
::
$ file ./tmp/usr/local/bin/hello
6. *Execute Your Project:* To execute the project, you would need to run
it on your target hardware. If your target hardware happens to be
your build host, you could run the project as follows: $
./tmp/usr/local/bin/hello As expected, the project displays the
"Hello World!" message.
your build host, you could run the project as follows:
::
$ ./tmp/usr/local/bin/hello
As expected, the project displays the "Hello World!" message.
Makefile-Based Projects
=======================
@@ -137,7 +185,7 @@ variables and Makefile variables during development.
The main point of this section is to explain the following three cases
regarding variable behavior:
- *Case 1 - No Variables Set in the ``Makefile`` Map to Equivalent
- *Case 1 - No Variables Set in the Makefile Map to Equivalent
Environment Variables Set in the SDK Setup Script:* Because matching
variables are not specifically set in the ``Makefile``, the variables
retain their values based on the environment setup script.
@@ -163,8 +211,8 @@ regarding variable behavior:
, the variables from the SDK setup script take precedence:
::
$ make -e target
$ make -e target
The remainder of this section presents a simple Makefile example that
demonstrates these variable behaviors.
@@ -172,21 +220,36 @@ demonstrates these variable behaviors.
In a new shell environment variables are not established for the SDK
until you run the setup script. For example, the following commands show
a null value for the compiler variable (i.e.
:term:`CC`). $ echo ${CC} $ Running the
:term:`CC`).
::
$ echo ${CC}
$
Running the
SDK setup script for a 64-bit build host and an i586-tuned target
architecture for a ``core-image-sato`` image using the current DISTRO
architecture for a ``core-image-sato`` image using the current 3.1.2
Yocto Project release and then echoing that variable shows the value
established through the script: $ source
/opt/poky/DISTRO/environment-setup-i586-poky-linux $ echo ${CC}
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
established through the script:
::
$ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
$ echo ${CC}
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/3.1.2/sysroots/i586-poky-linux
To illustrate variable use, work through this simple "Hello World!"
example:
1. *Create a Working Directory and Populate It:* Create a clean
directory for your project and then make that directory your working
location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
location.
::
$ mkdir $HOME/helloworld
$ cd $HOME/helloworld
After
setting up the directory, populate it with files needed for the flow.
You need a ``main.c`` file from which you call your function, a
``module.h`` file to contain headers, and a ``module.c`` that defines
@@ -194,13 +257,32 @@ example:
Create the three files as follows:
- *``main.c``:* #include "module.h" void sample_func(); int main() {
sample_func(); return 0; }
- ``main.c``:
::
- *``module.h``:* #include <stdio.h> void sample_func();
#include "module.h"
void sample_func();
int main()
{
sample_func();
return 0;
}
- *``module.c``:* #include "module.h" void sample_func() {
printf("Hello World!"); printf("\n"); }
- ``module.h``:
::
#include <stdio.h>
void sample_func();
- ``module.c``:
::
#include "module.h"
void sample_func()
{
printf("Hello World!");
printf("\n");
}
2. *Source the Cross-Toolchain Environment Setup File:* As described
earlier in the manual, installing the cross-toolchain creates a
@@ -211,38 +293,62 @@ example:
which is followed by the string "poky-linux". For this example, the
command sources a script from the default SDK installation directory
that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
Project release: $ source
/opt/poky/DISTRO/environment-setup-i586-poky-linux
Project release:
::
3. *Create the ``Makefile``:* For this example, the Makefile contains
$ source /opt/poky/DISTRO/environment-setup-i586-poky-linux
3. *Create the Makefile:* For this example, the Makefile contains
two lines that can be used to set the ``CC`` variable. One line is
identical to the value that is set when you run the SDK environment
setup script, and the other line sets ``CC`` to "gcc", the default
GNU compiler on the build host: # CC=i586-poky-linux-gcc -m32
-march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux #
CC="gcc" all: main.o module.o ${CC} main.o module.o -o target_bin
main.o: main.c module.h ${CC} -I . -c main.c module.o: module.c
module.h ${CC} -I . -c module.c clean: rm -rf \*.o rm target_bin
GNU compiler on the build host:
::
# CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
# CC="gcc"
all: main.o module.o
${CC} main.o module.o -o target_bin
main.o: main.c module.h
${CC} -I . -c main.c
module.o: module.c
module.h ${CC} -I . -c module.c
clean:
rm -rf *.o
rm target_bin
4. *Make the Project:* Use the ``make`` command to create the binary
output file. Because variables are commented out in the Makefile, the
value used for ``CC`` is the value set when the SDK environment setup
file was run: $ make i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
target_bin From the results of the previous command, you can see that
file was run:
::
$ make
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
From the results of the previous command, you can see that
the compiler used was the compiler established through the ``CC``
variable defined in the setup script.
You can override the ``CC`` environment variable with the same
variable as set from the Makefile by uncommenting the line in the
Makefile and running ``make`` again. $ make clean rm -rf \*.o rm
target_bin # # Edit the Makefile by uncommenting the line that sets
CC to "gcc" # $ make gcc -I . -c main.c gcc -I . -c module.c gcc
main.o module.o -o target_bin As shown in the previous example, the
Makefile and running ``make`` again.
::
$ make clean
rm -rf *.o
rm target_bin
#
# Edit the Makefile by uncommenting the line that sets CC to "gcc"
#
$ make
gcc -I . -c main.c
gcc -I . -c module.c
gcc main.o module.o -o target_bin
As shown in the previous example, the
cross-toolchain compiler is not used. Rather, the default compiler is
used.
@@ -250,36 +356,62 @@ example:
variable as part of the command line. Go into the Makefile and
re-insert the comment character so that running ``make`` uses the
established SDK compiler. However, when you run ``make``, use a
command-line argument to set ``CC`` to "gcc": $ make clean rm -rf
\*.o rm target_bin # # Edit the Makefile to comment out the line
setting CC to "gcc" # $ make i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
target_bin $ make clean rm -rf \*.o rm target_bin $ make CC="gcc" gcc
-I . -c main.c gcc -I . -c module.c gcc main.o module.o -o target_bin
command-line argument to set ``CC`` to "gcc":
::
$ make clean
rm -rf *.o
rm target_bin
#
# Edit the Makefile to comment out the line setting CC to "gcc"
#
$ make
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
$ make clean
rm -rf *.o
rm target_bin
$ make CC="gcc"
gcc -I . -c main.c
gcc -I . -c module.c
gcc main.o module.o -o target_bin
In the previous case, the command-line argument overrides the SDK
environment variable.
In this last case, edit Makefile again to use the "gcc" compiler but
then use the "-e" option on the ``make`` command line: $ make clean
rm -rf \*.o rm target_bin # # Edit the Makefile to use "gcc" # $ make
gcc -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o
target_bin $ make clean rm -rf \*.o rm target_bin $ make -e
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586
--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
target_bin In the previous case, the "-e" option forces ``make`` to
then use the "-e" option on the ``make`` command line:
::
$ make clean
rm -rf *.o
rm target_bin
#
# Edit the Makefile to use "gcc"
#
$ make
gcc -I . -c main.c
gcc -I . -c module.c
gcc main.o module.o -o target_bin
$ make clean
rm -rf *.o
rm target_bin
$ make -e
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
In the previous case, the "-e" option forces ``make`` to
use the SDK environment variables regardless of the values in the
Makefile.
5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
use the following command: $ ./target_bin Hello World!
use the following command:
::
$ ./target_bin
Hello World!
.. note::