diff --git a/docs/UsingRobotPlugins.md b/docs/UsingRobotPlugins.md new file mode 100644 index 00000000..5063afce --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 9a1acea9..af54eeea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,7 @@ instructions may still be too GO-specific. InitialSetup Configs Installgit + UsingRobotPlugins DailyWorkflow CreateNewTerm Synonyms diff --git a/odk/odk.py b/odk/odk.py index c09a0418..064b4a45 100755 --- a/odk/odk.py +++ b/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""" diff --git a/template/src/ontology/Makefile.jinja2 b/template/src/ontology/Makefile.jinja2 index f779f8e7..fbaa14ef 100644 --- a/template/src/ontology/Makefile.jinja2 +++ b/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 # ----------------------------------------