cookutils view doc/cookutils.en.html @ rev 525
Add cookiso.conf.
| author | Christopher Rogers <slaxemulator@gmail.com> |
|---|---|
| date | Fri Aug 24 22:05:20 2012 +0000 (2012-08-24) |
| parents | b5f2e3c5d984 |
| children |
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 both share <a href="#blocked">blocked</a>
31 and broken packages as well as any activity.
32 </p>
33 <p>
34 For technical information, for example the coding style, etc, please refer to the
35 README found in the source tree or in /usr/share/doc/cookutils.
36 </p>
38 <h3>Cook usage</h3>
39 <p>
40 Cook provides a small built-in help usage that you can display with the
41 command 'usage'. It also has some options to perform special tasks on
42 a package before cooking it or afterwards. To get help and usage:
43 </p>
44 <pre>
45 # cook usage
46 </pre>
48 <h3>Howto</h3>
49 <p>
50 The first thing you will have to do before building packages is setup
51 your environment. The 2 recommended ways of working: cook directly on host
52 or cook in chroot to protect your host. In the case you want to work in a
53 chroot you can install and use Tazdev to create one and chroot into it:
54 </p>
55 <pre>
56 # tazdev gen-chroot && tazdev chroot
57 </pre>
58 <p>
59 By default Tazdev creates a chroot in /home/slitaz/cooking/chroot but you
60 can specify a custom path in the argument. The chroot location is not
61 important, when you will be in the chroot you will use standard SliTaz
62 paths such as /home/slitaz/wok for the wok directory or /home/slitaz/log
63 for all the cook logs. As usual you can display tazdev help usage with:
64 tazdev usage.
65 </p>
66 <p>
67 When you use a chroot there are 2 special directories mounted with the bind
68 option: src and packages. The sources for all packages are stored by default
69 in /home/slitaz/src, this directory is mounted into the chroot so the utils
70 can use them. This method lets you share sources between many chroots such
71 as one for cooking and one for stable. The packages directory default
72 location is: /home/slitaz/[version]/packages so they are not in the chroot
73 and are safe in case the chroot is removed by error.
74 </p>
76 <h3>Getting started</h3>
77 <p>
78 So you have decided the way you want to work, so lets prepare the cook environment.
79 Cook uses the cook.conf configuration file, if you want to use custom paths for
80 SliTaz directories and files, you'll have to modify it. The setup will create
81 some directories and files to keep trace of activity and errors, all files
82 are pure plain text files that you can open in a text editor. To prepare
83 your environment:
84 </p>
85 <pre>
86 # cook setup
87 </pre>
88 <p>
89 The setup command has a --wok option which lets you clone a SliTaz wok while
90 setting up your cook environment. Even if you are not yet an official developer
91 you can clone it and use existing packages as an example to create your own.
92 To setup and clone the default cooking wok or the undigest wok:
93 </p>
94 <pre>
95 # cook setup --wok
96 # cook setup --undigest
97 </pre>
99 <h3>Test your environment</h3>
100 <p>
101 Cook provides a test command which will create a package and cook it. This lets
102 you see if your environment is working and it provides an example package with
103 a receipt. The dummy package is named 'cooktest' and can be removed after
104 testing. To cook the test package:
105 </p>
106 <pre>
107 # cook test
108 </pre>
110 <h3>Create and cook</h3>
111 <p>
112 If your environment is setup correctly you can start creating and compiling
113 SliTaz packages from your wok. To create a new package with an empty receipt
114 (you can also create a receipt interactively):
115 </p>
116 <pre>
117 # cook new pkgname
118 # cook new pkgname --interactive
119 </pre>
120 <p>
121 If you have just created a new package, you'll have to edit the receipt with your
122 favorite text editor. When the receipt is ready or if you have an existing
123 package, you can cook it:
124 </p>
125 <pre>
126 # cook pkgname
127 </pre>
128 <p>
129 If all went well you will find your package in the $SLITAZ/packages
130 directory and any produced files in $SLITAZ/wok/pkgname.
131 </p>
133 <h3>Cook and install</h3>
134 <p>
135 If you want to cook and install the package in one command:
136 </p>
137 <pre>
138 # cook pkgname --install
139 </pre>
141 <h3>Get sources</h3>
142 <p>
143 If you want or need to download only the source of a package without
144 building it, you can use the option --getsrc as below:
145 </p>
146 <pre>
147 # cook pkgname --getsrc
148 </pre>
150 <h3>Clean packages</h3>
151 <p>
152 After compilation and packaging there are several files in the wok that take up
153 disk space. To clean a single package:
154 </p>
155 <pre>
156 # cook pkgname --clean
157 </pre>
158 <p>
159 You can also clean the full wok at once or you can choose to keep SliTaz
160 related files and just remove the source:
161 </p>
162 <pre>
163 # cook clean-wok
164 # cook clean-src
165 </pre>
167 <h3>Search</h3>
168 <p>
169 Cook provides a simple search function to quickly find a package in the
170 wok. It uses grep and so supports regular expressions:
171 </p>
172 <pre>
173 # cook search busybox
174 </pre>
176 <h3>Unbuild</h3>
177 <p>
178 Unbuild is to provide a list of packages you don't have build based on
179 fullco.txt file. It will echo a list of packages that you have not build:
180 (Note: This also makes a unbuild file in your cache folder.)
181 </p>
182 <pre>
183 # cook unbuild
184 </pre>
185 <p>
186 If you want a more full list with wanted packages use this option:
187 </p>
188 <pre>
189 # cook unbuild --full
190 </pre>
192 <h3>Packages DB list</h3>
193 <p>
194 Cook can list packages in the wok and also create a suitable packages list
195 for Tazpkg. This lets you create a local packages repository quite easily
196 and is used to create the official SliTaz packages list found on the mirrors.
197 To list the current wok used by cook (you don't need to be root):
198 </p>
199 <pre>
200 $ cook list-wok
201 </pre>
202 <p>
203 When creating the packages DB, cook will check if you have a flavors repo in
204 /home/slitaz/flavors, if so, it will pack all flavors using the latest
205 packages list available. To create a packages list and the Live flavors
206 files:
207 </p>
208 <pre>
209 # cook pkgdb
210 </pre>
211 <p>
212 To update DB for incoming or packages do this:
213 </p>
214 <pre>
215 # cook pkgdb incoming
216 # cook pkgdb packages
217 </pre>
219 <p>
220 For the most part pkgdb rebuilds wanted.txt, depends.txt, and libraries.txt.
221 But to build or update fullco.txt in packages you need to do this:
222 </p>
223 <p>
224 NOTE: fullco.txt is the full cookorder to help rebuild slitaz from scratch
225 and slitaz source dvd.
226 </p>
227 <pre>
228 # cook gen-wok-db
229 </pre>
231 <a name="cooker"></a>
232 <h3>The Cooker</h3>
233 <p>
234 The Cooker is a Build Bot, its first function is to check for commits in a wok,
235 create an ordered cooklist and cook all modified packages. It can also be
236 used as a frontend to cook since they both use the same files. The Cooker can
237 also be used to cook a big list of packages at once such as all the packages
238 in a flavor. The Cooker provides a nice CGI/Web interface that works by
239 default on any SliTaz system since it provides CGI support via the Busybox httpd
240 web server.
241 </p>
242 <p>
243 The Cooker provides a small built-in help usage and short command switch.
244 For example to display usage you can use:
245 </p>
246 <pre>
247 # cooker usage
248 # cooker -u
249 </pre>
251 <h3>Cooker setup</h3>
252 <p>
253 Like cook, the Cooker needs a working environment before starting to use it.
254 The main difference with the cook environment is that the Cooker needs 2 woks.
255 One Hg and clean wok as a reference and one build wok. In this way it is easy
256 to compare both woks and get modifications. If you already have a cook
257 environment, you must move your wok before setting up the Cooker or it
258 will complain. Setup will also install a set of development packages that
259 can be configured in the cook.conf configuration file and the variable
260 SETUP_PKGS. To setup your cooker environment:
261 </p>
262 <pre>
263 # cooker setup
264 </pre>
265 <p>
266 If all went well you now have 2 woks, base development packages installed
267 and all needed files created. The default behavior is to check for commits,
268 you can run a test:
269 </p>
270 <pre>
271 # cooker
272 </pre>
274 <h3>Cooker cook</h3>
275 <p>
276 Again, 2 ways to work now: make changes in the clean Hg wok and launch the
277 cooker without any arguments or cook packages manually. The cooker lets you
278 cook a single package or all packages of a category or a flavor. You can also
279 try to build all unbuilt packages, but be aware the Cooker was not designed
280 to handle thousands of packages.
281 </p>
282 <p>
283 To cook a single package which is the same as 'cook pkgname' but with more
284 logs:
285 </p>
286 <pre>
287 # cooker pkg pkgname
288 </pre>
289 <p>
290 To cook more than one package at once you have different kind of choices.
291 You can use an existing package such as used for Live flavors, you can also
292 use a custom list using the package names listed line by line. Finally you can
293 build all packages of a category.
294 </p>
295 <pre>
296 # cooker flavor [name]
297 # cooker list [/path/to/cooklist]
298 # cooker cat [category]
299 </pre>
300 <p>
301 The Cooker lets you also recook a specific Hg revision. It's useful in
302 production so that if the Build Bot was interrupted while cooking commits, you
303 can then cook packages manually:
304 </p>
305 <pre>
306 # cooker rev 9496
307 </pre>
309 <a name="blocked"></a>
310 <h3>Blocked packages</h3>
311 <p>
312 Cook and the Cooker handle a file with a list of blocked package so they will
313 not cook when commits happen or if a cooklist is used. This is very useful
314 for a Cooker Build Bot in production. When you block or unblock a package
315 you can add a note to the cooknotes. Blocking packages example:
316 </p>
317 <pre>
318 # cook pkgname --block
319 # cooker block pkgname
320 # cooker -n "Blocked pkgname note"
321 </pre>
322 <p>
323 The list of blocked packages are also displayed on the Cooker web interface.
324 To unblock a package you have to use the unblock command or cook --unblock
325 option:
326 </p>
327 <pre>
328 # cook pkgname --unblock
329 # cooker unblock pkgname
330 </pre>
332 <h3>Cooker CGI/Web</h3>
333 <p>
334 To let you view log files in a nice way, keep trace of activity and help find
335 errors, you can use the Cooker Web interface located by default in the folder
336 /var/www/cooker. If you don't use a chroot and the Busybox httpd web server
337 is running, the web interface will work without configuration and should be
338 reachable at: <a href="http://localhost/cooker/cooker.cgi">
339 http://localhost/cooker/cooker.cgi</a>
340 </p>
341 <p>
342 If you used a chroot environment, you should also install cookutils on your
343 host and modify the SLITAZ path variable. A standard working way is to have
344 a chroot in:
345 </p>
346 <pre>
347 /home/slitaz/cooking/chroot
348 </pre>
349 <p>
350 With /etc/slitaz/cook.conf modified as below:
351 </p>
352 <pre>
353 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
354 </pre>
355 <p>
356 Note: It's not obligatory to install the cookutils on your host to use the
357 web interface. If you use Lighttpd you can also copy the cooker.cgi and
358 style.css files for example into your ~/Public directory and use a custom
359 cook.conf with it. The advantage of installing cookutils on the host is to
360 get regular updates via the Tazpkg packages manager. Say you have cloned or
361 downloaded the cookutils:
362 </p>
363 <pre>
364 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
365 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
366 </pre>
367 <p>
368 Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set your
369 SLITAZ path and you're all done!
370 </p>
372 <h3>Cooknotes</h3>
373 <p>
374 The cooknotes feature lets you write small personal notes about packaging
375 and is useful for collaboration. The cooknotes was coded to let the SliTaz
376 Cooker bot maintainers share notes between themselves and other contributors.
377 The Cooker can block a package's build or recook packages manually, for example
378 it's nice to make a note if a package is blocked so that the maintainer knows why
379 admin did that. Cooknotes are displayed on the web interface and can be
380 checked from a cmdline:
381 </p>
382 <pre>
383 # cooker note "Blocked pkgname due to heavy CPU load"
384 # cooker notes
385 </pre>
387 <h3>Cooker as a Build Bot</h3>
388 <p>
389 The Cooker is designed to be a Built Bot for SliTaz, this means it monitors
390 2 woks, updates the Hg wok, gets the differences and cooks all packages that
391 have been committed. The safer and cleaner way to run the Cooker as a Build
392 Bot with cron is to use a chroot environment, but it can run directly on the
393 host if you want.
394 </p>
395 <p>
396 To run The Cooker automatically you must use cron from the chroot and add a
397 single line to root crontabs in /var/spool/cron/crontabs. Say you would like
398 to run the Cooker every 2 hours:
399 </p>
400 <pre>
401 * */2 * * * /usr/bin/cooker
402 </pre>
404 <h3>Cooker BB started at boot</h3>
405 <p>
406 The Cooker environment and cron task can automatically be started at boot time.
407 You must have the cookutils-daemon installed on the host and use a standard SliTaz
408 installation to make it work properly (cooking goes in /home/slitaz/cooking). The
409 daemon script will mount any virtual filesystems if needed as well as source and
410 packages. Source files are in /home/slitaz/src and bound into the chroot
411 so you can share package's sources between several versions (stable, cooking,
412 undigest). If the package is not yet installed:
413 </p>
414 <pre>
415 # tazpkg get-install cookutils-daemon
416 </pre>
417 <p>
418 To start the daemon you must have a cron file definition for
419 root in the chroot, the daemon script works like all other system daemons
420 and can be handled with:
421 </p>
422 <pre>
423 # /etc/init.d/cooker [start|stop|restart]
424 </pre>
426 <!-- End content -->
427 </div>
429 <div id="footer">
430 Copyright © 2011 SliTaz contributors
431 </div>
433 </body>
434 </html>