Getting Started
===============

.. _getting_started:

.. contents:: Table of Contents

SPBench Dependencies
--------------------

The folowing packages are required to install and use SPBench:

   - build-essential
   - pkg-config
   - cmake
   - python (tested on python3 and python2.7)

You can run the command below to install theses packages or ask a system admin.

.. code-block:: bash

   sudo apt-get install -y build-essential pkg-config cmake python3

Command-Line Interface
----------------------

The SPBench framework works with a command-line interface (CLI).

The CLI offers some commands. You can check them running:

.. code-block:: bash

   ./spbench --help

For each command there is also a "help" guide. You can access it using:

.. code-block:: bash

   ./spbench [command] -h

Check :doc:`CLI` for more details.

Installing SPBench
------------------

The purpose of the SPBench is to provide self-contained benchmarks, i.e., it provides the specific installation dependencies for each supported application. These dependencies can be either libraries like OpenCV for the image processing applications or parallel programming interfaces like Intel TBB for the parallel benchmarks.

Therefore, SPBench has specific commands to help download and install these dependencies. See :doc:`installation` section for more details or run the command below:

.. code-block:: bash

   ./spbench install -help


To run the benchmarks it is not enough to install the dependencies, you also need to download and install the workloads. SPBench also offers commands to do this. See section :doc:`workloads` for more details, or run the command below.

.. code-block:: bash

   ./spbench download-inputs -help

If there were no errors during the installation of the dependencies or workloads, then you are ready to compile and run the SPBench benchmarks. See section :doc:`how_to_run` for more details.

How to use
----------

In this framework you can simply run the benchmarks that are already provided or implement your own specific benchmark.

To run the benchmarks you first need to have installed the application dependencies and also the workloads. See pages :doc:`install` and :doc:`workloads` for more details.

After installing the workloads and dependencies (make sure you set the environment variables ``source setup_vars.sh``), you can run the 'list' command to see all the pre-available benchmarks in SPBench.

.. code-block:: bash

   ./spbench list

Then you can select one of the benchmarks from the list and use the command below to compile it.

.. code-block:: bash
   
   ./spbench compile -bench <selected_bench_name_from_list>

If the compilation was successful, just run it via the 'exec' command.

.. code-block:: bash
   
   ./spbench exec -bench <selected_bench_name_from_list> -input <input_id> ... [optional_commands] <optional_args>


.. Note::

   For GrPPI benchmarks you must select a backend using a custom user argument. Available backends: 'omp' (OpenMP), 'thr' (C++11 threads), 'ff' (FastFlow), and 'tbb'.

.. code-block:: bash
   
   ./spbench exec -bench <grppi_bench> -input <input_id> ... -user-arg <backend>

Check :doc:`CLI` for other options.

Inputs
------

In the exec step you must choose a given input for the benchmark.

These inputs can be downloaded and will be stored in the inputs/ directory.

You can run the ``./spbench download-inputs`` to automatically download them.

You can use your own input or choose a given one.

You can check the given inputs through:

.. code-block:: bash
   
   ./spbench list-inputs

See the :doc:`workloads` page for more details about workloads.

.. Tip::

   - You can run ``source setup_vars.sh`` to load the libraries.
   - You must load the libraries before using SPBench every time you star a new session.