Differences
This shows you the differences between two versions of the page.
| setting_up_a_development_environment [2024/06/27 00:08] – external edit 127.0.0.1 | setting_up_a_development_environment [2026/04/07 18:27] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ===== Setting up an Indigo Plugin Development Environment ===== | ===== Setting up an Indigo Plugin Development Environment ===== | ||
| If you're interested in developing an Indigo plugin to share with other users or just for yourself, the way you approach development can make a big difference. Whether you choose to write your Indigo plugin without any specialized tools or expensive software packages, or instead choose one of the open source applications -- or even a plain text editor -- there are ways to make the process easier and more streamlined. This page describes many authoring packages and steps you can take to make your effort more successful. | If you're interested in developing an Indigo plugin to share with other users or just for yourself, the way you approach development can make a big difference. Whether you choose to write your Indigo plugin without any specialized tools or expensive software packages, or instead choose one of the open source applications -- or even a plain text editor -- there are ways to make the process easier and more streamlined. This page describes many authoring packages and steps you can take to make your effort more successful. | ||
| + | |||
| ===== Integrated Development Environments ===== | ===== Integrated Development Environments ===== | ||
| - | Using an Integrated Development Environment (IDE) can make writing Indigo plugins much easier. | + | Using an Integrated Development Environment (IDE) can make writing Indigo plugins much easier. |
| * [[https:// | * [[https:// | ||
| * [[https:// | * [[https:// | ||
| - | * [[https:// | + | * [[https:// |
| * [[https:// | * [[https:// | ||
| * [[https:// | * [[https:// | ||
| * [[https:// | * [[https:// | ||
| - | |||
| - | |||
| ===== Other Editors ===== | ===== Other Editors ===== | ||
| + | You can use any of several great text editors to write plugin code, but one aspect is crucial -- they must be able to save **plain text files**. | ||
| - | You can use any of several great text editors | + | * **TextEdit** - the editor that ships with macOS. If you choose |
| + | * [[https:// | ||
| - | * **TextEdit** - the editor that ships with macOS. If you choose to use Apple' | ||
| - | * [[https:// | ||
| ===== Setting Up Your Development Environment ===== | ===== Setting Up Your Development Environment ===== | ||
| Choosing what tools to use to develop your plugin is only one of the considerations you'll need to address. You'll also need to decide how you're going to configure your environment. | Choosing what tools to use to develop your plugin is only one of the considerations you'll need to address. You'll also need to decide how you're going to configure your environment. | ||
| Line 23: | Line 22: | ||
| * **Project organization considerations** -- will you be developing on the same machine where your Indigo server lives? Where will your project files be located? On your machine? Online? A common approach is to have a separate folder structure just for development -- with subfolders dedicated to each project. You should also consider whether you'll benefit from a common location within your project space that can be used for segments of code that you'll use across multiple plugin projects. | * **Project organization considerations** -- will you be developing on the same machine where your Indigo server lives? Where will your project files be located? On your machine? Online? A common approach is to have a separate folder structure just for development -- with subfolders dedicated to each project. You should also consider whether you'll benefit from a common location within your project space that can be used for segments of code that you'll use across multiple plugin projects. | ||
| * **Virtual environments** -- some developers choose to build their projects using [[https:// | * **Virtual environments** -- some developers choose to build their projects using [[https:// | ||
| - | * **Backups and version control** -- You'll want to save your work along the way. Backups are easy. Make them. Often. But you'll also want to be in a position to be able to revert back to prior versions in case you decide to undo some changes you've made. Github | + | * **Backups and version control** -- You'll want to save your work along the way. Backups are easy. Make them. Often. But you'll also want to be in a position to be able to revert back to prior versions in case you decide to undo some changes you've made. GitHub |
| * **Plugin versioning** -- You'll need to come up with a way to assign version numbers to your plugin. By incrementing the version number with each release, Indigo will be better able to identify updates and more easily install them--version numbers are required if you release your plugin through the Indigo Plugin Store. There are many ways to do versioning, but it's common to use a two- or three-number [[https:// | * **Plugin versioning** -- You'll need to come up with a way to assign version numbers to your plugin. By incrementing the version number with each release, Indigo will be better able to identify updates and more easily install them--version numbers are required if you release your plugin through the Indigo Plugin Store. There are many ways to do versioning, but it's common to use a two- or three-number [[https:// | ||
| * Major version - often incremented with substantial changes to the software. | * Major version - often incremented with substantial changes to the software. | ||
| * Minor version - often incremented with new features or enhancements. | * Minor version - often incremented with new features or enhancements. | ||
| * Patch - often incremented with bug fixes and minor code refinements. | * Patch - often incremented with bug fixes and minor code refinements. | ||
| - | * **Collaboration** -- will you be working on the plugin by yourself or will you be coordinating with other developers? | + | * **Collaboration** -- will you be working on the plugin by yourself or will you be coordinating with other developers? |
| * **Symlinks** | * **Symlinks** | ||
| - Open two Finder windows, one pointing to the folder that contains your plugin code and the second pointing to the Indigo file tree. | - Open two Finder windows, one pointing to the folder that contains your plugin code and the second pointing to the Indigo file tree. | ||
| Line 35: | Line 34: | ||
| - Drag the Indigo Plugins (Disabled) folder and drop it on the Terminal window, so it looks something like this:< | - Drag the Indigo Plugins (Disabled) folder and drop it on the Terminal window, so it looks something like this:< | ||
| </ | </ | ||
| - | - Switch to Terminal and hit < | + | - Switch to Terminal and hit return. If things went according to plan, you should see your plugin in the Plugins (Disabled) folder with a small arrow in the lower left corner (indicating that it's a linked file). |
| - Restart the Indigo server and you should see your plugin in the Plugins Menu. With the file successfully linked, you can safely Enable and Disable the plugin in Indigo and the operating system will update the symbolic link accordingly. | - Restart the Indigo server and you should see your plugin in the Plugins Menu. With the file successfully linked, you can safely Enable and Disable the plugin in Indigo and the operating system will update the symbolic link accordingly. | ||
| * **Hosting** -- If you choose to share your plugin with the world, you'll need a place to host the plugin files so that others can download it. | * **Hosting** -- If you choose to share your plugin with the world, you'll need a place to host the plugin files so that others can download it. | ||
| - | * **Indigo Plugin Store** -- The recommended way to share plugins with other Indigo users is via the Indigo Plugin Store. By using the store, you get a central place where users can search for plugins to solve various scenarios, you get built-in version notifications to users via the Mac Client, etc. Check out the [[https:// | + | * **Indigo Plugin Store** -- The recommended way to share plugins with other Indigo users is via the Indigo Plugin Store. By using the store, you get a central place where users can search for plugins to solve various scenarios, you get built-in version notifications to users via the Mac Client, etc. Check out the [[https:// |
| - | * **Github** -- Many developers manage their plugin code on GitHub, and in fact you can configure your Plugin Store entry to pull information and releases from Github | + | * **GitHub** -- Many developers manage their plugin code on GitHub, and in fact you can configure your Plugin Store entry to pull information and releases from GitHub |
| * **Providing Support** -- If you choose to share your plugin with others, it's inevitable that someone will have a question, an issue, or want to contribute code to your effort. There are a variety of ways to do this, but there are several common approaches that developers currently use: | * **Providing Support** -- If you choose to share your plugin with others, it's inevitable that someone will have a question, an issue, or want to contribute code to your effort. There are a variety of ways to do this, but there are several common approaches that developers currently use: | ||
| * **Indigo Forums** - many developers have dedicated forums for their plugins on the Indigo forums site. If you think your plugin might qualify for its own forum, please [[mailto: | * **Indigo Forums** - many developers have dedicated forums for their plugins on the Indigo forums site. If you think your plugin might qualify for its own forum, please [[mailto: | ||
| - | * **Github | + | * **GitHub |
| - | * **Plugin Issues** - Some developers prefer users report problems via the Indigo forums, while others prefer users to file issues on Github. | + | * **Plugin Issues** - Some developers prefer users report problems via the Indigo forums, while others prefer users to file issues on GitHub. |
| ===== Debugging ===== | ===== Debugging ===== | ||
| As a quick summary, Indigo plugins and scripts must run in a special process called the Indigo Plugin Host. That process bridges Indigo native objects (C++ objects) to python. One side effect of this requirement is that debugging a plugin has some special challenges. For instance, you can't directly debug plugins from most of the IDEs listed above. | As a quick summary, Indigo plugins and scripts must run in a special process called the Indigo Plugin Host. That process bridges Indigo native objects (C++ objects) to python. One side effect of this requirement is that debugging a plugin has some special challenges. For instance, you can't directly debug plugins from most of the IDEs listed above. | ||
| Line 49: | Line 49: | ||
| However, we have facilitated the use a several Python debuggers together with Indigo: | However, we have facilitated the use a several Python debuggers together with Indigo: | ||
| - | * [[https:// | + | * [[https:// |
| - | * [[https:// | + | * [[https:// |
| - | * [[https:// | + | * [[https:// |
| Each has its pros and cons, but all are a significant improvement over '' | Each has its pros and cons, but all are a significant improvement over '' | ||
| In the Plugins Preferences tab, there is a Development section: | In the Plugins Preferences tab, there is a Development section: | ||
| - | {{ : | + | {{ : |
| (Bet you didn't even remember that tab was there). Because we need to start plugins in a special way for debugging to work, we need to show some special debugging menus. Check the checkbox to see those menus in each plugin' | (Bet you didn't even remember that tab was there). Because we need to start plugins in a special way for debugging to work, we need to show some special debugging menus. Check the checkbox to see those menus in each plugin' | ||
| Line 68: | Line 68: | ||
| ==== pdb ==== | ==== pdb ==== | ||
| [[https:// | [[https:// | ||
| - | {{ : | + | {{ : |
| To add breakpoints to your code, you just add '' | To add breakpoints to your code, you just add '' | ||
| ==== PuDB ==== | ==== PuDB ==== | ||
| [[http:// | [[http:// | ||
| - | {{ : | + | {{ : |
| As with pdb, you add breakpoints to your code by adding '' | As with pdb, you add breakpoints to your code by adding '' | ||
| ==== PyCharm ==== | ==== PyCharm ==== | ||
| - | + | Finally, we were able to use PyCharm' | |
| - | Finally, we were able to use PyCharm' | + | |
| === Configure Local Debugging === | === Configure Local Debugging === | ||
| - | |||
| The most straight-forward debug configuration is to use PyCharm to debug your plugin running in Indigo on the same Mac. With your plugin' | The most straight-forward debug configuration is to use PyCharm to debug your plugin running in Indigo on the same Mac. With your plugin' | ||
| - | {{ : | + | {{ : |
| - | There are three important config parameters in this dialog (you can name the configuration anything you want). The first two tell how to connect: specify localhost in the **Local host name** box and 5678 in the **Port** field. The next field you need to adjust is the Path mappings field. | + | There are three important config parameters in this dialog (you can name the configuration anything you want). The first two tell how to connect: specify localhost in the **Local host name** box and 5678 in the **Port** field. The next field you need to adjust is the Path mappings field. |
| Recall that the recommended way of developing Indigo plugins is to put your plugin in a central location (not inside the Indigo folders), then make a symbolic link to it in the Plugins directory. We do this because the Indigo server moves a plugin between two different folders when enabling/ | Recall that the recommended way of developing Indigo plugins is to put your plugin in a central location (not inside the Indigo folders), then make a symbolic link to it in the Plugins directory. We do this because the Indigo server moves a plugin between two different folders when enabling/ | ||
| - | Because of this, you need to tell PyCharm where the actual path to the source is when the plugin is enabled and being debugged. Click the ellipsis button at the end of the **Path mappings** field to add a mapping. On the **Local path** side, you want to specify the actual path to your plugin' | + | Because of this, you need to tell PyCharm where the actual path to the source is when the plugin is enabled and being debugged. Click the ellipsis button at the end of the **Path mappings** field to add a mapping. On the **Local path** side, you want to specify the actual path to your plugin' |
| One other option is the **Suspend after connect** checkbox: if you have that checked, then when your plugin restarts with the debugger, it will pause execution in the '' | One other option is the **Suspend after connect** checkbox: if you have that checked, then when your plugin restarts with the debugger, it will pause execution in the '' | ||
| + | |||
| + | <color # | ||
| That's it for setup! To debug, just run the debug configuration and then restart your plugin in the debugger. Unlike when using pdb and PuDB, you don't need to add explicit breakpoints to the source code using '' | That's it for setup! To debug, just run the debug configuration and then restart your plugin in the debugger. Unlike when using pdb and PuDB, you don't need to add explicit breakpoints to the source code using '' | ||
| - | {{ : | + | {{ : |
| You can step through code, inspect, etc., just like you are debugging any other Python project. | You can step through code, inspect, etc., just like you are debugging any other Python project. | ||
| We hope that you'll find a great debugging solution for your needs in one of these options. We've added a couple of new API methods on the plugin objects that are part of this change: | We hope that you'll find a great debugging solution for your needs in one of these options. We've added a couple of new API methods on the plugin objects that are part of this change: | ||
| Line 117: | Line 117: | ||
| def main(argv): | def main(argv): | ||
| parser = argparse.ArgumentParser( | parser = argparse.ArgumentParser( | ||
| - | description=" | + | description=" |
| ) | ) | ||
| parser.add_argument( | parser.add_argument( | ||
| Line 149: | Line 149: | ||
| </ | </ | ||
| And you would set up the external tool with these settings: | And you would set up the external tool with these settings: | ||
| - | {{ : | + | {{: |
| Now, when you use that External Tool, it will reload your plugin with the debugger enabled. You can even configure your debug run configuration to run this as a **Before launch** tool (see the configuration image above). So every time you run the debug configuration, | Now, when you use that External Tool, it will reload your plugin with the debugger enabled. You can even configure your debug run configuration to run this as a **Before launch** tool (see the configuration image above). So every time you run the debug configuration, | ||
| === Configure Remote Debugging (Experimental) === | === Configure Remote Debugging (Experimental) === | ||
| - | |||
| The above local debugging configuration presumes that the Indigo Server and the plugin you are debugging are running on the same machine on which you are running PyCharm. It's also possible (and experimental at this point) to debug a plugin running on an Indigo Server on a separate Mac on the network from the one on which you are running PyCharm. We're listing this approach as experimental for the time being as it hasn't been fully tested; however, the implementation shows promise. | The above local debugging configuration presumes that the Indigo Server and the plugin you are debugging are running on the same machine on which you are running PyCharm. It's also possible (and experimental at this point) to debug a plugin running on an Indigo Server on a separate Mac on the network from the one on which you are running PyCharm. We're listing this approach as experimental for the time being as it hasn't been fully tested; however, the implementation shows promise. | ||
| - | The setup is isn't radically different than the local configuration outlined above: it's the same " | + | The setup isn't radically different than the local configuration outlined above: it's the same " |
| < | < | ||
| Line 172: | Line 171: | ||
| ==== Plugin Specific Interactive Shell ==== | ==== Plugin Specific Interactive Shell ==== | ||
| - | |||
| Another great debugging tool is the ability to open a scripting shell that's specific to your plugin' | Another great debugging tool is the ability to open a scripting shell that's specific to your plugin' | ||
| + | ==== Detecting if Your Plugin is in Debug Mode ==== | ||
| + | It may be useful for your plugin to be able to detect whether it has been loaded in Debug Mode (Plugin Menu > My Plugin > Enable/ | ||
| - | ===== Tips, Tricks and Best Practices ===== | + | < |
| + | indigo.host.debugMode() | ||
| + | </ | ||
| - | ==== External Requirements ==== | + | Possible values are currently these integers: |
| + | < | ||
| + | kPluginDebugMode_none = 0, | ||
| + | kPluginDebugMode_debugPdb = 100, | ||
| + | kPluginDebugMode_debugPudb, | ||
| + | kPluginDebugMode_debugPyCharm, | ||
| + | kPluginDebugMode_debugShell = 200 | ||
| + | </ | ||
| + | |||
| + | ===== Tips, Tricks and Best Practices ===== | ||
| + | ==== External Requirements ==== | ||
| Python has a huge collection of libraries/ | Python has a huge collection of libraries/ | ||
| - | One option for setting up your development environment would be to create a virtual environment into which you install/ | + | One option for setting up your development environment would be to create a virtual environment into which you install/ |
| Once you create a virtual environment (let's say you named it '' | Once you create a virtual environment (let's say you named it '' | ||
| Line 210: | Line 222: | ||
| And this will write out the packages you have installed in your '' | And this will write out the packages you have installed in your '' | ||
| - | |||
| ==== Indigo Utilities ==== | ==== Indigo Utilities ==== | ||
| Line 222: | Line 233: | ||
| **//The indigo-clean-and-zip-plugin utility is especially useful for developers// | **//The indigo-clean-and-zip-plugin utility is especially useful for developers// | ||
| + | |||
| ==== Linters ==== | ==== Linters ==== | ||
| There are several utilities available to improve your code; one type of utility is often referred to as a " | There are several utilities available to improve your code; one type of utility is often referred to as a " | ||
| * Syntax problems, | * Syntax problems, | ||
| - | * Duplicated code segments, | + | * Duplicated code segments, |
| * typos, and | * typos, and | ||
| * other potential issues. | * other potential issues. | ||
| Line 238: | Line 250: | ||
| debug_mode_bool = bool(debug_mode) | debug_mode_bool = bool(debug_mode) | ||
| </ | </ | ||
| - | |||
| ==== No Module Named ' | ==== No Module Named ' | ||
| Line 249: | Line 260: | ||
| </ | </ | ||
| You will likely still get a syntax error warning on the '' | You will likely still get a syntax error warning on the '' | ||
| - | |||
| - | |||
| - | |||