-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 `lite/`, which is strongly recommended to use
in your applications:

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

The output from the `pkg-config` tool holds no surprises in this regard:

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

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

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