Mercurial > bitten > bitten-test
annotate doc/install.txt @ 671:7a8ddf54f012
0.6dev: Changing Windows `CommandLine.execute()` to not go through a shell. This makes execution consistent across platforms, and also fixes the quoting and escaping issues reported in #441. Also adds proper documentation for quoting and escaping.
author | osimons |
---|---|
date | Sat, 05 Sep 2009 00:20:09 +0000 |
parents | b3237a5ace1d |
children | 6511c192a957 |
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 |
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
|
42 $ python setup-slave.py install |
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
|
43 |
412 | 44 |
45 What's left to do now depends on whether you want to use the build master and | |
46 web interface, or just the build slave. In the latter case, you're already | |
47 done. You might need to install software that the build of your project | |
48 requires, but the Bitten build slave itself doesn't require anything extra. | |
49 | |
523 | 50 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
|
51 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
|
52 |
412 | 53 |
54 Build Master Configuration | |
55 ========================== | |
56 | |
57 Once both Bitten and Trac are installed and working, you'll have to introduce | |
58 Bitten to your Trac project environment. If you don't have a Trac project | |
59 set up yet, you'll need to do so in order to use Bitten. | |
60 | |
61 If you already have a Trac project environment, the Bitten plugin needs to be | |
62 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
|
63 ``[components]`` section in ``/path/to/projenv/conf/trac.ini``: |
412 | 64 |
65 .. code-block:: ini | |
66 | |
67 [components] | |
68 bitten.* = enabled | |
69 | |
70 The Trac web interface should now inform you with an error message that the | |
71 environment needs to be upgraded. To do this, run:: | |
72 | |
73 $ trac-admin /path/to/projenv upgrade | |
74 | |
75 This will create the database tables and directories that Bitten requires. | |
76 You probably also want to grant permissions to someone (such as yourself) | |
77 to manage build configurations, and allow anonymous users to view the | |
78 status and results of builds:: | |
79 | |
80 $ trac-admin /path/to/projenv permission add anonymous BUILD_EXEC | |
81 $ trac-admin /path/to/projenv permission add anonymous BUILD_VIEW | |
82 $ trac-admin /path/to/projenv permission add [yourname] BUILD_ADMIN | |
83 | |
84 You should now see an additional tab labeled "Build Status" in the Trac | |
85 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
|
86 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
|
87 |
555
fe4293ddf51c
Removed references to the `TracWebAdmin` plugin which is no longer needed - fixes #387
dfraser
parents:
523
diff
changeset
|
88 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
|
89 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
|
90 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
|
91 build master, and manage build configurations. |
436
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
92 |
cfbc9ee622d5
Finish the move of build configuration management into the admin interface.
cmlenz
parents:
412
diff
changeset
|
93 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
|
94 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
|
95 to "activate" your new build configuration. |
412 | 96 |
97 | |
98 Running the Build Slave | |
99 ======================= | |
100 | |
101 The build slave can be run on any machine that can connect to the machine | |
102 on which the build master is running. The installation of Bitten should have put | |
103 a `bitten-slave` executable on your path. If the script is not on your path, | |
104 look for it in the `bin` or `scripts` subdirectory of your Python installation. | |
105 | |
106 To get a list of options for the build slave, execute it with the `--help` | |
107 option:: | |
108 | |
109 $ bitten-slave --help | |
110 | |
111 To run the build slave against a Bitten-enabled Trac site installed at | |
112 http://myproject.example.org/trac, you'd run:: | |
113 | |
114 $ bitten-slave http://myproject.example.org/trac/builds |