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