doc/src/emb-features.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page fine-tuning-features.html
  44     \title Fine-Tuning Features in Qt
  45     \ingroup qtce
  46     \ingroup qt-embedded-linux
  47     \brief Describes how to reduce the size of Qt libraries by selecting only
  48     the features that are needed.
  49
  50     In many cases, only a fixed set of applications are deployed on an
  51     embedded device, making it possible to save resources by minimizing
  52     the size of the associated libraries. The Qt installation can easily
  53     be optimized by avoiding to compile in the features that are not
  54     required.
  55
  56     \tableofcontents
  57
  58     A wide range of features are defined, covering classes and technologies
  59     provided by several of Qt's modules.
  60     You can look up the different feature definitions in the
  61     \c{src/corelib/global/qfeatures.txt} file within the Qt source
  62     distribution.
  63
  64     \section1 Simple Customization
  65
  66     \section2 Embedded Linux
  67
  68     To disable a particular feature, just run the \c configure script
  69     for Qt for Embedded Linux with the \c -no-feature-<feature> option.
  70     For example:
  71
  72     \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 1
  73
  74     The feature can easily be enabled again by running \c configure
  75     with the \c -feature-<feature> option.
  76
  77     See also \l{Qt Performance Tuning}.
  78
  79     \section2 Windows CE
  80
  81     To disable a particular feature, just run the \c configure script
  82     with the set of required \c -D<feature> options. For example,
  83     you can use the \c -D option to define \c{QT_NO_THREAD}:
  84
  85     \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 0
  86
  87     The \c -D option only creates a Qt internal define. If you get linker
  88     errors you have to define \c QT_NO_THREAD also for your project.
  89     You can do this by adding \c DEFINES += \c QT_NO_THREAD to your
  90     \c .pro file.
  91
  92     See also \l{Qt Performance Tuning}.
  93
  94     \section1 Managing Large Numbers of Features
  95
  96     If you want to disable a lot of features, it is more comfortable
  97     to use the \c qconfig tool.
  98     You can disable a \e set of features by creating a custom
  99     configuration file that defines the preferred subset of Qt's
 100     functionality. Such a file uses macros to disable the unwanted
 101     features, and can be created manually or by using the \c qconfig
 102     tool located in the \c{tools/qconfig} directory of the Qt source
 103     distribution.
 104
 105     \note The \c qconfig tool is intended to be built against Qt on
 106     desktop platforms.
 107
 108     \bold{Windows CE:} The Qt for Windows CE package contains a \c qconfig
 109     executable that you can run on a Windows desktop to configure the build.
 110
 111     \image qt-embedded-qconfigtool.png
 112
 113     The \c qconfig tool's interface displays all of Qt's
 114     functionality, and allows the user to both disable and enable
 115     features. The user can open and edit any custom configuration file
 116     located in the \c{src/corelib/global} directory. When creating a
 117     custom configuration file manually, a description of the currently
 118     available Qt features can be found in the
 119     \c{src/corelib/global/qfeatures.txt} file.
 120
 121     Note that some features depend on others; disabling any feature
 122     will automatically disable all features depending on it. The
 123     feature dependencies can be explored using the \c qconfig tool,
 124     but they are also described in the \c{src/corelib/global/qfeatures.h}
 125     file.
 126
 127     To be able to apply the custom configuration, it must be saved in
 128     a file called \c qconfig-myfile.h in the \c{src/corelib/global}
 129     directory. Then use the \c configure tool's \c -qconfig option
 130     and pass the configuration's file name without the \c qconfig-
 131     prefix and \c .h extension, as argument.
 132     The following examples show how this is invoked on each of the
 133     embedded platforms for a file called \c{qconfig-myfile.h}:
 134
 135     \bold{Embedded Linux:}
 136
 137     \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 3
 138
 139     \bold{Windows CE:}
 140
 141     \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 2
 142
 143     Qt provides several ready-made custom configuration files,
 144     defining minimal, small, medium and large installations,
 145     respectively. These files are located in the
 146     \c{/src/corelib/global} directory in the Qt source distribution.
 147 */