From 1de6e14efe1f3966023ad1121a6ce3fcbbb1b573 Mon Sep 17 00:00:00 2001 From: Luca Barbato Date: Sat, 3 Dec 2011 21:25:04 +0100 Subject: doc: split platform specific information Move the platform-specific information in its own file. --- doc/platform.texi | 359 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 doc/platform.texi (limited to 'doc/platform.texi') diff --git a/doc/platform.texi b/doc/platform.texi new file mode 100644 index 0000000000..6a44640e8f --- /dev/null +++ b/doc/platform.texi @@ -0,0 +1,359 @@ +\input texinfo @c -*- texinfo -*- + +@settitle Platform Specific information +@titlepage +@center @titlefont{Platform Specific information} +@end titlepage + +@top + +@contents + +@chapter Unix-like + +Some parts of Libav cannot be built with version 2.15 of the GNU +assembler which is still provided by a few AMD64 distributions. To +make sure your compiler really uses the required version of gas +after a binutils upgrade, run: + +@example +$(gcc -print-prog-name=as) --version +@end example + +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 BSD + +BSD make will not build Libav, you need to install and use GNU Make +(@file{gmake}). + +@section (Open)Solaris + +GNU Make is required to build Libav, so you have to invoke (@file{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 +since the libc is not c99-compliant by default. The probes performed by +configure may raise an exception leading to the death of configure itself +due to a bug in the system shell. Simply invoke a different shell such as +bash directly to work around this: + +@example +bash ./configure +@end example + +@anchor{Darwin} +@section Darwin (OSX, iPhone) + +The toolchain provided with Xcode is sufficient to build the basic +unacelerated 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 +in your PATH, Libav'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. + + +@chapter DOS + +Using a cross-compiler is preferred for various reasons. +@url{http://www.delorie.com/howto/djgpp/linux-x-djgpp.html} + + +@chapter OS/2 + +For information about compiling Libav on OS/2 see +@url{http://www.edm2.com/index.php/FFmpeg}. + + +@chapter Windows + +@section Native Windows compilation + +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}). + +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 +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 +@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. + +@item By using @code{./configure --enable-shared} when configuring Libav, +you can build libavutil, libavcodec and libavformat as DLLs. + +@end itemize + +@section Microsoft Visual C++ compatibility + +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. + +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. + +@subsection Using static libraries + +Assuming you have just built and installed Libav in @file{/usr/local}. + +@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 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 +@end example + +@item Build your application, everything should work. + +@end enumerate + +@subsection Using shared libraries + +This is how to create DLL and LIB files that are compatible with MSVC++: + +Within the MSYS shell, build Libav with + +@example +./configure --enable-shared +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. + +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 +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. +This issue is reported upstream at +@url{http://sourceware.org/bugzilla/show_bug.cgi?id=12633}. + +To create import libraries that work with the @code{/OPT:REF} option +(which is enabled by default in Release mode), follow these steps: + +@enumerate + +@item Open @file{Visual Studio 2005 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}). + +@item Enter the @file{bin} directory where the created LIB and DLL files +are stored. + +@item Generate new import libraries with @file{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 +@end example + +@end enumerate + +@anchor{Cross compilation for Windows with Linux} +@section Cross compilation for Windows with Linux + +You must use the MinGW cross compilation tools available at +@url{http://www.mingw.org/}. + +Then configure Libav with the following options: +@example +./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc- +@end example +(you can change the cross-prefix according to the prefix chosen for the +MinGW tools). + +Then you can easily test Libav with @uref{http://www.winehq.com/, Wine}. + +@section Compilation under Cygwin + +Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack +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 +@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: + +@example +./configure --enable-shared --disable-static --extra-cflags=-fno-reorder-functions +@end example + +If you want to build Libav with additional libraries, download Cygwin +"Devel" packages for Ogg and Vorbis from any Cygwin packages repository: +@example +libogg-devel, libvorbis-devel +@end example + +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 +@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. + +@section Crosscompilation for Windows under Cygwin + +With Cygwin you can create Windows binaries that do not need the cygwin1.dll. + +Just install your Cygwin as explained before, plus these additional +"Devel" packages: +@example +gcc-mingw-core, mingw-runtime, mingw-zlib +@end example + +and add some special flags to your configure invocation. + +For a static build run +@example +./configure --target-os=mingw32 --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin +@end example + +and for a build with shared libraries +@example +./configure --target-os=mingw32 --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin +@end example + +@bye -- cgit v1.2.3