risset 0.1.3

A package manager for csound

risset: a package manager for csound

This is the repository of risset, a package manager for csound external plugins and user-defined-opcodes. All plugins are kept in a separate repository at risset-data

Installation

pip3 install risset

or via git:

git clone https://github.com/csound-plugins/risset
cd risset
python3 setup.py install

Example Usage

# list all defined packages
$ risset list

* else  @ 0.2.0        | Miscellaneous plugins
* poly  @ 0.2.0        | Run multiple copies of an opcode in parallel/series
* klib  @ 0.2.0        | hashtable / pool / string cache plugins [installed 0.2.0]
* jsfx  @ 0.2.0        | Jesusonics effects in csound
* mverb @ 1.3.7        | Artificial reverb based on a 2D waveguide mesh

# Install some packages

$ risset install else jsfx

# Show information about a specific package

$ risset show poly

Plugin     : poly
Installed  : not installed
Abstract   : Run multiple copies of an opcode in parallel/series
Minimal csound version : 6.14
Author     : Eduardo Moguillansky
Platforms  :
    * linux: Ubuntu 16.04
    * macos: 10.14.0
    * windows: Windows 10
Opcodes    :
             poly, polyseq, poly0

# Show documentation of a given opcode in the default browser

$ risset doc poly

---

For Developers

In order to add/modify a plugin, clone risset-data

At the root of the repository there is an index file plugins.json, listing all available plugins. Each entry in the index has the form

{
    "plugins": {
        "myplugin@1.0.0": "plugins/<collection>/<version>/manifests/myplugin.json",
        "..." : "..."
    }
}

The path to the manifest is relative to the plugins.json file inside the git repository.

Manifest

Each plugin has an accompanying manifest in the .json format. The name of this file should correspond to the name of the plugin: "myplugin.json"

Example of a manifest for a plugin

{
    "name": "name_of_the_plugin",
    "libname": "name_of_the_shared_library",
    "version": "major.minor.patch",
    "short_description": "a short description",
    "long_description": "a long description",
    "csound_version": "minimal_csound_version",
    "binaries": {
        "linux": {
            "url": "path_or_url_of_binary",
            "build_platform": "major.minor.patch",
            "extra_binaries": ["url1", "url2", "..."]
        },
        "macos": {
            "url": "...",
            "build_platform": "..."
        },
        "windows": "..."
    },
    "manual": "manual_zip_download_url",
    "opcodes": ["foo", "bar", "baz"],
    "author": "Plugin Author",
    "email": "[e-mail]",
    "repository": "https://url/to/were/the/source/is/developed"
}

Explanation of each term

In general, each field holding a url can be either a link or a path relative to the manifest itself.

• name: name of the plugin. For example, "chaoticoscils". This name must be unique
• libname: the name of the shared library, without extension (example: libchaoticoscils). This is used to check if the plugin is installed.
• version: a version string indicating the version of these binaries. The version should have the form "MAYOR.MINOR.PATCH" or "MAJOR.MINOR", where each term is an integer
• short_description: "A series of chaotic oscillators / noise generators"
• long_description (optional): "A longer description of what these opcodes do"
• csound_version: The minimal version of csound needed to run these opcodes. Example "6.14.0" (a string)
• binaries: A dictionary with platforms as keys. Possible platforms: "linux", "macos", "windows". The value for each entry should be itself a dictionary of the form:
  • url: the path to the shared binary itself (relative to the manifest), or a downloadable url pointing to the shared library.
  • extra_binaries: an optional field holding an array of other binaries needed
  • build_platform: a string identifying the platform used to build the binary
• manual: A path/url to a .zip file holding one .md file for each opcode
• opcodes: A list of all opcodes included in this plugin (for documentation purposes)
• author: The name of the author / mainteiner
• email: email of the author / mainteiner

Platform support

It is desirable, but not a requirement, that all opcodes support the three major desktop platforms: linux, macos and windows. Support for a given platform is indicated by the availability of a binary for the given platform in the manifest.json file.

Implementation

risset.py

A python script implementing installation of plugins

Commands

risset list

Lists all known plugins

risset show

Show information about a plugin

risset install [, ...]

Install a given plugin for the current platform. Plugins are installed into the system folder where all other builtin plugins are installed. If the --user flag is given, plugins are installed into the corresponding path for each platform.

• linux: $HOME/.local/share/csound6/plugins64
• macos: $HOME/Library/Application Support/csound6/plugins64
• windows: C:\Users\<username>\AppData\Local\csound6\plugins64

In order for this option to be available the user should have modified its OPCODE6DIR64 environment variable to include this path (but also include the builtin path)

risset remove

Remove an installed plugin

TODO

• subcommand doc: show documentation about an opcode inside a plugin