From 94b3639b500fa6844172a599c7d16393dda88c42 Mon Sep 17 00:00:00 2001 From: tobias-dv-lnu Date: Mon, 3 Aug 2020 09:43:06 +0200 Subject: [PATCH 1/6] Update paper.md added the mandatory statement of need heading --- JOSS-paper/paper.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/JOSS-paper/paper.md b/JOSS-paper/paper.md index fb3139a..4514b8d 100644 --- a/JOSS-paper/paper.md +++ b/JOSS-paper/paper.md @@ -30,6 +30,9 @@ Architectural drift and erosion, where the implementation starts to deviate from The ``s4rdm3x`` tool suite is designed for researchers and practitioners to study and evaluate algorithms that perform part of the mapping automatically, such as orphan-adoption clustering [@HuGMe] or information retrieval techniques [@InfoRetrieval]. It includes a graphical user interface to define the architecture, define and run experiments with mapping algorithms and their parameters, and visualize and explore the results of these experiments. The experiments can be executed locally or in a remote high-performance computing environment. The tool suite includes reference implementations of state of the art mapping algorithms and a set of Java systems with validated mappings between classes and architecture elements. The tool suite is extensible, so it is easy to add new mapping algorithms and visualizations to explore their performance. +# Statement of Need +To faciliate the further development and evaluiation of mapping techniques the software provides reference implementations of the current state-of-the-art mapping techniques and the means to implement new techniques and run experiments. It includes the HuGMe orphan adoption clustering method [@HuGMe], and four attraction functions to decide which architectural element a source code module should be mapped to: `CountAttract` [@HuGMe], `IRAttract`, `LSIAttract` [@InfoRetrieval] and `NBAttract` [@NaiveBayes]. There is also a reference implementation of our novel technique to create a textual representation of source code dependencies at an architectural level; Concrete Dependency Abstraction (CDA). It also contains a set of validated mappings between source code classes and architectural elements that are often used in software architecture erosion research. These systems have either been recovered from replication packages [@brunet2012evolutionary; @LenhardExploringSCMIndicatingArchInconsistency] or the [SAEroCon workshop repository](https://github.com/sebastianherold/SAEroConRepo). + # The ``s4rdm3x`` Tool Suite ``S4rdm3x`` is an extensible suite of tools for source code analysis, architecture definition, mapping of source code modules to architecture elements, experiment definitions, and exploratory and visual analysis. The suite consists of an *extensible core* and two tools, a *graphical editor* to create and visualize mapping experiments and a *command-line tool to run experiment* at scale. @@ -42,7 +45,7 @@ The *graphical editor* is used to define, visualize, analyze, and compare how we The graphical editor can be used to run experiments, but these generally require a large number of combinations of, e.g., parameters, initial sets, and systems, so they can take a long time to run. The suite includes a command-line tool that runs these combinations in parallel on many-core machines. The command-line tool can read experiment definitions in XML exported from the graphical editor and save the results in a format that can be imported and visualized. -The tool suite includes reference implementations of the most common mapping algorithms, such as the HuGMe orphan adoption clustering method [@HuGMe], and four attraction functions to decide which architectural element a source code module should be mapped to: `CountAttract` [@HuGMe], `IRAttract`, `LSIAttract` [@InfoRetrieval] and `NBAttract` [@NaiveBayes]. There is also a reference implementation of our novel technique to create a textual representation of source code dependencies at an architectural level; Concrete Dependency Abstraction (CDA). It also contains a set of Java systems with validated mappings between source code classes and architectural elements that are often used in software architecture erosion research. These systems have either been recovered from replication packages [@brunet2012evolutionary; @LenhardExploringSCMIndicatingArchInconsistency] or the [SAEroCon workshop repository](https://github.com/sebastianherold/SAEroConRepo). + ``S4rdm3x`` is implemented in Java and depends on [ASM](https://asm.ow2.io), [Weka](https://www.cs.waikato.ac.nz/ml/weka), and [Dear JVM ImGui](https://github.com/kotlin-graphics/imgui). From ecb659dc43e1ac71b4671bb37fc6aa806fee4de0 Mon Sep 17 00:00:00 2001 From: tobias-dv-lnu Date: Wed, 28 Oct 2020 18:17:22 +0100 Subject: [PATCH 2/6] Update index.md added links to JabRef 3.7 release and ProM 6.9 --- docs/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 686d5a2..399ee30 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,7 +37,12 @@ Check the included readme for further details. ## Data Systems S4rdm3x is distributed with architectural models and source code to implementation mappings for a number of systems (see the data/systems directory). Models and mappings are based on work during the [SAEroCon workshop](https://saerocon.wordpress.com/) and a replication package provided by Joao Brunet et. al. [On the Evolutionary Nature of Architectural Violations](https://code.google.com/archive/p/on-the-nature-dataset/wikis/ReplicabilityOfTheStudy.wiki) -To complement the models and mappings, the actual compiled systems are also needed (i.e. jar files). These are not included in this distribution as this would create a problematic licensing situation. However, the jar file dependencies are documented in the respective model file and should be available by either looking through the links from the sources above, or finding them in the actual official distributions of the systems. +To complement the models and mappings, the actual compiled systems are also needed (i.e. jar files). These are not included in this distribution as this would create a problematic licensing situation. However, the jar file dependencies are documented in the respective model file and should be available by either looking through the links from the sources above, or finding them in the actual official distribution of the systems. + +### Some Official Distributions +* [JabRef-3.7.jar](https://github.com/JabRef/jabref/releases/tag/v3.7) +* [ProM 6.9](http://www.promtools.org/doku.php?id=prom69) + ## How To Use It The release contains a ready to use test experiment as explained in the release README From 3377c05d4364c65d27085f83fc64de64d673054e Mon Sep 17 00:00:00 2001 From: tobias-dv-lnu Date: Wed, 28 Oct 2020 18:25:22 +0100 Subject: [PATCH 3/6] Update paper.md Minor fix. --- JOSS-paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/JOSS-paper/paper.md b/JOSS-paper/paper.md index 4514b8d..3e4d57c 100644 --- a/JOSS-paper/paper.md +++ b/JOSS-paper/paper.md @@ -28,7 +28,7 @@ bibliography: paper.bib Architectural drift and erosion, where the implementation starts to deviate from the intended software architecture or the rules set by it, are common problems in long-lived software systems. This can be avoided by using techniques, such as Reflexion modeling [@murphy1995software], to validate that the implementation conforms to the indented architecture. Unfortunately, such techniques require a mapping from source code modules (e.g., classes) to elements of the architecture, something that is not always available or up to date. This is a known problem when, e.g., companies want to adopt static architecture conformance checking; the effort to manually create or bring this mapping up to date is just too time-consuming and error-prone [@Ali2017ArchitectureRequirements; @InfoRetrieval]. -The ``s4rdm3x`` tool suite is designed for researchers and practitioners to study and evaluate algorithms that perform part of the mapping automatically, such as orphan-adoption clustering [@HuGMe] or information retrieval techniques [@InfoRetrieval]. It includes a graphical user interface to define the architecture, define and run experiments with mapping algorithms and their parameters, and visualize and explore the results of these experiments. The experiments can be executed locally or in a remote high-performance computing environment. The tool suite includes reference implementations of state of the art mapping algorithms and a set of Java systems with validated mappings between classes and architecture elements. The tool suite is extensible, so it is easy to add new mapping algorithms and visualizations to explore their performance. +The ``s4rdm3x`` tool suite is designed for researchers and practitioners to study and evaluate algorithms that perform part of the mapping automatically, such as orphan-adoption clustering [@HuGMe] or information retrieval techniques [@InfoRetrieval]. It includes a graphical user interface to define and run experiments with mapping algorithms and their parameters, and visualize and explore the results of these experiments. The experiments can be executed locally or in a remote high-performance computing environment. The tool suite includes reference implementations of state of the art mapping algorithms and a set of Java systems with validated mappings between classes and architecture elements. The tool suite is extensible, so it is easy to add new mapping algorithms and visualizations to explore their performance. # Statement of Need To faciliate the further development and evaluiation of mapping techniques the software provides reference implementations of the current state-of-the-art mapping techniques and the means to implement new techniques and run experiments. It includes the HuGMe orphan adoption clustering method [@HuGMe], and four attraction functions to decide which architectural element a source code module should be mapped to: `CountAttract` [@HuGMe], `IRAttract`, `LSIAttract` [@InfoRetrieval] and `NBAttract` [@NaiveBayes]. There is also a reference implementation of our novel technique to create a textual representation of source code dependencies at an architectural level; Concrete Dependency Abstraction (CDA). It also contains a set of validated mappings between source code classes and architectural elements that are often used in software architecture erosion research. These systems have either been recovered from replication packages [@brunet2012evolutionary; @LenhardExploringSCMIndicatingArchInconsistency] or the [SAEroCon workshop repository](https://github.com/sebastianherold/SAEroConRepo). From 52ba799351a98bed2635417d0ec21357005396f1 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Thu, 29 Oct 2020 09:00:31 +1300 Subject: [PATCH 4/6] Update README fixing typos --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index da407fc..330a05d 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,16 @@ # s4rdm3x -A tool suite to perform experiments in automatic mapping of source code to modular architecure definitions, also called the orphan adoption problem. It consists of a reusable base code (core) and two tools (v3xt & CMDExRunner). +A tool suite to perform experiments in automatic mapping of source code to modular architecture definitions, also called the orphan adoption problem. It consists of a reusable base code (core) and two tools (v3xt & CMDExRunner). ## core The base code provides Java bytecode analysis to extract a dependency graph (and naming information) as well as loading an architectural definition and source to module mapping. Furthermore it implements the HuGMe method and four attraction functions to map a source code file to an architectural module. The attraction functions are CountAttract, IRAttract, LSIAttract and NBAttract. ## v3xt -A tool that provides a GUI to define and run small scale experiments as well as visualize the results in real-time. This can be used to quickly try and asses new ideas and define larger experiments. Supports loading and saving of experiments definitions as experiments. +A tool that provides a GUI to define and run small scale experiments as well as visualize the results in real-time. This can be used to quickly try and assess new ideas and define larger experiments. Supports loading and saving of experiments definitions as experiments. ## CMDExRunner -A command line tool for executing experiments in parrallell. It reads an experiment definition xml-file and distributes the experiments over a number of threads. Typically useful for running experiments in multicore computing clouds. +A command line tool for executing experiments in parallel. It reads an experiment definition xml-file and distributes the experiments over a number of threads. Typically useful for running experiments in multicore computing clouds. # Documentation Documentation is available in [docs](docs) and published: https://tobias-dv-lnu.github.io/s4rdm3x/ @@ -33,7 +33,7 @@ Released under GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 https://www.gnu.org/licenses/gpl-3.0.html -See LICENCE for furher details +See LICENCE for further details From 5c5173909e7fdb4b92da4321bac3b1766d2b4bd9 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Mon, 2 Nov 2020 19:44:56 +1300 Subject: [PATCH 5/6] Add gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e0d44a0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.gradle +build + From e70835df7df005df1f5793ca55d0921355aa0c78 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Mon, 2 Nov 2020 19:49:28 +1300 Subject: [PATCH 6/6] Add prerequisites for installation --- docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.md b/docs/index.md index 399ee30..a79a854 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,6 +21,10 @@ A command line tool for executing experiments in parrallell. It reads an experim # Installation Download the latest [Release](https://github.com/tobias-dv-lnu/s4rdm3x/releases) from GitHub, it includes precompiled versions of the tools as jar applications for all plattforms. +# Prerequisites + +- Java 11 or superior + # Running Run via commandline: