forked from Azure/iotedge
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merged PR 923010: Update READMEs for OSS
Update READMEs for OSS. * Moves build instructions into a separate devguide * Cleans up initial readme * Adds logo
- Loading branch information
Showing
9 changed files
with
254 additions
and
359 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,114 +1,20 @@ | ||
| #IoT Edge | ||
| # IoT Edge | ||
|
|
||
| This repository consists of two projects: the Module Management Agent (edge-agent) and the Edge Hub (edge-hub). | ||
|  | ||
|
|
||
| ## Setup | ||
| Welcome to the home of IoT Edge. | ||
|
|
||
| Make sure the following dependencies are installed in your environment before you build IoT Edge code: | ||
| IoT Edge moves cloud analytics and custom business logic to devices so that your organization can focus on business insights instead of data management. | ||
| Enable your solution to truly scale by configuring your IoT software, deploying it to devices via standard containers, and monitoring it all from the cloud. | ||
| This repository consists of three main projects: the [Edge Agent](edge-agent), the [Edge Hub](edge-hub), and the [IoT Edge Security Daemon](edgelet). | ||
|
|
||
| | Dependency | Notes | | ||
| |-------------------|----------------------| | ||
| | .NET Core 2.0 | Installation instructions [here](https://www.microsoft.com/net/core/preview). | | ||
| | Java | Not needed if building in VS IDE (Windows). Otherwise, JRE is required to compile the Antlr4 grammar files into C# classes, and `java` must be on your path. | | ||
| | package feed authorization| Access to project package feeds. | | ||
| ## Documentation | ||
| Documentation for the Azure IoT Edge product can be found at https://docs.microsoft.com/azure/iot-edge. | ||
|
|
||
| ## Build | ||
| ## Contributing | ||
|
|
||
| Besides using Visual Studio IDE in Windows, you can build by running the build script: | ||
| If you would like to build or change the IoT Edge source code, please follow the [devguide](doc/devguide.md). | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/buildBranch.sh | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\buildBranch.bat | ||
| ``` | ||
|
|
||
| Binaries are published to `target/publish/`. | ||
|
|
||
| ## Run unit tests | ||
|
|
||
| Besides using Test Explorer in Visual Studio IDE, you can run the unit tests with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/runTests.sh | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\runTests.bat | ||
| ``` | ||
|
|
||
| ## Run integration tests & BVTs | ||
|
|
||
| To run integration tests and/or BVTs, make sure the following dependencies are installed in your environment: | ||
|
|
||
| | Dependency | Notes | | ||
| |-------------------|----------------------| | ||
| | Azure CLI | Installation instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) | | ||
| | Powershell | Installation instructions [here](https://github.com/PowerShell/PowerShell/tree/master/docs/installation) | | ||
| | Jq | Installation instructions [here](https://stedolan.github.io/jq/download/) | | ||
| | Docker | Installation instructions [here](https://docs.docker.com/engine/installation/#supported-platforms). In Linux environments, be sure to follow the [post-installation steps](https://docs.docker.com/engine/installation/linux/linux-postinstall/) so the tests can run without `sudo`. | | ||
|
|
||
| The integration tests and BVTs expect to find certain values in an Azure KeyVault (see `edge-util/test/Microsoft.Azure.Devices.Edge.Util.Test.Common/settings/base.json`). For the tests to access the KeyVault at runtime, a certificate must first be installed in the environment where the tests will run. Install the KeyVault certificate with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/downloadAndInstallCert.sh <SpUsername> <SpPassword> <AadTenant> <CertName> <VaultName> | ||
| ``` | ||
|
|
||
| | Argument | Description | | ||
| |-------------|----------------------------| | ||
| | SpUsername | Service principal username. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | SpPassword | Service principal password. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | AadTenant | Azure Active Directory tenant. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | CertName | Certificate name. See `--secret` in `az keyvault secret show` [help](https://docs.microsoft.com/en-us/cli/azure/keyvault/secret#show). | | ||
| | VaultName | KeyVault name. See `az keyvault secret show` [help](https://docs.microsoft.com/en-us/cli/azure/keyvault/secret#show). | | ||
|
|
||
| ### Windows | ||
| ``` | ||
| powershell scripts\windows\DownloadAndInstallCertificate.ps1 <VaultName> <CertificateName> | ||
| ``` | ||
|
|
||
| | Argument | Description | | ||
| |-------------|----------------------------| | ||
| | VaultName | KeyVault name. See `Get-AzureKeyVaultSecret` [help](https://docs.microsoft.com/en-us/powershell/module/azurerm.keyvault/get-azurekeyvaultsecret). | | ||
| | CertName | Certificate name. See `Get-AzureKeyVaultSecret` [help](https://docs.microsoft.com/en-us/powershell/module/azurerm.keyvault/get-azurekeyvaultsecret). | | ||
|
|
||
| Then run the tests either with Test Explorer in Visual Studio IDE, or with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/runTests.sh "--filter Category=Integration|Category=Bvt" | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\runTests.bat "--filter Category=Integration|Category=Bvt" | ||
| ``` | ||
|
|
||
| The syntax of the "filter" argument is described [here](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-test#filter-option-details). All IoT Edge tests are categorized as one of `Unit`, `Integration`, or `Bvt`. | ||
|
|
||
| ## Build Manifest Image | ||
| There is a script in the repo to build multi-architecture images. | ||
| This scripts assumes that the platform specific images are already in the docker registry. | ||
| Usage is as follows: | ||
| ``` | ||
| $ scripts/linux/buildManifest.sh --help | ||
| buildManifest.sh [options] | ||
| Note: Depending on the options you might have to run this as root or sudo. | ||
| options | ||
| -r, --registry Docker registry required to build, tag and run the module | ||
| -u, --username Docker Registry Username | ||
| -p, --password Docker Username's password | ||
| -v, --image-version Docker Image Version. | ||
| -t, --template Yaml file template for manifest definition. | ||
| ``` | ||
|
|
||
| ## Release | ||
| [Release Process](doc/release.md) | ||
| --- | ||
| This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| # Dev Guide | ||
|
|
||
| IoT Edge is written in C# and Rust. | ||
| The C# development setup is described below. The Rust development setup is described [here](../edgelet/README.md). | ||
|
|
||
| ## Setup | ||
|
|
||
| Make sure the following dependencies are installed in your environment before you build IoT Edge code: | ||
|
|
||
| | Dependency | Notes | | ||
| |-------------------|----------------------| | ||
| | .NET Core 2.1 | Installation instructions [here](https://www.microsoft.com/net/core). | | ||
| | Java | Not needed if building in VS IDE (Windows). Otherwise, a JRE is required to compile the Antlr4 grammar files into C# classes, and `java` must be on your path. | | ||
|
|
||
| ## Build | ||
|
|
||
| Besides using Visual Studio in Windows, you can build by running the build script: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/buildBranch.sh | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\buildBranch.bat | ||
| ``` | ||
|
|
||
| Binaries are published to `target/publish/`. | ||
|
|
||
| ## Run unit tests | ||
|
|
||
| Besides using Test Explorer in Visual Studio, you can run the unit tests with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/runTests.sh | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\runTests.bat | ||
| ``` | ||
|
|
||
| ## Run integration tests & BVTs | ||
|
|
||
| To run integration tests and/or BVTs, make sure the following dependencies are installed in your environment: | ||
|
|
||
| | Dependency | Notes | | ||
| |-------------------|----------------------| | ||
| | Azure CLI | Installation instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) | | ||
| | Powershell | Installation instructions [here](https://github.com/PowerShell/PowerShell/tree/master/docs/installation) | | ||
| | Jq | Installation instructions [here](https://stedolan.github.io/jq/download/) | | ||
| | Docker | Installation instructions [here](https://docs.docker.com/engine/installation/#supported-platforms). In Linux environments, be sure to follow the [post-installation steps](https://docs.docker.com/engine/installation/linux/linux-postinstall/) so the tests can run without `sudo`. | | ||
|
|
||
| The integration tests and BVTs expect to find certain values in an Azure KeyVault (see `edge-util/test/Microsoft.Azure.Devices.Edge.Util.Test.Common/settings/base.json`). For the tests to access the KeyVault at runtime, a certificate must first be installed in the environment where the tests will run. Install the KeyVault certificate with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/downloadAndInstallCert.sh <SpUsername> <SpPassword> <AadTenant> <CertName> <VaultName> | ||
| ``` | ||
|
|
||
| | Argument | Description | | ||
| |-------------|----------------------------| | ||
| | SpUsername | Service principal username. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | SpPassword | Service principal password. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | AadTenant | Azure Active Directory tenant. See `az login` [help](https://docs.microsoft.com/en-us/cli/azure/#login). | | ||
| | CertName | Certificate name. See `--secret` in `az keyvault secret show` [help](https://docs.microsoft.com/en-us/cli/azure/keyvault/secret#show). | | ||
| | VaultName | KeyVault name. See `az keyvault secret show` [help](https://docs.microsoft.com/en-us/cli/azure/keyvault/secret#show). | | ||
|
|
||
| ### Windows | ||
| ``` | ||
| powershell scripts\windows\DownloadAndInstallCertificate.ps1 <VaultName> <CertificateName> | ||
| ``` | ||
|
|
||
| | Argument | Description | | ||
| |-------------|----------------------------| | ||
| | VaultName | KeyVault name. See `Get-AzureKeyVaultSecret` [help](https://docs.microsoft.com/en-us/powershell/module/azurerm.keyvault/get-azurekeyvaultsecret). | | ||
| | CertName | Certificate name. See `Get-AzureKeyVaultSecret` [help](https://docs.microsoft.com/en-us/powershell/module/azurerm.keyvault/get-azurekeyvaultsecret). | | ||
|
|
||
| Then run the tests either with Test Explorer in Visual Studio IDE, or with: | ||
|
|
||
| ### Linux | ||
| ``` | ||
| scripts/linux/runTests.sh "--filter Category=Integration|Category=Bvt" | ||
| ``` | ||
|
|
||
| ### Windows | ||
| ``` | ||
| scripts\windows\runTests.bat "--filter Category=Integration|Category=Bvt" | ||
| ``` | ||
|
|
||
| The syntax of the "filter" argument is described [here](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-test#filter-option-details). All IoT Edge tests are categorized as one of `Unit`, `Integration`, or `Bvt`. | ||
|
|
||
| ## Build Manifest Image | ||
| There is a script in the repo to build multi-architecture images. | ||
| This script assumes that the platform specific images are already in the docker registry. | ||
| Usage is as follows: | ||
| ``` | ||
| $ scripts/linux/buildManifest.sh --help | ||
| buildManifest.sh [options] | ||
| Note: Depending on the options you might have to run this as root or sudo. | ||
| options | ||
| -r, --registry Docker registry required to build, tag and run the module | ||
| -u, --username Docker Registry Username | ||
| -p, --password Docker Username's password | ||
| -v, --image-version Docker Image Version. | ||
| -t, --template Yaml file template for manifest definition. | ||
| ``` |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.