iotedgedev/CONTRIBUTING.md

Contributing

This section describes how to get your developer workspace running for the first time so that you're ready to start making contributions.

Please fork, branch and pull-request any changes you'd like to make.

Workspace Setup

1. Clone this repository

   git clone https://github.com/azure/iotedgedev.git

2. Rename .env.tmp in the root of the repo to .env and set the IOTHUB_CONNECTION_STRING and DEVICE_CONNECTION_STRING values to settings from your IoT Hub and Edge Device. To set these values you could run iotedgedev iothub setup in the root of the repo.

3. Install Docker

   • Windows
     • Be sure to check whether you are running in Linux container mode or Windows container mode.
   • Linux
     • We've seen some issues with docker.io. If IoT Edge doesn't run for you, then try installing Docker CE directly instead of via docker.io. Use the CE install steps, or use the convenience script.
     • By default, you need sudo to run docker commands. If you want to avoid this, please follow the post-installation steps for Linux.

A) Contributor Dev Machine Setup

1. Install Python 3.6+, and pip

   • Windows: Install from Python's website
   • Linux: sudo apt-get install python-pip python3-pip
   • macOS: The OpenSSL used by the system built-in Python is old and vulnerable. Please use Python installed with Homebrew.

2. Install Azure CLI 2.0

3. Install Azure CLI IoT extension

   • New Install: az extension add --name azure-iot
   • Update Install: az extension update --name azure-iot

4. Install Node.js and the iothub-explorer package

   • npm i -g iothub-explorer

5. (Linux only) Install Docker Compose

   pip install -U docker-compose
   

6. (Linux only) Install extra system dependencies

   sudo apt-get install -y libffi-dev libssl-dev
   

7. Install module dependencies

   C# module and C# Azure Functions module

   Install .NET Core SDK 2.1 or later

   Python module

   1. Install Git
   2. Install Cookiecutter

   pip install -U cookiecutter
   

   Node.js module

   1. Install Node.js
   2. Install Yeoman and Azure IoT Edge Node.js module generator packages

   npm i -g yo generator-azure-iot-edge-module
   

   Java module

   1. Install JDK
   2. Install Maven

8. Install Python development dependencies

   pip install -r requirements_dev.txt
   

B) Contributor Docker Devcontainer Setup

With VSCode

Developing with docker using VSCode's remote containers:

• Install Remote Development Extension in VSCode
• Open the project in VSCode
• When prompted by VSCode, select "Reopen in Container"

To further customize your devcontainer checkout Personalizing with dotfile repositories. In the same settings you're also able to add personal extensions for your container.

Without VSCode

• Build the development environment: docker build -f .devcontainer/Dockerfile -t dev .

• Mount the root directory into the docker container, and drop into a bash shell in the container:

  docker run -it -v ${PWD}:/workspaces/iotedgedev iotedgedev
  

Developing

1. Run IoT Edge Dev Tool in editable mode

   Run the following command from the root of the repo to see changes to iotedgedev commands as you change code.

   pip install -e .
   

VS Code Debugging

VS Code Debugging works only with Python 3.6 VS Code Python Environments for now. Make sure that your VS Code Python Environment is pointing to Python 3.6

Set your CLI arguments in .vscode/launch.json and hit F5

Run Tests

Run the following command to run tests.

tox