========================
Structure of Directories
========================
* common
  Contains the heart of the h264 decoder. These algortihms are common to all decoders.
* decoder_xx
  Contains the sources of a specific decoder. These sources are not common.
* script
  Contains some useful scripts to make backups, to create a new decoder structure and others.

==================================
To configure and execute a decoder
==================================
In the following part, we will deal with the decoder_x86, but all the information given in this document can be applied to any of the other decoder present in the main decoder_h264 directory.

1)  Creation of the configuration files
	% cd decoder_x86
	% ./script/bootstrap.sh
	--> These commands will create the configure and Makefile files
2)  Configuration of the decoder
	* in native configuration (e.g. x86) do:
		% ./configure
	* in cross-compile configuration (e.g. arm) do:
		% ./configure --host=arm CC=path_to_cross_compiler/bin/arm-none-linux-gnueabi-gcc
3)  Compilation and creation of executables
	% make

===============================
To create a new decoder version
===============================
1)  New directory creation
	Go in the script directory and copy the structure for new decoder:
	% cp scipt/create_new_decoder .
	% mv create_new_decoder decoder_your_decoder_name
2)  Add sources
	Copy the sources of your decoder in the directory
	decoder_your_decoder_name/src
3)  Create configure.ac
	Edit the configure.ac file and modify the following line:
	AC_INIT(decoder_your_decoder_name,your_version)
	--> decoder_your_decoder_name: exemple decoder_x86
	--> your_version: exemple 0.1
4)  Create Makefile.am structure
	Edit the src/Makefile.am file and modify the follwing variables
	--> your_exe_name: exemple myplayh264
	--> sourceX.c: exemple h264.c etc.
5)  Create a link to common files
	% ln -s ../common


===================================
Management of the project using git
===================================

BASIC COMMANDS OF GIT
---------------------
* git-add: filenameordirectory: add a file or a directory to the tracked GIT data
* git-branch: show all the available branches
* git-branch nameofthebranch: create a new branch
* git checkout nameofthebranch: change current branch to another branch
* git-commit: store the modification made on a branch
* git-init-db: create an empty git repository
* git-reset --hard HEAD: remove all modifications made since last commit
* git-reset --hard ORIG_HEAD: after committed a modification, remove this last commit and return to the previous commit



HOW TO GIVE USERNAME AND PERSONAL E-MAIL TO GIT
-----------------------------------------------
Two solutions:
* Solution 1:
  Type following commands:
  % git config --global user.name "yourusername"
  % git config --global user.email yourpersonalemail
  NOTE: option "--global" means that the settings will be specified for all repository on the computer

* Solution 2:
  Modifty or add following line in the file ".git/config" of your git clone or repository:
[user]
	email = yourpersonalemail
	name = yourusername

NOTE: You can make this settings global by adding or modifying it in ~/.gitconfig file


CLONE A REPOSITORY AND BASIC COMMANDS
-------------------------------------
1) How to clone a repository?
* You can clone a repository with the following command:
  % git clone whereistherepository nameoftheclone
* To clone from an SSH connexion type the following command:
  % git clone username@ip_address:whereistherepository nameoftheclone
  example:
  % git clone t0043357@192.168.0.1:/home/sources/decoder_h264 clone_decoder_h264

  --> It will download the current branch of the repository. If you type "git branch", you will see only the downloaded branch.
      To see all branches, type "git branch -a"

2) How to work on a branch?
To work with another branch than the downloaded branch, you have to create a local branch of your work.

For example, you want to work with decoder_x86, and the clone only have "common" branch.
  1) Type:
     % git branch -a
     --> You will certainly see a branch with the following name "origin/decoder_x86"
  2) To make a local branch of this branch, type:
     % git checkout -b decoder_x86 origin/decoder_x86
  3) Type:
     % git branch
     --> Now you have a branch with the name "decoder_x86"


3) How to update your modifications in the main tree?
   1) Go in the main tree repository: /home/decoder_h264
   2) Select the appropriate branch that is to be updated
   3) Pull the modifications from the clone
      % git-pull /path_to_clone
   4) Update the clone with new values of the main tree. In the clone directory type:
      % git-pull

WARNING: If the GIT repository is in the same branch you update, your modifications will not appear directly on the repository.
  If no modification have been made in the local repository: type: git reset --hard HEAD ; the branch will go to the last commit, corresponding to the modification you send
  Else, you have to solve conflicts...


DIFFERENT SITUATION WHEN MODIFYING A COMMON FILE / HOW TO COMMIT A MODIFICATION ON A COMMON FILE?
-------------------------------------------------------------------------------------------------
Situation 1: modification in the common branch
In this case, the user directly modifies the files of the common branch.
   1) Checkout the common branch
      % git checkout common
   2) Make your modifications
   3) Commit your modifications on the branch common:
      % git commit -a -m "Your Message about the modifications"
   4) If the change is a major change, then:
      * Create a tag for this change in the branch
      * Create a "for merge" branch:
        % git branch common_for_merge

Situation 2 - You made a modification only on common files on your own branch without committing it more than one times
   1) Commit your modifications on your own branch:
      % git commit -a -m "Your Message about the modifications"
   2) Go to the common branch:
      % git checkout common
   3) Pick the last commit you made on your own branch:
      % git cherry-pick nameofyourownbranch

Situation 3 - You made some modifications only on common files on your own branch and committing it more than one times
  1) Commit your last modifications on your own branch:
     % git commit -a -m "Your Message about the modifications"
  2) Two cases:
    - Case 1: you want to keep all the commit you made
      a) Count the number of commit you made on the common files
      b) Go to the common branch:
         % git checkout master
      c) Pick the older commit you made on your own branch:
         % git cherry-pick nameofyourownbranch^^^^ where there are as many "^" as the number of commit-1
         For example: you made three commits. The first "cherry-pick" you made is git cherry-pick nameofyourbranch^^
      d) Remove one "^" and type the last command until you type: git cherry-picj nameofyourbranch

    - Case 2: only one commit for all the modifications is sufficient
      a) Copy the entire common directory on a local directory (with no link with the Git repository): for example: cp -r common ~/
      b) Go to the common branch:
         % git checkout common
      c) Remove the common directory:
         % rm -rf common //a bit violent we know ...
      d) Copy the modified common directory:
         % cp -r ~/common .
      e) Commit the new common directory:
         % git commit -a -m "Your Message about all the modifications of the common directory"

To update a decoder with the new version of common:
   1) Go to a decoder branch:
      % git checkout nameofthebranch
   2) Merge the modification on the branch:
      % git merge common_for_merge



================
  Error on Git
================
Error "Trailing whitespace”: 
----------------------------
Reason: carriage-return/line-feed(windows style line feed/end)
Solution: comment following lines(58-60) in .git/hooks/pre-commit file:
	58.  if (/\s$/) {
	59.    bad_line("trailing whitespace", $_);
	60. }

Error “Indent SP followed by a TAB”:
------------------------------------
Reason: leading spaces/tabs
Solution: comment following lines(61-63) in .git/hooks/pre-commit file:
	61. if (/^\s*   /) {
	62.   bad_line("indent SP followed by a TAB", $_);
	63. }


Authors:
 - Pierre-Edouard Beaucamps
 - Florian Broekaert
 - Fabien Colas-Bigey
