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.
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:
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.
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.namesome_name
$ git config --global user.emailusername
@domain
.com
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.
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.
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"
local.conf
file:
DISTRO_FEATURES_append = " ptest"
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
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:
Upgrading a Specific Recipe: To upgrade a specific recipe, use the following form:
$ upgrade-helper.py recipe_name
For example, this command upgrades the
xmodmap
recipe:
$ upgrade-helper.py xmodmap
Upgrading a Specific Recipe to a Particular Version: To upgrade a specific recipe to a particular version, use the following form:
$ upgrade-helper.pyrecipe_name
-tversion
For example, this command upgrades the
xmodmap
recipe to version
1.2.3:
$ upgrade-helper.py xmodmap -t 1.2.3
Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications: To upgrade all recipes to their most recent versions and suppress the email notifications, use the following command:
$ upgrade-helper.py all
Upgrading all Recipes to the Latest Versions and Send Email Notifications: To upgrade all recipes to their most recent versions and send email messages to maintainers for each attempted recipe as well as a status email, use the following command:
$ upgrade-helper.py -e all
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.