Difference between revisions of "MOD command line interface"
Bramgiesen (talk | contribs) |
Bramgiesen (talk | contribs) |
||
(12 intermediate revisions by the same user not shown) | |||
Line 30: | Line 30: | ||
</source> | </source> | ||
− | == | + | == Publish a plugin == |
+ | |||
+ | Once the modcli is installed it can be used to interact with the mod cloud API. All the steps for publishing a plugin are described bellow. | ||
+ | |||
+ | === Create project descriptor file === | ||
For this tutorial we'll build the [https://github.com/drobilla/lv2 lv2 examples] from [https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package/lv2-examples here]. | For this tutorial we'll build the [https://github.com/drobilla/lv2 lv2 examples] from [https://github.com/moddevices/mod-plugin-builder/tree/master/plugins/package/lv2-examples here]. | ||
Line 67: | Line 71: | ||
* <code>image_required</code> - Define a minimum version of the MOD Image that your bundle requires (if not defined it's assumed to be <code>1.0.0</code>) | * <code>image_required</code> - Define a minimum version of the MOD Image that your bundle requires (if not defined it's assumed to be <code>1.0.0</code>) | ||
− | == | + | === Compile and publish a plugin in the cloud === |
+ | |||
+ | After the file descriptor is in place, the plugin can be compiled and published in the cloud. | ||
+ | For the example mentioned above this command would look like this: | ||
+ | |||
+ | <source lang="console"> | ||
+ | $ modcli bundle publish lv2-example.json | ||
+ | Submitting release process for project ./lv2-examples.json using file lv2-examples.tar.gz | ||
+ | URL: https://pipeline-labs.moddevices.com/bundle | ||
+ | Release process created: xxx | ||
+ | Uploading buildroot package lv2-examples.tar.gz ... | ||
+ | Checksum match ok! | ||
+ | Cleaning up... | ||
+ | Process url: https://pipeline-labs.moddevices.com/bundle/xxx/?pretty=true | ||
+ | Done | ||
+ | </source> | ||
+ | |||
+ | At the end you'll see a process url. You can load it with curl: | ||
+ | |||
+ | <source lang="console"> | ||
+ | $ curl "https://pipeline-labs.moddevices.com/bundle/xxx/?pretty=true" | ||
+ | </source> | ||
+ | |||
+ | That's the publishing process that has been created in the cloud. Keep refreshing it until the status changes to <code>finished</code> or <code>error</code>. | ||
+ | You can check the logs opening the logs_href URL in case there any issues. Once the status changes to <code>finished</code> the plugin is available in the labs cloud API. | ||
+ | |||
+ | To verify the published bundles you can call the cloud API: | ||
+ | |||
+ | <source lang="console"> | ||
+ | $ curl "https://api-labs.moddevices.com/v2/lv2/plugins?pretty=true&budle_name=eg-amp.lv2" | ||
+ | </source> | ||
− | The most basic command for publishing a plugin is: | + | The example for publishing the <code>lv2-examples</code> is using the most basic command for publishing a plugin of which the syntax is: |
<source lang="console"> | <source lang="console"> | ||
$ modcli bundle publish <path/to/.json> | $ modcli bundle publish <path/to/.json> | ||
</source> | </source> | ||
− | When using this command it's important the the .mk file used for the package is in the same directory is the .json file. | + | When using this command it's important the the <code>.mk</code> file used for the package is in the same directory is the <code>.json</code> file. |
− | If .mk file is located somewhere else, for example when using the mod-plugin-builder, the | + | If .mk file is located somewhere else, for example when using the mod-plugin-builder, the <code>-p</code> flag can be used to provide a path to this file. This is done as follows: |
<source lang="console"> | <source lang="console"> | ||
$ modcli bundle publish -p ../mod-plugin-builder <path/to/.json> | $ modcli bundle publish -p ../mod-plugin-builder <path/to/.json> | ||
</source> | </source> | ||
− | When using the mod-plugin-builder, and the .mk file is in | + | When using the mod-plugin-builder, and the <code>.mk</code> file is in <code>mod-plugin-builder/plugins/package/<package-name>/<package-name>.mk</code> the modcli only needs the path the mod-plugin-builder repo, not the full path the package directory. When the <code>.mk</code> file is not located is not located in the same directory as the <code>.json</code> file and is also not in the plugin builder, a relative path |
+ | the directory where the <code>.mk</code> can be given. |
Latest revision as of 15:29, 24 September 2020
The MOD command line interface (modcli) is a small python tool that is used to communicate with the cloud API and ease the process of building and publishing your plugin.
Contents
Installation
First you will need to follow the instructions from the mod-devel-cli project to install the tool.
Once installed you can check the status:
$ modcli config list
Active environment: labs
Authenticated in [labs]: No
Registered environments: ['dev', 'labs']
If your active environment is not 'labs' then you have to change it:
$ modcli config set_active_env labs
Current environment set to: labs
Next you need to authenticate. The modcli tool will authenticate using SSO against MOD Forum. So make sure you register for an account first. Then:
$ modcli auth login_sso
SSO login requires you have a valid account in MOD Forum (https://forum.moddevices.com).
If your browser has an active session the credentials will be used for this login. Confirm? [y/N]: y
Logging in to [labs]...
You're now logged in as [xxx] in [labs].
Publish a plugin
Once the modcli is installed it can be used to interact with the mod cloud API. All the steps for publishing a plugin are described bellow.
Create project descriptor file
For this tutorial we'll build the lv2 examples from here.
Now you need to create a project descriptor file so the cloud knows how to compile and publish your plugin. If you followed the tutorials on creating a plugin and deploying to your Duo you must have a buildroot .mk file in a folder. If your project is called lv2-examples
then your package folder should be named lv2-examples
and there must be a .mk file named lv2-examples.mk
inside that folder.
Now create a new descriptor file named lv2-example.json
inside your package folder with contents:
{
"bundles": [
{ "name": "eg-amp.lv2" },
{ "name": "eg-fifths.lv2" },
{ "name": "eg-metro.lv2", "stable": true, "image_required": "1.5.0" },
{ "name": "eg-midigate.lv2" },
{ "name": "eg-sampler.lv2" },
{ "name": "eg-scope.lv2" }
],
"project": "LV2 Examples",
"developer": "David Robillard",
"buildroot_pkg": "lv2-examples",
"project_url": "https://github.com/drobilla/lv2"
}
In that descriptor you have to define:
bundles
- The list of bundles that will be published after the source code is compiledproject
- The project namedeveloper
- The name of the developerbuildroot_pkg
- The name of your buildroot package (it has to match the .mk filename)project_url
- The url of the project
For each bundle in the bundle list you can define:
name
- The bundle name (it has to match the folder name of the bundle in the compilation output)stable
- When set to false the plugins of the bundle will be considered being in BETA (if not defined it's assumed to befalse
)image_required
- Define a minimum version of the MOD Image that your bundle requires (if not defined it's assumed to be1.0.0
)
Compile and publish a plugin in the cloud
After the file descriptor is in place, the plugin can be compiled and published in the cloud. For the example mentioned above this command would look like this:
$ modcli bundle publish lv2-example.json
Submitting release process for project ./lv2-examples.json using file lv2-examples.tar.gz
URL: https://pipeline-labs.moddevices.com/bundle
Release process created: xxx
Uploading buildroot package lv2-examples.tar.gz ...
Checksum match ok!
Cleaning up...
Process url: https://pipeline-labs.moddevices.com/bundle/xxx/?pretty=true
Done
At the end you'll see a process url. You can load it with curl:
$ curl "https://pipeline-labs.moddevices.com/bundle/xxx/?pretty=true"
That's the publishing process that has been created in the cloud. Keep refreshing it until the status changes to finished
or error
.
You can check the logs opening the logs_href URL in case there any issues. Once the status changes to finished
the plugin is available in the labs cloud API.
To verify the published bundles you can call the cloud API:
$ curl "https://api-labs.moddevices.com/v2/lv2/plugins?pretty=true&budle_name=eg-amp.lv2"
The example for publishing the lv2-examples
is using the most basic command for publishing a plugin of which the syntax is:
$ modcli bundle publish <path/to/.json>
When using this command it's important the the .mk
file used for the package is in the same directory is the .json
file.
If .mk file is located somewhere else, for example when using the mod-plugin-builder, the -p
flag can be used to provide a path to this file. This is done as follows:
$ modcli bundle publish -p ../mod-plugin-builder <path/to/.json>
When using the mod-plugin-builder, and the .mk
file is in mod-plugin-builder/plugins/package/<package-name>/<package-name>.mk
the modcli only needs the path the mod-plugin-builder repo, not the full path the package directory. When the .mk
file is not located is not located in the same directory as the .json
file and is also not in the plugin builder, a relative path
the directory where the .mk
can be given.