source: trunk/doc/src/platforms/mac-differences.qdoc@ 564

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page mac-differences.html
    \title Qt for Mac OS X - Specific Issues
    \brief A description of issues with Qt that are specific to Mac OS X.
    \ingroup platform-specific

    This file outlines known issues and possible workarounds when
    using Qt on Mac OS X. Contact Qt's technical support team if you find
    additional issues which are not covered here. (See also the
    document \l{qtmac-as-native.html} {Qt is Mac OS X Native}.)

    \tableofcontents

    \section1 GUI Applications

    Mac OS X handles most applications as "bundles". A bundle is a
    directory structure that groups related files together (e.g.,
    widgets.app/). GUI applications in particular must be run from a
    bundle or by using the open(1), because Mac OS X needs the bundle
    to dispatch events correctly, as well as for accessing the menu
    bar.

    If you are using older versions of GDB you must run with the full
    path to the executable.  Later versions allow you to pass the
    bundle name on the command line.

    \section1 Painting

    Mac OS X always double buffers the screen so the
    Qt::WA_PaintOnScreen attribute has no effect. Also it is
    impossible to paint outside of a paint event so
    Qt::WA_PaintOutsidePaintEvent has no effect either.

    \section1 Library Support

    \section2 Qt libraries as frameworks

    By default, Qt is built as a set of frameworks. Frameworks is the
    Mac OS X "preferred" way of distributing libraries. There are
    definite advantages to using them. See
    \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html}
    {Apple's Framework Programming Guide} for more information.

    In general, this shouldn't be an issue because qmake takes care of
    the specifics for you. The
    \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html}
    {Framework Programming Guide} discusses issues to keep in mind
    when choosing frameworks over the more typical, dynamic libraries.
    However, one point to remember is: \bold {Frameworks always link
    with "release" versions of libraries}.

    If you actually want to use a \e{debug} version of a Qt framework,
    you must ensure that your application actually loads that debug
    version. This is often done by using the DYLD_IMAGE_SUFFIX
    environment variables, but that way often doesn't work so well.
    Instead, you can temporarily swap your debug and release versions,
    which is documented in
    \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB}
    {Apple's "Debugging Magic" technical note}.

    If you don't want to use frameworks, simply configure Qt with
    \c{-no-framework}.

    \section2 Bundle-Based Libraries

    If you want to use some dynamic libraries in your Mac OS X
    application bundle (the application directory), create a
    subdirectory named "Frameworks" in the application bundle
    directory and place your dynamic libraries there. The application
    will find a dynamic library if it has the install name
    \e{@executable_path/../Frameworks/libname.dylib}.

    If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting:

    \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0

    Alternatively, you can modify the install name using the
    install_name_tool(1) on the command line. See its manpage for more
    information.

    Note that the \c DYLD_LIBRARY_PATH environment variable will
    override these settings, and any other default paths, such as a
    lookup of dynamic libraries inside \c /usr/lib and similar default
    locations.

    \section2 Combining Libraries

    If you want to build a new dynamic library combining the Qt 4
    dynamic libraries, you need to introduce the \c{ld -r} flag. Then
    relocation information is stored in the output file, so that
    this file could be the subject of another \c ld run. This is done
    by setting the \c -r flag in the \c .pro file, and the \c LFLAGS
    settings.

    \section2 Initialization Order

    dyld(1) calls global static initializers in the order they are
    linked into your application. If a library links against Qt and
    references globals in Qt (from global initializers in your own
    library), be sure to link your application against Qt before
    linking it against the library.  Otherwise the result will be
    undefined because Qt's global initializers have not been called
    yet.

    \section1 Compile-Time Flags