Blame INSTALL

Packit c32a2d
mpg123 install hints
Packit c32a2d
--------------------
Packit c32a2d
Packit c32a2d
(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.)
Packit c32a2d
Packit c32a2d
Packit c32a2d
0. Prerequesites
Packit c32a2d
Packit c32a2d
You really need:
Packit c32a2d
Packit c32a2d
- a C compiler; we try to keep the code ANSI C89/ISO C90 compatible
Packit c32a2d
  gcc from 2.95 on should work, others, too - please report any issues
Packit c32a2d
  Actually, we have a confirmed working build (svn trunk leading to release 0.67) on SunOS 4.1.4 with gcc-2.7.0 .
Packit c32a2d
Packit c32a2d
- 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.
Packit c32a2d
- For the library only, you may get lucky with MSVC++ using the project files under ports/
Packit c32a2d
- For other exotic platforms, also see ports/
Packit c32a2d
- If building from direct SCM checkout, you need GNU autotools installed (see below).
Packit c32a2d
Packit c32a2d
You want:
Packit c32a2d
Packit c32a2d
- working assembler (recent GNU binutils) if using certain CPU optimizations
Packit c32a2d
- headers and lib for certain audio output drivers (libasound for alsa, sdl for sdl...)
Packit c32a2d
Packit c32a2d
1. Build
Packit c32a2d
Packit c32a2d
There is one main supported way to get your mpg123 installation consisting of
Packit c32a2d
Packit c32a2d
	a) the mpg123 binary file
Packit c32a2d
	    - with libmpg123 as shared library or statically linked
Packit c32a2d
	    - with audio output plugins, or one statically linked
Packit c32a2d
	b) a man page
Packit c32a2d
Packit c32a2d
(you may want to copy some of the documentation - README, etc - to /usr/share/doc/mpg123 or the like, too)
Packit c32a2d
Packit c32a2d
This way is the usual GNU 3-step procedure:
Packit c32a2d
Packit c32a2d
	./configure
Packit c32a2d
	make
Packit c32a2d
	make install
Packit c32a2d
Packit c32a2d
Run
Packit c32a2d
Packit c32a2d
	./configure --help
Packit c32a2d
Packit c32a2d
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.
Packit c32a2d
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).
Packit c32a2d
Packit c32a2d
There are various parameters you can tune, but of course the defaults are what is mainly tested.
Packit c32a2d
Packit c32a2d
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).
Packit c32a2d
Packit c32a2d
An example (working on mpg123 trunk r3062):
Packit c32a2d
Packit c32a2d
	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
Packit c32a2d
Packit c32a2d
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.
Packit c32a2d
Packit c32a2d
The shared library of a full build weighs 170 KiB after stripping.
Packit c32a2d
Packit c32a2d
Packit c32a2d
2. Developer build
Packit c32a2d
Packit c32a2d
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.
Packit c32a2d
Packit c32a2d
One a fresh SCM checkout, or after changing things in configure.ac, you need to run
Packit c32a2d
Packit c32a2d
	autoreconf -iv
Packit c32a2d
Packit c32a2d
to prepare the configure script. Then you can build as per point 1.
Packit c32a2d
Packit c32a2d
Packit c32a2d
3. Library-only build
Packit c32a2d
Packit c32a2d
If you do not want to build the whole thing, but only the library, run
Packit c32a2d
Packit c32a2d
	./configure
Packit c32a2d
	cd src/libmpg123
Packit c32a2d
	make
Packit c32a2d
Packit c32a2d
You can then find the library itself under src/libmpg123/.libs (libtool likes to hide things there).
Packit c32a2d
Packit c32a2d
Packit c32a2d
4. Exotic platforms
Packit c32a2d
Packit c32a2d
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).
Packit c32a2d
Packit c32a2d
Then compile objects, link.
Packit c32a2d
Packit c32a2d
Packit c32a2d
4a. Preparing Win32 binary packages.
Packit c32a2d
Packit c32a2d
Caution: You should make sure to use some gcc >= 4.2.0, even if it's still the experimental package for MinGW32.
Packit c32a2d
This helps preventing incompatibilities between generated DLL files and other compilers (it's about stack alignment).
Packit c32a2d
Packit c32a2d
Get MinGW/MSYS installed, run the MSYS shell.
Packit c32a2d
Enter the mpg123 source directory.
Packit c32a2d
Execute sh ./windows-builds.sh .
Packit c32a2d
Packit c32a2d
After some time, you should have some relevant files under releases/ (or releases\, for Windows people;-).
Packit c32a2d
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 .
Packit c32a2d
Packit c32a2d
Packit c32a2d
5. Note on large file support
Packit c32a2d
Packit c32a2d
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.
Packit c32a2d
To deal with the incompatibilities that can cause, the library needs to separate code paths for small and large off_t.
Packit c32a2d
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.
Packit c32a2d
In both large-file and normal mode, the library should just work for your app.
Packit c32a2d
Packit c32a2d
6. Security
Packit c32a2d
Packit c32a2d
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?
Packit c32a2d
Packit c32a2d
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.