|
1 | | -# East tool |
2 | | - |
3 | | -## Installation and updating |
4 | | - |
5 | | -Use the package manager [pip](https://pip.pypa.io/en/stable/) to install East. |
6 | | - |
7 | | -```bash |
8 | | -pip install --upgrade east-tool |
9 | | -``` |
10 | | - |
11 | | -## Usage |
12 | | - |
13 | | -`east` intends to be fully documented inside the tool itself, (which is not |
14 | | -yet). Executing `east` or `east --help` in the command line should give you |
15 | | -sufficient information on how to use the tool in basic ways. |
16 | | - |
17 | | -To learn more about configuration refer to the [docs](docs) folder. |
18 | | - |
19 | | - |
20 | | -## Developing East |
21 | | - |
22 | | -For development and testing of `east` the use of `virtualenv` is suggested. |
23 | | - |
24 | | -Install `virtualenv`: |
25 | | - |
26 | | -```bash |
27 | | -pip install virtualenv |
28 | | -``` |
29 | | - |
30 | | -Create and activate `virtualenv`, run this from project root: |
31 | | - |
32 | | -```bash |
33 | | -virtualenv venv |
34 | | -source venv/bin/activate |
35 | | -``` |
36 | | - |
37 | | -To create and editable install of `east` run below command. Whatever change you |
38 | | -make in the code it will be immediately reflected in the actual tool. |
39 | | - |
40 | | -```bash |
41 | | -make install-dev |
42 | | -``` |
43 | | - |
44 | | -### Running unit tests |
45 | | - |
46 | | -```bash |
47 | | -make test |
48 | | -``` |
49 | | - |
50 | | -#### Editable install does not work |
51 | | - |
52 | | -If `make install` (more exactly `pip install -e .`) ever misbehaves, it is |
53 | | -probably due to this: https://github.com/pypa/pip/issues/7953. |
54 | | - |
55 | | -Run below command once and then again `make install`, this fixed it last time: |
56 | | - |
57 | | -```bash |
58 | | -python3 -m pip install --prefix=$(python3 -m site --user-base) -e . |
59 | | -``` |
60 | | - |
61 | | -#### Test for version check fails |
62 | | - |
63 | | -This happens if the `make install-dev` command was not run before running `make test`. |
| 1 | +# East - tool for building NCS/Zephyr applications |
| 2 | + |
| 3 | +East is a command line meta-tool, useful for creating, managing, and deploying |
| 4 | +[Zephyr] or [nRF Connect SDK] (NCS) projects. |
| 5 | + |
| 6 | +[zephyr]: https://docs.zephyrproject.org/latest/ |
| 7 | +[nrf connect sdk]: |
| 8 | + https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/introduction.html |
| 9 | + |
| 10 | +It is built on top of Zephyr's RTOS meta-tool [West] and Nordic's [nRF Connect |
| 11 | +Toolchain Manager]. |
| 12 | + |
| 13 | +[west]: https://github.com/zephyrproject-rtos/west |
| 14 | +[nrf connect toolchain manager]: |
| 15 | + https://github.com/NordicSemiconductor/pc-nrfconnect-toolchain-manager |
| 16 | + |
| 17 | +## Reasoning behind East |
| 18 | + |
| 19 | +There are several reasons why someone would like to create yet another tool on |
| 20 | +top of `west`: |
| 21 | + |
| 22 | +- Working on several projects at once means using different versions of the NCS |
| 23 | + repository and different versions of the toolchain. Managing these differences |
| 24 | + is not a trivial task. |
| 25 | +- There is no reproducible build guarantee between the developer's machines. |
| 26 | + Slight differences between tool versions can manifest into hard-to-find bugs. |
| 27 | +- Creating GitHub releases manually takes ages as you have to run the build |
| 28 | + process for every combination of the board, application, build variant, etc. |
| 29 | + and properly rename the release binary. The release procedure gets longer with |
| 30 | + every addition of new hardware and build variation option. |
| 31 | + |
| 32 | +East automates the above tasks and tries to make the developer more productive. |
| 33 | + |
| 34 | +## Key features |
| 35 | + |
| 36 | +- Automated detection and installation of tooling required for NCS projects. |
| 37 | +- Common `west` commands used for the development, such as `build`, `flash`, |
| 38 | + etc. |
| 39 | +- Sandboxed development environment, thanks to the nRF Connect Toolchain |
| 40 | + Manager, every `build`, `flash`, etc. command runs inside of its toolchain |
| 41 | + environment. |
| 42 | +- Automated process of generating release artefacts for your entire project, no |
| 43 | + matter the number of applications, samples or boards. |
| 44 | +- Support for build types, which is integrated into the usual build process. |
| 45 | +- RTT utility commands to connect and see the RTT stream. |
| 46 | + |
| 47 | +## Documentation |
| 48 | + |
| 49 | +`docs` directory contains several markdown documents about East: |
| 50 | + |
| 51 | +- [Getting stared] - Quickly setup an example project and get it building with |
| 52 | + East. |
| 53 | +- [How East works] - How East works under the hood and what to expect from it. |
| 54 | +- [Configuration] - How to configure build types and release procedure via |
| 55 | + `east.yml` file. |
| 56 | +- [Development guide] - How to setup development environment for working on |
| 57 | + East. |
| 58 | + |
| 59 | +[getting stared]: docs/getting_started.md |
| 60 | +[how east works]: docs/how_east_works.md |
| 61 | +[configuration]: docs/configuration.md |
| 62 | +[development guide]: docs/development_guide.md |
0 commit comments