diff options
Diffstat (limited to 'documentation/sdk-manual/working-projects.rst')
| -rw-r--r-- | documentation/sdk-manual/working-projects.rst | 93 |
1 files changed, 49 insertions, 44 deletions
diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst index ad84ce2b87..4236bcec24 100644 --- a/documentation/sdk-manual/working-projects.rst +++ b/documentation/sdk-manual/working-projects.rst @@ -11,14 +11,15 @@ 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`. +installed, it is very easy to develop a project using the :wikipedia:`GNU +Autotools-based <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 + :width: 70% Follow these steps to create a simple Autotools-based "Hello World" project: @@ -30,10 +31,9 @@ project: GNOME Developer site. -1. *Create a Working Directory and Populate It:* Create a clean +#. *Create a Working Directory and Populate It:* Create a clean directory for your project and then make that directory your working - location. - :: + location:: $ mkdir $HOME/helloworld $ cd $HOME/helloworld @@ -74,7 +74,7 @@ project: bin_PROGRAMS = hello hello_SOURCES = hello.c -2. *Source the Cross-Toolchain Environment Setup File:* As described +#. *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 @@ -87,9 +87,13 @@ project: $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux -3. *Create the configure Script:* Use the ``autoreconf`` command to - generate the ``configure`` script. - :: + Another example is sourcing the environment setup directly in a Yocto + build:: + + $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux + +#. *Create the configure Script:* Use the ``autoreconf`` command to + generate the ``configure`` script:: $ autoreconf @@ -104,7 +108,7 @@ project: which ensures missing auxiliary files are copied to the build host. -4. *Cross-Compile the Project:* This command compiles the project using +#. *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 @@ -125,7 +129,7 @@ project: $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir -5. *Make and Install the Project:* These two commands generate and +#. *Make and Install the Project:* These two commands generate and install the project into the destination directory:: $ make @@ -135,19 +139,17 @@ project: 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. + overridden by the Makefile, see the + :ref:`sdk-manual/working-projects: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. - :: + 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 +#. *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:: @@ -169,23 +171,24 @@ variables and Makefile variables during development. .. image:: figures/sdk-makefile-flow.png :align: center + :width: 70% 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. -- *Case 2 - Variables Are Set in the Makefile that Map to Equivalent +- *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 +- *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 @@ -205,8 +208,7 @@ 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`). -:: +:term:`CC`):: $ echo ${CC} @@ -225,10 +227,9 @@ established through the script:: To illustrate variable use, work through this simple "Hello World!" example: -1. *Create a Working Directory and Populate It:* Create a clean +#. *Create a Working Directory and Populate It:* Create a clean directory for your project and then make that directory your working - location. - :: + location:: $ mkdir $HOME/helloworld $ cd $HOME/helloworld @@ -265,7 +266,7 @@ example: printf("\n"); } -2. *Source the Cross-Toolchain Environment Setup File:* As described +#. *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 @@ -278,27 +279,32 @@ example: $ 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 + Another example is sourcing the environment setup directly in a Yocto + build:: + + $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux + +#. *Create the Makefile:* For this example, the Makefile contains + two lines that can be used to set the :term:`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 + setup script, and the other line sets :term:`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 + ${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 + ${CC} -I . -c main.c + module.o: module.c module.h + ${CC} -I . -c module.c clean: - rm -rf *.o - rm target_bin + rm -rf *.o + rm target_bin -4. *Make the Project:* Use the ``make`` command to create the binary +#. *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 + value used for :term:`CC` is the value set when the SDK environment setup file was run:: $ make @@ -307,13 +313,12 @@ example: 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`` + the compiler used was the compiler established through the :term:`CC` variable defined in the setup script. - You can override the ``CC`` environment variable with the same + You can override the :term:`CC` environment variable with the same variable as set from the Makefile by uncommenting the line in the - Makefile and running ``make`` again. - :: + Makefile and running ``make`` again:: $ make clean rm -rf *.o @@ -334,7 +339,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 :term:`CC` to "gcc":: $ make clean rm -rf *.o @@ -382,7 +387,7 @@ example: use the SDK environment variables regardless of the values in the Makefile. -5. *Execute Your Project:* To execute the project (i.e. ``target_bin``), +#. *Execute Your Project:* To execute the project (i.e. ``target_bin``), use the following command:: $ ./target_bin |