Document CMake build system

BUILDING

@@ -0,0 +1,107 @@
+Building lwIP
+=============
+
+lwIP uses a CMake based build system.
+
+The CMake files in this project are designed to
+be included into your own CMake files. They are
+mainly variable definitions containing a list of
+source files and predefined static libraries to
+be linked against application code.
+
+1) lwIP sources:
+   src/Filelists.cmake provides file lists containing
+   the lwIP core library.
+   The file also contains two static libraries, lwipcore
+   and lwipallapps, where you can link your app against.
+   This is the file that is useful to all lwIP users.
+
+2) Example applications:
+   contrib/Filelists.cmake provides several file lists
+   containing the example applications.
+   The file also contains several static libraries
+   for these example apps.
+   This file is only useful for you, if you can use one
+   of the examples in your application, which is normally
+   not the case.
+
+3) OS/platform port:
+   Usually the OS port needs to be provided by the user.
+   If a port to Linux, Windows or MacOS is useful for
+   you, you can use
+   contrib/ports/{win32, unix}/Filelists.cmake
+   that contains file lists and libraries for
+   these operating systems.
+
+VARIABLES
+=========
+In all cases, you need to provide two variables.
+
+"LWIP_DIR" pointing to the lwIP directory
+Example:
+set(LWIP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/lwip)
+
+"LWIP_INCLUDE_DIRS" that contains the include base paths
+- for lwIP itself (${LWIP_DIR}/src/include)
+- for lwIP contrib if you use it (${LWIP_CONTRIB_DIR}/)
+- to a directory for an lwIP OS port
+- to a directory containing lwipopts.h
+
+Example:
+set (LWIP_INCLUDE_DIRS
+    "${LWIP_DIR}/src/include"
+    "${LWIP_DIR}/contrib"
+    "${LWIP_DIR}/contrib/ports/unix/port/include"
+    "${LWIP_DIR}/contrib/examples/example_app"
+)
+
+Putting it all together
+=======================
+To get a working application, your CMake system
+needs to provide the variables described above, e.g.
+set (LWIP_DIR <path to lwip sources>)
+set (LWIP_INCLUDE_DIRS
+    "${LWIP_DIR}/src/include"
+    "${LWIP_DIR}/contrib"
+    "<path to my port>/include"
+    "<path to lwipopts.h>"
+)
+
+You may add some defines:
+set (LWIP_DEFINITIONS LWIP_DEBUG=1)
+
+Then include the filelists you need:
+include(${LWIP_DIR}/src/Filelists.cmake)
+include(${LWIP_DIR}/contrib/Filelists.cmake)
+
+Then, declare you executable:
+add_executable(my_app <my source files> <my lwip port files>)
+
+Add lwIP include dirs to your app:
+target_include_directories(my_app PRIVATE ${LWIP_INCLUDE_DIRS})
+
+Link your app against the lwIP libs from the filelists you need:
+target_link_libraries(my_app lwipcontribapps lwipallapps lwipcore)
+
+Working example
+===============
+Working build examples can be found in the
+contrib/ports/{win32, unix}/example_app
+subdirectory.
+To use them, create a build directory and call cmake with
+the lwIP root dir:
+
+- mkdir build
+- cd build
+- cmake <path to lwip dir>
+- cmake --build
+
+The CMakeLists.txt will autoselect the correct port
+for your system.
+
+Makefile based build system
+===========================
+lwIP also maintains file lists for Makefile-based
+build systems. Look for Filelists.mk files
+in the source tree. We try to maintain them,
+but lwIP's mainly focused build system is CMake.