How to Contribute to Libav (VLC)

I happened to have a few hours free and I was looking for some coding to do. I thought about VLC, the media player which I have enjoyed so much using over the years and I decided that I wanted to contribute in some way.

To start helping in such a complex process there are a few steps involved. Here I describe how I got my first patched accepted. In particular I wrote a patch for libav, the library behind VLC.

The General Picture

I started by reading the wiki. It is a very helpful starting point but the process to setup the environment and send a first patch was not yet 100% clear to me. So, I got in touch with some of the developers of libav to understand how they work and how I could start lending an hand with something simple. They explained me that the easier way to start is by solving issues reported by static analysis tools and style checkers. They use uncrustify to verify that the code is adhering to their style guidelines and they run coverity to check for potential issues like memory leaks or null deferences. So I:

• started looking at some coverity issues
• found something easy to address (a very simple null deference)
• prepared the patch
• submitted the patch

After a few minutes the patch was approved by a committer, ready to be merged. The day after it made its way to the master branch. Yeah!

Download Source code, Build libav and Run the Tests

First of all, let’s clone the git repository:

git clone git://git.libav.org/libav.git

Alternatively you could use the GitHub mirror, if you want to.

At this point you may want to install all the dependencies. The instructions are platform specific, you can find them here. If you have Mac Os-X be sure to have installed yasm, because nasm does not work. If you have installed both configure will pick up yasm (correctly). Just be sure to run configure after installing yasm.

If everything goes well you can now build libav by running:

./configure
make

Note that it is fine to build in-tree (no need to build in a separate directory).

Now it is time to run the tests. You will have to specify one directory where to download some samples, later used by tests. Let’s assume you wanted to put your samples under ~/libav-samples:

mkdir ~/libav-samples
# This download the samples
make fate-rsync SAMPLES=~/libav-samples
# This run the tests
make fate

Did everything run fine? Good! Let’s start to patch then!

Write the Patch

First of all we need to find an open issue. Visit Coverity page for libav at https://scan.coverity.com/projects/106. You will have to ask for access and wait that someone grants it to you. When you will be able to login you will encounter a screen like this:

Here, this seems an easy one! The variable oggstream has been allocated by av_mallocz (basically a wrapper for malloc) but the result values has not been checked. If the allocation fails a NULL pointer is returned and when we will try to access it at the next line things are going end up unpleasantly. What we need to do is to check the return value of av_mallocz and if it is NULL we should return an error. The appropriate error to return in this case is AVERROR(ENOMEM). To get this information… you have to start reading code, getting familiar with the way of doing business of this codebase.

Libav follows strict rules about the comments in git commits: use git log to look at previous commits and try to use the same style.

Submitting the Patch

I think many of you are familiar with GitHub and the whole process of submitting a patch for revision. GitHub is great because it made that process so easy. However there are some projects (notably including the Linux kernel) which adopts another approach: they receive patches by e-mail.

Git has a functionality that permits to submit a patch by e-mail with a simple command. The patch will be sent to the mailing list, discussed, and if approved the e-mail will be downloaded, processed through git and committed in the official repository. Does it sound cumbersome? Well, it sounds to me, spoiled as I am by GitHub and similar tools but, you know, if you go in Rome you should behave as the Romans do, so…

Sending Patches using Gmail with 2-factor Authentication Enabled

Now, many of you are using Gmail and many of you have enabled 2-factor authentication (right? If not, you should). If this is you case you will get an error along this lines:

Password for 'smtp://[email protected]@smtp.gmail.com:587': 5.7.9 Application-specific password required. Learn more at 5.7.9 http://support.google.com/accounts/bin/answer.py?answer=185833 cj12sm14743233wjb.35 - gsmtp

Here you can find how to create a password for this goal: https://support.google.com/accounts/answer/185833 The name of the application that I had to create was smtp://[email protected]@smtp.gmail.com:587. Note that I used the same name specified in the previous error message.

What If I Need to Correct My Patch?

If things go well an e-mail with your patch will be sent to the mailing-list, someone will look at it and accept it. Most of the times you will receive suggestions about possible adjustments to be done to improve your patch. When it happens you want to submit a new version of your patch in the same thread which contains your first version of the patch and the e-mails commenting it.

To do that you want to update your patch (typically using git commit –amend) and then run something like:

git send-email -1 --to [email protected] --in-reply-to Message-ID: [email protected]

Of course you need to find out the message-id of the e-mail to which you want to reply. To do that in Gmail select the “Show original” item from the contextual menu for the message and in the screen opened look for the Message-Id header.

Tools to Manage Patches Sent by E-mail

There are also web applications which are used to manage the patches sent by e-mail. Libav is currently using Patchwork for managing patches. You can see it deployed at: https://patches.libav.org/project/libav-devel/list/. Currently another tool has been developed to replace patchwork. It is named Plaid and I tried to help a little bit with that also :)

Conclusions

Mine has been a very small contribution, and in the future I hope to be able to do more. But being a maintainer of other open-source projects I learned that also small help is useful and appreciated, so for today I feel good.

Please, if I am missing something help me correct this post