Mercurial > bitten > bitten-test
comparison README.txt @ 189:2f0b36b313cc
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/> |