From e6a34609f2ad50f7b0448588ebbb87850dbc2d37 Mon Sep 17 00:00:00 2001 From: Drew Bednar Date: Thu, 26 Jun 2025 15:25:26 -0400 Subject: [PATCH] Basic packaging primer --- docs/PACKAGING.md | 97 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 91 insertions(+), 6 deletions(-) diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md index 9d561db..baf93bd 100644 --- a/docs/PACKAGING.md +++ b/docs/PACKAGING.md @@ -43,9 +43,15 @@ A binary package for can be constructed for Go with as little as a `control` an ### Control File -The `debian/control` file +The `debian/control` file defines a package's metadata and build-time parameters. Refer to https://www.debian.org/doc/debian-policy/ch-controlfields.html for indepth descriptions of all the available fields. The most minimal file can contain -- control +``` +Package: YOUR_PACKAGE_NAME +Version: YOUR_DEBIAN_PACKAGE_VERSION +Architecture: YOUR_TARGET_PROCESSOR_ARCHITECTURE +Maintainer: YOUR_EMAIL(Ex: Your Name ) +Description: YOUR_PACAKGE_DESCRIPTION +``` ### Changelog @@ -97,12 +103,14 @@ cp ./build/foo ./dist/foo_0.1.0-1/usr/local/bin/foo chmod +x ./dist/foo_0.1.0-1/usr/local/bin/foo ``` -Now create a `control` file under the `DEBIAN/` directory +Create a `control` file under the `DEBIAN/` directory ```bash touch ./dist/foo_0.1.0-1/DEBIAN/control ``` +And using a text editor add: + ``` Package: foo Version: 0.1.0-1 @@ -119,18 +127,95 @@ touch ./dist/foo_0.1.0-1/DEBIAN/changelog We will use the debchange tool `dch` to create the first entry in our file. Use `man dch` to learn more about all the options available to you for editing these entries. -``` +```bash dch --changelog ./dist/foo_0.1.0-1/DEBIAN/changelog --create ``` Since we did not set envvars for things like our package or maintainer email you will see warnings. Press enter to continue and you will drop into an text editor with a basic template. +output: +``` +PACKAGE (VERSION) UNRELEASED; urgency=medium + + * Initial release. (Closes: #XXXXXX) + + -- toor Thu, 26 Jun 2025 14:28:27 -0400 +``` + +Change the contents of this entry as needed and save. + ``` +foo (0.1.0-1) unstable; urgency=low + + * Initial release. + + -- me Thu, 26 Jun 2025 14:28:27 -0400 +``` + +Now we can build the package with `dpkg-deb`. Again see `man dpkg-deb` for more information. +```bash +cd ./dist +dpkg-deb --build foo_0.1.0-1/ + +pkg-deb: building package 'foo' in 'foo_0.1.0-1.deb'. ``` -Change the contents of this entry as needed. +You should now have successfully built a `foo_0.1.0-1.deb` in your ./dist/ directory. + +You can view the contents of this pacakge + +```bash +dpkg-deb --contents ./foo_0.1.0-1.deb` + +drwxrwxr-x toor/toor 0 2025-06-22 15:44 ./ +drwxrwxr-x toor/toor 0 2025-06-22 15:44 ./usr/ +drwxrwxr-x toor/toor 0 2025-06-22 15:44 ./usr/local/ +drwxrwxr-x toor/toor 0 2025-06-22 15:44 ./usr/local/bin/ +-rwxrwxr-x toor/toor 3433713 2025-06-22 15:44 ./usr/local/bin/foo +``` + +You can test the installation of this new package + +```bash +sudo dpkg -i ./foo_0.1.0-1.deb + +Selecting previously unselected package dirp. +(Reading database ... 217265 files and directories currently installed.) +Preparing to unpack foo_0.1.0-1.deb ... +Unpacking foo (0.1.0-1) ... +Setting up foo (0.1.0-1) +``` + +We can check that a the binary is now in our `/usr/local/bin` + +```bash +which foo + +/usr/local/bin/foo +``` + +We can see which version of the package is installed + +```bash +dpkg -l foo + +Desired=Unknown/Install/Remove/Purge/Hold +| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend +|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) +||/ Name Version Architecture Description ++++-==============-============-============-================================= +ii foo 0.1.0-1 amd64 foo - A Go application +``` + +And we can remove it. + +```bash +sudo dpkg -r foo +(Reading database ... 217268 files and directories currently installed.) +Removing dirp (0.1.0-1) ... +dpkg: warning: while removing dirp, directory '/usr/local/bin' not empty so not removed ``` -``` \ No newline at end of file +We can disregard the warning because the package manager is doing what its supposed to. It removed the `/usr/local/bin/foo` and attempts to clean up all directories it may have created in the process. Once it finds existing files in the directory structure it was avoid deleting them.