[SCM] libav/experimental: Updated and rewritten Windows-related documentation.

[siretart at users.alioth.debian.org]

The following commit has been merged in the experimental branch:
commit c198955252b181637581cf294782547141fcd560
Author: Ramiro Polla <ramiro.polla at gmail.com>
Date:   Wed Oct 24 03:26:10 2007 +0000

    Updated and rewritten Windows-related documentation.
    
    Originally committed as revision 10849 to svn://svn.ffmpeg.org/ffmpeg/trunk

diff --git a/doc/faq.texi b/doc/faq.texi
index e29cc77..18ba855 100644
--- a/doc/faq.texi
+++ b/doc/faq.texi
@@ -360,27 +360,27 @@ It depends. If your compiler is C99-compliant, then patches to support
 it are likely to be welcome if they do not pollute the source code
 with @code{#ifdef}s related to the compiler.
 
- at section Visual C++ produces many errors.
+ at section Microsoft Visual C++ produces many errors.
 
-Visual C++ is not compliant to the C standard and does not support
+Microsoft Visual C++ is not compliant to the C standard and does not support
 the inline assembly used in FFmpeg.
-If you wish - for whatever weird reason - to use Visual C++ for your
-project then you can link the Visual C++ code with libav* as long as
+If you wish - for whatever weird reason - to use MSVC++ for your
+project then you can link the MSVC++ code with libav* as long as
 you compile the latter with a working C compiler. For more information, see
-the @emph{Visual C++ compatibility} section in the FFmpeg documentation.
+the @emph{Microsoft Visual C++ compatibility} section in the FFmpeg
+documentation.
 
-There have been efforts to make FFmpeg compatible with Visual C++ in the
+There have been efforts to make FFmpeg compatible with MSVC++ in the
 past. However, they have all been rejected as too intrusive, especially
 since MinGW does the job perfectly adequately. None of the core developers
-work with Visual C++ and thus this item is low priority. Should you find
+work with MSVC++ and thus this item is low priority. Should you find
 the silver bullet that solves this problem, feel free to shoot it at us.
 
 @section Can I use FFmpeg or libavcodec under Windows?
 
-Yes, but the MinGW tools @emph{must} be used to compile FFmpeg. You
-can link the resulting DLLs with any other Windows program. Read the
- at emph{Native Windows Compilation} and @emph{Visual C++ compatibility}
-sections in the FFmpeg documentation to find more information.
+Yes, but the Cygwin or MinGW tools @emph{must} be used to compile FFmpeg.
+Read the @emph{Windows} section in the FFmpeg documentation to find more
+information.
 
 To get help and instructions for using FFmpeg under Windows, check out
 the FFmpeg Windows Help Forum at
diff --git a/doc/general.texi b/doc/general.texi
index a6aeea0..978c34e 100644
--- a/doc/general.texi
+++ b/doc/general.texi
@@ -341,118 +341,67 @@ the FFmpeg Windows Help Forum at
 
 @subsection Native Windows compilation
 
- at itemize
- at item Install the current versions of MSYS and MinGW from
- at url{http://www.mingw.org/}. You can find detailed installation
+FFmpeg can be built to run natively on Windows using the MinGW tools. Install
+the current versions of MSYS and MinGW from @url{http://www.mingw.org/}. Also
+install the coreutils package. You can find detailed installation
 instructions in the download section and the FAQ.
 
-NOTE: Use at least bash 3.1. Older versions are known to be failing on the
-configure script.
-
- at item If you want to test the FFplay, also download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
- at url{http://www.libsdl.org}. Unpack it in a temporary directory, and
-unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
-directory. Edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked.
+Within the MSYS shell, configure and make with:
 
- at item If you want to use vhooks, you must have a POSIX compliant libdl in your
-MinGW system. Get dlfcn-win32 from @url{http://code.google.com/p/dlfcn-win32}.
+ at example
+./configure --enable-memalign-hack
+make
+make install
+ at end example
 
- at item Extract the current version of FFmpeg.
+This will install @file{ffmpeg.exe} along with many other development files
+to @file{/usr/local}. You may specify another install path using the
+ at code{--prefix} option in @file{configure}.
 
- at item Start the MSYS shell (file @file{msys.bat}).
+Notes:
 
- at item Change to the FFmpeg directory and follow
- the instructions of how to compile FFmpeg (file
- at file{INSTALL}). Usually, launching @file{./configure} and @file{make}
-suffices. If you have problems using SDL, verify that
- at file{sdl-config} can be launched from the MSYS command line.
+ at itemize
 
- at item You can install FFmpeg in @file{Program Files/FFmpeg} by typing
- at file{make install}. Do not forget to copy @file{SDL.dll} to the place
-you launch @file{ffplay} from.
+ at item Use at least bash 3.1. Older versions are known to be fail on the
+configure script.
 
- at end itemize
+ at item In order to compile vhooks, you must have a POSIX-compliant libdl in
+your MinGW system. Get dlfcn-win32 from
+ at url{http://code.google.com/p/dlfcn-win32}.
 
-Notes:
- at itemize
+ at item In order to compile FFplay, you must have the MinGW development library
+of SDL. Get it from @url{http://www.libsdl.org}.
+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.
 
- at item The target @file{make wininstaller} can be used to create a
-Nullsoft based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
+ at item The target @code{make wininstaller} can be used to create a
+Nullsoft-based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
 must be copied to the FFmpeg directory in order to build the
 installer.
 
 @item By using @code{./configure --enable-shared} when configuring FFmpeg,
-you can build @file{avcodec.dll} and @file{avformat.dll}. With
- at code{make install} you install the FFmpeg DLLs and the associated
-headers in @file{Program Files/FFmpeg}.
-
- at item Visual C++ compatibility: If you used @code{./configure --enable-shared}
-when configuring FFmpeg, FFmpeg tries to use the Microsoft Visual
-C++ @code{lib} tool to build @code{avcodec.lib} and
- at code{avformat.lib}. With these libraries you can link your Visual C++
-code directly with the FFmpeg DLLs (see below).
+you can build libavutil, libavcodec and libavformat as DLLs.
 
 @end itemize
 
- at subsection Visual C++ compatibility
-
-FFmpeg will not compile under Visual C++ -- and it has too many
-dependencies on the GCC compiler to make a port viable. However,
-if you want to use the FFmpeg libraries in your own applications,
-you can still compile those applications using Visual C++. An
-important restriction to this is that you have to use the
-dynamically linked versions of the FFmpeg libraries (i.e. the
-DLLs), and you have to make sure that Visual-C++-compatible
-import libraries are created during the FFmpeg build process.
+ at subsection Microsoft Visual C++ compatibility
 
-This description of how to use the FFmpeg libraries with Visual C++ is
-based on Visual C++ 2005 Express Edition Beta 2. If you have a different
-version, you might have to modify the procedures slightly.
+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.
 
-Here are the step-by-step instructions for building the FFmpeg libraries
-so they can be used with Visual C++:
+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.
 
- at enumerate
-
- at item Install Visual C++ (if you have not done so already).
-
- at item Install MinGW and MSYS as described above.
-
- at item Add a call to @file{vcvars32.bat} (which sets up the environment
-variables for the Visual C++ tools) as the first line of
- at file{msys.bat}. The standard location for @file{vcvars32.bat} is
- at file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
-and the standard location for @file{msys.bat} is
- at 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}:
-
- at code{call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"}
-
- at item Start the MSYS shell (file @file{msys.bat}) and type @code{link.exe}.
-If you get a help message with the command line options of @code{link.exe},
-this means your environment variables are set up correctly, the
-Microsoft linker is on the path and will be used by FFmpeg to
-create Visual-C++-compatible import libraries.
-
- at item Extract the current version of FFmpeg and change to the FFmpeg directory.
-
- at item Type the command
- at code{./configure --enable-shared --disable-static --enable-memalign-hack}
-to configure and, if that did not produce any errors,
-type @code{make} to build FFmpeg.
-
- at item The subdirectories @file{libavformat}, @file{libavcodec}, and
- at file{libavutil} should now contain the files @file{avformat.dll},
- at file{avformat.lib}, @file{avcodec.dll}, @file{avcodec.lib},
- at file{avutil.dll}, and @file{avutil.lib}, respectively. Copy the three
-DLLs to your System32 directory (typically @file{C:\Windows\System32}).
-
- at end enumerate
+ at subsubsection Using static libraries
 
-And here is how to use these libraries with Visual C++:
+Assuming you have just built and installed FFmpeg in @file{/usr/local}.
 
 @enumerate
 
@@ -462,30 +411,27 @@ 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 Visual C++ has already created for you. (Note that your source
-filehas to have a @code{.cpp} extension; otherwise, Visual C++ will not
-compile the FFmpeg headers correctly because in C mode, it does not
-recognize the @code{inline} keyword.)  For example, you can copy
- at file{output_example.c} from the FFmpeg distribution (but you will
-have to make minor modifications so the code will compile under
-C++, see below).
+that MSVC++ has already created for you. For example, you can copy
+ at file{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 complete paths to the
- at file{libavformat}, @file{libavcodec}, and @file{libavutil}
-subdirectories of your FFmpeg directory. Note that the directories have
-to be separated using semicolons. Now select "Linker / General" from the
-tree view and edit the "Additional Library Directories" setting to
-contain the same three directories.
-
- at item Still in the "Project / Properties" dialog box, select "Linker / Input"
-from the tree view, then add the files @file{avformat.lib},
- at file{avcodec.lib}, and @file{avutil.lib} to the end of the "Additional
-Dependencies". Note that the names of the libraries have to be separated
-using spaces.
+Directories" setting to contain the path where the FFmpeg includes were
+installed (i.e. @file{c:\msys\1.0\local\include}).
+
+ at 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},
+ at file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
+ at 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
@@ -493,26 +439,80 @@ 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".
 
- at item Click "OK" to close the "Project / Properties" dialog box and build
-the application. Hopefully, it should compile and run cleanly. If you
-used @file{output_example.c} as your sample application, you will get a
-few compiler errors, but they are easy to fix. The first type of error
-occurs because Visual C++ does not allow an @code{int} to be converted to
-an @code{enum} without a cast. To solve the problem, insert the required
-casts (this error occurs once for a @code{CodecID} and once for a
- at code{CodecType}).  The second type of error occurs because C++ requires
-the return value of @code{malloc} to be cast to the exact type of the
-pointer it is being assigned to. Visual C++ will complain that, for
-example, @code{(void *)} is being assigned to @code{(uint8_t *)} without
-an explicit cast. So insert an explicit cast in these places to silence
-the compiler. The third type of error occurs because the @code{snprintf}
-library function is called @code{_snprintf} under Visual C++.  So just
-add an underscore to fix the problem. With these changes,
- at file{output_example.c} should compile under Visual C++, and the
-resulting executable should produce valid video files.
+ at item Click "OK" to close the "Project / Properties" dialog box.
+
+ at 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}).
+
+ at item MSVC++ also does not understand the @code{inline} keyword used by
+FFmpeg, so you must add this line before @code{#include}ing libav*:
+ at example
+#define inline _inline
+ at end example
+
+ at item If you used @file{output_example.c} as your sample application,
+you will have to edit the @code{#include}s to point to the files which
+are under the @file{ffmpeg} directory (i.e. @code{<ffmpeg/avformat.h>}).
+
+ at item Build your application, everything should work.
+
+ at end enumerate
+
+ at subsubsection Using shared libraries
+
+This is how to create DLL and LIB files that are compatible with MSVC++:
+
+ at enumerate
+
+ at 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
+ at 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}:
+
+ at example
+call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
+ at end example
+
+Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
+and run @file{c:\msys\1.0\msys.bat} from there.
+
+ at 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.
+
+ at item Build FFmpeg with
+
+ at example
+./configure --enable-shared --enable-memalign-hack
+make
+make install
+ at end example
+
+Your install path (@file{/usr/local/} by default) should now have the
+necessary DLL and LIB files under the @file{bin} directory.
 
 @end enumerate
 
+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 @file{libxx.a}
+files, you should add @file{avcodec.lib}, @file{avformat.lib}, and
+ at file{avutil.lib}. There should be no need for @file{libmingwex.a},
+ at file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
+statically linked into the DLLs. The @file{bin} directory contains a bunch
+of DLL files, but the ones that are actually used to run your application
+are the ones with a major version number in their filenames
+(i.e. @file{avcodec-51.dll}).
+
 @subsection Cross compilation for Windows with Linux
 
 You must use the MinGW cross compilation tools available at

-- 
Libav/FFmpeg packaging