-lite | Frog DNA, basically

Table of Contents

• Introduction
• Using -lite
• API
  • Important Node
  • Helper Macros
  • Generic Functions
  • GNU Functions
  • OpenBSD/NetBSD/FreeBSD Functions
• Build & Install
• Origin & References

NOTE: Incompatible changes in v2.0 compared to v1.x!

Introduction

Libite is a lightweight library of frog DNA that can be used to fill the gaps in any dinosaur project. It holds useful functions and macros developed by both Finit and the OpenBSD project. Most notably the string functions: strlcpy(3), strlcat(3) and the highly useful *BSD sys/queue.h and sys/tree.h API's.

Libite holds many of the missing pieces in GNU libc, although -lite does not aim to become another GLIB. One noticeable gap in GLIBC is the _SAFE macros available in the BSD sys/queue.h API — highly recommended when traversing lists to delete/free nodes.

The code is open sourced under a mix of permissive Open Source licenses: MIT/X11 license, ISC license, and BSD licenses.

Tip: have a look at my blog post about other useful UNIX API's! https://troglobit.com/post/2020-02-22-useful-unix-apis/

Using -lite

Libite is by default installed as a library and a set of include files. To prevent clashing with include files of the same name -lite employs an include file namespace libite/, which is strongly recommended to use in your applications:

#include <libite/lite.h>
#include <libite/conio.h>
#include <libite/queue.h>
#include <libite/tree.h>

Note: prior to v2.5.0, the lite/ namespace was used for headers, which is still available in the default install. This clashed with the headers of the LiTE library from the DirectFB project.

The output from the pkg-config tool holds no surprises:

$ pkg-config --libs --static --cflags libite
-I/usr/local/include -D_LIBITE_LITE -L/usr/local/lib -lite

Note: _LIBITE_LITE is defined since v2.5.0, useful for software that want to be able to build against headers from an older libite:

#ifdef _LIBITE_LITE
# include <libite/lite.h>
#else
# include <lite/lite.h>
#endif

The prefix path /usr/local/ shown here is only the default. Use the configure script to select a different prefix when installing libite.

For GNU autotools based projects, use the following in configure.ac:

# Check for required libraries
PKG_CHECK_MODULES([lite], [libite >= 1.5.0])

and in your Makefile.am:

proggy_CFLAGS = $(lite_CFLAGS)
proggy_LDADD  = $(lite_LIBS)

API Documentaion: https://codedocs.xyz/troglobit/libite/

Build & Install

This library was initially built for and developed on GNU/Linux systems as a light weight utility library, these days NetBSD should also work.

$ ./configure
$ make -j5
$ sudo make install-strip
$ sudo ldconfig

Use ./configure --without-symlink to prevent the install step from creating the lite -> libite/ compatibility symlink for the header files, required for systems with DirectFB LiTE. The default, however, is to install the symlink to ensure compatibility with existing software that depends on the -lite library headers in their previous namespace.

Note: When checking out code from GIT, use ./autogen.sh to generate a configure script. It is a generated file and otherwise only included in released tarballs.

Origin & References

Much of the code in libite (-lite) is written by Claudio Matsuoka for the original Finit and released under the MIT/X11 license. Joachim Wiberg later improved on the Finit code base and included pieces of software released under the ISC and BSD licenses. See each respective file for license details.