tutorial.md

@@ -8,7 +8,7 @@ The purpose of this document is to provide guidelines on how the SDK4ED Dashboar
 
 Before connecting to the SDK4ED Dashboard, the user should prepare their software project that they would like to analyse appropriately, in order to be in the right form required by the SDK4ED Platform. In brief, the SDK4ED Platform imposes the following limitations:
 
-1. The selected software project should be written in Java, C, or C++ programming language.The analysis of software projects that are written in mixed languages (e.g., Java and C/C++) is not supported.
+1. The selected software project should be written in Java, C, or C++ programming language. Currently, the platform does not support other programming languages. The analysis of software projects that are written in mixed languages (e.g., Java and C/C++) is not supported either. 
 2. The selected software project should be available on an online Git repository, such as GitHub, Gitlab, Bitbucket, etc. 
 3. The source code that should be analysed must be part of the master branch of the Git repository
 
@@ -18,20 +18,57 @@ For the purposes of the present tutorial, we created a software project named *r
 
 https://github.com/siavvasm/rodinia-project
 
-[2]: https://ieeexplore.ieee.org/document/5306797
+[footnote]: https://ieeexplore.ieee.org/document/5306797
 
 ![github_repo](uploads/089274e548e317264693861bbbf50b47/github_repo.png)
 
+#### *Toolbox-specific Limitations and Prerequisites*
+
+Some toolboxes of the SDK4ED Platform impose some additional limitations and prerequisites in order for a software project to be analysed with their features (i.e., services). These limitations are listed below:
+
+ - Dependability Toolbox: 
+    - <ins>C/C++ Projects:</ins> No prerequisites or limitations
+    - <ins>Java Projects:</ins> The binary (i.e., compiled) files of the source code of the software project should be also uploaded on the Git repository. The user should upload either the .class files that are produced after the compilation of the software project, or the final JAR (or WAR) file of the software project.  
+ - TD Toolbox:
+    - <ins>C/C++ Projects:</ins> No prerequisites or limitations
+    - <ins>Java Projects:</ins> 
+       - The user must create a folder named "jars" and inside this folder, he/she should place the jar file of the code. 
+       - TD Analysis toolbox, analyses versions not commits. So for each commit that is version, you should include the jar file. 
+       - In addition, the name of the jar file should be the same as the Git project's name followed by the number of version e.g. projectName0.jar for the project with title "projectName" and version 0 (the first version),  projectName1.jar for the version 1 (the second version) and so on. The projectName is the Git repo name (without “/” and “.git” for example for project
+ - Energy Toolbox: 
+    - A config.txt file must be added in the root directory with the following format (all the paths starting from the root directory of the repo):
 ```
-Toolbox-specific Limitations and Prerequisites: Some toolboxes of the SDK4ED Platform
-impose some additional limitations and prerequisites in order for a software
-project to be analysed with their features (i.e., services). These limitations
-are listed below:
+  [app1]
+  dir = app1_directory
+  exec = exec_command_for_app1
+  source = path/to/source/file1, path/to/source/file2
+  include_dirs = path/to/lib1, path/to/lib2
+  build = app1_compiling_building_commands
+  language = C/C++
+
+  [app2]
+  dir = app2_directory
+  exec = exec_command_for_app2
+  source = path/to/source/file1, path/to/source/file2
+  include_dirs = path/to/lib1, path/to/lib2
+  build = app2_compiling_building_commands
+  language = Java
 ```
+ 1. *dir* is the name root directory of the project
+ 2. *exec* corresponds to the command that executes the application. It is worth mentioning that for performing dynamic analysis, the Energy Toolbox needs to execute the application. Furthermore, when the user wants to analyse a project dynamically in order to have more accurate results, care must be taken that the application is terminated and not run indefinitely.
+ 3. *source* is the path to the source files that the user wants to analyse separated by commas.
+ 4. *include_dirs* is optional and contains the paths to directories that have to be included in order to compile the source files separately (needed for static analysis)
+ 5. *build* includes the compiling and building commands.
+ 6. *Finally*, language is “Java” or “C/C++” for specifying the project’s programming language.
+    - <ins>C/C++ Projects:</ins> For C/C++ the building commands (either gcc commands or make) have to use gcc compiler with the -g debugging flag. All the paths to directories needed have also to be included using the -I flag. The static analysis can provide results without executing the project but the dynamic part (Hotspots identification, indicators monitoring, Acceleration estimation, optimizations suggestion) needs the project to be executed.
+    - <ins>Java Projects:</ins> Single jar executables have to be provided in exec parameter. The dynamic analysis requires the execution of the project.
+ - Forecasting Toolbox:
+    - This Toolbox receives as input a set of metrics generated during the TD, Energy and Dependability analysis. Therefore, a sufficient number of commits should be analysed by the aforementioned Toolboxes in order for the Forecasting Toolbox to generate predictions.
+
+> **Attention:** It should be noted that the SDK4ED Platform allows the user to choose which features of the provided toolboxes should be used for their analysis. If the user wishes to analyse a software project with specific toolboxes, only the >prerequisites for the selected toolboxes should be satisfied.
 
 ### Step 2: Connection to the SDK4ED Dashboard and Project Creation
 
-
 After preparing the software project and uploading it on an online Git repository, the user should navigate to the SDK4ED Dashboard, which is located at the following URL:
 
 http://160.40.52.130:3000/
@@ -48,5 +85,96 @@ The user needs to create a new project in order to define the characteristics of
 
 ![create_new_project](uploads/0333b21e23aff4e23c27cf33127b1df7/create_new_project.png)
 
+A pop-up window will be displayed to their screen, allowing them to define the details of the selected project (see Figure below). As can be seen by Figure 5, the user should define:
+-	The accessibility of their project within the SDK4ED Platform (i.e., Public or Private)
+-	The name of the project, which should be identical to the Git project name
+-	The Git URL of the online repository (i.e., Git URL)
+-	The username and password of the remote Git Repository (the password is required only in case that the selected project is private)
+-	Some toolbox-specific and common parameters that are necessary for the execution of the toolboxes
+
+![create_new_project_on_Dashboard](uploads/6bdde4420570610385b7c3f2688b7733/create_new_project_on_Dashboard.png)
+
+As can be seen by the above Figure, in the *“Project Name”*, *“Git URL”*, and *“Git Username”* fields, the user needs to provide the name of the project that should be used inside the SDK4ED Platform (i.e., *rodinia-project*), the GitHub URL to which the project is located, and the username of the remote Git repository respectively. It should be noted that since the *rodinia-project* is an open source repository, there is no need to provide the password (Only in case that you wish to analyse an open source-project with the *TD Analysis* service, you should not leave the *“Git Password”* text field empty. Please add an arbitrary character or number (e.g., 1) in the text field.). 
+
+Apart from these fields, some additional parameters should be defined in order for the analysis to run. More specifically, the user should define the programming language in which the selected project is written. As can be seen in Figure above, this is done by updating the *“Extra info (common for all the toolboxes)”* text field. If the selected software project is written in C/C++ programming language the following entry should be provided:
+-	{“language”:”cpp”}
+In case that the selected software project is written in Java, the following entry should be provided:
+-	{“language”:”java”}
+
+Since the *rodinia-project* is written in C/C++ the first entry is provided in the *“Extra info (common for all the toolboxes)”* text field, as can be seen in Figure above. 
+
+In addition to this, some toolbox-specific parameters should be also provided, in order for the project to be able to be analysed with specific toolboxes of the SDK4ED Platform. These parameters are defined in the *“Extra Info by Toolbox”* text field of the pop-up window (see Figure above) in JSON format. More specifically, the user needs to select from the dropdown list the specific SDK4ED Toolboxes for which they would like to provide specific parameters, and then they should provide these parameters in the *“Extra Info by Toolbox”* text field.  In the table below, we present the toolbox-specific parameters that need to be defined for analysing the *rodinia-project*, along with a brief description of these parameters. **A more detailed description of these parameters can be found in the deliverable *“D8.2 – Training material and User Manual”* [1] .**
+
+table1
+
+>**Attention:**  It should be noted that the SDK4ED Platform allows the user to select which specific features (i.e., services) of the SDK4ED Platform should be executed for analysing their software project. Hence, the user does not need to provide parameters for those toolboxes that they do not wish to use for 
+>the purposes of their analysis.  
+
+After defining the project details and the required parameters as described above, the user should click on the *“Save Changes”* button in order to create the project. After clicking on this button, a new entry is created on the Projects page (see Figure below) that corresponds to the newly created project (i.e., the *rodinia-project*). The user can edit the details of this project at any time, by clicking on the *“Edit”* button, or they can remove this project by clicking on the *“Delete”* button. 
+
+![projects_page](uploads/e126d9e8a13d2e0fe9272fe151d16114/projects_page.png)
+
+### Step 3: Execution of the analysis
+
+In the previous step, we described the process for creating a new project in the *Projects* page of the SDK4ED Dashboard, using the *rodinia-project* as an example. In order to analyse the newly created project with the SDK4ED Platform, the user needs to select the *rodinia-project* by clicking on it, and then to click on the *“Run Central Analysis”* button. It should be noted that the user, by clicking on the arrow that is next to the *“Run Central Analysis”* button, can choose which features (i.e., services of the SDK4ED Toolboxes) should be executed for the selected software project (see Figure below).
+
+![Analysis_for_rodinia](uploads/6b32a337874d08542ef6648603d87e46/Analysis_for_rodinia.png) 
+
+After clicking on the *“Run Central Analysis”* button, the analysis is triggered. Next to this button, the system shows the current status of the analysis for each one of the services of the SDK4ED Platform grouped per toolbox (see Figure below). The following status flags are displayed next to the name of each toolbox:
+
+-	**pending**: the analysis has not started yet (the corresponding service has not been invoked)
+-	**running**: the analysis is not finished yet (the corresponding service is still running)
+-	**finished**: the analysis has been successfully completed for the selected service
+-	**failed**: the analysis for the selected service has failed
+
+![during_execution](uploads/ecee4f092ac5dc6ea96ec2cf071f6b4f/during_execution.png)
+
+### Step 4: Inspection of the produced results
+
+Whenever the analysis is marked as *finished* for a specific service, the user can navigate to the corresponding web page, in order to inspect the produced results. For instance, when the TD New Code service is finished, the user should click on the *“Technical Debt”* menu item on the dashboard’s menu, and then on the *TD Analysis* option from the displayed dropdown list (see Figure below). 
+
+![Navigation_to_the_td](uploads/537d69e66cfbdf6cbf958b2531007528/Navigation_to_the_td.png)
+
+This will redirect the user to the TD New Code panel, where they can inspect the results of the TD New Code service of the selected project (i.e., the *rodinia-project*). More specifically, on this panel the user is presented with (i) the evolution of the TD Density of the *rodinia-project*, (ii) information about TD liabilities that have been added to the project the previous month, and (iii) information about the Quality Gate of the project (see Figure below).
+
+![td_new_code_panel](uploads/59f0e8bc2b082be38d736c8a446d0c09/td_new_code_panel.png)
+
+Similarly, the user can navigate to other pages in order to inspect the produced results. In the table below we summarize what information is presented in each panel of the SDK4ED Dashboard after the completion of the analysis. This information can be used by the reader as a reference point in order to pinpoint specific information that he/she would like to retrieve. **A detailed description of the information that is provided in each panel is provided in deliverable *“D8.2 – Training material and User Manual”* [1].**
+
+table 2
+
+## *Conclusions*
+
+The purpose of this document was to demonstrate through an example how the SDK4ED Dashboard can be used for analysing a specific software project. For this purpose, an open source software project was used as the basis of the tutorial. Details about the information that is provided by each toolbox have also been provided. However, for a more in-depth description of the different toolboxes that the SDK4ED Platform provides (i.e., theoretical background, internal technical details, etc.), we refer the reader to the public deliverables of the SDK4ED Project [1], [2], [11]–[15], [3]–[10]. 
+
+
+## *References*
+
+1. SDK4ED, “D8.2 - Training material and User Manual (first draft),” *Deliverable*.
+2. SDK4ED, “D3.1 - Most suitable indicators of technical debt,” *Deliverable*.
+3. SDK4ED, “D3.2 - Suitable monitor indicators for energy consumption,” *Deliverable*.
+4. SDK4ED, “D3.3 - Suitable Monitor Indicators for Software Dependability,” *Deliverable*.
+5. SDK4ED, “D3.4 - Forecasting methods for TD/Energy/ Dependability,” *Deliverable*.
+6. SDK4ED, “D4.1 - Strategies for prioritizing and repaying TD in embedded systems,” *Deliverable*.
+7. SDK4ED, “D4.2 - Energy optimization for embedded/ heterogeneous systems,” *Deliverable*.
+8. SDK4ED, “D4.3 - Dependability Optimisation for embedded/heterogeneous systems,” *Deliverable*.
+9. SDK4ED, “D4.5 - Design space exploration of the optimizations,” Deliverable.
+10. SDK4ED, “D4.4 - Costs and Financial Benefits from quality optimization,” *Deliverable*.
+11. SDK4ED, “D5.5 - TD Management Toolbox (FINAL version),” Deliverable.
+12. SDK4ED, “D5.6 - Energy optimizations toolbox (final version),” Deliverable.
+13. SDK4ED, “D5.7 - Toolbox for Dependability Optimization (final version),” *Deliverable*.
+14. SDK4ED, “D5.8 - Forecasting Toolbox (final version),” Deliverable.
+15. SDK4ED, “D6.4 - Decision-Support Tools(final version),” Deliverable.
+
+
+
+ 
+
+
+
+ 
+
+
+