One of the significant defining features of abuild is that it will automatically build items to satisfy dependencies. Most of the time, this is useful and helpful behavior, but there are certain cases in which it can actually get in the way. For example, you may have one build tree that provides common code, which you may want to build manually in advance of building everything else. Then you may want to kick off parallel builds of separate dependent trees on multiple platforms simultaneously and be able to be sure that they won't step on each other by all trying to build the shared tree at the same time. In cases like this, you might want to tell abuild to assume the shared tree is built and to treat it as read-only.
To support this and similar scenarios, abuild allows you to
explicitly designate specific paths as read-only on the command
line.
[27]
Most of the time, specifying a read-only path is as simple as
invoking abuild with the
--ro-path=
option for the directory you want to treat as read-only. There
may cases, however, where you want a much more specific degree of
control. When you need it, it's there. Here we describe the
exact behavior of the directory--ro-path and
--rw-path options.
Both --ro-path=
and dir--rw-path=
may appear multiple times.
dir
If neither option appears, all build items are writable. (Except those in backing areas; backing areas are always read-only.)
If only --ro-path appears, build items are
writable by default, and only those located under any specified
read-only path are read-only.
If only --rw-path appears, build items are
read-only by default, and only build items
located under a directory specified with
--rw-path are writable.
If both --ro-path and
--rw-path are specified:
Either every --ro-path must be a path under
some --rw-path, in which case build items
are read-only by default,
or every --rw-path must be path under some
--ro-path, in which case build items are
writable by default.
In this case, the writability of items is determined by the lowest directory actually specified (start with the item's directory and walk up the file system until you find a directory explicitly mentioned), using the default of none is found.
This seems more complicated than it really is, so let's look at a
simple example. Suppose you have the directory structure
a/b/c/d. If you specified
--ro-path=a/b --rw-path=a/b/c, all read/write
paths are under some read only path, so build items are writable
by default. Everything under a/b/c is
writable, and everything under a/b that is
not under a/b/c is
read-only. Use of --ro-path and
--rw-path together basically lets you make a
particular area read only and then give exceptions. Likewise, you
can make everything read-only by default, and then make only a
specific directory read-write, again make exceptions to that.
These rules make it possible to unambiguously create any combination of read-only/writable build items without having the order of the arguments matter. If you're sufficiently determined, you can use this mechanism to precisely control which items should be read-only and which should be writable.
Paths specified may be absolute or relative. Relative paths are
resolved relative to the starting directory of abuild. They are
converted internally to absolute paths after any -C
option is
evaluated.
start-directory
[27] In abuild 1.0, we had a different mechanism for addressing this need: read-only externals. There were several problems with read-only externals, though: they were ambiguous since whether a tree was read-only or not would depend on how abuild came to know about it through other trees, they were not granular as you could only control this at the tree level, and they were inflexible: you might set them up to address the needs of a particular build, and then have them get in the way of other builds. When externals were replaced by named trees and tree dependencies, we dropped support for read-only externals and replaced them with read-only paths, which are much more flexible and which make the decision a function of the specific build rather than of the build trees, as it always should have been.