Automatic Upgrade Helper
========================
This is a utility designed to be used in conjunction with the
OpenEmbedded build system (BitBake and OE-Core) in order to
automatically generate upgrades for recipes based on new versions being
published upstream.
Setup
-----
0. AUH needs all the dependencies listed for Yocto also requires git
configured because uses it to save upgrades, you need to have git
user and email configured, example:
$ git config --global user.name "Some Name"
$ git config --global user.email "somename@somedomain.com"
1. Run the oe-init-build-env script to create a fresh build directory, solely
for the purpose of running AUH:
$ . ./oe-init-build-env build-auh
Re-using existing build directories and configurations is not recommended
as they may contains tweaks that will break AUH or make it behave in
undesirable ways.
2. Prepare a configuration file, by default in $BUILDDIR/upgrade-helper/
upgrade-helper.conf. A sample file is provided in AUH source tree;
it can be used as-is, or tweaked further.
WARNING: if you are using the default maintainers.inc file supplied
with Poky (in meta-yocto) and you don't set a
maintainers_whitelist or (global_)maintainer_override in the
upgrade-helper configuration as above, and you specify "-e all"
on the command line, the script will automatically send out
emails to the default maintainers. Please be careful not to
do this :)
4. If you want to enable buildhistory (optional) you need to enable it in
upgrade-helper.conf, and also add the following lines to your conf/local.conf
file:
--------------- snip ---------------
INHERIT =+ "buildhistory"
BUILDHISTORY_COMMIT = "1"
--------------- snip ---------------
If upgrade is succesful buildhistory diff's are generated into
$BUILDDIR/upgrade-helper/work/recipe/buildhistory-diff.txt.
(Do not remove any other inherited class in the process).
5. If you want to enable testimage (optional) you need to enable in
upgrade-helper.conf also add the following lines to your conf/local.conf
file:
--------------- snip ---------------
INHERIT += "testimage"
# Add the following if your distro does not enable by default (poky does)
#DISTRO_FEATURES_append = " ptest"
--------------- snip ---------------
Also if you are running in a server without X11 session, you need to start
a vncserver example:
$ vncserver :1
$ export DISPLAY=:1
(Do not remove any other inherited class in the process).
Usage
-----
Some manual usage examples:
* To upgrade the xmodmap recipe to the latest available version:
$ upgrade-helper.py xmodmap
* To upgrade the xmodmap recipe to a user specified version:
$ upgrade-helper.py xmodmap -t 1.2.3
* To upgrade all recipes to latest available versions, without
sending any emails:
$ upgrade-helper.py all
* To attempt to upgrade all recipes and automatically send email
messages to maintainers for each attempted recipe as well as a
status mail at the end, use:
$ upgrade-helper.py -e all
The results of the AUH run (patches, logs and any other relevant information)
are then found in ${BUILDDIR}/upgrade-helper/<timestamp>. AUH will also
create recipe update commits from successful upgrade attempts in the layer tree.
If you wish to run the script on a regular basis, you can set up a cron
job; the "weeklyjob.sh" file distributed with this project is the basis
of a script you can call from a cron job and also provides an example
crontab line.
Maintenance
-----------
The code for this application is maintained by the Yocto Project.
The latest version of the code can always be found here:
http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/
Contributions are welcome. Please send patches / pull requests to
yocto@lists.yoctoproject.org with '[auh]' in the subject also CC the
current maintainer: Alex Kanavin <alex.kanavin@gmail.com>.
License
-------
This application is licensed under the GNU General Public License
version 2.0 or (at your option) any later version. Please see the
LICENSE file for further details.
