# liberate

<p align="center">
<img src="./docs/liberate.png" />
</p>

[![status-badge](https://ci.codeberg.org/api/badges/interpeer/liberate/status.svg)](https://ci.codeberg.org/interpeer/liberate)
[![Build status](https://ci.appveyor.com/api/projects/status/objyc63xyiv2rbf8?svg=true)](https://ci.appveyor.com/project/jfinkhaeuser/liberate)
[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)

liberate is a small platform liberation library for the Interpeer Project.

The scope of the project is bound to the needs of the overall proejct. It may
change over time. For now, the focus is on the subset of platform abstractions
that are shared amongst several other projects:

- [packeteer](https://codeberg.org/interpeer/packeteer)
- [channeler](https://codeberg.org/interpeer/channeler)
- [s3kr1t](https://codeberg.org/interpeer/s3kr1t)
- [caprock](https://codeberg.org/interpeer/caprock)
- [vessel](https://codeberg.org/interpeer/vessel)

## Contents

1. `liberate/checksum/` contains a header-only implementation of CRC32
  with various polynomials.
1. `liberate/concurrency` contains some useful classes for concurrent
  algorithms.
1. `liberate/cpp/` contains headers that make some C++ language features
  a little more accessible.
1. `liberate/fs/` contains simple operating system abstractions of file
  system operations.
1. `liberate/net/` contains classes for socket and network addresses, and
  a simple URL parser for socket-URLs.
1. `liberate/string/` contains some string utilities.
1. `liberate/serialization/` contains functions for serializing and
  deserializing value types.
1. `liberate/sys/` contains miscellaneous operating system abstractions.
1. `liberate/types{.h}` contains standard type headers, as well as type
  definitions such as a variable length integer type.
1. `liberate/visibility.h` contains library symbol visibility macros that
  can be re-used in other libraries.
1. `liberate/logging.h` contains logging macros.

## Logging

Liberate itself does not provide genuine logging facilities. It does, however,
provide macros which delegate to one of several logging backends, or to a simple
stderr-based logging mechanism. The purpose of these macros is to provide the same
logging interface for liberate and it's dependent project, but leave the project
user in control of where log data is sent.

You choose the logging backend from `meson_options.txt`, or by passing the
`-DLIBERATE_LOG_BACKEND` compiler flag. Note that depending on how you use the
macros, either option may be more appropriate for you. If all your projects
are built with meson, in the top-level project do:

```bash
$ cd <build-dir>
$ meson <source-dir> -Dliberate:log_backend=plog
```

Everything should build with the selected backend. Note that depending on the
backend you choose, you may need to promote the backend's subproject, but meson
will provide instructions for how to do that.

Possible backends are:

1. [loguru](https://github.com/emilk/loguru)
1. [plog](https://github.com/SergiusTheBest/plog)
1. [spdlog](https://github.com/gabime/spdlog)
1. Builtin `stderr` log.

### Log Levels

In order of descending verbosity:

| Liberate              | loguru  | plog      | spdlog     |
|-----------------------|---------|-----------|------------|
| `LIBLOG_LEVEL_TRACE`  | `9`     | `verbose` | `TRACE`    |
| `LIBLOG_LEVEL_DEBUG`  | `1`     | `debug`   | `DEBUG`    |
| `LIBLOG_LEVEL_INFO`   | `INFO`  | `info`    | `INFO`     |
| `LIBLOG_LEVEL_WARN`   | `WARN`  | `warning` | `WARN`     |
| `LIBLOG_LEVEL_ERROR`  | `ERROR` | `error`   | `ERROR`    |
| `LIBLOG_LEVEL_FATAL`  | `FATAL` | `fatal`   | `CRITICAL` |


### Log Macros

- `LIBLOG(LEVEL, message)` log message at the given log level.
- `LIBLOG_<LEVEL_WITHOUT_PREFIX>(message)` shorthand for the above.
- Short versions of the above: `LLOG_<FIRST_LEVEL_LETTER>(message)`.
- `LIBLOG_ERR(code, message)` logs the given message. The code is considered
  a platform error code, as returned by e.g. `errno` or `GetLastError()`.
- `LIBLOG_ERRNO(message)` same as above, but uses `errno`/`WSAGetLastError()`
  internally to retrieve the platform error code.
- `LIBLOG_EXC(exception, message)` logs the message, followed by the
  exception's `.what()`.

All of the shorthand macros above for logging error information log
at `LIBLOG_ERROR` level. The below, therefore, are all equivalent:

```c++
char buf[200] = {};
snprintf("%s // %s", msg, strerror(errno));

LIBLOG(LIBLOG_LEVEL_ERROR, buf);
LIBLOG_ERROR(buf);
LLOG_E(buf);
LIBLOG_ERR(errno, msg);
LIBLOG_ERRNO(msg);

auto exc = hypothetical_make_exception(errno);
LIBLOG_EXC(exc, msg);
```

### Builtin logger

The builtin `stderr` log is very simple: it prefixes each log entry with the
file and line number, and the severity. Additionally, it only produces output
if the `-DDEBUG` flag is set and the `-DNDEBUG` flag is unset, so that you can
produce entirely log-free release binaries.

### Other Backends

Liberate does not initialize other logging backends. It includes the selected
backend headers, but does nothing else. You can use the logging header to write
log messages, but where they end up is up to your project's initialization
code.

- `loguru`:
  - In the examples, `FATAL` error messages are redirected to `ERROR`, to
    demonstrate all `LIBLOG*` macros appropriately.
  - The library cannot be used on Android or Win32.
- `plog`:
  - The library cannot be used on Win32.