Troubleshooting package dependency issues

Here's a step-by-step guide to resolving Could not find dependency errors coming from pmbootstrap, as well as unsatisfiable constraints errors coming from apk.
== Why does this happen? ==
The errors indicate that there is an issue with the binary package repositories either of postmarketOS or of Alpine Linux. pmOS Edge is built upon Alpine's "edge" repository (as in bleeding edge), so a certain amount of breakage is expected.
In most cases a library (e.g. libcrypto.so from libressl/openssl) has been updated with an incompatible change (soname bump), and a package that was built against the previous version did not get rebuilt yet.
Triggering rebuilds is done by both Alpine and pmOS by increasing the pkgrel in the APKBUILD.
=== Alpine Linux ===
The package maintainers from Alpine trigger a rebuild for all packages that depend on a certain library at the same time as they update that library. But building packages takes time, and when a big number of packages depend on such a library, build bots may even get stuck at a package that used to compile fine a few months ago, but doesn't compile in the current environment (let's say because they don't build with the latest GCC version that Alpine has packaged).
There is a dedicated build bot for each architecture and branch combination (e.g. build-edge-armhf), and once it is stuck, it won't continue with compiling other packages in the queue. If you have some time to spare, you could actually help out with getting these packages to compile again by finding out which one is failing on build.alpinelinux.org (click the packages to see the build logs) and assisting Alpine developers in #alpine-devel. However, the quick workaround is rebuilding just the packages you need, as explained below.
=== postmarketOS ===
For postmarketOS packages, we need to trigger the rebuild manually, as soon as a library gets updated in Alpine on which one of our packages depend. We have a test case in place, that detects such breakage and we fix it in master and our binary repository as soon as we see it, typically within a day.
== Update your package index ==
Maybe the issue has already been resolved in the package repositories of postmarketOS or Alpine. pmbootstrap will automatically download the newest package indexes when they are older than four hours. Force it to download the currrent index files with:
$ pmbootstrap update
From inside the postmarketOS installation, you can do the same with:
$ sudo apk update
== Find the package name ==
=== apk ===
All packages are mentioned that depend on the shared library. Find the package that depends on the lower version of it. In the example below, this is g++-armhf-6.4.0-r5[libstdc++=6.4.0-r5] (the higher version would be libstdc++=6.4.0-r6). This means the package that needs to be rebuilt is g++-armhf.
ERROR: unsatisfiable constraints:
libstdc++-6.4.0-r6:
breaks:
g++-armhf-6.4.0-r5[libstdc++=6.4.0-r5]
satisfies: world[libstdc++]
g++-6.4.0-r6[libstdc++=6.4.0-r6]
g++-6.4.0-r6[libstdc++=6.4.0-r6]
gcc-6.4.0-r6[so:libstdc++.so.6]
lzip-1.19-r1[so:libstdc++.so.6]
gcc-6.4.0-r6:
breaks: g++-armhf-6.4.0-r5[gcc=6.4.0-r5]
satisfies: world[gcc]
g++-6.4.0-r6[gcc=6.4.0-r6]
build-base-0.5-r0[gcc]
=== pmbootstrap ===
Here the package depending on the dependency that was not found is not mentioned:
[21:38:23] ERROR: Could not find dependency 'so:libcrypto.so.42' in any aports folder or APKINDEX. See: <https://postmarketos.org/depends>
[21:38:23] Run 'pmbootstrap log' for details.
[21:38:23] See also: <https://postmarketos.org/troubleshooting>
In order to see it, run your last pmbootstrap command again, but with verbose mode (-v). For example:
$ pmbootstrap -v install
After it crashed at the same point, check pmbootstrap log for a line like the following (on the right should be the library you are interested in). The "????" is the package we are looking for. If you're having a hard time looking through the whole log, you can use pmbootstrap log -c to clear it.
????: depends on: so:libcrypto.so.42
== Find out where the package comes from ==
We need to know if the package comes from postmarketOS or Alpine Linux. The fastest way to do this is to search on pkgs.postmarketos.org - if the package appears there, then it's coming from postmarketOS. If it isn't there, check pkgs.alpinelinux.org.
Alternatively, you can change into your pmbootstrap workdir folder (by default that's ~/.local/var/pmbootstrap, and search for the package:
$ find cache_git/pmaports -name "hello-world"
cache_git/pmaports/main/hello-world
If you can find it, the package comes from postmarketOS. Otherwise from Alpine.
== Trigger a rebuild ==
=== postmarketOS ===
It might be, that we marked the package for rebuild already, so pull the latest changes from the master branch (or rebase if you are on your own branch):
$ git pull
Then try again. If the problem persists, mark all postmarketOS packages with broken dependencies for rebuild:
$ pmbootstrap pkgrel_bump --auto
When you execute the command that caused the error next time, the package should get built locally and the problem should be gone.
==== Cross compilers ====
This is a special case, because we generate the cross compilers directly from Alpine: If the error has libstdc++ and gcc-armhf involved, regenerate your gcc-armhf aport based on the latest gcc aport from Alpine (replace armhf with aarch64 etc. as necessary):
$ pmbootstrap aportgen gcc-armhf
=== Alpine Linux ===
Clone Alpine's packages to a folder outside of your pmbootstrap folder:
$ cd ~/code
$ git clone https://git.alpinelinux.org/cgit/aports
Find the package in question:
$ find -name uboot-tools
./testing/uboot-tools
Build it with pmbootstrap for the architecture in question (replace the path to pmbootstrap accordigly):
$ cp -r ./testing/uboot-tools ~/code/pmbootstrap/cache_git/pmaports/temp/
$ pmbootstrap build uboot-tools --arch=armhf
$ rm -r ~/code/pmbootstrap/cache_git/pmaports/temp/uboot_tools
= See also =
* nokia-n900: pmbootstrap install fails for libcrypto.so.42
* Dependency conflict blocks generation of hammerhead image
dependencies