looper/subprojects/mpg123/INSTALL

mpg123 install hints
--------------------

0. Prerequesites

You really need:

- a C99 compiler (moderate C99 support)

- an (UNIX-like) operating system with standard tools; MinGW32 and
  Cygwin are working for Microsoft Windows, too. We also have users happily
  on OS/2.

- For the library only, you may get lucky with MSVC++ using CMake and
  ports/cmake as source directory. You can also use CMake on other
  platforms for a full build, but its main purpose is for portability
  where autotools don't do the trick.

- For other exotic platforms, also see ports/

- If building from direct source code repository checkout, as opposed to
  a release or snapshot tarball, you need GNU autotools installed
  (see Developer Build below).

You want:

- working assembler (recent GNU binutils) if using certain CPU
  optimizations

- headers and lib for certain audio output drivers (libasound for alsa,
  sdl for sdl...)

1. Build

There is one main supported way to get your mpg123 installation
consisting of

a) the mpg123, mpg123-strip, mpg123-id3dump, out123 program binaries
  - with libmpg123, libout123, and libsyn123 as shared libraries or
    statically linked
  - with audio output plugins for libout123, or one statically linked

b) man pages

(you may want to copy some of the documentation - README, etc - to
/usr/share/doc/mpg123 or the like, too)

This way is the usual GNU 3-step procedure:

	./configure
	make
	make install

Run

	./configure --help

for a list of possible parameters you can specify in the configuration
step. The obvious are --prefix and the normal GNU autotool bunch, but
others include what audio subsystem to use and what CPU optimizations
to build in.
For the optimizations (decoder choice), the default is a build that
combines all usable optimizations for the platform and chooses one at
runtime (see --cpu, --list-cpu and --test-cpu parameters).

There are various parameters you can tune, but of course the defaults
are what is mainly tested.

Also, various library features can be left out via --disable options
(like output formats, resampling modes). That way, you can strive for a
minimal build that only does what you really need. Not every combination
of library features is tested regularily, so you might hit some speed
bumps, but usually stuff that is easily worked out (at least for the
mpg123 team when you report it).

An example (working on mpg123 trunk r3062):

	CFLAGS="-Os -s" ./configure --with-cpu=generic	--disable-id3v2
	--disable-lfs-alias --disable-feature-report --with-seektable=0
	--disable-16bit --disable-32bit --disable-8bit --disable-messages
	--disable-feeder --disable-ntom --disable-downsample --disable-icy
	&& make

That, and further application of `strip --strip-unneeded`, yields a lean
93 KiB shared library for MPEG layer I/II/III decoding to floating point
on my x86-64 system (it should be a bit smaller on 32 bit systems). When
disabling layers I and II, too, that goes down to 81 KiB.

The shared library of a full build weighs 170 KiB after stripping.


2. Developer build

This project uses GNU autotools (no specific version, but they should
be fairly recent), also libtool. You need to have those installed, as
it is usually the case for build environments based on the GNU toolchain.

One a fresh SCM checkout, or after changing things in configure.ac,
you need to run

	autoreconf -iv

to prepare the configure script. Then you can build as per point 1.


3. Library-only build

Mpg123 uses a non-recursive build. If you want to build only one of the
libraries, specify it as a target:

	./configure
	make src/libmpg123/libmpg123.la
	make src/libsyn123/libsyn123.la
	make src/libout123/libout123.la

You can then find the library itself under src/lib*123/.libs (libtool
likes to hide things there).


4. Exotic platforms

See the ports/ directory for some help for building at least libmpg123
without the UNIX shell / autotools. The main strategy is to write
a config.h to replace what configure would generate and then have a
correct listing of all source files involved in that configuration
(there are optional files for different decoder choices, for example).

Then compile objects, link.

Instead of manually curated MSVC project files, there is a CMake port
now in ports/cmake to build mpg123 with the MS compilers. It might be
helpful for other platforms, too. But the main build system for
POSIX-like systems is the autotools one.


4a. Preparing Win32 binary packages.

Caution: You should make sure to use some gcc >= 4.2.0, even if it's
still the experimental package for MinGW32.
This helps preventing incompatibilities between generated DLL files and
other compilers (it's about stack alignment).

Get MinGW/MSYS installed, run the MSYS shell.
Enter the mpg123 source directory.
Execute sh ./windows-builds.sh .

After some time, you should have some relevant files under releases/
(or releases\, for Windows people;-).
You don't just get one build -- there are several variants, corresponding
to what usually is to be found under http://mpg123.org/download/win32 .


5. Note on large file support

The libmpg123 API includes the generic off_t type for file offsets and
thus is subject to shape-shifting on systems that change off_t depending
on build flags.
To deal with the incompatibilities that can cause, the library needs to
separate code paths for small and large off_t.
Since version 1.12.0, a large-file-enabled libmpg123 (the default set
by configure) provides a dual-mode ABI. Depending on _FILE_OFFSET_BITS,
the mpg123.h header file selects different library symbols to use for
your app.
In both large-file and normal mode, the library should just work for
your app.

6. Security

If you consider installing the mpg123 binary or any program using
libout123 as suid root, please don't. Apart from evaluating MPG123_MODDIR
from the environment and thus possibly loading any code, the purpose of
libout123 is to write audio data to somewhere. That includes writing raw
data to files. Any files you specify to the program. You do not install
dd or gzip suid root, do you?

Programs using libmpg123 should be fine, as that one does not load runtime
modules and also only has code to read files, not write them. Still,
if your task involves decoding random MPEG audio files from anywhere,
it is only sensible to limit the damage of a possible bug triggered by
certain crafted files. This is not specific to libmpg123 but generally
a good idea working with data from untrusted sources.