Differences

This shows you the differences between two versions of the page.

--- setting_up_a_development_environment [2026/03/06 00:00] – [Plugin Specific Interactive Shell] davel17
+++ 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 =====
 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 =====
-Using an Integrated Development Environment (IDE) can make writing Indigo plugins much easier.  IDEs are programming environments that can help you reference Python functions, make recommendations on syntax, and even color code and highlight sections of code to make things easier for you. There are way too many Python IDEs to list them all here, but the more poplar ones include (in alphabetical order):
+Using an Integrated Development Environment (IDE) can make writing Indigo plugins much easier.  IDEs are programming environments that can help you reference Python functions, make recommendations on syntax, and even color code and highlight sections of code to make things easier for you. There are way too many Python IDEs to list them all here, but the more popular ones include (in alphabetical order):
   * [[https://atom.io|Atom]] - Atom is a free and open-source text and source code editor for macOS, Linux, and Microsoft Windows with support for plug-ins written in JavaScript, and embedded Git Control. It was developed by GitHub. **NOTE:** Atom and all projects under the Atom organization are slated for an official sunset on December 15, 2022.
   * [[https://www.barebones.com|BBEdit]] - BBEdit is a proprietary text editor made by Bare Bones Software, originally developed for Macintosh System Software 6, and currently supporting macOS. The free version of BBEdit works very well for writing Indigo plugins, and the paid version includes some IDE-type integration as well.
-  * [[https://www.jetbrains.com/pycharm/|PyCharm]] - PyCharm is an excellent full-featured commercial Python development environment made by Jetbrains. There are several licenses available for PyCharm from paid to free -- the license you need depends on what you use the program for.  **NOTE:** for certain features (including the ability to debug Indigo plugins from within the IDE) require a paid PyCharm Professional Edition license.
+  * [[https://www.jetbrains.com/pycharm/|PyCharm]] - PyCharm is an excellent full-featured commercial Python development environment made by JetBrains. There are several licenses available for PyCharm from paid to free -- the license you need depends on what you use the program for.  **NOTE:** for certain features (including the ability to debug Indigo plugins from within the IDE) require a paid PyCharm Professional Edition license.
   * [[https://www.spyder-ide.org|Spyder]] - Spyder is an open-source cross-platform integrated development environment for scientific programming in the Python language. While it is more geared towards scientific programming, it works for non-scientific applications, too.
   * [[https://www.sublimetext.com|Sublime Text]] - Sublime Text is a shareware cross-platform source code editor. It natively supports many programming languages and markup languages. Users can expand its functionality with plugins, typically community-built and maintained under free-software licenses.
   * [[https://code.visualstudio.com|VSCode]] - VSCode is a free source code editor made by Microsoft that runs on Mac, Linux and Windows. VSCode is an extremely popular tool used for Python development.
 ===== 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**.
   * **TextEdit** - the editor that ships with macOS. If you choose to use Apple's TextEdit app, when you save your code to file, you MUST select **Make Plain Text** from the **Format** menu, and when you save, be sure that the **Plain Text Encoding** is set to ''Unicode (UTF-8)''.
   * [[https://www.vim.org|vim]] - Vim is a highly configurable text editor built to make creating and changing any kind of text very efficient. It is included as "vi" with most UNIX systems and with Apple OS X.
 ===== 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.
@@ Line 44: / Line 43: @@
     * **GitHub Wikis** - many developers write documentation for their plugins, and on popular way to make that available to others is by creating a dedicated wiki page on GitHub.
     * **Plugin Issues** - Some developers prefer users report problems via the Indigo forums, while others prefer users to file issues on GitHub.
 ===== 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.
@@ Line 77: / Line 77: @@
 ==== PyCharm ====
+Finally, we were able to use PyCharm's **Python Debug Server** feature to enable plugin debugging (formerly referred to as "remote debugging"). It requires a bit more setup, but if you want to use a fantastic modern IDE, this is the choice for you. **Note**: because we're using the Debug Server feature, you can only use the paid professional version of PyCharm as the community edition doesn't support it.
-Finally, we were able to use PyCharm's **Python Debug Server** feature to enable plugin debugging (formerly referred to as "remote debugging"). It requires a bit more setup, but if want to use a fantastic modern IDE, this is the choice for you. **Note**: because we're using the Debug Server feature, you can only use the paid professional version of PyCharm as the community edition doesn't support it.
 === 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's project open in PyCharm, create a run configuration of type **Python Debug Server ** (formerly **Remote Python Debug**):
@@ Line 90: / Line 88: @@
 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/disabling. An IDE/editor will get confused when this happens, so by putting the actual code in a place that never moves and allowing the Indigo Server to move a symbolic link around, you get around this issue.
-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's source (i.e. /Users/you/path/to/myplugin.indigoPlugin). On the **Remote path** side, you want to specify the path to your plugin's symlink when the plugin is enabled (i.e. ''/Library/Application Support/Perceptive Automation/Indigo 2022.1/Plugins/myplugin.indigoPlugin)''. **TIP:** to get the path to a file in the Finder, right click on the file to show the contextual menu, then press the Option key. The Copy item will change to Copy as Pathname which is exactly what you want.
+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's source (i.e. /Users/you/path/to/myplugin.indigoPlugin). On the **Remote path** side, you want to specify the path to your plugin's symlink when the plugin is enabled (i.e. ''/Library/Application Support/Perceptive Automation/Indigo 2022.1/Plugins/myplugin.indigoPlugin)''. **TIP:** to get the path to a file in the Finder, right-click on the file to show the contextual menu, then press the Option key. The Copy item will change to Copy as Pathname which is exactly what you want.
 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 ''__init__()'' method. We don't recommend doing this since you can add breakpoints anywhere you want in the code, including in the ''__init__()'' method.
@@ Line 119: / Line 117: @@
 def main(argv):
     parser = argparse.ArgumentParser(
-        description="Restart a plugin given it's full name or ID"
+        description="Restart a plugin given its full name or ID"
     )
     parser.add_argument(
@@ Line 156: / Line 154: @@
 === 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 setup is isn't radically different than the local configuration outlined above: it's the same "Python Debug Server" configuration, EXCEPT that you specify an IP address. In the Debug configuration in PyCharm you specify the IP address of the Mac //PyCharm// is running on (local won't work, it has to be the IP address). In the plugin's init method, make the very first line of the init method:
+The setup isn't radically different than the local configuration outlined above: it's the same "Python Debug Server" configuration, EXCEPT that you specify an IP address. In the Debug configuration in PyCharm you specify the IP address of the Mac //PyCharm// is running on (local won't work, it has to be the IP address). In the plugin's init method, make the very first line of the init method:
 <code>
@@ Line 174: / Line 171: @@
 ==== Plugin Specific Interactive Shell ====
 Another great debugging tool is the ability to open a scripting shell that's specific to your plugin's context. This shell is like the more general shell you get when you select the **Plugins->Open Scripting Shell** menu item, except that because we launch it as part of your plugin's startup, it has access to everything in your plugin. You can call methods that your plugin implements, inspect your plugin's objects, etc.
@@ Line 193: / Line 189: @@
 kPluginDebugMode_debugShell = 200
 </code>
 ===== Tips, Tricks and Best Practices =====
 ==== External Requirements ====
 Python has a huge collection of libraries/modules available on [[https://pypi.org|pypi.org]] and installable with the ''pip3'' command. Your plugin can use those libraries, and by specifying which of those libraries in a ''requirements.txt'' file, Indigo will automatically install those when your plugin first starts. Check out the [[https://www.indigodomo.com/docs/python_packages#python_packages_for_plugin_developers|Python Packages for Plugin Developers]] section of the developer docs (**starting with the 2023.2 release**) for more details.
-One option for setting up your development environment would be to create a virtual environment into which you install/manage the libraries that your plugin will need. This is best done when you first start working on a plugin or when you make significant changes (additional libraries, etc). There's lots of information available online regarding setting up and working with virtual environments--it may be best to start at [[https://docs.python.org/3.11/library/venv.html|the source]].
+One option for setting up your development environment would be to create a virtual environment into which you install/manage the libraries that your plugin will need. This is best done when you first start working on a plugin or when you make significant changes (additional libraries, etc.) There's lots of information available online regarding setting up and working with virtual environments--it may be best to start at [[https://docs.python.org/3.11/library/venv.html|the source]].
 Once you create a virtual environment (let's say you named it ''venv''), this is what it's directory structure will look like:
@@ Line 227: / Line 222: @@
 And this will write out the packages you have installed in your ''venv'' that the host process will install for the user. The last step would be to remove (or just move out of the way) the ''Packages'' directory, and create a release for your plugin using whatever method you currently use.
 ==== Indigo Utilities ====
@@ Line 239: / Line 233: @@
 **//The indigo-clean-and-zip-plugin utility is especially useful for developers//**. You can use this utility to prepare your ''indigoPlugin'' file for distribution. The utility will inspect the plugin package and remove unnecessary files (such as ''.pyc'' files) and zip the plugin package to the same location as the plugin file. **//Using the clean and zip tool before publishing your plugin is highly recommended.//**
 ==== Linters ====
 There are several utilities available to improve your code; one type of utility is often referred to as a "Linter".  Linters inspect your code for things that you might want to address including:
@@ Line 255: / Line 250: @@
 debug_mode_bool = bool(debug_mode)
 </code>
 ==== No Module Named 'indigo' ====
@@ Line 266: / Line 260: @@
 </code>
 You will likely still get a syntax error warning on the ''import indigo'' line, but this is preferable to many, many syntax warnings throughout your code base.