86 lines
3.5 KiB
Plaintext
86 lines
3.5 KiB
Plaintext
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.
|