diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index b6bf4858b97068488b069297326a1ec70aeaa19b..e5a30e5a7bba8003594b853fc1eda86531001e43 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -2,6 +2,7 @@ stages: - build - test - jar +- deploy build: image: openjdk:8 @@ -41,3 +42,15 @@ jar: artifacts: paths: - "/builds/jastadd/*/build/libs/*relast*.jar" + +pages: + image: python:3.7-alpine + stage: deploy + script: + - pip install -U sphinx sphinx-rtd-theme recommonmark sphinxemoji sphinx-markdown-tables + - sphinx-build -b html pages/ public + artifacts: + paths: + - public + only: + - master diff --git a/pages/.gitignore b/pages/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..69fa449dd96e2405945b2e4cff2fd0ab8b102097 --- /dev/null +++ b/pages/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/pages/Command-Line-Arguments.rst b/pages/Command-Line-Arguments.rst new file mode 100644 index 0000000000000000000000000000000000000000..1711faf47f6d41205eadbfe6a98c9848a225db73 --- /dev/null +++ b/pages/Command-Line-Arguments.rst @@ -0,0 +1,13 @@ +Supported command-line options +============================== + +--ast print AST (ignores quiet option) +--file write output to files <filename>Gen.ast and <filename>Gen.jadd +--grammarName name of the generated grammar and aspect (without file extension) +--jastAddList set the name of the List type in JastAdd (has to match the option '--List' or its default List) +--listClass determine the class name of the nonterminal reference list +--quiet do not output anything on stdout +--resolverHelper create a subtype for each type containing a string that can be used to resolve the type later +--serializer generate a (de-)serializer (allowed values: jackson, jackson-json-pointer, jackson-manual-references) +--useJastAddNames generate names in the form of addX, removeX and setX. If omitted, the default, original naming scheme resulting in addToX, removeFromX and setX will be used. +--version print version and exit diff --git a/pages/Makefile b/pages/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..d4bb2cbb9eddb1bb1b4f366623044af8e4830919 --- /dev/null +++ b/pages/Makefile @@ -0,0 +1,20 @@ +# 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 = _build + +# 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) diff --git a/pages/Supported-Relations.rst b/pages/Supported-Relations.rst new file mode 100644 index 0000000000000000000000000000000000000000..23192578691a49c0e5e39ccb9584940eea06bc43 --- /dev/null +++ b/pages/Supported-Relations.rst @@ -0,0 +1,23 @@ +Supported relations +=================== + +.. code:: Java + + // Directed relations + A.b -> B; + A.b? -> B; + A.bs* -> B; + B <- A.b ; + B <- A.b? ; + B <- A.bs*; + + // Bidirectional relations + A.b <-> B.a; + A.b <-> B.a?; + A.b <-> B.as*; + A.b? <-> B.a; + A.b? <-> B.a?; + A.b? <-> B.as*; + A.bs* <-> B.a; + A.bs* <-> B.a?; + A.bs* <-> B.as*; diff --git a/pages/Using.rst b/pages/Using.rst new file mode 100644 index 0000000000000000000000000000000000000000..bfd773451b939af38b6102c70d2c6d4057565e49 --- /dev/null +++ b/pages/Using.rst @@ -0,0 +1,38 @@ +Using Relational RAGs +===================== + +The Relational RAGs preprocessor takes a ``.relast`` file as input comprising AST rules and relations. It produces files that afterwards are processed by JastAdd_ to generated Java code. +To use it in your project, build the JAR file running + +.. code:: Bash + + ./gradlew jar + +This will produce ``build/libs/relast.jar``. Copy it to your project and extend your build config (preferably Gradle_) with the following: + +.. code:: Groovy + + task preprocess(type: JavaExec) { + group = 'Build' + main = "-jar" + args = [ + "libs/relast.jar", + "./src/main/jastadd/main.relast", + "--listClass=RefList", + "--jastAddList=JastAddList", + "--file" + ] + + inputs.files file("./src/main/jastadd/main.relast") + outputs.files file("./src/main/jastadd/mainGen.ast"), file("./src/main/jastadd/mainGen.jadd") + } + +Note that you may have to change + +- the directory of ``relast.jar`` +- the ``.relast`` file(s) both as argument(s) and input file(s) +- the output files +- parameters of RelAST (in this case, the list classes were renamed), the following table shows the supported ones + +.. _JastAdd: http://jastadd.org/ +.. _Gradle: https://gradle.org/ diff --git a/pages/conf.py b/pages/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..df20528ffd66f1981a254cd50dc0022416a80a9f --- /dev/null +++ b/pages/conf.py @@ -0,0 +1,65 @@ +# 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('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Relational RAGs' +copyright = '2020, Johannes Mey, René Schöne, Görel Hedin, Emma Söderberg, Thomas Kühn, Niklas Fors, Jesper Öqvist, Uwe Aßmann' +author = 'Johannes Mey, René Schöne, Görel Hedin, Emma Söderberg, Thomas Kühn, Niklas Fors, Jesper Öqvist, Uwe Aßmann' + +# The full version, including alpha/beta/rc tags +release = '0.3.0' + + +# -- 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 = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- 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' + +html_theme_options = { + 'navigation_depth': 4, +} diff --git a/pages/images/relast-process.png b/pages/images/relast-process.png new file mode 100644 index 0000000000000000000000000000000000000000..e3dda55dbd8e7a3bcb98207e8c81f52f4a682d10 Binary files /dev/null and b/pages/images/relast-process.png differ diff --git a/pages/index.rst b/pages/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..a529404601fba5874ea3b449abcccf5ed0978677 --- /dev/null +++ b/pages/index.rst @@ -0,0 +1,23 @@ +.. Relational RAGs documentation master file, created by + sphinx-quickstart on Tue Oct 20 11:41:47 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Relational RAGs documentation +============================= + +.. toctree:: + :caption: Contents: + :hidden: + + Using.rst + Command-Line-Arguments.rst + Supported-Relations.rst + publications.rst + +.. image:: images/relast-process.png + :alt: RelAST process + +See `releases page`_ for the latest version. + +.. _releases page: https://git-st.inf.tu-dresden.de/jastadd/relational-rags/-/releases diff --git a/pages/make.bat b/pages/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..922152e96a04a242e6fc40f124261d74890617d8 --- /dev/null +++ b/pages/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/pages/publications.rst b/pages/publications.rst new file mode 100644 index 0000000000000000000000000000000000000000..038cc59f316b6497ae015a06ac5a292d15e66672 --- /dev/null +++ b/pages/publications.rst @@ -0,0 +1,163 @@ +Publications +============ + +Main publication at SLE'18 +-------------------------- + +.. raw:: html + + <link rel="stylesheet" + href="https://dl.acm.org/specs/products/acm/widgets/authorizer/scss/style.css" /> + <style> + .multi-search { + min-height: 0; + padding: 0px; + } + .issue-item { + } + </style> + <div class="multi-search multi-search--issue-item"> + <div class="issue-item clearfix"> + <div class="issue-item__citation"> + <div class="issue-heading">chapter</div> + </div> + <div class="issue-item__content"> + <h5 class="issue-item__title"><a + href="https://dl.acm.org/doi/10.1145/3276604.3276616?cid=81318498502">Continuous + model validation using reference attribute + grammars</a></h5> + + <ul class="rlist--inline loa truncate-list" + title="list of authors" data-lines="2"> + <li><a href="https://dl.acm.org/profile/99659180755" + title="Johannes Mey"><img class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Johannes Mey profile image" /><span>Johannes + Mey</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-99659180755">TU + Dresden, Germany</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/81318498502" + title="René Schöne"><img class="author-picture" + src="https://dl.acm.org/do/10.1145/contrib-81318498502/rel-imgonly/author-rene.jpg" + alt="René Schöne profile image" /><span>René + Schöne</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-81318498502">TU + Dresden, Germany</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/81100270533" + title="Görel Hedin"><img class="author-picture" + src="https://dl.acm.org/do/10.1145/contrib-81100270533/rel-imgonly/81100270533.jpg" + alt="Görel Hedin profile image" /><span>Görel + Hedin</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-81100270533">Lund + University, Sweden</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/81482659289" + title="Emma Söderberg"><img + class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Emma Söderberg profile image" /><span>Emma + Söderberg</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-81482659289">Lund + University, Sweden</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/81100443648" + title="Thomas Kühn"><img class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Thomas Kühn profile image" /><span>Thomas + Kühn</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-81100443648">TU + Dresden, Germany</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/82459076457" + title="Niklas Fors"><img class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Niklas Fors profile image" /><span>Niklas + Fors</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-82459076457">Lund + University, Sweden</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/82858857457" + title="Jesper Öqvist"><img + class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Jesper Öqvist profile image" /><span>Jesper + Öqvist</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-82858857457">Lund + University, Sweden</p> + </span><span>, </span></li> + <li><a href="https://dl.acm.org/profile/81100444066" + title="Uwe Aßmann"><img class="author-picture" + src="https://dl.acm.org/pb-assets/icons/DOs/default-profile-1543932446943.svg" + alt="Uwe Aßmann profile image" /><span>Uwe + Aßmann</span></a><span + class="loa_author_inst hidden"> + <p data-doi="10.1145/contrib-81100444066">TU + Dresden, Germany</p> + </span></li> + </ul> + + <div class="issue-item__detail"><span>October + 2018</span><span class="dot-separator">pp 70-82 + </span><span><a + href="https://doi.org/10.1145/3276604.3276616" + class="issue-item__doi dot-separator">https://doi.org/10.1145/3276604.3276616</a></span> + </div> + <div data-lines='4' + class="issue-item__abstract truncate-text"> + <div class="issue-item__abstract truncate-text" + data-lines="4"> + + <p>Just like current software systems, models are + characterised by increasing complexity + and rate of change. Yet, these models only + become useful if they can be continuously + evaluated and validated. To achieve sufficiently + low response times for large ... + </p> + </div> + </div> + </div> + </div> + </div> + <br/> + +Follow-Up publication in JCL +---------------------------- + +**Relational reference attribute grammars: Improving continuous model validation** + +Johannes Mey |a|, René Schöne |a|, Görel Hedin |b|, Emma Söderberg |b|, Thomas Kühn |a|, Niklas Fors |b|, Jesper Öqvist |b|, Uwe Aßmann |a| + +- |a| Technische Universitãt Dresden, Germany +- |b| Lund University, Sweden + +Received 31 March 2019, Revised 1 November 2019, Accepted 20 December 2019, Available online 20 January 2020. + +https://doi.org/10.1016/j.cola.2019.100940 + +.. |a| replace:: :sup:`a` +.. |b| replace:: :sup:`b` + + +Publications using Relational RAGs +---------------------------------- + +- `Subpage on RagConnect`_ +- Götz, Sebastian, Johannes Mey, René Schöne, and Uwe Aßmann. **“A JastAdd- and ILP-Based Solution to the Software-Selection and Hardware-Mapping-Problem at the TTC 2018.”** In 11th Transformation Tool Contest, 2018. +- Götz, Sebastian, Johannes Mey, René Schöne, and Uwe Aßmann. **“Quality-Based Software-Selection and Hardware-Mapping as Model Transformation Problem.”** In 11th Transformation Tool Contest, 2018. +- Mey, Johannes, René Schöne, Christopher Werner, and Uwe Aßmann. **“Transforming Truth Tables to Binary Decision Diagrams Using Relational Reference Attribute Grammars.”** In Proceedings of the 12th Transformation Tool Contest (TTC 2019), 2019. +- Schöne, René, and Johannes Mey. **“A JastAdd-Based Solution to the TTC 2018 Social Media Case.”** In 11th Transformation Tool Contest, 2018. +- Schöne, René, Johannes Mey, Boqi Ren, and Uwe Aßmann. **“Bridging the Gap between Smart Home Platforms and Machine Learning Using Relational Reference Attribute Grammars.”** In Proceedings of the 14th International Workshop on Models\@run.Time, 533–42. Munich, 2019. https://doi.org/10.1109/MODELS-C.2019.00083 +- Mey, Johannes, Thomas Kühn, René Schöne, and Uwe Aßmann. **“Reusing Static Analysis across Different Domain-Specific Languages Using Reference Attribute Grammars.”** Programming 4, no. 3 (February 17, 2020). https://doi.org/10.22152/programming-journal.org/2020/4/15 + + +.. _Subpage on RagConnect: http://connector.relational-rags.eu/