Difference between revisions of "How To Build and Deploy LV2 Plugin to MOD Duo"

From MOD Wiki
Jump to navigation Jump to search
(35 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
  
This is a quick start guide to get a LV2 plugin running in a MOD Duo Device.
+
This is a quick start guide to get an LV2 plugin running in a MOD Duo device.
 
Let's cut the chatter and get started.
 
Let's cut the chatter and get started.
  
 
== LV2 Basics ==
 
== LV2 Basics ==
  
This information is well described elsewhere.
+
This information is well described elsewhere. The SDK assumes that you have a working lv2 plugin for desktop linux. If you haven't gotten that far, you should start with these links:
  
* [http://www.nongnu.org/ll-plugins/lv2pftci/ LV2 programming for the complete idiot]
+
* [[Creating_Plugins]]
 
* [http://lv2plug.in/book/ LV2 Book]
 
* [http://lv2plug.in/book/ LV2 Book]
 
* [http://harryhaaren.blogspot.com/2012/06/writing-lv2-plugins-lv2-overview.html Writing Lv2 plugins : An Lv2 Overview]
 
* [http://harryhaaren.blogspot.com/2012/06/writing-lv2-plugins-lv2-overview.html Writing Lv2 plugins : An Lv2 Overview]
Line 14: Line 14:
 
== Prepare build tools ==
 
== Prepare build tools ==
  
A LV2 plugin is just a binary plus a TTL file. In order to run in a MOD Device it must be compiled using a cross-compiler targeting our hardware and software.
+
In order to run a plugin in the MOD Duo we must compile it for its specific architecture.<br/>
MOD Duo for example uses an ARM processor running a special flavor of Linux containing a specific set of libraries (dependencies).
+
The Duo uses an ARMv7 processor running a very basic and stripped-down version of Linux.<br/>
 +
Several audio-related libraries are included (fftw, libsndfile, libresample, etc) as well as generic libraries (boost, eigen, qt5core, etc).
  
We currently provide a custom cross-compiler that will take care of building LV2 plugins that will run in a MOD Duo.
+
We currently provide a custom build system that gives developers a similar system to what's available inside the Duo.<br/>
Just clone [https://github.com/moddevices/mod-plugin-builder MOD Plugin Builder] and follow the [https://github.com/moddevices/mod-plugin-builder/blob/master/README.md instructions].
+
Do not use a regular Linux system, it might lead to issues due to mismatching library versions.
 +
 
 +
If you're running Linux just clone [https://github.com/moddevices/mod-plugin-builder MOD Plugin Builder] and follow the [https://github.com/moddevices/mod-plugin-builder/blob/master/README.md instructions].
  
 
In summary:
 
In summary:
  
 
<source lang="console">
 
<source lang="console">
$ cd
+
$ git clone git://github.com/moddevices/mod-plugin-builder
$ git clone https://github.com/moddevices/mod-plugin-builder
+
$ cd mod-plugin-builder
 
$ ./bootstrap.sh
 
$ ./bootstrap.sh
 
</source>
 
</source>
  
Once the process is finished you should have local binary called <code>build</code>.
+
This process should take at least 1 hour, probably more depending on your CPU.
 +
When it finishes you'll be able to build plugins for Duo.
 +
 
 +
=== Using docker ===
 +
 
 +
Alternatively, if you're familiar with [https://www.docker.com/ docker] or are not running Linux, you can also use our [https://hub.docker.com/r/moddevices/mod-plugin-builder/ mod-plugin-builder image] which includes an already built system.
  
== Get source code and create a .mk file ==
+
See [[How_To_Use_Docker_Toolbox_With_MPB| this HowTo]] for more information about docker and mod-plugin-builder.
  
If you have an existing LV2 Plugin you just need to create a makefile to build it. In case you haven't started your LV2 plugin yet just follow through the links above from [[#LV2 Basics]].
+
== Build using buildroot '.mk' files ==
  
We have a few samples available [https://github.com/moddevices/mod-lv2-examples/ here]. For this guide we'll use the eg-amp.lv2 example.
+
=== Get source code and create a '.mk' file ===
  
The build script is based on [https://buildroot.org/ Buildroot] which requires you to create a new package under <code>plugins/package/</code> and add a make file <code><package-name>.mk</code>. To learn more about how Buildroot works check the [https://buildroot.org/downloads/manual/manual.html manual].
+
In case you haven't started your LV2 plugin yet just please follow through the links above in [[#LV2 Basics]].<br/>
 +
We have a few plugin examples available [https://github.com/moddevices/mod-lv2-examples/ here]. For this guide we'll use the eg-amp.lv2 example, already included inside of mod-plugin-builder.
  
In our example you must do this:
+
Assuming you have a working LV2 plugin code, you'll now need to create a [https://buildroot.org/ buildroot] mk file to build it.<br/>
 +
Buildroot requires you to create the new mk file as <code>plugins/package/NAME/NAME.mk</code> - using the same name for both the folder and mk file.
  
<source lang="console">
+
The [https://buildroot.org/downloads/manual/manual.html#_the_literal_mk_literal_file documentation] for this file type is quite extensive, so it's not possible to cover everything here.<br/>
$ cd
+
On the mod-plugin-builder repository (that you should have cloned before) there are many mk file examples under plugins/package/.
$ git clone git://github.com/moddevices/mod-lv2-examples
 
$ cp -R mod-lv2-examples/package/eg-amp-lv2 mod-plugin-builder/plugins/package/
 
</source>
 
  
I suggest you take a look at sections [[#Few things about Buildroot]] and [[#Alternatives to retrieve source code]] for more information.
+
TIP: The eg-* "packages" have their plugin code stored locally instead of downloading from external sources.
  
== Compile it ==
+
=== Compile it ===
  
 
We're all set to compile.
 
We're all set to compile.
Line 54: Line 61:
 
<source lang="console">
 
<source lang="console">
 
$ cd ~/mod-plugin-builder/
 
$ cd ~/mod-plugin-builder/
$ ./build eg-amp-lv2  
+
$ ./build eg-amp-lv2
 
$ ls ~/mod-workdir/plugins/
 
$ ls ~/mod-workdir/plugins/
 
eg-amp.lv2
 
eg-amp.lv2
Line 60: Line 67:
  
 
Success, the plugin has been built.
 
Success, the plugin has been built.
 +
If you get an error of no-such file or directory, check that you have set WORKDIR the same as when you bootstrapped the plugin-builder.
  
== Deploy it ==
+
=== Few things about the build script and Buildroot ===
Coming soon...
 
  
 
+
Buildroot is based on packages to build things. An LV2 plugin becomes a package and because of that it must comply with Buildroot rules.<br/>
== Publish it ==
 
Coming soon...
 
 
 
 
 
== Few things about the build script and Buildroot ==
 
 
 
Buildroot is based on packages to build things. An LV2 plugin becomes a package and because of that it must comply with Buildroot rules.<br>
 
 
A few important notes:
 
A few important notes:
 
* The package name is defined by the folder name and cannot contain '.'
 
* The package name is defined by the folder name and cannot contain '.'
 
* There must be a <packagename>.mk file inside the package folder
 
* There must be a <packagename>.mk file inside the package folder
* Inside the .mk file all defined variables must start with the package name replacing '-' with '_'
+
* The package name and '.mk' file name must be the same
* Browse through other [https://github.com/moddevices/mod-lv2-examples examples] so you get an idea of other variations of the makefiles (how to use waf for example)
+
* Inside the '.mk' file all defined variables must start with the package name in uppercase replacing '-' with '_'
* If your code has dependencies you need to fill in the _BUNDLES variable with a list; you can check the available packages [http://fixme.com/ here]
+
* You need to define the generated plugin bundle names in the <PACKAGE_NAME>_BUNDLES variable
 +
* Browse through other [https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package examples] so you get an idea of other variations of the makefiles (how to use cmake or waf for example)  
 +
* If you want to rebuild after a change to your plugin or the .mk then it is often easiest to just delete the previous build's directory for your plugin ~/mod-workdir/plugins-dep/build/<packagename>-<version>
  
== Alternatives to retrieve source code ==
+
=== Alternatives to retrieve source code ===
  
The .mk file will define how your source code is retrieved. In the eg-amp example the .mk file tells Buildroot to download it from github. Alternatively you can use a local tarball or point directly to the source code.
+
The '.mk' file will define how your source code is retrieved.<br/>
 +
In most of the existing packages the '.mk' file tells buildroot to download the source. You can use a local tarball or point directly to the source code if you wish.
  
=== Point directly to the source code ===
+
==== Point directly to the source code ====
  
Just replace the top section called 'download source code' with the following:
+
Just replace the top section with the following:
  
<source>
+
<source lang="makefile">
 
<PACKAGE_NAME>_SITE_METHOD = local
 
<PACKAGE_NAME>_SITE_METHOD = local
 
<PACKAGE_NAME>_SITE = /path/to/source
 
<PACKAGE_NAME>_SITE = /path/to/source
 
</source>
 
</source>
  
If you place the source code in same folder as the .mk file you can set the _SITE using <code>$($(PKG)_PKGDIR)/</code> as a relative path.
+
Make sure to remove the <PACKAGE_NAME>_SOURCE line, if it exists.
  
It's important that you replace the section, a _VERSION variable cannot exist or it will fail.
+
If you try changing the eg-amp-lv2 example don't forget to remove the trailing path from the make command. It should look like this:
If you try changing the eg-amp example don't forget to remove the trailing path from the make command. It should look like this:
 
  
<source>
+
<source lang="makefile">
 
<PACKAGE_NAME>_TARGET_MAKE = $(TARGET_MAKE_ENV) $(TARGET_CONFIGURE_OPTS) $(MAKE) -C $(@D)
 
<PACKAGE_NAME>_TARGET_MAKE = $(TARGET_MAKE_ENV) $(TARGET_CONFIGURE_OPTS) $(MAKE) -C $(@D)
 
</source>
 
</source>
  
=== Point to a local tarball ===
+
If you place the source code in same folder as the '.mk' file you can set the <PACKAGE_NAME>_SITE like this:
 +
 
 +
<source lang="makefile">
 +
<PACKAGE_NAME>_SITE_METHOD = local
 +
<PACKAGE_NAME>_SITE = $($(PKG)_PKGDIR)/
 +
</source>
 +
 
 +
You can find a working example of such setup [https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package/eg-amp-lv2 here].
 +
 
 +
==== Point to a local tarball ====
  
Assuming you make a tar.gz file and put it in the same folder as the .mk file then you must replace the top section called 'download source code' with the following:
+
If you make a tar.gz file and put it in the same folder as the '.mk' file, you can replace the top section with the following:
  
<source>
+
<source lang="makefile">
 
<PACKAGE_NAME>_VERSION = 1.0
 
<PACKAGE_NAME>_VERSION = 1.0
 
<PACKAGE_NAME>_SITE_METHOD = file
 
<PACKAGE_NAME>_SITE_METHOD = file
 
<PACKAGE_NAME>_SITE = $($(PKG)_PKGDIR)
 
<PACKAGE_NAME>_SITE = $($(PKG)_PKGDIR)
<PACKAGE_NAME>_SOURCE = eg-amp-$(<PACKAGE_NAME>_VERSION).tar.gz
+
<PACKAGE_NAME>_SOURCE = eg-amp-1.0.tar.gz
 +
</source>
 +
 
 +
If you want to use an arbitrary path just replace the <PACKAGE_NAME>_SITE variable.
 +
 
 +
== Local development ==
 +
 
 +
For local development of plugins using buildroot can be bothersome and confusing.<br/>
 +
You can use the cross-compiler and toolchain directly instead of going through buildroot methods.<br/>
 +
Note that this expects that your source code build system is cross-compile friendly (ie, no hardcoded compiler and paths and uses pkg-config to find extra libraries).<br/>
 +
Also this only works on a real Linux system, without using docker.
 +
 
 +
The setup is as simple as: (adjust as needed)
 +
 
 +
<source lang="console">
 +
$ . ~/mod-plugin-builder/local.env
 +
$ make
 +
</source>
 +
 
 +
The local.env file will setup your Linux compiler environment variables (such as CC, CXX, CFLAGS, etc) to use mod-plugin-builder files.<br/>
 +
If everything goes well, the resulting binaries will be ARMv7, MOD Duo compatible.
 +
 
 +
=== Quick example plugin ===
 +
 
 +
A quick example plugin is available inside mod-plugin-builder in make -C plugins/package/eg-amp-lv2/source/, which works with this cross-compilation setup.<br/>
 +
See https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package/eg-amp-lv2/source
 +
 
 +
Building this example plugin is as simple as:
 +
 
 +
<source lang="console">
 +
$ . ~/mod-plugin-builder/local.env
 +
$ make -C ~/mod-plugin-builder/plugins/package/eg-amp-lv2/source
 +
</source>
 +
 
 +
That's it! After this the eg-amp.lv2 bundle is ready to be deployed into a MOD unit.
 +
 
 +
== Deploy it ==
 +
 
 +
We can deploy the compiled plugin to the MOD using [https://github.com/moddevices/mod-sdk MOD-SDK] or manually using curl (advanced).
 +
 
 +
If you have mod-sdk installed start it up using the target plugin dir as LV2_PATH, like so:
 +
 
 +
<source lang="console">
 +
$ export LV2_PATH=~/mod-workdir/plugins/
 +
$ modsdk
 
</source>
 
</source>
  
If you want to use an arbitrary path just replace the _SITE variable.
+
Then open a browser at localhost:9000, select a plugin from the list and use the "deploy" tab to push the selected plugin's bundle to the Duo.
 +
 
 +
 
 +
For advanced users, you can push a bundle to the mod by running this: (adjust as needed)
 +
 
 +
<source lang="console">
 +
$ cd ~/mod-workdir/plugins/
 +
$ tar cz eg-amp.lv2 | base64 | curl -F 'package=@-' http://192.168.51.1/sdk/install
 +
</source>
 +
 
 +
 
 +
That's it! Your plugin is now inside the MOD!

Revision as of 12:02, 27 April 2017

Introduction

This is a quick start guide to get an LV2 plugin running in a MOD Duo device. Let's cut the chatter and get started.

LV2 Basics

This information is well described elsewhere. The SDK assumes that you have a working lv2 plugin for desktop linux. If you haven't gotten that far, you should start with these links:

Prepare build tools

In order to run a plugin in the MOD Duo we must compile it for its specific architecture.
The Duo uses an ARMv7 processor running a very basic and stripped-down version of Linux.
Several audio-related libraries are included (fftw, libsndfile, libresample, etc) as well as generic libraries (boost, eigen, qt5core, etc).

We currently provide a custom build system that gives developers a similar system to what's available inside the Duo.
Do not use a regular Linux system, it might lead to issues due to mismatching library versions.

If you're running Linux just clone MOD Plugin Builder and follow the instructions.

In summary:

$ git clone git://github.com/moddevices/mod-plugin-builder
$ cd mod-plugin-builder
$ ./bootstrap.sh

This process should take at least 1 hour, probably more depending on your CPU. When it finishes you'll be able to build plugins for Duo.

Using docker

Alternatively, if you're familiar with docker or are not running Linux, you can also use our mod-plugin-builder image which includes an already built system.

See this HowTo for more information about docker and mod-plugin-builder.

Build using buildroot '.mk' files

Get source code and create a '.mk' file

In case you haven't started your LV2 plugin yet just please follow through the links above in #LV2 Basics.
We have a few plugin examples available here. For this guide we'll use the eg-amp.lv2 example, already included inside of mod-plugin-builder.

Assuming you have a working LV2 plugin code, you'll now need to create a buildroot mk file to build it.
Buildroot requires you to create the new mk file as plugins/package/NAME/NAME.mk - using the same name for both the folder and mk file.

The documentation for this file type is quite extensive, so it's not possible to cover everything here.
On the mod-plugin-builder repository (that you should have cloned before) there are many mk file examples under plugins/package/.

TIP: The eg-* "packages" have their plugin code stored locally instead of downloading from external sources.

Compile it

We're all set to compile.

$ cd ~/mod-plugin-builder/
$ ./build eg-amp-lv2
$ ls ~/mod-workdir/plugins/
eg-amp.lv2

Success, the plugin has been built. If you get an error of no-such file or directory, check that you have set WORKDIR the same as when you bootstrapped the plugin-builder.

Few things about the build script and Buildroot

Buildroot is based on packages to build things. An LV2 plugin becomes a package and because of that it must comply with Buildroot rules.
A few important notes:

  • The package name is defined by the folder name and cannot contain '.'
  • There must be a <packagename>.mk file inside the package folder
  • The package name and '.mk' file name must be the same
  • Inside the '.mk' file all defined variables must start with the package name in uppercase replacing '-' with '_'
  • You need to define the generated plugin bundle names in the <PACKAGE_NAME>_BUNDLES variable
  • Browse through other examples so you get an idea of other variations of the makefiles (how to use cmake or waf for example)
  • If you want to rebuild after a change to your plugin or the .mk then it is often easiest to just delete the previous build's directory for your plugin ~/mod-workdir/plugins-dep/build/<packagename>-<version>

Alternatives to retrieve source code

The '.mk' file will define how your source code is retrieved.
In most of the existing packages the '.mk' file tells buildroot to download the source. You can use a local tarball or point directly to the source code if you wish.

Point directly to the source code

Just replace the top section with the following:

<PACKAGE_NAME>_SITE_METHOD = local
<PACKAGE_NAME>_SITE = /path/to/source

Make sure to remove the <PACKAGE_NAME>_SOURCE line, if it exists.

If you try changing the eg-amp-lv2 example don't forget to remove the trailing path from the make command. It should look like this:

<PACKAGE_NAME>_TARGET_MAKE = $(TARGET_MAKE_ENV) $(TARGET_CONFIGURE_OPTS) $(MAKE) -C $(@D)

If you place the source code in same folder as the '.mk' file you can set the <PACKAGE_NAME>_SITE like this:

<PACKAGE_NAME>_SITE_METHOD = local
<PACKAGE_NAME>_SITE = $($(PKG)_PKGDIR)/

You can find a working example of such setup here.

Point to a local tarball

If you make a tar.gz file and put it in the same folder as the '.mk' file, you can replace the top section with the following:

<PACKAGE_NAME>_VERSION = 1.0
<PACKAGE_NAME>_SITE_METHOD = file
<PACKAGE_NAME>_SITE = $($(PKG)_PKGDIR)
<PACKAGE_NAME>_SOURCE = eg-amp-1.0.tar.gz

If you want to use an arbitrary path just replace the <PACKAGE_NAME>_SITE variable.

Local development

For local development of plugins using buildroot can be bothersome and confusing.
You can use the cross-compiler and toolchain directly instead of going through buildroot methods.
Note that this expects that your source code build system is cross-compile friendly (ie, no hardcoded compiler and paths and uses pkg-config to find extra libraries).
Also this only works on a real Linux system, without using docker.

The setup is as simple as: (adjust as needed)

$ . ~/mod-plugin-builder/local.env
$ make

The local.env file will setup your Linux compiler environment variables (such as CC, CXX, CFLAGS, etc) to use mod-plugin-builder files.
If everything goes well, the resulting binaries will be ARMv7, MOD Duo compatible.

Quick example plugin

A quick example plugin is available inside mod-plugin-builder in make -C plugins/package/eg-amp-lv2/source/, which works with this cross-compilation setup.
See https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package/eg-amp-lv2/source

Building this example plugin is as simple as:

$ . ~/mod-plugin-builder/local.env
$ make -C ~/mod-plugin-builder/plugins/package/eg-amp-lv2/source

That's it! After this the eg-amp.lv2 bundle is ready to be deployed into a MOD unit.

Deploy it

We can deploy the compiled plugin to the MOD using MOD-SDK or manually using curl (advanced).

If you have mod-sdk installed start it up using the target plugin dir as LV2_PATH, like so:

$ export LV2_PATH=~/mod-workdir/plugins/
$ modsdk

Then open a browser at localhost:9000, select a plugin from the list and use the "deploy" tab to push the selected plugin's bundle to the Duo.


For advanced users, you can push a bundle to the mod by running this: (adjust as needed)

$ cd ~/mod-workdir/plugins/
$ tar cz eg-amp.lv2 | base64 | curl -F 'package=@-' http://192.168.51.1/sdk/install


That's it! Your plugin is now inside the MOD!