Skip to content

Commit 6757650

Browse files
LinjingZhangLinjingZhang
committed
docs/: Add Development Instuctions in Documentation.
Signed-off-by: zhanglinjing <[email protected]>
1 parent b0c76ca commit 6757650

File tree

5 files changed

+143
-51
lines changed

5 files changed

+143
-51
lines changed

‎CONTRIBUTING.md

+7-49
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,14 @@
11
# Contributing to XMC for Arduino
22
First important point: **All Contributions** are welcomed :open_hands:.
33

4-
Please contribute and raise issues via the [github repository](https://github.com/Infineon/XMC-for-Arduino/tree/master)
4+
Please contribute and raise issues via the [github repository](https://github.com/Infineon/XMC-for-Arduino/tree/master).
55

66
## Overview for Contributors
77

8-
- Start your contribution by creating a [fork](https://github.com/Infineon/XMC-for-Arduino/fork) of this repository
9-
- It's recommended to create a separate branch for your contribution in your fork
10-
- Once your contribution is ready & tested, please create a [Pull Request](https://github.com/Infineon/XMC-for-Arduino/compare) to the master branch
11-
- Once we merged your changes to the master branch, they are automatically included in the next release
8+
- Start your contribution by creating a [fork](https://github.com/Infineon/XMC-for-Arduino/fork) of this repository.
9+
- It's recommended to create a separate branch for your contribution in your fork.
10+
- Once your contribution is ready & tested, please create a [Pull Request](https://github.com/Infineon/XMC-for-Arduino/compare) to the master branch. We have some automated tests, so make sure you've browsed our [CODE CONVENTION](CODE_CONVENTION.md) and [development instructions](https://xmc-arduino.readthedocs.io/en/latest/development-instructions.html)
11+
- Once we merged your changes to the master branch, they are automatically included in the next release.
1212

13-
## Install the BSP under development (on Windows)
14-
Clone the repository in Arduino folder:
15-
- Open Arduino and install any version of this project as described [here](https://xmc-arduino.readthedocs.io/en/latest/installation-instructions.html).
16-
- Open the installation location in your Arduino program folder, e.g.
17-
`C:\Users\<username>\AppData\Local\Arduino15\packages\Infineon\hardware\xmc`
18-
- Open git bash, type command:
19-
`git clone <your-xmc-for-arduino-fork> <version>`
20-
21-
This allows quick testing of local changes during development.
22-
23-
[!TIP]
24-
If you encounter strange behavior with Arduino IDE during development, try cleaning up the cache:
25-
* Windows: `C:\User\"username"\AppData\Roaming\arduino-ide`
26-
* Linux: `~/.config/arduino-ide`
27-
* macOS: `~/Library/Application Support/arduino-ide/`
28-
29-
## Automated Build Checks
30-
31-
Currently a Github workflow is used for automatic compilation checking and releasing. Workflows are defined [here](https://github.com/Infineon/XMC-for-Arduino/tree/master/.github/workflows).
32-
Before opening a Pull Request for your contribution, please add a git tag in the format `Vx.y.z` (e.g. V3.3.0) to trigger the release process in your fork and pass the compilation tests.
33-
34-
## Creating and Maintaining Third Party Libraries
35-
### Basics
36-
The Arduino IDE allows for external libraries to be added to support specific devices and functions which are not part of the core setup. For details on creating libraries see the
37-
[Arduino library specifications](https://arduino.github.io/arduino-cli/library-specification/). If you add additional libraries to this project, make sure to [document them](https://xmc-arduino.readthedocs.io/en/latest/builtin-libraries.html) accordingly.
38-
39-
### XMC-for-Arduino Configuration
40-
To ensure that a library specific to one architecture or board type is only compiled when a supporting board is set up, this specification includes a setting for *architecture* in the *library.properties* file.
41-
42-
When creating or maintaining third party or external libraries for XMC-for-Arduino please use this setting:
43-
~~~
44-
architecture=xmc
45-
~~~
46-
47-
If your library also supports other boards and architectures, add those in as well.
48-
49-
## Validation test
50-
To test the XMC4arduino, we used unity to test some of the features of the arduino core & builtin library.
51-
52-
Tests are located in tests/arduino-core-tests and included as submodule in this project. Run `git submodule update --init --recursive` to update them. If you are nor familiar with submodules, check out: https://git-scm.com/book/en/v2/Git-Tools-Submodules
53-
54-
## Code checks (WIP)
55-
Refer to libraries\CAN\Makefile.codecheck
56-
* Regarding formatting, we currently use [pre-commit](https://pre-commit.com/) to automatically run clang-formatting to format all c/c++ code. Please install this python package, and follow the quick start (the pre-commit configuration file is already there). You should be able to format your code automatically on git commit!
13+
## Development
14+
Please check [development instructions](https://xmc-arduino.readthedocs.io/en/latest/development-instructions.html) section in our documentation for more information on how to set up your development enviroment and start developing XMC4Arduino!

‎docs/conf.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,8 @@
4646

4747
extensions = [
4848
# 'sphinx.ext.autodoc',
49-
# 'sphinxemoji.sphinxemoji',
50-
# 'sphinx_tabs.tabs',
49+
'sphinxemoji.sphinxemoji',
50+
'sphinx_tabs.tabs',
5151
# 'sphinx.ext.intersphinx',
5252
# 'sphinx.ext.autosectionlabel',
5353
# 'sphinx.ext.todo',

‎docs/development-instructions.rst

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
Development Instructions
2+
=========================
3+
4+
..
5+
TODOS:
6+
- Contribution guidelines (move here from Contributing.md)
7+
- Code conventions
8+
- ....
9+
- Tools installation:
10+
- pre-commit hook?
11+
- spellchecker
12+
- ...
13+
14+
.. _env_dev_setup:
15+
16+
Environment setup
17+
------------------
18+
19+
#. Pre-conditions:
20+
21+
* Install `Arduino IDE (2.0 or higher) <https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing/>`_
22+
* Or Install `Arduino CLI (1.0.0 or higher) <https://arduino.github.io/arduino-cli/latest/installation/>`_
23+
* Python (you need this for upload/ flash XMC board anyways)
24+
25+
#. Create an ``<SKETCHBOOK>/hardware/arduino-git`` folder. Where ``<SKETCHBOOK>`` is the location of your Arduino sketchbook. The ``<SKETCHBOOK>`` default is OS-dependent:
26+
27+
.. tabs::
28+
29+
.. group-tab:: Linux
30+
31+
::
32+
33+
{HOME}/Arduino
34+
35+
.. group-tab:: Windows
36+
37+
::
38+
39+
{DOCUMENTS}/Arduino
40+
41+
.. group-tab:: MacOS
42+
43+
::
44+
45+
{HOME}/Documents/Arduino
46+
47+
48+
#. Clone this repo in ``<SKETCHBOOK>/hardware/arduino-git``:
49+
::
50+
51+
git clone https://github.com/Infineon/XMC-for-Arduino.git xmc
52+
53+
This allows quick testing of local changes during development, and keep released version.
54+
55+
#. You can check if the correct version is installed by running:
56+
::
57+
58+
arduino-cli core list
59+
60+
you should be able to see the ``arduino-git:xmc core``.
61+
62+
#. Update all submodule included in this project:
63+
::
64+
65+
git submodule update --init --recursive
66+
67+
If you are not familiar with submodules, check out `Git-Tools-Submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
68+
69+
#. Start developing |:tools:|!
70+
71+
|:bell:|
72+
If you encounter strange behavior with Arduino IDE during development, try cleaning up the IDE cache:
73+
74+
.. tabs::
75+
76+
.. group-tab:: Windows
77+
78+
.. code-block:: text
79+
80+
C:\User\"username"\AppData\Roaming\arduino-ide
81+
82+
.. group-tab:: Linux
83+
84+
::
85+
86+
~/.config/arduino-ide
87+
88+
.. group-tab:: macOS
89+
90+
::
91+
92+
~/Library/Application Support/arduino-ide/
93+
94+
95+
Automated Build Checks
96+
-----------------------
97+
98+
Currently a Github workflow is used for automatic compilation checking and releasing. Workflows are defined [here](https://github.com/Infineon/XMC-for-Arduino/tree/master/.github/workflows).
99+
Before opening a Pull Request for your contribution, please add a git tag in the format `Vx.y.z` (e.g. V3.3.0) to trigger the release process in your fork and pass the compilation tests.
100+
101+
Creating and Maintaining Third Party Libraries
102+
------------------------------------------------
103+
Basics
104+
^^^^^^^^
105+
The Arduino IDE allows for external libraries to be added to support specific devices and functions which are not part of the core setup. For details on creating libraries see the
106+
[Arduino library specifications](https://arduino.github.io/arduino-cli/library-specification/). If you add additional libraries to this project, make sure to [document them](https://xmc-arduino.readthedocs.io/en/latest/builtin-libraries.html) accordingly.
107+
108+
XMC-for-Arduino Configuration
109+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110+
To ensure that a library specific to one architecture or board type is only compiled when a supporting board is set up, this specification includes a setting for *architecture* in the *library.properties* file.
111+
112+
When creating or maintaining third party or external libraries for XMC-for-Arduino please use this setting:
113+
114+
.. code-block:: text
115+
116+
architecture=xmc
117+
118+
If your library also supports other boards and architectures, add those in as well.
119+
120+
Validation test
121+
----------------
122+
To test the XMC4arduino, we used unity to test some of the features of the arduino core & builtin library.
123+
124+
Tests are located in tests/arduino-core-tests and included as submodule in this project. Run ``git submodule update --init --recursive`` to update them.
125+
126+
Code checks (WIP)
127+
----------------------
128+
Refer to ``libraries\CAN\Makefile.codecheck``.
129+
130+
Regarding formatting, we currently use `pre-commit <https://pre-commit.com/>`_ to automatically run clang-formatting to format all c/c++ code. Please install this python package, and follow the quick start (the pre-commit configuration file is already there). You should be able to format your code automatically on git commit!

‎docs/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ advantage of the advanced features and performance offered by XMC microcontrolle
3737

3838
Introduction<self>
3939
installation-instructions
40+
development-instructions
4041
hw-platforms
4142
builtin-libraries
4243
arduino-deviations

‎docs/requirements.txt

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# This is a list of python packages used to generate documentation. This file is used with pip:
2+
# pip install --user -r requirements.txt
3+
#
14
sphinx>=7.2.6
25
sphinx-tabs
36
sphinxemoji

0 commit comments

Comments
 (0)