cookutils view doc/cookutils.en.html @ rev 49
cook + cooker + doc: add blocked functionality and information
| author | Christophe Lincoln <pankso@slitaz.org> |
|---|---|
| date | Sat May 07 05:34:17 2011 +0200 (2011-05-07) |
| parents | 12fe3e17e20a |
| children | 99f1b17a5659 |
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 build SliTaz packages. They
21 are easy to use and learn, fast and light. You will be able to create SliTaz
22 in a few commands. The cookutils provide the 'cook' utility and the
23 <a href="#cooker">Cooker</a>.
24 </p>
25 <p>
26 Cook let you compile and create a package, provide a log file and check
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 provide a CGI/web interface
29 who let you view cook logs in a nice and colored way. Cook and the Cooker
30 use the same DB files and wok, ther share <a href="#blocked">blocked</a>
31 and broken packages as well as activity.
32 </p>
34 <h3>Cook usage</h3>
35 <p>
36 Cook provide a small built-in help usage that you can display with the
37 command 'usage'. It also have some options to perform special task on
38 a package, rater before cooking it or after. To get help and usage:
39 </p>
40 <pre>
41 # cook usage
42 </pre>
44 <h3>Howto work</h3>
45 <p>
46 The first thing you will have to do before building packages is to setup
47 your environment. These 2 recommended way to work: 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 in it:
50 </p>
51 <pre>
52 # tazdev gen-chroot && tazdev chroot
53 </pre>
54 <p>
55 By default Tazdev create a chroot in /home/slitaz/cooking/chroot but you
56 can specify a custome path in argument. The chroot location is not
57 important, when you will be in the chroot you will use standard SliTaz
58 path 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 they is 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 let 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 safe in case the chroot is removed by error.
70 </p>
72 <h3>Getting started</h3>
73 <p>
74 So you decided the way you want to work, so let prepare the cook environement.
75 Cook use cook.conf configuration file, if you want to use custom path for
76 SliTaz directories and files, you have to modify it. The setup will create
77 some directories and files to keep trace on activity and error, all files
78 are pure plain text files that you can open in a text editor. To prepare
79 you environment:
80 </p>
81 <pre>
82 # cook setup
83 </pre>
84 <p>
85 The setup command have a --wok option who let you clone SliTaz wok while
86 setting up your cook environment. Even if you not yet an official developers
87 you can clone it and use existing packages as 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 provide a test command who will create a package and cook it. This let
97 you see if your enviroment and by the it provide and example package with
98 a receipt. The create 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 just created a new package, you 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 $SLITAZ/packages
123 directory and 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 sources of a package but without
137 building it, you can use the option --getsrc as bellow:
138 </p>
139 <pre>
140 # cook pkgname --getsrc
141 </pre>
143 <h3>Clean packages</h3>
144 <p>
145 After compilation and packaging ther is several files in the wok that take
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>Packages lists</h3>
161 <p>
162 Cook can list packages in the wok but also create suitable packages list
163 for Tazpkg. That let you create a locale packages repository quiet easily
164 and is used to create official SliTaz packages list found on mirrors. To
165 list the current wok used by cook (you dont need to be root):
166 </p>
167 <pre>
168 $ cook list-wok
169 </pre>
170 <p>
171 To create packages lists:
172 </p>
173 <pre>
174 # cook pkglist
175 </pre>
177 <a name="cooker"></a>
178 <h3>The Cooker</h3>
179 <p>
180 The Cooker is a Build Bot, it first usage is to check for commits in a wok,
181 create an ordered cooklist and cook all modified packages. It can also be
182 used as a frontend to cook since they use the same files. The Cooker can
183 also be used to cook a big list of packages at once such has all package
184 of a flavor. The Cooker provide a nice CGI/Web interface that works by
185 default on any SliTaz system since we provide CGI support via Busybox httpd
186 web server.
187 </p>
188 <p>
189 The Cooker provide a small built-in help usage and short command switch.
190 For example to display usage you can use:
191 </p>
192 <pre>
193 # cooker usage
194 # cooker -u
195 </pre>
197 <h3>Cooker setup</h3>
198 <p>
199 Like cook, the Cooker needs a working environment before starting using it.
200 The main difference with the cook environment is that the Cooker needs 2 wok.
201 One Hg and clean wok as reference and one build wok, in this way is is easy
202 to compare both wok and get modifications. If you already have a cook
203 environement, you must move your wok before setting up the Cooker or it
204 will complain. Setup will also install a set of development packages that
205 can be configured in the cook.conf configuration file and the variable
206 SETUP_PKGS. To setup your cooker environment:
207 </p>
208 <pre>
209 # cooker setup
210 </pre>
211 <p>
212 If all went well you have now 2 wok, base developement packages installed
213 and all needed files created. The default behavor is to check for commits,
214 you can run a test:
215 </p>
216 <pre>
217 # cooker
218 </pre>
220 <h3>Cooker cook</h3>
221 <p>
222 Again, 2 way to work now: make change in the clean Hg wok and launch the
223 cooker without any argument or cook packages manually. The cooker let you
224 cook a single package, all packages of a category or a flavor. You can also
225 try to build all unbuilt packages, but be aware the Cooker was not designed
226 to handle thousand of packages.
227 </p>
228 <p>
229 To cook a single package wich is the same than 'cook pkgname' but with more
230 logs:
231 </p>
232 <pre>
233 # cooker pkg pkgname
234 </pre>
235 <p>
236 To cook more than one package at once you have different kind of choices.
237 You use an existing package such as used for Live flavors, you can also
238 use a custom list with packages name line by line. Finaly you can build
239 all packages of a category.
240 </p>
241 <pre>
242 # cooker flavor [name]
243 # cooker list [/path/to/cooklist]
244 # cooker cat [category]
245 </pre>
247 <a name="blocked"></a>
248 <h3>Blocked packages</h3>
249 <p>
250 Cook and the Cooker handle a file with a list of blocked package so they
251 not cook when commits appends or if a cooklist is used. This is very useful
252 for a Cooker Build Bot in production. When you block or unblock a package
253 you can add a note to the cooknotes. Blocking packages example:
254 </p>
255 <pre>
256 # cook pkgname --block
257 # cooker block pkgname
258 # cooker -n "Blocked pkgname note"
259 </pre>
260 <p>
261 The list of blocked packages are also displayed on the Cooker web interface.
262 To unblock a package you have to use the unblock command or cook --unblock
263 option:
264 </p>
265 <pre>
266 # cook pkgname --unblock
267 # cooker unblock pkgname
268 </pre>
270 <h3>Cooker CGI/Web</h3>
271 <p>
272 To let you view log files in a nice way, keep activity trace and help find
273 errors, you can use the Cooker Web interface located by default in the folder
274 /var/www/cgi-bin/cooker. If you dont use a chroot and the Busybox httpd
275 web server is running, the web interface will work without configuration and
276 should be reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi">
277 http://localhost/cgi-bin/cooker/cooker.cgi</a>
278 </p>
279 <p>
280 If you used a chroot environment, you should also install cookutils on your
281 host and modify the SLITAZ path variable. A standard working way is to have
282 a chroot in:
283 </p>
284 <pre>
285 /home/slitaz/cooking/chroot
286 </pre>
287 <p>
288 With /etc/slitaz/cook.conf modified as bellow:
289 </p>
290 <pre>
291 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
292 </pre>
293 <p>
294 Note: It's not obligatory to install the cookutils on your host to use the
295 web interface, you can also copy the cooker.cgi and style.css files for
296 example in your ~/Public directory and use a custom cook.conf with it. The
297 advantage of installing cookutils on the host is to get regular update via
298 Tazpkg packages manager. Say you have cloned or downloaded the cookutils:
299 </p>
300 <pre>
301 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
302 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
303 </pre>
304 <p>
305 Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set
306 SLITAZ path and you all done!
307 </p>
309 <h3>Cooknotes</h3>
310 <p>
311 The cooknotes feature let you write small personnal notes about packaging
312 and is usefull for collaboration. The cooknotes was coded to let SliTaz
313 Cooker bot maintainer share notes between them self and other contributors.
314 The Cooker can block packages build or recook packages manually, for example
315 it's nice to make a note if a package is blocked so the maintainer know why
316 admin did that. Cooknotes are displayed on the web interface and can be
317 checked from cmdline:
318 </p>
319 <pre>
320 # cooker note "Blocked pkgname due to heavy CPU load"
321 # cooker notes
322 </pre>
324 <!-- End content -->
325 </div>
327 <div id="footer">
328 Copyright © 2011 SliTaz contributors
329 </div>
331 </body>
332 </html>