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. Ensure you have a working copy of the build system that is configured
and ready to run, i.e. you've run the oe-init-build-env script to
create a build directory and edited local.conf / bblayers.conf as
desired.
2. Prepare a configuration file, by default in $BUILDDIR/upgrade-helper/
upgrade-helper.conf, as below:
--------------- snip ---------------
[maintainer_override]
# mails for recipe upgrades will go to john.doe instead of jane.doe, etc
jane.doe@doe.com=john.doe@doe.com
johhny.bravo@bravo.com=john.doe@doe.com
[settings]
# recipes in blacklist will be skipped
blacklist=python glibc gcc
# only recipes belonging to maintainers in whitelist will be attempted
maintainers_whitelist=jane.doe@doe.com john.doe@doe.com johhny.bravo@bravo.com
# SMTP server
smtp=smtp.my-server.com:25
# from whom should the mails arrive
from=upgrade.helper@my-server.com
# who should get the status mail with statistics, at the end
status_recipients=john.doe@doe.com
# specify the directory where work (patches) will be saved (optional)
#workdir=
# publish url to use in statistics summary (optional)
#publish_work_url=http://auh.somehost.com/work
# clean sstate directory before upgrading
clean_sstate=yes
# clean tmp directory before upgrading
clean_tmp=yes
# machines to test build with
machines=qemux86 qemux86-64 qemuarm qemumips qemuppc
# optional features
buildhistory=no
testimage=no
testimage_name=image-custom # defaults to core-image-sato
# to enable upgrade recipes in a layer example for meta-intel
layer_mode=False
layer_name=meta-intel
layer_dir=DIR/meta-intel
layer_machines=intel-core2-32 intel-corei7-64 intel-quark
--------------- snip ---------------
3. Enable distrodata and supply appropriate additional metadata. For
example, you could add the following to your conf/local.conf:
--------------- snip ---------------
INHERIT =+ "distrodata"
--------------- snip ---------------
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 maintainer_override in the
upgrade-helper configuration as above, and you specify "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 in
upgrade-helper.conf 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, e.g. distrodata).
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"
DISTRO_FEATURES_append = " ptest"
EXTRA_IMAGE_FEATURES = "debug-tweaks package-management ptest-pkgs"
# testimage/ptest only work with rpm
PACKAGE_CLASSES = "package_rpm"
--------------- snip ---------------
Also if you are running in a server without X11 session, you need to start
a vncserver example:
$ vncserver :1
$ export DISPLAY=:1
If upgrade is succesful testimage/ptest results are generated into
$BUILDDIR/upgrade-helper/work/recipe/ptest_recipe.log if recipe support
ptest.
(Do not remove any other inherited class in the process, e.g. distrodata).
Usage
-----
Some manual usage examples:
* To upgrade the xmodmap recipe to the latest available version,
interactively:
$ upgrade-helper.py xmodmap
* To upgrade the xmodmap recipe to a user specified version,
interactively:
$ upgrade-helper.py xmodmap -t 1.2.3
* 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 all
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@yoctoproject.org with '[auh]' in the subject also CC the
current maintainer: Aníbal Limón <anibal.limon@linux.intel.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.
