|
libose
|
describes how to build and configure the library
libose may be use by either including the source code directly in a project, or by compiling a static or dynamic library and linking that with an executable.
Typing make produces a static library. (An earlier version of this page promised a dynamic one as well; the rule for it has been commented out in the Makefile for some time.)
The compiler is clang by default, but may be set with the environment variable CCOMPILER, for example
CCOMPILER=gcc make debug
Objects and the archive are written to build/$(BUILD_ID)/, not alongside the source:
make -> build/default/libose.a make BUILD_ID=o.se -> build/o.se/libose.a
This is because libose is meant to be vendored, and every host that embeds it builds it with different options – different VM sizes, different types, different hooks. With a fixed output path those configurations overwrote each other and the last build silently won. A parent project passes BUILD_ID and reads its archive back from $(LIBOSEDIR)/build/$(BUILD_ID)/libose.a; several configurations can exist in one source tree at once.
Each build directory holds a .flags stamp recording the configuration it was built with, so changing a -D or an optimisation level rebuilds rather than mixing objects from two configurations in one archive. That mixing is not hypothetical: ose_bundle is a struct under OSE_CONF_DEBUG and a bare pointer without it, so the two configurations do not agree on what a bundle is.
make check-build
verifies that a change to a header actually reaches every object that includes it. Prerequisites are generated by the compiler (-MMD -MP) rather than written by hand; before that, an object depended only on its own header, so editing ose_util.h recompiled ose_util.o, left ose_vm.o alone, and relinked the archive from the stale object – a fresh timestamp over old code.
The documentation is built with doxygen, and uses graphviz to draw dependency graphs.
From the libose directory, type
make doc
to build the documentation.
Building the tests is done with
make test
at the top level, or simply
make
in test/ose_test.
See the section on Build Options.
By default, libose provides support for the 4 required OSC types: 32-bit signed integer, 32-bit float, string, and blob (typetags i, f, s, and b respectively).
libose also provides support for a number of "extended" types, which may be enabled at compile-time, including 1, 2, and 8-byte ints, unsigned ints, double-precision floats, symbols, and unit types (true, false, nil, and infinitum). See ose.h and Extended OSC Types.
Additionally, support for additional user-defined types may be added at runtime. See Types and Hooks for more information.
If using the OSE Virtual Machine, you may set the sizes of the different bundles (registers) at compile-time, or run-time.
If setting the sizes at compile-time, note that all sizes must be set, and a different signature for osevm_init will be generated, which takes a single argument.
In general, it is a good idea to set the sizes of the VM registers at compile-time.
A number of hooks may be defined to customize the behavior of the VM and type system. See Hooks and ex_ose_conf for more information.
1.9.8