quickstart.rst

..
  Copyright 2021 Max Planck Institute for Software Systems, and
  National University of Singapore
..
  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:
..
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.
..
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

###################################
Getting Started
###################################

Welcome! We are happy that you want to give SimBricks a try.

The easiest way to get started with just running a simulation is to use our
Docker images, see our `README
<https://github.com/simbricks/simbricks#using-pre-built-docker-images>`_. Given
a working docker installation (`docker engine
<https://docs.docker.com/engine/install/#server>`_ or `docker desktop
<https://docs.docker.com/get-docker/>`_ both work), this is as simple as just
launching a new container and docker will take care of the rest:

.. code-block:: bash

  $ docker run -it simbricks/simbricks /bin/bash

If you have a host system with support for KVM virtualization, you can greatly
speed up many simulations (and building images) by passing through the KVM
device into the container:

.. code-block:: bash

  $ docker run --device=/dev/kvm --privileged -it simbricks/simbricks /bin/bash

Now you are ready to run your first SimBricks simulation (in the container):

.. code-block:: bash

  $ cd experiments
  $ simbricks-run --verbose --force pyexps/qemu_i40e_pair.py

Where you go from here depends on what you plan to do with SimBricks. Our How-To
section, see :ref:`sec-howto`, provides instructions for some common scenarios.
In general, we suggest starting with reading up on our orchestration framework,
see :ref:`sec-orchestration`, and experimenting with building different
simulation configurations, e.g. :ref:`sec-howto-createrun` and
:ref:`sec-howto-nodeconfig`. This will enable you to assemble and customize
various configurations of SimBricks simulations.

If you are planning on making changes to the implementation of SimBricks
components, you may next want to make sure you can build SimBricks from source,
see our `Quick Start section in the README <https://github.com/simbricks/simbricks#quick-start>`_. We
recommend diving into our :ref:`sec-devel` for learning about the SimBricks
architecture, internals, and APIs.

If you run into problems please refer to :ref:`sec-troubleshoot-getting-help`.