doc/src/deployment/qt-conf.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-conf.html
  30
  31     \title Using qt.conf
  32
  33     The \c qt.conf file overrides the hard-coded paths that are
  34     compiled into the Qt library. These paths are accessible using the
  35     QLibraryInfo class. Without \c qt.conf, the functions in
  36     QLibraryInfo return these hard-coded paths; otherwise they return
  37     the paths as specified in \c qt.conf.
  38
  39     Without \c qt.conf, the Qt libraries will use the hard-coded paths
  40     to look for plugins, translations, and so on. These paths may not
  41     exist on the target system, or they may not be
  42     accesssible. Because of this, you need \c qt.conf to make the Qt
  43     libraries look elsewhere.
  44
  45     QLibraryInfo will load \c qt.conf from one of the following locations:
  46
  47     \list 1
  48
  49     \o \c :/qt/etc/qt.conf using the resource system
  50
  51     \o on Mac OS X, in the Resource directory inside the application
  52     bundle, for example \c assistant.app/Contents/Resources/qt.conf
  53
  54     \o in the directory containing the application executable, i.e.
  55     QCoreApplication::applicationDirPath() + QDir::separator() + "qt.conf"
  56
  57     \endlist
  58
  59     The \c qt.conf file is an INI text file, as described in the \l
  60     {QSettings::Format}{QSettings} documentation. The file should have
  61     a \c Paths group which contains the entries that correspond to
  62     each value of the QLibraryInfo::LibraryLocation enum. See the
  63     QLibraryInfo documentation for details on the meaning of the
  64     various locations.
  65
  66     \table
  67
  68     \header \o Entry            \o Default Value
  69
  70     \row \o Prefix              \o QCoreApplication::applicationDirPath()
  71     \row \o Documentation       \o \c doc
  72     \row \o Headers             \o \c include
  73     \row \o Libraries           \o \c lib
  74     \row \o Binaries            \o \c bin
  75     \row \o Plugins             \o \c plugins
  76     \row \o Imports             \o \c imports
  77     \row \o Data                \o \c .
  78     \row \o Translations        \o \c translations
  79     \row \o Settings            \o \c .
  80     \row \o Examples            \o \c .
  81     \row \o Demos               \o \c .
  82
  83     \endtable
  84
  85     Absolute paths are used as specified in the \c qt.conf file. All
  86     paths are relative to the \c Prefix. On Windows and X11, the \c
  87     Prefix is relative to the directory containing the application
  88     executable (QCoreApplication::applicationDirPath()). On Mac OS X,
  89     the \c Prefix is relative to the \c Contents in the application
  90     bundle. For example, \c application.app/Contents/plugins/ is the
  91     default location for loading Qt plugins. Note that the plugins
  92     need to be placed in specific sub-directories under the
  93     \c{plugins} directory (see \l{How to Create Qt Plugins} for
  94     details).
  95
  96     For example, a \c qt.conf file could contain the following:
  97
  98     \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 0
  99
 100     Subgroups of the \c Paths group may be used to specify locations
 101     for specific versions of the Qt libraries. Such subgroups are of
 102     the form \c Paths/x.y.z, where x is the major version of the Qt
 103     libraries, y the minor, and z the patch level. The subgroup that
 104     most closely matches the current Qt version is used. If no
 105     subgroup matches, the \c Paths group is used as the fallback. The
 106     minor and patch level values may be omitted, in which case they
 107     default to zero.
 108
 109     For example, given the following groups:
 110
 111     \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 1
 112
 113     The current version will be matched as shown:
 114
 115     \list
 116     \o 4.0.1 matches \c Paths/4
 117     \o 4.1.5 matches \c Paths/4.1
 118     \o 4.6.3 matches \c Paths/4.2.5 (because 4.2.5 is the latest version with the same major version number)
 119     \o 5.0.0 matches \c Paths
 120     \o 6.0.2 matches \c Paths/6
 121     \endlist
 122 */