|
|
|
In this wiki page we describe how the Energy Toolbox can be used as an individual Microservice. More specifically, we describe how the four services that it provides (i.e., Hotspot identification, Static Analysis Energy Estimation, Propose energy Optimizations, Github Project History Analysis) can be invoked, whereas intuitive examples are also provided, in an attempt to facilitate understanding.
|
|
|
|
|
|
|
|
- Make a private repository for each project to be analyzed.
|
|
|
|
- Get a private access token from the hosting platform.
|
|
|
|
- In the project repo, add a config.txt file with the following format (all the paths starting from the mounted directory):
|
|
|
|
In order to analyse a new project, the steps presented below must be followed:
|
|
|
|
- A github repository for the project that the user wants to analyse.
|
|
|
|
- A private access token from the hosting platform (password authentication is also supported) or nothing if the project is open-source.
|
|
|
|
- In the project repo, 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):
|
|
|
|
|
|
|
|
```
|
|
|
|
[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++
|
|
|
|
|
| ... | ... | @@ -15,6 +18,7 @@ In this wiki page we describe how the Energy Toolbox can be used as an individua |
|
|
|
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
|
|
|
|
```
|
| ... | ... | @@ -22,18 +26,9 @@ In this wiki page we describe how the Energy Toolbox can be used as an individua |
|
|
|
* _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.
|
|
|
|
* _source_ is the path to the source files that the user wants to analyse separated by commas.
|
|
|
|
* _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)
|
|
|
|
* _build_ includes the compiling and building commands. 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.
|
|
|
|
* _build_ includes the compiling and building commands. 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.
|
|
|
|
* Finally, _language_ is “Java” or “C/C++” for specifying the project’s programming language.
|
|
|
|
|
|
|
|
|
|
|
|
- Create database docker container
|
|
|
|
```
|
|
|
|
docker run -d -p 27017-27019:27017-27019 --name energy_toolbox_db mongo:latest
|
|
|
|
```
|
|
|
|
- Create the docker container. Replace in the following command the **SRC** with the **full path** to the directory that includes the applications that will be used to the SDK4ED_energy_toolkit. Also replace **DATA** with the **full path** to the directory on the server where analysis results will be saved.
|
|
|
|
```
|
|
|
|
docker run -t --rm -p 0.0.0.0:3002:5000 --name sdk4ed --link energy_toolbox_db:mongo --privileged --interactive --tty -e DISPLAY=:0 sdk4ed_energy_image
|
|
|
|
```
|
|
|
|
- Invoke the ```analysis``` API from localhost. All requests are made on the localhost/analysis endpoint, accompanied by a series of parameters that define the tool's expected behavior. These
|
|
|
|
parameters are:
|
|
|
|
- ```new```: whether to run a new analysis, or return (if any) existing results.
|
| ... | ... | @@ -43,11 +38,9 @@ parameters are: |
|
|
|
- ```token```:private access token in the case of private repo (not needed for public case).
|
|
|
|
- ```commit```:if the user wants to analyse only a specific commit.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The Energy Toolbox API includes both the Consumption Analysis API and the Energy Optimization API. A call to this API tests the whole functionality of the Energy Toolbox. The URL given below represents the call to the Energy Toolbox API including the requested information.
|
|
|
|
```
|
|
|
|
http://<local_ip>:3002/analysis?new=T&user=<github-user>&token=<github-token>&url=<github-url>&commit=<github_commit>&type=<analysis-type>
|
|
|
|
http://<energy_toollbox_endpoint>:3002/analysis?new=T&user=<github-user>&token=<github-token>&url=<github-url>&commit=<github_commit>&type=<analysis-type>&speciter=<loop_id>-<iterations>
|
|
|
|
```
|
|
|
|
|
|
|
|
| Parameter | Description | Type | Notes |
|
| ... | ... | @@ -55,8 +48,9 @@ http://<local_ip>:3002/analysis?new=T&user=<github-user>&token=<github-token>&ur |
|
|
|
| url | The URL of the repository to be analyzed | String | - |
|
|
|
|
| user | The user name of the repository owner | string | - |
|
|
|
|
| token | Private access token in the case of private repo | string | Example: GitHub private access token |
|
|
|
|
| type | whether to run a full, hotspots-only, static-only, acceleration or history analysis. Supported values: ['full', 'hotspots', 'static', 'acceleration', 'history'] | string | This parameter implements the selection between the toolbox components as well as their individual functionalities |
|
|
|
|
| new | whether to run a new analysis, or return existing results (if any)| bool | From our tests, a bool parameter is considered True if and only if it is non-emtpy.
|
|
|
|
| type | whether to run a full, hotspots-only, static-only, acceleration or history analysis. Supported values: ['full', 'hotspots', 'static', 'acceleration', 'history','hotstatic','android'] | string | This parameter implements the selection between the toolbox components as well as their individual functionalities |
|
|
|
|
| new | whether to run a new analysis, or return existing results (if any)| bool | From our tests, a bool parameter is considered True if and only if it is non-emtpy. |
|
|
|
|
| speciter | Optional: Special case of static analysis call only when the user asks for an additional calculation with specific number of iterations in a loop | int-int | Two integer number separated with a “-“. The first one corresponds to the loop id and the second to the number of iterations in this loop.
|
|
|
|
|
|
|
|
After the successful execution of the analysis, a JSON report with the results is produced and sent as a response to the user. See an example of the full analysis response below:
|
|
|
|
|
| ... | ... | |
