Skip to content
This repository has been archived by the owner on Sep 22, 2024. It is now read-only.

Dependency Management

Jump to bottom
Alexander SR edited this page Jul 4, 2024 · 11 revisions

Epoch wraps the Lingua Franca code base in a plugin (org.lflang) to provide it in the Epoch IDE. That means dependencies used in the code and usually provided via the Gradle configuration must additionally be provided in the plugin environment.

Eclipse only uses inter-plugin dependencies that means each plugin declares its dependencies to other plugins (in MANIFEST.MF) proving certain code packages. Epoch further uses a managed target platform (two manually synchronized definition in the Oomph setup for the development IDE and the target platform bundle) that specifies which dependencies should be available.

Adding a New Dependency

Given the presence of the target platform, adding dependencies can have variable complexity.

1. Adjusting the Manifest

  1. Open the MANIFEST.MF file.
  2. Click Add... and find and select the new dependency.
    In most cases plugins have the same name as their provided packages (e.g. com.google.gson for com.google.gson.JsonObject).
  3. Only if your plugin is not available, you need to adjust the target platform before you can add your dependency.

image

2. Adjusting the Target Platform

  1. Open the oomph setup file and navigate to the Targetlet definition in the Main stream.
    image
  2. Go to the DefaultRepositories element and select the URL of the P2 update site that provides the plugin you want to add to the list of available dependencies.
    The most common plugins are available at the Eclipse update side or the Orbit drops.
  3. If your update site is not yet listed you can add it. If your dependency is not available as a plugin (e.g. it is only published as library via Maven Central), you need to create a wrapper plugin to make your library available via our epoch-external-dependencies update site before you can proceed.
  4. Right-click on the update side entry and select Explore in the context menu. This will open the Repository Explorer view and list all the plugins/features that are provided.
    image
  5. When you located your plugin, you can drag and drop the entry from the Repository Explorer into the oomph setup file.
  6. After saving the oomph setup file you need to update the target platform in your development IDE via Help -> Perform Setup Tasks.
  7. Finally, you need to add the new plugin to the target definition in the target platform module). E.g.:
    <location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="false" type="InstallableUnit">
      <unit id="com.google.inject" version="0.0.0"/>
      <unit id="jakarta.activation" version="0.0.0"/>
      <unit id="javax.activation" version="0.0.0"/>
      <unit id="javaewah" version="0.0.0"/>
      <unit id="com.google.gson" version="0.0.0"/>
      <repository location="https://download.eclipse.org/tools/orbit/downloads/drops/R20230531010532/repository/"/>
    </location>
  1. Now you can proceed with adding the dependency to the plugin manifest.

3. Creating a Wrapper Plugin for Non-Plugin Dependencies

  1. Clone the epoch-external-dependencies repository.
  2. If you do not want to add a new dependency but update the version of an existing dependency, jump to step 6.
  3. Copy an existing dependency folder (e.g. org.lflang.epoch.mirror.kotlin)
  4. Replace the license file (e.g. kotlin.license.txt) with the one of the new dependency.
  5. Delete all jars in lib folder.
  6. Update the pom.xml
  • Set the correct artifactId in the pom.xml.
  • Set the dependencies in the pom.xml to the dependency according to maven central.
  • Set version based on maven central version.
  • Set includeGroupIds based on the group id from maven central.
  1. Update the reposiroty top-level pom.xml
  • Add the artifactId for the new dependency as a module to the already existing ones.
  1. Update META-INF/MANIFEST.MF
  • Adjust Bundle-Name, Symbolic-Name, Bundle-Version, and Automatic-Module-Name.
  • Delete Bundle-Classpath and Export-Package.
  1. Run maven packagein root.
  • This will fail but enables further steps.
  • The maven command will download the maven jar into the lib folder.
  1. In build.properties
  • Add the jar from the lib folder to the bin/includes.
  1. Import the repository into your developer Eclipse.
  2. Open and update the MANIFEST.MF in Eclipse. manifest-packages
  • Go to Runtime tab
  • Click on Add in Classpath
  • Add dependency jars from lib folder.
  • Click on Add in Exported Packages.
  • Select all packages and add them.
  1. Open and update category.xml in org.lflang.epoch.external.dependencies.reporitory
  • Add a new bundle for the dependencies artifactId.
  1. Run maven package again.
  • This should not fail.
  1. Adjust top-level README
  2. Create a PR and push and commit changes.
  1. Now you can continue with Case 2 above and find your new dependency by exploring https://lf-lang.github.io/epoch-external-dependencies.

Common Pitfalls

Adding Dependencies to POM File

Adding dependencies to the pom file (e.g. like this one) will have no effect on the compilation of the LF code. These dependencies are only used in the code generation stage for the Xtext grammar. During compilation of the LF code in the plugin, only dependencies listed in the manifest file will be available.

Clone this wiki locally