Merge pull request #968 from gouttegd/odk-provided-plugins

Deliver ROBOT plugins in ODK

docs/UsingRobotPlugins.md

@@ -0,0 +1,54 @@
+# Using ROBOT Plugins
+
+Since version 1.9.5, the ROBOT tool allows to use [plugins](http://robot.obolibrary.org/plugins) that provide supplementary commands that are not part of the default command set.
+
+## Declaring the plugins to be used
+
+Before you can use plugins in a custom workflow, the ODK must be aware of those plugins. There are several ways to do that.
+
+### Listing the plugins in the ODK configuration
+
+Add a new `robot_plugins` section to your ODK configuration file (`src/ontology/ONT-odk.yaml`). That section should contain a single `plugins` key, which itself should contain the list of the plugins you want to use. Each entry in the list must contain at least a `name` key, which is the name under which the plugin will be available, and optionally a `mirror_from` key, pointing to an online location from which the plugin can be downloaded.
+
+For example, to use the [KGCL](https://github.com/gouttegd/kgcl-java/) plugin:
+
+```yaml
+robot_plugins:
+  plugins:
+    - name: kgcl
+      mirror_from: https://github.com/gouttegd/kgcl-java/releases/download/kgcl-0.2.0/kgcl-robot-plugin-0.2.0.jar
+```
+
+If you do not specify a download location with the `mirror_from` key, a dummy rule `${ROBOT_PLUGINS_DIRECTORY}/kgcl.jar` will be generated in the standard Makefile. You will need to override that rule in your ontology-specific Makefile:
+
+```Make
+${ROBOT_PLUGINS_DIRECTORY}/kgcl.jar:
+    curl -L -o $@ https://github.com/gouttegd/kgcl-java/releases/download/kgcl-0.2.0/kgcl-robot-plugin-0.2.0.jar
+```
+
+
+### Using custom rules
+
+If for whatever reason you do not want to modify your ODK configuration, you can still set up a plugin by adding a rule such as the one above in the custom Makefile, and listing the plugin in the `custom_robot_plugins` variable. For example, again with the KGCL lplugin:
+
+```Make
+${ROBOT_PLUGINS_DIRECTORY}/kgcl.jar:
+    curl -L -o $@ https://github.com/gouttegd/kgcl-java/releases/download/kgcl-0.2.0/kgcl-robot-plugin-0.2.0.jar
+
+custom_robot_plugins: $(ROBOT_PLUGINS_DIRECTORY)/kgcl.jar
+```
+
+
+### Putting the plugin file in the top-level `plugins` directory
+
+Any Jar file found in the repository’s top-level `plugins` directory (if such a directory exists) will automatically be found by the ODK, without requiring any change to the ODK configuration or the custom Makefile.
+
+
+### ODK-provided plugins
+
+Some plugins are already bundled with the ODK and don’t need to be declared or downloaded from somewhere else. For now, there is only one such plugin: the [SSSOM plugin](https://github.com/gouttegd/sssom-java/). More default plugins may be added in future ODK versions.
+
+
+## Using a plugin a custom workflow
+
+Any Make rule that involves the use of a ROBOT plugin MUST depend on the `all_robot_plugins` target. This will ensure that all plugins have been properly set up in the runtime ROBOT plugins directory.

docs/index.rst

@@ -20,6 +20,7 @@ instructions may still be too GO-specific.
    InitialSetup
    Configs
    Installgit
+   UsingRobotPlugins
    DailyWorkflow
    CreateNewTerm
    Synonyms

odk/odk.py

@@ -453,6 +453,31 @@ class ExportGroup(ProductGroup):
     directory : Directory = "reports/"
     """directory where exports are placed"""
 
+
+@dataclass_json
+@dataclass
+class RobotPlugin(JsonSchemaMixin):
+    """
+    A configuration for a single ROBOT plugin
+    """
+
+    name : str = ""
+    """Basename for the plugin"""
+
+    mirror_from : Optional[str] = None
+    """Automatically download the plugin from this URL"""
+
+
+@dataclass_json
+@dataclass
+class PluginsGroup(JsonSchemaMixin):
+    """
+    A configuration section to list extra ROBOT plugins not provided by the ODK
+    """
+
+    plugins : Optional[List[RobotPlugin]] = None
+    """The list of plugins to use"""
+
 
 @dataclass_json
 @dataclass
@@ -634,6 +659,9 @@ class OntologyProject(JsonSchemaMixin):
     extra_rdfxml_checks : bool = False
     """When enabled, RDF/XML product files are checked against additional parsers"""
 
+    robot_plugins : Optional[PluginsGroup] = None
+    """Block that includes information on the extra ROBOT plugins used by this project"""
+
     # product groups
     import_group : Optional[ImportGroup] = None
     """Block that includes information on all ontology imports to be generated"""

template/src/ontology/Makefile.jinja2

@@ -141,6 +141,47 @@ config_check:
 $(TMPDIR) $(REPORTDIR) $(MIRRORDIR) $(IMPORTDIR) $(COMPONENTSDIR) $(SUBSETDIR):
 	mkdir -p $@
 
+# ----------------------------------------
+# ODK-managed ROBOT plugins
+# ----------------------------------------
+
+# Make sure ROBOT knows where to find plugins
+export ROBOT_PLUGINS_DIRECTORY=$(TMPDIR)/plugins
+
+# Override this rule in {{ project.id }}.Makefile to install custom plugins
+.PHONY: custom_robot_plugins
+custom_robot_plugins:
+
+{% if project.robot_plugins is defined %}
+.PHONY: extra_robot_plugins
+extra_robot_plugins: {% for plugin in project.robot_plugins.plugins %} $(ROBOT_PLUGINS_DIRECTORY)/{{ plugin.name }}.jar {% endfor %}
+{% endif %}
+
+# Install all ROBOT plugins to the runtime plugins directory
+.PHONY: all_robot_plugins
+all_robot_plugins: $(foreach plugin,$(notdir $(wildcard /tools/robot-plugins/*.jar)),$(ROBOT_PLUGINS_DIRECTORY)/$(plugin)) \
+		   $(foreach plugin,$(notdir $(wildcard ../../plugins/*.jar)),$(ROBOT_PLUGINS_DIRECTORY)/$(plugin)) \
+		   custom_robot_plugins {% if project.robot_plugins is defined %}extra_robot_plugins {% endif %} \
+
+# Default rule to install plugins
+$(ROBOT_PLUGINS_DIRECTORY)/%.jar:
+	@mkdir -p $(ROBOT_PLUGINS_DIRECTORY)
+	@if [ -f ../../plugins/$*.jar ]; then        \
+		ln ../../plugins/$*.jar $@ ;         \
+	elif [ -f /tools/robot-plugins/$*.jar ]; then \
+		cp /tools/robot-plugins/$*.jar $@ ;  \
+	fi
+
+# Specific rules for supplementary plugins defined in configuration
+{% if project.robot_plugins is defined %}{% for plugin in project.robot_plugins.plugins %}
+$(ROBOT_PLUGINS_DIRECTORY)/{{ plugin.name }}.jar:
+{%- if plugin.mirror_from %}
+	curl -L -o $@ {{ plugin.mirror_from }}
+{%- else %}
+	echo "ERROR: No URL has been provided for this plugin; you must install it yourself by overwriting this rule in {{ project.id }}.Makefile!" && false
+{% endif %}
+{% endfor %}{% endif %}
+
 # ----------------------------------------
 # Release assets
 # ----------------------------------------