From 8edc963f08812b287d99d9eaae1801421dabc6cc Mon Sep 17 00:00:00 2001 From: Ryan Jacobs Date: Tue, 17 Feb 2015 14:38:17 -0800 Subject: [PATCH] README: Convert to markdown, improve grammar. --- README | 101 ------------------------------------------------- README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 101 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index ee40a73..0000000 --- a/README +++ /dev/null @@ -1,101 +0,0 @@ -This repository provides integration scripts to build complete standalone -SDK (with toolchain) for software development for Espressif ESP8266, -ESP8266EX chips. - -Complete SDK consists of: - -1. Xtensa lx106 architecture toolchain (100% OpenSource), based on -following projects: - -https://github.com/jcmvbkbc/crosstool-NG -https://github.com/jcmvbkbc/gcc-xtensa -https://github.com/jcmvbkbc/newlib-xtensa -https://github.com/tommie/lx106-hal - -The sourcecode above originates from work done directly by Tensilica Inc., -Cadence Design Systems, Inc, or their contractors. - -2. ESP8266 IoT SDK from Espressif Systems. This component is only partially -open source, some libraries provided as binary blobs. - -http://bbs.espressif.com/viewforum.php?f=5 - -OpenSource components of SDK are based on: - -lwIP, http://savannah.nongnu.org/projects/lwip/ -Contiki, http://www.contiki-os.org/ -axTLS, http://axtls.sourceforge.net/ -wpa_supplicant, http://w1.fi/wpa_supplicant/ (source withheld by Espressif) - - -Building -======== - -To build standalone SDK with toolchain, you need GNU/POSIX system (Linux, -BSD, MacOSX, Windows with Cygwin) with standard GNU development tools -installed, like gcc, binutils, flex, bison, etc. For Ubuntu 14.04 -install: - -sudo apt-get install make unrar autoconf automake libtool gcc g++ gperf \ - flex bison texinfo gawk ncurses-dev libexpat-dev python sed - -For other Debian/Ubuntu versions, dependencies may be somewhat different. -E.g., you may need to install libtool-bin, etc. - -The project can be build in two modes: - -1. Where OpenSource toolchain and tools kept separate from vendor IoT SDK -containing binary blobs. That makes licensing more clear, and facilitates -upgrades to new vendor SDK releases. - -2. Completely standalone ESP8266 SDK with vendor SDK files merged with -toolchain. This mode makes it easier to build software (no additinal --I and -L flags are needed), but redistributability of this build is -unclear and upgrade to newer vendor IoT SDK release is complicated. -This mode is default for local builds. Note that if you want to -redistribute binary toolchain built with this mode, your should: -1) make it clear to your users that the release is bound to particular -vendor IoT SDK and provide instructions how to upgrade to newer vendor -IoT SDK releases; 2) abide by licensing terms of the vendor IoT SDK. - -To build separated SDK: - -make STANDALONE=n - -To build standalone SDK: - -make STANDALONE=y - -This will download all necessary components and compile them. Once done, -the toolchain (with Xtensa HAL library) will be available in xtensa-lx106-elf/ -directory. Add its bin/ subdirectory to PATH to execute "xtensa-lx106-elf-gcc" -and other tools. - -ESP8266 SDK will be installed in sdk/. If you chose non-standalone SDK, to use it, -run the compiler with corresponding include and lib dir flags: - -xtensa-lx106-elf-gcc -I$(THISDIR)/sdk/include -L$(THISDIR)/sdk/lib - -Extra -I and -L flags are not needed for standalone SDK. - - -Pulling updates -=============== -The project is updated from time to time, to get the updates and prepare to -build new SDK: - -make clean -git pull -git submodule update - -If you don't issue "make clean" (which causes toolchain and SDK to be rebuilt -from scratch on next "make"), you risk getting broken/inconsistent result. - - -Additional configuration -======================== - -You can build statically linked toolchain by uncommenting -CT_STATIC_TOOLCHAIN=y option in crosstool-config-overrides -file. More fine-tunable options may be available in that -file and/or Makefile. diff --git a/README.md b/README.md new file mode 100644 index 0000000..58cc544 --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +esp-open-sdk +------------ + +This repository provides the integration scripts to build a complete +standalone SDK (with toolchain) for software development with the +Espressif ESP8266 and ESP8266EX chips. + +The complete SDK consists of: + +1. Xtensa lx106 architecture toolchain (100% OpenSource), based on + following projects: + * https://github.com/jcmvbkbc/crosstool-NG + * https://github.com/jcmvbkbc/gcc-xtensa + * https://github.com/jcmvbkbc/newlib-xtensa + * https://github.com/tommie/lx106-hal + +The source code above originates from work done directly by Tensilica Inc., +Cadence Design Systems, Inc, and/or their contractors. + +2. ESP8266 IoT SDK from Espressif Systems. This component is only + partially open source, (some libraries are provided as binary blobs). + * http://bbs.espressif.com/viewforum.php?f=5 + +OpenSource components of the SDK are based on: +* lwIP, http://savannah.nongnu.org/projects/lwip/ +* Contiki, http://www.contiki-os.org/ +* axTLS, http://axtls.sourceforge.net/ +* wpa_supplicant, http://w1.fi/wpa_supplicant/ (source withheld by Espressif) + +Building +======== + +To build the standalone SDK and toolchain, you need a GNU/POSIX system +(Linux, BSD, MacOSX, Windows with Cygwin) with the standard GNU development +tools installed: gcc, binutils, flex, bison, etc. For Ubuntu 14.04 +run: + +``` +$ sudo apt-get install make unrar autoconf automake libtool gcc g++ gperf \ + flex bison texinfo gawk ncurses-dev libexpat-dev python sed +``` + +For other Debian/Ubuntu versions, dependencies may be somewhat different. +E.g. you may need to install libtool-bin, etc. + +The project can be built in two modes: + +1. Where the toolchain and tools are kept separate from the vendor IoT SDK + which contains binary blobs. This makes licensing more clear, and helps + facilitate upgrades to vendor SDK releases. + +2. A completely standalone ESP8266 SDK with the vendor SDK files merged + into the toolchain. This mode makes it easier to build software (no + additinal `-I` and `-L` flags are needed), but redistributability of + this build is unclear and upgrades to newer vendor IoT SDK releases are + complicated. This mode is default for local builds. Note that if you + want to redistribute the binary toolchain built with this mode, you + should: + + 1. Make it clear to your users that the release is bound to a + particular vendor IoT SDK and provide instructions how to upgrade + to a newer vendor IoT SDK releases. + 2. Abide by licensing terms of the vendor IoT SDK. + +To build the separated SDK: + +``` +$ make STANDALONE=n +``` + +To build the standalone SDK: + +``` +$ make STANDALONE=y +``` + +This will download all necessary components and compile them. Once done, +the toolchain (with the Xtensa HAL library) will be available in the +`xtensa-lx106-elf/` directory. Add its `bin/` subdirectory to your +`$PATH` to execute `xtensa-lx106-elf-gcc` and other tools. + +ESP8266 SDK will be installed in `sdk/`. If you chose the non-standalone +SDK, run the compiler with the corresponding include and lib dir flags: + +``` +$ xtensa-lx106-elf-gcc -I$(THISDIR)/sdk/include -L$(THISDIR)/sdk/lib +``` + +The extra -I and -L flags are not needed when using the standalone SDK. + +Pulling updates +=============== +The project is updated from time to time, to update and prepare to +build a new SDK, run: + +``` +$ make clean +$ git pull +$ git submodule update +``` + +If you don't issue `make clean` (which causes toolchain and SDK to be +rebuilt from scratch on next `make`), you risk getting broken/inconsistent +results. + +Additional configuration +======================== + +You can build a statically linked toolchain by uncommenting +`CT_STATIC_TOOLCHAIN=y` in the file `crosstool-config-overrides`. More +fine-tunable options may be available in that file and/or Makefile.