From 202a6b16e880f0e451a901b2b17cff040ea97f25 Mon Sep 17 00:00:00 2001 From: Ladislas de Toldi Date: Sun, 9 Jan 2022 23:52:42 +0100 Subject: [PATCH] :memo: (docs): Update & clean up install/how-to documentation - remove Linux/Ubuntu instructions - fix typos, old links, etc. - add vscode plugins and instructions --- docs/INSTALL.md | 99 +++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 52 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index ac6dc222e0..9f3cd7aaad 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -5,13 +5,13 @@ LekaOS repository is made to be easy to use: - simple directory structure -- CMake based with [USCRPL/mbed-cmake](https://github.com/USCRPL/mbed-cmake/) -- Code completion with VSCode + [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) +- compile with CMake (based on [USCRPL/mbed-cmake](https://github.com/USCRPL/mbed-cmake/)) +- code completion with VSCode + [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) + [clangd/vscode-clangd](https://github.com/clangd/vscode-clangd) - format with `.clang-format` and `.editorconfig` ## How to install -Before starting, make sure you've read the [mbed documentation](https://os.mbed.com/docs/mbed-os/v6.8/introduction/index.html). +Before starting, make sure you've read the [mbed documentation](https://os.mbed.com/docs/mbed-os/v6.15/introduction/index.html). We'll guide you in the process, just follow the steps. @@ -36,7 +36,7 @@ Then install the tools: ```bash # first install GNU core utilities brew install coreutils -# don’t forget to add `$(brew --prefix coreutils)/libexec/gnubin` to your `$PATH` +# 💡 don’t forget to add `$(brew --prefix coreutils)/libexec/gnubin` to your `$PATH` # then the prerequisites brew install git curl python @@ -45,21 +45,6 @@ brew install git curl python brew install make cmake ninja lcov gcovr stlink ccache open-ocd clang-format ``` -#### Ubuntu/Linux - -*Note: The following instructions have not really been tested, so you might need to modify the names of the packages.* - -```bash -# first update -sudo apt update - -# then the prerequisites -sudo apt install build-essential git python-minimal - -# and finally the needed tools -sudo apt install make cmake ninja-build lcov gcovr stlink ccache open-ocd -``` - ### 1. Clone the repository To start with: @@ -68,20 +53,15 @@ To start with: # Clone the repository git clone https://github.com/leka/LekaOS && cd LekaOS -# Clone or curl Mbed OS using the Makefile -make mbed_clone -# or -make mbed_curl - -# With mbed_clone You can specify a branch -make mbed_clone BRANCH=master +# Pull dependencies: mbed-os & mcuboot +make pull_deps ``` ### 2. Install mbed-cli & co I recommend the manual install. Make sure to follow the instructions from mbed: -> +> ```bash # install mbed-cli and mbed-tools (mbed-cli2) @@ -103,31 +83,12 @@ brew tap ArmMbed/homebrew-formulae brew install arm-none-eabi-gcc ``` -#### Ubuntu/Linux - -You can download the toolchain here: - -> - -The file to download should have a name looking like this: `gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2`, save it to your `$HOME` directory (or anywhere you can remember). - -Then do the following (you might need to change the name of the file depending on the version): - -```bash -# untar the new package in the directory of your choosing -tar -xjvf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2 - -# add the new toolchain to your path -export PATH=$PATH:$HOME/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux/bin/ - -# test it works -arm-none-eabi-gcc --version -``` - ## How to use We put together an handy [`Makefile`](./Makefile) to make it easier to configure and compile your projects. +### Building the project + ```bash # first configure the project make config @@ -141,16 +102,50 @@ make ### Flashing the board -> ⚠️ // TODO - add instructions for openOCD +Make sure you have [OpenOCD](https://openocd.org/) installed. ```bash make flash BIN_PATH=_build/path/to/binary_file.bin ``` +### Building & running unit tests + +```bash +# first configure unit tests +make config_unit_tests + +# build and run them +make ut + +# if you want to see coverage +make utc +``` + ## LekaOS, spikes & tests -The main idea behind this template is to have your main source files (those for the big project you're working on) under the [`./src`](./src) directory. +The firmware of the robot is located in [`./app/os`](./app/os) & [`./app/bootloader`](./app/bootloader). + +> `firmware = bootloader + os` + +Sometimes, you might need to create a simple, very basic example project to test a new features, investigate a bug or try a different solution to a problem. + +These can be added to the [`spikes`](./spikes) directory inside their own directory. You'll need at leat a `main.cpp` and a `CMakeLists.txt`. See [`mbed_blinky`](./spikes/mbed_blinky) for a working example. + +## VSCode & useful tools + +We use VSCode and a handful of plugins to work on LekaOS: + +- [Better C++ Syntax](https://github.com/jeff-hykin/better-cpp-syntax) +- [Better Comments](https://github.com/aaron-bond/better-comments) +- [Clang-Format](https://github.com/xaverh/vscode-clang-format-provider) +- [clangd](https://github.com/clangd/vscode-clangd) +- [CMake](https://github.com/twxs/vs.language.cmake) +- [CMake Tools](https://github.com/microsoft/vscode-cmake-tools) +- [Cortex-Debug](https://github.com/Marus/cortex-debug) +- [EditorConfig for VSCode](https://github.com/editorconfig/editorconfig-vscode) + +It is highly recommended to install them for a better experience and to make sure you comply with our coding style. -Now, you sometimes need to create a simple, very basic example project to test a new features, investigate a bug or try a different solution to a problem. +Settings for those plugins are shared in the repos and should not be modified. -These can be added to the [`spikes`](./spikes) directory inside their own directory. You'll need at leat a `main.cpp` and a `CMakeLists.txt`. See [`blinky`](./spikes/blinky) for a working example. +To configure autocompletion and code checking using `clangd`, simply run `make config_tools` in your terminal. And then in VSCode, run `CMake: Configure`.