Update copyright headers
[qt:qt.git] / 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 */