From 9ec0e1545d3c00dfbf920f195b7c6f3b8aed8260 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 19 Aug 2016 14:30:39 +0800 Subject: [PATCH] Standardise remaining uses of SDK to ESP-IDF --- Kconfig | 2 +- README.buildenv | 16 ++++++++-------- components/bootloader/Makefile.projbuild | 2 +- components/bootloader/src/main/Makefile | 2 +- components/freertos/Makefile | 5 ----- components/lwip/Makefile | 5 ----- components/nvs_flash/Makefile | 5 ----- components/nvs_flash/include/nvs.h | 6 +++--- components/tcpip_adapter/Makefile | 5 ----- docs/eclipse-setup.rst | 6 +++--- docs/windows-setup.rst | 16 ++++++++-------- make/component.mk | 9 +++++---- tools/windows/windows_install_prerequisites.sh | 6 +++--- 13 files changed, 33 insertions(+), 52 deletions(-) diff --git a/Kconfig b/Kconfig index f3cfbef101..58ce77b2b5 100644 --- a/Kconfig +++ b/Kconfig @@ -2,7 +2,7 @@ # For a description of the syntax of this configuration file, # see kconfig/kconfig-language.txt. # -mainmenu "Espressif ESP32 SDK Configuration" +mainmenu "Espressif IoT Development Framework Configuration" menu "SDK tool configuration" diff --git a/README.buildenv b/README.buildenv index 249268c480..e87393f421 100644 --- a/README.buildenv +++ b/README.buildenv @@ -13,15 +13,15 @@ have: ESP-IDF makes these components explicit and configurable. To do that, when a project is compiled, the build environment will look up all the components in the -SDK directories, the project directories and optionally custom other component +ESP-IDF directories, the project directories and optionally custom other component directories. It then allows the user to configure compile-time options using -a friendly text-based menu system to customize the SDK as well as other components +a friendly text-based menu system to customize the ESP-IDF as well as other components to the requirements of the project. After the components are customized, the build process will compile everything into an output file, which can then be uploaded into a board in a way that can also be defined by components. A project in this sense is defined as a directory under which all the files required -to build it live, excluding the SDK files and the toolchain. A simple project +to build it live, excluding the ESP-IDF files and the toolchain. A simple project tree looks like this: - myProject/ - build/ @@ -55,7 +55,7 @@ PROJECT_NAME: Mandatory. Name for the project BUILD_DIR_BASE: Set the directory where all objects/libraries/binaries end up in. Defaults to $(PROJECT_PATH)/build COMPONENT_DIRS: Search path for components. Defaults to the component/ directories - in the SDK path and the project path. + in the ESP-IDF path and the project path. COMPONENTS: A list of component names. Defaults to all the component found in the COMPONENT_DIRS directory EXTRA_COMPONENT_DIRS: Defaults to unset. Use this to add directories to the default @@ -97,7 +97,7 @@ These variables are already set early on in the Makefile and the values in it wi be usable in component or project Makefiles: CC, LD, AR, OBJCOPY: Xtensa gcc tools HOSTCC, HOSTLD etc: Host gcc tools -LDFLAGS, CFLAGS: Set to usable values as defined in SDK Makefile +LDFLAGS, CFLAGS: Set to usable values as defined in ESP-IDF Makefile PROJECT_NAME: Name of the project, as set in project makefile PROJECT_PATH: Path to the root of the project folder COMPONENTS: Name of the components to be included @@ -139,7 +139,7 @@ options not in the 'components' submenu, create a Kconfig.projbuild and it will be included in the main menu of menuconfig. Take good care when (re)defining stuff here: because it's included with all the other .projbuild files, it's possible to overwrite variables or re-declare -targets defined in the SDK makefile/Kconfig and other .projbuild files +targets defined in the ESP-IDF makefile/Kconfig and other .projbuild files WRITING COMPONENT MAKEFILES @@ -154,7 +154,7 @@ One of the things that most components will have is a Makefile, containing instructions on how to build the component. Because the build environment tries to set reasonable defaults that will work most of the time, a component Makefile can be pretty small. At the absolute -minimum, it will just include the SDK component makefile, which adds +minimum, it will just include the ESP-IDF component makefile, which adds component functionality: ----8<---- @@ -228,7 +228,7 @@ why it is added to the COMPONENT_EXTRA_CLEAN variable. This will work just fine, but there's one last cosmetic improvement that -can be done. The SDK make system tries to make the make process somewhat +can be done. The make system tries to make the make process somewhat easier on the eyes by hiding the commands (unless you run make with the V=1 switch) and this does not do that yet. Here's an improved version that will output in the same style as the rest of the make process: diff --git a/components/bootloader/Makefile.projbuild b/components/bootloader/Makefile.projbuild index 63c77ed72f..073112febd 100644 --- a/components/bootloader/Makefile.projbuild +++ b/components/bootloader/Makefile.projbuild @@ -6,7 +6,7 @@ # the upper projects build directory. This Makefile.projbuild provides the # glue to build the bootloader project from the original project. It # basically runs Make in the src/ directory but it needs to zero some variables -# the SDK makefile exports first, to not let them interfere. +# the ESP-IDF project.mk makefile exports first, to not let them interfere. # BOOTLOADER_COMPONENT_PATH := $(COMPONENT_PATH) diff --git a/components/bootloader/src/main/Makefile b/components/bootloader/src/main/Makefile index 2f07b6972e..5330efe867 100644 --- a/components/bootloader/src/main/Makefile +++ b/components/bootloader/src/main/Makefile @@ -4,7 +4,7 @@ # This Makefile should, at the very least, just include $(SDK_PATH)/make/component.mk. By default, # this will take the sources in the src/ directory, compile them and link them into # lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable, -# please read the SDK documents if you need to do this. +# please read the esp-idf build system document if you need to do this. # COMPONENT_ADD_LDFLAGS := -L $(abspath .) -lmain -T eagle.bootloader.ld -T $(SDK_PATH)/components/esp32/ld/eagle.fpga32.rom.addr.v7.ld diff --git a/components/freertos/Makefile b/components/freertos/Makefile index b00176dd1d..912148d232 100644 --- a/components/freertos/Makefile +++ b/components/freertos/Makefile @@ -1,11 +1,6 @@ # # Component Makefile # -# This Makefile should, at the very least, just include $(SDK_PATH)/make/component.mk. By default, -# this will take the sources in this directory, compile them and link them into -# lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable, -# please read the SDK documents if you need to do this. -# COMPONENT_ADD_INCLUDEDIRS := include COMPONENT_PRIV_INCLUDEDIRS := include/freertos diff --git a/components/lwip/Makefile b/components/lwip/Makefile index b2de346b21..018d3af793 100755 --- a/components/lwip/Makefile +++ b/components/lwip/Makefile @@ -1,11 +1,6 @@ # # Component Makefile # -# This Makefile should, at the very least, just include $(SDK_PATH)/make/component.mk. By default, -# this will take the sources in this directory, compile them and link them into -# lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable, -# please read the SDK documents if you need to do this. -# COMPONENT_ADD_INCLUDEDIRS := include/lwip include/lwip/port diff --git a/components/nvs_flash/Makefile b/components/nvs_flash/Makefile index 32ee644926..8eb3654887 100755 --- a/components/nvs_flash/Makefile +++ b/components/nvs_flash/Makefile @@ -1,11 +1,6 @@ # # Component Makefile # -# This Makefile should, at the very least, just include $(SDK_PATH)/Makefile. By default, -# this will take the sources in this directory, compile them and link them into -# lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable, -# please read the SDK documents if you need to do this. -# COMPONENT_ADD_INCLUDEDIRS := include diff --git a/components/nvs_flash/include/nvs.h b/components/nvs_flash/include/nvs.h index 084fa70545..2d0f27544c 100644 --- a/components/nvs_flash/include/nvs.h +++ b/components/nvs_flash/include/nvs.h @@ -49,9 +49,9 @@ typedef enum { /** * @brief Open non-volatile storage with a given namespace * - * Multiple SDK and application modules can store their key-value pairs in the - * NVS module. In order to reduce possible conflicts on key names, each module - * can use its own namespace. + * Multiple internal ESP-IDF and third party application modules can store + * their key-value pairs in the NVS module. In order to reduce possible + * conflicts on key names, each module can use its own namespace. * * @param[in] name Namespace name. Maximal length is determined by the * underlying implementation, but is guaranteed to be diff --git a/components/tcpip_adapter/Makefile b/components/tcpip_adapter/Makefile index 6fd5e726d2..c08a03896b 100755 --- a/components/tcpip_adapter/Makefile +++ b/components/tcpip_adapter/Makefile @@ -1,11 +1,6 @@ # # Component Makefile # -# This Makefile should, at the very least, just include $(SDK_PATH)/make/component.mk. By default, -# this will take the sources in this directory, compile them and link them into -# lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable, -# please read the SDK documents if you need to do this. -# EXTRA_CFLAGS := -DLWIP_ESP8266 diff --git a/docs/eclipse-setup.rst b/docs/eclipse-setup.rst index bbfd2ee26c..4345569f90 100644 --- a/docs/eclipse-setup.rst +++ b/docs/eclipse-setup.rst @@ -3,7 +3,7 @@ Installing Eclipse IDE The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects. -* Start by installing the SDK for your platform (see Windows, OS X, Linux). +* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux). * Download the Eclipse Installer for your platform from eclipse.org_. @@ -23,7 +23,7 @@ Import New Project * In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. -* On the next page, enter "Existing Code Location" to be the directory of your SDK project. Don't specify the path to the SDK itself. +* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself. * On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. @@ -35,7 +35,7 @@ Project Properties * Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``V`` and value ``1``. -* Click "Add..." again, and enter name ``SDK_PATH``. The value should be the full path where the ESP32 SDK is installed. *Windows users: Use forward-slashes not backslashes for this path, ie C:/Users/MyUser/Development/SDK*. +* Click "Add..." again, and enter name ``SDK_PATH``. The value should be the full path where ESP-IDF is installed. *Windows users: Use forward-slashes not backslashes for this path, ie C:/Users/MyUser/Development/esp-idf*. *Windows users only, follow these two additional steps:* diff --git a/docs/windows-setup.rst b/docs/windows-setup.rst index 30acca82a6..a8a567b80b 100644 --- a/docs/windows-setup.rst +++ b/docs/windows-setup.rst @@ -20,15 +20,15 @@ As an alternative to getting a pre-prepared environment, you can set up the envi * Run through the installer steps, and accept the "Run MSYS2 now" option at the end. A window will open with a MSYS2 terminal. -* The SDK repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't downloaded the SDK yet, that's OK - you can just `download that one file in Raw format from here `_. Save it somewhere on your computer. +* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't downloaded the ESP-IDF yet, that's OK - you can just `download that one file in Raw format from here `_. Save it somewhere on your computer. * Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does. * If you use the 201602 MSYS2 installer, the first time you run ``windows_install_prerequisites.sh`` it will update the MSYS2 core system. At the end of this update, you will be prompted to close the MSYS2 terminal and re-open. When you re-open after the update, re-run ``windows_install_prerequisites.sh``. The next version of MSYS2 (after 201602) will not need this interim step. -* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP32 SDK support, and the ESP32 toolchain. +* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain. -Note: You may encounter a bug where svchost.exe uses 100% CPU in Windows after setup is finished, resulting in the SDK building very slowly. Terminating svchost.exe or restarting Windows will solve this problem. +Note: You may encounter a bug where svchost.exe uses 100% CPU in Windows after setup is finished, resulting in the ESP-IDF building very slowly. Terminating svchost.exe or restarting Windows will solve this problem. Another Alternative Step 1: Just download a toolchain ===================================================== @@ -41,8 +41,8 @@ If you followed one of the above options for Step 1, you won't need this downloa Important: Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). -Step 2: Getting the SDK from github -=================================== +Step 2: Getting the esp-idf repository from github +================================================== Open an MSYS2 terminal window by running ``C:\msys32\msys2_shell.cmd``. The environment in this window is a bash shell. @@ -53,11 +53,11 @@ If you'd rather use a Windows UI tool to manage your git repositories, this is a Step 3: Starting a project ========================== -The SDK by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP32 SDK. +ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory on your computer. The easiest way to start a project is to download the Getting Started project from github_. -The process is the same as for checking out the SDK from github. Change to the parent directory and run ``git clone https://github.com/espressif/esp-idf-template.git``. +The process is the same as for checking out the ESP-IDF from github. Change to the parent directory and run ``git clone https://github.com/espressif/esp-idf-template.git``. Step 4: Configuring the project =============================== @@ -66,7 +66,7 @@ Open an MSYS2 terminal window by running ``C:\msys32\msys2_shell.cmd``. The envi Type a command like this to set the path to ESP-IDF directory: ``export SDK_PATH="C:/path/to/esp-idf"`` (note the forward-slashes not back-slashes for the path). If you don't want to run this command every time you open an MSYS2 window, create a new file in ``C:/msys32/etc/profile.d/`` and paste this line in - then it will be run each time you open an MYS2 terminal. -Use ``cd`` to change to the project directory (not the SDK directory.) Type ``make menuconfig`` to configure your project, then ``make`` to build it, ``make clean`` to remove built files, and ``make flash`` to flash (use the menuconfig to set the serial port for flashing.) +Use ``cd`` to change to the project directory (not the ESP-IDF directory.) Type ``make menuconfig`` to configure your project, then ``make`` to build it, ``make clean`` to remove built files, and ``make flash`` to flash (use the menuconfig to set the serial port for flashing.) If you'd like to use the Eclipse IDE instead of running ``make``, check out the Eclipse setup guide in this directory. diff --git a/make/component.mk b/make/component.mk index 3ee16166da..e062c8e8d8 100644 --- a/make/component.mk +++ b/make/component.mk @@ -1,4 +1,5 @@ -# Main SDK Makefile +# Component common makefile +# # This Makefile gets included in the Makefile of all the components to set the correct include paths etc. # PWD is the build directory of the component and the top Makefile is the one in the # component source dir. @@ -10,12 +11,12 @@ # # This Makefile requires the environment variable SDK_PATH to be set -# to the directory where the SDK (containing the make directory with -# this file) is located +# to the top-level directory where ESP-IDF is located (the directory +# containing this 'make' directory). # ifeq ("$(PROJECT_PATH)","") -$(error Make was invoked from $(CURDIR). However please do not run make from the sdk or a component directory; invoke make from the project directory. See SDK README for details.) +$(error Make was invoked from $(CURDIR). However please do not run make from the sdk or a component directory; invoke make from the project directory. See the ESP-IDF README for details.) endif # Find the path to the component diff --git a/tools/windows/windows_install_prerequisites.sh b/tools/windows/windows_install_prerequisites.sh index 2d7f8d0a53..55166a7b23 100755 --- a/tools/windows/windows_install_prerequisites.sh +++ b/tools/windows/windows_install_prerequisites.sh @@ -1,6 +1,6 @@ #!/bin/bash # -# Setup script to configure an MSYS2 environment for ESP32 SDK. +# Setup script to configure an MSYS2 environment for Espressif IoT Development Framework (ESP-IDF). # See docs/windows-setup.rst for details. if [ "$OSTYPE" != "msys" ]; then @@ -47,12 +47,12 @@ pacman --noconfirm -R unzip pacman --noconfirm -Scc echo "************************************************" -echo "MSYS2 environment is now ready to use ESP32 SDK." +echo "MSYS2 environment is now ready to use ESP-IDF." echo "Run 'source /etc/profile' to add the toolchain to" echo "your path. Execute 'msys_shell.cmd' to launch an" echo "MSYS terminal." echo -echo "Once ESP32 SDK is downloaded/checked out, set the" +echo "Once ESP-IDF is downloaded/checked out, set the" echo "environment variable SDK_PATH in /etc/profile to" echo "point to the directory." echo "************************************************"