Generating and Modifying Package Template Files¶

To ensure your package has all the required files for successful installations, you must use the debmake command to generate the template files necessary to create your package.

About This Task¶

Whether you are creating a new package or updating an existing one, you should generate the template files to ensure the package has everything it needs to build and install successfully, regardless of the destination. In this procedure, you will use the debmake command to create the template files, and update them as necessary.

By default, if run with no options, and your package working directory includes all the minimum required files per Creating a Sample Application, the command will provide default values based on your environment. For example, the binary and source package name is derived from the working directory name, as well as the upstream revision. If you want to specify different values, run debmake with the –help option to see all your available customization options.

It is important to understand that each template file will be processed when you run the debuild command to compile your application package. The debuild output will provide specfic details for any missing template information. For additional information, see Building the Application Package.

Note

A set of updated template files for the fibonacci application is available at eLxr User Documentation: Samples repository.

Before You Begin¶

You must have the necessary development tools installed. For details, see Development Tools Overview and Requirements
You must have a package directory as described in Creating a Sample Application, or an existing package that you want to update.

This procedure assumes the directory structure for your package looks like this:

├─ fibonacci-1.0
│  ├── LICENSE
│  ├── Makefile
│  ├── fibonacci-1.0.tar.gz
│  └── src
│      ├── main.c
|      ├── math.c
|      └── math.h
└─ fibonacci-1.0.tar.gz

Procedure¶

Navigate to your package working directory.
```
$ cd fibonacci-1.0
```

Run the debmake command.

$ debmake

set parameters
I: =================================================================
I: package_dir     = /usr/lib/python3/dist-packages
I: base_path       = /usr
I: base_lib_path   = /usr/lib/debmake
I: base_share_path = /usr/share/debmake
I: =================================================================
I: sanity check of parameters
I: pkg="fibonacci", ver="1.0", rev="1"
I: *** start packaging in "fibonacci-1.0". ***
I: provide fibonacci_1.0.orig.tar.gz for non-native Debian package
I: pwd = "/root/elxr-dev/fibonacci-1.0"
I: $ ln -sf fibonacci-1.0.tar.gz fibonacci_1.0.orig.tar.gz
I: pwd = "/root/elxr-dev/fibonacci-1.0/fibonacci-1.0"
I: parse binary package settings:
I: binary package=fibonacci Type=bin / Arch=any M-A=foreign
I: analyze the source tree
I: build_type = make
I: scan source for copyright+license text and file extensions
I:  60 %, ext = c
W: archive type exists.  Maybe non-DFSG!
I:  20 %, ext = archive
I:  20 %, ext = Debian
I: make debian/* template files
I: found "debian/changelog"
I: debmake -x "0" ...
I: skipping :: debian/control (file exists)
I: skipping :: debian/copyright (file exists)
I: substituting => /usr/share/debmake/extra0/changelog
I: skipping :: debian/changelog (file exists)
I: substituting => /usr/share/debmake/extra0/rules
I: skipping :: debian/rules (file exists)
I: run "debmake -x1" to get more template files
I: $ wrap-and-sort

Review the new folder structure and template files. Once the debmake command completes, it creates a number of new files, called template files, in a new debian directory in the working directory. Essentially, you must review and update each template file in the debian directory. For details on each template file requirement, see Guide for Debian Maintainers: Modification to the Template Files.

The following output is from the working directory’s parent directory.

$ tree ../

├── fibonacci-1.0
│   ├── LICENSE
│   ├── Makefile
│   ├── debian
│   │   ├── README.Debian
│   │   ├── changelog
│   │   ├── control
│   │   ├── copyright
│   │   ├── patches
│   │   │   └── series
│   │   ├── rules
│   │   ├── source
│   │   │   ├── control
│   │   │   ├── format
│   │   │   ├── local-options
│   │   │   ├── options
│   │   │   └── patch-header
│   │   ├── tests
│   │   │   └── control
│   │   ├── upstream
│   │   │   └── metadata
│   │   └── watch
│   ├── fibonacci-1.0.tar.gz
│   └── src
│       ├── main.c
│       ├── math.c
│       └── math.h
├── fibonacci-1.0.tar.gz
└── fibonacci_1.0.orig.tar.gz -> fibonacci-1.0.tar.gz

Review and update the debian/rules template. This file defines the options that the debuild build script will run. Each option is specific to a certain function to let you specify additional lintian build options. Note that the only required option is the two lines that comprise %: dh $@.

Uncomment each line to dh $@, except for the first that specifies the location of the make command, and add a new export DEB_CFLAGS = -g line to enable debug symbols in the build.
```
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_CFLAGS = -g
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
      dh $@

#override_dh_auto_install:
#      dh_auto_install -- prefix=/usr

#override_dh_install:
  dh_missing --list-missing
      dh_install
      #dh_installman debian/fibonacci.1
```

Review and update the debian/control template to match the following example.

Source: fibonacci
Section: devel
Priority: optional
Maintainer: Your Name <your.name@youremail.com>
Build-Depends: debhelper-compat (= 13)
Standards-Version: 4.5.1
Homepage: http://elxr.org
Rules-Requires-Root: no
#Vcs-Git: https://salsa.debian.org/debian/fibonacci.git
#Vcs-Browser: https://salsa.debian.org/debian/fibonacci

Package: fibonacci
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: Simple fibonacci application to demonstrate
  packaging with eLxr.

Review and update the debian/copyright template to match the following example. For your own applications, with specific license or copyright information, you will want to ensure this file is accurate.

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: fibonacci
Upstream-Contact: your.name@elxr.org
Source: https://elxr.org
#
# Please double check copyright with the licensecheck(1) command.

Files:     *
           Makefile
           src/math.c
           src/math.h
Copyright: 2024 eLxr Dev
License:   __NO_COPYRIGHT_NOR_LICENSE__
           The Fibonacci application is public domain software.
            For the purposes of this example we keep these statements in this file
            but you should include the full text of the license here instead.


Files:     src/main.c
Copyright: 2024 eLxr Dev
License:   __NO_LICENSE__
           The Fibonacci application is public domain software.
            For the purposes of this example we keep these statements in this file
            but you should include the full text of the license here instead.

Review the remaining template files and make updates as necessary.
- changelog file. Add and entry to this file for each package update.
- README.Debian file. This is the README file for your package. Update this with as much information as necessary to help someone understand what your package does and how to get started with it.
- source directory
  - control file. Update this file if you want to perform automated testing as part of the installation. This includes specifying testcode.sh script and setting any restrictions required by the application.
  - format file. Update this file to specify the quilt version (default 3.0).
  - local-options file. Update this file to specify any local build options for the gbp-buildpackage command.
  - options file. Update this file to specify merge and commit options for patches.
  - patch-header file. Review and update this file only if you are using dgit-maint-merge. If you are using gbp-buildpackage, no updates are necessary.
- tests/control file. Same as source/control file, above.
- upstream/metadata file. Update this file to include the upstream metadata that defines your application.

Results¶

Now that your template file updates are complete, you will need to build the package with debuild. For details, see Building the Application Package.