Provided by: dpkg-cross_2.6.20_all bug

Name

       dpkg-cross - manage libraries for cross compiling

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-2011  Neil Williams <codehelp@debian.org>
        Copyright (c) 2011  Wookey <wookey@debian.org>

        This program 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 2 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, write to the Free Software
        Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

SYNOPSIS

        dpkg-cross [OPTIONS] [--install|-i] <files...>
        dpkg-cross [OPTIONS] [--build|-b] <files...>
        dpkg-cross [OPTIONS] [--remove|--purge|-r] <packages...>
        dpkg-cross [OPTIONS] [--status|-s] <packages...>
        dpkg-cross [OPTIONS] [--list|-l] <packages...>
        dpkg-cross [OPTIONS] [--list-files|-L] <packages...>
        dpkg-cross [OPTIONS] [--query|-Q] <pkgpath>
        dpkg-cross [OPTIONS] [--update|-u] <pkgpath>

        OPTIONS: [ -v | --verbose ] [ -q | --quiet ]
        { [ -a | --arch ] architecture } { [ -X | --exclude ] PACKAGE }
        [ -A | --convert-anyway ] [ -M | --convert-multiarch ]  [ -k | --keep-temp ]

DESCRIPTION

       dpkg-cross is a tool to install and manage libraries and header files for cross compiling.
       dpkg-cross converts native Debian packages for the target architecture to cross compiling
       support packages that can be installed on any architecture, but in different paths to
       avoid conflicts. It then calls dpkg to install the converted package. The conversion step
       alone can be done with the --build option. Other options are wrappers around corresponding
       dpkg functionality.

       dpkg-cross is intended to make it easier for you to keep your cross compiling libraries
       up-to-date, as it works directly on Debian packages. It saves you copying the libs and
       headers from a machine with your target  architecture, or extracting them via dpkg-deb
       --fsys-tarfile.

       dpkg-cross also collects and install the .shlibs files in -dev packages, which are needed
       by dpkg-shlibdeps.

CMAKE

       CMake cross-building support is experimental!

       CMake requires a little support from dpkg-cross to cross-build. The included cmake support
       file is an example for Linux kernels.  Use:

        rm CMakeCache.txt
        cmake -DCMAKE_TOOLCHAIN_FILE=/etc/dpkg-cross/cmake/CMakeCross.txt

       The  main changes involve setting PKG_CONFIG_LIBDIR within CMake an setting the include
       directories to locate the cross libraries installed by dpkg-cross e.g.

        #Make pkg-config look in the right place
        SET(ENV{PKG_CONFIG_LIBDIR} ${CMAKE_FIND_ROOT_PATH}/lib/pkgconfig/)
        ELSE (CMAKE_CROSSCOMPILING)

       Packages using cmake may need some tweaks to debian/rules, e.g.

        ifneq ($(DEB_HOST_GNU_TYPE),$(DEB_BUILD_GNU_TYPE))
        export CC=$(DEB_HOST_GNU_TYPE)-gcc
        export CXX=$(DEB_HOST_GNU_TYPE)-g++
        export CMAKE_TOOLCHAIN_FILE=/etc/dpkg-cross/cmake/CMakeCross.txt
        else
        export CC=gcc
        export CXX=g++
        endif

OPTIONS

       dpkg-cross follows the usual GNU command line syntax, with long options starting with two
       dashes ('-').

        -h|--help

       Show summary of options.

        -v|--verbose

       Be more verbose.

        -q|--quiet

       Be more quiet.

        -a|--arch architecture

       Install for architecture architecture.

        -i|--install

       Install Debian packages (.deb) named on the command line. Only files in the directories
       /lib, /usr/lib and /usr/include are extracted, since only they can be relevant for cross
       compiling. In the lib directories, also no subdirectories are extracted.

        -A|--convert-anyway

       Convert Debian package even if it does not provide any files useful for cross-compile
       environment.

        -M|--convert-multiarch

       Convert package even if it is a multiarch package. If the package is not a multiarch
       package, processing continues as normal.

        -X|--exclude PACKAGE

       Removes the specified package from the dependencies of the current package. Typically used
       to drop dependencies on packages that are not required within a cross-build environment,
       e.g. packages containing only executables or architecture independent files.

       dpkg-cross can only check the current package and information about a dependency is not
       available (for that, use xapt). By default, dpkg-cross converts all dependencies to
       specify the cross version of the dependency package.

       If you know that a particular dependency should not be converted (it provides no useful
       files or is architecture  independent), that dependency can be excluded and dpkg-cross
       will remove that package from the dependency information of the cross package. -X has
       replaced the use of keepdeps and removedeps in /etc/dpkg-cross/cross-compile.

       -X|--exclude PACKAGE needs to be repeated for each package to be excluded.

        -k|--keep-temp

       Keep the built and installed package instead of deleting it.  Requires --install.

        -b|--build

       Just build the converted Debian package, but do not install it with dpkg.

        -r|--remove

       Remove the cross compiling packages named on the command line.

        -s|--status

       Print status of the named packages.

        -l|--list

       Print short version of status of named packages or package name patterns.

        -L|--list-files

       List files belonging to the named packages.

        -u|--update

       Update current cross-installation with Debian packages found in/under the paths given as
       arguments. Will check all packages there if they are installed already as cross-compiling
       packages and if they are really updates. Those packages will be installed as with -i.

        -Q|--query

       Much like --update, but just prints available update packages and does not install them.

FILES

       /etc/dpkg-cross/cross-compile defines the default_arch for dpkg-cross:

       The default architecture for dpkg-cross is normally set by debconf.  To change the system-
       wide value, use:

        $ sudo dpkg-reconfigure dpkg-cross

       Alternatively, the default can be overridden on a per-user basis using the optional file
       in $HOME/.dpkg-cross/

Conversion process

       There is no safe way for dpkg-cross to mangle certain files in -dev packages, particularly
       files in /usr/share or to determine precisely which of these files could be parsed and
       which cannot. Special cases do not help - dpkg-cross already has too many of those.

       It is not safe to leave files in the package nor is it safe to move files into arbitrary
       locations when there is no reliable and standardised way to determine the usefulness of a
       particular kind of file. Package specific config scripts cannot be supported and even
       build-system specific ones are not necessarily going to work without a lot of ongoing
       maintenance.

       Therefore, "dpkg-cross" is very restrictive on which files are retained in the -cross
       package.

   Files to be converted
       All files in

        /usr/include/*

       Also /usr/src and /usr/lib are searched for includes - files with .h, .hh, .hpp extensions
       (case insensitive).

       Library files - *.so* and *.a and *.o files from /lib and /usr/lib (and all the multilib
       eqivalents (lib64, lib32, libo32, libhf, libx32 etc).  Other library files are not copied.
       *.la files in library directories are also copied, and library and paths are modified
       there. Same for /usr/lib/pkgconfig/*.pc files.

       Symlinks are copied (and modified appropriately) if their destination is copied. Also,
       symlinks to non-existing shared libraries are copied (this is common case for libdevel
       packages)

       Directories are created only to hold some files or symlinks.  No empty directories are
       copied.

Multiarch behaviour

       By default <dpkg-cross> does nothing with packages from Debian which already support
       Multi-Arch - the package is simply copied to the current work directory, if it does not
       already exist. Any package containing a Multi-Arch: field in DEBIAN/control is skipped in
       this manner.

       --convert-multiarch can be specified to instead force the generation of a -<arch>-cross
       package with the files moved into the conventional dpkg-cross locations.

       The Multiarch spec ensures that multiarch packages will only be available from Debian
       mirrors once dpkg itself is capable of installing the packages and installing a Multiarch
       package means being able to install a 32bit multiarch package alongside a 64bit multiarch
       package.  Installing an armel multiarch package alongside an x86 multiarch package is no
       different to 32bit vs 64bit. (What changes is how the multiarch package itself handles the
       header files and pkg-config files.)