Skip to content

Latest commit

 

History

History
124 lines (86 loc) · 4.59 KB

developers_guide.md

File metadata and controls

124 lines (86 loc) · 4.59 KB
Raw
title
Developers’ guide

Please familiarise yourself with the contributing guide before beginning any development on pyOCD or related projects.

Setup

PyOCD developers are strongly recommended to setup a working environment using either virtualenv or the built-in venv module (only use of venv is shown below, but the two are equivalent). After cloning the code, you can setup a virtualenv and install the pyOCD dependencies for the current platform by following the detailed steps below.

Install the necessary tools listed below. Skip any step where a compatible tool already exists.

  • Install Python version 3.7.0 or above. Add to PATH.
    • Note that on Windows, the 32-bit Python 2.7 must be installed for the Python-enabled arm-none-eabi-gdb-py to work properly and for the test/gdb_test.py functional test to pass.
  • Install Git. Add to PATH.
  • Install GNU Arm Embedded toolchain. This provides arm-none-eabi-gdb used for testing the gdbserver. Add to PATH.

Steps

Step 1. Get the sources and create a virtual environment

$ git clone https://github.com/pyocd/pyOCD
$ cd pyOCD
$ python3 -m venv venv

Step 2. Activate virtual environment

Activate your virtualenv and install the pyOCD dependencies for the current platform by doing the following.

Linux or Mac:

$ source venv/bin/activate

Windows:

$ venv\Scripts\activate

Step 3. Install editable pyOCD

$ pip install -e .[test]

If you switch branches, you may need to reinstall.

Because the develop branch doesn't have version tags except older tags from the develop branch point, the version number of pyOCD might be significantly out of date. If this is an issue, you can override the version by setting the SETUPTOOLS_SCM_PRETEND_VERSION environmment variable to the desired version number (without a "v" prefix).

Step 4. Develop

See the [porting guide]({% link _docs/adding_new_targets.md %}) for how to add new devices. Of course, we welcome all improvements and changes. See the contributor statement for some guidelines.

See the branch policy below for details about branches and which branch you should work from.

If you'd like suggestions for something to work on, from small to large, the Slack workspace is a great way to engage with the community and maintainers.

Step 5. Test

See the [automated test documentation]({% link _docs/automated_tests.md %}) for an introduction to available tests and related scripts.

To run the unit tests, you can execute the following.

$ pytest

The automated test suite also needs to be run:

$ cd test
$ python ./automated_test.py

Step 6. Pull request

Once you are satisfied with your changes and all automated tests pass, please create a new pull request on GitHub to share your work. Please see below for which branch to target.

Pull requests should be made after a changeset is rebased.

Branch configuration policy

There are two primary branches:

  • main: Stable branch reflecting the most recent release. May contain bug fixes not yet released, but no new feature commits are allowed.
  • develop: Active development branch for the next minor version. Merged into main at release time.

There may be other development branches present to host long term development of major new features and backwards incompatible changes, such as API changes.

The branch that your changes should be made against depends on the type and complexity of the changes:

  • Only a bug fix: please target main.
  • Any other changes, or a mix of changes: target the develop branch. This is also a good choice if you aren't sure.

Maintainers will cherry-pick commits between main and develop as necessary to keep fixes in sync.

If you have any questions about how best to submit changes or the branch policy, please ask in the Slack workspace or GitHub Discussions. We'll be happy to help.