Debugging Your Extension in the Production Application

Note

This page assumes you have already created Your First Extension.

Running your extension in an app

To run an extension against a release build of the software, put it in the following location depending on your operating system and which application you are running:

• Platform.Bible:
  • Windows: %USERPROFILE%/.platform.bible/installed-extensions
  • Mac: ~/.platform.bible/installed-extensions
  • Linux
    • Running in Snap (expected): ~/snap/platform-bible/common/app/installed-extensions
    • Running outside of Snap (uncommon): ~/.platform.bible/installed-extensions
• Paratext 10 Studio:
  • Windows: %USERPROFILE%/.paratext-10-studio/installed-extensions
  • Mac: ~/.paratext-10-studio/installed-extensions
  • Linux
    • Running in Snap (expected): ~/snap/paratext-10-studio/common/app/installed-extensions
    • Running outside of Snap (uncommon): ~/.paratext-10-studio/installed-extensions

Alternatively for repos made with the extension template, you can specify paths to extensions by appending arguments

RUN-APP --extensions PATH-TO-EXTENSION-1 PATH-TO-EXTENSION-2 ...   # to specific extensions
RUN-APP --extensionDirs PATH-TO-DIR-1 PATH-TO-DIR-1 ...            # to directories containing extensions

to whatever command RUN-APP you'd usually use to run Platform.Bible or Paratext Studio.

Note: when running the application in Snap on Linux, if unzipped extension folders (extension zips are ok) are provided via command line arguments, those extensions will not be able to launch separate processes due to sandbox permission restrictions.

Note: if you uninstall the Snap package in Linux, it will remove the common folder including installed extensions and extension data. Installing a new version over the old version does not remove this folder.

Debug the Backend

To debug your extension running in the Platform.Bible application:

1. From the root folder of the paranext-core repo, run npm run package:debug.
2. Change to the release folder. Run:
   • on Windows cd .\release\build\win-unpacked.
   • on Linux cd ./release/build/linux-unpacked.
   • on macOS cd ./release/build/osx-unpacked.
3. Set the debugging environment variable. Run:
   • on Windows PowerShell $env:ELECTRON_IS_DEV=1.
   • on Linux and macOS export ELECTRON_IS_DEV=1.
4. Run the application:
   • on Windows .\ParanextCore.exe --inspect-brk=5858 --remote-debugging-port=9223 --remote-allow-origins=http://localhost:9223 --extensions <path\to\my\built\extension>.
   • on Linux and macOS ./paranext --inspect-brk=5858 --remote-debugging-port=9223 --remote-allow-origins=http://localhost:9223 --extensions <path/to/my/built/extension>.
   • Note: Extension paths (using --extensions switch) can be absolute or relative to where the app is run from.
   • Note: Instead of using the --extensions switch, you can build or copy your built extension into the ./release/build/<os>-unpacked/resources/extensions/<my-extension-name>/ folder (where <os> is the same as in step 2).
5. In VS Code, add breakpoints in main.ts or below, i.e. in your extension backend code.
6. Go to Run and Debug.
7. Select Attach to Platform app, and click Start Debugging.
8. Click Continue - it should stop at your breakpoint.

Note: with these settings you have to attach the debugger (step 7) and click Continue (step 8) since the code halts at the beginning. This allows you to catch any subsequence backend breakpoints (this is necessary to debug Electron main and dependencies). If you don't wan't or need this, then replace the command-line switch --inspect-brk=5858 with --inspect=5858.

Debug the Frontend

Follow the steps above in Debug the Backend.

Although in step 7 above, you can also select Attach to Renderer to debug the frontend in VS Code, however, it is recommended to use the Chrome Developer Tools for debugging:

• Open the Developer Tools:
  • on Windows and Linux press Ctrl+Shift+I or F12.
  • on macOS press Cmd+Alt+I or F12.

Reload Extensions When They Change

When you change and rebuild your extension, Platform.Bible will automaticaly restart extensions to load your changes. If that doesn't work like you expect, you can reload extensions manually:

1. Download and install the Reload Extension Host extension
2. In Platform.Bible, click the main menu.
3. Click Reload Extension Host to reload the extension host and all installed extensions.

Alternatively, you can run the command platform.restartExtensionHost to restart the extension host.