Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A suggestion for off-line building plus wsl #46

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

A suggestion for off-line building plus wsl #46

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
62b6a7b
Installation with WSL
OwenBrotherwood Mar 3, 2017
1a6f9ed
md lint
OwenBrotherwood Mar 3, 2017
a0140d3
native - Native
OwenBrotherwood Mar 3, 2017
03f405f
for review
OwenBrotherwood Mar 4, 2017
92f3c5d
add example cp for wsl
OwenBrotherwood Mar 4, 2017
c3163d6
remove hence
OwenBrotherwood Mar 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 49 additions & 124 deletions docs/offline-toolchains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<TARGET_NAME>/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/<TARGET_NAME>/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
```

Expand All @@ -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/<TARGET_NAME>/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/
```