README.rst: add info about command-line, xterm and multihost setups

Having proper gitversion.h helps tracking software versions
in the wild. This commit makes source trees that lack the
gitversion.h file for one reason or another buildable.

.github/workflows/build.yml

@@ -0,0 +1,21 @@
+name: build
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+jobs:
+  ubuntu_22_04:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: Build
+      shell: bash
+      run: |
+        sudo apt-get install libdbus-1-dev liblo-dev libevent-dev
+        make cibuild

.gitignore

@@ -0,0 +1,3 @@
+/.waf*
+/build/
+/.lock-waf*

COPYING

@@ -3,9 +3,9 @@ under the terms of multiple licenses.
 
 Choose the one that suits you:
 
- * GPLv2+ (see gpl2.txt)
- * GPLv3 (see gpl3.txt)
- * Academic Free License version 2.1 (see afl21.txt)
- * MIT (see mit.txt)
+ * GPLv2+ (see doc/gpl2.txt)
+ * GPLv3 (see doc/gpl3.txt)
+ * Academic Free License version 2.1 (see doc/afl21.txt)
+ * MIT (see doc/mit.txt)
 
-Documentation is provided under the terms of GFDL-1.3 (see gfdl-1.3.txt)
+Documentation is provided under the terms of GFDL-1.3 (see doc/gfdl-1.3.txt)

GNUmakefile

@@ -0,0 +1,24 @@
+.PHONY: default
+default:
+	@echo "This is a project that uses the WAF build system."
+	@echo ""
+	@echo "A typical command sequence for configuring,"
+	@echo "building and installing the software is:"
+	@echo ""
+	@echo "  ./waf configure --prefix=${HOME}/opt/"
+	@echo "  ./waf"
+	@echo "  ./waf install"
+	@echo ""
+	@echo "To get more info about waf configure parameters, run:"
+	@echo ""
+	@echo "  ./waf configure --help"
+	@echo ""
+	@echo "Read the README.rst file for more info."
+	@echo ""
+
+TOP := $(shell pwd)
+EPREFIX := $(TOP)/build/destdir
+
+.PHONY: cibuild
+cibuild:
+	./waf configure --prefix=$(EPREFIX) && ./waf install && $(EPREFIX)/bin/jpl

README.rst

@@ -0,0 +1,53 @@
+JACK Plugin Launcher
+====================
+
+A project for providing improved environment that is well suited
+for applications in a JACK Audio Connection Kit modular system.
+
+Jack Plugin is a term for libjack.so linked program that executes
+in one or more dedicated processes.
+
+Goals:
+ * For improved DSP performance and recovery from crashes
+   that occured in the UI parts of the Jack Plugins,
+   JACK Plugins are facilitated to run with
+   separate DSP and UI OS-level processes.
+ * Multi-protocol session management approach,like the one used in
+   LADISH implementation of liblash and in nsm-proxy used in
+   NON Session, RaySession & New Session management systems,
+   for handling incompatibilities between session managers
+   and apps (out of process plugins) and providing better overal
+   experience in modular systems using jack programs for a diverse set
+   of sesison management protocols.
+ * Possibility for each Jack Plugin to have multiple DSP backends.
+   Some projected backend ideas:
+    * non-optimized code that runs on any compatible CPU of given ISA
+    * optimized code that runs only on matching CPUs
+    * code optimized for running on iGPU or dGPU
+    * code for running in possible future implementation of jack
+      server in kernel mode.
+    * Source code to build during load (FAUST, llvm, etc.)
+ * Possibility for each Jack Plugin to have multiple UI frontends.
+   Some projected frontend ideas:
+    * X11 UI
+    * ncurses (with optional sixel support) UI, via tmux or screen
+    * (HTTP) Web UI
+    * GPU accelerated UI for GLX
+    * GPU accelerated UI for Wayland
+    * GPU accelerated UI for EGL and linux framebuffer
+ * Settings for tweaking desired behaviour.
+   (Good) built-in defaults and system-wide (/etc), user-wide (~/)
+   and per session managment project overrides of the settings.
+   Some projected ideas for settings:
+    * Order of preference for backends
+    * Order of preference for frontends
+    * Tweaks for LD_LIBRARY_PATH and other environment variables
+    * whether to use tmux, screen or some other terminal emulator
+      like xterm (X11) for starting new command-line shell or
+      ncruses UI.
+ * Execution on other machine in the network, via ssh/libssh/gabriel.
+   Facilitate public / private key setup for such deployments.
+
+For installation instructions, read the doc/INSTALL.rst file.
+If you are a (linux or libre) distribution packager,
+read the doc/PACKAGING.rst file.

doc/INSTALL.rst

@@ -0,0 +1 @@
+TODO

doc/PACKAGING.rst

@@ -0,0 +1 @@
+TODO

main.c

@@ -0,0 +1,26 @@
+/* -*- Mode: C ; c-basic-offset: 2 -*- */
+/* Copyleft JACK Plugin Authors, see COPYING file for more info
+ * This file is part of JACK Plugin Launcher (jpl) */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <stdio.h>
+
+#if HAVE_GITVERSION_H
+#include "gitversion.h"
+#endif
+
+int main(void)
+{
+  printf(
+    "JACK Plugin Launcher, version " JPL_VERSION "\n"
+    "Copyleft JACK Plugin Authors\n"
+#if defined(GIT_VERSION)
+    "built from " GIT_VERSION "\n"
+#endif
+    "built on " BUILD_TIMESTAMP"\n"
+    );
+  return 0;
+}

wscript

@@ -0,0 +1,133 @@
+#! /usr/bin/env python
+# encoding: utf-8
+#
+# wscript for building JACK Plugin Launcher
+
+from __future__ import print_function
+
+import os
+import subprocess
+import shutil
+import re
+import time
+
+from waflib import Logs, Options, TaskGen, Context, Utils
+from waflib.Build import BuildContext, CleanContext, InstallContext, UninstallContext
+
+APPNAME='jpl'
+VERSION='0-dev'
+
+# these variables are mandatory ('/' are converted automatically)
+srcdir = '.'
+blddir = 'build'
+
+def git_ver(self):
+    bld = self.generator.bld
+    header = self.outputs[0].abspath()
+    if os.access('./version.h', os.R_OK):
+        header = os.path.join(os.getcwd(), out, "version.h")
+        shutil.copy('./version.h', header)
+        data = open(header).read()
+        m = re.match(r'^#define GIT_VERSION "([^"]*)"$', data)
+        if m != None:
+            self.ver = m.group(1)
+            Logs.pprint('BLUE', "tarball from git revision " + self.ver)
+        else:
+            self.ver = "tarball"
+        return
+
+    if bld.srcnode.find_node('.git'):
+        self.ver = bld.cmd_and_log("LANG= git rev-parse HEAD", quiet=Context.BOTH).splitlines()[0]
+        if bld.cmd_and_log("LANG= git diff-index --name-only HEAD", quiet=Context.BOTH).splitlines():
+            self.ver += "-dirty"
+
+        Logs.pprint('BLUE', "git revision " + self.ver)
+    else:
+        self.ver = "unknown"
+
+    fi = open(header, 'w')
+    if self.ver != "unknown":
+        fi.write('#define GIT_VERSION "%s"\n' % self.ver)
+    fi.close()
+
+def display_msg(conf, msg="", status = None, color = None):
+    if status:
+        #Logs.pprint(msg, status, color)
+        conf.msg(msg, status, color=color)
+    else:
+        Logs.pprint('NORMAL', msg)
+
+def display_raw_text(conf, text, color = 'NORMAL'):
+    Logs.pprint(color, text, sep = '')
+
+def display_line(conf, text, color = 'NORMAL'):
+    Logs.pprint(color, text, sep = os.linesep)
+
+def options(opt):
+    # options provided by the modules
+    opt.load('compiler_c')
+
+    opt.add_option('--mandir', type='string', help="Manpage directory [Default: <prefix>/share/man]")
+
+def configure(conf):
+    conf.load('compiler_c')
+
+    conf.check_cfg(package='libevent', mandatory=True, args='--cflags --libs')
+    conf.check_cfg(package='liblo', mandatory=True, args='--cflags --libs')
+    conf.check_cfg(package='dbus-1', mandatory=False, args='--cflags --libs')
+
+    if Options.options.mandir:
+        conf.env['MANDIR'] = Options.options.mandir
+    else:
+        conf.env['MANDIR'] = conf.env['PREFIX'] + '/share/man'
+
+    conf.define('JPL_VERSION', VERSION)
+    conf.define('HAVE_GITVERSION_H', 1)
+    conf.define('BUILD_TIMESTAMP', time.ctime())
+    conf.write_config_header('config.h')
+
+    gitrev = None
+    if os.access('gitversion.h', os.R_OK):
+        data = file('gitversion.h').read()
+        m = re.match(r'^#define GIT_VERSION "([^"]*)"$', data)
+        if m != None:
+            gitrev = m.group(1)
+
+    print()
+    display_msg(conf, "==================")
+    version_msg = "jpl-" + VERSION
+    if gitrev:
+        version_msg += " exported from " + gitrev
+    else:
+        version_msg += " git revision will checked and eventually updated during build"
+    print(version_msg)
+    print()
+
+    display_msg(conf, "Install prefix", conf.env['PREFIX'], 'CYAN')
+    print()
+
+def build(bld):
+    bld(rule=git_ver,
+        target='gitversion.h',
+        update_outputs=True,
+        always=True,
+        ext_out=['.h'])
+
+    prog = bld(features=['c', 'cprogram'])
+    prog.source = [
+        'main.c',
+        ]
+    prog.includes = '.' # config.h, gitverson.h include path
+    prog.target = 'jpl'
+    prog.use = ['LIBEVENT', 'LIBLO', 'DBUS-1']
+    prog.defines = ["HAVE_CONFIG_H"]
+
+    # install man pages
+    man_pages = [
+#TODO:        "jpl.1",
+        ]
+
+    for i in range(len(man_pages)):
+        man_pages[i] = "man/" + man_pages[i]
+
+    bld.install_files(os.path.join(bld.env['MANDIR'], 'man1'), man_pages)