diff options
Diffstat (limited to 'documentation/adt-manual/adt-command.rst')
-rw-r--r-- | documentation/adt-manual/adt-command.rst | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/documentation/adt-manual/adt-command.rst b/documentation/adt-manual/adt-command.rst new file mode 100644 index 0000000000..de854772bb --- /dev/null +++ b/documentation/adt-manual/adt-command.rst | |||
@@ -0,0 +1,180 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ********************** | ||
4 | Using the Command Line | ||
5 | ********************** | ||
6 | |||
7 | Recall that earlier the manual discussed how to use an existing | ||
8 | toolchain tarball that had been installed into the default installation | ||
9 | directory, ``/opt/poky/DISTRO``, which is outside of the :term:`Build Directory` | ||
10 | (see the section | ||
11 | "`Using a Cross-Toolchain | ||
12 | Tarball) <#using-an-existing-toolchain-tarball>`__". And, that sourcing | ||
13 | your architecture-specific environment setup script initializes a | ||
14 | suitable cross-toolchain development environment. | ||
15 | |||
16 | During this setup, locations for the compiler, QEMU scripts, QEMU | ||
17 | binary, a special version of ``pkgconfig`` and other useful utilities | ||
18 | are added to the ``PATH`` variable. Also, variables to assist | ||
19 | ``pkgconfig`` and ``autotools`` are also defined so that, for example, | ||
20 | ``configure.sh`` can find pre-generated test results for tests that need | ||
21 | target hardware on which to run. You can see the "`Setting Up the | ||
22 | Cross-Development | ||
23 | Environment <#setting-up-the-cross-development-environment>`__" section | ||
24 | for the list of cross-toolchain environment variables established by the | ||
25 | script. | ||
26 | |||
27 | Collectively, these conditions allow you to easily use the toolchain | ||
28 | outside of the OpenEmbedded build environment on both Autotools-based | ||
29 | projects and Makefile-based projects. This chapter provides information | ||
30 | for both these types of projects. | ||
31 | |||
32 | Autotools-Based Projects | ||
33 | ======================== | ||
34 | |||
35 | Once you have a suitable cross-toolchain installed, it is very easy to | ||
36 | develop a project outside of the OpenEmbedded build system. This section | ||
37 | presents a simple "Helloworld" example that shows how to set up, | ||
38 | compile, and run the project. | ||
39 | |||
40 | Creating and Running a Project Based on GNU Autotools | ||
41 | ----------------------------------------------------- | ||
42 | |||
43 | Follow these steps to create a simple Autotools-based project: | ||
44 | |||
45 | 1. *Create your directory:* Create a clean directory for your project | ||
46 | and then make that directory your working location: $ mkdir | ||
47 | $HOME/helloworld $ cd $HOME/helloworld | ||
48 | |||
49 | 2. *Populate the directory:* Create ``hello.c``, ``Makefile.am``, and | ||
50 | ``configure.in`` files as follows: | ||
51 | |||
52 | - For ``hello.c``, include these lines: #include <stdio.h> main() { | ||
53 | printf("Hello World!\n"); } | ||
54 | |||
55 | - For ``Makefile.am``, include these lines: bin_PROGRAMS = hello | ||
56 | hello_SOURCES = hello.c | ||
57 | |||
58 | - For ``configure.in``, include these lines: AC_INIT(hello.c) | ||
59 | AM_INIT_AUTOMAKE(hello,0.1) AC_PROG_CC AC_PROG_INSTALL | ||
60 | AC_OUTPUT(Makefile) | ||
61 | |||
62 | 3. *Source the cross-toolchain environment setup file:* Installation of | ||
63 | the cross-toolchain creates a cross-toolchain environment setup | ||
64 | script in the directory that the ADT was installed. Before you can | ||
65 | use the tools to develop your project, you must source this setup | ||
66 | script. The script begins with the string "environment-setup" and | ||
67 | contains the machine architecture, which is followed by the string | ||
68 | "poky-linux". Here is an example that sources a script from the | ||
69 | default ADT installation directory that uses the 32-bit Intel x86 | ||
70 | Architecture and the DISTRO_NAME Yocto Project release: $ source | ||
71 | /opt/poky/DISTRO/environment-setup-i586-poky-linux | ||
72 | |||
73 | 4. *Generate the local aclocal.m4 files and create the configure | ||
74 | script:* The following GNU Autotools generate the local | ||
75 | ``aclocal.m4`` files and create the configure script: $ aclocal $ | ||
76 | autoconf | ||
77 | |||
78 | 5. *Generate files needed by GNU coding standards:* GNU coding | ||
79 | standards require certain files in order for the project to be | ||
80 | compliant. This command creates those files: $ touch NEWS README | ||
81 | AUTHORS ChangeLog | ||
82 | |||
83 | 6. *Generate the configure file:* This command generates the | ||
84 | ``configure``: $ automake -a | ||
85 | |||
86 | 7. *Cross-compile the project:* This command compiles the project using | ||
87 | the cross-compiler. The | ||
88 | :term:`CONFIGURE_FLAGS` | ||
89 | environment variable provides the minimal arguments for GNU | ||
90 | configure: $ ./configure ${CONFIGURE_FLAGS} | ||
91 | |||
92 | 8. *Make and install the project:* These two commands generate and | ||
93 | install the project into the destination directory: $ make $ make | ||
94 | install DESTDIR=./tmp | ||
95 | |||
96 | 9. *Verify the installation:* This command is a simple way to verify | ||
97 | the installation of your project. Running the command prints the | ||
98 | architecture on which the binary file can run. This architecture | ||
99 | should be the same architecture that the installed cross-toolchain | ||
100 | supports. $ file ./tmp/usr/local/bin/hello | ||
101 | |||
102 | 10. *Execute your project:* To execute the project in the shell, simply | ||
103 | enter the name. You could also copy the binary to the actual target | ||
104 | hardware and run the project there as well: $ ./hello As expected, | ||
105 | the project displays the "Hello World!" message. | ||
106 | |||
107 | Passing Host Options | ||
108 | -------------------- | ||
109 | |||
110 | For an Autotools-based project, you can use the cross-toolchain by just | ||
111 | passing the appropriate host option to ``configure.sh``. The host option | ||
112 | you use is derived from the name of the environment setup script found | ||
113 | in the directory in which you installed the cross-toolchain. For | ||
114 | example, the host option for an ARM-based target that uses the GNU EABI | ||
115 | is ``armv5te-poky-linux-gnueabi``. You will notice that the name of the | ||
116 | script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the | ||
117 | following command works to update your project and rebuild it using the | ||
118 | appropriate cross-toolchain tools: $ ./configure | ||
119 | --host=armv5te-poky-linux-gnueabi \\ --with-libtool-sysroot=sysroot_dir | ||
120 | |||
121 | .. note:: | ||
122 | |||
123 | If the | ||
124 | configure | ||
125 | script results in problems recognizing the | ||
126 | --with-libtool-sysroot= | ||
127 | sysroot-dir | ||
128 | option, regenerate the script to enable the support by doing the | ||
129 | following and then run the script again: | ||
130 | :: | ||
131 | |||
132 | $ libtoolize --automake | ||
133 | $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ | ||
134 | [-I dir_containing_your_project-specific_m4_macros] | ||
135 | $ autoconf | ||
136 | $ autoheader | ||
137 | $ automake -a | ||
138 | |||
139 | |||
140 | Makefile-Based Projects | ||
141 | ======================= | ||
142 | |||
143 | For Makefile-based projects, the cross-toolchain environment variables | ||
144 | established by running the cross-toolchain environment setup script are | ||
145 | subject to general ``make`` rules. | ||
146 | |||
147 | To illustrate this, consider the following four cross-toolchain | ||
148 | environment variables: | ||
149 | :term:`CC`\ =i586-poky-linux-gcc -m32 | ||
150 | -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux | ||
151 | :term:`LD`\ =i586-poky-linux-ld | ||
152 | --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux | ||
153 | :term:`CFLAGS`\ =-O2 -pipe -g | ||
154 | -feliminate-unused-debug-types | ||
155 | :term:`CXXFLAGS`\ =-O2 -pipe -g | ||
156 | -feliminate-unused-debug-types Now, consider the following three cases: | ||
157 | |||
158 | - *Case 1 - No Variables Set in the ``Makefile``:* Because these | ||
159 | variables are not specifically set in the ``Makefile``, the variables | ||
160 | retain their values based on the environment. | ||
161 | |||
162 | - *Case 2 - Variables Set in the ``Makefile``:* Specifically setting | ||
163 | variables in the ``Makefile`` during the build results in the | ||
164 | environment settings of the variables being overwritten. | ||
165 | |||
166 | - *Case 3 - Variables Set when the ``Makefile`` is Executed from the | ||
167 | Command Line:* Executing the ``Makefile`` from the command line | ||
168 | results in the variables being overwritten with command-line content | ||
169 | regardless of what is being set in the ``Makefile``. In this case, | ||
170 | environment variables are not considered unless you use the "-e" flag | ||
171 | during the build: $ make -e file If you use this flag, then the | ||
172 | environment values of the variables override any variables | ||
173 | specifically set in the ``Makefile``. | ||
174 | |||
175 | .. note:: | ||
176 | |||
177 | For the list of variables set up by the cross-toolchain environment | ||
178 | setup script, see the " | ||
179 | Setting Up the Cross-Development Environment | ||
180 | " section. | ||