User Tools

Site Tools


library-hacking

How to modify / enhance the ROHC library?

Follow this procedure in order to know how to get and modify the in-development source code of the ROHC library and send your changes for inclusion in the library.

Get source code with Git

In order to modify the ROHC library, you must first get the in-development source code of the library. This may be achieved by using the Version Control System (VCS) called Git. Git may often be found in the software packages of your distribution. Otherwise, get it from the official web site. You may also want to read the Git documentation. In any case, you may get help by running git –help or git <command> –help at the shell prompt.

To get a fresh copy of the source code, type the following:

$ git clone https://github.com/didier-barvaux/rohc.git

You should now have a copy of the ROHC repository on your disk in the rohc subdirectory.

You may speed up the download by retrieving only the last N changesets, eg. for 10 changesets:

$ git clone --depth 10 https://github.com/didier-barvaux/rohc.git

Build the source code

Enter the rohc subdirectory and then follow the instructions to configure and build the library starting with step 4.

Run the non-regression tests

Follow the instructions to run the non-regression tests. It is important that there is no regression in the source code before you start modifying the library.

Modifying the source code

First create a local Git branch to host your changes:

$ git checkout -b dev_my_cool_feature

Then, use your favorite code editor to change the source code of the ROHC library.

You may have a look at the API documentation. You may also read the questions asked by developers on the public mailing list dedicated to the ROHC library or send new questions by subscribing to the list.

Building and testing your changes

Please build your changes on different environments. Please also test your changes by running the library tests. Adding new tests that check your changes is also a great idea.

Submitting your modifications

Add all new source or capture files with Git:

$ git add <new source files> <new captures files>
$ git commit

Your default editor pops up. Write a short summary on first line, leave an empty line, then write a longer description on the next lines. Example:

TCP profile: handle sack_unchanged_irregular() encoding
    
The ROHC compressor had no support for the sack_unchanged_irregular()
encoding, so the decoding part in the ROHC decompressor was untested
and wrong.

This change adds support for the sack_unchanged_irregular() encoding to
the ROHC compressor. It also fixes the support at decompressor.

The problem was reported and fixed by Klaus Warnke in bug #1496023.

Make more changes if needed. Don't forget to add and commit them.

When your feature is complete, create the patches that contains all your modifications with Git:

$ git format-patch -o patches/ remotes/origin/HEAD

The generated patches are available in the patches/ folder.

Now, send an email to the ROHC mailing list. Please describe carefully your changes and attach your patches. Be careful to not send too large attachments (this could be the case if you added some non-regression tests with PCAP files). Put your files on a public HTTP/FTP server or any upload platform of your choice and send a link to them to the mailing list. You may also upload your Git repository to GitHub.

library-hacking.txt · Last modified: 2016/01/03 20:50 by didier