Debian Codegraph @

INSTALL

raw
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.