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