blob: de854772bbdbe50c4adbd892da95fa2894bbf990 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001.. SPDX-License-Identifier: CC-BY-2.0-UK
2
3**********************
4Using the Command Line
5**********************
6
7Recall that earlier the manual discussed how to use an existing
8toolchain tarball that had been installed into the default installation
9directory, ``/opt/poky/DISTRO``, which is outside of the :term:`Build Directory`
10(see the section
11"`Using a Cross-Toolchain
12Tarball) <#using-an-existing-toolchain-tarball>`__". And, that sourcing
13your architecture-specific environment setup script initializes a
14suitable cross-toolchain development environment.
15
16During this setup, locations for the compiler, QEMU scripts, QEMU
17binary, a special version of ``pkgconfig`` and other useful utilities
18are 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
21target hardware on which to run. You can see the "`Setting Up the
22Cross-Development
23Environment <#setting-up-the-cross-development-environment>`__" section
24for the list of cross-toolchain environment variables established by the
25script.
26
27Collectively, these conditions allow you to easily use the toolchain
28outside of the OpenEmbedded build environment on both Autotools-based
29projects and Makefile-based projects. This chapter provides information
30for both these types of projects.
31
32Autotools-Based Projects
33========================
34
35Once you have a suitable cross-toolchain installed, it is very easy to
36develop a project outside of the OpenEmbedded build system. This section
37presents a simple "Helloworld" example that shows how to set up,
38compile, and run the project.
39
40Creating and Running a Project Based on GNU Autotools
41-----------------------------------------------------
42
43Follow these steps to create a simple Autotools-based project:
44
451. *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
492. *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
623. *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
734. *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
785. *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
836. *Generate the configure file:* This command generates the
84 ``configure``: $ automake -a
85
867. *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
928. *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
969. *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
10210. *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
107Passing Host Options
108--------------------
109
110For an Autotools-based project, you can use the cross-toolchain by just
111passing the appropriate host option to ``configure.sh``. The host option
112you use is derived from the name of the environment setup script found
113in the directory in which you installed the cross-toolchain. For
114example, the host option for an ARM-based target that uses the GNU EABI
115is ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
116script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
117following command works to update your project and rebuild it using the
118appropriate 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
140Makefile-Based Projects
141=======================
142
143For Makefile-based projects, the cross-toolchain environment variables
144established by running the cross-toolchain environment setup script are
145subject to general ``make`` rules.
146
147To illustrate this, consider the following four cross-toolchain
148environment 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.