Mercurial > bitten > bitten-test
annotate doc/install.txt @ 754:545be0c8f405
Adding the ability to modify the default ''onerror'' property in the ''<build>'' element. If not specified, the behavior is unchanged; by default any step failure will result in the build failing and stopping.
Added a new ''continue'' onerror specification-- it's similar to ''ignore''
except the results of ''continue'' steps are counted in the overall build
status (in ''ignore'' they're ignored.)
You'll need to upgrade both your master and slaves if you wish to use
the ''<build>'' element override or the new ''continue'' value.
Will update http://bitten.edgewall.org/wiki/Documentation/recipes.html .
Thanks to jerith for comments.
Closes #409.
Refs #210.
author | wbell |
---|---|
date | Sat, 24 Apr 2010 13:37:26 +0000 |
parents | 7c8b6a329e12 |
children |
rev | line source |
---|---|
412 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ============ | |
4 Installation | |
5 ============ | |
6 | |
7 .. contents:: Contents | |
8 :depth: 2 | |
9 .. sectnum:: | |
10 | |
11 | |
12 Prerequisites | |
13 ============= | |
14 | |
15 Bitten is written in Python, so make sure that you have Python installed. | |
657
9546e25b9d5c
0.6dev: The install docs did not mention that master requires Trac 0.11.
osimons
parents:
654
diff
changeset
|
16 You'll need Python 2.4 or later for running build slave. The build master is |
658
b3237a5ace1d
0.6dev: Linking to Trac in first install paragraph.
osimons
parents:
657
diff
changeset
|
17 a plugin for Trac_ 0.11, and should still work with Python 2.3. Also, make |
657
9546e25b9d5c
0.6dev: The install docs did not mention that master requires Trac 0.11.
osimons
parents:
654
diff
changeset
|
18 sure that setuptools_, version 0.6a2 or later, is installed. |
412 | 19 |
658
b3237a5ace1d
0.6dev: Linking to Trac in first install paragraph.
osimons
parents:
657
diff
changeset
|
20 .. _trac: http://trac.edgewall.org |
412 | 21 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools |
22 | |
23 If that's taken care of, you just need to download and unpack the Bitten | |
24 distribution, and execute the command:: | |
25 | |
26 $ python setup.py install | |
27 | |
28 from the top of the directory where you unpacked (or checked out) the Bitten | |
29 code. Note that you may need administrator/root privileges for this step, as | |
30 it will by default attempt to install Bitten to the Python site-packages | |
31 directory on your system. | |
32 | |
33 It's also a good idea to run the unit tests at this point, to make sure that | |
522
ad7c5f4b1cf0
Added note that you need Trac for the tests; see #265
dfraser
parents:
436
diff
changeset
|
34 the code works as expected on your platform (please note that Trac_ needs to |
ad7c5f4b1cf0
Added note that you need Trac for the tests; see #265
dfraser
parents:
436
diff
changeset
|
35 be installed for the tests to run; see below):: |
412 | 36 |
37 $ python setup.py test | |
38 | |
598
5f3e66e5b451
0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents:
555
diff
changeset
|
39 It is also possible to install only the build slave, installing only the |
5f3e66e5b451
0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents:
555
diff
changeset
|
40 parts of Bitten that are needed by clients to run builds:: |
5f3e66e5b451
0.6dev: Running `python setup-slave.py install` now works for installing only the parts of Bitten needed by slave to run builds. Closes #383.
osimons
parents:
555
diff
changeset
|
41 |
682
6511c192a957
0.6dev: Complete rework of the slave-only install to use `setuptools.Feature` to disable the master-parts. This should make all regular distribution commands like 'test', 'sdist', 'bdist_egg' and so on work as intended, and the output can be adjusted using option `--without-master` (master is enabled by default).
osimons
parents:
658
diff
changeset
|
42 $ python setup.py --without-master install |
412 | 43 |
44 What's left to do now depends on whether you want to use the build master and | |
45 web interface, or just the build slave. In the latter case, you're already | |
46 done. You might need to install software that the build of your project | |
47 requires, but the Bitten build slave itself doesn't require anything extra. | |
48 | |
523 | 49 For the build master and web interface, you'll need to install Trac_ 0.11 or |
555
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
50 later. Please refer to the Trac documentation for information on how it is installed. |
436
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
51 |
412 | 52 |
53 Build Master Configuration | |
54 ========================== | |
55 | |
56 Once both Bitten and Trac are installed and working, you'll have to introduce | |
57 Bitten to your Trac project environment. If you don't have a Trac project | |
58 set up yet, you'll need to do so in order to use Bitten. | |
59 | |
60 If you already have a Trac project environment, the Bitten plugin needs to be | |
61 explicitly enabled in the Trac configuration. This is done by adding it to the | |
436
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
62 ``[components]`` section in ``/path/to/projenv/conf/trac.ini``: |
412 | 63 |
64 .. code-block:: ini | |
65 | |
66 [components] | |
67 bitten.* = enabled | |
68 | |
69 The Trac web interface should now inform you with an error message that the | |
70 environment needs to be upgraded. To do this, run:: | |
71 | |
72 $ trac-admin /path/to/projenv upgrade | |
73 | |
74 This will create the database tables and directories that Bitten requires. | |
75 You probably also want to grant permissions to someone (such as yourself) | |
76 to manage build configurations, and allow anonymous users to view the | |
77 status and results of builds:: | |
78 | |
739
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
79 $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN |
412 | 80 $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW |
739
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
81 |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
82 Build slaves (see next section) will need permission to download build |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
83 configurations and submit results. You can grant the permission using:: |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
84 |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
85 $ trac-admin /path/to/projenv permission add [slavegroup] BUILD_EXEC |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
86 |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
87 Alternatively you may allow anyone to submit builds by giving anonymous |
7c8b6a329e12
Clarify BUILD_EXEC meaning in install docs. See #555.
hodgestar
parents:
682
diff
changeset
|
88 users this permission. |
412 | 89 |
90 You should now see an additional tab labeled "Build Status" in the Trac | |
91 navigation bar. This link will take you to the list of build configurations, | |
436
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
92 which at this point is of course empty. |
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
93 |
555
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
94 If Bitten is installed, and you are logged in as a user with the required |
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
95 permissions, you should see additional administration pages inside the “Admin” |
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
96 area, under a group named “Builds”. These pages allow you to set options of the |
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
97 build master, and manage build configurations. |
436
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
98 |
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
99 Add a new build configuration and fill out the form. Also, add at least one |
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
100 target platform after saving the configuration. Last but not least, you'll have |
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
101 to "activate" your new build configuration. |
412 | 102 |
103 | |
104 Running the Build Slave | |
105 ======================= | |
106 | |
107 The build slave can be run on any machine that can connect to the machine | |
108 on which the build master is running. The installation of Bitten should have put | |
109 a `bitten-slave` executable on your path. If the script is not on your path, | |
110 look for it in the `bin` or `scripts` subdirectory of your Python installation. | |
111 | |
112 To get a list of options for the build slave, execute it with the `--help` | |
113 option:: | |
114 | |
115 $ bitten-slave --help | |
116 | |
117 To run the build slave against a Bitten-enabled Trac site installed at | |
118 http://myproject.example.org/trac, you'd run:: | |
119 | |
120 $ bitten-slave http://myproject.example.org/trac/builds |