xtc/docs/LINUX.md

Linux setup and installation

Use a C99 compiler, C++17 compiler for the GUI, GNU Make, binutils and pkg-config. The core needs only the C/math runtime. FLTK 1.4 development files enable the GUI; JACK-compatible development files enable the optional audio/MIDI backend. Packaging/install tests additionally use Python 3.12+ (standard library only). No command starts a server, installs dependencies or changes system settings.

make all test
make gui
./build/xtc

Start/configure a JACK or PipeWire JACK-compatible server through your existing system setup first. xtc opens without starting one and requires reconnect after server loss/rate changes. In a separate JACK routing tool connect desired MIDI to midi_in, audio capture to input, and output/output_right to left/right playback ports. No physical routes are automatic. Input/recording remain mono. See GUI.md, AUDIO_FILES.md, MIDI.md and MIXER.md for composing/recording/editing.

xtc --help and xtc --version work without a display/server. xtc project.xtc opens one project; no-file startup retains FLTK options such as -display. xtc-check --validate project.xtc validates metadata only; native graphs cannot be serialized. See RECOVERY.md before replacing damaged files.

Staged installation

Core-only installation retains the original make install behavior and now adds xtc-check, pkg-config metadata, license and documentation. install-gui adds the GUI executable and desktop launcher. Defaults to PREFIX=/usr/local:

make install-gui DESTDIR="$PWD/build/stage" PREFIX=/usr
make uninstall DESTDIR="$PWD/build/stage" PREFIX=/usr

Review staged contents before using a package manager or choosing a writable live prefix. For a user installation, use an absolute PREFIX such as $HOME/.local and ensure its bin is in PATH. Prefixes containing spaces are tested; shell metacharacters/newlines, quotes, dollar signs and backslashes are not supported. No root installation is performed by tests. Uninstall from the same source version and prefix: it removes only known files, keeps unrelated files and removes directories only if empty. It is idempotent. It is not a system package manager and cannot undo replacement of another installation.

Installed files: bin/xtc-check, optional bin/xtc, include/xtc/*.h, lib/libxtc.a, lib/pkgconfig/xtc.pc, share/doc/xtc, share/licenses/xtc/LICENSE and optional share/applications/xtc.desktop. No daemon, service, bundled library or MIME registration is installed. Desktop caches are left to the packager/environment. The launcher uses the system audio icon and can open a single file argument.

C/C++ consumers use pkg-config --cflags --libs --static xtc plus the chosen compiler; expose PREFIX/lib/pkgconfig through PKG_CONFIG_PATH when needed. Static backend consumers need JACK if that optional backend was built; the pc file records its private dependency. Public headers contain no JACK/FLTK types. To build without optional libraries, set PKG_CONFIG=false FLTK_CONFIG=false. Python is not needed to run the installed executables or library.

Phase 20 binary/development archive

make package creates a system-linked Linux archive plus SHA-256 sidecar below BUILD_DIR; make test-package verifies its contents. It includes usr/bin, headers/static library/pkg-config metadata, desktop file (when FLTK is present), manuals, baseline and MIT license. No shared library, third-party plugin, media, service or dependency installer is bundled. BINARY_MANIFEST.json lists file hashes/sizes, architecture/libc and ELF NEEDED libraries. The entire archive's hash covers the manifest too. Do not assume compatibility with another distribution.

Inspect/test under a temporary directory first. For a writable user prefix, extract the archive with two leading path components stripped (xtc-VERSION-linux- ARCH/usr), placing bin/include/lib/share directly under that prefix. Put its bin on PATH and lib/pkgconfig on PKG_CONFIG_PATH. The archive's pkg-config prefix is relative to its installed location; normal make install retains explicit PREFIX. Use the matching source's uninstall with that PREFIX, or review the manifest before removing its files. Unknown/unrelated files are retained by source uninstall. This local tar package is not a pacman/RPM/deb registration or public distribution.

xtc-check --diagnose reports build capabilities and format/engine limits without opening a server or executing a plugin. xtc --diagnose works headlessly as well. Missing runtime GUI libraries are loader errors: install the distribution's compatible dependencies or rebuild the core-only configuration. Build without optional libraries using a fresh directory, PKG_CONFIG=false FLTK_CONFIG=false CPPFLAGS=-DXTC_DISABLE_LADSPA. No system setting or package is changed by tests.