Quickstart
==========

This tutorial provides a basic programmer's introduction to working with rpcc to define
RPCs for the Mercury framework. By following this tutorial, we will be able to:

1. Define rpcs in a :code:`.rpcc` file.
2. Use the :code:`rpcc` compiler to generate C/C++ source files.

Defining our RPCs
------------------

In order to create Mercury RPCs for our service, we need to start with a :code:`.rpcc` file. The
definitions in a :code:`.rpcc` file are simple: we simply add a :code:`rpc` statement for each remote procedure we
need, and then define both its :code:`arguments` and :code:`return_values` by specifying the
:ref:`types <language_data_types>` and names of the fields that compose each message.

Here's an example of a simple remote procedure definition:

.. code-block:: rpcc

    # contents of rpc_sample.rpcc
    package tutorial;

    rpc hello_world {

        id: 42;
        arguments {
            string message;
        };

        return_values {
            int8 error_code;
        };
    };

In this example, our service provides a simple :code:`hello_world` remote procedure that requires a string with the
containing the message that should be printed, and returns an :code:`error_code` to let the developer know whether
the remote procedure executed successfully or not. As we can see, the syntax of a :code:`.rpcc` file is pretty similar to C++ or Java. Let's go through each part of the
file and see what it does:

- The file starts with a :code:`package` declaration, which helps prevent naming conflicts when integrating the
  generated code into an existing project. In C++, all the generated classes and functions will be placed in a namespace
  matching the package name.

- Next, we have the remote procedure definitions. A remote procedure definition is just a *named* structure that
  contains the defined :code:`arguments` and :code:`return_values` of the rpc, alongside some
  :ref:`options <language_rpc_options>` that control how the rpc itself is generated.

.. note::
    Note that, in Mercury, each rpc requires a unique identifier so that the corresponding functions can be
    executed on the target. By default, the :code:`rpcc` compiler will automically generate unique identifiers for each
    defined rpc. The :code:`id` option shown in the example can be used to override this behavior, allowing developers
    to explictly provide a user-defined unique identifier for the rpc.

Compiling our remote procedures
--------------------------------

Now that we have a :code:`.rpcc` file, the next thing we need is to generate the code that we will use to be able to
call the :code:`hello_world` remote procedure. To do this, we need to run the :code:`rpcc` compiler on our
:code:`sample_rpc.rpcc` file.

1. If you haven't installed the compiler, follow :ref:`these instructions <intro_installation>` to install the latest
   version.

2. Now we run the compiler, specifying the desired *output mode* (i.e. which of the
   :ref:`Supported Libraries` is going to be used by client code to interact with remote procedures), as well as the
   *code standard* to use when generating code.

.. code-block:: console

   $ rpcc --output-mode=hermes --std=c++17 rpc_sample.rpcc

.. warning::

    Note that some of the supported output modes may not work with all the code standards.

This generates the following Hermes-compatible source files in the current directory, which should
be integrated into your project's build system:

- :code:`rpc_sample-rpcc.hpp`, the header which declares our generated classes.
- :code:`rpc_sample-rpcc.cpp`, which contains the implementation of our classes.