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 thetest/gdb_test.py
functional test to pass.
- Note that on Windows, the 32-bit Python 2.7 must be installed for the Python-enabled
- 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
environment variable to the desired version number
(without a “v” prefix).
Step 4. Develop
See the porting guide 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 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 intomain
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.
Debugging pyOCD
VS Code
Debugging pyOCD launched by VS Code is straightforward, and is much like debugging any package.
-
First, set up the pyOCD development and virtualenv as described above.
-
Set up the launch config as follows.
-
Set
pythonPath
to the python executable in the virtualenv. -
Set
module
topyocd.__main__
, to debug pyOCD entry point as a module. This works better than trying to debug the script.../pyocd/__main__.py
as it ensures the relative module references inside pyOCD work correctly..
For instance, here is a VS Code launch config for pyOCD’s gdbserver:
{ "name": "pyocd gdbserver", "type": "python", "request": "launch", "module": "pyocd.__main__", "console": "integratedTerminal", "stopOnEntry": true, "pythonPath": "/Users/username/projects/pyOCD/venv/bin/python3", "showReturnValue": true, "args": ["gdb", "-v"] }
-
It’s also possible to debug pyOCD remotely. This is useful either for cases where it is launched by another tool and you cannot directly control the command line , or is on another machine.
For remote debug, use a launch config like this:
{
"name": "Python: Attach using port",
"type": "python",
"request": "attach",
"port": 5678,
}
If the pyOCD process is on another machine, add a host
key to the launch config with the host name. (This defaults to localhost.)
Install debugpy with pip into your virtual environment.
To remotely debug pyOCD from the command line, run it with the debugpy
module. For instance, python -m debugpy --listen 5678 -m pyocd gdb -v
. Additionally, --wait-for-client
can be added after the port number to wait for the debug client to connect before running pyOCD.
If you don’t control pyOCD’s launch, then debugpy
can be called directly from pyOCD’s code. Add the following code to pyocd. Inside pyocd.__main__.PyOCDTool.run()
is a good location, though it can be done at module level in __main__.py
.
import debugpy
debugpy.listen(5678)
To pause pyOCD’s execution and wait for the debug client to connect, add this line as well:
debugpy.wait_for_client()