249 lines
9.2 KiB
Text
249 lines
9.2 KiB
Text
mpg123 install hints
|
|
--------------------
|
|
|
|
0. Prerequesites
|
|
|
|
You really need:
|
|
|
|
- a C99 compiler (moderate C99 support)
|
|
|
|
- an (UNIX-like) operating system with standard tools; mingw-w64 and
|
|
Cygwin are working for Microsoft Windows, too. We also have users happily
|
|
playing 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 UNIX-like
|
|
platforms for a full build, but its main purpose is for portability
|
|
where autotools don't do the trick.
|
|
|
|
- There used to be some additional ports in ports/, now there is a single
|
|
CMake structure there that handles most systems that cannot use autotools
|
|
to at least build the decoder library.
|
|
|
|
- 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) or have cmake present for ports/cmake/.
|
|
|
|
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
|
|
|
|
Note: If you want the full range of output modules, you might
|
|
run into cirucular dependencies, as pulseaudio or SDL might also
|
|
want to use parts of the mpg123 distribution. You can split the
|
|
build avoid that circle.
|
|
|
|
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
|
|
|
|
If you want to separate components (for avoiding circular dependencies,
|
|
for example), you can split things at various points. Either you build
|
|
all libraries and programs first, then all output modules via
|
|
|
|
# Build programs and libs only.
|
|
./configure --disable-components --enable-programs \
|
|
--enable-libmpg123 --enable-libsyn123 --enable-libout123 \
|
|
--with-default-audio=$OUTPUT_MODULES
|
|
make && make install
|
|
# Build packges relying on mpg123 libraries.
|
|
# After that, build out123 modules with external dependencies
|
|
./configure --disable-components --enable-libout123-modules \
|
|
--with-audio=$OUTPUT_MODULES
|
|
make && make install
|
|
|
|
or you can build each component individually, or just separate out the
|
|
problematic modules by
|
|
|
|
# Build all components, but dummy output only.
|
|
./configure --with-audio=dummy,$SAFE_MODULES \
|
|
--with-default-audio=$OUTPUT_MODULES
|
|
make && install
|
|
# Build other packages, like SDL, pulse.
|
|
# After that, build output modules depending on those.
|
|
# Without --with-audio, auto-detection will build a list.
|
|
./configure --disable-components --enable-libout123-modules \
|
|
--with-audio=$UNSAFE_MODULES
|
|
make && make install
|
|
|
|
The variables OUTPUT_MODULES, SAFE_MOULES, and UNSAFE_MODULES are
|
|
supposed to contain comma-separated lists of output modules like
|
|
"oss,pulse,alsa,jack". You need to give a full list when building
|
|
libout123 without modules to setup the default search order. Without
|
|
this, it won't find modules automatically without specifying one with
|
|
mpg123 -o $module. There is no module registry, just a simple build-time
|
|
list and the option to specify a module at runtime.
|
|
|
|
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).
|
|
|
|
Alternatively, you can use --disable-components and --enable-foo for
|
|
building only component foo (like libmpg123).
|
|
|
|
|
|
4. Exotic platforms
|
|
|
|
There used to be (and still are in revsion control history) special
|
|
ports for some platforms or language bindings in the ports/ directory.
|
|
|
|
Right now, there is only ports/cmake for an alternate CMake-based
|
|
build, mainly for libmpg123 itself, but also libsyn123 and possibly
|
|
the full set if the platform is UNIX-like.
|
|
|
|
If autotools and also ports/cmake do not do the trick, you need to
|
|
construct a src/config.h and build and gather the object files you want.
|
|
The autotools input files should help here, too.
|
|
|
|
4a. Microsoft Windows
|
|
|
|
Under Windows, you can use Cygwin, MSYS2 or probably also the WSL
|
|
environment to build mpg123 binaries. If you want binaries that
|
|
work nicely stand-alone, and also at least being able to force correct
|
|
printout of UTF-8 text using chcp 65001 and mpg123 --utf8, the MSYS2
|
|
UCRT64 shell and accompanying toolchain seem to work (see MSYS2
|
|
documentation on how to set up, it is not that hard).
|
|
|
|
To generate a set of binary builds matching the erstwhile official mpg123
|
|
binaries, run
|
|
|
|
sh ./windows-builds.sh x86
|
|
|
|
or
|
|
|
|
sh ./windows-builds.sh x86_64
|
|
|
|
(optionally followed by a number to indicate the count of parallel make
|
|
tasks).
|
|
|
|
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 was to be found under https://mpg123.org/download/win32/ and
|
|
https://mpg123.org/download/win64/ .
|
|
|
|
Notet hat, depending on you msys/mingw variant, you might have to copy
|
|
libwinpthread-1.dll to the respective release directory. This is a quirk
|
|
of the toolchain which insists on linking in a threading runtime. You
|
|
might be able to statically link it in with some extra magic.
|
|
|
|
You can also run this script on a Linux host with mingw-w64 cross toolchain
|
|
installed, with arguments x86-cross and x86_64-cross.
|
|
|
|
|
|
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.
|
|
|
|
In the meantime a portable API with fixed 64 bit integers (and some irony
|
|
on top) also was added. You can limit yourself to that api by defining
|
|
MPG123_PORTABLE_API in client code.
|
|
|
|
|
|
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.
|