Skip to content

3D-e-Chem/tycho-knime-node-archetype

Repository files navigation

Tycho KNIME node archetype

Java CI with Maven DOI

Generates KNIME workflow node skeleton repository with sample code.

This archetype was made because the instructions to create KNIME nodes at https://www.knime.com/developer-guide, requires interaction with Eclipse wizards. We wanted a way to start and perform node development from the command line and headless. KNIME nodes are Eclipse plugins. The Tycho Maven plugin is used to build and handle dependencies of Eclipse plugins, so we use Tycho for KNIME node building.

The Maven archetype will generate a multi-module project with the following structure:

  • / - parent Maven project
  • /plugin/ - code for KNIME node
  • /tests/ - tests of KNIME node
  • /feature/ - eclipse feature
  • /p2/ - eclipse update site

The generated project offers:

  • Usage from the command-line using maven or from Eclipse
  • Integrates with normal Eclipse plugin development flow
  • Integration with Continuous Integration builds on GitHub Actions
  • Integration with SonarCloud quality analysis via GitHub Actions
  • Test workflows for end-2-end tests
  • Test coverage
  • Start KNIME from Eclipse to test nodes without having to release them in a update site

Items above are documented in the generated README.md file, the README also includes instructions for setup for a user, setup for a developer, creating a release and citing the software.

Requirements

  • Java ==17
  • Maven >=3.0

The archetype is hosted on a GitHub packages repository. Maven does not resolve to this GitHub packages repository by default so it must be added.

The ~/.m2/settings.xml should contain the following profile:

<?xml version="1.0" encoding="UTF-8" ?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                          https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>knimearchetype</id>
      <repositories>
        <repository>
          <id>archetype</id>
          <url>https://maven.pkg.github.com/3D-e-Chem</url>
        </repository>
      </repositories>
    </profile>
  </profiles>
</settings>

Generate

The following command will generate a skeleton project

mvn archetype:generate -DarchetypeGroupId=nl.esciencecenter \
-DarchetypeArtifactId=tycho-knime-node-archetype \
-DarchetypeVersion=2.0.4 -P knimearchetype

The command will ask the following questions:

  1. Enter the groupId
  2. Enter the artifactId
  3. Enter the name of the package under which your code will be created
  4. Enter the version of your project, use x.y.z-SNAPSHOT format (for example 1.2.3-SNAPSHOT), where x.y.z is semantic versioning.
  5. Enter the GitHub organization name or GitHub username
  6. Enter the GitHub repository name
  7. Enter the KNIME node name
  8. Enter the vendor name
  9. For branded property enter Y to enable the 3D-e-Chem project branding like splash logo, node category and update site category or enter N to skip the branding.
  10. Confirm

The skeleton has been generated in a sub-directory named after the artifactId in the current working directory.

The following steps are needed to get a ready to use project.

  1. Change directory to generated code.

  2. Make skeleton git aware, by running git init.

  3. Fill in all placeholders ([Enter ... here.]) in

    • plugin/src/**/*.xml
    • feature/feature.xml
  4. Commit all changes and push to GitHub

  5. Optionally, setup Continuous Integration as described in the project README.md file.

Further instructions about generated project can be found in it's README.md file.

Generate from inside KNIME SDK

  1. Install Java 17

  2. Install Eclipse for RCP and RAP developers

  3. Configure Java 17 inside Eclipse Window > Preferences > Java > Installed JREs

  4. Register the archetype catalog which contains this archetype

    1. Goto Window > Preferences > Maven > Archetypes
    2. Add a remote catalog with https://github.com/3D-e-Chem/tycho-knime-node-archetype/raw/master/archetype-catalog.xml
  5. Create a new project based on archetype

    1. Goto File > New > Project ... > Maven
    2. Select Maven Project & press Next button
    3. Use default location & press Next button
    4. Select Catalog you added in step 4.2
    5. Select the archetype with artifact id tycho-knime-node-archetype & press Next button
    6. Fill in the form & press Finish button

Further instructions about generated project can be found in it's README.md file.

New release

  1. Adjust version in pom.xml & CHANGELOG.md & README.md & archetype-catalog.xml
  2. Commit & push
  3. Test archetype by running mvn verify
  4. Create GitHub release
  5. Deploy to GitHub packages, see Deploy chapter below

Deploy

To deploy current version to GitHub Packages.

  1. Create personal access token with write:packages scope
  2. Create ~/.m2/settings.xml
  3. Run mvn --batch-mode deploy

Attribution

The https://github.com/open-archetypes/tycho-eclipse-plugin-archetype was used as inspiration for this archetype. Also https://github.com/knime-community/community-repository-template/ and https://github.com/vernalis/vernalis-knime-nodes/ where used as inspiration to upgrade to KNIME 5.1.