Automatic Resource Configuration in IPlug2

21 May 2020

Adding a script to the build process that automatically catalogs resource files

Adding Resources the Normal Way

Suppose you’re developing a plugin, MyPlugin, with IPlug2, and you’ve just downloaded a font that you want to add to the project.

To use the new font in the project, you must:

Specify the font filename in config.h:
config.h
```
#define DS_DIGII_FN "DS-DIGII.TTF"
```
Delve into main.rc, viewing the file directly (instead of Visual Studio’s Resource View), scroll to the bottom where you’ll see the Generated from the TEXTINCLUDE 3 resource block, and add this line:
main.rc
```
///////////////////////////////////////////////////////////////
  //
  // Generated from the TEXTINCLUDE 3 resource.
  //
  #include "..\config.h"
  DS_DIGII_FN TTF DS_DIGII_FN
  
```
Finally, load the font in your plugin’s main .cpp file:
MyPlugin.cpp
```
Graphics->LoadFont("DS-DIGII", DS_DIGII_FN);
```

You can’t get around having to load the font in your .cpp file, but don’t the first two steps seem a little boilerplate? What if I need to add 50 presets as resources?

Automating Resource Registration

Philipe Zenz wrote a python script to scan the contents of your resources directory and generate the references to the each file. Macros are generated automatically in the format FN_ + filename. The filename omits file extension, is uppercase, and alphanumeric.

So my filename DS-DIGII.tff will be converted to FN_DSDIGII.

Here are the steps to get this working:

Download the script here (right click and 'Save Link As...') and place it in your plugin’s scripts directory.
Assuming you have python installed, ensure that you have an environment variable called PYTHON pointing to your python installation.
Open scripts/prebuild-win.bat and append the following line:
```
"%PYTHON%/python.exe" ../scripts/write_resource_files-win.py
```
Adding this line makes it so any new resources will be cataloged every time the plugin is built.
In config.h, instead of the #define statements for each resource, we will #include a file generated by the script which contains them:
```
#include "resourceconfig.h"
```
Once it is generated, make sure to add resourceconfig.h to the solution by right-clicking MyPlugin-app in the Solution Explorer and clicking Add -> Existing Item. This way MyPlugin.cpp will recognize the macros defined within.
In main.rc, include another generated file in place of the resource declarations from before:
```
///////////////////////////////////////////////////////////////
  //
  // Generated from the TEXTINCLUDE 3 resource.
  //
  #include "..\config.h"
  #include "auto.rc"
```
Do NOT add auto.rc to the solution. Your builds will fail as the macros defined in the resource script are interpreted as filenames, resulting in this error:
```
1>..\resources\auto.rc(1): error RC2135: file not found: FN_DSDIGII
```

That should be it! If you’re wondering why this functionality isn’t built into IPlug2 automatically, consider the fact that the script sets a precedent for the format of the generated macros, and that every file added to resources will be cataloged. Adding this to the library now will break any existing applications that upgrade to the newest version who aren’t using the predefined format, and establishing such a format for resource macros is taking a bit too much agency from the developer.

But, if you’re starting out a new project and are fine with the format, this is a pleasant quality of life improvement.