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

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