README
cookopts.txt
cookutils.de.html
cookutils.en.html
cookutils.fr.html
cookutils.html
cookutils.pt.html
cookutils.ru.html
cross.txt
general-questions.md
receipts-v2.md
timestats.txt
README
SliTaz Cookutils
================================================================================
The SliTaz Cookutils provide tools and utils to build SliTaz packages.
Repository layout
--------------------------------------------------------------------------------
bin/ User-facing tools — cook + cook-* sub-tools, plus cooker,
cookiso, cooklinux, cross, cooks, fix-desktop-file, uname.
lib/ Shared shell library (libcook.sh).
modules/ Internal pipeline helpers run by cook itself
(precheck, postcheck, compressor) — not user-callable.
configs/ Files that install to /etc/slitaz/ or /usr/share/cross/
(cook.conf, cook.site, cookorder, cross-*.conf).
data/ Templates and shared data (receipt template, cooklist,
cooktest, .desktop).
doc/ HTML and plain text user docs.
po/ Gettext translations.
web/ CGI scripts for the cooker web interface.
lighttpd/ Alternative web UI for the cooker.
init.d/ Init scripts.
tasks/ Pre-defined cooker tasks (freetype-harfbuzz, up-toolchain).
Top-level keeps only README, AUTHORS, COPYING, COOKUTILS.md, Makefile.
Cook
--------------------------------------------------------------------------------
The cook tool should be used in a chroot environment: simply use the command
'tazdev gen-chroot' to build one. You can also build packages directly but
build deps will not be handled correctly since cook will install missing
packages to perform a build and then remove them only if they were not
installed before, this way we can keep a clean build environment.
We use standard SliTaz paths to work such as /home/slitaz/wok, if you work on
cooking from stable or want to keep a clean system: create a chroot.
Cook features:
* Setup a build environment
* Check and install missing build dependencies
* Compile and generate the package
* Remove installed build dependencies
* Provide a log for each cook
* Clean one or all packages in the wok
* Check for receipt and package quality
* Clean chroot even on Ctrl-C
Cook does not:
* Depend on Hg but can use it to manage a wok
* Do complex work like compiling the whole system from source in
one command (but it can rebuild the full system step by step)
* Check build deps for you, use: BUILD_DEPENDS
* The work of a Build Bot, UNIX philosophy: one tool for one task
* Cook a package if your receipt is crappy :-)
Cook paths variables used in receipt:
* $src : Package source: wok/pkg/source
* $stuff : Package stuff: wok/pkg/stuff
* $fs : Package file system: wok/pkg/taz/*/fs
* $install : All installed files by the package
Old style is $_pkg and cook is compatible
Cook internal paths variables:
* $pkgdir : Package directory in the wok: wok/pkg
* $receipt : Package receipt in wok: wok/pkg/receipt
* $taz : The taz directory: wok/pkg/taz
* $pack : Package to compress: wok/taz/pkg-*
Cook-pkgdb
--------------------------------------------------------------------------------
Cook-pkgdb generates the package database files for a directory of *.tazpkg
(typically $PKGS) and refreshes the wok-wide split.db / maint.db. It is the
companion to cook for the build host that pushes a repository to the mirror.
Following UNIX philosophy, it is a standalone tool — cook just cooks, pkgdb
just lists.
Usage:
cook-pkgdb Full rebuild (wok DBs + lists in $PKGS)
cook-pkgdb <dir> Full rebuild against the packages dir <dir>
cook-pkgdb --splitdb Refresh $cache/split.db only
cook-pkgdb --maintdb Refresh $cache/maint.db only
cook-pkgdb --flavors Full rebuild + regenerate TazLiTo flavors
cook-pkgdb --rmpkg Full rebuild + remove unused tazpkg files
For backwards compatibility, 'cook pkgdb', 'cook splitdb' and 'cook maintdb'
are kept as transparent shims that exec cook-pkgdb.
Files produced in $PKGS:
* packages.list : Simple list of package-versions
* packages.md5 : MD5sum list of all packages
* packages.info : Packages with name, version, category, description,
site, tags, sizes, deps, rsum, provide
* packages.equiv : Equivalent packages list (used by tazpkg)
* descriptions.txt: Concatenated package description.txt
* bdeps.txt : BUILD_DEPENDS of each receipt in the wok
* files-list.lzma : Sorted list of files provided by all packages
* bundle.tar.lzma : Optional one-shot recharge bundle (set
MAKE_BUNDLE="yes" in cook.conf — build host only)
Files produced in $cache:
* split.db : Mapping pkg -> all_names (main + SPLIT)
* maint.db : Mapping maintainer -> pkg
Cook-wok
--------------------------------------------------------------------------------
Cook-wok provides read-only queries against the wok and the cook activity log.
Lists, searches and "what needs to be cooked next" — no side effects on
packages or DB. Like cook-pkgdb, it is a standalone tool. cook keeps shims
for the historical subcommands.
Usage:
cook-wok list List packages in the wok (ARCH-filtered)
cook-wok search <query> Grep package names
cook-wok uncook List packages with no corresponding tazpkg
cook-wok wanted [<prefix>] Cooker tasks driven by WANTED
cook-wok build_depends [<prefix>] Cooker tasks driven by BUILD_DEPENDS
The optional <prefix> scopes wanted/build_depends to a directory-name
prefix (e.g. "lib" -> $WOK/lib*/receipt). Speeds up scans on large woks.
Omit to scan the whole wok.
Backwards-compat shims kept in cook:
cook list-wok -> cook-wok list
cook search <query> -> cook-wok search <query>
cook uncook -> cook-wok uncook
cook wanted [prefix] -> cook-wok wanted [prefix]
cook build_depends -> cook-wok build_depends
cook activity stays in cook (logs of cook itself, not a wok query).
Cook-doctor
--------------------------------------------------------------------------------
Cook-doctor runs read-only health checks and, for each problem, prints a
suggested fix command without ever running it. Two modes:
cook-doctor Diagnose the build environment (config, cache DB
cook-doctor env files, disk space, orphan chroot mounts, toolchain
and SETUP_MD5, arch/cross coherence, permissions,
and any enabled network toggle).
cook-doctor <pkg> Diagnose one wok package: receipt sanity (as in
module precheck), category, PACKAGE vs dir name,
WANTED/BUILD_DEPENDS targets, broken state with a
log tail, stale taz/, the cooked tazpkg and the
source tarball.
cook-doctor all Run the package checks across the whole wok and
cook-doctor all lib print one summary line per non-healthy package
("<pkg> N problems, M warnings"). An optional
prefix scopes the scan to $WOK/<prefix>*. arm*
ports only scan matching HOST_ARCH receipts;
i486 and x86_64 scan everything.
Each line is tagged v (ok), ! (warning) or x (problem); a footer sums up
"<n> checks, healthy / <n> warnings / <n> problems" (or, for all, the
package tallies). cook-doctor never modifies the system — opt-in
automatic repair (--fix) is planned later. Exit status is 0 when nothing
is broken and 1 when any problem (x) is found, so it works as a gate in
cook all / the cooker / CI.
Backwards-compat shim kept in cook:
cook doctor [...] -> cook-doctor [...]
cook.conf toggles
--------------------------------------------------------------------------------
A few global toggles live in /etc/slitaz/cook.conf to keep the build
host vs developer chroot use cases clean:
MAKE_BUNDLE="no" Build host only — produce bundle.tar.lzma in
$PKGS via cook-pkgdb, baking upstream mirrors
and extra.list. Default "no".
REPOLOGY_CHECK="no" Build host only — postcheck queries
repology.org for outdated badges. Requires
HTTPS-capable wget. Default "no".
Both default to "no" so a fresh chroot doesn't try to reach the network
during cook / cook-pkgdb. Pascal-style build hosts flip them to "yes".
Cook-all
--------------------------------------------------------------------------------
Cook-all is the batch driver. It cooks packages listed in a plain text file,
one per line ('#' and blank lines ignored). With no file argument, ./cookorder
is tried first, then /etc/slitaz/cookorder. --resume skips packages that
already have a taz/ subdir, which lets you restart a broken full rebuild
without recooking what's already built.
Usage:
cook-all Use ./cookorder or /etc/slitaz/cookorder
cook-all <file> Cook from the given list
cook-all --resume Skip packages with an existing taz/
cook-all <file> --resume Combine
Backwards-compat shims kept in cook:
cook list <file> -> cook-all <file>
cook all [opts] -> cook-all [opts]
Note: cookall.sh is a separate beast — it's a cooker-daemon driver that
topologically sorts the wok by WANTED / BUILD_DEPENDS and breaks dep loops
with a hardcoded fallback. It stays alongside cook-all for now.
Cook-deps
--------------------------------------------------------------------------------
Cook-deps analyzes the runtime dependencies of a cooked package by reading
its files.list and resolving each binary, shared library, pkg-config or
libtool reference back to the package that ships it. Output: one line
"pkg: dep1 dep2 ..." per sub-package (with -q), otherwise pretty-printed
per sub-package.
It maintains per-cache indexes in $cache/tp.so.db / tp.a.db / tp.la.db /
tp.pc.db built from the local files.list and (off-tank) the mirror's
files.list.lzma. Indexes are rebuilt only when the source data is newer.
Usage:
cook-deps <pkg> Pretty output (one section per sub-package)
cook-deps <pkg> -q Quiet: "pkg: dep1 dep2 ..." per line
cook-deps <pkg> --la Also follow *.la dependency_libs
cook-deps <pkg> --incl Include glibc-base / gcc-lib-base / gcc
Backwards-compat shim kept in cook:
cook <pkg> --deps -> cook-deps <pkg>
cook <pkg> --cdeps -> cook-deps <pkg>
Cook-setup
--------------------------------------------------------------------------------
Cook-setup bootstraps a build chroot or sets up a cross-compile environment.
It creates the standard $SLITAZ directory layout, touches DB files in $CACHE,
installs SETUP_PKGS (or CROSS_SETUP for cross), and optionally clones a wok.
Usage:
cook-setup Native chroot bootstrap
cook-setup --wok Bootstrap + clone the cooking wok
cook-setup --stable Bootstrap + clone the stable wok
cook-setup --undigest Bootstrap + clone the undigest wok
cook-setup --tiny Bootstrap + clone the tiny wok
cook-setup --forced Re-install SETUP_PKGS even if present
cook-setup <arch> Cross-compile setup (arm|armv6hf|armv7|x86_64)
cook-setup <arch> --forced Cross + force re-install of CROSS_SETUP
Backwards-compat shims kept in cook:
cook setup [options] -> cook-setup [options]
cook arm-setup -> cook-setup arm
cook x86_64-setup -> cook-setup x86_64
cook armv6hf-setup -> cook-setup armv6hf
cook armv7-setup -> cook-setup armv7
Cook-new
--------------------------------------------------------------------------------
Cook-new creates a new package directory in $WOK from the receipt template.
Optional interactive mode prompts for the standard fields (version, category,
maintainer, license, web site, wget URL).
Usage:
cook-new <pkg> Create $WOK/<pkg>/ with template receipt
cook-new <pkg> -x Interactive prompts
cook-new <pkg> --interactive Same as -x
Backwards-compat shim:
cook new <pkg> [-x] -> cook-new <pkg> [-x]
Cook-clean
--------------------------------------------------------------------------------
Cook-clean wipes per-package build artefacts across the whole wok.
Usage:
cook-clean wok Remove taz/, install/, source/ for all pkgs
cook-clean src Remove source/ only (reclaim disk)
Backwards-compat shims kept in cook:
cook clean-wok -> cook-clean wok
cook clean-src -> cook-clean src
Cooker
--------------------------------------------------------------------------------
The Cooker is a Build Bot which automates the build process but doesn't make
the dinner for you! We need quality receipts to cook successfully and the goal
is not to have a bloated script so please Keep It Short and Simple.
Cmdline tool : /usr/bin/cooker
Web interface : /var/www/cooker
Cache folder : /home/slitaz/cache
The web interface consists of one CGI script and one CSS style. Cook logs can
be produced by cook and the cooker just acts as a fronted to check them in
a nice way. A web interface also highlights success and error and can show
receipts and the cooker logs such as the last ordered list or commits check.
Database files in the cache folder:
* activity : Activity information for the web interface
* blocked : List of manually blocked packages
* broken : Broken packages list, when cook fails it is added here
* commits : List of packages of the last commit check
* cooklist : Cooklist for unbuilt packages or custom commands
* cooknotes : All the notes added with 'cooker -n "My note"
* installed* : Lists used to compare installed packages before and after
a package is cooked so we can remove them
The Cooker web interface ships a built-in default header, so it works
standalone for a local install. It can be customized through the CSS style and
via an optional header.html file placed in the same directory as the CGI
script (like style.css and a custom favicon); the build host uses such a header
to add SliTaz branding.
Cookiso
-------------------------------------------------------------------------------
Cookiso is the official tool to automate the ISO build. The goal is to provide
a simple to use, rock solid tool with a web interface à la Cooker. It shares
configuration and templates with the Cooker but can be run on its own so it
can be used by contributors or customers to automate custom ISO building.
Cookiso must be run in a chroot which can be the same chroot as the Cooker.
Cookiso is also used to build rolling ISOs by tracking changes in a packages
list or Hg repository. The rolling command is designed to be run by cron
in a chroot environment. Here are some usage examples:
# cookiso setup
# cookiso gen --flavors="base justx"
# cookiso gen --flavors=base --version=cooking
Cross
-------------------------------------------------------------------------------
See : doc/cross.txt
Install: make install-cross
Usage : cross usage
Howto : cross howto
Cross compiling
--------------------------------------------------------------------------------
Cookutils lets you cross compile a package for a specific architecture. Say you
want to build ARM binaries from a standard i486 machine. Cookutils provides
helpers for the ARM platform, but the first thing to do is compile a cross
toolchain and modify the main cook.conf variables to use the correct ARCH, CFLAGS
and BUILD_SYSTEM
Cook handles HOST_ARCH and CROSS_* receipt variables. Some packages won't build
or are not packaged for an architecture and so cross compiling will fail if the
package receipt has not been reviewed and includes HOST_ARCH. Here is an example
and a list of cross variables:
HOST_ARCH="i486 arm"
CROSS_BUGS="Bugs description"
Before cross compiling, cook will automatically add cross-tools path to PATH,
set CC, AR, LD, etc and also export CROSS_COMPILE.
Toolchain
--------------------------------------------------------------------------------
To rebuild the full SliTaz toolchain at once - cook and the Cooker will use the
slitaz-toolchain package. No built-in code manages that since it is not a
common task. The toolchain package will build all needed packages in the correct
order, which is very important.
Coding style
--------------------------------------------------------------------------------
Here are the cookutils coding style notes, follow them if you want your code
included in the package.
* In all cases: KISS
* Use tab and not space to indent
* Max 80 char by line (try to edit in a Xterm 80x24)
* Use names rather than $1 $2 $3
* Variables from config file are $UPPERCASE
* Variables initialized by cook are $lowercase
* Functions can be a single word or use_underline()
my_function() {
echo "Hello World"
}
* Use $(command) and not: `command`
* Cook uses gettext for messages, not the cooker
* If you add a feature, add also the doc to explain it
* Use clean case with space before case end ;;
case "$pkg" in
a) echo "Hello World" ;;
*) continue ;;
esac
* Make commands and options as short as possible
* Think to log everything to help debug
* Quote variables if used in a test: [ "$var" ]
================================================================================
SliTaz Cooker · i486