Skip to content

Latest commit

 

History

History
76 lines (44 loc) · 8.11 KB

plugin-development.md

File metadata and controls

76 lines (44 loc) · 8.11 KB

Developing Plugins in an Active Installation

English | 简体中文

The reference project is OpenTest-Plugins. Host commands pnpm dev, pnpm dev:backend, pnpm build, and pnpm start run independently and do not automatically build plugin source. First import a compatible .otplugin through plugin management and fully restart, then use plugin repository development commands to update that active installation. The host does not load plugin source directories directly.

default-plugins.json lists only the public plugin fft-tools. To prepare it, explicitly run pnpm prepare:plugins. Its source comes from OpenTest-Plugins; OPENTEST_PUBLIC_PLUGINS_SOURCE selects that directory and defaults to ../OpenTest-Plugins. Relative paths resolve from the host root. Preparation requires the catalog's sources and dependencies. To bundle plugins with the host, build their final packages independently and pass --plugins-dir. --edition community bundles only catalog plugins; --edition full also accepts other compatible business plugin packages from --plugins-dir.

Explicit batch preparation validates development kit (dev-kit) digests, host compatibility, and installed dependency locks. It uses existing frontend dependencies and incremental Maven compilation without installing dependencies or rewriting SDKs or lockfiles. It installs the host's public Java API and prerequisite modules into the existing local Maven repository. Default preparation skips plugin tests; use pnpm prepare:plugins --release for complete checks. Host packaging accepts completed packages without rebuilding plugins.

Explicitly prepared .otplugin archives and index.json reside in the host's .runtime/bundled-plugins/. When bundled materials exist, plugin management's Open Bundled Plugin Directory action locates them. Manual reinstallation still requires preview, trust confirmation, and a full restart. Uninstalled plugins are not reinstalled automatically, disabled state is retained, and newer installed versions are not downgraded. Bundled installation does not overwrite active content changed by development commands.

Configuration and Startup

At the plugin repository root, copy its plugin-development.example.json to Git-ignored plugin-development.json. Set runtimeDirectory to the host's runtime root. Relative paths resolve from that configuration file's directory; environment variables do not override it.

# opentest-plugins root: build and deploy the complete plugin
pnpm dev fft-tools

# opentest root: run Maven clean package and start the JAR with mutable installed content
pnpm dev

Omitting plugin names processes all plugins. The command reads the host's plugins/state/active-plugins.json and uses plugin IDs, installed versions, and package digests to locate normal installation directories. Plugins without a normal installation fail individually while other plugins continue. Development commands do not rewrite host state or the installed package's original files.sha256.

The plugin ID, installed version, and package digest in active state identify the installation and retain their normal installed values. The actual plugin.json inside that directory is the runtime manifest and may declare a different runtime version. version in development candidates and registration reports means that runtime version; packageDigest remains the original installed package digest. These values must not be combined into another installation directory identity.

Host pnpm dev and pnpm dev:backend start the executable cry-daq.jar with an explicit mutable installed-content policy. pnpm start, installed applications, and Java startup without an explicit policy remain strict.

Applying Changes

Change Action
Java backend, plugin.json, contributions, or contracts Run the complete pnpm dev <plugin> command again; after success, manually restart the host backend and fully refresh the page
Frontend or language resources Run a complete plugin command once, or keep pnpm dev:watch <plugin> running; fully refresh the page after successful deployment
Plugin dependencies or build environment Prepare dependencies, then restart the plugin command; development commands do not install frontend dependencies

Watch mode builds and deploys only frontend/ and locales/, without backend, manifest, or contract updates. There is no frontend revision polling, plugin-level dispose/re-activate, or automatic refresh. A full page refresh recreates the module graph and reads the installed content.

Failures, Management, and Recovery

  • Deployment synchronizes files in place, without staging, backups, or automatic rollback. Failure may leave mixed old and new content. Fix the problem and rerun the complete plugin command before starting the backend or refreshing the page.
  • A backend JAR replacement failure does not prevent frontend and language deployment attempts. The overall command still fails and reports individual results.
  • Development mode keeps plugin management enabled. Installation, upgrade, enable, disable, and uninstall continue through pending operations and full-restart boundaries.
  • If an upgrade, disable, or uninstall is pending, development tools still update the active directory and warn that the next full restart may replace or remove it.
  • Strict startup rejects installed packages modified for development. There is no dedicated recovery command; uninstall and reinstall the .otplugin through normal plugin management before returning to strict operation.

Verification Entry Points

The plugin repository's pnpm test:tools checks building, deployment, and watch behavior. Host checks cover installed-content resolution, runtime lifecycle, resource controllers, normal frontend bootstrap, and development JAR startup. The host does not reference plugin business implementations or test JARs.

Host-Provided Jackson

Plugins can use the host's com.fasterxml.jackson.* classes directly, sharing the same runtime types and versions. Maven dependencies must match the target host and declare provided. Do not include Jackson classes in plugin backend JARs; both regular and multi-release JAR entries are rejected.

This contract covers Jackson modules actually shipped by the host. It does not guarantee arbitrary optional modules or expose other third-party libraries or private host implementations. See Host-Provided Jackson for the dependency boundary.

Measurement Editing

MeasurementEditor, returned by DashboardProvider.editor(), controls writes to configurations, plugin actions, and result parameters. Add business rules through editCurrent and editSaved, without new business-specific host callbacks. Read and execution projections continue through ConfigurationProjection. See Measurement Editing Contracts for migration and verification limits.

Pipeline File Output

Plugins explicitly connect raw WAV, external WAV/HDF5/PTI, and result crybin output in their own graphs. See Pipeline File Output Integration for shared nodes, frozen input, file targets, and completion boundaries.

Project Trigger References

Plugins declare references with dedicated SDK types. See Project Trigger References.

Crybin File Unit Identity

Result definitions declare Y_ONLY (default) or X_AND_Y through custom.fileUnitIdentity. Use the latter only when files must be distinguished by their X unit, such as special Hz/Bark sound-quality results. Actual X units and numeric coordinates are always retained.

Standard file and thumbnail processors use ResultFileUnitRules.fromRequirements(run.resultRequirements()); do not choose naming rules from live/recorded mode. The host binds current or saved result declarations to execution requirements and file targets; ResultFileNames accepts the same ResultFileUnitIdentity. Historical reads match only the declared file identity. See ADR 0033.