In part 1 of this article I described the constexpr feature, a C++ facility to perform compile-time evaluation.

In this part, I describe the how to write a library for compile-time (and runtime) parsing of CSV files called Csv::Parser:

Writing a CSV Parser

Why a Compile-Time Parser?

When I started writing the CSV parser library, I was focused on implementing a runtime parser in modern C++. However, while working on the code, I realized that almost all of the code I was writing could also be used in constexpr context!

Some of the benefits of having a compile-time parser are:

• You can embed the CSV data in your program and have the values immediately available at runtime without additional computational overhead.
• You can perform tests on the embedded data, verifying its integrity at compile-time.
• You can test the parser code at compile-time without running any tests.
• Due to constexpr nature of the parser, you can still use it at runtime.

The CSV Format

CSV (comma-separated values) format, while very common, has quite a few variations. The format is formally documented in RFC 4180. With many variations available, the RFC states that when processing CSV files,

Implementors should "be conservative in what you do, be liberal in what you accept from others".

The general format is defined as follows:

• The record lines are delimited by a line break (CRLF). Implementations may use other line break formats (LF, CR). The line break on the last line is optional. Example:

  aaa,bbb,ccc CRLF
  zzz,yyy,xxx CRLF
  

• Fields are separated by commas. There is no trailing comma on a record line. Space is considered a part of a field. Each line must contain the same number of fields.

• Each field may be enclosed by double-quotes. The enclosing double-quotes are mandatory if the field contains line breaks, commas, or double-quotes.

• Double-quotes are escaped by repeating them:

  "this field has "" double "" quotes",second field CRLF
  "this field has , comma and CRLF
  newline","last field"
  

Our parser fully supports the RFC 4180, while accepting other line break formats, ignoring whitespace around quoted values, and allowing escaped quotes inside unquoted fields. This is done to ensure the ability to load files from different implementations.

How to Represent Input and Output Data

C++17 added a new type std::string_view which refers to a constant contiguous sequence of characters. A typical implementation holds only two members: const char* (a pointer to the start of a data chunk) and a size. Plainly speaking, it's a section of a string-like sequence without mandatory terminating null. Luckily for us, std::string_view fully supports constexpr!

Unlike std::string, std::string_view does not own the data it points to, so great care is required to ensure that the pointed data is not destroyed while operating on std::string_view. Of course, in compile-time context, we can point std::string_view to a static data (embedded in binary file) so the input data lifetime is no longer an issue.

Having the std::string_view facility, we can define the input:

using namespace std::string_view_literals;

// The "sv" user-defined literal specifies a string_view
constexpr auto input = "ab,cd\r\nef,gh"sv;

But how do we represent the individual cells in parser output? We cannot use constexpr std::string in C++17 and it would also be inefficient to store all these strings again. Once again, we can use a collection of std::string_view objects pointing to the original input!

Depending on whether we want the result at compile-time or runtime, we can use two-dimensional either std::array, or std::vector as output.

Notice that I didn't mention what happens when we have to collapse duplicate double-quotes inside the field data. I will discuss a method of dealing with this issue later in the article.

Let's Start With Tests

Starting with a "write test first" approach, we should define how we would like to use the CSV parser in compile-time and runtime contexts.

Note that I chose to use "a collection of columns" style of representing the 2D data (as opposed to a "a collection of rows"), due to the fact that large numeric CSV data is usually represented this way.

Keeping constexpr specifics in mind, a simple compile-time interface could look like:

using namespace std::string_view_literals;

constexpr auto data = "ab,cd\r\nef,gh" sv;
constexpr std::size_t columns = 2, rows = 2;

constexpr Parser parser;
// parse into std::array<std::array<std::string_view, rows>, columns>
constexpr auto matrix = parser.parseTo2DArray<columns, rows>(data);

// Verify the data at compile time.
static_assert(matrix[0][0] == "ab"sv);
// ...

On the other hand, at runtime we should be able to use dynamic features as well:

using namespace std::string_view_literals;

auto data = "ab,cd\r\nef,gh" sv;

// Let "cell_refs" be a vector of columns.
// After parsing, each element will be referencing
// a part of the original data.
std::vector<std::vector<std::string_view>> cell_refs;

Parser parser;

try {
    // parseTo() throws ParseError on error.
    parser.parseTo(data, cell_refs);
}
catch(ParseError& ex) {
    // ... handle the error
}

assert(cell_refs[0][0] == "ab"sv);  // Runtime assertion

The Parser Function Interface

Since we need the parser to be able to operate on both std::vector (at runtime) and std::array (at compile-time), we begin by writing a generic parse() function that can be used in both contexts. To do this, we can use a callback to store the parsed results.

class Parser {
    public:

    /// Parse CSV string data and store the results using a callback
    /// function.
    /// Callback function signature:
    /// void func(std::size_t row, std::size_t column, std::string_view cell_data).
    /// \throws ParseError
    template<typename StoreCellFunction>
    constexpr void parse(std::string_view data, StoreCellFunction func) const
    {
        // Iterate over data character by character,
        // invoking func(row, column, cell_data) each time a cell
        // is fully parsed.
    }

    // ...
};

A few benefits of this approach are:

• parse() does not depend on any particular output container type.
• By throwing an exception on error, we make sure that in compile-time context, parse error triggers a compile-time error if the input data is invalid.

The actual parse() function implementation can be seen in csv_parser.h at GutHub

Implementing parseTo2DArray() and parseTo()

Now that we have a constexpr parse() function, we can use it to define user-friendly methods.

A simple Parser::parseTo2DArray() implementation would look like:

/// Parse CSV string into an array of columns.
/// This method wraps parseTo() to simplify compile-time parsing.
/// \return std::array<std::array<std::string_view, rows>, columns>
/// \throws ParseError
template<std::size_t columns, std::size_t rows>
constexpr auto Parser::parseTo2DArray(std::string_view data) const
{
    std::array<std::array<std::string_view, rows>, columns> matrix;

    parse(data,
        [&matrix](std::size_t row, std::size_t column,
            std::string_view cell_data) constexpr
        {
            matrix[column][row] = cell_data;
        }
    );

    return matrix;
}

Note that we cannot pass columns and rows as ordinary arguments. Even though we're in constexpr context, constexpr functions can still be called at runtime and passing runtime values as (compile-time) template arguments to std::array is an error.

As for dynamic version, Parser::parseTo() function accepting various container types would look like:

/// Parse CSV string into a vector of columns.
/// \tparam Vector2D accepts 2D containers such as
/// std::vector<std::vector<std::string_view>>.
/// \throws ParseError
template<typename Vector2D>
void Parser::parseTo(std::string_view data, Vector2D& matrix) const
{
    Vector2D parsed_matrix;

    parse(data,
        [&](std::size_t row, std::size_t column,
            std::string_view cell_data)
        {
            if (parsed_matrix.size() < (column + 1)) {
                parsed_matrix.resize(column + 1);
            }
            if (parsed_matrix[column].size() < (row + 1)) {
                parsed_matrix[column].resize(row + 1);
            }
            parsed_matrix[column][row] = cell_data;
        }
    );

    // To avoid partial result, only touch the "matrix" parameter
    // after everything is parsed.
    std::swap(matrix, parsed_matrix);
}

Notice the exception safety - we avoid touching matrix unless all the data is parsed.

Escaped Double-Quotes

I already discussed how we could use std::string_view to point to the original data. However not every field is simply a substring of the original CSV data, as the CSV format has a feature of escaping double-quotes by repeating them.

In runtime environment we could easily solve this problem by introducing a cleanup function like std::string collapseQuotes(std::string_view view). However, at least for now, std::string is not usable in constexpr world. A simple solution for this is to introduce a new CellStringBuffer<BufferSize> class, a fixed-size buffer to contain the cleaned-up cell value:

/// A helper class for compile-time buffer construction
/// and string cleanup
template<std::size_t Size>
class CellStringBuffer {
    public:

        /// Constructor. Creates a buffer with cleaned-up
        /// cell contents.
        constexpr explicit CellStringBuffer(std::string_view cell)
                : buffer_(prepareBuffer(cell))
        { }


        /// Return string_view to a stored buffer.
        /// The returned view has collapsed consecutive
        /// double-quotes.
        /// \throw std::out_of_range if buffer is of insufficient size
        [[nodiscard]] constexpr std::string_view getStringView() const
        {
            return {buffer_.buffer.data(), buffer_.size};
        }


    private:

        struct Buffer {
            std::array<char, Size> buffer = { };
            std::size_t size = 0;
        };


        /// Create a buffer object with cleaned-up input in it
        constexpr static Buffer prepareBuffer(std::string_view input)
        {
            if (Size < input.size()) {
                throw std::logic_error("Insufficient buffer size");
            }
            std::array<char, Size> buffer = { };
            std::size_t output_pos = 0;
            for (std::size_t input_pos = 0; input_pos < std::min(Size, input.size()); ++input_pos) {
                char c = input[input_pos];
                buffer[output_pos] = c;
                ++output_pos;
                if (c == '\"' && (input_pos + 1) < input.size() && input[input_pos + 1] == '\"') {
                    ++input_pos;
                }
            }
            return {buffer, output_pos};
        }


        Buffer buffer_;
};

Notice that we have to store the cleaned up string length because it may be shorter than the buffer size. Having this data, we can easily construct std::string_view pointing to the buffer contents.

To create a better interface, we can wrap the std::string_views returned by parseTo2DVector() into a new CellStringReference class and store it in std::array<std::array<CellStringReference, rows>, columns> instead.

The CellStringReference class would look like this:

/// A value of a cell, referencing the data in original CSV text.
class CellStringReference {
    public:

        /// Constructor
        constexpr CellStringReference() = default;

        /// Constructor
        constexpr CellStringReference(std::string_view cell) noexcept
                : value_(cell)
        { }

        /// Get stored cell reference as string_view.
        /// The returned data may contain escaped consecutive
        /// double-quotes.
        [[nodiscard]] constexpr std::string_view getOriginalStringView() const noexcept
        {
            return value_;
        }

        /// Get a string buffer with collapsed consecutive
        /// double-quotes.
        /// This function is useful in constexpr context to
        /// retrieve cleaned-up cell data.
        /// \tparam BufferSize buffer size, has to be at least
        /// getOriginalStringView().size().
        /// \throw std::logic_error if BufferSize is too small.
        template<std::size_t BufferSize>
        [[nodiscard]] constexpr CellStringBuffer<BufferSize> getCleanStringBuffer() const
        {
            return CellStringBuffer<BufferSize>(value_);
        }


    private:

        /// Stored data
        std::string_view value_;

};

Putting it all together, we can now remove the escaped quotes at compile-time:

using namespace std::string_view_literals;

constexpr std::string_view data = R"(ab""cd,efgh)"sv;
constexpr std::size_t columns = 2, rows = 1;

constexpr Csv::Parser parser;

// parse into std::array<std::array<CellStringReference, rows>, columns>
constexpr auto matrix = parser.parseTo2DArray<columns, rows>(data);

// Verify the data at compile-time.
static_assert(matrix[0][0].getOriginalStringView() == "ab\"\"cd"sv);
static_assert(matrix[0][0]
    .getCleanStringBuffer<"ab\"\"cd"sv.size()>()
    .getStringView() == "with \"quote inside"sv);

Future Improvements

As you can see, with some work, even string processing can be done at compile-time.

The above code could be improved further by detecting and parsing a string representation of a IEEE 754 double value at compile-time. Unfortunately, std::strtod() and its family of C library functions cannot be used in constexpr context, so a similar constexpr function would have to be implemented.

Perhaps, with time, all the common algorithms and functions we're used to in C++ and C library will have constexpr versions.

Useful Links

• Csv::Parser at GitHub
• RFC 4180 - CSV Format
• constexpr reference
• Features supported by various C++ compilers
• CppCon 2017: Ben Deane & Jason Turner “constexpr ALL the Things!” - a compile-time JSON parser

Copyright © 2021 Alexander Shaduri

In part 1 of the article I discuss the constexpr feature as it's specified in C++17 and C++20.

In part 2 I describe the steps I took to write a library for compile-time (and runtime) parsing of CSV files called Csv::Parser:

What Do I Mean by Compile-Time?

One of the major strengths of C++, like other compiled-to-native-code languages, is speed. C++ achieves it by compiling the source code to fast, optimized, CPU-native machine code.

While the first ISO standard of C++ (C++98) is a fast language, many developers think that there is more room for efficiency. Move operations, "as if" rule for optimizing out memory allocations, and guaranteed copy elision introduced in later C++ standards are some of the new features which improve the performance of existing code "for free".

However, the quickest calculation is the one that does not happen at all, or, more precisely, happens in advance during compilation.

Templates always provided the standard C++ with some rudimentary capability of compile-time calculation. However, C++11 introduced a whole new feature called constexpr which made compile-time calculation easier, but still tricky and difficult to reason about due to its limitations. C++17 removed most of these limitations and now a lot of ordinary source code can be easily evaluated during compilation, freeing up valuable computational resources on the user's machine.

What constexpr Does

For sake of simplicity, I will mainly focus on constexpr as it's defined in C++17. Pre-C++17 constexpr is quite limited and not many of C++20 constexpr features have been fully implemented as of GCC 11 / Clang 11.

Marking a function or a variable constexpr declares that it is possible to evaluate the value of the function or variable at compile time. Such values can then be used where only compile-time constant expressions are allowed. Marking a variable declaration constexpr also implies const. (Note: constexpr methods used to be const by default, but this was removed in C++14).

The syntax for making a function or a variable constexpr is:

constexpr int func()
{
    // ...
}

// must be initialized by a constant expression
constexpr int variable = 1;

Compile-Time or Runtime?

It is important to understand that simply marking a function constexpr does not mean it will be evaluated during compilation. Whether such functions are evaluated at compile-time or runtime depends on a few things:

• If the result of the function must be available at compile-time as a constant expression, the function is evaluated at compile-time. For example, assigning the function result to a constexpr variable or using it as a non-type template argument forces compile-time evaluation. Of course, for this to work, all the arguments of the constexpr function must be constant expressions as well. Note that if such evaluation is impossible (because, for example, a function argument value is unavailable at compile-time), you will get a compilation error.

• If the function depends on runtime values, it will be evaluated at runtime.

• If the function depends on compile-time values, but its result is not required to be a constant expression, it is up to the compiler to decide whether it will run the evaluation at compile-time or not. Current compilers fall back to runtime evaluation in this case.

C++20 Standard Library provides a function std::is_constant_evaluated to help you find out whether the evaluation is happening at compile-time or runtime.

A Note on constexpr Lambdas

Unlike regular functions, lambda functions are automatically constexpr if the compiler determines that they can be. It may still be useful to mark them explicitly with constexpr keyword to force them to adhere to constexpr rules:

auto lambda = [](int argument) constexpr
{
    // only the operations valid in constexpr context are allowed here
};

Forcing Compile-Time Evaluation

The only way to guarantee that a constexpr function will be evaluated at compile-time is to use its result as a constant expression. There are a few ways to do this in C++:

• Assign it to a constexpr variable:

  constexpr auto result = func();
  

• Provided its result can be used as a non-type template argument, you can do the following: ```C++ template constexpr void forceCompileTime() { }

forceCompileTime();

Or something like:
```C++
template <int N>
struct ForceCompileTime {
    static const int value = N;
};

auto value = ForceCompileTime<func()>::value;

• If you just want to call a few functions at compile-time, you could use constexpr lambda:

  [[maybe_unused]] constexpr auto result = [&]() constexpr {
    func1();
    func2();
    return true;  // or perhaps return func3();
  }();
  

Constexpr Functions - What Can I Write Inside Them?

constexpr functions are limited in what they can do. Here are a few of these limitations (as of C++17 and C++20):

• A constexpr function cannot call a non-constexpr function. This means that the C standard library is off limits.

• The definition of a constexpr function must be available when calling it. This is similar to function templates and inline functions (in fact, constexpr functions are implicitly inline). In practice, this means that the definitions should be placed in header files.

• All local variables, parameters, and the return value must be of a Literal Type

• A constexpr function cannot be a coroutine.

• A constexpr function can be virtual, but only since C++20.

• goto is not allowed.

• Inside a constexpr function, declaration of a variable without initialization is allowed, but only since C++20. The same rule applies to constexpr variables.

• Since C++20, try blocks are allowed, but actually throwing an exception at compile-time is also prohibited, causing a compilation error.

• C++20 allows some use of std::vector and std::string in constexpr contexts, but neither GCC 11 nor Clang 11 implement it (yet).

Testing and Error Reporting

One useful side effect of evaluating constexpr functions at compile-time is that we can also do some testing during compilation without actually running any unit tests. By catching the errors early on at compile-time, this approach increases the reliability and correctness of the code without being dependent on runtime tests.

For example, we can use static_assert in a test to verify correctness of a function at compile-time:

constexpr int add(int a, int b)
{
    return a + b;
}

static_assert(add(1, 2) == 3);  // OK

// The following line fails to compile: 
static_assert(add(1, 2) == 4);

We can also conditionally throw an exception to trigger a compilation error. For example, to verify that a precondition is met we can write:

constexpr int compute(int a, int b)
{
    if (a > b) {
        throw std::logic_error("Precondition failed");
    }
    return a + b;
}

[[maybe_unused]] constexpr int result1 = compute(1, 5);  // OK
[[maybe_unused]] constexpr int result2 = compute(50, 2);  // Fails to compile

Note that we cannot use static_assert in compute() because the parameters may or may not be constant expressions - compute() can be used in runtime context as well.

It is important to note that a compiler is not required to issue an error if a constexpr function contains a code path that can only be evaluated at runtime, but is not triggered with particular set of compile-time arguments. The conditional throwing of exception in the example above relies on this behavior.

What's Next

In part 2 of the article I will talk about a way to approach writing a compile-time CSV parser, presenting a Csv::Parser library implemented using constexpr.

Useful Links

• constexpr reference
• Features supported by various C++ compilers
• CppCon 2017: Ben Deane & Jason Turner “constexpr ALL the Things!” - a compile-time JSON parser
• Csv::Parser at GitHub

Copyright © 2021 Alexander Shaduri

When working on a cross-platform C++ or C project, it is easy to get confused by platform differences and scattered information. Writing, compiling, and using shared libraries in a cross-platform manner with a modern build system is one of the most common problems in development.

Unfortunately, practical information about the actual specifics is quite scarce - most of the information is either outdated, scattered, or incomplete.

In this article I describe a simple way to create a shared library in your C++ / CMake project while accounting for platform differences.

I'm also providing a sample project at GitHub which can be used as a starting point or a reference. The sample project has a few features that you may find useful:

1. It uses modern CMake.
2. It supports compiling the library either as static or shared.
3. It provides cross-platform macros for exporting library symbols, supporting Windows and Linux.

The project can be found at GitHub: %[https://github.com/ashaduri/demo-library-simple]

Libraries - A Quick Refresher

A library can be either static or shared.¹

• A static library can be thought of as an archive of object files. There isn't a big difference between directly linking all the object files together, and grouping them into several static libraries, linking them into a final executable afterwards.²
  During the final stages of building the project, static libraries are linked into the executable files (binaries / .exe files, or even shared libraries / .dll files). Therefore, the compiled machine code is readily available as part of the executable files.
  It is not recommended to distribute static libraries because they may be dependent on specific compiler versions.
  Static library files usually have .lib (Windows) or .a (Linux, MinGW) extensions.³

• A shared (also known as dynamic, dynamically-linked, dynamic-link) library is a file that is searched for and loaded by your operating system's dynamic linker when you run your executable. One of the advantages of shared libraries is reduced memory and disk consumption - if multiple executables use the same shared library, only one copy has to exist on the disk and be loaded into system memory.
  Shared library files usually have .dll (Windows), .so (Linux), or .dylib (macOS) extensions.

¹: For sake of simplicity, in this article I am not covering C++20 modules, link-time optimization, or import libraries.

²: In reality, unless used, global symbols in static libraries may be optimized out by the linker. This may cause problems, for example, when Windows resource files are compiled into static libraries.

³: .lib extension is also used for .dll companion files called "import libraries" on Windows, used during the linking stage of project build.

Default Visibility of Symbols

There are a few facilities in C++ to control the visibility of symbols (functions, global variables) between object files. For example, by placing a function into anonymous namespace, you get a guarantee that the function is only visible in the object file it's compiled to, and does not cause conflicts with other, similarly-named functions in other object files.

A symbol in a static library is visible just like any other symbol in your object files - there is usually no need to modify your code.

However, using symbols from shared libraries is a bit more complicated. As of C++20, Standard C++ does not (yet) have a facility to control visibility of shared library symbols across the library boundary. This is where the platform- and compiler-specific behavior occurs:

• Visual C++ treats all symbols inside a shared library as private by default - you cannot use or call them from outside code.

• GCC, Clang, MinGW and many other GCC-like compilers treat all symbols as public by default. While this may be very convenient because libraries can be made shared with minimal changes, it also makes the libraries "leak" their private symbols to outside world, which may cause hard-to-diagnose conflicts.⁴

Fortunately, it is easy to make GCC / Clang behave like Visual C++ by simply adding -fvisibility=hidden option during library compilation.

⁴ Treating all symbols as private by default can also help wrap a symbol-leaking C code in a library with safe public interface, avoiding potential symbol conflicts.

CMake Support for Setting Symbol Visibility

If using CMake, you don't have to use the visibility compiler option. Instead, simply set the propertiesC_VISIBILITY_PRESET and CXX_VISIBILITY_PRESET (for C and C++, respectively) to hidden on your library target (called foo_library here):

    set_target_properties(foo_library
        PROPERTIES
            C_VISIBILITY_PRESET hidden
            CXX_VISIBILITY_PRESET hidden
    )

Exporting and Importing Symbols

Since all library symbols should be private by default, a symbol has to be marked as public / exported for it to be visible form outside the shared library. This is achieved by marking the symbol with a special attribute:

• __declspec(dllexport) is used on Windows (including GCC / MinGW)
• __attribute__((visibility("default"))) is used on most other operating systems with GCC-like compilers.

Additionally, on Windows, the outside code that uses these exported symbols has to "import" them from the shared library. When using these symbols, they have to be marked as "imported":

• __declspec(dllimport)

This code illustrates a function declaration which has to be exported from a shared library on Windows:

// When *building* the shared library,
// function declarations have to be written this way:
__declspec(dllexport) void myPublicFunction();

// When *using* the shared library from outside
// (by including its header files),
// function declarations have to be written this way:
__declspec(dllimport) void myPublicFunction();

Obviously, it is impractical to have two header files - one with symbols marked as "exported" and one with the same symbols marked as "imported". A common workaround is to create a macro that abstracts the import / export attributes. Assuming our library is named "foo_library", let's call this macro FOO_LIBRARY_BUILD. Depending on whether FOO_LIBRARY_BUILD is defined or not, the new FOO_LIBRARY_EXPORT macro changes its value to either export or import the symbol:

#ifdef FOO_LIBRARY_BUILD
    // Building the library
    #ifdef _WIN32
        // Use the Windows-specific export attribute
        #define FOO_LIBRARY_EXPORT __declspec(dllexport)
    #elif __GNUC__ >= 4
        // Use the GCC-specific export attribute
        #define FOO_LIBRARY_EXPORT __attribute__((visibility("default")))
    #else
        // Assume that no export attributes are needed
        #define FOO_LIBRARY_EXPORT
    #endif
#else
    // Using (including) the library
    #ifdef _WIN32
        // Use the Windows-specific import attribute
        #define FOO_LIBRARY_EXPORT __declspec(dllimport)
    #else
        // Assume that no import attributes are needed
        #define FOO_LIBRARY_EXPORT
    #endif
#endif

Now that we have defined the helper macro, we can easily mark our public symbols with it. For example, the library header file could contain the following declarations:

// Automatically export or import a symbol depending
// on whether FOO_LIBRARY_BUILD is defined or not.

// Make the function available to outside code
FOO_LIBRARY_EXPORT void myPublicFunction();

// Make the members of the struct available to outside code
struct FOO_LIBRARY_EXPORT MyStruct {
    // member function and data member declarations...
};

The code can be easily modified to define FOO_LIBRARY_EXPORT to nothing if static library compilation is required. Our "demo-library-simple" project contains all the necessary enhancements to support both static and shared compilation.

Using CMake to Handle FOO_LIBRARY_BUILD

In CMake, it is easy to define our FOO_LIBRARY_BUILD macro only when building the library:

target_compile_definitions(foo_library
    PRIVATE
        FOO_LIBRARY_BUILD
)

The PRIVATE nature of this definition tells CMake to define this macro only when building the library itself, but not when other CMake targets use this library.

CMake Support

Now that we have the C/C++ code support, we can write the remainder of our CMake code. The GitHub sample project contains support for compiling the same library either as static or shared, but for the sake of simplicity I describe only the shared part here.

Creating the Library Target

Assuming our library source and header files are in "foo_library" subdirectory of our project, we start by declaring the foo_library CMake target in foo_library/CMakeLists.txt:

# List all library sources
set(FOO_LIBRARY_SOURCES
    foo_library.h
    foo_library.cpp
)

# Add a shared library target
add_library(foo_library SHARED ${FOO_LIBRARY_SOURCES})

# Make all non-exported symbols hidden by default
set_target_properties(foo_library
    PROPERTIES
        CXX_VISIBILITY_PRESET hidden
)

# Treat the public symbols as exported
# (and not imported) by defining FOO_LIBRARY_BUILD
# when building the library.
target_compile_definitions(foo_library
    PRIVATE
        FOO_LIBRARY_BUILD
)

# Export the library's public header path to dependent targets
target_include_directories(foo_library
    INTERFACE
        ${CMAKE_CURRENT_SOURCE_DIR}
)

Now that we have the shared library compilation down, we can create an executable target (let's call it "demo") and link our library with it:

# List all sources of the executable
set(DEMO_SOURCES
    demo.cpp
)

# Create a CMake target for the executable 
add_executable(demo ${DEMO_SOURCES})

# Link the library with the executable
target_link_libraries(demo
    PRIVATE
        foo_library
)

It is important to keep in mind that "link" in CMake's target_link_libraries() is not linking in the classical sense. Apart from the actual linking via linker, it also makes the new target inherit all the PUBLIC and INTERFACE properties of the library.

What's Next

In the next part of the article series I will talk about generalizing the export macro to handle multiple libraries, making sure the executables can find the libraries, setting RPATH, and much more.

Notes on Versions

This article assumes to the following versions of software:

• CMake 3.0 or later (tested with CMake 3.19).
• Visual Studio 2008 or later (tested with Visual Studio 2019).
• GCC 4.0 or later (tested with GCC 11).

Useful Links

Please check out the links below for more detailed information on the topics discussed above.

• Code from the Article: demo-library-simple

• GCC: Visibility

• MSDN: Importing and Exporting

• CMake: add_library

• CMake: target_link_libraries

Copyright © 2021 Alexander Shaduri