VideoLAN Wiki - User contributions [en]

Git

2008-07-05T22:39:17Z

Grae: /* Configure your global git config */ Probably, new version of git changes the syntax of the config commands.

= Basic Git usage =
== Getting VLC source code via Git ==
$ git clone git://git.videolan.org/vlc.git
Voilà! The full VLC history should be on your hard disk in vlc/.

You can also clone using http with out repo.or.cz mirror.
$ git clone http://repo.or.cz/r/vlc.git

$ git log
to see the full log of the trunk.
$ gitk
to see the log graphically.

You can also browse the sources via [http://git.videolan.org/ gitweb].

'''Note for Windows users using [http://www.cygwin.com Cygwin] (linux-like build environment):'''

Applies to:

Windows XP Service Pack 2 with Security Update '''KB925902''' installed
Windows XP Service Pack 3

There is a problem on Windows XP (and possibly on other Microsoft Operating Systems) with 'git clone' which aborts unexpectedly with a Cygwin error during the 'checking out files' (reproducable every time and at the same percentage) at the end of the clone procedure:

$ 2 [main] git 4012 D:\cygwin\bin\git.exe:
*** fatal error - '''could not load shell32, Win32 error 487'''

This has been verified (May 22, 2008) against the currently available Cygwin 1.5.25-12 with git package versions 1.5.5.1-1 and 1.5.4-1 and is a generic problem which also affects cloning from other git repositories (although x264.git seems unaffected).

The issue is referred to in the mail archives of the Cygwin project mailing list here
[http://sourceware.org/ml/cygwin/2007-07/msg00858.html Git error on Cygwin].

By eliminating the impossible, whatever remained, however improbable, it is the following Windows Security Update (April 3, 2007) which is actually the cause of the Cygwin issue: [http://www.microsoft.com/technet/security/bulletin/ms07-017.mspx Microsoft Security Bulletin MS07-017 - Vulnerabilities in GDI Could Allow Remote Code Execution (925902)]

Even though the same Security Update applies to the following systems, these are reported not to be affected:

Windows Vista Service Pack 1
Windows 2003 Server Standard Service Pack 2

''It is possible to get 'git clone' working again on the affected systems by removing the Security Update (KB925902) but this is obviously not recommended for security reasons.''

== Configure your global git config ==
May need to use
$ git repo-config {various options}
1.4.4.2 Requires the repo-config command rather than just config

=== Personal Information ===
Tell git your name. (use mostly by git-commit)
$ git config --global user.name "Your Name"
$ git config --global user.email "me@example.com"

=== Using git with color (Tip) ===
If you want to use git with colored output use:
$ git config --global color.ui true

If you are using an old git version (prior to 1.5.5) and previous command didn't work, use:
$ git config --global color.diff auto
$ git config --global color.status auto
$ git config --global color.branch auto

=== Setting up "git up" (Tip) ===
If you want to be able to just keep in sync using "git up" use:
$ git config --global alias.up "pull --rebase"
And if you like your tree to be messy and don't want git to complain (like in svn) use:
$ git config --global alias.up '!sh -c "git stash && git pull --rebase && git stash apply"'

=== Setting up "git wu" (Git What's Up) (Tip) ===
If you want to see what you are about to "git push":
$ git config --global alias.wu "log --stat origin..@{0}"
Now use:
$ git wu

=== Setting up "git wup" (Git What's Up - with patch) (Tip) ===
If you want to see what you are about to "git push", along with the diff:
$ git config --global alias.wup "log -p origin..@{0}"
Now use:
$ git wup

== General GIT Workflow ==
1. Make your file edits in your local repository.

2. "git commit" the changes in your local repository

3. "git pull --rebase" or "git up" (if you did ''git config --global alias.up "pull --rebase"'') to bring the rest of your local repository up to date

4. "git log origin..master" to check what you are going to commit

4. "git push" to move your changes up to the master

"git stash" if you want to "hide" your changes. Do this if you think there may be other commits against ther same things you are working on, want to refresh yourself (using a git pull --rebase) from the master. Use "git stash apply" to get your stash back.

"git checkout -f master" if you think your tree is pretty hopeless, need a kill-and-fill to bring the master into your local repository.

== List the local branch ==
You can now list your local branch by doing
$ git branch
which should ouput
$ git branch
* master

== List your local non committed changes ==
$ git status | less

== Commit ==
Now you can start to work on your tree. As soon as you feel you've reached a step in developement you can commit '''locally''' your work by
$ git commit -a
or
$ git commit <specific files>

== List your commits ==
$ git log

== Keeping your local working branch in sync ==
$ git pull --rebase

To shorten up that command type
$ git config --global alias.up "pull --rebase"

Now you can just type:
$ git up

== Use a graphical interface ==
$ gitk # Tree Browser
$ qgit # Tree Browser
$ git-gui # Commit/push/... editor

== Submitting patches to the vlc-devel ==

First make sure you have '''read''' our [[Sending Patches]] page. And that you've '''read''' the [[Sending Patches#Check_List| Check List]].

If you have been developing on vlc locally and (still) don't have write access, you can submit all your commit in one shot using:
$ rm -Rf patches
$ git format-patch -o patches origin
$ git-send-email --to vlc-devel@videolan.org patches
If you have multiple patch consider using:
$ git-send-email --compose --no-chain-reply-to --to vlc-devel@videolan.org patches
which will produce the patches for each local commit in the directory "patches" and send them.
--no-chain-reply-to make sure it doesn't reply do
* [PATCH 0/m]
** [PATCH 1/m]
*** [PATCH 2/m]
**** ...
But :
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 2/m]
** ..

= Advanced usage =
== Creating a secondary local branch ==
If you want to work on a specific project that could require a branch of the trunk, create a local branch of the current branch by doing:
$ git branch mywork
and to actually use it do:
$ git checkout mywork
Which could be summarized by:
$ git checkout -b mywork

Then do some commit on it... And you can go back to your original master branch by doing:
$ git checkout master

== Fetching a remote branch ==
To see the remote branch use:
$ git branch -r
If the remote branch is named 0.8.6-bugfix
$ git branch 0.8.6-bugfix origin/0.8.6-bugfix
Branch 0.8.6-bugfix set up to track remote branch refs/remotes/origin/0.8.6-bugfix.
$ git branch
0.8.6-bugfix
* master
To checkout that branch use:
$ git checkout 0.8.6-bugfix
To stay up-to-date a simple
$ git pull --rebase
Should be enough.

If warnings appear that files still need updating:
$ include/libvlc_internal.h: needs update
include/mediacontrol_internal.h: needs update
include/vlc/libvlc.h: needs update
include/vlc_update.h: needs update
modules/access/mms/mms.c: needs update
...

Then do a checkout -f to revert non committed local changes
$ git checkout -f

To stay up-to-date another
$ git pull --rebase
Should give no more warnings.

To push to the remote branch, use:
$git push origin 0.8.6-bugfix:0.8.6-bugfix

== Creating a remote branch ==
If the new remote branch is named 0.9.0-bugfix, and is based on the local master branch.
First make sure everything go as planned with the --dry-run option:
$ git push --dry-run origin master:refs/heads/0.9.0-stable
To git@git.videolan.org:vlc.git
* [new branch] master -> 0.9.0-stable

Then push it:
$ git push origin master:refs/heads/0.9.0-stable
To git@git.videolan.org:vlc.git
* [new branch] master -> 0.9.0-stable
$ git branch -r
origin/0.9.0-stable
origin/master

To checkout that branch now see ''Fetching a remote branch''

== Publishing your own fork ==
Goto [http://repo.or.cz/w/vlc.git http://repo.or.cz/w/vlc.git] and click [http://repo.or.cz/m/regproj.cgi?name=vlc/ fork]. You will be able to publish your work there.

Please don't forget to send a mail to the vlc-devel as soon as you create your fork.

== Revert your non-committed local changes ==
$ git checkout -f

==Edit or undo not yet pushed commits ==
This will undo the last commit
$ git reset HEAD^
which is the same as
$ git reset master^
(if you are checked-out copy of your tree is master)
And also the same as
$ git reset a44a594 # note that there is no need to use the full sha id

If you have a stack of patch that you have not yet committed you can delete one patch from the list using git rebase --interactive
$ git rebase --interactive origin
pick eacf185 test
pick 56322eb VLMA owner is vlma prod.

# Rebase 826757e..56322eb onto 826757e
#
# Commands:
# pick = use commit
# edit = use commit, but stop for amending
# squash = use commit, but meld into previous commit

== Diff-ing ==
* You can diff between two branches using
$ git diff branch1 branch2
* You can diff between the previous 10th commit and current using
$ git diff HEAD~10 HEAD
* You can diff between the previous 10th commit and current of the branch "mywork" using
$ git diff mywork~10 mywork
* Imagine that git log is like
$ git log
commit e0394f269305edd09843257e7c1d1a66aaf48ab3
Author: jb <jb>
Date: Fri Apr 13 07:14:48 2007 +0000
qt4 - Mousewheel (2)
commit e80b339081aa6755f67c9bd8e2aacf93a9a79d95
[..]
commit ff7004b70fd239e4120deb160e2991bd5237b8df
[..]
commit a44a594898f981a145cfcace5f16f8973f9eb46f
[..]
commit 690df705c963cf6bf6f5746d54bc97a85ff91919
[..]
commit 679f8b1c3e0baa469efa970588b95a625c595d64
[..]

$ git diff a44a594898f981a145cfcace5f16f8973f9eb46f~2 e80b339081aa6755f67c9bd8e2aacf93a9a79d95
Will be equivalent to:
$ git diff ff7004b70fd239e4120deb160e2991bd5237b8df e80b339081aa6755f67c9bd8e2aacf93a9a79d95
And to:
$ git diff HEAD~4 HEAD^

* Remember that to produce a patch you should rather use git-format-patch than git-diff most of the time.

== Tracking regression ==
git has a great tool called [http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html git-bisect] to help you to track a faulty commit. Imagine you are tracking a bug that is known to appear after 0.8.6 (assuming 0.8.6 is tagged):
$ git bisect start
$ git bisect bad # tell git current version has the bug you are tracking
$ git bisect good 0.8.6 # tell git 0.8.6 didn't has the bug
And then git will checkout a certain revision, and ask you to test it. And you simply say whether this version has the bug.
If it has the bug:
$ git bisect bad
if the bug is not present:
$ git bisect good
And so on by bisection... At the end git will indicate the faulty commit. Most of the time this tool is really efficient to track regression.

If you can provide a script that test the presence of the bug
$ git bisect run <script_name>
will be able to track down the regression by itself. See [http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html git-bisect Documentation].

= Using Git to push to VideoLAN git =
== Initial requirement ==
* Make sure you've set your name and email in your commits
$ git config --global user.name "Your Name"
$ git config --global user.email "me@example.com"

== Convert your tree to use your ssh push commit access ==
$ vi vlc/.git/config
And replace git://git.videolan.org/vlc.git by git@git.videolan.org:vlc.git

== Staying up to date ==
$ git pull --rebase

If you don't want to have to type --rebase everytime you pull do:
$ git config branch.master.rebase true

This one creates a merge object which is not how SVN worked, so let's use the first version...
$ git pull

== Pushing your work ==
$ git log origin..master # Check what you are going to push
$ git push



= Documentation about git =
* [http://git.or.cz/ Official Git Website]
* [http://www.kernel.org/pub/software/scm/git/docs/tutorial.html Git Tutorial]
* [http://git.or.cz/course/svn.html Switching from SVN to git using cogito]
* [http://wiki.sourcemage.org/Git_Guide Very good Git guide]

[[Category:Building]]

Hacker Guide/Input

2008-06-26T16:48:10Z

Grae: /* Structures exported to the interface */

=The complex multi-layer input=

The idea behind the input module is to treat packets, without knowing at all what is in it. It only takes a packet, reads its ID, and delivers it to the decoder at the right time indicated in the packet header (SCR and PCR fields in MPEG). All the basic browsing operations are implemented without peeking at the content of the elementary stream.

Thus it remains very generic. This also means you can't do stuff like "play 3 frames now" or "move forward 10 frames" or "play as fast as you can but play all frames". It doesn't even know what a "frame" is. There is no privileged elementary stream, like the video one could be (for the simple reason that, according to MPEG, a stream may contain several video ES).

==What happens to a file==

An input thread is spawned for every file read. Indeed, input structures and decoders need to be reinitialized because the specificities of the stream may be different. input_CreateThread is called by the interface thread (playlist module).

At first, an input plug-in capable of reading the plugin item is looked for [this is inappropriate : we should first open the socket, and then probe the beginning of the stream to see which plug-in can read it]. The socket is opened by either input_FileOpen, input_NetworkOpen, or input_DvdOpen. This function sets two very important parameters : b_pace_control and b_seekable (see next section).

===Note===
We could use so-called "access" plugins for this whole mechanism of opening the input socket. This is not the case because we thought only those three methods were to be used at present, and if we need others we can still build them in.

Now we can launch the input plugin's pf_init function, and an endless loop doing pf_read and pf_demux. The plugin is responsible for initializing the stream structures (p_input->stream), managing packet buffers, reading packets and demultiplex them. But in most tasks it will be assisted by functions from the advanced input API (c). That is what we will study in the coming sections !

==Stream Management==

The function which has opened the input socket must specify two properties about it :

p_input->stream.b_pace_control : Whether or not the stream can be read at our own pace (determined by the stream's frequency and the host computer's system clock). For instance a file or a pipe (including TCP/IP connections) can be read at our pace, if we don't read fast enough, the other end of the pipe will just block on a write() operation. On the contrary, UDP streaming (such as the one used by VideoLAN Server) is done at the server's pace, and if we don't read fast enough, packets will simply be lost when the kernel's buffer is full. So the drift introduced by the server's clock must be regularly compensated. This property controls the clock management, and whether or not fast forward and slow motion can be done.

Subtilities in the clock management : With a UDP socket and a distant server, the drift is not negligible because on a whole movie it can account for seconds if one of the clocks is slightly fucked up. That means that presentation dates given by the input thread may be out of sync, to some extent, with the frequencies given in every Elementary Stream. Output threads (and, anecdotically, decoder threads) must deal with it.

The same kind of problems may happen when reading from a device (like video4linux's /dev/video ) connected for instance to a video encoding board. There is no way we could differentiate it from a simple cat foo.mpg | vlc - , which doesn't imply any clock problem. So the Right Thing (c) would be to ask the user about the value of b_pace_control , but nobody would understand what it means (you are not the dumbest person on Earth, and obviously you have read this paragraph several times to understand it :-). Anyway, the drift should be negligible since the board would share the same clock as the CPU, so we chose to neglect it.

p_input->stream.b_seekable : Whether we can do lseek() calls on the file descriptor or not. Basically whether we can jump anywhere in the stream (and thus display a scrollbar) or if we can only read one byte after the other. This has less impact on the stream management than the previous item, but it is not redundant, because for instance cat foo.mpg | vlc - is b_pace_control = 1 but b_seekable = 0. On the contrary, you cannot have b_pace_control = 0 along with b_seekable = 1. If a stream is seekable, p_input->stream.p_selected_area->i_size must be set (in an arbitrary unit, for instance bytes, but it must be the same as p_input->i_tell which indicates the byte we are currently reading from the stream).

===Offset to time conversions===
Functions managing clocks are located in src/input/input_clock.c. All we know about a file is its start offset and its end offset (p_input->stream.p_selected_area->i_size), currently in bytes, but it could be plugin-dependant. So how the hell can we display in the interface a time in seconds ? Well, we cheat. PS streams have a mux_rate property which indicates how many bytes we should read in a second. This is subject to change at any time, but practically it is a constant for all streams we know. So we use it to determine time offsets.

==Structures exported to the interface==

Let's focus on the communication API between the input module and the interface. The most important file is include/input_ext-intf.h, which you should know almost by heart. This file defines the input_thread_t structure, the stream_descriptor_t and all programs and ES descriptors included (you can view it as a tree).

Update: input_thread_t is now defined in include/vlc_input.h

First, note that the input_thread_t structure features two void * pointers, p_method_data and p_plugin_data, which you can respectivly use for buffer management data and plugin data.

Second, a stream description is stored in a tree featuring program descriptors, which themselves contain several elementary stream descriptors. For those of you who don't know all MPEG concepts, an elementary stream, aka ES, is a continuous stream of video or (exclusive) audio data, directly readable by a decoder, without decapsulation.

This tree structure is illustrated by the following figure, where one stream holds two programs. In most cases there will only be one program (to my knowledge only TS streams can carry several programs, for instance a movie and a football game at the same time - this is adequate for satellite and cable broadcasting).

===Warning===

For all modifications and accesses to the p_input->stream structure, you must hold the p_input->stream.stream_lock.

ES are described by an ID (the ID the appropriate demultiplexer will look for), a stream_id (the real MPEG stream ID), a type (defined in ISO/IEC 13818-1 table 2-29) and a litteral description. It also contains context information for the demultiplexer, and decoder information p_decoder_fifo we will talk about in the next chapter. If the stream you want to read is not an MPEG system layer (for instance AVI or RTP), a specific demultiplexer will have to be written. In that case, if you need to carry additional information, you can use void * p_demux_data at your convenience. It will be automatically freed on shutdown.

===Why ID and not use the plain MPEG stream_id ?===

When a packet (be it a TS packet, PS packet, or whatever) is read, the appropriate demultiplexer will look for an ID in the packet, find the relevant elementary stream, and demultiplex it if the user selected it. In case of TS packets, the only information we have is the ES PID, so the reference ID we keep is the PID. PID don't exist in PS streams, so we have to invent one. It is of course based on the stream_id found in all PS packets, but it is not enough, since private streams (ie. AC3, SPU and LPCM) all share the same stream_id (0xBD). In that case the first byte of the PES payload is a stream private ID, so we combine this with the stream_id to get our ID (if you did not understand everything, it isn't very important - just remember we used our brains before writing the code :-).

The stream, program and ES structures are filled in by the plugin's pf_init() using functions in src/input/input_programs.c, but are subject to change at any time. The DVD plugin parses .ifo files to know which ES are in the stream; the TS plugin reads the PAT and PMT structures in the stream; the PS plugin can either parse the PSM structure (but it is rarely present), or build the tree "on the fly" by pre-parsing the first megabyte of data.

===Warning===

In most cases we need to pre-parse (that is, read the first MB of data, and go back to the beginning) a PS stream, because the PSM (Program Stream Map) structure is almost never present. This is not appropriate, though, but we don't have the choice. A few problems will arise. First, non-seekable streams cannot be pre-parsed, so the ES tree will be built on the fly. Second, if a new elementary stream starts after the first MB of data (for instance a subtitle track won't show up during the credits), it won't appear in the menu before we encounter the first packet. We cannot pre-parse the entire stream because it would take hours (even without decoding it).

It is currently the responsibility of the input plugin to spawn the necessary decoder threads. It must call input_SelectES ( input_thread_t * p_input, es_descriptor_t * p_es ) on the selected ES.

The stream descriptor also contains a list of areas. Areas are logical discontinuities in the stream, for instance chapters and titles in a DVD. There is only one area in TS and PS streams, though we could use them when the PSM (or PAT/PMT) version changes. The goal is that when you seek to another area, the input plugin loads the new stream descriptor tree (otherwise the selected ID may be wrong).

==Methods used by the interface==

Besides, input_ext-intf.c provides a few functions to control the reading of the stream :

*input_SetStatus ( input_thread_t * p_input, int i_mode ) : Changes the pace of reading. i_mode can be one of INPUT_STATUS_END, INPUT_STATUS_PLAY, INPUT_STATUS_PAUSE, INPUT_STATUS_FASTER, INPUT_STATUS_SLOWER.

===Note===
Internally, the pace of reading is determined by the variable p_input->stream.control.i_rate. The default value is DEFAULT_RATE. The lower the value, the faster the pace is. Rate changes are taken into account in input_ClockManageRef. Pause is accomplished by simply stopping the input thread (it is then awaken by a pthread signal). In that case, decoders will be stopped too. Please remember this if you do statistics on decoding times (like src/video_parser/vpar_synchro.c does). Don't call this function if p_input->b_pace_control == 0.

*input_Seek ( input_thread_t * p_input, off_t i_position ) : Changes the offset of reading. Used to jump to another place in a file. You mustn't call this function if p_input->stream.b_seekable == 0. The position is a number (usually long long, depends on your libc) between p_input->p_selected_area->i_start and p_input->p_selected_area->i_size (current value is in p_input->p_selected_area->i_tell).

===Note===
Multimedia files can be very large, especially when we read a device like /dev/dvd, so offsets must be 64 bits large. Under a lot of systems, like FreeBSD, off_t are 64 bits by default, but it is not the case under GNU libc 2.x. That is why we need to compile VLC with -D_FILE_OFFSET_BITS=64 -D__USE_UNIX98.

===Escaping stream discontinuities===

Changing the reading position at random can result in a messed up stream, and the decoder which reads it may segfault. To avoid this, we send several NULL packets (ie. packets containing nothing but zeros) before changing the reading position. Indeed, under most video and audio formats, a long enough stream of zeros is an escape sequence and the decoder can exit cleanly.

*input_OffsetToTime ( input_thread_t * p_input, char * psz_buffer, off_t i_offset ) : Converts an offset value to a time coordinate (used for interface display). [currently it is broken with MPEG-2 files]
*input_ChangeES ( input_thread_t * p_input, es_descriptor_t * p_es, u8 i_cat ) : Unselects all elementary streams of type i_cat and selects p_es. Used for instance to change language or subtitle track.
*input_ToggleES ( input_thread_t * p_input, es_descriptor_t * p_es, boolean_t b_select ) : This is the clean way to select or unselect a particular elementary stream from the interface.

==Buffers management==

Input plugins must implement a way to allocate and deallocate packets (whose structures will be described in the next chapter). We basically need four functions :

*pf_new_packet ( void * p_private_data, size_t i_buffer_size ) : Allocates a new data_packet_t and an associated buffer of i_buffer_size bytes.
*pf_new_pes ( void * p_private_data ) : Allocates a new pes_packet_t.
*pf_delete_packet ( void * p_private_data, data_packet_t * p_data ) : Deallocates p_data.
*pf_delete_pes ( void * p_private_data, pes_packet_t * p_pes ) : Deallocates p_pes.

All functions are given p_input->p_method_data as first parameter, so that you can keep records of allocated and freed packets.

===Buffers management strategies===

Buffers management can be done in three ways :

#Traditional libc allocation : For a long time we have used in the PS plugin malloc() and free() every time we needed to allocate or deallocate a packet. Contrary to a popular belief, it is not that slow.
#Netlist : In this method we allocate a very big buffer at the beginning of the problem, and then manage a list of pointers to free packets (the "netlist"). This only works well if all packets have the same size. It is used for long for the TS input. The DVD plugin also uses it, but adds a refcount flag because buffers (2048 bytes) can be shared among several packets. It is now deprecated and won't be documented.
#Buffer cache : We are currently developing a new method. It is already in use in the PS plugin. The idea is to call malloc() and free() to absorb stream irregularities, but re-use all allocated buffers via a cache system. We are extending it so that it can be used in any plugin without performance hit, but it is currently left undocumented.

==Demultiplexing the stream==

After being read by pf_read , your plugin must give a function pointer to the demultiplexer function. The demultiplexer is responsible for parsing the packet, gathering PES, and feeding decoders.

Demultiplexers for standard MPEG structures (PS and TS) have already been written. You just need to indicate input_DemuxPS and input_DemuxTS for pf_demux. You can also write your own demultiplexer.

It is not the purpose of this document to describe the different levels of encapsulation in an MPEG stream. Please refer to your MPEG specification for that.

Win32CompileCygwinNew

2008-06-05T14:06:19Z

Grae: /* Selecting Cygwin packages to install */ Basically, atleast sometimes you get a compile error requesting libiconv. Which sometimes not include in the cygwin, thing.

This is a new version of the Win32CompileCygwin written by [[User:J-b|Jean-Baptiste Kempf]]
'''This version ONLY works for 0.9.x.'''

=Introduction=

This is a guide for Windows users with a step-by-step instruction to download, install, configure and build your VLC.

This guide uses [http://www.cygwin.com '''Cygwin'''] a Linux-like environment for Windows used for compilation of the VLC source code.

Start off by creating a VLC and a download folder on your hard drive where you can put all the installation files:

C:\VLC\
C:\VLC\Downloads

For further reference, the assumption is made that the local user will be 'Administrator'.

=Cygwin=

Download the latest [http://www.cygwin.com/cygwin/setup.exe Cygwin setup] and save it in your download location:

C:\VLC\Downloads\

More info about Cygwin can be found at http://www.cygwin.com or http://sourceware.org/cygwin

==Selecting Cygwin packages to install==

Run the setup program with the following options:

Installation type : Install from Internet (default)

Root directory : C:\cygwin (default)

Local Package directory : C:\VLC\Downloads\cygwin (your download location)

Internet Connection : Direct Connection (preferred, if it fails try another)

Download Site : Choose a download site closest to you (FTP preferred)

At the "Select Packages" section of the installation process you can select packages by clicking the button with the rotating 2 arrows. (This is under the "New" section). It shows "Skip" next to the button if the package isn't selected yet.

Clicking the button a few times will rotate through the possible package versions including "Skip" (meaning do not install or remove if installed) and "Keep" (meaning keep using the current installed version). If a package was already installed it will also show the "Current" version just to the left of it.

Select the following packages (some others will automatically be selected as well):

Archive
unzip
zip

Devel
autoconf
automake
binutils
cvs
expat
gcc
gcc-core
gcc-g++
gcc-mingw
gcc-mingw-core
gcc-mingw-g++
gdb
gettext
gettext-devel
git
libiconv
libtool
make
mingw-runtime
nasm
patchutils
pkg-config
subversion

Editor
vim

Libs
libgcrypt

Web
curl (optional: for building extras/contrib)
wget (optional: for building extras/contrib)

==Cygwin environment==

Start Cygwin from the icon on your desktop (With Windows Vista run it with admin rights, so right click and select "Run as administrator"). If it runs for the first time it will automatically create a home\"username" folder in the Cygwin environment; user being the currently logged on Windows user. Assuming this is the 'Administrator' user it will create the following folder:

C:\cygwin\home\Administrator (example)

NOTE: On your desktop, you can rightclick the Cygwin icon and (in the Options field of the Cygwin Properties) set the Command history Buffer size to as large as possible: 999. This setting will make it possible to scroll back further in the Cygwin environment.

=VLC source code=

== Git ==
The very latest VLC source code can be obtained through a tool called Git. The Cygwin package we're about to install comes with an internal git component.

cd /cygdrive/c/VLC/

git clone git://git.videolan.org/vlc.git

'''Note for Windows users using [http://www.cygwin.com Cygwin] (linux-like build environment):'''

Applies to:

Windows XP Service Pack 2 with Security Update '''KB925902''' installed
Windows XP Service Pack 3

There is a problem on Windows XP (and possibly on other Microsoft Operating Systems) with 'git clone' which aborts unexpectedly with a Cygwin error during the 'checking out files' (reproducable every time and at the same percentage) at the end of the clone procedure:

$ 2 [main] git 4012 D:\cygwin\bin\git.exe:
*** fatal error - '''could not load shell32, Win32 error 487'''

This has been verified (May 22, 2008) against the currently available Cygwin 1.5.25-12 with git package versions 1.5.5.1-1 and 1.5.4-1 and is a generic problem which also affects cloning from other git repositories (although x264.git seems unaffected).

The issue is referred to in the mail archives of the Cygwin project mailing list here
[http://sourceware.org/ml/cygwin/2007-07/msg00858.html Git error on Cygwin].

By eliminating the impossible, whatever remained, however improbable, it is the following Windows Security Update (April 3, 2007) which is actually the cause of the Cygwin issue: [http://www.microsoft.com/technet/security/bulletin/ms07-017.mspx Microsoft Security Bulletin MS07-017 - Vulnerabilities in GDI Could Allow Remote Code Execution (925902)]

Even though the same Security Update applies to the following systems, these are reported not to be affected:

Windows Vista Service Pack 1
Windows 2003 Server Standard Service Pack 2

''It is possible to get 'git clone' working again on the affected systems by removing the Security Update (KB925902) but this is obviously not recommended for security reasons.''

== Snapshots ==

You can do the same by using the snapshots in the nightly builds site.

=Bootstrap=

Open the configure.ac file, and modify the requirement for gettext 0.17 to 0.15 (so replace line '''AM_GNU_GETTEXT_VERSION(0.17)''' with line '''AM_GNU_GETTEXT_VERSION(0.15)'''), and then run bootstrap.

cd vlc
./bootstrap

= External libraries to the source code=

VLC depends on other libraries (code) to provide some features like AC3 audio or MPEG-4 video encoding/decoding etc.

Depending on your needs you will have to install and compile some or all of these external libraries.

== Get the Win32 "contrib" package ==

A package with most of these libraries already compiled so it's actually really easy to compile a full-featured version of vlc can be found here:

http://download.videolan.org/pub/testing/win32/

Download the latest version of a "contrib" package for win32:

contrib-20060730-win32-bin-gcc-3.4.5-only.tar.bz2 (example)

Those days, you should use
http://people.videolan.org/~jb/Contribs/contrib-20080215-win32-bin-gcc-4.2.1-sjlj-runtime-3.13-only.tar.bz2

It's a good idea to check the INSTALL.Win32 file in the VLC source directory for the appropriate contrib download file.

Save it into your download location:

C:\VLC\Downloads\

==Installing the Win32 "contrib" package in Cygwin==

Start Cygwin and enter the following command in your shell:

cd /cygdrive/c/VLC/Downloads
tar xf contrib-20080215-win32-bin-gcc-4.2.1-sjlj-runtime-3.13-only.tar.bz2 -C /

Replace with your version of the "contrib" file and DON'T FORGET THE / (slash)
at the end.

This will extract the contents of the file into usr/win32 folder within your Cygwin environment.

NOTE: Make sure to DELETE your old version (/usr/win32 folder) instead of extracting a new version on top of it.

==Keeping the Win32 "contrib" package up-to-date==

For maintenance purposes periodically check:

http://download.videolan.org/pub/testing/win32/

=Configure=

In order to make our lives just a bit easier the following section describes what commandline options should be used for compiling and those commands will then be put into a "script" that can be executed (rather than having to copy and paste all the time).

==Configure script for compiling VLC==

Create a new text document with the following lines:

PATH=/usr/win32/bin:$PATH \
PKG_CONFIG_PATH=/usr/win32/lib/pkgconfig \
CPPFLAGS="-I/usr/win32/include -I/usr/win32/include/ebml" \
LDFLAGS=-L/usr/win32/lib \
CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin" \
./configure \
--host=i686-pc-mingw32 \
--disable-gtk \
--enable-nls --enable-sdl --with-sdl-config-path=/usr/win32/bin \
--enable-ffmpeg --with-ffmpeg-mp3lame --with-ffmpeg-faac \
--with-ffmpeg-zlib --enable-faad --enable-flac --enable-theora \
--with-wx-config-path=/usr/win32/bin \
--with-freetype-config-path=/usr/win32/bin \
--with-fribidi-config-path=/usr/win32/bin \
--enable-live555 --with-live555-tree=/usr/win32/live.com \
--enable-caca --with-caca-config-path=/usr/win32/bin \
--with-xml2-config-path=/usr/win32/bin \
--with-dvdnav-config-path=/usr/win32/bin \
--disable-cddax --disable-vcdx --enable-goom \
--enable-twolame --enable-dvdread \
--enable-debug --enable-dca \
--disable-mkv --disable-taglib

NOTE: The following options are added for debug purposes and makes the final package a bit larger but the advantage is it's easier to debug in case of crash reports:

--disable-optimizations
--enable-debug

If you want to report a crash bug to the VLC team, it is necessary that you provide a stack backtrace. Unfortunately, Windows automatic crash reporter cannot generate such a backtrace as debug symbols used by GCC compiler aren't understood by Windows, therefore we suggest that you install Dr. MinGW (http://jrfonseca.dyndns.org/projects/gnu-win32/software/drmingw/) which will extend Windows Just-In-Time Debugger and provide the necessary debug information.

NOTE: The following options is needed for Qt4 support:

--enable-qt4

As of version 0.9.0 VLC will include the Qt interface. More information can be found about QT here: http://www.trolltech.com

The "Win32 contrib package" at present includes the linux and Windows equivalents of uic, moc and roc executables which are required for building this interface.

The linuxs executables have to be '''deleted''' from the contrib folder:

C:\cygwin\usr\win32\bin\moc (example)
C:\cygwin\usr\win32\bin\rcc (example)
C:\cygwin\usr\win32\bin\uic (example)

Save as filename in your "scripts" folder at your download/install location:

configure-vlc.sh

NOTE: Save using "All files" and not "Text files" otherwise Windows might append the extension .txt

Copy the file into your home directory:

C:\cygwin\home\Administrator

Start Cygwin and enter the following command in your shell:

dos2unix configure-vlc.sh

After your configure-vlc.sh is completed, copy it to your vlc directory and run it:

./configure-vlc.sh

If it complains about permissions, use chmod and try again:

chmod 777 configure-vlc.sh

NOTE. (If you plan to use JVLC) To make vlc-control.dll accessible by Java on ''Windows'' cofigure-vlc.sh should be modified to include "-Wl,--add-stdcal-alias". Example:

...
CC="gcc -mno-cygwin -Wl,--add-stdcall-alias" CXX="g++ -mno-cygwin -Wl,--add-stdcall-alias" \
./configure \
...

===POSIX emulation layer===

VLC can be built with or without the so called POSIX emulation layer. Without is the default and is usually better (and with hasn't been tested for quite some time). If you do want to use the emulation layer, then just leave out the line with the following options:

CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin"

=Compiling source code=

It's time to start Cygwin again...

==Compiling VLC==

Enter the following commands in your Cygwin shell:

cd vlc

Build it! (remember to run configure-vlc.sh before first build)

make

Cross your fingers and wait... because it might take few hours before compilation is done.
If you have multicore CPU or multi CPU box, you can use -j2 switch (or maybe -j3 or -j4 etc.) to speed up make process

make -j2

==Creating self contained packages==

Once the compilation is done, you can either run VLC directly from the source tree or you can build self-contained VLC packages with the following "make" commands:

make package-win32-base

(This will create a subdirectory named vlc-x.x.x with all the binaries "stripped" without any debugging symbols).

make package-win32-zip

(Same as above but will package the directory in a zip file).

make package-win32

(Same as above but will also create an auto-installer package. You will need to have NSIS installed in its default location for this to work).

=Advanced usage=

==Updating Cygwin package versions==

If you need to update or install additional packages you can just run the Cygwin setup.exe from your download location:

C:\Downloads\cygwin\setup.exe (example)

==GDB (Gnu Debugger)==

This section requires that you installed the gdb (Gnu Debugger) in Cygwin.

This is a typical example of creating a crashlog:

cd vlc-trunk

gdb --args vlc.exe --fast-mutex --reset-config --reset-plugins-cache

NOTE: vlc-0.9.0 uses libtool for building sources, if you want to debug from the source tree, you should type the following command instead:

libtool --mode=execute gdb --args vlc --reset-config --reset-plugins-cache

In the debugger mode run the program and make sure you reset the preferences!

(gdb) run

NOTE: the (gdb) is just a prompt which means you are in the debugger mode, please note that ''--fast-mutex'' option is no longer supported in vlc-0.9.0

It will now take a lot longer than usual for VLC to start :)

Now operate VLC as you would normally do. As soon as a crash issue occurs
you'll notice a line like this:

Program received signal SIGSEGV, Segmentation fault.
0x0041394c in playlist_ItemGetById (p_playlist=0x19ec4f8, i_id=29)
at src/playlist/item-ext.c:459
---Type <return> to continue, or q <return> to quit---
459 i = i_bottom + ( i_top - i_bottom ) / 2;

Now you can do a "backtrace" by using the bt command:

(gdb) bt

And output similar to this will be created:

#0 0x0041394c in playlist_ItemGetById (p_playlist=0x19ec4f8, i_id=29)
at src/playlist/item-ext.c:459
#1 0x0b26bbf7 in wxvlc::Playlist::CountItems (this=0x1822e288, root=
{m_pItem = 0x29fef8}) at playlist.cpp:695
#2 0x0b26bc83 in wxvlc::Playlist::CountItems (this=0x1822e288, root=
{m_pItem = 0x29e8b0}) at playlist.cpp:689
#3 0x0b26bc83 in wxvlc::Playlist::CountItems (this=0x1822e288, root=
{m_pItem = 0x29a818}) at playlist.cpp:689
#4 0x0b26bc83 in wxvlc::Playlist::CountItems (this=0x1822e288, root=
{m_pItem = 0x299718}) at playlist.cpp:689
#5 0x0b26bc83 in wxvlc::Playlist::CountItems (this=0x1822e288, root=
{m_pItem = 0xffff0000}) at playlist.cpp:689
#6 0x0b26bf49 in wxvlc::Playlist::AppendItem (this=0x1822e288,
event=@0x1827afd0) at playlist.cpp:564
#7 0x0b2757fc in wxvlc::Playlist::OnPlaylistEvent (this=0x1822e288,
event=@0x1827afd0) at playlist.cpp:1438
#8 0x0b3771b8 in wxEvtHandler::ProcessEventIfMatches ()
at /usr/win32/include/wx-2.6/wx/event.h:2183
#9 0x0b376a1c in wxEventHashTable::HandleEvent ()
at /usr/win32/include/wx-2.6/wx/event.h:2183
#10 0x0b37730d in wxEvtHandler::ProcessEvent ()
at /usr/win32/include/wx-2.6/wx/event.h:2183
#11 0x0b37711b in wxEvtHandler::ProcessPendingEvents ()
at /usr/win32/include/wx-2.6/wx/event.h:2183
---Type <return> to continue, or q <return> to quit---
#12 0x0b376017 in wxAppConsole::ProcessPendingEvents ()
at /usr/win32/include/wx-2.6/wx/event.h:2183
#13 0x0b3ec75a in wxIdleWakeUpModule::MsgHookProc ()
at /usr/win32/include/wx-2.6/wx/bmpbuttn.h:81
#14 0x773aca2d in USER32!GetScrollRange ()
from /cygdrive/c/WINDOWS/system32/user32.dll
#15 0x00000000 in ?? () from
(gdb)

To backtrace all the running threads use:

(gdb) thread apply all bt

These are the log outputs that are more usefull to developers than just mentioning "it crashes"!

NOTE: In GDB mode there are sometimes situations where GDB initially "crashes" on certain network activity (opening network shares, network traffic) which in normal operation does not occur. Just select c for continue until "normal" operation continues.

== Common errors ==
===vlc.exe: Permission denied===

A make finished successfully and produced vlc.exe, but running the executable returns the following:

bash: ./vlc.exe: Permission denied

The permissions on both vlc.exe & vlc.exe.manifest must be set to executable.

FIX: Type the following:

chmod 755 vlc.exe vlc.exe.manifest

===error: parse error before '(' token===

A make (compile) of FFmpeg results in the following error:

/usr/include/sys/unistd.h:203: error: parse error before '(' token
make[1]: *** [ffm.o] Error 1

It's very likely you are usix the POSIX emulater which you shouldn't...

FIX: compile with the option

-mno-cygwin

==error: expected primary-expression before '<<' token==

In file included from /usr/lib/gcc/i686-pc-mingw32/3.4.4/../../../../include/w32
api/windows.h:52,
from ../../../include/vlc_common.h:459,
from ../../../include/vlc/vlc.h:153,
from dshow.cpp:31:
/usr/lib/gcc/i686-pc-mingw32/3.4.4/../../../../include/w32api/wingdi.h:3:1: warn
ing: this is the location of the previous definition
In file included from /usr/win32/include/dshow.h:35,
from common.h:45,
from dshow.cpp:35:
/usr/win32/include/ddraw.h:14: warning: ignoring #pragma warning
In file included from /usr/win32/include/dshow.h:35,
from common.h:45,
from dshow.cpp:35:
/usr/win32/include/ddraw.h:5552: warning: ignoring #pragma warning
In file included from /usr/win32/include/dshow.h:45,
from common.h:45,
from dshow.cpp:35:
/usr/win32/include/strmif.h:2: warning: ignoring #pragma warning
In file included from /usr/win32/include/dsound.h:13,
from /usr/win32/include/amaudio.h:18,
from /usr/win32/include/dshow.h:47,
from common.h:45,
from dshow.cpp:35:
/usr/win32/include/d3dtypes.h:22: warning: ignoring #pragma warning
/usr/win32/include/d3dtypes.h:1813: warning: ignoring #pragma warning
In file included from /usr/win32/include/dshow.h:48,
from common.h:45,
from dshow.cpp:35:
/usr/win32/include/control.h:2: warning: ignoring #pragma warning
dshow.cpp: In function `int CommonOpen(vlc_object_t*, access_sys_t*, vlc_bool_t)
':
dshow.cpp:456: error: expected primary-expression before '<<' token
dshow.cpp:456: error: expected primary-expression before '<<' token
dshow.cpp:456: error: expected primary-expression before '<<' token
dshow.cpp:456: error: expected primary-expression before '<' token
dshow.cpp:456: error: expected primary-expression before '.' token
dshow.cpp:470: error: expected primary-expression before '==' token
dshow.cpp:470: error: expected primary-expression before '==' token
dshow.cpp:470: error: expected primary-expression before '==' token
dshow.cpp:470: error: expected primary-expression before '=' token
dshow.cpp:484: error: expected primary-expression before '>>' token
dshow.cpp:484: error: expected primary-expression before '>>' token
dshow.cpp:484: error: expected primary-expression before '>>' token
dshow.cpp:484: error: expected primary-expression before '>' token
dshow.cpp:484: error: expected primary-expression before '.' token
dshow.cpp:485: error: expected `;' before "IAMCrossbar"
dshow.cpp:491: error: `pXbar' undeclared (first use this function)
dshow.cpp:491: error: (Each undeclared identifier is reported only once for each
function it appears in.)
make[6]: *** [libdshow_plugin_a-dshow.o] Error 1
make[6]: Leaving directory `/home/Administrator/vlc-trunk/modules/access/dshow'
make[5]: *** [all-modules] Error 1
make[5]: Leaving directory `/home/Administrator/vlc-trunk/modules/access/dshow'
make[4]: *** [all-recursive] Error 1
make[4]: Leaving directory `/home/Administrator/vlc-trunk/modules/access'
make[3]: *** [all] Error 2

Basically in case of conflict svn adds "<<< mine" and "=======" and ">>>> r1242" which makes gcc complain.

FIX: revert the offending file

==Objective C source seen but `OBJC' is undefined==

The configure process stops halfway.

+ aclocal-1.9 -I m4
+ autoconf
+ autoheader
+ automake-1.9 --add-missing --copy -Wall
configure.ac: installing `autotools/install-sh'
configure.ac: installing `autotools/missing'
activex/Makefile.am:143: shell $(VLC_CONFIG: non-POSIX variable name
activex/Makefile.am:143: (probably a GNU make extension)
activex/Makefile.am: installing `autotools/compile'
activex/Makefile.am: installing `autotools/depcomp'
modules/gui/macosx/Makefile.am: Objective C source seen but `OBJC' is undefined
modules/misc/testsuite/Makefile.am: Objective C source seen but `OBJC' is undefi
ned
src/Makefile.am: Objective C source seen but `OBJC' is undefined
Makefile.am:282: user target `vlc$(EXEEXT)' defined here...
/usr/share/automake-1.9/am/program.am: ... overrides Automake target `vlc$(EXEEX
T)' defined here
Makefile.am:230: while processing program `vlc'
make: *** No targets specified and no makefile found. Stop.

This problem is related to a warning earlier on and only occured in a few revisions where a built-in workaround wasn't working properly:

+ echo 'Enabling provisional autoconf 2.59 work-around. Update autoconf ASAP.'
Enabling provisional autoconf 2.59 work-around. Update autoconf ASAP.

FIX: update autoconf to 2.60 or newer. If Cygwin doesn't provide this version yet then build it yourself from extras/contrib.

Enter the following commands in your Cygwin shell:

cd vlc-trunk/extras/contrib

./bootstrap

cd src

make .autoconf

There should now be compiled autoconf version (probably 2.60 or newer) in extras/contrib that the bootstrap process will use.

Now start the whole "Compile VLC" process from the start again.

==Error: cannot create temporary file for diversion: Permission denied==

If the above error appears, it might mean you don't have the TMPDIR defined in cygwin. You will need to define it and have its value point to your temporary directory. You can use '''export TMPDIR="/cygdrive/c/temp"''' or any directory for it (/cygdrive/c/temp is same as C:\temp). If this doesn't help, make sure you run cygwin with admin rights (With Windows Vista, right click cygwin shortcut and select "Run as administrator"). Avira AntiVir might also cause issues to m4, so disabling it while ./bootstrap might help.

=Version=

20050627 Initial version

20050628 Updated some more exceptions

20050628 Some info added about FFmpeg compiling with AMR

20050629 Finalized FFmpeg compiling

20050630 Cross-compiling

20050724 Some extra compile explanations

20050726 Removed cross-compiling (was for linux -> win32) Patching source code with .diff files

20050823 Added zlib error

20050923 --enable-sdl --with-sdl-config-path=/usr/win32/bin added to configure. Added debug section

20051102 Changed FFmpeg lib names

20051128 Detailed Cygwin upgrade/downgrade for gcc 3.3. Renamed some update scripts. Added FFmpeg CVS update. --disable-gnomevfs added to configure (only used on linux)

20060121 PKG_CONFIG_PATH=/usr/win32/lib/pkgconfig added to configure

20060128 Added curl and libtool to Cygwin for those that want to be able to build extras/contrib themselves

20060217 Added make install-libs install-headers to FFmpeg compile

20060222 Remark about missing "gettext" libs for Cygwin during install

20060225 ./bootstrap: you need libtool

20060618 Updated GCC to 3.4 version and added FFmpeg SVN and DTS support

20060805 Added note about using older binutils and gdb for Cygwin!

20060915 Added note about updating autoconf from extras/contrib for an OBJC problem during configure

20061108 Added note this document is no longer usable since Cygwin has been unusable probably related to some bash/dos2unix change

20070612 Added note about --enable-dca

20080228 New version by [[User:J-b|jb]]

20080307 Added --host=i686-pc-mingw32 option to the configure script

20080311 Simplification

20080323 Added some tips for Vista

[[Category:Building]]
[[Category:Coding]]