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@382
|
129 Cook handles HOST_ARCH and CROSS_* receipt variables. Some packages don'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 ================================================================================
|