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 --- documentation/sdk-manual/sdk-working-projects.rst | 294 ++++++++++++++++------ 1 file changed, 213 insertions(+), 81 deletions(-) (limited to 'documentation/sdk-manual/sdk-working-projects.rst') 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