Mercurial > hg > autobot

comparison README.txt @ 206:3e5d1c1e302d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* documentation * fix syntax error
author Jeff Hammel <jhammel@mozilla.com>
date Fri, 04 Feb 2011 08:28:21 -0800
parents 5f188d2a36aa
children 2d5b78d3411c
comparison
equal deleted inserted replaced
205:45da31ae738e 206:3e5d1c1e302d
8 ---------------- 8 ----------------
9 9
10 autobot is a continuous integration solution for the Automation and 10 autobot is a continuous integration solution for the Automation and
11 Tools Team. We have a lot of software. We're really talented, so 11 Tools Team. We have a lot of software. We're really talented, so
12 usually it doesn't break. But we're not infalliable. Our robot ally, 12 usually it doesn't break. But we're not infalliable. Our robot ally,
13 autobot, is there to test things for us. Let's me autobot! 13 autobot, is there to test things for us. Let's meet autobot!
14 14
15 15
16 Installing autobot 16 Installing autobot
17 ------------------ 17 ------------------
18 18
19 autobot may be installed using the Install script:: 19 autobot may be installed using the install script::
20 20
21 curl http://k0s.org/mozilla/hg/autobot/raw-file/tip/INSTALL.sh | bash 21 curl http://k0s.org/mozilla/hg/autobot/raw-file/tip/INSTALL.sh | bash
22 22
23 This will create a virtualenv and install autobot for development 23 This will create a virtualenv and install autobot for development
24 ($VIRTUAL_ENV/src/autobot). 24 ($VIRTUAL_ENV/src/autobot). You can also use the script as
25 instructions and install it in the same manner as any other python package.
25 26
26 27
27 Setting up a buildmaster and slave 28 Setting up a buildmaster and slave
28 ---------------------------------- 29 ----------------------------------
29 30
31 want to create a buildmaster and a buildslave. 32 want to create a buildmaster and a buildslave.
32 33
33 You can create a master-slave pair by running ``create-autobot`` after 34 You can create a master-slave pair by running ``create-autobot`` after
34 activating the virtualenv. This is mostly useful for autobot 35 activating the virtualenv. This is mostly useful for autobot
35 development. The scripts ``create-autobot-master`` and 36 development. The scripts ``create-autobot-master`` and
36 ``create-autobot-slave`` are also available. The scripts will prompt you 37 ``create-autobot-slave`` are also available and are more useful for
37 for a factory. The factories are from ``autobot.projects`` and its 38 production, as normally you will not want to keep the master and the
38 subdirectories. You can list the available factories with 39 slave on the same machine except for development and testing. The
39 ``create-autobot --list-factories`` (or ``create-autobot-master 40 scripts will prompt you for a factory or you can specify one or more
40 --list-factories``). 41 from the commandline using ``--factory`` or ``-f``. The factories are
42 from ``autobot.projects`` and its subdirectories. You can list the
43 available factories with ``create-autobot --list-factories`` (or
44 ``create-autobot-master --list-factories``).
41 45
42 Running ``create-autobot --help`` will give the variables you can set 46 Running ``create-autobot --help`` will give the variables you can set
43 when it makes a new bot for you (``create-autobot-master`` and 47 when it makes a new bot for you (``create-autobot-master`` and
44 ``create-autobot-slave`` also have a ``--help``, the variables in 48 ``create-autobot-slave`` also have a ``--help``, the variables in
45 ``create-autobot`` being a superset of these). 49 ``create-autobot`` being a superset of these).
46 50
47 If you don't specify a variable, the default will be used to create 51 If you don't specify a variable, the default will be used to create
48 your particular bot. You can (probably) change it later. 52 your particular bot. You can change these in the resultant
53 configuration later.
49 54
50 55
51 Using autobot 56 Using autobot
52 ------------- 57 -------------
53 58
54 The buildmaster and buildslave are started with 59 The buildmaster and buildslave are started with
55 ``buildbot start master`` and ``buildslave stop slave``. Respective 60 ``buildbot start master`` and ``buildslave stop slave`` from the bot's
56 ``stop`` commands also exist. If you used the ``create-autobot`` 61 directories. Respective ``stop`` commands also exist. If you used the
57 command the generated bot will have a ``restart_buildbot.py`` script 62 ``create-autobot`` command the generated bot will have a
58 that will stop and start both the master and slave and (if debug is 63 ``restart_buildbot.py`` script that will stop and start both the
59 set) remove the log as well. 64 master and slave and (if debug is set) remove the log as well.
60 65
61 The generated ``master.cfg`` file reads values from an ``master.ini`` 66 The generated ``master.cfg`` file reads values from a ``master.ini``
62 file in the same directory. The master.ini contains a number of 67 file in the same directory. The master.ini contains a number of
63 different sections: 68 different sections:
64 69
65 * ``[:master:]`` contains the top level configuration for the master 70 * ``[:master:]`` contains the top level configuration for the master
66 as well as default settings for slaves 71 as well as default settings for slaves
67 * sections like ``[slave:slavename]`` indicate a slave of name 72 * sections like ``[slave:slavename]`` indicate a slave of name
68 ``slavename`` 73 ``slavename``
69 * other sections are construction parameters for factories 74 * all other sections are construction parameters for factories
70 75
71 The format of the ``.ini`` file is detailed in the subsequent 76 The format of the ``.ini`` file is detailed in the subsequent
72 section. You may change the .ini file used by editing the 77 section. You may change which .ini file is used by editing the
73 ``master.cfg`` file, or, if for whatever reason you don't want to use 78 ``master.cfg`` file, or, if for whatever reason you don't want to use
74 an .ini file you can construct the appropriate configuration therein 79 an .ini file as a driver you can construct the appropriate
75 yourself. 80 configuration therein yourself.
76 81
77 An overview of the build status is detailed at the waterfall display, 82 An overview of the build status is detailed at the waterfall display,
78 by default at http://localhost:8010/waterfall . To force a build, 83 by default at http://localhost:8010/waterfall . To force a build,
79 click on the desired builder and there will be a force build button 84 click on the desired builder and there will be a force build button
80 towards the bottom. 85 towards the bottom.
81 86
82 It is important to remember that continuous integration is a safety 87 It is important to remember that continuous integration is a safety
83 net, not a first line of defense. In other words, continue to check your code 88 net, not a first line of defense. In other words, continue to check
84 *before* sending it to autobot. 89 your code *before* sending it to autobot.
90
85 91
86 .ini file format 92 .ini file format
87 ---------------- 93 ----------------
88 94
89 As stated above, a ``master.ini`` file contains three different kinds 95 As stated above, a ``master.ini`` file contains three different types
90 of sections: 96 of sections:
91 97
92 * ``[:master:]`` contains the top level configuration for the master 98 * ``[:master:]`` contains the top level configuration for the master
93 as well as default settings for slaves 99 as well as default settings for slaves
94 * sections like ``[slave:slavename]`` indicate a slave of name 100 * sections like ``[slave:slavename]`` indicate a slave of name
115 ---- 121 ----
116 122
117 ``slave:`` parameters for each slave: 123 ``slave:`` parameters for each slave:
118 124
119 * password: each slave *must* have a password. Unless there's a 125 * password: each slave *must* have a password. Unless there's a
120 reason to have a password per slave, its probably better to put this 126 reason to have a different password per slave, its probably better
121 in the ``:master:`` section 127 to put this in the ``:master:`` section
122 128
123 * factories: space-separated list of factories to run on that slave. 129 * factories: space-separated list of factories to run on that slave.
124 If the special value ``*`` is used, all factories will be run. You 130 If the special value ``*`` is used, all factories will be run. You
125 can view the factories available with 131 can view the factories available with
126 ``create-autobot --list-factories``. The factory name corresponds to 132 ``create-autobot --list-factories``. The factory name corresponds to
127 the directory (or module) name in ``autobot.projects``. 133 the directory (or module) name in ``autobot.projects``. If
128 134 every slave is meant to run the same factories, you can put this in
129 * os: the operating system of the slave. Should be one of linux, win, 135 the ``:master:`` section
130 or mac (though see TODO about future use of MozInfo making this 136
131 obselescent). You probably *shouldn't* have a default key for this 137 * os: the operating system of the slave. Should be one of ``linux``,
132 in the ``:master:`` section (though autobot won't try to stop you!). 138 ``win``, or ``mac`` (though see TODO about future use of MozInfo
139 making this obselescent). You probably *shouldn't* have a default
140 key for this in the ``:master:`` section (though autobot won't try
141 to stop you!).
133 142
134 ---- 143 ----
135 144
136 factory sections: Each parameter in a factory section is used as a 145 factory sections: All other sections are used to build the factories.
137 constructor (``__init__``) keyword argument when they are created in 146 Each parameter in a factory section is used as a constructor
138 the ``master.cfg``. So a factory section like:: 147 (``__init__``) keyword argument when they are created in the
148 ``master.cfg``. So a factory section like::
139 149
140 [foo] 150 [foo]
141 bar = fleem 151 bar = fleem
142 baz = another parameter 152 baz = another parameter
143 153
169 ``autobot.projects`` (use 179 ``autobot.projects`` (use
170 ``python -c 'from autobot import projects; print projects.__file__'`` 180 ``python -c 'from autobot import projects; print projects.__file__'``
171 to see this location). 181 to see this location).
172 182
173 183
184
174 Adding a New Project 185 Adding a New Project
175 -------------------- 186 --------------------
176 187
177 Occassionally, you'll need to add a new project to test. You can add 188 Occassionally, you'll need to add a new project to test. You can add
178 a ``__init__.py`` file 189 a ``__init__.py`` file to a directory under ``autobot.projects`` and,
190 if you have a factory therein, autobot will find it and add it to the
191 list of factories it knows about.
192
193 There is also a script, ``create-autobot-project``, that can create
194 this stub for you::
195
196 Usage: create-autobot-project [options] project <output>
197
198 ``project`` is the name of the project and ``output``, if specified,
199 is the path of the file to create. If output is not specified, it
200 will find its way to a directory named for the project under
201 ``autobot.projects``.
179 202
180 203
181 Is your autobot being feisty? 204 Is your autobot being feisty?
182 ----------------------------- 205 -----------------------------
183 206