The skarnet library interface
libskarnet is the library exported by skalibs; both a static library and a shared library (if they are supported on your system) are available. Every skarnet.org binary needs this library.
Compiling
- Make sure the place you installed the skalibs header files in is in your header directory list; the default is /usr/include, which is normally browsed by default by your C preprocessor.
- Use #include <skalibs/foobar.h> where
foobar.h is the header you need.
- The skalibs/skalibs.h header is the general entry point that will declare the near-entirety of the functions, variables and constants in skalibs. Including this header in your source files whenever you need a skalibs function will work; however, it is rather heavy, and you might want to include lower-level headers instead to reduce compilation time.
Linking
- For static linking: add /usr/lib/skalibs, or wherever you installed your .a files, to your library directory list.
- For dynamic linking: make sure the place you installed the libskarnet.so shared library in is in your shared library directory list; the default is /lib, which is normally browsed by default by your build-time and run-time linker. If you are using another place than the default (for instance, if you are using the slashpackage convention), make sure to edit your ld.so.conf file so your linker can find this place, and to run ldconfig if needed.
- Take note of the place where your sysdeps directory has been installed: by default, it's /usr/lib/skalibs/sysdeps. Let's call it $sysdeps.
- Link with -lskarnet. If you are using socket functions, you will also need to link with `cat $sysdeps/socket.lib`. If you are using time functions such as tain_now(), you will also need to link with `cat $sysdeps/sysclock.lib`. Also `cat $sysdeps/spawn.lib`` for posix_spawn() functions, timer.lib for timer_create functions, and so on. This is, unfortunately, the only way to work with all the idiosyncrasies and whimsies of various libcs; only musl does the sensible thing and exports all its functions from libc.a and libc.so, without requiring any additional linker command line flags.
The skarnet library as a whole is big (945k for libskarnet.a and 179k for libskarnet.so.2.4.0.0 on x86_64-linux), but the utmost care has been given to separate functions so that linkers never pull in any more than they need. Linking against the static version of libskarnet actually produces very small executables, and if your libc is suited for that, since skalibs only uses very basic libc interfaces, it is very possible to produce small static binaries - in many cases, a static program written with skalibs APIs will be an order of magnitude smaller than the equivalent program written using libc's or other utility libraries' APIs.
Programming
The skalibs source code is divided into several subdirectories, each containing a logical unit of code implementing independent functions.
- libposixplz: workarounds for some POSIX deficiencies and for systems that don't quite implement POSIX
- libstddjb: basic C API for system programming
- libdatastruct: efficient C implementation of basic data structures like sets or trees
- libstdcrypto: a few crypto primitives
- librandom: cryptographically secure random or pseudorandom number generation
- libunixonacid: more advanced C/Unix APIs, mainly for safe asynchronous interprocess communication