How to build for ESP32

yichone edited this page Dec 1, 2016 · 8 revisions



The following tools are required, use apt-get to install them.

  • GNU autoconf, libtool, libtool-bin
  • GNU flex, bison, gawk,
  • libexpat1-dev


We utilize VirtualBox (VB) with Ubuntu installed as build environment. If your OS is Linux, you can also setup the build environment according the following steps:

    1. Download and install VirtualBox-5.0.16-105871-Win (You'd better install the latest version, since I found that the older version such as 4.x cannot install the VB Guest Additions)
  • Download ubuntu-15.10-desktop-amd64.iso and install it on VB. Make sure that asign more than 1G RAM and 12G Hard Disk for this virtual machine. The tool chain build process require much memory!
    1. Setup share file folder: Settings->Share Folders->Add new shared folder, input your share folder path and the select Make Permanent, Note that do not select Auto Mount. Launch Ubuntu and then create a folder to mount the share folder, I create a folder, named share, in the path /mnt. Type the commond in the terminal to mount share folder:
sudo mount -t vboxsf share /mnt/share 

Note: if you mount failed, check whether the module vboxsf is exist by executing commond c lsmod | grep vboxsf. If nothing found, maybe the Guest Additions are not installed correctly. Try to install that again or upgrade your VirtualBox to the latest version.

    1. Download toolchain: Before downloading, make sure that the git has been installed, if not, install it by sudo apt-get install git. I create path /opt/Espressif and then install to sdk to it, then make the current user the owner:
sudo chown $USER /opt/Espressif/; Execute the following commond to download toolchain:
cd /opt/Espressif/
git clone -b esp108-1.21.0 git://
    1. Install toolchain: Before installing, make sure that all the required tools list in Requirements are installed on your virtual machine. Type the following commands to build the toolchain.
cd crosstool-NG
./bootstrap && ./configure --prefix=`pwd` && make && make install
./ct-ng xtensa-esp108-elf
./ct-ng build
    1. After installing the toolchain, export the bin path by the following commond, then you can build your source on your machine! Note: if your machine is not enough memory, the error such as Build failed in step: 'installing pass-2 core C compiler' may occur. The following screenshot shows the error:

    1. After installing the toolchain, export the bin path by the following commond, then you can build your source on your machine!
export PATH=/opt/Espressif/crosstool-NG/builds/xtensa-esp108-elf/bin:$PATH

Now that you can place your source in the share folder, build it with your virtual machine.

Build App:

  • Create a directory, say LuaNode, and then clone the LuaNode project to it: git clone --recursive
  • Create a Bin folder for LuaNode, say LuaNode_Bin, you should place LuaNode_Bin and LuaNode_Esp32 at the same directory.
  • Modify the, setup the following three variables: SDK_PATH, BIN_PATH, and APP_NAME. SDK_PATH is the path of LuaNode_Esp32; BIN_PATH is the path of LuaNode_Bin; APP is the path of the application that you want to build. The apps you can build is in the apps folder.
  • Start to build by input ./ in your shell.


  • System requiement: RAM>1G; Hard Disk>10G
  • Setup the build environment as that on Windows:)

Mac OS:

  • Download and install VirtualBox for Mac
  • Assign memory > 1G and hard disk > 12G for the virtual machine
  • Setup the build environment as that on Windows:)



The required tools are the same as those list in the section How To Build for ESP8266. But the firmware for ESP32 utilize different toolchain.


Follow the Step 1~3 list in How To Build for ESP32.

  • Create a new directory for toolchain by executing the commond: sudo mkdir /opt/esp-open-sdk. Download the latest toolchain:

  • git clone --recursive /opt/esp-open-sdk Install the toolchain (If you are not in the toolchain directory now, change directory first cd /opt/Espressif/): 'make STANDALONE=y'

  • Setup PATH variable: export PATH=/opt/esp-open-sdk/xtensa-lx106-elf/bin:$PATH

Note: You have to export PATH again if you restart the shell. If you don't want to reqeat this step, you 
can place the toolchain directory to the .bashrc file.

If you prefer IDE, such as Eclipse, you can also build the firmware with Eclipse. To setup Eclipse, follow the steps list below:

Note: You should place the Eclipse under the path C:, since the install-mingw-package.bat   
run in step 5 will search the path. If install-mingw-package.bat run failed, it may   
probably you didn't place Eclipse in C:
    1. Download and install MinGW. Run the downloader mingw-get-setup.exe, the installation process to select without GUI, ie uncheck "... also install support for the graphical user interface".
    1. Run from the file install-mingw-package.bat. He will establish the basic modules for MinGW, installation should proceed without error.
    1. Start the Eclipse Luna from the directory c:\eclipse\eclipse.exe
    1. In Eclipse, select File -> Import -> General -> Existing Project into Workspace, in the line Select root directory, select the directory C:\Espressif\examples and import work projects. Further, the right to select the Make Target project, such as hello-world and run the target All the assembly, while in the console window should display the progress of the build. To select the target firmware flash.

Now that you can build firmware using Eclipse, if you have any questions, go to ESP8266 Community Forum, read this post for details.


Setup as that in Windows VirtualBox

Mac OS:

Setup as in Windows

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.