doc: Document better how to use MSYS2
[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 Advanced linking configuration
28
29 If you compiled Libav libraries statically and you want to use them to
30 build your own shared library, you may need to force PIC support (with
31 @code{--enable-pic} during Libav configure) and add the following option
32 to your project LDFLAGS:
33
34 @example
35 -Wl,-Bsymbolic
36 @end example
37
38 If your target platform requires position independent binaries, you should
39 pass the correct linking flag (e.g. @code{-pie}) to @code{--extra-ldexeflags}.
40
41 @section BSD
42
43 BSD make will not build Libav, you need to install and use GNU Make
44 (@command{gmake}).
45
46 @section (Open)Solaris
47
48 GNU Make is required to build Libav, so you have to invoke (@command{gmake}),
49 standard Solaris Make will not work. When building with a non-c99 front-end
50 (gcc, generic suncc) add either @code{--extra-libs=/usr/lib/values-xpg6.o}
51 or @code{--extra-libs=/usr/lib/64/values-xpg6.o} to the configure options
52 since the libc is not c99-compliant by default. The probes performed by
53 configure may raise an exception leading to the death of configure itself
54 due to a bug in the system shell. Simply invoke a different shell such as
55 bash directly to work around this:
56
57 @example
58 bash ./configure
59 @end example
60
61 @anchor{Darwin}
62 @section Darwin (OS X, iPhone)
63
64 The toolchain provided with Xcode is sufficient to build the basic
65 unacelerated code.
66
67 OS X on PowerPC or ARM (iPhone) requires a preprocessor from
68 @url{git://git.libav.org/gas-preprocessor.git} to build the optimized
69 assembly functions. Put the Perl script somewhere
70 in your PATH, Libav's configure will pick it up automatically.
71
72 OS X on AMD64 and x86 requires @command{yasm} to build most of the
73 optimized assembly functions @url{http://mxcl.github.com/homebrew/, Homebrew},
74 @url{http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-macos.xml, Gentoo Prefix}
75 or @url{http://www.macports.org, MacPorts} can easily provide it.
76
77
78 @chapter DOS
79
80 Using a cross-compiler is preferred for various reasons.
81 @url{http://www.delorie.com/howto/djgpp/linux-x-djgpp.html}
82
83
84 @chapter OS/2
85
86 For information about compiling Libav on OS/2 see
87 @url{http://www.edm2.com/index.php/FFmpeg}.
88
89
90 @chapter Windows
91
92 @section Native Windows compilation using MinGW or MinGW-w64
93
94 Libav can be built to run natively on Windows using the MinGW-w64
95 toolchain. Install the latest versions of MSYS2 and MinGW-w64 from
96 @url{http://msys2.github.io/} and/or @url{http://mingw-w64.sourceforge.net/}.
97 You can find detailed installation instructions in the download section and
98 the FAQ.
99
100 Notes:
101
102 @itemize
103
104 @item Native MSYS building is discouraged, MSYS2 provides a full mingw-w64
105 environment through @file{mingw64_shell.bat} or @file{mingw32_shell.bat}
106 that should be used instead of the environment provides by
107 @file{msys2_shell.bat}.
108
109 @item Building using MSYS2 can be sped up by disabling implicit rules in the
110 Makefile by calling @code{make -r} instead of plain @code{make}. This
111 speed up is close to non-existent for normal one-off builds and is only
112 noticeable when running make for a second time (for example during
113 @code{make install}).
114
115 @item In order to compile @command{avplay}, you must have the MinGW development
116 library of @uref{http://www.libsdl.org/, SDL} and @code{pkg-config} installed.
117
118 @item By using @code{./configure --enable-shared} when configuring Libav,
119 you can build all libraries as DLLs.
120
121 @end itemize
122
123 @subsection Native Windows compilation using MSYS2
124
125 The MSYS2 MinGW-w64 environment provides ready to use toolchains and dependencies
126 through @command{pacman}.
127
128 Make sure to use @file{mingw64_shell.bat} or @file{mingw32_shell.bat} to have
129 the correct MinGW-w64 environment.
130
131 @example
132 # normal msys2 packages
133 pacman -S make pkgconf diffutils
134
135 # mingw-w64 packages and toolchains
136 pacman -S mingw-w64-x86_64-yasm mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL
137 @end example
138
139 To target 32bit replace the @code{x86_64} with @code{i686} in the command above.
140
141 @section Microsoft Visual C++ or Intel C++ Compiler for Windows
142
143 Libav can be built with MSVC 2012 or earlier using a C99-to-C89 conversion utility
144 and wrapper, or with MSVC 2013 and ICL natively.
145
146 You will need the following prerequisites:
147
148 @itemize
149 @item @uref{https://github.com/libav/c99-to-c89/, C99-to-C89 Converter & Wrapper}
150 (if using MSVC 2012 or earlier)
151 @item @uref{http://code.google.com/p/msinttypes/, msinttypes}
152 (if using MSVC 2012 or earlier)
153 @item @uref{http://msys2.github.io/, MSYS2}
154 @item @uref{http://yasm.tortall.net/, YASM}
155 (Also available via MSYS2's package manager.)
156 @end itemize
157
158 To set up a proper environment in MSYS2, you need to run @code{msys_shell.bat} from
159 the Visual Studio or Intel Compiler command prompt.
160
161 Place @code{yasm.exe} somewhere in your @code{PATH}. If using MSVC 2012 or
162 earlier, place @code{c99wrap.exe} and @code{c99conv.exe} somewhere in your
163 @code{PATH} as well.
164
165 Next, make sure any other headers and libs you want to use, such as zlib, are
166 located in a spot that the compiler can see. Do so by modifying the @code{LIB}
167 and @code{INCLUDE} environment variables to include the @strong{Windows-style}
168 paths to these directories. Alternatively, you can try and use the
169 @code{--extra-cflags}/@code{--extra-ldflags} configure options. If using MSVC
170 2012 or earlier, place @code{inttypes.h} somewhere the compiler can see too.
171
172 Finally, run:
173
174 @example
175 For MSVC:
176 ./configure --toolchain=msvc
177
178 For ICL:
179 ./configure --toolchain=icl
180
181 make
182 make install
183 @end example
184
185 If you wish to compile shared libraries, add @code{--enable-shared} to your
186 configure options. Note that due to the way MSVC and ICL handle DLL imports and
187 exports, you cannot compile static and shared libraries at the same time, and
188 enabling shared libraries will automatically disable the static ones.
189
190 Notes:
191
192 @itemize
193
194 @item If you wish to build with zlib support, you will have to grab a compatible
195 zlib binary from somewhere, with an MSVC import lib, or if you wish to link
196 statically, you can follow the instructions below to build a compatible
197 @code{zlib.lib} with MSVC. Regardless of which method you use, you must still
198 follow step 3, or compilation will fail.
199 @enumerate
200 @item Grab the @uref{http://zlib.net/, zlib sources}.
201 @item Edit @code{win32/Makefile.msc} so that it uses -MT instead of -MD, since
202 this is how Libav is built as well.
203 @item Edit @code{zconf.h} and remove its inclusion of @code{unistd.h}. This gets
204 erroneously included when building Libav.
205 @item Run @code{nmake -f win32/Makefile.msc}.
206 @item Move @code{zlib.lib}, @code{zconf.h}, and @code{zlib.h} to somewhere MSVC
207 can see.
208 @end enumerate
209
210 @item Libav has been tested with the following on i686 and x86_64:
211 @itemize
212 @item Visual Studio 2010 Pro and Express
213 @item Visual Studio 2012 Pro and Express
214 @item Visual Studio 2013 Pro and Express
215 @item Intel Composer XE 2013
216 @item Intel Composer XE 2013 SP1
217 @end itemize
218 Anything else is not officially supported.
219
220 @end itemize
221
222 @subsection Linking to Libav with Microsoft Visual C++
223
224 If you plan to link with MSVC-built static libraries, you will need
225 to make sure you have @code{Runtime Library} set to
226 @code{Multi-threaded (/MT)} in your project's settings.
227
228 You will need to define @code{inline} to something MSVC understands:
229 @example
230 #define inline __inline
231 @end example
232
233 Also note, that as stated in @strong{Microsoft Visual C++}, you will need
234 an MSVC-compatible @uref{http://code.google.com/p/msinttypes/, inttypes.h}.
235
236 If you plan on using import libraries created by dlltool, you must
237 set @code{References} to @code{No (/OPT:NOREF)} under the linker optimization
238 settings, otherwise the resulting binaries will fail during runtime.
239 This is not required when using import libraries generated by @code{lib.exe}.
240 This issue is reported upstream at
241 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
242
243 To create import libraries that work with the @code{/OPT:REF} option
244 (which is enabled by default in Release mode), follow these steps:
245
246 @enumerate
247
248 @item Open the @emph{Visual Studio Command Prompt}.
249
250 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
251 which sets up the environment variables for the Visual C++ tools
252 (the standard location for this file is something like
253 @file{C:\Program Files (x86_\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat}).
254
255 @item Enter the @file{bin} directory where the created LIB and DLL files
256 are stored.
257
258 @item Generate new import libraries with @command{lib.exe}:
259
260 @example
261 lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
262 @end example
263
264 Replace @code{foo-version} and @code{foo} with the respective library names.
265
266 @end enumerate
267
268 @anchor{Cross compilation for Windows with Linux}
269 @section Cross compilation for Windows with Linux
270
271 You must use the MinGW cross compilation tools available at
272 @url{http://www.mingw.org/}.
273
274 Then configure Libav with the following options:
275 @example
276 ./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
277 @end example
278 (you can change the cross-prefix according to the prefix chosen for the
279 MinGW tools).
280
281 Then you can easily test Libav with @uref{http://www.winehq.com/, Wine}.
282
283 @section Compilation under Cygwin
284
285 Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
286 llrint() in its C library.
287
288 Install your Cygwin with all the "Base" packages, plus the
289 following "Devel" ones:
290 @example
291 binutils, gcc4-core, make, git, mingw-runtime, texi2html
292 @end example
293
294 In order to run FATE you will also need the following "Utils" packages:
295 @example
296 diffutils
297 @end example
298
299 If you want to build Libav with additional libraries, download Cygwin
300 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
301 @example
302 libogg-devel, libvorbis-devel
303 @end example
304
305 These library packages are only available from
306 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
307
308 @example
309 yasm, libSDL-devel, libfaac-devel, libgsm-devel, libmp3lame-devel,
310 libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-devel
311 @end example
312
313 The recommendation for x264 is to build it from source, as it evolves too
314 quickly for Cygwin Ports to be up to date.
315
316 @section Crosscompilation for Windows under Cygwin
317
318 With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
319
320 Just install your Cygwin as explained before, plus these additional
321 "Devel" packages:
322 @example
323 gcc-mingw-core, mingw-runtime, mingw-zlib
324 @end example
325
326 and add some special flags to your configure invocation.
327
328 For a static build run
329 @example
330 ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
331 @end example
332
333 and for a build with shared libraries
334 @example
335 ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
336 @end example
337
338 @chapter Plan 9
339
340 The native @uref{http://plan9.bell-labs.com/plan9/, Plan 9} compiler
341 does not implement all the C99 features needed by Libav so the gcc
342 port must be used.  Furthermore, a few items missing from the C
343 library and shell environment need to be fixed.
344
345 @itemize
346
347 @item GNU awk, grep, make, and sed
348
349 Working packages of these tools can be found at
350 @uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9}.
351 They can be installed with @uref{http://9front.org/, 9front's} @code{pkg}
352 utility by setting @code{pkgpath} to
353 @code{http://ports2plan9.googlecode.com/files/}.
354
355 @item Missing/broken @code{head} and @code{printf} commands
356
357 Replacements adequate for building Libav can be found in the
358 @code{compat/plan9} directory.  Place these somewhere they will be
359 found by the shell.  These are not full implementations of the
360 commands and are @emph{not} suitable for general use.
361
362 @item Missing C99 @code{stdint.h} and @code{inttypes.h}
363
364 Replacement headers are available from
365 @url{http://code.google.com/p/plan9front/issues/detail?id=152}.
366
367 @item Missing or non-standard library functions
368
369 Some functions in the C library are missing or incomplete.  The
370 @code{@uref{http://ports2plan9.googlecode.com/files/gcc-apelibs-1207.tbz,
371 gcc-apelibs-1207}} package from
372 @uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9}
373 includes an updated C library, but installing the full package gives
374 unusable executables.  Instead, keep the files from @code{gccbin.tgz}
375 under @code{/386/lib/gnu}.  From the @code{libc.a} archive in the
376 @code{gcc-apelibs-1207} package, extract the following object files and
377 turn them into a library:
378
379 @itemize
380 @item @code{strerror.o}
381 @item @code{strtoll.o}
382 @item @code{snprintf.o}
383 @item @code{vsnprintf.o}
384 @item @code{vfprintf.o}
385 @item @code{_IO_getc.o}
386 @item @code{_IO_putc.o}
387 @end itemize
388
389 Use the @code{--extra-libs} option of @code{configure} to inform the
390 build system of this library.
391
392 @item FPU exceptions enabled by default
393
394 Unlike most other systems, Plan 9 enables FPU exceptions by default.
395 These must be disabled before calling any Libav functions.  While the
396 included tools will do this automatically, other users of the
397 libraries must do it themselves.
398
399 @end itemize
400
401 @bye