From de89b5a0b6ecb9a5b6a3e5a862cf4cee32dc8a94 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Mon, 14 Sep 2020 13:34:34 +0100 Subject: sphinx: sdk-manual: Various URL, code block and other fixes to imported data (From yocto-docs rev: 12f5e9cb36409b813ffef9242ce9a042f08acf69) Signed-off-by: Richard Purdie --- .../sdk-manual/sdk-appendix-customizing.rst | 72 +++-- documentation/sdk-manual/sdk-appendix-obtain.rst | 137 ++++++---- documentation/sdk-manual/sdk-extensible.rst | 303 ++++++++++++++------- documentation/sdk-manual/sdk-intro.rst | 26 +- documentation/sdk-manual/sdk-using.rst | 73 +++-- documentation/sdk-manual/sdk-working-projects.rst | 294 ++++++++++++++------ 6 files changed, 623 insertions(+), 282 deletions(-) (limited to 'documentation') diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst index 3bb6ef3a19..7743e3c004 100644 --- a/documentation/sdk-manual/sdk-appendix-customizing.rst +++ b/documentation/sdk-manual/sdk-appendix-customizing.rst @@ -18,8 +18,7 @@ build system applies them against ``local.conf`` and ``auto.conf``: - 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 ` 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 ` 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 ` -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 diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst index ed460c78ea..ffaed9deef 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.rst +++ b/documentation/sdk-manual/sdk-appendix-obtain.rst @@ -17,10 +17,10 @@ and then run the script to hand-install the toolchain. 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 ` + :yocto_dl:`Index of Releases ` 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 `. 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 diff --git a/documentation/sdk-manual/sdk-extensible.rst b/documentation/sdk-manual/sdk-extensible.rst index 5836bd8549..1ad5c46bea 100644 --- a/documentation/sdk-manual/sdk-extensible.rst +++ b/documentation/sdk-manual/sdk-extensible.rst @@ -45,14 +45,13 @@ functionality. 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 ` 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 diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst index 215889f390..2e01cf1365 100644 --- a/documentation/sdk-manual/sdk-intro.rst +++ b/documentation/sdk-manual/sdk-intro.rst @@ -6,8 +6,8 @@ Introduction .. _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 ` 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 ` 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 `__ 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. diff --git a/documentation/sdk-manual/sdk-using.rst b/documentation/sdk-manual/sdk-using.rst index b240f9174a..cd57f07eeb 100644 --- a/documentation/sdk-manual/sdk-using.rst +++ b/documentation/sdk-manual/sdk-using.rst @@ -42,13 +42,12 @@ Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. 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 ` 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 diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst index df216175c9..2c20a1ec57 100644 --- a/documentation/sdk-manual/sdk-working-projects.rst +++ b/documentation/sdk-manual/sdk-working-projects.rst @@ -10,8 +10,7 @@ projects. 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 `__ 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 main() { printf("Hello - World!\n"); } + - ``hello.c``: + :: + + #include - - *``configure.ac``:* AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign]) - AC_PROG_CC AC_CONFIG_FILES(Makefile) AC_OUTPUT + main() + { + printf("Hello World!\n"); + } - - *``Makefile.am``:* bin_PROGRAMS = hello hello_SOURCES = hello.c + - ``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: + :: + + $ 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`` +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``: + :: + + #include "module.h" + void sample_func(); + int main() + { + sample_func(); + return 0; + } + + - ``module.h``: + :: - - *``module.h``:* #include void sample_func(); + #include + void sample_func(); - - *``module.c``:* #include "module.h" void sample_func() { - printf("Hello World!"); printf("\n"); } + - ``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: + :: + + $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux -3. *Create the ``Makefile``:* For this example, the Makefile contains +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:: -- cgit v1.2.3-54-g00ecf