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

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