# VaRA Tool Suite
## Project Status [](https://codecov.io/gh/se-sic/VaRA-Tool-Suite) [](https://vara.readthedocs.io/en/vara-dev/?badge=vara-dev)
| branch | build status |
| :---- | :---: |
| vara |  |
| vara-dev |  |
## Using VaRA with VaRA-TS
VaRA is a variability-aware framework to analyze interactions between code regions that convey a semantic meaning for the researcher, e.g., `CommitRegions` represent blocks of code that belongs to the same commit.
Our tool suite allows the researcher to automatically run analyses provided by VaRA on different software projects.
For this, we provides different preconfigured experiments and projects.
Experiments abstract the actions that should be taken when analyzing a project, e.g., build, analyze, generate result graph.
Projects describe how a software project should be configured and build, e.g., `gzip` provides all necessary information to checkout, configure, and compile the project.
## Setup Tool Suite
### Install dependencies
To use the VaRA Tool Suite, make sure you have the necessary packages installed.
For ubuntu, you can use the following command to install them (your system has to
have at least `python3.6`):
```bash
sudo apt install python3-dev python3-tk python3-psutil psutils ninja-build python3-pip autoconf cmake ruby curl time libyaml-dev git
sudo apt install python3-venv # If you want to install VaRA-TS in a python virtualenv
```
### Installation from PyPI
```bash
pip3 install varats
```
### Installation from source
Additional packages are required to build VaRA from source.
```bash
sudo apt install libsqlite3-dev libcurl4-openssl-dev libboost-all-dev libpapi-dev googletest libxml2-dev
```
The easiest way to install VaRA is to use the `vara-buildsetup` tool. You can find more information
about this tool in its [documentation](https://vara.readthedocs.io/en/vara-dev/vara-ts/vara-buildsetup.html).
## Running experiments and analyzing projects
VaRA-TS provides different preconfigured experiments and projects.
In order to execute an experiment on a project we use BenchBuild, an empirical-research toolkit.
### Setup: Configuring BenchBuild
First, we need to generate a folder with a configuration file for BenchBuild in the vara root directory, this is done with:
```console
vara-gen-bbconfig
```
### Running BenchBuild experiments
Second, we change into the benchbuild folder and run an experiment that generates `CommitReports` for provided projects, in this case we use `gzip`.
```console
cd $VARA_ROOT/benchbuild
benchbuild -vv run -E GenerateCommitReport gzip
```
The generated result files are place in the `vara/results/$PROJECT_NAME` folder and can be further visualized with VaRA-TS graph generators.
### Using CaseStudy and paper configs
Reproducing results for different projects and experiments is important. To help with reproducing results, VaRA-TS proposes the concept of a `CaseStudy` and paper configs. Each case study specifies which revision of a project needs to be analyzed. Paper configs then group together a set of case studies that belong to the same paper, allowing the user to precisly specify which revisions of what project need to be analyzed to regenerate the results for a specific paper.
For more information visit our [documentation](https://vara.readthedocs.io/en/vara-dev/vara-ts-api/paper.html#paper-and-case-study-handling).
## VaRA developer tools
VaRA-TS provides different tools to ease VaRA development.
### vara-develop
`vara-develop`, short `vd`, is a helper to interact with the different VaRA project repositories when working on VaRA.
The tool provides commands for showing `git status`, creating `new-branch` or `checkout` existing branches.
Furthermore, commands to `pull`/`push` the current branches and to show currently developed feature branches `f-branches`.
It can be used on a set of projects simultaneously.
A command like:
```console
> vd new-branch f-FooBar vara clang llvm
```
will create the branch `f-FooBar` on all three repositories.
Showing the current status of the listed projects can be done with:
```console
> vd status clang vara
################################################################################
# Project: clang #
################################################################################
On branch vara-80-dev
Your branch is up to date with 'origin/vara-80-dev'.
nothing to commit, working tree clean
################################################################################
# Project: VaRA #
################################################################################
On branch f-InstrumentationVerifier
Your branch is up to date with 'origin/f-InstrumentationVerifier'.
nothing to commit, working tree clean
```
The `checkout` tool helps you to checkout the same branch on different projects, if one exists.
Furthermore, it can easily switch all projects to `vara-dev` or `vara` by just typing:
```console
vd checkout vara-dev
```
To get a full overview of the tool use `vd -h` and `vd {sub_command} -h`.
## Extending the tool suite
VaRA-TS allows the user to extend it with different projects, experiments, and data representations.
### BenchBuild Projects
`VaRA-TS` defines a set of projects that can be analyzed with `benchbuild`.
```console
benchbuild
└── projects
```
### BenchBuild Experiments
`VaRA-TS` defines a set of projects that can be analyzed with `benchbuild`.
```console
benchbuild
└── experiments
```
### Running tests
Running all python tests:
```bash
python setup.py test
```
Running all test with coverage:
```bash
python setup.py test --addopts "--cov=varats --cov-report term-missing"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/se-sic/vara-tool-suite",
"name": "varats",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Florian Sattler",
"author_email": "sattlerf@cs.uni-saarland.de",
"download_url": null,
"platform": null,
"description": "# VaRA Tool Suite\n\n## Project Status [](https://codecov.io/gh/se-sic/VaRA-Tool-Suite) [](https://vara.readthedocs.io/en/vara-dev/?badge=vara-dev)\n\n| branch | build status |\n| :---- | :---: |\n| vara |  |\n| vara-dev |  |\n\n## Using VaRA with VaRA-TS\nVaRA is a variability-aware framework to analyze interactions between code regions that convey a semantic meaning for the researcher, e.g., `CommitRegions` represent blocks of code that belongs to the same commit.\nOur tool suite allows the researcher to automatically run analyses provided by VaRA on different software projects.\nFor this, we provides different preconfigured experiments and projects.\nExperiments abstract the actions that should be taken when analyzing a project, e.g., build, analyze, generate result graph.\nProjects describe how a software project should be configured and build, e.g., `gzip` provides all necessary information to checkout, configure, and compile the project.\n\n## Setup Tool Suite\n\n### Install dependencies\nTo use the VaRA Tool Suite, make sure you have the necessary packages installed.\nFor ubuntu, you can use the following command to install them (your system has to\nhave at least `python3.6`):\n\n```bash\nsudo apt install python3-dev python3-tk python3-psutil psutils ninja-build python3-pip autoconf cmake ruby curl time libyaml-dev git\nsudo apt install python3-venv # If you want to install VaRA-TS in a python virtualenv\n```\n\n### Installation from PyPI\n\n```bash\npip3 install varats\n```\n\n### Installation from source\n\nAdditional packages are required to build VaRA from source.\n```bash\nsudo apt install libsqlite3-dev libcurl4-openssl-dev libboost-all-dev libpapi-dev googletest libxml2-dev\n```\n\nThe easiest way to install VaRA is to use the `vara-buildsetup` tool. You can find more information\nabout this tool in its [documentation](https://vara.readthedocs.io/en/vara-dev/vara-ts/vara-buildsetup.html).\n\n## Running experiments and analyzing projects\nVaRA-TS provides different preconfigured experiments and projects.\nIn order to execute an experiment on a project we use BenchBuild, an empirical-research toolkit.\n\n### Setup: Configuring BenchBuild\nFirst, we need to generate a folder with a configuration file for BenchBuild in the vara root directory, this is done with:\n```console\nvara-gen-bbconfig\n```\n\n### Running BenchBuild experiments\nSecond, we change into the benchbuild folder and run an experiment that generates `CommitReports` for provided projects, in this case we use `gzip`.\n```console\ncd $VARA_ROOT/benchbuild\nbenchbuild -vv run -E GenerateCommitReport gzip\n```\nThe generated result files are place in the `vara/results/$PROJECT_NAME` folder and can be further visualized with VaRA-TS graph generators.\n\n### Using CaseStudy and paper configs\nReproducing results for different projects and experiments is important. To help with reproducing results, VaRA-TS proposes the concept of a `CaseStudy` and paper configs. Each case study specifies which revision of a project needs to be analyzed. Paper configs then group together a set of case studies that belong to the same paper, allowing the user to precisly specify which revisions of what project need to be analyzed to regenerate the results for a specific paper.\nFor more information visit our [documentation](https://vara.readthedocs.io/en/vara-dev/vara-ts-api/paper.html#paper-and-case-study-handling).\n\n## VaRA developer tools\nVaRA-TS provides different tools to ease VaRA development.\n\n### vara-develop\n`vara-develop`, short `vd`, is a helper to interact with the different VaRA project repositories when working on VaRA.\nThe tool provides commands for showing `git status`, creating `new-branch` or `checkout` existing branches.\nFurthermore, commands to `pull`/`push` the current branches and to show currently developed feature branches `f-branches`.\nIt can be used on a set of projects simultaneously.\nA command like:\n```console\n> vd new-branch f-FooBar vara clang llvm\n```\nwill create the branch `f-FooBar` on all three repositories.\n\nShowing the current status of the listed projects can be done with:\n```console\n> vd status clang vara\n################################################################################\n# Project: clang #\n################################################################################\nOn branch vara-80-dev\nYour branch is up to date with 'origin/vara-80-dev'.\n\nnothing to commit, working tree clean\n\n################################################################################\n# Project: VaRA #\n################################################################################\nOn branch f-InstrumentationVerifier\nYour branch is up to date with 'origin/f-InstrumentationVerifier'.\n\nnothing to commit, working tree clean\n```\n\nThe `checkout` tool helps you to checkout the same branch on different projects, if one exists.\nFurthermore, it can easily switch all projects to `vara-dev` or `vara` by just typing:\n```console\nvd checkout vara-dev\n```\n\nTo get a full overview of the tool use `vd -h` and `vd {sub_command} -h`.\n\n## Extending the tool suite\nVaRA-TS allows the user to extend it with different projects, experiments, and data representations.\n\n### BenchBuild Projects\n`VaRA-TS` defines a set of projects that can be analyzed with `benchbuild`.\n```console\n benchbuild\n \u2514\u2500\u2500 projects\n```\n\n### BenchBuild Experiments\n`VaRA-TS` defines a set of projects that can be analyzed with `benchbuild`.\n```console\n benchbuild\n \u2514\u2500\u2500 experiments\n```\n\n### Running tests\nRunning all python tests:\n```bash\n python setup.py test\n```\nRunning all test with coverage:\n```bash\n \u00a0 \u00a0python setup.py test --addopts \"--cov=varats --cov-report term-missing\"\n```\n",
"bugtrack_url": null,
"license": "BSD 2-Clause",
"summary": null,
"version": "13.0.5",
"project_urls": {
"Homepage": "https://github.com/se-sic/vara-tool-suite"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d64d34e171a57761c481ba49045d03498d9d2054e5cd408a2dbc7cb70a5ae96",
"md5": "882579b17a41f4cd3d56c80e285f04f1",
"sha256": "fd2ae160f99e41755d5286faf9a42ee3ca0a002cc5d488696e1aa8d925fa7da1"
},
"downloads": -1,
"filename": "varats-13.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "882579b17a41f4cd3d56c80e285f04f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 465372,
"upload_time": "2024-10-20T10:46:24",
"upload_time_iso_8601": "2024-10-20T10:46:24.166077Z",
"url": "https://files.pythonhosted.org/packages/0d/64/d34e171a57761c481ba49045d03498d9d2054e5cd408a2dbc7cb70a5ae96/varats-13.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 10:46:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "se-sic",
"github_project": "vara-tool-suite",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "benchbuild",
"specs": [
[
">=",
"6.8"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.3"
]
]
},
{
"name": "cliffs-delta",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "distro",
"specs": [
[
">=",
"1.5.0"
]
]
},
{
"name": "graphviz",
"specs": [
[
">=",
"0.14.2"
]
]
},
{
"name": "ijson",
"specs": [
[
">=",
"3.1.4"
]
]
},
{
"name": "Jinja2",
"specs": [
[
">=",
"3.1.2"
]
]
},
{
"name": "jupyter",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "kaleido",
"specs": [
[
">=",
"0.2.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8.2"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"3.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.2"
]
]
},
{
"name": "packaging",
"specs": [
[
">=",
"20.1"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.5.3"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.13.1"
]
]
},
{
"name": "plumbum",
"specs": [
[
">=",
"1.6"
]
]
},
{
"name": "pre-commit",
"specs": [
[
">=",
"3.2.0"
]
]
},
{
"name": "PyDriller",
"specs": [
[
">=",
"2.4.1"
]
]
},
{
"name": "pygit2",
"specs": [
[
">=",
"1.10"
]
]
},
{
"name": "PyGithub",
"specs": [
[
">=",
"1.58"
]
]
},
{
"name": "pygraphviz",
"specs": [
[
">=",
"1.7"
]
]
},
{
"name": "pygtrie",
"specs": [
[
">=",
"2.3"
]
]
},
{
"name": "pylatex",
"specs": [
[
">=",
"1.4.1"
]
]
},
{
"name": "PyQt5",
"specs": [
[
"<",
"5.16.0"
],
[
">=",
"5.10.0"
]
]
},
{
"name": "PyQt5-stubs",
"specs": [
[
"<",
"5.16.0"
],
[
">=",
"5.10.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.2.2"
]
]
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.28.2"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"12.6"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.2.2"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.13.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9"
]
]
},
{
"name": "types-PyYAML",
"specs": []
},
{
"name": "types-requests",
"specs": []
},
{
"name": "types-tabulate",
"specs": []
},
{
"name": "virtualenv",
"specs": [
[
">=",
"20.0.8"
]
]
},
{
"name": "wllvm",
"specs": [
[
">=",
"1.3.1"
]
]
}
],
"tox": true,
"lcname": "varats"
}
JSON
