[ST-devel] Patches to 1.3c to produce rpm/debs

[Wesley W. T. <ter...@te...>]

On Fri, Jan 04, 2002 at 07:21:37PM -0800, Gene Shekhtman wrote:
> +case "$sys_info" in
> +  *-ibm-aix4*     ) OS=AIX        ;;
> +  *-freebsd*      ) OS=FREEBSD    ;;
> +  hppa*-hp-hpux11*) OS=HPUX       ;;
> +  *-sgi-irix6*    ) OS=IRIX       ;;
> +  ia64-*-linux*   ) OS=LINUX_IA64 ;;
> +  *-linux*        ) OS=LINUX      ;;
> +  *-openbsd*      ) OS=OPENBSD    ;;
> +  *-dec-osf*      ) OS=OSF1       ;;
> +  *-solaris2*     ) OS=SOLARIS    ;;
> +  *               ) OS=
> +                    echo "Sorry, unsupported OS"
> +                    exit 1        ;;
> +esac

Are you sure this case statement will work? In my own patch this was the
part that worried me the most.

Anyways, since you're the upstream maintainer and I but a lowly contributor,
I've decided to abandon my first packaging attempt and build my next off of
this patch.

This email is quite long, but it's because I explain why I made the changes
to the Makefile I had to make. These changes should be merged upstream even
if the packaging files are not; they constitute bugs at present.

---

Problem 1:

The libraries built right now are not relocatable. I'm not entirely sure
what this does, but from packaging libraries before I know that it is
supposed to be done. :-) 

I believe it has something to do with being able to share the library in
memory: if it's not relocatable you have to modify the addresses at load
time for each program that needs the library and so it can't be shared. A
relocatable library looks at some register for this modification and thus it
doesn't need to be modified and can be shared by all programs. I could be
wrong however; like I said, I don't know exactly what it does. :-)

Anyways, of the things I know for sure: -fPIC -fpic turn it on, relocatable
libraries are slightly larger than normal, it is supposed to be done for .so
libraries and not for .a libraries, and libtool does it.

Unfortunately, this means you have to compile the library objects twice.

I believe this is also true for FreeBSD and OpenBSD so I've changed them as
well. I'm fairly positive that something similar exists for the other
platforms, but I don't know what it is. This is why I advocated libtool
earlier: it knows all about these issues and correctly deals with them.

I've attached a patch that fixes it for those platforms I know about - it is
incremental to your Makefile changes above. (libst-1.3-fpic.patch)

Problem 2:

Also, under linux/bsd systems (and unixs in general I believe), it is common
practice to adopt the following library versioning system:
	libst.so.x.y.z
	libst.so.x -> libst.so.x.y.z
	libst.so -> libst.so.x.y.z
	a soname of libst.so.x

Here is an example situtation:
	libst.so.1.3.1	(soname libst.so.1)
	libst.so.0.6.2	(soname libst.so.0)
	libst.so.1 -> libst.1.3.1
	libst.so.0 -> libst.0.6.2
	libst.so -> libst.1.3.1

	st.h (v1.3.1)

** NOTE: x.y.z in some situations does not match the package version.
This is because there are restrictions x.y.z must obey and package versions
sometimes mean things like: x=rewrite, y=major change, z=bug fix. For a
small library like libst, it would make more sense to keep the two in sync.
Hence, I strongly advocate applying the restrictions to x.y.z to the libst
version in general. My patch assumes that this is what is being done
(x.y.z=1.3.0).

These are the constraints that apply:
1	The version of the header and libst.so symlink should match
2	The soname of a library should be libst.so.x
3	The actual binary should use the full version information
4	Each version of the API that removes features or otherwise breaks
compatability requires x++
5	Each change to the API that adds features requires y++
6	Each bug fix / optimization requires z++
7	The libst.so.x link should point to the newest libst.so.x.y.z
available.

The reason for this setup is:
	When compiling with '#include <st.h>' and -lst, a matching pair of
the library and header are used [1]. The program will also remember what
library version it needs for later [2].
	The sysadmin knows exactly at a glance which version of the library
is which and what programs are using (by looking at libst.so.x -> ?) [3]
	Any program that was compiled against a given interface will
continue to work if that library is present. Even the removal of a library
feature or change to a functions API will not break the program since the
library maintainer will have increased x++ [4]. Hence, the new library can
coexist with the old (which the program needs). (as in example above)
	When a library is upgraded due to bugfix or feature add only,
programs linked against it will benefit from the new version. [5,6,7]

One of the nice things about libtool is that it will check at runtime that
*y* is sufficiently large for an application as well. That is, the dynamic
loader already makes sure to use the right *x* (no features removed), but
libtool ensures that the program has all the new features it needs (y).

However, this problem (version check y) can for the most part be ignored.
Any decent packaging format (rpm/deb) will automatically deal with it. For
example: 'foo' depends on libst1 (>= 1.3.2) ensures that the feature
requirement y>=3 is met.

Note: libst1 vs. libst0 as packages make sure that the libraries can coexist
in the package management tool. However, libst-dev can only be installed
once, and it include libst.so -> ? and st.h that match.

Presently libst violates constraints: 2, 3, 7 and by omision 4,5,6
For 4,5,6 this is simply a versioning policy it's easy to adopt and adhere
to.

A common problem with packaging libraries is that the upstream maintainer is
not aware of these constraints on versioning. Then the packager gets in
trouble when his package breaks the distribution. This is a problem if, say,
the libdb upstream maintainers removed or changed a feature from 3.0.2 ->
3.1.0. Suddenly every program linked to libdb.so.3 is broken on the system!
(don't laugh, this happens!) 

libst probably hasn't had to worry about this yet because it's not widely
used as a shared library by vital system tools. However, we want to change
that right? :-) So we have to play by the rules.

Here's my patch that address 2,3,7. The upstream maintainers will just have
to be careful to follow 4,5,6 and all will be well.

(libst-1.3-version.patch) is incremental on libst-1.3-fpic.patch

One caveat: I added -lc to the link line so that package tools detect that
it depends on libc (which it does).

--

Finally! Now libst is able to be properly packaged. Here is a patch that
adds those files to build it as a deb and rpm. Not sure if you want this in
the upstream version or not... Sometimes it's nice, but it's not crucial.

(libst-1.3-packaged.patch) is incremental on libst-1.3-version.patch

As before:
	cd st-1.3c; debuild -> makes debs
	rpm -ta st-1.3c.tar.gz -> makes rpms

--

Summary:
	Patches libst-1.3-(fpic&version).patch should be applied to the tree
after the patch you already made. (they are bug fixes)
	The versioning policy constraints 4,5,6 should be adhered to.
	libst-1.3-packaged.patch may be optionally applied.

A tarball with all the patches applied is at:
<http://www.pez.ca/terpstra/st-1.3.0.tar.gz>

-- 
Wesley W. Terpstra <we...@te...>