Update QSettings and Mac OS X documentation with App Store information

Add information about changing the location of global Qt settings to
QSettings documentation, and general information about submitting Qt
apps to the Mac App Store to the "Qt for Mac OS X - Specific Issues"
document.

Task-number: QTBUG-16549
Change-Id: Ic0210e8f4d3c3f6369032abd5c1e214b4200b179
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>

3 files changed, 74 insertions, 0 deletions

diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index 7f40229..8fcd833 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -503,3 +503,8 @@
     \externalpage ftp://ftp.qt.nokia.com/pub/qt/solutions/lgpl/qtmotifextension-2.7_1-opensource.tar.gz
     \title Motif Extension
 */
+
+/*!
+    \externalpage https://developer.apple.com/library/mac/#releasenotes/General/SubmittingToMacAppStore/_index.html#//apple_ref/doc/uid/TP40010572
+    \title Submitting to the Mac App Store
+*/
\ No newline at end of file
diff --git a/doc/src/platforms/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc
index 0aa17d0..8672e72 100644
--- a/doc/src/platforms/mac-differences.qdoc
+++ b/doc/src/platforms/mac-differences.qdoc
@@ -280,6 +280,54 @@
     metal windows can also be created by using the
     Qt::WA_MacMetalStyle window attribute.
 
+    \section1 Preparing a Qt application for Mac App Store submission
+
+    \section2 Changing the location of global Qt settings
+
+    By default, global Qt settings are stored in the file com.trolltech.plist,
+    which does not conform with Mac App Store file system usage requirements.
+    Instructions for changing the location can be found in the
+    \l{QSettings#Changing the location of global Qt settings on Mac OS X}{QSettings documentation}.
+
+    \section2 Storage location paths
+
+    If you are using QDesktopServices::storageLocation() to find locations
+    for data or cache files, you should ensure that the application and
+    organization names used by Qt match the values in iTunes Connect. If
+    the values do not match, the paths that storageLocation() returns will
+    not conform with the Mac App Store file system usage requirements.
+    You can set the application and organization names that Qt uses by
+    calling QCoreApplication::setOrganizationName() and QCoreApplication::setApplicationName().
+
+    \section2 Info.plist and application icon
+
+    A custom Info.plist file instead of the qmake-generated one is needed,
+    since the Mac App Store requires some specific keys to be set that
+    are not present in the generated file. See \l{qmake Variable Reference#QMAKE_INFO_PLIST}{QMAKE_INFO_PLIST} for details.
+
+    Information about the required Info.plist contents can be found in
+    Apple's \l{Submitting to the Mac App Store} document.
+
+    You'll also need to provide an icon for your application, as
+    described in \l{Setting the Application Icon#Setting the Application Icon on Mac OS X}{Setting the Application Icon on Mac OS X}.
+
+    \section2 Debug symbols
+
+    To generate the debug symbol information needed for the Mac App Store
+    submission in a release build, add these settings to your .pro file:
+
+    \code
+    QMAKE_CFLAGS_RELEASE = $$QMAKE_CFLAGS_RELEASE_WITH_DEBUGINFO
+    QMAKE_CXXFLAGS_RELEASE = $$QMAKE_CXXFLAGS_RELEASE_WITH_DEBUGINFO
+    QMAKE_OBJECTIVE_CFLAGS_RELEASE = $$QMAKE_OBJECTIVE_CFLAGS_RELEASE_WITH_DEBUGINFO
+    QMAKE_LFLAGS_RELEASE = $$QMAKE_LFLAGS_RELEASE_WITH_DEBUGINFO
+    \endcode
+
+    The debug symbols can be extracted with the dsymutil command as follows:
+
+    \code
+    dsymutil MyApp.app/Contents/MacOS/MyApp -o MyApp.app.dSYM
+    \endcode
 */
 
 /*!
diff --git a/src/corelib/io/qsettings.cpp b/src/corelib/io/qsettings.cpp
index d7c8c50..4f318ae 100644
--- a/src/corelib/io/qsettings.cpp
+++ b/src/corelib/io/qsettings.cpp
@@ -2437,6 +2437,27 @@ void QConfFileSettingsPrivate::ensureSectionParsed(QConfFile *confFile,
     Note that this may affect framework libraries' functionality if they expect
     the settings to be shared between applications.
 
+    \section2 Changing the location of global Qt settings on Mac OS X
+
+    On Mac OS X, the global Qt settings (stored in \c com.trolltech.plist)
+    are stored in the application settings file in two situations:
+
+    \list 1
+    \o If the application runs in a Mac OS X sandbox (on Mac OS X 10.7 or later) or
+    \o If the \c Info.plist file of the application contains the key \c "ForAppStore" with the value \c "yes"
+    \endlist
+
+    In these situations, the application settings file is named using
+    the bundle identifier of the application, which must consequently
+    be set in the application's \c Info.plist file.
+
+    This feature is provided to ease the acceptance of Qt applications into
+    the Mac App Store, as the default behaviour of storing global Qt
+    settings in the \c com.trolltech.plist file does not conform with Mac
+    App Store file system usage requirements. For more information
+    about submitting Qt applications to the Mac App Store, see
+    \l{mac-differences.html#Preparing a Qt application for Mac App Store submission}{Preparing a Qt application for Mac App Store submission}.
+
     \section2 Platform Limitations
 
     While QSettings attempts to smooth over the differences between