Add documentation; prep for 0.9.0 (#23)

Add documentation, a header, etc.. and prep for a 0.9.0 binary release with github actions.
free-audio · Jul 9, 2022 · 8f51edb · 8f51edb
1 parent de57667
commit 8f51edb
Show file tree

Hide file tree

Showing 13 changed files with 316 additions and 249 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -5,7 +5,7 @@ cmake_policy(SET CMP0091 NEW)
 # and macOS 10.15
 set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15 CACHE STRING "Minimum macOS version")
 
-project(clap-info VERSION 0.1.0 LANGUAGES C CXX)
+project(clap-info VERSION 0.9.0 LANGUAGES C CXX)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 set(CMAKE_CXX_STANDARD 17)
 

diff --git a/README.md b/README.md
@@ -1,15 +1,19 @@
 # clap-info: A simple command line CLAP information tool
 
 This is a CLAP information tool which simply loads a clap and allows you to
-print a variety of information about the plugin. It is primarily useful in 
-debugging and when starting a CLAP, but also is handy for smoke tests, attaching
-debuggers, and so on.
+print a variety of information about the plugin. It prints the information in 
+machine-readable (JSON) format.
 
-We welcome pull requests and improvements.
+`clap-info` can perform the following
 
-Please note we are transitioning the output of this tool to be human
-readable JSON documents rather than unstructured prints. We are some of the
-way there. 
+- Traverse your system finding .clap files, and scanning them for information
+- Load a single CLAP and display the descriptors
+- For a given CLAP and descriptor, create an instance of a plugin and print
+  extension information, including ports, parameters, and more
+
+We occasionally tag releases with versions and make binary releases available,
+but the program is designed to be easy to build, and when starting a CLAP development
+effort, can be a useful tiny host to debug the first stages of CLAP development.
 
 ## To build
 
@@ -21,19 +25,22 @@ cmake -Bbuild
 cmake --build build
 ```
 
-## To use
+## To use as a scanner
 
-The most basic usage, using all the default flags, is:
+`clap-info -l` will list all installed CLAPs on your system, using the CLAP 
+locations documented in `entry.h`
 
-```bash
-build/clap-info "/path/to/Surge XT.clap"
-```
+`clap-info -s` will load each clap and print the descriptors for each CLAP,
+and as such implements a CLAP scanner.
 
-But you can configure the information with various degrees of probes, verbosity, and more. 
-In this regard, the code is the documentation, but luckily our argument parser means the
-code is also our help screen! Try:
+## To use on a single CLAP
 
 ```bash
-build/clap-info --help
+clap-info "/path/to/YourCLAP.clap"
 ```
 
+this usage will print complete information on plugin 0 in your clap.
+
+You can configure the information with various degrees of probes, verbosity, and more. 
+Use `clap-info --help` to get full information on the options.
+
diff --git a/include/clap-scanner/scanner.h b/include/clap-scanner/scanner.h
@@ -1,6 +1,14 @@
-//
-// Created by Paul Walker on 7/9/22.
-//
+/*
+ * CLAP-INFO
+ *
+ * https://github.com/free-audio/clap-info
+ *
+ * CLAP-INFO is Free and Open Source software, released under the MIT
+ * License, a copy of which is included with this source in the file
+ * "LICENSE.md"
+ *
+ * Copyright (c) 2022 Various Authors, per the Git Transaction Log
+ */
 
 #ifndef CLAP_INFO_SCANNER_H
 #define CLAP_INFO_SCANNER_H
@@ -13,12 +21,35 @@
 
 namespace clap_scanner
 {
+/*
+ * Return a list of the valid CLAP search paths, per the spec
+ * in entry.h, including parsing the appropriate environment.
+ */
 std::vector<std::filesystem::path> validCLAPSearchPaths();
+
+/*
+ * Traverse the valid CLAP search paths looking for OS specific
+ * paths to .clap instances
+ */
 std::vector<std::filesystem::path> installedCLAPs();
 
+/*
+ * Given the path of a CLAP instance, undertake the OS specific code
+ * to open the clap and resolve the clap_plugin_entry_t *, which can return
+ * null in the case of an invalid CLAP file
+ */
 const clap_plugin_entry_t *entryFromCLAPPath(const std::filesystem::path &p);
 
+/*
+ * Given a clap_plugin_entry_t, visit each clap description available
+ * inside the CLAP with a std::function
+ */
 bool foreachCLAPDescription(const clap_plugin_entry_t *, std::function<void(const clap_plugin_descriptor_t *)> );
+
+/*
+ * Given a path to a CLAP, visit each clap description available inside the
+ * CLAP with a std::function
+ */
 inline bool foreachCLAPDescription(const std::filesystem::path &p, std::function<void(const clap_plugin_descriptor_t *)> cb)
 {
     auto e = entryFromCLAPPath(p);

diff --git a/src/clap-info/clap-info-host.cpp b/src/clap-info/clap-info-host.cpp
@@ -1,6 +1,14 @@
-//
-// Created by Paul Walker on 5/13/22.
-//
+/*
+ * CLAP-INFO
+ *
+ * https://github.com/free-audio/clap-info
+ *
+ * CLAP-INFO is Free and Open Source software, released under the MIT
+ * License, a copy of which is included with this source in the file
+ * "LICENSE.md"
+ *
+ * Copyright (c) 2022 Various Authors, per the Git Transaction Log
+ */
 
 #include <iostream>
 #include "clap-info-host.h"
@@ -22,11 +30,19 @@ void request_process(const struct clap_host *h) {}
 
 void request_callback(const struct clap_host *h) {}
 
-static clap_host clap_info_host_static{
-    CLAP_VERSION_INIT, nullptr,       "clap-info",     "CLAP team", "https://github.com/free-audio",
-    "1.0.0",           get_extension, request_restart, request_process,     request_callback};
-
-clap_host_t *createClapValHost() {
+static clap_host clap_info_host_static{CLAP_VERSION_INIT,
+                                       nullptr,
+                                       "clap-info",
+                                       "CLAP team",
+                                       "https://github.com/free-audio/clap-info",
+                                       "1.0.0",
+                                       get_extension,
+                                       request_restart,
+                                       request_process,
+                                       request_callback};
+
+clap_host_t *createCLAPInfoHost()
+{
     if (!static_host_config)
         static_host_config = std::make_unique<HostConfig>();
     return &clap_info_host_static;
@@ -36,7 +52,7 @@ HostConfig *getHostConfig()
 {
     if (!static_host_config)
     {
-        std::cout << "Please call createClapValHost before getHostConfig()";
+        std::cout << "Please call createCLAPInfoHost before getHostConfig()";
         return nullptr;
     }
     return static_host_config.get();

diff --git a/src/clap-info/clap-info-host.h b/src/clap-info/clap-info-host.h
@@ -1,9 +1,17 @@
-//
-// Created by Paul Walker on 5/13/22.
-//
-
-#ifndef CLAP_VAL_HOST_CLAP_VAL_HOST_H
-#define CLAP_VAL_HOST_CLAP_VAL_HOST_H
+/*
+ * CLAP-INFO
+ *
+ * https://github.com/free-audio/clap-info
+ *
+ * CLAP-INFO is Free and Open Source software, released under the MIT
+ * License, a copy of which is included with this source in the file
+ * "LICENSE.md"
+ *
+ * Copyright (c) 2022 Various Authors, per the Git Transaction Log
+ */
+
+#ifndef CLAP_INFO_HOST_CLAP_INFO_HOST_H
+#define CLAP_INFO_HOST_CLAP_INFO_HOST_H
 
 #include <filesystem>
 #include <cassert>
@@ -27,95 +35,9 @@ struct HostConfig
     bool announceQueriedExtensions{true};
 };
 
-clap_host_t *createClapValHost();
+clap_host_t *createCLAPInfoHost();
 HostConfig *getHostConfig();
 
-struct clap_info_input_events
-{
-    static constexpr int max_evt_size = 10 * 1024;
-    static constexpr int max_events = 4096;
-    uint8_t data[max_evt_size * max_events];
-    uint32_t sz{0};
-
-    static void setup(clap_input_events *evt)
-    {
-        evt->ctx = new clap_info_input_events();
-        evt->size = size;
-        evt->get = get;
-    }
-    static void destroy(clap_input_events *evt) { delete (clap_info_input_events *)evt->ctx; }
-
-    static uint32_t size(const clap_input_events *e)
-    {
-        auto mie = static_cast<clap_info_input_events *>(e->ctx);
-        return mie->sz;
-    }
-
-    static const clap_event_header_t *get(const clap_input_events *e, uint32_t index)
-    {
-        auto mie = static_cast<clap_info_input_events *>(e->ctx);
-        assert(index >= 0);
-        assert(index < max_events);
-        uint8_t *ptr = &(mie->data[index * max_evt_size]);
-        return reinterpret_cast<clap_event_header_t *>(ptr);
-    }
-
-    template <typename T> static void push(clap_input_events *e, const T &t)
-    {
-        auto mie = static_cast<clap_info_input_events *>(e->ctx);
-        assert(t.header.size <= max_evt_size);
-        assert(mie->sz < max_events - 1);
-        uint8_t *ptr = &(mie->data[mie->sz * max_evt_size]);
-        memcpy(ptr, &t, t.header.size);
-        mie->sz++;
-    }
-
-    static void reset(clap_input_events *e)
-    {
-        auto mie = static_cast<clap_info_input_events *>(e->ctx);
-        mie->sz = 0;
-    }
-};
-
-struct clap_info_output_events
-{
-    static constexpr int max_evt_size = 10 * 1024;
-    static constexpr int max_events = 4096;
-    uint8_t data[max_evt_size * max_events];
-    uint32_t sz{0};
-
-    static void setup(clap_output_events *evt)
-    {
-        evt->ctx = new clap_info_output_events();
-        evt->try_push = try_push;
-    }
-    static void destroy(clap_output_events *evt) { delete (clap_info_output_events *)evt->ctx; }
-
-    static bool try_push(const struct clap_output_events *list, const clap_event_header_t *event)
-    {
-        auto mie = static_cast<clap_info_output_events *>(list->ctx);
-        if (mie->sz >= max_events || event->size >= max_evt_size)
-            return false;
-
-        uint8_t *ptr = &(mie->data[mie->sz * max_evt_size]);
-        memcpy(ptr, event, event->size);
-        mie->sz++;
-        return true;
-    }
-
-    static uint32_t size(clap_output_events *e)
-    {
-        auto mie = static_cast<clap_info_output_events *>(e->ctx);
-        return mie->sz;
-    }
-
-    static void reset(clap_output_events *e)
-    {
-        auto mie = static_cast<clap_info_output_events *>(e->ctx);
-        mie->sz = 0;
-    }
-};
-
 } // namespace clap_info_host
 
-#endif // CLAP_VAL_HOST_CLAP_VAL_HOST_H
+#endif // CLAP_INFO_HOST_CLAP_INFO_HOST_H