llvm/docs/HowToAddABuilder.rst

   1 ===================================================================
   2 How To Add Your Build Configuration To LLVM Buildbot Infrastructure
   3 ===================================================================
   4
   5 Introduction
   6 ============
   7
   8 This document contains information about adding a build configuration and
   9 buildbot-worker to private worker builder to LLVM Buildbot Infrastructure.
  10
  11 Buildmasters
  12 ============
  13
  14 There are two buildmasters running.
  15
  16 * The main buildmaster at `<http://lab.llvm.org:8011>`_. All builders attached
  17   to this machine will notify commit authors every time they break the build.
  18 * The staging buildbot at `<http://lab.llvm.org:8014>`_. All builders attached
  19   to this machine will be completely silent by default when the build is broken.
  20   Builders for experimental backends should generally be attached to this
  21   buildmaster.
  22
  23 Steps To Add Builder To LLVM Buildbot
  24 =====================================
  25 Volunteers can provide their build machines to work as build workers to
  26 public LLVM Buildbot.
  27
  28 Here are the steps you can follow to do so:
  29
  30 #. Check the existing build configurations to make sure the one you are
  31    interested in is not covered yet or gets built on your computer much
  32    faster than on the existing one. We prefer faster builds so developers
  33    will get feedback sooner after changes get committed.
  34
  35 #. The computer you will be registering with the LLVM buildbot
  36    infrastructure should have all dependencies installed and you can
  37    actually build your configuration successfully. Please check what degree
  38    of parallelism (-j param) would give the fastest build.  You can build
  39    multiple configurations on one computer.
  40
  41 #. Install buildbot-worker (currently we are using buildbot version 2.8.5).
  42    Depending on the platform, buildbot-worker could be available to download and
  43    install with your package manager, or you can download it directly from
  44    `<http://trac.buildbot.net>`_ and install it manually.
  45
  46 #. Create a designated user account, your buildbot-worker will be running under,
  47    and set appropriate permissions.
  48
  49 #. Choose the buildbot-worker root directory (all builds will be placed under
  50    it), buildbot-worker access name and password the build master will be using
  51    to authenticate your buildbot-worker.
  52
  53 #. Create a buildbot-worker in context of that buildbot-worker account. Point it
  54    to the **lab.llvm.org** port **9990** (see `Buildbot documentation,
  55    Creating a worker
  56    <http://docs.buildbot.net/current/tutorial/firstrun.html#creating-a-worker>`_
  57    for more details) by running the following command:
  58
  59     .. code-block:: bash
  60
  61        $ buildbot-worker create-worker <buildbot-worker-root-directory> \
  62                     lab.llvm.org:9990 \
  63                     <buildbot-worker-access-name> \
  64                     <buildbot-worker-access-password>
  65
  66    To point a worker to silent master please use lab.llvm.org:9994 instead
  67    of lab.llvm.org:9990.
  68
  69 #. Fill the buildbot-worker description and admin name/e-mail.  Here is an
  70    example of the buildbot-worker description::
  71
  72        Windows 7 x64
  73        Core i7 (2.66GHz), 16GB of RAM
  74
  75        g++.exe (TDM-1 mingw32) 4.4.0
  76        GNU Binutils 2.19.1
  77        cmake version 2.8.4
  78        Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
  79
  80 #. Make sure you can actually start the buildbot-worker successfully. Then set
  81    up your buildbot-worker to start automatically at the start up time.  See the
  82    buildbot documentation for help.  You may want to restart your computer
  83    to see if it works.
  84
  85 #. Send a patch which adds your build worker and your builder to
  86    `zorg <https://github.com/llvm/llvm-zorg>`_. Use the typical LLVM
  87    `workflow <https://llvm.org/docs/Contributing.html#how-to-submit-a-patch>`_.
  88
  89    * workers are added to ``buildbot/osuosl/master/config/workers.py``
  90    * builders are added to ``buildbot/osuosl/master/config/builders.py``
  91
  92    Please make sure your builder name and its builddir are unique through the
  93    file.
  94
  95    It is possible to allow email addresses to unconditionally receive
  96    notifications on build failure; for this you'll need to add an
  97    ``InformativeMailNotifier`` to ``buildbot/osuosl/master/config/status.py``.
  98    This is particularly useful for the staging buildmaster which is silent
  99    otherwise.
 100
 101 #. Send the buildbot-worker access name and the access password directly to
 102    `Galina Kistanova <mailto:gkistanova@gmail.com>`_, and wait till she
 103    will let you know that your changes are applied and buildmaster is
 104    reconfigured.
 105
 106 #. Check the status of your buildbot-worker on the `Waterfall Display
 107    <http://lab.llvm.org:8011/#/waterfall>`_ to make sure it is connected, and
 108    ``http://lab.llvm.org:8011/#/workers`` to see if administrator contact and
 109    worker information are correct.
 110
 111 #. Wait for the first build to succeed and enjoy.