From 62b6a7b18342a99698cfd65b2a2328f4391fc647 Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Fri, 3 Mar 2017 15:57:42 +0100 Subject: [PATCH 1/6] Installation with WSL Bash on Windows provides developers with a familiar Bash shell and Linux environment in which you can run most Linux command-line tools, directly on Windows, UNMODIFIED, without needing an entire Linux virtual machine! --- docs/offline-toolchains.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index 1ff961e..6a77e08 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -9,6 +9,12 @@ When using `yotta` to build micro:bit projects there are currently two supported ## Installation on Windows +There are three methods for building + +- VM: install a VM machine and use Linux method +- WSL: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method +- native: see below + ### Install yotta and dependencies The first step is to get `yotta` and its dependencies onto your machine, to do this follow the install guide [here](http://docs.yottabuild.org/#installing). From 1a6f9ed61fb05a56d6e97b4f374b3127826faeee Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Fri, 3 Mar 2017 17:39:35 +0100 Subject: [PATCH 2/6] md lint However, multiple headers with same content --- docs/offline-toolchains.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index 6a77e08..f23568b 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -11,9 +11,9 @@ When using `yotta` to build micro:bit projects there are currently two supported There are three methods for building -- VM: install a VM machine and use Linux method -- WSL: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method -- native: see below +* VM: install a VM machine and use Linux method +* WSL: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method +* native: see below ### Install yotta and dependencies @@ -38,7 +38,7 @@ A `yotta` target contains the information required by `yotta` in order to build You can use either `yotta` or `yt`, which is far easier to type! -``` +```bash yt target bbc-microbit-classic-gcc ``` @@ -60,9 +60,10 @@ The `yt build` command will place files in `/build//source`. The fi In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `E:`) as follows: -``` +```bash copy build\bbc-microbit-classic-gcc\source\microbit-samples-combined.hex E: ``` + The expected result will be that the micro:bit will scroll `HELLO WORLD! :)` on its display. ____________________ @@ -97,7 +98,7 @@ A `yotta` target contains the information required by `yotta` in order to build You can use either `yotta` or `yt`, which is far easier to type! -``` +```bash yt target bbc-microbit-classic-gcc ``` @@ -108,7 +109,7 @@ You only need to set the target once per project. All future `yotta` commands wi #### Build the project -``` +```bash yt build ``` @@ -119,7 +120,7 @@ The `yt build` command will place files in `/build//source`. The fi In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `/Volumes/"MICROBIT"`) as follows: -``` +```bash cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /Volumes/"MICROBIT" ``` @@ -143,7 +144,8 @@ The first step is to get `yotta` and its dependencies onto your machine, to do t For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Ubuntu** using -``` + +```bash sudo apt-get install srecord ``` @@ -165,7 +167,7 @@ A `yotta` target contains the information required by `yotta` in order to build You can use either `yotta` or `yt`, which is far easier to type! -``` +```bash yt target bbc-microbit-classic-gcc ``` @@ -176,7 +178,7 @@ You only need to set the target once per project. All future `yotta` commands wi #### Build the project -``` +```bash yt build ``` @@ -187,9 +189,10 @@ The `yt build` command will place files in `/build//source`. The fi In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `/media/MICROBIT`) as follows: -``` +```bash cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /media/MICROBIT ``` + The expected result will be that the micro:bit will scroll `HELLO WORLD! :)` on its display. !!!note From a0140d39a19357a6dc8e34fed4d189a51e278278 Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Fri, 3 Mar 2017 17:39:59 +0100 Subject: [PATCH 3/6] native - Native --- docs/offline-toolchains.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index f23568b..5249d84 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -13,7 +13,7 @@ There are three methods for building * VM: install a VM machine and use Linux method * WSL: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method -* native: see below +* Native: see below ### Install yotta and dependencies From 03f405f0960f85c48cdbd7142bef41ac2e0818c4 Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Sat, 4 Mar 2017 06:05:27 +0100 Subject: [PATCH 4/6] for review --- docs/offline-toolchains.md | 170 +++++++++---------------------------- 1 file changed, 39 insertions(+), 131 deletions(-) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index 5249d84..dddeefd 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -7,161 +7,93 @@ When using `yotta` to build micro:bit projects there are currently two supported * GCC * ARMCC -## Installation on Windows +## Installation -There are three methods for building +In general, the first step is to get `yotta` and its dependencies onto your machine, to do this follow the install guide [here](http://docs.yottabuild.org/#installing). -* VM: install a VM machine and use Linux method -* WSL: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method -* Native: see below - -### Install yotta and dependencies - -The first step is to get `yotta` and its dependencies onto your machine, to do this follow the install guide [here](http://docs.yottabuild.org/#installing). - - -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Windows** from [sourceforge](http://srecord.sourceforge.net/). - -`srecord` is used to create the final binaries for the micro:bit so is an essential dependency. - - -### Fetch the example project - -```bash -git clone https://github.com/lancaster-university/microbit-samples -cd microbit-samples -``` - -### Set your yotta target +For the micro:bit targets you currently still need the [`srecord` tools from sourceforge](http://srecord.sourceforge.net/) to create the final binaries for the micro:bit. -A `yotta` target contains the information required by `yotta` in order to build a project for a specific combination of hardware. This includes the type of compiler. The microbit projects can build with both `armcc` and `gcc`, but as it gets installed with the `yotta` installer, we'll use `gcc` by default and choose a micro:bit specific target that knows about the hardware on the board. - -You can use either `yotta` or `yt`, which is far easier to type! -```bash -yt target bbc-microbit-classic-gcc -``` +### Windows -!!! note - In microbit-samples this target will be configured by default. +The choices are: -You only need to set the target once per project. All future `yotta` commands will use this target information (for example, when resolving dependencies). +* VM: install a VM machine and use Linux method +* Windows 10: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method +* Native: follow the `yotta` install guide and install `srecord`. -#### Build the project +### OSX -``` -yt build -``` +The choices are: -### Flash your micro:bit -The final step is to check your hex works. +* VM: install a VM machine and use Linux method +* Native: follow the `yotta` install guide and install `srecord`. -The `yt build` command will place files in `/build//source`. The file you will need to flash will be microbit-combined.hex. Simply drag and drop the hex onto the MICROBIT usb device. +Note: -In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `E:`) as follows: +* [srecord is also available from brew](http://brew.sh/): ```bash -copy build\bbc-microbit-classic-gcc\source\microbit-samples-combined.hex E: -``` - -The expected result will be that the micro:bit will scroll `HELLO WORLD! :)` on its display. - -____________________ - -## Installation on Mac OSX - -### Install yotta and dependencies - -The first step is to get `yotta` and its dependencies onto your machine, to do this follow the install guide [here](http://docs.yottabuild.org/#installing). - - -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Mac OSX** using -[brew](http://brew.sh/): -``` brew install srecord ``` -You can also install it manually from [sourceforge](http://srecord.sourceforge.net/). +### Linux -`srecord` is used to create the final binaries for the micro:bit so is an essential dependency. +The choices are: -### Fetch the example project +* Native: follow the `yotta` install guide and install `srecord`. -```bash -git clone https://github.com/lancaster-university/microbit-samples -cd microbit-samples -``` +Note: -### Set your yotta target - -A `yotta` target contains the information required by `yotta` in order to build a project for a specific combination of hardware. This includes the type of compiler. The microbit projects can build with both `armcc` and `gcc`, but as it gets installed with the `yotta` installer, we'll use `gcc` by default and choose a micro:bit specific target that knows about the hardware on the board. - -You can use either `yotta` or `yt`, which is far easier to type! +* srecord is often available in the Linux distribution, for example: ```bash -yt target bbc-microbit-classic-gcc +sudo apt-get install srecord ``` -!!! note - In microbit-samples this target will be configured by default. +## Build your first project -You only need to set the target once per project. All future `yotta` commands will use this target information (for example, when resolving dependencies). +After installation, the result can be tested with some [microbit-samples](https://github.com/lancaster-university/microbit-samples). One can either git clone or download them. -#### Build the project +In the directory that contains microbit-samples, the quick test for sucessfull installation of the work so far is: ```bash +yt clean yt build ``` -### Flash your micro:bit -The final step is to check your hex works. - -The `yt build` command will place files in `/build//source`. The file you will need to flash will be `microbit-samples-combined.hex`. Simply drag and drop the hex onto the MICROBIT usb device. - -In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `/Volumes/"MICROBIT"`) as follows: +The file for the micro:bit is then `micro-bit-samples-combined.hex`, which can be found under the directory structure for `build`, the target `bbc-microbit-classic-gcc` and finally, `source`. -```bash -cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /Volumes/"MICROBIT" -``` +## Flash your micro:bit +Now that the hex is built, it can be flashed onto the micro:bit. The expected result will be that the micro:bit will scroll `HELLO WORLD! :)` on its display. -!!!note - Note that if you'd like to copy the file from the command line, you can use the following command in any `yotta` project to do so, though it assumes you have only one micro:bit plugged in: - - ``` - cp build/$(yt --plain target | head -n 1 | cut -f 1 -d' ')/source/$(yt --plain ls | head -n 1 | cut -f 1 -d' ')-combined.hex /Volumes/"MICROBIT" - ``` - +### Windows -____________________ +Flash the micro:bit (assuming it is plugged in and mounted at `E:`) as follows: -## Installation on Linux - -### Install yotta and dependencies - -The first step is to get `yotta` and its dependencies onto your machine, to do this follow the install guide [here](http://docs.yottabuild.org/#installing). +```bash +copy build\bbc-microbit-classic-gcc\source\microbit-samples-combined.hex E: +``` +### MacOS -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Ubuntu** using +Flash the micro:bit (assuming it is plugged in and mounted at `/Volumes/"MICROBIT"`) as follows: ```bash -sudo apt-get install srecord +cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /Volumes/"MICROBIT" ``` -You can also install it manually from [sourceforge](http://srecord.sourceforge.net/). - -`srecord` is used to create the final binaries for the micro:bit so is an essential dependency. +### Linux - -### Fetch the example project +Flash the micro:bit (assuming it is plugged in and mounted at `/media/MICROBIT`) as follows: ```bash -git clone https://github.com/lancaster-university/microbit-samples -cd microbit-samples +cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /media/MICROBIT ``` -### Set your yotta target +## Tips A `yotta` target contains the information required by `yotta` in order to build a project for a specific combination of hardware. This includes the type of compiler. The microbit projects can build with both `armcc` and `gcc`, but as it gets installed with the `yotta` installer, we'll use `gcc` by default and choose a micro:bit specific target that knows about the hardware on the board. @@ -176,28 +108,4 @@ yt target bbc-microbit-classic-gcc You only need to set the target once per project. All future `yotta` commands will use this target information (for example, when resolving dependencies). -#### Build the project - -```bash -yt build -``` - -### Flash your micro:bit -The final step is to check your hex works. - -The `yt build` command will place files in `/build//source`. The file you will need to flash will be `microbit-samples-combined.hex`. Simply drag and drop the hex onto the MICROBIT usb device. - -In the case of our example, using `bbc-microbit-classic-gcc` we could flash the micro:bit (assuming it is plugged in and mounted at `/media/MICROBIT`) as follows: - -```bash -cp ./build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex /media/MICROBIT -``` - -The expected result will be that the micro:bit will scroll `HELLO WORLD! :)` on its display. - -!!!note - Note that if you'd like to copy the file from the command line, you can use the following command in any `yotta` project to do so, though it assumes you have only one micro:bit plugged in: - ``` - cp build/$(yt --plain target | head -n 1 | cut -f 1 -d' ')/source/$(yt --plain ls | head -n 1 | cut -f 1 -d' ')-combined.hex /media/MICROBIT/ - ``` From 92f3c5d64f71147982f4b5e628682c91cbb25a8f Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Sat, 4 Mar 2017 17:34:42 +0100 Subject: [PATCH 5/6] add example cp for wsl --- docs/offline-toolchains.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index dddeefd..af190ee 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -22,6 +22,14 @@ The choices are: * Windows 10: install [wsl](https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide) and use the linux method * Native: follow the `yotta` install guide and install `srecord`. +Note: + +At the time of writing, wsl does not allow access to usb. Copy the hex file over to c: + +```bash +cp build/bbc-microbit-classic-gcc/source/microbit-samples.hex /mnt/c/ +``` + ### OSX The choices are: From c3163d6596908227ebf393d6535bdf9585c929bd Mon Sep 17 00:00:00 2001 From: Owen Brotherwood Date: Sat, 4 Mar 2017 17:37:43 +0100 Subject: [PATCH 6/6] remove hence --- docs/offline-toolchains.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index af190ee..341bee8 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -1,6 +1,6 @@ # Yotta -The micro:bit DAL is built on top of [ARM mbed](http://mbed.com) and hence uses [yotta](http://yotta.mbed.com) as an offline build system. +The micro:bit DAL is built on top of [ARM mbed](http://mbed.com) and uses [yotta](http://yotta.mbed.com) as an offline build system. When using `yotta` to build micro:bit projects there are currently two supported toolchains: