3.5.1. Using the Auto Upgrade Helper (AUH)

The AUH utility works in conjunction with the OpenEmbedded build system in order to automatically generate upgrades for recipes based on new versions being published upstream. Use AUH when you want to create a service that performs the upgrades automatically and optionally sends you an email with the results.

AUH allows you to update several recipes with a single use. You can also optionally perform build and integration tests using images with the results saved to your hard drive and emails of results optionally sent to recipe maintainers. Finally, AUH creates Git commits with appropriate commit messages in the layer's tree for the changes made to recipes.

Note

Conditions do exist when you should not use AUH to upgrade recipes and you should instead use either devtool upgrade or upgrade your recipes manually:
  • When AUH cannot complete the upgrade sequence. This situation usually results because custom patches carried by the recipe cannot be automatically rebased to the new version. In this case, devtool upgrade allows you to manually resolve conflicts.

  • When for any reason you want fuller control over the upgrade process. For example, when you want special arrangements for testing.

The following steps describe how to set up the AUH utility:

  1. Be Sure the Development Host is Set Up: You need to be sure that your development host is set up to use the Yocto Project. For information on how to set up your host, see the "Preparing the Build Host" section.

  2. Make Sure Git is Configured: The AUH utility requires Git to be configured because AUH uses Git to save upgrades. Thus, you must have Git user and email configured. The following command shows your configurations:

         $ git config --list
                            

    If you do not have the user and email configured, you can use the following commands to do so:

         $ git config --global user.name some_name
         $ git config --global user.email username@domain.com
                            

  3. Clone the AUH Repository: To use AUH, you must clone the repository onto your development host. The following command uses Git to create a local copy of the repository on your system:

         $ git clone git://git.yoctoproject.org/auto-upgrade-helper
         Cloning into 'auto-upgrade-helper'...
         remote: Counting objects: 768, done.
         remote: Compressing objects: 100% (300/300), done.
         remote: Total 768 (delta 499), reused 703 (delta 434)
         Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done.
         Resolving deltas: 100% (499/499), done.
         Checking connectivity... done.
                            

    AUH is not part of the OpenEmbedded-Core (OE-Core) or Poky repositories.

  4. Create a Dedicated Build Directory: Run the oe-init-build-env script to create a fresh build directory that you use exclusively for running the AUH utility:

         $ cd ~/poky
         $ source oe-init-build-env your_AUH_build_directory
                            

    Re-using an existing build directory and its configurations is not recommended as existing settings could cause AUH to fail or behave undesirably.

  5. Make Configurations in Your Local Configuration File: Several settings need to exist in the local.conf file in the build directory you just created for AUH. Make these following configurations:

    • Enable "distrodata" as follows:

           INHERIT =+ "distrodata"
                                      

    • If you want to enable Build History, which is optional, you need the following lines in the conf/local.conf file:

           INHERIT =+ "buildhistory"
           BUILDHISTORY_COMMIT = "1"
                                      

      With this configuration and a successful upgrade, a build history "diff" file appears in the upgrade-helper/work/recipe/buildhistory-diff.txt file found in your build directory.

    • If you want to enable testing through the testimage class, which is optional, you need to have the following set in your conf/local.conf file:

           INHERIT += "testimage"
                                      

      Note

      If your distro does not enable by default ptest, which Poky does, you need the following in your local.conf file:
           DISTRO_FEATURES_append = " ptest"
                                          

  6. Optionally Start a vncserver: If you are running in a server without an X11 session, you need to start a vncserver:

         $ vncserver :1
         $ export DISPLAY=:1
                            

  7. Create and Edit an AUH Configuration File: You need to have the upgrade-helper/upgrade-helper.conf configuration file in your build directory. You can find a sample configuration file in the AUH source repository.

    Read through the sample file and make configurations as needed. For example, if you enabled build history in your local.conf as described earlier, you must enable it in upgrade-helper.conf.

    Also, if you are using the default maintainers.inc file supplied with Poky and located in meta-yocto and you do not set a "maintainers_whitelist" or "global_maintainer_override" in the upgrade-helper.conf configuration, and you specify "-e all" on the AUH command-line, the utility automatically sends out emails to all the default maintainers. Please avoid this.

This next set of examples describes how to use the AUH:

Once you have run the AUH utility, you can find the results in the AUH build directory:

     ${BUILDDIR}/upgrade-helper/timestamp
                

The AUH utility also creates recipe update commits from successful upgrade attempts in the layer tree.

You can easily set up to run the AUH utility on a regular basis by using a cron job. See the weeklyjob.sh file distributed with the utility for an example.