cookutils annotate README @ rev 30

README: Add explaination about toolchain
author Christophe Lincoln <pankso@slitaz.org>
date Fri May 06 16:30:47 2011 +0200 (2011-05-06)
parents 0eb341935f31
children a491bec2d20a
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 --------------------------------------------------------------------------------
pankso@0 10 The cook tool should be used in a chroot environment, simply use the command
pankso@0 11 'tazdev gen-chroot' to build one. You can also build package directly but
pankso@0 12 build deps will not be handled correctly since cook will install missing
pankso@0 13 packages to perform a build and then remove them only if there wasn't
pankso@0 14 installed before, this way we can keep a clean build environment.
pankso@0 15
pankso@0 16 We use standard SliTaz path 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
pankso@0 31 * Depends on Hg but can use it to manage a wok
pankso@0 32 * Do complex work about compiling the all 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
pankso@0 36 * Cook a package if you receipt is crappy :-)
pankso@0 37
pankso@20 38 Cook variables used in receipt:
pankso@20 39
pankso@20 40 * $src : Path to package source: wok/pkg/source
pankso@20 41 * $stuff : Path to package stuff: wok/pkg/stuff
pankso@20 42 * $fs : Path to package file system: wok/pkg/taz/*/fs
pankso@20 43 * $install : Path to all installed files by the package
pankso@25 44 Old style is $_pkg and cook is compatible
pankso@20 45
pankso@0 46 Cook also manage packages list so they can be used for a personnal packages
pankso@0 47 repository or sent to the official mirror. We create and use:
pankso@0 48
pankso@0 49 * packages.list Simple list of package-version
pankso@0 50 * packages.md5 MD5sum list of all packages
pankso@0 51 * packages.desc Packages with name, version, category, desc
pankso@0 52 * packages.equiv Equivalent paclages list
pankso@0 53 * files.list.lzma A files provides by all packages
pankso@0 54
pankso@0 55
pankso@30 56 Cooker
pankso@30 57 --------------------------------------------------------------------------------
pankso@0 58 The Cooker is a Build Bot who automate the build process but dont do the diner
pankso@0 59 for you! We need quality receipt to cook succefully and the goal is not to have
pankso@0 60 a bloated script so please Keep It Short and Simple.
pankso@0 61
pankso@0 62 Cmdline tool : /usr/bin/cooker
pankso@20 63 Web interface : /var/www/cgi-bin/cooker
pankso@0 64 Cache folder : /home/slitaz/cache
pankso@0 65
pankso@25 66 The web interface consist in one CGI script and one CSS style. Cook log can
pankso@25 67 are produced by cook and the cooker just act as a fronted to check them in
pankso@25 68 a nice way. Web interface also hightligh success and error, can show receipt
pankso@25 69 and the cooker logs such as the last ordered list or commits check.
pankso@25 70
pankso@25 71
pankso@30 72 Toolchain
pankso@30 73 --------------------------------------------------------------------------------
pankso@30 74 The rebuild the full SliTaz toolchain at once cook and the Cooker will use the
pankso@30 75 slitaz-toolchain package. No built-in code to manage that since it is not a
pankso@30 76 common task. The toolchain package will built all needed package in the correct
pankso@30 77 order, wich is very important.
pankso@30 78
pankso@30 79
pankso@25 80 Coding style
pankso@30 81 --------------------------------------------------------------------------------
pankso@30 82 Here are the cookutils coding style notes, follow them if you want your code
pankso@30 83 include in the package.
pankso@25 84
pankso@30 85 * In all cases: KISS
pankso@25 86 * Use tab and not space to ident
pankso@25 87 * Use name rater than $1 $2 $2
pankso@25 88 * Variables from config file are $UPERCASE
pankso@25 89 * Variables initialized by cook are $lowercase
pankso@25 90 * Function can be a single word or use_underline()
pankso@25 91 my_function() {
pankso@25 92 echo "Hello World"
pankso@25 93 }
pankso@25 94 * Use $(command) and not: `command`
pankso@25 95 * Cook use gettext for messages, not the cooker
pankso@25 96 * If you add a feature, add also the doc to explain it
pankso@25 97 * Use clean case with space before case end ;;
pankso@25 98 case "$pkg" in
pankso@25 99 a) echo "Hello World" ;;
pankso@25 100 *) continue ;;
pankso@25 101 esac
pankso@25 102 * Make commands and options as short as possible
pankso@25 103 * Think to log everything to help debug
pankso@0 104
pankso@0 105
pankso@0 106 ================================================================================