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

Installation
------------

First, install the required dependencies:

.. code-block:: bash

    sudo apt install libsodium18

Then you can install the debian package you were provided with:

.. code-block:: bash

    sudo dpkg -i ride-cli_*.deb

This will place the ``ride`` executable in ``/usr/bin``. Execute:

.. code-block:: bash

    ride --help

to see the available commands.

Compiling a Simple Bundle
-------------------------

Your workspace should be structured similar to this:

.. code-block:: none

  .
  └── bundles
    ├── test
    │   ├── manifest.json
    │   ├── sources
    │   │  └── Test.lf
    │   └── resources
    └── pick

The bundle ``test`` can simply be created by using:

.. code-block:: bash

  ride bundle new bundles/test

Here, ``test`` and ``pick`` constitute bundles. They each contain a
``manifest.json`` file, which indicates the name, the version and
the dependencies (on other bundles) of the bundle. Next to this,
``sources`` and ``resources`` folders are created. The ``sources``
folder holds your source files (i.e. all ``.lf`` files), the
``resources`` folder holds app resources like icons.

Let's compile the ``test`` bundle:

.. code-block:: shell

  ride bundle compile bundles/test

This will create a ``test.bundle`` file next to the test bundle directory.

.. note::

  You can specify the path of the resulting bundle file with the ``-o`` argument

Installing a Bundle
-------------------

To get a bundle onto the robot, you should first login:

.. code-block:: shell

  ride login SERVER

Then you can upload the bundle to the robot by installing it:

.. code-block:: shell

  ride bundle install test.bundle


Handling Dependencies
---------------------

Oftentimes, you want to utilize state machines from the common bundles or
other developers (including yourself). How exactly you can use state machines
from other bundles in your state machine is described later in more detail in the
chapter `LF File Format <lf_file_format.html#states>`_. The `ride` CLI tries to
assist you as much as possible with finding and fixing missing dependencies.

When you are using a state machine from another bundle you have to *declare* the
bundle dependency in your manifest. Let's assume that our ``test`` bundle uses some
functionality from the ``pick`` bundle. Oftentimes, it is enough to just `use` a
dependency and let `ride` fix the manifest for you:

.. code-block::

   $ ride bundle compile bundles/test
   ~/statemachines/bundles/test/manifest.json: ERROR
       Missing or undeclared dependencies: pick
       Try these "dependencies": ["pick"] or use --fix-manifest.
   ExitFailure 1

   $ ride compile bundles/test --fix-manifest

The fixed manifest will then contain the bundle our ``test`` bundle depends on. Now ride
happily compile our test bundle again.

.. code-block:: json

  {
    "name": "test",
    "version": "1.0",
    "dependencies": ["pick"]
  }


.. note::
  You don't need to specify the following builtin dependencies:

  * base
  * cartesian_motion
  * common
  * common-robot
  * haptic_common
  * joint_motion
  * no-gripper
  * gripper
  * cobot-pump

There is one edge case which has to be considered by developers and is not covered by `RIDE`.
If a bundle uses a resource from another bundle (e.g. pick) and an SVG file is specified in the
``clientData.icon`` markup that bundle needs to be added manually to the dependencies section
in the manifest. `RIDE` will not check if this dependency exists. Using this bundle on a robot
where the dependency is missing will result in an HTML/JS error when using the Bundle in Desk.

.. _deps:

Dependency Resolution
---------------------

Sometimes you get an error about missing dependencies, where `RIDE` does not offer
the ``--fix-manifest`` option. This is because `RIDE` is unable to find the dependent
bundle. By default `RIDE` will look through the parent folder of your bundle to
resolve the bundles you depend on. Let's assume our workspace layout looks like this:

.. code-block:: none

  .
  ├── bundles
  │ └── test
  │     ├── manifest.json
  │     ├── sources
  │     │  └── Test.lf
  │     └── resources
  └── dependencies
    ├── pick
    └── ...

When we now try to compile the test bundle again, we will get an error message
saying, that the ``pick`` dependency could not be resolved. This is because we
**explicitly** have to tell where `RIDE` can find this dependency with
the ``-B`` option:

.. code-block:: shell

   ride bundle compile bundles/test -B dependencies/pick

.. note::
  You can use multiple ``-B`` options to specify multiple paths for different dependencies.
  However you can also specify the *workspace* directory (e.g. ``-B dependencies/``) to search
  recursively through all bundles.

Now our ``test`` bundle should compile nicely and can be installed on the robot.

Compiling with Make
-------------------

Another way to compile and install your bundle(s) is to use ``make``.
You can download a Makefile :download:`here<_static/Makefile>`. Put it next
to ``bundles`` and then, from outside of the ``bundles`` directory, simply
use ``make`` to compile and install your bundles on the robot. There are several

.. code-block:: shell

  make
  make install

There exist several different make targets depending on your need:

  * ``make bundles`` will compile all bundles within the ``bundles`` folder (default)
  * ``make bundle-X`` will compile only the bundle named ``X`` and put the result into ``build/X.bundle``
  * ``make install``  will upload all ``build/*.bundle`` s to the robot
  * ``make install-X`` will compile and upload the bundle named ``X``

If you get warnings about missing dependencies during make, add the bundle directory
containing the missing dependency, similarly as :ref:`described above<deps>`.

.. code-block:: shell

  make DEPS="-B ee-gripper"

.. warning::

   If you omit  the ``DEPS=...`` to make, `RIDE` will build your bundles with
   ``--ignore-dependencies`` by default. However you should always specify the
   folder to missing dependencies such as the gripper if you can!