Cross-compiling perl

Unpack perl-X.Y.Z-cross-W.Q.tar.gz over perl-X.Y.Z distribution.
Perl-cross package should overwrite top-level Makefile and some other files in the perl source tree.

The build process is similar to that of most autoconf-based packages. For a native build, use something like

	./configure --prefix=/usr
	make
	make DESTDIR=/some/tmp/dir install

For a cross-build, specify your target:

	./configure --prefix=/usr --target=i586-pc-linux-uclibc
	make
	make DESTDIR=/some/tmp/dir install

Check below for other possible make targets.

Target-specific notes

Android. Tested with NDK 24.0.8215888, Perl 5.36.0, and perl-cross 1.4. Installed on a Pixel 6 in /data/local/tmp/perl.

	NDK=$HOME/Android/Sdk/ndk/24.0.8215888
	TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/linux-x86_64
	SYSROOT=$TOOLCHAIN/sysroot
	export AR=$TOOLCHAIN/bin/llvm-ar
	export CC=$TOOLCHAIN/bin/aarch64-linux-android21-clang
	export RANLIB=$TOOLCHAIN/bin/llvm-ranlib
	export STRIP=$TOOLCHAIN/bin/llvm-strip
	export NM=$TOOLCHAIN/bin/llvm-nm
	export READELF=$TOOLCHAIN/bin/llvm-readelf
	export OBJDUMP=$TOOLCHAIN/bin/llvm-objdump
	./configure --target=aarch64-linux-android --sysroot=$SYSROOT --prefix=/data/local/tmp/perl
	make
        make DESTDIR=<local install dir> install

Then, to install:

        cd <local install dir>/data/local/tmp
        find perl -type d -exec adb shell mkdir /data/local/tmp/\{\} \;
        adb push perl /data/local/tmp
	adb shell '/data/local/tmp/perl/bin/perl -e "print qq{Hello, world!\n}";'

Adjust platform and compiler version to match your particular NDK.

arm-linux-uclibc: successful build is highly likely.
Check target tools prefix, it may be useful here, especially if --sysroot is used.

	./configure --target=arm-linux-uclibc --target-tools-prefix=arm-linux-

ix86-* with Intel cc, native build: use -Dcc=icc. Configure will not supply any optimization options to the compiler, consider -Doptimize if necessary.

MinGW32: cannot be built yet. Configure will produce config.sh, but current perl-cross Makefiles can't handle win32 build.

	./configure --target=i486-mingw32 --no-dynaloader

Complete configure options list

Overall call order:

	configure [options]

Perl-cross configure adheres to common GNU autoconf style, but also accepts most of the original Configure options. Both short and long options are supported (-D, --define).

Valid ways to supply arguments for the options:

-f config.sh
-fconfig.sh
-D key=val
-Dkey=val
--set-key=val
--set key=val

Whenever necessary, dashes in "key" are converted to underscores; use --set-d-something instead of --set-d_something.

The only essential thing configure does is writing config.sh (and possibly xconfig.sh). Most options are meant to alter the values written there. Refer to Porting/Glossary for description of variables found in config.sh. This page only decribes how to modify them, not which values to use.

General configure control options:

--help: dump a short help message on stdout and exit
--mode=(native|cross|target|buildmini): set configure mode; used internally
--keeplog: Append to config.log instead of truncating it; used internally.
--regenerate: Re-generates config.h, xconfig.h and Makefile.config from config.sh and xconfig.sh. Does not change config.sh or xconfig.sh.

General installation setup:

--prefix=/usr: Installation prefix (on the target).
--html{1,3}dir=dir: Installation prefix for HTML documentation (not used)
--man{1,3}dir=dir: Installation prefix for manual pages
--target=machine: Target description (e.g. i586-pc-linux-uclibc); machine-gcc, machine-ld, machine-ar will be used for target build unless explicitly overriden, and perl archname will be set to machine. Hints will be choosen based on this value.
--target-tools-prefix=prefix: Use prefix-gcc, prefix-ld without overriding archname.
--build=machine: Same as --target but for host executables (miniperl)
--hints=h1,h2,...: Suggest specified hint files (cnf/hints/h1 and so on). The hints are processed after other options, see Workflow below.
--with-libs=lib1,lib2,...: Comma-separated list of libraries to check
(basenames only, use "dl" to have -ldl passed to the linker).
--with-cc=cmd: (target) C compiler.
--with-cpp=cmd: (target) C preprocessor.
--with-ranlib=cmd: (target) ranlib; set to 'true' or 'echo' to disable.
--with-objdump=cmd: (target) objdump; not used during the build, but crucial for some configure test.
--host-cc=cmd
--host-cpp=cmd
--host-ranlib=cmd
--host-objdump=cmd
--host-libs=cmd: Same, for host executables. Only useful when cross-compiling.
--sysroot=/path: Passed directly to target compiler, linker and preprocessor. See gcc(1) on how to use this option.

Options from the original Configure which are not supported or make no sense for this version of configure:

-e: go on without questioning past the production of config.sh
(ignored, you'll have to run make manually)
-E: stop at the end of questions, after having produced Jconfig.sh (ignored, that's the only way perl-cross works)
-r: reuse C symbols value if possible, skips costly nm extraction (ignored, configure uses completely different method of checking function availability)
-s: silent mode (ignored, perl-cross has no other modes)
-K: (not supported)
-S: perform variable substitutions on all .SH files (ignored, configure can't do that)
-V: show version number (not supported)
-d: use defaults for all answers (ignored, default mode)
-h: show help (ignored, use --help instead)

The following options are used to manipulate the values configure will write to config.sh. Check Porting/Glossary for the list of possible symbols.

-f file.sh

load configuration from a file.
See Workflow below.

-D symbol[=value]

set value for symbol; default value is "define".
Common examples (see INSTALL for more info):

-Duse64bitint use 64bit integers
-Duse64bitall use 64bit integers and pointers
-Dusethreads use thread support (also --enable-threads)
-Dinc_version_list=none do not include older perl trees in @INC
-DEBUGGING=none DEBUGGING options
-Dcc=gcc same as --with-cc=gcc
-Dprefix=/opt/perl5 same as --prefix=/opt/perl5

-U symbol

set symbol to "undef"; -U symbol= set empty value.

-O

let -D and -U override definitions from loaded configuration files; without -O, configuration files specified with -f will overwrite anything that was set using configure options. See Workflow below.

-A [a:]symbol=value

append value to symbol; some other forms are supported for compatibility with Configure but their use is discouraged.

--set symbol=value

Set symbol to value (default "").

--enable-something

Same as --set usesomething=define

--has-function

Same as --set d_function=define

--define-something

Same as --set something=define

--include-header[=yes|no]

Set i_header to 'define' or 'undef'; e.g. to disable <sys/time.h> use --include-sys-time-h=no.

When configuring for a cross-build, -D/--set and other similar options affect target perl configuration (config.sh) only. Use --host-option[=value] to pass --option[=value over to miniperl configure.

Configure tries to build all modules it can find in the source tree. Use the following options to alter modules list:

--static-mod=mod1,mod2,...: Build specified modules statically
--disable-mod=mod1,mod2,...: Do not build specified modules.
--only-mod=mod1,mod2,...: Build listed modules only
--all-static: Build all XS modules as static. Does not imply --no-dynaloader.
--no-dynaloader: Do not build DynaLoader. Implies --all-static. Resulting perl won't be able to load any XS modules. Same as -Uusedl.

modX should be something like cpan/Archive-Extract; static only applies to XS modules and will not affect non-XS modules.

make targets

Warning: run "make crosspatch" BEFORE making other targets manually.

Default make target is building perl and all configured modules. Other targets:

crosspatch: Apply all patches from cnf/diffs. Files are only patched once, cnf/diffs/path/file.applied locks are created to track that.
miniperl: Build miniperl only.
config.h
xconfig.h
Makefile.config: Re-build resp. files from [x]config.sh, may be needed after editing [x]config.sh manually. Note that make may try updating Makefile.config as a dependency for something else, but it won't re-read it immediately.
dynaloader: Build DynaLoader module. This is the first big target after miniperl, and the first that requires target compiler. If you can't get past dynaloder, something's really wrong. May be used to check target compiler viability.
perl: Build the main perl executable. Implies dynaloader and any static modules, but does not build dynamic or non-XS ones.
nonxs_ext
dynamic_ext
static_ext: Build all non-XS / dynamic XS / static XS modules listed in Makefile.config. Check Modules page for details.
modules
extensions: Build all modules at once.
cpan/Some-Module
ext/Some-Module: Build Some-Module. Only works for modules listed in Makefile.config.
modules-reset: Remove all pm_to_blib locks. See Modules page for more info.
modules-makefiles: Create/update Makefiles for all configured modules.
modules-clean: Run make clean for all modules. May cause unexpected side effects, see Modules page.
utilites: Build everything in utils/.
install: Same as make install.perl install.man.
install.perl: Install perl and all the modules.
install.man: Install manual pages.
test: Run perl test suite from t/
testpack: Build testpack for on-target testing. See Testing page.
clean: Try to clean up the source tree. Does not always work as expected.

For most generated files, make file should be enough to rebuild file.