diff --git a/docs/offline-toolchains.md b/docs/offline-toolchains.md index 1ff961e..341bee8 100644 --- a/docs/offline-toolchains.md +++ b/docs/offline-toolchains.md @@ -1,165 +1,113 @@ # 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: * GCC * ARMCC -## Installation on Windows +## Installation -### Install yotta and dependencies +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). -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 from sourceforge](http://srecord.sourceforge.net/) to create the final binaries for the micro:bit. -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Windows** from [sourceforge](http://srecord.sourceforge.net/). +### Windows -`srecord` is used to create the final binaries for the micro:bit so is an essential dependency. +The choices are: +* 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`. -### Fetch the example project +Note: -```bash -git clone https://github.com/lancaster-university/microbit-samples -cd microbit-samples -``` - -### 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! - -``` -yt target bbc-microbit-classic-gcc -``` - -!!! note - In microbit-samples this target will be configured by default. - -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 +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/ ``` -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-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 `E:`) as follows: - -``` -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. -____________________ +### OSX -## Installation on Mac OSX +The choices are: -### Install yotta and dependencies +* VM: install a VM machine and use Linux method +* Native: follow the `yotta` install guide and install `srecord`. -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). +Note: +* [srecord is also available from brew](http://brew.sh/): -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Mac OSX** using -[brew](http://brew.sh/): -``` +```bash 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 +* srecord is often available in the Linux distribution, for example: -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! - -``` -yt target bbc-microbit-classic-gcc +```bash +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`. -``` -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 +```bash +copy build\bbc-microbit-classic-gcc\source\microbit-samples-combined.hex E: +``` -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). +### MacOS +Flash the micro:bit (assuming it is plugged in and mounted at `/Volumes/"MICROBIT"`) as follows: -For the micro:bit targets you currently still need the `srecord` tools, which can be installed on **Ubuntu** using -``` -sudo apt-get install srecord +```bash +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. You can use either `yotta` or `yt`, which is far easier to type! -``` +```bash yt target bbc-microbit-classic-gcc ``` @@ -168,27 +116,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 - -``` -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: - -``` -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/ - ```