doc/platform: Remove false claim about MinGW installer
[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 or MinGW-w64
81 toolchains. Install the latest versions of MSYS and MinGW or MinGW-w64 from
82 @url{http://www.mingw.org/} or @url{http://mingw-w64.sourceforge.net/}.
83 You can find detailed installation instructions in the download section and
84 the FAQ.
85
86 Notes:
87
88 @itemize
89
90 @item Building natively using MSYS can be sped up by disabling implicit rules
91 in the Makefile by calling @code{make -r} instead of plain @code{make}. This
92 speed up is close to non-existent for normal one-off builds and is only
93 noticeable when running make for a second time (for example during
94 @code{make install}).
95
96 @item In order to compile AVplay, you must have the MinGW development library
97 of @uref{http://www.libsdl.org/, SDL} and @code{pkg-config} installed.
98
99 @item By using @code{./configure --enable-shared} when configuring Libav,
100 you can build all libraries as DLLs.
101
102 @end itemize
103
104 @section Microsoft Visual C++ compatibility
105
106 As stated in the FAQ, Libav will not compile under MSVC++. However, if you
107 want to use the libav* libraries in your own applications, you can still
108 compile those applications using MSVC++. But the libav* libraries you link
109 to @emph{must} be built with MinGW. However, you will not be able to debug
110 inside the libav* libraries, since MSVC++ does not recognize the debug
111 symbols generated by GCC.
112 We strongly recommend you to move over from MSVC++ to MinGW tools.
113
114 This description of how to use the Libav libraries with MSVC++ is based on
115 Microsoft Visual C++ 2005 Express Edition. If you have a different version,
116 you might have to modify the procedures slightly.
117
118 @subsection Using static libraries
119
120 Assuming you have just built and installed Libav in @file{/usr/local}:
121
122 @enumerate
123
124 @item Create a new console application ("File / New / Project") and then
125 select "Win32 Console Application". On the appropriate page of the
126 Application Wizard, uncheck the "Precompiled headers" option.
127
128 @item Write the source code for your application, or, for testing, just
129 copy the code from an existing sample application into the source file
130 that MSVC++ has already created for you. For example, you can copy
131 @file{libavformat/output-example.c} from the Libav distribution.
132
133 @item Open the "Project / Properties" dialog box. In the "Configuration"
134 combo box, select "All Configurations" so that the changes you make will
135 affect both debug and release builds. In the tree view on the left hand
136 side, select "C/C++ / General", then edit the "Additional Include
137 Directories" setting to contain the path where the Libav includes were
138 installed (i.e. @file{c:\msys\1.0\local\include}).
139 Do not add MinGW's include directory here, or the include files will
140 conflict with MSVC's.
141
142 @item Still in the "Project / Properties" dialog box, select
143 "Linker / General" from the tree view and edit the
144 "Additional Library Directories" setting to contain the @file{lib}
145 directory where Libav was installed (i.e. @file{c:\msys\1.0\local\lib}),
146 the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
147 and the directory where MinGW's GCC libs are installed
148 (i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
149 "Linker / Input" from the tree view, and add the files @file{libavformat.a},
150 @file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
151 @file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
152 to the end of "Additional Dependencies".
153
154 @item Now, select "C/C++ / Code Generation" from the tree view. Select
155 "Debug" in the "Configuration" combo box. Make sure that "Runtime
156 Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
157 the "Configuration" combo box and make sure that "Runtime Library" is
158 set to "Multi-threaded DLL".
159
160 @item Click "OK" to close the "Project / Properties" dialog box.
161
162 @item MSVC++ lacks some C99 header files that are fundamental for Libav.
163 Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
164 and install it in MSVC++'s include directory
165 (i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
166
167 @item MSVC++ also does not understand the @code{inline} keyword used by
168 Libav, so you must add this line before @code{#include}ing libav*:
169 @example
170 #define inline _inline
171 @end example
172
173 @item Build your application, everything should work.
174
175 @end enumerate
176
177 @subsection Using shared libraries
178
179 This is how to create DLL and LIB files that are compatible with MSVC++:
180
181 Within the MSYS shell, build Libav with
182
183 @example
184 ./configure --enable-shared
185 make
186 make install
187 @end example
188
189 Your install path (@file{/usr/local/} by default) should now have the
190 necessary DLL and LIB files under the @file{bin} directory.
191
192 Alternatively, build the libraries with a cross compiler, according to
193 the instructions below in @ref{Cross compilation for Windows with Linux}.
194
195 To use those files with MSVC++, do the same as you would do with
196 the static libraries, as described above. But in Step 4,
197 you should only need to add the directory where the LIB files are installed
198 (i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
199 installed in the @file{bin} directory. And instead of adding the static
200 libraries (@file{libxxx.a} files) you should add the MSVC import libraries
201 (@file{avcodec.lib}, @file{avformat.lib}, and
202 @file{avutil.lib}). Note that you should not use the GCC import
203 libraries (@file{libxxx.dll.a} files), as these will give you undefined
204 reference errors. There should be no need for @file{libmingwex.a},
205 @file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
206 statically linked into the DLLs.
207
208 Libav headers do not declare global data for Windows DLLs through the usual
209 dllexport/dllimport interface. Such data will be exported properly while
210 building, but to use them in your MSVC++ code you will have to edit the
211 appropriate headers and mark the data as dllimport. For example, in
212 libavutil/pixdesc.h you should have:
213 @example
214 extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[];
215 @end example
216
217 Note that using import libraries created by dlltool requires
218 the linker optimization option to be set to
219 "References: Keep Unreferenced Data (@code{/OPT:NOREF})", otherwise
220 the resulting binaries will fail during runtime. This isn't
221 required when using import libraries generated by lib.exe.
222 This issue is reported upstream at
223 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
224
225 To create import libraries that work with the @code{/OPT:REF} option
226 (which is enabled by default in Release mode), follow these steps:
227
228 @enumerate
229
230 @item Open @emph{Visual Studio 2005 Command Prompt}.
231
232 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
233 which sets up the environment variables for the Visual C++ tools
234 (the standard location for this file is
235 @file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat}).
236
237 @item Enter the @file{bin} directory where the created LIB and DLL files
238 are stored.
239
240 @item Generate new import libraries with @command{lib.exe}:
241
242 @example
243 lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
244 @end example
245
246 Replace @code{foo-version} and @code{foo} with the respective library names.
247
248 @end enumerate
249
250 @anchor{Cross compilation for Windows with Linux}
251 @section Cross compilation for Windows with Linux
252
253 You must use the MinGW cross compilation tools available at
254 @url{http://www.mingw.org/}.
255
256 Then configure Libav with the following options:
257 @example
258 ./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
259 @end example
260 (you can change the cross-prefix according to the prefix chosen for the
261 MinGW tools).
262
263 Then you can easily test Libav with @uref{http://www.winehq.com/, Wine}.
264
265 @section Compilation under Cygwin
266
267 Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
268 llrint() in its C library.
269
270 Install your Cygwin with all the "Base" packages, plus the
271 following "Devel" ones:
272 @example
273 binutils, gcc4-core, make, git, mingw-runtime, texi2html
274 @end example
275
276 In order to run FATE you will also need the following "Utils" packages:
277 @example
278 bc, diffutils
279 @end example
280
281 If you want to build Libav with additional libraries, download Cygwin
282 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
283 @example
284 libogg-devel, libvorbis-devel
285 @end example
286
287 These library packages are only available from
288 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
289
290 @example
291 yasm, libSDL-devel, libfaac-devel, libgsm-devel, libmp3lame-devel,
292 libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-devel
293 @end example
294
295 The recommendation for x264 is to build it from source, as it evolves too
296 quickly for Cygwin Ports to be up to date.
297
298 @section Crosscompilation for Windows under Cygwin
299
300 With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
301
302 Just install your Cygwin as explained before, plus these additional
303 "Devel" packages:
304 @example
305 gcc-mingw-core, mingw-runtime, mingw-zlib
306 @end example
307
308 and add some special flags to your configure invocation.
309
310 For a static build run
311 @example
312 ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
313 @end example
314
315 and for a build with shared libraries
316 @example
317 ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
318 @end example
319
320 @bye