24.4. Dependencies and Pass-through Build Items

When a build item does not declare any platform types and has dependencies on items of multiple platform types, that item because a pass-through build item and is handled slightly differently with respect to dependencies. Specifically, a pass-through build item is implicitly buildable on every platform, so any build item may depend on a pass-through build item. Also if a specific instance of pass-through build item on a specific platform depends on another item for which there are no compatible platform types, that dependency is ignored. This makes it possible to use pass-through build items to provide wrappers around families of alternative build items that provide related but separate functionality for consumers of different platform types.

For example, suppose build items A1 and B1 build on platform X and build items A2 and B2 build on platform Y. If A1 and A2 depend on pass-through item P which in turn depends on B1 and B2, abuild will create effective dependencies between the A1 and A2 and also between B1 and B2 based on platform type (see Figure 24.1, “Multiplatform Pass-through Build Item”).

Figure 24.1. Multiplatform Pass-through Build Item

Multiplatform Pass-through Build Item

Pass-through item P effectively connects A1 to B1 and A2 to B2 based on their platform types.

What's really happening here is that the instance of P for X depends on B1 and ignores B2 while the instance of P on Y depends on B2 and ignores B1. If P also had a dependency on some third build item of type indep, both instances of P, and therefore effectively both A1 and B1 would also depend on the third item of type indep.

The documentation doesn't provide a specific example that illustrates that case because this type of usage would be fairly unusual. [51] Instead, we will provide a description of how it would work. Suppose you had a plugin to support VxWorks, an embedded operating system, that added a platform type vxworks, and you wanted to provide a custom threading library that worked for your native platform and for VxWorks. Suppose also that your native library implementation used boost threads but that you wanted to create a VxWorks implementation that used VxWorks native threads. You could create a pass-through build item called threads that depends on threads.native and threads.vxworks, and you could set up threads.native to have platform-types native and threads.vxworks to have platform-types vxworks. The threads build item would not declare any platform types. It would just depend on threads.vxworks and threads.native. If you now had a program that supported both native and vxworks that depended on threads, your application would use the threads.native implementation when it built on the native platforms and the threads.vxworks implementation when it built on vxworks platforms. This would happen transparently because of the pass-through build item. If you wanted to allow any build item to depend on threads even if there is no support for that item's platform type, you could also create threads.indep and make threads depend on that as well. Just keep in mind that all instances of threads will depend on the indep version even if they also depend on one of the platform-specific versions.

To fully understand why this works, please see Section 33.6, “Construction of the Build Graph”. Note that you could also put conditionals in your Abuild.interface and/or Abuild.mk to avoid having to split this into multiple build items, so this is not the only solution. The same trick would work if you wanted to create a facade for a library that was implemented in multiple languages, though it's unlikely that there would be any reason to do that: although you can have one build item that builds for multiple platform types, you can't have a single build item that builds for target types.

[51] Okay, we don't provide an example because it's tricky to make one that would be more illustrative than confusing without an actual embedded platform to work with. If we did create an example, we'd have to make up some kind of simulated embedded platform with a plugin, and that would probably create more confusion than it would be worth.