NAME

       perl-cross-debian - Long term maintenance of cross-build support for the Debian configuration of perl

SYNOPSIS

       perl-cross-debian [--rootdir=DIRECTORY] --variant=STRING

       perl-cross-debian --clean

       perl-cross-debian [{-h | --help} | {-v | --version}]

DESCRIPTION

       perl-cross-debian supports the long term maintenance of cross-build support for the Debian configuration
       of perl.

       perl-cross-debian is not expected to be run directly on the command line, it is executed by the modified
       debian/rules of a Debian source package of perl, within the constraints of a cross-build.
       perl-cross-debian uses the cross-building environment set by dpkg-architecture -aARCH to provide
       essential configuration values for the requested architecture to avoid executing cross-built binaries
       within the cross-build. Full support is limited to specific versions of perl already packaged in Debian
       and only for selected architectures.

       perl-cross-debian copies pre-produced config files into the current perl build tree to prevent the build
       from needing to execute test binaries during the configuration stage by providing the values of the tests
       in advance.  perl-cross-debian then extracts values from the cached files to update the build information
       and package Makefiles.

       perl-cross-debian then relies on a patched Makefile.SH to call the host perl interpreter instead of the
       perl interpreter being built internally.

       See Running the cross build for details of how to prepare the Debian packages of perl for cross-building
       for the one of the currently supported host architectures. (Patches to apply to supported Debian versions
       of perl are included in /usr/share/perl-cross-debian/patches).

       See perl-cross-staging (1) for information on how to extend perl-cross-debian to other host architectures
       and other versions of perl.

COMMAND

       --variant VARIANT
           Name of the current perl build variant (static, debug or shared), passed in via debian/rules, must be
           specified once for each iteration.

       --clean
           Runs the perl-cross-debian clean target and exits zero.  --clean overrides any --variant command -
           the clean operation does not depend on the current variant.

OPTIONS

       --rootdir DIRECTORY
           Debug support for testing with unreleased config files, uses the files from the rootdir instead of
           looking in the /usr/share/perl-cross-debian/$(DEB_HOST_GNU_TYPE)/$(PERL_VERSION) directory.
           ($(PERL_VERSION) in this instance is the output of /bin/bash debian/config.debian --full-version.)

       -?, -h, --help, --version
           Show summary of options and the version information.

LIMITATIONS

       perl-cross-debian implements a safeguard that the perl interpreter to be used during the cross-build is
       the same upstream version as the perl interpreter to be cross-built due to limitations of DynaLoader.pm :

           arm-linux-gnueabi-gcc -c   -D_REENTRANT -D_GNU_SOURCE -DDEBIAN -D_FORTIFY_SOURCE=2 -g -O2 -fstack-protector
            --param=ssp-buffer-size=4 -Wformat -Werror=format-security -fno-strict-aliasing -pipe -I/usr/local/include
            -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -O2 -g   -DVERSION=\"3.39_02\" -DXS_VERSION=\"3.39_02\"
            -fPIC "-I../.."   Cwd.c
           Running Mkbootstrap for Cwd ()
           DynaLoader object version 1.13 does not match $DynaLoader::VERSION 1.14 at ../../lib/DynaLoader.pm line 86.
           Compilation failed in require at ../../lib/ExtUtils/Mkbootstrap.pm line 27.

       Instead, perl-cross-debian dies with a version mismatch and fails the cross-build. Ensure that the
       installed perl interpreter is upgraded before testing a cross-build of the updated perl source code (or
       use a chroot). When using a chroot and old-style dpkg-cross dependencies, consider preparing at least the
       zlib and bzip2 dependencies outside the chroot as a new version of perl is frequently not installable
       with lots of perl modules such as those used by dpkg-cross. e.g. zlib1g-dev-armel-cross and
       libbz2-dev-armel-cross as well as libdb-dev-armel-cross and libgdbm-dev-armel-cross.

           sudo xapt -a armel -b zlib1g-dev libbz2-dev libdb-dev libgdbm-dev

       The -cross packages are in /var/lib/xapt/output and need to be copied into the chroot and installed with
       dpkg -i ./*

       perl-cross-debian also implements a safeguard to prevent cross-builds when DEB_BUILD_OPTIONS="nocheck"
       has not been set prior to starting the build. Cross-build failures due to the running of test code within
       the perl build are not always easy to identify, so perl-cross-debian checks for this build option and
       fails the cross-build if it is not set. (The check occurs inside perl-cross-debian so the clean target
       will have been run before the check is made.)

RUNNING THE CROSS BUILD

       perl-cross-debian needs some changes to the perl package before cross-building, so ensure that
       Makefile.SH and debian/rules are both patched and that the cross dependencies and cross compiler are
       installed.

       Patches are carried in the perl-cross-debian package in /usr/share/perl-cross-debian/patches.

       debuild is preferred as this will provide a build log and run lintian (by default) which means that the
       built packages will be checked to ensure that the binaries have been correctly compiled for the cross
       architecture (amongst the normal checks). Run the cross build with:

           DEB_BUILD_OPTIONS="nocheck" debuild -aarmel -us -uc -d

       Note the use of the -d option as dpkg cannot check cross-build dependencies until MutiArch -dev packages
       are in use and the requirement for DEB_BUILD_OPTIONS to disable the test suite.

SUPPORTED VERSIONS AND ARCHITECTURES

       perl-cross-debian support is patchy but can be improved. Only specific architectures at specific versions
       are supported - if you do not find the files for the requested version in the directory of the
       architecture required, see perl-cross-staging (1) for information on how this information can be added
       and also for details of ongoing work with perl upstream.

CLEAN TARGET SUPPORT

       perl-cross-debian includes support for a custom clean target for cross-builds to ensure that
       version-specific content generated during the cross-build is cleaned up before dpkg-source tries to
       verify the source package. If there are additional files which need to be cleaned, file a bug against
       perl-cross-debian.

EXTENSION INSTALLATION

       The current method of building and installing the extensions does need testing and improvement. Whilst
       the main emphasis for a perl cross build is to support bootstrapping by having the normal perl
       interpreter available instead of just miniperl, there may be less emphasis on the correct functioning of
       the extensions and modules normally packaged by a native perl build. Problems relating to any use of perl
       extensions and modules when the cross built perl packages are installed should be reported as bugs in
       perl-cross-debian.

EXTENDING PERL-CROSS-DEBIAN

       perl-cross-debian provides some POD documentation of how to extend support to new architectures and how
       to update existing support for new versions of perl.

       See /usr/share/doc/perl-cross-debian/converting-native.pod and
       /usr/share/doc/perl-cross-debian/new-arch.pod

AUTHOR

       Neil Williams <codehelp@debian.org>
           Wrote this manpage for the Debian system.

COPYRIGHT

       Copyright © 2012 Neil Williams

       This manual page was written for the Debian system (and may be used by others).

       Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General
       Public License, Version 2 or (at your option) any later version published by the Free Software
       Foundation.

       On Debian systems, the complete text of the GNU General Public License can be found in
       /usr/share/common-licenses/GPL.