cookutils annotate README @ rev 565

cook: track more errors
author Pascal Bellard <pascal.bellard@slitaz.org>
date Sat Jan 05 18:34:59 2013 +0100 (2013-01-05)
parents 95ba9a892bb4
children 8fbd30a8686a
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@262 28 * Clean chroot even on Ctrl-C
pankso@0 29
pankso@0 30 Cook does not:
pankso@0 31
paul@38 32 * Depend on Hg but can use it to manage a wok
pankso@253 33 * Do complex work like compiling the whole system from source in
paul@256 34 one command (but it can rebuild the full system step by step).
pankso@0 35 * Check build deps for you, use: BUILD_DEPENDS
pankso@0 36 * The work of a Build Bot, unix philosophy: one tool for one task
paul@38 37 * Cook a package if your receipt is crappy :-)
pankso@0 38
pankso@44 39 Cook paths variables used in receipt:
pankso@20 40
pankso@44 41 * $src : Package source: wok/pkg/source
pankso@44 42 * $stuff : Package stuff: wok/pkg/stuff
pankso@44 43 * $fs : Package file system: wok/pkg/taz/*/fs
pankso@44 44 * $install : All installed files by the package
pankso@25 45 Old style is $_pkg and cook is compatible
pankso@20 46
pankso@44 47 Cook internal paths variables:
pankso@44 48
pankso@44 49 * $pkgdir : Package directory in the wok: wok/pkg
pankso@44 50 * $receipt : Package receipt in wok: wok/pkg/receipt
pankso@44 51 * $taz : The taz directory: wok/pkg/taz
pankso@44 52 * $pack : Package to compress: wok/taz/pkg-*
pankso@44 53
paul@38 54 Cook also manages packages lists so they can be used for a personal packages
pankso@0 55 repository or sent to the official mirror. We create and use:
pankso@0 56
paul@38 57 * packages.list Simple list of package-versions
pankso@0 58 * packages.md5 MD5sum list of all packages
pankso@262 59 * packages.txt List of packages with version, desc and sizes
pankso@0 60 * packages.desc Packages with name, version, category, desc
paul@38 61 * packages.equiv Equivalent packages list
paul@38 62 * files.list.lzma A list of files provided by all packages
pankso@0 63
pankso@0 64
pankso@30 65 Cooker
pankso@30 66 --------------------------------------------------------------------------------
pankso@44 67 The Cooker is a Build Bot which automates the build process but doesn't make
paul@382 68 the dinner for you! We need quality receipts to cook successfully and the goal
pankso@44 69 is not to have a bloated script so please Keep It Short and Simple.
pankso@0 70
pankso@0 71 Cmdline tool : /usr/bin/cooker
pankso@261 72 Web interface : /var/www/cooker
pankso@0 73 Cache folder : /home/slitaz/cache
pankso@0 74
paul@38 75 The web interface consists of one CGI script and one CSS style. Cook logs can
paul@38 76 be produced by cook and the cooker just acts as a fronted to check them in
pankso@44 77 a nice way. A web interface also highlights success and error and can show
pankso@44 78 receipts and the cooker logs such as the last ordered list or commits check.
pankso@25 79
pankso@59 80 Database files in the cache folder
pankso@59 81
pankso@59 82 * activity : Activity information for the web interface
pankso@59 83 * blocked : List of manually blocked packages
paul@62 84 * broken : Broken packages list, when cook fails it is added here
pankso@59 85 * commits : List of packages of the last commit check
paul@62 86 * cooklist : Cooklist for unbuilt packages or custom commands
pankso@59 87 * cooknotes : All the notes added with 'cooker -n "My note"
pankso@364 88 * installed* : Lists used to compare installed packages before and after
paul@62 89 a package is cooked so we can remove them
pankso@59 90
paul@256 91 The Cooker web interface can by highly customized through the CSS style and via
paul@256 92 an optional header.html file that must be in the same directory as the CGI
paul@256 93 script, like for style.css and a custom favicon. You can find a header.html
pankso@253 94 example in the data/ directory or in /usr/share/cook if cookutils are installed.
pankso@253 95
pankso@25 96
pankso@317 97 Cookiso
pankso@317 98 -------------------------------------------------------------------------------
paul@325 99 Cookiso is the official tool to automate the ISO build. The goal is to provide
paul@325 100 a simple to use, rock solid tool with a web interface à la Cooker. It shares
paul@325 101 configuration and templates with the Cooker but can be run on its own so it
pankso@317 102 can be used by contributors or customers to automate custom ISO building.
paul@325 103 Cookiso must be run in a chroot which can be the same chroot as the Cooker.
pankso@317 104
paul@325 105 Cookiso is also used to build rolling ISOs by tracking changes in a packages
paul@325 106 list or Hg repository. The rolling command is designed to be run by cron
paul@325 107 in a chroot environment. Here are some usage examples:
pankso@317 108
pankso@317 109 # cookiso setup
pankso@317 110 # cookiso gen --flavors="base justx"
pankso@317 111 # cookiso gen --flavors=base --version=cooking
pankso@317 112
pankso@317 113
pankso@364 114 Cross
pankso@364 115 -------------------------------------------------------------------------------
paul@382 116 See : doc/cross.txt
paul@382 117 Install: make install-cross
paul@382 118 Usage : cross usage
paul@382 119 Howto : cross howto
pankso@364 120
pankso@364 121
pankso@380 122 Cross compiling
pankso@380 123 --------------------------------------------------------------------------------
paul@382 124 Cookutils lets you cross compile a package for a specific architecture. Say you want
paul@382 125 to build ARM binaries from a standard i486 machine. Cookutils provides helpers
pankso@380 126 for the ARM platform, but the first thing to do is compile a cross toolchain and
paul@382 127 modify the main cook.conf variables to use a correct ARCH, CFLAGS and BUILD_SYSTEM
pankso@380 128
paul@495 129 Cook handles HOST_ARCH and CROSS_* receipt variables. Some packages won't build or
paul@382 130 are not packaged for an architecture and so cross compiling will fail if the
paul@382 131 package receipt has not been reviewed and includes HOST_ARCH. Here is an example
pankso@380 132 and a list of cross variables:
pankso@380 133
pankso@380 134 HOST_ARCH="i486 arm"
pankso@380 135 CROSS_BUGS="Bugs description"
pankso@380 136
paul@382 137 Before cross compiling, cook will automatically add cross-tools path to PATH, set
pankso@380 138 CC, AR, LD, etc and also export CROSS_COMPILE.
pankso@380 139
pankso@380 140
pankso@30 141 Toolchain
pankso@30 142 --------------------------------------------------------------------------------
paul@38 143 To rebuild the full SliTaz toolchain at once - cook and the Cooker will use the
paul@38 144 slitaz-toolchain package. No built-in code manages that since it is not a
paul@38 145 common task. The toolchain package will build all needed packages in the correct
paul@38 146 order, which is very important.
pankso@30 147
pankso@30 148
pankso@25 149 Coding style
pankso@30 150 --------------------------------------------------------------------------------
pankso@30 151 Here are the cookutils coding style notes, follow them if you want your code
paul@38 152 included in the package.
pankso@25 153
pankso@30 154 * In all cases: KISS
paul@38 155 * Use tab and not space to indent
pankso@44 156 * Max 80 char by line (try to edit in a Xterm 80x24)
paul@38 157 * Use names rather than $1 $2 $3
paul@38 158 * Variables from config file are $UPPERCASE
pankso@25 159 * Variables initialized by cook are $lowercase
paul@38 160 * Functions can be a single word or use_underline()
pankso@25 161 my_function() {
pankso@25 162 echo "Hello World"
pankso@25 163 }
pankso@25 164 * Use $(command) and not: `command`
paul@38 165 * Cook uses gettext for messages, not the cooker
pankso@25 166 * If you add a feature, add also the doc to explain it
pankso@25 167 * Use clean case with space before case end ;;
pankso@261 168 case "$pkg" in
pankso@261 169 a) echo "Hello World" ;;
pankso@261 170 *) continue ;;
pankso@261 171 esac
paul@214 172 * Make commands and options as short as possible
paul@214 173 * Think to log everything to help debug
paul@214 174 * Quote variables if used in a test: [ "$var" ]
pankso@0 175
pankso@0 176
pankso@0 177 ================================================================================