=pod

=head1 Name

converting-native - guidance on updating an existing architecture

=head1 Converting a series of native files to cross-support

Once more data is collected for particular versions of perl, this step
may become scriptable. For now, there are steps to be taken to prepare
a set of cross-build support data files from the files collated from a
particular sequence of build commands on the native architecture.

=head1 Prerequisites

=over 1

=item Debian buildd base system

F<perl-cross-debian> only supports Debian builds - numerous config settings
will change if perl detects a different base system and these will mask
the required changes to update the cross support to that version of perl.

Always prepare the files on a Debian base system - specifically a Debian
buildd system which is as close as possible to a typical buildd environment.

This explicitly includes ensuring that all of the Debian build-dependencies
for the version of perl to be tested are installed correctly as Debian
packages - i.e. C<dpkg-checkbuilddeps> must complete successfully and the
same environment must be capable of doing a complete native build of perl,
including running the test suite successfully.

It is uncertain at this time whether a Debian chroot on a non-Debian
system is supportable - if relevant data is collected and compared, this
can be clarified.

=item Debian patches applied

Similarly to the buildd setup, the config files can be affected by the
patches normally applied by Debian. Therefore, the cross-support for any
particular version of perl can only be started after the first usable
upload of perl is made for that version, typically via experimental and
the full Debian patch set needs to be applied. For this reason, the
data builds use C<fakeroot debian/rules> and it is necessary to run
C<debclean> between runs.

=back

=head1 Running each of the three builds

C<perl-cross-staging> will do this work for you, but the manual steps
are described here for easier debugging.

=over 1

=item Static config files

 DEB_BUILD_OPTIONS="nocheck" fakeroot debian/rules perl.static 

 cp config.h ../config.h.static
 cp config.sh ../config.sh.static

=item Debug config files

 DEB_BUILD_OPTIONS="nocheck" fakeroot debian/rules perl.debug 

 cp config.h ../config.h.debug
 cp config.sh ../config.sh.debug

=item Shared library config files

 VERSION=`/bin/bash debian/config.debian --full-version`
 DEB_BUILD_OPTIONS="nocheck" fakeroot debian/rules libperl.so.$(VERSION)

 cp config.h ../config.h.shared
 cp config.sh ../config.sh.shared

=back

=head2 Identifying and caching generated header files

Versions of perl from 5.16.2 onwards use a generated_headers variable in
Makefile.SH - each of those headers needs to be copied out of the tree
and kept for cross-build support.

These headers B<are not expected to change> between stages B<but must
be compared> between builds to check for modified upstream behaviour.

To see how these headers are generated, see the C source code in perl upstream:
F<generate_uudmap.c>

This C file can be compiled using the native compiler for any architecture
or an existing cross compiler for a new architecture and executed on that
architecture or a model to generate the headers.

=over 1

=item Example from an amd64 build of perl 5.14.2:

 $ make generate_uudmap
 cc   -Wl,-z,relro -fstack-protector -L/usr/local/lib  generate_uudmap.c   -o generate_uudmap
 $ ./generate_uudmap uudemap.h bitcount.h

In 5.14.2, these headers are included into F<perl.h> and used in
F<pp_pack.c> for unpacking support. e.g. in 5.14.2, bitcount.h is a
population count of an array of char.

e.g. EBCDIC platforms are likely to produce different content to
common destktop / embedded platforms. Modern Linux kernels are able to
use an in-kernel converter to handle EBCDIC as ASCII on such platforms.

http://en.wikipedia.org/wiki/EBCDIC

=back

Note that different versions of perl prepare different sets of generated
headers - check the source code of the version of perl you are using.

=head1 Handling absolute paths

The cached files will contain absolute paths based on the environment of
the native build system which will not necessarily match any future
cross-build. The absolute paths in fields like B<installscript> and
B<installbin> need to be converted:

 '/home/codehelp/perl/5.14/perl-5.14.2/debian/tmp/usr/bin'

becomes:

 'PERL_BUILD_DIR/debian/tmp/usr/bin'

=head1 Retaining architecture-dependent values

The staged files are generated within the perl build system and the
ordering and layout of the files frequently changes between perl upstream
versions. This needs careful management as the files are several
thousand lines long and it can be all to easy to port the values for
the staging architecture and not update with the original cross values
which occur later in the same file.

Fix the ordering of the files first, then look at the lines which only
occur in the cross files and update the earlier sections with the original
cross values.

=head1 Adding new upstream features and components

If the cross build fails at the installperl stage, check the listed
extensions, known_extensions, nonxs_ext and dynamic_ext in the config
files for the cross architecture and compare with the files from 
C<perl-cross-staging>. 

=head1 Testing the updated files

Use the --rootdir option to C<perl-cross-debian> to copy in files from
your staging location instead of from the installed files in /usr/share
and remember to test with a fully patched tree and with DEB_BUILD_OPTIONS
set to include 'nocheck'.

=head1 Adding the files to perl-cross-debian

Within the F<perl-cross-debian> source code tree for the relevant
architecture, create a new directory for the full upstream version string
obtained from:

 /bin/bash debian/config.debian --full-version

Just add all the cross-support files into the new directory.

If the list of generated_headers has changed in this version of perl,
C<perl-cross-debian> may need modification to look for and copy the new
list.

=cut
