Provided research tools

List of provided research tools:

• VaRA research tool
• SZZUnleashed

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 itself 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 tool’s 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.Distro(*values)

Bases: Enum

Linux distributions supported by the tool suite.

value: str

DEBIAN = 'debian'

ARCH = 'arch'

FEDORA = 'fedora'

static get_current_distro()

Returns the current Linux distribution or None.

Return type:

Optional[Distro]

class varats.tools.research_tools.research_tool.Dependencies(dependencies)

Bases: object

Models the dependencies for a research tool.

property distros: List[Distro]

has_dependencies_for_distro(distro)

Check whether the deendency object has any entries for the given distro.

Parameters:

distro (Distro) – the distro to check

Return type:

bool

Returns:

whether there are any dependencies for the given distro

Test: >>> deps = Dependencies({Distro.DEBIAN: [“foo”, “bar”]}) >>> deps.has_dependencies_for_distro(Distro.DEBIAN) True >>> deps.has_dependencies_for_distro(Distro.ARCH) False >>> deps = Dependencies({Distro.DEBIAN: []}) >>> deps.has_dependencies_for_distro(Distro.DEBIAN) False

has_all_dependencies_for_distro(distro)

Given a distro, return if all specified dependencies are installed. :type distro: Distro :param distro: the distro tu use

Return type:

bool

Returns:

True if all dependencies are installed and False otherwise

get_missing_dependencies_for_distro(distro)

Given a distro, return all not installed dependencies. :type distro: Distro :param distro: the distro to use

Return type:

List[str]

Returns:

a list containing all not installed dependencies

get_install_command(distro)

Given a distro, return a command how the dependencies can be installed. :type distro: Distro :param distro: the distro to use

Return type:

str

Returns:

the command how the dependencies can be installed

Test: >>> deps = Dependencies({Distro.DEBIAN: [“foo”, “bar”], Distro.ARCH: [“baz”]}) >>> deps.get_install_command(Distro.DEBIAN) ‘apt install -y foo bar’ >>> deps.get_install_command(Distro.ARCH) ‘pacman -S –noconfirm baz’

class varats.tools.research_tools.research_tool.SubProject(parent_base_dir, name, url, remote, sub_path, is_submodule=False)

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.

property url: str

Repository URL.

property remote: str

Git remote, for interacting with upstream repositories.

property path: 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.

property is_submodule: bool

Determine if this project is a submodule and shouldn’t be cloned and pulled automatically when a CodeBase is initialized or updated.

Returns:

True, if it should be automatically cloned

init_and_update_submodules()

Initialize and update all submodules of this sub project.

Parameters:

cb_base_dir – base directory for the CodeBase

Return type:

None

clone()

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)

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)

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)

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)

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)

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)

Fetch updates from the remote.

Return type:

None

pull()

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

Return type:

None

push()

Push updates from the current branch to the remote branch.

Return type:

None

show_status()

Show the current status of the sub project.

Return type:

None

get_tags(extra_args=None)

Get the list of available git tags.

Return type:

List[str]

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

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: Path

get_sub_project(name)

Lookup a sub project of this CodeBase

Parameters:

name (str) – of the sub project

Return type:

SubProject

clone(cb_base_dir)

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, exclude_submodules=False)

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

Parameters:

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

• exclude_submodules (bool) – if True sub projects that are managed using git submodules will be excluded

Return type:

None

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

Bases: Generic[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: SpecificCodeBase

property name: str

is_build_type_supported(build_type)

Return type:

bool

abstractmethod classmethod get_dependencies()

Returns the dependencies for this research tool.

Return type:

Dependencies

abstractmethod static source_location()

Returns the source location of the research tool.

Return type:

Path

abstractmethod static has_source_location()

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

Return type:

bool

abstractmethod static install_location()

Returns the install location of the research tool.

Return type:

Path

abstractmethod static has_install_location()

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

Return type:

bool

abstractmethod setup(source_folder, install_prefix, version)

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

• install_prefix (Path) – Installation prefix path

• version (Optional[int]) – Version to setup

Return type:

None

abstractmethod find_highest_sub_prj_version(sub_prj_name)

Returns the highest release version number for the specified SubProject name.

Return type:

int

abstractmethod is_up_to_date()

Returns true if VaRA’s major release version is up to date.

Return type:

bool

abstractmethod upgrade()

Upgrade the research tool to a newer version.

Return type:

None

abstractmethod build(build_type, install_location, build_folder_suffix)

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

• build_folder_suffix (Optional[str]) – a suffix that is appended to the build folder

Return type:

None

abstractmethod get_install_binaries()

Returns a list of binaries to check when validating the installation.

Return type:

List[str]

invalidate_install(install_location)

Delete Binaries which are checked to validate the installation.

Parameters:

install_location (Path) – the installation directory to check

Return type:

None

install_exists(install_location)

Check whether a research tool installation exists at the given path.

In contrast to verify_install(), this does not try to execute any binaries. This is useful if the VaRA installation is intended for a different environment, e.g., in a container.

Parameters:

install_location (Path) – the installation directory to check

Return type:

bool

Returns:

True if the given directory contains a research tool installation

verify_install(install_location)

Verify if the research tool was correctly installed.

Return type:

bool

Returns:

True, if the tool was correctly installed

abstractmethod verify_build(build_type, build_folder_suffix)

Verify if the research tool was built correctly for a given build_type.

Parameters:

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

• build_folder_suffix (Optional[str]) – a suffix that is appended to the build folder

Return type:

bool

Returns:

True, if the build was correct.

class varats.tools.research_tools.research_tool.ContainerInstallable(*args, **kwargs)

Bases: Protocol

Protocol for installing a research tool inside a container.

container_install_dependencies(stage_builder)

Add layers for installing this research tool’s dependencies to the given container.

Parameters:

stage_builder (StageBuilder) – the builder object for the current container stage

Return type:

None

container_install_tool(stage_builder)

Add layers for installing this research tool to the given container.

Parameters:

stage_builder (StageBuilder) – the builder object for the current container stage

Return type:

None

container_tool_env(stage_builder)

Tool-specific container configuration in the form of environment variables.

Parameters:

stage_builder (StageBuilder) – the builder object for the current container stage

Return type:

Dict[str, List[str]]

Returns:

a dictionary of environment variables and their values