Installation

Table of Contents

• Make Commands
• Installation
  • Installation via pkg-config (easiest)
  • Installation via manual linking
• Using the library
  • Choose your API
  • Library error messages
  • Building Examples

Make Commands

Command	Description
make all	Build the static library with -O2 optimizations (default)
make tests	Build and run all tests (use VERBOSE=1 for stdout output)
make examples	Build all examples
make install	Install library in /usr/local (for pkg-config)
make uninstall	Uninstall library
make clean	Remove all build artifacts
make help	Show this help message

Installation

A gcc or clang compiler is required due to the use of various builtins.

First clone the repository:

git clone https://github.com/fastserial/lite3.git
cd lite3/

Then choose between installation via pkg-config or manual linking.

Installation via pkg-config (easiest)

Inside the project root, run:

sudo make install -j
sudo ldconfig

This will build the static library, then install it to /usr/local and refresh the pkg-config cache. If installation was successful, you should be able to check the library version like so:

pkg-config --modversion lite3

You can now compile using these flags:

$(pkg-config --libs --cflags --static lite3)

For example, to compile a single file main.c:

gcc -o main main.c $(pkg-config --libs --cflags --static lite3)

Installation via manual linking

First build the library inside project root:

make -j

Then in your main program:

1. Link against build/liblite3.a
2. And include: include/lite3.h + include/lite3_context_api.h

For example, to compile a single file main.c:

gcc -o main main.c -I/path/to/lite3/include /path/to/lite3/build/liblite3.a

Using the library

Choose your API

The Buffer API provides the most control, utilizing caller-supplied buffers to support environments with custom allocation patterns, avoiding the use of malloc().

The Context API is a wrapper aound the Buffer API where memory allocations are hidden from the user, presenting a more accessible interface. If you are using Lite³ for the first time, it is recommmended to start with the Context API.

#include "lite3.h"              // Buffer API
#include "lite3_context_api.h"  // Context API

There is no need to include both headers, only the API you intend to use.

Library error messages

By default, library error messages are disabled. However it is recommended to enable them to receive feedback during development. To do this, either:

1. uncomment the line // #define LITE3_ERROR_MESSAGES inside the header file: include/lite3.h
2. build the library using compilation flag -DLITE3_ERROR_MESSAGES

If you installed using pkg-config, you may need to reinstall the library to apply the changes. To do this, run:

sudo make uninstall
sudo make clean
sudo make install
sudo ldconfig

Building Examples

Examples can be found in separate directories for each API:

• examples/buffer_api/*
• examples/context_api/*

To build the examples, inside the project root run:

make examples -j

To run an example:

./build/examples/context_api/01-building-messages