[cme] 01/03: added dh_cme_upgrade (moved from libconfig-model-perl)
dod at debian.org
dod at debian.org
Fri May 29 17:40:52 UTC 2015
This is an automated email from the git hooks/post-receive script.
dod pushed a commit to branch master
in repository cme.
commit a76d77e3e9379306b7d63b686ae9794357391de6
Author: Dominique Dumont <dod at debian.org>
Date: Thu May 28 19:03:13 2015 +0200
added dh_cme_upgrade (moved from libconfig-model-perl)
---
debian/README.Debian | 68 +++++++++
debian/cme.install | 5 +
debian/dh/cme_upgrade.pm | 17 +++
debian/dh/config-script-cme | 15 ++
debian/dh/dh_cme_upgrade | 329 +++++++++++++++++++++++++++++++++++++++++++
debian/dh/postinst-cme | 13 ++
debian/dh/postrm-cme | 7 +
debian/dh/template-cme | 15 ++
debian/patches/add_dh_config | 26 ++++
debian/patches/series | 1 +
10 files changed, 496 insertions(+)
diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644
index 0000000..8e5825c
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,68 @@
+The aim of dh_cme_upgrade is to provide an easy way for a
+Debian developer to add better configuration upgrade to the packages
+they maintain.
+
+Let's assume that Joe, Debian developer, had seen too many questions
+from users regarding configuration upgrades during package
+upgrades. Users complains that their settings are lost or that ucf's
+questions are too cryptic. So Joe has had enough and wants to add
+smooth upgrade capability to his foobar package.
+
+What will the end user see?
+----------------------------
+
+Hopefully, just a message during upgrade indicating that Config::Model
+is taking care of the upgrade.
+
+What does Joe, Debian developer, have to do?
+--------------------------------------------
+
+- ensure that a proper configuration model for the application
+ contained in foobar exists. Either:
+ - find the package containing the relevant model in Debian
+ (something like libconfig-model-foobar-perl)
+ - find the package in CPAN and ask debian-perl team to package it
+ - write the model. In this case, you may want to subscribe to
+ config-model users list (see below)
+- ensure that foobar.postinst has a #DEBHELPER# line (if this file
+ exists)
+- ensure that foobar.control has a dependency on ${misc:Depends}
+- ensure that call dh_cme_upgrade during package build.
+ Either:
+ - run "dh --with cme_upgrade"
+ - directly call dh_cme_upgrade. (*)
+
+Note to developer for embedded system: dh_cme_upgrade will do
+nothing is DH_NO_ACT is set or if DEB_BUILD_OPTIONS contains
+'noconfigmodel'
+
+CDBS users should add a line like this in rules (*):
+
+build/foo::
+ dh_cme_upgrade --model Foo
+
+(*) See dh_cme_upgrade man page for more details on usage and
+options
+
+
+How does this work?
+--------------------
+
+When called, dh_cme_upgrade will setup foobar package to
+upgrade the configuration with Config::Model.
+
+In more details, dh_cme_upgrade will:
+- add a dependency on libconfig-model-perl in foobar control file
+- add or update foobar.postinst file so that the configuration is
+ upgraded. In case of upgrade issue, a message is displayed inviting the
+ user to re-run the upgrade command in force and interactive mode.
+
+All these operations are handled by dh_cme_upgrade.
+
+For more information, see http://wiki.debian.org/PackageConfigUpgrade
+
+Config::Model home page is http://config-model.wiki.sourceforge.net/
+User mailing list: http://sourceforge.net/mail/?group_id=155650
+
+Feel free to contact the package maintainer (domi dot dumont at free dot fr)
+if more explanations are needed.
diff --git a/debian/cme.install b/debian/cme.install
new file mode 100644
index 0000000..a64a6a2
--- /dev/null
+++ b/debian/cme.install
@@ -0,0 +1,5 @@
+debian/dh/cme_upgrade.pm usr/share/perl5/Debian/Debhelper/Sequence/
+debian/dh/template-cme usr/share/debhelper/autoscripts/
+debian/dh/postinst-cme usr/share/debhelper/autoscripts/
+debian/dh/postrm-cme usr/share/debhelper/autoscripts/
+debian/dh/config-script-cme usr/share/debhelper/autoscripts/
diff --git a/debian/dh/cme_upgrade.pm b/debian/dh/cme_upgrade.pm
new file mode 100644
index 0000000..fab551b
--- /dev/null
+++ b/debian/dh/cme_upgrade.pm
@@ -0,0 +1,17 @@
+#!/usr/bin/perl
+
+# (c) Dominique Dumont <dod at debian.org>
+
+# This Debhelper addon will insert configuration upgrade instructions
+# in Debian package. This upgrade will be performed by Config::Model
+
+use warnings;
+use strict;
+use Debian::Debhelper::Dh_Lib;
+
+# see /usr/share/doc/debhelper/PROGRAMMING.gz
+insert_before("dh_install","dh_install_debconf") ;
+insert_after("dh_install_debconf", "dh_cme_upgrade");
+
+
+1;
diff --git a/debian/dh/config-script-cme b/debian/dh/config-script-cme
new file mode 100755
index 0000000..6cb21aa
--- /dev/null
+++ b/debian/dh/config-script-cme
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+set -e
+
+. /usr/share/debconf/confmodule
+
+if db_get %PACKAGE%/auto-upgrade-config; then
+ CURRENT=$RET
+fi
+
+db_title %PACKAGE% configuration
+
+db_set %PACKAGE%/auto-upgrade-config ${CURRENT:-true}
+db_input high %PACKAGE%/auto-upgrade-config || true
+db_go || true
diff --git a/debian/dh/dh_cme_upgrade b/debian/dh/dh_cme_upgrade
new file mode 100644
index 0000000..7d89d06
--- /dev/null
+++ b/debian/dh/dh_cme_upgrade
@@ -0,0 +1,329 @@
+#!/usr/bin/perl
+
+# Copyright (c) 2009.2012-2013 Dominique Dumont.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser Public License as
+# published by the Free Software Foundation; either version 2.1 of
+# the License, or (at your option) any later version.
+#
+# Config-Model is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with Config-Model; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+# 02110-1301 USA
+
+# dh_cme_upgrade file provided by cme package
+
+# See /usr/share/doc/debhelper/PROGRAMMING for debhelper details
+
+use warnings;
+use strict;
+use File::Find;
+
+use Debian::Debhelper::Dh_Lib;
+
+my $prefix = '/usr';
+
+init();
+
+# See debhelper(7)
+if ( $dh{NO_ACT} ) {
+ exit;
+}
+
+if ( defined $ENV{DEB_BUILD_OPTIONS} and $ENV{DEB_BUILD_OPTIONS} =~ /noconfigmodel/ ) {
+ warn "dh_cme_upgrade: DEB_BUILD_OPTIONS specifies 'noconfigmodel', exiting ...\n";
+ exit;
+}
+
+my @do_packages = @{ $dh{DOPACKAGES} };
+
+unless (@do_packages) {
+ @do_packages = map { m!debian/(.*)\.config-model!; $1; } glob("debian/*.config-model");
+}
+
+my @mandatory = qw/cme-app-name cme-model-package/;
+my @legal_list = ( @mandatory, qw/cme-model-version cme-options cme-purge cme-command/ );
+my %legal = map { ( $_ => 1 ) } @legal_list;
+
+# debian/config file: foo.config-model
+foreach my $package (@do_packages) {
+
+ verbose_print("dh_cme_upgrade: package $package");
+
+ my $metaconf = "debian/$package.config-model";
+
+ next unless -e $metaconf;
+
+ my %cm_config;
+
+ # declare model name to load ($model below)
+ # declare which package provides the model (optional)
+ open my $meta_fh, $metaconf || die "Can't open $metaconf:$!";
+ my @meta = <$meta_fh> ;
+ close $meta_fh;
+ while ($_ = shift @meta) {
+ chomp;
+ s/#.*//;
+ next unless /\w/;
+ my ( $k, $v ) = split /\s*?[:= ]\s*/,$_,2;
+ if ( not $legal{$k} ) {
+ die "Error: Unexpected option $k in $metaconf, expected @legal_list\n";
+ }
+ $cm_config{$k} = $v;
+ }
+
+ foreach my $k (@mandatory) {
+ die "Error: Missing $k parameter in $metaconf\n" unless $cm_config{$k };
+ }
+
+ # add dependency
+ addsubstvar( $package, 'misc:Depends', 'cme' );
+
+ # add dependency in misc:Depends control file
+ my $dep = $cm_config{'cme-model-package'};
+ $dep .= '(>= ' . $cm_config{'cme-model-version'}.')' if $cm_config{'cme-model-version'};
+
+ addsubstvar( $package, 'misc:Depends', $dep );
+
+ my $purge = $cm_config{'cme-purge'};
+ my $command = $cm_config{'cme-command'} || 'migrate' ;
+ my $conf_target = $cm_config{'cme-conf-target'} || '/etc' ;
+ my $munge_sub = sub {
+ s/%APPNAME%/$cm_config{'cme-app-name'}/g;
+ s/%PACKAGE%/$package/g;
+ s/%COMMAND%/$command/g;
+ s/%CONF_TARGET%/$conf_target/g;
+ no warnings 'uninitialized';
+ s/%OPTION%/$cm_config{'cme-options'}/g;
+ s/%PURGE%/$purge/g;
+ };
+
+ # calls autoscript to update pkg.postinst with cme command
+ # see /usr/share/doc/debhelper/PROGRAMMING.gz
+ autoscript( $package, postinst => 'postinst-cme', $munge_sub );
+ autoscript( $package, config => 'config-script-cme', $munge_sub );
+
+ if ($purge) {
+ my @purge_paths = split /\s+/, $purge ;
+ my @ok = grep { m!^/etc/\w+! } @purge_paths ;
+ die "Error: cme-purge is not safe ('$purge'). Expected all paths to be something like /etc/foo"
+ if @ok < @purge_paths ;
+ autoscript( $package, postrm => 'postrm-cme', $munge_sub );
+
+ }
+
+ autotemplate( $package, 'template-cme', $munge_sub );
+
+}
+
+# modified from autoscript
+sub autotemplate {
+ my $package = shift;
+ my $filename = shift;
+ my $sub = shift || "";
+
+ # This is the file we will modify.
+ my $outfile = "debian/" . pkgext($package) . 'templates';
+
+ # Figure out what shell script snippet to use.
+ my $infile;
+ if ( defined( $ENV{DH_AUTOSCRIPTDIR} )
+ && -e "$ENV{DH_AUTOSCRIPTDIR}/$filename" )
+ {
+ $infile = "$ENV{DH_AUTOSCRIPTDIR}/$filename";
+ }
+ else {
+ if ( -e "$prefix/share/debhelper/autoscripts/$filename" ) {
+ $infile = "$prefix/share/debhelper/autoscripts/$filename";
+ }
+ else {
+ error("$prefix/share/debhelper/autoscripts/$filename does not exist");
+ }
+ }
+
+ open(IN, $infile) or die "$infile: $!";
+ open(OUT, ">$outfile") or die "$outfile: $!";
+ while (<IN>) { $sub->(); print OUT }
+ close(OUT) or die "$outfile: $!";
+ close(IN) or die "$infile: $!";
+}
+
+
+__END__
+
+=encoding UTF-8
+
+=head1 NAME
+
+dh_cme_upgrade - add cme based configuration merge
+
+=head1 SYNOPSIS
+
+ dh_cme_upgrade [ debhelper options ] [ -p pkg ]
+
+=head1 DESCRIPTION
+
+B<dh_cme_upgrade is experimental>
+
+dh_cme_upgrade is a debhelper that will modify the package script to
+merge configuration on package upgrade. This merge is based on L<cme>
+from L<Config::Model> and will merge user's customisations with
+maintainer's configuration updates. This provides another way to
+preserve users modifications during upgrades.
+
+Configuration information used by L<cme> for upgrade are specified in
+a configuration file (see below)
+
+Configuration information is specified in a configuration model. It
+must be provided by another package like
+C<libconfig-model-lcdproc-perl>
+
+=head1 REQUIREMENTS
+
+For this program to work, package maintainer must make sure that:
+
+=over
+
+=item *
+
+C<*.postinst>, C<*.postrm> and C<*.config> have a C<#DEBHELPER#> line (if these files exist)
+
+=item *
+
+C<control> file has a dependency on C<${misc:Depends}>
+
+=item *
+
+Configuration files upgraded by C<cme> must not be conffiles. Any
+default configuration file provided by upstream must not be installed
+directly in C</etc>. They should be installed in C</usr/share/doc/> for
+reference. C<cme> will create a default configuration file during package
+installation.
+
+=back
+
+=head1 OPTIONS
+
+This program accepts all debhelper options, including the C<-p>
+option to specify which package(s) to act on.
+
+=head1 Usage
+
+C<dh_cme_upgrade> is designed be called in the rules file via
+the dh command:
+
+ %:
+ dh --with cme_upgrade
+
+No options can be passed to C<dh_cme_upgrade>. Its
+configuration must be specified in C<debian/*.config_model> file. This
+file contains several lines, each in the form of "key: value".
+
+Here are the possible keys:
+
+=over
+
+=item cme-app-name
+
+Specifies the application or model name (� la C<Config::Model>) that will be used to
+perform the upgrade. (mandatory)
+
+=item cme-model-package
+
+Specifies the debian package that provide the model specified by
+C<cme-app-name>. (mandatory)
+
+=item cme-model-version
+
+Specifies the minimal version of the package that provides the model.
+(optional)
+
+=item cme-command
+
+Specify the command passed to L<cme>. Defaults to C<migrate>. Another useful value is C<fix> which
+will migrate and fix the configuration file.
+
+=item cme-options
+
+Specify a list of options or command that will be passed verbatim to
+L<cme> during upgrade. (optional)
+
+=item cme-purge
+
+Specify the configuration files or directory to be removed when purging the package. E.g
+C</etc/LCDd.conf*> or C</etc/java/>. Several files or directory can be purged by using a shell glob.
+If this option is empty, configuration files handled by cme will be left as-is after a purge.
+
+=item cme-conf-target
+
+Specifies where the target configuration files is expected. Defaults to
+C</etc>. This parameter is used to create a message to inform user who
+don't want automatic upgrade where to find the original configuration
+file (in C</usr/share/doc/package_name>) and where to copy it (in
+C</cme-conf-target>).
+
+=back
+
+=head1 Examples
+
+Here's a possible configuration for openssh server:
+
+ $ cat debian/openssh-server.config-model
+ cme-app-name: sshd
+ cme-model-package: lib-config-model-openssh-perl
+ cme-model-version: 1.206
+
+For lcdproc:
+
+ $ cat debian/lcdproc.config-model
+ cme-app-name: lcdproc
+ cme-package: libconfig-model-lcdproc-perl
+ cme-model-version: 2.040
+ # required to upgrade LCDd.conf from upstream configuration
+ cme-options: -force
+ cme-purge: /etc/LCDd.conf*
+
+For Popcon:
+
+ $ cat debian/popcon.config-model
+ cme-app-name: popcon
+ cme-model-package: libconfig-model-perl
+
+=head1 debian files setup
+
+C<dh_cme_upgrade> will work only if:
+
+=over 4
+
+=item *
+
+C<control> file contains a C<${misc:Depends}> variable in C<Depends> line
+
+=item *
+
+If present, C<postinst> script contains a C<#DEBHELPER#> line to insert generated postinst snippet
+
+=back
+
+=head1 ENVIRONMENT
+
+This program will exit(0) if C<DH_NO_ACT> is set or if C<DEB_BUILD_OPTIONS>
+contains C<noconfigmodel>.
+
+=head1 SEE ALSO
+
+L<debhelper>
+
+This program is an addendum to debhelper (part of libconfig-model-perl).
+
+=head1 AUTHOR
+
+Dominique Dumont <dod at debian.org>
+
+=cut
diff --git a/debian/dh/postinst-cme b/debian/dh/postinst-cme
new file mode 100644
index 0000000..233477a
--- /dev/null
+++ b/debian/dh/postinst-cme
@@ -0,0 +1,13 @@
+# In case of error (error in configuration file or model bug), the
+# configuration file is left as is.
+
+. /usr/share/debconf/confmodule
+
+db_get %PACKAGE%/auto-upgrade-config
+
+# testing perl is required to avoid problem in embedded environments
+if [ "$RET" = true ] && [ -x "/usr/bin/perl" ] && [ -x "/usr/bin/cme" ]
+then
+ cme %COMMAND% %APPNAME% -create -backup dpkg-old -try-app-as-model %OPTION% || \
+ echo "WARNING: upgrade with cme failed: Run 'sudo cme migrate %APPNAME% %OPTION%'."
+fi
diff --git a/debian/dh/postrm-cme b/debian/dh/postrm-cme
new file mode 100644
index 0000000..6d63148
--- /dev/null
+++ b/debian/dh/postrm-cme
@@ -0,0 +1,7 @@
+# Purge configuration files handled by cme
+
+if [ "$1" = purge ]
+then
+ echo "Purging cme files: '%PURGE%'"
+ rm -rf %PURGE%
+fi
diff --git a/debian/dh/template-cme b/debian/dh/template-cme
new file mode 100644
index 0000000..d78b644
--- /dev/null
+++ b/debian/dh/template-cme
@@ -0,0 +1,15 @@
+Template: %PACKAGE%/auto-upgrade-config
+Type: boolean
+Default: true
+Description: Perform automatic configuration upgrade ?
+ %PACKAGE% configuration can be merged automatically by cme
+ during package upgrade. This process will keep your
+ configuration customization, apply maintainer's changes and write back
+ the configuration files.
+ .
+ You can later edit %PACKAGE% configuration with the command
+ 'sudo cme edit %APPNAME%'.
+ .
+ If you decline this option, you must then copy the original configuration
+ file(s) from /usr/share/doc/%PACKAGE% to %CONF_TARGET%. This file will
+ not be managed by Debian package manager.
diff --git a/debian/patches/add_dh_config b/debian/patches/add_dh_config
new file mode 100644
index 0000000..8da9193
--- /dev/null
+++ b/debian/patches/add_dh_config
@@ -0,0 +1,26 @@
+Description: Arrange for dh_config to be handled by Module::Build
+ (mostly to generate proper man page from pod doc)
+Author: Dominique Dumont <domi.dumont at free.fr>
+Reviewed-by: Salvatore Bonaccorso <carnil at debian.org>
+Last-Update: 2010-11-12
+--- a/Build.PL
++++ b/Build.PL
+@@ -41,7 +41,7 @@
+ "perl" => "5.010"
+ },
+ "script_files" => [
+- "bin/cme"
++ "bin/cme", 'debian/dh/dh_cme_upgrade'
+ ],
+ "test_requires" => {
+ "File::Path" => 0,
+--- a/MANIFEST
++++ b/MANIFEST
+@@ -10,6 +10,7 @@
+ README.pod
+ bin/cme
+ contrib/bash_completion.cme
++debian/dh/dh_cme_upgrade
+ lib/App/Cme.pm
+ lib/App/Cme/Command/check.pm
+ lib/App/Cme/Command/dump.pm
diff --git a/debian/patches/series b/debian/patches/series
new file mode 100644
index 0000000..cdc0a2e
--- /dev/null
+++ b/debian/patches/series
@@ -0,0 +1 @@
+add_dh_config
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/cme.git
More information about the Pkg-perl-cvs-commits
mailing list