To access the classes and templates described in this part,
the application must be linked with the -lcxx library.
Some templates also require linking with the
-lcourier-unicode library.
All classes and templates in this library are defined in the
“x” namespace. This documentation includes
doxygen-generated reference pages
for each documented class.
Currently, the class documentation does not always
explicitly note the
x namespace. When reading the separate class
documentation pages, mentally prepend the x
namespace to all documented classes that do not have one.
Example: “x::obj”,
“x::ref”, and so on.
Patches to the voluminous header files, noting the explicit namespace reference, are welcome. See the existing header files for an example (the namespace is referenced by a macro that's handled by pre-processing, prior to documentation generation).
You're reading LibCXX's manual that's organized as a loosely-structured tutorial. The tutorial contains additional links to doxygen-generated class references, where more information can be found.
LibCXX uses autotools.
If you're not familiar with
automake,
autoconf, and
libtool,
follow these links, and start there.
After installing the library and the
header files add the
LIBCXX_INIT macro to your
configure.ac in order to set up the environment
to develop and build applications with LibCXX:
configure.ac:Makefile.am:
The LIBCXX_INIT configure script macro
overrides CC and CXX, and
sets them to the compiler that built LibCXX.
The same compiler must be used to build
any code that links with it. The macro also adds any additional compiler
flags (currently “-std=c++20 -fno-omit-frame-pointer -pthread”).
The “-export-dynamic” compiler flag is also recommended,
but is not required.
LIBCXX_INIT defines the
LIBCXX_AM automake macro which pulls in Makefile
macros used in Chapter 22, Message dispatching-based thread design pattern and
Chapter 17, Parsing command line options.
See
examples/managedsingleton subdirectory in
LibCXX's source code tarball. This is an example of building C++
applications with LibCXX, complete with a basic autotools configuration:
$ aclocal $ autoreconf -i [ output not shown] $ ./configure [ output not shown] $ make make all-am make[1]: Entering directory `/home/mrsam/src/ng/examples/managedsingleton' g++ -DHAVE_CONFIG_H -I. -g -O2 -std=c++20 -fno-omit-frame-pointer -pthread -I/usr/inc lude/p11-kit-1 -MT managedsingleton.o -MD -MP -MF .deps/managedsingleton.Tpo - c -o managedsingleton.o managedsingleton.C mv -f .deps/managedsingleton.Tpo .deps/managedsingleton.Po /bin/sh ./libtool --tag=CXX --mode=link g++ -g -O2 -std=c++20 -fno-omit-frame-pointer -pthread -I/usr/include/p11-kit-1 -o managedsingleton managedsingleton.o -lcxx libtool: link: g++ -g -O2 -fno-omit-frame-pointer -std=c++20 -fno-omit-frame-pointer -pthread -I/usr/include/p11- kit-1 -o managedsingleton managedsingleton.o /usr/lib64/libcxx.so -lpthread -lrt -lpcre
This is the example code from Chapter 25, Application singleton design pattern.
This is certainly possible, but the autotools support in LibCXX takes care of many ancillary details. Here's an explanation of what needs to be done by hand, and what the automake macros do:
Use pkgconf/pkg-config to extract the relevant configuration settings:
--cflags and
--libs compiler flags for building and
linking C++ source.
The
--variable=pkgdatadir option returns
the directory with makefile fragments
for the options parser
generator, thread-based
message dispatcher generator, and other supporting
tools.
The
--variable=CXX and
--variable=CC options returns
the compiler invocation commands.
Link with -lcxx;
-lcxxtls gets the
GnuTLS-based classes.
Also, link with
-lrt, and
-lpcre.
Most Linux distributions also require
the -pthread compiler and link flag
even if without direct usage of thread-related methods and
classes
like x::run(),
or x::start_threadmsgdispatcher.
This is because the library has internal references to them
that require runtime resolution.
Index
x::const_ref and x::const_ptrcreate() - create reference-counted objectsbasex::ref or an x::ptr from thisx::refs and x::ptrsisa()