Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
en:cookbook:wok [2010/06/19 17:38] seawolf |
en:cookbook:wok [2017/04/17 18:31] (current) hgt create package after writing recipe |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Overview ===== | ===== Overview ===== | ||
| - | The SliTaz project uses a variety of small utilities to automatically rebuild the distribution from source. [[http://hg.slitaz.org/tazwok/raw-file/tip/doc/tazwok.en.html|Tazwok]] is used to compile and generate code (cooking) via instructions found in the receipts. The project also offers an archive of [[en:cookbook:slitaztools|tools]] containing various small utilities, examples and configuration files. The distribution generator [[http://hg.slitaz.org/tazwok/raw-file/tip/doc/tazwok.en.html|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. | + | [[http://hg.slitaz.org/cookutils/raw-file/tip/doc/cookutils.en.html|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. |
| - | <note tip>Developers and future contributors can refer to the [[http://doc.slitaz.org/en:cookbook:devcorner|development]] page that provides information on SliTaz project management.</note> | + | 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 [[en:cookbook:slitaztools|tools]] containing various small utilities, examples and configuration files. The distribution generator [[http://hg.slitaz.org/tazlito/raw-file/tip/doc/tazlito.en.html|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. |
| + | |||
| + | <note tip>Developers and future contributors can refer to the [[http://www.slitaz.org/en/devel/forge.php|development]] page that provides information on SliTaz project management.</note> | ||
| === Wok Structure and Organisation === | === 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. Tazwok 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/tazwok.conf// file. | + | 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 [[http://hg.slitaz.org|Mercurial repositories]]: | There is more than one Wok on the [[http://hg.slitaz.org|Mercurial repositories]]: | ||
| Line 22: | Line 24: | ||
| ===== Preparation ===== | ===== Preparation ===== | ||
| - | To begin using the Wok, [[http://hg.slitaz.org/tazwok/raw-file/tip/doc/tazwok.en.html|Tazwok]] 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//: | + | The [[http://www.slitaz.org/en/devel/forge.php|Developer's Corner]] provides invaluable background information. Please ensure you have read and understood it before continuing. |
| + | |||
| + | To begin using the Wok, [[http://hg.slitaz.org/cookutils/raw-file/tip/doc/cookutils.en.html|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//: | ||
| <code> | <code> | ||
| - | tazpkg recharge | + | # tazpkg recharge |
| - | tazpkg get-install slitaz-toolchain | + | # tazpkg get-install slitaz-toolchain |
| </code> | </code> | ||
| Line 32: | Line 36: | ||
| <code> | <code> | ||
| - | tazpkg get-install mercurial | + | # tazpkg get-install mercurial |
| </code> | </code> | ||
| + | More information on the use of the Mercurial VCS is available from its [[http://mercurial-scm.org/|website]] and the "[[http://hgbook.red-bean.com/|Hg Book]]". | ||
| === Cloning the Wok === | === 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 Tazwok to build packages for personal use, this is not necessary. | + | 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 [[#creating-a-personal-wok|Personal Wok]] section below instead. |
| - | + | ||
| - | <note important>The Wok is one of many projects hosted in the [[http://hg.slitaz.org|Mercurial repositories]]. Individual packages are grouped as a large project (the Wok, Wok-Stable or Wok-Undigest) and is not its own sub-project but merely a sub-directory; Mercurial cannot (yet) clone specific parts of a project thus you cannot clone an individual package.</note> | + | |
| The usual destination for a Wok clone is ///home/slitaz/wok//: | The usual destination for a Wok clone is ///home/slitaz/wok//: | ||
| <code> | <code> | ||
| - | hg clone http://hg.slitaz.org/wok/ /home/slitaz/wok | + | # cook setup --wok |
| </code> | </code> | ||
| - | <note tip>The archives are also available from [[ftp://download.tuxfamily.org/slitaz/wok/|TuxFamily via FTP]]; just take the latest version from the cooking or undigest directories.</note> | + | This download may take some time; you will have a complete directory structure of the [[http://hg.slitaz.org/wok/|Cooking wok]] as a working directory. |
| - | Before compiling your first package, Tazwok 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. To view and check Tazwok paths that will be used, and the number of packages in the wok, you can ask Tazwok for statistics: | + | <note important>The Wok is one of many projects hosted in the [[http://hg.slitaz.org|Mercurial repositories]]. Individual packages are grouped as a large project (the Wok, Wok-Stable or Wok-Undigest) and is not its own sub-project but merely a sub-directory; Mercurial cannot (yet) clone specific parts of a project thus you cannot clone an individual package.</note> |
| + | |||
| + | === 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. | ||
| - | <code> tazwok stats </code> | + | <code> # cook setup </code> |
| ===== Compiling and Generating Packages ===== | ===== Compiling and Generating Packages ===== | ||
| - | The process for generating a SliTaz package from source can be summerised thus: [[http://www.tuxfiles.org/linuxhelp/softinstall.html#s2|configure]], [[http://www.tuxfiles.org/linuxhelp/softinstall.html#s3|compile]] & [[http://linux.die.net/man/1/strip|strip]]. | + | 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. |
| - | <note>We do not carry out the '//make install//'-style step ourselves; the built files are not to be installed in the system but left in the output directory, ready for packaging.</note> | + | The process for generating a SliTaz package from source can be summarised thus: [[http://www.tuxfiles.org/linuxhelp/softinstall.html#s2|configure]], [[http://www.tuxfiles.org/linuxhelp/softinstall.html#s3|compile]] & [[http://linux.die.net/man/1/strip|strip]]. |
| - | 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//: | + | <note>We do not carry out the '//make install//'-style step ourselves; the built files are not to be installed in the system but left in the output directory ($DESTDIR), ready for packaging.</note> |
| - | <code> tazwok cook m4 </code> | + | When generating your first package, it is advisable to [[http://doc.slitaz.org/en:cookbook:devcorner#kiss-comply-to-standards|keep it simple]] and build your package without changing its receipt or seeking dependencies. M4 is an ideal candidate for your first //cook//: |
| - | When Tazwok 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! | + | <code> # cook m4 </code> |
| - | To create a new package, you can use //new-tree// with the option //--interactive//, and begin to build your [[en:cookbook:receipt|receipt]]. Be sure to read the documentation on the options provided by the [[en:cookbook:receipt|receipt]] and the [[en:guides:tazwoktips|Tazwok Tips]] to avoid frustration! | + | 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 [[en:cookbook:receipt|receipts]] and the compilation process, you can use the following command to create a new package, after interactively writing its receipt: | ||
| - | === Cook-list - List of cooking === | + | <code> # cook new <packageName> --interactive </code> |
| + | Be sure to read the documentation on the options provided by the [[en:cookbook:receipt|receipt]] and the [[en:guides:tazwoktips|Tazwok Tips]] to avoid frustration! | ||
| - | To compile several packages with a single command, you can use a cooking list. There are example lists in **usr/share/examples/tazwok/cooklists** on SliTaz, these are just text files with a package put on every line. Cook-list example using **mypkgs.cooklist**: | + | === Cooking Multiple Packages with a cook list === |
| - | <code> tazwok cook-list mypkgs.cooklist </code> | + | 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: |
| - | ===== Options during compilation of package ===== | + | <code> # cook list mypkgs.cooklist </code> |
| + | ===== Package Compilation Options ===== | ||
| - | You are free to use any options you want, it is necessary to respect the FSH, the docs in **/usr/share/doc** and follow the Freedesktop standards (.desktop). Then it's just a question of 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**. | + | 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). |
| - | === Optimization === | ||
| + | === Package-Specific === | ||
| - | The official SliTaz packages are optimized for i486, the optimization arguments used to configure are specified in **/etc/tazwok.conf** and can be called via the variable $CONFIGURE_ARGS. If you want to compile a package with different arguments, you can modify the Tazwok configuration file: | + | 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//. |
| - | <code> | ||
| - | CONFIGURE_ARGS="--build=i486-pc-linux-gnu --host=i486-pc-linux-gnu" | ||
| - | </code> | ||
| + | === Optimization === | ||
| + | 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: | ||
| + | |||
| + | <file bash> | ||
| + | CONFIGURE_ARGS="--build=i486-pc-linux-gnu --host=i486-pc-linux-gnu" | ||
| + | </file> | ||
| - | =====Files included or excluded package ==== | ||
| + | ==== Files to Include/Exclude ==== | ||
| - | Generally the base packages contain no man, info, doc or static libraries, we have to create them via a package-doc or a package-dev. Note that SliTaz is not intending 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, especially if the material is in English (I say). By contrast a piece of text on the package in the Handbook is more appreciated. | + | 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, whenever possible, the aim is to offer basic configuration files to run the package directly. In the case of the web server LightTPD package, SliTaz supplies configuration files and startup scripts located 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 easiest for the end user. On SliTaz you have **/usr/share/examples** for example configurations and other kinds of useful infomation. | + | 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. |
| - | ===== Categories of packages ===== | ||
| + | ===== Package Categories ===== | ||
| - | The categories of packages exist only for informational purposes and are not fixed, the idea is to classify packages so that a web page can be generated each night recovering data in the package receipt. For the short term, place developement packages in 'devel', Xorg in 'x-window' and the variety of new packages in 'extra' | + | 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 package in the wok ===== | ||
| + | ===== Structure of a Wok Package ===== | ||
| - | The structure of the packages in the wok should always be respected so that Tazwok can find the correct files and directories. Possible contents of a package (note the directory taz/ is created at time of cooking): | + | 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). | + | * **stuff/** : The material used to configure, compile and generate the package (patch(es), Makefile, pseudo fs, etc); |
| - | * taz/ : Directory tree containing the package Tazpkg generated, the compressed package is stored in the directory specified by $PACKAGES_REPOSITORY in the Tazwok configuraton file. | + | * **receipt**: The ever-present [[en:cookbook:receipt|receipt]]; |
| - | * receipt : The receipt (see [[en:cookbook:receipt|receipts]]). | + | * //**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//.// |
| - | * description.txt : (optional) The description of the package is copied to the root of the Tazpkg package. Once installed, Tazpkg knows how do deal with this file 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.// |
| - | ===== Structure of a Tazpkg package ===== | + | 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 filesystem compressed with gzip: | + | The SliTaz packages are cpio archives containing files and a file-system compressed with gzip: |
| - | * fs/ : Pseudo filesystem containing all the files to install. | + | * **fs/**: //Pseudo-file-system containing all the files to install.// |
| - | * receipt : The receipt (see receipt.txt). | + | * **receipt**: //The [[en:cookbook:receipt|receipt]].// |
| - | * files.list : A list of files in the package. | + | * **files.list**: //A list of files in the package.// |
| - | * description.txt : The description of the package (optional). | + | * //**description.txt**: The description of the package (optional).// |