From 42658df87b72255f84ab804d090a9cb5c3724ce2 Mon Sep 17 00:00:00 2001 From: Fabrice Quenneville Date: Wed, 23 Oct 2024 10:01:00 -0400 Subject: [PATCH] Add detailed Debian packaging notes - Added a comprehensive guide for creating Debian packages, including steps for source tarball creation, building control files, changelog format, and package testing. - Clarified the purpose of key Debian control files (control, rules, changelog, etc.). - Included optional `lintian` step to ensure package compliance with Debian policies. - Provided instructions for testing the built `.deb` package after installation. - Ensured versioning structure aligns with Debian conventions. These notes provide a full step-by-step process to package applications for Debian, making it easier to manage future packaging tasks. --- notes/debian packaging.md | 174 +++++++++++++++++++ notes/{pip_packaging.md => pip packaging.md} | 0 2 files changed, 174 insertions(+) create mode 100644 notes/debian packaging.md rename notes/{pip_packaging.md => pip packaging.md} (100%) diff --git a/notes/debian packaging.md b/notes/debian packaging.md new file mode 100644 index 0000000..e17d0e4 --- /dev/null +++ b/notes/debian packaging.md @@ -0,0 +1,174 @@ +# Debian packaging + +## Table of Contents + +- [Debian packaging](#debian-packaging) + - [Table of Contents](#table-of-contents) + - [Upstream documentation](#upstream-documentation) + - [Required Tools](#required-tools) + - [Packaging steps](#packaging-steps) + - [Notes](#notes) + +## Upstream documentation + +- [Packaging portal](https://wiki.debian.org/Packaging) + - [Introduction to Debian Packaging](https://wiki.debian.org/Packaging/Intro) + - [Binary package](https://wiki.debian.org/Packaging/BinaryPackage) + - [Source package](https://wiki.debian.org/Packaging/SourcePackage) +- [Simple packaging tutorial](https://wiki.debian.org/SimplePackagingTutorial) + +## Required Tools + +Ensure that you have the necessary tools (`build-essential`, `devscripts`, `debhelper`, `dh-python`, and optionally `lintian` for linting) installed on your Debian system. You can install them using `apt`: + +```bash +apt update +apt install build-essential devscripts debhelper dh-python lintian +``` + +`Lintian` is recommended as it helps ensure your package adheres to Debian standards. + +## Packaging steps + +**1. Download source archive** +You can either download the source tarball directly from GitHub or create it using Git. Since you have already created it, you can skip the wget step: + +- **Direct download (optional)**: + + ```bash + wget https://github.com/fabquenneville/mediacurator/archive/refs/tags/v1.0.1.tar.gz + ``` + +- **Using Git to create the tarball from tag v1.0.1 (already done)**: + + ```bash + git archive --format=tar.gz --prefix=mediacurator/ v1.0.1 -o /mnt/workbench/builds/mediacurator/v1.0.1/mediacurator_1.0.1.orig.tar.gz + ``` + +- **Using Git to create the tarball from the latest commit (already done)**: + + ```bash + git archive --format=tar.gz --prefix=mediacurator/ HEAD -o /mnt/workbench/builds/mediacurator/v1.0.1/mediacurator_1.0.1.orig.tar.gz + ``` + +**2. Extract source archive** + +```bash +tar -xvzf mediacurator_1.0.1.orig.tar.gz +``` + +**3. Create necessary folder** +Create a `debian` directory where all Debian packaging files will reside: + +```bash +mkdir debian +mkdir debian/source +``` + +**4. Create changelog** +Initialize the changelog file with your package version. Make sure to follow Debian formatting standards (`package (version) distribution; urgency=urgency-level`): + +```bash +dch --create -v 1.0.1-1 --package mediacurator +``` + +Example changelog entry: + +```text +mediacurator (1.0.1-1) unstable; urgency=medium + + * Initial release + + -- Fabrice Quenneville Wed, 23 Oct 2024 10:00:00 +0000 +``` + +**5. Create control files** +Create the necessary files for packaging: + +```bash +touch debian/control +touch debian/copyright +touch debian/rules +touch debian/source/format +touch debian/source/options +touch debian/install +``` + +Explanation of files: + +- **`control`**: Contains package metadata (dependencies, package name, description, etc.) +- **`copyright`**: Specifies copyright and license information for your package. +- **`rules`**: The main script for building the package. This file orchestrates the build process. +- **`source/format`**: Defines the source package format, e.g., "3.0 (quilt)" for most packages. +- **`install`**: Lists files to install and their destinations. + +**6. Make rules executable** +Make the `rules` file executable, as it's the main script for building the package: + +```bash +chmod +x debian/rules +``` + +**7. Add dependencies in `debian/control`** + +Make sure to declare both Python and non-Python dependencies in the `debian/control` file. For example, if your application requires `ffmpeg`: + +```text +Depends: ${misc:Depends}, ${python3:Depends}, ffmpeg +``` + +**8. Copy python source tarball** + +Copy your generated source tarball to the appropriate location for Debian packaging: + +```bash +cp ./mediacurator-1.0.1.tar.gz ../mediacurator_1.0.1.orig.tar.gz +``` + +Ensure you are in the correct directory where `mediacurator-1.0.1.tar.gz` exists before running this command. + +**9. Run lintian (optional but recommended)** + +Before building your package, it’s a good practice to run `lintian` to check for any packaging issues: + +```bash +lintian +``` + +This step ensures your package complies with Debian policy. + +**10. Build the package** + +Finally, build your Debian package: + +```bash +debuild -us -uc +``` + +**11. Test the package** +After building, you can test the package by installing it: + +**With `dpkg`** + +```bash +dpkg -i ../mediacurator_1.0.1-1_all.deb +``` + +**With `apt`** + +```bash +apt install ../mediacurator_1.0.1-1_all.deb +``` + +Then check if it works as expected. If there are missing dependencies, you can run: + +```bash +apt --fix-broken install +``` + +### Notes + +- Make sure your `debian/control` and other files are filled with the necessary package information (dependencies, description, etc.). +- Ensure that non-Python dependencies (e.g., `ffmpeg`) are listed in the `debian/control` file. +- If you encounter any issues or errors during the build process, review the output logs for clues on what might need adjusting. +- It’s a good idea to test the `.deb` package after building to ensure it installs and runs as expected. diff --git a/notes/pip_packaging.md b/notes/pip packaging.md similarity index 100% rename from notes/pip_packaging.md rename to notes/pip packaging.md