1===================================================================
2How To Add Your Build Configuration To LLVM Buildbot Infrastructure
3===================================================================
4
5Introduction
6============
7
8This document contains information about adding a build configuration and
9buildslave to private slave builder to LLVM Buildbot Infrastructure.
10
11Buildmasters
12============
13
14There 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
23Steps To Add Builder To LLVM Buildbot
24=====================================
25Volunteers can provide their build machines to work as build slaves to
26public LLVM Buildbot.
27
28Here 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 buildslave (currently we are using buildbot version 0.8.5).
42   Depending on the platform, buildslave 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 buildslave will be running under,
47   and set appropriate permissions.
48
49#. Choose the buildslave root directory (all builds will be placed under
50   it), buildslave access name and password the build master will be using
51   to authenticate your buildslave.
52
53#. Create a buildslave in context of that buildslave account.  Point it to
54   the **lab.llvm.org** port **9990** (see `Buildbot documentation,
55   Creating a slave
56   <http://docs.buildbot.net/current/tutorial/firstrun.html#creating-a-slave>`_
57   for more details) by running the following command:
58
59    .. code-block:: bash
60
61       $ buildslave create-slave <buildslave-root-directory> \
62                    lab.llvm.org:9990 \
63                    <buildslave-access-name> <buildslave-access-password>
64
65   To point a slave to silent master please use lab.llvm.org:9994 instead
66   of lab.llvm.org:9990.
67
68#. Fill the buildslave description and admin name/e-mail.  Here is an
69   example of the buildslave description::
70
71       Windows 7 x64
72       Core i7 (2.66GHz), 16GB of RAM
73
74       g++.exe (TDM-1 mingw32) 4.4.0
75       GNU Binutils 2.19.1
76       cmake version 2.8.4
77       Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
78
79#. Make sure you can actually start the buildslave successfully. Then set
80   up your buildslave to start automatically at the start up time.  See the
81   buildbot documentation for help.  You may want to restart your computer
82   to see if it works.
83
84#. Send a patch which adds your build slave and your builder to zorg.
85
86   * slaves are added to ``buildbot/osuosl/master/config/slaves.py``
87   * builders are added to ``buildbot/osuosl/master/config/builders.py``
88
89   Please make sure your builder name and its builddir are unique through the file.
90
91   It is possible to whitelist email addresses to unconditionally receive notifications
92   on build failure; for this you'll need to add an ``InformativeMailNotifier`` to
93   ``buildbot/osuosl/master/config/status.py``. This is particularly useful for the
94   staging buildmaster which is silent otherwise.
95
96#. Send the buildslave access name and the access password directly to
97   `Galina Kistanova <mailto:gkistanova@gmail.com>`_, and wait till she
98   will let you know that your changes are applied and buildmaster is
99   reconfigured.
100
101#. Check the status of your buildslave on the `Waterfall Display
102   <http://lab.llvm.org:8011/waterfall>`_ to make sure it is connected, and
103   ``http://lab.llvm.org:8011/buildslaves/<your-buildslave-name>`` to see
104   if administrator contact and slave information are correct.
105
106#. Wait for the first build to succeed and enjoy.
107