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