How to build packages using buildeb
Here's what you will find on this page :
Introduction to Debian packages
Debian packages are ar archives that contains normally two files :
- control.tar.gz: This archive contains informations about the package (version, dependencies, descriptions, ...).
- data.tar.gz: This archive contains all the files that will be installed.
There are mainly 4 types of packages (or at least, there's 4 of them that will interest us here) :
-
Binary packages:
This concerns the packages that contains binary files. They depend on the architecture they were built on. They're generally named according to the following pattern: <package_name>_<version>-1_<arch>.deb -
Library packages:
This packages concerns libraries and headers files. Library packages can be divided into two categories :- The first category of library packages concerns the ones which only contains libraries. They're named according to the following pattern: <package_name>_<version>-1_<arch>.deb. Usually, the name of the package contains 'lib', but it's not mandatory.
- The second category concerns the packages that only contains header files. Those packages are named according to the following pattern: <package_name>-dev_<version>-1_<arch>.deb.
-
Arch-Independant packages:
Those packages contains files that don't depend on the architecture on which the package was built. This category of files includes images, scripts, configuration files, ... -
Sources packages:
Sources packages are actually composed of two files : a .dsc file which describe the package, and a tarball (an archive which format usually is .tar.[gbx]z). This type of package allows you to build one of the three other types, and is usually generated during a package's build.
Building packages is usually quite difficult. That's why we've created buildeb, a shell script that will help you build packages easily.
Introduction to buildeb
The purpose of buildeb is to help you create packages. In order to download it, you have to add the CosyVerif repository to your sources.list. You can also clone the following git repository: https://github.com/CosyVerif/deb-base. However, in that case there's a few things you need to know. If you clone the git repository, you'll need to put the perl scripts (i.e. the files located in scripts/*.pl) in the directory where you'll launch buildeb. So, it's probably better to just install the buildeb package.
If you want to use buildeb, your project needs to follow some rules. You'll find them below.
Requirements
Here's the list of the dependencies of buildeb:
- perl
- sed
- dh-make
- devscripts
- debhelper
- build-essential
- make
- fakeroot
- lintian
- coreutils
- mawk
- libyaml-tiny-perl
In addition of that, your project needs to follow some rules. First, you need to have a makefile that builds your project. You can have a makefile generated by autoreconf, or something like that, but there MUST be a makefile in your source code directory. If you don't have one, but you have something else that build your project, you can create a makefile which will call the thing that builds you project. Here's what might look like the Makefile in that case:
Example
Let's say you have a script named build.sh that builds your project. The makefile will look like:
path/to/build.sh
Then, the names of all the files in your project (or at least the ones you want to include in the packages you want to build) MUST be without spaces.
Finally, all the paths in your makefile must not be absolute. They HAVE TO be relative. Furthermore, if your Makefile calls other Makefiles, you can't use the -e option.
If your project meet these requirements, you'll be able to use buildeb without much trouble.
Before executing buildeb, you have to fill a configuration file, in order to specify what files you want to put in your packages, the name of the packages you want to build, ...
The configuration file
The configuration file needed by buildeb can be found in the directory /usr/share/buildeb/ (or in scripts/ (in the git repository) if you haven't installed the package). You can also generate a template of it by using -g when executing buildeb.
Here's an explanation of every field you have to fill. All the paths you have to provide MUST BE relative to the directory that contains the makefile.
-
BINPACKAGENAME
The name of the binary package. If you don't want to build one, you can leave it empty. -
LIBPACKAGENAME
The name of the library package. The package containing the libraries will be named according to the following pattern: LIBPACKAGENAME_<version>-1_<arch>.deb. The package containing the headers files will be named that way: LIBPACKAGENAME-dev_<version>-1_<arch>.deb. -
INDPACKAGENAME
Name of the package that will contain the architecture independent files. You don't have to fill it if you don't want to build one. -
VERSION
Version of your program. If you leave it empty, the version will be the number of seconds that have elapsed since the Epoch at the moment of buildeb's execution). However, if you don't leave it empty, and you're using Jenkins to build your packages, you HAVE TO increase the value of that field. If you don't, all the packages you've previously built with that version number will be erased from the repository. -
COPYRIGHT
This field can be one the three following values:- gpl, gpl2, gpl3, lgpl, lgpl2, lgpl3, artistic, apache, mit: In that case, a generic copyright file will be generated. You have to fill the field DEVS with the names of the developers that participated on your project, unless you have a file named AUTHORS in the directory containing the Makefile.
- A path leading to your own copyright file.
- Empty. In that case, if you have a file named COPYING or LICENSE, we will use it as the copyright file. If not, the copyright file will be empty.
-
DEVS
Name of the developers that participated on your project. It must follow the following pattern: year(s) name <email>. -
PACKAGETYPE
Type(s) of package(s) you want to build. For each type of package you want to build, you have to put the right letter. Each letter must be separated by ONE space. Each letter correspond to a certain type of package. So, here's what each letter means:- s: Binary Package. If there's one in the field PACKAGETYPE, it means that you want to build a binary package (and only one. If you put more than one s in this field, the script will ignore them and still only build one binary package. This is also true for the other letters).
- l: Library package.
- i: Architecture independent package.
Example 1
Let's say you only want to build a binary package. Then what you have to put in this field is:
PACKAGETYPE : sIf you put something like that:
PACKAGETYPE : s s severything will work fine, but the script will only build one binary package.Example 2
Now let's say you want to build a binary package and a library package. Here are the lines that will work:
PACKAGETYPE : s lThe letters' order are not important.
-- OR --
PACKAGETYPE : l sExample 3
Now let's say you want to build all types of packages (i.e. binary package, library package and architecture independent package). Here are the lines that will work:
PACKAGETYPE : l s i
-- OR --
PACKAGETYPE : l i s
-- OR --
PACKAGETYPE : s l i
-- OR --
PACKAGETYPE : s i l
-- OR --
PACKAGETYPE : i l s
-- OR --
PACKAGETYPE : i s l -
BUILDDEPENDS
Name of the packages that need to be installed in order to build your program. You can use the symbols =, >= or <= to specify a version number.Example
Let's say that in order to build your project you need: gcc (version 4.7 or better), perl (version 5.16.0), autoconf (version 2.69 or lower) and make. Here's what you can write:BUILDDEPENDS :
- gcc (>= 4.7)
- perl (= 5.16.0)
- autoconf <= 2.69)
- make -
BINRUNDEPENDS
Name of the packages needed by your binaries during their execution. It's the same syntax as BUILDDEPENDS. -
LIBRUNDEPENDS
Name of the packages needed by the libraries (or by the headers) in order to behave properly. In other words, those are the packages that need to be installed before installing the library package you're creating. -
INDRUNDEPENDS
Name of the dependencies of the architecture independent package you're building. -
BEFOREBUILD
List of commands that need to be executed before building your program. If your Makefile is generated by some kind of program, you HAVE TO put the commands that creates the said makefile (like autoreconf, ...) in this field. -
AFTERBUILD
Commands that needs to be executed after the build. If you've modified things in BEFOREBUILD, you have to restore them in this field ! -
CONFIGUREFLAGS
If you're using a configure script with any flags, you have to put them in this field. -
BINARYNAMES
Name of the binary files you want to include in the package you're creating. It should be written like that: PATH/TO/FILE::PATH//ONCE//INSTALLED. You MUST NOT put the first '/' (i.e. the root directory).Example
Let's say you want to include the binary file foo/bar in the package, and you want it to be installed in the directory /usr/bin. Let's say you also want to include the binaries foo/baz1, foo/baz2, and foo/bar3 in the package, and you want them to be installed in the directory /usr/local/bin. Here's what you should do:
BINARYNAMES :
- foo/bar::usr/bin
- foo/baz*::usr/local/bin -
LIBNAMES
Name of the libraries you want to include in the package you're creating. Works the same way as BINARYNAMES -
HEADERNAMES
Name of the headers you want to include. If you leave it empty, the package that is supposed to contain the header files won't be created. Works the same way as BINARYNAMES and LIBNAMES. -
INDNAMES
Name of the arch independent files you want to include. Same as before. -
MANPAGES
Manpages you want to include. It also works the same way as before. -
DISTRIBUTION
Section of the repository where you want to upload your package. If you're building your packages on jenkins, you should leave it empty. -
BINPACKAGEDESCFILE
Description file for the binary package. It must be written that way: The first line is a short description of the package (up to 60 chars). The other lines represent the long description of the package. It's not mandatory.Example
Here's what it should look like:
Short description of the package.
Long description of the package. blah blah blah
blah blah blah -
LIBPACKAGEDESCFILE
Description file for the library package. It works that way: The first line is a short description of the package that will contains the libraries (up to 60 chars). Then, you can put a long description for that package. Then, you have to put a blank line. After that blank line, you can put the short description for the package that will contain the headers (up to 60 chars). Then, you can write the long description for that packages.Example
Here's what it should look like:
Short description of the package that contains the libraries
Long description of that package. blah blah blah
blah blah blah
Short description of the package that contains the headers.
Long description ... blah blah blah blah
blah blah blah -
INDPACKAGEDESCFILE
File that contains the descriptions for the arch independent package. Works the same way as BINPACKAGEDESC. -
DEBFULLNAME
Name of the package maintainer. -
DEBEMAIL
Email of the package maintainer. -
HOMEPAGE
Homepage of your project.
buildeb's options
Here are the list of options you can specify when calling buildeb:
- -c <configuration_file>: This option allows you to specify where your configuration file is located. You can omitthis option if your configuration file is located in the directory where you're executing buildeb, and its name is "build_config.yml". Otherwise, you have to use it.
- -d <makefile_dir>: Allows you to specify the path leading to the directory containing the Makefile. If your makefile is located where you're executing buildeb, you can omit this option. Otherwise, you should use it.
- -l: Don't clean the temporary files created by buildeb.
- -g: Generate a configuration file template (only if you've installed the debian package containing buildeb).
- -t: Stop the building process before creating the packages. It allows you to modify the debian's configuration files as you wish.
- -V: Verbose mode.
- -D: Debug mode.
- -h: Print help
Here's an example of how to call buildeb:
Example
Let's say that your configuration file is named conf.yml and is located in foo/bar/. Your Makefile is located in foo/baz/. And let's say that you're in the directory foo/. You should call buildeb that way: