Document Core API extensions

index.rst

@@ -16,6 +16,10 @@ The Spoofax documentation is a work in progress. Most pages in the table of cont
     - :doc:`source/langdev/meta/lang/sdf3`
     - :doc:`source/langdev/meta/lang/nabl`
 
+- Core API
+
+  - :doc:`source/core/manual/extension`
+
 - Development
 
   - :doc:`source/dev/maven`

source/core/manual/extension.rst

@@ -0,0 +1,70 @@
+.. highlight:: java
+
+===============
+Core Extensions
+===============
+
+Spoofax Core can be extended by providing additional Guice Modules at startup.
+Additional modules can be hardcoded when creating a Spoofax facade object, or by specifying the module as a plugin.
+Both Spoofax and meta-Spoofax can be extended with additional modules.
+
+-----------------------------
+Hardcoding additional modules
+-----------------------------
+
+To extend Spoofax with additional hardcoded modules, add them when creating a :java:ref:`Spoofax <org.metaborg.spoofax.core.Spoofax>` facade object::
+
+   final Spoofax spoofax = new Spoofax(new CustomModule(), new OtherCustomModule());
+
+Similarly, to extend meta-Spoofax, add modules to the meta-facade :java:ref:`SpoofaxMeta <org.metaborg.spoofax.meta.core.SpoofaxMeta>`::
+
+   final SpoofaxMeta spoofaxMeta = new SpoofaxMeta(spoofax, new CustomMetaModule(),
+     new OtherCustomMetaModule());
+
+--------------
+Plugin modules
+--------------
+
+Modules can be loaded as plugins through Java service providers for regular Java applications, and through Eclipse extensions for Eclipse plugins.
+
+^^^^^^^^^^^^^^^^^^^^^
+Java service provider
+^^^^^^^^^^^^^^^^^^^^^
+
+Java service providers are the standard solution for creating extensible applications on the JVM.
+Spoofax Core supports specifying additional modules as plugins through a service provider.
+To register your module as a plugin, `register it as a service provider <https://docs.oracle.com/javase/tutorial/ext/basics/spi.html#register-service-providers>`_ for the :java:ref:`IServiceModulePlugin <org.metaborg.core.plugin.IServiceModulePlugin>` class.
+For example, if you would like to register the ``org.example.CustomModule`` and ``org.example.OtherCustomModule`` module:
+
+1. Create the :file:`src/main/resources/META-INF/services/org.metaborg.core.plugin.IServiceModulePlugin` file.
+2. Add org.example.CustomModule and org.example.OtherCustomModule to that file, separated by a newline.
+
+Whenever your JAR file is on the classpath together with Spoofax Core, Spoofax Core will pick up the module plugins and load them whenever the Spoofax facade is instantiated.
+
+Similarly, for additional meta-modules, register a service provider for the :java:ref:`IServiceMetaModulePlugin <org.metaborg.meta.core.plugin.IServiceMetaModulePlugin>` class:
+
+1. Create the :file:`src/main/resources/META-INF/services/org.metaborg.meta.core.plugin.IServiceMetaModulePlugin` file.
+2. Add org.example.CustomMetaModule and org.example.OtherCustomMetaModule to that file, separated by a newline.
+
+^^^^^^^^^^^^^^^^^
+Eclipse extension
+^^^^^^^^^^^^^^^^^
+
+.. highlight:: xml
+
+Eclipse does not support Java service providers.
+To get your module plugins working in Eclipse, they need to be specified as an extension in the :file:`plugin.xml` file.
+
+Add the module classes with the ``org.metaborg.spoofax.eclipse.module`` extension point. For example::
+
+   <extension point="org.metaborg.spoofax.eclipse.module">
+     <module class="org.example.CustomModule" />
+     <module class="org.example.OtherCustomModule" />
+   </extension>
+
+For meta-modules, use the ``org.metaborg.spoofax.eclipse.meta.module`` extension point. For example::
+
+   <extension point="org.metaborg.spoofax.eclipse.meta.module">
+     <module class="org.example.CustomMetaModule" />
+     <module class="org.example.OtherCustomMetaModule" />
+   </extension>

source/core/manual/index.rst

@@ -10,3 +10,4 @@ Core API Manual
    component
    facade
    high-service
+   extension