.. _comphowto:

Contribute Components
=====================

Preconditions: Installation of :ref:`cca`, :ref:`rci` and :ref:`rcirst`.
Currently this how-to is quite AMARSi-specific and you need credentials for the
`AMARSi Redmine <https://redmine.amarsi-project.eu>`_.

1. Check out the component repository

  Use :ref:`git <http://git-scm.com/>` to check out the component repository.

  .. code-block:: sh

    git clone https://USERNAME@redmine.amarsi-project.eu/git/components.git
  
  where :samp:`{USERNAME}` is your
  `AMARSi Redmine <https://redmine.amarsi-project.eu>`_ credential.

2. Copy and adapt the template

  Copy the component template 

  .. code-block:: sh

    cd components
    cp -R cca-component YOURNAME
    cd YOURNAME
  
  where :samp:`{YOURNAME}` is your component name (avoid white-spaces).
  
3. Change the name of the component, by adapting the first lines :samp:`{COMPONENTNAME}`
  and :samp:`{COMPONENTDESCRIPTION}` of the file ``CMakeList.txt`` of your
  component folder. 

4. Test

  The component template should be working out of the box. Try to build it and
  check the example.

  .. code-block:: sh

    cd build
    cmake ..
    make

  After the project is build you should be able to execute the component example.

  .. code-block:: sh

    build/pingpong  

5. Implement your component

  * Adapt cmake for dependencies
  * Implement component in its ``src/`` folder
  * Implement example in its ``bin/`` folder
  
  **TODO:** *Dependency handling*

6. Add the component to the repository

  To initially add your component to the component repository (this has to be
  done once), do:

  .. code-block:: sh

    git add YOURNAME
    git commit -m "Added component COMPONENTNAME"
    
  where :samp:`{YOURNAME}` is your component folder and :samp:`{COMPONENTNAME}`
  is the name of your component.
  
  If your component is added to the repository, you can later on push changes
  of your component via:

  .. code-block:: sh

    git pull origin master
    git add CHANGEDFILES
    git commit
    git push origin master
    
  where :samp:`{CHANGEDFILES}` are all the files you changed and want to push
  to the repository.