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