GNOME.org
 

[Notes] [Git][BuildGrid/buildgrid][mablanch/111-recc-usage-guide] 3 commits: Locked sphinx to version 1.7.8.

Title: GitLab

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

Commits:

5 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_bazel.rst
    ... ... @@ -98,7 +98,7 @@ has ``gcc`` installed, run:
    98 98
    99 99 
     The ``--remote`` option is used to specify the server location (running on the
    100 100 
     same machine here, and listening to port 50051). The ``--parent`` option is used
    101 
    -to specify the server instance you except the bot to be attached to. Refer to
    101 
    +to specify the server instance you expect the bot to be attached to. Refer to
    102 102 
     the :ref:`CLI reference section <invoking-bgd-bot-temp-directory>` for command
    103 103 
     line interface details.
    104 104
    ... ... @@ -120,7 +120,7 @@ You can finally have Bazel to build the example workspace by running:
    120 120
    121 121 
        bazel build //main:hello-world
    122 122
    123 
    -You can verify that the example has been successfully build by running the
    123 
    +You can verify that the example has been successfully built by running the
    124 124 
     generated executable. Simply invoke:
    125 125
    126 126 
     .. code-block:: sh

  • docs/source/using_buildstream.rst
    ... ... @@ -149,7 +149,7 @@ that the ``buildbox`` tool is functional on your machine (refer to
    149 149
    150 150 
     The ``--remote`` option is used to specify the server location (running on the
    151 151 
     same machine here, and listening to port 50051). The ``--parent`` option is
    152 
    -used to specify the server instance you except the bot to be attached to (empty
    152 
    +used to specify the server instance you expect the bot to be attached to (empty
    153 153 
     here). ``--fuse-dir`` and ``--local-cas`` are specific to the ``buildbox`` bot
    154 154 
     and respectively specify the sandbox mount point and local CAS cache locations.
    155 155 
     Refer to the :ref:`CLI reference section <invoking-bgd-bot-buildbox>` for
    ... ... @@ -178,7 +178,7 @@ You can finally have BuildStream to build the example project by running:
    178 178
    179 179 
        bst build hello.bst
    180 180
    181 
    -You can verify that the example has been successfully build by running the
    181 
    +You can verify that the example has been successfully built by running the
    182 182 
     generated executable. Simply invoke:
    183 183
    184 184 
     .. code-block:: sh

  • 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 expect 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 built 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

  • setup.py
    ... ... @@ -97,7 +97,8 @@ tests_require = [
    97 97 
     ]
    98 98
    99 99 
     docs_require = [
    100 
    -    'sphinx',
    100 
    +    # rtd-theme broken in Sphinx >= 1.8, this breaks search functionality.
    101 
    +    'sphinx == 1.7.8',
    101 102 
         'sphinx-click',
    102 103 
         'sphinx-rtd-theme',
    103 104 
         'sphinxcontrib-apidoc',

    • —
    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]