GNOME.org
 

[Notes] [Git][BuildGrid/buildgrid][mablanch/111-recc-usage-guide] docs: Add a RECC usage example

Title: GitLab

Martin Blanchard pushed to branch mablanch/111-recc-usage-guide at BuildGrid / buildgrid

Commits:

2 changed files:

Changes:

  • docs/source/using.rst
    ... ... @@ -12,3 +12,4 @@ This section covers how to run an use the BuildGrid build service.
    12 12 
        using_internal.rst
    13 13 
        using_bazel.rst
    14 14 
        using_buildstream.rst
    15 
    +   using_recc.rst
    \ No newline at end of file

  • docs/source/using_recc.rst
    1 
    +
    2 
    +.. _recc-client:
    3 
    +
    4 
    +RECC client
    5 
    +===========
    6 
    +
    7 
    +`RECC`_ is the *Remote Execution Caching Compiler*, an open source build tool
    8 
    +that wraps compiler command calls and forwards them to a remote build execution
    9 
    +service using the remote execution API (REAPI) v2.
    10 
    +
    11 
    +.. note::
    12 
    +
    13 
    +   There is no stable release of RECC yet. You'll have to `install it from
    14 
    +   sources`_.
    15 
    +
    16 
    +.. _RECC: https://gitlab.com/bloomberg/recc
    17 
    +.. _install it from sources: https://gitlab.com/bloomberg/recc#installing-dependencies
    18 
    +
    19 
    +
    20 
    +.. _recc-configuration:
    21 
    +
    22 
    +Configuration
    23 
    +-------------
    24 
    +
    25 
    +RECC reads configuration from its execution environment. You can get a complete
    26 
    +list of environment variables it accepts by running:
    27 
    +
    28 
    +.. code-block:: sh
    29 
    +
    30 
    +   recc --help
    31 
    +
    32 
    +The variables are prefixed with ``RECC_``. The most important ones for remote
    33 
    +execution are:
    34 
    +
    35 
    +- ``RECC_SERVER``: URI of the remote execution server.
    36 
    +- ``RECC_CAS_SERVER``: URI of the CAS server, defaults to ``RECC_SERVER``.
    37 
    +- ``RECC_INSTANCE``: name of the remote execution instance.
    38 
    +
    39 
    +.. hint::
    40 
    +
    41 
    +   ``RECC_VERBOSE=1`` can be set in order to enable verbose output.
    42 
    +
    43 
    +As an example, in order to forward compile commands to the ``main`` instance of
    44 
    +the remote execution server available at ``controller.grid.build`` on port
    45 
    +``50051`` you should export:
    46 
    +
    47 
    +.. code-block:: sh
    48 
    +
    49 
    +   export RECC_SERVER=controller.grid.build:50051
    50 
    +   export RECC_INSTANCE=main
    51 
    +
    52 
    +
    53 
    +.. _recc-example:
    54 
    +
    55 
    +Example build
    56 
    +-------------
    57 
    +
    58 
    +RECC can be use with any existing software package respecting `GNU make common
    59 
    +variables`_ like ``CC`` for the C compiler or ``CXX`` for the C++ compiler.
    60 
    +We'll focus here on instructions on how to build the `GNU Hello`_ example
    61 
    +program using RECC and BuildGrid on your local machine.
    62 
    +
    63 
    +First, you need to download the hello source package:
    64 
    +
    65 
    +.. code-block:: sh
    66 
    +
    67 
    +   wget https://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz
    68 
    +
    69 
    +Next, unpack it and change the current directory to the source root:
    70 
    +
    71 
    +.. code-block:: sh
    72 
    +
    73 
    +   tar xvf hello-2.10.tar.gz
    74 
    +   cd hello-2.10
    75 
    +
    76 
    +.. hint::
    77 
    +
    78 
    +   All the commands in the instructions below are expected to be executed from
    79 
    +   that root source directory (the GNU Hello project's root directory).
    80 
    +
    81 
    +Before trying to build the hello example program, you'll have to setup and run a
    82 
    +BuildGrid server and bot. A minimal server's configuration is given below, paste
    83 
    +it in a ``server.conf`` file in the root directory:
    84 
    +
    85 
    +.. literalinclude:: ./data/bazel-example-server.conf
    86 
    +   :language: yaml
    87 
    +
    88 
    +This defines a single ``main`` server instance implementing a
    89 
    +``ContentAddressableStorage`` (CAS) + ``ByteStream`` service together with an
    90 
    +``Execution`` + ``ActionCache`` service, both using the same in-memory storage.
    91 
    +You can then start the BuildGrid server daemon using that configuration by
    92 
    +running:
    93 
    +
    94 
    +.. code-block:: sh
    95 
    +
    96 
    +   bgd server start server.conf
    97 
    +
    98 
    +In order to perform the actual build work, you need to attach a worker bot to
    99 
    +that server for that ``main`` instance. RECC comes with its own ``reccworker``
    100 
    +bot implementation. However, BuildGrid's host-tools based bot should be enough
    101 
    +to build the hello example program. Once you've make sure that your machine has
    102 
    +``gcc`` installed, run:
    103 
    +
    104 
    +.. code-block:: sh
    105 
    +
    106 
    +   bgd bot --remote=http://localhost:50051 --parent=main temp-directory
    107 
    +
    108 
    +The ``--remote`` option is used to specify the server location (running on the
    109 
    +same machine here, and listening to port 50051). The ``--parent`` option is used
    110 
    +to specify the server instance you except the bot to be attached to. Refer to
    111 
    +the :ref:`CLI reference section <invoking-bgd-bot-temp-directory>` for command
    112 
    +line interface details.
    113 
    +
    114 
    +The BuildGrid server is now ready to accept jobs and execute them. RECC's
    115 
    +:ref:`configuration <bazel-configuration>` needs to be defined as environment
    116 
    +variables. Define minimal configuration by running:
    117 
    +
    118 
    +.. code-block:: sh
    119 
    +
    120 
    +   export RECC_SERVER=localhost:50051
    121 
    +   export RECC_INSTANCE=main
    122 
    +
    123 
    +This points RECC to the ``main`` remote execution server instance at
    124 
    +``localhost:50051``.
    125 
    +
    126 
    +GNU Hello is using `The Autotools`_ as a build system, so first, you need to
    127 
    +configure your build. Run:
    128 
    +
    129 
    +.. code-block:: sh
    130 
    +
    131 
    +   ./configure
    132 
    +
    133 
    +You can finally build the hello example program, using RECC by running:
    134 
    +
    135 
    +.. code-block:: sh
    136 
    +
    137 
    +   make CC="recc cc"
    138 
    +
    139 
    +You can verify that the example program has been successfully build by running
    140 
    +the generated executable. Simply invoke:
    141 
    +
    142 
    +.. code-block:: sh
    143 
    +
    144 
    +   ./hello
    145 
    +
    146 
    +.. _GNU make common variables: https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html
    147 
    +.. _GNU Hello: https://www.gnu.org/software/hello
    148 
    +.. _The Autotools: https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html
    \ No newline at end of file

    • —
    View it on GitLab.
    You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.

    [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]