Doc/SQL: update sql driver creation instructions

Update the instructions on how to build and distribute the mysql and
postgresql drivers on windows.

Change-Id: Ie4d50c1c34820680d7496b9544eb00fcee17f8e7
Reviewed-by: Andy Shaw <andy.shaw@qt.io>

3 files changed, 95 insertions, 24 deletions

diff --git a/src/plugins/sqldrivers/README b/src/plugins/sqldrivers/README
index 7000fb5613..26418c5e36 100644
--- a/src/plugins/sqldrivers/README
+++ b/src/plugins/sqldrivers/README
@@ -1,5 +1,5 @@
-Please note that the DB2, Oracle and TDS client drivers are not distributed
-with the Qt Open Source Editions.
+Please note that the DB2, MySQL, Oracle and TDS client drivers are not
+distributed with the Qt Open Source Editions.
 
 This is because the client libraries are distributed under a license which
 is not compatible with the GPL license.
diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
index 9709deeccb..12a39d80b2 100644
--- a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
+++ b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc
@@ -70,7 +70,6 @@ BEGIN
 END
 //! [1]
 
-
 //! [3]
 cd $QTDIR/qtbase/src/plugins/sqldrivers
 qmake -- MYSQL_PREFIX=/usr/local
@@ -86,14 +85,15 @@ make install
 
 //! [5]
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
-qmake -- MYSQL_INCDIR=C:/MySQL/include "MYSQL_LIBDIR=C:/MYSQL/MySQL Server <version>/lib/opt"
+qmake -- MYSQL_INCDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/include" MYSQL_LIBDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/lib"
 nmake sub-mysql
+nmake install
 //! [5]
 
 
 //! [6]
 cd $QTDIR/qtbase/src/plugins/sqldrivers
-qmake -- "OCI_INCDIR=$ORACLE_HOME/rdbms/public" OCI_LIBDIR=$ORACLE_HOME/lib "OCI_LIBS=-lclntsh -lwtc9"
+qmake -- OCI_INCDIR="$ORACLE_HOME/rdbms/public" OCI_LIBDIR="$ORACLE_HOME/lib" OCI_LIBS="-lclntsh -lwtc9"
 make sub-oci
 //! [6]
 
@@ -142,6 +142,7 @@ make sub-psql
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
 qmake -- PSQL_INCDIR=C:/psql/include PSQL_LIBDIR=C:/psql/lib/ms
 nmake sub-psql
+nmake install
 //! [15]
 
 
@@ -156,6 +157,7 @@ make sub-tds
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
 qmake
 nmake sub-tds
+nmake install
 //! [17]
 
 
@@ -168,8 +170,9 @@ make sub-db2
 
 //! [20]
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
-qmake -- "DB2_PREFIX=<DB2 home>/sqllib"
+qmake -- DB2_PREFIX="<DB2 home>/sqllib"
 nmake sub-db2
+nmake install
 //! [20]
 
 
@@ -184,6 +187,7 @@ make sub-sqlite
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
 qmake -- -system-sqlite SQLITE3_PREFIX=C:/SQLITE
 nmake sub-sqlite
+nmake install
 //! [23]
 
 
@@ -205,6 +209,7 @@ make sub-ibase
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
 qmake -- IBASE_INCDIR=C:/interbase/include
 nmake sub-ibase
+nmake install
 //! [29]
 
 
@@ -212,17 +217,18 @@ nmake sub-ibase
 cd %QTDIR%\qtbase\src\plugins\sqldrivers
 qmake -- IBASE_INCDIR=C:/interbase/include IBASE_LIBS=-lfbclient
 nmake sub-ibase
+nmake install
 //! [30]
 
 
 //! [32]
-configure OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib "OCI_LIBS=-lclntsh -lnnz10"
+configure OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib OCI_LIBS="-lclntsh -lnnz10"
 make
 //! [32]
 
 //! [33]
 cd $QTDIR/qtbase/src/plugins/sqldrivers
-qmake -- OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib "OCI_LIBS=-Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10"
+qmake -- OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib OCI_LIBS="-Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10"
 make sub-oci
 //! [33]
 
@@ -250,3 +256,42 @@ q.exec(QString("CREATE TABLE %1 (id INTEGER)").arg(tableString));
 // Call toLower() on the string so that it can be matched
 QSqlRecord rec = database.record(tableString.toLower());
 //! [40]
+
+//! [41]
+C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers>qmake -version
+QMake version 3.1
+Using Qt version 5.13.2 in C:/Qt5/5.13.2/mingw73_64/lib
+C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers>qmake -- MYSQL_INCDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/include" MYSQL_LIBDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/lib"
+Info: creating stash file C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers\.qmake.stash
+
+Running configuration tests...
+Checking for DB2 (IBM)... no
+Checking for InterBase... no
+Checking for MySQL... yes
+Checking for OCI (Oracle)... no
+Checking for ODBC... yes
+Checking for PostgreSQL... no
+Checking for SQLite (version 2)... no
+Checking for TDS (Sybase)... no
+Done running configuration tests.
+
+Configure summary:
+
+Qt Sql Drivers:
+  DB2 (IBM) .............................. no
+  InterBase .............................. no
+  MySql .................................. yes
+  OCI (Oracle) ........................... no
+  ODBC ................................... yes
+  PostgreSQL ............................. no
+  SQLite2 ................................ no
+  SQLite ................................. yes
+    Using system provided SQLite ......... no
+  TDS (Sybase) ........................... no
+
+Qt is now configured for building. Just run 'mingw32-make'.
+Once everything is built, you must run 'mingw32-make install'.
+Qt will be installed into 'C:\Qt5\5.13.2\mingw73_64'.
+
+Prior to reconfiguration, make sure you remove any leftovers from the previous build.
+//! [41]
diff --git a/src/sql/doc/src/sql-driver.qdoc b/src/sql/doc/src/sql-driver.qdoc
index c6ac4d17ff..9c26c4089c 100644
--- a/src/sql/doc/src/sql-driver.qdoc
+++ b/src/sql/doc/src/sql-driver.qdoc
@@ -48,7 +48,7 @@
     \header \li Driver name \li DBMS
     \row \li \l{#QDB2}{QDB2} \li IBM DB2 (version 7.1 and above)
     \row \li \l{#QIBASE}{QIBASE} \li Borland InterBase
-    \row \li \l{#QMYSQL}{QMYSQL} \li MySQL
+    \row \li \l{#QMYSQL}{QMYSQL} \li MySQL (version 5.0 and above)
     \row \li \l{#QOCI}{QOCI} \li Oracle Call Interface Driver
     \row \li \l{#QODBC}{QODBC}
          \li Open Database Connectivity (ODBC) - Microsoft SQL Server and other
@@ -70,7 +70,8 @@
     access to the API exposed by the DBMS, and is typically shipped with it.
     Most installation programs also allow you to install "development
     libraries", and these are what you need. These libraries are responsible
-    for the low-level communication with the DBMS.
+    for the low-level communication with the DBMS. Also make sure to install
+    the correct database libraries for your Qt architecture (32 or 64 bit).
 
     \note When using Qt under Open Source terms but with a proprietary
     database, verify the client library's license compatibility with
@@ -91,11 +92,21 @@
     may be necessary to specify these paths using the \c *_INCDIR=,
     \c *_LIBDIR=, or \c *_PREFIX= command-line options. For example,
     if your MySQL files are installed in \c /usr/local/mysql (or in
-    \c{C:\mysql} on Windows), then pass the following parameter to
-    configure: \c MYSQL_PREFIX=/usr/local/mysql
-    (or \c{MYSQL_PREFIX=C:\mysql} for Windows).
+    \c{C:/Program Files/MySQL/MySQL Connector C 6.1} on Windows), then pass the
+    following parameter to configure: \c MYSQL_PREFIX=/usr/local/mysql
+    (or \c{MYSQL_PREFIX="C:/Program Files/MySQL/MySQL Connector C 6.1"} for Windows).
     The particulars for each driver are explained below.
 
+    If something goes wrong and you want qmake to recheck your
+    available drivers, you must remove \e{config.cache} in
+    \e{<QTDIR>/qtbase/src/plugins/sqldrivers} - otherwise qmake will not
+    search for the available drivers again. If you encounter an error during
+    the qmake stage, open \e{config.log} to see what went wrong.
+
+    A typical qmake run (in this case to configure for MySQL) looks like this:
+
+    \snippet code/doc_src_sql-driver.qdoc 41
+
     Due to the practicalities of dealing with external dependencies,
     only the SQLite3 plugin is shipped with binary builds of Qt.
     To be able to add additional drivers to the Qt installation
@@ -112,11 +123,11 @@
     \section1 Driver Specifics
 
     \target QMYSQL
-    \section2 QMYSQL for MySQL 4 and higher
+    \section2 QMYSQL for MySQL 5 and higher
 
     \section3 QMYSQL Stored Procedure Support
 
-    MySQL 5 introduces stored procedure support at the SQL level, but no
+    MySQL 5 has stored procedure support at the SQL level, but no
     API to control IN, OUT, and INOUT parameters. Therefore, parameters
     have to be set and read using SQL commands instead of QSqlQuery::bindValue().
 
@@ -159,16 +170,32 @@
 
     \section3 How to Build the QMYSQL Plugin on Windows
 
-    You need to get the MySQL installation files. Run \c SETUP.EXE and
-    choose "Custom Install". Install the "Libs & Include Files" Module.
-    Build the plugin as follows (here it is assumed that MySQL is
-    installed in \c{C:\MySQL}):
+    You need to get the MySQL installation files (e.g.
+    \e{mysql-installer-web-community-8.0.18.0.msi}). Run the installer,
+    select custom installation and install the MySQL C Connector
+    which matches your Qt installation (x86 or x64).
+    After installation make sure that the needed files are there:
+    \list
+    \li \c {<MySQL dir>/lib/libmysql.lib}
+    \li \c {<MySQL dir>/lib/libmysql.dll}
+    \li \c {<MySQL dir>/include/mysql.h}
+    \endlist
+
+    Build the plugin as follows (here it is assumed that the MySQL
+    C Connector is installed in
+    \c{C:/Program Files/MySQL/MySQL Connector C 6.1}):
 
     \snippet code/doc_src_sql-driver.qdoc 5
 
     If you are not using a Microsoft compiler, replace \c nmake with \c
     mingw32-make in the line above.
 
+    When you distribute your application, remember to include libmysql.dll
+    in your installation package. It must be placed in the same folder
+    as the application executable. libmysql.dll additionally needs the
+    MSVC runtime libraries which can be installed with vcredist.exe
+    (\l {https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads}(vcredist.exe)
+
     \target QOCI
     \section2 QOCI for the Oracle Call Interface (OCI)
 
@@ -398,11 +425,6 @@
 
     \snippet code/doc_src_sql-driver.qdoc 40
 
-    \section3 QPSQL BLOB Support
-
-    Binary Large Objects are supported through the \c BYTEA field type in
-    PostgreSQL server versions >= 7.1.
-
     \section3 QPSQL Forward-only query support
 
     To use forward-only queries, you must build the QPSQL plugin with
@@ -463,6 +485,10 @@
     Users of MinGW may wish to consult the following online document:
     \l{http://www.postgresql.org/docs/current/static/installation-platform-notes.html#INSTALLATION-NOTES-MINGW}{PostgreSQL MinGW/Native Windows}.
 
+    When you distribute your application, remember to include libpq.dll
+    in your installation package. It must be placed in the same folder
+    as the application executable.
+
     \target QTDS
     \section2 QTDS for Sybase Adaptive Server