VideoLAN Wiki - User contributions [en]

Win32Compile

2014-11-29T06:07:40Z

Elindsey: /* Fix your contrib path */

This page will help you to compile {{VLC}} for [[Windows]].

== Building Methods ==

If you want to build VLC from source, you have several choices:

{| class="wikitable"
|-
! Method
! Documentation
! Notes
|-
| '''MinGW on Linux'''
| [[Win32Compile#Obtaining_the_toolchain|Obtaining the toolchain]]
| '''Preferred''' method (uses cross compilation). On Windows, you should do it in a virtual machine.
|-
| '''[http://www.mingw.org MSYS+MinGW]''' on Windows
| [[Win32CompileMSYS|Compile with MSys]]
| '''Native''' compilation method. Note: This is not supported. MSYS is a minimal build environment to compile Unixish projects under Microsoft Windows. Good luck.
|-
| '''Cygwin''' on Windows
| [[Win32CompileCygwinNew|Compile with Cygwin]]
| Build using cygwin as your compile environment. '''Error''' prone, and '''slow'''.
|}

== Obtaining the cross-compilation toolchain ==

=== Compiler and binary toolchain ===

==== Mingw-w64 ====
To compile VLC for Windows (32-bits or 64-bits), the Mingw-w64 toolchain is required:

* '''Debian/Ubuntu''': run <code>apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 mingw-w64-tools</code>
For the 64-bit version, this becomes <code>apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 mingw-w64-tools</code>

(on Debian you must be on wheezy or above to find this package)

You might want to use the following script to enforce static compilation.
Run as root, and use at your own risk.

#!/bin/sh

# This script enforces statically linking of libgcc, libstdc++-6, and libpthread,
# without needing to rebuild gcc and mingw-w64 from scratch.
# -static-libgcc -static-libstdc++ flags can not be used in a libtool build system,
# as libtool removes flags that it doesn't understand.

move() {
[ -f $1 ] || return 1
mkdir -p old/
mv -v $* old/
return 0
}

for x in i686 x86_64
do
library_path_list=`$x-w64-mingw32-gcc -v /dev/null 2>&1 | grep ^LIBRARY_PATH|cut -d= -f2|sort|uniq`
IFS=':'
for i in $library_path_list
do
cd $i
move libstdc++-6.dll libstdc++.dll.a libgcc_s.a libgcc_s_sjlj-1.dll && ln -s libgcc_eh.a libgcc_s.a
move libpthread.dll.a libwinpthread.dll.a
move libwinpthread-1.dll
[ -d ../bin ] && cd ../bin && move libwinpthread-1.dll
done
done

exit 0

==== Mingw32 ====
Up to versions 2.0.x, VLC was compiled with the older mingw32 toolchain, which only supports 32-bits Windows. If you have problems with mingw-w64, you can try mingw32 instead:

* '''Debian/Ubuntu''': run <code>apt-get install gcc-mingw32 mingw32-binutils</code>. Note that at least version 3.17 of Mingw32 is required, which Debian does not provide. You may obtain mingw32-runtime-3.17 [http://people.videolan.org/~jb/debian/mingw32-runtime_3.17.0-0videolan_all.deb here].
* '''Gentoo''' users can <code>emerge crossdev && crossdev mingw32</code>
* '''ArchLinux''' users can <code>pacman -S mingw32-gcc</code>
* '''Fedora''' users should read [[Win32Compile Under Fedora]]
* Other '''Linux''' systems may attempt http://www.mingw.org/wiki/LinuxCrossMinGW

=== Development tools ===
You will also need:
* lua (5.1 or 5.2)
* all autotools: libtool, automake, autoconf, autopoint, make, gettext
* pkg-config
* qt4-dev-tools, qt5-default
* git
* subversion
* cmake, cvs if you want to rebuild contribs
* wine-dev for creating Win32 packages
* zip [for creating .zip package], p7zip [for .7z package], nsis [for .exe auto-installer], bzip2 [for 'make prebuild]

=== Host triplet ===
A number of example commands below include the identifier of the toolchain. This value is '''essential''': it instructs the build system to use the correct toolchain and compile the program for Windows. Without the value, the build system will perform a native compilation for Linux (or whatever your computer runs). With an incorrect value, the build will fail.

This is known as the ''host triplet'', although it's more of a pair than a triplet in the case of Mingw. The exact value depends on your installation of the toolchain. Notably on Debian/Ubuntu, these values must be used:

* ''i686-w64-mingw32'' for Windows 32-bits, using the Mingw-w64 toolchain
* ''x86_64-w64-mingw32'' for Windows 64-bits, using the Mingw-w64 toolchain
* ''i586-mingw32msvc'' for Windows 32-bits, using the Mingw32 toolchain

Again, you '''MUST''' substitute the value in the following command snippets.

== Get the source code ==
$ git clone git://git.videolan.org/vlc.git vlc

See [[Git]] for more information.

== Go into the VLC directory ==
$ cd vlc

== Prepare [[Contrib Status|3rd party libraries]] ==

Before compiling VLC, you need lots of other libraries. Here is how to get them:

$ mkdir -p contrib/win32
$ cd contrib/win32
$ ../bootstrap --host=i686-w64-mingw32
$ make prebuilt

or, if you want to compile the contribs yourself and are feeling adventurous and have lots of time to burn,
# apt-get install subversion yasm cvs cmake

$ mkdir -p contrib/win32
$ cd contrib/win32
$ ../bootstrap --host=i686-w64-mingw32
$ make fetch
$ make

=== Linux 64-bit ===

If you are on Linux '''64-bit''', you '''SHOULD''' remove some files, or install the lib32 packages (ia32-libs, multilibs, etc...)

$ rm -f ../i686-w64-mingw32/bin/moc ../i686-w64-mingw32/bin/uic ../i686-w64-mingw32/bin/rcc

=== Fix your contrib path ===

If your host triplet is not '''i686-w64-mingw32''' (you are ''not'' compiling for Debian or Ubuntu), create a symlink to contribs:
$ ln -sf '''''insert_your_host_triplet_here''''' ../i686-w64-mingw32
So, for example:
$ ln -sf x86_64-w64-mingw32 ../i686-w64-mingw32
Notice that there is no <code>../</code> before the host triplet. This is intentional, and if done properly, you should see a functioning symbolic link created in the parent directory (try <code>ls -l ..</code> and you should see <code>i686-w64-mingw32 -> x86_64-w64-mingw32/</code>).

=== Go Back ===

Go back to the VLC source directory:

$ cd -

== Configuring the build ==

=== Bootstrap ===
First, prepare the tree:
$ ./bootstrap

=== Configure ===
Then you can to configure the build with the <code>./configure</code> script.

Create a subfolder:
$ mkdir win32 && cd win32

Set your PKG_CONFIG_LIBDIR
$ export PKG_CONFIG_LIBDIR=$HOME/vlc/contrib/i686-w64-mingw32/lib/pkgconfig

Use the standard configuration:
$ ../extras/package/win32/configure.sh --host=i686-w64-mingw32
'''NB''': use '''YOUR''' cross-compiling prefix here, like ''i486-mingw32''

Also, if you have a problem here (such as an error about Library dvdread), see the [[Talk:Win32Compile|Talk]] page.

Alternatively, you can run configure manually:
$ ../configure --host=i686-w64-mingw32
See <code>'../configure --help'</code> for more information.

== Building VLC ==

Once configured, to build VLC, just run:
$ make

== Packaging VLC ==
Once the compilation is done, you can build self-contained VLC packages with the following <code>make</code> rules:

{| class="wikitable"
|-
! Command
! Description
|-
| <code>make package-win-common</code>
| Creates a subdirectory named <code>vlc-x.x.x</code> with all the binaries. You can run VLC directly from this directory.
|-
| <code>make package-win-strip</code>
| Same as above but will create 'stripped' binaries (that is, smallest size, unusable with a debugger).
|-
| <code>make package-win32-7zip</code>
| Same as above but will package the directory in a 7z file.
|-
| <code>make package-win32-zip</code>
| Same as above but will package the directory in a zip file.
|-
| <code>make package-win32</code>
| Same as above but will also create an auto-installer package. You must have NSIS installed in its default location for this to work.
|}

'''''Well done—you're ready to use VLC!'''''

[[Category:Building]]

Win32Compile

2014-11-29T05:48:49Z

Elindsey: /* Configure */

This page will help you to compile {{VLC}} for [[Windows]].

== Building Methods ==

If you want to build VLC from source, you have several choices:

{| class="wikitable"
|-
! Method
! Documentation
! Notes
|-
| '''MinGW on Linux'''
| [[Win32Compile#Obtaining_the_toolchain|Obtaining the toolchain]]
| '''Preferred''' method (uses cross compilation). On Windows, you should do it in a virtual machine.
|-
| '''[http://www.mingw.org MSYS+MinGW]''' on Windows
| [[Win32CompileMSYS|Compile with MSys]]
| '''Native''' compilation method. Note: This is not supported. MSYS is a minimal build environment to compile Unixish projects under Microsoft Windows. Good luck.
|-
| '''Cygwin''' on Windows
| [[Win32CompileCygwinNew|Compile with Cygwin]]
| Build using cygwin as your compile environment. '''Error''' prone, and '''slow'''.
|}

== Obtaining the cross-compilation toolchain ==

=== Compiler and binary toolchain ===

==== Mingw-w64 ====
To compile VLC for Windows (32-bits or 64-bits), the Mingw-w64 toolchain is required:

* '''Debian/Ubuntu''': run <code>apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 mingw-w64-tools</code>
For the 64-bit version, this becomes <code>apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 mingw-w64-tools</code>

(on Debian you must be on wheezy or above to find this package)

You might want to use the following script to enforce static compilation.
Run as root, and use at your own risk.

#!/bin/sh

# This script enforces statically linking of libgcc, libstdc++-6, and libpthread,
# without needing to rebuild gcc and mingw-w64 from scratch.
# -static-libgcc -static-libstdc++ flags can not be used in a libtool build system,
# as libtool removes flags that it doesn't understand.

move() {
[ -f $1 ] || return 1
mkdir -p old/
mv -v $* old/
return 0
}

for x in i686 x86_64
do
library_path_list=`$x-w64-mingw32-gcc -v /dev/null 2>&1 | grep ^LIBRARY_PATH|cut -d= -f2|sort|uniq`
IFS=':'
for i in $library_path_list
do
cd $i
move libstdc++-6.dll libstdc++.dll.a libgcc_s.a libgcc_s_sjlj-1.dll && ln -s libgcc_eh.a libgcc_s.a
move libpthread.dll.a libwinpthread.dll.a
move libwinpthread-1.dll
[ -d ../bin ] && cd ../bin && move libwinpthread-1.dll
done
done

exit 0

==== Mingw32 ====
Up to versions 2.0.x, VLC was compiled with the older mingw32 toolchain, which only supports 32-bits Windows. If you have problems with mingw-w64, you can try mingw32 instead:

* '''Debian/Ubuntu''': run <code>apt-get install gcc-mingw32 mingw32-binutils</code>. Note that at least version 3.17 of Mingw32 is required, which Debian does not provide. You may obtain mingw32-runtime-3.17 [http://people.videolan.org/~jb/debian/mingw32-runtime_3.17.0-0videolan_all.deb here].
* '''Gentoo''' users can <code>emerge crossdev && crossdev mingw32</code>
* '''ArchLinux''' users can <code>pacman -S mingw32-gcc</code>
* '''Fedora''' users should read [[Win32Compile Under Fedora]]
* Other '''Linux''' systems may attempt http://www.mingw.org/wiki/LinuxCrossMinGW

=== Development tools ===
You will also need:
* lua (5.1 or 5.2)
* all autotools: libtool, automake, autoconf, autopoint, make, gettext
* pkg-config
* qt4-dev-tools, qt5-default
* git
* subversion
* cmake, cvs if you want to rebuild contribs
* wine-dev for creating Win32 packages
* zip [for creating .zip package], p7zip [for .7z package], nsis [for .exe auto-installer], bzip2 [for 'make prebuild]

=== Host triplet ===
A number of example commands below include the identifier of the toolchain. This value is '''essential''': it instructs the build system to use the correct toolchain and compile the program for Windows. Without the value, the build system will perform a native compilation for Linux (or whatever your computer runs). With an incorrect value, the build will fail.

This is known as the ''host triplet'', although it's more of a pair than a triplet in the case of Mingw. The exact value depends on your installation of the toolchain. Notably on Debian/Ubuntu, these values must be used:

* ''i686-w64-mingw32'' for Windows 32-bits, using the Mingw-w64 toolchain
* ''x86_64-w64-mingw32'' for Windows 64-bits, using the Mingw-w64 toolchain
* ''i586-mingw32msvc'' for Windows 32-bits, using the Mingw32 toolchain

Again, you '''MUST''' substitute the value in the following command snippets.

== Get the source code ==
$ git clone git://git.videolan.org/vlc.git vlc

See [[Git]] for more information.

== Go into the VLC directory ==
$ cd vlc

== Prepare [[Contrib Status|3rd party libraries]] ==

Before compiling VLC, you need lots of other libraries. Here is how to get them:

$ mkdir -p contrib/win32
$ cd contrib/win32
$ ../bootstrap --host=i686-w64-mingw32
$ make prebuilt

or, if you want to compile the contribs yourself and are feeling adventurous and have lots of time to burn,
# apt-get install subversion yasm cvs cmake

$ mkdir -p contrib/win32
$ cd contrib/win32
$ ../bootstrap --host=i686-w64-mingw32
$ make fetch
$ make

=== Linux 64-bit ===

If you are on Linux '''64-bit''', you '''SHOULD''' remove some files, or install the lib32 packages (ia32-libs, multilibs, etc...)

$ rm -f ../i686-w64-mingw32/bin/moc ../i686-w64-mingw32/bin/uic ../i686-w64-mingw32/bin/rcc

=== Fix your contrib path ===

If your Mingw prefix is not ''i686-w64-mingw32'' (you are NOT on Debian or Ubuntu), create a symlink to contribs:
$ ln -sf ../i686-w64-mingw32 ../i486-mingw32

=== Go Back ===

Go back to the VLC source directory:

$ cd -

== Configuring the build ==

=== Bootstrap ===
First, prepare the tree:
$ ./bootstrap

=== Configure ===
Then you can to configure the build with the <code>./configure</code> script.

Create a subfolder:
$ mkdir win32 && cd win32

Set your PKG_CONFIG_LIBDIR
$ export PKG_CONFIG_LIBDIR=$HOME/vlc/contrib/i686-w64-mingw32/lib/pkgconfig

Use the standard configuration:
$ ../extras/package/win32/configure.sh --host=i686-w64-mingw32
'''NB''': use '''YOUR''' cross-compiling prefix here, like ''i486-mingw32''

Also, if you have a problem here (such as an error about Library dvdread), see the [[Talk:Win32Compile|Talk]] page.

Alternatively, you can run configure manually:
$ ../configure --host=i686-w64-mingw32
See <code>'../configure --help'</code> for more information.

== Building VLC ==

Once configured, to build VLC, just run:
$ make

== Packaging VLC ==
Once the compilation is done, you can build self-contained VLC packages with the following <code>make</code> rules:

{| class="wikitable"
|-
! Command
! Description
|-
| <code>make package-win-common</code>
| Creates a subdirectory named <code>vlc-x.x.x</code> with all the binaries. You can run VLC directly from this directory.
|-
| <code>make package-win-strip</code>
| Same as above but will create 'stripped' binaries (that is, smallest size, unusable with a debugger).
|-
| <code>make package-win32-7zip</code>
| Same as above but will package the directory in a 7z file.
|-
| <code>make package-win32-zip</code>
| Same as above but will package the directory in a zip file.
|-
| <code>make package-win32</code>
| Same as above but will also create an auto-installer package. You must have NSIS installed in its default location for this to work.
|}

'''''Well done—you're ready to use VLC!'''''

[[Category:Building]]

Hacker Guide/Core

2014-11-24T18:50:17Z

Elindsey: /* Synchronization */

== Introduction to libVLCcore ==

The core of {{VLC}} is called [[LibVLCcore|'''libVLCcore''']]. 
It manages the threads, the modules (codecs, demuxers, etc...), the modules' layers, the clocks, the playlist and all low-level control in VLC. For example, it is responsible for the synchronization management between all the audio, video and subtitle tracks.

On top of libVLCcore, there is [[LibVLC|'''libVLC''']] that allow external application builders to access to all features of the core. Modules are linked with libvlccore, to interact with the core.

'''Modules are built against libvlccore. External applications are built against [[LibVLC|libVLC]].'''

== VLC Pipeline and Modularity ==

One of the main concepts in VLC is "'''''modularity'''''".

VLC is, in fact, a complete [http://en.wikipedia.org/wiki/Multimedia_framework multimedia framework] (like DirectShow or GStreamer) where you can load and plug-in many modules dynamically, depending on the necessity.

The core framework is used to do the "wiring" and the media processing, from input (files, network streams) to output (audio or video, on a screen or a network). It uses modules to do most of the work at every stage (various muxers, demuxers, decoders, filters and outputs). Even the interfaces are plugins for libVLC.

=== The modules in VLC ===

So, VLC uses '''modules''' to do most of the work, at every stage of the pipeline. Modules are loaded accordingly at runtime depending on the necessity. (See [[Documentation:VLC_Modules_Loading|VLC Modules loading mechanism]]).

Every module offers different features that will best suit a particular use-case or a particular environment. 
Besides, most portability of VLC results from writing [[Documentation:Hacker%27s_Guide/Audio_Output|audio_output]]/[[Documentation:Hacker%27s_Guide/Video_Output|video_output]]/[[Documentation:Hacker%27s_Guide/Interfaces|interface]] modules specific to the platform.

'''plugins''' modules are loaded and unloaded dynamically by functions in src/modules/modules.c . 
Modules can also be built directly into the application which uses libVLC, for instance when VLC is on an operating system that does not have support for dynamically loadable code. They are then called '''builtins'''.

In the [[Documentation:Modules_source_tree|source code]], modules are usually located inside the [[Documentation:Modules_source_tree|modules/ subdirectory]].

== Thread management ==

VLC is heavily multi-threaded.

The single-threaded approach would have introduced too much complexity because decoder preemptibility and scheduling would then be a mastermind (for instance decoders and outputs have to be separated, otherwise it cannot be warrantied that a frame will be played at the exact presentation time). 
Multi-process approach wasn't chosen either, because multi-process decoders usually imply more overhead (problems of shared memory) and communication between processes is harder.

VLC's threading structure is modeled after POSIX threads (''pthread''). However, for portability reasons, VLC does not use pthread_* functions directly, but a similar custom set of APIs.

=== Threads (vlc_thread_t) ===
* vlc_clone() creates a thread.
* vlc_join() waits for a thread to terminate and releases its resources

=== Mutual exclusion (vlc_mutex_t) ===
* vlc_mutex_init() creates a non-recursive mutex.
* vlc_mutex_init_recursive() creates a recursive mutex (discouraged).
* vlc_mutex_lock() locks a mutex, waiting if required.
* vlc_mutex_trylock() locks a mutex if it is not already locked, or returns an error otherwise.
* vlc_mutex_unlock() unlocks a mutex.
* vlc_mutex_destroy() destroys a mutex.

=== Condition variable (vlc_cond_t) ===
* vlc_cond_init() creates a condition variable using the monotonic clock (''mdate()'') for timeouts.
* vlc_cond_init_daytime() creates a condition variable using the realtime clock / wall clock for timeouts.
* vlc_cond_signal() signals one thread waiting on a condition variable.
* vlc_cond_broadcast() signals all threads waiting on a condition variable.
* vlc_cond_wait() waits for a condition variable to be signaled (can also wake up spuriously).
* vlc_cond_timedwait() waits for a condition variable to be signaled up to a certain timeout (can also wake up spuriosuly).
* vlc_cond_destroy() destroys a condition variable.

=== Misc ===
VLC also has abstractions for slim read/write locks, spin locks, thread-specific variables, similar to POSIX threads.

=== Atomic variables ===
Atomic variables are small (sizeof(void *)) values that can be manipulated from multiple threads without locking. See include/vlc_atomic.h for the list of supported operations.

== Synchronization ==

Another key feature of VLC is that decoding and playing are asynchronous: decoding is done by a decoder thread, playing is done by audio_output or video_output thread. The design goal is to ensure that an audio or video frame is played exactly at the right time, without blocking any of the decoder threads. This leads to a complex communication structure between the interface, the input, the decoders and the outputs.

Having several input and video_output threads reading multiple files at the same time is permitted, despite the fact that the current interface doesn't allow any way to do it (this is subject to change in the near future). Anyway the client has been written from the ground up with this in mind. This also implies that a non-reentrant library (including in particular liba52[[Talk:Hacker Guide/Core|See talk page]]) cannot be used without using a global lock.

Presentation Time Stamps located in the system layer of the stream are passed to the decoders, and all resulting samples are dated accordingly. The output layers are supposed to play them at the right time. Dates are converted to microseconds ; an absolute date is the number of microseconds since Epoch (Jan 1st, 1970). The mtime_t type is a signed 64-bit integer.

The current date can be retrieved with mdate(). The execution of a thread can be suspended until a certain date via mwait ( mtime_t date ). You can sleep for a fixed number of microseconds with msleep ( mtime_t delay ).

=== Warning ===

Please remember to wake up slightly before the presentation date, if some particular treatment needs to be done (e.g. a chroma transformation). For instance in modules/codec/libmpeg2.c, track of the average decoding times is kept to ensure pictures are not decoded too late.

== Core Source code details ==

All the [[LibVLCcore|libVLCcore]] source files are located in the src/ directory and its subdirectories:

*[[Documentation:Hacker's Guide/Audio Output|audio_output/]]: initializes the audio mixer, ie. finds the right playing frequency, and then resamples audio frames received from the decoder(s).
*config/: load the configuration from command line and configuration file, provides functions for the modules to read and write to configuration
*control/: functions to control the behaviour of [[LibVLCcore|libVLCcore]], like Play/Pause, volume management, fullscreen, log verbosity, etc.
*extras/: mostly platform-specific code
*[[Documentation:Hacker's Guide/Input|input/]]: opens an input module, reads packets, parses them and passes reconstituted elementary streams to the decoder(s).*modules/: module management
*[[Documentation:Hacker's Guide/Interfaces|interface/]]: contains code for user interaction such as key presses and device ejection.
*misc/: miscellaneous utilities used in other parts of libvlc, such as the thread system, the message queue, CPU detection, the object lookup system, or platform-specific code.
*modules/: modules management
*network/: network interface (socket management, network errors, etc.)
*osd/: On Screen Display manipulation
*playlist/: manages playlist interaction such as stop, play, next, or random playback.
*stream_output/: functions to stream audio and video to the network
*test/: libVLC needs to be tested, and not only by users :)
*text/: charset stuff
*[[Documentation:Hacker's Guide/Video Output|video_output/]]: initializes the video display, gets all pictures and subpictures (ie. subtitles) from the decoder(s), optionally converts them to another format (such as YUV to RGB), and displays them.

{{Hacker_Guide}}

Talk:Hacker Guide/Core

2014-11-24T18:45:40Z

Elindsey:

Based on the VLC media player API Documentation by Christophe Massiot and Samuel Hocevar

=== Question about liba52 facts ===
According to http://liba52.sourceforge.net/ retrieved November 24, 2014, "July 27, 2002: a52dec-0.7.4 is released ! With full reentrancy..." Does this affect liba52 which is stated '''not''' to have reentrancy on this page?