Merge pull request #174 from erlingrj/zephyr-update

Update Zephyr docs

packages/documentation/copy/en/embedded/Zephyr.md

@@ -19,7 +19,6 @@ Arduino-support, which is `lfc`-centric.
 
 ## Prerequisites
 - Linux or macOS development system
-- `lfc` v0.4.0 or greater
 - nrf52 Development Kit (optional)
 
 # Getting started
@@ -106,9 +105,21 @@ You should now be able to build and emulate a simple Hello World! LF program:
 
 ```
 cd application
-west lf-build src/HelloWorld.lf -w "-t run"
+lfc src/HelloWorld.lf -n
+west build src-gen/HelloWorld -t run
 ```
-`HelloWorld.lf` sets the target property `platform: "Zephyr"` and `threading: false`. This tells `lfc` to create a Zephyr-compatible CMake project. In the example above the custom `west` command `lf-build` is used to first invoke `lfc` and then `west build` on the resulting generated sources.
+`HelloWorld.lf` has the target properties `platform: "Zephyr"` and `threading: false`. This tells `lfc` to create a Zephyr-compatible CMake project. Then we use `west` to build the
+generated CMake project and to start an emulation.
+
+To enable **west-centric** development we have added a custom west command, `west lfc`. 
+It is a wrapper around the original lfc but also copies the files `prj.conf` and `Kconfig`
+into to generated project. It can also invoke `west build` directly. The above example
+can be compiled and emulated with the following command:
+```
+west lfc src/HelloWorld.lf --build "-t run"
+```
+
+The string within the quotation marks after `--build` is passed on to `west build`.
 
 # Nrf52 blinky
 In this example we will program a simple Blinky program onto an nrf52dk. This
@@ -118,59 +129,54 @@ the following installation guide
 
 ```
 cd application
-west lf-build src/NrfBlinky.lf -w "-b nrf52dk_nrf52832 -p always"
+west lfc src/NrfBlinky.lf --build "-p always -b nrf52dk_nrf52832"
 west flash
 ```
-In this example we use the `-w` flag to pass additional flags to `west build`. In particular we inform `west` that we are targeting a the nrf52 with `-b nrf52dk_nrf52832`. We also tell west to clean the build directory first with `-p always`.
+In this example we use the `-p always` to tell west to do a clean build and `-b nrf52dk_nrf52832` to target the nrf52dk. These parameters are west-specific so
+refer to west documentation for more info. `west flash` is used to interact with
+`nrfjprog` and flash the application into the dev-board.
 
-# Kernel configuration options
+# Zephyr configuration options
 The Lingua Franca Zephyr platform depends on some specific [Zephyr Kernel configurations](https://docs.zephyrproject.org/latest/build/kconfig/index.html#).
 For instance, the Counter drivers must be linked with the application to provide
 hi-resolution timing. These required configurations are stored in a file called
 `prj_lf.conf` which is copied to the generated `src-gen` folder by `lfc`. You
 can also supply your own configuration options in a file called `prj.conf` which
-has to be located in the same folder as `west lf-build` is invoked from.
-There is such a file located in `~/application` in the template. There is also a
-file called `debug.conf` which is meant for containing debug options. Such
-additional configuration files can also be passed to `west lf-build` through the
-`--conf-overlays` options. E.g. `west lf-build -c debug.conf`.
-
-# The `lf-build` west command
-The custom `lf-build` west command has already been used in previous sections.
+has to be located in the same folder as `west lfc` is invoked from.
+There is such a file located in `~/application` in the template. There is also
+a `Kconfig` file. Both are copied into the `src-gen` folder when invoking
+`west lfc`.
+
+# The `west lfc` command
+The custom `lfc` west command has already been used in previous sections.
 It can be inspected in `scripts/lf_build.py`.
-It invokes `lfc` on the provided LF source file.
-It then invokes `west build` on the generated sources.
-If you would like to pass forward arguments to the `west build` command do so
-with the `-w` flag. E.g. `-w -b nrf52dk_nrf52832 -p always` passes information
-about the dev-kit and also tells `west` to clean the build folder before
-starting.
-One of the important functions of `lf-build` is to parse a file called
-`CompileDefinitions.txt` generated by `lfc`. This file contains all the compiler
-definitions which should be defined for the program. `lf-build` passes all the
-compiler definitions to the `west build` command.
-
-Please see `west lf-build -h` for more information and the `scripts/lf_build.py`.
+It invokes `lfc` on the provided LF source file. It also copies `prj.conf` and `Kconfig`
+into the src-gen directory before it, optionally, calls `west build` on the
+resulting project.
+
+Please see `west lfc --help` for more information and the `scripts/lf_build.py`.
 
 # Debugging LF Zephyr programs using QEMU and GDB
 In this section we will see how a LF program can be debugged while running in QEMU emulation.
 
 1. Compile `HelloWorld.lf` for `qemu_cortex_m3`
 ```
 cd application
-west lf-build src/HelloWorld.lf -w "-b qemu_cortex_m3 -p always"
+west lfc src/HelloWorld.lf --build "-b qemu_cortex_m3 -p always"
 ```
-Note that we here, unlike the very first example, explicitly tell `lf-build` that we are targeting a `qemu_cortex_m3` platform. This is the default platform which is used unless another is specified. It is added here for clarity. 
+Note that we here, unlike the very first example, explicitly tell `lfc` that we are targeting a `qemu_cortex_m3` platform. This is the default platform which is used unless another is specified. It is added here for clarity. 
 
-2. Start qemu as a debug server waiting for a local connection from `gdb`
+2. In one terminal, start qemu as a debug server waiting for a local connection from `gdb`
 ```
 ninja -C build debugserver
 ```
 
-3. Start `gdb` and connect to the qemu server. Load the application image and run until main.
+3. In another terminal start `gdb` and connect to the qemu server. Load the application image and run until main.
 ```
 $ZEPHYR_SDK/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb
 (gdb) arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb
 (gdb) target remote localhost:1234
+(gdb) file build/zephyr/zephyr.elf
 (gdb) b main
 (gdb) c
 ```
@@ -189,7 +195,7 @@ This causes the emulation of threaded programs to appear as if the `fast` target
 ## Troubleshooting
 
 ### Multiple Zephyr installations
-If the follwing warning is shown when invoking `west lf-build` or any other `west` command:
+If the following warning is shown when invoking `west lfc` or any other `west` command:
 ```
 WARNING: ZEPHYR_BASE=/path/to/zephyr in the calling environment will be used,
 but the zephyr.base config option in /path/to/lf-west-template is "deps/zephyr"