# HG changeset patch # User Jeff Hammel # Date 1296836901 28800 # Node ID 3e5d1c1e302d2c3b3393dc4f2ff8cd9e47bc7b69 # Parent 45da31ae738e2356653296a7629f274f9e49b6cf * documentation * fix syntax error diff -r 45da31ae738e -r 3e5d1c1e302d README.txt --- a/README.txt Fri Feb 04 08:11:07 2011 -0800 +++ b/README.txt Fri Feb 04 08:28:21 2011 -0800 @@ -10,18 +10,19 @@ autobot is a continuous integration solution for the Automation and Tools Team. We have a lot of software. We're really talented, so usually it doesn't break. But we're not infalliable. Our robot ally, -autobot, is there to test things for us. Let's me autobot! +autobot, is there to test things for us. Let's meet autobot! Installing autobot ------------------ -autobot may be installed using the Install script:: +autobot may be installed using the install script:: curl http://k0s.org/mozilla/hg/autobot/raw-file/tip/INSTALL.sh | bash This will create a virtualenv and install autobot for development -($VIRTUAL_ENV/src/autobot). +($VIRTUAL_ENV/src/autobot). You can also use the script as +instructions and install it in the same manner as any other python package. Setting up a buildmaster and slave @@ -33,11 +34,14 @@ You can create a master-slave pair by running ``create-autobot`` after activating the virtualenv. This is mostly useful for autobot development. The scripts ``create-autobot-master`` and -``create-autobot-slave`` are also available. The scripts will prompt you -for a factory. The factories are from ``autobot.projects`` and its -subdirectories. You can list the available factories with -``create-autobot --list-factories`` (or ``create-autobot-master ---list-factories``). +``create-autobot-slave`` are also available and are more useful for +production, as normally you will not want to keep the master and the +slave on the same machine except for development and testing. The +scripts will prompt you for a factory or you can specify one or more +from the commandline using ``--factory`` or ``-f``. The factories are +from ``autobot.projects`` and its subdirectories. You can list the +available factories with ``create-autobot --list-factories`` (or +``create-autobot-master --list-factories``). Running ``create-autobot --help`` will give the variables you can set when it makes a new bot for you (``create-autobot-master`` and @@ -45,20 +49,21 @@ ``create-autobot`` being a superset of these). If you don't specify a variable, the default will be used to create -your particular bot. You can (probably) change it later. +your particular bot. You can change these in the resultant +configuration later. Using autobot ------------- The buildmaster and buildslave are started with -``buildbot start master`` and ``buildslave stop slave``. Respective -``stop`` commands also exist. If you used the ``create-autobot`` -command the generated bot will have a ``restart_buildbot.py`` script -that will stop and start both the master and slave and (if debug is -set) remove the log as well. +``buildbot start master`` and ``buildslave stop slave`` from the bot's +directories. Respective ``stop`` commands also exist. If you used the +``create-autobot`` command the generated bot will have a +``restart_buildbot.py`` script that will stop and start both the +master and slave and (if debug is set) remove the log as well. -The generated ``master.cfg`` file reads values from an ``master.ini`` +The generated ``master.cfg`` file reads values from a ``master.ini`` file in the same directory. The master.ini contains a number of different sections: @@ -66,13 +71,13 @@ as well as default settings for slaves * sections like ``[slave:slavename]`` indicate a slave of name ``slavename`` -* other sections are construction parameters for factories +* all other sections are construction parameters for factories The format of the ``.ini`` file is detailed in the subsequent -section. You may change the .ini file used by editing the +section. You may change which .ini file is used by editing the ``master.cfg`` file, or, if for whatever reason you don't want to use -an .ini file you can construct the appropriate configuration therein -yourself. +an .ini file as a driver you can construct the appropriate +configuration therein yourself. An overview of the build status is detailed at the waterfall display, by default at http://localhost:8010/waterfall . To force a build, @@ -80,13 +85,14 @@ towards the bottom. It is important to remember that continuous integration is a safety -net, not a first line of defense. In other words, continue to check your code -*before* sending it to autobot. +net, not a first line of defense. In other words, continue to check +your code *before* sending it to autobot. + .ini file format ---------------- -As stated above, a ``master.ini`` file contains three different kinds +As stated above, a ``master.ini`` file contains three different types of sections: * ``[:master:]`` contains the top level configuration for the master @@ -117,25 +123,29 @@ ``slave:`` parameters for each slave: * password: each slave *must* have a password. Unless there's a - reason to have a password per slave, its probably better to put this - in the ``:master:`` section + reason to have a different password per slave, its probably better + to put this in the ``:master:`` section * factories: space-separated list of factories to run on that slave. If the special value ``*`` is used, all factories will be run. You can view the factories available with ``create-autobot --list-factories``. The factory name corresponds to - the directory (or module) name in ``autobot.projects``. + the directory (or module) name in ``autobot.projects``. If + every slave is meant to run the same factories, you can put this in + the ``:master:`` section -* os: the operating system of the slave. Should be one of linux, win, - or mac (though see TODO about future use of MozInfo making this - obselescent). You probably *shouldn't* have a default key for this - in the ``:master:`` section (though autobot won't try to stop you!). +* os: the operating system of the slave. Should be one of ``linux``, + ``win``, or ``mac`` (though see TODO about future use of MozInfo + making this obselescent). You probably *shouldn't* have a default + key for this in the ``:master:`` section (though autobot won't try + to stop you!). ---- -factory sections: Each parameter in a factory section is used as a -constructor (``__init__``) keyword argument when they are created in -the ``master.cfg``. So a factory section like:: +factory sections: All other sections are used to build the factories. +Each parameter in a factory section is used as a constructor +(``__init__``) keyword argument when they are created in the +``master.cfg``. So a factory section like:: [foo] bar = fleem @@ -171,11 +181,24 @@ to see this location). + Adding a New Project -------------------- Occassionally, you'll need to add a new project to test. You can add -a ``__init__.py`` file +a ``__init__.py`` file to a directory under ``autobot.projects`` and, +if you have a factory therein, autobot will find it and add it to the +list of factories it knows about. + +There is also a script, ``create-autobot-project``, that can create +this stub for you:: + + Usage: create-autobot-project [options] project + +``project`` is the name of the project and ``output``, if specified, +is the path of the file to create. If output is not specified, it +will find its way to a directory named for the project under +``autobot.projects``. Is your autobot being feisty? diff -r 45da31ae738e -r 3e5d1c1e302d autobot/process/factory.py --- a/autobot/process/factory.py Fri Feb 04 08:11:07 2011 -0800 +++ b/autobot/process/factory.py Fri Feb 04 08:28:21 2011 -0800 @@ -75,7 +75,7 @@ self.addStep(ShellCommand(command=['unzip', WithProperties('%(firefox_bundle)s')], haltOnFailure=True)) self.addStep(SetProperty(property='firefox', - command=self.abspath('firefox/firefox.exe')) + command=self.abspath('firefox/firefox.exe'))) else: # TODO: mac raise NotImplementedError("FirefoxDownloader doesn't know how to work with your os: %s" % platform['os'])