From 60895a127ef4a41e7f9730b3194a6cababadd03a Mon Sep 17 00:00:00 2001 From: Jonas 'Sortie' Termansen Date: Sun, 22 Jun 2014 23:59:06 +0200 Subject: [PATCH] Add doc/portability-sins. --- doc/portability-sins | 85 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 doc/portability-sins diff --git a/doc/portability-sins b/doc/portability-sins new file mode 100644 index 00000000..9a982967 --- /dev/null +++ b/doc/portability-sins @@ -0,0 +1,85 @@ +Portability Sins +================ + +Sortix makes use of third-party software. In many cases porting software and +integrating it into the Sortix ports is a fairly smooth ride. Unfortunately, +this is not always the case if the package is flawed. Such mistakes are usually +not intentional, but are simply accidents, rarely tested code cases or simply +the upstream being unaware of portability issues. We should identify such issues +and report them to the upstream projects. + +This is a list of common problems that cause problems when integrating packages +into the Sortix ports build system. Almost all the issues listed here will tend +to get patched in Sortix as we want good ports, not fragile ports that we would +need all sorts of tricks to work around. + +TODO: Potentially merge with cross-compilation-sins as a package-sins guide. + +Cross-compilation issues +------------------------ + +See doc/cross-compilation-sins as well. + +Don't be different for the sake of it +------------------------------------- + +Pay respect to the traditions unless you are strictly better. + +distclean is what goes into a release +------------------------------------- + +When finishing it's useful to be able to reset the source tree to the state that +you got it in (i.e. no temporary build files left behind) so you can easily diff +it against the upstream tarball. Packages usually have a makefile target called +distclean that cleans the source directory for distribution, ideal for such +purposes. However, in some packages the distclean target doesn't actually do +that: It occasionally deletes files present in the upstream tarball while +leaving other files behind that wasn't in the upstream tarball. This is pretty +annoying. It makes the Sortix patches for a port harder to read as they are +filled with noise (generated XML files are fun), unless manual care is taken. + +The ideal is that you can extract a tarball and run configure, make and finally +make distclean. The source directory should then be equal to what is in the +tarball. Otherwise the actual distribution wasn't actually distribution-clean. + +Fun examples: Deleting the configure script upon distclean, deleting the license +files upon distclean, calling the target dist-clean instead of distclean. + +DESTDIR comes from the environment +---------------------------------- + +It comes from the environment. + +Use setenv instead of putenv +---------------------------- + +Use the system malloc + +Print system types in a portable manner +--------------------------------------- + +Use the proper casts and large types or Sortix extensions. + +64-bit and JIT +-------------- + +Don't assume that mmap() always returns below 4 GiB and that the distance +between any two memory mappings are always less than 2 GiB. There are no such +guarantees on 64-bit systems, yet many just-in-time virtual machines assumes +this is true and truncate pointers if it is not (leading to obscure crashes). + +Don't use seemingly-unused bits in types +---------------------------------------- + +For instance, on x86-64 the address space is currently actually only 48-bit +and the most significant 16-bits must always equal the 47th bit. Some see this +as 16-bit perfectly usable bits for their own purposes. Don't do this, it's +crazy and you know it. This often comes up in more subtle cases such as telldir +that returns an opaque value that might have any bits set, but usually doesn't, +which looks like bits that can be re-purposed. That is, until the system changes +a bit and the package explodes. + +Don't do crazy stuff +-------------------- + +Just don't.