Ordinarily, when A depends on B, abuild requires that B be buildable on every platform that A is being built on. In this case, the instance of A being built on platform p depends specifically on the instance of B being built on platform p. Under these rules, it would be impossible for A to depend on B if B couldn't be built on all of A's platforms. This would make it impossible for a platform-independent item to depend on any object-code or Java build items or for object-code and Java build items to depend on each other. (There is a special case that any item can depend on a platform-independent build item.) To make these other cases possible, abuild allows a dependency to declare a specific platform using the -platform flag. Rather than declaring a platform by name, the argument to the -platform argument is either a platform type or a platform-type-qualified platform selector. In this case, the instance of A on each of its platforms depends on the specifically selected instance of B.

To choose which of B's platforms will be used, abuild picks the first platform in the given type that matches the platform selector. Matches are performed using the same technique as when platform selectors are specified on the command line with two exceptions: the criteria field may be omitted, and the selector only ever matches a single platform even if * appears as one of the fields. Also, abuild ignores any platform specifiers given on the command line or in the environment when resolving cross-platform dependencies. The rationale for this is that platform selectors specified on the command line or the environment should only ever affect what is actually built. It should never affect the shape of the internal dependency graph. (For details on the internal, platform-aware dependency graph, see Section 29.6, “Construction of the Build Graph”.)

The other situation in which a build item may depend on another item with different platforms occurs with pass-through build items. In this case, 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 As and the Bs based on platform type (see Figure 21.1, “Multiplatform Pass-through Build Item”).

Figure 21.1. Multiplatform Pass-through Build Item

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

The documentation doesn't provide a specific example that illustrates that case because this type of usage would be fairly unusual. ^[38] 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. To fully understand why this works, please see Section 29.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 multiple languages.