Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-crosscompiling.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-crosscompiling.html
30
31     \title Cross-Compiling Qt for Embedded Linux Applications
32     \ingroup qt-embedded-linux
33
34     Cross-compiling is the process of compiling an application on one
35     machine, producing executable code for a different machine or
36     device. To cross-compile a \l{Qt for Embedded Linux} application,
37     use the following approach:
38
39     \tableofcontents
40
41     \note The cross-compiling procedure has the configuration
42     process in common with the installation procedure; i.e., you might
43     not necessarily have to perform all the mentioned actions
44     depending on your current configuration.
45
46     \section1 Step 1: Set the Cross-Compiler's Path
47
48     Specify which cross-compiler to use by setting the \c PATH
49     environment variable. For example, if the current shell is bash,
50     ksh, zsh or sh:
51
52     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 0
53
54     \section1 Step 2: Create a Target Specific qmake Specification
55
56     The qmake tool requires a platform and compiler specific \c
57     qmake.conf file describing the various default values, to generate
58     the appropriate Makefiles. The standard \l{Qt for Embedded Linux}
59     distribution provides such files for several combinations of
60     platforms and compilers. These files are located in the
61     distribution's \c mkspecs/qws subdirectory.
62
63     Each platform has a default specification. \l{Qt for Embedded Linux} will
64     use the default specification for the current platform unless told
65     otherwise. To override this behavior, you can use the \c configure
66     script's \c -platform option to change the specification for the host
67     platform (where compilation will take place).
68
69     The \c configure script's \c -xplatform option is used to provide a
70     specification for the target architecture (where the library will be
71     deployed).
72
73     For example, to cross-compile an application to run on a device with
74     an ARM architecture, using the GCC toolchain, run the configure
75     script at the command line in the following way:
76
77     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 1
78
79     If neither of the provided specifications fits your target device,
80     you can create your own.  To create a custom \c qmake.conf file,
81     just copy and customize an already existing file. For example:
82
83     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 2
84
85     \note When defining a mkspec for a Linux target, the directory must
86     be prefixed with "linux-". We recommend that you copy the entire
87     directory.
88
89     Note also that when providing you own qmake specifcation, you must
90     use the \c configure script's \c -xplatform option to make
91     \l{Qt for Embedded Linux} aware of the custom \c qmake.conf file.
92
93     \section1 Step 3: Provide Architecture Specific Files
94
95     Starting with Qt 4, all of Qt's implicitly shared classes can
96     safely be copied across threads like any other value classes,
97     i.e., they are fully reentrant. This is accomplished by
98     implementing reference counting operations using atomic hardware
99     instructions on all the different platforms supported by Qt.
100
101     To support a new architecture, it is important to ensure that
102     these platform-specific atomic operations are implemented in a
103     corresponding header file (\c qatomic_ARCH.h), and that this file
104     is located in Qt's \c src/corelib/arch directory. For example, the
105     Intel 80386 implementation is located in \c
106     src/corelib/arch/qatomic_i386.h.
107
108     See the \l {Implementing Atomic Operations} documentation for
109     details.
110
111     \section1 Step 4: Provide Hardware Drivers
112
113     Without the proper mouse and keyboard drivers, you will not be
114     able to give any input to your application when it is installed on
115     the target device. You must also ensure that the appropriate
116     screen driver is present to make the server process able to put
117     the application's widgets on screen.
118
119     \l{Qt for Embedded Linux} provides several ready-made mouse, keyboard and
120     screen drivers, see the \l{Qt for Embedded Linux Pointer Handling}{pointer
121     handling}, \l{Qt for Embedded Linux Character Input}{character input} and
122     \l{Qt for Embedded Linux Display Management}{display management}
123     documentation for details.
124
125     In addition, custom drivers can be added by deriving from the
126     QWSMouseHandler, QWSKeyboardHandler and QScreen classes
127     respectively, and by creating corresponding plugins to make use of
128     Qt's plugin mechanism (dynamically loading the drivers into the
129     server application at runtime). Note that the plugins must be
130     located in a location where Qt will look for plugins, e.g., the
131     standard \c plugin directory.
132
133     See the \l {How to Create Qt Plugins} documentation and the \l
134     {tools/plugandpaint}{Plug & Paint} example for details.
135
136     \section1 Step 5: Build the Target Specific Executable
137
138     Before building the executable, you must specify the target
139     architecture as well as the target specific hardware drivers by
140     running the \c configure script:
141
142     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 3
143
144     It is also important to make sure that all the third party
145     libraries that the application and the Qt libraries require, are
146     present in the tool chain. In particular, if the zlib and jpeg
147     libraries are not available, they must be included by running the
148     \c configure script with the \c -L and \c -I options. For example:
149
150     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 4
151
152     The JPEG source can be downloaded from \l http://www.ijg.org/. The
153     \l{Qt for Embedded Linux} distribution includes a version of the zlib source
154     that can be compiled into the Qt for Embedded Linux library. If integrators
155     wish to use a later version of the zlib library, it can be
156     downloaded from the \l http://www.gzip.org/zlib/ website.
157
158     Then build the executable:
159
160     \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 5
161
162     That's all. Your target specific executable is ready for deployment.
163
164     \table 100%
165     \row
166     \o \bold {See also:}
167
168     \l{Qt for Embedded Linux Architecture} and \l{Deploying Qt for Embedded Linux
169     Applications}.
170     \endtable
171 */