From 7d4ca8253a775b195b804abea769a36dd953e240 Mon Sep 17 00:00:00 2001 From: rschoene <rene.schoene@tu-dresden.de> Date: Sun, 27 Jun 2021 12:54:05 +0200 Subject: [PATCH] 0.2.9 - add pages documentation - propagate jastAddList option to ragconnect - add logIncremental to ragconnect --- .gitlab-ci.yml | 25 +++++ build.gradle | 2 +- pages/.gitignore | 2 + pages/custom_theme/footer.html | 11 ++ pages/doc/index.md | 69 ++++++++++++ pages/main.py | 24 ++++ pages/mkdocs.yml | 17 +++ .../testing/doc/DocumentationCreator.java | 106 ++++++++++++++++++ .../testing/plugin/Description.java | 11 ++ .../testing/plugin/JastAddConfiguration.java | 10 ++ .../plugin/RagConnectConfiguration.java | 19 ++++ .../testing/plugin/RagConnectTest.java | 6 + .../testing/plugin/RelastConfiguration.java | 8 ++ 13 files changed, 309 insertions(+), 1 deletion(-) create mode 100644 pages/.gitignore create mode 100644 pages/custom_theme/footer.html create mode 100644 pages/doc/index.md create mode 100644 pages/main.py create mode 100644 pages/mkdocs.yml create mode 100644 src/main/java/org/jastadd/preprocessor/testing/doc/DocumentationCreator.java create mode 100644 src/main/java/org/jastadd/preprocessor/testing/plugin/Description.java diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 3c94406..0852b85 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -19,6 +19,15 @@ build: script: - ./gradlew assemble +createDoc: + image: openjdk:11 + stage: build + script: + - "./gradlew :run" + artifacts: + paths: + - "pages/doc/config.md" + publish: image: openjdk:11 stage: publish @@ -26,3 +35,19 @@ publish: - "./gradlew publishPluginMavenPublicationToMavenRepository" only: - master + +pages: + image: python:3.8-buster + stage: publish + needs: + - createDoc + before_script: + - pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin + script: + - cd pages && mkdocs build + only: + - dev + - master + artifacts: + paths: + - public diff --git a/build.gradle b/build.gradle index 0edac03..618faff 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ plugins { } group 'org.jastadd.preprocessor' -version '0.2.8' +version '0.2.9' gradlePlugin { plugins { diff --git a/pages/.gitignore b/pages/.gitignore new file mode 100644 index 0000000..0b3e404 --- /dev/null +++ b/pages/.gitignore @@ -0,0 +1,2 @@ +/doc/config.md +__pycache__ diff --git a/pages/custom_theme/footer.html b/pages/custom_theme/footer.html new file mode 100644 index 0000000..8e9d67e --- /dev/null +++ b/pages/custom_theme/footer.html @@ -0,0 +1,11 @@ +{% block footer %} +<p>{% if config.copyright %} + <small>{{ config.copyright }}<br></small> + {% endif %} +<hr> +Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. +{% if page and page.meta and page.meta.git_revision_date_localized %} +<small><br><i>Last updated {{ page.meta.git_revision_date_localized }}</i></small> +{% endif %} +</p> +{% endblock %} diff --git a/pages/doc/index.md b/pages/doc/index.md new file mode 100644 index 0000000..f1cea28 --- /dev/null +++ b/pages/doc/index.md @@ -0,0 +1,69 @@ +# Gradle Plugin for JastAdd preprocessors + +This [Gradle plugin](https://git-st.inf.tu-dresden.de/jastadd/testing) is providing means to write Gradle tasks to invoke the two preprocessors [Relast]() and [RagConnect](https://jastadd.pages.st.inf.tu-dresden.de/ragconnect) as well as [JastAdd](http://jastadd.org/) itself. + +To use this plugin, add the following to your `build.gradle`: + +```groovy +buildscript { + repositories { + mavenCentral() + maven { + name "gitlab-maven" + url "https://git-st.inf.tu-dresden.de/api/v4/groups/jastadd/-/packages/maven" + } + } + dependencies { + classpath 'org.jastadd.preprocessor:testing:0.2.8' + } +} + +import org.jastadd.preprocessor.testing.plugin.PreprocessorPlugin +import org.jastadd.preprocessor.testing.plugin.RagConnectTest + +apply plugin: PreprocessorPlugin +``` + +A typical usage (taken from tests used for RagConnect) looks as follows: + +```groovy +task compileTreeIncremental(type: RagConnectTest) { + ragconnect { + outputDir = file('src/test/02-after-ragconnect/treeInc') + inputFiles = [file('src/test/01-input/tree/Test.relast'), + file('src/test/01-input/tree/Test.connect')] + rootNode = 'Root' + logWrites = true + } + relast { + useJastAddNames = true + grammarName = 'src/test/03-after-relast/treeInc/treeInc' + serializer = 'jackson' + } + jastadd { + jastAddList = 'JastAddList' + packageName = 'treeInc.ast' + inputFiles = [file('src/test/01-input/tree/Test.jadd')] + extraOptions = ['--tracing=cache,flush', + '--incremental=param', + '--cache=all', + '--rewrite=cnta', + '--flush=full'] + } +} +``` + +Available options are listed at [configuration](/config). +Notably, all options passed to JastAdd are also passed to the preprocessors, and generated files are handled correctly, e.g., generated aspects are passed to JastAdd automatically. + +The compilers to be used can be configured as follows: + +```groovy +preprocessorTesting { + //noinspection GroovyAssignabilityCheck + relastCompilerLocation = '../libs/relast.jar' + ragconnectCompilerLocation = '../libs/ragconnect.jar' +} +``` + +By default, the compilers are expected to be available in the classpath. diff --git a/pages/main.py b/pages/main.py new file mode 100644 index 0000000..f48dc72 --- /dev/null +++ b/pages/main.py @@ -0,0 +1,24 @@ +buildGradle = '../build.gradle' + + +def get_version(): + with open(buildGradle) as fd: + for line in fd.readlines(): + # look for line `version 'Major.Minor.Patch'` + if line.startswith('version '): + return line[9:-2] + return '?' + + +def define_env(env): + """ + This is the hook for defining variables, macros and filters + + - variables: the dictionary that contains the environment variables + - macro: a decorator function, to declare a macro. + """ + env.conf['site_name'] = 'Gradle Plugin RelastTest ' + get_version() + + +if __name__ == '__main__': + print(get_version()) diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml new file mode 100644 index 0000000..4b9e75b --- /dev/null +++ b/pages/mkdocs.yml @@ -0,0 +1,17 @@ +site_name: Gradle Plugin RelastTest +nav: + - using.md + - API documentation: ragdoc/index.html +theme: + name: readthedocs + custom_dir: custom_theme/ +plugins: + - search + - git-revision-date-localized: + type: datetime + timezone: Europe/Berlin + locale: en + fallback_to_build_date: True + - macros +repo_url: https://git-st.inf.tu-dresden.de/jastadd/preprocessors/coverage-generator +site_dir: ../public diff --git a/src/main/java/org/jastadd/preprocessor/testing/doc/DocumentationCreator.java b/src/main/java/org/jastadd/preprocessor/testing/doc/DocumentationCreator.java new file mode 100644 index 0000000..8f819e8 --- /dev/null +++ b/src/main/java/org/jastadd/preprocessor/testing/doc/DocumentationCreator.java @@ -0,0 +1,106 @@ +package org.jastadd.preprocessor.testing.doc; + +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.InputFiles; +import org.gradle.api.tasks.Optional; +import org.gradle.api.tasks.OutputDirectory; +import org.jastadd.preprocessor.testing.plugin.Description; +import org.jastadd.preprocessor.testing.plugin.JastAddConfiguration; +import org.jastadd.preprocessor.testing.plugin.RagConnectConfiguration; +import org.jastadd.preprocessor.testing.plugin.RelastConfiguration; + +import java.io.BufferedWriter; +import java.io.IOException; +import java.lang.reflect.Method; +import java.nio.file.Files; +import java.nio.file.Paths; +import java.nio.file.StandardOpenOption; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.PriorityQueue; + +public class DocumentationCreator { + private static final String HEADER = "# Configuration options\n\n"; + private static final List<Map.Entry<String, Class<?>>> entitiesToBeDocumented = new ArrayList<>() {{ + add(Map.entry("RagConnect Configuration", RagConnectConfiguration.class)); + add(Map.entry("Relast Configuration", RelastConfiguration.class)); + add(Map.entry("JastAdd Configuration", JastAddConfiguration.class)); + }}; + private static final String outputFile = "pages/doc/config.md"; + + public static void main(String[] args) { + new DocumentationCreator().run(); + } + + protected void run() { + PriorityQueue<String[]> options = new PriorityQueue<>((e1, e2) -> { + if (e1[1].equals("Yes")) { + if (e2[1].equals("Yes")) { + return e1[0].compareTo(e2[0]); + } + return -1; + } + if (e2[1].equals("Yes")) { + return 1; + } + return e1[0].compareTo(e2[0]); + }); + try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputFile), + StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING)) { + writer.write(HEADER); + for (Map.Entry<String, Class<?>> entry : entitiesToBeDocumented) { + options.clear(); + writer.write("## " + entry.getKey() + "\n\n"); + writer.write("Name | Required? | Corresponding parameter | Description\n"); + writer.write("--- | --- | --- | ---\n"); + for (Method method : entry.getValue().getMethods()) { + if (method.isAnnotationPresent(Input.class) || + method.isAnnotationPresent(InputFiles.class) || + method.isAnnotationPresent(OutputDirectory.class)) { + String name = nameOfOption(method.getName()); + String required = method.isAnnotationPresent(Optional.class) ? "No" : "Yes"; + final String parameter, description; + if (method.isAnnotationPresent(Description.class)) { + Description descriptionAnnotation = method.getAnnotation(Description.class); + if (descriptionAnnotation.skip()) { + continue; + } + if (descriptionAnnotation.correspondingParameter().isBlank()) { + parameter = ""; + } else { + parameter = "`" + descriptionAnnotation.correspondingParameter() + "`"; + } + description = descriptionAnnotation.value(); + } else { + parameter = ""; + description = "_not provided_"; + } + options.add(new String[]{name, required, parameter, description}); + } + } + while(!options.isEmpty()) { + String[] option = options.poll(); + String toWrite = String.format("%s | %s | %s | %s%n", (Object[]) option); + writer.write(toWrite); + } + writer.write("\n\n"); + } + } catch (IOException e) { + e.printStackTrace(); + } + } + + private String nameOfOption(String methodName) { + if (methodName == null || methodName.isEmpty()) { return methodName; } + final String s; + if (methodName.startsWith("get")) { + s = methodName.substring(3); + } else if (methodName.startsWith("is")) { + s = methodName.substring(2); + } else { + throw new RuntimeException("Unknown prefix in method " + methodName); + } + return Character.toLowerCase(s.charAt(0)) + s.substring(1); + } +} diff --git a/src/main/java/org/jastadd/preprocessor/testing/plugin/Description.java b/src/main/java/org/jastadd/preprocessor/testing/plugin/Description.java new file mode 100644 index 0000000..21f6c85 --- /dev/null +++ b/src/main/java/org/jastadd/preprocessor/testing/plugin/Description.java @@ -0,0 +1,11 @@ +package org.jastadd.preprocessor.testing.plugin; + +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +@Retention(RetentionPolicy.RUNTIME) +public @interface Description { + String value(); + String correspondingParameter() default ""; + boolean skip() default false; +} diff --git a/src/main/java/org/jastadd/preprocessor/testing/plugin/JastAddConfiguration.java b/src/main/java/org/jastadd/preprocessor/testing/plugin/JastAddConfiguration.java index 0d60e46..8ed8cdc 100644 --- a/src/main/java/org/jastadd/preprocessor/testing/plugin/JastAddConfiguration.java +++ b/src/main/java/org/jastadd/preprocessor/testing/plugin/JastAddConfiguration.java @@ -15,20 +15,24 @@ import java.util.List; */ public interface JastAddConfiguration { + @Description(value = "Package name of AST files", correspondingParameter = "--package") @Input String getPackageName(); void setPackageName(String packageName); + @Description(value = "Name of the List class", correspondingParameter = "--List") @Optional @Input String getJastAddList(); void setJastAddList(String jastAddList); + @Description(value = "Do not run JastAdd") @Optional @Input boolean isSkipRun(); void setSkipRun(boolean skipRun); + @Description(value = "Add more options not directly supported") @Optional @Input List<String> getExtraOptions(); @@ -37,19 +41,25 @@ public interface JastAddConfiguration { return getExtraOptions() != null ? getExtraOptions() : Collections.emptyList(); } + @Description(value = "Add new input files to be processed") @Optional @InputFiles List<File> getInputFiles(); void setInputFiles(List<File> inputFiles); + @Description(value = "Output directory (defaults to `src/test/java-gen`)", correspondingParameter = "--o") @Optional @OutputDirectory File getOutputDir(); void setOutputDir(File outputDir); + + @Description(value = "_only used internally_", skip = true) @OutputDirectory default File getOutputDirOrDefault() { return getOutputDir() != null ? getOutputDir() : Paths.get("src", "test", "java-gen").toFile(); } + + @Description(value = "_only used internally_", skip = true) @OutputDirectory default File getPackageOutputDir() { return getOutputDirOrDefault().toPath().resolve(getPackageName().replace('.', File.separatorChar)).toFile(); diff --git a/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectConfiguration.java b/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectConfiguration.java index 8c7bb91..783fe60 100644 --- a/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectConfiguration.java +++ b/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectConfiguration.java @@ -14,35 +14,54 @@ import java.util.List; */ public interface RagConnectConfiguration { + @Description(value = "Sets the root node", correspondingParameter = "--rootNode") @Input String getRootNode(); void setRootNode(String rootNode); + @Description(value = "Sets the output directory", correspondingParameter = "--o") @Input String getOutputDir(); void setOutputDir(String outputDir); + @Description(value = "Add new input files to be processed") @InputFiles List<File> getInputFiles(); void setInputFiles(List<File> inputFiles); + @Description(value = "Log read endpoints", correspondingParameter = "--logReads") @Optional @Input boolean isLogReads(); void setLogReads(boolean logReads); + @Description(value = "Log write endpoints", correspondingParameter = "--logWrites") @Optional @Input boolean isLogWrites(); void setLogWrites(boolean logWrites); + @Description(value = "Log incremental activities", correspondingParameter = "--logIncremental") + @Optional + @Input + boolean isLogIncremental(); + void setLogIncremental(boolean loggIncremental); + + @Description(value = "Be more verbose during compilation", correspondingParameter = "--verbose") @Optional @Input boolean isVerbose(); void setVerbose(boolean verbose); + @Description(value = "Set protocols to be used", correspondingParameter = "--protocols") @Optional @Input List<String> getProtocols(); void setProtocols(List<String> protocols); + + @Description(value = "Add more options not directly supported") + @Optional + @Input + List<String> getAdditionalOptions(); + void setAdditionalOptions(List<String> additionalOptions); } diff --git a/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectTest.java b/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectTest.java index 726c6ec..d310f3a 100644 --- a/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectTest.java +++ b/src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectTest.java @@ -108,12 +108,18 @@ public abstract class RagConnectTest extends RelastTest { if (getRagconnect().isLogWrites()) { args.add("--logWrites"); } + if (getRagconnect().isLogIncremental()) { + args.add("--logIncremental"); + } if (getRagconnect().isVerbose()) { args.add("--verbose"); } if (getRagconnect().getProtocols() != null && !getRagconnect().getProtocols().isEmpty()) { args.add("--protocols=" + String.join(",", getRagconnect().getProtocols())); } + if (getJastadd().getJastAddList() != null) { + args.add("--jastAddList=" + getJastadd().getJastAddList()); + } args.addAll(getJastadd().getExtraOptionsOrDefault()); args.addAll(getRagconnect().getInputFiles()); javaExecSpec.args(args); diff --git a/src/main/java/org/jastadd/preprocessor/testing/plugin/RelastConfiguration.java b/src/main/java/org/jastadd/preprocessor/testing/plugin/RelastConfiguration.java index 958ec33..bf721f6 100644 --- a/src/main/java/org/jastadd/preprocessor/testing/plugin/RelastConfiguration.java +++ b/src/main/java/org/jastadd/preprocessor/testing/plugin/RelastConfiguration.java @@ -14,40 +14,48 @@ import java.util.List; */ public interface RelastConfiguration { + @Description(value = "Use JastAdd like API for relations", correspondingParameter = "--useJastAddNames") @Optional @Input boolean isUseJastAddNames(); void setUseJastAddNames(boolean useJastAddNames); + @Description(value = "Name of resulting grammar (can be a path)", correspondingParameter = "--grammarName") @Input String getGrammarName(); void setGrammarName(String grammarName); + @Description(value = "Add new input files to be processed") @Optional @InputFiles List<File> getInputFiles(); void setInputFiles(List<File> inputFiles); + @Description(value = "Do not write any files", correspondingParameter = "--file") @Optional @Input boolean isNoWriteToFile(); void setNoWriteToFile(boolean noWriteToFile); + @Description(value = "Do not generate resolverHelper", correspondingParameter = "--resolverHelper") @Optional @Input boolean isNoResolverHelper(); void setNoResolverHelper(boolean noResolverHelper); + @Description(value = "Class to be used for relations", correspondingParameter = "--listClass") @Optional @Input String getListClass(); void setListClass(String listClass); + @Description(value = "Activate serialization, and set its implementation", correspondingParameter = "--serializer") @Optional @Input String getSerializer(); void setSerializer(String serializer); + @Description(value = "Be more verbose during compilation") @Optional @Input boolean isVerbose(); -- GitLab