cookutils annotate doc/cookutils.en.html @ rev 53

Edit en.html
author Paul Issott <paul@slitaz.org>
date Sat May 07 11:18:47 2011 +0100 (2011-05-07)
parents 7281d806c7ea
children e72b406b4f0c
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 &amp; Cooker</h2>
pankso@19 18
pankso@19 19 <p>
paul@53 20 The SliTaz Cookutils provide tools and utils to help build SliTaz packages. They
pankso@19 21 are easy to use and learn, fast and light. You will be able to create SliTaz
paul@53 22 packages 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>
paul@53 26 Cook lets you compile and create a package, provide a log file and check the
pankso@19 27 receipt/package quality. The Cooker is a build bot with more automation
paul@53 28 and can be used as a frontend to cook, since it provides a CGI/web interface
paul@53 29 which lets you view cook logs in a nice and colored way. Cook and the Cooker
paul@53 30 use the same DB files and wok, they share <a href="#blocked">blocked</a>
paul@53 31 and broken packages as well as any activity.
pankso@19 32 </p>
pankso@19 33
pankso@27 34 <h3>Cook usage</h3>
pankso@27 35 <p>
paul@53 36 Cook provides a small built-in help usage that you can display with the
paul@53 37 command 'usage'. It also has some options to perform special tasks on
paul@53 38 a package before cooking it or after. To get help and usage:
pankso@27 39 </p>
pankso@27 40 <pre>
pankso@27 41 # cook usage
pankso@27 42 </pre>
pankso@27 43
paul@53 44 <h3>Howto</h3>
pankso@19 45 <p>
paul@53 46 The first thing you will have to do before building packages is setup
paul@53 47 your environment. The 2 recommended ways of working: cook directly on host
pankso@19 48 or cook in chroot to protect your host. In the case you want to work in a
paul@53 49 chroot you can install and use Tazdev to create one and chroot into it:
pankso@19 50 </p>
pankso@19 51 <pre>
pankso@19 52 # tazdev gen-chroot &amp;&amp; tazdev chroot
pankso@19 53 </pre>
pankso@27 54 <p>
paul@53 55 By default Tazdev creates a chroot in /home/slitaz/cooking/chroot but you
paul@53 56 can specify a custom path in the argument. The chroot location is not
pankso@40 57 important, when you will be in the chroot you will use standard SliTaz
paul@53 58 paths such as /home/slitaz/wok for the wok directory or /home/slitaz/log
pankso@40 59 for all the cook logs. As usual you can diplay tazdev help usage with:
pankso@40 60 tazdev usage.
pankso@40 61 </p>
pankso@40 62 <p>
paul@53 63 When you use a chroot there are 2 special directories mounted with the bind
pankso@40 64 option: src and packages. The sources for all packages are stored by default
pankso@40 65 in /home/slitaz/src, this directory is mounted into the chroot so the utils
paul@53 66 can use them. This method lets you share sources between many chroots such
pankso@40 67 as one for cooking and one for stable. The packages directory default
pankso@40 68 location is: /home/slitaz/[version]/packages so they are not in the chroot
paul@53 69 and are safe in case the chroot is removed by error.
pankso@27 70 </p>
pankso@19 71
pankso@19 72 <h3>Getting started</h3>
pankso@19 73 <p>
paul@53 74 So you have decided the way you want to work, so lets prepare the cook environment.
paul@53 75 Cook uses the cook.conf configuration file, if you want to use custom paths for
paul@53 76 SliTaz directories and files, you'll have to modify it. The setup will create
paul@53 77 some directories and files to keep trace of activity and errors, all files
pankso@19 78 are pure plain text files that you can open in a text editor. To prepare
paul@53 79 your environment:
pankso@19 80 </p>
pankso@19 81 <pre>
pankso@19 82 # cook setup
pankso@19 83 </pre>
pankso@27 84 <p>
paul@53 85 The setup command has a --wok option which lets you clone a SliTaz wok while
paul@53 86 setting up your cook environment. Even if you not yet an official developer
paul@53 87 you can clone it and use existing packages as an example to create your own.
pankso@27 88 To setup and clone the wok:
pankso@27 89 </p>
pankso@27 90 <pre>
pankso@27 91 # cook setup --wok
pankso@27 92 </pre>
pankso@19 93
pankso@19 94 <h3>Test your environment</h3>
pankso@19 95 <p>
paul@53 96 Cook provides a test command which will create a package and cook it. This lets
paul@53 97 you see if your enviroment is working and it provides an example package with
paul@53 98 a receipt. The dummy package is named 'cooktest' and can be removed after
pankso@19 99 testing. To cook the cooktest:
pankso@19 100 </p>
pankso@19 101 <pre>
pankso@19 102 # cook test
pankso@19 103 </pre>
pankso@19 104
pankso@19 105 <h3>Create and cook</h3>
pankso@19 106 <p>
pankso@19 107 If you environment is setup corectly you can start creating and compiling
pankso@19 108 SliTaz packages from your wok. To create a new package with an empty receipt:
pankso@19 109 </p>
pankso@19 110 <pre>
pankso@19 111 # cook new pkgname
pankso@19 112 </pre>
pankso@19 113 <p>
paul@53 114 If you have just created a new package, you'll have to edit the receipt with your
pankso@19 115 favorite text editor. When the receipt is ready or if you have existing
pankso@19 116 packages, you can cook it:
pankso@19 117 </p>
pankso@19 118 <pre>
pankso@19 119 # cook pkgname
pankso@19 120 </pre>
pankso@19 121 <p>
paul@53 122 If all went well you will find your packages in the $SLITAZ/packages
paul@53 123 directory and any produced files in $SLITAZ/wok/pkgname.
pankso@39 124 </p>
pankso@39 125
pankso@39 126 <h3>Cook and install</h3>
pankso@39 127 <p>
pankso@39 128 If you want to cook and install the package in one command:
pankso@19 129 </p>
pankso@19 130 <pre>
pankso@19 131 # cook pkgname --install
pankso@19 132 </pre>
pankso@19 133
pankso@39 134 <h3>Get sources</h3>
pankso@39 135 <p>
paul@53 136 If you want or need to download only the source of a package without
paul@53 137 building it, you can use the option --getsrc as below:
pankso@39 138 </p>
pankso@39 139 <pre>
pankso@39 140 # cook pkgname --getsrc
pankso@39 141 </pre>
pankso@39 142
pankso@19 143 <h3>Clean packages</h3>
pankso@19 144 <p>
paul@53 145 After compilation and packaging there are several files in the wok that take up
pankso@19 146 disk space. To clean a single package:
pankso@19 147 </p>
pankso@19 148 <pre>
pankso@19 149 # cook pkgname --clean
pankso@19 150 </pre>
pankso@19 151 <p>
pankso@19 152 You can also clean the full wok at once or you can choose to keep SliTaz
pankso@19 153 related files and just remove the source:
pankso@19 154 </p>
pankso@19 155 <pre>
pankso@19 156 # cook clean-wok
pankso@19 157 # cook clean-src
pankso@19 158 </pre>
pankso@19 159
paul@53 160 <h3>Packages list</h3>
pankso@19 161 <p>
paul@53 162 Cook can list packages in the wok and also create a suitable packages list
paul@53 163 for Tazpkg. This lets you create a locale packages repository quite easily
paul@53 164 and is used to create the official SliTaz packages list found on the mirrors.
paul@53 165 To list the current wok used by cook (you don't need to be root):
pankso@19 166 </p>
pankso@19 167 <pre>
pankso@19 168 $ cook list-wok
pankso@19 169 </pre>
pankso@19 170 <p>
paul@53 171 To create a packages list:
pankso@19 172 </p>
pankso@19 173 <pre>
pankso@19 174 # cook pkglist
pankso@19 175 </pre>
pankso@19 176
pankso@19 177 <a name="cooker"></a>
pankso@19 178 <h3>The Cooker</h3>
pankso@19 179 <p>
paul@53 180 The Cooker is a Build Bot, its first function is to check for commits in a wok,
pankso@19 181 create an ordered cooklist and cook all modified packages. It can also be
paul@53 182 used as a frontend to cook since they both use the same files. The Cooker can
paul@53 183 also be used to cook a big list of packages at once such as all the packages
paul@53 184 in a flavor. The Cooker provides a nice CGI/Web interface that works by
paul@53 185 default on any SliTaz system since it provides CGI support via the Busybox httpd
pankso@19 186 web server.
pankso@19 187 </p>
pankso@27 188 <p>
paul@53 189 The Cooker provides a small built-in help usage and short command switch.
pankso@31 190 For example to display usage you can use:
pankso@27 191 </p>
pankso@27 192 <pre>
pankso@31 193 # cooker usage
pankso@31 194 # cooker -u
pankso@27 195 </pre>
pankso@19 196
pankso@19 197 <h3>Cooker setup</h3>
pankso@19 198 <p>
paul@53 199 Like cook, the Cooker needs a working environment before starting to use it.
paul@53 200 The main difference with the cook environment is that the Cooker needs 2 woks.
paul@53 201 One Hg and clean wok as a reference and one build wok. In this way it is easy
paul@53 202 to compare both woks and get modifications. If you already have a cook
paul@53 203 environment, you must move your wok before setting up the Cooker or it
pankso@31 204 will complain. Setup will also install a set of development packages that
pankso@31 205 can be configured in the cook.conf configuration file and the variable
pankso@31 206 SETUP_PKGS. To setup your cooker environment:
pankso@19 207 </p>
pankso@19 208 <pre>
pankso@31 209 # cooker setup
pankso@19 210 </pre>
pankso@19 211 <p>
paul@53 212 If all went well you have now 2 woks, base developement packages installed
paul@53 213 and all needed files created. The default behavior is to check for commits,
pankso@19 214 you can run a test:
pankso@19 215 </p>
pankso@19 216 <pre>
pankso@19 217 # cooker
pankso@19 218 </pre>
pankso@19 219
pankso@19 220 <h3>Cooker cook</h3>
pankso@19 221 <p>
paul@53 222 Again, 2 ways to work now: make changes in the clean Hg wok and launch the
paul@53 223 cooker without any arguments or cook packages manually. The cooker lets you
paul@53 224 cook a single package or all packages of a category or a flavor. You can also
pankso@19 225 try to build all unbuilt packages, but be aware the Cooker was not designed
pankso@19 226 to handle thousand of packages.
pankso@19 227 </p>
pankso@19 228 <p>
paul@53 229 To cook a single package which is the same as 'cook pkgname' but with more
pankso@19 230 logs:
pankso@19 231 </p>
pankso@19 232 <pre>
pankso@31 233 # cooker pkg pkgname
pankso@19 234 </pre>
pankso@19 235 <p>
pankso@19 236 To cook more than one package at once you have different kind of choices.
paul@53 237 You can use an existing package such as used for Live flavors, you can also
paul@53 238 use a custom list using the package names listed line by line. Finally you can
paul@53 239 build all packages of a category.
pankso@19 240 </p>
pankso@19 241 <pre>
pankso@31 242 # cooker flavor [name]
pankso@31 243 # cooker list [/path/to/cooklist]
pankso@31 244 # cooker cat [category]
pankso@19 245 </pre>
pankso@19 246
pankso@49 247 <a name="blocked"></a>
pankso@49 248 <h3>Blocked packages</h3>
pankso@49 249 <p>
paul@53 250 Cook and the Cooker handle a file with a list of blocked package so they will
paul@53 251 not cook when commits happen or if a cooklist is used. This is very useful
pankso@49 252 for a Cooker Build Bot in production. When you block or unblock a package
pankso@49 253 you can add a note to the cooknotes. Blocking packages example:
pankso@49 254 </p>
pankso@49 255 <pre>
pankso@49 256 # cook pkgname --block
pankso@49 257 # cooker block pkgname
pankso@49 258 # cooker -n "Blocked pkgname note"
pankso@49 259 </pre>
pankso@49 260 <p>
pankso@49 261 The list of blocked packages are also displayed on the Cooker web interface.
pankso@49 262 To unblock a package you have to use the unblock command or cook --unblock
pankso@49 263 option:
pankso@49 264 </p>
pankso@49 265 <pre>
pankso@49 266 # cook pkgname --unblock
pankso@49 267 # cooker unblock pkgname
pankso@49 268 </pre>
pankso@49 269
pankso@19 270 <h3>Cooker CGI/Web</h3>
pankso@19 271 <p>
paul@53 272 To let you view log files in a nice way, keep trace of activity and help find
pankso@27 273 errors, you can use the Cooker Web interface located by default in the folder
paul@53 274 /var/www/cgi-bin/cooker. If you don't use a chroot and the Busybox httpd
pankso@27 275 web server is running, the web interface will work without configuration and
pankso@27 276 should be reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi">
pankso@19 277 http://localhost/cgi-bin/cooker/cooker.cgi</a>
pankso@19 278 </p>
pankso@19 279 <p>
pankso@19 280 If you used a chroot environment, you should also install cookutils on your
pankso@19 281 host and modify the SLITAZ path variable. A standard working way is to have
pankso@19 282 a chroot in:
pankso@19 283 </p>
pankso@19 284 <pre>
pankso@19 285 /home/slitaz/cooking/chroot
pankso@19 286 </pre>
pankso@19 287 <p>
paul@53 288 With /etc/slitaz/cook.conf modified as below:
pankso@19 289 </p>
pankso@19 290 <pre>
pankso@19 291 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
pankso@19 292 </pre>
pankso@19 293 <p>
pankso@19 294 Note: It's not obligatory to install the cookutils on your host to use the
pankso@19 295 web interface, you can also copy the cooker.cgi and style.css files for
pankso@27 296 example in your ~/Public directory and use a custom cook.conf with it. The
paul@53 297 advantage of installing cookutils on the host is to get regular updates via
paul@53 298 the Tazpkg packages manager. Say you have cloned or downloaded the cookutils:
pankso@19 299 </p>
pankso@19 300 <pre>
pankso@27 301 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
pankso@27 302 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
pankso@19 303 </pre>
pankso@19 304 <p>
paul@53 305 Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set your
paul@53 306 SLITAZ path and you're all done!
pankso@19 307 </p>
pankso@19 308
pankso@24 309 <h3>Cooknotes</h3>
pankso@24 310 <p>
paul@53 311 The cooknotes feature lets you write small personal notes about packaging
paul@53 312 and is useful for collaboration. The cooknotes was coded to let the SliTaz
paul@53 313 Cooker bot maintainers share notes between themselves and other contributors.
paul@53 314 The Cooker can block a package's build or recook packages manually, for example
paul@53 315 it's nice to make a note if a package is blocked so that the maintainer knows why
pankso@24 316 admin did that. Cooknotes are displayed on the web interface and can be
paul@53 317 checked from a cmdline:
pankso@24 318 </p>
pankso@24 319 <pre>
pankso@31 320 # cooker note "Blocked pkgname due to heavy CPU load"
pankso@31 321 # cooker notes
pankso@24 322 </pre>
pankso@19 323
pankso@19 324 <!-- End content -->
pankso@19 325 </div>
pankso@19 326
pankso@19 327 <div id="footer">
pankso@19 328 Copyright &copy; 2011 SliTaz contributors
pankso@19 329 </div>
pankso@19 330
pankso@19 331 </body>
pankso@19 332 </html>
pankso@19 333