cookutils view doc/receipts-v2.md @ rev 1150
Show recent broken packages first
| author | Pascal Bellard <pascal.bellard@slitaz.org> |
|---|---|
| date | Sat Feb 19 15:32:45 2022 +0000 (2022-02-19) |
| parents | dc7238a11470 |
| children |
line source
1 Brief info about SliTaz receipts v2
2 ===================================
4 Version 2 was developed as an extension of the receipts in order to facilitate
5 the maintenance of packages by small forces.
7 In order to switch to version 2, you must specify 'v2' in the first line of the
8 receipt:
10 ```bash
11 # SliTaz package receipt v2.
12 ```
14 You can write the single receipt v2 to compile, for example `attr` sources and
15 then make two packages: `attr` and `attr-dev` using compiled files. Next we will
16 call `attr` the *main package*, while `attr-dev` -- the *split package*.
18 You must specify all the names of *split packages* that must be created after
19 the compilation in the SPLIT variable. Example for our `attr` receipt:
21 ```bash
22 SPLIT="attr-dev"
23 ```
25 You must specify rules to generate each package inside the genpkg_rules().
26 Example for package `attr`:
28 ```bash
29 genpkg_rules() {
30 case $PACKAGE in
31 attr) copy @std ;;
32 attr-dev) copy @dev ;;
33 esac
34 }
35 ```
37 Here, in every rule you can:
39 * use the `copy()` function or other methods to copy specified files from
40 $install to $fs.
41 * define the DEPENDS variable for specified packages; you may omit this
42 definition, then it will mean the following:
43 * for the *main package*: it doesn't depend on any package;
44 * for the *split packages*: it depends exclusively on a *main package*.
45 Note, a receipt is the shell script with all its restrictions: there's no
46 difference if you define an empty DEPENDS variable or do not define it at all.
47 Here's the small trick: if you really want to define empty dependencies,
48 put single spaces between the quotes: `DEPENDS=" "`.
49 * define the two-in-one CAT variable for *split packages*. Variable format:
51 ```bash
52 CAT="category|addition"
53 ```
55 Where `category` is just the chosen category for the specified *split
56 package*. And `addition` you will find in the brackets at the end of a
57 short description of the specified *split package*. You may omit this
58 definition for the "dev" packages. In this case it will be implicitly
59 defined as:
61 ```bash
62 CAT="development|development files"
63 ```
64 * define some other variables, like COOKOPTS.
67 Long descriptions
68 -----------------
70 You may provide a `description.txt` for the *main package* and/or
71 `description.package-name.txt` for any of the *split packages*.
74 `post_install()` and friends
75 ----------------------------
77 You may define one of the following functions:
79 * `pre_install()`;
80 * `post_install()`;
81 * `pre_remove()`;
82 * `post_remove()`.
84 These functions may be defined for every one of *main* or *split packages*, so
85 you need to extend function names with underscores (`_`) and the package name.
86 Like this for the `cookutils` package:
88 post_install_cookutils()
90 Attention! You should know that some characters that are valid in package names
91 are not allowed in function names. Please, substitute each symbol that doesn't
92 belong to the intervals `A-Z, a-z, 0-9` by yet another underscore (`_`).
93 Example for `coreutils-disk`:
95 post_install_coreutils_disk()
98 Function `copy()`
99 -----------------
101 It's the flexible tool allowing you to copy files and folders from `$install` to
102 `$fs` using patterns. All files are copied with the folder structure preserved:
104 $install/my/folder/ -> $fs/my/folder/
105 $install/my/system/file -> $fs/my/system/file
107 Now `copy()` understands 4 main forms of patterns:
109 * `@std` - all the "standard" files;
110 * `@dev` - all the "developer" files;
111 * `folder/` - append folder name in question by slash;
112 * `file` - file name without the slash at the end.
114 Both patterns `@std` and `@dev` are meta-patterns making the most common actions
115 extremely simple. Here all files are divided into three types: standard,
116 development and all the others (documentation, translations, etc). You may put
117 `@std` into "standard" package, `@dev` into "developer" package, not packaging
118 any documentation, man pages, translations, BASH completion, etc...
120 In the `folder/` and `file` forms of the patterns you can use the asterisk (`*`)
121 symbol meaning any number of any characters.
123 Some examples (executed in the chroot with the "busybox" package installed):
125 Pattern | Result
126 -----------|--------------------------------------------------------------------
127 ` bin/ `|`/bin`<br>`/usr/bin`
128 ` *bin/ `|`/bin`<br>`/sbin`<br>`/usr/bin`<br>`/usr/sbin`<br>`/var/www/cgi-bin`
129 `/usr/bin/`|`/usr/bin`
130 ` usr/bin/`|`/usr/bin`
131 ` r/bin/`|` `
132 ` cat `|`/bin/cat`
133 ` *.sh `|`/lib/libtaz.sh`<br>`/sbin/mktazdevs.sh`<br>`/usr/bin/gettext.sh`<br>`/usr/bin/httpd_helper.sh`<br>`/usr/lib/slitaz/httphelper.sh`<br>`/usr/lib/slitaz/libpkg.sh`<br>`/var/www/cgi-bin/cgi-env.sh`
134 ` pt* `|`/dev/pts`<br>`/usr/share/locale/pt_BR`<br>`/usr/share/locale/pt_BR/LC_MESSAGES`
135 `/bin/*.sh`|`/usr/bin/gettext.sh`<br>`/usr/bin/httpd_helper.sh`
136 `/lib/*.sh`|`/lib/libtaz.sh`<br>`/usr/lib/slitaz/httphelper.sh`<br>`/usr/lib/slitaz/libpkg.sh`
138 Additional patterns for the `copy()`:
140 * `@rm` - quick alias for the `remove_already_packed` function:
141 remove from the current package already copied files that was already
142 packed in any of previously packed packages (within current receipt);
143 * `@ico` - remove all the copied *hicolor* icons (if any) and copy only 16px
144 and 48px variants of *hicolor* icons.
147 ### Some more examples of using `copy()`
149 If your packages are used only for development purposes (like automake, flex, vala
150 and some others), you may use the next command to put all the files you want
151 to pack into one package:
153 ```bash
154 copy @std @dev
155 ```
157 In most cases, the package breaks up into "main" and "dev" packages. In this
158 case, your code might look like this:
160 ```bash
161 PACKAGE="my-package"
162 SPLIT="my-package-dev"
164 genpkg_rules() {
165 case $PACKAGE in
166 my-package)
167 copy @std
168 DEPENDS="your-package"
169 ;;
170 *-dev)
171 copy @dev
172 ;;
173 esac
174 }
175 ```
177 In the following example, a package can contain libraries (which can be used by
178 other programs) and executables that use these libraries. We need to split
179 `@std` into two parts: libraries and executable files. This can be done in a few
180 ways.
182 ```bash
183 PACKAGE="my-pkg"
184 # We omit "my-pkg" in the $SPLIT, then it is implicit in the first place
185 SPLIT="my-pkg-bin my-pkg-dev"
186 genpkg_rules() {
187 case $PACKAGE in
188 my-pkg) copy *.so*;; # (1) copy all the libs
189 *-bin) copy bin/;; # (2) copy all the execs from /usr/bin/
190 *-dev) copy @dev;; # (3) copy development files
191 esac
192 }
193 ```
195 ```bash
196 # If a package contains some more files outside of the /bin/ (for example, configs),
197 # that we want to pack with the "bin" package:
198 PACKAGE="my-pkg"
199 SPLIT="my-pkg-bin my-pkg-dev"
200 genpkg_rules() {
201 case $PACKAGE in
202 my-pkg) copy *.so*;; # (1) copy all the libs
203 *-bin) copy @std @rm;; # (2) copy standard (binaries and configs, etc),
204 # then remove already packed (libs)
205 *-dev) copy @dev;; # (3) copy development files
206 esac
207 }
208 ```
210 ```bash
211 # Pack two different libraries into two packages, and the rest into a third
212 # package:
213 PACKAGE="my-pkg"
214 # We explicitly specify all the packages, therefore they will be processed
215 # in the specified order
216 SPLIT="my-pkg-lib1 my-pkg-lib2 my-pkg my-pkg-dev"
217 genpkg_rules() {
218 case $PACKAGE in
219 *-lib1) copy lib-cli.so*;; # (1) copy first libraries
220 *-lib2) copy lib-gui.so*;; # (2) copy second libraries
221 my-pkg) copy @std @rm;; # (3) copy all the standard files,
222 # then remove already packed (libs)
223 *-dev) copy @dev;; # (4) copy development files
224 esac
225 }
226 ```
229 Compiling sets
230 --------------
232 Sometimes you may need to compile the same source code of the same version,
233 but with different options. For example, without PAM support and with PAM
234 support. Or with support for GTK+2 or GTK+3. Or a complete package with all
235 the rich features and a small limited package. You can not limit yourself
236 in the number of options.
238 Compiling set is a pair of separate `$src` and `$install` folders. You can
239 still compile the sources using the `$src` variable and install compiled files
240 into folder defined by `$install` variable, but these values will be different
241 for the different compiling sets.
243 Set defined by the name which is simple mnemonic made up of one or more letters
244 or numbers. It may be "1", "2", "z", or something more meaningful like "pam",
245 "gtk2", or "gtk3".
247 Also you should know that default set with the empty name always exists
248 for the backward compatibility and for the cases when you don't want to use
249 the sets.
251 How to use the sets?
253 First, you should define which set you want to use for each package appending
254 package names in the `$SPLIT` variable. You may not make it for the default set
255 with empty name. Few examples:
257 ```bash
258 PACKAGE="fuse-emulator"
259 SPLIT="fuse-emulator-gtk3:gtk3"
260 ```
262 ```bash
263 PACKAGE="yad"
264 SPLIT="yad-html:html yad-gtk3:gtk3"
265 ```
267 ```bash
268 PACKAGE="urxvt"
269 SPLIT="urxvt-full:full"
270 ```
272 Second, function `compile_rules()` will be executed sequently for default set
273 and then for all the sets you mention in the `$SPLIT` variable on the previous
274 step. You should make the business logic inside the `compile_rules()` function
275 to compile and install different variants based on the value of the `$SET`
276 variable. This variable has an empty value for the default set and the set
277 name in other cases. Few examples how you make the job:
279 ```bash
280 PACKAGE="fuse-emulator"
281 SPLIT="fuse-emulator-gtk3:gtk3"
283 compile_rules() {
284 SET_ARGS=''; [ -z "$SET" ] && SET_ARGS='--disable-gtk3'
286 ./configure \
287 --enable-desktop-integration \
288 $SET_ARGS \
289 $CONFIGURE_ARGS &&
290 make && make install
291 }
292 ```
294 ```bash
295 PACKAGE="urxvt"
296 SPLIT="urxvt-full:full"
298 compile_rules() {
299 case $SET in
300 '')
301 ./configure \
302 --disable-everything \
303 $CONFIGURE_ARGS &&
304 make && make install
305 ;;
306 full)
307 ./configure \
308 --enable-everything \
309 --enable-256-color \
310 --with-terminfo=/usr/share/terminfo \
311 $CONFIGURE_ARGS &&
312 make && make install || return 1
314 R="$install/usr/share/terminfo"
315 mkdir -p $R
316 tic -s -o $R $src/doc/etc/rxvt-unicode.terminfo
317 ;;
318 esac
319 }
320 ```
322 ```bash
323 PACKAGE="yad"
324 SPLIT="yad-html:html yad-gtk3:gtk3"
326 compile_rules() {
327 case $SET in
328 '') Gtk=gtk2; Html=disable;;
329 html) Gtk=gtk2; Html=enable ;;
330 gtk3) Gtk=gtk3; Html=disable;;
331 esac
333 ./configure \
334 --enable-icon-browser \
335 --with-gtk=$Gtk \
336 --$Html-html \
337 $CONFIGURE_ARGS &&
338 make &&
339 make install
340 }
341 ```
343 Thirdly, make `genpkg_rules()` as usual. *Cook* will switch to the required
344 set automatically based on conformity between packages and sets that you
345 described in the `$SPLIT` variable on the first step. That's all.
348 Dependency tracking
349 -------------------
351 Many packages use `libtool`, created during the `configure` processing.
352 This `libtool` contains one old and well-known (in narrow circles) “feature”
353 that is expressed in the fact that unnecessary dependencies are added to
354 libraries and executable files. Read about it:
356 * [Bug 655517 - using --as-needed in LDFLAGS is not respected and it links
357 on unneeded libs](https://bugzilla.gnome.org/show_bug.cgi?id=655517)
358 * [Project:Quality Assurance/As-needed](https://wiki.gentoo.org/wiki/Project:Quality_Assurance/As-needed)
360 Links above recommend to add `-Wl,--as-needed` to the LDFLAGS variable. You can
361 use short statement `fix ld` in the beginning (to add `-Wl,--as-needed` to the
362 LDFLAGS) and `fix libtool` just after the `configure` invocation (to
363 additionally fix just created `libtool`). Example of using:
365 ```bash
366 compile_rules() {
367 fix ld
368 ./configure \
369 --sysconfdir=/etc \
370 $CONFIGURE_ARGS &&
371 fix libtool &&
372 make && make install
373 }
374 ```
376 You should not use `fix libtool` if you do not see a file named `libtool` in the root
377 of the sources tree after the `configure` is done. It will not lead to an error,
378 although there will be no sense in it.
380 You can check dependencies of separate files using one of the next methods:
382 ```bash
383 ldd /path/to/file
385 readelf -d /path/to/file | grep NEEDED
386 ```
388 You can check dependencies of an entire package using the command:
390 ```bash
391 cook package_name --deps
392 ```
394 You can note a significant decrease in the number of dependencies. For example:
396 * for **fontconfig**:
397 * before: bzlib freetype liblzma libpng16 libxml2 zlib
398 * after: freetype libxml2
399 * for **at-spi2-core**:
400 * before: dbus glib libffi pcre util-linux-blkid util-linux-mount
401 util-linux-uuid xorg-libICE xorg-libSM xorg-libX11 xorg-libXau
402 xorg-libXdmcp xorg-libXext xorg-libXi xorg-libXtst xorg-libxcb zlib
403 * after: dbus glib xorg-libX11 xorg-libXtst
405 For some packages nothing will change.
408 ### Dependency tracking for development packages
410 This is a separate and complex issue.
412 Dependency info may be extracted from `.pc`, `.la` and `.h` files. Extracting
413 dependencies from the header files (`.h`) is a non-trivial task due to conditional
414 branching and can not be realized using simple tools.
416 As for `.la` files — Gentoo
417 [recommend](https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Handling_Libtool_Archives)
418 to remove them in most cases. As they stated, `.la` files may be useful only
419 for static libraries (`.a` files). Currently, the dependency tracking tool doesn't
420 use `.la` files unless you a provide special argument `--la`:
422 ```bash
423 cook fontconfig --deps --la
424 ```
426 It turns out that `.pc` files are the only development files that describe
427 dependencies of development packages. Usually the `configure` script checks
428 dependencies using something like this:
430 ```bash
431 pkg-config --exists --print-errors "gtk-doc >= 1.15"
432 pkg-config --exists --print-errors "xrender >= 0.6"
433 ```
435 Dependency tracking tools try to find the package that contains required
436 libraries, then determine a `*-dev` package that corresponds to the found package.
438 For example, file `/usr/lib/pkgconfig/cairo.pc` contains the line:
440 ```
441 Requires.private: gobject-2.0 glib-2.0 >= 2.14 pixman-1 >= 0.30.0
442 fontconfig >= 2.2.95 freetype2 >= 9.7.3 libpng xcb-shm x11-xcb
443 xcb >= 1.6 xcb-render >= 1.6 xrender >= 0.6 x11 xext
444 ```
446 Finding the next files shows the dependencies:
448 ```
449 gobject-2.0.pc glib-2.0.pc pixman-1.pc fontconfig.pc freetype2.pc
450 libpng.pc xcb-shm.pc x11-xcb.pc xcb.pc xcb-render.pc xrender.pc
451 x11.pc xext.pc
452 ```
454 Next example using file `/usr/lib/pkgconfig/apr-1.pc`:
456 ```
457 prefix=/usr
458 exec_prefix=${prefix}
459 libdir=${exec_prefix}/lib
460 APR_MAJOR_VERSION=1
462 Libs: -L${libdir} -lapr-${APR_MAJOR_VERSION} -luuid -lrt -lcrypt -lpthread -ldl
463 ```
465 Finding the next files shows the runtime dependencies and then full dependencies;
466 `*-dev` packages are the full packages.
468 ```
469 libapr-1.so libuuid.so librt.so libcrypt.so libpthread.so libdl.so
470 | | | | | |
471 v v v v v v
472 apr util-linux-uuid glibc-base glibc-base glibc-base glibc-base
473 | | | | | |
474 v v v v v v
475 apr-dev util-linux-uuid-dev glibc-dev glibc-dev glibc-dev glibc-dev
477 ```
479 Note, sometimes required files may be found in two or more packages, for
480 example, `libdl.so` exists within packages:
482 * `glibc-base`
483 * `uclibc-armv4eb`
484 * `uclibc-armv4l`
485 * `uclibc-armv4tl`
486 * `uclibc-armv5l`
487 * `uclibc-armv6l`
488 * `uclibc-cross-compiler-armv4eb`
489 * `uclibc-cross-compiler-armv4l`
490 * `uclibc-cross-compiler-armv4tl`
491 * `uclibc-cross-compiler-armv5l`
492 * `uclibc-cross-compiler-armv6l`
493 * `uclibc-cross-compiler-i486`
494 * `uclibc-cross-compiler-mips`
495 * `uclibc-cross-compiler-mips64`
496 * `uclibc-cross-compiler-mipsel`
497 * `uclibc-cross-compiler-powerpc`
498 * `uclibc-cross-compiler-sh4`
499 * `uclibc-cross-compiler-sparc`
500 * `uclibc-cross-compiler-x86_64`
501 * `uclibc-i486`
502 * `uclibc-mips`
503 * `uclibc-mips64`
504 * `uclibc-mipsel`
505 * `uclibc-powerpc`
506 * `uclibc-sh4`
507 * `uclibc-sparc`
508 * `uclibc-x86_64`