feat(bulk-model-sync): add a configuration option to load plugins

In simple cases, `MPSBulkSynchronizer` does not rely on concepts (and in turn of languages and plugins) of the synced nodes to be loaded.
Plugins might become necessary when they provide custom persistence
and in other, yet unknown cases.

Author: Oleksandr Dzhychko

bulk-model-sync-gradle/src/main/kotlin/org/modelix/model/sync/bulk/gradle/ModelSyncGradlePlugin.kt

@@ -20,11 +20,17 @@ import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.tasks.TaskProvider
+import org.modelix.buildtools.runner.BundledPluginPath
+import org.modelix.buildtools.runner.ExternalPluginPath
 import org.modelix.buildtools.runner.MPSRunnerConfig
+import org.modelix.buildtools.runner.PluginConfig
 import org.modelix.gradle.mpsbuild.MPSBuildPlugin
+import org.modelix.model.sync.bulk.gradle.config.BundledPluginSpec
+import org.modelix.model.sync.bulk.gradle.config.ExternalPluginSpec
 import org.modelix.model.sync.bulk.gradle.config.LocalSource
 import org.modelix.model.sync.bulk.gradle.config.LocalTarget
 import org.modelix.model.sync.bulk.gradle.config.ModelSyncGradleSettings
+import org.modelix.model.sync.bulk.gradle.config.PluginSpec
 import org.modelix.model.sync.bulk.gradle.config.ServerSource
 import org.modelix.model.sync.bulk.gradle.config.ServerTarget
 import org.modelix.model.sync.bulk.gradle.config.SyncDirection
@@ -151,6 +157,7 @@ class ModelSyncGradlePlugin : Plugin<Project> {
             mpsHome = localSource.mpsHome,
             workDir = jsonDir,
             additionalModuleDirs = localSource.mpsLibraries.toList() + listOfNotNull(localSource.repositoryDir),
+            plugins = createPluginConfig(localSource.mpsPlugins),
             jvmArgs = listOfNotNull(
                 "-Dmodelix.mps.model.sync.bulk.output.path=${jsonDir.absolutePath}",
                 "-Dmodelix.mps.model.sync.bulk.output.modules=${syncDirection.includedModules.joinToString(",")}",
@@ -212,6 +219,7 @@ class ModelSyncGradlePlugin : Plugin<Project> {
             mpsHome = localTarget.mpsHome,
             workDir = jsonDir,
             additionalModuleDirs = localTarget.mpsLibraries.toList() + listOfNotNull(localTarget.repositoryDir),
+            plugins = createPluginConfig(localTarget.mpsPlugins),
             jvmArgs = listOfNotNull(
                 "-Dmodelix.mps.model.sync.bulk.input.path=${jsonDir.absolutePath}",
                 "-Dmodelix.mps.model.sync.bulk.input.modules=${syncDirection.includedModules.joinToString(",")}",
@@ -238,6 +246,16 @@ class ModelSyncGradlePlugin : Plugin<Project> {
         }
     }
 
+    private fun createPluginConfig(mpsPlugins: Set<PluginSpec>): List<PluginConfig> {
+        return mpsPlugins.map {
+            val pluginPath = when (it) {
+                is BundledPluginSpec -> BundledPluginPath(it.folder)
+                is ExternalPluginSpec -> ExternalPluginPath(it.folder)
+            }
+            PluginConfig(it.id, pluginPath)
+        }
+    }
+
     private fun getBaseDir(project: Project): File {
         return project.layout.buildDirectory.dir("model-sync").get().asFile
     }

bulk-model-sync-gradle/src/main/kotlin/org/modelix/model/sync/bulk/gradle/config/ModelSyncGradleSettings.kt

@@ -95,6 +95,25 @@ sealed interface LocalEndpoint : SyncEndpoint {
     var repositoryDir: File?
     var mpsDebugPort: Int?
 
+    /**
+     * Add a plugin to be loaded when running MPS.
+     * `jetbrains.mps.core`, `jetbrains.mps.testing`, `jetbrains.mps.ide.make` are always loaded.
+     *
+     * All other plugins, even bundled ones, must be configured explicitly.
+     * In general cases, the sync does not rely on concepts (and in turn on languages and plugins) of the synced nodes.
+     *
+     * Loading other plugins might become necessary when they provide custom persistence
+     * and in other, yet unknown cases.
+     * First, try if the sync works for your project without adding plugins.
+     *
+     * Example usage:
+     * ```
+     * mpsPlugin(BundledPluginSpec("jetbrains.mps.vcs", File("plugins/mps-vcs")))
+     * mpsPlugin(ExternalPluginSpec("com.example.mps.aPlugin", File("/full/path/to/aPlugin")))
+     * ```
+     */
+    fun mpsPlugin(plugin: PluginSpec)
+
     fun mpsLibrary(folder: File)
 
     override fun getValidationErrors(): List<String> {
@@ -112,10 +131,14 @@ data class LocalSource(
     override var mpsHeapSize: String = "2g",
     override var repositoryDir: File? = null,
     override var mpsDebugPort: Int? = null,
+    internal var mpsPlugins: Set<PluginSpec> = emptySet(),
 ) : LocalEndpoint {
     override fun mpsLibrary(folder: File) {
         mpsLibraries += folder
     }
+    override fun mpsPlugin(plugin: PluginSpec) {
+        mpsPlugins += plugin
+    }
 }
 
 data class LocalTarget(
@@ -124,12 +147,36 @@ data class LocalTarget(
     override var mpsHeapSize: String = "2g",
     override var repositoryDir: File? = null,
     override var mpsDebugPort: Int? = null,
+    internal var mpsPlugins: Set<PluginSpec> = emptySet(),
 ) : LocalEndpoint {
     override fun mpsLibrary(folder: File) {
         mpsLibraries += folder
     }
+    override fun mpsPlugin(plugin: PluginSpec) {
+        mpsPlugins += plugin
+    }
+}
+
+/**
+ * Specifies an MPS-plugin to be loaded.
+ * The [id] is the one that can be found in the `META-INF/plugin.xml` of a plugin.
+ */
+sealed interface PluginSpec {
+    val id: String
 }
 
+/**
+ * Specifies a plugin by specifying its installation [folder]
+ * that will be resolved against the installation of MPS.
+ */
+data class BundledPluginSpec(override val id: String, val folder: File) : PluginSpec
+
+/**
+ * Specifies a plugin by specifying its installation [folder]
+ * that can be absolute or will be resolved depending on the JVM process it is executed in.
+ */
+data class ExternalPluginSpec(override val id: String, val folder: File) : PluginSpec
+
 private const val DEFAULT_REQUEST_TIMEOUT_SECONDS = 5 * 60
 
 sealed interface ServerEndpoint : SyncEndpoint {

docs/global/modules/core/pages/reference/component-bulk-model-sync-gradle.adoc

@@ -112,6 +112,16 @@ mpsBuild {
 |`mpsDebugPort`
 |Int
 |If set, the headless MPS will suspend on startup and wait for a remote debugger on the specified port.
+|`mpsPlugin`
+| PluginSpec
+| Add a plugin to be loaded when running MPS.
+`jetbrains.mps.core`, `jetbrains.mps.testing`, `jetbrains.mps.ide.make` are always loaded.
+
+All other plugins, even bundled ones, must be configured explicitly.
+In general cases, the sync does not rely on concepts (and in turn on languages and plugins) of the synced nodes.
+
+Loading other plugins might become necessary when they provide custom persistence and in other, yet unknown cases.
+First, try if the sync works for your project without adding plugins.
 |===
 
 === ServerSource/-Target configuration