debian man page for dh_config_model_upgrade

DH_CONFIG_MODEL_UPGRADE(1p)				User Contributed Perl Documentation			       DH_CONFIG_MODEL_UPGRADE(1p)

NAME
       dh_config_model_upgrade - add Config::Model based configuration merge

SYNOPSIS
	dh_config_model_upgrade [ debhelper options ] [ --model_name xx ] 
	 [ --model_package xx [ --model_version yy ] ] 
	 [ --edit_option "..." ] [ -p pkg ]

DESCRIPTION
       dh_config_model_upgrade is experimental

       dh_config_model_upgrade is a debhelper that will modify the package script to perform configuration merge on package upgrade. This merge is
       based on config-edit from Config::Model.

       Model information can be specified by command options or a configuration file: "debian/foo.config-model"

       A Model must be either :

       o   Delivered in the package in "debian/config-model/models/" directory

       o   Provided by another package

REQUIREMENTS
       For this program to work, package maintainer must ensure that:

       o   ensure that *.postinst and *.config have a #DEBHELPER#  line (if these files exist)

       o   ensure that control file has a dependency on ${misc:Depends}

OPTIONS
   --model_name XX
       Specifies the model name (a la "Config::Model") that will be used to perform the upgrade. Without this information,
       "dh_config_model_upgrade" will do nothing. (shortcut "--mn")

   --model_for "xx yy"
       Specifies the package to act upon. Without this option, "dh_config_model_upgrade" will do nothing. To specify several packages, list the
       packages between quotes.  (shortcut "--mf")

   --model_package XX
       Specifies the debian package that provide the model specified bu "-model_name". (shortcut "--mp")

   --model_version YY
       Specifies the minimal version of the package that provides the model.  (shortcut "--mv")

   --edit_option "..."
       Specify a list of options or command that will be passed verbatim to config-edit during upgrade. Be sure to use quotes.

   -p
       debhelper option to specify which package(s) to act on.

Usage
       "dh_config_model_upgrade" can be used with only command line options. For instance

	dh_config_model_upgrade --model_name Sshd  -p openssh-server 
		  --model_package lib-config-model-openssh-perl --model_version 1.206

       Alternatively, you can specify relevant information in configuration files. For instance:

	$ cat debian/openssh-server.config-model
	model_name: Sshd
	model_package: lib-config-model-openssh-perl
	model_version: 1.206
	$ cat debian/openssh-client.config-model
	model_name: Ssh
	model_package: lib-config-model-openssh-perl
	model_version: 1.206

       In this case, "dh_config_model_upgrade" will be invoked this way

	dh_config_model_upgrade

       If the model are delivered within the package, you will have to specify them in xx.install file.

       Here's a example based on "approx" package where the model file and the parser/writer are delivered in approx package.

       Debian dir contains:

	 debian/config-model/Approx.pm
	 debian/config-model/models/Approx.pl

       "debian/approx.install" contains:

	 debian/config-model/Approx.pm usr/share/perl5/Config/Model
	 debian/config-model/models/Approx.pl usr/share/perl5/Config/Model/models

       dh_config_model_upgrade is invoked as :

	 dh_config_model_upgrade -model_name Approx

debian files setup
       "dh_config_model_upgrade" will work if:

       o   "control" file contains a "S{misc:Depends}" variable in "Depends" line

       o   "rules" contains a "#DEBHELPER#" line to insert generated postinst snippet

EXAMPLES
       "dh_config_model_upgrade" can be called in the rules file via the dh command (no options are possible, you will have to specify
       "debian/*.config_model" files):

	%:
	  dh --with config_model

       Or directly at the start of the build with

	build:
	  dh_config_model_upgrade -model_name FooBar

       Here's an example to avoid using Augeas when upgrading

	build:
	  dh_config_model_upgrade -model_name Sshd -edit_option "-backend custom"

CAVEATS
       Using options with a single dash (e.g. "-model_name" instead of "--model_name") will lead to ""Unknown option"" errors.

ENVIRONMENT
       This program will exit(0) if "DH_NO_ACT" is set or if "DEB_BUILD_OPTIONS" contains "noconfigmodel".

SEE ALSO
       debhelper

       This program is an addendum to debhelper (part of libconfig-model-perl).

AUTHOR
       Dominique Dumont <dod@debian.org>

perl v5.14.2							    2012-11-09					       DH_CONFIG_MODEL_UPGRADE(1p)