Abuild 1.1 can operate in 1.0 compatibility mode. If you are testing out abuild 1.1 on a build tree that is still under active development with abuild 1.0, you should obviously wait before you try to upgrade the trees. Once you have upgraded your build trees, abuild 1.0 will no longer be able to build them.

As a general rule, it's best to start your upgrade process with build trees that don't have any backing areas. This will save you a lot of trouble. Most of the time, if you have backing areas and your backing areas are already upgraded, abuild's upgrade process can run without any intervention. But we'll come back to that in the next section.

Once you are ready to start upgrading, the first thing you should do is to make sure your build is working with abuild 1.0. You must be sure to start with this as a known baseline so you can be sure problems that you find during upgrade weren't already there.

The next thing you should do is to make sure your build still works with abuild 1.1 running in 1.0-compatibility mode, which you can enable by passing --compat-level="1.0" on the command line or by setting the environment variable ABUILD_COMPAT_LEVEL to “1.0”. There are a small number of non-compatible changes (Section B.1, “Non-compatible Changes”). If your build trees run into any of those, you should try to fix them in a way that is still compatible with abuild 1.0. You should fairly quickly be able to reach a point where you have a build tree that builds the same way under 1.0 and 1.1. Only when you have reached this stage should you attempt to upgrade. If you run into trouble during this process, ask for help or consult Section C.2, “Potential Upgrade Problems: Things to Watch Out For”.

Once you have your build trees in a state where your build produces identical results with both abuild 1.0 and 1.1, you should find a directory that is above all the trees you are trying to upgrade. If your intention is to upgrade an entire forest of trees at once, meaning that you wish to upgrade a collection of build trees that refer to each other through external-dirs, you should go to a common ancestor of all those trees. This will be the root of your upgraded build forest. If you only wish to upgrade specific trees, you can just go to the root of the trees you are upgrading. The upgrade process will allow you to upgrade your forests a little bit at a time. This is especially important for distributed development environments in which different trees are maintained by different teams. Whichever case you pick, your starting directory must either contain a root build item or be above the top of trees with root build items. You can't pick a directory that's in the middle of a build tree. For example, you can't start in a directory that has a parent-dir key or that is referred to as a child in a higher Abuild.conf file.

Once you have identified your start directory, you should run abuild --upgrade-trees and follow the upgrade process as described in Section C.3, “Upgrade Procedures”. At the end of that process, your trees will be upgraded, but you are not done yet! There are still a few ways in which things can be broken, so read on.

After you have finished this stage of the upgrade process, you should once again run abuild in 1.0-compatibility mode to make sure your build still works. If you run into problems, please consult Section C.2, “Potential Upgrade Problems: Things to Watch Out For”.

Once your build is once again working as it should, you will want to address deprecation errors that are reported by the backends. Mostly this would involve moving build item-supplied rules from Rules.mk to their new locations under rules (see Chapter 22, Build Item Rules and Automatically Generated Code ) and then replacing BUILD_ITEM_RULES with appropriate RULES entries by the items that use them. You could also remove LINK_SHLIBS variables that you find. After you have done this, you should hopefully reach a point where you are no longer getting any deprecation warnings.

When you think you have eliminated all deprecation warnings, you should retry your build in 1.0-compatibility mode with the --deprecation-is-error flag. In this mode, any deprecated features will be reported as errors instead of warnings. Once your build gets past this point, then you can be confident that you are no longer using any deprecated features.

If you have upgraded a tree that has externals that point into an area that has not yet been upgraded, though you won't be getting any deprecation warnings, abuild will still tell you that it sees deprecated features and that you should upgrade. This is because your root build item will still have a external-dirs key in it. Abuild is not warning you about it specifically because there's nothing you can do about it if the directory it points to is the root of a tree that hasn't been upgraded yet. The solution to this problem is to run the upgrade process from a higher level directory to upgrade the other tree. If you can't do that, you'll just have to wait until the other tree is upgraded. As soon as it is, abuild will notify you that you have an external-dirs that points to the root of an upgraded tree. Then you can run abuild --upgrade-trees again to let abuild replace the external-dirs key with tree-deps. In the mean time, you will continue to see the upgrade suggestion until all your build trees have been upgraded.

When you finally get to the point where all your build trees are upgraded, you should once again run with the --deprecation-is-error flag. This will give you one last check that you are not using any deprecated features. Once that passes, you are finally ready to try running in 1.1-compatibility mode. To do this, either run abuild with --compat-level=1.1, set the ABUILD_COMPAT_LEVEL environment variable to the value “1.1”, or just unset ABUILD_COMPAT_LEVEL and don't specify a compatibility level on the command line. If all goes well, you should see no difference. Once you have reached this point, you can be sure that your upgrade process is complete.