Contributor's guide =================== The development of Aery32 Framework happens in GitHub, which is a web-based hosting service that use the Git revision control system. To contribute the code you have to have a GitHub account. After that you can `fork `_ Aery32 repository and start contribute by sending `pull request `_. GitHub has a good beginners guide about `how to set up Git in Windows `_. Sending a pull request (creating a patch) ----------------------------------------- Fixes are sent as `pull requests `_. Before you start fixing the Aery32 library, create a new branch and code your patch in this new branch. If there is a reported issue you are fixing, name the branch according to the GitHub issue number, e.g. gh-02. The benefit of this approach is that you can have plenty of fixes which are isolated from each others, especially from the master branch. Coding standards ---------------- Follow `Linux kernel coding style `_. .. code-block:: c #include typedef struct Foo Foo; typedef struct Bar Bar; struct Foo { Bar *bar; }; struct Bar { Foo *foo; }; /** * Initializes io pins (define the function briefly at the first line) * \param allinput If true all pins initialized as inputs * * More detailed description comes here. Remember to use param names * within the function prototypes too. */ void init_io(bool allinput); void init_io(bool allinput) /* Layout functions like this */ { int i; /* Use space between the syntactic keywords and opening parenthesis */ for (i = 0; i < 2; i++) { AVR32_GPIO.port[i].gpers = 0xffffffff; if (allinput == 0) /* Do not use curly braces if not needed */ AVR32_GPIO.port[i].oders = 0xffffffff; else AVR32_GPIO.port[i].oderc = 0xffffffff; } } int main(void) { char *c; Foo foo; Bar bar; bar.foo = &foo; /* * This is multiline comment that reminds you not to use compound literals * in Aery32 library, because avr32-g++ does not support those. What's * compound literal? This is: bar = (Bar) {.foo = &foo}; */ for (;;) { /* This is how infinite loops are written */ } return 0; } Writing the documentation ------------------------- The documentation is constructed by Sphinx. Sphinx is a Python documentation generator but works fine for C as well. The source files of this documentation are located at the separate GitHub repository, https://github.com/aery32/aery32-refguide. To build local html version of this documentation use make:: make html The following commands assume you have Sphinx installed -- if not, see the installation instructions below. Now browse to ``source/`` directory and open the ``index.rst``. This is the master document serving as a welcome page and "*table of contents tree*". To edit these source files just open the file in your favorite editor and be sure to edit in UTF-8 mode. To understand reSt syntax start from http://sphinx.pocoo.org/rest.html. Installing Sphinx ''''''''''''''''' **In Windows** *Case 1: I do have Python already installed* If you do have Python installed already, then you likely have setuptools installed as well. In this case install Sphinx with easy_install. Fire your command prompt (Win+R cmd) and command:: easy_install -U Sphinx Otherwise follow steps below to install Python first and then Sphinx. *Case 2: I don't have Python installed* .. note:: We do not install setuptools here and thus do not use easy_install to install Sphinx. However you will get it installed along Sphinx installer and it is recommended to use it later when installing other Python packages. - Create temporary directory (e.g. myfoo) where to download the following things: - Python 2.7.x from http://python.org/download/ - Sphinx 1.1.2 from http://pypi.python.org/pypi/Sphinx - When the both download processes have been completed, you should have these two files: - ``python-2.7.2.msi`` or ``python-2.7.2.amd64.msi`` if you downloaded 64-bit version - ``Sphinx-1.1.2.tar.gz`` - First install Python by double clicking Python installer - After successful installation of Python, untar ``Sphinx-1.1.2.tar.gz`` into temporary directory - The exctarction process creates the ``Sphinx-1.1.2`` directory, change to that directory and double click setup to install Sphinx - Once the Sphinx installation is complete, you will find sphinx-xxx executables in your Python Scripts subdirectory, ``C:\Python27\Scripts``. Be sure to add this directory to your PATH environment variable. As you can see, this directory includes now also easy_install executable, which you should use later to install other Python packages. - You can now remove the temporary directory