cosmetics: Fix spelling mistakes
[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 unaccelerated 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 Building for the MSYS environment is discouraged, MSYS2 provides a full
105 MinGW-w64 environment through @file{mingw64_shell.bat} or
106 @file{mingw32_shell.bat} that should be used instead of the environment
107 provided by @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. The default install provides shortcuts to
130 them under @command{MinGW-w64 Win64 Shell} and @command{MinGW-w64 Win32 Shell}.
131
132 @example
133 # normal msys2 packages
134 pacman -S make pkgconf diffutils
135
136 # mingw-w64 packages and toolchains
137 pacman -S mingw-w64-x86_64-yasm mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL
138 @end example
139
140 To target 32 bits replace @code{x86_64} with @code{i686} in the command above.
141
142 @section Microsoft Visual C++ or Intel C++ Compiler for Windows
143
144 Libav can be built with MSVC 2012 or earlier using a C99-to-C89 conversion utility
145 and wrapper, or with MSVC 2013 and ICL natively.
146
147 You will need the following prerequisites:
148
149 @itemize
150 @item @uref{https://github.com/libav/c99-to-c89/, C99-to-C89 Converter & Wrapper}
151 (if using MSVC 2012 or earlier)
152 @item @uref{http://code.google.com/p/msinttypes/, msinttypes}
153 (if using MSVC 2012 or earlier)
154 @item @uref{http://msys2.github.io/, MSYS2}
155 @item @uref{http://yasm.tortall.net/, YASM}
156 (Also available via MSYS2's package manager.)
157 @end itemize
158
159 To set up a proper environment in MSYS2, you need to run @code{msys_shell.bat} from
160 the Visual Studio or Intel Compiler command prompt.
161
162 Place @code{yasm.exe} somewhere in your @code{PATH}. If using MSVC 2012 or
163 earlier, place @code{c99wrap.exe} and @code{c99conv.exe} somewhere in your
164 @code{PATH} as well.
165
166 Next, make sure any other headers and libs you want to use, such as zlib, are
167 located in a spot that the compiler can see. Do so by modifying the @code{LIB}
168 and @code{INCLUDE} environment variables to include the @strong{Windows-style}
169 paths to these directories. Alternatively, you can try and use the
170 @code{--extra-cflags}/@code{--extra-ldflags} configure options. If using MSVC
171 2012 or earlier, place @code{inttypes.h} somewhere the compiler can see too.
172
173 Finally, run:
174
175 @example
176 For MSVC:
177 ./configure --toolchain=msvc
178
179 For ICL:
180 ./configure --toolchain=icl
181
182 make
183 make install
184 @end example
185
186 If you wish to compile shared libraries, add @code{--enable-shared} to your
187 configure options. Note that due to the way MSVC and ICL handle DLL imports and
188 exports, you cannot compile static and shared libraries at the same time, and
189 enabling shared libraries will automatically disable the static ones.
190
191 Notes:
192
193 @itemize
194
195 @item If you wish to build with zlib support, you will have to grab a compatible
196 zlib binary from somewhere, with an MSVC import lib, or if you wish to link
197 statically, you can follow the instructions below to build a compatible
198 @code{zlib.lib} with MSVC. Regardless of which method you use, you must still
199 follow step 3, or compilation will fail.
200 @enumerate
201 @item Grab the @uref{http://zlib.net/, zlib sources}.
202 @item Edit @code{win32/Makefile.msc} so that it uses -MT instead of -MD, since
203 this is how Libav is built as well.
204 @item Edit @code{zconf.h} and remove its inclusion of @code{unistd.h}. This gets
205 erroneously included when building Libav.
206 @item Run @code{nmake -f win32/Makefile.msc}.
207 @item Move @code{zlib.lib}, @code{zconf.h}, and @code{zlib.h} to somewhere MSVC
208 can see.
209 @end enumerate
210
211 @item Libav has been tested with the following on i686 and x86_64:
212 @itemize
213 @item Visual Studio 2010 Pro and Express
214 @item Visual Studio 2012 Pro and Express
215 @item Visual Studio 2013 Pro and Express
216 @item Intel Composer XE 2013
217 @item Intel Composer XE 2013 SP1
218 @end itemize
219 Anything else is not officially supported.
220
221 @end itemize
222
223 @subsection Linking to Libav with Microsoft Visual C++
224
225 If you plan to link with MSVC-built static libraries, you will need
226 to make sure you have @code{Runtime Library} set to
227 @code{Multi-threaded (/MT)} in your project's settings.
228
229 You will need to define @code{inline} to something MSVC understands:
230 @example
231 #define inline __inline
232 @end example
233
234 Also note, that as stated in @strong{Microsoft Visual C++}, you will need
235 an MSVC-compatible @uref{http://code.google.com/p/msinttypes/, inttypes.h}.
236
237 If you plan on using import libraries created by dlltool, you must
238 set @code{References} to @code{No (/OPT:NOREF)} under the linker optimization
239 settings, otherwise the resulting binaries will fail during runtime.
240 This is not required when using import libraries generated by @code{lib.exe}.
241 This issue is reported upstream at
242 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
243
244 To create import libraries that work with the @code{/OPT:REF} option
245 (which is enabled by default in Release mode), follow these steps:
246
247 @enumerate
248
249 @item Open the @emph{Visual Studio Command Prompt}.
250
251 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
252 which sets up the environment variables for the Visual C++ tools
253 (the standard location for this file is something like
254 @file{C:\Program Files (x86_\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat}).
255
256 @item Enter the @file{bin} directory where the created LIB and DLL files
257 are stored.
258
259 @item Generate new import libraries with @command{lib.exe}:
260
261 @example
262 lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
263 @end example
264
265 Replace @code{foo-version} and @code{foo} with the respective library names.
266
267 @end enumerate
268
269 @anchor{Cross compilation for Windows with Linux}
270 @section Cross compilation for Windows with Linux
271
272 You must use the MinGW cross compilation tools available at
273 @url{http://www.mingw.org/}.
274
275 Then configure Libav with the following options:
276 @example
277 ./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
278 @end example
279 (you can change the cross-prefix according to the prefix chosen for the
280 MinGW tools).
281
282 Then you can easily test Libav with @uref{http://www.winehq.com/, Wine}.
283
284 @section Compilation under Cygwin
285
286 Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
287 llrint() in its C library.
288
289 Install your Cygwin with all the "Base" packages, plus the
290 following "Devel" ones:
291 @example
292 binutils, gcc4-core, make, git, mingw-runtime, texi2html
293 @end example
294
295 In order to run FATE you will also need the following "Utils" packages:
296 @example
297 diffutils
298 @end example
299
300 If you want to build Libav with additional libraries, download Cygwin
301 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
302 @example
303 libogg-devel, libvorbis-devel
304 @end example
305
306 These library packages are only available from
307 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
308
309 @example
310 yasm, libSDL-devel, libfaac-devel, libgsm-devel, libmp3lame-devel,
311 libschroedinger1.0-devel, speex-devel, libtheora-devel, libxvidcore-devel
312 @end example
313
314 The recommendation for x264 is to build it from source, as it evolves too
315 quickly for Cygwin Ports to be up to date.
316
317 @section Crosscompilation for Windows under Cygwin
318
319 With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
320
321 Just install your Cygwin as explained before, plus these additional
322 "Devel" packages:
323 @example
324 gcc-mingw-core, mingw-runtime, mingw-zlib
325 @end example
326
327 and add some special flags to your configure invocation.
328
329 For a static build run
330 @example
331 ./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
332 @end example
333
334 and for a build with shared libraries
335 @example
336 ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
337 @end example
338
339 @chapter Plan 9
340
341 The native @uref{http://plan9.bell-labs.com/plan9/, Plan 9} compiler
342 does not implement all the C99 features needed by Libav so the gcc
343 port must be used.  Furthermore, a few items missing from the C
344 library and shell environment need to be fixed.
345
346 @itemize
347
348 @item GNU awk, grep, make, and sed
349
350 Working packages of these tools can be found at
351 @uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9}.
352 They can be installed with @uref{http://9front.org/, 9front's} @code{pkg}
353 utility by setting @code{pkgpath} to
354 @code{http://ports2plan9.googlecode.com/files/}.
355
356 @item Missing/broken @code{head} and @code{printf} commands
357
358 Replacements adequate for building Libav can be found in the
359 @code{compat/plan9} directory.  Place these somewhere they will be
360 found by the shell.  These are not full implementations of the
361 commands and are @emph{not} suitable for general use.
362
363 @item Missing C99 @code{stdint.h} and @code{inttypes.h}
364
365 Replacement headers are available from
366 @url{http://code.google.com/p/plan9front/issues/detail?id=152}.
367
368 @item Missing or non-standard library functions
369
370 Some functions in the C library are missing or incomplete.  The
371 @code{@uref{http://ports2plan9.googlecode.com/files/gcc-apelibs-1207.tbz,
372 gcc-apelibs-1207}} package from
373 @uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9}
374 includes an updated C library, but installing the full package gives
375 unusable executables.  Instead, keep the files from @code{gccbin.tgz}
376 under @code{/386/lib/gnu}.  From the @code{libc.a} archive in the
377 @code{gcc-apelibs-1207} package, extract the following object files and
378 turn them into a library:
379
380 @itemize
381 @item @code{strerror.o}
382 @item @code{strtoll.o}
383 @item @code{snprintf.o}
384 @item @code{vsnprintf.o}
385 @item @code{vfprintf.o}
386 @item @code{_IO_getc.o}
387 @item @code{_IO_putc.o}
388 @end itemize
389
390 Use the @code{--extra-libs} option of @code{configure} to inform the
391 build system of this library.
392
393 @item FPU exceptions enabled by default
394
395 Unlike most other systems, Plan 9 enables FPU exceptions by default.
396 These must be disabled before calling any Libav functions.  While the
397 included tools will do this automatically, other users of the
398 libraries must do it themselves.
399
400 @end itemize
401
402 @bye