diff --git a/READMEs/README.build.md b/READMEs/README.build.md
index bfd29029a07690ca27e359172b634921c8eddc4c..b92c557fb74959e2477a2339ca527a754a7dfb5a 100644
--- a/READMEs/README.build.md
+++ b/READMEs/README.build.md
@@ -50,7 +50,7 @@ see below on how to toggle compile options.
4. Finally you can build using the generated Makefile:
```
- $ make && sudo make install
+ $ make && sudo make install
```
**NOTE**: The `build/`` directory can have any name and be located anywhere
on your filesystem, and that the argument `..` given to cmake is simply
@@ -62,14 +62,14 @@ A common option you may want to give is to set the install path, same
as --prefix= with autotools. It defaults to /usr/local.
You can do this by, eg
```
- $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr .
+ $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr .
```
**NOTE3**:
On machines that want libraries in lib64, you can also add the
following to the cmake line
```
- -DLIB_SUFFIX=64
+ -DLIB_SUFFIX=64
```
**NOTE4**:
@@ -77,20 +77,20 @@ If you are building against a non-distro OpenSSL (eg, in order to get
access to ALPN support only in newer OpenSSL versions) the nice way to
express that in one cmake command is eg,
```
- $ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
- -DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
- -DLWS_WITH_HTTP2=1
+ $ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
+ -DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
+ -DLWS_WITH_HTTP2=1
```
When you run the test apps using non-distro SSL, you have to force them
to use your libs, not the distro ones
```
- $ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
+ $ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
```
To get it to build on latest openssl (2016-04-10) it needed this approach
```
- cmake .. -DLWS_WITH_HTTP2=1 -DLWS_OPENSSL_INCLUDE_DIRS=/usr/local/include/openssl -DLWS_OPENSSL_LIBRARIES="/usr/local/lib64/libssl.so;/usr/local/lib64/libcrypto.so"
+ cmake .. -DLWS_WITH_HTTP2=1 -DLWS_OPENSSL_INCLUDE_DIRS=/usr/local/include/openssl -DLWS_OPENSSL_LIBRARIES="/usr/local/lib64/libssl.so;/usr/local/lib64/libcrypto.so"
```
Mac users have reported
@@ -105,7 +105,7 @@ worked for them when using "homebrew" OpenSSL
To build with debug info and _DEBUG for lower priority debug messages
compiled in, use
```
- $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
+ $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
```
**NOTE6**
@@ -113,13 +113,13 @@ To build on Solaris the linker needs to be informed to use lib socket
and libnsl, and only builds in 64bit mode.
```bash
- $ cmake .. -DCMAKE_C_FLAGS=-m64 -DCMAKE_EXE_LINKER_FLAGS="-lsocket -lnsl"
+ $ cmake .. -DCMAKE_C_FLAGS=-m64 -DCMAKE_EXE_LINKER_FLAGS="-lsocket -lnsl"
```
4. Finally you can build using the generated Makefile:
```bash
- $ make
+ $ make
```
@section lcap Linux Capabilities
@@ -153,14 +153,14 @@ deleting build/CMakeCache.txt may be enough.
**NOTE2**:
Be sure that OPENSSL_CONF environment variable is defined and points at
<OpenSSL install location>\bin\openssl.cfg
-
+
3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
```
- cd <path to src>
- md build
- cd build
- cmake -G "Visual Studio 10" ..
+ cd <path to src>
+ md build
+ cd build
+ cmake -G "Visual Studio 10" ..
```
(**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
@@ -191,25 +191,25 @@ deleting build/CMakeCache.txt may be enough.
a) If still necessary, sdd the following lines to C:\MinGW\include\winsock2.h:
```
- #if(_WIN32_WINNT >= 0x0600)
+ #if(_WIN32_WINNT >= 0x0600)
- typedef struct pollfd {
+ typedef struct pollfd {
- SOCKET fd;
- SHORT events;
- SHORT revents;
+ SOCKET fd;
+ SHORT events;
+ SHORT revents;
- } WSAPOLLFD, *PWSAPOLLFD, FAR *LPWSAPOLLFD;
+ } WSAPOLLFD, *PWSAPOLLFD, FAR *LPWSAPOLLFD;
- WINSOCK_API_LINKAGE int WSAAPI WSAPoll(LPWSAPOLLFD fdArray, ULONG fds, INT timeout);
+ WINSOCK_API_LINKAGE int WSAAPI WSAPoll(LPWSAPOLLFD fdArray, ULONG fds, INT timeout);
- #endif // (_WIN32_WINNT >= 0x0600)
+ #endif // (_WIN32_WINNT >= 0x0600)
```
Update crtdefs.h line 47 to say:
```
- typedef __int64 ssize_t;
+ typedef __int64 ssize_t;
```
b) Create C:\MinGW\include\mstcpip.h and copy and paste the content from following link into it:
@@ -228,10 +228,10 @@ deleting build/CMakeCache.txt may be enough.
5. Generate the build files (default is Make files) using MSYS shell:
```
- $ cd /drive/path/to/src
- $ mkdir build
- $ cd build
- $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW ..
+ $ cd /drive/path/to/src
+ $ mkdir build
+ $ cd build
+ $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW ..
```
(**NOTE**: The `build/`` directory can have any name and be located anywhere
on your filesystem, and that the argument `..` given to cmake is simply
@@ -242,13 +242,13 @@ deleting build/CMakeCache.txt may be enough.
To generate build files allowing to create libwebsockets binaries with debug information
set the CMAKE_BUILD_TYPE flag to DEBUG:
```
- $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW -DCMAKE_BUILD_TYPE=DEBUG ..
+ $ cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/MinGW -DCMAKE_BUILD_TYPE=DEBUG ..
```
6. Finally you can build using the generated Makefile and get the results deployed into your MinGW installation:
```
- $ make
- $ make install
+ $ make
+ $ make install
```
@section ssllib Choosing Your TLS Poison
@@ -296,25 +296,25 @@ or do it via the command line.
To list available options (omit the H if you don't want the help text):
- cmake -LH ..
+ cmake -LH ..
Then to set an option and build (for example turn off SSL support):
- cmake -DLWS_WITH_SSL=0 ..
+ cmake -DLWS_WITH_SSL=0 ..
or
- cmake -DLWS_WITH_SSL:BOOL=OFF ..
+ cmake -DLWS_WITH_SSL:BOOL=OFF ..
@subsection cmcoug Unix GUI
If you have a curses-enabled build you simply type:
(not all packages include this, my debian install does not for example).
- ccmake
+ ccmake
@subsection cmcowg Windows GUI
On windows CMake comes with a gui application:
- Start -> Programs -> CMake -> CMake (cmake-gui)
+ Start -> Programs -> CMake -> CMake (cmake-gui)
@section wolf wolfSSL/CyaSSL replacement for OpenSSL
@@ -331,9 +331,9 @@ this to work.
@section wolf1 Compiling libwebsockets with wolfSSL
```
- cmake .. -DLWS_WITH_WOLFSSL=1 \
- -DLWS_WOLFSSL_INCLUDE_DIRS=/path/to/wolfssl \
- -DLWS_WOLFSSL_LIBRARIES=/path/to/wolfssl/wolfssl.a ..
+ cmake .. -DLWS_WITH_WOLFSSL=1 \
+ -DLWS_WOLFSSL_INCLUDE_DIRS=/path/to/wolfssl \
+ -DLWS_WOLFSSL_LIBRARIES=/path/to/wolfssl/wolfssl.a ..
```
**NOTE**: On windows use the .lib file extension for `LWS_WOLFSSL_LIBRARIES` instead.
@@ -341,33 +341,33 @@ this to work.
@section cya Compiling libwebsockets with CyaSSL
```
- cmake .. -DLWS_WITH_CYASSL=1 \
- -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
- -DLWS_CYASSL_LIBRARIES=/path/to/wolfssl/cyassl.a ..
+ cmake .. -DLWS_WITH_CYASSL=1 \
+ -DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
+ -DLWS_CYASSL_LIBRARIES=/path/to/wolfssl/cyassl.a ..
```
**NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIBRARIES` instead.
@section esp32 Building for ESP32
-Step 1, get ESP-IDF with lws integrated as a component
+Building for ESP32 requires the ESP-IDF framework. It can be built under Linux, OSX or Windows (MSYS2).
+1. Install ESP-IDF, follow the getting started guide here - http://esp-idf.readthedocs.io/en/latest/get-started/
+2. Set ESP-IDF to last known working version (assuming ESP-IDF is in `~/esp/esp-idf`) :
```
- $ git clone --int --recursive https://github.com/lws-team/lws-esp-idf
+ cd ~/esp/esp-idf
+ git checkout 0c50b65a34cd6b3954f7435193411a88adb49cb0
+ git submodule update --recursive
```
-
-Step 2: Get Application including the test plugins
-
+3. Add `libwebsockets` as a submodule in the `components` folder of your ESP-IDF project:
```
- $ git clone https://github.com/lws-team/lws-esp32
+ git submodule add https://github.com/warmcat/libwebsockets.git components/libwebsockets
```
-
-Set your IDF_PATH to point to the esp-idf you downloaded in 1)
-
-There's docs for how to build the lws-esp32 test app and reproduce it in the README.md here
-
-https://github.com/lws-team/lws-esp32/blob/master/README.md
-
+4. If on Windows (MSYS2) you will need to install CMake in the MSYS2 environment:
+```
+ pacman -S mingw-w64-i686-cmake
+```
+If you're on Linux or OSX ensure CMake version is at least 3.7.
@section extplugins Building plugins outside of lws itself
@@ -375,11 +375,11 @@ The directory ./plugin-standalone/ shows how easy it is to create plugins
outside of lws itself. First build lws itself with -DLWS_WITH_PLUGINS,
then use the same flow to build the standalone plugin
```
- cd ./plugin-standalone
- mkdir build
- cd build
- cmake ..
- make && sudo make install
+ cd ./plugin-standalone
+ mkdir build
+ cd build
+ cmake ..
+ make && sudo make install
```
if you changed the default plugin directory when you built lws, you must
@@ -389,12 +389,12 @@ also give the same arguments to cmake here (eg,
Otherwise if you run lwsws or libwebsockets-test-server-v2.0, it will now
find the additional plugin "libprotocol_example_standalone.so"
```
- lwsts[21257]: Plugins:
- lwsts[21257]: libprotocol_dumb_increment.so
- lwsts[21257]: libprotocol_example_standalone.so
- lwsts[21257]: libprotocol_lws_mirror.so
- lwsts[21257]: libprotocol_lws_server_status.so
- lwsts[21257]: libprotocol_lws_status.so
+ lwsts[21257]: Plugins:
+ lwsts[21257]: libprotocol_dumb_increment.so
+ lwsts[21257]: libprotocol_example_standalone.so
+ lwsts[21257]: libprotocol_lws_mirror.so
+ lwsts[21257]: libprotocol_lws_server_status.so
+ lwsts[21257]: libprotocol_lws_status.so
```
If you have multiple vhosts, you must enable plugins at the vhost
additionally, discovered plugins are not enabled automatically for security
@@ -410,9 +410,9 @@ ALPN. At the time of writing, recent distros have started upgrading to OpenSSL
1.1+ that supports this already. You'll know it's right by seeing
```
- lwsts[4752]: Compiled with OpenSSL support
- lwsts[4752]: Using SSL mode
- lwsts[4752]: HTTP2 / ALPN enabled
+ lwsts[4752]: Compiled with OpenSSL support
+ lwsts[4752]: Using SSL mode
+ lwsts[4752]: HTTP2 / ALPN enabled
```
at lws startup.
@@ -422,7 +422,7 @@ with the test server running in -s / ssl mode.
For testing with nghttp client:
```
- $ nghttp -nvas https://localhost:7681/test.html
+ $ nghttp -nvas https://localhost:7681/test.html
```
Testing with h2spec (https://github.com/summerwind/h2spec)
@@ -461,21 +461,21 @@ you can use as a starting point.
The commandline to configure for cross with this would look like
```
- $ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr/lib/my-cross-root \
- -DCMAKE_TOOLCHAIN_FILE=../contrib/cross-arm-linux-gnueabihf.cmake \
- -DLWS_WITHOUT_EXTENSIONS=1 -DLWS_WITH_SSL=0 \
- -DLWS_WITH_ZIP_FOPS=0 -DLWS_WITH_ZLIB=0
+ $ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr/lib/my-cross-root \
+ -DCMAKE_TOOLCHAIN_FILE=../contrib/cross-arm-linux-gnueabihf.cmake \
+ -DLWS_WITHOUT_EXTENSIONS=1 -DLWS_WITH_SSL=0 \
+ -DLWS_WITH_ZIP_FOPS=0 -DLWS_WITH_ZLIB=0
```
The example shows how to build with no external cross lib dependencies, you
need to provide the cross libraries otherwise.
**NOTE**: start from an EMPTY build directory if you had a non-cross build in there
- before the settings will be cached and your changes ignored.
- Delete `build/CMakeCache.txt` at least before trying a new cmake config
- to ensure you are really building the options you think you are.
+ before the settings will be cached and your changes ignored.
+ Delete `build/CMakeCache.txt` at least before trying a new cmake config
+ to ensure you are really building the options you think you are.
Additional information on cross compilation with CMake:
- http://www.vtk.org/Wiki/CMake_Cross_Compiling
+ http://www.vtk.org/Wiki/CMake_Cross_Compiling
@section cross_example Complex Cross compiling example
@@ -648,13 +648,13 @@ server, built on ARM Cortex-A9:
Update at 8dac94d (2013-02-18)
```
- $ ./configure --without-client --without-extensions --disable-debug --without-daemonize
+ $ ./configure --without-client --without-extensions --disable-debug --without-daemonize
- Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
- Per-connection [3]: 72 bytes, +1328 during headers
+ Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
+ Per-connection [3]: 72 bytes, +1328 during headers
- .text .rodata .data .bss
- 11512 2784 288 4
+ .text .rodata .data .bss
+ 11512 2784 288 4
```
This shows the impact of the major configuration with/without options at
13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
diff --git a/READMEs/README.esp32.md b/READMEs/README.esp32.md
index 6f64891c04abc5f7dd8ad89b4dbf6bdbe49c2ca8..df792d00c621b8bcf78665a00b2c605d5ac333be 100644
--- a/READMEs/README.esp32.md
+++ b/READMEs/README.esp32.md
@@ -1,6 +1,8 @@
ESP32 Support
=============
+See \ref esp32 for details on how to build lws as a component in an ESP-IDF project.
+
Lws provides a "factory" application
https://github.com/warmcat/lws-esp32-factory
diff --git a/libwebsockets.dox b/libwebsockets.dox
index 659433bdc5fbf5e5788cf3ccc560f6f73951cda4..b1dfecc6c86e3a1bb9dd82a47c1bc15e70b60d03 100644
--- a/libwebsockets.dox
+++ b/libwebsockets.dox
@@ -108,6 +108,8 @@ INPUT = lib/libwebsockets.h \
./READMEs/README.problems.md \
./READMEs/README.lwsws.md \
./READMEs/README.coding.md \
+ ./READMEs/README.esp32.md \
+ ./READMEs/README.esp8266.md \
./READMEs/README.generic-sessions.md \
./READMEs/README.generic-table.md \
./READMEs/README.test-apps.md \