Building

There are several options to building Espruino on various platforms for the OS and board versions that are avaiable.

To build and run Espruino on the OS that one is using is as simple as the following, if prerequisits are met:

make clean && make

Note:

In general, have a look through the head of the Makefile to see what other options are available
If you're swapping between compiling for different targets, you need to call make clean before you compile for the new target.
RELEASE=1 for performance and code size, without it, assertions are kept for debugging.
DEBUG=1 is available (it may not be possible to build many targets with DEBUG=1 without first disabling features in boards/BOARDNAME.py

Building a specific board

To work out which 'Board name' to use, simply look in the boards folder for the right BOARD.py file. To build for boards/PUCKJS.py use BOARD=PUCKJS RELEASE=1 make

Super Easy GitHub method

GitHub now automatically builds Espruino for the most popular targets.

Simply go to https://github.com/espruino/Espruino/actions, click on the build you're interested in, then scroll down to the Artefacts heading. Just click on an artefact (for instance PUCKJS) to download a zip containing the files.

To perform a DFU update on an nRF52 device, you need to unzip the BOARDNAME.zip file and then the zip file inside that called espruino_2vXX.YY_boardname.zip is the one you need to use for the firmware updates. On MacOS it may not be immediately apparent that the thing in BOARDNAME.zip named espruino_2vXX.YY_boardname is another zip file, and not a folder.

If you fork the Espruino repository and make changes yourself you should be able to see the builds for your changes at https://github.com/YOUR_USERNAME/Espruino/actions

Note: the firmware files produced by this method are for uploads via a bootloader only. If you need a full binary file for uploading via SWD you'll need to follow the instructions below.

Under Linux (recommended)

Espruino is easy to build under Linux, for either for Espruino running on Linux or a board.

Easy Method : provision.sh

Simply run the following with the name of your board to set your computer up ready for a build:

source scripts/provision.sh BOARDNAME

This should work for common platforms on Linux, but will only set paths up for your current session. You'll have to run it again next time you log in.

Manual Method (not recommended)

For Espruino

sudo apt-get update
sudo apt-get install -y \
  build-essential git python python-pip
sudo pip install --upgrade pip
# User choice for placement of source repos
mkdir -p ~/source/repos/github/espruino
cd ~/source/repos/github/espruino
git clone https://github.com/espruino/Espruino.git
cd Espruino
make clean && make
chmod +x espruino && sudo cp espruino /usr/local/bin

for cross compilation to Puck.js

Having successfully created an native OS Espruino, try a cross compilation.

sudo apt-get update
sudo pip install nrfutil
sudo apt-get install -y \
  lib32z1 lib32ncurses5
wget https://launchpad.net/gcc-arm-embedded/5.0/5-2016-q3-update/+download/gcc-arm-none-eabi-5_4-2016q3-20160926-linux.tar.bz2
tar xjf gcc-arm-none-eabi-5_4-2016q3-20160926-linux.tar.bz2
sudo mv gcc-arm-none-eabi-5_4-2016q3 /usr/local
export PATH=/usr/local/gcc-arm-none-eabi-5_4-2016q3/bin:$PATH
cd ~/source/repos/github/espruino/Espruino
make clean && DFU_UPDATE_BUILD=1 BOARD=PUCKJS RELEASE=1 make
ls -l *puckjs*

Under MacOS

Create a self growing sparse image and mount

mkdir ~/diskimages

hdiutil create -size 10g -fs "Case-sensitive HFS+" -volname Espruino ~/diskimages/Espruino.sparsebundle

hdiutil attach ~/diskimages/Espruino.sparsebundle

sudo ln -s /Volumes/Espruino/ /Espruino

cd /Espruino

Resize if needed

hdiutil detach /Volumes/Espruino
hdiutil resize -size 15G ~/diskimages/Espruino.sparsebundle
hdiutil attach ~/diskimages/Espruino.sparsebundle

Create some directories on /Espruino

mkdir /Espruino/{gcc,sdk,repos,tmp}

/Espruino -+- gcc     GNU Compiler Collection for different processors
           +- sdk     Software Development Kits
           +- repos   like Espruino EspruinoDocs ... 
	   +- tmp     temporary files

Install build and flash tools

brew upgrade gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake

# version 1.4.0
brew upgrade stlink

# version 2.1
pip install esptool

Get GNU Compiler Collection

# Espruino, Pico, PuckJS, EspruinoWifi 
# gcc arm https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads
curl -Ls https://goo.gl/42fcKX | tar -C gcc -xvzf - 

# xtensa gcc - pre buid from  https://github.com/MaBecker/esp8266
curl -Ls https://github.com/MaBecker/esp8266/xtensa-lx106-elf-4.8.5.tgz | tar -C gcc -xvzf -

Get SDK

# ESP8266/esp8285 starting with 01  
# espressif ESP8266 2.0 <- actual one 
wget -P tmp  https://github.com/espressif/ESP8266_NONOS_SDK/archive/v2.0.0.zip
unzip -d sdk tmp/v2.0.0.zip
rm tmp/v2.0.0.zip
# add esptool.py
mkdir /Espruino/sdk/ESP8266_NONOS_SDK-2.0.0/esptool
ln -s /usr/local/bin/esptool.py /Espruino/sdk/ESP8266_NONOS_SDK-2.0.0/esptool/

The other stuff is similar to Linux

Under Windows

It is possible to build Espruino under Windows with the following addition to the Linux explanation:

Install Bash on Ubuntu on Windows 10 https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide
- After enabling, just use the instructions for Linux

Note:

there is no access to USB in the present version
- copy any crosscompile output to one's user directory and either bluetooth or USB the result to the target
Ubuntu 14.04 LTS is the present version.

Or use a Virtual machine as described below dependent on ones taste.

Cross compilation

for Raspberry Pi

Using RASPBIAN JESSIE WITH PIXEL, getting Espruino is easy.

To enable the full power of Espruino on the Pi, WiringPi:

sudo apt-get install wiringpi

Getting Espruino:

clone this repository and cd into the directory
- make clean && make
- chmod +x espruino && sudo cp espruino /usr/local/bin

for OpenWRT

Follow the instructions for OpenWRT build system

After a successful OpenWRT build, OpenWRT Espruino packages

for STM32 Boards (incl. Espruino Board

make clean && BOARD=BOARDNAME RELEASE=1 make

Where BOARDNAME is one of:

PICO_R1_3 for Espruino Pico
ESPRUINOBOARD for Original Espruino
ESPRUINOWIFI for Espruino WiFi

Or choose another board name based on the files in boards/*.py

BOARD=BOARDNAME RELEASE=1 make serialflash will flash to /dev/ttyUSB0 using the STM32 serial bootloader (what's needed for the Espruino and HY boards)
BOARD=BOARDNAME RELEASE=1 make flash will flash using st-flash if it's a discovery board, the maple bootloader if using that board, or will copy the binary to /media/NUCLEO if using a Nucleo board.

It may complain that there isn't enough space on the chip. This isn't an issue unless you save to flash, but you can fix the error in a few ways:

Disable the check by adding TRAVIS=1
Change the compile flags from -O3 to -Os in the Makefile
Knock out some functionality (like USE_GRAPHICS=1) that you don't need in the Makefile

Note: Espruino boards contain a special bootloader at 0x08000000 (the default address), with the Espruino binary moved on 10240 bytes to 0x08002800. To load the Espruino binary onto a board at the correct address, use BOARD=ESPRUINO_1V3 RELEASE=1 make serialflash. If you want to make a binary that contains the bootloader as well as Espruino (like the ones that the Espruino Web IDE expects to use) use the script scripts/create_espruino_image_1v3.sh which will compile the bootloader and Espruino, and then join them together.

for Nordic Semiconductor's nRF51/nRF52 series devices

Dependant on the board, either usb or bluetooth can be used to program the board or install the bootloader from different devices.

Bluetooth Low energy
- the board will appear as Espruino XYZ where XYZ is the board name
USB
- the board appears as a drive to drop a hex on

for Puck.js and Pixl.js

The Puck.js and Pixl.js are based on the nRF52

# Puck.js
make clean && DFU_UPDATE_BUILD=1 BOARD=PUCKJS RELEASE=1 make
# Pixl.js
make clean && DFU_UPDATE_BUILD=1 BOARD=PIXLJS RELEASE=1 make

The resulting file is a zip that has to be transferred via Bluetooth Low Energy. See the Puck.js and Pixl.js pages for information concerning transferring the ZIP.

for NRF52-DK

All boards based on the nRF52 have RAM and Flash to support Espruino without feature disablement.

make clean && BOARD=NRF52832DK RELEASE=1 make

for micro:bit

The micro:bit is based on the nRF51.

make clean && BOARD=MICROBIT RELEASE=1 make
Drop the hex generated on the micro:bit drive and it is then an Espruino.

Note:

At the time of writing, if one uses the Espruino Web IDE, access the Settings->Communications
- Request board details on connect: false
- Throttle Send: true

for NRF51-DK

All boards based on the nRF51 are limited in RAM and Flash so many features are disabled.

make clean && BOARD=NRF51822DK RELEASE=1 make

for esp8266

In order to compile for the esp8266 on Linux several pre-requisites have to be installed:

the esp-open-sdk from https://github.com/pfalcon/esp-open-sdk, use make STANDALONE=n
the Espressif NONOS SDK (version 2.2.1) from https://github.com/espruino/EspruinoBuildTools/blob/master/esp8266/ESP8266_NONOS_SDK-2.2.1.tgz

To run make you need to pass a couple of environment variables to make. These include:

BOARD=ESP8266_BOARD
FLASH_4MB=1 if you have an esp-12
ESP8266_SDK_ROOT=<Path to the 2.21 SDK>
PATH=<Path to esp-open-sdk/xtensa-lx106-elf/bin/>
COMPORT=</dev/ttyUSB0|COM1|...>

The easiest is to place the following lines into a script, adapt it to your needs and then run it.

#! /bin/bash
export BOARD=ESP8266_BOARD
export FLASH_4MB=1
export ESP8266_SDK_ROOT=/esp8266/sdk/ESP8266_NONOS_SDK-2.2.1
export PATH=$PATH:/esp8266/gcc/xtensa-lx106-elf/bin/
export COMPORT=/dev/ttyUSB0
make clean && make $*

If you do make flash it will try to flash your esp8266 module over serial
If you do make wiflash it will try to flash you esp8266 module over wifi, which assumes that it's already running Espruino
You will also get an espruino_2v0x_*_esp8266.tgz archive, which contains everything you need to flash a module (except for esptool.py), including a README_flash.txt

for esp32

On 64 bit linux:

git clone https://github.com/espruino/Espruino.git
cd Espruino
source scripts/provision.sh ESP32
make clean && BOARD=ESP32 make

If you are on a different platform such as the Mac, you will need to install the toolchain and esp-idf for your platform, see http://esp-idf.readthedocs.io/en/latest/macos-setup.html

The easiest way to get the esp-idf environment is to install: https://github.com/espruino/EspruinoBuildTools

and then replace the toolchain with what is required for your platform.

You only need to use the EspruinoBuildTools if you want to compile esp-idf libaries

Building on Eclipse

When building on Eclipse, update the Makefile properties to include the definitions show above. The easiest way to achieve that task is to right-click your Espruino project and select properties. From there, navigate to C/C++ Build > Environment.

Embedding in other applications

You can build Espruino with BOARD=EMBED RELEASE=1 make and a .c and .h file will be generated.

It doesn't contain any of the hardware access code, just the basic JS interpreter.

See targets/embed/test.c for an example of usage.

Documentation

sudo pip install markdown
python scripts/build_docs.py

This will create a file called functions.html that is a version of the reference pages, but based on your source code.

Virtual Machines under Windows and MacOS

The easiest solution for a Virtual Machine for Windows and MacOS is VirtualBox. A really easy way to provision, ie setup the system for development, is Vagrant.

Note:

Windows
- Installation of https://git-scm.com/ gives a ssh that can be used with vagrant ssh

Vagrant and VirtualBox

For your host OS (Windows or MacOS)
- Download and install VirtualBox
- Download and install Vagrant
- Note: for MacOS, the two previous steps can be accomplished easily with Homebrew Cask
  - brew cask install virtualbox vagrant
Clone this repository and navigate with the command prompt to the contents
Install the auto-network plugin
- vagrant plugin install vagrant-auto_network
Execute
- vagrant up
  - This will take a little while while the box is downloaded, and your virtual machine is provisioned.
- vagrant ssh
  - a ssh session into your new VM will be created.
- cd /vagrant && make clean && make
  - a native OS version of Espruino is now built. See this documentation for further examples
- To exit the ssh session
  - exit.
- On the host OS, the following are useful vagrant commands
  - vagrant suspend
    - will pause the VM
  - vagrant halt
    - will stop the VM
  - See Vagrant's "Getting Started" page for further information.

VirtualBox

If one does not wish to use vagrant, then install Virtual Box and use the Linux method.

USB access

In order to access USB, bluetooth or connected USB devices, one has USB filters to dedicate access to the guest OS. The easiest method is via the VirtualBox Manager, and select which devices should be dedicated to the VM with the device filter. Note: VirtualBox Guest Additions from VirtualBox are required.

To flash Espruino from the VM

Plug the Espruino board in while holding BTN1, and wait for Windows to finish connecting to the USB device
Go into the VirtualBox Manager (There's no need to stop your VM)
Click on USB, then click on the icon with the + sign (With the tooltip 'Adds a new USB filter ... selected USB device')
Click on the device labeled STMicroelectronics STM32 ...
Now unplug the Espruino board, wait a few seconds, and plug it back in (holding BTN1 again)
Go back into the VM, and type sudo BOARD=ESPRUINO_1V3 RELEASE=1 make serialflash
Your board will now be flashed

Note: if you want to you can change permissions so you don't need sudo by typing sudo cp misc/45-espruino.rules /etc/udev/rules.d;sudo udevadm control --reload-rules and then re-inserting the board.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README_Building.md

README_Building.md

Building

Building a specific board

Super Easy GitHub method

Under Linux (recommended)

Easy Method : provision.sh

Manual Method (not recommended)

For Espruino

for cross compilation to Puck.js

Under MacOS

Create a self growing sparse image and mount

Resize if needed

Create some directories on /Espruino

Install build and flash tools

Get GNU Compiler Collection

Get SDK

Under Windows

Cross compilation

for Raspberry Pi

for OpenWRT

for STM32 Boards (incl. Espruino Board

for Nordic Semiconductor's nRF51/nRF52 series devices

for Puck.js and Pixl.js

for NRF52-DK

for micro:bit

for NRF51-DK

for esp8266

for esp32

Building on Eclipse

Embedding in other applications

Documentation

Virtual Machines under Windows and MacOS

Vagrant and VirtualBox

VirtualBox

USB access

To flash Espruino from the VM

Files

README_Building.md

Latest commit

History

README_Building.md

File metadata and controls

Building

Building a specific board

Super Easy GitHub method

Under Linux (recommended)

Easy Method : provision.sh

Manual Method (not recommended)

For Espruino

for cross compilation to Puck.js

Under MacOS

Create a self growing sparse image and mount

Resize if needed

Create some directories on /Espruino

Install build and flash tools

Get GNU Compiler Collection

Get SDK

Under Windows

Cross compilation

for Raspberry Pi

for OpenWRT

for STM32 Boards (incl. Espruino Board

for Nordic Semiconductor's nRF51/nRF52 series devices

for Puck.js and Pixl.js

for NRF52-DK

for micro:bit

for NRF51-DK

for esp8266

for esp32

Building on Eclipse

Embedding in other applications

Documentation

Virtual Machines under Windows and MacOS

Vagrant and VirtualBox

VirtualBox

USB access

To flash Espruino from the VM