Basic packaging primer

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 <youremail@example.com>)
+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 <toor@toor-runcible>  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 <me@example.com>  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
 ```
 
-```
+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.