Table of Contents
This chapter presents a summary of the major changes to abuild that were introduced in version 1.1. If you are already familiar with abuild 1.0, this material should help you come up to speed with version 1.1 fairly quickly.
With few exceptions, abuild 1.1 is able to build trees that
version 1.0 could build, which should make it possible, in almost
all cases, to operate in a mixed 1.0/1.1 environment during a
transitional period. Once you are ready to start taking full
advantage of new functionality in 1.1, it is recommended that you
upgrade your trees. Abuild includes a utility that will do
almost all of the work of upgrading your
Abuild.conf files. You will have to perform
upgrades to your Abuild.mk files manually,
though there are relatively few such upgrades, and most build
items will not require any changes. For details on the upgrade
process, please see Appendix C, Upgrading from 1.0 to Version 1.1.
Please do not use the list below to try to upgrade your build
trees manually. You shouldn't go through this list and start
manually fixing your Abuild.conf files.
Doing this will only waste your time and making the automated
upgrade process less reliable. There is a lot of complex logic
involved in doing the upgrades, so you're best off leaving it to
abuild which has the benefit of knowing the entire build tree
structure of all your trees. Refer to Appendix C, Upgrading from 1.0 to Version 1.1 for details.
As a general rule, we avoid making non-compatible changes in abuild minor releases. There are some instances, however, in which supporting the old feature is very difficult or problematic in comparison to fixing existing build trees. In all cases, there is a solution that provides the desired functionality that will work in a hybrid 1.0/1.1 environment.
The make backend now loads the toolchain support file
before your Abuild.mk
file. This will almost never make a difference, and it allows
build items to manipulate or override variables defined by the
toolchain. This greatly simplifies things like selectively
overriding warning or optimization flags, and is also used by
the new variables that allow for tighter configuration of the
msvc toolchain. It's possible that
certain incorrect Abuild.mk code that you
might have gotten away with in the past may cause problems now
as a result of this change. This is discussed in Section C.2, “Potential Upgrade Problems: Things to Watch Out For”.
Absolute path externals are no longer supported. Use of the
absolute path externals or of the -winpath
option in the external-dirs key will
result in an error message. If you are relying on absolute
path externals, you can replace them with relative-path
externals, and make the relative path externals be empty except
for an Abuild.backing file that points to
the absolute path previously referenced. This provides the
exact functionality of the absolute path external. You will
use this only as a temporary workaround, since after you
upgrade your trees to version 1.1, you will no longer have any
external-dirs keys.
Read-only externals are no longer supported. In abuild 1.1,
you can force parts of your build tree to be read only by using
the much more flexible --ro-path and
--rw-path options, described in Chapter 12, Explicit Read-Only and Read/Write Paths. In order to allow hybrid
1.0/1.1 environments to work properly, abuild 1.1 will allow
the -ro option to be specified in your
Abuild.conf's
external-dirs keyword, but it will issue a
warning and ignore the option. Once you upgrade to version
1.1, you will no longer have any
external-dirs keys anyway.
The value of the parent-dir key must now
point up in the file system. That is, if the value has more
than one path element, every path element must be
“..”. (So, for example,
“../..” is valid.) Once you
upgrade your build trees to abuild 1.1, you will no longer
have any parent-dir keys. This check for
existing parent-dir keys effectively just
makes sure that whatever abuild 1.1 would now automatically
figure out is consistent with you explicitly specified in your
1.0 trees.
Each value of the child-dirs key must now
point down in the file system. That is, the path element
“..” may not appear in a
child-dirs key. This check is important
to ensure that whatever parent/child relationships between
build items abuild 1.1 would now automatically figure out is
consistent with you explicitly specified in your 1.0 trees.
The values of child-dirs keys may not be or cross over any symbolic links. In most cases, use of symbolic links for child directories would not have worked in abuild 1.0 anyway and would have resulted in a cryptic error message. Now abuild explicitly detects and disallows this case.
If you use multi-element paths in your
child-dirs keys (skipping directories),
none of the intermediate directories may contain
Abuild.conf files. In other words, you
can't interleave unrelated abuild trees.
Trying to do this with abuild 1.0 would have been crazy
anyway, but abuild would not have noticed if you tried. Now
it will notice and prevent you from doing so. This check is
required in order to ensure that abuild 1.1 is always able to
accurately locate the parent of any build item.