1keyirc 0.1.1 - build and installation

REQUIREMENTS

    C11 compiler and standard C library
    POSIX shell and make
    POSIX terminal, poll, socket, fork, and descriptor interfaces
    Descriptor-relative operations and no-follow opens (openat,
        fstatat, mkdirat, O_NOFOLLOW), plus a monotonic clock
    GNU/BSD getopt_long option parsing
    OpenSSL-compatible TLS development headers and libraries
    A certificate authority trust store for public TLS servers
    An ANSI-compatible terminal for interactive operation

1keyirc has no curses or terminfo dependency. It uses read/write, termios,
poll, and terminal escape sequences directly. It does not spawn telnet or
tail, and the live chat log is bounded RAM state rather than a disk file.
The installed executable does not require Python.

The TLS code uses OpenSSL 1.1.1-or-newer-compatible APIs. LibreSSL is
usable when the installed headers and libraries supply those APIs.
Use your operating system's maintained TLS library and matching headers.

GPG-encrypted credentials are optional. They require a gpg executable
from GnuPG 2.2.20 or newer in PATH and an already running agent able to
decrypt without prompting. No GPG library is linked. Ordinary IRC and
private plaintext credential sources work without GnuPG. The client
does not relax its fixed helper options for older gpg versions.

BUILD

From the extracted source directory:

    ./configure
    make
    ./1keyirc -h

This produces only ./1keyirc. Configure checks the compiler and TLS
development files; it neither downloads dependencies nor installs files.
Regenerate the Makefile on each target because configured paths and
library names belong to that host. The distributed Makefile.in is a
template, not a host-specific Makefile.

Standard build variables are supported:

    CC=cc CFLAGS='-O2 -g' ./configure
    make

For dependencies in an additional prefix:

    CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure
    make

For explicit TLS libraries:

    TLS_LIBS='-lssl -lcrypto' ./configure

On Debian-family Linux, build-essential and libssl-dev usually supply
the build dependencies; ca-certificates supplies public trust material.
On ChromeOS, build in the Linux development environment. The program is
a Unix executable, not a browser extension or Android application.

Linux is the tested release platform. The code targets Unix-like systems
including BSD, but native OpenBSD/FreeBSD release validation remains to
be done. A successful build or test on Linux does not establish native
BSD compatibility. The actual target must provide the listed interfaces.

Before DNS lookup, resolver children close unrelated inherited descriptors.
Supported facilities include Linux close_range, BSD closefrom, or a
complete /proc/self/fd or /dev/fd scan with a bounded deadline. If no
complete isolation method is available, connection setup reports an
error instead of retaining another connection's descriptors in a helper.

CHECK

    make check

The C unit and Python integration tests use temporary private files,
PTYs, simulated IRC, and loopback/local sockets. They do not use a real
account, credential file, or public IRC server. The integration suite
needs Python 3 and Bash for the shell job-control checks. A restricted
build environment must permit PTYs and local sockets to run these tests.
Readelf, when available, checks the executable's dynamic dependencies.

    make check-unit

runs just the C tests. Optional credential-helper tests require gpg:

    make check-gpg

With a compiler that supports AddressSanitizer and UndefinedBehaviorSanitizer:

    make sanitize

This builds separate instrumented test executables without replacing
./1keyirc. These development tools are not installed with the application.

RUN

    ./1keyirc
    ./1keyirc --test-mode
    ./1keyirc --server irc.ircnow.org --channel '#ircnow' --nick tutankh-aten
    ./1keyirc --manual

Quote channel arguments beginning with # so the shell passes them as
arguments. Interactive operation requires a terminal. -h/--help,
-v/--version, --manual, and --check-config also work without a terminal.

/quickstart asks only for Server, TLS, Port, and Nickname before the final
choice: 1 Save and connect, 2 Save only, 3 Connect once, 4 Apply without
saving. Quickstart defaults to 3. /panel guides broader settings for any
saved server and defaults to Save only. Enter keeps a value; Up returns
to the previous question; Escape cancels unapplied answers.

See doc/1keyirc-start.txt, doc/1keyirc-manual.txt, or /help inside the app.
Help appears in a separate reader; Escape restores the log. --test-mode
does not connect, read credentials, or write configuration.

INSTALL

The default prefix is /usr/local. Install with an account permitted to
write there:

    make install

For a user-owned prefix, configure and install without elevated privileges:

    ./configure --prefix="$HOME/.local"
    make
    make install

Add the selected bin directory to PATH if your shell does not already
include it. Installation copies only this program's executable, man page,
example, license, and documentation. It does not create or overwrite
your personal configuration.

Package managers can stage an installation without writing the host prefix:

    make install PREFIX=/usr DESTDIR=/absolute/staging-directory

The usual destinations are:

    PREFIX/bin/1keyirc
    PREFIX/share/man/man1/1keyirc.1
    PREFIX/share/doc/1keyirc/

PREFIX, BINDIR, MANDIR, DOCDIR, and DESTDIR may be overridden at make time.
Use the same destination arguments when uninstalling:

    make uninstall

Uninstall removes the installed application files, not user configurations
or background sessions. make clean removes build products. make distclean
also removes the generated Makefile and configure log.
