doc: Drop obsolete shared libs cflags hint to workaround Cygwin gcc bugs
[ffmpeg.git] / doc / platform.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle Platform Specific information
4 @titlepage
5 @center @titlefont{Platform Specific information}
6 @end titlepage
7
8 @top
9
10 @contents
11
12 @chapter Unix-like
13
14 Some parts of Libav cannot be built with version 2.15 of the GNU
15 assembler which is still provided by a few AMD64 distributions. To
16 make sure your compiler really uses the required version of gas
17 after a binutils upgrade, run:
18
19 @example
20 $(gcc -print-prog-name=as) --version
21 @end example
22
23 If not, then you should install a different compiler that has no
24 hard-coded path to gas. In the worst case pass @code{--disable-asm}
25 to configure.
26
27 @section BSD
28
29 BSD make will not build Libav, you need to install and use GNU Make
30 (@command{gmake}).
31
32 @section (Open)Solaris
33
34 GNU Make is required to build Libav, so you have to invoke (@command{gmake}),
35 standard Solaris Make will not work. When building with a non-c99 front-end
36 (gcc, generic suncc) add either @code{--extra-libs=/usr/lib/values-xpg6.o}
37 or @code{--extra-libs=/usr/lib/64/values-xpg6.o} to the configure options
38 since the libc is not c99-compliant by default. The probes performed by
39 configure may raise an exception leading to the death of configure itself
40 due to a bug in the system shell. Simply invoke a different shell such as
41 bash directly to work around this:
42
43 @example
44 bash ./configure
45 @end example
46
47 @anchor{Darwin}
48 @section Darwin (OS X, iPhone)
49
50 The toolchain provided with Xcode is sufficient to build the basic
51 unacelerated code.
52
53 OS X on PowerPC or ARM (iPhone) requires a preprocessor from
54 @url{http://github.com/yuvi/gas-preprocessor} to build the optimized
55 assembler functions. Just download the Perl script and put it somewhere
56 in your PATH, Libav's configure will pick it up automatically.
57
58 OS X on AMD64 and x86 requires @command{yasm} to build most of the
59 optimized assembler functions @url{http://mxcl.github.com/homebrew/, Homebrew},
60 @url{http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-macos.xml, Gentoo Prefix}
61 or @url{http://www.macports.org, MacPorts} can easily provide it.
62
63
64 @chapter DOS
65
66 Using a cross-compiler is preferred for various reasons.
67 @url{http://www.delorie.com/howto/djgpp/linux-x-djgpp.html}
68
69
70 @chapter OS/2
71
72 For information about compiling Libav on OS/2 see
73 @url{http://www.edm2.com/index.php/FFmpeg}.
74
75
76 @chapter Windows
77
78 @section Native Windows compilation
79
80 Libav can be built to run natively on Windows using the MinGW tools. Install
81 the latest versions of MSYS and MinGW from @url{http://www.mingw.org/}.
82 You can find detailed installation
83 instructions in the download section and the FAQ.
84
85 Libav does not build out-of-the-box with the packages the automated MinGW
86 installer provides. It also requires coreutils to be installed and many other
87 packages updated to the latest version. The minimum versions for some packages
88 are listed below:
89
90 @itemize
91 @item bash 3.1
92 @item msys-make 3.81-2 (note: not mingw32-make)
93 @item w32api 3.13
94 @item mingw-runtime 3.15
95 @end itemize
96
97 Libav automatically passes @code{-fno-common} to the compiler to work around
98 a GCC bug (see @url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37216}).
99
100 Notes:
101
102 @itemize
103
104 @item Building natively using MSYS can be sped up by disabling implicit rules
105 in the Makefile by calling @code{make -r} instead of plain @code{make}. This
106 speed up is close to non-existent for normal one-off builds and is only
107 noticeable when running make for a second time (for example during
108 @code{make install}).
109
110 @item In order to compile AVplay, you must have the MinGW development library
111 of @uref{http://www.libsdl.org/, SDL} and @code{pkg-config} installed.
112
113 @item By using @code{./configure --enable-shared} when configuring Libav,
114 you can build all libraries as DLLs.
115
116 @end itemize
117
118 @section Microsoft Visual C++ compatibility
119
120 As stated in the FAQ, Libav will not compile under MSVC++. However, if you
121 want to use the libav* libraries in your own applications, you can still
122 compile those applications using MSVC++. But the libav* libraries you link
123 to @emph{must} be built with MinGW. However, you will not be able to debug
124 inside the libav* libraries, since MSVC++ does not recognize the debug
125 symbols generated by GCC.
126 We strongly recommend you to move over from MSVC++ to MinGW tools.
127
128 This description of how to use the Libav libraries with MSVC++ is based on
129 Microsoft Visual C++ 2005 Express Edition. If you have a different version,
130 you might have to modify the procedures slightly.
131
132 @subsection Using static libraries
133
134 Assuming you have just built and installed Libav in @file{/usr/local}:
135
136 @enumerate
137
138 @item Create a new console application ("File / New / Project") and then
139 select "Win32 Console Application". On the appropriate page of the
140 Application Wizard, uncheck the "Precompiled headers" option.
141
142 @item Write the source code for your application, or, for testing, just
143 copy the code from an existing sample application into the source file
144 that MSVC++ has already created for you. For example, you can copy
145 @file{libavformat/output-example.c} from the Libav distribution.
146
147 @item Open the "Project / Properties" dialog box. In the "Configuration"
148 combo box, select "All Configurations" so that the changes you make will
149 affect both debug and release builds. In the tree view on the left hand
150 side, select "C/C++ / General", then edit the "Additional Include
151 Directories" setting to contain the path where the Libav includes were
152 installed (i.e. @file{c:\msys\1.0\local\include}).
153 Do not add MinGW's include directory here, or the include files will
154 conflict with MSVC's.
155
156 @item Still in the "Project / Properties" dialog box, select
157 "Linker / General" from the tree view and edit the
158 "Additional Library Directories" setting to contain the @file{lib}
159 directory where Libav was installed (i.e. @file{c:\msys\1.0\local\lib}),
160 the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
161 and the directory where MinGW's GCC libs are installed
162 (i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
163 "Linker / Input" from the tree view, and add the files @file{libavformat.a},
164 @file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
165 @file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
166 to the end of "Additional Dependencies".
167
168 @item Now, select "C/C++ / Code Generation" from the tree view. Select
169 "Debug" in the "Configuration" combo box. Make sure that "Runtime
170 Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
171 the "Configuration" combo box and make sure that "Runtime Library" is
172 set to "Multi-threaded DLL".
173
174 @item Click "OK" to close the "Project / Properties" dialog box.
175
176 @item MSVC++ lacks some C99 header files that are fundamental for Libav.
177 Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
178 and install it in MSVC++'s include directory
179 (i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
180
181 @item MSVC++ also does not understand the @code{inline} keyword used by
182 Libav, so you must add this line before @code{#include}ing libav*:
183 @example
184 #define inline _inline
185 @end example
186
187 @item Build your application, everything should work.
188
189 @end enumerate
190
191 @subsection Using shared libraries
192
193 This is how to create DLL and LIB files that are compatible with MSVC++:
194
195 Within the MSYS shell, build Libav with
196
197 @example
198 ./configure --enable-shared
199 make
200 make install
201 @end example
202
203 Your install path (@file{/usr/local/} by default) should now have the
204 necessary DLL and LIB files under the @file{bin} directory.
205
206 Alternatively, build the libraries with a cross compiler, according to
207 the instructions below in @ref{Cross compilation for Windows with Linux}.
208
209 To use those files with MSVC++, do the same as you would do with
210 the static libraries, as described above. But in Step 4,
211 you should only need to add the directory where the LIB files are installed
212 (i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
213 installed in the @file{bin} directory. And instead of adding the static
214 libraries (@file{libxxx.a} files) you should add the MSVC import libraries
215 (@file{avcodec.lib}, @file{avformat.lib}, and
216 @file{avutil.lib}). Note that you should not use the GCC import
217 libraries (@file{libxxx.dll.a} files), as these will give you undefined
218 reference errors. There should be no need for @file{libmingwex.a},
219 @file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
220 statically linked into the DLLs.
221
222 Libav headers do not declare global data for Windows DLLs through the usual
223 dllexport/dllimport interface. Such data will be exported properly while
224 building, but to use them in your MSVC++ code you will have to edit the
225 appropriate headers and mark the data as dllimport. For example, in
226 libavutil/pixdesc.h you should have:
227 @example
228 extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[];
229 @end example
230
231 Note that using import libraries created by dlltool requires
232 the linker optimization option to be set to
233 "References: Keep Unreferenced Data (@code{/OPT:NOREF})", otherwise
234 the resulting binaries will fail during runtime. This isn't
235 required when using import libraries generated by lib.exe.
236 This issue is reported upstream at
237 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
238
239 To create import libraries that work with the @code{/OPT:REF} option
240 (which is enabled by default in Release mode), follow these steps:
241
242 @enumerate
243
244 @item Open @emph{Visual Studio 2005 Command Prompt}.
245
246 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
247 which sets up the environment variables for the Visual C++ tools
248 (the standard location for this file is
249 @file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat}).
250
251 @item Enter the @file{bin} directory where the created LIB and DLL files
252 are stored.
253
254 @item Generate new import libraries with @command{lib.exe}:
255
256 @example
257 lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
258 @end example
259
260 Replace @code{foo-version} and @code{foo} with the respective library names.
261
262 @end enumerate
263
264 @anchor{Cross compilation for Windows with Linux}
265 @section Cross compilation for Windows with Linux
266
267 You must use the MinGW cross compilation tools available at
268 @url{http://www.mingw.org/}.
269
270 Then configure Libav with the following options:
271 @example
272 ./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
273 @end example
274 (you can change the cross-prefix according to the prefix chosen for the
275 MinGW tools).
276
277 Then you can easily test Libav with @uref{http://www.winehq.com/, Wine}.
278
279 @section Compilation under Cygwin
280
281 Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
282 llrint() in its C library.
283
284 Install your Cygwin with all the "Base" packages, plus the
285 following "Devel" ones:
286 @example
287 binutils, gcc4-core, make, git, mingw-runtime, texi2html
288 @end example
289
290 In order to run FATE you will also need the following "Utils" packages:
291 @example
292 bc, diffutils
293 @end example
294
295 If you want to build Libav with additional libraries, download Cygwin
296 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
297 @example
298 libogg-devel, libvorbis-devel
299 @end example
300
301 These library packages are only available from
302 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
303
304 @example
305 yasm, libSDL-devel, libfaac-devel, libgsm-devel, libmp3lame-devel,
306 libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-devel
307 @end example
308
309 The recommendation for x264 is to build it from source, as it evolves too
310 quickly for Cygwin Ports to be up to date.
311
312 @section Crosscompilation for Windows under Cygwin
313
314 With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
315
316 Just install your Cygwin as explained before, plus these additional
317 "Devel" packages:
318 @example
319 gcc-mingw-core, mingw-runtime, mingw-zlib
320 @end example
321
322 and add some special flags to your configure invocation.
323
324 For a static build run
325 @example
326 ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
327 @end example
328
329 and for a build with shared libraries
330 @example
331 ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
332 @end example
333
334 @bye