cookutils diff 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 |
line diff
1.1 --- a/doc/cookutils.en.html Sat May 07 05:34:17 2011 +0200 1.2 +++ b/doc/cookutils.en.html Sat May 07 11:18:47 2011 +0100 1.3 @@ -17,74 +17,74 @@ 1.4 <h2>SliTaz Cook & Cooker</h2> 1.5 1.6 <p> 1.7 - The SliTaz Cookutils provide tools and utils to build SliTaz packages. They 1.8 + The SliTaz Cookutils provide tools and utils to help build SliTaz packages. They 1.9 are easy to use and learn, fast and light. You will be able to create SliTaz 1.10 - in a few commands. The cookutils provide the 'cook' utility and the 1.11 + packages in a few commands. The cookutils provide the 'cook' utility and the 1.12 <a href="#cooker">Cooker</a>. 1.13 </p> 1.14 <p> 1.15 - Cook let you compile and create a package, provide a log file and check 1.16 + Cook lets you compile and create a package, provide a log file and check the 1.17 receipt/package quality. The Cooker is a build bot with more automation 1.18 - and can be used as a frontend to cook, since it provide a CGI/web interface 1.19 - who let you view cook logs in a nice and colored way. Cook and the Cooker 1.20 - use the same DB files and wok, ther share <a href="#blocked">blocked</a> 1.21 - and broken packages as well as activity. 1.22 + and can be used as a frontend to cook, since it provides a CGI/web interface 1.23 + which lets you view cook logs in a nice and colored way. Cook and the Cooker 1.24 + use the same DB files and wok, they share <a href="#blocked">blocked</a> 1.25 + and broken packages as well as any activity. 1.26 </p> 1.27 1.28 <h3>Cook usage</h3> 1.29 <p> 1.30 - Cook provide a small built-in help usage that you can display with the 1.31 - command 'usage'. It also have some options to perform special task on 1.32 - a package, rater before cooking it or after. To get help and usage: 1.33 + Cook provides a small built-in help usage that you can display with the 1.34 + command 'usage'. It also has some options to perform special tasks on 1.35 + a package before cooking it or after. To get help and usage: 1.36 </p> 1.37 <pre> 1.38 # cook usage 1.39 </pre> 1.40 1.41 -<h3>Howto work</h3> 1.42 +<h3>Howto</h3> 1.43 <p> 1.44 - The first thing you will have to do before building packages is to setup 1.45 - your environment. These 2 recommended way to work: cook directly on host 1.46 + The first thing you will have to do before building packages is setup 1.47 + your environment. The 2 recommended ways of working: cook directly on host 1.48 or cook in chroot to protect your host. In the case you want to work in a 1.49 - chroot you can install and use Tazdev to create one and chroot in it: 1.50 + chroot you can install and use Tazdev to create one and chroot into it: 1.51 </p> 1.52 <pre> 1.53 # tazdev gen-chroot && tazdev chroot 1.54 </pre> 1.55 <p> 1.56 - By default Tazdev create a chroot in /home/slitaz/cooking/chroot but you 1.57 - can specify a custome path in argument. The chroot location is not 1.58 + By default Tazdev creates a chroot in /home/slitaz/cooking/chroot but you 1.59 + can specify a custom path in the argument. The chroot location is not 1.60 important, when you will be in the chroot you will use standard SliTaz 1.61 - path such as /home/slitaz/wok for the wok directory or /home/slitaz/log 1.62 + paths such as /home/slitaz/wok for the wok directory or /home/slitaz/log 1.63 for all the cook logs. As usual you can diplay tazdev help usage with: 1.64 tazdev usage. 1.65 </p> 1.66 <p> 1.67 - When you use a chroot they is 2 special directories mounted with the bind 1.68 + When you use a chroot there are 2 special directories mounted with the bind 1.69 option: src and packages. The sources for all packages are stored by default 1.70 in /home/slitaz/src, this directory is mounted into the chroot so the utils 1.71 - can use them. This method let you share sources between many chroots such 1.72 + can use them. This method lets you share sources between many chroots such 1.73 as one for cooking and one for stable. The packages directory default 1.74 location is: /home/slitaz/[version]/packages so they are not in the chroot 1.75 - and safe in case the chroot is removed by error. 1.76 + and are safe in case the chroot is removed by error. 1.77 </p> 1.78 1.79 <h3>Getting started</h3> 1.80 <p> 1.81 - So you decided the way you want to work, so let prepare the cook environement. 1.82 - Cook use cook.conf configuration file, if you want to use custom path for 1.83 - SliTaz directories and files, you have to modify it. The setup will create 1.84 - some directories and files to keep trace on activity and error, all files 1.85 + So you have decided the way you want to work, so lets prepare the cook environment. 1.86 + Cook uses the cook.conf configuration file, if you want to use custom paths for 1.87 + SliTaz directories and files, you'll have to modify it. The setup will create 1.88 + some directories and files to keep trace of activity and errors, all files 1.89 are pure plain text files that you can open in a text editor. To prepare 1.90 - you environment: 1.91 + your environment: 1.92 </p> 1.93 <pre> 1.94 # cook setup 1.95 </pre> 1.96 <p> 1.97 - The setup command have a --wok option who let you clone SliTaz wok while 1.98 - setting up your cook environment. Even if you not yet an official developers 1.99 - you can clone it and use existing packages as example to create your own. 1.100 + The setup command has a --wok option which lets you clone a SliTaz wok while 1.101 + setting up your cook environment. Even if you not yet an official developer 1.102 + you can clone it and use existing packages as an example to create your own. 1.103 To setup and clone the wok: 1.104 </p> 1.105 <pre> 1.106 @@ -93,9 +93,9 @@ 1.107 1.108 <h3>Test your environment</h3> 1.109 <p> 1.110 - Cook provide a test command who will create a package and cook it. This let 1.111 - you see if your enviroment and by the it provide and example package with 1.112 - a receipt. The create package is named 'cooktest' and can be removed after 1.113 + Cook provides a test command which will create a package and cook it. This lets 1.114 + you see if your enviroment is working and it provides an example package with 1.115 + a receipt. The dummy package is named 'cooktest' and can be removed after 1.116 testing. To cook the cooktest: 1.117 </p> 1.118 <pre> 1.119 @@ -111,7 +111,7 @@ 1.120 # cook new pkgname 1.121 </pre> 1.122 <p> 1.123 - If you just created a new package, you have to edit the receipt with your 1.124 + If you have just created a new package, you'll have to edit the receipt with your 1.125 favorite text editor. When the receipt is ready or if you have existing 1.126 packages, you can cook it: 1.127 </p> 1.128 @@ -119,8 +119,8 @@ 1.129 # cook pkgname 1.130 </pre> 1.131 <p> 1.132 - If all went well you will find your packages in $SLITAZ/packages 1.133 - directory and produced files in $SLITAZ/wok/pkgname. 1.134 + If all went well you will find your packages in the $SLITAZ/packages 1.135 + directory and any produced files in $SLITAZ/wok/pkgname. 1.136 </p> 1.137 1.138 <h3>Cook and install</h3> 1.139 @@ -133,8 +133,8 @@ 1.140 1.141 <h3>Get sources</h3> 1.142 <p> 1.143 - If you want or need to download only the sources of a package but without 1.144 - building it, you can use the option --getsrc as bellow: 1.145 + If you want or need to download only the source of a package without 1.146 + building it, you can use the option --getsrc as below: 1.147 </p> 1.148 <pre> 1.149 # cook pkgname --getsrc 1.150 @@ -142,7 +142,7 @@ 1.151 1.152 <h3>Clean packages</h3> 1.153 <p> 1.154 - After compilation and packaging ther is several files in the wok that take 1.155 + After compilation and packaging there are several files in the wok that take up 1.156 disk space. To clean a single package: 1.157 </p> 1.158 <pre> 1.159 @@ -157,18 +157,18 @@ 1.160 # cook clean-src 1.161 </pre> 1.162 1.163 -<h3>Packages lists</h3> 1.164 +<h3>Packages list</h3> 1.165 <p> 1.166 - Cook can list packages in the wok but also create suitable packages list 1.167 - for Tazpkg. That let you create a locale packages repository quiet easily 1.168 - and is used to create official SliTaz packages list found on mirrors. To 1.169 - list the current wok used by cook (you dont need to be root): 1.170 + Cook can list packages in the wok and also create a suitable packages list 1.171 + for Tazpkg. This lets you create a locale packages repository quite easily 1.172 + and is used to create the official SliTaz packages list found on the mirrors. 1.173 + To list the current wok used by cook (you don't need to be root): 1.174 </p> 1.175 <pre> 1.176 $ cook list-wok 1.177 </pre> 1.178 <p> 1.179 - To create packages lists: 1.180 + To create a packages list: 1.181 </p> 1.182 <pre> 1.183 # cook pkglist 1.184 @@ -177,16 +177,16 @@ 1.185 <a name="cooker"></a> 1.186 <h3>The Cooker</h3> 1.187 <p> 1.188 - The Cooker is a Build Bot, it first usage is to check for commits in a wok, 1.189 + The Cooker is a Build Bot, its first function is to check for commits in a wok, 1.190 create an ordered cooklist and cook all modified packages. It can also be 1.191 - used as a frontend to cook since they use the same files. The Cooker can 1.192 - also be used to cook a big list of packages at once such has all package 1.193 - of a flavor. The Cooker provide a nice CGI/Web interface that works by 1.194 - default on any SliTaz system since we provide CGI support via Busybox httpd 1.195 + used as a frontend to cook since they both use the same files. The Cooker can 1.196 + also be used to cook a big list of packages at once such as all the packages 1.197 + in a flavor. The Cooker provides a nice CGI/Web interface that works by 1.198 + default on any SliTaz system since it provides CGI support via the Busybox httpd 1.199 web server. 1.200 </p> 1.201 <p> 1.202 - The Cooker provide a small built-in help usage and short command switch. 1.203 + The Cooker provides a small built-in help usage and short command switch. 1.204 For example to display usage you can use: 1.205 </p> 1.206 <pre> 1.207 @@ -196,11 +196,11 @@ 1.208 1.209 <h3>Cooker setup</h3> 1.210 <p> 1.211 - Like cook, the Cooker needs a working environment before starting using it. 1.212 - The main difference with the cook environment is that the Cooker needs 2 wok. 1.213 - One Hg and clean wok as reference and one build wok, in this way is is easy 1.214 - to compare both wok and get modifications. If you already have a cook 1.215 - environement, you must move your wok before setting up the Cooker or it 1.216 + Like cook, the Cooker needs a working environment before starting to use it. 1.217 + The main difference with the cook environment is that the Cooker needs 2 woks. 1.218 + One Hg and clean wok as a reference and one build wok. In this way it is easy 1.219 + to compare both woks and get modifications. If you already have a cook 1.220 + environment, you must move your wok before setting up the Cooker or it 1.221 will complain. Setup will also install a set of development packages that 1.222 can be configured in the cook.conf configuration file and the variable 1.223 SETUP_PKGS. To setup your cooker environment: 1.224 @@ -209,8 +209,8 @@ 1.225 # cooker setup 1.226 </pre> 1.227 <p> 1.228 - If all went well you have now 2 wok, base developement packages installed 1.229 - and all needed files created. The default behavor is to check for commits, 1.230 + If all went well you have now 2 woks, base developement packages installed 1.231 + and all needed files created. The default behavior is to check for commits, 1.232 you can run a test: 1.233 </p> 1.234 <pre> 1.235 @@ -219,14 +219,14 @@ 1.236 1.237 <h3>Cooker cook</h3> 1.238 <p> 1.239 - Again, 2 way to work now: make change in the clean Hg wok and launch the 1.240 - cooker without any argument or cook packages manually. The cooker let you 1.241 - cook a single package, all packages of a category or a flavor. You can also 1.242 + Again, 2 ways to work now: make changes in the clean Hg wok and launch the 1.243 + cooker without any arguments or cook packages manually. The cooker lets you 1.244 + cook a single package or all packages of a category or a flavor. You can also 1.245 try to build all unbuilt packages, but be aware the Cooker was not designed 1.246 to handle thousand of packages. 1.247 </p> 1.248 <p> 1.249 - To cook a single package wich is the same than 'cook pkgname' but with more 1.250 + To cook a single package which is the same as 'cook pkgname' but with more 1.251 logs: 1.252 </p> 1.253 <pre> 1.254 @@ -234,9 +234,9 @@ 1.255 </pre> 1.256 <p> 1.257 To cook more than one package at once you have different kind of choices. 1.258 - You use an existing package such as used for Live flavors, you can also 1.259 - use a custom list with packages name line by line. Finaly you can build 1.260 - all packages of a category. 1.261 + You can use an existing package such as used for Live flavors, you can also 1.262 + use a custom list using the package names listed line by line. Finally you can 1.263 + build all packages of a category. 1.264 </p> 1.265 <pre> 1.266 # cooker flavor [name] 1.267 @@ -247,8 +247,8 @@ 1.268 <a name="blocked"></a> 1.269 <h3>Blocked packages</h3> 1.270 <p> 1.271 - Cook and the Cooker handle a file with a list of blocked package so they 1.272 - not cook when commits appends or if a cooklist is used. This is very useful 1.273 + Cook and the Cooker handle a file with a list of blocked package so they will 1.274 + not cook when commits happen or if a cooklist is used. This is very useful 1.275 for a Cooker Build Bot in production. When you block or unblock a package 1.276 you can add a note to the cooknotes. Blocking packages example: 1.277 </p> 1.278 @@ -269,9 +269,9 @@ 1.279 1.280 <h3>Cooker CGI/Web</h3> 1.281 <p> 1.282 - To let you view log files in a nice way, keep activity trace and help find 1.283 + To let you view log files in a nice way, keep trace of activity and help find 1.284 errors, you can use the Cooker Web interface located by default in the folder 1.285 - /var/www/cgi-bin/cooker. If you dont use a chroot and the Busybox httpd 1.286 + /var/www/cgi-bin/cooker. If you don't use a chroot and the Busybox httpd 1.287 web server is running, the web interface will work without configuration and 1.288 should be reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi"> 1.289 http://localhost/cgi-bin/cooker/cooker.cgi</a> 1.290 @@ -285,7 +285,7 @@ 1.291 /home/slitaz/cooking/chroot 1.292 </pre> 1.293 <p> 1.294 - With /etc/slitaz/cook.conf modified as bellow: 1.295 + With /etc/slitaz/cook.conf modified as below: 1.296 </p> 1.297 <pre> 1.298 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz" 1.299 @@ -294,27 +294,27 @@ 1.300 Note: It's not obligatory to install the cookutils on your host to use the 1.301 web interface, you can also copy the cooker.cgi and style.css files for 1.302 example in your ~/Public directory and use a custom cook.conf with it. The 1.303 - advantage of installing cookutils on the host is to get regular update via 1.304 - Tazpkg packages manager. Say you have cloned or downloaded the cookutils: 1.305 + advantage of installing cookutils on the host is to get regular updates via 1.306 + the Tazpkg packages manager. Say you have cloned or downloaded the cookutils: 1.307 </p> 1.308 <pre> 1.309 $ cp -a cookutils/web ~/Public/cgi-bin/cooker 1.310 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker 1.311 </pre> 1.312 <p> 1.313 - Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set 1.314 - SLITAZ path and you all done! 1.315 + Edit the configuration file: ~/Public/cgi-bin/cooker/cook.conf to set your 1.316 + SLITAZ path and you're all done! 1.317 </p> 1.318 1.319 <h3>Cooknotes</h3> 1.320 <p> 1.321 - The cooknotes feature let you write small personnal notes about packaging 1.322 - and is usefull for collaboration. The cooknotes was coded to let SliTaz 1.323 - Cooker bot maintainer share notes between them self and other contributors. 1.324 - The Cooker can block packages build or recook packages manually, for example 1.325 - it's nice to make a note if a package is blocked so the maintainer know why 1.326 + The cooknotes feature lets you write small personal notes about packaging 1.327 + and is useful for collaboration. The cooknotes was coded to let the SliTaz 1.328 + Cooker bot maintainers share notes between themselves and other contributors. 1.329 + The Cooker can block a package's build or recook packages manually, for example 1.330 + it's nice to make a note if a package is blocked so that the maintainer knows why 1.331 admin did that. Cooknotes are displayed on the web interface and can be 1.332 - checked from cmdline: 1.333 + checked from a cmdline: 1.334 </p> 1.335 <pre> 1.336 # cooker note "Blocked pkgname due to heavy CPU load"