docs: add project status and installation sections to readme

Signed-off-by: Christopher Arndt <chris@chrisarndt.de>

README.md

@@ -3,12 +3,38 @@
 A [Nim] wrapper for the [JACK] [C API]
 
 
+## Project status
+
+This software is in *alpha status* and has no official release yet.
+
+The basic JACK APIs (client lifecycle, ports, callbacks) have been wrapped and
+are functional (see [examples]), but MIDI, transport and meta-data APIs still 
+need wrapping. Also, symbol names may still be changed and things moved around
+before the first public release.
+
+Also, I plan to add a higher-level abstraction on top of the direct mapping
+from Nim procs and types to C functions and types, probably in the form of
+a JACk client object, which takes care of a JACK client instance, registering
+ports and setting up all the callbacks necessary for a well-behaved JACK 
+application.
+
+
+# Installation
+
+* Clone this repository.
+* Change into the `jacket` directory.
+* Run [`nimble install`] (or `nimble develop`).
+* Run the examples with `nim compile --run examples/<example>.nim`.
+
+
 ## License
 
 This software is released under the *MIT License*. See the [LICENSE](./LICENSE)
 file for more information.
 
 
+[`nimble install`]: https://github.com/nim-lang/nimble#nimble-usage
 [C API]: https://jackaudio.org/api/
+[examples]: ./examples
 [JACK]: https://jackaudio.org/
 [Nim]: https://nim-lang.org/

examples/jacket_info.nim

@@ -12,8 +12,8 @@ proc errorCb(msg: cstring) {.cdecl.} =
 
 addHandler(log)
 setErrorFunction(errorCb)
-jclient = clientOpen("test_jacket", NullOption.ord, status.addr)
-debug "Server status: " & $status
+jclient = clientOpen("jacket_info", NullOption.ord, status.addr)
+debug "JACK server status: " & $status
 
 if jclient == nil:
     error getJackStatusErrorString(status)

examples/jacket_port_connect_cb.nim

@@ -4,22 +4,28 @@ import signal
 
 var jclient: ClientTPtr
 var status: cint
+var exitSignalled: bool = false
 var log = newConsoleLogger(when defined(release): lvlInfo else: lvlDebug)
 
+proc cleanup(sig: cint = 0) =
+    debug "Cleaning up..."
+    if jclient != nil:
+        discard jclient.deactivate()
+        discard jclient.clientClose()
+        jclient = nil
+
 proc errorCb(msg: cstring) {.cdecl.} =
     # Suppress verbose JACK error messages when server is not available by
     # default. Pass ``lvlAll`` when creating the logger to enable them.
     debug "JACK error: " & $msg
 
-proc cleanup(sig: cint = 0) {.noconv.} =
-    debug "Cleaning up..."
+proc signalCb(sig: cint) {.noconv.} =
+    info "Received signal: " & $sig
+    exitSignalled = true
 
-    if jclient != nil:
-        discard jclient.deactivate()
-        discard jclient.clientClose()
-        jclient = nil
-
-    quit QuitSuccess
+proc shutdownCb(arg: pointer = nil) {.cdecl.} =
+    info "JACK server has shut down."
+    exitSignalled = true
 
 proc portConnected(portA: PortIdT; portB: PortIdT; connect: cint; arg: pointer) {.cdecl.} =
     let portAPtr = jclient.portById(portA)
@@ -40,26 +46,28 @@ proc portConnected(portA: PortIdT; portB: PortIdT; connect: cint; arg: pointer)
 
 addHandler(log)
 setErrorFunction(errorCb)
-jclient = clientOpen("jacket_port_register", NoStartServer.ord, status.addr)
-debug "Server status: " & $status
+jclient = clientOpen("jacket_port_connect_cb", NoStartServer.ord, status.addr)
+debug "JACK server status: " & $status
 
 if jclient == nil:
     error getJackStatusErrorString(status)
-    quit 1
+    quit QuitFailure
 
 when defined(windows):
-    setSignalProc(cleanup, SIGABRT, SIGINT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGINT, SIGTERM)
 else:
-    setSignalProc(cleanup, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
 
 discard jclient.portRegister("in_1", JACK_DEFAULT_AUDIO_TYPE, PortIsInput.ord, 0)
 discard jclient.portRegister("out_1", JACK_DEFAULT_AUDIO_TYPE, PortIsOutput.ord, 0)
 
 if jclient.setPortConnectCallback(portConnected, nil) != 0:
-    error "Error: could not set port connection callback."
+    error "Error: could not set JACK port connection callback."
+
+jclient.onShutdown(shutdownCb, nil)
 
 if jclient.activate() == 0:
-    while true:
+    while not exitSignalled:
         sleep(50)
 
-cleanup() # normally not reached
+cleanup()

examples/jacket_port_register.nim

@@ -4,40 +4,48 @@ import jacket
 
 var jclient: ClientTPtr
 var status: cint
+var exitSignalled: bool = false
 var log = newConsoleLogger(when defined(release): lvlInfo else: lvlDebug)
 
+proc cleanup(sig: cint = 0) =
+    debug "Cleaning up..."
+    if jclient != nil:
+        discard jclient.clientClose()
+        jclient = nil
+
 proc errorCb(msg: cstring) {.cdecl.} =
     # Suppress verbose JACK error messages when server is not available by
     # default. Pass ``lvlAll`` when creating the logger to enable them.
     debug "JACK error: " & $msg
 
-proc cleanup(sig: cint = 0) {.noconv.} =
-    debug "Cleaning up..."
-    
-    if jclient != nil:
-        discard jclient.clientClose
-        jclient = nil
+proc signalCb(sig: cint) {.noconv.} =
+    info "Received signal: " & $sig
+    exitSignalled = true
 
-    quit QuitSuccess
+proc shutdownCb(arg: pointer = nil) {.cdecl.} =
+    info "JACK server has shut down."
+    exitSignalled = true
 
 addHandler(log)
 setErrorFunction(errorCb)
 jclient = clientOpen("jacket_port_register", NoStartServer.ord or UseExactName.ord, status.addr)
-debug "Server status: " & $status
+debug "JACK server status: " & $status
 
 if jclient == nil:
     error getJackStatusErrorString(status)
     quit 1
 
 when defined(windows):
-    setSignalProc(cleanup, SIGABRT, SIGINT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGINT, SIGTERM)
 else:
-    setSignalProc(cleanup, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
 
 discard jclient.portRegister("in_1", JACK_DEFAULT_AUDIO_TYPE, PortIsInput.ord, 0)
 discard jclient.portRegister("out_1", JACK_DEFAULT_AUDIO_TYPE, PortIsOutput.ord, 0)
 
-while true:
+jclient.onShutdown(shutdownCb, nil)
+
+while not exitSignalled:
     sleep(50)
 
-cleanup() # normally not reached
+cleanup()

examples/jacket_sine.nim

@@ -3,8 +3,9 @@ import signal
 import jacket
 
 var jclient: ClientTPtr
-var out1: PortTPtr
+var outPort: PortTPtr
 var status: cint
+var exitSignalled: bool = false
 var log = newConsoleLogger(when defined(release): lvlInfo else: lvlDebug)
 
 type
@@ -40,27 +41,28 @@ proc tick(osc: SineOscPtr): float =
     if osc.phase >= tableSize:
         osc.phase -= tableSize
 
-proc errorCb(msg: cstring) {.cdecl.} =
-    # Suppress verbose JACK error messages when server is not available by
-    # default. Pass ``lvlAll`` when creating the logger to enable them.
-    debug "JACK error: " & $msg
-
-proc cleanup(sig: cint = 0) {.noconv.} =
+proc cleanup() =
     debug "Cleaning up..."
-    
     if jclient != nil:
         discard jclient.deactivate()
         discard jclient.clientClose()
         jclient = nil
 
-    quit QuitSuccess
+proc errorCb(msg: cstring) {.cdecl.} =
+    # Suppress verbose JACK error messages when server is not available by
+    # default. Pass ``lvlAll`` when creating the logger to enable them.
+    debug "JACK error: " & $msg
+
+proc signalCb(sig: cint) {.noconv.} =
+    info "Received signal: " & $sig
+    exitSignalled = true
 
 proc shutdownCb(arg: pointer = nil) {.cdecl.} =
-    debug "Server has shut down"
-    cleanup()
+    info "JACK server has shut down."
+    exitSignalled = true
 
-proc process(nFrames: NFramesT, arg: pointer): cint {.cdecl.} = 
-    var outbuf = cast[JackBufferPtr](portGetBuffer(out1, nFrames))
+proc processCb(nFrames: NFramesT, arg: pointer): cint {.cdecl.} = 
+    var outbuf = cast[JackBufferPtr](portGetBuffer(outPort, nFrames))
     let osc = cast[SineOscPtr](arg)
 
     for i in 0 ..< nFrames:
@@ -70,35 +72,40 @@ proc process(nFrames: NFramesT, arg: pointer): cint {.cdecl.} =
 
 addHandler(log)
 
-# create JACK client
+# Create JACK client
 setErrorFunction(errorCb)
-jclient = clientOpen("jacket_port_register", NoStartServer.ord or UseExactName.ord, status.addr)
-debug "Server status: " & $status
+jclient = clientOpen("jacket_sine", NoStartServer.ord or UseExactName.ord, status.addr)
+debug "JACK server status: " & $status
 
 if jclient == nil:
     error getJackStatusErrorString(status)
     quit 1
 
+# Create sine oscillator
 let sampleRate =(float) jclient.getSampleRate()
+debug "JACK sample rate: " & $sampleRate
 var osc = initSineOsc(sampleRate, sineFreq)
 
-
+# Set up signal handlers to clean up on exit
 when defined(windows):
-    setSignalProc(cleanup, SIGABRT, SIGINT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGINT, SIGTERM)
 else:
-    setSignalProc(cleanup, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
+    setSignalProc(signalCb, SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGTERM)
 
-if jclient.setProcessCallback(process, osc.addr) != 0:
-    error "Could not set process callback function."
+# Register JACK callbacks
+if jclient.setProcessCallback(processCb, osc.addr) != 0:
+    error "Could not set JACK process callback function."
     cleanup()
 
 jclient.onShutdown(shutdownCb, nil)
 
-out1 = jclient.portRegister("out_1", JACK_DEFAULT_AUDIO_TYPE, PortIsOutput.ord, 0)
+# Create output port
+outPort = jclient.portRegister("out_1", JACK_DEFAULT_AUDIO_TYPE, PortIsOutput.ord, 0)
 
+# Activate JACK client ...
 if jclient.activate() == 0:
-    #  keep running until the Ctrl+C
-    while true:
+    # ... and keep running until a signal is received
+    while not exitSignalled:
         sleep(50)
 
-cleanup() # normally not reached
+cleanup()