diff options
-rw-r--r-- | CONTRIBUTING.md | 48 | ||||
-rw-r--r-- | README.md | 58 |
2 files changed, 78 insertions, 28 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..d5191795 --- /dev/null +++ b/CONTRIBUTING.md | |||
@@ -0,0 +1,48 @@ | |||
1 | <!-- | ||
2 | SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/> | ||
3 | |||
4 | SPDX-License-Identifier: EPL-2.0 | ||
5 | --> | ||
6 | |||
7 | # Contributing to Refinery | ||
8 | |||
9 | ## Setting up the development environment | ||
10 | |||
11 | ### With Eclipse IDE | ||
12 | |||
13 | 1. Download and install a _Java 17_ compatible JDK. For Windows, prefer OpenJDK builds from [Adoptium](https://adoptium.net/). | ||
14 | |||
15 | 2. Download and extract the [Eclipse IDE for Java and DSL Developers 2022-09](https://www.eclipse.org/downloads/packages/release/2022-09/r/eclipse-ide-java-and-dsl-developers) package. | ||
16 | |||
17 | 3. Launch Eclipse and create a new workspace. | ||
18 | |||
19 | 4. Open _Help > Install New Software..._ and install the following software from the _2022-09_ update site: | ||
20 | * _Modeling > Ecore Diagram Editor (SDK)_ | ||
21 | |||
22 | 5. Open _Help > Eclipse Marketplace_ and install the following software: | ||
23 | * _EclEmma Java Code Coverage_ | ||
24 | * _SonarLint_ | ||
25 | |||
26 | 6. Open _Window > Preferences_ and set the following preferences: | ||
27 | * _General > Workspace > Text file encoding_ should be _UTF-8_. | ||
28 | * _General > Workspace > New text file line delimiter_ should be _Unix_. | ||
29 | * Add the JDK 17 to _Java > Installed JREs_. | ||
30 | * Make sure JDK 17 is selected for _JavaSE-17_ at _Java > Installed JREs > Execution Environments_. | ||
31 | * Set _Gradle > Java home_ to the `JAVA_HOME` directory (the directory which contains the `bin` directory) of JDK 17. Here, Buildship will show a yellow warning sign, which can be safely ignored. | ||
32 | * Set _Java > Compiler > JDK Compliance > Compiler compliance level_ to _17_. | ||
33 | |||
34 | 7. Clone the project Git repository but do not import it into Eclipse yet. | ||
35 | |||
36 | 8. Open a new terminal an run `./gradlew prepareEclipse` (`.\gradlew prepareEclipse` on Windows) in the cloned repository. | ||
37 | * This should complete without any compilation errors. | ||
38 | * If you get any errors about the JVM version, check whether the `JAVA_HOME` environment variable is set to the location of JDK. You can query the variable with `echo $JAVA_HOME` on Linux and `echo $Env:JAVA_HOME` in PowerShell on Windows. To set it, use `export JAVA_HOME=/java/path/here` or `$Env:JAVA_HOME="C:\java\path\here"`, respectively. | ||
39 | * If the build fails with a `Host name must not be empty` error, you [might need to remove the empty proxy configuration from your global `gradle.properties` file](https://stackoverflow.com/a/62128323). | ||
40 | |||
41 | 9. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse. | ||
42 | * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_. | ||
43 | * If you have previously imported the project into Eclipse, this step will likely fail. In that case, you should remove the projects from Eclipse, run `git clean -fxd` in the repository, and start over from step 8. | ||
44 | |||
45 | ### With IntelliJ IDEA | ||
46 | |||
47 | It is possible to import the project into IntelliJ IDEA, but it gives no editing help for Xtext (`*.xtext`), MWE2 (`*.mwe2`), and Xtend (`*.xtend`) and Ecore class diagrams (`*.aird`, `*.ecore`, `*.genmodel`). | ||
48 | |||
@@ -6,47 +6,49 @@ | |||
6 | 6 | ||
7 | # Refinery | 7 | # Refinery |
8 | 8 | ||
9 | [![Build](https://github.com/graphs4value/refinery/actions/workflows/build.yml/badge.svg)](https://github.com/graphs4value/refinery/actions/workflows/build.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=graphs4value_refinery&metric=alert_status)](https://sonarcloud.io/dashboard?id=graphs4value_refinery) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=graphs4value_refinery&metric=coverage)](https://sonarcloud.io/dashboard?id=graphs4value_refinery) | 9 | [![Build](https://github.com/graphs4value/refinery/actions/workflows/build.yml/badge.svg)](https://github.com/graphs4value/refinery/actions/workflows/build.yml)<!--[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=graphs4value_refinery&metric=alert_status)](https://sonarcloud.io/dashboard?id=graphs4value_refinery) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=graphs4value_refinery&metric=coverage)](https://sonarcloud.io/dashboard?id=graphs4value_refinery)--> |
10 | 10 | ||
11 | ## How to contribute | 11 | Refinery provides consistent graph model generation by partial model _refinement_. |
12 | 12 | ||
13 | ### With Eclipse IDE | 13 | See the [Refinery tutorial](https://github.com/graphs4value/refinery-tutorials/tree/main/filesystem) for more information. |
14 | 14 | ||
15 | 1. Download and install a _Java 17_ compatible JDK. For Windows, prefer OpenJDK builds from [Adoptium](https://adoptium.net/). | 15 | ## [Graph-Solver-as-a-Service](https://refinery.services) |
16 | 16 | ||
17 | 2. Download and extract the [Eclipse IDE for Java and DSL Developers 2022-09](https://www.eclipse.org/downloads/packages/release/2022-09/r/eclipse-ide-java-and-dsl-developers) package. | 17 | Visit [https://refinery.services](https://refinery.services) to try our Graph-Solver-as-a-Service supported by the [2022 Amazon Research Award](https://www.amazon.science/research-awards/recipients/daniel-varro-fall-2021). |
18 | 18 | ||
19 | 3. Launch Eclipse and create a new workspace. | 19 | ## Running locally |
20 | 20 | ||
21 | 4. Open _Help > Install New Software..._ and install the following software from the _2022-09_ update site: | 21 | To generate larger models with a longer timeout, you can use our [Docker container](https://github.com/graphs4value/refinery/pkgs/container/refinery) on either `amd64` or `arm64` machines: |
22 | * _Modeling > Ecore Diagram Editor (SDK)_ | ||
23 | 22 | ||
24 | 5. Open _Help > Eclipse Marketplace_ and install the following software: | 23 | ```sh |
25 | * _EclEmma Java Code Coverage_ | 24 | docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery |
26 | * _SonarLint_ | 25 | ``` |
27 | 26 | ||
28 | 6. Open _Window > Preferences_ and set the following preferences: | 27 | Once Docker pulls and starts the container, you can navigate to [http://localhost:8888](http://localhost:8888) to open the model generation interface and start editing. |
29 | * _General > Workspace > Text file encoding_ should be _UTF-8_. | ||
30 | * _General > Workspace > New text file line delimiter_ should be _Unix_. | ||
31 | * Add the JDK 17 to _Java > Installed JREs_. | ||
32 | * Make sure JDK 17 is selected for _JavaSE-17_ at _Java > Installed JREs > Execution Environments_. | ||
33 | * Set _Gradle > Java home_ to the `JAVA_HOME` directory (the directory which contains the `bin` directory) of JDK 17. Here, Buildship will show a yellow warning sign, which can be safely ignored. | ||
34 | * Set _Java > Compiler > JDK Compliance > Compiler compliance level_ to _17_. | ||
35 | 28 | ||
36 | 7. Clone the project Git repository but do not import it into Eclipse yet. | 29 | Alternatively, you can follow the instructions in [CONTRIBUTING.md](CONTRIBUTING.md) to set up a local development environment and compile and run Refinery from source. |
37 | 30 | ||
38 | 8. Open a new terminal an run `./gradlew prepareEclipse` (`.\gradlew prepareEclipse` on Windows) in the cloned repository. | 31 | ## Related publications |
39 | * This should complete without any compilation errors. | ||
40 | * If you get any errors about the JVM version, check whether the `JAVA_HOME` environment variable is set to the location of JDK. You can query the variable with `echo $JAVA_HOME` on Linux and `echo $Env:JAVA_HOME` in PowerShell on Windows. To set it, use `export JAVA_HOME=/java/path/here` or `$Env:JAVA_HOME="C:\java\path\here"`, respectively. | ||
41 | * If the build fails with a `Host name must not be empty` error, you [might need to remove the empty proxy configuration from your global `gradle.properties` file](https://stackoverflow.com/a/62128323). | ||
42 | 32 | ||
43 | 9. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse. | 33 | ### Partial model specification language |
44 | * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_. | ||
45 | * If you have previously imported the project into Eclipse, this step will likely fail. In that case, you should remove the projects from Eclipse, run `git clean -fxd` in the repository, and start over from step 8. | ||
46 | 34 | ||
47 | ### With IntelliJ IDEA | 35 | * K. Marussy, O. Semeráth, A. Babikian, D. Varró: _A Specification Language for Consistent Model Generation based on Partial Models._ |
36 | J. Object Technol. **19**(3): 3:1-22 (2020) [[doi](https://doi.org/10.5381/jot.2020.19.3.a12)] [[pdf](https://www.jot.fm/issues/issue_2020_03/article12.pdf)] [[video](https://www.youtube.com/watch?v=ggTbv_s5t2A)] | ||
48 | 37 | ||
49 | It is possible to import the project into IntelliJ IDEA, but it gives no editing help for Xtext (`*.xtext`), MWE2 (`*.mwe2`), and Xtend (`*.xtend`) and Ecore class diagrams (`*.aird`, `*.ecore`, `*.genmodel`). | 38 | ### Consitent graph generation techniques |
39 | |||
40 | * O. Semeráth, A. Nagy, D. Varró: “A graph solver for the automated generation of consistent domain-specific models.” _ICSE 2018:_ 969-980 [[doi](https://doi.org/10.1145/3180155.3180186)] [[pdf](https://dl.acm.org/doi/pdf/10.1145/3180155.3180186)] | ||
41 | * K. Marussy, O. Semeráth, D. Varró: _Automated Generation of Consistent Graph Models With Multiplicity Reasoning._ IEEE Trans. Software Eng. **48**(5): 1610-1629 (2022) [[doi](https://doi.org/10.1109/TSE.2020.3025732)] [[pdf](https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=9201551)] | ||
42 | * A.. Babikian, O. Semeráth, A. Li, K. Marussy, D. Varró: _Automated generation of consistent models using qualitative abstractions and exploration strategies._ Softw. Syst. Model. **21**(5): 1763-1787 (2022) [[doi](https://doi.org/10.1007/s10270-021-00918-6)] [[pdf](https://link.springer.com/content/pdf/10.1007/s10270-021-00918-6.pdf?pdf=button)] | ||
43 | |||
44 | ### Diverse and realistic graph generation | ||
45 | |||
46 | * O. Semeráth, R. Farkas, G. Bergmann, D. Varró: _Diversity of graph models and graph generators in mutation testing._ Int. J. Softw. Tools Technol. Transf. **22**(1): 57-78 (2020) [[doi](https://doi.org/10.1007/s10009-019-00530-6)] [[pdf](https://link.springer.com/content/pdf/10.1007/s10009-019-00530-6.pdf?pdf=button)] | ||
47 | * O. Semeráth, A. Babikian, B. Chen, C. Li, K. Marussy, G. Szárnyas, D. Varró: _Automated generation of consistent, diverse and structurally realistic graph models._ Softw. Syst. Model. **20**(5): 1713-1734 (2021) [[doi](https://doi.org/10.1007/s10270-021-00884-z)] [[pdf](https://link.springer.com/content/pdf/10.1007/s10270-021-00884-z.pdf?pdf=button)] | ||
48 | |||
49 | ### Correcness proofs | ||
50 | |||
51 | * D. Varró, O. Semeráth, G. Szárnyas, Á. Horváth: “Towards the Automated Generation of Consistent, Diverse, Scalable and Realistic Graph Models.” _Graph Transformation, Specifications, and Nets 2018:_ 285-312 [[doi](https://doi.org/10.1007/978-3-319-75396-6_16)] [[pdf](https://inf.mit.bme.hu/sites/default/files/publications/fmhe-model-generation.pdf)] | ||
50 | 52 | ||
51 | ## License | 53 | ## License |
52 | 54 | ||