X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fplatform.texi;h=999a5f19f1ab6f23c6123fb667526e7834d93e48;hb=2026eb1408a718c37835eb4b258c63714ab3205e;hp=7ec7cb3dd081dbb383e46ce7093e48ae9ef37c38;hpb=5ea20630b4cc96a6538a6a11b08698debe3a303a;p=ffmpeg diff --git a/doc/platform.texi b/doc/platform.texi index 7ec7cb3dd08..999a5f19f1a 100644 --- a/doc/platform.texi +++ b/doc/platform.texi @@ -27,11 +27,11 @@ to configure. @section BSD BSD make will not build Libav, you need to install and use GNU Make -(@file{gmake}). +(@command{gmake}). @section (Open)Solaris -GNU Make is required to build Libav, so you have to invoke (@file{gmake}), +GNU Make is required to build Libav, 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 @@ -75,27 +75,13 @@ For information about compiling Libav on OS/2 see @chapter Windows -@section Native Windows compilation +@section Native Windows compilation using MinGW or MinGW-w64 -Libav 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. - -Libav 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 - -Libav 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}). +Libav can be built to run natively on Windows using the MinGW or MinGW-w64 +toolchains. Install the latest versions of MSYS and MinGW or MinGW-w64 from +@url{http://www.mingw.org/} or @url{http://mingw-w64.sourceforge.net/}. +You can find detailed installation instructions in the download section and +the FAQ. Notes: @@ -104,138 +90,116 @@ Notes: @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 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 AVplay, 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 Libav, -you can build libavutil, libavcodec and libavformat as DLLs. +you can build all libraries as DLLs. @end itemize -@section Microsoft Visual C++ compatibility +@section Microsoft Visual C++ -As stated in the FAQ, Libav 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. +Libav can be built with MSVC using a C99-to-C89 conversion utility and +wrapper. -This description of how to use the Libav 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. +You will need the following prerequisites: -@subsection Using static libraries +@itemize +@item @uref{https://github.com/libav/c99-to-c89/, C99-to-C89 Converter & Wrapper} +@item @uref{http://code.google.com/p/msinttypes/, msinttypes} +@item @uref{http://www.mingw.org/, MSYS} +@item @uref{http://yasm.tortall.net/, YASM} +@item @uref{http://gnuwin32.sourceforge.net/packages/bc.htm, bc for Windows} if +you want to run @uref{fate.html, FATE}. +@end itemize -Assuming you have just built and installed Libav in @file{/usr/local}. +To set up a proper MSVC environment in MSYS, you simply need to run +@code{msys.bat} from the Visual Studio command prompt. -@enumerate +Place @code{makedef}, @code{c99wrap.exe}, @code{c99conv.exe}, and @code{yasm.exe} +somewhere in your @code{PATH}. + +Next, make sure @code{inttypes.h} and any other headers and libs you want to use +are located in a spot that MSVC can see. Do so by modifying the @code{LIB} and +@code{INCLUDE} environment variables to include the @strong{Windows} paths to +these directories. Alternatively, you can try and use the +@code{--extra-cflags}/@code{--extra-ldflags} configure options. + +Finally, run: -@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 Libav 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 Libav 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 Libav 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 Libav. -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 -Libav, so you must add this line before @code{#include}ing libav*: @example -#define inline _inline +./configure --toolchain=msvc +make +make install @end example -@item Build your application, everything should work. +If you wish to compile static libraries, add @code{--enable-shared} to your +configure options. Note that due to the way MSVC handles 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. -@end enumerate +Notes: -@subsection Using shared libraries +@itemize -This is how to create DLL and LIB files that are compatible with MSVC++: +@item It is possible that coreutils' @code{link.exe} conflicts with MSVC's linker. +You can find out by running @code{which link} to see which @code{link.exe} you +are using. If it is located at @code{/bin/link.exe}, then you have the wrong one +in your @code{PATH}. Either move or remove that copy, or make sure MSVC's +@code{link.exe} takes precedence in your @code{PATH} over coreutils'. + +@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 Libav is built as well. +@item Edit @code{zconf.h} and remove its inclusion of @code{unistd.h}. This gets +erroneously included when building Libav. +@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 -Within the MSYS shell, build Libav with +@item Libav has been tested with Visual Studio 2010 and 2012, Pro and Express. +Anything else is not officially supported. -@example -./configure --enable-shared -make -make install -@end example +@end itemize -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. +@subsection Linking to Libav 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. Libav 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 +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: @example extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[]; @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. +You will also need to define @code{inline} to something MSVC understands: +@example +#define inline __inline +@end example + +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}. @@ -244,27 +208,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} @@ -293,24 +254,9 @@ following "Devel" ones: binutils, gcc4-core, make, git, mingw-runtime, texi2html @end example -And the following "Utils" one: -@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: - +In order to run FATE you will also need the following "Utils" packages: @example -./configure --enable-shared --disable-static --extra-cflags=-fno-reorder-functions +bc, diffutils @end example If you want to build Libav with additional libraries, download Cygwin @@ -323,16 +269,12 @@ These library packages are only available from @uref{http://sourceware.org/cygwinports/, Cygwin Ports}: @example -yasm, libSDL-devel, libdirac-devel, libfaac-devel, libgsm-devel, -libmp3lame-devel, libschroedinger1.0-devel, speex-devel, libtheora-devel, -libxvidcore-devel +yasm, libSDL-devel, libfaac-devel, libgsm-devel, libmp3lame-devel, +libschroedinger1.0-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 @@ -356,4 +298,67 @@ and for a build with shared libraries ./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin @end example +@chapter Plan 9 + +The native @uref{http://plan9.bell-labs.com/plan9/, Plan 9} compiler +does not implement all the C99 features needed by Libav so the gcc +port must be used. Furthermore, a few items missing from the C +library and shell environment need to be fixed. + +@itemize + +@item GNU awk, grep, make, and sed + +Working packages of these tools can be found at +@uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9}. +They can be installed with @uref{http://9front.org/, 9front's} @code{pkg} +utility by setting @code{pkgpath} to +@code{http://ports2plan9.googlecode.com/files/}. + +@item Missing/broken @code{head} and @code{printf} commands + +Replacements adequate for building Libav can be found in the +@code{compat/plan9} directory. Place these somewhere they will be +found by the shell. These are not full implementations of the +commands and are @emph{not} suitable for general use. + +@item Missing C99 @code{stdint.h} and @code{inttypes.h} + +Replacement headers are available from +@url{http://code.google.com/p/plan9front/issues/detail?id=152}. + +@item Missing or non-standard library functions + +Some functions in the C library are missing or incomplete. The +@code{@uref{http://ports2plan9.googlecode.com/files/gcc-apelibs-1207.tbz, +gcc-apelibs-1207}} package from +@uref{http://code.google.com/p/ports2plan9/downloads/list, ports2plan9} +includes an updated C library, but installing the full package gives +unusable executables. Instead, keep the files from @code{gccbin.tgz} +under @code{/386/lib/gnu}. From the @code{libc.a} archive in the +@code{gcc-apelibs-1207} package, extract the following object files and +turn them into a library: + +@itemize +@item @code{strerror.o} +@item @code{strtoll.o} +@item @code{snprintf.o} +@item @code{vsnprintf.o} +@item @code{vfprintf.o} +@item @code{_IO_getc.o} +@item @code{_IO_putc.o} +@end itemize + +Use the @code{--extra-libs} option of @code{configure} to inform the +build system of this library. + +@item FPU exceptions enabled by default + +Unlike most other systems, Plan 9 enables FPU exceptions by default. +These must be disabled before calling any Libav functions. While the +included tools will do this automatically, other users of the +libraries must do it themselves. + +@end itemize + @bye