PACKAGERS - jrn/xz - Git at Google


 Information to packagers of XZ Utils
 ====================================

     0. Preface
     1. Package naming
     2. Package description
     3. License
     4. configure options
        4.1. Static vs. dynamic linking of liblzma
        4.2. Optimizing xzdec and lzmadec
     5. Additional documentation
     6. Extra files
     7. Installing XZ Utils and LZMA Utils in parallel
     8. Example


 0. Preface
 ----------

     This document is meant for people who create and maintain XZ Utils
     packages for operating system distributions. The focus is on GNU/Linux
     systems, but most things apply to other systems too.

     While the standard "configure && make DESTDIR=$PKG install" should
     give a pretty good package, there are some details which packagers
     may want to tweak.

     Packagers should also read the INSTALL file.


 1. Package naming
 -----------------

     The preferred name for the XZ Utils package is "xz", because that's
     the name of the upstream tarball. Naturally you may have good reasons
     to use some other name; I won't get angry about it. ;-) It's just nice
     to be able to point people to the correct package name without asking
     what distro they have.

     If your distro policy is to split things into small pieces, here is
     one suggestion:

         xz              xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs
         xz-lzma         lzma, unlzma, lzcat, lzgrep etc. symlinks and
                         lzmadec binary for compatibility with LZMA Utils
         liblzma         liblzma.so.*
         liblzma-devel   liblzma.so, liblzma.a, API headers


 2. Package description
 ----------------------

     Here is a suggestion which you may use as the package description.
     If you can use only one-line description, pick only the first line.
     Naturally, feel free to use some other description if you find it
     better, and maybe send it to me too.

         Library and command line tools for XZ and LZMA compressed files

         XZ Utils provide a general purpose data compression library
         and command line tools. The native file format is the .xz
         format, but also the legacy .lzma format is supported. The .xz
         format supports multiple compression algorithms, of which LZMA2
         is currently the primary algorithm. With typical files, XZ Utils
         create about 30 % smaller files than gzip.

     If you are splitting XZ Utils into multiple packages, here are some
     suggestions for package descriptions:

     xz:

         Command line tools for XZ and LZMA compressed files

         This package includes the xz compression tool and other command
         line tools from XZ Utils. xz has command line syntax similar to
         that of gzip. The native file format is the .xz format, but also
         the legacy .lzma format is supported. The .xz format supports
         multiple compression algorithms, of which LZMA2 is currently the
         primary algorithm. With typical files, XZ Utils create about 30 %
         smaller files than gzip.

         Note that this package doesn't include the files needed for
         LZMA Utils 4.32.x compatibility. Install also the xz-lzma
         package to make XZ Utils emulate LZMA Utils 4.32.x.

     xz-lzma:

         LZMA Utils emulation with XZ Utils

         This package includes executables and symlinks to make
         XZ Utils emulate lzma, unlzma, lzcat, and other command
         line tools found from the legacy LZMA Utils 4.32.x package.

     liblzma:

         Library for XZ and LZMA compressed files

         liblzma is a general purpose data compression library with
         an API similar to that of zlib. liblzma supports multiple
         algorithms, of which LZMA2 is currently the primary algorithm.
         The native file format is .xz, but also the legacy .lzma
         format and raw streams (no headers at all) are supported.

         This package includes the shared library.

     liblzma-devel:

         Library for XZ and LZMA compressed files

         This package includes the API headers, static library, and
         other development files related to liblzma.


 3. License
 ----------

     If the package manager supports a license field, you probably should
     put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
     XZ Utils are in the public domain, but some less important files
     ending up into the binary package are under GPLv2+. So it is simplest
     to just say GPLv2+ if you cannot specify "public domain and GPLv2+".

     If you split XZ Utils into multiple packages as described earlier
     in this file, liblzma and liblzma-dev packages will contain only
     public domain code (from XZ Utils at least; compiler or linker may
     add some third-party code, which may be copyrighted).


 4. configure options
 --------------------

     Unless you are building a package for a distribution that is meant
     only for embedded systems, don't use the following configure options:

         --enable-debug
         --enable-encoders (*)
         --enable-decoders
         --enable-match-finders
         --enable-checks
         --enable-small (*)
         --disable-threads (*)

     (*) These are OK when building xzdec and lzmadec as explained later.

     You may use --enable-werror but be careful with it since it may break
     the build due to some useless warning when the build environment
     changes (like CPU architecture or compiler version).


 4.1. Static vs. dynamic linking of liblzma

     The default is to link the most important command line tools against
     static liblzma, and the less important tools against shared liblzma.
     This can be changed by passing --enable-dynamic to configure, or by
     not building static libraries at all by passing --disable-static
     to configure. It is mildly recommended that you use the default, but
     the configure options make it easy to do otherwise if the distro policy
     so requires.

     On 32-bit x86, linking against static liblzma can give a minor
     speed improvement. Static libraries on x86 are usually compiled as
     position-dependent code (non-PIC) and shared libraries are built as
     position-independent code (PIC). PIC wastes one register, which can
     make the code slightly slower compared to a non-PIC version. (Note
     that this doesn't apply to x86-64.)

     Linking against static liblzma avoids a dependency on liblzma shared
     library, and makes it slightly easier to copy the command line tools
     between systems (e.g. quick 'n' dirty emergency recovery of some
     files). It also allows putting the command line tools to /bin while
     leaving liblzma to /usr/lib (assuming that your distribution uses
     such a file system hierarchy), if no other file in /bin would require
     liblzma.

     If you don't want to distribute static libraries but you still
     want to link the command line tools against static liblzma, it is
     probably easiest to build both static and shared liblzma, but after
     "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la
     to not contain a reference to liblzma.a.


 4.2. Optimizing xzdec and lzmadec

     xzdec and lzmadec are intended to be relatively small instead of
     optimizing for the best speed. Thus, it is a good idea to build
     xzdec and lzmadec separately:

       - Only decoder code is needed, so you can speed up the build
         slightly by passing --disable-encoders to configure. This
         shouldn't affect the final size of the executables though,
         because the linker is able to omit the encoder code anyway.

       - xzdec and lzmadec will never use multithreading capabilities of
         liblzma. You can avoid dependency on libpthread by passing
         --disable-threads to configure.

       - There are and will be no translated messages for xzdec and
         lzmadec, so it is fine to pass also --disable-nls to configure.

       - To select somewhat size-optimized variant of some things in
         liblzma, pass --enable-small to configure.

       - Tell the compiler to optimize for size instead of speed.
         E.g. with GCC, put -Os into CFLAGS.


 5. Additional documentation
 ---------------------------

     "make install" copies some additional documentation to $docdir
     (--docdir in configure). These a copy of the GNU GPL v2, which can
     be replaced with a symlink if your distro ships with shared copies
     of the common license texts.


 6. Extra files
 --------------

     The "extra" directory contains some small extra tools or other files.
     The exact set of extra files can vary between XZ Utils releases. The
     extra files have only limited use or they are too dangerous to be
     put directly to $bindir (7z2lzma.sh is a good example, since it can
     silently create corrupt output if certain conditions are not met).

     If you feel like it, you may copy the extra directory under the doc
     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
     them useful. However, most people needing these tools probably are
     able to find them from the source package too.

     The "debug" directory contains some tools that are useful only when
     hacking on XZ Utils. Don't package these tools.


 7. Installing XZ Utils and LZMA Utils in parallel
 -------------------------------------------------

     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
     from the XZ Utils package. It's probably a good idea to still package
     the symlinks into a separate package so that users may choose if they
     want to use XZ Utils or LZMA Utils for handling .lzma files.


 8. Example
 ----------

     Here is an example for i686 GNU/Linux that
       - links xz against static liblzma;
       - includes only shared liblzma in the final package;
       - links xzdec and lzmadec against static liblzma while
         avoiding libpthread dependency.

     PKG=/tmp/xz-pkg
     tar xf xz-x.y.z.tar.gz
     cd xz-x.y.z
     ./configure \
             --prefix=/usr \
             --sysconfdir=/etc \
             CFLAGS='-march=i686 -O2'
     make
     make DESTDIR=$PKG install-strip
     rm -f $PKG/usr/lib/lib*.a
     sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la
     make clean
     ./configure \
             --prefix=/usr \
             --sysconfdir=/etc \
             --disable-shared \
             --disable-nls \
             --disable-encoders \
             --enable-small \
             --disable-threads \
             CFLAGS='-march=i686 -Os'
     make -C src/liblzma
     make -C src/xzdec
     make -C src/xzdec DESTDIR=$PKG install-strip
     cp -a extra $PKG/usr/share/doc/xz

	Information to packagers of XZ Utils
	====================================

	0. Preface
	1. Package naming
	2. Package description
	3. License
	4. configure options
	4.1. Static vs. dynamic linking of liblzma
	4.2. Optimizing xzdec and lzmadec
	5. Additional documentation
	6. Extra files
	7. Installing XZ Utils and LZMA Utils in parallel
	8. Example


	0. Preface
	----------

	This document is meant for people who create and maintain XZ Utils
	packages for operating system distributions. The focus is on GNU/Linux
	systems, but most things apply to other systems too.

	While the standard "configure && make DESTDIR=$PKG install" should
	give a pretty good package, there are some details which packagers
	may want to tweak.

	Packagers should also read the INSTALL file.


	1. Package naming
	-----------------

	The preferred name for the XZ Utils package is "xz", because that's
	the name of the upstream tarball. Naturally you may have good reasons
	to use some other name; I won't get angry about it. ;-) It's just nice
	to be able to point people to the correct package name without asking
	what distro they have.

	If your distro policy is to split things into small pieces, here is
	one suggestion:

	xz xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs
	xz-lzma lzma, unlzma, lzcat, lzgrep etc. symlinks and
	lzmadec binary for compatibility with LZMA Utils
	liblzma liblzma.so.*
	liblzma-devel liblzma.so, liblzma.a, API headers


	2. Package description
	----------------------

	Here is a suggestion which you may use as the package description.
	If you can use only one-line description, pick only the first line.
	Naturally, feel free to use some other description if you find it
	better, and maybe send it to me too.

	Library and command line tools for XZ and LZMA compressed files

	XZ Utils provide a general purpose data compression library
	and command line tools. The native file format is the .xz
	format, but also the legacy .lzma format is supported. The .xz
	format supports multiple compression algorithms, of which LZMA2
	is currently the primary algorithm. With typical files, XZ Utils
	create about 30 % smaller files than gzip.

	If you are splitting XZ Utils into multiple packages, here are some
	suggestions for package descriptions:

	xz:

	Command line tools for XZ and LZMA compressed files

	This package includes the xz compression tool and other command
	line tools from XZ Utils. xz has command line syntax similar to
	that of gzip. The native file format is the .xz format, but also
	the legacy .lzma format is supported. The .xz format supports
	multiple compression algorithms, of which LZMA2 is currently the
	primary algorithm. With typical files, XZ Utils create about 30 %
	smaller files than gzip.

	Note that this package doesn't include the files needed for
	LZMA Utils 4.32.x compatibility. Install also the xz-lzma
	package to make XZ Utils emulate LZMA Utils 4.32.x.

	xz-lzma:

	LZMA Utils emulation with XZ Utils

	This package includes executables and symlinks to make
	XZ Utils emulate lzma, unlzma, lzcat, and other command
	line tools found from the legacy LZMA Utils 4.32.x package.

	liblzma:

	Library for XZ and LZMA compressed files

	liblzma is a general purpose data compression library with
	an API similar to that of zlib. liblzma supports multiple
	algorithms, of which LZMA2 is currently the primary algorithm.
	The native file format is .xz, but also the legacy .lzma
	format and raw streams (no headers at all) are supported.

	This package includes the shared library.

	liblzma-devel:

	Library for XZ and LZMA compressed files

	This package includes the API headers, static library, and
	other development files related to liblzma.


	3. License
	----------

	If the package manager supports a license field, you probably should
	put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
	XZ Utils are in the public domain, but some less important files
	ending up into the binary package are under GPLv2+. So it is simplest
	to just say GPLv2+ if you cannot specify "public domain and GPLv2+".

	If you split XZ Utils into multiple packages as described earlier
	in this file, liblzma and liblzma-dev packages will contain only
	public domain code (from XZ Utils at least; compiler or linker may
	add some third-party code, which may be copyrighted).


	4. configure options
	--------------------

	Unless you are building a package for a distribution that is meant
	only for embedded systems, don't use the following configure options:

	--enable-debug
	--enable-encoders (*)
	--enable-decoders
	--enable-match-finders
	--enable-checks
	--enable-small (*)
	--disable-threads (*)

	(*) These are OK when building xzdec and lzmadec as explained later.

	You may use --enable-werror but be careful with it since it may break
	the build due to some useless warning when the build environment
	changes (like CPU architecture or compiler version).


	4.1. Static vs. dynamic linking of liblzma

	The default is to link the most important command line tools against
	static liblzma, and the less important tools against shared liblzma.
	This can be changed by passing --enable-dynamic to configure, or by
	not building static libraries at all by passing --disable-static
	to configure. It is mildly recommended that you use the default, but
	the configure options make it easy to do otherwise if the distro policy
	so requires.

	On 32-bit x86, linking against static liblzma can give a minor
	speed improvement. Static libraries on x86 are usually compiled as
	position-dependent code (non-PIC) and shared libraries are built as
	position-independent code (PIC). PIC wastes one register, which can
	make the code slightly slower compared to a non-PIC version. (Note
	that this doesn't apply to x86-64.)

	Linking against static liblzma avoids a dependency on liblzma shared
	library, and makes it slightly easier to copy the command line tools
	between systems (e.g. quick 'n' dirty emergency recovery of some
	files). It also allows putting the command line tools to /bin while
	leaving liblzma to /usr/lib (assuming that your distribution uses
	such a file system hierarchy), if no other file in /bin would require
	liblzma.

	If you don't want to distribute static libraries but you still
	want to link the command line tools against static liblzma, it is
	probably easiest to build both static and shared liblzma, but after
	"make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la
	to not contain a reference to liblzma.a.


	4.2. Optimizing xzdec and lzmadec

	xzdec and lzmadec are intended to be relatively small instead of
	optimizing for the best speed. Thus, it is a good idea to build
	xzdec and lzmadec separately:

	- Only decoder code is needed, so you can speed up the build
	slightly by passing --disable-encoders to configure. This
	shouldn't affect the final size of the executables though,
	because the linker is able to omit the encoder code anyway.

	- xzdec and lzmadec will never use multithreading capabilities of
	liblzma. You can avoid dependency on libpthread by passing
	--disable-threads to configure.

	- There are and will be no translated messages for xzdec and
	lzmadec, so it is fine to pass also --disable-nls to configure.

	- To select somewhat size-optimized variant of some things in
	liblzma, pass --enable-small to configure.

	- Tell the compiler to optimize for size instead of speed.
	E.g. with GCC, put -Os into CFLAGS.


	5. Additional documentation
	---------------------------

	"make install" copies some additional documentation to $docdir
	(--docdir in configure). These a copy of the GNU GPL v2, which can
	be replaced with a symlink if your distro ships with shared copies
	of the common license texts.


	6. Extra files
	--------------

	The "extra" directory contains some small extra tools or other files.
	The exact set of extra files can vary between XZ Utils releases. The
	extra files have only limited use or they are too dangerous to be
	put directly to $bindir (7z2lzma.sh is a good example, since it can
	silently create corrupt output if certain conditions are not met).

	If you feel like it, you may copy the extra directory under the doc
	directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
	them useful. However, most people needing these tools probably are
	able to find them from the source package too.

	The "debug" directory contains some tools that are useful only when
	hacking on XZ Utils. Don't package these tools.


	7. Installing XZ Utils and LZMA Utils in parallel
	-------------------------------------------------

	XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
	omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
	from the XZ Utils package. It's probably a good idea to still package
	the symlinks into a separate package so that users may choose if they
	want to use XZ Utils or LZMA Utils for handling .lzma files.


	8. Example
	----------

	Here is an example for i686 GNU/Linux that
	- links xz against static liblzma;
	- includes only shared liblzma in the final package;
	- links xzdec and lzmadec against static liblzma while
	avoiding libpthread dependency.

	PKG=/tmp/xz-pkg
	tar xf xz-x.y.z.tar.gz
	cd xz-x.y.z
	./configure \
	--prefix=/usr \
	--sysconfdir=/etc \
	CFLAGS='-march=i686 -O2'
	make
	make DESTDIR=$PKG install-strip
	rm -f $PKG/usr/lib/lib*.a
	sed -i "s/^old_library=.$/old_library=''/" $PKG/usr/lib/lib.la
	make clean
	./configure \
	--prefix=/usr \
	--sysconfdir=/etc \
	--disable-shared \
	--disable-nls \
	--disable-encoders \
	--enable-small \
	--disable-threads \
	CFLAGS='-march=i686 -Os'
	make -C src/liblzma
	make -C src/xzdec
	make -C src/xzdec DESTDIR=$PKG install-strip
	cp -a extra $PKG/usr/share/doc/xz