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

(This file has very long lines - die-hard terminal nostalgists can be satisfied by `fmt -s -w 75 < INSTALL | less`. I think it's better to let the reader's preference rule than to preformat the stuff to some arbitrary width.)

There are now two basic ways to get your mpg123 installation consisting of

	a) the mpg123 binary file
	    - with libmpg123 as shared library or statically linked
	    - with audio output plugins, or one statically linked
	b) a man page

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


0. Prerequesites

You really need:

- a C compiler; we try to keep the code ANSI C89/ISO C90 compatible
  gcc from 2.95 on should work, others, too - please report any issues
  Actually, we have a confirmed working build (svn trunk leading to release 0.67) on SunOS 4.1.4 with gcc-2.7.0 .

- an (UNIX-like) operating system with standard tools; MinGW32 and Cygwin are working for Microsoft Windows, too.
- For the library only, you may get lucky with MSVC++ using the project files under ports/
- For other exotic platforms, see ports/

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. New installation via GNU autotools

The GNU 3-step procedure:

	./configure
	make
	make install

Run

	./configure --help

for a list of possible parameters you can specify. 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 on 32bit x86 systems since version 0.66 is a build that combines all possible optimizations and chooses one at runtime (see --cpu, --list-cpu and --test-cpu parameters).

Another possibly important choice is --with-seektable=<number> for setting the size for the table of stored frame addresses to make seeking faster. When you want a minimal memory footprint, you can set number to 0. Seeking will always start from the beginning, then - being accurate, but rather slow, what doesn't matter if you don't use interactive seeking forth and back.

There are various library features you can leave out via --disable options (like output formats, resampling modes). Please note that this is only configured/tested for the generic (fpu) decoder, not optimized ones. Perhaps that changes in future.

1a. 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, depending on your build configuration, the library name will change when large file support is enabled.

Generally, you can use ./configure --disable-large file to force a build with default (small) file support and the resulting library will be called libmpg123 (same for the pkg-config package name).
Auto detection of large file support that can be enabled (via _FILE_OFFSET_BITS) optionally on your platform will result in a build that supports large files and uses the appropriate extended API of the system libc.
Since this build will have a different ABI from the "default" one, the library changes its name to reflect that (on 32 bit systems wiht 64 bit large file support, the library will be called libmpg123_64). To prevent further possible damage by mis-linking, the symbols sensitive to relevant I/O calls get a _64 suffix appended, too.

The mpg123 header uses the value of _FILE_OFFSET_BITS to determine which set of symbols shall be used in a client application -- it is the client build system's responsibility to define _FILE_OFFSET_BITS and link to the correct variant of libmpg123.

Hint: If you want to install both variants of the library, do a main build with support for large files and install that. Then, do a build without large file support and install to some DESTDIR, then only adding the library files (.la, .so, .a) and pkg-config file to the main install.
There is no benefit from installing the non-large-file mpg123 end-user binary.
Also, the header will work for both libs.

Oh, a simpler method might be to just do

./configure --disable-largefile && make && make install
./configure && make && make install

The second build will enable large file support if possible and replace all files from the first install except the library and its pkg-config definition.


2. The classic way via the provided Makefile

No, the Makefile is not provided anymore. Even if autotools is complicated, it is more cumbersome to take care of two build systems in parallel.
You can dig in SVN for MakeLegacy.sh and src/Makefile.legacy and src/config.h.legacy, if you want.

Again, to be clear: There is no classic way anymore.


3. Do something different on a special platform/compiler/...

Look into the ports/ directory for some traces of "porting" mpg123 or usually libmpg123 alone to different systems and compilers.

3a. 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 .


4. Have fun!


These are some remarks from Michael that could still bear some relevance:

 - There is currently no direct audio hardware support for the
   "dec" and "generic" targets.  That means that you have to use
   the "-s" commandline option to write the decoded audio data
   to stdout.

 - On Solaris, use Sun's SparcWorks compiler ("make solaris")
   if at all possible.  It generates faster code than gcc, so
   use gcc only if there's no other way.

 - The macro "htons" causes a compiler warning in httpget.c
   (at least on FreeBSD 2.1.x).  This can be safely ignored.

 - For Solaris 2.4:  append the options "-L/usr/ucblib -lucb"
   at the end of the link command line.  Do this ONLY for
   Solaris 2.4, NOT for Solaris 2.5 or newer versions.

 - The HP-UX port might be broken.  I was able to compile it
   on an HP-UX 9 account, but there were some problems with
   libraries on HP-UX 10.  I'm not an HP expert, but perhaps
   someone else can fix it.
   [note: some people report NO problems also with HP-UX 10]

 - IRIX: some people reported compile problems on IRIX 5.x (5.3)
         but 6.x seems to compile without problems

