cookutils view doc/cookutils.en.html @ rev 84
doc: Add more info about the cooker and cron
| author | Christophe Lincoln <pankso@slitaz.org> |
|---|---|
| date | Sun May 08 02:54:13 2011 +0200 (2011-05-08) |
| parents | 246abb0e12d9 |
| children | b2cf2da8c3b3 |
line source
1 <!DOCTYPE html>
2 <html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <title>Cookutils Documentation</title>
5 <meta charset="utf-8" />
6 <link rel="stylesheet" type="text/css" href="style.css" />
7 </head>
8 <body>
10 <div id="header">
11 <h1>Cookutils Documentation</h1>
12 </div>
14 <!-- Start content -->
15 <div id="content">
17 <h2>SliTaz Cook & Cooker</h2>
19 <p>
20 The SliTaz Cookutils provide tools and utils to help build SliTaz packages. They
21 are easy to use and learn, fast and light. You will be able to create SliTaz
22 packages in a few commands. The cookutils provide the 'cook' utility and the
23 <a href="#cooker">Cooker</a>.
24 </p>
25 <p>
26 Cook lets you compile and create a package, provide a log file and check the
27 receipt/package quality. The Cooker is a build bot with more automation
28 and can be used as a frontend to cook, since it provides a CGI/web interface
29 which lets you view cook logs in a nice and colored way. Cook and the Cooker
30 use the same DB files and wok, they share <a href="#blocked">blocked</a>
31 and broken packages as well as any activity.
32 </p>
34 <h3>Cook usage</h3>
35 <p>
36 Cook provides a small built-in help usage that you can display with the
37 command 'usage'. It also has some options to perform special tasks on
38 a package before cooking it or after. To get help and usage:
39 </p>
40 <pre>
41 # cook usage
42 </pre>
44 <h3>Howto</h3>
45 <p>
46 The first thing you will have to do before building packages is setup
47 your environment. The 2 recommended ways of working: cook directly on host
48 or cook in chroot to protect your host. In the case you want to work in a
49 chroot you can install and use Tazdev to create one and chroot into it:
50 </p>
51 <pre>
52 # tazdev gen-chroot && tazdev chroot
53 </pre>
54 <p>
55 By default Tazdev creates a chroot in /home/slitaz/cooking/chroot but you
56 can specify a custom path in the argument. The chroot location is not
57 important, when you will be in the chroot you will use standard SliTaz
58 paths such as /home/slitaz/wok for the wok directory or /home/slitaz/log
59 for all the cook logs. As usual you can diplay tazdev help usage with:
60 tazdev usage.
61 </p>
62 <p>
63 When you use a chroot there are 2 special directories mounted with the bind
64 option: src and packages. The sources for all packages are stored by default
65 in /home/slitaz/src, this directory is mounted into the chroot so the utils
66 can use them. This method lets you share sources between many chroots such
67 as one for cooking and one for stable. The packages directory default
68 location is: /home/slitaz/[version]/packages so they are not in the chroot
69 and are safe in case the chroot is removed by error.
70 </p>
72 <h3>Getting started</h3>
73 <p>
74 So you have decided the way you want to work, so lets prepare the cook environment.
75 Cook uses the cook.conf configuration file, if you want to use custom paths for
76 SliTaz directories and files, you'll have to modify it. The setup will create
77 some directories and files to keep trace of activity and errors, all files
78 are pure plain text files that you can open in a text editor. To prepare
79 your environment:
80 </p>
81 <pre>
82 # cook setup
83 </pre>
84 <p>
85 The setup command has a --wok option which lets you clone a SliTaz wok while
86 setting up your cook environment. Even if you not yet an official developer
87 you can clone it and use existing packages as an example to create your own.
88 To setup and clone the wok:
89 </p>
90 <pre>
91 # cook setup --wok
92 </pre>
94 <h3>Test your environment</h3>
95 <p>
96 Cook provides a test command which will create a package and cook it. This lets
97 you see if your enviroment is working and it provides an example package with
98 a receipt. The dummy package is named 'cooktest' and can be removed after
99 testing. To cook the cooktest:
100 </p>
101 <pre>
102 # cook test
103 </pre>
105 <h3>Create and cook</h3>
106 <p>
107 If you environment is setup corectly you can start creating and compiling
108 SliTaz packages from your wok. To create a new package with an empty receipt:
109 </p>
110 <pre>
111 # cook new pkgname
112 </pre>
113 <p>
114 If you have just created a new package, you'll have to edit the receipt with your
115 favorite text editor. When the receipt is ready or if you have existing
116 packages, you can cook it:
117 </p>
118 <pre>
119 # cook pkgname
120 </pre>
121 <p>
122 If all went well you will find your packages in the $SLITAZ/packages
123 directory and any produced files in $SLITAZ/wok/pkgname.
124 </p>
126 <h3>Cook and install</h3>
127 <p>
128 If you want to cook and install the package in one command:
129 </p>
130 <pre>
131 # cook pkgname --install
132 </pre>
134 <h3>Get sources</h3>
135 <p>
136 If you want or need to download only the source of a package without
137 building it, you can use the option --getsrc as below:
138 </p>
139 <pre>
140 # cook pkgname --getsrc
141 </pre>
143 <h3>Clean packages</h3>
144 <p>
145 After compilation and packaging there are several files in the wok that take up
146 disk space. To clean a single package:
147 </p>
148 <pre>
149 # cook pkgname --clean
150 </pre>
151 <p>
152 You can also clean the full wok at once or you can choose to keep SliTaz
153 related files and just remove the source:
154 </p>
155 <pre>
156 # cook clean-wok
157 # cook clean-src
158 </pre>
160 <h3>Search</h3>
161 <p>
162 Cook provide a simple search function to quickly find a package in the
163 wok. It use grep and so support regular expressions:
164 </p>
165 <pre>
166 # cook search busybox
167 </pre>
169 <h3>Packages list</h3>
170 <p>
171 Cook can list packages in the wok and also create a suitable packages list
172 for Tazpkg. This lets you create a locale packages repository quite easily
173 and is used to create the official SliTaz packages list found on the mirrors.
174 To list the current wok used by cook (you don't need to be root):
175 </p>
176 <pre>
177 $ cook list-wok
178 </pre>
179 <p>
180 To create a packages list:
181 </p>
182 <pre>
183 # cook pkglist
184 </pre>
186 <a name="cooker"></a>
187 <h3>The Cooker</h3>
188 <p>
189 The Cooker is a Build Bot, its first function is to check for commits in a wok,
190 create an ordered cooklist and cook all modified packages. It can also be
191 used as a frontend to cook since they both use the same files. The Cooker can
192 also be used to cook a big list of packages at once such as all the packages
193 in a flavor. The Cooker provides a nice CGI/Web interface that works by
194 default on any SliTaz system since it provides CGI support via the Busybox httpd
195 web server.
196 </p>
197 <p>
198 The Cooker provides a small built-in help usage and short command switch.
199 For example to display usage you can use:
200 </p>
201 <pre>
202 # cooker usage
203 # cooker -u
204 </pre>
206 <h3>Cooker setup</h3>
207 <p>
208 Like cook, the Cooker needs a working environment before starting to use it.
209 The main difference with the cook environment is that the Cooker needs 2 woks.
210 One Hg and clean wok as a reference and one build wok. In this way it is easy
211 to compare both woks and get modifications. If you already have a cook
212 environment, you must move your wok before setting up the Cooker or it
213 will complain. Setup will also install a set of development packages that
214 can be configured in the cook.conf configuration file and the variable
215 SETUP_PKGS. To setup your cooker environment:
216 </p>
217 <pre>
218 # cooker setup
219 </pre>
220 <p>
221 If all went well you have now 2 woks, base developement packages installed
222 and all needed files created. The default behavior is to check for commits,
223 you can run a test:
224 </p>
225 <pre>
226 # cooker
227 </pre>
229 <h3>Cooker cook</h3>
230 <p>
231 Again, 2 ways to work now: make changes in the clean Hg wok and launch the
232 cooker without any arguments or cook packages manually. The cooker lets you
233 cook a single package or all packages of a category or a flavor. You can also
234 try to build all unbuilt packages, but be aware the Cooker was not designed
235 to handle thousand of packages.
236 </p>
237 <p>
238 To cook a single package which is the same as 'cook pkgname' but with more
239 logs:
240 </p>
241 <pre>
242 # cooker pkg pkgname
243 </pre>
244 <p>
245 To cook more than one package at once you have different kind of choices.
246 You can use an existing package such as used for Live flavors, you can also
247 use a custom list using the package names listed line by line. Finally you can
248 build all packages of a category.
249 </p>
250 <pre>
251 # cooker flavor [name]
252 # cooker list [/path/to/cooklist]
253 # cooker cat [category]
254 </pre>
255 <p>
256 The Cooker let you also recook a specific Hg revision. It usefull in
257 production so if the Build Bot was interupted while cooking commits, you
258 can then cook packages manually:
259 </p>
260 <pre>
261 # cooker rev 9496
262 </pre>
264 <a name="blocked"></a>
265 <h3>Blocked packages</h3>
266 <p>
267 Cook and the Cooker handle a file with a list of blocked package so they will
268 not cook when commits happen or if a cooklist is used. This is very useful
269 for a Cooker Build Bot in production. When you block or unblock a package
270 you can add a note to the cooknotes. Blocking packages example:
271 </p>
272 <pre>
273 # cook pkgname --block
274 # cooker block pkgname
275 # cooker -n "Blocked pkgname note"
276 </pre>
277 <p>
278 The list of blocked packages are also displayed on the Cooker web interface.
279 To unblock a package you have to use the unblock command or cook --unblock
280 option:
281 </p>
282 <pre>
283 # cook pkgname --unblock
284 # cooker unblock pkgname
285 </pre>
287 <h3>Cooker CGI/Web</h3>
288 <p>
289 To let you view log files in a nice way, keep trace of activity and help find
290 errors, you can use the Cooker Web interface located by default in the folder
291 /var/www/cgi-bin/cooker. If you don't use a chroot and the Busybox httpd
292 web server is running, the web interface will work without configuration and
293 should be reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi">
294 http://localhost/cgi-bin/cooker/cooker.cgi</a>
295 </p>
296 <p>
297 If you used a chroot environment, you should also install cookutils on your
298 host and modify the SLITAZ path variable. A standard working way is to have
299 a chroot in:
300 </p>
301 <pre>
302 /home/slitaz/cooking/chroot
303 </pre>
304 <p>
305 With /etc/slitaz/cook.conf modified as below:
306 </p>
307 <pre>
308 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
309 </pre>
310 <p>
311 Note: It's not obligatory to install the cookutils on your host to use the
312 web interface, you can also copy the cooker.cgi and style.css files for
313 example in your ~/Public directory and use a custom cook.conf with it. The
314 advantage of installing cookutils on the host is to get regular updates via
315 the Tazpkg packages manager. Say you have cloned or downloaded the cookutils:
316 </p>
317 <pre>
318 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
319 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
320 </pre>
321 <p>
322 Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set your
323 SLITAZ path and you're all done!
324 </p>
326 <h3>Cooknotes</h3>
327 <p>
328 The cooknotes feature lets you write small personal notes about packaging
329 and is useful for collaboration. The cooknotes was coded to let the SliTaz
330 Cooker bot maintainers share notes between themselves and other contributors.
331 The Cooker can block a package's build or recook packages manually, for example
332 it's nice to make a note if a package is blocked so that the maintainer knows why
333 admin did that. Cooknotes are displayed on the web interface and can be
334 checked from a cmdline:
335 </p>
336 <pre>
337 # cooker note "Blocked pkgname due to heavy CPU load"
338 # cooker notes
339 </pre>
341 <h3>Cooker as a Build Bot</h3>
342 <p>
343 The Cooker is designed to be a Built Bot for SliTaz, this means it monitors
344 2 woks, updates the Hg wok, gets the differences and cooks all packages that
345 have been committed. The safer and cleaner way to run the Cooker as a Build
346 Bot with cron is to use a chroot environment, but it can run directly on the
347 host if you want.
348 </p>
349 <p>
350 To run The Cooker automatically you must use cron from the chroot and add a
351 single line to root crontabs in /var/spool/cron/crontabs. Say you would like
352 to run the Cooker every 2 hours:
353 </p>
354 <pre>
355 */2 * * * * /usr/bin/cooker
356 </pre>
358 <!-- End content -->
359 </div>
361 <div id="footer">
362 Copyright © 2011 SliTaz contributors
363 </div>
365 </body>
366 </html>