| Home | Libraries | People | FAQ | More

## Integrating Boost.MySQL into your project

| Note
Breaking change in Boost 1.85: the compiled library Boost.Charconv is now required. If you're upgrading and getting linker errors, link your executable to the `Boost::charconv` CMake target.

### Header-only mode

The easiest way to start using the library is header-only mode (the default). You will need the following:

- A C++11 compiler (like gcc >=5.4, clang >=3.6, or Visual Studio 2017 or higher).
- The Boost headers and Boost.Charconv. You can obtain them following the official installation instructions for UNIX-like systems and for Windows, or from a package manager. Note that Boost.MySQL does not work with the standalone version of Boost.Asio.
- The OpenSSL headers and libraries. We recommend using your system package manager to obtain them.
- CMake.

Use the following `CMakeLists.txt`, replacing `main.cpp` with your project's source files:

    project(boost_mysql_example LANGUAGES CXX)

    find_package(Boost REQUIRED COMPONENTS charconv)
    find_package(Threads REQUIRED)
    find_package(OpenSSL REQUIRED)

    add_executable(main main.cpp)
    target_link_libraries(main PRIVATE Boost::charconv Threads::Threads OpenSSL::Crypto OpenSSL::SSL)

| Note
`Boost::charconv` is only available in Boost 1.85 and higher. If you're using an older version, use the `Boost::headers` target, instead.

If you're happy with header-only mode, have a look at the tutorial or any of the examples to learn how to use the library.

### Separate compilation mode

Header-only mode is simple but can make your project's build times high. If this is the case, we recommend switching to separate compilation mode.

To use it, you must add the following to exactly one `.cpp` file:

    // Contents of boost_mysql.cpp

    // This header file contains all Boost.MySQL implementations.
    // It should be included in exactly one .cpp file.
    // All code using Boost.MySQL in separate build mode, including this file,
    // should define BOOST_MYSQL_SEPARATE_COMPILATION.
    #include <boost/mysql/src.hpp>

All of your code, including this `.cpp` file, should define the `BOOST_MYSQL_SEPARATE_COMPILATION` macro. This is what your `CMakeLists.txt` could look like:

    project(boost_mysql_example LANGUAGES CXX)

    find_package(Boost REQUIRED COMPONENTS charconv)
    find_package(Threads REQUIRED)
    find_package(OpenSSL REQUIRED)

    add_executable(
        main
        # Contains Boost.MySQL sources via #include <boost/mysql/src.hpp>
        boost_mysql.cpp
        # List any other .cpp your exe has here
        main.cpp
    )
    target_link_libraries(main PRIVATE Boost::charconv Threads::Threads OpenSSL::Crypto OpenSSL::SSL)

    # We need to define BOOST_MYSQL_SEPARATE_COMPILATION in any code using Boost.MySQL in separate-build mode
    target_compile_definitions(main PRIVATE BOOST_MYSQL_SEPARATE_COMPILATION)

Boost.Asio and Boost.Beast offer a very similar separate compilation mode. If you're using them together with Boost.MySQL, you may consider enabling separate compilation for them, too.