cookutils annotate README @ rev 59

doc + README: add info about build bot and cron as well as DB files in cache
author Christophe Lincoln <pankso@slitaz.org>
date Sat May 07 14:33:44 2011 +0200 (2011-05-07)
parents 969f0ec4eeac
children c49e394e87d3
rev   line source
pankso@0 1 SliTaz Cookutils
pankso@0 2 ================================================================================
pankso@0 3
pankso@0 4
pankso@0 5 The SliTaz Cookutils provide tools and utils to build SliTaz packages.
pankso@0 6
pankso@0 7
pankso@30 8 Cook
pankso@30 9 --------------------------------------------------------------------------------
paul@38 10 The cook tool should be used in a chroot environment: simply use the command
paul@38 11 'tazdev gen-chroot' to build one. You can also build packages directly but
pankso@0 12 build deps will not be handled correctly since cook will install missing
paul@38 13 packages to perform a build and then remove them only if they were not
pankso@0 14 installed before, this way we can keep a clean build environment.
pankso@0 15
paul@38 16 We use standard SliTaz paths to work such as /home/slitaz/wok, if you work on
pankso@0 17 cooking from stable or want to keep a clean system: create a chroot.
pankso@0 18
pankso@0 19 Cook features:
pankso@0 20
pankso@0 21 * Setup a build env
pankso@0 22 * Check and install missing build deps
pankso@0 23 * Compile and generate the package
pankso@0 24 * Remove installed build deps
pankso@0 25 * Provide a log for each cook
pankso@25 26 * Clean one or all packages in the wok
pankso@25 27 * Check for receipt and package quality
pankso@0 28
pankso@0 29 Cook does not:
pankso@0 30
paul@38 31 * Depend on Hg but can use it to manage a wok
paul@38 32 * Do complex work like compiling the whole system from source
pankso@0 33 * Check build deps for you, use: BUILD_DEPENDS
pankso@0 34 If all deps are also build deps do: BUILD_DEPENDS="$DEPENDS"
pankso@0 35 * The work of a Build Bot, unix philosophy: one tool for one task
paul@38 36 * Cook a package if your receipt is crappy :-)
pankso@0 37
pankso@44 38 Cook paths variables used in receipt:
pankso@20 39
pankso@44 40 * $src : Package source: wok/pkg/source
pankso@44 41 * $stuff : Package stuff: wok/pkg/stuff
pankso@44 42 * $fs : Package file system: wok/pkg/taz/*/fs
pankso@44 43 * $install : All installed files by the package
pankso@25 44 Old style is $_pkg and cook is compatible
pankso@20 45
pankso@44 46 Cook internal paths variables:
pankso@44 47
pankso@44 48 * $pkgdir : Package directory in the wok: wok/pkg
pankso@44 49 * $receipt : Package receipt in wok: wok/pkg/receipt
pankso@44 50 * $taz : The taz directory: wok/pkg/taz
pankso@44 51 * $pack : Package to compress: wok/taz/pkg-*
pankso@44 52
paul@38 53 Cook also manages packages lists so they can be used for a personal packages
pankso@0 54 repository or sent to the official mirror. We create and use:
pankso@0 55
paul@38 56 * packages.list Simple list of package-versions
pankso@0 57 * packages.md5 MD5sum list of all packages
pankso@0 58 * packages.desc Packages with name, version, category, desc
paul@38 59 * packages.equiv Equivalent packages list
paul@38 60 * files.list.lzma A list of files provided by all packages
pankso@0 61
pankso@0 62
pankso@30 63 Cooker
pankso@30 64 --------------------------------------------------------------------------------
pankso@44 65 The Cooker is a Build Bot which automates the build process but doesn't make
pankso@44 66 the dinner for you! We need quality receipts to cook succesfully and the goal
pankso@44 67 is not to have a bloated script so please Keep It Short and Simple.
pankso@0 68
pankso@0 69 Cmdline tool : /usr/bin/cooker
pankso@20 70 Web interface : /var/www/cgi-bin/cooker
pankso@0 71 Cache folder : /home/slitaz/cache
pankso@0 72
paul@38 73 The web interface consists of one CGI script and one CSS style. Cook logs can
paul@38 74 be produced by cook and the cooker just acts as a fronted to check them in
pankso@44 75 a nice way. A web interface also highlights success and error and can show
pankso@44 76 receipts and the cooker logs such as the last ordered list or commits check.
pankso@25 77
pankso@59 78 Database files in the cache folder
pankso@59 79
pankso@59 80 * activity : Activity information for the web interface
pankso@59 81 * blocked : List of manually blocked packages
pankso@59 82 * broken : Broken packages list when cook fail it is add here
pankso@59 83 * commits : List of packages of the last commit check
pankso@59 84 * cooklist : Cooklist for unbuild packages or custom command
pankso@59 85 * cooknotes : All the notes added with 'cooker -n "My note"
pankso@59 86 * installed* : Lists used to compare installed package before a package
pankso@59 87 is cooked and after so we can remove them.
pankso@59 88
pankso@25 89
pankso@30 90 Toolchain
pankso@30 91 --------------------------------------------------------------------------------
paul@38 92 To rebuild the full SliTaz toolchain at once - cook and the Cooker will use the
paul@38 93 slitaz-toolchain package. No built-in code manages that since it is not a
paul@38 94 common task. The toolchain package will build all needed packages in the correct
paul@38 95 order, which is very important.
pankso@30 96
pankso@30 97
pankso@25 98 Coding style
pankso@30 99 --------------------------------------------------------------------------------
pankso@30 100 Here are the cookutils coding style notes, follow them if you want your code
paul@38 101 included in the package.
pankso@25 102
pankso@30 103 * In all cases: KISS
paul@38 104 * Use tab and not space to indent
pankso@44 105 * Max 80 char by line (try to edit in a Xterm 80x24)
paul@38 106 * Use names rather than $1 $2 $3
paul@38 107 * Variables from config file are $UPPERCASE
pankso@25 108 * Variables initialized by cook are $lowercase
paul@38 109 * Functions can be a single word or use_underline()
pankso@25 110 my_function() {
pankso@25 111 echo "Hello World"
pankso@25 112 }
pankso@25 113 * Use $(command) and not: `command`
paul@38 114 * Cook uses gettext for messages, not the cooker
pankso@25 115 * If you add a feature, add also the doc to explain it
pankso@25 116 * Use clean case with space before case end ;;
pankso@25 117 case "$pkg" in
pankso@25 118 a) echo "Hello World" ;;
pankso@25 119 *) continue ;;
pankso@25 120 esac
pankso@25 121 * Make commands and options as short as possible
pankso@25 122 * Think to log everything to help debug
pankso@0 123
pankso@0 124
pankso@0 125 ================================================================================