getting-started.md (5960B)
1 - [Overview](#overview) 2 - [0. Setting up your build environment](#0-setting-up-your-build-environment) 3 - [Windows](#windows) 4 - [Mac](#mac) 5 - [1. Creating a new project](#1-creating-a-new-project) 6 - [2. Editing your gen~ patch](#2-editing-your-gen-patch) 7 - [3. Exporting code from gen~](#3-exporting-code-from-gen) 8 - [4. Generate VCV Rack module code](#4-generate-vcv-rack-module-code) 9 - [Optional - Adjust module GUI](#optional---adjust-module-gui) 10 - [5. Register your module](#5-register-your-module) 11 - [`plugin.hpp`](#pluginhpp) 12 - [`plugin.cpp`](#plugincpp) 13 - [`plugin.json`](#pluginjson) 14 - [6. Building and installing the module](#6-building-and-installing-the-module) 15 16 17 # Overview 18 19 The workflow to generate a VCV Rack module will involve the following steps: 20 21 0. Set up a VCV Rack building environment. 22 1. Create a new project in the `/gen/projects/` directory which contains a template Max patch and some helper NodeJS scripts. 23 2. In that project, open the `builder.maxpat` and edit your `gen~` patch. 24 3. When you're ready, export the C++ code from `gen~`. It'll land in the `/gen/exports/` directory. 25 4. Still in the `builder.maxpat`, use the provided Node for Max script to generate the VCV Rack module code. 26 5. Make a few edits to `/src/plugin.cpp` and `plugin.json`. 27 6. Build and install your new VCV Rack module from the command line with `make install`. 28 29 30 Most of the heavy lifting is done by these scripts, so going from a `gen~` patch to a new VCV Rack module can be done in as little as a few minutes as opposed to hours. 31 32 33 # 0. Setting up your build environment 34 35 Requirements: 36 - Max 8 (Windows or Mac) 37 - VCV Development Environment 38 - See the official [documentation](https://vcvrack.com/manual/Building) for how to set this up. You do not need to build Rack from scratch, just install the packages (via MSYS2 on Windows or homebrew on Mac) as needed and download a copy of the [Rack SDK](https://vcvrack.com/downloads/). 39 40 41 # 1. Creating a new project 42 43 To create a new project, you can either copy and paste an existing project from the `/gen/projects/` directory or use the `/gen/projects/new-project.maxpat` which will do a copy for you. 44 45 # 2. Editing your gen~ patch 46 47  48 49 In your project folder, open the `builder.maxpat`. Edit the name of the project in the "name" textedit box. This will set the proper export folder for the `gen~` object. 50 51 Edit your `gen~` patch. Note that any inputs or outputs must be in the range -1 to 1. They will then be scaled to -5 to 5 volts in your VCV Rack module. 52 53 When to use inputs vs params: 54 - Inputs are processed at audio rate and have no knobs on the resulting VCV Rack interface. 55 - Params are processed at block rate and have both knobs and CV input on the VCV Rack interface. 56 57 # 3. Exporting code from gen~ 58 59 Hit the `exportcode` message box! 60 61 You can check everything was exported by looking in the `/gen/exports/` directory. There should be a `.cpp` and `.h` file with the name of your module. (If there isn't, check the inspector to make sure the `gen~` object's export folder is set to `/gen/exports/`.) 62 63  64 65 # 4. Generate VCV Rack module code 66 67 Hit the `create $1` message box. This runs the `builder.js` script which will create the boilerplate VCV Rack module code in `/src/modules/`. 68 69  70 71 Behind the scenes, it is using the `/src/modules/module.in` template and replacing some text to properly change the namespace, display name, and a few variables to match up with the name of your exported code. 72 73 ## Optional - Adjust module GUI 74 75 If you're comfortable editing the look of your VCV Rack module, it is in this newly generated `.cpp` file where you can change the UI of your module. You'll want to take a look at the `struct` which inherits from `ModuleWidget` and make your changes there. 76 77 # 5. Register your module 78 79 VCV Rack groups modules into groups called plugins. You've created a module, but you need to register it with your plugin. 80 81 ## `plugin.hpp` 82 The builder script has already added a line to the end of `/src/plugin.hpp` that looks like this: 83 84 ``` 85 extern Model* modelMyModule; 86 ``` 87 88 This exposes the model for your module (which pairs the processing and interface parts of your module) so that the VCV Rack engine will know to register your plugin. Make sure this file looks okay. You can remove any duplicates if there are any. 89 90 ## `plugin.cpp` 91 92 You'll also need to register the plugin in `/src/plugin.cpp`. For this `myModule` example, I'd edit `/src/plugin.cpp` to look like this: 93 94 ``` 95 void init(Plugin* p) { 96 pluginInstance = p; 97 98 // GENRACK: add modules here 99 p->addModel(modelMyModule); 100 } 101 ``` 102 103 For any additional modules you create, you'll need to register them in the same way by adding in more lines in the designated area. 104 105 ## `plugin.json` 106 107 This is the third and final place to register the module as part of your plugin. 108 109 The easiest way to see how to add modules to your plugin is to take a look at existing `plugin.json` files in the library. For example, see the `plugin.json` for the [Fundamental](https://github.com/VCVRack/Fundamental/blob/v2/plugin.json) modules. 110 111 For our example, I'll simply add `myModule` as the only module. 112 113 ``` 114 "modules": [ 115 { 116 "slug" : "myModule", 117 "name" : "myModule", 118 "description" : "My first gen-rack module", 119 "tags" : [ 120 "effect" 121 ] 122 } 123 ] 124 ``` 125 126 127 # 6. Building and installing the module 128 129 Now you should just need to open a terminal window, `cd` to the `gen-rack` directory, and run `make install`. (Do make sure you've exported the `RACK_DIR` environment variable as described in the [VCV Rack dev docs](https://manual.vcvrack.com/Building#setting-up-your-development-environment).) 130 131 (You may see some warnings about unused variables. This is okay.) 132 133 Open up VCV and check out your new module! 134 135 