Commit fb257702 authored by René Schöne's avatar René Schöne
Browse files

Merge branch 'release-0.3.0' into 'master'

Testing incremental dependency tracking.

See merge request !5
parents 24062cab c2e8a9de
Pipeline #9501 passed with stages
in 13 minutes and 13 seconds
......@@ -6,3 +6,4 @@
.idea/
.gradle/
build/
public/
variables:
GIT_SUBMODULE_STRATEGY: recursive
GIT_DEPTH: 1000
stages:
- build
- test
- publish
- build
- test
- ragdoc_build
- ragdoc_view
- publish
before_script:
- export GRADLE_USER_HOME=`pwd`/.gradle
......@@ -21,7 +24,8 @@ build:
- ./gradlew --console=plain --no-daemon assemble jar
artifacts:
paths:
- "/builds/jastadd/ragconnect/ragconnect.base/build/libs/ragconnect-*.jar"
- "ragconnect.base/build/libs/ragconnect-*.jar"
- "ragconnect.base/src/gen"
expire_in: 1 week
test:
......@@ -30,29 +34,70 @@ test:
services:
- name: "eclipse-mosquitto:1.6.9"
alias: "mqtt"
needs:
- build
script:
- ./gradlew --console=plain --no-daemon allTests
artifacts:
when: always
reports:
junit: "/builds/jastadd/ragconnect/ragconnect.tests/build/test-results/test/TEST-*.xml"
junit: "ragconnect.tests/build/test-results/**/TEST-*.xml"
expire_in: 1 week
publish:
image: openjdk:11
stage: publish
needs:
- test
script:
- "./gradlew publish"
only:
- master
ragdoc_build:
image:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
entrypoint: [""]
stage: ragdoc_build
needs:
- build
script:
- JAVA_FILES=$(find ragconnect.base/src/ -name '*.java')
- /ragdoc-builder/start-builder.sh -excludeGenerated -d data/ $JAVA_FILES
artifacts:
paths:
- "data/"
ragdoc_view:
image:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
entrypoint: [""]
stage: ragdoc_view
needs:
- ragdoc_build
script:
- DATA_DIR=$(pwd -P)/data
- mkdir -p pages/docs/ragdoc
- OUTPUT_DIR=$(pwd -P)/pages/docs/ragdoc
- cd /ragdoc-view/src/ && rm -rf data && ln -s $DATA_DIR
- /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
artifacts:
paths:
- "pages/docs/ragdoc"
pages:
image: python:3.7-alpine
image: python:3.8-buster
stage: publish
needs:
- ragdoc_view
- test
before_script:
- pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin
script:
- pip install -U sphinx sphinx-rtd-theme recommonmark sphinxemoji sphinx-markdown-tables
- sphinx-build -b html pages/ public
- cd pages && mkdocs build
only:
- dev
- master
artifacts:
paths:
- public
only:
- master
[submodule "relast-preprocessor"]
path = relast-preprocessor
url = ../relast-preprocessor.git
branch = jastadd-fix-inc-param-debug
[submodule "ragconnect.base/src/main/jastadd/mustache"]
path = ragconnect.base/src/main/jastadd/mustache
url = ../mustache
# RagConnect
[RagConnect](https://git-st.inf.tu-dresden.de/jastadd/ragconnect) is a preprocessor to enable easy connection to/from models based on [Reference Attribute Grammars](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf) and [Relational Reference Attribute Grammars](https://doi.org/10.1016/j.cola.2019.100940) built with [JastAdd](http://jastadd.org/).
Documentation can be found at <http://connect.relational-rags.eu> including an API documentation.
The most recent version is listed at the [package registry](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/packages).
_static/poster-presentation.mp4 filter=lfs diff=lfs merge=lfs -text
docs/img/poster-presentation.mp4 filter=lfs diff=lfs merge=lfs -text
docs/img/moving-robot.mp4 filter=lfs diff=lfs merge=lfs -text
/public/
/docs/ragdoc/
__pycache__
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = public
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import sphinx_rtd_theme
# -- Project information -----------------------------------------------------
project = 'RagConnect'
copyright = '2021, René Schöne, Johannes Mey'
author = 'René Schöne, Johannes Mey'
# The full version, including alpha/beta/rc tags
ragconnectVersionFileName = '../ragconnect.base/src/main/resources/ragConnectVersion.properties'
with open(ragconnectVersionFileName) as ragconnectVersionFile:
versionFileContent = ragconnectVersionFile.read()
release = version = versionFileContent[versionFileContent.rindex('version=') + 8:].strip()
print('Version: ' + version)
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_rtd_theme',
'recommonmark',
'sphinxemoji.sphinxemoji',
'sphinx_markdown_tables'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
sphinxemoji_style = 'twemoji'
{% 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 %}
# Extending `RagConnect`
To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol):
Within `ragconnect.base/src/main/resources`:
{% raw %}
- Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers
- If further methods are needed for handler initialization, add a new template `abc.mustache` containing those procedures. Add `{{#usesABC}}{{> abc}}{{/usesABC}}` at the top of `ragconnect.mustache` to use this template
- In `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`.
{% endraw %}
Within `ragconnect.base/src/main/jastadd`:
- In `backend/Configuration`:
- Add a new static boolean flag `usesABC` to indicate whether the protocol is used
- In `backend/Generation`:
- Add new attributes for type `MRagConnect` for handler attribute and handler field, if needed
- Add attributes for newly introduced references in changed mustache templates, if any
- Add a newly constructed handler within the definition of `RagConnect.toMustache` with the needed fields (class name, construction snippet, handler attribute, handler field, the boolean flag you just added to Configuration)
- In `backend/MustacheNodesToYAML`:
- Add key-value-pair for `usesABC` (and handler, if any)
- Add key-value-pairs for newly introduced referemces in changed mustache templates, if any
In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`:
- Add a new choice for `--protocols` similar to the existing ones
- Set the flag `usesABC` if the choice is given.
- Add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC`
Furthermore, new test cases are appreciated, see [below](#writing-tests).
## Writing Tests
To add new tests, have a look at the module `ragconnect.tests`.
It has three parts:
1) In `src/test/01-input/*` are the [specifications](#specifications) that are going to be compiled (in principle using the steps described in [the guide to add RagConnect](adding)).
2) In `src/test/java`, the jUnit 5 [test classes](#test-classes) are implemented. They mostly correspond 1-to-1 to a directory of the first part.
3) In `build.gradle` the [instructions how to compile](#buildgradle) the specifications using the gradle plugin [PreprocessorPlugin][preprocessor-plugin] (`org.jastadd.preprocessor:testing`).
### Specifications
Every specification must have at least a `README.md` to describe the purpose of the test, a grammar `Test.relast`, and a RagConnect specification `Test.connect`.
Usually an aspect file `Test.jadd` is included.
### Test Classes
Based on jUnit 5, the test classes testing some behaviour. If sending and/or receiving functionality is used, consider extending `AbstractMqttTest` in order to avoid duplicate code. In case of extending this class, please order the methods according to their lifecycle, i.e.:
- createModel
- setupReceiverAndConnect
- communicateSendInitialValue
- communicateOnlyUpdatedValue
- closeConnections
Within `AbstractMqttTest`, an `MqttHandler` named `publisher` is available to publish content.
Some convenience methods are provided in `TestUtils`, e.g., the `DefaultMappings`, and `mqttUri` to prepend `"mqtt://"` and the correct host for the mqtt broker (`localhost` or a CI-specific host).
All tests are required to run both locally, and within the CI.
### build.gradle
Use the [PreprocessorPlugin][preprocessor-plugin], the build process can be written concisely in three parts per task:
```groovy
task compileTreeAllowedTokens(type: RagConnectTest) {
ragconnect {
outputDir = file('src/test/02-after-ragconnect/treeAllowedTokens')
inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.relast'),
file('src/test/01-input/treeAllowedTokens/Test.connect'),
file('src/test/01-input/treeAllowedTokens/TestDependencies.connect')]
rootNode = 'Root'
}
relast {
useJastAddNames = true
grammarName = 'src/test/03-after-relast/treeAllowedTokens/treeAllowedTokens'
serializer = 'jackson'
}
jastadd {
jastAddList = 'JastAddList'
packageName = 'treeAllowedTokens.ast'
inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.jadd')]
}
}
```
[preprocessor-plugin]: https://git-st.inf.tu-dresden.de/jastadd/testing
# RagConnect Documentation
[RagConnect](https://git-st.inf.tu-dresden.de/jastadd/ragconnect) is a preprocessor to enable easy connection to/from models based on [Reference Attribute Grammars](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf) and [Relational Reference Attribute Grammars](https://doi.org/10.1016/j.cola.2019.100940) built with [JastAdd](http://jastadd.org/).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment