Maybe it’s somehow not clear in the documentation, as I see this kind of mistakes happens quite a lot. The obvious reason is that sometimes it happens you oversee something, but as a lot of these problems happen on packages maintained by the same person or group, I start to think this is not clear enough. In particular I’m afraid the reasoning why you should make sure that the two variables are filled in properly is not clear enough.
First of all, at the moment we unfortunately have only two dependency variables, DEPEND and RDEPEND. Cross-compiling and proper multilib support would need two more, splitting both in executed and linked-against packages, as the first just need to be available in some executable form, while the latter need to have the same ABI as the program being built. But that’s a story for another day.
So we’re back to DEPEND and RDEPEND. The first is the set of packages that has to be available during build, as this is what we have, it has to have both tools used to build, and library linked against. RDEPEND instead is the set of packages that has to be available during execution of the program. This means it has to have the libraries linked against, if shared – which is what we want with pretty rare exceptions – and the programs that are ran by the program at runtime.
Programs like unzip and other tools used to extract the source archive as DEPEND and not RDEPEND. Unless they are executed by the software itself, like Amarok does (alas), in which case they are RDEPEND and not DEPEND. Build tools, like pmake or build systems like imake, scons or cmake, generators like flex and bison, rust or swig are DEPEND only, as they are used during source build. Software used for the tests is DEPEND only and subject to the test USE flag.
Fonts, when used by a graphical application, are most likely useful only at runtime. Rarely tools require them at buildtime, but it happens, for instance when you use gd to generate some images for the documentation. By the way, Doxygen is a build-only dependency, and should always be subject to the doc USE flag!
Most, but not all, packages for interpreted languages like Perl, Python and Ruby extensions have little or no build dependency (they are not built, most of the times) but may have lots of runtime dependencies. And might have build-time dependencies under test USE flag for the tests.
When a package install no shared library, it’s usually just one of the two between DEPEND and RDEPEND, as rarely the software checks at build-time what it will execute at runtime, which is quite good for us, as we’ll see. If the configure script for a package just checks if the tools are available, but doesn’t use them, it’s a good idea to either fool it through cache values, or change it so that the tests are not done. Again, we’ll see why.
So okay, why should we spend time to make sure the dependencies are right? Shouldn’t people install the packages anyway for both build and runtime? Well, sort of. When you prepare a filesystem image for another system through ROOT=, you usually just want the packages needed at runtime, not at buildtime. This means you don’t want autotools, you don’t want pkg-config, you don’t want lzma and so on. Often this is done through cross-compile, and this saves you cross-compiling for instance Perl – which, if you didn’t know, is not cross-compilable at this stage – but it might also apply to systems that are maintained through binary packages, as you don’t want to have to distribute extra packages, especially if the target machines don’t have as much space as you’d like them to be.
But having proper DEPEND/RDEPEND also helps testing. For instance, if I’m to check whether a given package builds after a flex bump, I don’t want to have to install all its runtime dependencies, as that would stop me from using the
-B option of emerge to try just the build.
This also means that if you know for sure that the package calls the linker with a given library at build-time, but the library is never ever used (and for instance
--as-needed drops it), you should be patching the package not to try to use it at build-time, or use it only conditionally, so that you don’t depend on a package that is not useful at all.
Please, when you write the dependencies of an ebuild, think a lot how to get them right, make sure that datafiles are only runtime dependencies unless they are used for build stuff too, make sure that build tools are not leaked at runtime. Basically, look at the package from every angle and make sure that you actually get the thing how it is supposed to be.