MkDocs migration

.gitignore

@@ -1,3 +1,4 @@
 perl-cross.tar
 perl-cross-*.tar.gz
 tags
+site

docs/design.md

@@ -0,0 +1,89 @@
+# Cross-compiling perl
+
+---
+
+All configure-related files (except for ./configure which is just
+a wrapper script) are stored in cnf/ directory.
+For the sake of clarity/readability, sh functions are used extensively.
+
+Each config.sh variable is only set once, and immediately written
+to config.sh. Attempts to re-set it later are ignored. This scheme is used
+to implement hints and handle command-line overrides: both force the value
+to be written early, prevent normal configure code from setting it.
+Check configure__f.sh for the code that does it.
+
+Values that cannot be tested on the build host are supposed to be set
+by target-specific hint files. See [hints page](hints.md) on this.
+
+## configure files
+
+cnf/configure is the entry point, and the only file that calls other
+configure_* files. Test-specific functions are defined in their respective
+test files. The tests are mostly independent, but do rely on values from
+preceeding tests, and most rely on target toolchain being set up.
+
+## configure variables
+
+Most variables from config.sh are described in Porting/Glossary in the
+perl source. Make sure to check that file.
+
+To see where a particular variable gets defined, grep its name in cnf/*.sh.
+Beware there's one exception: d_(func)_r and (func)_r_proto are not greppable.
+Those symbols are set in configure_thrd.sh.
+
+## Patching perl files
+
+There are some minor changes perl-cross needs in the original perl files.
+Relevant patches for each supported upstream version are supplied in
+`cnf/diffs/`.
+
+The patches are applied by `crosspatch` make target, which is
+the first one in `make all` sequence.
+
+For each successfully applied `cnf/diffs/file.patch` a lock file
+`cnf/diffs/file.applied` is created, so the patches are not applied
+twice.
+
+## Building miniperl
+
+miniperl should work on the build, not target, platform. It is compiled
+using native compiler, unlike primary perl executable which is built later
+using build-to-target cross-compiler. Because of this, during cross-build
+configure is run twice, first to set up miniperl and then to set up
+the main perl config.
+
+Native and target build differ in file extensions: the latter uses usual .o
+(default) but the former has .host.o instead. All object files are kept in
+the same (root) directory.
+
+Different configs are used for different platforms:
+config.{h,sh} for the target build and xconfig.{h,sh} for build-time miniperl.
+**Beware**: this is exactly opposite of what the original Configure does,
+The relation was inversed because most tools use config.sh by default, and cross-build
+is viewed as primary. Among other things, building extensions with config.sh
+is simpler, and extensions are not built for miniperl.
+
+See also [Cross-compiling modules](modules.md) on some issues
+with config files.
+
+## Build-time scripts
+
+Most of the time perl-cross tries to use scripts like configpm,
+utils/ext/* etc. unchanged.
+.
+
+Some of the code used during build stage tries to load XS modules.
+Most of the time, for mundane tasks like can_run() or tempfile() or strftime().
+This is not acceptable for perl-cross, which uses miniperl to run those
+(unlike the native makefiles which can and do rely on newly-built perl).
+
+Current solution is either to patch the offending scripts, or to provide
+minimalistic pure-perl stubs for the required XS modules.   
+Patches are kept in `cnf/diffs`, and stubs are in `cnf/stub`.   
+In one particular case, Digest::MD5, a dynaloaded module was replaced with
+non-XS equivalent Digest::MD5::Perl from CPAN.
+
+The way configpm used to choose which files to update made no sense with
+the new configure, so it was changed: --config-sh, --config-pm and --config-pod
+were added, with default values set to config.sh, lib/Config.pm
+and lib/Config.pod.

docs/download.md

@@ -0,0 +1,174 @@
+# Cross-compiling perl
+
+---
+
+Current version of perl-cross is 1.1.0   
+Supported perl versions: perl-5.24.0, perl-5.25.4, cperl-5.24.0, cperl-5.25.0.   
+Download it here:
+
+!!! note " "
+    <https://github.com/arsv/perl-cross/releases/download/1.1.0/perl-cross-1.1.0.tar.gz>
+
+To use, unpack over an appropriate perl distribution, overwriting the original Makefile.
+Use one of supported perl versions; the are version-specific patches inside.
+
+For older releases, check [GitHub releases branch](https://github.com/arsv/perl-cross/tree/releases).
+
+## Changelog
+- 1.1.0 (2016-09-12)
+    + Major code cleanup
+    + Package name changed to `perl-cross-N.M.tar.gz`
+    + Support for multiple perl versions
+    + Experimental cperl support
+    + General list of config.sh variables (configure_genc.sh) removed; values are now written to config.sh immediately
+    + bash is no longer necessary to run configure; dash or busybox sh should be enough
+    + Extended -A support removed (prepend and such)
+    + Build host info (cf_by, cf_email etc) is no longer passed to config.sh
+    + Various test fixes, and some new tests
+    + Hints re-arranged, support for compiler hints removed
+    + Newer gcc get -fwrapv -fno-strict-aliasing in ccflags
+    + `gccversion` is now set for any cc
+- 1.1 (2016-09-10) &mdash; botched release, see 1.1.0 instead
+- 1.0.3 (2016-06-30)
+    + perl-5.24.0
+    + Android detection and proper osname
+    + Errno.pm building fixed for Android
+    + fixed rpath handling in presence of --sysroot
+    + busybox sed may be used now instead of GNU sed
+- 1.0.2 (2015-12-15)
+    + perl-5.22.1
+    + Berkeley DB detection fix (DB::File)
+- 1.0.1 (2015-11-03)
+    + poisoned paths patch from Buildroot
+    + disable gcc built-ins to avoid false positives in hasfunc
+    + proper escaping for values written to config.sh
+- 1.0.0 (2015-08-26)
+    + perl-5.22.0
+    + floating-point functions detection and minor updates
+    + absolutely nothing special about this release
+- 0.9.7 (2015-06-28)
+    + MakeMaker library detection fixes
+    + better --no-dynaloader / --all-static options handling
+- 0.9.6 (2015-03-07)
+    + a2p yacc invocation suppressed for 5.20.2 sources
+- 0.9.5 (2015-02-24)
+    + perl 5.20.2
+    + --sysroot handling fixed
+- 0.9.4 (2014-11-04)
+    + --all-static fix
+- 0.9.3 (2014-10-14)
+    + perl 5.20.1
+    + bigendian target byteorder detection fix
+- 0.9.2 (2014-09-20)
+    + minor updates to handle perl 5.20.1-RC1
+    + soname'd libperl installation
+- 0.9.1 (2014-08-26)
+    + module cleanup for 5.20.0
+    + host-installed miniperl stuff removed
+- 0.9 (2014-08-01)
+    + perl-5.20.0
+- 0.8.5 (2014-02-23)
+    + out-of-source builds with absolute path to the source
+    + patch --follow-symlinks is not used anymore
+- 0.8.4 (2014-02-20)
+    + variable/versioned libperl.so
+    + out-of-source building support
+    + default paths fixed (sitescript/vendorscript)
+    + some Makefile fixes
+    + project moved to GitHub
+- 0.8.3 (2013-10-19)
+    + Testpack for on-target testing
+    + $extensions, ${static,dynamic,nonxs}_ext format changed to match Configure
+    + $sharepath default fixed
+- 0.8.2 (2013-09-09)
+    + NV-related tests added
+    + C++ and ELF format test added
+    + largefile flags are now passed correctly to tests & modules
+    + $ccdefines variable dropped in favor of $ccflags
+    + hint files handling changed
+    + config.sh variables list updated to match current Configure closely
+    + --with-*, --host-* options handling fixed
+- 0.8.1 (2013-09-05)
+    + perl-5.18.1 (with no changes to perl-cross)
+    + test-related fixes
+- 0.8 (2013-08-08)
+    + perl-5.18.0
+    + module stubs are provided for ExtUtils::* to make them usable with miniperl
+    + patch application is now done as a bulk phony target; patching the files in-place doen't translate well into make-dependencies
+    + module paths fixes
+    + Makefile dependencies cleaned up
+- 0.7.4 (2013-04-11)
+    + shared libperl support; enable with -Duseshrplib
+    + nv_preserves_uv stuff reset to safe defaults; it can't be tested for currently, but at least it won't cause precision issues
+- 0.7.3 (2013-04-05)
+    + libs/perllibs split, and libswanted handling fixes; NDBM is properly linked now
+    + standard format for extensions lists in $Config
+    + install paths adjusted to match mainline perl
+    + $libpth default value added, DynaLoader::dl_findfile should work now
+    + drop-in replacement for Digest::MD5, calling Digest::Perl::MD5; no need to alter existing scripts anymore
+    + patched Liblist now warns about non-usable libraries (and passes relevant tests)
+    + minor config.sh tweaks
+- 0.7.2 (2013-03-25)
+    + perl-5.16.3
+    + preliminary "make test" support (native builds only for now)
+    + specifying --mode manually should work as expected in most cases
+    + various configure/Makefile fixes
+- 0.7.1 (2012-12-15)
+    + use gcc for dynalinking modules
+- 0.7 (2012-07-06)
+    + perl-5.16.0
+    + original perl files are now patched (vs. supplying modified versions)
+    + Digest::Perl::MD5 added to allow using install{perl,man} with miniperl
+    + Module name handling fixed in make_ext_Makefile.pl
+    + archlib is now $prefix/lib/perl/$archname, instead of just $prefix/lib/perl/arch
+    + d_csh set to undef, to prevent glob() failures
+    + useithreads and use5005threads handling added
+- 0.6.5 (2012-02-16)
+    + inttypes.h added in byte order test
+- 0.6.4 (2011-12-05)
+    + /bin/sh changed to /bin/bash, take 2
+- 0.6.3 (2011-11-02)
+    + perl-5.14.2 (without any actual changes to perl-cross)
+    + /bin/sh changed to /bin/bash everywhere
+- 0.6.2 (2011-09-03)
+    + Android and Intel CC builds support
+    + --sysroot is now passed to compiler/linker
+    + target specifications not recognized by config.sub are allowed
+    + several configure tests fixes
+    + no-DynaLoader configuration support
+- 0.6.1 (2011-08-24)
+    + static modules handling fixed
+    + --all-static option for configure
+- 0.6 (2011-08-20)
+    + perl-5.14 support
+    + make rules to build disabled modules
+    + hints switched to flat directory style, added compiler and mode hints
+    + libswanted handling fixed
+    + configure now reads patchlevel.h to get perl version
+    + minor fixes & cleanup
+- 0.5 (2011-07-23)
+    + need_va_copy bug fixed (this is what caused build errors on x86_64)
+    + configure can now load configuration from a file (-f, -O)
+    + support for most of the original Configure options (inc. -D, -U, -A)
+    + --set/-D now allow passing arbitrary variables to config.sh
+    + make rules to track MakeMaker dependencies
+    + ccflags/ldflags support fixed
+    + -DEBUGGING support added
+    + environment clean-up added, configure no longer stumbles upon stray environment variables
+    + Time::HiRes specific hints to allow successful builds
+    + removed module tests for miniperl
+- 0.4.1 (2011-04-25)
+    + make rules for xsubpp changed
+    + fixed static modules handling
+- 0.4 (2011-03-11)
+    + perl-5.12 support
+    + miniperl_top introduced
+    + make rules for all modules, make_ext is no longer used
+- 0.3 (2011-03-04)
+    + threads support
+    + various fixes done after the demise of the old site
+- 0.2 (2009-12-06)
+    + make rules for DynaLoader fixed
+    + other minor fixes to allow MIPS build
+- 0.1 (2009-01-05)
+    + first public release

docs/hints.md

@@ -0,0 +1,52 @@
+# Cross-compiling perl
+
+---
+
+Hints are pre-defined values for config.sh variables, used when
+testing for particular value is impossible or such test should be
+avoided for whatever reasons.
+
+Hints for perl-cross are stored under `cnf/hints`.
+Unless told otherwise with `--hints`, configure will load
+hints for `$archname` and `$osname`. A build that ends
+up creating `$prefix/lib/perl5/5.24.0/x86_64-linux` likely
+starts by loading `cnf/hints/x86_64_linux` and `cnf/hints/linux`.
+
+Hints in perl-cross are not just regular shell scripts.
+They are filtered with `sed` and generally should not contain
+anything but
+
+```text
+variable="properly quoted value"
+```
+
+lines, which are internally converted to
+
+```text
+hint variable "properly quoted value"
+```
+
+and then executed.
+
+### Difference between mainline perl hints and perl-cross hints
+
+Hint files supplied with the mainline perl (hints/ in the source tree)
+and not used by perl-cross configure. This is mainly because mainline perl
+hint files are expected to take care of preset variables and command line
+options by themselves, in style with the rest of Configure, while perl-cross
+configure handles such things in a different manner.
+These two systems do not mix very well.
+
+Another reason is that mainline hints are allowed to run tests and look
+around in the host system, which is a good way to get into troubles during
+cross builds.
+
+Mainline hints use (os).sh naming scheme and must determine
+other aspects of target configuration internally using conditionals.
+In contrast, perl-cross uses passive hint files with nothing but variable
+assignments in them.
+
+perl-cross does not support callbacks and per-file cflags from the mainline
+hints. Callbacks are not really necessary in non-interactive mode because all
+user-set values are known from the very start, and cctype hints partially
+solve the problem of compiler related settings.

docs/index.md

@@ -0,0 +1,76 @@
+# Cross-compiling perl
+
+---
+
+**perl-cross** provides alternative `configure` script,
+top-level Makefile as well as some auxilliary files for the standard
+**perl** distribution intended to allow cross-compiling perl in
+a relatively straighforward way.
+
+!!! note " "
+    perl-cross is not a part of perl distribution, it's a third-party tool in an eternal-alpha state.
+
+    **Use at your own risk!**
+
+    If you can use Configure from the vanilla distribution, you probably should use Configure;   
+    **perl-cross** is for the cases when Configure just can't make it.
+
+The configure script from perl-cross is essentially a 100 kB long session
+of severe sh(1) abuse. Unlike the products of GNU autoconf, it sacrifices
+portability for readability; it will likely only run on a relatively sane GNU
+system with GNU binutils (which is kind of expected for a cross-build
+but still feels like a limitation).
+
+Typical native build:
+
+```sh
+./configure
+make
+make DESTDIR=... install
+```
+
+Typical cross-build for a uclibc system on a Geode board:
+
+```sh
+./configure --target=i586-pc-linux-uclibc
+make
+make DESTDIR=... install
+```
+
+See [configure usage](usage.md) page for a complete list
+of available `configure` options.
+
+## History
+
+perl can't be cross-compiled "out of the box".
+You can get an impression it isn't so when you read INSTALL file,
+but once you start digging deeper (or just trying to do it),
+you quickly find out that this cross-compilation
+
+- requires SSH access to the target system
+- and/or requires hand-crafted config.sh
+- ...and still doesn't work
+- when performed routinely, is performed in some non-standard way
+  (by circumventing Configure and patching source tree)
+
+Cross-compiling is rarely easy, but in case of perl this was not enough to explain why it is **so** hard.
+After all, many autoconf'ed projects allow it much easier.
+I had no intention to build native toolchain for my Alix project
+(more for ideological reasons, not due to impossiblity, but that's another question).
+A close look at config.sh made me sure I'm **not** going to hand-craft it.
+CE and other ports were outright target-specific hacks, didn't work too and could not satisfy me anyway.
+So I started hacking it on my own.
+
+Currently the whole thing works well enough to suite my needs.
+It's still of alpha quality though; use with caution,
+and be ready to tweak it (I hope it's tweakable enough).
+
+## Authors
+
+Alex Suykov <[email protected]>.   
+Feel free to ask questions, most of the time I'll try to help.
+
+Several other people contributed patches and suggestions.
+
+If possible, please report successful builds and/or problems you encountered
+while using perl-cross for your particular platform.