Repository files navigation

Besearcher (bot researcher) is a cross-platform tool to help researchers automate and keep track of software-based experiments. The main idea to define a command, its parameters and the possible values of those parameters. Besearcher will then generates all permutations of that command and its parameter values. It will execute each one of them, keeping track of their status (running, finished or aborted) and the output they produced.

• Features
• Installation
• Getting started
  • Prerequisites
  • Installing
  • Configuring
• Usage
• License
• Changelog

Besearcher was created out of a need from a scientific project, so its design values reproducibility and trackability of results. It is easy to use, has minimal dependencies (PHP) and focus on automating repetitive and boring tasks. It also has an (optional) web dashboard that allows users to easily and quickly monitor tasks:

You needPHP andGit available in the command line to run Besearcher. If you intend to use the web dashboard (recommended), you need a web server with PHP support.Wamp is an easy choice.

Go to the folder where you want to install Besearcher, e.g.c:\:

cd c:\

Clone Besearcher's repository:

git clone https://github.com/Dovyski/besearcher.git besearcher

Create a configuration file using the example file provided with Besearcher:

copy besearcher\config.ini-example besearcher\config.ini

If you intend to use the web dashboard, you also need a configuration file for it:

copy besearcher\www\config.ini-example besearcher\www\config.ini

Besearcher has two configuration files:besearcher\config.ini which controls the behavior of Besearcher, andbesearcher\www\config.ini which controls the web dashboard.

Let's start with the first one. Openbesearcher\config.ini in your editor of choice. Search for the line with the directivedata_dir and inform theabsolute path of a directory that Besearcher can use to store results and internal data. E.g.:

data_dir = "c:\experiment\besearcher\"

Then search for the line with the directivetask_cmd, which is the command Besearcher will use to create permutation and execute them:

task_cmd = "test.exe --blah={@data} {@debug} --input={@files}"

The section[task_params] in the config file contains the values that will be used to parametrize the task indicated bytask_cmd. Before executing thetask_cmd string, Besearcher will replace strings like{@name} with the values informed in the[task_params] section. Any param under that section can be used as{@name}. For instance, the following configuration:

task_cmd = test.exe --blah={@data} {@debug} --input={@files}[task_params]data = hidebug = -dfiles[] = 1files[] = 2

will produce the following commands to be executed:

test.exe --blah=hi -d --input=1test.exe --blah=hi -d --input=2

In that case,{@data} is replaced by the value of the param nameddata within the[task_cmd_params] section, as well as{@debug} is replaced by the value of the paramdebug (which is-d). The value of{@files} will be replaced by1 and by2, because{@files} was defined as an array. If more than one param is defined as an array, Besearcher will generate all possible permutations with the informed param values.

Now let's configure the web dashboard, if you are using it. Openbesearcher\www\config.ini in your editor of choice. Set the directivebesearcher_ini_file to the path of theconfig.ini file being used by Besearcher.

For example, if besearcher is installed inc:\besearcher, the path to the configuration INI file will be:

besearcher_ini_file = "c:\besearcher\config.ini"

In order to make the web dashboard available in the browser, you need to create a virtual host or equivalent in your web server and point its document root to thewww folder within Besearcher's installation folder.

Go to the folder where Besearcher was installed and run:

php besearcher.php --ini=config.ini

Besearcher will continue to run, outputing log messages tostdout. While running, Besearcher will execute all permutations created from the command specified intask_cmd.

Besearcher might run for a long time if the issued command has several permutations. Because of that, you can control a running instance of Besearcher via command line using thebc tool.

Assuming you are in the folder where Besearcher was intalled, just run:

cmd\bc --ini=config.ini OPTION

whereOPTION is one of the many available options inbc. Below are a few examples of how you can control a running instance of Beseacher.

Show a summary (running tasks, results, etc)

cmd\bc --ini=config.ini --status

Pause the creation of new tasks:

cmd\bc --ini=config.ini --pause

Resume creation of new tasks:

cmd\bc --ini=config.ini --resume

Stop Besearcher:

cmd\bc --ini=config.ini --stop

Runcmd\bc --help for a list of all available options. Additionally check the fileconfig.ini-example for more usage information.

If you configured the web dashboard of Besearcher, you need to create user(s) to access the dashboard. That is done via command line using thebcuser tool.

Assuming you are in the folder where Besearcher was intalled, you can add users by running the command:

cmd\bcuser --ini=config.ini --add

Runcmd\bcuser -h for a complete list of all available options inbcuser.

Besearcher is licensed under the terms of theMIT Open Sourcelicense and is available for free.

See all changes in theCHANGELOG file.