| 1 |
mpg123 install hints |
| 2 |
-------------------- |
| 3 |
|
| 4 |
0. Prerequesites |
| 5 |
|
| 6 |
You really need: |
| 7 |
|
| 8 |
- a C99 compiler (moderate C99 support) |
| 9 |
|
| 10 |
- an (UNIX-like) operating system with standard tools; mingw-w64 and |
| 11 |
Cygwin are working for Microsoft Windows, too. We also have users happily |
| 12 |
playing on OS/2. |
| 13 |
|
| 14 |
- For the library only, you may get lucky with MSVC++ using CMake and |
| 15 |
ports/cmake as source directory. You can also use CMake on UNIX-like |
| 16 |
platforms for a full build, but its main purpose is for portability |
| 17 |
where autotools don't do the trick. |
| 18 |
|
| 19 |
- There used to be some additional ports in ports/, now there is a single |
| 20 |
CMake structure there that handles most systems that cannot use autotools |
| 21 |
to at least build the decoder library. |
| 22 |
|
| 23 |
- If building from direct source code repository checkout, as opposed to |
| 24 |
a release or snapshot tarball, you need GNU autotools installed |
| 25 |
(see Developer Build below) or have cmake present for ports/cmake/. |
| 26 |
|
| 27 |
You want: |
| 28 |
|
| 29 |
- working assembler (recent GNU binutils) if using certain CPU |
| 30 |
optimizations |
| 31 |
|
| 32 |
- headers and lib for certain audio output drivers (libasound for alsa, |
| 33 |
sdl for sdl...) |
| 34 |
|
| 35 |
1. Build |
| 36 |
|
| 37 |
Note: If you want the full range of output modules, you might |
| 38 |
run into cirucular dependencies, as pulseaudio or SDL might also |
| 39 |
want to use parts of the mpg123 distribution. You can split the |
| 40 |
build avoid that circle. |
| 41 |
|
| 42 |
There is one main supported way to get your mpg123 installation |
| 43 |
consisting of |
| 44 |
|
| 45 |
a) the mpg123, mpg123-strip, mpg123-id3dump, out123 program binaries |
| 46 |
- with libmpg123, libout123, and libsyn123 as shared libraries or |
| 47 |
statically linked |
| 48 |
- with audio output plugins for libout123, or one statically linked |
| 49 |
|
| 50 |
b) man pages |
| 51 |
|
| 52 |
(you may want to copy some of the documentation - README, etc - to |
| 53 |
/usr/share/doc/mpg123 or the like, too) |
| 54 |
|
| 55 |
This way is the usual GNU 3-step procedure: |
| 56 |
|
| 57 |
./configure |
| 58 |
make |
| 59 |
make install |
| 60 |
|
| 61 |
If you want to separate components (for avoiding circular dependencies, |
| 62 |
for example), you can split things at various points. Either you build |
| 63 |
all libraries and programs first, then all output modules via |
| 64 |
|
| 65 |
# Build programs and libs only. |
| 66 |
./configure --disable-components --enable-programs \ |
| 67 |
--enable-libmpg123 --enable-libsyn123 --enable-libout123 \ |
| 68 |
--with-default-audio=$OUTPUT_MODULES |
| 69 |
make && make install |
| 70 |
# Build packges relying on mpg123 libraries. |
| 71 |
# After that, build out123 modules with external dependencies |
| 72 |
./configure --disable-components --enable-libout123-modules \ |
| 73 |
--with-audio=$OUTPUT_MODULES |
| 74 |
make && make install |
| 75 |
|
| 76 |
or you can build each component individually, or just separate out the |
| 77 |
problematic modules by |
| 78 |
|
| 79 |
# Build all components, but dummy output only. |
| 80 |
./configure --with-audio=dummy,$SAFE_MODULES \ |
| 81 |
--with-default-audio=$OUTPUT_MODULES |
| 82 |
make && install |
| 83 |
# Build other packages, like SDL, pulse. |
| 84 |
# After that, build output modules depending on those. |
| 85 |
# Without --with-audio, auto-detection will build a list. |
| 86 |
./configure --disable-components --enable-libout123-modules \ |
| 87 |
--with-audio=$UNSAFE_MODULES |
| 88 |
make && make install |
| 89 |
|
| 90 |
The variables OUTPUT_MODULES, SAFE_MOULES, and UNSAFE_MODULES are |
| 91 |
supposed to contain comma-separated lists of output modules like |
| 92 |
"oss,pulse,alsa,jack". You need to give a full list when building |
| 93 |
libout123 without modules to setup the default search order. Without |
| 94 |
this, it won't find modules automatically without specifying one with |
| 95 |
mpg123 -o $module. There is no module registry, just a simple build-time |
| 96 |
list and the option to specify a module at runtime. |
| 97 |
|
| 98 |
Run |
| 99 |
|
| 100 |
./configure --help |
| 101 |
|
| 102 |
for a list of possible parameters you can specify in the configuration |
| 103 |
step. The obvious are --prefix and the normal GNU autotool bunch, but |
| 104 |
others include what audio subsystem to use and what CPU optimizations |
| 105 |
to build in. |
| 106 |
For the optimizations (decoder choice), the default is a build that |
| 107 |
combines all usable optimizations for the platform and chooses one at |
| 108 |
runtime (see --cpu, --list-cpu and --test-cpu parameters). |
| 109 |
|
| 110 |
There are various parameters you can tune, but of course the defaults |
| 111 |
are what is mainly tested. |
| 112 |
|
| 113 |
Also, various library features can be left out via --disable options |
| 114 |
(like output formats, resampling modes). That way, you can strive for a |
| 115 |
minimal build that only does what you really need. Not every combination |
| 116 |
of library features is tested regularily, so you might hit some speed |
| 117 |
bumps, but usually stuff that is easily worked out (at least for the |
| 118 |
mpg123 team when you report it). |
| 119 |
|
| 120 |
An example (working on mpg123 trunk r3062): |
| 121 |
|
| 122 |
CFLAGS="-Os -s" ./configure --with-cpu=generic --disable-id3v2 |
| 123 |
--disable-lfs-alias --disable-feature-report --with-seektable=0 |
| 124 |
--disable-16bit --disable-32bit --disable-8bit --disable-messages |
| 125 |
--disable-feeder --disable-ntom --disable-downsample --disable-icy |
| 126 |
&& make |
| 127 |
|
| 128 |
That, and further application of `strip --strip-unneeded`, yields a lean |
| 129 |
93 KiB shared library for MPEG layer I/II/III decoding to floating point |
| 130 |
on my x86-64 system (it should be a bit smaller on 32 bit systems). When |
| 131 |
disabling layers I and II, too, that goes down to 81 KiB. |
| 132 |
|
| 133 |
The shared library of a full build weighs 170 KiB after stripping. |
| 134 |
|
| 135 |
|
| 136 |
2. Developer build |
| 137 |
|
| 138 |
This project uses GNU autotools (no specific version, but they should |
| 139 |
be fairly recent), also libtool. You need to have those installed, as |
| 140 |
it is usually the case for build environments based on the GNU toolchain. |
| 141 |
|
| 142 |
One a fresh SCM checkout, or after changing things in configure.ac, |
| 143 |
you need to run |
| 144 |
|
| 145 |
autoreconf -iv |
| 146 |
|
| 147 |
to prepare the configure script. Then you can build as per point 1. |
| 148 |
|
| 149 |
|
| 150 |
3. Library-only build |
| 151 |
|
| 152 |
Mpg123 uses a non-recursive build. If you want to build only one of the |
| 153 |
libraries, specify it as a target: |
| 154 |
|
| 155 |
./configure |
| 156 |
make src/libmpg123/libmpg123.la |
| 157 |
make src/libsyn123/libsyn123.la |
| 158 |
make src/libout123/libout123.la |
| 159 |
|
| 160 |
You can then find the library itself under src/lib*123/.libs (libtool |
| 161 |
likes to hide things there). |
| 162 |
|
| 163 |
Alternatively, you can use --disable-components and --enable-foo for |
| 164 |
building only component foo (like libmpg123). |
| 165 |
|
| 166 |
|
| 167 |
4. Exotic platforms |
| 168 |
|
| 169 |
There used to be (and still are in revsion control history) special |
| 170 |
ports for some platforms or language bindings in the ports/ directory. |
| 171 |
|
| 172 |
Right now, there is only ports/cmake for an alternate CMake-based |
| 173 |
build, mainly for libmpg123 itself, but also libsyn123 and possibly |
| 174 |
the full set if the platform is UNIX-like. |
| 175 |
|
| 176 |
If autotools and also ports/cmake do not do the trick, you need to |
| 177 |
construct a src/config.h and build and gather the object files you want. |
| 178 |
The autotools input files should help here, too. |
| 179 |
|
| 180 |
4a. Microsoft Windows |
| 181 |
|
| 182 |
Under Windows, you can use Cygwin, MSYS2 or probably also the WSL |
| 183 |
environment to build mpg123 binaries. If you want binaries that |
| 184 |
work nicely stand-alone, and also at least being able to force correct |
| 185 |
printout of UTF-8 text using chcp 65001 and mpg123 --utf8, the MSYS2 |
| 186 |
UCRT64 shell and accompanying toolchain seem to work (see MSYS2 |
| 187 |
documentation on how to set up, it is not that hard). |
| 188 |
|
| 189 |
To generate a set of binary builds matching the erstwhile official mpg123 |
| 190 |
binaries, run |
| 191 |
|
| 192 |
sh ./windows-builds.sh x86 |
| 193 |
|
| 194 |
or |
| 195 |
|
| 196 |
sh ./windows-builds.sh x86_64 |
| 197 |
|
| 198 |
(optionally followed by a number to indicate the count of parallel make |
| 199 |
tasks). |
| 200 |
|
| 201 |
After some time, you should have some relevant files under releases/ |
| 202 |
(or releases\, for Windows people;-). |
| 203 |
You don't just get one build -- there are several variants, corresponding |
| 204 |
to what usually was to be found under https://mpg123.org/download/win32/ and |
| 205 |
https://mpg123.org/download/win64/ . |
| 206 |
|
| 207 |
Notet hat, depending on you msys/mingw variant, you might have to copy |
| 208 |
libwinpthread-1.dll to the respective release directory. This is a quirk |
| 209 |
of the toolchain which insists on linking in a threading runtime. You |
| 210 |
might be able to statically link it in with some extra magic. |
| 211 |
|
| 212 |
You can also run this script on a Linux host with mingw-w64 cross toolchain |
| 213 |
installed, with arguments x86-cross and x86_64-cross. |
| 214 |
|
| 215 |
|
| 216 |
5. Note on large file support |
| 217 |
|
| 218 |
The libmpg123 API includes the generic off_t type for file offsets and |
| 219 |
thus is subject to shape-shifting on systems that change off_t depending |
| 220 |
on build flags. |
| 221 |
To deal with the incompatibilities that can cause, the library needs to |
| 222 |
separate code paths for small and large off_t. |
| 223 |
Since version 1.12.0, a large-file-enabled libmpg123 (the default set |
| 224 |
by configure) provides a dual-mode ABI. Depending on _FILE_OFFSET_BITS, |
| 225 |
the mpg123.h header file selects different library symbols to use for |
| 226 |
your app. |
| 227 |
In both large-file and normal mode, the library should just work for |
| 228 |
your app. |
| 229 |
|
| 230 |
In the meantime a portable API with fixed 64 bit integers (and some irony |
| 231 |
on top) also was added. You can limit yourself to that api by defining |
| 232 |
MPG123_PORTABLE_API in client code. |
| 233 |
|
| 234 |
|
| 235 |
6. Security |
| 236 |
|
| 237 |
If you consider installing the mpg123 binary or any program using |
| 238 |
libout123 as suid root, please don't. Apart from evaluating MPG123_MODDIR |
| 239 |
from the environment and thus possibly loading any code, the purpose of |
| 240 |
libout123 is to write audio data to somewhere. That includes writing raw |
| 241 |
data to files. Any files you specify to the program. You do not install |
| 242 |
dd or gzip suid root, do you? |
| 243 |
|
| 244 |
Programs using libmpg123 should be fine, as that one does not load runtime |
| 245 |
modules and also only has code to read files, not write them. Still, |
| 246 |
if your task involves decoding random MPEG audio files from anywhere, |
| 247 |
it is only sensible to limit the damage of a possible bug triggered by |
| 248 |
certain crafted files. This is not specific to libmpg123 but generally |
| 249 |
a good idea working with data from untrusted sources. |