diff --git a/.gitignore b/.gitignore index bb6b1122..be93e381 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ build # python **/__pycache__/ venv/ +myenv/ # code-check standards and reports misra.txt @@ -20,3 +21,9 @@ scan-build-reports/ cppcheck_reports/ cppcheck.checkers err.xml + +# Ignore docs build (Sphinx) +docs/build +docs/source/_build +__pycache__/ +_build/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2a91d67..2985ab1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,56 +1,14 @@ # Contributing to XMC for Arduino First important point: **All Contributions** are welcomed :open_hands:. -Please contribute and raise issues via the [github repository](https://github.com/Infineon/XMC-for-Arduino/tree/master) +Please contribute and raise issues via the [github repository](https://github.com/Infineon/XMC-for-Arduino/tree/master). ## Overview for Contributors -- Start your contribution by creating a [fork](https://github.com/Infineon/XMC-for-Arduino/fork) of this repository -- It's recommended to create a separate branch for your contribution in your fork -- Once your contribution is ready & tested, please create a [Pull Request](https://github.com/Infineon/XMC-for-Arduino/compare) to the master branch -- Once we merged your changes to the master branch, they are automatically included in the next release +- Start your contribution by creating a [fork](https://github.com/Infineon/XMC-for-Arduino/fork) of this repository. +- It's recommended to create a separate branch for your contribution in your fork. +- 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) +- Once we merged your changes to the master branch, they are automatically included in the next release. -## Install the BSP under development (on Windows) -Clone the repository in Arduino folder: -- Open Arduino and install any version of this project as described [here](https://xmc-arduino.readthedocs.io/en/latest/installation-instructions.html). -- Open the installation location in your Arduino program folder, e.g. -`C:\Users\\AppData\Local\Arduino15\packages\Infineon\hardware\xmc` -- Open git bash, type command: -`git clone ` - -This allows quick testing of local changes during development. - -[!TIP] -If you encounter strange behavior with Arduino IDE during development, try cleaning up the cache: -* Windows: `C:\User\"username"\AppData\Roaming\arduino-ide` -* Linux: `~/.config/arduino-ide` -* macOS: `~/Library/Application Support/arduino-ide/` - -## Automated Build Checks - -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). -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. - -## Creating and Maintaining Third Party Libraries -### Basics -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 -[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. - -### XMC-for-Arduino Configuration -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. - -When creating or maintaining third party or external libraries for XMC-for-Arduino please use this setting: -~~~ -architecture=xmc -~~~ - -If your library also supports other boards and architectures, add those in as well. - -## Validation test -To test the XMC4arduino, we used unity to test some of the features of the arduino core & builtin library. - -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 - -## Code checks (WIP) -Refer to libraries\CAN\Makefile.codecheck -* 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! \ No newline at end of file +## Development +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! \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 0008b484..16ffe347 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,8 +46,8 @@ extensions = [ # 'sphinx.ext.autodoc', - # 'sphinxemoji.sphinxemoji', - # 'sphinx_tabs.tabs', + 'sphinxemoji.sphinxemoji', + 'sphinx_tabs.tabs', # 'sphinx.ext.intersphinx', # 'sphinx.ext.autosectionlabel', # 'sphinx.ext.todo', diff --git a/docs/development-instructions.rst b/docs/development-instructions.rst new file mode 100644 index 00000000..bce7eeff --- /dev/null +++ b/docs/development-instructions.rst @@ -0,0 +1,150 @@ +Development Instructions +========================= + +.. + TODOS: + - Code conventions + - Tools installation: + - test + - doc + - code check + - ... + +.. _env_dev_setup: + +Environment Setup +------------------ + +#. Pre-conditions: + + * Install `Arduino IDE (2.0 or higher) `_ + * Or Install `Arduino CLI (1.0.0 or higher) `_ + * Python + +#. Create a ``/hardware/arduino-git`` folder. Where ```` is the location of your Arduino sketchbook. The ```` default is OS-dependent: + + .. tabs:: + + .. group-tab:: Linux + + :: + + {HOME}/Arduino + + .. group-tab:: Windows + + :: + + {DOCUMENTS}/Arduino + + .. group-tab:: MacOS + + :: + + {HOME}/Documents/Arduino + + +#. Clone this repo in ``/hardware/arduino-git``: + :: + + git clone https://github.com/Infineon/XMC-for-Arduino.git xmc + + This allows quick testing of local changes during development while keeping the released version. + +#. You can check if the correct version is installed by running: + :: + + arduino-cli core list + + You should be able to see the ``arduino-git:xmc core``. + +#. Update all submodule included in this project: + :: + + git submodule update --init --recursive + + If you are not familiar with git submodules, check out `Git-Tools-Submodules `_ + +#. Start developing |:tools:|! + +|:bell:| +If you encounter strange behavior with Arduino IDE during development, try cleaning up the Arduino IDE's cache: + + .. tabs:: + + .. group-tab:: Windows + + .. code-block:: text + + %AppData%\arduino-ide + + .. group-tab:: Linux + + :: + + ~/.config/arduino-ide + + .. group-tab:: macOS + + :: + + ~/Library/Application Support/arduino-ide/ + +Code Check and Tests +---------------------- + +Pre-commit Hooks +^^^^^^^^^^^^^^^^^^ +For the C/C++ code format and commit message format, we add git hooks to check it automatically. + +For ease of use, we currently use `pre-commit `_ 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. + +We also have workflow to for auto-checking, so please refer to code convention before committing your code. + +Code Check +^^^^^^^^^^^^ +.. warning:: + + Code Checks are still a work in progress in this project. + +If you are developing a new built-in library, please refer to ``libraries\CAN\Makefile.codecheck`` using cppcheck for static code analysis to ensure code quality. + +Automated Build Checks +^^^^^^^^^^^^^^^^^^^^^^^^ +Currently a GitHub Action workflow is used for automatic compilation checking. +Workflows are defined `here `_. + +Validation Test +^^^^^^^^^^^^^^^^ +To validate the XMC-for-Arduino, we utilize Unity for testing various features of the Arduino core and built-in libraries. + +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 need to run these tests locally, you'll also need to download `GNU Make `_ . + +Release +--------- +Add a git tag in the format `Vx.y.z` (e.g. V3.3.0) to trigger the release process. + + +Creating and Maintaining Third Party Libraries +------------------------------------------------ +Basics +^^^^^^^^ +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 +`Arduino library specification `_. + +If you add additional libraries to this project, make sure to `document them `_ accordingly. + +XMC-for-Arduino Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. + +When creating or maintaining third party or external libraries for XMC-for-Arduino please use this setting: + + .. code-block:: text + + architecture=xmc + +If your library also supports other boards and architectures, add those in as well. diff --git a/docs/index.rst b/docs/index.rst index 060ffae7..e1077c85 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ advantage of the advanced features and performance offered by XMC microcontrolle Introduction installation-instructions + development-instructions hw-platforms builtin-libraries arduino-deviations diff --git a/docs/requirements.txt b/docs/requirements.txt index 2a185d91..779f6572 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,6 @@ +# This is a list of python packages used to generate documentation. This file is used with pip: +# pip install --user -r requirements.txt +# sphinx>=7.2.6 sphinx-tabs sphinxemoji diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index 55821fd4..00000000 --- a/tests/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Test Environment - -## Develop on Windows -Clone the repository in arduino folder: -- Open Arduino and install any Infineon XMC library (e.g. 2.2.0) -- Open the library location in Arduino program folder -`C:\Users\"USERNAME"\AppData\Local\Arduino15\packages\Infineon\hardware\xmc` -- Open git bash, type command: -`git clone "HTTP_SSH_REPOSITORY" "LIBRARY_VERSION (e.g. 2.2.0)"` - -This is a workaround for current local compilation/testing. - -## Test on WSL -To be able to use some tools (make, clang, gcc...) easier on Linux, WSL is needed. -Since now we still compile the code with arduino-cli.exe on windows, in order to useLinux commands/ build tools, a symbolic link is created to eunsure the changes are immediately reflected in the other. -In WSL, you can create a symbolic link pointing to your windows project folder: -`ln -s /mnt/c/Users//AppData/Local/Arduino15/packages/Infineon/hardware/xmc /home//project` - -## (legacy) Manual tests -located in `tests/manual`. The application level `.ino` files for testing purposes. - -## Unity tests - -Currently, we are using Unity as the testing framework. You can find more information about Unity at [Unity](https://www.throwtheswitch.org/unity). -Please refer to `unity\README.md` for more details. - -To run the tests, use the commands example in `Makefile.test`. - diff --git a/tools/dev-setup.sh b/tools/dev-setup.sh deleted file mode 100644 index 5a1db31b..00000000 --- a/tools/dev-setup.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash - -# Change dir to the directory where this script is located -cd $(dirname $0) -echo ${PWD} - -function git_submodule_setup { - git submodule update --init --recursive -} - -function core_api_setup { - - cores_xmc_dir="${PWD}/../cores/xmc" - core_api_submodule_dir="${PWD}/../extras/arduino-core-api" - - # Create symbolic link (overwrite) to the api/ - # folder of ArduinoCore-API submodule. - # Note: Symlinks might not work without full paths - # https://stackoverflow.com/questions/8601988/symlinks-not-working-when-link-is-made-in-another-directory - if [ ! -d "$cores_xmc_dir" ]; then - mkdir -p "$cores_xmc_dir" - echo "Directory created: $cores_xmc_dir" - fi - ln -sf ${core_api_submodule_dir}/api ${cores_xmc_dir} -} - - -# Check if a function name is passed as an argument -if [ $# -gt 0 ]; then - if declare -f "$1" > /dev/null; then - "$1" - else - echo "Function $1 not found" - exit 1 - fi -else - git_submodule_setup - core_api_setup -fi