D
DevynCJohnson
Guest
Many developers may want to make a Debian file (*.deb) so their program/library can be distributed among Debian-based Linux distros. Thankfully, creating Debian packages is easy. Many tools are available for programmers to use to ease the building process.
Preparing for the Build
Before building, install the needed packages using the two commands below. The installed tools are needed to create a variety of Debian packages.
When ready, be sure that the files intended for the Debian package are in a folder titled in a format like "name_version" where the "name" is the package's name in lowercase letters and numbers (if desired). "version" is the software's version.
Users will need to create a GPG key that they use to sign the Debian packages that they will create. Remember the name, email address, and password used to generate your GPG key. Also, know the KeyID of the GPG key.
For more info on GPG keys:
Be sure that the terminal being used to run the commands is in the same directory as the files intended to be packaged. In other words, the current working directory must be inside the package directory (like "name-1.0"). Next, run the two commands below, but use your own name and email that you used when making your GPG key. This allows the building process to automatically sign the Debian files.
Packaging a Script
Packaging software that is a script or some other type of software that does not need a "configure" or "Makefile" needs to be built a little differently than other package types. First, place the files to distribute in a directory that is named using a format like "name-version", where "name" is the package's name and "version" is the version. As my example, I will use the nagdev program. So, the developer would place the nagdev script and man page in the folder titled "nagdev-1.0".
Next, run something like "dh_make -s -c gpl3 -e $DEBEMAIL -p nagdev_1.0 --rulesformat dh7 --createorig" (as I did for my project), or use a command as simple as "dh_make". The command that I used creates the "copyright" file and sets the license to GPL3 (-c gpl3). The maintainer's email is set (-e $DEBEMAIL) and the package's name and version is declared (-p nagdev_1.0). The "rules" file is set to use the DebHelper version 7 format (--rulesformat dh7). The "--createorig" flag creates the *.orig.gz file, if one has not already been created.
NOTE: The package's version can also be specified with the rest of the version (-p nagdev_1.0-trusty1).
Depending on the project's needs, if the "dh_make" command asks about the package type ("Type of package: single binary, indep binary, multiple binary, library, kernel module, kernel patch?"), choose "single" by typing "s" for single-binary packages (like most packages). "i" is for architecture-independent packages, "l" is for libraries, "k" is for kernel modules, "m" is for packages with multiple binaries, and "n" is for kernel patches. Alternately, the developer can use the letters specified as parameters so that the dh_make command never asks. For instance, "dh_make -i" indicates that an architecture-independent package will be generated. Use "--kpatch" for kernel patches. See "man dh_make for more info.
Afterwards, a "debian" directory is generated. Running that command will generate a variety of template files for your project that are placed in that "debian" folder. For instance, a "control" file will be seen that will need some modifications. Some files (like "compat") are ready for use without tweaking. These templates help developers save time by having ready-made files that need minor edits. Not all of the files are needed. For instance, if a developer has already created a man page for their program, then the man page templates are not needed. The only file here that is required is "control". However, it is strongly recommended that the “copyright”, “rules”, and “compat” files also be included. Directories that are generated (like “source”) should also be kept for use.
NOTE: Most of the "*.ex" files are seldomly needed, so type "rm ./debian/*ex; rm ./debian/*EX" in a terminal to delete all of them.
After taking the time to tweak the files that are needed for the project, remove the ones that are not going to be used. Next, make an "install" file that will specify where the files will be installed. Inside this file, type a file's name (like "nagdev.1.gz") and then specify the intended install location (such as "usr/share/man/man1/") separated by a space. The leading (first) slash is not required as can be seen in my example below. Wildcards are permitted in this file.
"Install" File
Once finished, execute "dpkg-buildpackage -rfakeroot -k$GPGKEY" in a terminal to create the Debian file. If you get errors that state the package was not signed, then try executing "sudo dpkg-buildpackage -k$GPGKEY". If that also fails, then ensure you are using the correct name, email address, and KeyID.
NOTE: Notice the use of the "-rfakeroot" parameter or the use of "sudo". This is necessary because the Root user on all systems has the same User ID (UID). The files in a Debian package must have the proper UID associated with them. Using a regular user's UID would cause problems.
If the package does not need to be signed, try running “debuild -us -uc” instead of dpkg-buildpackage.
Alternately, when packaging for repo/PPA servers like Launchpad, use “debuild” instead of “dpkg-buildpackage”. For the nagdev project, “debuild -S -rfakeroot -k$GPGKEY” was used for the Launchpad Debian files.
Below are examples of what developers should see when checking the finished Debian package.
Packaging a Binary
To package a binary, perform the same actions as mentioned for script packaging. However, be sure the control file lists the proper system architecture. Also, select the proper package type (a single binary). Do not include the “Source” field in the control file, unless the source package uses a different package name than the binary package.
Packaging Source Code
Sometimes, developers may want to distribute their program as source code so that users can compile the program on their system. Packaging source code is just like it is for scripts, except some minor differences. The first step that should take place is listing all dependencies for build-time. Run "dpkg-depcheck -d ./configure" to get a list of needed packages for build-time. Some of the listed packages may also be needed even after the package is installed. The list will need to be added to the "Depends" and "Build-Depends" depending on when the software is needed by your package. Next, run "sudo apt-get build-dep [pkgs]" to install the needed software for build-time. Then, perform the other steps for building a Debian file. Once done, be sure to test the package.
It helps to understand the difference between the "Depends" and "Build-Depends" packages. The "Depends" are needed for the program to run while the "Build-Depends" are needed when the software is being compiled/built. For example, a package may need "libssl-dev" to get the headers (*.h) during build-time, but then need "libssl" during runtime.
When creating source packages containing code that needs to be compiled, the source package should contain a Makefile and a “configure” script.
FUN FACT: The version number “1.0-1” for a Debian file has a special meaning. The “1.0” is the software's version number and the “-1” refers to the Debian package. So, if a bug is fixed in the package (like an error in the control file) the “-1” is incremented. Both “1.0-1” and “1.0-2” contain the same software, but “1.0-2” (hopefully) has less package bugs.
Packaging Upstream Tarballs
To package a tarball, perform the following actions.
# Rename the tarball (replace hyphens with underscores)-
mv project-1.0.tar.gz project_1.0.orig.tar.gz
# Unpack
tar xf project_1.0.orig.tar.gz
# Make sure the unpacked tarball's directory is “project-version”
cd project-1.0
mkdir debian
# Specify version and package name
dch --create -v 1.0-1 --package project
# Make any edits the files (like control)
# Generate the Debian file
debuild -us -uc
Set Layout
If the files that are to be packaged are already set in the proper Debian-file layout and all the special files have been created (like "control"), the developer can run "dpkg-deb -b DIRECTORY" to create the Debian file. This is helpful if a Debian file has been uncompressed and a file has been changed (and the md5sums file). Developers can use this to make minor changes after packaging a new file. Assume a developer has forgotten to fix a spelling error in a file. With the dpkg-deb tool, the fix can be applied quickly. This tool is useful on directory structures like the one below.
NOTE: If one of the files in the “DEBIAN” folder were to be changed and then repackaged, then the new package would be “script-parser_3.7-2_all.deb”. The “-2” indicates the package's version. The “3.7” refers to the software's version.
Create md5sums
Use the “dh_md5sums” to create the needed “md5sums” file if a Debian files is missing that file or if a package has been uncompressed due to a minor edit. Alternately, use the “md5sum” command to get the checksum of a single file and replace the former entry if one or few files have been changed. For instance, to update the “md5sums” file for the “script.sh” file, execute “md5sum ./path/script.sh”. Then, paste the output in-place of the old checksum.
Sign Already-Made Packages
Type "dpkg-sig -k$GPGKEY --sign builder package.deb" to sign packages that have already been created but not yet signed. Remember to type the actual Debian file's name and specify the "keyid".
Check the File
By now, the Debian file should have been successfully created. However, some errors may exist. To check for errors, first type "dpkg -I ./*.deb" to see the information about the Debian file to ensure obvious errors are caught (like if the wrong version number was used). Then, execute "lintian -ciI ./*.deb" to have lintian try to find errors. If errors were found, go back and fix the errors and then rebuild the package.
Use the "licensecheck" command on the source files to ensure that the licenses applied to the files are compatible. If only one license is used, then this check is not needed. To use the command, run it like “licensecheck -r ./directory/to/check”.
Once all of the errors have been fixed, try to install the package to ensure that it works (dpkg -i [pkg]).
Upload to Repo
To upload a built package to a repository, execute "reprepro -b /path/to/repo includedeb production script-parser_3.7_all.deb". As a substitute, developers could use “dput ppa:repo/ppa ./name_ver-pkgver_source.changes” as recommended by Launchpad for uploading software to Launchpad PPAs.
Other Environment/Project Variables
Here are some other environment variables developers may want to set to make the packaging process easier.
DEBFOLDER=~/somescripts
DEBVERSION=1.0
DEBFOLDERNAME=$DEBFOLDER-$DEBVERSION
For more information
https://www.debian.org/devel/wnpp/
http://packages.ubuntu.com/trusty/
http://packages.ubuntu.com/utopic/
http://packages.ubuntu.com/
http://manpages.ubuntu.com/manpages/trusty/en/man7/debhelper.7.html
http://manpages.ubuntu.com/manpages/trusty/en/man1/debuild.1.html
https://wiki.debian.org/IntroDebianPackaging
http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/
Preparing for the Build
Before building, install the needed packages using the two commands below. The installed tools are needed to create a variety of Debian packages.
Code:
apt-get install build-essential autoconf automake autotools-dev dpkg-dev cdbs
apt-get install dh-make debhelper devscripts fakeroot xutils lintian pbuilderWhen ready, be sure that the files intended for the Debian package are in a folder titled in a format like "name_version" where the "name" is the package's name in lowercase letters and numbers (if desired). "version" is the software's version.
Users will need to create a GPG key that they use to sign the Debian packages that they will create. Remember the name, email address, and password used to generate your GPG key. Also, know the KeyID of the GPG key.
For more info on GPG keys:
- http://keyring.debian.org/creating-key.html
- https://wiki.debian.org/Keysigning
- http://keyring.debian.org/
- https://wiki.debian.org/SecureApt
Be sure that the terminal being used to run the commands is in the same directory as the files intended to be packaged. In other words, the current working directory must be inside the package directory (like "name-1.0"). Next, run the two commands below, but use your own name and email that you used when making your GPG key. This allows the building process to automatically sign the Debian files.
Code:
export DEBFULLNAME="Devyn Collier Johnson"
export DEBEMAIL="[email protected]"
export GPGKEY="8C90A2B0"
export DEBSIGN_KEYID="8C90A2B0"Packaging a Script
Packaging software that is a script or some other type of software that does not need a "configure" or "Makefile" needs to be built a little differently than other package types. First, place the files to distribute in a directory that is named using a format like "name-version", where "name" is the package's name and "version" is the version. As my example, I will use the nagdev program. So, the developer would place the nagdev script and man page in the folder titled "nagdev-1.0".
Next, run something like "dh_make -s -c gpl3 -e $DEBEMAIL -p nagdev_1.0 --rulesformat dh7 --createorig" (as I did for my project), or use a command as simple as "dh_make". The command that I used creates the "copyright" file and sets the license to GPL3 (-c gpl3). The maintainer's email is set (-e $DEBEMAIL) and the package's name and version is declared (-p nagdev_1.0). The "rules" file is set to use the DebHelper version 7 format (--rulesformat dh7). The "--createorig" flag creates the *.orig.gz file, if one has not already been created.
NOTE: The package's version can also be specified with the rest of the version (-p nagdev_1.0-trusty1).
Depending on the project's needs, if the "dh_make" command asks about the package type ("Type of package: single binary, indep binary, multiple binary, library, kernel module, kernel patch?"), choose "single" by typing "s" for single-binary packages (like most packages). "i" is for architecture-independent packages, "l" is for libraries, "k" is for kernel modules, "m" is for packages with multiple binaries, and "n" is for kernel patches. Alternately, the developer can use the letters specified as parameters so that the dh_make command never asks. For instance, "dh_make -i" indicates that an architecture-independent package will be generated. Use "--kpatch" for kernel patches. See "man dh_make for more info.
Afterwards, a "debian" directory is generated. Running that command will generate a variety of template files for your project that are placed in that "debian" folder. For instance, a "control" file will be seen that will need some modifications. Some files (like "compat") are ready for use without tweaking. These templates help developers save time by having ready-made files that need minor edits. Not all of the files are needed. For instance, if a developer has already created a man page for their program, then the man page templates are not needed. The only file here that is required is "control". However, it is strongly recommended that the “copyright”, “rules”, and “compat” files also be included. Directories that are generated (like “source”) should also be kept for use.
NOTE: Most of the "*.ex" files are seldomly needed, so type "rm ./debian/*ex; rm ./debian/*EX" in a terminal to delete all of them.
After taking the time to tweak the files that are needed for the project, remove the ones that are not going to be used. Next, make an "install" file that will specify where the files will be installed. Inside this file, type a file's name (like "nagdev.1.gz") and then specify the intended install location (such as "usr/share/man/man1/") separated by a space. The leading (first) slash is not required as can be seen in my example below. Wildcards are permitted in this file.
"Install" File
Code:
nagdev usr/bin/
nagdev.1.gz usr/share/man/man1/Once finished, execute "dpkg-buildpackage -rfakeroot -k$GPGKEY" in a terminal to create the Debian file. If you get errors that state the package was not signed, then try executing "sudo dpkg-buildpackage -k$GPGKEY". If that also fails, then ensure you are using the correct name, email address, and KeyID.
NOTE: Notice the use of the "-rfakeroot" parameter or the use of "sudo". This is necessary because the Root user on all systems has the same User ID (UID). The files in a Debian package must have the proper UID associated with them. Using a regular user's UID would cause problems.
If the package does not need to be signed, try running “debuild -us -uc” instead of dpkg-buildpackage.
Alternately, when packaging for repo/PPA servers like Launchpad, use “debuild” instead of “dpkg-buildpackage”. For the nagdev project, “debuild -S -rfakeroot -k$GPGKEY” was used for the Launchpad Debian files.
Below are examples of what developers should see when checking the finished Debian package.
Packaging a Binary
To package a binary, perform the same actions as mentioned for script packaging. However, be sure the control file lists the proper system architecture. Also, select the proper package type (a single binary). Do not include the “Source” field in the control file, unless the source package uses a different package name than the binary package.
Packaging Source Code
Sometimes, developers may want to distribute their program as source code so that users can compile the program on their system. Packaging source code is just like it is for scripts, except some minor differences. The first step that should take place is listing all dependencies for build-time. Run "dpkg-depcheck -d ./configure" to get a list of needed packages for build-time. Some of the listed packages may also be needed even after the package is installed. The list will need to be added to the "Depends" and "Build-Depends" depending on when the software is needed by your package. Next, run "sudo apt-get build-dep [pkgs]" to install the needed software for build-time. Then, perform the other steps for building a Debian file. Once done, be sure to test the package.
It helps to understand the difference between the "Depends" and "Build-Depends" packages. The "Depends" are needed for the program to run while the "Build-Depends" are needed when the software is being compiled/built. For example, a package may need "libssl-dev" to get the headers (*.h) during build-time, but then need "libssl" during runtime.
When creating source packages containing code that needs to be compiled, the source package should contain a Makefile and a “configure” script.
FUN FACT: The version number “1.0-1” for a Debian file has a special meaning. The “1.0” is the software's version number and the “-1” refers to the Debian package. So, if a bug is fixed in the package (like an error in the control file) the “-1” is incremented. Both “1.0-1” and “1.0-2” contain the same software, but “1.0-2” (hopefully) has less package bugs.
Packaging Upstream Tarballs
To package a tarball, perform the following actions.
# Rename the tarball (replace hyphens with underscores)-
mv project-1.0.tar.gz project_1.0.orig.tar.gz
# Unpack
tar xf project_1.0.orig.tar.gz
# Make sure the unpacked tarball's directory is “project-version”
cd project-1.0
mkdir debian
# Specify version and package name
dch --create -v 1.0-1 --package project
# Make any edits the files (like control)
# Generate the Debian file
debuild -us -uc
Set Layout
If the files that are to be packaged are already set in the proper Debian-file layout and all the special files have been created (like "control"), the developer can run "dpkg-deb -b DIRECTORY" to create the Debian file. This is helpful if a Debian file has been uncompressed and a file has been changed (and the md5sums file). Developers can use this to make minor changes after packaging a new file. Assume a developer has forgotten to fix a spelling error in a file. With the dpkg-deb tool, the fix can be applied quickly. This tool is useful on directory structures like the one below.
Code:
script-parser_3.7-1_all/DEBIAN/control
script-parser_3.7-1_all/DEBIAN/md5sums
script-parser_3.7-1_all/usr/bin/script-parser
script-parser_3.7-1_all/usr/share/man/man1/script-parser.1.gzNOTE: If one of the files in the “DEBIAN” folder were to be changed and then repackaged, then the new package would be “script-parser_3.7-2_all.deb”. The “-2” indicates the package's version. The “3.7” refers to the software's version.
Create md5sums
Use the “dh_md5sums” to create the needed “md5sums” file if a Debian files is missing that file or if a package has been uncompressed due to a minor edit. Alternately, use the “md5sum” command to get the checksum of a single file and replace the former entry if one or few files have been changed. For instance, to update the “md5sums” file for the “script.sh” file, execute “md5sum ./path/script.sh”. Then, paste the output in-place of the old checksum.
Sign Already-Made Packages
Type "dpkg-sig -k$GPGKEY --sign builder package.deb" to sign packages that have already been created but not yet signed. Remember to type the actual Debian file's name and specify the "keyid".
Check the File
By now, the Debian file should have been successfully created. However, some errors may exist. To check for errors, first type "dpkg -I ./*.deb" to see the information about the Debian file to ensure obvious errors are caught (like if the wrong version number was used). Then, execute "lintian -ciI ./*.deb" to have lintian try to find errors. If errors were found, go back and fix the errors and then rebuild the package.
Use the "licensecheck" command on the source files to ensure that the licenses applied to the files are compatible. If only one license is used, then this check is not needed. To use the command, run it like “licensecheck -r ./directory/to/check”.
Once all of the errors have been fixed, try to install the package to ensure that it works (dpkg -i [pkg]).
Upload to Repo
To upload a built package to a repository, execute "reprepro -b /path/to/repo includedeb production script-parser_3.7_all.deb". As a substitute, developers could use “dput ppa:repo/ppa ./name_ver-pkgver_source.changes” as recommended by Launchpad for uploading software to Launchpad PPAs.
Other Environment/Project Variables
Here are some other environment variables developers may want to set to make the packaging process easier.
DEBFOLDER=~/somescripts
DEBVERSION=1.0
DEBFOLDERNAME=$DEBFOLDER-$DEBVERSION
For more information
https://www.debian.org/devel/wnpp/
http://packages.ubuntu.com/trusty/
http://packages.ubuntu.com/utopic/
http://packages.ubuntu.com/
http://manpages.ubuntu.com/manpages/trusty/en/man7/debhelper.7.html
http://manpages.ubuntu.com/manpages/trusty/en/man1/debuild.1.html
https://wiki.debian.org/IntroDebianPackaging
http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/
Attachments
Last edited:
