.. _getting-started:

Getting started
***************

Once you have installed the WRENCH library, following the instructions
on the :ref:`installation page <install>`, you are ready to create a
WRENCH simulator. **Information on what can be simulated and how to do
it are provided in the** :ref:`WRENCH 101 <wrench-101-header>` **and** 
:ref:`WRENCH 102 <wrench-102-header>` **pages. This page is only about the
logistics of setting up a simulator project.**

.. _getting-started-wrench-init:

Using the WRENCH initialization tool
====================================

The ``wrench-init`` tool is a project generator built with WRENCH, which
creates a simple project structure as follows:

.. code:: sh

   project-folder/
   ├── CMakeLists.txt
   ├── CMakeModules
   │   └── FindSimGrid.cmake
   │   └── FindWRENCH.cmake
   ├── src/
   │   ├── Simulator.cpp
   │   ├── Controller.cpp
   ├── include/
   │   └── Controller.h 
   ├── build/
   └── data/
       └── platform.xml

The ``Simulator.cpp`` source file contains the ``main()`` function of
the simulator, which initializes a simulated platform and services
running on this platform; ``Controller.h`` and ``Controller.cpp``
contain the implementation of an execution controller, which executes a
workflow on the available services. The simulator takes as command-line
argument a path to a platform description file in XML, which is
available in ``data/platform.xml``. These files provide the minimum
necessary implementation for a WRENCH-enabled simulator.

The ``wrench-init`` tool only requires a single argument, the name of
the folder where the project skeleton will be generated:

.. code:: sh

   $ wrench-init <project_folder>

Additional options supported by the tool can be found by using the
``wrench-init --help`` command.

Of course, you do not have to use ``wrench-init``, especially if you are
used to creating your own CMake projects. But you still may want to look
at the ``CMakeLists.txt`` file generated by ``wrench-init``. In
particular, note that ``CMakeLists.txt`` uses the ``FindSimgrid.cmake``
and ``FindWRENCH.cmake`` files, which are placed by ``wrench-init`` in
the ``CMakeModules`` directory.

.. _getting-started-example:

Example WRENCH simulators
=========================

The examples in the ``examples`` directory provide good starting points
for developing your own simulators. Examples are provided for the
generic “action” API as well as for the “workflow” API, and are built
along with the WRENCH library and tools. See the ``examples/README.md``
file for a brief description of all examples. Examples can be built by
typing ``make examples`` in the build directory.

For instance, the
``examples/action_api/bare-metal-bag-of-actions`` example
can be executed as:

.. code:: sh

   $ wrench-example-bare-metal-bag-of-actions 6 two_hosts.xml --log=custom_wms.threshold=info

(File ``two_hosts.xml`` is in the
``examples/action_api/bare-metal-bag-of-actions``
directory.) You should see some output in the terminal. The output in
white is produced by the simulator's main function. The output in green
is produced by the execution controller implemented with the WRENCH
developer API.

Although you can inspect the codes of the examples on your own, we
highly recommend that you go through the :ref:`Simulation
101 <simulation-101>`, :ref:`WRENCH 101 <wrench-101-header>`, and
:ref:`WRENCH 102 <wrench-102-header>` pages first. These pages make direct
references to the examples, a description of which is available in
``examples/README.md`` in the WRENCH distribution.