docs: whitespace and add existing READMEs to doxygen list

This commit is contained in:
Ben Delarre 2017-11-12 14:37:17 +08:00 committed by Andy Green
parent dcf5a83ee4
commit 3160605462
3 changed files with 88 additions and 84 deletions

View file

@ -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.

View file

@ -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

View file

@ -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 \