Mercurial > bitten > bitten-test

comparison README.txt @ 189:2f0b36b313cc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added [source:trunk/README.txt README.txt] to explain installation, configuration and usage of Bitten. Closes #36.
author cmlenz
date Wed, 31 Aug 2005 22:58:43 +0000
parents
children 8f5f772c70b0
comparison
equal deleted inserted replaced
188:5a67232c0d69 189:2f0b36b313cc
1 About Bitten
2 ============
3
4 Bitten is a simple distributed continuous integration system that not only
5 coordinates builds across multiple machines, but also collects software
6 metrics generated by builds, to enable feedback and reporting about
7 the progress of a software project.
8
9 The Bitten software consists of three separate parts:
10 * The build slave, which executes build on behalf of a local or remote
11 build master
12 * The build master, which orchestrate builds for a project across all
13 connected slaves, and stores the build status and results to the
14 database
15 * The web interface, which is implemented as an add-on to Trac
16 (http://trac.edgewall.com/) and provides a build management interface
17 as well as presentation of build results.
18
19 Both the build master and the web interface depend on Trac 0.9 beta 1, and
20 need to be installed on the same machine, together with the Subversion
21 repository. The build slave only requires Python (>= 2.3) as well as the
22 tools required by the build process itself. A build slave may be run on
23 any machine that can connect to the server running the Bitten build master.
24
25
26 Installation
27 ------------
28
29 Bitten is written in Python, so make sure that you have Python installed.
30 Also, make sure that the version of Python you have installed is 2.3 or
31 later.
32
33 If that's taken care of, you just need to download and unpack the Bitten
34 distribution, and execute the command:
35
36 $ python setup.py install
37
38 from the top of the directory where you unpacked (or checked out) the Bitten
39 code. Note that you may need administrator/root privileges for this step, as
40 it will attempt to install Bitten to the Python site-packages directory on
41 your system.
42
43 It's also a good idea to run the unit tests at this point, to make sure that
44 the code works as expected on your platform:
45
46 $ python setup.py test
47
48
49 What's left to do now depends on whether you want to use the build master and
50 web interface, or just the build slave. In the latter case, you're already
51 done. You might need to install software that the build of your project
52 requires, but the Bitten build slave itself doesn't require anything extra.
53
54 For the build master and web interface, you'll need to install Trac 0.9
55 beta 1 and Berkeley DB XML >= 2.1.x, as well as their respective
56 dependencies. Please refer to the documentation of those projects for
57 information how they are installed.
58
59
60 Build Master Configuration
61 --------------------------
62
63 Once Bitten, Trac and BDB XML are installed and working, you'll have to
64 introduce Bitten to your Trac project environment. If you don't have a
65 Trac project set up yet, you'll need to do so in order to use Bitten.
66
67 If you already have a Trac project environment, the Trac web interface
68 will inform you with an error message that the environment needs to be
69 upgraded. To do this, run:
70
71 $ trac-admin /path/to/projenv upgrade
72
73 This will create the database tables and directories that Bitten requires.
74 You probably also want to grant permissions to someone (such as yourself)
75 to manage build configurations, and allow anonymous users to view the
76 status and results of builds:
77
78 $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW
79 $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN
80
81 You should now see an additional tab labelled "Build Status" in the Trac
82 navigation bar. This link will take you to the list of build configurations,
83 which at this point is of course empty. If you've set up permissions
84 correctly as described previously, you should see a button for adding new
85 build configurations. Click that button and fill out the form. Also, add
86 at least one target platform after saving the configuration. Last but not
87 least, you'll have to "active" the build configuration.
88
89
90 Running the Build Master
91 ------------------------
92
93 At this point, you're ready to start the Bitten build master. The
94 installation of Bitten should have put a `bittend` script on your path.
95 If the script is not on your path, look for it in the `bin` or `scripts`
96 subdirectory of your Python installation.
97
98 To find out about the options and arguments of the script, execute it with
99 the `--help` option as follows:
100
101 $ bittend --help
102
103 Most commonly, you'll want to specify the log level and log file, as well as
104 the path to the Trac environment:
105
106 $ bittend --verbose --log=/var/log/bittend /var/trac/myproject
107
108
109 Running the Build Slave
110 -----------------------
111
112 The build slave can be run on any machine that can connect to the machine
113 on which the build master is running. Just as with the build master script,
114 you should find the build slave script on your path after the installation.
115 The build slave script is called `bitten`.
116
117 To get a list of options for the build slave, execute it with the `--help`
118 option:
119
120 $ bitten --help
121
122 To run the build slave against a slave installed on myproject.example.org,
123 you'd run:
124
125 $ bitten myproject.example.org
126
127
128 More Information
129 ----------------
130
131 For further documentation, please see the Bitten website at:
132
133 <http://bitten.cmlenz.net/>
Copyright (C) 2012-2017 Edgewall Software