From c3c6de21876aad811e08538544c8fe76d22ccd09 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Fri, 16 Apr 2021 18:27:05 +0200 Subject: manuals: code insertion simplification over two lines This simplifies paragraphs ending with a colon and followed by code insertion. Automatically substituted through the command: sed -i -z "s/:\n\s*::/::/g" file.rst This generates identical HTML output. (From yocto-docs rev: 28e2192a7c12d64b68061138a9f6c796453eebb1) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/sdk-manual/appendix-customizing.rst | 27 +++----- documentation/sdk-manual/appendix-obtain.rst | 30 +++------ documentation/sdk-manual/extensible.rst | 81 ++++++++--------------- documentation/sdk-manual/using.rst | 6 +- documentation/sdk-manual/working-projects.rst | 60 ++++++----------- 5 files changed, 68 insertions(+), 136 deletions(-) (limited to 'documentation/sdk-manual') diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index 8e7115046b..fb2d78452b 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -149,8 +149,7 @@ from the :term:`DISTRO` variable. The :ref:`populate_sdk_base ` class defines the default value of the ``SDK_TITLE`` variable as -follows: -:: +follows:: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" @@ -162,8 +161,7 @@ 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: -:: +form:: SDK_TITLE = "your_title" @@ -194,8 +192,7 @@ 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: - :: +4. Publish the SDK using the following command:: $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory @@ -218,8 +215,7 @@ installation directory for the SDK is based on the :term:`SDKEXTPATH` variables from within the :ref:`populate_sdk_base ` -class as follows: -:: +class as follows:: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" @@ -236,8 +232,7 @@ 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: -:: +form:: SDKEXTPATH = "some_path_for_your_installed_sdk" @@ -272,8 +267,7 @@ 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`: - :: + :term:`SSTATE_MIRRORS`:: SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH" @@ -287,8 +281,7 @@ 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: - :: + to the SDK by adding the following:: SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" @@ -313,8 +306,7 @@ everything needed to reconstruct the image for which the SDK was built. 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: -:: +``devtool command`` by setting the following in your configuration:: SDK_EXT_TYPE = "minimal" @@ -336,8 +328,7 @@ information enables the ``devtool search`` command to return useful results. To facilitate this wider range of information, you would need to set the -following: -:: +following:: SDK_INCLUDE_PKGDATA = "1" diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst index 3c1dc52d19..0ce828aa29 100644 --- a/documentation/sdk-manual/appendix-obtain.rst +++ b/documentation/sdk-manual/appendix-obtain.rst @@ -25,8 +25,7 @@ Follow these steps to locate and hand-install the toolchain: download the installer appropriate for your build host, target hardware, and image type. - The installer files (``*.sh``) follow this naming convention: - :: + The installer files (``*.sh``) follow this naming convention:: poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh @@ -55,15 +54,13 @@ 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: - :: + folder and download the following installer:: 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: - :: + directory:: $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh @@ -132,8 +129,7 @@ build the SDK installer. Follow these steps: using to build the installer. If SDKMACHINE is not set appropriately, the build fails and provides an error - message similar to the following: - :: + message similar to the following:: 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). @@ -144,8 +140,7 @@ build the SDK installer. Follow these steps: 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: - :: + SDK using this command form:: $ bitbake image -c populate_sdk_ext @@ -170,8 +165,7 @@ 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: - :: + ``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 @@ -211,8 +205,7 @@ 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: - :: + conventions:: core-image-profile-arch.tar.bz2 @@ -233,8 +226,7 @@ Follow these steps to extract the root filesystem: 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: - :: + download the following file:: core-image-sato-sdk-beaglebone-yocto.tar.bz2 @@ -246,8 +238,7 @@ 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 - ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: - :: + ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section:: $ source poky_sdk/environment-setup-core2-64-poky-linux @@ -258,8 +249,7 @@ Follow these steps to extract the root filesystem: from a previously built root filesystem image that was downloaded from the :yocto_dl:`Index of Releases `. This command extracts the root filesystem into the ``core2-64-sato`` - directory: - :: + directory:: $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst index baa432ef3b..04bafaed9e 100644 --- a/documentation/sdk-manual/extensible.rst +++ b/documentation/sdk-manual/extensible.rst @@ -59,8 +59,7 @@ 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. An extensible SDK has the string "-ext" as part of the name. Following -is the general form: -:: +is the general form:: poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh @@ -83,8 +82,7 @@ is the general form: 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: -:: +the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:: poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh @@ -150,8 +148,7 @@ 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: -:: +script is for an IA-based target machine using i586 tuning:: $ cd /home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux @@ -258,8 +255,7 @@ 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: - :: + need will be located in the workspace:: $ devtool add recipe fetchuri @@ -283,8 +279,7 @@ 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: - :: + empty directory:: $ devtool add recipe srctree fetchuri @@ -300,8 +295,7 @@ command: ``devtool`` workspace. The following command provides a new recipe name and identifies - the existing source tree location: - :: + the existing source tree location:: $ devtool add recipe srctree @@ -317,8 +311,7 @@ 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: - :: + the file:: $ devtool edit-recipe recipe @@ -338,8 +331,7 @@ command: 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: - :: + command:: $ devtool build-image image @@ -435,8 +427,7 @@ command: outside the workspace (i.e. ``meta-``\ layername). The following command identifies the recipe and, by default, - extracts the source files: - :: + extracts the source files:: $ devtool modify recipe @@ -474,8 +465,7 @@ 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: - :: + workspace:: $ devtool modify recipe srctree @@ -508,8 +498,7 @@ 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: - :: + source files:: $ devtool modify -n recipe srctree @@ -532,8 +521,7 @@ 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: - :: + hardware, use the following ``devtool`` command:: $ devtool build recipe @@ -556,8 +544,7 @@ command: development machine. You can deploy your build output to that target hardware by using the - ``devtool deploy-target`` command: - :: + ``devtool deploy-target`` command:: $ devtool deploy-target recipe target @@ -651,8 +638,7 @@ 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: - :: + use the newer version of the software:: $ devtool upgrade -V version recipe @@ -703,16 +689,14 @@ 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: - :: + 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: - :: + command:: $ devtool build-image image @@ -828,8 +812,7 @@ 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: -:: +incorrect. For such a case, you must reset the recipe:: $ devtool reset -n recipename @@ -853,8 +836,7 @@ 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: -:: +following to your recipe:: RDEPENDS_${PN} += "dependency1 dependency2 ..." @@ -938,8 +920,7 @@ mind: the command line, add the variable setting to :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` - within the recipe. Here is an example using ``EXTRA_OEMAKE``: - :: + within the recipe. Here is an example using ``EXTRA_OEMAKE``:: EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" @@ -993,8 +974,7 @@ 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``: -:: +Use the following form to add Node.js modules through ``npm``:: $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" @@ -1018,8 +998,7 @@ 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`` in the following form:: $ devtool add https://github.com/diversario/node-ssdp @@ -1196,15 +1175,13 @@ 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: -:: +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: -:: +thus restoring the target device to its original state:: $ devtool undeploy-target -a root@192.168.7.2 @@ -1235,22 +1212,19 @@ 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: -:: +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: -:: +(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: -:: +source, you can add the "-s" option as follows:: $ devtool sdk-install -s mesa @@ -1266,8 +1240,7 @@ 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: -:: +To update your installed SDK, use ``devtool`` as follows:: $ devtool sdk-update diff --git a/documentation/sdk-manual/using.rst b/documentation/sdk-manual/using.rst index 62967f5572..fa0e8d4098 100644 --- a/documentation/sdk-manual/using.rst +++ b/documentation/sdk-manual/using.rst @@ -77,8 +77,7 @@ immediately followed by a string representing the target architecture. 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: -:: +the SDK for ``core-image-sato`` and using the current DISTRO snapshot:: poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh @@ -141,8 +140,7 @@ 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: -:: +script is for an IA-based target machine using i586 tuning:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst index f880cbe0d5..ad84ce2b87 100644 --- a/documentation/sdk-manual/working-projects.rst +++ b/documentation/sdk-manual/working-projects.rst @@ -45,16 +45,14 @@ project: respectively. Use the following command to create an empty README file, which is - required by GNU Coding Standards: - :: + required by GNU Coding Standards:: $ touch README Create the remaining three files as follows: - - ``hello.c``: - :: + - ``hello.c``:: #include @@ -63,8 +61,7 @@ project: printf("Hello World!\n"); } - - ``configure.ac``: - :: + - ``configure.ac``:: AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign]) @@ -72,8 +69,7 @@ project: AC_CONFIG_FILES(Makefile) AC_OUTPUT - - ``Makefile.am``: - :: + - ``Makefile.am``:: bin_PROGRAMS = hello hello_SOURCES = hello.c @@ -87,8 +83,7 @@ project: 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; Yocto - Project release: - :: + Project release:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux @@ -113,8 +108,7 @@ project: the cross-compiler. The :term:`CONFIGURE_FLAGS` environment variable provides the minimal arguments for GNU - configure: - :: + configure:: $ ./configure ${CONFIGURE_FLAGS} @@ -127,14 +121,12 @@ 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: - :: + 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: - :: + install the project into the destination directory:: $ make $ make install DESTDIR=./tmp @@ -157,8 +149,7 @@ project: 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: - :: + your build host, you could run the project as follows:: $ ./tmp/usr/local/bin/hello @@ -203,8 +194,7 @@ regarding variable behavior: .. note:: Regardless of how you set your variables, if you use the "-e" option - with ``make``, the variables from the SDK setup script take precedence: - :: + with ``make``, the variables from the SDK setup script take precedence:: $ make -e target @@ -226,8 +216,7 @@ 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; Yocto Project release and then echoing that variable shows the value -established through the script: -:: +established through the script:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux $ echo ${CC} @@ -252,8 +241,7 @@ example: Create the three files as follows: - - ``main.c``: - :: + - ``main.c``:: #include "module.h" void sample_func(); @@ -263,14 +251,12 @@ example: return 0; } - - ``module.h``: - :: + - ``module.h``:: #include void sample_func(); - - ``module.c``: - :: + - ``module.c``:: #include "module.h" void sample_func() @@ -288,8 +274,7 @@ 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: - :: + Project release:: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux @@ -297,8 +282,7 @@ example: 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: - :: + 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" @@ -315,8 +299,7 @@ example: 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: - :: + file was run:: $ make i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c @@ -351,8 +334,7 @@ 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": - :: + command-line argument to set ``CC`` to "gcc":: $ make clean rm -rf *.o @@ -376,8 +358,7 @@ example: 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: - :: + then use the "-e" option on the ``make`` command line:: $ make clean rm -rf *.o @@ -402,8 +383,7 @@ example: Makefile. 5. *Execute Your Project:* To execute the project (i.e. ``target_bin``), - use the following command: - :: + use the following command:: $ ./target_bin Hello World! -- cgit v1.2.3-54-g00ecf