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