R6 Generator Maven Archetype: Recommended project setup

The project configuration needed for a Java project with generated R package can be automated to allow easy best practice using a maven archetype.

STEP 1: Set up temporary location:

For the purposes of this vignette we are using a temporary directory and the most up to date version of the generator library available which we are setting as the $TMP_VERSION environment variable.

## /tmp/Rtmp7mxF6F/testProject

## [1] "1.1.0"

Maven archetype

The maven archetype is triggered from the command line and will interactively ask for the details if not provided inline as in this example:

cd $TMP_DIR
rm -r examplePackage ||: 
mvn archetype:generate -B \
  -DarchetypeGroupId=io.github.terminological \
  -DarchetypeArtifactId=r6-generator-maven-archetype \
  -DarchetypeVersion=$TMP_VERSION \
  -DgithubOrganisation=exampleOrganisation \
  -DgithubRepository=examplePackage

## rm: cannot remove 'examplePackage': No such file or directory
## [INFO] Scanning for projects...
## [INFO] 
## [INFO] ------------------< org.apache.maven:standalone-pom >-------------------
## [INFO] Building Maven Stub Project (No POM) 1
## [INFO] --------------------------------[ pom ]---------------------------------
## [INFO] 
## [INFO] >>> maven-archetype-plugin:3.2.1:generate (default-cli) > generate-sources @ standalone-pom >>>
## [INFO] 
## [INFO] <<< maven-archetype-plugin:3.2.1:generate (default-cli) < generate-sources @ standalone-pom <<<
## [INFO] 
## [INFO] 
## [INFO] --- maven-archetype-plugin:3.2.1:generate (default-cli) @ standalone-pom ---
## [INFO] Generating project in Batch mode
## [INFO] Archetype repository not defined. Using the one from [io.github.terminological:r6-generator-maven-archetype:1.0.0] found in catalog remote
## [INFO] ----------------------------------------------------------------------------
## [INFO] Using following parameters for creating project from Archetype: r6-generator-maven-archetype:1.1.0
## [INFO] ----------------------------------------------------------------------------
## [INFO] Parameter: groupId, Value: io.github.exampleOrganisation
## [INFO] Parameter: artifactId, Value: examplePackage
## [INFO] Parameter: version, Value: main-SNAPSHOT
## [INFO] Parameter: package, Value: io.github.exampleOrganisation
## [INFO] Parameter: packageInPathFormat, Value: io/github/exampleOrganisation
## [INFO] Parameter: githubOrganisation, Value: exampleOrganisation
## [INFO] Parameter: rPackageLicense, Value: MIT
## [INFO] Parameter: package, Value: io.github.exampleOrganisation
## [INFO] Parameter: libraryStyle, Value: fat-jar
## [INFO] Parameter: gitignore, Value: .gitignore
## [INFO] Parameter: groupId, Value: io.github.exampleOrganisation
## [INFO] Parameter: maintainerEmail, Value: a.n.example@example.org
## [INFO] Parameter: version, Value: main-SNAPSHOT
## [INFO] Parameter: rPackageVersion, Value: 0.0.0.9000
## [INFO] Parameter: rPackageName, Value: examplePackage
## [INFO] Parameter: archetypeVersion, Value: 1.1.0
## [INFO] Parameter: githubRepository, Value: examplePackage
## [INFO] Parameter: maintainerOrganisation, Value: exampleOrganisation
## [INFO] Parameter: maintainerSurname, Value: Example
## [INFO] Parameter: artifactId, Value: examplePackage
## [INFO] Parameter: maintainerName, Value: Anne
## [WARNING] Don't override file /tmp/Rtmp7mxF6F/testProject/examplePackage/java/src/main/java/io/github/exampleOrganisation
## [WARNING] Don't override file /tmp/Rtmp7mxF6F/testProject/examplePackage/java/src/test/java/io/github/exampleOrganisation
## [WARNING] Don't override file /tmp/Rtmp7mxF6F/testProject/examplePackage/data-raw
## [WARNING] Don't override file /tmp/Rtmp7mxF6F/testProject/examplePackage/vignettes
## [INFO] Project created from Archetype in dir: /tmp/Rtmp7mxF6F/testProject/examplePackage
## [INFO] ------------------------------------------------------------------------
## [INFO] BUILD SUCCESS
## [INFO] ------------------------------------------------------------------------
## [INFO] Total time:  1.168 s
## [INFO] Finished at: 2024-05-16T16:27:22+01:00
## [INFO] ------------------------------------------------------------------------

with this configuration it creates a skeleton example project consisting mostly of Java and maven files set up as follows.

## /tmp/Rtmp7mxF6F/testProject
## └── examplePackage
##     ├── README.md
##     ├── data-raw
##     │   └── setup-test-data.R
##     ├── examplePackage.Rproj
##     ├── java
##     │   ├── pom.xml
##     │   └── src
##     │       ├── main
##     │       │   └── java
##     │       │       └── io
##     │       │           └── github
##     │       │               └── exampleOrganisation
##     │       │                   ├── BasicExample.java
##     │       │                   ├── MoreComplexExample.java
##     │       │                   └── TestDataGenerator.java
##     │       └── test
##     │           ├── java
##     │           │   └── io
##     │           │       └── github
##     │           │           └── exampleOrganisation
##     │           │               └── TestData.java
##     │           └── resources
##     ├── pom.xml
##     └── vignettes
##         └── examplePackage.Rmd

Building the project

The project should be fully ready to be built as a R package, with the minimal example class provided.

cd $TMP_DIR/examplePackage/java
mvn install

## [INFO] Scanning for projects...
## [INFO] 
## [INFO] ------------< io.github.exampleOrganisation:examplePackage >------------
## [INFO] Building examplePackage main-SNAPSHOT
## [INFO] --------------------------------[ jar ]---------------------------------
## [INFO] 
## [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ examplePackage ---
## [INFO] Using 'UTF-8' encoding to copy filtered resources.
## [INFO] skip non existing resourceDirectory /tmp/Rtmp7mxF6F/testProject/examplePackage/java/src/main/resources
## [INFO] 
## [INFO] --- r6-generator-maven-plugin:1.1.0:flatten-pom (flatten-pom) @ examplePackage ---
## [INFO] Executing R6 generator
## [INFO] Generating flattened POM of project io.github.exampleOrganisation:examplePackage:jar:main-SNAPSHOT...
## [INFO] 
## [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ examplePackage ---
## [INFO] Changes detected - recompiling the module!
## [INFO] Compiling 3 source files to /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/classes
## [INFO] 
## [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ examplePackage ---
## [INFO] Using 'UTF-8' encoding to copy filtered resources.
## [INFO] Copying 0 resource
## [INFO] 
## [INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ examplePackage ---
## [INFO] Changes detected - recompiling the module!
## [INFO] Compiling 1 source file to /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/test-classes
## [INFO] 
## [INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ examplePackage ---
## [INFO] Surefire report directory: /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/surefire-reports
## 
## -------------------------------------------------------
##  T E S T S
## -------------------------------------------------------
## Running io.github.exampleOrganisation.TestData
## Tests run: 0, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
## 
## Results :
## 
## Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
## 
## [INFO] 
## [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ examplePackage ---
## [INFO] Building jar: /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/examplePackage-main-SNAPSHOT.jar
## [INFO] 
## [INFO] --- maven-install-plugin:2.4:install (default-install) @ examplePackage ---
## [INFO] Installing /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/examplePackage-main-SNAPSHOT.jar to /home/vp22681/.m2/repository/io/github/exampleOrganisation/examplePackage/main-SNAPSHOT/examplePackage-main-SNAPSHOT.jar
## [INFO] Installing /tmp/Rtmp7mxF6F/testProject/examplePackage/java/.flattened-pom.xml to /home/vp22681/.m2/repository/io/github/exampleOrganisation/examplePackage/main-SNAPSHOT/examplePackage-main-SNAPSHOT.pom
## [INFO] 
## [INFO] --- r6-generator-maven-plugin:1.1.0:generate-r-library (generate-r-library) @ examplePackage ---
## [INFO] Executing R6 generator
## [INFO] Building jar: /tmp/Rtmp7mxF6F/testProject/examplePackage/java/target/examplePackage-main-SNAPSHOT-jar-with-dependencies.jar
## [INFO] Copying fat jar into inst/java.
## [INFO] Reflections took 39 ms to scan 2 urls, producing 42 keys and 144 values
## [INFO] io.github.exampleOrganisation.BasicExample
## [INFO] io.github.exampleOrganisation.MoreComplexExample
## [INFO] io.github.exampleOrganisation.TestDataGenerator
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/DESCRIPTION
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/NAMESPACE
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/inst/CITATION
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/tests/testthat.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/LICENSE
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/LICENSE.md
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/JavaApi.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/examplePackage-package.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/JavaApi.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/StaticApi.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/zzz.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/cran-comments.md
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/.Rbuildignore
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/.github/workflows/R-CMD-check.yaml
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/BasicExample.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/BasicExample.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/tests/testthat/test-BasicExample.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/greet.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/MoreComplexExample.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/MoreComplexExample.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/tests/testthat/test-MoreComplexExample.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/salutation.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/TestDataGenerator.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/R/TestDataGenerator.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/tests/testthat/test-TestDataGenerator.R
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/serialise_dataframe.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/serialise_list.Rd
## [INFO] Writing file: /tmp/Rtmp7mxF6F/testProject/examplePackage/man/serialise_named_list.Rd
## [INFO] Installing R package
## [INFO] 
## [INFO] R version 4.4.0 (2024-04-24) -- "Puppy Cup"
## [INFO] Copyright (C) 2024 The R Foundation for Statistical Computing
## [INFO] Platform: x86_64-pc-linux-gnu
## [INFO] 
## [INFO] R is free software and comes with ABSOLUTELY NO WARRANTY.
## [INFO] You are welcome to redistribute it under certain conditions.
## [INFO] Type 'license()' or 'licence()' for distribution details.
## [INFO] 
## [INFO]   Natural language support but running in an English locale
## [INFO] 
## [INFO] R is a collaborative project with many contributors.
## [INFO] Type 'contributors()' for more information and
## [INFO] 'citation()' on how to cite R or R packages in publications.
## [INFO] 
## [INFO] Type 'demo()' for some demos, 'help()' for on-line help, or
## [INFO] 'help.start()' for an HTML browser interface to help.
## [INFO] Type 'q()' to quit R.
## [INFO] 
## [INFO] > pak::local_install(root = '/tmp/Rtmp7mxF6F/testProject/examplePackage',upgrade=FALSE, ask=FALSE)
## [INFO] ℹ Loading metadata database
## [INFO] ✔ Loading metadata database ... done
## [INFO] 
## [INFO]  
## [INFO] → Will update 1 package.
## [INFO] → The package (0 B) is cached.
## [INFO] + examplePackage 0.0.0.9000 → 0.0.0.9000 [bld]
## [INFO] ✔ All system requirements are already installed.
## [INFO]   
## [INFO] ℹ No downloads are needed, 1 pkg is cached
## [INFO] ✔ Got examplePackage 0.0.0.9000 (source) (4.10 kB)
## [INFO] ℹ Packaging examplePackage 0.0.0.9000
## [INFO] ✔ Packaged examplePackage 0.0.0.9000 (697ms)
## [INFO] ℹ Building examplePackage 0.0.0.9000
## [INFO] ✔ Built examplePackage 0.0.0.9000 (2.4s)
## [INFO] ✔ Installed examplePackage 0.0.0.9000 (local) (25ms)
## [INFO] ✔ 1 pkg + 13 deps: kept 13, upd 1, dld 1 (NA B) [6.8s]
## [INFO] > 
## [INFO] > 
## [INFO] Generating pkgdown site - please be patient
## [INFO] 
## [INFO] R version 4.4.0 (2024-04-24) -- "Puppy Cup"
## [INFO] Copyright (C) 2024 The R Foundation for Statistical Computing
## [INFO] Platform: x86_64-pc-linux-gnu
## [INFO] 
## [INFO] R is free software and comes with ABSOLUTELY NO WARRANTY.
## [INFO] You are welcome to redistribute it under certain conditions.
## [INFO] Type 'license()' or 'licence()' for distribution details.
## [INFO] 
## [INFO]   Natural language support but running in an English locale
## [INFO] 
## [INFO] R is a collaborative project with many contributors.
## [INFO] Type 'contributors()' for more information and
## [INFO] 'citation()' on how to cite R or R packages in publications.
## [INFO] 
## [INFO] Type 'demo()' for some demos, 'help()' for on-line help, or
## [INFO] 'help.start()' for an HTML browser interface to help.
## [INFO] Type 'q()' to quit R.
## [INFO] 
## [INFO] > pkgdown::build_site(pkg = '/tmp/Rtmp7mxF6F/testProject/examplePackage')
## [INFO] ── Installing package examplePackage into temporary library ────────────────────
## [INFO] ── Building pkgdown site for package examplePackage ────────────────────────────
## [INFO] Reading from: /tmp/Rtmp7mxF6F/testProject/examplePackage
## [INFO] Writing to: /tmp/Rtmp7mxF6F/testProject/examplePackage/docs
## [INFO] ── Initialising site ───────────────────────────────────────────────────────────
## [INFO] Copying
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/bootstrap-toc.css,
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/bootstrap-toc.js,
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/docsearch.css,
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/docsearch.js,
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/link.svg,
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/pkgdown.css,
## [INFO] and
## [INFO] ../../../../home/vp22681/R/x86_64-pc-linux-gnu-library/4.4/pkgdown/BS3/assets/pkgdown.js
## [INFO] to bootstrap-toc.css, bootstrap-toc.js, docsearch.css, docsearch.js, link.svg,
## [INFO] pkgdown.css, and pkgdown.js
## [INFO] ── Building home ───────────────────────────────────────────────────────────────
## [INFO] Writing `authors.html`
## [INFO] Reading LICENSE.md
## [INFO] Writing `LICENSE.html`
## [INFO] Writing `LICENSE-text.html`
## [INFO] Writing `404.html`
## [INFO] ── Building function reference ─────────────────────────────────────────────────
## [INFO] Writing `reference/index.html`
## [INFO] Reading man/BasicExample.Rd
## [INFO] Writing `reference/BasicExample.html`
## [INFO] Reading man/JavaApi.Rd
## [INFO] Writing `reference/JavaApi.html`
## [INFO] Reading man/MoreComplexExample.Rd
## [INFO] Writing `reference/MoreComplexExample.html`
## [INFO] Reading man/RFuture.Rd
## [INFO] Writing `reference/RFuture.html`
## [INFO] Reading man/TestDataGenerator.Rd
## [INFO] Writing `reference/TestDataGenerator.html`
## [INFO] Reading man/dot-background_cancel.Rd
## [INFO] Writing `reference/dot-background_cancel.html`
## [INFO] Reading man/dot-background_cancel_all.Rd
## [INFO] Writing `reference/dot-background_cancel_all.html`
## [INFO] Reading man/dot-background_get_by_id.Rd
## [INFO] Writing `reference/dot-background_get_by_id.html`
## [INFO] Reading man/dot-background_status.Rd
## [INFO] Writing `reference/dot-background_status.html`
## [INFO] Reading man/dot-background_tidy_up.Rd
## [INFO] Writing `reference/dot-background_tidy_up.html`
## [INFO] Reading man/examplePackage-package.Rd
## [INFO] Writing `reference/examplePackage-package.html`
## [INFO] Reading man/greet.Rd
## [INFO] Writing `reference/greet.html`
## [INFO] Reading man/pipe.Rd
## [INFO] Writing `reference/pipe.html`
## [INFO] Reading man/salutation.Rd
## [INFO] Writing `reference/salutation.html`
## [INFO] Reading man/serialise_dataframe.Rd
## [INFO] Writing `reference/serialise_dataframe.html`
## [INFO] Reading man/serialise_list.Rd
## [INFO] Writing `reference/serialise_list.html`
## [INFO] Reading man/serialise_named_list.Rd
## [INFO] Writing `reference/serialise_named_list.html`
## [INFO] ── Building articles ───────────────────────────────────────────────────────────
## [INFO] Writing `articles/index.html`
## [INFO] Reading vignettes/examplePackage.Rmd
## [INFO] Writing `articles/examplePackage.html`
## [INFO] Writing sitemap.xml
## [INFO] ── Finished building pkgdown site for package examplePackage ───────────────────
## [INFO] ── Finished building pkgdown site for package examplePackage ───────────────────
## [INFO] > 
## [INFO] > 
## [INFO] ------------------------------------------------------------------------
## [INFO] BUILD SUCCESS
## [INFO] ------------------------------------------------------------------------
## [INFO] Total time:  28.085 s
## [INFO] Finished at: 2024-05-16T16:27:51+01:00
## [INFO] ------------------------------------------------------------------------

Generated files:

Building the project creates a set of generated R package files, which provide all the R package infrastructure, to execute the Java code from R. These additional files are all generated from the Java code by the maven plugin.

## /tmp/Rtmp7mxF6F/testProject
## └── examplePackage
##     ├── DESCRIPTION
##     ├── LICENSE
##     ├── LICENSE.md
##     ├── NAMESPACE
##     ├── R
##     │   ├── BasicExample.R
##     │   ├── JavaApi.R
##     │   ├── MoreComplexExample.R
##     │   ├── StaticApi.R
##     │   ├── TestDataGenerator.R
##     │   ├── aa_maven.R
##     │   ├── aa_rfuture.R
##     │   └── zzz.R
##     ├── README.md
##     ├── cran-comments.md
##     ├── data-raw
##     │   └── setup-test-data.R
##     ├── docs
##     ├── examplePackage.Rproj
##     ├── inst
##     │   ├── CITATION
##     │   └── java
##     │       └── examplePackage-main-SNAPSHOT-jar-with-dependencies.jar
##     ├── java
##     │   ├── pom.xml
##     │   ├── src
##     │   │   ├── main
##     │   │   │   └── java
##     │   │   │       └── io
##     │   │   │           └── github
##     │   │   │               └── exampleOrganisation
##     │   │   │                   ├── BasicExample.java
##     │   │   │                   ├── MoreComplexExample.java
##     │   │   │                   └── TestDataGenerator.java
##     │   │   └── test
##     │   │       ├── java
##     │   │       │   └── io
##     │   │       │       └── github
##     │   │       │           └── exampleOrganisation
##     │   │       │               └── TestData.java
##     │   │       └── resources
##     │   │           ├── test_iris.ser
##     │   │           ├── test_list.ser
##     │   │           └── test_namedlist.ser
##     │   └── target
##     ├── man
##     │   ├── BasicExample.Rd
##     │   ├── JavaApi.Rd
##     │   ├── MoreComplexExample.Rd
##     │   ├── RFuture.Rd
##     │   ├── TestDataGenerator.Rd
##     │   ├── dot-background_cancel.Rd
##     │   ├── dot-background_cancel_all.Rd
##     │   ├── dot-background_get_by_id.Rd
##     │   ├── dot-background_status.Rd
##     │   ├── dot-background_tidy_up.Rd
##     │   ├── examplePackage-package.Rd
##     │   ├── greet.Rd
##     │   ├── pipe.Rd
##     │   ├── salutation.Rd
##     │   ├── serialise_dataframe.Rd
##     │   ├── serialise_list.Rd
##     │   └── serialise_named_list.Rd
##     ├── pom.xml
##     ├── tests
##     │   ├── testthat
##     │   │   ├── test-BasicExample.R
##     │   │   ├── test-MoreComplexExample.R
##     │   │   └── test-TestDataGenerator.R
##     │   └── testthat.R
##     └── vignettes
##         └── examplePackage.Rmd

Package website:

The maven package installation in this example is configured to build a pkgdown site which can be viewed as follows:

if (interactive()) 
  browseURL(paste0("file:/",URLencode(fs::path(dir,"examplePackage","docs","index.html"))))

Rob Challen

STEP 1: Set up temporary location:

Maven archetype

Building the project

Generated files:

Package website: