Merge pull request #86 from RustAudio/develop

Version 0.6 Release
RustAudio · Oct 23, 2020 · c93bfe8 · c93bfe8
2 parents b3fd950 + 3ec16a2
commit c93bfe8
Show file tree

Hide file tree

Showing 242 changed files with 22,983 additions and 5,378 deletions.
diff --git a/.cargo/config b/.cargo/config
@@ -0,0 +1,2 @@
+[alias]
+systool = "run -p systool --"
diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
@@ -0,0 +1,34 @@
+name: Book
+
+on:
+  push:
+    branches: 
+    - master
+    - develop
+
+jobs:
+  book:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/[email protected]
+      with:
+        python-version: 3.8
+    - name: Install Sphinx
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+    - name: Build Book
+      run: |
+        cd docs
+        make html
+        touch _build/html/.nojekyll
+    - name: Deploy
+      if: success()
+      uses: crazy-max/ghaction-github-pages@v1
+      with:
+        target_branch: gh-pages
+        build_dir: docs/_build/html
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -0,0 +1,72 @@
+name: Rust
+
+on:
+  push:
+    branches: 
+    - master
+    - develop
+  pull_request:
+    branches: 
+    - master
+    - develop
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        toolchain: [stable, beta, nightly]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: ${{ matrix.toolchain }}
+        override: true
+    - name: Build
+      run: cargo build --all --all-features --verbose
+    - name: Run tests
+      run: cargo test --all --all-features --verbose
+
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        override: true
+        components: rustfmt, clippy
+    - name: Format
+      run: cargo fmt --all -- --check
+    - uses: actions-rs/clippy-check@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        args: --all --all-features -- -D warnings
+
+  linux-bindings:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        override: true
+        target: i686-unknown-linux-gnu
+    - name: Install 32-bit libc
+      run: |
+        sudo apt-get update
+        sudo apt-get install libc6-dev-i386
+    - name: Generate
+      run: |
+        mkdir bindings
+        cargo run -p systool -- -I ./sys/lv2/ -o bindings/x86_64.rs -- -target x86_64-unknown-linux-gnu
+        cargo run -p systool -- -I ./sys/lv2/ -o bindings/x86.rs -- -target i686-unknown-linux-gnu
+    - uses: actions/upload-artifact@v1
+      with:
+        name: linux-bindings
+        path: bindings
diff --git a/.travis.yml b/.travis.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,12 +1,12 @@
-# Contributing to rust-lv2
+# Contributing to Rust-LV2
 
 *Inspired by [Rust's contribution guide](https://github.com/rust-lang/rust/blob/d9051341a1c142542a3f7dab509266606c775382/CONTRIBUTING.md).*
 
-Thank you for your interest in contributing to rust-lv2! There are many ways to contribute, and we appreciate all of them.
+Thank you for your interest in contributing to Rust-LV2! There are many ways to contribute, and we appreciate all of them.
 
 ## General or Usage questions, Feature Ideas or Discussions
 
-Our main discussion panel is the [Rust Audio Discourse](https://rust-audio.discourse.group/). Most of our design decisions are taken there and it's the perfect place to post any question or idea. rust-lv2 isn't the only project there, so you may post anything that is somehow related to Rust and Audio Processing.
+Our main discussion panel is the [Rust Audio Discourse](https://rust-audio.discourse.group/). Most of our design decisions are taken there and it's the perfect place to post any question or idea. Rust-LV2 isn't the only project there, so you may post anything that is somehow related to Rust and Audio Processing.
 
 ## Bug Reports
 
@@ -39,15 +39,15 @@ Instead, this happened: <explanation>
 ### Backtrace:
 ```
 
-All three components are important: what you did, what you expected, what happened instead. Please include the dependencies to rust-lv2 in your `Cargo.toml` so we can track down where to find the bug.
+All three components are important: what you did, what you expected, what happened instead. Please include the dependencies to Rust-LV2 in your `Cargo.toml` so we can track down where to find the bug.
 
 Sometimes, a backtrace is helpful, and so including that is nice. To get a backtrace, set the `RUST_BACKTRACE` environment variable to a value other than `0`. The easiest way to do this is to invoke `cargo` like this:
 
     $ RUST_BACKTRACE=1 cargo build
 
 ## Pull Requests
 
-Pull requests are the primary mechanism we use to change rust-lv2. GitHub itself has some [great documentation](https://help.github.com/articles/about-pull-requests/) on using the Pull Request feature. We use the "fork and pull" model [described here](https://help.github.com/articles/about-collaborative-development-models/), where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository.
+Pull requests are the primary mechanism we use to change Rust-LV2. GitHub itself has some [great documentation](https://help.github.com/articles/about-pull-requests/) on using the Pull Request feature. We use the "fork and pull" model [described here](https://help.github.com/articles/about-collaborative-development-models/), where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository.
 
 Please make pull requests against the `develop` branch.
 
@@ -59,6 +59,6 @@ Another useful feature are [draft Pull Requests](https://github.blog/2019-02-14-
 
 ## Writing Documentation
 
-Documentation improvements are very welcome. The API documentation is generated from the source code itself. However, the [rust-lv2 book](https://github.com/Janonard/rust-lv2-book), which explains how to use rust-lv2 in general, is a separate project. Documentation pull requests function in the same way as other pull requests.
+Documentation improvements are very welcome. The API documentation is generated from the source code itself. Documentation pull requests function in the same way as other pull requests.
 
 To find documentation-related issues, sort by the [documentation](https://github.com/RustAudio/rust-lv2/labels/documentation) label.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "lv2"
-version = "0.5.1"
+version = "0.6.0"
 authors = ["Jan-Oliver 'Janonard' Opdenhövel <[email protected]>", "Adrien Prokopowicz <[email protected]>",
  "Yruama_Lairba <[email protected]>"]
 edition = "2018"
@@ -16,39 +16,43 @@ travis-ci = { repository = "RustAudio/rust-lv2", branch = "master" }
 maintenance = { status = "actively-developed" }
 
 [dependencies.lv2-atom]
-version = "1.0.0"
+version = "2.0.0"
 optional = true
 
 [dependencies.lv2-core]
-version = "2.0.0"
+version = "3.0.0"
 optional = true
 
 [dependencies.lv2-midi]
-version = "1.0.0"
+version = "1.2.0"
 optional = true
 
 [dependencies.lv2-time]
-version = "0.1.0"
+version = "0.1.3"
 optional = true
 
 [dependencies.lv2-units]
-version = "0.1.0"
+version = "0.1.3"
 optional = true
 
 [dependencies.urid]
 version = "0.1.0"
 optional = true
 
 [dependencies.lv2-urid]
-version = "2.0.0"
+version = "2.1.0"
 optional = true
 
 [dependencies.lv2-state]
-version = "1.0.0"
+version = "2.0.0"
+optional = true
+
+[dependencies.lv2-sys]
+version = "2.0.0"
 optional = true
 
 [dependencies.lv2-worker]
-version = "0.1.0"
+version = "0.1.1"
 optional = true
 
 [features]
@@ -74,6 +78,7 @@ full = [
     "urid",
     "lv2-urid",
     "lv2-state",
+    "lv2-sys",
     "lv2-worker",
 ]
 wmidi = ["lv2-midi", "lv2-midi/wmidi"]
@@ -86,10 +91,33 @@ members = [
     "midi",
     "state",
     "sys",
+    "sys/tool",
     "time",
     "units",
     "urid",
     "urid/derive",
     "urid/lv2-urid",
     "worker",
+    "docs/amp",
+    "docs/fifths",
+    "docs/metro",
+    "docs/midigate",
 ]
+
+[profile.release]
+lto = true
+
+[patch.crates-io]
+lv2 = { path = "." }
+lv2-atom = { path = "atom" }
+lv2-core = { path = "core" }
+lv2-core-derive = { path = "core/derive" }
+lv2-midi = { path = "midi" }
+lv2-state = { path = "state" }
+lv2-sys = { path = "sys" }
+lv2-time = { path = "time" }
+lv2-units = { path = "units" }
+urid = { path = "urid" }
+urid-derive = { path = "urid/derive" }
+lv2-urid = { path = "urid/lv2-urid" }
+lv2-worker = { path = "worker" }
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# rust-lv2
+# Rust-LV2
 
 [![Build Status][travis-badge]][travis-url] [![Current Crates.io Version][crates-badge]][crates-url]
 
@@ -92,12 +92,26 @@ impl Plugin for Amp {
 lv2_descriptors!(Amp);
 ```
 
-## Using this framework
+## About this framework
+
+### Q&A
+
+#### Does my host program support it?
+
+Plugins created with `rust-lv2` are compatible to all LV2 hosts that comply to the specifications. If your application uses [`lilv`](https://drobilla.net/software/lilv), it's a good sign that it will support your plugin. Some prime examples are [Carla](https://kx.studio/Applications:Carla) and [Ardour](https://ardour.org/).
+
+#### Can I host plugins with `rust-lv2`?
+
+Currently, hosting plugins is not supported. This project was initialy started to create plugins using safe Rust and therefore, it is very plugin-centric. There are plans for integrated plugin hosting or a spin-off project, but those won't start in the near future.
+
+However, there is a lot of code that can be re-used for a hosting framework. If you want to create such a framework, you should take a look at `lv2-sys`, `urid`, and `lv2-atom`.
+
+A bare hosting framework would require an RDF triple store which can load Turtle files, an internal store for plugin interfaces and their extensions, a centralized URID map store, and a graph based work scheduling system to execute `run` functions in order.
 
 ### Documentation
 
 There are multiple valuable sources of documentation:
-* ["The rust-lv2 book"](https://janonard.github.io/rust-lv2-book/) describes how to use rust-lv2 in general, broad terms. It's the ideal point to get started and is updated with every new version of rust-lv2.
+* ["The Rust-LV2 book"](https://rustaudio.github.io/rust-lv2/) describes how to use Rust-LV2 in general, broad terms. It's the ideal point to get started and is updated with every new version of Rust-LV2.
 * [The API documentation](https://docs.rs/lv2).
 * [The LV2 specification reference](https://lv2plug.in/ns/).
 
@@ -122,37 +136,35 @@ There are also feature sets that account for common scenarios:
 * `plugin`: Usual crates for standard plugins. Includes `lv2-core`, `lv2-atom`, `lv2-midi`, `lv2-urid`, and `urid`. **This is the default.**
 * `full`: All sub-crates.
 
-### Building
+## Supported targets
 
-Since the bindings to the raw C headers are generated with bindgen, you need to have [Clang](https://clang.llvm.org/) installed on your system and, if it isn't in your system's standard path, set the environment variable `LIBCLANG_PATH` to the path of `libClang`.
+Rust-LV2 uses pregenerated C API bindings for different targets in order to increase usability and building speed. Rust has a lot of [supported targets](https://forge.rust-lang.org/release/platform-support.html), but our maintaining power is limited and therefore, only certain targets can be supported. We've ranked different targets in Tiers, [just like rustc does](https://doc.rust-lang.org/nightly/rustc/platform-support.html), which gives you a general understanding of what to expect of a target. The tables below list the supported targets, the used binding in the [`lv2-sys`](sys/) crate, and, if applicable, the maintainer and the last verification of that target.
 
-## Q&A
+The bindings itself are generated with the [LV2 systool](sys/tool/) and verified by building the [example plugins of the book](docs) and testing them with a host of that target.
 
-### Does my host program support it?
+### Tier 1
 
-Plugins created with `rust-lv2` are compatible to all LV2 hosts that comply to the specifications. If your application uses [`lilv`](https://drobilla.net/software/lilv), it's a good sign that it will support your plugin. Some prime examples are [Carla](https://kx.studio/Applications:Carla) and [Ardour](https://ardour.org/).
-
-### What targets are supported?
-
-We currently support stable and beta Rust running on macOS and Linux. Windows will probably work too, but the Windows build environment of Travis CI is currently broken and we therefore can not support it.
-
-We would like to also support Windows as well as ARM-based embedded devices like Raspberry Pis. If you can help us with these targets, please do so!
-
-### Can I host plugins with `rust-lv2`?
-
-Currently, hosting plugins is not supported. This project was initialy started to create plugins using safe Rust and therefore, it is very plugin-centric. There are plans for integrated plugin hosting or a spin-off project, but those won't start in the near future.
-
-However, there is a lot of code that can be re-used for a hosting framework. If you want to create such a framework, you should take a look at `lv2-sys`, `urid`, and `lv2-atom`.
-
-A bare hosting framework would require an RDF triple store which can load Turtle files, an internal store for plugin interfaces and their extensions, a centralized URID map store, and a graph based work scheduling system to execute `run` functions in order.
+A Tier 1 target for `rust-lv2` also has to be a Tier 1 target of rustc. You can check the [platform support page](https://doc.rust-lang.org/nightly/rustc/platform-support.html) to see which targets are included and what they provide. Additionally, there has to be a [maintainer](https://github.com/orgs/RustAudio/teams/lv2-maintainers) of `rust-lv2` who has access to a machine that runs this target and who can generate and verify bindings on this machine. This means that if you have a problem running your code on a Tier 1 target, there will be a maintainer who can help you.
 
-### Why `bindgen`?
+| Target                     | Binding           | Maintainer | Last Verification                                                                                        |
+|----------------------------|-------------------|------------|----------------------------------------------------------------------------------------------------------|
+| `x86_64-unknown-linux-gnu` | `linux/x86_64.rs` | @Janonard  | 10. of May 2020, using [Carla](https://github.com/falkTX/Carla) v2.1, running on Arch Linux              |
+| `x86-unknown-linux-gnu`    | `linux/x86.rs`    | @Janonard  | 16th of May 2020, using [Carla](https://github.com/falkTX/Carla) v2.1, running on Linux Mint 19.3 32-bit |
 
-`lv2-sys` uses `bindgen` to generate the Rust representation of the LV2 C API. Rust can not handle verbatim C code, but is able to define type and function definitions that exactly match those from the C headers. However, since serveral importants details in C aren't properly defined, these bindings need to be different for every platform. One example: While Rust's `u32` is always an unsigned, 32-bit wide integer, C's `int` may be 16 to 64 bits wide and may be signed or unsigned; It depends on the platform.
+### Tier 2
 
-One solution would be to generate bindings for every supported target, but if we would only support stable, beta and nightly Rust on [tier 1 platforms](https://forge.rust-lang.org/release/platform-support.html#tier-1), we would still have to maintain 21 different versions of the same crate. If we would add [tier 2 platforms](https://forge.rust-lang.org/release/platform-support.html#tier-2) too (which would include e.g. the Raspberry Pis), there would be 216(!) different versions.
+A Tier 2 target is a target that is at least in Tier 2 of rustc and has a generated binding. However, it might not work (well) and there might not be a maintainer who has access to a machine that runs this target and who can generate and verify bindings on this machine. This means that if you have a problem running your code on a Tier 2 target, you're stepping into uncharted territory.
 
-I guess it's obvious that this isn't a maintainable situation. Therefore, the bindings need to be generated every time they are build, which requires the build dependency to `bindgen`.
+| Target                                | Binding      |
+|---------------------------------------|--------------|
+| `aarch64-unknown-linux-gnu`           | `aarch64.rs` |
+| `arm-unknown-linux-gnueabi`           | `arm.rs`     |
+| `arm-unknown-linux-gnueabihf`         | `arm.rs`     |
+| `armv5te-unknown-linux-gnueabi`       | `arm.rs`     |
+| `armv7-unknown-linux-gnueabi`         | `arm.rs`     |
+| `armv7-unknown-linux-gnueabihf`       | `arm.rs`     |
+| `thumbv7neon-unknown-linux-gnueabihf` | `arm.rs`     |
+| `x86_64-pc-windows-msvc`              | `windows.rs` |
 
 ## License