Building lidi

Prerequisites

The only dependency needed to build lidi from source is the Rust toolchain (rustc and cargo). The usual way to install it is through rustup:

$ rustup install stable

Some optional compilation features pull in native libraries that must be available on the build host, most notably OpenSSL for the TLS features (from-tls / to-tls / tls).

Building

Building lidi with its default features is straightforward:

$ cargo build --release

The resulting binaries are placed in target/release/. With the default workspace members, this builds:

  • the two core binaries, lidi-send and lidi-receive, and their oneshot variants lidi-send-oneshot and lidi-receive-oneshot;

  • the client utilities lidi-file-send, lidi-file-receive, lidi-dir-send, lidi-udp-send, lidi-udp-receive, lidi-flood-send, lidi-flood-receive and lidi-network-simulator;

  • the C shared library (lidi-bindings).

Cargo workspace layout

Lidi is a Cargo workspace made of several crates, each with its own set of compilation features:

  • lidi-send — the sender binaries.

  • lidi-receive — the receiver binaries.

  • lidi-clients — the file, directory and UDP-tunnel client utilities.

  • lidi-bindings — the C shared library.

  • lidi-command-utils — internal library shared by the binaries (command line, configuration, logging, sockets, TLS, hashing). Its features are enabled transitively by the crates above and normally do not need to be selected manually.

  • lidi-protocol — internal library implementing the on-wire protocol. It has no compilation feature.

Selecting compilation features

All features listed below are enabled by default unless stated otherwise. To build a crate with a custom set of features, disable the defaults and list the ones you want. For example, to build a minimal sender that only accepts plain TCP connections and only uses the sendmmsg UDP strategy:

$ cargo build --release -p lidi-send \
    --no-default-features \
    --features "command-line,from-tcp,heartbeat,send-mmsg"

To keep the defaults and only add an opt-in feature (for instance the mimalloc allocator):

$ cargo build --release -p lidi-send --features mimalloc

Note

Most features gate a runtime capability. When a configured option requires a feature that was not compiled in, lidi either logs a warning and ignores the option (hash, heartbeat, log4rs, prometheus) or logs an error and refuses to use the corresponding endpoint (from-* / to-* / tcp / tls / unix).

Sender features (lidi-send)

  • command-line (default) — parse command line options with clap in addition to the configuration file. Without this feature the binary accepts only a single positional configuration-file path.

  • from-tcp (default) — accept plain TCP client connections (tcp: source endpoints).

  • from-tls (default) — accept TLS client connections (tls: source endpoints). Pulls in OpenSSL.

  • from-unix (default) — accept Unix-domain socket client connections (unix: source endpoints).

  • hash (default) — support the per-endpoint hash option (compute a hash of the transferred data).

  • heartbeat (default) — send periodic heartbeat blocks (the heartbeat parameter).

  • log4rs (default) — support a log4rs YAML logging configuration file (log4rs-config).

  • prometheus (default) — expose Prometheus metrics (prometheus-listen).

  • send-native (default) — compile the send UDP strategy.

  • send-msg (default) — compile the sendmsg UDP strategy.

  • send-mmsg (default) — compile the sendmmsg UDP strategy.

  • mimalloc (opt-in) — use the mimalloc global allocator instead of the system one.

At least one of send-native, send-msg or send-mmsg must be enabled. When several UDP strategies are compiled in, the default mode is mmsg, then msg, then native (see the mode parameter).

Receiver features (lidi-receive)

  • command-line (default) — parse command line options with clap in addition to the configuration file. Without this feature the binary accepts only a single positional configuration-file path.

  • to-tcp (default) — forward to plain TCP destination endpoints (tcp:).

  • to-tls (default) — forward to TLS destination endpoints (tls:). Pulls in OpenSSL.

  • to-unix (default) — forward to Unix-domain socket destination endpoints (unix:).

  • hash (default) — support the per-endpoint hash option (verify a hash of the transferred data).

  • heartbeat (default) — monitor incoming heartbeat blocks and warn on sender disconnection (the heartbeat parameter).

  • log4rs (default) — support a log4rs YAML logging configuration file (log4rs-config).

  • prometheus (default) — expose Prometheus metrics (prometheus-listen).

  • receive-native (default) — compile the recv UDP strategy.

  • receive-msg (default) — compile the recvmsg UDP strategy.

  • receive-mmsg (default) — compile the recvmmsg UDP strategy.

  • mimalloc (opt-in) — use the mimalloc global allocator instead of the system one.

At least one of receive-native, receive-msg or receive-mmsg must be enabled. When several UDP strategies are compiled in, the default mode is mmsg, then msg, then native (see the mode parameter).

Client features (lidi-clients)

These features apply to the file, directory and UDP-tunnel client utilities.

  • tcp (default) — connect to / listen on plain TCP (--to-tcp / --from-tcp).

  • tls (default) — connect to / listen on TLS (--to-tls / --from-tls). Pulls in OpenSSL.

  • unix (default) — connect to / listen on Unix-domain sockets (--to-unix / --from-unix).

  • hash (default) — compute (sending) or verify (receiving) file content hashes (--hash).

  • inotify (default) — watch directories for new files using inotify (lidi-dir-send --watch). Without this feature, watching falls back to periodically re-scanning the directory tree.

  • log4rs (default) — support a log4rs YAML logging configuration file (--log-config).

At least one of tcp, tls or unix must be enabled.

C bindings features (lidi-bindings)

The C shared library exposes a subset of the file client. Its features simply forward to the corresponding lidi-clients features:

  • hash (default) — forwards to lidi-clients/hash.

  • inotify (default) — forwards to lidi-clients/inotify.

Internal library features (lidi-command-utils)

lidi-command-utils is not built directly; the following features are enabled transitively by the sender, receiver and client crates and do not normally need to be selected by hand: command-line (clap), hash (xxHash), log4rs, mimalloc, prometheus and tls (OpenSSL).