diff options
Diffstat (limited to '')
| -rw-r--r-- | debian/README.source | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source new file mode 100644 index 0000000..15c11bf --- /dev/null +++ b/debian/README.source @@ -0,0 +1,116 @@ +firmware-nonfree +================ + +Upstream +-------- + +firmware-nonfree is based on the linux-firmware.git repository, which +does not currently make tarball (or tagged) releases. Also, some of +its contents are not clearly redistributable, and some are obsolete +for Debian's purposes. +git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git + +We set the upstream version to the date of the last commit and use +uscan to generate a tarball from upstream git. The Files-Excluded +field in 'debian/copyright' lists file patterns that should be +excluded from the tarball. + +We also pull module information from Linux binary packages. To update +this information, run: + + debian/bin/update-modinfo + +You can optionally pass a specific kernel release string or directory +in which to look for modules. + +Licences +-------- + +The upstream source includes the file 'WHENCE' which lists the licence +and any source code for each file. The script +'debian/bin/check_upstream.py' will warn about any files that aren't +recognised to be distributable based on the information in 'WHENCE' +and that haven't been excluded. + +Each binary package is assumed to have a different licence(s). The +installed 'copyright' file is taken from the 'LICENSE' file in its +subdirectory. + +Some firmware redistribution licences require us to prompt the user to +accept an EULA. In this case, put the EULA text in 'LICENSE.install' +and set the [base] license-accept field to 'required'. There is no +upstream provision for EULAs. + +Binary package definition +------------------------- + +The binary package definitions are placed under 'debian/config' and +written in a format similar to INI files, parsed using the Python +ConfigParser module +<https://docs.python.org/3/library/configparser.html>, + +The [base] packages field in the top-level 'defines' file lists all +the binary package names, without the fixed prefix 'firmware-'. + +For each binary package, there is a subdirectory with matching name +(again without the prefix) containing another 'defines' file with +metadata. Any non-upstream firmware files are also included in +these subdirectories. + +The script 'debian/bin/check_upstream.py' will list the upstream +firmware files that are non-free but not assigned to any binary +package. + +Required metadata: + +[base] desc: Short description of related hardware, used in Description +[base] files: List of files to be included, one per line +[base] longdesc: Longer description of related hardware and drivers, used in + Description. + +Optional metadata: + +[base] uri: Upstream URL, used as Homepage and in copyright file. Not + needed if the contents come from linux-firmware.git. +[base] license-accept: Set to 'required' if we must prompt the user to + accept a EULA on installation +[base] license-title: Title of the EULA +[base] support: Set to 'initramfs-tools' if update-initramfs should be + invoked after installation +[base] replaces: Used as Replaces field +[base] conflicts: Used as Conflicts field +[base] provides: Used as Provides field + +Optional per-file metadata: + +[<filename>_base] desc: One-line description for this file, used in + package description +[<filename>_base] version: Verson number for this file, used in package + description + +To re-generate debian/control (and other files) based on these +definitions: + +1. Install the current linux-support-<kernelversion> package +2. Ensure debian/rules.defs has the right value of KERNELVERSION +3. If the 'orig.tar' archive is not yet available, retrieve it as follows: + ``uscan --download-version <upstream-version>`` (<upstream-version> is f.e. ``20230210``) + To retrieve <upstream-version> programmatically, use f.e. this: + $(head -n1 debian/changelog | sed 's/.*\([[:digit:]]\{8\}\).*/\1/') + Combined that results in: + ``uscan --download-version $(head -n1 debian/changelog | sed 's/.*\([[:digit:]]\{8\}\).*/\1/')`` +4. Run: debian/rules orig +5. Run: debian/rules debian/control + +To update the current package's changelog with the new upstream version: + +1. Run: PYTHONPATH=/usr/share/linux-support-<version>/lib/python \ + debian/bin/release-update /path/to/linux-firmware-repository + + This will update debian/changelog with the changes added between + the commit of the current package version and the HEAD commit found in the + linux firmware repository, passed as argument. + +2. Remove entries regarding firmwares files not packaged + + -- Ben Hutchings <benh@debian.org>, Sat, 22 Jan 2022 21:05:51 +0100 |