=head1 NAME

makepp_compatibility -- Compatibility list for makepp

=for vc $Id: makepp_compatibility.pod,v 1.44 2017/08/06 21:19:20 pfeiffer Exp $

=head1 DESCRIPTION

=head2 Perl Version vs. System

The many Perl versions available and still installed on many machines come
with various subtle bugs.  We have tried to work around most of them, but a
few remain.  We have a test suite of around 95 tests, all of which usually
pass.  On some platforms lacking some features, notably Cygwin, a few tests
are explicitly skipped.  This table shows with what version this has been
tested where, and whether it was successful.  We would like to hear of your
results on other platforms too!

Note that you get a comparable overview when going to the top right CPAN tab
and choosing Perl/Platform Version Matrix
(L<http://matrix.cpantesters.org/?dist=makepp>).  But they give a red bar even
if only one out of about hundred tests fail.  And since those test are
automated on screened off machines, it can be hard to find out or even fix
what is going wrong.  Often it is something that could be worked around, like
compiler, operating or file system particularities or wrong environment
variables.

=for html
<ul>
<li>successful: <b class="good">&nbsp;x&nbsp;</b></li>
<li>mostly successful with footnote: <b class="soso">&nbsp;x<sup>*)</sup></b></li>
<li>failed: <b class="bad">&nbsp;<i>/</i>&nbsp;</b></li>
<li>Click the navigation side bar's close button (&#xd7;) to have more space for the table!</li>
</ul>
<div class='compatibility'>
<table cellspacing="3" cellpadding="3">

=for comment
The following table, where each table row must be separated by an empty line,
has the structure " OS#x|x|x#x|x|...#".  Here 'x' means success, '/' means
failure, empty means not tested, and anything else is a footnote link to the
list below.  The first two lines are special, based on the OS field being
empty.  This is converted to html by install.pl and readable as is in other
formats.

		#|||||||||			5.8						#|	5.10	#||||		5.12			#|| 5.14		#|||	 5.16			#||	5.18		# 5.20	#||| 5.22			#|| 5.24		# 5.26	#

		# .0	| .1	| .2	| .3	| .4	| .5	| .6	| .7	| .8	| .9	# .0	| .1	# .0	| .1	| .2	| .3	| .4	# .0	| .1	| .2	# .0	| .1	| .2	| .3	# .0	| .1	| .2	# .0	# .0	| .1	| .2	| .3	# .0	| .1	| .2	# .0	#

 GNU/Linux (x86)# x	| x	| x	| x	| x	|	| x	| x	| x	| x	# x	| x	# x	| x	| x	| x	| x	# x	| x	| x	# x	| x	| x	| x	# x	| x	|	# x	# x	| x	| x	| x	# x	| x	| x	# x	#

 GNU/Linux (amd64)#	|	|	|	|	| x	|	|	|	| x	#	|	#	|	| x	| x	|	# x	|	| x	#	|	| x	| x	#	|	|	#	#	|	|	|	#	|	|	#	#

 GNU/Linux (S/390)#	|	|	|	|	|	|	|	| x	| x	# x	| x	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 FreeBSD (x86)	#	|	|	|	|	|	|	|	| x	| x	# x	| x	# x	| x	| x	| x	|	#	| x	|	#	|	| x	| x	#	| x	| x	# x	#	|	|	|	#	|	|	#	#

 NetBSD (x86)	#	|	|	|	|	|	|	|	|	| x	# x	| x	# x	| x	| x	| x	|	#	| x	| x	#	|	| x	| x	#	| x	|	#	#	|	|	|	#	|	|	#	#

 NetBSD (Alpha)	#	|	|	|	|	|	|	|	|	| x	# x	| x	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 OpenBSD (x86)	# x	|	|	|	|	|	|	|	|	| x	# x	| x	# x	| x	| x	|	| x	# x	| x	| x	# x	| x	| x	|	# x	| x	|	#	#	|	|	|	#	|	|	#	#


 AIX (PPC)	#	| x	| x	|	|	|	|	| x	| x	|	#	|	#	|	|	|	|	#	|	|	#	| x	|	|	#	| x	|	#	#	|	|	|	#	|	|	#	#

 Darwin (x86)	#	|	|	|	|	|	|	|	|	|	#	|	#	| x	|	|	|	#	|	| x	#	|	|	|	#	|	| x	# x	#	|	|	|	#	|	|	#	#

 Darwin (PPC)	#	|	|	|	|	|	| x	| x	| x	| x	# x	| x	# x	| x	| x	|	|	#	|	|	#	|	| x	|	#	| x	|	#	#	|	|	|	#	|	|	#	#

 HP/UX (IA64)	# x	|	|	| x	|	|	|	|	|	|	#	|	#	|	|	|	|	#	|	|	#	|	|	|	#	| x	|	# x	#	|	|	|	#	|	|	#	#

 Irix		#	|	|	|	|	|	|	|	| x	|	#	|	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 Solaris (Sparc)# x	| x	| x	| x	| x	| x	| x	| x	| x	| x	# x	|	# x	| x	|	|	|	#	|	|	# x	| x	|	|	# x	| x	|	# x	#	|	|	|	#	|	|	#	#

 Solaris (64bit)#	| x	|	|	|	|	|	|	| x	|	# x	|	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 Solaris (x86)	#	| x	|	|	|	|	|	|	| x	| x	# x	| x	# x	| x	| x	|	|	#	|	|	#	|	| x	|	#	|	|	#	#	|	|	|	#	|	|	#	#


 BS2000 (S/390)	#	| x	|	|	|	|	|	|	|	|	# /	|	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 z/OS USS (S/390)#	|	|	|	|	|	|	|	| zOS	|	# /	|	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#


 Cygwin (x86)	#	|	|	|	|	|	|	| Win	| x	|	# x	| x	#	|	|	|	|	#	|	| x	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 MinGW MSYS	#	|	|	|	|	|	|	|	| x	|	#	|	#	|	|	|	|	#	|	|	#	|	|	|	#	|	|	#	#	|	|	|	#	|	|	#	#

 Stawberry	#	|	|	|	|	|	|	|	| x	| x	# x	| x	#	| x	| x	| x	|	#	|	| x	# x	| x	| x	| x	# x	|	|	#	#	|	|	|	#	|	|	#	#

 ActiveState Win# x	| x	| x	| x	| x	|	| x	| x	| x	| x	# x	| x	# x	| x	|	| x	|	# x	|	| x	#	| x	|	| x	#	|	|	#	#	|	|	|	#	|	|	#	#

=for html </table>
</div>

=over

=item Win

There are 4 different Perl environments on Windows, which normally extend one
another when installed in parallel.  Here they have been tested with a minimal
PATH, so as to separate them completely.  When using native programs, you may
need to see the note under
L<&ln|makepp_builtins/ln_option_sourcefile_destfile>.

=over

=item *

B<Cygwin> fairly closely emulates GNU/Linux and gives the best results.  Perl
5.8.7 has a small problem with environment vars, making one test fail.  In the
long gone past, parallel builds didn't work, but it hasn't be verified which
version of Cygwin or Perl made them usable.  Perl 5.10.1 has a problem with
chmod 0 files, so they can't be used to prevent repository imports.  In rare
cases recent Cygwin also leads stat() to report a symlink for an inexistent
file.  This does not seem a Perl bug, since the same perls that were error
free before, now show this behaviour.  Makepp has been reorganized to much
reduce this, so you may never see it.

=item *

B<MinGW> stays close to Windows, giving it only a Unixy look and feel.  It has
a clever workaround for lack of symbolic links, namely copying instead (C<&ln>
has stolen this idea).  Alas this is not good enough for the B<repository>
mechanism, so that isn't available, in addition to the Cygwin deficiencies.

=item *

On B<Strawberry> Perl with only native Windows most customary Unix commands
(except GNU compilers) are missing, and the "shell" is extremely primitive.  A
maximal use of makepp's builtin commands and embedded Perl can increase
makefile portability.

While Windows programs can handle normal slashes as directory separators, this
does not work for command names.  Those should always be portably written as
F<dir$/command>, where C<$/> gets replaced by a forward or backward slash,
depending on the environment.  If you tell makepp, via the SHELL variable,
where to find a Unix-like Shell, you don't have these worries.

It cannot do smart recursive makes (but who would want them, since they are
known to be a broken paradigm) and B<parallel> builds.

=item *

B<ActiveState> Perl is very similar to Strawberry, as far as makepp goes,
though it doesn't come with GNU compilers.  Up to Perl 5.8.6, it will
rewrite Mpp/File.pm so as to have a needed workaround for an lstat bug.

=back

=item zOS

On z/OS (alias VMS or OS/390) Unix System Services smart recursive make
doesn't work.  If your compiler is picky about option order, you may have to
write your own rules.  (To compile Perl 5.8.8 you may have to remove the silly
"(void)env;" in miniperlmain.c.  Perl 5.10.0 is not compilable on an Ebcdic
system while 5.12.1 and 5.14.0 may have macro errors with the z/OS C
compiler.)

=item Nest

Some old compilers do not like nested comments.  Since
F<additional_tests/2006_03_23_c_comments.test> looks at all kinds of
constellations, and verifies it's conclusions with the compiler, this test can
fail if you do not use gcc.

=back

=head2 File Systems

Various special file systems have unusual properties, giving makepp a hard
time when working on them:

=over

=item NFS

NFS may reorder file operations at its discretion, leading to unexpected
relationships between time stamps.  This is relevant for the build info
meta-data files, which makepp stores alongside each file.  Especially in build
caches, with their concurrent access, some workaround handling was necessary,
but it is shown by load test to work fine.

=item Windows CIFS on GNU/Linux

A few special characters are not allowed in filenames.  Links are emulated by
copying while symbolic linking fails.  Apparently write operations come back
before they are visible on disk, which confuses makepp about the success of
the commands it executes.  Six out of 76 tests fail due to this.  On the bright
side, timestamps have a precision of 100 nanoseconds (though the observed
obtainable differences are only about a centisecond).  This is much better
than most older Unix file systems -- alas Perl's C<stat> function has no
access to this very welcome precision.

=item Windows Server Share on Cygwin

The same CIFS disk that was works so badly on Linux, passes all tests on
Cygwin.  Possibly there are CIFS mount options that might improve something.

=item Unix SMBFS from GNU/Linux

Linking and symbolic linking fails.  No other tests fail.  I have no access to
a more realistic Windows SMB server, where the situation might be different.

=item VFAT on GNU/Linux

A few special characters are not allowed in filenames.  Linking and symbolic
linking fails.  The file permission mask and owner are mount options, while
the time stamps are not settable.

=item Mixed Case Sensitive & Insensitive File Names

Makepp's file name handling is either fully case sensitive or not, depending
on the directory where it was invoked.  If this directory is case insensitive,
but it is mounted on a path containing upper case letters within the case
sensitive part of the path, then makepp will trip.

If you need this setup to work (e.g. the Windows host is reachable as
F</mnt/hgfs/C> from Linux inside VMware) you will have to design your Makefile
as though you were on a case sensitive file system and C<export
MAKEPP_CASE_SENSITIVE_FILENAMES=1> before you call makepp.

=back

=head1 AUTHOR

Daniel Pfeiffer (occitan@esperanto.org)
