Cross/README.new

   1 You're reading ./Cross/README.new, describing Perl cross-compilation process.
   2 NOTE: this file will replace ./Cross/README, after the cross-compilation scheme
   3 is stabilized.
   4
   5 =head1 NAME
   6
   7 README.new - Cross-compilation for linux
   8
   9 =head1 DESCRIPTION
  10
  11 This is second approach to linux cross-compilation, which should allow
  12 building full perl and extensions for target platform.
  13
  14 We refer to HOST as the platform where the build is performed, and to
  15 TARGET as where final executables will run.
  16
  17 =head2 Basic ideas
  18
  19 =head3 common
  20
  21 Output files from GCC cross-compiler are produced in the same
  22 directory where C files are. All TARGET binaries have different extensions
  23 so to distinguish HOST and TARGET binaries. Namely, object files for C<arm>
  24 cross-compilation will have extension C<.armo>, executable files will have
  25 C<.arm>.
  26
  27 After typical cross-compilation the following files will be built, among
  28 others:
  29
  30   sv.c
  31   sv.o
  32   sv.armo
  33   libperl.arma
  34
  35 (this approach may be reconsidered, however.)
  36
  37 =head3 build process
  38
  39 C<miniperl> is built. This executable is intended to run on HOST, and it
  40 will facilitate the remaining build process; all binaries built after it are
  41 foreign (TARGET) and should not run locally (HOST).
  42
  43 Unlike HOST build, miniperl will not have C<Config.pm> of HOST within reach;
  44 it rather will use the C<Config.pm> from the cross-compilation directories.
  45 In fact, if the build process does have Config.pm within reach, this is only
  46 an indication of a mistake somewhere in the middle.
  47
  48   # following command is okay:
  49   ./miniperl -Ilib -MCross -MConfig -e 1
  50   # following command should cluck, and it is bad if it does not:
  51   ./miniperl -Ilib -MConfig -e 1
  52
  53 After C<miniperl> is built, C<configpm> is invoked to create an
  54 appropriate C<Config.pm> in the right place and its corresponding
  55 C<Cross.pm>.
  56
  57 File C<Cross.pm> is dead simple: for given cross-architecture places in @INC
  58 a path where perl modules are, and right C<Config.pm> in that place.
  59
  60 That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
  61 it cannot find C<Config.pm>. If it does not give an error, a wrong C<Config.pm>
  62 is substituted, and resulting binaries will be a mess.
  63
  64 C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide a
  65 correct C<Config.pm> for further compilations.
  66
  67 During extensions build phase, the script C<./ext/util/make_ext_cross> is
  68 invoked.
  69
  70 All invocations of C<Makefile.PL> are provided with C<-MCross> so to enable
  71 cross-compilation.
  72
  73 =head2 BUILD
  74
  75 =head3 Tools & SDK
  76
  77 To compile, you need the following:
  78
  79 =over 4
  80
  81 =item * TODO
  82
  83 =back
  84
  85 =head1 Things to be done
  86
  87 =over 4
  88
  89 =item * better distinguishing of config.h/xconfig.h, dependencies
  90
  91 =item * object files created in ./xlib/cross-name/ ?
  92
  93 =back