poky: subtree update:0ac99625bf..796be0593a
Alexander Kanavin (31):
netbase: upgrade 6.1 -> 6.2
meson: upgrade 0.55.1 -> 0.56.0
vulkan-samples: update to latest revision
libcap: update 2.44 -> 2.45
bind: upgrade 9.16.7 -> 9.16.9
quota: upgrade 4.05 -> 4.06
pango: upgrade 1.46.2 -> 1.48.0
elfutils: upgrade 0.181 -> 0.182
ifupdown: upgrade 0.8.35 -> 0.8.36
createrepo-c: upgrade 0.16.1 -> 0.16.2
acpica: upgrade 20200925 -> 20201113
grep: upgrade 3.5 -> 3.6
man-pages: upgrade 5.08 -> 5.09
stress-ng: upgrade 0.11.23 -> 0.11.24
libhandy: upgrade 1.0.1 -> 1.0.2
piglit: upgrade to latest revision
xkbcomp: upgrade 1.4.3 -> 1.4.4
lz4: upgrade 1.9.2 -> 1.9.3
bison: upgrade 3.7.3 -> 3.7.4
python3-setuptools-scm: fix upstream version check
cantarell-fonts: update 0.0.25 -> 0.201
meta/lib/oe/reproducible.py: gitsm:// works just as fine as git:// for timestamps
llvm: fix reproducibility
ruby: fix reproducibility
webkitgtk: fix reproducibility
ffmpeg: fix reproducibility
piglit: fix reproducibility
serf: do not install the static library
llvm: sort the lists in generated source reproducibibly
kea: fix reproducibility
poky.conf: do not write current date into distro version, use git hash instead
Andrej Valek (1):
kernel-dummy: fix executing unexpected tasks
Anuj Mittal (1):
releases.rst: add gatesgarth to current releases
Brett Warren (1):
libffi: add patch to revert clang VFP workaround
Chandana kalluri (1):
populate_sdk_ext: use SDK_CUSTOM_TEPLATECONF variable to enable custom templateconf.cfg
Changqing Li (1):
buildtools-tarball: add wic dependency into extended buildtools
Diego Sueiro (2):
modutils-initscripts: Fix modules.dep creation when USE_DEPMOD="0"
initscripts: Change execution order between checkroot and modutils
Dmitry Baryshkov (2):
linux-firmware: upgrade 20201022 -> 20201118
linux-firmware: package ath11k firmware
Fabio Berton (1):
mesa: Update 20.2.1 -> 20.2.4
Gratian Crisan (1):
kernel-module-split.bbclass: fix kernel modules getting marked as CONFFILES
Jack Mitchell (3):
Revert "connman: set service to conflict with systemd-networkd"
systemd-conf: add PACKAGECONFIG to enable/disable auto ethernet DHCP
systemd-conf: match ethernet interfaces by type rather than globbing
Joshua Watt (2):
bitbake: hashserv: client: Fix AF_UNIX path length limits
bitbake: hashserv: Fix broken AF_UNIX path length limit
Kai Kang (2):
systemd-systemctl-native: capable to call without argument
systemd.bbclass: update command to check systemctl available
Kevin Hao (1):
tune-octeontx2.inc: Add tune for Marvell OCTEON TX2 core
Li Wang (2):
qemu: CVE-2020-29129 CVE-2020-29130
qemu: CVE-2020-25624
Luca Boccassi (1):
dbus: move messagebus user to dbus-common package
Michael Halstead (1):
releases: conf: add link to 3.1.4, update to include 3.1.4
Nicolas Dechesne (19):
sphinx: add .vscode in .gitignore
{dev,kernel,sdk}-manual: replace hardcoded release version with &DISTRO;
sphinx: replace bitbake labels with references to corresponding title
brief-yoctoprojectqs: replace labels with references to section title
dev-manual: replace labels with references to section title
ref-manual: replace labels with references to section title
sdk-manual: replace labels with references to section title
overview-manual: remove unused labels
dev-manual: remove unused labels
sphinx: rename top level document in each manual
sphinx: use absolute paths for :doc: references
test-manual: remove 'test-manual' from filenames
toaster-manual: remove 'toaster-manual' from filenames
dev-manual: remove 'dev-manual' from filenames
kernel-dev: remove 'kernel-dev' from filenames
profile-manual: remove 'profile-manual' from filenames
overview-manual: remove 'overview-manual' from filenames
sdk-manual: remove 'sdk' from filenames
ref-manual: remove 'ref' from filenames
Paul Barker (5):
documentation: Simplify yocto_wiki links
documentation: Simplify yocto_git links
ref-manual: Simplify oe_git links
poky.conf: Add opensuseleap-15.2 and fedora-33 to tested distros
poky.conf: Drop fedora-30 from tested distros
Peter Kjellerstedt (2):
pseudo: Simplify pseudo_client_ignore_path_chroot()
bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS
Richard Purdie (8):
lz4: Use the new branch naming from upstream
Revert "bitbake.conf: Add all layers (from BBLAYERS) to PSEUDO_IGNORE_PATHS"
build-appliance-image: Update to master head revision
bitbake: Revert "fetch2: use relative symlinks for anything pulled from PREMIRRORS"
build-appliance-image: Update to master head revision
metadata_scm: Fix signature handling of METADATA_REVISION and METADATA_BRANCH
poky: Set SDK_VERSION explicitly
build-appliance-image: Update to master head revision
Ross Burton (9):
oeqa/devtool: use Yocto mirror for pv-1.5.3 tarball
image_types: remove obsolete tar comment
image_types: sort tarball file listings
package_manager/ipk: neaten OPKGLIBDIR logic
ldconfig-native: don't write auxiliary cache
package_manager/ipk: improve remove_packaging_data
oeqa/selftest/containerimage: update for improved cleanup
coreutils: add SUSE-specific issues to CVE whitelist
bitbake: msg: use safe YAML loader
Sinan Kaya (1):
poky-tiny: enable section removal
Tomasz Dziendzielski (1):
pseudo: Update to print PSEUDO_LOGFILE in abort message on path mismatches
sangeeta jain (1):
meta/lib/oeqa/manual/oe-core.json: Update test_bitbake_devshell
zangrc (3):
libinput: upgrade 1.16.3 -> 1.16.4
lighttpd: upgrade 1.4.55 -> 1.4.56
sysstat: upgrade 12.4.0 -> 12.4.1
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: I65f2f1c9d44433f3e62609240012c42256679b51
diff --git a/poky/documentation/sdk-manual/working-projects.rst b/poky/documentation/sdk-manual/working-projects.rst
new file mode 100644
index 0000000..3e40936
--- /dev/null
+++ b/poky/documentation/sdk-manual/working-projects.rst
@@ -0,0 +1,423 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+********************************
+Using the SDK Toolchain Directly
+********************************
+
+You can use the SDK toolchain directly with Makefile and Autotools-based
+projects.
+
+Autotools-Based Projects
+========================
+
+Once you have a suitable :ref:`sdk-manual/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`.
+
+The following figure presents a simple Autotools workflow.
+
+.. image:: figures/sdk-autotools-flow.png
+ :align: center
+
+Follow these steps to create a simple Autotools-based "Hello World"
+project:
+
+.. note::
+
+ For more information on the GNU Autotools workflow, see the same
+ example on the
+ GNOME Developer
+ site.
+
+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.
+ 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
+ three files as follows:
+
+ - ``hello.c``:
+ ::
+
+ #include <stdio.h>
+
+ 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
+ cross-toolchain environment setup script in the directory that the
+ SDK was installed. Before you can use the tools to develop your
+ project, you must source this setup script. The script begins with
+ 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; Yocto
+ Project release:
+ ::
+
+ $ source /opt/poky/&DISTRO;/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``.
+
+ .. note::
+
+ If you get errors from
+ configure.ac
+ , which
+ autoreconf
+ runs, that indicate missing files, you can use the "-i" option,
+ which ensures missing auxiliary files are copied to the build
+ host.
+
+4. *Cross-Compile the Project:* This command compiles the project using
+ the cross-compiler. The
+ :term:`CONFIGURE_FLAGS`
+ environment variable provides the minimal arguments for GNU
+ 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
+ directory in which you installed the cross-toolchain. For example,
+ the host option for an ARM-based target that uses the GNU EABI is
+ ``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
+
+5. *Make and Install the Project:* These two commands generate and
+ install the project into the destination directory:
+ ::
+
+ $ make
+ $ make install DESTDIR=./tmp
+
+ .. note::
+
+ To learn about environment variables established when you run the
+ cross-toolchain environment setup script and how they are used or
+ overridden when the Makefile, see the "
+ Makefile-Based Projects
+ " section.
+
+ 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
+
+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.
+
+Makefile-Based Projects
+=======================
+
+Simple Makefile-based projects use and interact with the cross-toolchain
+environment variables established when you run the cross-toolchain
+environment setup script. The environment variables are subject to
+general ``make`` rules.
+
+This section presents a simple Makefile development flow and provides an
+example that lets you see how you can use cross-toolchain environment
+variables and Makefile variables during development.
+
+.. image:: figures/sdk-makefile-flow.png
+ :align: center
+
+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
+ 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.
+
+- *Case 2 - Variables Are Set in the Makefile that Map to Equivalent
+ Environment Variables from the SDK Setup Script:* Specifically
+ setting matching variables in the ``Makefile`` during the build
+ results in the environment settings of the variables being
+ overwritten. In this case, the variables you set in the ``Makefile``
+ are used.
+
+- *Case 3 - Variables Are Set Using the Command Line that Map to
+ Equivalent Environment Variables from the SDK Setup Script:*
+ Executing the ``Makefile`` from the command line results in the
+ environment variables being overwritten. In this case, the
+ command-line content is used.
+
+.. 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:
+ ::
+
+ $ make -e target
+
+
+The remainder of this section presents a simple Makefile example that
+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
+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:
+::
+
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ $ echo ${CC}
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/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
+ 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
+ your function.
+
+ Create the three files as follows:
+
+ - ``main.c``:
+ ::
+
+ #include "module.h"
+ void sample_func();
+ int main()
+ {
+ sample_func();
+ return 0;
+ }
+
+ - ``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
+ cross-toolchain environment setup script in the directory that the
+ SDK was installed. Before you can use the tools to develop your
+ project, you must source this setup script. The script begins with
+ 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
+
+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
+
+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
+ 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
+ cross-toolchain compiler is not used. Rather, the default compiler is
+ used.
+
+ This next case shows how to override a variable by providing the
+ 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
+
+ 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
+ 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!
+
+ .. note::
+
+ If you used the cross-toolchain compiler to build
+ target_bin
+ and your build host differs in architecture from that of the
+ target machine, you need to run your project on the target device.
+
+ As expected, the project displays the "Hello World!" message.