Bug #108119 Document how to build/use libmysqlclient on Windows/Mac
Submitted: 11 Aug 2022 13:41 Modified: 26 Dec 2022 5:38
Reporter: Igor Korot Email Updates:
Status: Verified Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:8.0 OS:Any
Assigned to: CPU Architecture:Any

[11 Aug 2022 13:41] Igor Korot
Description:
This is a child ticket of 108113, but as I can't re-open a ticket and nobody can I am forced to make a new one!!!!

Let me answer:

1. How many different distribution of Windows there is? Just one - Windows.
2  How many different distribution of OSX there is? Just one - OSX.

This BUG is about building and using NEW (meaning - it should be better and easier)) C client library for mySQL on Windows and OSX. Nowhere in my report I mentioned *nix, which has multiple distributions, where mySQL team does not have control over.

The second point of your reply - please check the documentation of the Connector C from 5.x series. It clearly explains how to use the library and then how to build it for 2 most poplar compilers (MSVC and MinGW) and then how to use it (include mysql.h and which directory to use for include and library search path.
Moreover, one absolutely has to build DEBUG version of the library for Windows and OSX, because mySQL team does NOT provide them for Windows and OSX.

Please explain clearly how to build the DEBUG version of the library (and only library) and then how to use it.

Thank you.

Please don't close the bg as you are forcing me to open a new one as I can't re-open a bug to place a comment.

How to repeat:
N/A
[11 Aug 2022 23:31] MySQL Verification Team
How to build the MySQL Client library Release and Debug on Windows?

Read: https://dev.mysql.com/doc/c-api/8.0/en/c-api-implementations.html

...or you can use a MySQL Server source distribution and build the C API files yourself. Building MySQL Server also builds libmysqlclient; see Installing MySQL from Source. It cannot be built alone, but configuring with the optional -DWITHOUT_SERVER=ON CMake option is related.

https://dev.mysql.com/doc/refman/8.0/en/source-installation.html

On my environment on Windows 10 having the Server Source files stuff and a Microsoft Visual Studio install, to create the MySQL.sln VS project file I use i.e:

c:\build\2022JAN19\mysql-8.0>cmake . -DWITH_DEBUG=1 -G "Visual Studio 16 2019"  -DINSTALL_MYSQLKEYRINGDIR=C:\dbs\8.0\keyring\ -DDOWNLOAD_BOOST=1 -DWITH_BOOST=C:\build -DWITH_SSL=C:\OpenSSL-Win64 -DFORCE_INSOURCE_BUILD=1

Using VS open the MySQL.sln project file and select Debug option Build, after the compilation success I have:

c:\build\2022JAN19\mysql-8.0>dir libmysql\Debug
 Volume in drive C has no label.
 Volume Serial Number is BA9C-8BFC

 Directory of c:\build\2022JAN19\mysql-8.0\libmysql\Debug

01/20/2022  12:30 PM    <DIR>          .
01/20/2022  12:30 PM    <DIR>          ..
01/20/2022  12:30 PM            18,372 libmysql.exp
01/20/2022  12:30 PM            30,676 libmysql.lib
               2 File(s)         49,048 bytes
               2 Dir(s)  691,896,471,552 bytes free

All the above is documented on our Manual.
[12 Aug 2022 1:27] Igor Korot
Hi,

> How to build the MySQL Client library Release and Debug on Windows?

> Read: https://dev.mysql.com/doc/c-api/8.0/en/c-api-implementations.html

I read that page multiple times but it was not any more clear than when I started reading it. ;-)
All does it says is to basically install mySQL Server which will install the libmysqlclient.
Problem is - my server is already built and it is running on anothr machine on my network. So I don't need to build it - I just need a client.
We are talking about client/server architecture, right?

> ...or you can use a MySQL Server source distribution and build the C API
> files yourself. Building MySQL Server also builds libmysqlclient; see
> Installing MySQL from Source. It cannot be built alone, but configuring
> with the optional -DWITHOUT_SERVER=ON CMake option is related.

Please see above.

> On my environment on Windows 10 having the Server Source files stuff and
> a Microsoft Visual Studio install, to create the MySQL.sln VS project
> file I use i.e:

It would be nice to know which options are required and which are optional (for building the library, not the server).
As an example - some options might be required to build the server but building the library it could be optional.

Also, thank you for the example. This is exactly what I am talking abut - the old documentation showed the sample command to build the Connector and then explain the required vs optional options. The new documentation lacking it.

However lets continue. In that same document - part 3.2 "Building C API Client Program", subpart "Compiling MySQL Clients on Microsoft Windows", the very first sentence says "To specify header and library file locations, use facilities provided by your development environment".

I'm sorry - what? The old Connector documentation clearly explains where to find 
those files in the source tree. What's worse, there many "mysql.h" files in the source code. Which one I se in the "-I" option? Does it really matter? Are they the same or different? Only you as mySQL Devs knows answer to those questions. Because those answers are not documented.
Now I will find where the library will be created and use it in the "-L" option, but I need to compile my code first.

BTW, a huge thx for not closing the bug.
[12 Aug 2022 7:53] Georgi Kodinov
Hello,

First of all: let me start by saying there's no easy way to compile *JUST* libmysql from the command line. This would be a feature request. The best we can offer is to avoid compiling most of the other binaries. But you'd still need a full server source tree. 

I did some experiments on my windows box. First of all I've loosely followed Lefred's blog (https://lefred.be/content/how-to-build-mysql-8-0-c-api-libmysqlclient/), as cmake is a cross-platform build system. 

Note that, due to a CmakeFile.txt error, even when you compile -DWITHOUT_SERVER=1, it still requires boost. Boost is not needed for the client library though. So, after applying the following diff:

e:\gkodinov\mysql-8.0\bld-client2>git diff
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 727d66011f91..9c7c98e1e7ee 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1537,7 +1537,9 @@ ELSE()
   SET(DEFAULT_TMPDIR "\"${TMPDIR}\"")
 ENDIF()

+IF (NOT WITHOUT_SERVER)
 INCLUDE(cmake/boost.cmake)
+ENDIF()

 IF (LINUX)
   OPTION(WITH_SYSTEMD "Enable installation of systemd support files" OFF)

I've got the following sequence working:

cd e:\gkodinov\mysql-8.0 <== this is where my git source tree is.
mkdir bld-client2
cd bld-client2
cmake -DWITHOUT_SERVER=ON -DWITH_UNIT_TESTS=OFF -DWITH_DEBUG=1 ..
cmake --build . --target libmysql

This produces:

e:\gkodinov\mysql-8.0\bld-client2>ls library_output_directory\Debug
 Volume in drive E is Export
 Volume Serial Number is 4A2B-C7F2

 Directory of e:\gkodinov\mysql-8.0\bld-client2\library_output_directory\Debug

08/12/2022  07:46 AM    <DIR>          .
08/12/2022  07:46 AM    <DIR>          ..
08/12/2022  07:46 AM         9,453,568 libmysql.dll
08/12/2022  07:46 AM         6,713,344 libmysql.pdb
               2 File(s)     16,166,912 bytes
               2 Dir(s)  1,859,537,354,752 bytes free

e:\gkodinov\mysql-8.0\bld-client2>ls libmysql\Debug
 Volume in drive E is Export
 Volume Serial Number is 4A2B-C7F2

 Directory of e:\gkodinov\mysql-8.0\bld-client2\libmysql\Debug

08/12/2022  07:46 AM    <DIR>          .
08/12/2022  07:46 AM    <DIR>          ..
08/12/2022  07:46 AM            18,389 libmysql.exp
08/12/2022  07:46 AM            30,676 libmysql.lib
               2 File(s)         49,065 bytes
               2 Dir(s)  1,859,537,354,752 bytes free

e:\gkodinov\mysql-8.0\bld-client2>ls runtime_output_directory\Debug
 Volume in drive E is Export
 Volume Serial Number is 4A2B-C7F2

 Directory of e:\gkodinov\mysql-8.0\bld-client2\runtime_output_directory\Debug

08/12/2022  07:46 AM    <DIR>          .
08/12/2022  07:46 AM    <DIR>          ..
08/12/2022  07:46 AM         7,059,456 comp_err.exe
08/12/2022  07:46 AM         3,567,616 comp_err.pdb
08/12/2022  07:46 AM         3,407,360 libcrypto-1_1-x64.dll
08/12/2022  07:46 AM         9,453,568 libmysql.dll
08/12/2022  07:46 AM           681,472 libssl-1_1-x64.dll
08/12/2022  07:46 AM           983,552 uca9dump.exe
08/12/2022  07:46 AM           708,608 uca9dump.pdb
               7 File(s)     25,861,632 bytes
               2 Dir(s)  1,859,537,354,752 bytes free
[12 Aug 2022 8:04] Georgi Kodinov
After doing the above I decided to see if I can compile a test binary:

E:\gkodinov\mysql-8.0\bld-client2>type test.cc
#include <mysql.h>

int main() {
  mysql_library_init(0, NULL, NULL);

  MYSQL c;

  mysql_init(&c);

  mysql_real_connect(&c, "localhost", "root", nullptr, "mysql", 3306, nullptr, 0);

  mysql_close(&c);
  mysql_library_end();
}

And I was able to:

E:\gkodinov\mysql-8.0\bld-client2>cl /Zi  test.cc -I ../include -I include libmysql\Debug\libmysql.lib
Microsoft (R) C/C++ Optimizing Compiler Version 19.31.31105 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

test.cc
Microsoft (R) Incremental Linker Version 14.31.31105.0
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:test.exe
/debug
test.obj
libmysql\Debug\libmysql.lib

I believe that now, after all is said and done, this is in essence a cmake feature request (allow one to build the client without requiring the boost libary) and some documentation updates.
[12 Aug 2022 8:22] Georgi Kodinov
Another experiment worth sharing:

I have tried "installing" the binaries as follows:

cd e:\gkodinov\mysql-8.0\
mkdir bld-client3
cd bld-client3
cmake -DWITHOUT_SERVER=ON -DWITH_UNIT_TESTS=OFF -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=e:/gkodinov/mysql-8.0/bld-client3/install  -DWITH_BOOST=c:\boost ..
cmake --build . --target install
cd install
e:\gkodinov\mysql-8.0\bld-client3\install>dir
 Volume in drive E is Export
 Volume Serial Number is 4A2B-C7F2

 Directory of e:\gkodinov\mysql-8.0\bld-client3\install

08/12/2022  08:15 AM    <DIR>          .
08/12/2022  08:15 AM    <DIR>          ..
08/12/2022  08:15 AM    <DIR>          bin
08/12/2022  08:15 AM    <DIR>          docs
08/12/2022  08:15 AM    <DIR>          include
08/12/2022  08:15 AM    <DIR>          lib
06/09/2022  09:26 AM           287,624 LICENSE
06/08/2022  10:56 AM               666 README
08/12/2022  08:15 AM    <DIR>          share
               2 File(s)        288,290 bytes
               7 Dir(s)  1,858,116,661,248 bytes free
e:\gkodinov\mysql-8.0\bld-client3\install>dir lib
 Volume in drive E is Export
 Volume Serial Number is 4A2B-C7F2

 Directory of e:\gkodinov\mysql-8.0\bld-client3\install\lib

08/12/2022  08:15 AM    <DIR>          .
08/12/2022  08:17 AM    <DIR>          ..
08/12/2022  08:09 AM         9,453,056 libmysql.dll
08/12/2022  08:09 AM            30,676 libmysql.lib
08/12/2022  08:09 AM         6,713,344 libmysql.pdb
08/12/2022  08:11 AM        50,155,822 mysqlclient.lib
08/12/2022  08:15 AM    <DIR>          plugin
               4 File(s)     66,352,898 bytes

Consequently, the following worked:

E:\gkodinov\mysql-8.0\bld-client3\install>cl /Zi  test.cc -I include lib\libmysql.lib
Microsoft (R) C/C++ Optimizing Compiler Version 19.31.31105 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

test.cc
Microsoft (R) Incremental Linker Version 14.31.31105.0
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:test.exe
/debug
test.obj
lib\libmysql.lib

Note that in order to achieve this, you will need boost, since mysqlpump client command line tool requires it.

Thus, the above diff is experimental only and should be used with caution.
[12 Aug 2022 8:43] Georgi Kodinov
Final note: you'd of course need openssl. 
I had mine installed in C:/OpenSSL-Win64/

You can compile openssl following https://github.com/openssl/openssl/blob/OpenSSL_1_1_1-stable/INSTALL:

perl Configure VC-WIN64A --prefix=C:\OpenSSL-Win64 --openssldir=SSL
nmake
nmake install
[12 Aug 2022 11:44] MySQL Verification Team
Hi Mr. Korot,

This is now verified as a documentation bug.
[12 Aug 2022 14:23] Igor Korot
Hi, Georgi,
First let me tell you that CMake is NOT a build system - it is configuration software. CMake can not build anything on its own - it needs a compiler/linker.

Now, I don't care about building from command line - I will be perfectly OK with building from inside MSVC However, all those experiments gives me a starting point, because I wasn't able to find the requred info in the documentation.

It wold also be intere3sting if you can explain in documentation how to do all that from the CMake GUI. Because it is much easier and cleaner.

Now to the experiments:

1. For the Debug build the library name should contain "d" suffix. When you showed the listings, I didn't see it anywhere. And you were building the Debug version.
2. It is a documentation bug because nowhere it was explained how to build the library with the actual command. And then what options to use to build an actual client - see my OP as a reference
3. Is OpenSSL a required library? Can I build without it? What options I should supply to tell MSVC where to find it if its an absolute necessity?

Those questions are the ones that needs to be addressed in the documentation as it is an official source of information.

On the side note - it would be great if this can be also explained for OSX.
Unless you want me to make a separate ticket just for building on Mac

Thank you.
[12 Aug 2022 14:26] Igor Korot
As another side note - I don't understand why do I need to have the whole server in order to build the client portion. It was NOT the case with Connector-C

But that's completely separate topic...
[16 Aug 2022 13:11] MySQL Verification Team
Hi ,

Thank you for your comments.
[17 Dec 2022 4:58] Igor Korot
Hi,
I want to update this topic with the following question:

How do I tell CMake/MSVC that I want to build 32-bit library and not a 64-bit one?

If Georgi or anyone else of the mySQL team can answer - it would be great.
[17 Dec 2022 5:09] Igor Korot
One more thing-
It wold be nice if I could download ODBC driver for Windows and just install it.
[19 Dec 2022 8:14] Georgi Kodinov
Please stick to https://dev.mysql.com/doc/refman/8.0/en/bug-reports.html
[26 Dec 2022 5:38] Igor Korot
@GeorgiKodinov<
You should probably should mention that building 32-bit library is not supported anymore.
I don't know when you dropped it, but this should be mentioned as well in the docs.

Or there should be mentioning on how to build the library in 32bit mode...

The reason for that is when I tried to execute the command given in your comments on my Windows 8.1 64bit, I got an error message:

"Building in 32bit is not supported. Please rerun configuration with the "-G Microsoft Visual Studio 15 2017 Win64"

And this was successful.

The way I tried it is as follows:

1. Open Command Prompt by typing "cmd" in the Search Bar.
2 Supply the original configuration command from your post.
3 Get the error above
4 Add the suggested clause.
5 Configuring and building was successful

Thank you.
[3 Jan 2023 12:39] MySQL Verification Team
Hi Mr. Korot,

Thank you for your contribution.