diff options
| -rw-r--r-- | BUILDING.md | 172 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 42 | ||||
| -rw-r--r-- | README.md | 12 |
3 files changed, 198 insertions, 28 deletions
diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..a3b1b711 --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,172 @@ +# Building thin-edge.io + +## Get the code + +thin-edge.io code is in git repository on github to acquire the code use following command: + +* via SSH: + +```shell +git clone git@github.com:thin-edge/thin-edge.io.git +``` + +* or via HTTPS: + +```shell +git clone https://github.com/thin-edge/thin-edge.io.git +``` + +## Installing toolchain + +### Rust toolchain + +To install Rust follow [Official installation guide](https://www.rust-lang.org/tools/install). +To get started you need Cargo's bin directory (`$HOME/.cargo/bin`) in your `PATH` environment variable. + +```shell +export PATH=$PATH:$HOME/.cargo/bin +``` + +And then you can run `rustc` to view current version: + +```shell +$ rustc --version +rustc 1.51.0 (2fd73fabe 2021-03-23) +``` + +> Note: Above command will add rust to path only for existing session, +> after you restart the session you will have to add it again, +> to add rust to the path permanently it will depend on your shell but for Bash, +> you simply need to add the line from above, `export PATH=$PATH:$HOME/.cargo/bin` to your ~/.bashrc. + +> For other shells, you'll want to find the appropriate place to set a configuration at start time, +> eg. zsh uses ~/.zshrc. Check your shell's documentation to find what file it uses. + +thin-edge.io operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain. + +Current MSRV is `1.46.0`. + +### Cross compilation toolchain (optional) + +thin-edge.io can be compiled for target architecture on non-target device, this is called cross compilation. +Currently we support `Raspberry Pi 3B` for `armv7` architecture with Rust's cross compilation toolchain called [cargo cross](https://github.com/rust-embedded/cross). + +To install [cargo cross](https://github.com/rust-embedded/cross): + +```shell +cargo install cross +``` + +### Debian packaging (optional) + +We use [cargo deb](https://github.com/mmstick/cargo-deb) to build our debian packages, the tool takes care of all the work to package thin-edge.io. + +To install [cargo deb](https://github.com/mmstick/cargo-deb) use: + +```shell +cargo install cargo-deb +``` + +## Compiling + +To build thin-edge.io we are using `cargo`. + +As we are using `cargo workspace` for all our crates. All compiled files are put in `./target/` directory with target's name eg: `./target/debug` or `./target/release` for native builds and for cross compiled targets `./target/<architecture>/debug` or `./target/<architecture>/release` dependent on the target of the build. + +### Compiling dev + +To compile dev profile (with debug symbols) we use following command: + +```shell +cargo build +``` + +Build artifacts can be found in `./target/debug` and will include executables: + +```shell +$ ls ./target/debug/tedge* +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge_mapper +``` + +Binaries can be run eg: `./target/debug/tedge`. +Alternatively, you can use `cargo` to build and run executable in a single command: + +```shell +cargo run --bin tedge +``` + +### Compiling release + +To compile release profile we use following command: + +```shell +cargo build --release +``` + +Build artifacts can be found in `./target/release` and will include executables: + +```shell +$ ls ./target/release/tedge* +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge_mapper +``` + +Binaries can be run eg: `./target/release/tedge`. + +## Building deb package + +Currently thin-edge.io contains 2 binaries, `tedge` (cli) and `tedge_mapper` which are packaged as separate debian packages. To create following commands are to be issued: + +```shell +cargo deb -p tedge +``` + +```shell +cargo deb -p tedge_mapper +``` + +All resulting packages are going to be in: `./target/debian/` directory: + +```shell +$ ls ./target/debian -l +total 2948 +-rw-rw-r-- 1 user user 11111 Jan 1 00:00 tedge_0.1.0_amd64.deb +-rw-rw-r-- 1 user user 11111 Jan 1 00:00 tedge_mapper_0.1.0_amd64.deb +``` + +## Cross compiling + +To create binaries which can run on different platform than one you are currently on you can use [cargo cross](https://github.com/rust-embedded/cross): + +```shell +cross build --target armv7-unknown-linux-gnueabihf +``` + +Build artifacts can be found in `./target/armv7-unknown-linux-gnueabihf/debug` and will include executables: + +```shell +$ ls ./target/armv7-unknown-linux-gnueabihf/debug/tedge* +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge +-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge_mapper +``` + +To cross compile release version of the binaries just add `--release` to the above command like so: + +```shell +cross build --target armv7-unknown-linux-gnueabihf --release +``` + +## Running tests + +When contributing to thin-edge.io we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command: + +```shell +cargo test +``` + +This will run all tests from the repository and sometime may take long time, `cargo` allows you to run specific test or set of tests for binary: + +```shell +cargo test --bin tedge +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a454d4f..d107169c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,10 +9,12 @@ Of course, contributing code is more than welcome! If you're planning to submit If you are interested in contributing documentation, please note the following: - - Doc issues are labeled with the `doc` label. - The thin-edge.io docs content is in the `docs/src/` directory. +[How to build from source.](./BUILDING.md) + +<br/> <br/> # Pull request and git commit guidance @@ -29,7 +31,6 @@ When possible, fill out as much detail in the pull request template as is reason Git commit messages should explain the how and why of your change and be separated into a brief subject line followed by a more detailed body. When in doubt, follow this guide for good commit messages and you can’t go wrong: [https://chris.beams.io/posts/git-commit/](https://chris.beams.io/posts/git-commit/). - ## Reviewing, addressing feedback, and merging Generally, pull requests need two approvals from maintainers to be merged. @@ -38,48 +39,51 @@ When addressing review feedback, it is helpful to the reviewer if additional cha Once a PR has the necessary approvals, it can be merged. Here’s how the merge should be handled: - - If the PR is a single logical commit, the merger should use the “Rebase and merge” option. This keeps the git commit history very clean and simple and eliminates noise from "merge commits." - If the PR is more than one logical commit, the merger should use the “Create a merge commit” option. - If the PR consists of more than one commit because the author added commits to address feedback, the commits should be squashed into a single commit (or more than one logical commit, if it is a big feature that needs more commits). This can be achieved by the “Squash and merge” option. If they do this, the merger is responsible for cleaning up the commit message according to the previously stated commit message guidance. <br/> <br/> + # Contributor License Agreement + We do not want to bother you with too much legalese, but there are two pages you have to read carefully, this page and the CONTRIBUTOR LICENSE AGREEMENT. - + ## Signing the CONTRIBUTOR LICENSE AGREEMENT + Each Contribution to Software AG's Open Source Projects must be accompanied by a sign-off indicating acceptance of current version of the CONTRIBUTOR LICENSE AGREEMENT, which is derived from the Apache Foundation's Individual Contributor License Agreement, sign-off time stamp relates to corresponding version of the CONTRIBUTOR LICENSE AGREEMENT maintained here on GitHub as well. Sign-Off and acceptance of the CONTRIBUTOR LICENSE AGREEMENT is declared by using the option "-s" in - + > git commit -s - + which will automatically generate a sign-off statement in the form: - + > Signed-off-by: Max Mustermann \<MaxM@example.com\> - + By adding this sign-off statement, you are certifying: - + *By signing-off on this Submission, I agree to be bound by the terms of the **then current CONTRIBUTOR LICENSE AGREEMENT** located at https://github.com/thin-edge/thin-edge.io/blob/main/CONTRIBUTOR-LICENSE-AGREEMENT.md, **which I have read and understood** and I agree that this Submission constitutes a "Contribution" under this Agreement.* - + ## Note on Privacy + Please note that this project and any contributions to it are public and that a record of all contributions (including any personal information submitted with it, including a sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. - + In addition to [GitHub's privacy statement](https://docs.github.com/en/github/site-policy/github-privacy-statement) extracting personal data from these projects for any other use than maintaining the projects and communication related to it is prohibited, explicitly prohibited is extracting email addresses for unsolicited bulk mails. - -If you'd like to keep your personal email address private, you can use a GitHub-provided no-reply email address as your commit email address. You can choose which verified email address to author changes with when you edit, delete, or create files or merge a pull request on GitHub. If you enabled email address privacy, then the commit author email address cannot be changed and is \<username\>@users.noreply.github.com by default. - + +If you'd like to keep your personal email address private, you can use a GitHub-provided no-reply email address as your commit email address. You can choose which verified email address to author changes with when you edit, delete, or create files or merge a pull request on GitHub. If you enabled email address privacy, then the commit author email address cannot be changed and is \<username\>@users.noreply.github.com by default. + See [setting your commit email address on GitHub](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address#setting-your-commit-email-address-on-github). - + In the upper-right corner of any page, click your profile photo, then click **Settings**. - + 1. In the left sidebar, click **Emails**. 1. In "Add email address", type your email address and click **Add**. 1. Verify your email address. 1. In the "Primary email address" list, select the email address you'd like to associate with your web-based Git operations. 1. To keep your email address private when performing web-based Git operations, click **Keep my email address private**. 1. You can use the git config command to change the email address you associate with your Git commits. - + See [setting your commit email address in Git](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address#setting-your-commit-email-address-in-git). - + 1. Open Git Bash. 2. Set an email address in Git. You can use your GitHub-provided no-reply email addressor any email address. >$ git config --global user.email "email@example.com" @@ -87,5 +91,5 @@ See [setting your commit email address in Git](https://docs.github.com/en/github >$ git config --global user.email <br> >email@example.com 4. Add the email address to your account on GitHub, so that your commits are attributed to you and appear in your contributions graph. - + Release date: 2021-03-29 @@ -1,8 +1,6 @@ [](LICENSE.txt) [](https://twitter.com/thin_edge_io) - - <!-- PROJECT LOGO --> <br /> <p align="center"> @@ -16,8 +14,6 @@ <br /> </p> - - <!-- TABLE OF CONTENTS --> <details open="open"> <summary>Table of Contents</summary> @@ -35,29 +31,27 @@ * [Install thin-edge.io on your device](docs/src/howto-guides/002_installation.md) * [Connect your device to Cumulocity](docs/src/tutorials/connect-c8y.md) * [Connect your device to Azure](docs/src/tutorials/connect-azure.md) +* [How to build from source](./BUILDING.md) * [**Explore the Docs**](docs/src/SUMMARY.md) <br/> <br/> - <!-- ABOUT THE PROJECT --> # About The Project -thin-edge.io is the first open-source and cloud-agnostic edge framework designed for resource-constrained IoT edge devices. +thin-edge.io is the first open-source and cloud-agnostic edge framework designed for resource-constrained IoT edge devices. -We have started the project to solve the challenge of IoT device enablement in industrial IoT or more precisely to make the integration of IoT devices with cloud and IoT platforms easy and reliable. +We have started the project to solve the challenge of IoT device enablement in industrial IoT or more precisely to make the integration of IoT devices with cloud and IoT platforms easy and reliable. With thin-edge.io we want to provide re-usable and modular components, which are not bound to a specific IoT platform, domain model or vendor. It runs on a wide variety of hardware, from small, embedded Linux (Debian, Yocto, etc) devices with very low RAM footprint to large, multi-core industrial servers (IPC). It comes with multi-language support and aims to provide out-of-the box connectivity, security and device management features on any device its deployed on. <br/> <br/> - <!-- REFERENCESYSTEMS --> # Reference Systems These are the systems that we currently test on. This does not mean that thin-edge.io is not building and working on other systems, but these are the systems that we are testing on. - * Raspberry Pi 3b with Raspberry Pi OS 10 * Raspberry Pi 4 with Raspberry Pi OS 10 <br/> |