From a0636eb9f896b83045f61d55858cb2e9b8a6ce6d Mon Sep 17 00:00:00 2001 From: Jonathan Hudson Date: Fri, 28 Aug 2020 11:42:56 +0100 Subject: [PATCH] refine Linux build document --- docs/development/Building in Linux.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/development/Building in Linux.md b/docs/development/Building in Linux.md index feb86f1d78..af62239528 100644 --- a/docs/development/Building in Linux.md +++ b/docs/development/Building in Linux.md @@ -8,7 +8,7 @@ inav requires a reasonably modern `gcc-arm-none-eabi` cross-compiler. Different In order to provide a uniform and reasonably modern cross compiler, inav provides for the installation of a "known good / working" cross compiler, as well as a mechanism to override this if your distro provides a more modern option (e.g Arch Linux). In general, from a security perspective, Linux distros discourage the installation of software from sources other than the official distribution repositories and 'approved' sources (Ubuntu PPA, Arch AUR). The inav approach of providing a recommended compiler is however both sound and justified: * The cross-compiler is installed from a reputable source (ARM, the company that makes the CPUs used in our flight controllers) -* Disto cross-compiler are often older than the recommended inav compiler +* Disto cross-compilers are often older than the recommended inav compiler * The installed cross-compiler is only used to build inav and it not obviously / generally available outside of the inav build environment. There are a however some specific cases for using the distro cross-compiler in preference to that installed by inav: @@ -16,8 +16,6 @@ There are a however some specific cases for using the distro cross-compiler in p * You are using a distro that installs a more modern compiler (Arch) * You are using a host platform for which ARM does not provide a compiler (e.g. Linux ia32). -However, before we consider the compiler options, it is necessary to install some other dependencies. - ## Prerequisites In addition to a cross-compiler, it is necessary to install some other tools: @@ -62,14 +60,14 @@ git clone https://github.com/iNavFlight/inav.git Note: If you have a Github account with registered ssh key you can replace the `git clone` command with `git clone git@github.com:iNavFlight/inav.git` instead of the https link. -The `git clone` creates an `inav` directory; we can enter this directory and try and build the firmware. +The `git clone` creates an `inav` directory; we can enter this directory, configure the build environment and build firmware. ## Build tooling -For 2.6 and later, inav uses `cmake` as its primary build tool. `cmake` simplies various platform and hardware dependencies required to cross compile multiple targets. `cmake` still uses GNU `make` to invoke the actual compiler. +For 2.6 and later, inav uses `cmake` as its primary build tool. `cmake` simplies various platform and hardware dependencies required to cross compile multiple targets. `cmake` still uses GNU `make` to invoke the actual compiler. It is necessary to configure the build enviroment with `cmake` before we can build any firmware. -## Cmake generate the build environment +## Using `cmake` The canonanical method of using `cmake` is to create a `build` directory and run the `cmake` and `make` commands from within the `build` directory. So, assuming we've cloned the firmware repository into an `inav` directory, we can issue the following commands to set up the build environment. @@ -82,7 +80,7 @@ cmake .. # note the "..", this is required as it tells cmake where to find its ruleset ``` -`cmake` will check for the presence of an embedded cross-compiler; if the cross-compiler is not found it will attempt to download the vendor (ARM) GCC cross-compiler. +`cmake` will check for the presence of an inav-embedded cross-compiler; if this cross-compiler is not found it will attempt to download the vendor (ARM) GCC cross-compiler. Note. If you want to use your own cross-compiler, either because you're running a distro (e.g. Arch Linux) that ships a more recent cross-compiler, or you're on a platform for which ARM doesn't provide a cross-compiler (e.g. 32bit Linux), the you should run the `cmake` command as: @@ -90,11 +88,11 @@ Note. If you want to use your own cross-compiler, either because you're running cmake -DCOMPILER_VERSION_CHECK=OFF .. ``` -`cmake` will generate a number of files in your `build` directory, including a cache of generated build settings `CMakeCache.txt` and a standard `Makefile`. +`cmake` will generate a number of files in your `build` directory, including a cache of generated build settings `CMakeCache.txt` and a `Makefile`. ## Bulding the firmware -Once `cmake` has generated the `build/Makefile`, this (and `make`) is used to build the firmware, again from the `build` directory. It is not necessary to re-run `cmake` unless the inav cmake configuration is changed (i.e. a new release) or you wish to swap between the ARM SDK compiler and a distro or other external compiler. +Once `cmake` has generated the `build/Makefile`, this `Makfile` (with `make`) is used to build the firmware, again from the `build` directory. It is not necessary to re-run `cmake` unless the inav cmake configuration is changed (i.e. a new release) or you wish to swap between the ARM SDK compiler and a distro or other external compiler. The generated `Makefile` uses different a target selection mechanism from the older (pre 2.6) top level `Makefile`; you can generate a list of targets with `make help` (or, as the list is extremely long), pipe this into a pager, e.g. `make help | less`. @@ -113,7 +111,7 @@ make MATEKF405 MATEKF722 The resultant hex file are in the `build` directory. -You can then use the INAV Configurator to flash the local `build/inav_TARGET.hex` file, or use `stm32flash` or `dfu-util` directly from the command line. +You can then use the INAV Configurator to flash the local `build/inav_x.y.z_TARGET.hex` file, or use `stm32flash` or `dfu-util` directly from the command line. [msp-tool](https://github.com/fiam/msp-tool) and [flash.sh](https://github.com/stronnag/mwptools/blob/master/docs/MiscTools.asciidoc#flashsh) provide / describe 3rd party helper tools for command line flashing.