Wednesday, August 1, 2018

HOW TO: Mongoose OS (mos) local build on Windows.

For those of you who are just getting started with mgos, you might have noticed that you would typically compile your app, or an example app, with a command like this:

mos build --arch <arch> 

For example to build the c_hello firmware example for the esp8266 arch, you would navigate to the c_hello app directory, and build it like so:

cd ~/mongoose-os/fw/examples/c_hello/
mos build --arch esp8266

The output will look like this:
$ mos build --arch esp8266
Connecting to https://mongoose.cloud, user test
Uploading sources (2331 bytes)
Firmware saved to build\fw.zip

fw.zip is the file ready to be flashed onto your device, but where did it come from?  How and where did it get built?  What's actually happening here is that it's connecting to the mongoose cloud, uploading your app's source files building it on the cloud (using their build environment, libraries and OS sources) and spitting it back to you when it's done.

But what if, say, you want to modify a driver or library to suit your needs, or insert some debug printouts to figure out why your device won't work?  Or what happens if you want to build your app without relying on someone else's cloud service?

Then you'll need local build.  Mongoose OS does facilitate this, and it's quite easy, but there are some little hiccups along the way for some users.

Step 1:  Docker CE for Windows
The first thing you're going to need to do is download and install Docker CE (Community Edition) for Windows.  It's free, but you're going to have to sign up (I know.... a pain...); and it's pretty hefty too at about 500MB or so.

Docker will probably ask you to enable the above features in Windows in order for Docker to work.  Keep in mind that if you enable these, VirtualBox will no longer work.


Open the Performance tab of Task Manager and check that Virtualization is enabled.  If it's not, enable it from your BIOS settings.  You may need to do a quick Google search to confirm that your CPU supports virtualization and how to enable it.

In my case I had to go to Windows Features, disable Hyper-V, restart, re-enable Hyper-V, and restart before it would show up as 'Enabled' in the Performance tab.  Some other users report having to do this too.

Step 2:  Install Go for Windows
This should be pretty easy.  Just go to https://golang.org/dl/ and select an x86 or x86_64 self-extracting installer for Windows.

To verify the installation:
> go version
go version go1.10.3 windows/amd64

If this doesn't work.  Add the go path to your environment.

Step 3: Run the local build command

mos build --local --arch --esp8266 --libs-dir ../../../libs/ --repo ../../../../mongoose-os/ --verbose

Verbose is optional.  I like to have it enabled so I can see what's going on.  --libs-dir and --repo are both compulsory.  --libs-dir needs to point to the "libs" directory where you have cloned all your Mongoose OS libs (click for a link to the github), and --repo just simply points to the source of your actual Mongoose OS source which you would clone from here.

You run this command from the root directory of the app that you want to compile.  To check that local build is truly working, you will want to disconnect yourself from the World Wide Web before running the command again.  Enjoy.