add HACKING/mksource.md

1 files changed, 92 insertions, 0 deletions

diff --git a/HACKING/mksource.md b/HACKING/mksource.md
new file mode 100644
index 0000000..01d759d
--- /dev/null
+++ b/HACKING/mksource.md
@@ -0,0 +1,92 @@
+This is the internal libremakepkg program flow for a PKGBUILD with mksource().
+
+<pre>
+Given:
+  * a PKGBUILD with a mksource() function and a repo.parabola.nu URL in source()
+  * /etc/makepkg.d/librefetch.conf is sourced by makepkg.conf
+  * the checksum has be generated with: `librefetch -g`, and added to mksha256sums()
+  * mk*sums() is populated with a checksum for each mksource() (use: `librefetch -g`)
+  * *sums() is populated with 'SKIP' for each source() (add it before publishing the PKGBUILD)
+
+/usr/bin/libremakepkg
+  -> msg 'Starting pre-build activities...'
+  -> msg 'Downloading sources...'
+  -> /usr/lib/libretools/chroot/makechrootpkg.sh::download_sources()
+
+/usr/lib/libretools/chroot/makechrootpkg.sh::download_sources()
+  -> /usr/bin/makepkg --allsource (w/ special ENV and in-chroot makepkg.conf)
+
+/usr/bin/makepkg --allsource ($SOURCEONLY == 2):
+  -> msg "Making package:"
+  -> /usr/share/makepkg/source.sh::download_sources('allarch')
+
+/usr/share/makepkg/source.sh::download_sources():
+  -> msg "Retrieving sources..."
+  -> (/usr/bin/librefetch is download agent)
+
+/usr/bin/librefetch::doit()
+  -> 'download' mode ($src == PKGBUILD::source() , $inmirror == true)
+    -> if found
+      -> return to /usr/bin/makepkg
+    -> if not found
+      -> 'create' mode
+      -> /tmp/<SPECIAL>/makepkg -p /tmp/<SPECIAL>/PKGBUILD
+
+/tmp/<SPECIAL>/makepkg (SOURCEONLY == 0):
+  -> msg "Making source:"
+  -> msg "Checking source dependencies..."
+  -> /tmp/<SPECIAL>/source.sh::download_sources('allarch')
+
+/tmp/<SPECIAL>/source.sh::download_sources():
+  -> msg "Retrieving sources..."
+  -> (/usr/bin/librefetch is download agent)
+
+/usr/bin/librefetch::doit()
+  -> 'download' mode ($src == PKGBUILD::mksource() , $inmirror == false)
+  -> return to /tmp/<SPECIAL>/makepkg
+
+/tmp/<SPECIAL>/makepkg (post-return from /usr/bin/librefetch):
+  -> NOTE: all standard PKGBUILD functions are stubbed out,
+             with the only purpose to run the real PKGBUILD::mksource()
+           the standard functions in the real PKGBUILD will run later in the chroot
+  -> msg "Validating source files"
+  -> msg "Extracting sources..."
+  -> msg "Starting prepare()"
+  -> msg "Starting build()"
+    -> msg "Starting mksource()"
+    -> PKGBUILD::mksource()
+  -> msg "Starting check()"
+  -> msg "Starting package()"
+  -> msg "Creating package"
+  -> msg "Finished making:"
+
+NOTE: here we rewind back to /usr/lib/libretools/chroot/makechrootpkg.sh::download_sources()
+      to get/create the source-ball signature
+
+/usr/bin/librefetch::doit()
+  -> 'download' mode
+    -> if not found
+      -> 'create' mode ($src == PKGBUILD::source() , $inmirror == true)
+        -> /usr/bin/librefetch::create_signature()
+
+/usr/bin/librefetch::create_signature()
+  -> msg "Signing package..."
+  -> /usr/share/makepkg/integrity.sh::check_source_integrity()
+    -> /usr/share/makepkg/integrity/verify_checksum.sh
+      -> msg "Validating source files"
+    -> /usr/share/makepkg/integrity/verify_signature.sh
+      -> msg "Verifying source file signatures with gpg"
+
+NOTE: here we rewind back to /tmp/<SPECIAL>/makepkg
+
+/tmp/<SPECIAL>/makepkg:
+  -> msg "Source package created:"
+  -> exit
+
+NOTE: then we rewind back to /usr/lib/libretools/chroot/makechrootpkg.sh::download_sources()
+      which returns to /usr/bin/libremakepkg
+
+/usr/bin/libremakepkg:
+  -> msg "Starting to build the package"
+  -> NOTE: build package in the normal way
+</pre>