/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page qt-conf.html

    \title Using qt.conf

    The \c qt.conf file overrides the hard-coded paths that are

    compiled into the Qt library. These paths are accessible using the

    QLibraryInfo class. Without \c qt.conf, the functions in

    QLibraryInfo return these hard-coded paths; otherwise they return

    the paths as specified in \c qt.conf.

    Without \c qt.conf, the Qt libraries will use the hard-coded paths

    to look for plugins, translations, and so on. These paths may not

    exist on the target system, or they may not be

    accesssible. Because of this, you need \c qt.conf to make the Qt

    libraries look elsewhere.

    QLibraryInfo will load \c qt.conf from one of the following locations:

    \list 1

    \o \c :/qt/etc/qt.conf using the resource system

    \o on Mac OS X, in the Resource directory inside the appliction

    bundle, for example \c assistant.app/Contents/Resources/qt.conf

    \o in the directory containing the application executable, i.e.

    QCoreApplication::applicationDirPath() + QDir::separator() + "qt.conf"

    \endlist

    The \c qt.conf file is an INI text file, as described in the \l

    {QSettings::Format}{QSettings} documentation. The file should have

    a \c Paths group which contains the entries that correspond to

    each value of the QLibraryInfo::LibraryLocation enum. See the

    QLibraryInfo documentation for details on the meaning of the

    various locations.

    \table

    \header \o Entry            \o Default Value

    \row \o Prefix              \o QCoreApplication::applicationDirPath()

    \row \o Documentation       \o \c doc

    \row \o Headers             \o \c include

    \row \o Libraries           \o \c lib

    \row \o Binaries            \o \c bin

    \row \o Plugins             \o \c plugins

    \row \o Data                \o \c .

    \row \o Translations        \o \c translations

    \row \o Settings            \o \c .

    \row \o Examples            \o \c .

    \row \o Demos               \o \c .

    \endtable

    Absolute paths are used as specified in the \c qt.conf file. All

    paths are relative to the \c Prefix. On Windows and X11, the \c

    Prefix is relative to the directory containing the application

    executable (QCoreApplication::applicationDirPath()). On Mac OS X,

    the \c Prefix is relative to the \c Contents in the application

    bundle. For example, \c application.app/Contents/plugins/ is the

    default location for loading Qt plugins. Note that the plugins

    need to be placed in specific sub-directories under the

    \c{plugins} directory (see \l{How to Create Qt Plugins} for

    details).

    For example, a \c qt.conf file could contain the following:

    \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 0

    Subgroups of the \c Paths group may be used to specify locations

    for specific versions of the Qt libraries. Such subgroups are of

    the form \c Paths/x.y.z, where x is the major version of the Qt

    libraries, y the minor, and z the patch level. The subgroup that

    most closely matches the current Qt version is used. If no

    subgroup matches, the \c Paths group is used as the fallback. The

    minor and patch level values may be omitted, in which case they

    default to zero.

    For example, given the following groups:

    \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 1

    The current version will be matched as shown:

    \list

    \o 4.0.1 matches \c Paths/4

    \o 4.1.5 matches \c Paths/4.1

    \o 4.6.3 matches \c Paths/4.2.5 (because 4.2.5 is the latest version with the same major version number)

    \o 5.0.0 matches \c Paths

    \o 6.0.2 matches \c Paths/6

    \endlist

*/