You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/start/development.md
+5-8Lines changed: 5 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,12 @@
1
1
# Setting up your development environment
2
2
3
-
By default Renoise has all scripting utilities hidden to keep it simple for users who don't wish to mess around with code. If you want to write scripts, the first thing you have to do is to enable the hidden development tools.
3
+
To start developing Scripts in Renoise, use the following two menu entries inside the `Tools` menu on the top bar.
4
4
5
-
* For a quick test you can launch the Renoise executable with the `--scripting-dev` argument
6
-
* To have this mode enabled by default, you'll have to edit your `Config.xml` file inside Renoise's preferences folder. Search for the `<ShowScriptingDevelopmentTools>` property and set it to `true`. To reveal the Config.xml path, click on the *Help / Show the Preferences Folder...* menu entry in Renoise.
7
-
<!-- TODO consider exposing this setting in the Renoise GUI -->
5
+
*`Scripting Terminal & Editor` - This will open the debugging console used to test things and see your tool's output
6
+
*`Reload All Tools` - This will force a reload of all installed and running tools. It can be useful when adding new tools by hand or when changing them.
8
7
9
-
Once scripting is enabled, you'll have the following entries inside the *Tools* menu on the top bar.
10
-
11
-
**Scripting Terminal & Editor* - This will open the debugging console used to test things and see your tool's output
12
-
**Reload All Tools* - This will force a reload of all installed and running tools. It can be useful when adding new tools by hand or when changing them.
8
+
> [!NOTE]
9
+
> In previous versions of Renoise it was necessary to launch the Renoise executable with the `--scripting-dev` argument to see the above mentioned menue entries.
Copy file name to clipboardExpand all lines: docs/start/tool.md
+66-29Lines changed: 66 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,71 +2,108 @@
2
2
3
3
There are a few things that all tools must conform to for Renoise to successfully recognize and load them.
4
4
5
-
* A tool is either a folder or a zip file with the extension `.xrnx`
6
-
* It has a lua script named `main.lua` which contains the tool's program
7
-
* And a `manifest.xml` file that has version info, description and more
8
-
9
5
```sh
10
6
com.name_of_creator.name_of_tool.xrnx
11
7
├── manifest.xml
12
-
└── main.lua
8
+
├── main.lua
9
+
├── cover.png
10
+
├── thumbnail.png
11
+
├── LICENSE
12
+
└── README.md
13
13
```
14
14
15
+
A tool is a folder or a *zip file* with the extension `.xrnx`.
16
+
17
+
#### Required files:
18
+
*`main.lua` contains the tool's program.
19
+
*`manifest.xml` is an XML file which describes your tool.
20
+
21
+
#### Optional files:
22
+
*`cover.png` (600x350 px) is a large image, used on the [tools page](https://www.renoise.com/tools) and on the pages of individual tools.
23
+
*`thumbnail.png` (120x45 px) is a small capsule image, used when tools are shown in a list on the tools website.
24
+
*`README.md` is a markdown-formatted file that the website will render on the tool's page.
25
+
*`LICENSE` is a license file.
26
+
27
+
The paths to the cover, thumbnail, readme, and license files can be customized using the `...File` tags in the manifest. See below for more info.
28
+
29
+
15
30
> [!NOTE]
16
-
> You'll see that names of folders for most tools follow [reverse domain notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), but don't worry, you don't have to actually own a domain to create and share your tools. Just use whatever nickname you want, just make sure it's not already taken by other devs to avoid confusion.
31
+
> You'll see that the names of tool folders follow [reverse domain notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation), but don't worry, you don't have to actually own a domain to create and share your tools. Just use whatever nickname you want, but make sure it's not already taken by other developers to avoid confusion.
17
32
18
-
If needed, you can split your tool into multiple files and use the ["require" function](https://www.lua.org/pil/8.1.html) to load them inside your main script, but first you will be fine just using a single main script.
33
+
If needed, you can split your tool into multiple files and use the ["require" function](https://www.lua.org/pil/8.1.html) to load them inside your main script, but to start with, you will be fine just using a single main script.
19
34
20
-
Some tools will also make use of other resources like icons, text files or audio samples, these should all be placed in the same folder (or any subfolders inside it).
35
+
Some tools will also make use of other resources like bitmaps or audio samples; these should all be placed in the same folder (or any subfolders inside it).
21
36
22
37
Let's look at a basic tool to see what goes into these two files. You can find more elaborate examples by browsing the example tools.
23
38
24
39
## Manifest
25
40
26
-
The manifest is a short [XML](https://www.w3schools.com/XML/xml_whatis.asp) file with the name `manifest.xml`. It contains a few tag pairs like `<Tag>...</Tag>` and some text between them, Renoise reads these and loads your tool based on the information it finds inside.
41
+
The manifest is a short [XML](https://www.w3schools.com/XML/xml_whatis.asp) file with the name `manifest.xml`. It contains a few tag pairs like `<Tag>...</Tag>` and some text between them. Renoise reads these and loads your tool based on the information it finds within.
27
42
28
43
Here is an entire manifest file from a HelloWorld tool:
29
44
30
-
<!-- TODO copy data from the actual tool folder here -->
31
45
```xml
32
46
<?xml version="1.0" encoding="UTF-8"?>
33
47
<RenoiseScriptingTooldoc_version="0">
34
-
<ApiVersion>6.1</ApiVersion>
48
+
<!-- REQUIRED -->
35
49
<Id>com.renoise.HelloWorld</Id>
36
-
<Version>1.0</Version>
50
+
<ApiVersion>6.2</ApiVersion>
51
+
<Version>1.02</Version>
37
52
<Author>Your Name [your@email.com]</Author>
38
53
<Name>Hello World</Name>
39
-
<Category>Tool Development</Category>
54
+
<!-- OPTIONAL -->
55
+
<Category>Development, Workflow</Category>
40
56
<Description>
41
57
This tool is for printing "Hello World!" to the terminal when loaded.
Let's go through what each of these tags mean and what you should put inside them.
73
+
Let's go through what each of these tags means and what you should put inside them.
50
74
51
-
`<?xml>` is the header for the XML file, this will stay the same across all tools. `<RenoiseScriptingTool>` tells Renoise that this XML describes a tool. Don't change this.
75
+
`<?xml>` is the header for the XML file; this will stay the same across all tools.<br>
76
+
`<RenoiseScriptingTool>` tells Renoise that this XML describes a tool. Don't change this.<br>
77
+
`<!-- ... -->` is a XML comment, which will be ignored by Renoise.
52
78
53
79
### Required Properties
54
80
55
-
*`<ApiVersion>` The version of the Renoise API your tool is using. This should be `6.1` for the latest version.
56
-
*`<Id>` Should match the folder name of your tool **exactly** without the `.xrnx` at the end.
57
-
*`<Version>` The version of your tool, whenever you release a new update you should increase the version. Note that this is a **number value** and not a semantic version. So `1.02` is a valid version, while `1.0.2`**is not**.
58
-
*`<Author>` Your name and contact information. Whenever your tool crashes, this information is going to be provided for the user alongside the crash message, you should use some contact where you can accept possible bug reports or questions.
59
-
*`<Name>` Human readable name of your tool, it can be anything you want and you can change it anytime you feel like it.
60
-
*`<Category>` Category for your tool, which will be used to categorize your tool on the [official Tools page](https://www.renoise.com/tools) if you ever decide to submit it there
61
-
*`<Description>` A short description of your tool which will be displayed inside the *Tool Browser* in Renoise and on the Tools page.
81
+
*`<Id>` Should match the folder name of your tool **exactly**, without the `.xrnx` at the end.
82
+
*`<ApiVersion>` The version of the Renoise API your tool is using. This should be `6.2` for the latest version.
83
+
*`<Version>` The version of your tool. Whenever you release a new update, you should increase the version. Note that this is a **number value** and not a semantic version. So `1.02` is a valid version, while `1.0.2`**is not**.
84
+
*`<Author>` Your name and contact information. Whenever your tool crashes, this information is going to be provided for the user alongside the crash message. You should provide a contact method where you can receive bug reports or questions.
85
+
*`<Name>` The human-readable name of your tool. It can be anything you want, and you can change it anytime you feel like it.
62
86
63
87
### Optional Properties
64
88
65
-
*`<Homepage>` Your tool's website address if you have any. You could also put a forum topic or git repository here if you want.
66
-
*`<Icon>` A relative path to an optional icon to your tool.
67
-
*`<Platform>` List of platforms your tool supports separated by `,`. As long as you're only using the Renoise API, your tool will be automatically cross-platform, but once you do something OS specific you should communicate that here.
89
+
*`<Category>` A category for your tool, which will be used to categorize your tool on the [official Tools page](https://www.renoise.com/tools) if you ever decide to submit it there. See below for a valid list of categories.
90
+
*`<Description>` A short description of your tool which will be displayed inside the *Tool Browser* in Renoise and on the Tools page.
91
+
*`<License>` The type of license, e.g., *MIT* or *AGPL*.
92
+
*`<LicensePath>` Relative path to the license file within the XRNX bundle.
93
+
*`<ThumbnailPath>` Relative path to the thumbnail icon file for the Tools page.
94
+
*`<CoverPath>` Relative path to the cover image file for the Tools page.
95
+
*`<DocumentationPath>` Relative path to a plain text or markdown documentation file.
96
+
*`<Homepage>` The URL of your tool's homepage.
97
+
*`<Discussion>` The URL of your tool's discussion page, e.g., on the Renoise forums.
98
+
*`<Repository>` The URL of your tool's source code repository.
99
+
*`<Donate>` A URL to a website where donations can be made to support your tool.
100
+
*`<Documentation>` A URL to a website where your tool's documentation can be viewed.
0 commit comments