cookutils diff doc/cookutils.en.html @ rev 19
Add documentation (nor only manual but also howto) and put cooker.cgi in a cgi-bin dir so it works with Busybox httpd and LightTPD
| author | Christophe Lincoln <pankso@slitaz.org> |
|---|---|
| date | Thu May 05 21:14:03 2011 +0200 (2011-05-05) |
| parents | |
| children | 90ec7271d772 |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/doc/cookutils.en.html Thu May 05 21:14:03 2011 +0200 1.3 @@ -0,0 +1,229 @@ 1.4 +<!DOCTYPE html> 1.5 +<html xmlns="http://www.w3.org/1999/xhtml"> 1.6 +<head> 1.7 + <title>Cookutils Documentation</title> 1.8 + <meta charset="utf-8" /> 1.9 + <link rel="stylesheet" type="text/css" href="style.css" /> 1.10 +</head> 1.11 +<body> 1.12 + 1.13 +<div id="header"> 1.14 + <h1>Cookutils Documentation</h1> 1.15 +</div> 1.16 + 1.17 +<!-- Start content --> 1.18 +<div id="content"> 1.19 + 1.20 +<h2>SliTaz Cook & Cooker</h2> 1.21 + 1.22 +<p> 1.23 + The SliTaz Cookutils provide tools and utils to build SliTaz packages. They 1.24 + are easy to use and learn, fast and light. You will be able to create SliTaz 1.25 + in a few commands. The cookutils provide the 'cook' utility and the 1.26 + <a href="#cooker">Cooker</a>. 1.27 +</p> 1.28 +<p> 1.29 + Cook let you compile and create a package, provide a log file and check 1.30 + receipt/package quality. The Cooker is a build bot with more automation 1.31 + and can be used as a frontend to cook, since it provide a CGI/web interface 1.32 + who let you view cook logs in a nice and colored way. 1.33 +</p> 1.34 + 1.35 +<h3>Howto work</h3> 1.36 +<p> 1.37 + The first thing you will have to do before building packages is to setup 1.38 + your environment. These 2 recommended way to work: cook directly on host 1.39 + or cook in chroot to protect your host. In the case you want to work in a 1.40 + chroot you can use Tazdev to create one and chroot in it: 1.41 +</p> 1.42 +<pre> 1.43 +# tazdev gen-chroot && tazdev chroot 1.44 +</pre> 1.45 + 1.46 +<h3>Getting started</h3> 1.47 +<p> 1.48 + So you decided the way you want to work, so let prepare the cook environement. 1.49 + Cook use cook.conf configuration file, if you want to use custom path for 1.50 + SliTaz directories and files, you have to modify it. The setup will create 1.51 + some directories and files to keep trace on activity and error, all files 1.52 + are pure plain text files that you can open in a text editor. To prepare 1.53 + you environment: 1.54 +</p> 1.55 +<pre> 1.56 +# cook setup 1.57 +</pre> 1.58 + 1.59 +<h3>Test your environment</h3> 1.60 +<p> 1.61 + Cook provide a test command who will create a package and cook it. This let 1.62 + you see if your enviroment and by the it provide and example package with 1.63 + a receipt. The create package is named 'cooktest' and can be removed after 1.64 + testing. To cook the cooktest: 1.65 +</p> 1.66 +<pre> 1.67 +# cook test 1.68 +</pre> 1.69 + 1.70 +<h3>Create and cook</h3> 1.71 +<p> 1.72 + If you environment is setup corectly you can start creating and compiling 1.73 + SliTaz packages from your wok. To create a new package with an empty receipt: 1.74 +</p> 1.75 +<pre> 1.76 +# cook new pkgname 1.77 +</pre> 1.78 +<p> 1.79 + If you just created a new package, you have to edit the receipt with your 1.80 + favorite text editor. When the receipt is ready or if you have existing 1.81 + packages, you can cook it: 1.82 +</p> 1.83 +<pre> 1.84 +# cook pkgname 1.85 +</pre> 1.86 +<p> 1.87 + If all went well you will find your packages in $SLITAZ/packages 1.88 + directory and produced files in $SLITAZ/wok/pkgname. If you want to cook 1.89 + and install the package in one command: 1.90 +</p> 1.91 +<pre> 1.92 +# cook pkgname --install 1.93 +</pre> 1.94 + 1.95 +<h3>Clean packages</h3> 1.96 +<p> 1.97 + After compilation and packaging ther is several files in the wok that take 1.98 + disk space. To clean a single package: 1.99 +</p> 1.100 +<pre> 1.101 +# cook pkgname --clean 1.102 +</pre> 1.103 +<p> 1.104 + You can also clean the full wok at once or you can choose to keep SliTaz 1.105 + related files and just remove the source: 1.106 +</p> 1.107 +<pre> 1.108 +# cook clean-wok 1.109 +# cook clean-src 1.110 +</pre> 1.111 + 1.112 +<h3>Packages lists</h3> 1.113 +<p> 1.114 + Cook can list packages in the wok but also create suitable packages list 1.115 + for Tazpkg. That let you create a locale packages repository quiet easily 1.116 + and is used to create official SliTaz packages list found on mirrors. To 1.117 + list the current wok used by cook (you dont need to be root): 1.118 +</p> 1.119 +<pre> 1.120 +$ cook list-wok 1.121 +</pre> 1.122 +<p> 1.123 + To create packages lists: 1.124 +</p> 1.125 +<pre> 1.126 +# cook pkglist 1.127 +</pre> 1.128 + 1.129 +<a name="cooker"></a> 1.130 +<h3>The Cooker</h3> 1.131 +<p> 1.132 + The Cooker is a Build Bot, it first usage is to check for commits in a wok, 1.133 + create an ordered cooklist and cook all modified packages. It can also be 1.134 + used as a frontend to cook since they use the same files. The Cooker can 1.135 + also be used to cook a big list of packages at once such has all package 1.136 + of a flavor. The Cooker provide a nice CGI/Web interface that works by 1.137 + default on any SliTaz system since we provide CGI support via Busybox httpd 1.138 + web server. 1.139 +</p> 1.140 + 1.141 +<h3>Cooker setup</h3> 1.142 +<p> 1.143 + Like cook, the Cooker needs a working environment before starting using it. 1.144 + The main difference with the cook environment is that the Cooker needs 2 wok. 1.145 + One Hg and clean wok as reference and one build wok, in this way is is easy 1.146 + to compare both wok and get modifications. If you already have a cook 1.147 + environement, you must move your wok before setting up the Cooker or it 1.148 + will complain: 1.149 +</p> 1.150 +<pre> 1.151 +# cooker --setup 1.152 +</pre> 1.153 +<p> 1.154 + If all went well you have now 2 wok, base developement packages installed 1.155 + and all needed files created. The default behavor is to check for commits, 1.156 + you can run a test: 1.157 +</p> 1.158 +<pre> 1.159 +# cooker 1.160 +</pre> 1.161 + 1.162 +<h3>Cooker cook</h3> 1.163 +<p> 1.164 + Again, 2 way to work now: make change in the clean Hg wok and launch the 1.165 + cooker without any argument or cook packages manually. The cooker let you 1.166 + cook a single package, all packages of a category or a flavor. You can also 1.167 + try to build all unbuilt packages, but be aware the Cooker was not designed 1.168 + to handle thousand of packages. 1.169 +</p> 1.170 +<p> 1.171 + To cook a single package wich is the same than 'cook pkgname' but with more 1.172 + logs: 1.173 +</p> 1.174 +<pre> 1.175 +# cooker --pkg=pkgname 1.176 +</pre> 1.177 +<p> 1.178 + To cook more than one package at once you have different kind of choices. 1.179 + The currently implemeted way (more will come such as --list= --flavor=) 1.180 +</p> 1.181 +<pre> 1.182 +# cooker --cat=pkg-category 1.183 +</pre> 1.184 + 1.185 +<h3>Cooker CGI/Web</h3> 1.186 +<p> 1.187 + To let you view log files in a nice way, keep activity trace and help find 1.188 + errors, you can use the Cooker Web interface located by default in 1.189 + /var/www/cooker. If you dont use a chroot and the Busybox httpd web server 1.190 + is running, the web interface will work without modifiaction and should be 1.191 + reachable at: <a href="http://localhost/cgi-bin/cooker/cooker.cgi"> 1.192 + http://localhost/cgi-bin/cooker/cooker.cgi</a> 1.193 +</p> 1.194 +<p> 1.195 + If you used a chroot environment, you should also install cookutils on your 1.196 + host and modify the SLITAZ path variable. A standard working way is to have 1.197 + a chroot in: 1.198 +</p> 1.199 +<pre> 1.200 +/home/slitaz/cooking/chroot 1.201 +</pre> 1.202 +<p> 1.203 +With /etc/slitaz/cook.conf modified as bellow: 1.204 +</p> 1.205 +<pre> 1.206 +SLITAZ="/home/slitaz/cooking/chroot/home/slitaz" 1.207 +</pre> 1.208 +<p> 1.209 + Note: It's not obligatory to install the cookutils on your host to use the 1.210 + web interface, you can also copy the cooker.cgi and style.css files for 1.211 + example in your ~/Public directory and use a custom cook.conf with it. Say 1.212 + you have cloned or downloaded the cookutils: 1.213 +</p> 1.214 +<pre> 1.215 +$ cp cookutils/web ~/Public/cgi-bin/cooker 1.216 +$ cp cookutils/cook.conf ~/Public/cgi-bin/cooker 1.217 +</pre> 1.218 +<p> 1.219 +Edit ~/Public/cgi-bin/cooker/cook.conf and you all done! 1.220 +</p> 1.221 + 1.222 + 1.223 +<!-- End content --> 1.224 +</div> 1.225 + 1.226 +<div id="footer"> 1.227 + Copyright © 2011 SliTaz contributors 1.228 +</div> 1.229 + 1.230 +</body> 1.231 +</html> 1.232 +