doc/platform: Replace Visual Studio section with build instructions
[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 FFmpeg 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 FFmpeg, you need to install and use GNU Make
30 (@command{gmake}).
31
32 @section (Open)Solaris
33
34 GNU Make is required to build FFmpeg, 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 (Mac OS X, iPhone)
49
50 The toolchain provided with Xcode is sufficient to build the basic
51 unacelerated code.
52
53 Mac 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, FFmpeg's configure will pick it up automatically.
57
58 Mac OS X on amd64 and x86 requires @command{yasm} to build most of the
59 optimized assembler functions. @uref{http://www.finkproject.org/, Fink},
60 @uref{http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-macos.xml, Gentoo Prefix},
61 @uref{http://mxcl.github.com/homebrew/, Homebrew}
62 or @uref{http://www.macports.org, MacPorts} can easily provide it.
63
64
65 @chapter DOS
66
67 Using a cross-compiler is preferred for various reasons.
68 @url{http://www.delorie.com/howto/djgpp/linux-x-djgpp.html}
69
70
71 @chapter OS/2
72
73 For information about compiling FFmpeg on OS/2 see
74 @url{http://www.edm2.com/index.php/FFmpeg}.
75
76
77 @chapter Windows
78
79 To get help and instructions for building FFmpeg under Windows, check out
80 the FFmpeg Windows Help Forum at
81 @url{http://ffmpeg.arrozcru.org/}.
82
83 @section Native Windows compilation using MinGW or MinGW-w64
84
85 FFmpeg can be built to run natively on Windows using the MinGW or MinGW-w64
86 toolchains. Install the latest versions of MSYS and MinGW or MinGW-w64 from
87 @url{http://www.mingw.org/} or @url{http://mingw-w64.sourceforge.net/}.
88 You can find detailed installation instructions in the download section and
89 the FAQ.
90
91 Notes:
92
93 @itemize
94
95 @item Building natively using MSYS can be sped up by disabling implicit rules
96 in the Makefile by calling @code{make -r} instead of plain @code{make}. This
97 speed up is close to non-existent for normal one-off builds and is only
98 noticeable when running make for a second time (for example during
99 @code{make install}).
100
101 @item In order to compile FFplay, you must have the MinGW development library
102 of @uref{http://www.libsdl.org/, SDL} and @code{pkg-config} installed.
103
104 @item By using @code{./configure --enable-shared} when configuring FFmpeg,
105 you can build the FFmpeg libraries (e.g. libavutil, libavcodec,
106 libavformat) as DLLs.
107
108 @end itemize
109
110 @section Microsoft Visual C++
111
112 FFmpeg can be built with MSVC using a C99-to-C89 conversion utility and
113 wrapper. At this time, only static builds are supported.
114
115 You will need the following prerequisites:
116
117 @itemize
118 @item @uref{https://github.com/rbultje/c99-to-c89/, C99-to-C89 Converter & Wrapper}
119 @item @uref{http://code.google.com/p/msinttypes/, msinttypes}
120 @item @uref{http://www.mingw.org/, MSYS}
121 @item @uref{http://yasm.tortall.net/, YASM}
122 @item @uref{http://gnuwin32.sourceforge.net/packages/bc.htm, bc for Windows} if
123 you want to run @uref{fate.html, FATE}.
124 @end itemize
125
126 To set up a proper MSVC environment in MSYS, you simply need to run
127 @code{msys.bat} from the Visual Studio command prompt.
128
129 Caveat: Run @code{which link} to see which link you are using. If it is located
130 at @code{/bin/link.exe}, then you have the wrong link in your @code{PATH}.
131 Either move/remove that copy, or make sure MSVC's link.exe is higher up in your
132 @code{PATH} than coreutils'.
133
134 Place @code{c99wrap.exe}, @code{c99conv.exe}, and @code{yasm.exe} somewhere
135 in your @code{PATH}.
136
137 Next, make sure @code{inttypes.h} and any other headers and libs you want to use
138 are located in a spot that MSVC can see. Do so by modifying the @code{LIB} and
139 @code{INCLUDE} environment variables to include the @strong{Windows} paths to
140 these directories. Alternatively, you can try and use the
141 @code{--extra-cflags}/@code{--extra-ldflags} configure options.
142
143 Finally, run:
144
145 @example
146 ./configure --toolchain=msvc
147 make
148 make install
149 @end example
150
151 Notes:
152
153 @itemize
154
155 @item If you wish to build with zlib support, you will have to grab a compatible
156 zlib binary from somewhere, with an MSVC import lib, or if you wish to link
157 statically, you can follow the instructions below to build a compatible
158 @code{zlib.lib} with MSVC. Regardless of which method you use, you must still
159 follow step 3, or compilation will fail.
160 @enumerate
161 @item Grab the @uref{http://zlib.net/, zlib sources}.
162 @item Edit @code{win32/Makefile.msc} so that it uses -MT instead of -MD, since
163 this is how FFmpeg is built as well.
164 @item Edit @code{zconf.h} and remove its inclusion of @code{unistd.h}. This gets
165 erroneously included when building FFmpeg.
166 @item Run @code{nmake -f win32/Makefile.msc}.
167 @item Move @code{zlib.lib}, @code{zconf.h}, and @code{zlib.h} to somewhere MSVC
168 can see.
169 @end enumerate
170
171 @item FFmpeg has been tested with Visual Studio 2010 and 2012, Pro and Express.
172 Anything else is not officially supported.
173
174 @end itemize
175
176 @subsection Using shared libraries built with MinGW in Visual Studio
177
178 Currently, if you want to build shared libraries on Windows, you need to
179 use MinGW.
180
181 This is how to create DLL and LIB files that are compatible with MSVC++:
182
183 @enumerate
184
185 @item Add a call to @file{vcvars32.bat} (which sets up the environment
186 variables for the Visual C++ tools) as the first line of @file{msys.bat}.
187 The standard location for @file{vcvars32.bat} is
188 @file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
189 and the standard location for @file{msys.bat} is @file{C:\msys\1.0\msys.bat}.
190 If this corresponds to your setup, add the following line as the first line
191 of @file{msys.bat}:
192
193 @example
194 call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
195 @end example
196
197 Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
198 and run @file{c:\msys\1.0\msys.bat} from there.
199
200 @item Within the MSYS shell, run @code{lib.exe}. If you get a help message
201 from @file{Microsoft (R) Library Manager}, this means your environment
202 variables are set up correctly, the @file{Microsoft (R) Library Manager}
203 is on the path and will be used by FFmpeg to create
204 MSVC++-compatible import libraries.
205
206 @item Build FFmpeg with
207
208 @example
209 ./configure --enable-shared
210 make
211 make install
212 @end example
213
214 Your install path (@file{/usr/local/} by default) should now have the
215 necessary DLL and LIB files under the @file{bin} directory.
216
217 @end enumerate
218
219 Alternatively, build the libraries with a cross compiler, according to
220 the instructions below in @ref{Cross compilation for Windows with Linux}.
221
222 To use those files with MSVC++, do the same as you would do with
223 the static libraries, as described above. But in Step 4,
224 you should only need to add the directory where the LIB files are installed
225 (i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
226 installed in the @file{bin} directory. And instead of adding the static
227 libraries (@file{libxxx.a} files) you should add the MSVC import libraries
228 (@file{avcodec.lib}, @file{avformat.lib}, and
229 @file{avutil.lib}). Note that you should not use the GCC import
230 libraries (@file{libxxx.dll.a} files), as these will give you undefined
231 reference errors. There should be no need for @file{libmingwex.a},
232 @file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
233 statically linked into the DLLs.
234
235 FFmpeg headers do not declare global data for Windows DLLs through the usual
236 dllexport/dllimport interface. Such data will be exported properly while
237 building, but to use them in your MSVC++ code you will have to edit the
238 appropriate headers and mark the data as dllimport. For example, in
239 libavutil/pixdesc.h you should have:
240 @example
241 extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[];
242 @end example
243
244 Note that using import libraries created by dlltool requires
245 the linker optimization option to be set to
246 "References: Keep Unreferenced Data (@code{/OPT:NOREF})", otherwise
247 the resulting binaries will fail during runtime. This isn't
248 required when using import libraries generated by lib.exe.
249 This issue is reported upstream at
250 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
251
252 To create import libraries that work with the @code{/OPT:REF} option
253 (which is enabled by default in Release mode), follow these steps:
254
255 @enumerate
256
257 @item Open @emph{Visual Studio 2005 Command Prompt}.
258
259 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
260 which sets up the environment variables for the Visual C++ tools
261 (the standard location for this file is
262 @file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat}).
263
264 @item Enter the @file{bin} directory where the created LIB and DLL files
265 are stored.
266
267 @item Generate new import libraries with @command{lib.exe}:
268
269 @example
270 lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
271 @end example
272
273 Replace @code{foo-version} and @code{foo} with the respective library names.
274
275 @end enumerate
276
277 @anchor{Cross compilation for Windows with Linux}
278 @section Cross compilation for Windows with Linux
279
280 You must use the MinGW cross compilation tools available at
281 @url{http://www.mingw.org/}.
282
283 Then configure FFmpeg with the following options:
284 @example
285 ./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
286 @end example
287 (you can change the cross-prefix according to the prefix chosen for the
288 MinGW tools).
289
290 Then you can easily test FFmpeg with @uref{http://www.winehq.com/, Wine}.
291
292 @section Compilation under Cygwin
293
294 Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
295 llrint() in its C library.
296
297 Install your Cygwin with all the "Base" packages, plus the
298 following "Devel" ones:
299 @example
300 binutils, gcc4-core, make, git, mingw-runtime, texi2html
301 @end example
302
303 In order to run FATE you will also need the following "Utils" packages:
304 @example
305 bc, diffutils
306 @end example
307
308 If you want to build FFmpeg with additional libraries, download Cygwin
309 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
310 @example
311 libogg-devel, libvorbis-devel
312 @end example
313
314 These library packages are only available from
315 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
316
317 @example
318 yasm, libSDL-devel, libfaac-devel, libaacplus-devel, libgsm-devel, libmp3lame-devel,
319 libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-devel
320 @end example
321
322 The recommendation for x264 is to build it from source, as it evolves too
323 quickly for Cygwin Ports to be up to date.
324
325 @section Crosscompilation for Windows under Cygwin
326
327 With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
328
329 Just install your Cygwin as explained before, plus these additional
330 "Devel" packages:
331 @example
332 gcc-mingw-core, mingw-runtime, mingw-zlib
333 @end example
334
335 and add some special flags to your configure invocation.
336
337 For a static build run
338 @example
339 ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
340 @end example
341
342 and for a build with shared libraries
343 @example
344 ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
345 @end example
346
347 @bye