-lite | Frog DNA, basically
===========================
[![GitHub Status][]][GitHub] [![codedocs status][]][codedocs] [![Coverity Status][]][Coverity Scan]

Table of Contents
-----------------

* [Introduction](#introduction)
* [Using -lite](#using--lite)
* [API](doc/API.md#overview)
  * [Important Node](doc/API.md#important-note)
  * [Helper Macros](doc/API.md#helper-macros)
  * [Generic Functions](doc/API.md#generic-functions)
  * [GNU Functions](doc/API.md#gnu-functions)
  * [OpenBSD/NetBSD/FreeBSD Functions](doc/API.md#openbsd-netbsd-freebsd-functions)
* [Build & Install](#build--install)
* [Origin & References](#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][1] and the [OpenBSD][2] project.  Most notably
the string functions: [strlcpy(3)][3], [strlcat(3)][3] and the highly
useful *BSD [sys/queue.h][4] and [sys/tree.h][7] API's.

Libite holds many of the missing pieces in GNU libc, although -lite does
not aim to become another [GLIB][5].  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][MIT], [ISC license][ISC], and [BSD licenses][BSD].

> **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

Notice that `_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 skip the `lite -> libite/`
compatibility symlink in the include directory.  This is 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 <kbd>./autogen.sh</kbd>
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][original finit] and released under the MIT/X11
license.  Joachim Wiberg later improved on the [Finit][1] code base and
included pieces of software released under the ISC and BSD licenses.
See each respective file for license details.

[1]:                https://github.com/troglobit/finit
[2]:                http://www.openbsd.org/
[3]:                http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
[4]:                http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
[5]:                https://developer.gnome.org/glib/
[7]:                http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
[MIT]:              https://en.wikipedia.org/wiki/MIT_License
[ISC]:              https://en.wikipedia.org/wiki/ISC_license
[BSD]:              https://en.wikipedia.org/wiki/BSD_licenses
[GitHub]:           https://github.com/troglobit/libite/actions/workflows/build.yml/
[GitHub Status]:    https://github.com/troglobit/libite/actions/workflows/build.yml/badge.svg
[Coverity Scan]:    https://scan.coverity.com/projects/20602
[Coverity Status]:  https://img.shields.io/coverity/scan/20602.svg
[codedocs]:         https://codedocs.xyz/troglobit/libite.log
[codedocs status]:  https://codedocs.xyz/troglobit/libite.svg
[Claudio Matsuoka]: https://github.com/cmatsuoka
[original finit]:   http://helllabs.org/finit/