8.0.7 documentation update.

Author: rsomla1

doc/building.txt

@@ -11,10 +11,14 @@ To build Connector/C++, the following tools and libraries are required:
 
 - CMake 2.8.12 or later.
 
+- Boost 1.59 or later if the version of the C++ standard library used does
+  not implement the UTF8 converter (`codecvt_utf8`). Boost is also required
+  when building the legacy connector (see below).
+
 - OpenSSL version 1.0.x if connector is built with OpenSSL.
 
-@note: On some platforms Boost libraries are needed to build the connector.
-       Boost version 1.59.
+- MySQL 8.0 client library if building the legacy connector (see below).
+
 
 Build configuration
 -------------------
@@ -25,54 +29,30 @@ Only out-of-source builds are supported. To configure a build, execute
 $ cmake <Connector/C++ source location>
 ~~~~~~~
 
-If Boost libraries are used and `cmake` can not find the required Boost
-version, or if it is installed in a non-standard location, specify the
+If Boost libraries are required and `cmake` can not find them, specify the
 correct location using the option:
 
 - `-DWITH_BOOST=<Boost location>`
 
-To specify the installation location (see below), use the option:
-
-- `-DCMAKE_INSTALL_PREFIX=<Install location>`
-
-If not specified, the install location defaults to
-`/usr/local/mysql/connector-c++-8.0`
-(`<User home>/MySQL/"MySQL Connector C++ 8.0"` on Windows).
-
 By default a shared library is built. To build a static library, use the option:
 
 - `-DBUILD_STATIC=yes`
 
-Building of the legacy C++ JDBC4 library
-----------------------------------------
-Connector/C++ supports the legacy C++ JDBC4 API, which is placed inside a
-separate library `libmysqlcppconn` or `mysqlcppconn` depending on the Operating
-System.
+The build system generated by `cmake` has install target which, by default, installs to `/usr/local/mysql/connector-c++-8.0`
+(`<User home>/MySQL/"MySQL Connector C++ 8.0"` on Windows). To change this default install location use the option:
 
-In order to enable building of the legacy C++ JDBC4 library the Connector/C++
-needs to be built with the following options:
-
-- `WITH_JDBC` to enable the legacy C++ JDBC4 API. Usage of this option in cmake
-  command looks like this: `-DWITH_JDBC=yes`. By default this option is not
-  enabled and the legacty C++ JDBC4 functionality is not built.
-
-- `MYSQL_DIR` to allow using server libraries such as libmysqlclient if it is
-  not installed at the default location.
-  The command line should look like: `-DMYSQL_DIR=<path_to_mysql_server_dir>`
-
-- `WITH_BOOST` to point to boost location if it is different from the default.
-  The command line should look like: `-DMYSQL_DIR=<path_to_mysql_server_dir>`
+- `-DCMAKE_INSTALL_PREFIX=<Install location>`
 
 
 Configuring SSL libraries
 -------------------------
 Connector/C++ can be built with different SSL libraries.
-Use `-DWITH_SSL=<Option value>' to specify the desired SSL build type:
+Use `-DWITH_SSL=<Option value>` to specify the desired SSL build type:
 
-- bundled   - build with bundled YaSSL code
-- system    - build with external openSSL library installed on the system, the 
+- `bundled`   - build with bundled YaSSL code (the default)
+- `system`    - build with external openSSL library installed on the system, the
               library location is detected by cmake.
-- <path>    - build with external openSSL library installed at specified 
+- `<path>`    - build with external openSSL library installed at specified
               location.
 
 @note when Connector/C++ is configured to be built to use OpenSSL it will make
@@ -83,6 +63,7 @@ Use `-DWITH_SSL=<Option value>' to specify the desired SSL build type:
       it means adding -lssl -lcrypto to the compile/link command.
       In Windows this is handled automatically.
 
+
 Building and testing
 --------------------
 A build can be started with the following cmake invocation in the build
@@ -106,16 +87,10 @@ the Connector/C++ shared library:
 
 - `libmysqlcppconn8.so.1` on Unix
 - `libmysqlcppconn8.1.dylib` on OS X
-- `CCC/mysqlcppconn8-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
+- `CCC/mysqlcppconn8-1-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
   depends on the MSVC version used to build the connector
-  
-If Connector/C++ is built to support the legacy C++ JDBC4 API (WITH_JDBC option
-enabled) the build library directory will have another shared library:
 
-- `libmysqlcppconn.so.7` on Unix
-- `libmysqlcppconn.7.dylib` on OS X
-- `CCC/mysqlcppconn-7-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
-  depends on the MSVC version used to build the connector
+The number 1 in the library name is the major ABI version of the library. It is part of the library name so that different versions of the library can be used at the same time on a single system.
 
 On Unix and OS X also appropriate symbolic links are created. On Windows the
 import library for the DLL is created at `CCC/mysqlcppconn8.lib` (the `CCC/`
@@ -124,15 +99,8 @@ subdirectory is named the same as the build configuration used).
 In the case of a static library build, the output library names are:
 
 - `libmysqlcppconn8-static.a` on Unix and OS X
-- `CCC/mysqlcppconn8-static.lib` and `CCC/mysqlcppconn8-static-mt.lib`
-  on Windows
-
-If Connector/C++ is built to support the legacy C++ JDBC4 API (WITH_JDBC option
-enabled) the build library directory will have another static library:
-
-- `libmysqlcppconn-static.a` on Unix and OS X
-- `CCC/mysqlcppconn-static.lib` and `CCC/mysqlcppconn-static-mt.lib`
-  on Windows
+- `CCC/mysqlcppconn8-static.lib` or `CCC/mysqlcppconn8-static-mt.lib`
+  on Windows (see [Windows Notes] (@ref win_notes)).
 
 ### Testing
 
@@ -165,8 +133,8 @@ $ cmake -DWITH_CONCPP=<Connector/C++ install location> <source location>/testapp
 $ cmake --build . --config CCC
 ~~~~~~~
 
-This should create the `devapi_test`, `xapi_test` and `jdbc_test` executables
-in the `run/` subdirectory of the build location.
+This should create the `devapi_test` and `xapi_test` executables
+in the `run/` subdirectory of the build location. If testing static connector, pass `-DBUILD_STATIC=ON` option when configuring test applications.
 
 @note
   On Windows, if the connector was built with the static runtime by specifying
@@ -177,9 +145,6 @@ in the `run/` subdirectory of the build location.
   The 32/64-bit Windows `cmake` generator (`"Visual Studio 14 2015 Win64"` vs
   `"Visual Studio 14 2015"`) used to build test applications must match
   the one used to build the connector.
-  
-@note in order to build `jdbc_test` the Connector/C++ has to be built
-  with WITH_JDBC, MYSQL_DIR and WITH_BOOST options.
 
 Before running test programs, ensure that a MySQL Server instance is running
 with X Plugin loaded into it. The easiest way of arranging this is to use
@@ -190,36 +155,27 @@ the `mysql-test-run.pl` script from the MySQL Server distribution. In the
 $ perl mysql-test-run.pl --start-and-exit --mysqld=--plugin-load=mysqlx
 ~~~~~~~
 
-This should start a test server instance with X plugin loaded into it. This can
-be confirmed by looking at messages output by the server to the `mysqld.1.err`
-file found in `mysql-test/var/log/` subdirectory. The log file should contain
-a note from the X plugin informing about it being ready to serve connections:
-
-~~~~~~~
-Plugin mysqlx reported: 'X plugin tcp connection enable at port 13009.'
-~~~~~~~
-
-When started like this, the plugin will listen on port 13009 instead of
+This should start a test server instance with X plugin loaded into it. When
+started like this, the plugin will listen on port 13009 instead of
 the standard 33060 one.
 
-Now one can start one of the test programs and see the output similar to the
-one presented below. The `devapi_test` program accepts port number as the first
-argument, with the default value 33060. Thus, if the server was started
-as described above, run the test program with the following URL as a parameter:
+Now you can run one of the test programs and see the output similar to the
+one presented below. Test programs accept a connection string as an argument.
+If the server was started as described above, run the test program with the following connection string as a parameter:
 
 ~~~~~~~
 $ run/devapi_test mysqlx://[email protected]:13009
+$ run/xapi_test mysqlx://[email protected]:13009
 ~~~~~~~
 
-The program uses the `root` user account without any password and assumes
+This invocation uses the `root` user account without any password and assumes
 that there is a `test` schema in the server (these assumptions hold for
-a server started using `mysql-test-run.pl`). Different user credentials can
-be passed as the second and the third argument of `devapi_test` invocation.
+a server started using `mysql-test-run.pl`).
 
 If everything goes well, `devapi_test` should produce output similar to this:
 
 ~~~~~~~
-Creating session on localhost, port 13009 ...
+Creating session on mysqlx://[email protected]:13009 ...
 Session accepted, creating collection...
 Inserting documents...
 - added doc with id: AA71B4BF6B72E511BD76001E684A06F0
@@ -253,31 +209,69 @@ doc#1: {"_id": "A0ABC08DAABAD1110C120800273BD115", "age": 2, "name": "bar", "toy
 Done!
 ~~~~~~~
 
-For the `xapi_test` program, connection details can be given in form of an URL,
-as shown below:
 
-~~~~~~~
-$ run/xapi_test mysqlx://[email protected]:13009
-~~~~~~~
+Building legacy C++ JDBC4 library                            @anchor build_jdbc
+---------------------------------
+
+Apart from the new APIs introduced in version 8.0 of the connector (X DevAPI
+and XAPI), Connector/C++ also supports the legacy API based on JDBC4. This
+legacy API is implemented as a separate library with base name `mysqlcppconn`
+as opposed to `mysqlcppconn8` library implementing the new APIs.
+
+To build the legacy library pass `-DWITH_JDBC=ON` option during cmake
+configuration step (this option is disabled by default). This brings additional
+build dependencies that must be satisfied:
+
+- The MySQL 8.0 client library is needed. If `cmake` can not find it at default
+  locations, pass `-DMYSQL_DIR=<path_to_mysql_server_dir>` option.
+
+- Boost libraries are always required in this case. As explained above, use
+  `WITH_BOOST` option if `cmake` can not find Boost at default locations.
+
+@note
+  The code implementing legacy connector is inside `jdbc/` subdirectory of the
+  source tree. If sources are obtained from a git repository this sub-directory
+  must be fetched separately as a git sub-module. Invoke
+  `git submodule update --init` to populate contents of `jdbc/` subdirectory.
 
-For the `jdbc_test` program the command line would look as this:
+If everything goes well, after building the connector the build location
+should contain additional legacy connector library:
+
+- `libmysqlcppconn.so.7` on Unix
+- `libmysqlcppconn.7.dylib` on OS X
+- `CCC/mysqlcppconn-7-vsXX.dll` on Windows
+
+If building static libraries, the static legacy library has name:
+
+- `libmysqlcppconn-static.a` on Unix and OS X
+- `CCC/mysqlcppconn-static.lib` or `CCC/mysqlcppconn-static-mt.lib`
+  on Windows
+
+
+It is possible to build additional test application `jdbc_test` for testing
+the legacy connector library. To do this, pass `-DWITH_JDBC=ON` cmake option
+when configuring the build of test applications. Also, `MYSQL_DIR`
+and `WITH_BOOST` must be set of cmake can not find required dependencies.
+
+The connection string accepted as argument of `jdbc_test` application must be
+in the form expected by JDBC API. The user name is passed as the 2nd argument.
+For example:
 
 ~~~~~~~
 $ run/jdbc_test tcp://127.0.0.1:13009 root
 ~~~~~~~
 
 
-Windows Notes
+Windows Notes                                                 @anchor win_notes
 -------------
 Connector/C++ uses C++11 language and for that reason it is not possible
 to build it with Microsoft Visual Studio 2010 or earlier.
 
 On Windows one can request that Connector/C++ uses the static runtime library
-(The `/MT*` compiler option) by setting the cmake option
-`-DSTATIC_MSVCRT=yes`
-
+(The `/MT*` compiler option) by setting the cmake option `-DSTATIC_MSVCRT=yes`.
 This might be necessary if code which uses Connector/C++ also uses the static
-runtime.
+runtime.  If building static library in this mode, the `-mt` suffix will
+be added to its name to distinguish it from a library built in `/MD` mode.
 
 Selecting a cmake generator such as `"Visual Studio 14 2015 Win64"` vs
 `"Visual Studio 14 2015"` selects the 64 or 32 bit platform for which

doc/index.txt

@@ -1,43 +1,38 @@
 MySQL Connector/C++ Documentation  {#mainpage}
 =================================
 
-MySQL Connector/C++ is a library for applications written in C or C++ that want
-to communicate with MySQL database servers. Version 8.0 of Connector/C++
+MySQL Connector/C++ is a library for applications written in C or C++ that
+communicate with MySQL database servers. Version 8.0 of Connector/C++
 implements three different APIs which can be used by applications...
 
 - The new [X DevAPI] (@ref devapi) for applications written in C++.
 - The new [XAPI] (@ref xapi) for applications written in plain C.
-- The [legacy JDBC based API]
-  (https://dev.mysql.com/doc/connector-cpp/en/connector-cpp-reference.html),
+- The [legacy JDBC4 based API] (@ref jdbc_ref)
   also implemented in version 1.1 of the connector.
 
 The new APIs give access to MySQL implementing a [document store]
-(https://dev.mysql.com/doc/refman/8.0/en/document-store.html). Consequently,
-code written against these APIs can work only with a MySQL Server with the
-X Plugin enabled in it. This is supported by MySQL Server version 8 or 5.7.12+.
-Apart from accessing the document store, the new APIs allow executing
-traditional SQL queries as well.
+(https://dev.mysql.com/doc/refman/8.0/en/document-store.html). Internally
+these APIs use the new X Protocol to communicate with the MySQL Server.
+Consequently, code written against these APIs can work only with MySQL Server 8
+with the X Plugin enabled in it. Apart from accessing the document store, the
+new APIs allow executing traditional SQL queries as well.
 
-Application written against the JDBC based API of Connector/C++ 1.1 can be also
+Applications written against the JDBC4 based API of Connector/C++ 1.1 can be also
 compiled with Connector/C++ 8.0 which is backward compatible with the earlier
 version. Such code does not require the X Plugin and can communicate with older
-version of the MySQL Server.
+versions of the MySQL Server using the legacy protocol.
 
 The API to be used is chosen by including appropriate set of headers, as
 explained in @ref usage.
- 
+
 More information:
 
 - [Connector/C++ X DevAPI Reference] (@ref devapi_ref)
 - [Connector/C++ XAPI Reference] (@ref xapi_ref)
-- [Connector/C++ legacy C++ API based on JDBC4 Reference] (@ref jdbc_ref)
 - [How to build code that uses Connector/C++](@ref usage)
 - [Building Connector/C++] (@ref building)
 - [Indexing Document Collections] (@ref indexing)
 
-@note
-Code that uses Connector/C++ 8.0 can communicate only with MySQL Server version
-5.7 with X Plugin loaded into it.
 
 <!--
   Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.