debian/dh/dh_config_model_upgrade

   1 #!/usr/bin/perl
   2
   3 #    Copyright (c) 2009.2012 Dominique Dumont.
   4 #
   5 #    This library is free software; you can redistribute it and/or
   6 #    modify it under the terms of the GNU Lesser Public License as
   7 #    published by the Free Software Foundation; either version 2.1 of
   8 #    the License, or (at your option) any later version.
   9 #
  10 #    Config-Model is distributed in the hope that it will be useful,
  11 #    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 #    Lesser Public License for more details.
  14 #
  15 #    You should have received a copy of the GNU Lesser Public License
  16 #    along with Config-Model; if not, write to the Free Software
  17 #    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  18 #    02110-1301 USA
  19
  20 # dh_config_model_upgrade file provided by libconfig-model-perl package
  21
  22 # See /usr/share/doc/debhelper/PROGRAMMING for debhelper details
  23
  24 use warnings;
  25 use strict;
  26 use File::Find ;
  27
  28 use Debian::Debhelper::Dh_Lib ;
  29
  30 $dh{model_name} = ''; # avoids undef warnings
  31 $dh{edit_option} = '';
  32
  33 init(options => { "model_name|mn=s"    => \$dh{model_name},
  34                   "model_package|mp=s" => \$dh{model_package},
  35                   "model_version|mv=s" => \$dh{model_version},
  36                   "edit_option=s"      => \$dh{edit_option},
  37                 }
  38     );
  39
  40
  41 # See debhelper(7)
  42 if ($dh{NO_ACT}) {
  43   exit;
  44 }
  45
  46 if ($ENV{DEB_BUILD_OPTIONS} =~ /noconfigmodel/) {
  47   warn "dh_config_model_upgrade: DEB_BUILD_OPTIONS specifies 'noconfigmodel',  exiting ...\n";
  48   exit;
  49 }
  50
  51 my @do_packages = @{$dh{DOPACKAGES}} ;
  52
  53 unless (@do_packages) {
  54     @do_packages = map { m!debian/(.*)\.config-model!; $1; }
  55       glob("debian/*.config-model") ;
  56 }
  57
  58 # debian/config file: foo.config-model
  59 foreach my $package (@do_packages) {
  60
  61     verbose_print("dh_config_model_upgrade: package $package") ;
  62
  63     my $metaconf = "debian/$package.config-model" ;
  64
  65     my %cm_config = map {  $_ => $dh{$_} ; }
  66                         qw/model_name model_version model_package/;
  67
  68     # declare model name to load ($model below)
  69     # declare which package provides the model (optional)
  70     if (-e $metaconf) {
  71         open my $meta,$metaconf || die "Can't open $metaconf:$!";
  72         foreach (<$meta>) {
  73             chomp;
  74             my ($k,$v) = split /\s*?[:= ]\s*/ ;
  75             foreach my $cmhk (keys %cm_config) {
  76                 $cm_config{$cmhk} ||= $v if $k eq $cmhk ;
  77             }
  78         }
  79         close $meta ;
  80     }
  81
  82     next unless defined $dh{model_name} ;
  83
  84     # add dependency
  85     addsubstvar($package,'misc:Depends', 'libconfig-model-perl', '>= 0.637') ;
  86
  87     if (defined $cm_config{model_package}) {
  88         # add dependency in misc:Depends control file
  89         addsubstvar($package,'misc:Depends',
  90                     $cm_config{model_package},
  91                     '>= '.$cm_config{model_version}) ;
  92     }
  93     else {
  94         # should we check that model file is declared in *.install ?
  95     }
  96
  97     my $model_sed = 's/%MODEL%/'.$dh{model_name}.'/ ; ' ;
  98     my $pack_sed  = 's/%PACKAGE%/'.$package.'/ ; ' ;
  99     my $opt_sed   = 's/%OPTION%/'.$dh{edit_option}.'/ ; ' ;
 100
 101     # calls autoscript to update pkg.postinst with config-edit command
 102     autoscript($package,postinst => 'postinst-config-model',
 103                $model_sed.$pack_sed.$opt_sed ) ;
 104
 105 }
 106
 107 __END__
 108
 109 =head1 NAME
 110
 111 dh_config_model_upgrade - add Config::Model based configuration merge
 112
 113 =head1 SYNOPSIS
 114
 115  dh_config_model_upgrade [ debhelper options ] [ --model_name xx ] \
 116   [ --model_package xx [ --model_version yy ] ] \
 117   [ --edit_option "..." ] [ -p pkg ]
 118
 119 =head1 DESCRIPTION
 120
 121 B<dh_config_model_upgrade is experimental>
 122
 123 dh_config_model_upgrade is a debhelper that will modify the package
 124 script to perform configuration merge on package upgrade. This merge
 125 is based on L<config-edit> from L<Config::Model>.
 126
 127 Model information can be specified by command options or a
 128 configuration file: C<debian/foo.config-model>
 129
 130 A Model must be either :
 131
 132 =over
 133
 134 =item *
 135
 136 Delivered in the package in C<debian/config-model/models/> directory
 137
 138 =item *
 139
 140 Provided by another package
 141
 142 =back
 143
 144 =head1 REQUIREMENTS
 145
 146 For this program to work, package maintainer must ensure that:
 147
 148 =over
 149
 150 =item *
 151
 152 ensure that *.postinst and *.config have a #DEBHELPER#  line (if these files exist)
 153
 154 =item *
 155
 156 ensure that control file has a dependency on ${misc:Depends}
 157
 158 =back
 159
 160 =head1 OPTIONS
 161
 162 =head2 --model_name XX
 163
 164 Specifies the model name (à la C<Config::Model>) that will be used to
 165 perform the upgrade. Without this information,
 166 C<dh_config_model_upgrade> will do nothing. (shortcut C<--mn>)
 167
 168 =head2 --model_for "xx yy"
 169
 170 Specifies the package to act upon. Without this option,
 171 C<dh_config_model_upgrade> will do nothing. To specify several
 172 packages, list the packages between quotes.  (shortcut C<--mf>)
 173
 174 =head2 --model_package XX
 175
 176 Specifies the debian package that provide the model specified bu
 177 C<-model_name>. (shortcut C<--mp>)
 178
 179 =head2 --model_version YY
 180
 181 Specifies the minimal version of the package that provides the model.
 182 (shortcut C<--mv>)
 183
 184 =head2 --edit_option "..."
 185
 186 Specify a list of options or command that will be passed verbatim to
 187 L<config-edit> during upgrade. Be sure to use quotes.
 188
 189 =head2 -p
 190
 191 debhelper option to specify which package(s) to act on.
 192
 193 =head1 Usage
 194
 195 C<dh_config_model_upgrade> can be used with only command line
 196 options. For instance
 197
 198  dh_config_model_upgrade --model_name Sshd  -p openssh-server \
 199            --model_package lib-config-model-openssh-perl --model_version 1.206
 200
 201 Alternatively, you can specify relevant information in
 202 configuration files. For instance:
 203
 204  $ cat debian/openssh-server.config-model
 205  model_name: Sshd
 206  model_package: lib-config-model-openssh-perl
 207  model_version: 1.206
 208  $ cat debian/openssh-client.config-model
 209  model_name: Ssh
 210  model_package: lib-config-model-openssh-perl
 211  model_version: 1.206
 212
 213 In this case, C<dh_config_model_upgrade> will be invoked this way
 214
 215  dh_config_model_upgrade
 216
 217 If the model are delivered within the package, you will have to
 218 specify them in xx.install file.
 219
 220 Here's a example based on C<approx> package where the model file and
 221 the parser/writer are delivered in approx package.
 222
 223 Debian dir contains:
 224
 225   debian/config-model/Approx.pm
 226   debian/config-model/models/Approx.pl
 227
 228 C<debian/approx.install> contains:
 229
 230   debian/config-model/Approx.pm usr/share/perl5/Config/Model
 231   debian/config-model/models/Approx.pl usr/share/perl5/Config/Model/models
 232
 233 dh_config_model_upgrade is invoked as :
 234
 235   dh_config_model_upgrade -model_name Approx
 236
 237 =head1 debian files setup
 238
 239 C<dh_config_model_upgrade> will work if:
 240
 241 =over 4
 242
 243 =item *
 244
 245 C<control> file contains a C<S{misc:Depends}> variable in C<Depends> line
 246
 247 =item *
 248
 249 C<rules> contains a C<#DEBHELPER#> line to insert generated postinst snippet
 250
 251 =back
 252
 253
 254 =head1 EXAMPLES
 255
 256 C<dh_config_model_upgrade> can be called in the rules file via the dh
 257 command (no options are possible, you will have to specify
 258 C<debian/*.config_model> files):
 259
 260  %:
 261    dh --with config_model
 262
 263 Or directly at the start of the build with
 264
 265  build:
 266    dh_config_model_upgrade -model_name FooBar
 267
 268 Here's an example to avoid using Augeas when upgrading
 269
 270  build:
 271    dh_config_model_upgrade -model_name Sshd -edit_option "-backend custom"
 272
 273 =head1 CAVEATS
 274
 275 Using options with a single dash (e.g. C<-model_name> instead of
 276 C<--model_name>) will lead to "C<Unknown option>" errors.
 277
 278 =head1 ENVIRONMENT
 279
 280 This program will exit(0) if C<DH_NO_ACT> is set or if C<DEB_BUILD_OPTIONS>
 281 contains C<noconfigmodel>.
 282
 283 =head1 SEE ALSO
 284
 285 L<debhelper>
 286
 287 This program is an addendum to debhelper (part of libconfig-model-perl).
 288
 289 =head1 AUTHOR
 290
 291 Dominique Dumont <dod@debian.org>
 292
 293 =cut