Table of Contents
Wok & Tools
Cookutils is used to compile and generate code (cooking) via instructions found in a receipt. It places compiled files in to a directory and calls upon Tazpkg to package said directory. The receipt found in a wok has a different “bottom half” to that of a Tazpkg; Cookutils has rules for compilation and packaging (which it forwards to Tazpkg), whereas Tazpkg is only concerned with packaging.
Cookutils is one of many small utilities the SliTaz project uses to automatically rebuild the distribution from source. The project also offers an archive of tools containing various small utilities, examples and configuration files. The distribution generator Tazlito is designed for users and developers; it can retrieve and reconstruct a LiveCD ISO image and generate a distribution flavor from a list of packages, a configuration file and a description. The utilities are all distributed as a source archive and are installed by default on SliTaz.
Wok Structure and Organisation
The wok is a directory structure that houses all the available packages. Each directory contains at least one receipt to download, unpack, compile and generate a package. Cookutils also needs to create a directory to store downloaded sources ($SOURCES_REPOSITORY, usually /home/slitaz/src) and a repository of generated packages ($PACKAGES_REPOSITORY, usually /home/slitaz/packages); these values can be configured in the /etc/slitaz/cook.conf file.
There is more than one Wok on the Mercurial repositories:
- wok-undigest: contributions awaiting testing/bug-fixing for inclusion in the unstable Wok
- wok: packages for the unstable, Cooking release
- wok-stable: packages for the stable SliTaz release
Initially, any contributions will be committed to the undigest repository. When the package has seen sufficient testing with regards to automatic generation, it can be moved to the Wok.
The Developer's Corner provides invaluable background information. Please ensure you have read and understood it before continuing.
To begin using the Wok, Cookutils must already be installed on the system along with the main development tools (binutils, compiler, libraries-dev, make). This requires you to install the meta-package slitaz-toolchain:
# tazpkg recharge # tazpkg get-install slitaz-toolchain
To access the SliTaz repositories, you will need to install the mercurial package:
# tazpkg get-install mercurial
Cloning the Wok
If you are to generate a package for inclusion in the SliTaz repositories, it is necessary to first obtain the current wok by using Mercurial. This is called cloning the Wok, a procedure that downloads the entire Wok and all its history to a working directory. If you wish to only use Cookutils to build packages for personal use, this is not necessary. See the Personal Wok section below instead.
The usual destination for a Wok clone is /home/slitaz/wok:
# cook setup --wok
This download may take some time; you will have a complete directory structure of the Cooking wok as a working directory.
Creating a Personal Wok
If your packages are only for personal use and are not intended for inclusion in the SliTaz repositories, a wok can be created from scratch.
# cook setup
Compiling and Generating Packages
Before compiling your first package, Cookutils must know where your working directory is. By default the path is /home/slitaz/wok but you can change this or rename the wok that you want to download.
When generating your first package, it is advisable to keep it simple and build your package without changing its receipt or seeking dependencies. M4 is an ideal candidate for your first cook:
# cook m4
When Cookutils has finished building M4, its package is placed in the directory specified by the configuration file (/home/slitaz/packages by default). If all went well, you can install the package on the host system or use it to generate a LiveCD distribution via Tazlito!
When you are familiar with receipts and the compilation process, you can use the following command to create a new package, after interactively writing its receipt:
# cook new <packageName> --interactive
Cooking Multiple Packages with a cook list
Cookutils can compile several packages with a single command. This is achieved with a cooking list, a text file of one package per line. Cookutils can accept a cook-list with the command of the same name; for example, to cook the mypkgs cook-list:
# cook list mypkgs.cooklist
Package Compilation Options
While you are free to use any options you want, it is necessary to respect the FSH, the documentation in /usr/share/doc and follow the FreeDesktop standards (.desktop).
Package-specific options are your choice; for example, you can disable support for XML, have smaller binaries for PHP and get rid of libxml2, but in the case of PHP, it's not worth the cost in terms of loss of functionality. If you have any doubts, look at the receipts and compiler options in compile_rules.
The official SliTaz packages are optimized for i486, the optimization arguments used to configure are specified in /etc/slitaz/cook.conf and can be called via the variable $CONFIGURE_ARGS. If you want to compile a package with different arguments, you can modify the Cookutils configuration file:
Files to Include/Exclude
Generally, the base packages contain no man, info or doc files, nor static libraries; we have to create them via a package-doc or a package-dev. Note that SliTaz does not intend to use the man or info command so there's no manual or GNU info file. The creation of packages containing docs is really optional. By contrast, writing documentation in the Handbook is more appreciated as it is widely-available and can be updated and improved easily.
In terms of configuration, the aim is to offer basic configuration files to run the package directly. Special cases exist such as the web server LightTPD, for example, where SliTaz supplies configuration files and start-up scripts in /etc/init.d (documented in the Handbook). For a new package, you are free to choose its default configuration depending on what you think is best for the end-user. The /usr/share/examples directory has example configurations and other kinds of useful information.
The categories of packages exist only for informational purposes and are not fixed. The idea is to classify packages so that a web page that recovers data in the package receipt, can be generated each night. For the short term, place development packages in 'devel', Xorg in 'x-window' and the variety of new packages in 'extra'
Structure of a Wok Package
The structure of the packages in the wok should always be respected so that Cookutils can find the correct files and directories. Possible contents of a package (note the directory taz/ is created at time of cooking):
- stuff/ : The material used to configure, compile and generate the package (patch(es), Makefile, pseudo fs, etc);
- receipt: The ever-present receipt;
- description.txt : (optional) The description of the package is included in the final package, copied to its root. Once installed, Tazpkg identifies this file as the description and can display it via tazpkg desc pkgname.
- taz/ : Directory tree containing the package Tazpkg generated, the compressed package is stored in the directory specified by $PACKAGES_REPOSITORY in the Cookutils configuration file.
Cookutils will automatically call upon Tazpkg to package the taz directory. It also forwards any packaging instructions found in the receipt.
Structure of a Tazpkg
The SliTaz packages are cpio archives containing files and a file-system compressed with gzip:
- fs/: Pseudo-file-system containing all the files to install.
- receipt: The receipt.
- files.list: A list of files in the package.
- description.txt: The description of the package (optional).