doc/src/qt3to4.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page qt3to4.html
  44     \title qt3to4 - The Qt 3 to 4 Porting Tool
  45
  46     \ingroup porting
  47     \keyword qt3to4
  48
  49     The \c qt3to4 tool provides help when moving a project from Qt 3
  50     to Qt 4. It is designed to automate the most tedious part of the
  51     porting effort.
  52
  53     See \l{Porting to Qt 4} and \l{Porting .ui Files to Qt 4} for
  54     more information about porting Qt 3 applications to Qt 4.
  55
  56     \section1 Usage
  57
  58     \c qt3to4 can be run either on individual C++ source or header
  59     files, or on an entire project specified by a \c qmake \c .pro
  60     file:
  61
  62     \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 0
  63
  64     In project mode, \c qt3to4 reads the \c .pro file and converts
  65     all files specified in it. The tool modifies the files in place.
  66     You might want to make a copy of your project before you run the
  67     tool.
  68
  69     \section1 Porting Rules
  70
  71     The Qt porting tool loads its porting rules from an XML file
  72     called \c q3porting.xml located in Qt's \c tools/porting/src directory.
  73     By editing this file, you can add your own rules or remove some
  74     rules.
  75
  76     The standard \c q3porting.xml file specifies the following
  77     conversions:
  78
  79     \list
  80     \o  Rename classes that are now part of the Qt 3 support
  81         library (e.g., replace \c QFileDialog with \c{Q3FileDialog}).
  82     \o  Prefix or rename enum values that have been moved or
  83         renamed (e.g., replace \c QButton::On with \c{QCheckBox::On}) or
  84         members of the Qt namespace (e.g., replace \c QWidget::red with
  85         \c{Qt::red}).
  86     \o  Add \c #include directives that might be needed in Qt 4.
  87     \endlist
  88
  89     \section2 Location of the qt3porting.xml File
  90
  91     You can now specify the location of the \c qt3porting.xml file with the
  92     \c{-f} command line option. This is useful if you want to use a modified
  93     file with your own rules.
  94
  95     If you you don't want to maintain a modified \c qt3porting.xml it is
  96     possible to create a "patch" file that includes the original file and adds
  97     or disables rules. The syntax for this file looks like this:
  98
  99     \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 1
 100
 101     \section1 Logging
 102
 103     The porting tool logs all changes to a file called \c
 104     portinglog.txt in the current directory. This file lists all
 105     changes made to the source files.
 106
 107     \section1 Advanced Usage
 108
 109     When porting, \c qt3to4 parses the source files and ports the
 110     contents according to the C++ language rules. This C++ parsing
 111     step can be disabled with the \c -disableCppParsing option.
 112
 113     If C++ parsing is enabled, \c qt3to4 must be able to locate the
 114     headers included from the source files. Necessary headers include
 115     the public Qt headers and  any headers that declares names that
 116     may conflict with names in the public Qt headers. The standard
 117     C++ headers and system headers are usually not needed.
 118
 119     You can tell \c qt3to4 where to look for headers by using the
 120     \c{-I} command-line option. Qt 3.3 header information is built
 121     in, so it is normaly not necessary to specify the location of the
 122     Qt headers. If you are porting from a different version of Qt 3,
 123     you may want to disable the built-in headers with
 124     \c{-disableBuiltInQt3Headers}, and then add the path to the
 125     actual headers with the \c{-I} option.
 126
 127     When porting a project, \c qt3to4 will read the \c INCLUDEPATH
 128     and \c DEPENDPATH variables from the \c .pro file and add the
 129     paths specified here to the list of include search directories.
 130
 131     To see which headers that are not found, use the \c{-missingFileWarnings}
 132     option.
 133
 134     \section1 Limitations
 135
 136     In some cases, you might get compiler errors because of identifiers
 137     in the global namespace (e.g., \c CTRL). Adding
 138
 139     \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 2
 140
 141     at the beginning of the source file that contains
 142     the indentifier solves the problem.
 143
 144     \section1 Legal Notices
 145
 146     Some source code in \c qt3to4 is licensed under specific highly
 147     permissive licenses from the original authors. Nokia gratefully
 148     acknowledges these contributions to \c qt3to4 and all uses of
 149     \c qt3to4 should also acknowledge these contributions and quote the
 150     following license statements in an appendix to the documentation.
 151
 152     \list
 153     \o \l{Contributions to the Following qt3to4 Files: treewalker.h,
 154     treedump.cpp, treedump.h, treewalker.cpp}
 155     \endlist
 156 */
 157
 158 /*!
 159     \page qt3to4-treewalker.html
 160     \title Contributions to the Following qt3to4 Files: treewalker.h, treedump.cpp, treedump.h, treewalker.cpp
 161     \ingroup licensing
 162     \brief License information for contributions to the qt3to4 source code.
 163
 164     \legalese
 165     Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). \BR
 166     Copyright (C) 2005 Roberto Raggi
 167
 168     Permission is hereby granted, free of charge, to any person obtaining
 169     a copy of this software and associated documentation files (the
 170     "Software"), to deal in the Software without restriction, including
 171     without limitation the rights to use, modify, market, reproduce,
 172     grant sublicenses and distribute subject to the following
 173     conditions:  The above copyright notice and this permission notice
 174     shall be included in all copies or substantial portions of the
 175     Software.  These files are provided AS IS with NO WARRANTY OF ANY
 176     KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTIBILITY AND FITNESS
 177     FOR A PARTICULAR PURPOSE.
 178     \endlegalese
 179 */