avformat: add fields to AVProgram/AVStream for PMT change tracking
[ffmpeg.git] / doc / platform.texi
index d15c574..4090b85 100644 (file)
@@ -1,8 +1,9 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
-@settitle Platform Specific information
+@settitle Platform Specific Information
 @titlepage
-@center @titlefont{Platform Specific information}
+@center @titlefont{Platform Specific Information}
 @end titlepage
 
 @top
@@ -24,14 +25,28 @@ If not, then you should install a different compiler that has no
 hard-coded path to gas. In the worst case pass @code{--disable-asm}
 to configure.
 
+@section Advanced linking configuration
+
+If you compiled FFmpeg libraries statically and you want to use them to
+build your own shared library, you may need to force PIC support (with
+@code{--enable-pic} during FFmpeg configure) and add the following option
+to your project LDFLAGS:
+
+@example
+-Wl,-Bsymbolic
+@end example
+
+If your target platform requires position independent binaries, you should
+pass the correct linking flag (e.g. @code{-pie}) to @code{--extra-ldexeflags}.
+
 @section BSD
 
 BSD make will not build FFmpeg, you need to install and use GNU Make
-(@file{gmake}).
+(@command{gmake}).
 
 @section (Open)Solaris
 
-GNU Make is required to build FFmpeg, so you have to invoke (@file{gmake}),
+GNU Make is required to build FFmpeg, so you have to invoke (@command{gmake}),
 standard Solaris Make will not work. When building with a non-c99 front-end
 (gcc, generic suncc) add either @code{--extra-libs=/usr/lib/values-xpg6.o}
 or @code{--extra-libs=/usr/lib/64/values-xpg6.o} to the configure options
@@ -45,20 +60,22 @@ bash ./configure
 @end example
 
 @anchor{Darwin}
-@section Darwin (OSX, iPhone)
+@section Darwin (Mac OS X, iPhone)
 
 The toolchain provided with Xcode is sufficient to build the basic
-unacelerated code.
+unaccelerated code.
 
-OSX on PowerPC or ARM (iPhone) requires a preprocessor from
-@url{http://github.com/yuvi/gas-preprocessor} to build the optimized
-assembler functions. Just download the Perl script and put it somewhere
+Mac OS X on PowerPC or ARM (iPhone) requires a preprocessor from
+@url{https://github.com/FFmpeg/gas-preprocessor} or
+@url{https://github.com/yuvi/gas-preprocessor}(currently outdated) to build the optimized
+assembly functions. Put the Perl script somewhere
 in your PATH, FFmpeg's configure will pick it up automatically.
 
-OSX on amd64 and x86 requires @command{yasm} to build most of the
-optimized assembler functions @url{http://mxcl.github.com/homebrew/, Homebrew},
-@url{http://www.gentoo.org/proj/en/gentoo-alt/prefix/bootstrap-macos.xml, Gentoo Prefix}
-or @url{http://www.macports.org, MacPorts} can easily provide it.
+Mac OS X on amd64 and x86 requires @command{nasm} to build most of the
+optimized assembly functions. @uref{http://www.finkproject.org/, Fink},
+@uref{https://wiki.gentoo.org/wiki/Project:Prefix, Gentoo Prefix},
+@uref{https://mxcl.github.com/homebrew/, Homebrew}
+or @uref{http://www.macports.org, MacPorts} can easily provide it.
 
 
 @chapter DOS
@@ -76,46 +93,33 @@ For information about compiling FFmpeg on OS/2 see
 @chapter Windows
 
 To get help and instructions for building FFmpeg under Windows, check out
-the FFmpeg Windows Help Forum at
-@url{http://ffmpeg.arrozcru.org/}.
-
-@section Native Windows compilation
+the FFmpeg Windows Help Forum at @url{http://ffmpeg.zeranoe.com/forum/}.
 
-FFmpeg can be built to run natively on Windows using the MinGW tools. Install
-the latest versions of MSYS and MinGW from @url{http://www.mingw.org/}.
-You can find detailed installation instructions in the download
-section and the FAQ.
+@section Native Windows compilation using MinGW or MinGW-w64
 
-FFmpeg does not build out-of-the-box with the packages the automated MinGW
-installer provides. It also requires coreutils to be installed and many other
-packages updated to the latest version. The minimum version for some packages
-are listed below:
-
-@itemize
-@item bash 3.1
-@item msys-make 3.81-2 (note: not mingw32-make)
-@item w32api 3.13
-@item mingw-runtime 3.15
-@end itemize
-
-FFmpeg automatically passes @code{-fno-common} to the compiler to work around
-a GCC bug (see @url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37216}).
+FFmpeg can be built to run natively on Windows using the MinGW-w64
+toolchain. Install the latest versions of MSYS2 and MinGW-w64 from
+@url{http://msys2.github.io/} and/or @url{http://mingw-w64.sourceforge.net/}.
+You can find detailed installation instructions in the download section and
+the FAQ.
 
 Notes:
 
 @itemize
 
-@item Building natively using MSYS can be sped up by disabling implicit rules
-in the Makefile by calling @code{make -r} instead of plain @code{make}. This
+@item Building for the MSYS environment is discouraged, MSYS2 provides a full
+MinGW-w64 environment through @file{mingw64_shell.bat} or
+@file{mingw32_shell.bat} that should be used instead of the environment
+provided by @file{msys2_shell.bat}.
+
+@item Building using MSYS2 can be sped up by disabling implicit rules in the
+Makefile by calling @code{make -r} instead of plain @code{make}. This
 speed up is close to non-existent for normal one-off builds and is only
-noticeable when running make for a second time (for example in
+noticeable when running make for a second time (for example during
 @code{make install}).
 
 @item In order to compile FFplay, you must have the MinGW development library
-of @uref{http://www.libsdl.org/, SDL}.
-Edit the @file{bin/sdl-config} script so that it points to the correct prefix
-where SDL was installed. Verify that @file{sdl-config} can be launched from
-the MSYS command line.
+of @uref{http://www.libsdl.org/, SDL} and @code{pkg-config} installed.
 
 @item By using @code{./configure --enable-shared} when configuring FFmpeg,
 you can build the FFmpeg libraries (e.g. libavutil, libavcodec,
@@ -123,147 +127,114 @@ libavformat) as DLLs.
 
 @end itemize
 
-@section Microsoft Visual C++ compatibility
-
-As stated in the FAQ, FFmpeg will not compile under MSVC++. However, if you
-want to use the libav* libraries in your own applications, you can still
-compile those applications using MSVC++. But the libav* libraries you link
-to @emph{must} be built with MinGW. However, you will not be able to debug
-inside the libav* libraries, since MSVC++ does not recognize the debug
-symbols generated by GCC.
-We strongly recommend you to move over from MSVC++ to MinGW tools.
-
-This description of how to use the FFmpeg libraries with MSVC++ is based on
-Microsoft Visual C++ 2005 Express Edition. If you have a different version,
-you might have to modify the procedures slightly.
+@subsection Native Windows compilation using MSYS2
 
-@subsection Using static libraries
+The MSYS2 MinGW-w64 environment provides ready to use toolchains and dependencies
+through @command{pacman}.
 
-Assuming you have just built and installed FFmpeg in @file{/usr/local}.
+Make sure to use @file{mingw64_shell.bat} or @file{mingw32_shell.bat} to have
+the correct MinGW-w64 environment. The default install provides shortcuts to
+them under @command{MinGW-w64 Win64 Shell} and @command{MinGW-w64 Win32 Shell}.
 
-@enumerate
-
-@item Create a new console application ("File / New / Project") and then
-select "Win32 Console Application". On the appropriate page of the
-Application Wizard, uncheck the "Precompiled headers" option.
-
-@item Write the source code for your application, or, for testing, just
-copy the code from an existing sample application into the source file
-that MSVC++ has already created for you. For example, you can copy
-@file{libavformat/output-example.c} from the FFmpeg distribution.
-
-@item Open the "Project / Properties" dialog box. In the "Configuration"
-combo box, select "All Configurations" so that the changes you make will
-affect both debug and release builds. In the tree view on the left hand
-side, select "C/C++ / General", then edit the "Additional Include
-Directories" setting to contain the path where the FFmpeg includes were
-installed (i.e. @file{c:\msys\1.0\local\include}).
-Do not add MinGW's include directory here, or the include files will
-conflict with MSVC's.
-
-@item Still in the "Project / Properties" dialog box, select
-"Linker / General" from the tree view and edit the
-"Additional Library Directories" setting to contain the @file{lib}
-directory where FFmpeg was installed (i.e. @file{c:\msys\1.0\local\lib}),
-the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
-and the directory where MinGW's GCC libs are installed
-(i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
-"Linker / Input" from the tree view, and add the files @file{libavformat.a},
-@file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
-@file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
-to the end of "Additional Dependencies".
-
-@item Now, select "C/C++ / Code Generation" from the tree view. Select
-"Debug" in the "Configuration" combo box. Make sure that "Runtime
-Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
-the "Configuration" combo box and make sure that "Runtime Library" is
-set to "Multi-threaded DLL".
-
-@item Click "OK" to close the "Project / Properties" dialog box.
-
-@item MSVC++ lacks some C99 header files that are fundamental for FFmpeg.
-Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
-and install it in MSVC++'s include directory
-(i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
-
-@item MSVC++ also does not understand the @code{inline} keyword used by
-FFmpeg, so you must add this line before @code{#include}ing libav*:
 @example
-#define inline _inline
+# normal msys2 packages
+pacman -S make pkgconf diffutils
+
+# mingw-w64 packages and toolchains
+pacman -S mingw-w64-x86_64-nasm mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2
 @end example
 
-@item Build your application, everything should work.
+To target 32 bits replace @code{x86_64} with @code{i686} in the command above.
 
-@end enumerate
+@section Microsoft Visual C++ or Intel C++ Compiler for Windows
 
-@subsection Using shared libraries
+FFmpeg can be built with MSVC 2013 or later.
 
-This is how to create DLL and LIB files that are compatible with MSVC++:
+You will need the following prerequisites:
 
-@enumerate
-
-@item Add a call to @file{vcvars32.bat} (which sets up the environment
-variables for the Visual C++ tools) as the first line of @file{msys.bat}.
-The standard location for @file{vcvars32.bat} is
-@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
-and the standard location for @file{msys.bat} is @file{C:\msys\1.0\msys.bat}.
-If this corresponds to your setup, add the following line as the first line
-of @file{msys.bat}:
+@itemize
+@item @uref{http://msys2.github.io/, MSYS2}
+@item @uref{http://www.nasm.us/, NASM}
+(Also available via MSYS2's package manager.)
+@end itemize
 
-@example
-call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
-@end example
+To set up a proper environment in MSYS2, you need to run @code{msys_shell.bat} from
+the Visual Studio or Intel Compiler command prompt.
 
-Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
-and run @file{c:\msys\1.0\msys.bat} from there.
+Place @code{yasm.exe} somewhere in your @code{PATH}.
 
-@item Within the MSYS shell, run @code{lib.exe}. If you get a help message
-from @file{Microsoft (R) Library Manager}, this means your environment
-variables are set up correctly, the @file{Microsoft (R) Library Manager}
-is on the path and will be used by FFmpeg to create
-MSVC++-compatible import libraries.
+Next, make sure any other headers and libs you want to use, such as zlib, are
+located in a spot that the compiler can see. Do so by modifying the @code{LIB}
+and @code{INCLUDE} environment variables to include the @strong{Windows-style}
+paths to these directories. Alternatively, you can try to use the
+@code{--extra-cflags}/@code{--extra-ldflags} configure options.
 
-@item Build FFmpeg with
+Finally, run:
 
 @example
-./configure --enable-shared
+For MSVC:
+./configure --toolchain=msvc
+
+For ICL:
+./configure --toolchain=icl
+
 make
 make install
 @end example
 
-Your install path (@file{/usr/local/} by default) should now have the
-necessary DLL and LIB files under the @file{bin} directory.
-
-Alternatively, build the libraries with a cross compiler, according to
-the instructions below in @ref{Cross compilation for Windows with Linux}.
-
-To use those files with MSVC++, do the same as you would do with
-the static libraries, as described above. But in Step 4,
-you should only need to add the directory where the LIB files are installed
-(i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
-installed in the @file{bin} directory. And instead of adding the static
-libraries (@file{libxxx.a} files) you should add the MSVC import libraries
-(@file{avcodec.lib}, @file{avformat.lib}, and
-@file{avutil.lib}). Note that you should not use the GCC import
-libraries (@file{libxxx.dll.a} files), as these will give you undefined
-reference errors. There should be no need for @file{libmingwex.a},
-@file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
-statically linked into the DLLs.
-
-FFmpeg headers do not declare global data for Windows DLLs through the usual
-dllexport/dllimport interface. Such data will be exported properly while
-building, but to use them in your MSVC++ code you will have to edit the
-appropriate headers and mark the data as dllimport. For example, in
-libavutil/pixdesc.h you should have:
+If you wish to compile shared libraries, add @code{--enable-shared} to your
+configure options. Note that due to the way MSVC and ICL handle DLL imports and
+exports, you cannot compile static and shared libraries at the same time, and
+enabling shared libraries will automatically disable the static ones.
+
+Notes:
+
+@itemize
+
+@item If you wish to build with zlib support, you will have to grab a compatible
+zlib binary from somewhere, with an MSVC import lib, or if you wish to link
+statically, you can follow the instructions below to build a compatible
+@code{zlib.lib} with MSVC. Regardless of which method you use, you must still
+follow step 3, or compilation will fail.
+@enumerate
+@item Grab the @uref{http://zlib.net/, zlib sources}.
+@item Edit @code{win32/Makefile.msc} so that it uses -MT instead of -MD, since
+this is how FFmpeg is built as well.
+@item Edit @code{zconf.h} and remove its inclusion of @code{unistd.h}. This gets
+erroneously included when building FFmpeg.
+@item Run @code{nmake -f win32/Makefile.msc}.
+@item Move @code{zlib.lib}, @code{zconf.h}, and @code{zlib.h} to somewhere MSVC
+can see.
+@end enumerate
+
+@item FFmpeg has been tested with the following on i686 and x86_64:
+@itemize
+@item Visual Studio 2013 Pro and Express
+@item Intel Composer XE 2013
+@item Intel Composer XE 2013 SP1
+@end itemize
+Anything else is not officially supported.
+
+@end itemize
+
+@subsection Linking to FFmpeg with Microsoft Visual C++
+
+If you plan to link with MSVC-built static libraries, you will need
+to make sure you have @code{Runtime Library} set to
+@code{Multi-threaded (/MT)} in your project's settings.
+
+You will need to define @code{inline} to something MSVC understands:
 @example
-extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[];
+#define inline __inline
 @end example
 
-Note that using import libraries created by dlltool requires
-the linker optimization option to be set to
-"References: Keep Unreferenced Data (@code{/OPT:NOREF})", otherwise
-the resulting binaries will fail during runtime. This isn't
-required when using import libraries generated by lib.exe.
+Also note, that as stated in @strong{Microsoft Visual C++}, you will need
+an MSVC-compatible @uref{http://code.google.com/p/msinttypes/, inttypes.h}.
+
+If you plan on using import libraries created by dlltool, you must
+set @code{References} to @code{No (/OPT:NOREF)} under the linker optimization
+settings, otherwise the resulting binaries will fail during runtime.
+This is not required when using import libraries generated by @code{lib.exe}.
 This issue is reported upstream at
 @url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}.
 
@@ -272,27 +243,24 @@ To create import libraries that work with the @code{/OPT:REF} option
 
 @enumerate
 
-@item Open @file{Visual Studio 2005 Command Prompt}.
+@item Open the @emph{Visual Studio Command Prompt}.
 
 Alternatively, in a normal command line prompt, call @file{vcvars32.bat}
 which sets up the environment variables for the Visual C++ tools
-(the standard location for this file is
-@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat}).
+(the standard location for this file is something like
+@file{C:\Program Files (x86_\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat}).
 
 @item Enter the @file{bin} directory where the created LIB and DLL files
 are stored.
 
-@item Generate new import libraries with @file{lib.exe}:
+@item Generate new import libraries with @command{lib.exe}:
 
 @example
-lib /machine:i386 /def:..\lib\avcodec-53.def  /out:avcodec.lib
-lib /machine:i386 /def:..\lib\avdevice-53.def /out:avdevice.lib
-lib /machine:i386 /def:..\lib\avfilter-2.def  /out:avfilter.lib
-lib /machine:i386 /def:..\lib\avformat-53.def /out:avformat.lib
-lib /machine:i386 /def:..\lib\avutil-51.def   /out:avutil.lib
-lib /machine:i386 /def:..\lib\swscale-2.def   /out:swscale.lib
+lib /machine:i386 /def:..\lib\foo-version.def  /out:foo.lib
 @end example
 
+Replace @code{foo-version} and @code{foo} with the respective library names.
+
 @end enumerate
 
 @anchor{Cross compilation for Windows with Linux}
@@ -318,29 +286,14 @@ llrint() in its C library.
 Install your Cygwin with all the "Base" packages, plus the
 following "Devel" ones:
 @example
-binutils, gcc4-core, make, git, mingw-runtime, texi2html
+binutils, gcc4-core, make, git, mingw-runtime, texinfo
 @end example
 
-And the following "Utils" one:
+In order to run FATE you will also need the following "Utils" packages:
 @example
 diffutils
 @end example
 
-Then run
-
-@example
-./configure
-@end example
-
-to make a static build.
-
-The current @code{gcc4-core} package is buggy and needs this flag to build
-shared libraries:
-
-@example
-./configure --enable-shared --disable-static --extra-cflags=-fno-reorder-functions
-@end example
-
 If you want to build FFmpeg with additional libraries, download Cygwin
 "Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
 @example
@@ -351,16 +304,12 @@ These library packages are only available from
 @uref{http://sourceware.org/cygwinports/, Cygwin Ports}:
 
 @example
-yasm, libSDL-devel, libdirac-devel, libfaac-devel, libaacplus-devel, libgsm-devel,
-libmp3lame-devel, libschroedinger1.0-devel, speex-devel, libtheora-devel,
-libxvidcore-devel
+yasm, libSDL-devel, libgsm-devel, libmp3lame-devel,
+speex-devel, libtheora-devel, libxvidcore-devel
 @end example
 
-The recommendation for libnut and x264 is to build them from source by
-yourself, as they evolve too quickly for Cygwin Ports to be up to date.
-
-Cygwin 1.7.x has IPv6 support. You can add IPv6 to Cygwin 1.5.x by means
-of the @code{libgetaddrinfo-devel} package, available at Cygwin Ports.
+The recommendation for x264 is to build it from source, as it evolves too
+quickly for Cygwin Ports to be up to date.
 
 @section Crosscompilation for Windows under Cygwin