Adding New Applications
=======================

.. _new_app:

Adding new applications to SPBench can be challenging, even for small test applications. 
The main issue is that in SPBench, the source codes of each application are in different places in the SPBench file system, making it harder to visualize the applications as a whole.
The representation below shows the simplest structure an application can have inside SPBench.

.. code-block:: shell

   # File structure of a simple application inside SPBench
     SPBench
       |__ benchmarks # user-side benchmark code
       |   |__ app_id
       |       |__ PPI_id
       |           |__ bench_id
       |               |__ operators
       |               |   |__ include
       |               |   |   |__ operator1_op.hpp
       |               |   |   |__ operatorN_op.hpp
       |               |   |__ src
       |               |   |   |__ operator1_op.cpp
       |               |   |   |__ operatorN_op.cpp
       |               |   |__ operators.json
       |               |__ config.json
       |               |__ bench_id.cpp
       |               |__ app_id.hpp
       |               |__ Makefile
       |__ sys # system-side application code
           |__ apps
               |__ app_id
                   |__ templates
                   |   |__ operators
                   |   |  |__ include
                   |   |  |   |__ operator1_op.hpp
                   |   |  |   |__ operatorN_op.hpp
                   |   |  |__ src
                   |   |  |   |__ operator1_op.cpp
                   |   |  |   |__ operatorN_op.cpp
                   |   |  |__ operators.json
                   |   |__ app_id.hpp
                   |   |__ app_id.cpp
                   |   |__ config.json
                   |__ app_id_utils.hpp
                   |__ app_id_utils.cpp

When using the existent benchmarks provided by SPBench, users should be concerned only with the user-side benchmark code. On this side, there is the source code of the operators, besides Source and Sink, and the implementation of the main function.
Modifying the source codes on the system side is necessary to add a new application. 
The system side includes the implementation of Source and Sink operators, initializing and ending routines, command-line parameters parser, global variable declarations, standard auxiliary functions, etc.
It also includes a templates folder. This folder is copied to ``SPBench/app_id/PPI_id/bench_id/`` when users create a new benchmark. 
So, when adding a new application to SPBench, the developer should be concerned only with the system side. 
The user-side benchmarks will be automatically created if the developer did everything correctly. 

To help users/developers add new applications, SPBench implements the ``new-app`` command. 

Run ``./spbench new-app -h`` or check check :doc:`new_app_cmd` for more details.

This command ``./spbench new-app -h`` can generate a sample toy application with a given number of operators. 
This toy application is perfectly functional, which means it can be used to create, compile, and run a benchmark. 
However, it does not do any meaningful computation and should not be used for real experimentation.

Developers can use this toy application as a template for an actual application by modifying the source codes inside the ``SPBench/sys/apps/`` folder.
Of course, users can also add new folders and source codes that link to these ones. 
The important thing is not to change this structure or the name of the files generated by SPBench when using the ``./spbench new-app`` command.
Remember that the 'SPBench way' of implementing the applications is to keep the resulting benchmarks on the user side as generic as possible.
Besides the different number of operators, adding other elements to the main function should be avoided.

In the future, we may improve this documentation to explain better what should or should not be modified in each file.
For now, one should know that the main files that have to be modified are ``app_id_utils.cpp``, ``app_id_utils.hpp``, and ``operator(N)_op.cpp``. Other files may require minor modifications. 
Also, if the new application uses specific external libraries, they could be already added to the config.json file.

These are the instructions for adding a new application and using it locally.
To contribute to SPBench and permanently add an application to the SPBench suite, other files regarding input workloads and automatic download and installations of dependencies should be modified.
We can also host all external files.
In any case, you can email to ``adriano1mg@gmail.com``for support.
We will appreciate your contribution.