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.

CMakeLists.txt

@@ -9,8 +9,10 @@ set (LWIP_DEFINITIONS LWIP_DEBUG=1)
 
 if (${CMAKE_SYSTEM_NAME} STREQUAL Windows)
   add_subdirectory(${LWIP_DIR}/contrib/ports/win32/example_app)
-else()
+elseif(${CMAKE_SYSTEM_NAME} STREQUAL Linux OR ${CMAKE_SYSTEM_NAME} STREQUAL Darwin)
   add_subdirectory(${LWIP_DIR}/contrib/ports/unix/example_app)
+else()
+  message(WARNING "Host ${CMAKE_SYSTEM_NAME} is not supported to build example_app")
 endif()
 
 # Source package generation
@@ -24,5 +26,6 @@ set(CPACK_SOURCE_PACKAGE_FILE_NAME "lwip-${LWIP_VERSION_MAJOR}.${LWIP_VERSION_MI
 include(CPack)
 
 # Target for package generation
+include(src/Filelists.cmake)
 add_custom_target(dist COMMAND ${CMAKE_MAKE_PROGRAM} package_source)
 add_dependencies(dist lwipdocs)

contrib/ports/unix/example_app/CMakeLists.txt

@@ -2,16 +2,16 @@ include(${LWIP_DIR}/contrib/ports/CMakeCommon.cmake)
 
 set (LWIP_INCLUDE_DIRS
     "${LWIP_DIR}/src/include"
-    "${LWIP_CONTRIB_DIR}/"
+    "${LWIP_DIR}/contrib/"
-    "${LWIP_CONTRIB_DIR}/ports/unix/port/include"
+    "${LWIP_DIR}/contrib/ports/unix/port/include"
-    "${LWIP_CONTRIB_DIR}/examples/example_app"
+    "${LWIP_DIR}/contrib/examples/example_app"
 )
 
 include(${LWIP_DIR}/src/Filelists.cmake)
-include(${LWIP_CONTRIB_DIR}/Filelists.cmake)
+include(${LWIP_DIR}/contrib/Filelists.cmake)
-include(${LWIP_CONTRIB_DIR}/ports/unix/Filelists.cmake)
+include(${LWIP_DIR}/contrib/ports/unix/Filelists.cmake)
 
-add_executable(example_app ${LWIP_CONTRIB_DIR}/examples/example_app/test.c default_netif.c)
+add_executable(example_app ${LWIP_DIR}/contrib/examples/example_app/test.c default_netif.c)
 target_include_directories(example_app PRIVATE ${LWIP_INCLUDE_DIRS})
 target_compile_options(example_app PRIVATE ${LWIP_COMPILER_FLAGS})
 target_compile_definitions(example_app PRIVATE ${LWIP_DEFINITIONS} ${LWIP_MBEDTLS_DEFINITIONS})

contrib/ports/win32/example_app/CMakeLists.txt

@@ -2,16 +2,16 @@ include(${LWIP_DIR}/contrib/ports/CMakeCommon.cmake)
 
 set (LWIP_INCLUDE_DIRS
     "${LWIP_DIR}/src/include"
-    "${LWIP_CONTRIB_DIR}/"
+    "${LWIP_DIR}/contrib/"
-    "${LWIP_CONTRIB_DIR}/ports/win32/include"
+    "${LWIP_DIR}/contrib/ports/win32/include"
-    "${LWIP_CONTRIB_DIR}/examples/example_app"
+    "${LWIP_DIR}/contrib/examples/example_app"
 )
 
 include(${LWIP_DIR}/src/Filelists.cmake)
-include(${LWIP_CONTRIB_DIR}/Filelists.cmake)
+include(${LWIP_DIR}/contrib/Filelists.cmake)
-include(${LWIP_CONTRIB_DIR}/ports/win32/Filelists.cmake)
+include(${LWIP_DIR}/contrib/ports/win32/Filelists.cmake)
 
-add_executable(example_app ${LWIP_CONTRIB_DIR}/examples/example_app/test.c default_netif.c)
+add_executable(example_app ${LWIP_DIR}/contrib/examples/example_app/test.c default_netif.c)
 target_include_directories(example_app PRIVATE ${LWIP_INCLUDE_DIRS})
 target_compile_options(example_app PRIVATE ${LWIP_COMPILER_FLAGS})
 target_compile_definitions(example_app PRIVATE ${LWIP_DEFINITIONS} ${LWIP_MBEDTLS_DEFINITIONS})

doc/doxygen/main_page.h

@@ -123,6 +123,11 @@
  * @verbinclude "contrib.txt"
  */
 
+/**
+ * @page cmake CMake build system
+ * @verbinclude "BUILDING"
+ */
+
 /**
  * @page pitfalls Common pitfalls
  *