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