Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tweak formatting in DEVELOPING.md #202

Merged
merged 1 commit into from
Oct 17, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,38 +75,38 @@ Start a hot-reload server with `mkdocs serve`, and run `mkdocs build` to produce
1. First, make sure you can build the plugin using the instructions in either [Building the plugin using the Rack SDK](#building-the-plugin-using-the-rack-sdk) or [Building the plugin using the complete VCV Rack source](#building-the-plugin-using-the-complete-vcv-rack-source) above.
2. Optional: Sign up for a [GitHub] account and create a new fork in your own account for the firmware repo for the module you want to to modify.
3. Create a new firmware submodule inside the `firmware` folder. Let's say we want to create a new development version of the teletype firmware and call it `teletype-dev` within the Rack environment.
```bash
$ cd monome-rack
$ cd firmware
$ git submodule add https://github.com/<your user name>/teletype teletype-dev
```
```bash
$ cd monome-rack
$ cd firmware
$ git submodule add https://github.com/<your user name>/teletype teletype-dev
```
4. Run `git submodule update` again to make sure we have the submodules of the new submodule.
```bash
$ git submodule update --init --recursive
```
```bash
$ git submodule update --init --recursive
```
5. Add `teletype-dev` to our list of firmware binaries to build and add to the plugin. Edit `Makefile` in the monome-rack root folder and under the `firmware-build:` section, add the line:
```
cd firmware && $(MAKE) -f teletype.mk TARGET_NAME=teletype-dev
```
Make sure is indented with a single tab character, like the other lines in the section.
```
cd firmware && $(MAKE) -f teletype.mk TARGET_NAME=teletype-dev
```
Make sure this line is indented with a single tab character, like the other lines in the section.
6. Rebuild the plugin using `make install` or the Visual Studio Code **Run Build Task...** command, as in step 1.
7. Run Rack and place a Teletype module. You should be able to see `teletype-dev` as one of the choices in the **Firmware Tools** > **Switch Firmware** right-click menu. Switch to it! You're now using the code from the new submodule folder you created in step 3.
8. Let's make some changes to the code. Open `firmware/teletype-dev/module/live_mode.c` and go to line 771. Change the string `"TELETYPE "` to something else, like `"HELLO "`. Leave the space at the end of the string.
9. Rebuild the plugin again as in step 6.
10. Run Rack again, and now any Teletype modules in your patch running the `teletype-dev` firmware should say **HELLO** on the startup screen instead of **TELETYPE**.
11. Now you can make some more substantial changes. Fix a bug, add a new feature, or erase everything and create a completely new module.
* Note: if your goal is to create new behavior for the module from scratch, you'll need to preserve the `initialize_module()` and `check_events()` functions, but most everything else is fair game. You'll need to use the `DECLARE_VRAM` and `DECLARE_NVRAM` macros on your key data structures to have them preserved in the Rack patch. Compare the `whitewhale` and `whitewhale-kria` submodules to see and example of two different firmware for the same module.
* Modifying the firmware can't change anything about the Rack "virtual hardware"; it will have the same panel, with the same inputs, outputs, and controls. If you're making something new, pick the module that best aligns with the I/O needs of your new idea. (The name of the firmware determines which module the firmware will be available for, and therefore which panel and I/O will be used, so when you create the new submodule, make sure your submodule folder name starts with the name of the base module.)
* Note: if your goal is to create new behavior for the module from scratch, you'll need to preserve the `initialize_module()` and `check_events()` functions, but most everything else is fair game. You'll need to use the `DECLARE_VRAM` and `DECLARE_NVRAM` macros on your key data structures to have them preserved in the Rack patch. Compare the `whitewhale` and `whitewhale-kria` submodules to see and example of two different firmware for the same module.
* Modifying the firmware can't change anything about the Rack "virtual hardware"; it will have the same panel, with the same inputs, outputs, and controls. If you're making something new, pick the module that best aligns with the I/O needs of your new idea. (The name of the firmware determines which module the firmware will be available for, and therefore which panel and I/O will be used, so when you create the new submodule, make sure your submodule folder name starts with the name of the base module.)
12. When you have made something interesting and want to share it, you'll need to commit back to your firmware fork. It's probably a good idea to first create a branch:
```bash
$ cd firmware/teletype-dev
$ git checkout -b my_new_feature
```
```bash
$ cd firmware/teletype-dev
$ git checkout -b my_new_feature
```
13. Now push that branch to your fork:
```bash
$ git push -u origin my_new_feature
```
```bash
$ git push -u origin my_new_feature
```
14. Note that this will *not* create any commits in your local copy of the monome-rack repo. This is okay, as you don't need to commit the changes to Rack to add your development firmware. You can share the firmware binaries from the `res` folder to other people and they won't have to build anything. Alternately, they can add your firmware to their build environment themselves by following steps 3-6, with one change to add the `-b` option to the `git submodule add` command:
```bash
$ git submodule add -b my_new_feature https://github.com/<your user name>/teletype teletype-dev
```
```bash
$ git submodule add -b my_new_feature https://github.com/<your user name>/teletype teletype-dev
```
Loading