Building (User)

Table of Contents

• Small, medium, or big?
  • Small: one standalone library
  • Medium: the unity build
  • Big: separate compilation
• Add one library to an existing program
• Use normal C++ around Sane C++
• Account for platform libraries
• Plugins need exported library symbols
• When to use SC::Build

Sane C++ libraries are source libraries: add the code you need to your program and compile it with the rest of your sources. You do not install a prebuilt runtime or adopt a mandatory build system.

Small, medium, or big?

There is no mandatory package manager or project layout. Choose an integration size that matches the amount of Sane C++ your program uses, and change it later if the program grows.

Small: one standalone library

Download the released SaneCpp<Library>.h file when you need one self-contained library and do not want a repository checkout. The download link on each library page is the shortest route from an existing program to a Sane C++ API.

Medium: the unity build

Add SC.cpp to your target and add Includes/ to its header search paths. SC.cpp selects the platform implementation and compiles the repository libraries as one translation unit. This is the simplest complete integration and the best default when several libraries work together.

Big: separate compilation

Compile selected files under Libraries/ separately when your build needs per-library targets, incremental compilation, or precise ownership of source groups. Keep using the public headers from Includes/; files under Internal/ and Tests/ are implementation details rather than public API.

These forms contain the same library code. They change how the code enters your build, not the APIs your application uses.

Add one library to an existing program

1. Add SC.cpp to the target's source files.
2. Add the repository Includes directory to the target's include paths.
3. Include the entry-point header for the library you use.
4. Add the small set of platform link dependencies required by your selected libraries.

For example:

#include "SaneCppStrings.h"
 
int main()
{
    SC::Console console;
    console.print("{1} {0}!\n", "world", "Hello");
    return 0;
}

The library catalog identifies each library's dependencies and standalone download. The Platforms guide describes supported operating systems.

Use normal C++ around Sane C++

Normal projects may include C and C++ standard headers. Sane C++ library code still avoids STL containers, exceptions, RTTI, and hidden allocation, but your application is free to use them.

The APIs are designed to accept views and caller-provided storage, so application containers can interoperate without becoming library dependencies. For example, an application can expose writable storage from its own string type to a file read or formatter.

Strict no-standard-library compilation is an optional pressure mode, not the default integration path. The [FAQ](FAQ) explains the compile and link settings when you intentionally need it.

Account for platform libraries

The unity build selects platform implementations at compile time. Depending on the libraries used, a target may need:

• Apple system frameworks such as CoreFoundation or CoreServices;
• Linux system libraries such as dl and pthread;
• Windows system libraries, many of which are selected by the headers with #pragma comment(lib, ...).

Start from the link settings used by the corresponding repository example or test rather than adding every possible system library. This keeps a small consumer target honest about what it actually uses.

Plugins need exported library symbols

When using Plugin without SC::Build, define SC_EXPORT_LIBRARY_<LIBRARY>=1 in the host for each Sane C++ library that a plugin must resolve. Linux hosts also need exported executable symbols, normally through -rdynamic.

When to use SC::Build

Your existing build system remains a valid choice. Use SC::Build when its C++ build descriptions, native backend, cross-target profiles, or package-managed toolchains remove work from your project. The external-use guide shows a minimal adoption that does not copy the Sane C++ repository layout.

For a single self-contained library, download the released header from the relevant library page.