Bering-uClibc 4.x - Developer Guide - Building a Package
- 1 Chapter 3. Creating lrp packages with buildpacket
- 2 Introduction
- 3 Step by step guide to setting up the configuration for hdsupp.lrp
- 4 Configuration
- 5 Config settings in buildtool.cfg
- 6 Creating packages
Chapter 3. Creating lrp packages with buildpacket
Table of Contents
Buildpacket is a tool used to create lrp packages. When creating packages manually, there are many things that can go wrong (forgetting to copy a file, wrong file permissions) - buildpacket tries to eliminate those problems. It uses a package definition in XML format to know which files to copy (and what permissions they should have). It also automatically generates the lrcfg files.
This is the one instance where you will have to be root to use buildpacket - since we will have to change ownership of some files, which only root can do. To avoid problems, it is advised to use fakeroot.
Since it is not obvious at first, a little clarification: buildpacket creates lrp packages (packagename.lrp) that are defined in buildtool setups (unfortunately, those are sometimes also called packages). Those two need not have the same name. For example, there is a buildtool setup for lcd4linux - which has a package definition for buildpacket for a package called lcd4linx.lrp
Furthermore, one buildtool setup can contain definitions for more than one lrp package - the openssl buildtool setup, for example, contains definitions for libssl.lrp and openssl.lrp.
It is important to not confuse those two notions of "packages". The reason this is a little confusing is mainly historical - plus the fact that one source tarball can produce the binaries for several packages. This problem is common to other packaging systems (and the tools that generate the packages) - one "source rpm" for can create lots of individual rpm files, depending on how modular the packagers wanted to make things.
Step by step guide to setting up the configuration for hdsupp.lrp
In this section, we will finish up the hdsupp package, so buildpacket will be able to create an lrp-file from the sources buildtool created. To do this, open source/hdsupp/buildtool.cfg and append the following text:
<Package> <hdsupp> Version = 1.0 Revision = 1 Help <<EOF Tools to be create a bootable partition from within Bering-uClibc. The procedure to get a plain syslinux partition (if you want to use lilo, you're on your own) is something like this: 1. make sure your Bering install actually supports your harddrive (i.e. insert the appropriate modules) 2. Run fdisk to create the partitions. I usually create an empty DOS partition table (using the 'o' command) create a primary partition, make that bootable (using the 'a' command) 3. Run mkfs.msdos on the newly created partition (e.g. mkfs.msdos /dev/hda1) 4. Copy the MBR to the drive using (assuming your harddrive is /dev/hda) dd if=/usr/sbin/mbr.bin of=/dev/hda bs=512 count=1 5. Mount the drive and copy the bering files onto the drive (please read the bering users guide, section "Booting from an IDE device", it has some vital info for that part of the process) Remember to change the 'boot' and 'PKGPATH' to point to your harddrive. 6. run syslinux (e.g. syslinux /dev/hda1) This is usually the last thing I do (after unmounting the partition again, of course), because that way, I can simply copy everything from the floppy without having to worry about leaving ldlinux.sys alone (since that gets overwritten with the correct version by running syslinux) EOF <Permissions> Files = 644 Directories = 755 </Permissions> <Owner> Files = root:root Directories = root:root </Owner> <Contents> <File> Source = sbin/fdisk Filename = usr/sbin/fdisk Type = binary Permissions = 755 </File> <File> Source = sbin/mkfs.minix Filename = usr/sbin/mkfs.minix Type = binary Permissions = 755 </File> <File> Source = sbin/mkfs.msdos Filename = usr/sbin/mkfs.msdos Type = binary Permissions = 755 </File> <File> Source = usr/sbin/syslinux Filename = usr/sbin/syslinux Type = binary Permissions = 755 </File> <File> Source = usr/sbin/mbr.bin Filename = usr/sbin/mbr.bin Type = binary # We don't neet to specify permissions here, # since the default 644 will do just fine </File> </Contents> </hdsupp> </Package>
The configuration for this script is integrated into the buildtool.cfg file that controls the download of the sources. It resides in its own block called "Package". Sample (comments below):
<Package> <foo_1> Version = 1.0 Revision = 1 Help <<EOF Some Sample package See http://foo.bar.org LRP package by __PACKAGER__, __BUILDDATE__ EOF PackageType = lrp PackageName = foo <Permissions> Files = 644 Directories = 755 </Permissions> <Owner> Files = root:root Directories = root:root </Owner> <Contents> #include <common.cfg> <File> Filename = etc/init.d/foo Description = foo daemon init file Type = conf Type = local # because no ConfFile parameter was given, entry will end up in /var/lib/lrpkg/foo.conf </File> <File> Filename = etc/foo Type = list Type = local </File> <File> Filename = etc/foo/foo.cfg Description = foo config file Type = conf ConfFile = foo.bar # entry will end up in /var/lib/lrpkg/foo.bar.conf </File> <File> Source = usr/local/sbin/foo.d Filename = usr/sbin/foo.d Type = binary Permissions = 755 </File> </Contents> </foo_1> <anotherPackageHere> ... </anotherPackageHere> </Package>
Since for some packages, there are a lot of common entries between package definitions within one buildtool.cfg file (look at
initrd for an example) buildpacket supports include files, which contain all the common stuff
In the example above, the file
common.cfg (which must be declared as a file in
buildtool.cfg so it will be downloaded by buildtool) will be loaded by buildpacket, and its contents will be placed instead of the #include line
There is no limit on the number of times you include a single file, or on the total number of includes.
Include files may not contain include directives themselves (support for this may be added in a future version).
The version of the source-code used to compile the package. If Version and Revision are omitted (completely omitted, not simply defined as an empty string), no packagename.version file will be generated.
Revision of the package (to distinguish different builds of the same source)
If neither Version nor Revision are specified in the config file (this means, the key does not exist - not that the value is simply left blank) no
packagename.version file will be generated. This is useful for packages that get their version from another package (like
etc.lrp, which get their version info from initrd.lrp)
The skeleton file to build the package. Using skeleton files is deprecated - do not rely on them, since support for skeleton files will be removed in a future version.
Default permissions to give files/directories
Default ownership given to the files/directories
For simple packages, the name of the package and the actual lrp file are the same. There are cases though, where one needs to build several versions of the same package (and therefore needs to create different lrp files). One of those examples is initrd - there are several versions of the initrd package ("plain", one with ide support, one with usb support).
So to avoid a filename clash, we need to generate initrds of different names, while still making sure that internally, every package "thinks" it's name is
This is where the packagename parameter comes in. If it is omitted, the package-name and the filename of the generated package will be the same, it will be the name of the XML tag, with the extension
For those cases where we need different versions of the same package, the packagename parameter should be given the name that the package should "think" it has. For example:
<Package> <initrd> packageName = initrd # (redundant) other contents </initrd> <initrd_ide_cd> packageName = initrd other contents </initrd_ide_cd> <initrd_usb> packageName = initrd other contents </initrd_usb>
This would result in 3 packages being generated (
initrd_usb.lrp</ code>) but internally, all 3 packages would be defined as if their name was <code class="filename">initrd.lrp - which also means that one needs to rename
initrd.lrp before one can use it to boot from some USB stick.
All packages except initrd simply are gzip compressed tar archives. Initrd on the other hand is a gzip compressed image of a minix filesystem
to be able to also generate initrd packages with buildpacket, the packagetype parameter has been added. It defaults to "lrp", which means that a standard tar.gz type package will be generated
If one specifies "initrd" for the packagetype parameter, a gzip compressed minix filesystem will be generated instead
Obviously, this parameter is only useful if you are working on building customized initrd packages
For packages of type initrd, one can also specify the parameter "initrdsize", which defines the size of the minix filesystem to be generated. Default is 1500k
Text to put into the .help file. If the .help file should only consist of a single line, you can simply define it as
Help = Text for the help file
. If you need more than one line (most likely you will), you can use the mechanism used in the example.
The following "tags" that will be replaced at build time are supported:
- __PACKAGER__ The name of the user who built the package (this is why you need to specify the packager on the command line).
- __BUILDDATE__ Date the package was created
List of "File" blocks that define the contents of the package.
Only the files that need special care like binaries or directories "owned" by the lrp need to be listed here - stuff that came from the skeleton file or the files automatically generated by the tool are added automatically (but if they need other permissions/ownership than the default, you still need to specify them - as "LIST", for example). A file can be of more than one type - in this case, simply specify more than one "Type = xxx" line.
Target: filename (including relative path) that the link should point to (only used together with type=link)
Filename: (including relative path) of the file in the package
Source: relative (to buildtools staging-dir) path/filename to the file generated by buildtool. If source contains wildcards then the parameter "Filename" is assumed to be a directory.
Type: specifies the how buildpacket should treat this file. Possible types are:
- binary: (for files that are copied from the staging_dir of buildtool - not necessarily a binary)
- list: file (or pattern) to add to the packagename.list file
- conf: file to add to packagename.confFor files of this type, one can also add the parameter conffile. Normally, all conf-files are added to the file
/var/lib/lrpkg/packagename.conf. If one needs to put conf entries into a different file (needed for the etc package, for example), one can specify the name of the file (without exension) here.
- local: file to add to packagename.local (for partial backups). At this point only the type "I" (for including the file in the local backup) is supported, type "X" (for excluding a file from the local backup) is not.
- link: Specifies that this file is a (soft-) link that should be created during package creation. Filename specifies the name of the link (relative to the root dir). You MUST also specify Target (which tells buildpacket where the link should point to)
- device: specifies a device entry (e.g. /dev/console) - buildpacket.pl creates this device with the mknod command. The device type, major and minor number are required.
<File> Filename = dev/console Type = device devtype = c major = 5 minor = 1 </File>
- directory: Filename specifies the name of a directory that should be created. Source is ignored. Only useful if you need to create empty directories in the package (if they weren't empty buildpacket would create them automatically anyway)
You can use more than one type at the same time. For example, to specify that a file should be copied from the staging dir (making it a "binary") and is a configuration file and should be added to the packagename.local file, you would specify:
<File> Filename = etc/sample.conf Description = Configuration file Type = binary Type = conf Type = local </File>
In order to be able to generate the
root.lrp package, special handling of an an entry like
Filename = / Type = List
has been added. Normally, leading / in the filename are stripped, which would result in an empty entry in the list (which would in turn be ignored). To get around that, empty list-entries are replaced with ./ - which happens to be exactly what is needed to produce the correct
You can also use wildcards. For example, for copying a list of files with a common prefix or suffix , you would specify:
<File> Filename = lib/iptables/ Source = lib/iptables/libipt*.so Type = binary Permissions = 755 </File>
But be carefull with using wildcards - since buildpacket is doing some guessing here (it assumes that adding the file part from "Source" to the path specified in "Filename" will generate a pattern, that will match all files, copied into the archive). It will _not_ work if there are wildcards in the path of "Source" - so "Source = foo/bar*/*.txt" will _not_ work. Also, specifying wildcards in "Filename" will most likely not produce the desired results.
The reason why all this "guessing" is necessary, is that buildpacket needs to find the individual files, so it can apply the permissions/ownerships according to the specification.
Description: only used for file type "conf" - specifies the description/help to be shown in the lrcfg menu
Permissions: specifies the permissions of this file if they're different from the default
Config settings in buildtool.cfg
The following items can be set in buildtool.cfg
- gzip_options: should simply be "-9", but may also contain any other options you want to add when gzip is executed.
- packager: Name (and optionally email address) of the person using this buildtool/buildpacket installation. By setting this option, one doesn't need to supply the packager parameter on the command line
- lrpowner and lrpgroup: If you must run buildpacket as root (because fakeroot doesn't work on your plattform, for example), you can specify the username/groupname that should own the generated lrp package - so you don't have files owned by "root:root" in the packages directory
- mountpoint: The mountpoint where the minix-image should be mounted (used for initrd, for example). Default is /mnt/loop
buildpackage --package=packagename --packager=name_of_packager [--target=packagefile] [-lrp=existing.lrp] [-all] [--verbose]
./buildpacket.pl --package=zlip --packager="Martin Hejl" --verbose
Currently, buildpacket does not check whether the sources have already been installed. This is something that will be done later on, when buildpacket is more integrated into builtool
- --package: The name of the package you compiled using ./buildtool.pl build packagename
- --packager: The name of the user who created the package. The string you enter here is added to the .help file (if the help section contains the __PACKAGER__ tag)
- --target: For packages that create more than one lrp-file (like openssh), this specifies which lrp to create. If this option is omitted, the value of --package is used
- --lrp: If you already have an existing lrp file and you want to migrate your configuration to the new package, specify the lrp file here and it will be integrated into the package (if the .cfg file is set up correctly, the config will be migrated, but all binaries will be replaced with the new versions). This needs more work (it's pretty crude at this point), probably the lck-scripts by Alex Rhomberg will be integrated/used to take care of this.
- --verbose: Turns on verbose logging
- --all: If a package definition specifies more than one package (like openssh, which produces ssh, sshd, sshkey and sftp), specifying --all instead of --target causes buildpacket to create all packages at once. This parameter defaults to yes (it's a leftover from previous versions of buildpacket) so it should no longer be used. If you only want to build one specific package for a given buildtool setup which defines several packages, you must specify --package and --target