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

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