16.7 Building a Library That Has a C API

If you want to build a library that is written in C++ but that can be used with a C program, you must create a C API (application programming interface). To do this, make all the exported functions extern "C". Note that this can be done only for global functions and not for member functions.

If a C-interface library needs C++ run-time support and you are linking with cc, then you must also link your application with either libC (compatibility mode) or libCrun (standard mode) when you use the C-interface library. (If the C-interface library does not need C++ run-time support, then you do not have to link with libC or libCrun.) The steps for linking differ for archived and shared libraries.

When providing an archived C-interface library, you must provide instructions on how to use the library.

• If the C-interface library was built with CC in standard mode (the default), add -lCrun to the cc command line when using the C-interface library.

• If the C-interface library was built with CC in compatibility mode (-compat), add -lC to the cc command line when using the C-interface library.

When providing a shared C-interface library you must create a dependency on libC or libCrun at the time that you build the library. When the shared library has the correct dependency, you do not need to add -lC or -lCrun to the command line when you use the library.

• If you are building the C-interface library in compatibility mode (-compat), add -lC to the CC command line when you build the library.

• If you are building the C-interface library in standard mode (the default), add -lCrun to the CC command line when you build the library.

If you want to remove any dependency on the C++ runtime libraries, you should enforce the following coding rules in your library sources:

• Do not use any form of new or delete unless you provide your own corresponding versions.

• Do not use exceptions.

• Do not use runtime type information (RTTI).