Modulepaths and framework eol scripts in ant and eclipse

[jgsuess]

I have a system of generators running from ant, which use common eol scripts. However, the resolution of those scripts is relative to the running script. This means that cascading inputs are not easily possible. The answer seems to be to have multiple module paths for the task, one pointing at the location the script is (current ant directory), the other pointing at the framework root. However, there is no module path element on the ant tasks.

There are ways to do this in Java, and additional ant tasks could probably cover this. But I would rather not use such a helper.

So here is the question:

What is the current best practice to I configure multiple module paths within ant?

[kolovos]

Would using Ant properties to define base paths and setting them via command-line arguments work for your use case? If not, could you please share a minimal example so I can better understand the problem?

[jgsuess]

Hi Dimitri, please see attached

module_path_issue.zip

[kolovos]

Thank you very much for the detailed explanation. If we decide to support loading imported Epsilon files from configurable base locations (other than the base path of the importing program), the solution would need to work beyond Ant - including Epsilon's editors and debuggers - and it should also support EGX's loading of EGL templates.

An alternative approach I'm considering is to introduce support for an EPSILON_PATH environment variable (similar to the operating system's PATH variable). This would be a concatenation of directory paths where Epsilon would also look for imported and referenced files.

What do you think about this approach?

[jgsuess]

I am worried about background state. With an environment variable this may magically work, but generally I would not want to set environment variables outside a build or system to do this.

I recall that the ecore generator had similar issues (see my AI dig below to remind myself). It used EcorePlugin.computePlatformURIMap() . It seems that MWE2 hit the same issue. I am not sure if EMF is always a dependency of Epsilon, but if it is, the same mechanism could be reused. The resolver maps prefixes to local resources, so you could add framework to be <full path from root>/framework. and set the map in an ant task or utility. This would decouple the resolution mechanism.

There is even pre-prepared support for this in the
handlePlatformResourceOptions method.

Maybe this method could be wrapped for the various environments?

• ant

<platformUriMap>
<entry source="foo" target="file:///somewhere/on/disk/foo"/>
<entry source="bar" target="http://dimitris.code/bar"/>
</platformUriMap>

(The http expansion be used with care, as this is a security issue.)

• in eclipse:
  an option in the run dialog

That may cover it?

A very good description of resolution is here starting slide 14

After this, the resolution would occur as usual.

Example:

map contains

framework -> file:///home/jg/git/fhir-implementation-patterns-book/etc/base_path_module_issue/framework

Request is

import "platform:/plugin/framework/formatting.eol"

this is run through the map and turns into
/home/jg/git/fhir-implementation-patterns-book/etc/base_path_module_issue/framework/formatting.eol

If epsilon is in debug mode, it may log the expansion for clarity.

This is then handled by the URIStreamHandlers that are active. Not sure how epsilon does that. Note that there is also support for stream handlers in the EcorePlugin. If that is used, the alignment would be even greater.

If epsilon is in debug mode and has knowledge which resolution was chosen, it may log the expansion for clarity.

After that, the resource is loaded

how does the emf ecore generator handle resource resolution using the platform:/plugin convention when run outside eclipse?

Short answer: it doesn’t—at least not automatically. When you run EMF code generation (or any EMF-based loader) outside the Eclipse workbench, URIs with the platform:/plugin/... scheme are not resolvable by default. The EMF runtime only knows how to resolve platform:/plugin transparently when the Eclipse platform is up and the bundle registry is available. Standalone/headless code needs an explicit URI mapping (or an alternative loader) to find those resources. [help.eclipse.org], [download.eclipse.org]

Below is how this works under the hood and the common ways to fix it.

---

What happens inside EMF

• EMF uses ResourceSet + URIConverter to resolve and open resources from URIs. Resolution of special schemes (like platform:/resource and platform:/plugin) depends on helpers provided by Eclipse or custom mappings you add to the URIConverter. In a plain JVM (no Eclipse), there is no bundle registry, so platform:/plugin/... cannot be dereferenced. [download.eclipse.org], [download.eclipse.org]

• In an Eclipse runtime, EMF’s EcorePlugin computes maps between platform:/plugin and platform:/resource (workspace) URIs so references can be resolved seamlessly. Those helpers are tied to the workbench; outside Eclipse, you must supply equivalent mappings yourself. [download.eclipse.org]

---

The generator context (Ecore/GenModel)

EMF’s code generator and many workflows read .genmodel and .ecore files that often reference other models via platform:/plugin/.... If you invoke the generator in a headless build (Ant/Maven/Gradle, unit tests, CLI), you need to preconfigure URI mappings so those platform:/plugin imports point to actual files or classpath resources. Otherwise you’ll see unresolved proxies or load failures. [eclipse.dev]

---

Standard solutions outside Eclipse

1) Add explicit URI mappings on the ResourceSet (plain EMF)

Create a URIMap that remaps platform:/plugin/... to either file:/... (your build checkout) or jar:/... (if the dependency is in your classpath). Example:

ResourceSet rs = new ResourceSetImpl();
URIConverter uriConverter = rs.getURIConverter();
Map<URI, URI> uriMap = uriConverter.getURIMap();

// Map the plugin root to a folder in your build
URI pluginRoot = URI.createURI("platform:/plugin/org.example.metamodel/");
URI fileRoot   = URI.createFileURI("/path/to/org.example.metamodel/");
uriMap.put(pluginRoot, fileRoot);

// Now load a model that imports via platform:/plugin
URI modelUri = URI.createURI("platform:/plugin/org.example.metamodel/model/My.ecore");
Resource r = rs.getResource(modelUri, true);

This uses EMF’s URIConverterImpl.URIMap support; you can add as many mappings as needed for all referenced plugins. [ibm.com]

Tip: if you only struggle with saving and want to keep platform:/plugin URIs absolute in output XMI, you can set XMLResource.OPTION_URI_HANDLER to URIHandlerImpl.PlatformSchemeAware. That prevents unwanted “relative path” rewrites but does not resolve resources; it only affects serialization. [github.com]

2) Use MWE2’s StandaloneSetup (Xtext/Acceleo/EMF workflows)

If your generator runs via MWE2, StandaloneSetup has first-class support to map platform URIs:

component = org.eclipse.emf.mwe.utils.StandaloneSetup {
    // path to the “platform” root (your workspace checkout)
    platformUri = ".."

    // Map platform:/plugin → platform:/resource or file:
    uriMap = {
        from = "platform:/plugin/org.eclipse.emf.ecore/model/Ecore.ecore"
        to   = "platform:/resource/myproject/model/Ecore.ecore"
    }
}

The documentation explicitly states that platform:/plugin cannot be resolved in standalone mode and must be mapped to file: or platform:/resource URIs. This is the most common fix in headless generators based on MWE2/Xtext. [download.eclipse.org]

3) Leverage EcorePlugin maps—only when Eclipse is running

In a workbench or RCP environment (i.e., EMFPlugin.IS_ECLIPSE_RUNNING), EcorePlugin.computePlatformURIMap() and related helpers build bidirectional maps between plugin and resource locations. In standalone, these helpers won’t have the necessary platform context. Don’t rely on them unless you actually bootstrap Eclipse. [download.eclipse.org]

---

Practical checklist for headless EMF generation

1. Identify all platform:/plugin/... imports in your .ecore/.genmodel. If needed, normalize them to a few plugin roots. (EMF tutorials and docs show how models reference others via URIs.) [vogella.com], [eclipse.dev]
2. Create URI mappings on your ResourceSet (plain Java) or via StandaloneSetup (MWE2) for each plugin root to a stable file location in your build or workspace checkout. [download.eclipse.org], [ibm.com]
3. If you serialize models and want to preserve platform:/plugin URIs, set XMLResource.OPTION_URI_HANDLER to PlatformSchemeAware. (This is orthogonal to resolution.) [github.com]
4. For generators that run inside Eclipse (RCP/IDE), you can rely on EcorePlugin’s computed maps; for pure headless, don’t. [download.eclipse.org]

---

Why EMF behaves this way

platform:/plugin is an Eclipse-specific scheme that abstracts away whether a bundle is a directory or a JAR and where it’s installed. Without the OSGi runtime and the Eclipse platform, there’s no registry to resolve “which bundle and which entry.” That’s why EMF’s standalone story is: map those URIs to concrete locations yourself. [help.eclipse.org]

---

Related references

• EMF Javadoc (ResourceSet, ResourceSetImpl, URI conversion and demand load). [download.eclipse.org], [download.eclipse.org]
• EcorePlugin Javadoc—platform URI maps and Eclipse-only helpers. [download.eclipse.org]
• MWE2 StandaloneSetup—explicit guidance to map platform:/plugin in standalone workflows. [download.eclipse.org], [github.com]
• Eclipse help on the platform URI schemes (what platform:/plugin means). [help.eclipse.org]
• Practical note on keeping platform:/plugin absolute on save (PlatformSchemeAware handler). [github.com]

---

If you want, share a snippet of the .genmodel or the specific plugin URIs you need to resolve in your headless run. I can draft a minimal ResourceSet initializer or an MWE2 StandaloneSetup module tailored to your project layout.

[agarciadom]

The Epsilon core is independent from EMF, so we cannot directly reuse EMF mechanisms to resolve imports.

Epsilon can parse a module referenced via a URI. The URI gets turned into a URL, which gets a URLStreamHandler via the registered factories, as documented in the Java standard library Javadocs:

https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-java.lang.String-int-java.lang.String-

The Eclipse IDE sets up its own URLStreamHandlerFactory which handles platform:/ transparently for Epsilon (I don't recall us having any specific code for this). In a plain Java environment, it is possible to use Java services to add more factories that can handle other protocols, but in the Eclipse IDE this approach has to be changed to OSGi service registration (we're using this mechanism in a static analysis prototype, to intercept imports).

In any case, I think one solution would be to allow the ImportManager to use more than just the baseURI to try and resolve imports (which is the current behaviour - to resolve relative paths as relative to the current module). It could prioritise the modulePath first (which would be empty by default), and if that doesn't work, fall back to its current behaviour.

For your attached example, you could then have these elements in the modulePath:

• framework
• generators
• shared

Then you could just do import "utils.eol";, import "epub/epub-helpers.eol";, and so on.

We could extend all Epsilon program tasks (ExecutableModuleTasks) to take nested elements which can add elements to such a modulePath in the ImportManager object we use.

How does this sound?

[agarciadom]

I had a chat with Dimitris about the above approach, and it wouldn't be enough by itself, as we'd have to make tooling (IDE plugins / language servers) aware of this import path as well, or you'd start seeing error/warning markers in editors and you'd also have issues during debugging. Properly supporting such an import path idea would take quite a bit more time than what I first expected, and it'd impose more overheads on any tooling we develop in the future.

After some brainstorming, we came up with an alternative that should both solve your issue and integrate cleanly with existing tooling: supporting a new URI style for imports that is more flexible about how it finds the file to be imported. The format would be something like:

up://BASE_FOLDER/PATH_SUFFIX

The semantics of the URI would be:

1. Visit parent folders until reaching BASE_FOLDER (if we never reach BASE_FOLDER, fail with an error message).
2. Obtain a list of all the files in this folder and its subfolders (this could be cached for repeated uses of up://).
3. Filter the list to those files whose path ends in /PATH_SUFFIX.
4. If there is more than one candidate, fail with an error message (ambiguous import).
5. If there are no candidates, fail with an error message (unresolved import).
6. If there is exactly one candidate, access the file.

In your example project, you could then import framework/utils.eol with:

up://base_path_module_issue/utils.eol

If there was more than one utils.eol file in the project, you'd disambiguate with:

up://base_path_module_issue/framework/utils.eol

Would you like us to try and create a first version of the idea, so you can try it out and report back? Our plan would be to create a new URLStreamHandlerFactory to support this up protocol. We would register it via the Java service and OSGi service registration approaches that we mentioned above, so it should be transparent to existing code.

[jgsuess]

That sounds really good and very similar to some of the resolution styles I know from terragrunt.

Please note that such a URLStreamHandler would need really good documentation and logging for security reasons.

Do you also have to add URLStreamHandlerService ?

Maybe you can reuse my example for documentation?

[agarciadom]

One thing that struck me this morning is that the URLStreamHandler openConnection API does not allow us to specify a context to resolve the up:// URL from, so this approach might not quite work.

We may have to support up:// URLs from inside Epsilon itself (perhaps from the ImportManager) - this way in theory tooling should still work, so long as it's reusing the Epsilon libraries. I'll give it a bit more thought, but the idea would be that the ImportManager sees it's a up:// URL, and invokes a bit of machinery to resolve it to the file:// URL than is then processed as usual.

I note the need for documentation and logging :-).

As for the example - I think we can make it even more minimalistic (just to make it easier to understand for new users). Do you have an Eclipse Contributor Agreement in place, by the way?

[jgsuess]

Yes, I have an ECA. I also have an idea. I am thinking about a cascading connection handler that uses the EMF map mechanism. So, it will do the map expansion like this:

ex://some/prefix --> file://some/given/path
file://some/given/path --> http://it/is/somewhere/eles

with an occurs check if an expansion is used twice, so it cannot crash and a log that shows expansion if needed.
Configuration can be done through a Java config facility that has update. I have forgotten the name of that facility. I can prepare a PR.

[agarciadom]

Are you thinking about a Java service, basically? The main concern is to make sure that keeps working from an OSGi environment as well (e.g. by registering it as an OSGi service).

I've got a PR for the up:// URIs which works with file: / jar: (supporting recursion), and any other absolute and non-opaque URI without recursion. #212