181 lines
6.3 KiB
Text
181 lines
6.3 KiB
Text
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.
|