That's NAME, not TITLE.

[p5sagit/p5-mst-13.2.git] / Cross / README.new

You're reading ./Cross/README.new, describing Perl cross-compilation process.
NOTE: this file will replace ./Cross/README, after cross-compilation scheme
will stabilize;

=head1 Cross-compilation for linux

This is second approach to linux cross-compiling, which should allow building
full perl and entensions for target platform. Cross-compiling for linux
uses similar approach and share same files as cross-compiling for WINCE.

We refer to HOST as the platform where the build is performed, and to
TARGET as where final executables will run.

=head2 Basic ideas

=head3 common

Unlike WINCE, output files from GCC cross-compiler are produced in the same
directory where C files are. All TARGET binaries have different extensions
so to distinguish HOST and TARGET binaries. Namely, object files for C<arm>
cross-compilation will have extension C<.armo>, executable files will have
C<.arm>.

After typical cross-compilation the following files will be built, among
others:

  sv.c
  sv.o
  sv.armo
  libperl.arma

(this approach may be reconsidered, however.)

=head3 build process

C<miniperl> is built. This executable is intended to run on HOST, and it
will facilitate the remaining build process; all binaries built after it are
foreign (TARGET) and should not run locally (HOST).

Unlike HOST build, miniperl will not have C<Config.pm> of HOST within reach;
it rather will use the C<Config.pm> from the cross-compilation directories.
In fact, if the build process does have Config.pm within reach, this is only
an indication of a mistake somewhere in the middle.

  # following command is okay:
  ./miniperl -Ilib -MCross -MConfig -e 1
  # following command should cluck, and it is bad if it does not:
  ./miniperl -Ilib -MConfig -e 1

After C<miniperl> is built, C<configpm> is invoked to create right C<Config.pm>
in right place and its corresponding Cross.pm.

File C<Cross.pm> is dead simple: for given cross-architecture places in @INC
a path where perl modules are, and right C<Config.pm> in that place.

That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
it can not find C<Config.pm>. If it does not give an error -- wrong C<Config.pm>
is substituted, and resulting binaries will be a mess.

C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
C<Config.pm> for further compilations.

During extensions build phase, the script C<./ext/util/make_ext_cross> is
invoked.

All invokes of C<Makefile.PL> are provided with C<-MCross> so to enable cross-
compile.

=head2 BUILD

=head3 Tools & SDK

For compiling, you need following:

=over 4

=item * TODO

=back

=head1 Things to be done

=over 4

=item * better distinguishing of config.h/xconfig.h, dependancies

=item * object files created in ./xlib/cross-name/ ?

=back