Provided by: emdebian-grip_3.0.7_all bug

NAME

       emgrip - converts a .deb to Emdebian Grip on-the-fly

Synopsis

        DEB_BUILD_OPTIONS='usegrip' emgrip [-v|--verbose] [-q|--quiet] [-o|--outdir DIRECTORY] FILENAME

       where FILENAME is a .dsc, a .changes or a .deb

        emgrip -?|-h|--help|--version

Description

       Converts a .deb package to Emdebian Grip by unpacking, pruning particular classes of files
       (determined by DEB_BUILD_OPTIONS) and repacking with a shortened description and the em1
       version suffix.

       When creating a public Emdebian Grip repository, it is strongly recommended to specify
       .changes or .dsc files to allow the generation of Emdebian TDebs from the source package
       as well as including the source package itself in the repository.

       In .dsc mode, "emgrip" only processes the source package, as of version 3.0.0

       If a file exists with the same name in the output directory, it will be overwritten.

Copyright and Licence

        Copyright (C) 1997-2000  Roman Hodek <roman@hodek.net>
        Copyright (C) 2000-2002  Colin Watson <cjwatson@debian.org>
        Copyright (C) 2002-2004  David Schleef <ds@schleef.org>
        Copyright (C) 2004  Nikita Youshchenko <yoush@cs.msu.su>
        Copyright (C) 2004  Raphael Bossek <bossekr@debian.org>
        Copyright (C) 2007-2010  Neil Williams <codehelp@debian.org>
        Copyright (C) 2005 Joey Hess <joeyh@debian.org>

        This package is free software; you can redistribute it and/or modify
        it under the terms of the GNU General Public License as published by
        the Free Software Foundation; either version 3 of the License, or
        (at your option) any later version.

        This program 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 General Public License for more details.

        You should have received a copy of the GNU General Public License
        along with this program.  If not, see <http://www.gnu.org/licenses/>.

Emdebian Grip

       The idea here is based on dpkg-cross:

        1. receive .deb or .changes as a command-line option
        2. parse DEB_BUILD_OPTIONS
        3. unpack the .deb as dpkg-cross does
        4. remove files as per DEB_BUILD_OPTIONS
        5. repack the .deb with an Emdebian version suffix.
        6. build new .deb and revise .changes so that the
            original source can be retained.
        7. Include the gripped packages into a local mirror
            to reduce the size of Packages.gz and the size of
            the mirror itself.

       As few dependencies as possible - this script should become a new package and have a new
       set of lintian checks to allow perl etc.

        NO FUNCTIONAL CHANGES IN THE FINAL .DEB !

       Conversion of Debian TDebs to Emdebian TDebs needs to be done inside the source package so
       a .changes file is needed for this step. If the .changes file references a Debian TDeb,
       emgrip will run 'em_installtdeb --no-sign' inside the source package.

       Individual packages containing translation files will have the translation files removed
       and Debian TDebs are skipped.

       Future versions will also have to understand Dpkg Classes but until those are implemented,
       this uses brute force.

       Set the build options by placing a file in /etc/dpkg/origins/ containing the build options
       in a field called "Grip-Build-Option" and call "emgrip" with the "--vendor" option or
       "DEB_VENDOR" environment variable.

       dpkg-vendor fields used by emgrip with default values:

        Vendor: emdebian-grip
        Vendor-Name: Emdebian Grip
        Grip-Build-Option: usegrip
        Short-Desc-Suffix: gripped

       The "Short-Desc-Suffix" is wrapped in parentheses and appended to the short description
       [default is 'gripped'].

DEB_BUILD_OPTIONS

       If none of these options are set, emgrip does nothing.

        nodocs

       Remove all content in /usr/share/doc/*/ except the copyright file and compress the
       copyright file itself. Remove manpages and info pages (translated or not). Also remove
       doc-base files that describe the documentation that no longer exists.

        nohelp

       Remove even help files from all packages, including -doc packages.  Includes removing
       /usr/share/gtk-doc/html and /usr/share/gnome/help/\$package Despite removing the help
       files, dependencies on help file utilities like scrollkeeper will remain, at least for
       Lenny.

        noessential

       Remove the 'Essential: yes' tag from DEBIAN/control - this is a brute force removal, no
       additional dependencies are to be generated (no patches) so care is needed here.

        nolintian

       Remove all files from /usr/share/lintian/overrides and /usr/share/linda/overrides - saves
       up to 1Mb.

        usegrip

       Combination flag that sets all DEB_BUILD_OPTIONS for Emdebian Grip - noessential, nohelp,
       nodocs, nolintian

        nosymbols

       Currently being tested - the idea is to drop DEBIAN/symbols files but this could have
       unpredictable effects on packages built on a system lacking these symbols. The space saved
       by dropping these files might not be worth the cost, so 'usegrip' does not yet activate
       'nosymbols'. This might be suitable for Crush, maybe not Grip.

        noperl

       Remove any file that is found to be a perl script text executable by 'file' - used by
       Crush.

        usecrush

       Combination flag that adds nosymbols and noperl to usegrip.

        noscripts

       Drop all maintainer scripts from all packages irrespective of the type of script. Includes
       removing debconf templates and config scripts.  md5sums files and triggers are also
       removed. Scripts are moved to a scripts/ subdirectory of the output directory used by
       "emgrip".

        usebaked

       Combination flag that adds noscripts and nosymbols to usegrip. Add "noperl" to use Baked
       for Crush.

Field removal

       Functional control fields are retained but the question arises:

        Who defines functional?

       Well, for the current purposes of Emdebian Grip, functional includes only the following
       control fields:

        Package
        Source
        Version
        Architecture
        Maintainer
        Installed-Size
        Depends
        Pre-Depends
        Conflicts
        Replaces
        Section
        Priority
        Description
        Task
        XS-Python-Version

       Recommends is explicitly rejected, as is Suggests - the expectation is that Emdebian Grip
       will disable Install-Recommends in apt anyway, so that Gripped packages can be mixed with
       Debian or locally-built packages.

       Note also that 'Essential' is not preserved.

       Homepage, VCS* and all X- control fields are dropped.

       The net result is a (potentially) much cleaner dpkg database.

       The description is trimmed to four lines (or three if the fourth line is empty).

Automation

       Relatively simple, but a few checks are needed in case your list of possible packages
       includes packages already processed by dpkg-cross.

        #!/bin/sh
        set -e

        DIR=/tmp/myrepo/
        for deb in `ls /var/cache/apt/archives/*.deb`; do
           cross=`echo $deb | grep "\-.*-cross" || true`
           if [ ! -z "$cross" ]; then
               echo "skipping dpkg-cross package: $deb"
               continue
           fi
           DEB_BUILD_OPTIONS="nodocs nohelp usegrip" ./emgrip -o $DIR $deb
        done

       With "dpkg-vendor" support, DEB_BUILD_OPTIONS can be replaced by setting the vendor.

       A similar script should be able to cope with obtaining .changes files to retain the source
       packages.

       Despite using dcut internally, emgrip isn't set up to obtain the .changes files directly
       from http://incoming.debian.org, a wrapper script would be needed.

       An additional wrapper is likely to be needed to allow an Emdebian Grip repository to
       "catch-up" with the existing Debian mirrors, e.g. if the first upload to the Grip
       repository is a binary-only upload without a referenced .orig.tar.gz.

       emgrip does ensure that the .tar.gz is copied into the output directory and reprepro can
       locate the relevant files if the --ignore=missingfile option is passed. Sadly, this
       functionality is not preserved in the reprepro processincoming mode.

       To ease the process of gripping an existing mirror, the emdebian-grip-server package
       depends on 'reprepro' to create a filtered Debian mirror that can be kept up to date,
       generates meta-data for Emdebian Grip, builds gripped packages in an 'incoming/' directory
       and includes the packages into the final Emdebian Grip repository.

       Once a package has been "gripped", the binary packages could be removed from the filtered
       mirror - the source packages (particularly the .orig.tar.gz) are probably best retained in
       the filtered mirror.