svn commit - mysqldoc@docsrva: r16852 - trunk/refman-common

[anthony.bedford]

Author: tbedford
Date: 2009-09-29 16:14:51 +0200 (Tue, 29 Sep 2009)
New Revision: 16852

Log:
Initial discussion of dynamically loading the client library at runtime.

Modified:
   trunk/refman-common/connector-cpp-core.xml


Modified: trunk/refman-common/connector-cpp-core.xml
===================================================================
--- trunk/refman-common/connector-cpp-core.xml	2009-09-29 09:50:54 UTC (rev 16851)
+++ trunk/refman-common/connector-cpp-core.xml	2009-09-29 14:14:51 UTC (rev 16852)
Changed blocks: 1, Lines Added: 62, Lines Deleted: 0; 2843 bytes

@@ -1077,6 +1077,68 @@
 
     </section>
 
+    <section id="connector-cpp-dynamic-linking-client-library">
+
+      <title>Dynamically Linking &ccpp; against the MySQL Client Library</title>
+
+      <note>
+        <para>
+          Note this section refers to dynamic linking of the &ccpp; with
+          the client library, not the dynamic linking of the application
+          to &ccpp;.
+        </para>
+      </note>
+
+      <para>
+        An application that uses &ccpp; can be either statically or
+        dynamically linked to the &ccpp; libraries. &ccpp; is usually
+        statically linked to the underlying MySQL Client Library (or
+        Connector/C). Note, that unless otherwise stated, reference to
+        the MySQL Client Library is also taken to include Connector/C,
+        which is a separately packaged, stand alone version of the MySQL
+        Client Library. From &ccpp; version 1.1.0 it is possible to also
+        dynamically link to the underlying MySQL Client Library. The
+        ability of &ccpp; to dynamically link to MySQL Client Library is
+        not enabled by default, and enabling this feature is done
+        through a compile time option, when compiling the &ccpp; source
+        code.
+      </para>
+
+      <para>
+        To use the ablity to dynamically link the client library to
+        &ccpp; the <literal>MYSQLCLIENT_STATIC_BINDING:BOOL</literal>
+        needs to be defined when building the &ccpp; source code:
+      </para>
+
+<programlisting>
+rm CMakeCache.txt
+cmake -DMYSQLCLIENT_STATIC_BINDING:BOOL=1 .
+make clean
+make
+make install
+</programlisting>
+
+      <para>
+        Note that pre-compiled binaries of &ccpp; use static binding
+        with the client library by default.
+      </para>
+
+      <para>
+        Now, in your application, when creating a connection, &ccpp;
+        will select and load a client library at runtime. It will choose
+        the client library by searching defined locations and
+        environment variables depending on the host operating system. It
+        also possible when creating a connection in an application to
+        define an absolute path to the client library to be loaded at
+        runtime. This can be convenient if you have defined a standard
+        location from which you want the client library to be loaded.
+        This is sometimes done to circumvent possible conflicts with
+        other versions of the client library that may be located on the
+        system.
+      </para>
+
+    </section>
+
   </section>
 
   <section id="connector-cpp-apps-windows-visual-studio">