Merge branch 'reiner' into 'main'

Updated used documentation. Fixed some typos.

See merge request !85

README.md

@@ -7,15 +7,31 @@ Project containing all Java-based tools developed in OceanDSL.
 All java tools can be build with
 `./gradlew build`
 
+## Package
+
+Call `./assemble-tools.sh` to produce one tar bundle containing all tools and its
+libraries. This archive uses way less space than the individual tools, as they 
+share many of the libraries.
+
 ## Execute
 
 Each tool has its own set of parameters and can be found in
 `doc/tools/$TOOL_NAME`.
 
 Current tools:
-- rewrite-log-entries
+- allen-upper-limit compute the maximal upper complexity limit for a given architecture
+- cmi check the integrity of a model
 - dar (dynamic architecture reconstruction) read Kieker log data and reconstruct the architecture
-- sar (static architecutre reconstruction) read calls and data access files to reconstruct the architecture
+- delta produce architecture model deltas in different formats based on *restructuring* output
+- fxca process fxtran output and generate CSV files with calls, dataflows and storage info
+- maa model architecture analysis tool
+- mktable generate LaTeX tables representing architecture changes based on results from delta
 - mop (model operation) merge, diff, diff-tag, subtract, subtract-tag models
 - mvis (model visualization) visualize and compute metrics for a given architecture model
-- pp-static-log
+- pp-static-log preprocess log files from static analysis (deprecated)
+- relabel allows to change labels assigned to architecture model elements
+- restructuring compute the necessary steps to change one architecture into a new one
+- rewrite-log-entries preprocess kieker log files from Kieker4C monitoring to resolve function references
+- sar (static architecutre reconstruction) read calls and data access files to reconstruct the architecture
+
+

doc/tools/cmi.rst

@@ -4,5 +4,13 @@ Check Model Integrity
 This is more or less a debugging tool to check whether a model is without
 technical issues.
 
-Usage: cmi <input-path>
+Usage: cmi -i <model path> [-c <checks>]
+
+===== ====================== ======== ======================================================
+Short Long                   Required Description
+===== ====================== ======== ======================================================
+-i    --input                yes      Input architecture model directory
+-c    --checks               no       Checks: type, assembly, deployment, execution, source,
+                                      statistics
+===== ====================== ======== ======================================================
 

doc/tools/delta.rst

+Architecture Delta
+==================
+
+Process restructuring information to compute deltas between architecture
+models and store the result in different output formats
+
+===== ====================== ======== ======================================================
+Short Long                   Required Description
+===== ====================== ======== ======================================================
+-i    --input                yes      input restructure XMI file path
+-o    --output               yes      output restructure information path and filename
+                                      without extension
+      --eol                  no       specify which kind of end of line character should be
+                                      used in CSV files. Default is system's default EOL
+===== ====================== ======== ======================================================
+

doc/tools/fxca.rst

+FXTran Code Analysis
+====================
+
+Fxtran is a Fortran parser which outputs an XML based AST.
+fxca processes this AST and outputs CSV files for calls, dataflows,
+components and data storages.
+
+===== ====================== ======== ======================================================
+Short Long                   Required Description
+===== ====================== ======== ======================================================
+-d    --default-component    no       In case callees are identified that do not have an
+                                      implementation in the code, assign the callee to this
+                                      operation.
+      --eol                  no       End of line symbol, Default is system dependent
+-f    --flat                 no       Scan source directories flat, i.e. not in recusrive
+                                      mode, default is scan recursively
+-i    --input                yes      One or more paths to fxtran-generated XML files.
+-l    --library-functions    no       Map files for built-in and other runtime functions.
+-o    --output               yes      Path where the output files are placed.
+===== ====================== ======== ======================================================
+

doc/tools/maa.rst

@@ -17,7 +17,9 @@ Short Long                   Required Description
 -g    --hierarchy-grouping            Generate a component hierarchy based on a map file
 -c    --operation-calls               Output the list of calls
 -s    --component-statistics          Output numerous component statistics
--gs   --separator                     Sparator string for CSV inputs
+-gs   --separator                     Separator string for CSV inputs
+-E    --experiment-name               Experiment name
+      --eol                           Set the end of line characters, default: system
 ===== ====================== ======== ======================================================
 
 For the option **hierarchy-grouping** you need to specify at least one map file

doc/tools/mktable.rst

+Make Table
+==========
+
+Processes output from the delta tool and generates two LaTeX files
+compact.tex and full.tex which show an aggregated and complete mapping.
+respectively.
+
+===== ====================== ======== ======================================================
+Short Long                   Required Description
+===== ====================== ======== ======================================================
+-i    --input                yes      Input CSV restructure file produced by the delta tool
+-o    --output               yes      Output path for the two LaTeX file
+===== ====================== ======== ======================================================
+

doc/tools/mop.rst

@@ -2,6 +2,9 @@ Model Operation
 ===============
 
 Merges models together from different sources or select a portion of the model.
+In merge mode, the tool tries to infer whether two components from the input
+models are the same based on their similarity in operations. The highest fit
+is considered the corresponding component and merged.
 
 ===== ===================== ======== ======================================================
 Short Long                  Required Description
@@ -10,6 +13,8 @@ Short Long                  Required Description
 -o    --output              yes      Ouput architecture model directory
 -e    --experiment          yes      Experiment name
 -s    --selection-criteria           Element selection criteria file
+-t    --threshold                    Threshold for accepted similarity in component names:
+                                     1 = identical, 0 = nothing identical Default: 0.4
 ===== ===================== ======== ======================================================
 
 Example merge:

doc/tools/mvis.rst

@@ -16,6 +16,8 @@ Short Long                  Required Description
 -m    --mode                         Mode deciding whether an edge is added when its nodes
                                      are not selected add-nodes, only
 -c    --compute-statistics           Generate the listed statistics
+      --eol                          Set end of line character for CSV files
+                                     Default: system's standard symbol                               
 ===== ===================== ======== ======================================================
 
 Selectors

doc/tools/pp-static-log.rst

@@ -18,3 +18,4 @@ Short Long                  Required Description
 -o    --output              yes      Output file for 4 column log
 ===== ===================== ======== ======================================================
 
+(Deprecated)

doc/tools/relabel.rst

@@ -12,6 +12,7 @@ Short Long                  Required Description
 -i    --input               yes      Directory for the input model
 -o    --output              yes      Directory for the modified model
 -r    --replacements        yes      Replacement for labels source:target
+-e    --experiment          no       Set experiment name of the model repository
 ===== ===================== ======== ======================================================
 
 Examples

doc/tools/restructuring.rst

+Restructuring
+=============
+
+Identify a number of operations to transform an architecture model
+into another one. Best strategy to use is kuhn
+
+===== ====================== ======== ======================================================
+Short Long                   Required Description
+===== ====================== ======== ======================================================
+-i    --input                yes      Input architecture model directories
+-o    --output               yes      Output architecture model directory
+      --eol                  no       End of line symbol
+-e    --experiment           no       Experiment name
+-s    --strategy             yes      Strategy identifier
+                                      Possible Values: [NORMAL, EMPTY, RANDOM, KUHN]
+===== ====================== ======== ======================================================

doc/tools/sar.rst

@@ -8,27 +8,22 @@ e.g., common blocks in Fortran.
 ===== ========================== ======== ======================================================
 Short Long                       Required Description
 ===== ========================== ======== ======================================================
--i    --call-input                        Operation call CSV file
--j    --dataflow-input                    Dataflow CSV file
--cs   --call-separation-char              Separation character for operation call CSV files,
-                                          default is comma (,)
--ds   --dataflow-separation-char          Separation character for dataflow CSV files, default
-                                          is comma (,)
--ns   --names-separation-char             Separation character for function name lists CSV 
-                                          files, default is comma (,)
--f    --function-names                    Function file map CSV file
+-i    --input                    yes      Input directory
 -o    --output                   yes      Output directory to store graphics and statistics
--M    --component-maps                    Component, file and function map file
--l    --source-label             yes      Set source label for the read data
--c    --case-insensitive                  Handle function names in CSV case insensitive
+-M    --component-maps                    Component, file and function map files
+-E    --experiment-name                   Name of the experiment
 -H    --hostname                          Hostname to be used in CSV reconstruction
--E    --experiment-name          yes      Name of the experiment
--n    --missing-mappings-file             Output file for the list of files with a missing
-                                          mapping in the mapping file
+-g    --input-mode                        Input mode to be used for static analysis
+                                          Possible Values: [CALL, DATAFLOW, BOTH]
 -a    --missing-functions                 Output file for the list of functions without an
                                           associated file
--m    --module-modes             yes      Module converter strategies (at lease one of):
+-n    --missing-mappings-file             Output file for the list of files with a missing
+                                          mapping in the mapping file. 
+-m    --module-modes                      Module converter strategies (at lease one of):
                                           module-mode, file-mode, map-mode 
+-sc   --separation-character              Separation character for CSV files, default is
+                                          comma (,)
+-l    --source-label                      Set source label for the read data
 ===== ========================== ======== ======================================================
 
 The tool reads a list of operation calls, e.g., in Fortran, one subroutine

tools/delta/src/main/java/org/oceandsl/tools/delta/Settings.java

@@ -34,7 +34,7 @@ public class Settings { // NOPMD data class
     private Path inputPath;
 
     @Parameter(names = { "-o",
-            "--output" }, required = true, converter = PathConverter.class, description = "Output restructure information as CSV table")
+            "--output" }, required = true, converter = PathConverter.class, description = "Output restructure information path and filename without extension")
     private Path outputPath;
 
     @Parameter(names = { "--eol" }, required = false, description = "End of line symbol")