Appendix B. Major Changes from Version 1.0 to Version 1.1

Table of Contents

B.1. Non-compatible Changes
B.2. Deprecated Features
B.3. Small, Localized Changes
B.4. Groovy-based Backend for Java Builds
B.5. Redesigned Build Tree Structure

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 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.

B.1. Non-compatible Changes

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 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 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.