NAME

       dh_cme_upgrade - add cme based configuration merge

VERSION

       version 1.041

SYNOPSIS

        dh_cme_upgrade [ debhelper options ] [ -p pkg ]

DESCRIPTION

       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 cme from 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 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 "libconfig-model-lcdproc-perl"

REQUIREMENTS

       For this program to work, package maintainer must make sure that:

       •   "*.postinst", "*.postrm" and "*.config" have a "#DEBHELPER#"  line (if these files exist)

       •   "control" file has a dependency on "${misc:Depends}"

       •   Configuration  files upgraded by "cme" must not be conffiles. Any default configuration file provided
           by upstream must not be installed directly in "/etc". They should be installed  in  "/usr/share/doc/"
           for reference. "cme" will create a default configuration file during package installation.

OPTIONS

       This  program accepts all debhelper options, including the "-p" option to specify which package(s) to act
       on.

Usage

       "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   "dh_cme_upgrade".   Its   configuration   must   be   specified   in
       "debian/*.config_model" file. This file contains several lines, each in the form of "key: value".

       Here are the possible keys:

       cme-app-name
           Specifies  the  application  or  model  name  (à la "Config::Model") that will be used to perform the
           upgrade. (mandatory)

       cme-model-package
           Specifies the debian package that provide the model specified by "cme-app-name". (mandatory)

       cme-model-version
           Specifies the minimal version of the package that provides the model.  (optional)

       cme-command
           Specify the command passed to cme. Defaults to "migrate". Another useful value is  "fix"  which  will
           migrate and fix the configuration file.

       cme-options
           Specify a list of options or command that will be passed verbatim to cme during upgrade. (optional)

       cme-purge
           Specify  the  configuration  files  or  directory  to  be  removed  when  purging  the  package.  E.g
           "/etc/LCDd.conf*" or "/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.

       cme-conf-target
           Specifies  where  the  target  configuration files is expected. Defaults to "/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 "/usr/share/doc/package_name") and where to copy it (in "/cme-conf-target").

       Alternatively,  since  cme/1.030-1  you  can  just  build  depend on dh-sequence-cme-upgrade and omit the
       "--with cme_upgrade" part.

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

debian files setup

       "dh_cme_upgrade" will work only if:

       •   "control" file contains a "${misc:Depends}" variable in "Depends" line

       •   If present, "postinst" script contains a "#DEBHELPER#" line to insert generated postinst snippet

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>

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2014-2022 by Dominique Dumont <ddumont@cpan.org>.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999

perl v5.40.0                                       2024-12-01                                 DH_CME_UPGRADE(1p)