Changeset 846 for trunk/doc/src/development/qmake-manual.qdoc

Timestamp:

May 5, 2011, 5:36:53 AM (14 years ago)

Author:

Dmitry A. Kuminov

Message:

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

Location:

trunk

Files:

• . (modified) (1 prop)
• doc/src/development/qmake-manual.qdoc (modified) (35 diffs)

trunk/doc/src/development/qmake-manual.qdoc

@@ -1 +1 @@
 /****************************************************************************
 **
-** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
 ** All rights reserved.
 ** Contact: Nokia Corporation (qt-info@nokia.com)
@@ -7 +7 @@
 ** This file is part of the documentation of the Qt Toolkit.
 **
-** $QT_BEGIN_LICENSE:LGPL$
+** $QT_BEGIN_LICENSE:FDL$
 ** 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.
+** 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.
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
 **
 ** If you have questions regarding the use of this file, please contact
@@ -348 +334 @@
                              an application.
     \row    \o vclib         \o Creates a Visual Studio Project file to build a library.
+    \row    \o vcsubdirs     \o Creates a Visual Studio Solution file to build projects in sub-directories.
     \endtable
 
@@ -873 +860 @@
     Developers using Visual Studio to write Qt applications can use the
     Visual Studio integration facilities provided with the
-    \l{Qt Commercial Editions} and do not need to worry about how
+    \l{Qt Commercial Edition} and do not need to worry about how
     project dependencies are managed.
 
@@ -953 +940 @@
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 130
 
-    The default values depend on the version of the Symbian SDK you're using.
+    The default values depend on the version of the Symbian SDK you're using,
+        however, the Qt toolchain sets this to the maximum possible value and this
+        should not be changed.
 
     \section2 Compiler specific options
@@ -972 +961 @@
     Here is how to define them in a project file:
 
-    There are four types of IDs supported: \c UID2, \c UID3, \c SID, and \c VID. They
+    There are four available types of IDs supported: \c UID2, \c UID3, \c SID, and \c VID. They
     are specified like this:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 132
 
-    If \c UID2 is not specified, it defaults to the same value as \c UID3.
+    If \c SID is not specified, it defaults to the same value as \c UID3.
     If \c UID3 is not specified, qmake will automatically generate a \c UID3
     suitable for development and debugging. This value should be manually
     specified for applications that are to be released. In order to obtain
-    an official UID, please contact Nokia. Both \c SID and \c VID default to empty values.
-
-    For more information about unique identifiers and their meaning for
-    Symbian applications, please refer to the Symbian SDK documentation.
-
+    an official UID, please contact \l{Symbian}{http:\\www.symbiansigned.com}.
+        Both \c SID and \c VID default to empty values.
+
+    There exists one UID1 too, but this should not be touched by any application.
+        
+        The UID2 has a specific value for different types of files - e.g. apps/exes
+        are always 0x100039CE. The toolchain will set this for value for the most common file types like,
+        EXE/APP and shared library DLL. 
+        
+        For more information about unique identifiers and their meaning for Symbian applications,
+        please refer to the \l{Symbian SDK documentation}{http://developer.symbian.org/main/documentation/reference/s3/pdk/GUID-380A8C4F-3EB6-5E1C-BCFB-ED5B866136D9.html}
+        
     \section2 Capabilities
 
-    Capabilities define extra priviledges for the application, such as the
+    Capabilities define extra privileges for the application, such as the
     ability to list all files on the file system. Capabilities are defined
     in the project file like this:
@@ -1093 +1089 @@
     \target BLD_INF_RULES
     \section1 BLD_INF_RULES
-    
+
     \e {This is only used on the Symbian platform.}
-    
+
     Generic \c bld.inf file content can be specified with \c BLD_INF_RULES variables. 
     The section of \c bld.inf file where each rule goes is appended to 
     \c BLD_INF_RULES with a dot.
-    
+
     For example:
-    
-    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 146
-    
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 152
+
     This will add the specified statements to the \c prj_exports section of the 
     generated \c bld.inf file.
-    
+
     It is also possible to add multiple rows in a single block. Each double
     quoted string will be placed on a new row in the generated \c bld.inf file.
-    
+
     For example: 
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 143
-       
+
     Any rules you define will be added after automatically generated
     rules in each section.
@@ -1288 +1284 @@
 
     These options only have an effect on the Symbian platform:
-    
+
     \table 95%
     \header \o Option \o Description
@@ -1299 +1295 @@
          Note that this only affects automatically generated bld.inf content;
          the content added via \c BLD_INF_RULES variable is not affected.
+    \row \o localize_deployment \o Makes \c lupdate tool add fields for
+         application captions and package file names into generated \c{.ts}
+         files. Qmake generates properly localized \c{.loc} and \c{.pkg} files
+         based on available translations. Translation file name bodies must
+         end with underscore and the language code for deployment localization
+         to work. E.g. \c{myapp_en.ts}.
+         \bold{Note:} All languages supported by Qt are not supported by Symbian,
+         so some \c{.ts} files may be ignored by qmake.
     \endtable
-    
+
     These options have an effect on Linux/Unix platforms:
 
@@ -1330 +1334 @@
     \section1 DEF_FILE
 
-    \e {This is only used on Windows when using the \c app template}.
-
-    Specifies a \c .def file to be included in the project.
+    \e {This is only used on Windows when using the \c app template,
+    and on Symbian when building a shared DLL}.
+
+    Specifies a \c .def file to be included in the project. On Symbian
+    a directory may be specified instead, in which case the real files
+    will be located under the standard Symbian directories \c bwins and
+    \c eabi.
 
     \target DEPENDPATH
@@ -1363 +1371 @@
     \c{%CSIDL_PROGRAM_FILES%\target}, which usually gets expanded to
     \c{\Program Files\target}. For the Symbian platform, the default target
-is the application private directory on the drive it is installed to.
+    is the application private directory on the drive it is installed to.
 
     It is also possible to specify multiple \c sources to be deployed on
@@ -1376 +1384 @@
     specified by \c{myFiles.path}. On Symbian platform all libraries and executables
     will always be deployed to the \\sys\\bin of the installation drive.
-    
+
     Since the Symbian platform build system automatically moves binaries to certain
     directories under the epoc32 directory, custom plugins, executables or
@@ -1395 +1403 @@
     variable. You can use either \c pkg_prerules or \c pkg_postrules to 
     pass raw data to PKG file. The strings in \c pkg_prerules are added before
-    package-body and \c pkg_postrules after. The strings defined in 
-    \c pkg_postrules or \c pkg_prerules are not parsed by qmake, so they 
-    should be in a format understood by Symbian package generation tools. 
+    package-body and \c pkg_postrules after. \c pkg_prerules is used for
+    defining vendor information, dependencies, custom package headers, and the
+    like, while \c pkg_postrules is used for custom file deployment and
+    embedded sis directives.
+    The strings defined in \c pkg_postrules or \c pkg_prerules are not parsed
+    by qmake, so they should be in a format understood by Symbian package
+    generation tools.
     Please consult the Symbian platform documentation for correct syntax.
-    
-    For example, to deploy DLL and add a new dependency: 
+
+    For example, to deploy DLL and add a new dependency:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 140
@@ -1407 +1419 @@
     pkg file. If no pkg_prerules is defined, qmake makes sure that PKG file
     syntax is correct and it contains all mandatory statements such as:
-    
+
     \list
     \o languages, for example \BR
@@ -1416 +1428 @@
         %{"Vendor-EN", ..., "Vendor-FR"}
         :"Unique vendor name"
-    \endlist    
-    
-    If you decide to override any of these statements, you need to pay 
+    \endlist
+
+    If you decide to override any of these statements, you need to pay
     attention that also other statements stay valid. For example if you
     override languages statement, you must override also package-header
     statement and all other statements which are language specific.
+
+    On the Symbian platform, three separate PKG files are generated:
+
+    \list
+    \o <app>_template.pkg - For application SIS file. Rules suffix: \c{.main}
+    \o <app>_installer.pkg - For smart installer SIS file. Rules suffix: \c{.installer}
+    \o <app>_stub.pkg - For ROM stubs. Rules suffix: \c{.stub}
+    \endlist
+
+    \c pkg_prerules and \c pkg_postrules given without rules suffix will
+    intelligently apply to each of these files, but rules can also be
+    targeted to only one of above files by appending listed rules suffix
+    to the variable name:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 153
 
     On the Symbian platform, the \c default_deployment item specifies
@@ -1429 +1456 @@
     more languages need to be supported by the package file. The supported
     \c default_deployment rules that can be disabled are:
-    
+
     \list
     \o pkg_depends_qt
@@ -1437 +1464 @@
 
     For example:
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 141
-    
+
+    On the Symbian platform, a default deployment is generated for all
+    application projects. You can modify the autogenerated default
+    deployment via following \c DEPLOYMENT variable values:
+
+    \list
+    \o default_bin_deployment - Application executable
+    \o default_resource_deployment - Application resources, including icon
+    \o default_reg_deployment - Application registration file
+    \endlist
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 154
+
+    This will entirely remove the default application deployment.
+
+    On the Symbian platform, you can specify file specific install options
+    with \c{.flags} modifier. Please consult the Symbian platform documentation
+    for supported options.
+
+    For example:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 155
+
+    This will show a message box that gives user an option to cancel the
+    installation and then automatically runs the application after
+    installation is complete.
+
+    \note Automatically running the applications after install may require signing
+    the package with better than self-signed certificate, depending on the phone model.
+    Additionally, some tools such as Runonphone may not work properly with sis
+    packages that automatically run the application upon install.
+
+    On the Symbian platform, the default package name and the default name that
+    appears in application menu is derived from the \c TARGET variable.
+    Often the default is not optimal for displaying to end user. To set a better
+    display name for these purposes, use \c{DEPLOYMENT.display_name} variable:
+
+    \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 156
+
     On the Symbian platform, you can use \c{DEPLOYMENT.installer_header}
     variable to generate smart installer wrapper for your application.
@@ -1464 +1531 @@
     If the application depends on plugins, these plugins have to be specified 
     manually.
-    
+
     \note On the Symbian platform, all plugins supported by this variable
-will be deployed by default with Qt libraries, so generally using this
-variable is not needed.
+    will be deployed by default with Qt libraries, so generally using this
+    variable is not needed.
 
     For example:
@@ -1571 +1638 @@
 
     See also \l{#SOURCES}{SOURCES}.
-    
+
     \target ICON
     \section1 ICON
-    
+
     This variable is used only in MAC and the Symbian platform to set the application icon.
     Please see \l{Setting the Application Icon}{the application icon documentation}
     for more information.
-    
+
     \target INCLUDEPATH
     \section1 INCLUDEPATH
@@ -1611 +1678 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 36
+
+    Note that \c qmake will skip files that are executable. If you need to install
+    executable files, you can unset the files' executable flags.
 
     \target LEXIMPLS
@@ -1667 +1737 @@
 
     \bold{Note:} On the Symbian platform, the build system makes a
-distinction between shared and
+    distinction between shared and
     static libraries. In most cases, qmake will figure out which library you
     are refering to, but in some cases you may have to specify it explicitly to
@@ -1703 +1773 @@
     handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
 
+    \bold{Note:} On the Symbian platform, this variable is ignored.
+
     \target MAKEFILE_GENERATOR
     \section1 MAKEFILE_GENERATOR
@@ -1712 +1784 @@
     \target MMP_RULES
     \section1 MMP_RULES
-    
+
     \e {This is only used on the Symbian platform.}
-    
+
     Generic MMP file content can be specified with this variable. 
-    
+
     For example:
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 137
-    
+
     This will add the specified statement to the end of the generated MMP file.
-    
+
     It is also possible to add multiple rows in a single block. Each double
     quoted string will be placed on a new row in the generated MMP file.
-    
+
     For example: 
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 138
-       
+
     If you need to include a hash (\c{#}) character inside the
     \c MMP_RULES statement, it can be done with the variable 
     \c LITERAL_HASH as follows:
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 139
 
@@ -2005 +2077 @@
 
     This variable is not empty if the warn_off
-    \l{#TEMPLATE}{TEMPLATE} option is specified.  The value of this
+    \l{#CONFIG}{CONFIG} option is specified.  The value of this
     variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
     and rarely needs to be modified.
@@ -2013 +2085 @@
 
     This variable is not empty if the warn_on
-    \l{#TEMPLATE}{TEMPLATE} option is specified.
+    \l{#CONFIG}{CONFIG} option is specified.
     The value of this variable is typically handled by
     \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
@@ -2041 +2113 @@
 
     \bold{Note:} On the Symbian platform, this variable can be used to pass
-architecture specific options to each compiler in the Symbian build system.
-For example:
+    architecture specific options to each compiler in the Symbian build system.
+    For example:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131
@@ -2280 +2352 @@
     then QMAKE_INCDIR_EGL may also need to be set.
 
-    \section1 QMAKE_INCDIR_OPENGL_ES1, QMAKE_INCDIR_OPENGL_ES1CL, QMAKE_INCDIR_OPENGL_ES2
+    \section1 QMAKE_INCDIR_OPENGL_ES1, QMAKE_INCDIR_OPENGL_ES2
 
     These variables contain the location of OpenGL headers files to be added
-    to INCLUDEPATH when building an application with OpenGL ES 1, OpenGL ES 1 Common
-    Lite or OpenGL ES 2 support respectively.
+    to INCLUDEPATH when building an application with OpenGL ES 1
+    or OpenGL ES 2 support respectively.
 
     The value of this variable is typically handled by \c qmake or
@@ -2384 +2456 @@
 
     \e {This is used on Unix platforms only.}
-    
+
     Library paths in this definition are added to the executable at link
     time so that the added paths will be preferentially searched at runtime.
-    
+
     \section1 QMAKE_LFLAGS_QT_DLL
 
@@ -2538 +2610 @@
      \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
 
-    \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES1CL, QMAKE_LIBS_OPENGL_ES2
-
-    These variables contain all the OpenGL libraries for OpenGL ES 1,
-    OpenGL ES 1 Common Lite profile and OpenGL ES 2.
+    \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES2
+
+    These variables contain all the OpenGL libraries for OpenGL ES 1
+    and OpenGL ES 2.
 
     The value of these variables is typically handled by \c qmake or
@@ -2610 +2682 @@
     \section1 QMAKE_LIBS_THREAD
 
-    \e {This is used on Unix platforms only.}
+    \e {This is used on Unix and Symbian platforms only.}
 
     This variable contains all libraries that need to be linked against
@@ -2726 +2798 @@
 
     \section1 QMAKE_RPATH
-    
+
     \e {This is used on Unix platforms only.}
 
@@ -2880 +2952 @@
     The value of this variable is typically handled by \c qmake or
      \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
-     
+
     \target RSS_RULES
     \section1 RSS_RULES
-    
+
     \e {This is only used on the Symbian platform.}    
-    
+
     Generic RSS file content can be specified with this variable. The syntax is 
     similar to \c MMP_RULES and \c BLD_INF_RULES.
-    
+
     For example:
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 144
-    
+
     This will add the specified statement to the end of the \c APP_REGISTRATION_INFO
     resource struct in the generated registration resource file.
     As an impact of this statement, the application will not be visible in application shell.
-    
+
     It is also possible to add multiple rows in a single block. Each double
     quoted string will be placed on a new row in the registration resource file.
-    
+
     For example: 
-    
+
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 145
-    
+
     This example will install the application to MyFolder in the Symbian
     platform application shell. In addition it will make the application to
@@ -2943 +3015 @@
 
     \e {This is only used on the Symbian platform.}
-    
+
     Contains the version number of the underlying S60 SDK; e.g. "5.0".
 
@@ -2979 +3051 @@
 
     This variable, when used with the \l{#TEMPLATE}{\c subdirs template}
-    contains the names of all subdirectories that contain parts of the project
-    that need be built. Each subdirectory must contain its own project file.
+    contains the names of all subdirectories or project files that contain
+    parts of the project that need be built. Each subdirectory specified
+    using this variable must contain its own project file.
 
     For example:
@@ -3024 +3097 @@
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 150
+
+    \target SYMBIAN_VERSION
+    \section1 SYMBIAN_VERSION
+
+    \e {This is only used on the Symbian platform.}
+
+    Contains the version number of the underlying Symbian SDK; e.g. "9.2" or "Symbian3".
 
     \target TARGET