cookutils view doc/cookutils.en.html @ rev 31
cooker: use command like cook not --options so we can also use short switch, ex: cooker -n 'Add note to cooknotes'
| author | Christophe Lincoln <pankso@slitaz.org> |
|---|---|
| date | Fri May 06 17:05:53 2011 +0200 (2011-05-06) |
| parents | 107f17f16133 |
| children | e1a3c5900648 |
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.
30 </p>
32 <h3>Cook usage</h3>
33 <p>
34 Cook provide a small built-in help usage that you can display with
35 the command:
36 </p>
37 <pre>
38 # cook usage
39 </pre>
41 <h3>Howto work</h3>
42 <p>
43 The first thing you will have to do before building packages is to setup
44 your environment. These 2 recommended way to work: cook directly on host
45 or cook in chroot to protect your host. In the case you want to work in a
46 chroot you can install and use Tazdev to create one and chroot in it:
47 </p>
48 <pre>
49 # tazdev gen-chroot && tazdev chroot
50 </pre>
51 <p>
52 By default Tazdev create a chrrot in /home/slitaz/cooking/chroot but you
53 can specify a custome path in argument. The chroot place is not important,
54 when you will be in the chroot you will use standard SliTaz path such as
55 /home/slitaz/wok for the wok directory or /home/slitaz/log for all the cook
56 logs. As usual you can diplay tazdev help usage with: tazdev usage
57 </p>
59 <h3>Getting started</h3>
60 <p>
61 So you decided the way you want to work, so let prepare the cook environement.
62 Cook use cook.conf configuration file, if you want to use custom path for
63 SliTaz directories and files, you have to modify it. The setup will create
64 some directories and files to keep trace on activity and error, all files
65 are pure plain text files that you can open in a text editor. To prepare
66 you environment:
67 </p>
68 <pre>
69 # cook setup
70 </pre>
71 <p>
72 The setup command have a --wok option who let you clone SliTaz wok while
73 setting up your cook environment. Even if you not yet an official developers
74 you can clone it and use existing packages as example to create your own.
75 To setup and clone the wok:
76 </p>
77 <pre>
78 # cook setup --wok
79 </pre>
81 <h3>Test your environment</h3>
82 <p>
83 Cook provide a test command who will create a package and cook it. This let
84 you see if your enviroment and by the it provide and example package with
85 a receipt. The create package is named 'cooktest' and can be removed after
86 testing. To cook the cooktest:
87 </p>
88 <pre>
89 # cook test
90 </pre>
92 <h3>Create and cook</h3>
93 <p>
94 If you environment is setup corectly you can start creating and compiling
95 SliTaz packages from your wok. To create a new package with an empty receipt:
96 </p>
97 <pre>
98 # cook new pkgname
99 </pre>
100 <p>
101 If you just created a new package, you have to edit the receipt with your
102 favorite text editor. When the receipt is ready or if you have existing
103 packages, you can cook it:
104 </p>
105 <pre>
106 # cook pkgname
107 </pre>
108 <p>
109 If all went well you will find your packages in $SLITAZ/packages
110 directory and produced files in $SLITAZ/wok/pkgname. If you want to cook
111 and install the package in one command:
112 </p>
113 <pre>
114 # cook pkgname --install
115 </pre>
117 <h3>Clean packages</h3>
118 <p>
119 After compilation and packaging ther is several files in the wok that take
120 disk space. To clean a single package:
121 </p>
122 <pre>
123 # cook pkgname --clean
124 </pre>
125 <p>
126 You can also clean the full wok at once or you can choose to keep SliTaz
127 related files and just remove the source:
128 </p>
129 <pre>
130 # cook clean-wok
131 # cook clean-src
132 </pre>
134 <h3>Packages lists</h3>
135 <p>
136 Cook can list packages in the wok but also create suitable packages list
137 for Tazpkg. That let you create a locale packages repository quiet easily
138 and is used to create official SliTaz packages list found on mirrors. To
139 list the current wok used by cook (you dont need to be root):
140 </p>
141 <pre>
142 $ cook list-wok
143 </pre>
144 <p>
145 To create packages lists:
146 </p>
147 <pre>
148 # cook pkglist
149 </pre>
151 <a name="cooker"></a>
152 <h3>The Cooker</h3>
153 <p>
154 The Cooker is a Build Bot, it first usage is to check for commits in a wok,
155 create an ordered cooklist and cook all modified packages. It can also be
156 used as a frontend to cook since they use the same files. The Cooker can
157 also be used to cook a big list of packages at once such has all package
158 of a flavor. The Cooker provide a nice CGI/Web interface that works by
159 default on any SliTaz system since we provide CGI support via Busybox httpd
160 web server.
161 </p>
162 <p>
163 The Cooker provide a small built-in help usage and short command switch.
164 For example to display usage you can use:
165 </p>
166 <pre>
167 # cooker usage
168 # cooker -u
169 </pre>
171 <h3>Cooker setup</h3>
172 <p>
173 Like cook, the Cooker needs a working environment before starting using it.
174 The main difference with the cook environment is that the Cooker needs 2 wok.
175 One Hg and clean wok as reference and one build wok, in this way is is easy
176 to compare both wok and get modifications. If you already have a cook
177 environement, you must move your wok before setting up the Cooker or it
178 will complain. Setup will also install a set of development packages that
179 can be configured in the cook.conf configuration file and the variable
180 SETUP_PKGS. To setup your cooker environment:
181 </p>
182 <pre>
183 # cooker setup
184 </pre>
185 <p>
186 If all went well you have now 2 wok, base developement packages installed
187 and all needed files created. The default behavor is to check for commits,
188 you can run a test:
189 </p>
190 <pre>
191 # cooker
192 </pre>
194 <h3>Cooker cook</h3>
195 <p>
196 Again, 2 way to work now: make change in the clean Hg wok and launch the
197 cooker without any argument or cook packages manually. The cooker let you
198 cook a single package, all packages of a category or a flavor. You can also
199 try to build all unbuilt packages, but be aware the Cooker was not designed
200 to handle thousand of packages.
201 </p>
202 <p>
203 To cook a single package wich is the same than 'cook pkgname' but with more
204 logs:
205 </p>
206 <pre>
207 # cooker pkg pkgname
208 </pre>
209 <p>
210 To cook more than one package at once you have different kind of choices.
211 You use an existing package such as used for Live flavors, you can also
212 use a custom list with packages name line by line. Finaly you can build
213 all packages of a category.
214 </p>
215 <pre>
216 # cooker flavor [name]
217 # cooker list [/path/to/cooklist]
218 # cooker cat [category]
219 </pre>
221 <h3>Cooker CGI/Web</h3>
222 <p>
223 To let you view log files in a nice way, keep activity trace and help find
224 errors, you can use the Cooker Web interface located by default in the folder
225 /var/www/cgi-bin/cooker. If you dont use a chroot and the Busybox httpd
226 web server is running, the web interface will work without configuration and
227 should be reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi">
228 http://localhost/cgi-bin/cooker/cooker.cgi</a>
229 </p>
230 <p>
231 If you used a chroot environment, you should also install cookutils on your
232 host and modify the SLITAZ path variable. A standard working way is to have
233 a chroot in:
234 </p>
235 <pre>
236 /home/slitaz/cooking/chroot
237 </pre>
238 <p>
239 With /etc/slitaz/cook.conf modified as bellow:
240 </p>
241 <pre>
242 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
243 </pre>
244 <p>
245 Note: It's not obligatory to install the cookutils on your host to use the
246 web interface, you can also copy the cooker.cgi and style.css files for
247 example in your ~/Public directory and use a custom cook.conf with it. The
248 advantage of installing cookutils on the host is to get regular update via
249 Tazpkg packages manager. Say you have cloned or downloaded the cookutils:
250 </p>
251 <pre>
252 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
253 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
254 </pre>
255 <p>
256 Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set
257 SLITAZ path and you all done!
258 </p>
260 <h3>Cooknotes</h3>
261 <p>
262 The cooknotes feature let you write small personnal notes about packaging
263 and is usefull for collaboration. The cooknotes was coded to let SliTaz
264 Cooker bot maintainer share notes between them self and other contributors.
265 The Cooker can block packages build or recook packages manually, for example
266 it's nice to make a note if a package is blocked so the maintainer know why
267 admin did that. Cooknotes are displayed on the web interface and can be
268 checked from cmdline:
269 </p>
270 <pre>
271 # cooker note "Blocked pkgname due to heavy CPU load"
272 # cooker notes
273 </pre>
275 <!-- End content -->
276 </div>
278 <div id="footer">
279 Copyright © 2011 SliTaz contributors
280 </div>
282 </body>
283 </html>