Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-install.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-install.html
30
31     \title Installing Qt for Embedded Linux
32     \ingroup qt-embedded-linux
33     \ingroup installation
34     \brief How to install Qt for Embedded Linux.
35
36     This document describes how to install \l{Qt for Embedded Linux} in your
37     development environment:
38
39     \tableofcontents
40
41     Please see the \l{Cross-Compiling Qt for Embedded Linux Applications}{cross
42     compiling} and \l{Deploying Qt for Embedded Linux Applications}{deployment}
43     documentation for details on how to install \l{Qt for Embedded Linux} on
44     your target device.
45
46     Note also that this installation procedure is written for Linux,
47     and that it may need to be modified for other platforms.
48
49     \section1 Step 1: Installing the License File (commercial editions only)
50
51     If you have the commercial edition of \l{Qt for Embedded Linux}, the first step
52     is to install your license file as \c $HOME/.qt-license.
53
54     For the open source version you do not need a license file.
55
56     \section1 Step 2: Unpacking the Archive
57
58     First uncompress the archive in the preferred location, then
59     unpack it:
60
61     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 0
62
63     This document assumes that the archive is unpacked in the
64     following directory:
65
66     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 1
67
68     \section1 Step 3: Building the Library
69
70     Before building the \l{Qt for Embedded Linux} library, run the \c
71     ./configure script to configure the library for your development
72     architecture. You can list all of the configuration system's
73     options by typing
74
75     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc embedded help
76
77     The \l{Configuration Options for Qt} page gives a brief overview
78     of these.
79
80     Note that by default, \l{Qt for Embedded Linux} is configured for
81     installation in the \c{/usr/local/Trolltech/QtEmbedded-%VERSION%}
82     directory, but this can be changed by using the \c{-prefix}
83     option. Alternatively, the \c{-prefix-install} option can be used
84     to specify a "local" installation within the source directory.
85
86     The configuration system is also designed to allow you to specify
87     your platform architecture:
88
89     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 2
90
91     In general, all Linux systems which have framebuffer support can
92     use the \c generic architecture. Other typical architectures are
93     \c x86, \c arm and \c mips.
94
95     \note If you want to build Qt for Embedded Linux for use with a virtual
96     framebuffer, pass the \c{-qvfb} option to the \c configure
97     script.
98
99     To create the library and compile all the demos, examples, tools,
100     and tutorials, type:
101
102     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 3
103
104     On some systems the \c make utility is named differently, e.g. \c
105     gmake. The \c configure script tells you which \c make utility to
106     use.
107
108     If you did not configure \l{Qt for Embedded Linux} using the \c{-prefix-install}
109     option, you need to install the library, demos, examples, tools,
110     and tutorials in the appropriate place. To do this, type:
111
112     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 4
113
114     and enter the root password.
115
116     \note You can use the \c INSTALL_ROOT environment variable to specify
117     the location of the installed files when invoking \c{make install}.
118
119     \section1 Step 4: Adjusting the Environment Variables
120
121     In order to use \l{Qt for Embedded Linux}, the \c PATH variable must be extended
122     to locate \c qmake, \c moc and other \l{Qt for Embedded Linux} tools, and the \c
123     LD_LIBRARY_PATH must be extended for compilers that do not support
124     \c rpath.
125
126     To set the \c PATH variable, add the following lines to your \c
127     .profile file if your shell is bash, ksh, zsh or sh:
128
129     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 5
130
131     In case your shell is csh or tcsh, add the following line to the
132     \c .login file instead:
133
134     \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 6
135
136     If you use a different shell, please modify your environment
137     variables accordingly.
138
139     For compilers that do not support \c rpath you must also extend
140     the \c LD_LIBRARY_PATH environment variable to include
141     \c /usr/local/Trolltech/QtEmbedded-%VERSION%/lib. Note that on Linux
142     with GCC, this step is not needed.
143
144     \section1 Step 5: Building the Virtual Framebuffer
145
146     For development and debugging, \l{Qt for Embedded Linux} provides a virtual
147     framebuffer as well as the option of running \l{Qt for Embedded Linux} as a VNC
148     server. For a description of how to install the virtual
149     framebuffer and how to use the VNC protocol, please consult the
150     documentation at:
151
152     \list
153        \o \l {The Virtual Framebuffer}
154        \o \l {The VNC Protocol and Qt for Embedded Linux}
155     \endlist
156
157     Note that the virtual framebuffer requires a Qt for X11
158     installation. See \l {Installing Qt for X11 Platforms} for details.
159
160     The Linux framebuffer, on the other hand, is enabled by default on
161     all modern Linux distributions. For information on older versions,
162     see \l http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html. To test
163     that the Linux framebuffer is set up correctly, use the program
164     provided by the \l {Testing the Linux Framebuffer} document.
165
166     That's all. \l{Qt for Embedded Linux} is now installed.
167
168     \table 100%
169     \row
170     \o
171     \bold {Customizing the Qt for Embedded Linux Library}
172
173     When building embedded applications on low-powered devices,
174     reducing the memory and CPU requirements is important.
175
176     A number of options tuning the library's performance are
177     available. But the most direct way of saving resources is to
178     fine-tune the set of Qt features that is compiled. It is also
179     possible to make use of accelerated graphics hardware.
180
181     \list
182         \o \l {Fine-Tuning Features in Qt}
183         \o \l {Qt Performance Tuning}
184         \o \l {Adding an Accelerated Graphics Driver to Qt for Embedded Linux}
185     \endlist
186
187     \endtable
188 */