Provided research tools

List of provided research tools:

Research Tool API

VaRA-TS offers an abstraction to implement research tools that makes it easy to add a new tool and automatically deploy it, and it’s experiments, via the tool suite. To add a new research tool one has to implement two classes. The research tool it self must inherit from ResearchTool and implement the specified abstract methods to setup, upgrade, build, and install the research tool. In addition, one needs to implement a CodeBase to specify the repository layout of the research tools code. The CodeBase makes it convenient to interact with the repository (or repositories) of a research tool to setup and manage the code. Furthmore, the tool suite provides different helper functions and services that depend on the CodeBase abstraction, e.g., vara-develop.

This modules provides the base classes for research tools that allow developers to setup and configure their own research tool by inheriting and implementing the base classes ResearchTool and CodeBase.

class varats.tools.research_tools.research_tool.SubProject(parent_code_base, name, URL, remote, sub_path, auto_clone=True)[source]

Bases: object

Encapsulates a sub project, e.g., a library or tool, defining how it can be downloaded and integrated inside a CodeBase.

property name: str

Name of the sub project.

Return type

str

property url: str

Repository URL.

Return type

str

property remote: str

Git remote, for interacting with upstream repositories.

Return type

str

property path: pathlib.Path

Path to the sub project folder within a CodeBase.

For example:

CodeBase.base_dir / self.path

Specifies the absolute path to the sub project folder.

Return type

Path

property auto_clone: bool

Determine if this project should be automatically cloned when a CodeBase is initialized.

Return type

bool

Returns

True, if it should be automatically cloned

init_and_update_submodules()[source]

Initialize and update all submodules of this sub project.

Parameters

cb_base_dir – base directory for the CodeBase

Return type

None

clone()[source]

Clone the sub project into the specified folder relative to the base dir of the CodeBase.

Return type

None

has_branch(branch_name, remote_to_check=None)[source]

Check if the sub project has a branch with the specified branch name.

Parameters

  • branch_name (str) – name of the branch

  • remote_to_check (Optional[str]) – name of the remote to check, if None, only a local check will be performed

Return type

bool

Returns

True, if the branch exists

get_branches(extra_args=None)[source]

Get branch names from this sub project.

Parameters

extra_args (Optional[List[str]]) – extra arguments passed to git branch

Return type

List[str]

Returns

list of branch names

add_remote(remote, url)[source]

Add a new remote to the sub project.

Parameters

  • remote (str) – name of the new remote

  • url (str) – to the remote

Return type

None

checkout_branch(branch_name)[source]

Checkout out branch in sub project.

Parameters

branch_name (str) – name of the branch, should exists in the repo

Return type

None

checkout_new_branch(branch_name, remote_branch=None)[source]

Create and checkout out a new branch in the sub project.

Parameters

branch_name (str) – name of the new branch, should not exists in the repo

Return type

None

fetch(remote=None, extra_args=None)[source]

Fetch updates from the remote.

Return type

None

pull()[source]

Pull updates from the remote of the current branch into the sub project.

Return type

None

push()[source]

Push updates from the current branch to the remote branch.

Return type

None

show_status()[source]

Show the current status of the sub project.

Return type

None

class varats.tools.research_tools.research_tool.CodeBase(base_dir, sub_projects)[source]

Bases: object

A CodeBase depicts the layout of a project, specifying where the a research tool lives and how different sub projects should be cloned.

In addition, it allows access to the sub projects, e.g., for checkout or other repository manipulations.

property base_dir: pathlib.Path
Return type

Path

get_sub_project(name)[source]

Lookup a sub project of this CodeBase

Parameters

name (str) – of the sub project

Return type

SubProject

clone(cb_base_dir)[source]

Clones the full code base into the specified folder cb_base_dir, which marks the base folder of the code base structure.

Parameters

cb_base_dir (Path) – new base dir of the code base

Return type

None

map_sub_projects(func)[source]

Execute a callable func on all sub projects of the code base.

Parameters

func (Callable[[SubProject], None]) – function to execute on the sub projects

Return type

None

class varats.tools.research_tools.research_tool.ResearchTool(tool_name, supported_build_types, code_base)[source]

Bases: Generic[varats.tools.research_tools.research_tool.SpecificCodeBase]

ResearchTool is an abstract base class for specifying research tools that are set up by VaRA-TS and usable through the tool suites experiments and tools.

property code_base: varats.tools.research_tools.research_tool.SpecificCodeBase
Return type

TypeVar(SpecificCodeBase, bound= CodeBase)

property name: str
Return type

str

is_build_type_supported(build_type)[source]
Return type

bool

abstract static source_location()[source]

Returns the source location of the research tool.

Return type

Path

abstract static has_source_location()[source]

Checks if a source location of the research tool is configured.

Return type

bool

abstract static install_location()[source]

Returns the install location of the research tool.

Return type

Path

abstract static has_install_location()[source]

Checks if a install location of the research tool is configured.

Return type

bool

abstract setup(source_folder, **kwargs)[source]

Setup a research tool with it’s code base. This method sets up all relevant config variables, downloads repositories via the CodeBase, checks out the correct branches and prepares the research tool to be build.

Parameters

source_folder (Optional[Path]) – location to store the code base in

Return type

None

abstract upgrade()[source]

Upgrade the research tool to a newer version.

Return type

None

abstract build(build_type, install_location)[source]

Build/Compile the research tool in the specified build_type and install it to the specified install_location.

Parameters

  • build_type (BuildType) – which type of build should be used, e.g., debug, development or release

  • install_location (Path) – location to install the research tool into

Return type

None

abstract verify_install(install_location)[source]

Verify if the research tool was correctly installed.

Return type

bool

Returns

True, if the tool was correctly installed