move examples -> tutorials

.github/workflows/nightly.yml

@@ -165,97 +165,12 @@ jobs:
     - uses: actions/checkout@v4
     - run: make -C test riscv SSL=${{ matrix.ssl }}
 
-  examples:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: [-DMG_TLS=MG_TLS_NONE, -DMG_TLS=MG_TLS_BUILTIN]
-    name: examples ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-    - run: sudo apt -y install libpcap-dev
-    - run: make -C test examples CFLAGS_EXTRA="${{ matrix.ssl }}"
-    - run: make -C test clean_examples
-  examples_win:
-    runs-on: windows-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
-    name: examples_win ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-#    - uses: egor-tensin/setup-mingw@v2
-#      with:
-#        platform: x64
-    - name: test they build
-      run: make -C test examples_win CFLAGS_EXTRA="${{ matrix.ssl }}"
-      shell: cmd
-    - name: test they clean
-      run: make -C test clean_examples_win
-      shell: cmd
-  examples_mac:
-    runs-on: macos-latest
-    env: { HOMEBREW_NO_AUTO_UPDATE: 1 }
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
-    name: examples_mac ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test examples_mac CFLAGS_EXTRA="${{ matrix.ssl }}"
-    - run: make -C test clean_examples_mac
-
-  refprojs:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
-    name: reference-projects ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test refprojs CFLAGS_EXTRA="${{ matrix.ssl }}"
-    - run: make -C test clean_refprojs
-  refprojs_win:
-    runs-on: windows-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
-    name: reference-projects_win ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-#    - uses: egor-tensin/setup-mingw@v2
-#      with:
-#        platform: x64
-    - name: test they build
-      run: make -C test refprojs_win CFLAGS_EXTRA="${{ matrix.ssl }}"
-      shell: cmd
-    - name: test they clean
-      run: make -C test clean_refprojs_win
-      shell: cmd
-  refprojs_mac:
-    runs-on: macos-latest
-    env: { HOMEBREW_NO_AUTO_UPDATE: 1 }
-    strategy:
-      fail-fast: false
-      matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
-    name: reference-projects_mac ${{ matrix.ssl }}
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test refprojs CFLAGS_EXTRA="${{ matrix.ssl }}"
-    - run: make -C test clean_refprojs
-
   tutorials:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
+        ssl: [-DMG_TLS=MG_TLS_NONE, -DMG_TLS=MG_TLS_BUILTIN]
     name: tutorials ${{ matrix.ssl }}
     steps:
     - uses: actions/checkout@v4
@@ -267,7 +182,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
+        ssl: [-DMG_TLS=MG_TLS_NONE, -DMG_TLS=MG_TLS_BUILTIN]
     name: tutorials_win ${{ matrix.ssl }}
     steps:
     - uses: actions/checkout@v4
@@ -286,7 +201,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ssl: ["", -DMG_TLS=MG_TLS_BUILTIN]
+        ssl: [-DMG_TLS=MG_TLS_NONE, -DMG_TLS=MG_TLS_BUILTIN]
     name: tutorials_mac ${{ matrix.ssl }}
     steps:
     - uses: actions/checkout@v4

.github/workflows/quicktest.yml

@@ -91,60 +91,6 @@ jobs:
     - uses: actions/checkout@v4
     - run: make -C test riscv
 
-  examples:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test examples_essential
-    - run: make -C test clean_examples_essential
-  examples_win:
-    runs-on: windows-latest
-    steps:
-    - uses: actions/checkout@v4
-#    - uses: egor-tensin/setup-mingw@v2
-#      with:
-#        platform: x64
-    - name: test they build
-      run: make -C test examples_win
-      shell: cmd
-    - name: test they clean
-      run: make -C test clean_examples_win
-      shell: cmd
-  examples_mac:
-    runs-on: macos-latest
-    env: { HOMEBREW_NO_AUTO_UPDATE: 1 }
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test examples_mac
-    - run: make -C test clean_examples_mac
-
-  refprojs:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test refprojs
-    - run: make -C test clean_refprojs
-  refprojs_win:
-    runs-on: windows-latest
-    steps:
-    - uses: actions/checkout@v4
-#    - uses: egor-tensin/setup-mingw@v2
-#      with:
-#        platform: x64
-    - name: test they build
-      run: make -C test refprojs_win
-      shell: cmd
-    - name: test they clean
-      run: make -C test clean_refprojs_win
-      shell: cmd
-  refprojs_mac:
-    runs-on: macos-latest
-    env: { HOMEBREW_NO_AUTO_UPDATE: 1 }
-    steps:
-    - uses: actions/checkout@v4
-    - run: make -C test refprojs
-    - run: make -C test clean_refprojs
-
   tutorials:
     runs-on: ubuntu-latest
     steps:
@@ -398,7 +344,7 @@ jobs:
       with: { fetch-depth: 2 }
     - name: baremetal
       run: |
-        if ./test/match_changed_files.sh "^src|tutorials/http/device-dashboard|tutorials/stm32" ; then
+        if ./test/match_changed_files.sh "^src|tutorials/http/device-dashboard|tutorials/stm32/nucleo-f7.*-make-" ; then
           echo GO=1 >> $GITHUB_ENV
           sudo apt -y update && sudo apt -y install gcc-arm-none-eabi
         fi

examples/README.md

@@ -1,24 +0,0 @@
-# Mongoose Network Library Examples
-
-In order to build and run any of the existing examples, please follow:
-https://mongoose.ws/documentation/#how-to-build-and-run-examples
-
-## Contributing
-
-Rules for creating a new example:
-
-- Makefile golden reference for desktop/server example: [http-server](http-server)
-- Makefile golden reference for the embedded example:
-   [stm32/nucleo-f746zg-baremetal](stm32/nucleo-f746zg-baremetal)
-- An example must build on Windows, Mac and Ubuntu Linux systems
-- Assume that user installed tools according to https://mongoose.ws/tutorials/tools/
-- Makefile must not include any other make files
-- Use `CFLAGS` for system-specific compilation options
-- Use `CFLAGS_MONGOOSE` for mongoose-specific compilation options
-- Use `$(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA)` to compile
-- If external repository is required, download it on demand using git
-  shallow clone. See embedded example golden reference
-- Keep Makefile as short as possible, but verbose to understand it easily
-- Symlink files when required, like `mongoose.c`, `ca.pem`, etc. Make no copies
-- Example's README.md should contain only the title and the link to mongoose.ws
-  tutorial page

mongoose.h

@@ -1068,7 +1068,7 @@ struct mg_fs {
 };
 
 extern struct mg_fs mg_fs_posix;   // POSIX open/close/read/write/seek
-extern struct mg_fs mg_fs_packed;  // Packed FS, see examples/device-dashboard
+extern struct mg_fs mg_fs_packed;  // see tutorials/core/embedded-filesystem
 extern struct mg_fs mg_fs_fat;     // FAT FS
 
 // File descriptor
@@ -2832,7 +2832,7 @@ struct mg_tcpip_spi {
 // timestamp in milliseconds since connection init time.
 //
 // Test (run in two separate terminals):
-//   make -C examples/http-server/ CFLAGS_EXTRA=-DMG_ENABLE_PROFILE=1
+//   make -C tutorials/http/http-server/ CFLAGS_EXTRA=-DMG_ENABLE_PROFILE=1
 //   curl localhost:8000
 // Output:
 //   1ea1f1e7 2 net.c:150:mg_close_conn      3 profile:                                                            

src/fs.h

@@ -28,7 +28,7 @@ struct mg_fs {
 };
 
 extern struct mg_fs mg_fs_posix;   // POSIX open/close/read/write/seek
-extern struct mg_fs mg_fs_packed;  // Packed FS, see examples/device-dashboard
+extern struct mg_fs mg_fs_packed;  // see tutorials/core/embedded-filesystem
 extern struct mg_fs mg_fs_fat;     // FAT FS
 
 // File descriptor

src/profile.h

@@ -6,7 +6,7 @@
 // timestamp in milliseconds since connection init time.
 //
 // Test (run in two separate terminals):
-//   make -C examples/http-server/ CFLAGS_EXTRA=-DMG_ENABLE_PROFILE=1
+//   make -C tutorials/http/http-server/ CFLAGS_EXTRA=-DMG_ENABLE_PROFILE=1
 //   curl localhost:8000
 // Output:
 //   1ea1f1e7 2 net.c:150:mg_close_conn      3 profile:                                                            

test/Makefile

@@ -14,15 +14,12 @@ VCFLAGS = /nologo /W3 /O2 /MD /I. $(DEFS) $(TFLAGS)
 IPV6 ?= 1
 ASAN ?= -fsanitize=address,undefined,alignment -fno-sanitize-recover=all -fno-omit-frame-pointer -fno-common
 ASAN_OPTIONS ?= detect_leaks=1
-EXAMPLES := $(dir $(wildcard ../examples/*/Makefile))
-EXAMPLES_QUICK := $(filter-out ../examples/micropython/, $(EXAMPLES))
-EXAMPLES_MAC := $(filter-out ../examples/micropython/, $(EXAMPLES))
-EXAMPLES_WIN := $(dir $(wildcard ../examples/device-dashboard/Makefile) $(wildcard ../examples/file-*/Makefile) $(wildcard ../examples/http-*/Makefile) $(wildcard ../examples/mqtt-*/Makefile) $(wildcard ../examples/websocket-*/Makefile) $(wildcard ../examples/webui-*/Makefile))
-EXAMPLES_EMBEDDED := $(filter-out $(wildcard ../examples/zephyr/*/), $(dir $(wildcard ../examples/*/*/Makefile)))
 REFPROJS := $(dir $(wildcard ../reference-projects/windows-macos-linux/*/Makefile))
-TUTORIALS := $(dir $(wildcard ../tutorials/*/*/Makefile))
+# This does not include ESP32, ESP8266, Microchip; all examples that are directly placed under an OS tutorial. Also, it is needed that way...
-TUTORIALS_QUICK := $(filter-out ../tutorials/tcpip/pcap-driver/, $(TUTORIALS))
+TUTORIALS_EMBEDDED := $(dir $(wildcard ../tutorials/infineon/*/Makefile)) $(dir $(wildcard ../tutorials/nxp/*/Makefile)) $(dir $(wildcard ../tutorials/pico-sdk/*/Makefile)) $(dir $(wildcard ../tutorials/renesas/*/Makefile)) $(dir $(wildcard ../tutorials/stm32/*/Makefile)) $(dir $(wildcard ../tutorials/ti/*/Makefile)) $(dir $(wildcard ../tutorials/wch/*/Makefile))
-TUTORIALS_MAC := $(filter-out ../tutorials/tcpip/pcap-driver/ ../tutorials/tcpip/tap-driver/, $(TUTORIALS))
+TUTORIALS := ../tutorials/micropython/ $(filter-out $(TUTORIALS_EMBEDDED), $(dir $(wildcard ../tutorials/*/*/Makefile)))
+TUTORIALS_QUICK := $(filter-out ../tutorials/micropython/ ../tutorials/tcpip/pcap-driver/, $(TUTORIALS))
+TUTORIALS_MAC := $(filter-out ../tutorials/micropython/ ../tutorials/tcpip/pcap-driver/ ../tutorials/tcpip/tap-driver/, $(TUTORIALS))
 TUTORIALS_WIN := $(dir $(wildcard ../tutorials/http/file-*/Makefile) $(wildcard ../tutorials/http/http-*/Makefile) $(wildcard ../tutorials/mqtt/*/Makefile) $(wildcard ../tutorials/websocket/*/Makefile) $(wildcard ../tutorials/webui/*/Makefile))
 PREFIX ?= /usr/local
 LIBDIR ?= $(PREFIX)/lib
@@ -32,7 +29,7 @@ COMMON_CFLAGS ?= $(C_WARN) $(WARN) $(INCS) $(DEFS) -DMG_ENABLE_IPV6=$(IPV6) $(TF
 CFLAGS ?= $(OPTS) $(ASAN) $(COMMON_CFLAGS)
 VALGRIND_CFLAGS ?= $(OPTS) $(COMMON_CFLAGS)
 VALGRIND_RUN ?= valgrind --tool=memcheck --gen-suppressions=all --leak-check=full --show-leak-kinds=all --leak-resolution=high --track-origins=yes --error-exitcode=1 --exit-on-first-error=yes --fair-sched=yes
-.PHONY: clean_examples examples mip_test test valgrind
+.PHONY: clean_tutorials tutorials mip_test test valgrind
 
 ifeq "$(findstring ++,$(CC))" ""
 # $(CC) does not end with ++, i.e. we're using C. Apply C flags
@@ -84,7 +81,7 @@ endif
 all:
 	$(MAKE) -C ../tutorials/http/http-server
 
-tall: mg_prefix unamalgamated test mip_test arm examples vc98 vc17 vc22 mingw mingw++ fuzz
+tall: mg_prefix unamalgamated test mip_test arm tutorials vc98 vc17 vc22 mingw mingw++ fuzz
 
 mip_test: mip_test.c mongoose.c mongoose.h packed_fs.c Makefile
 	$(CC) mip_test.c packed_fs.c $(CFLAGS) $(LDFLAGS) -o $@
@@ -212,41 +209,11 @@ mongoose.h: $(HDRS) Makefile
 	cd .. && (cat src/license.h; echo; echo '#ifndef MONGOOSE_H'; echo '#define MONGOOSE_H'; echo; cat src/version.h ; echo; echo '#ifdef __cplusplus'; echo 'extern "C" {'; echo '#endif'; cat src/arch.h src/arch_*.h src/net_ft.h src/net_lwip.h src/net_rl.h src/config.h src/str.h src/queue.h src/fmt.h src/printf.h src/log.h src/timer.h src/fs.h src/util.h src/url.h src/iobuf.h src/base64.h src/md5.h src/sha1.h src/sha256.h src/tls_x25519.h src/tls_aes128.h src/tls_uecc.h src/tls_chacha20.h src/tls_rsa.h src/event.h src/net.h src/http.h src/ssi.h src/tls.h src/tls_mbed.h src/tls_openssl.h src/ws.h src/sntp.h src/mqtt.h src/dns.h src/json.h src/rpc.h src/ota.h src/flash.h src/net_builtin.h src/profile.h src/drivers/*.h | sed -e '/keep/! s,#include ".*,,' -e 's,^#pragma once,,'; echo; echo '#ifdef __cplusplus'; echo '}'; echo '#endif'; echo '#endif  // MONGOOSE_H')> $@
 
 
-clean: clean_examples clean_refprojs clean_tutorials clean_examples_embedded
+clean: clean_tutorials clean_tutorials_embedded
 	rm -rf $(PROG) *.exe *.o *.dSYM *_test ut fuzzer *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb slow-unit* _CL_* infer-out data.txt crash-* packed_fs.c pack
-	#find examples -maxdepth 3 -name zephyr -prune -o -name Makefile -print | xargs dirname | xargs -n1 make clean -C
+	#find tutorials -maxdepth 3 -name zephyr -prune -o -name Makefile -print | xargs dirname | xargs -n1 make clean -C
 
 
-examples:
-	@for X in $(EXAMPLES); do test -f $$X/Makefile || continue; $(MAKE) -C $$X example || exit 1; done
-clean_examples:
-	for X in $(EXAMPLES); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
-
-examples_essential:
-	@for X in $(EXAMPLES_QUICK); do test -f $$X/Makefile || continue; $(MAKE) -C $$X example || exit 1; done
-clean_examples_essential:
-	for X in $(EXAMPLES_QUICK); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
-
-examples_mac:
-	for X in $(EXAMPLES_MAC); do test -f $$X/Makefile || continue; $(MAKE) -C $$X example || exit 1; done
-clean_examples_mac:
-	for X in $(EXAMPLES_MAC); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
-
-examples_win:
-	$(foreach X, $(EXAMPLES_WIN), $(MAKE) -C $(X) example &)
-clean_examples_win:
-	$(foreach X, $(EXAMPLES_WIN), $(MAKE) -C $(X) clean &)
-
-refprojs:
-	@for X in $(REFPROJS); do test -f $$X/Makefile || continue; $(MAKE) -C $$X example || exit 1; done
-clean_refprojs:
-	for X in $(REFPROJS); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
-
-refprojs_win:
-	$(foreach X, $(REFPROJS), $(MAKE) -C $(X) example.exe &)
-clean_refprojs_win:
-	$(foreach X, $(REFPROJS), $(MAKE) -C $(X) clean &)
-
 tutorials:
 	@for X in $(TUTORIALS); do test -f $$X/Makefile || continue; $(MAKE) -C $$X example || exit 1; done
 clean_tutorials:
@@ -268,8 +235,8 @@ clean_tutorials_win:
 	$(foreach X, $(TUTORIALS_WIN), $(MAKE) -C $(X) clean &)
 
 
-examples_embedded:
+tutorials_embedded:
-	@for X in $(EXAMPLES_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X build || exit 1; done
+	@for X in $(TUTORIALS_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X build || exit 1; done
-clean_examples_embedded:
+clean_tutorials_embedded:
-	for X in $(EXAMPLES_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
+	for X in $(TUTORIALS_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done
 

test/cube/Makefile

@@ -1,5 +1,5 @@
 ROOT ?= $(realpath $(CURDIR)/../..)
-PROJECTS ?= $(wildcard ../../examples/stm32/nucleo-*-cube-*)
+PROJECTS ?= $(wildcard ../../tutorials/stm32/nucleo-*-cube-*)
 TARGET ?= Debug
 DOCKER = docker run --rm -v $(ROOT):$(ROOT) -v $(CURDIR):/root -w $(CURDIR) 
 IMAGE ?= scaprile/cubeozone

test/esp-idf/Makefile

@@ -1,5 +1,5 @@
 ROOT ?= $(realpath $(CURDIR)/../..)
-PROJECTS ?= $(wildcard ../../examples/esp32/*)
+PROJECTS ?= ../../tutorials/http/device-dashboard/esp32/ ../../tutorials/micropython/esp32/ ../../tutorials/http/uart-bridge/esp32/
 TARGET ?= Debug
 DOCKER = docker run --rm -v $(ROOT):$(ROOT) -v $(CURDIR):/root -w $(CURDIR) 
 IMAGE ?= espressif/idf

test/gcc+make/Makefile

@@ -1,4 +1,4 @@
-PROJECTS ?= $(wildcard ../../examples/*/*-make-*)
+PROJECTS ?= $(wildcard ../../tutorials/*/*-make-*)
 
 all: $(PROJECTS)
 	echo

test/keil/Clean

@@ -1,5 +1,5 @@
 # Do NOT use parenthesis on Windows project dir names
-PROJECTS ?= $(wildcard ../../examples/stm32/nucleo-*-keil-*)
+PROJECTS ?= $(wildcard ../../tutorials/stm32/nucleo-*-keil-*)
 
 MAKEFILEPATH := $(dir $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))
 BATPATH := $(subst /,\,$(MAKEFILEPATH))

test/keil/Makefile

@@ -1,5 +1,5 @@
 # Do NOT use parenthesis on Windows project dir names
-PROJECTS ?= $(wildcard ../../examples/stm32/nucleo-*-keil-*)
+PROJECTS ?= $(wildcard ../../tutorials/stm32/nucleo-*-keil-*)
 TARGET ?= "Target 1"
 
 all: $(PROJECTS)

test/pico-sdk/Makefile

@@ -1,4 +1,4 @@
-PROJECTS ?= $(wildcard ../../examples/pico-sdk/*-picosdk-*)
+PROJECTS ?= $(wildcard ../../tutorials/pico-sdk/*-picosdk-*)
 SDK_PATH ?= $(realpath $(PWD))/pico-sdk
 SDK_VERSION ?= 2.1.0
 

test/xpresso/Makefile

@@ -1,5 +1,5 @@
 ROOT ?= $(realpath $(CURDIR)/../..)
-PROJECTS ?= $(wildcard ../../examples/nxp/*-xpresso-*)
+PROJECTS ?= $(wildcard ../../tutorials/nxp/*-xpresso-*)
 TARGET ?= Debug
 DOCKER = docker run --rm -v $(ROOT):$(ROOT) -v $(CURDIR):/root -w $(CURDIR) 
 IMAGE ?= scaprile/xpresso

test/zephyr/Makefile

@@ -1,5 +1,5 @@
 ROOT ?= $(realpath $(CURDIR)/../..)
-ZEPHYR_DIR ?= $(ROOT)/examples/zephyr/zephyrproject
+ZEPHYR_DIR ?= $(ROOT)/tutorials/zephyr/zephyrproject
 DOCKER ?= docker run --rm -v $(ROOT):$(ROOT) -w $(CURDIR)/wizard
 IMAGE ?= zephyrprojectrtos/ci
 REVNO ?= --mr v3.7-branch

tutorials/README.md

@@ -0,0 +1,41 @@
+# Mongoose Network Library tutorials and example code
+
+The fastest way to quickly get Mongoose running on your hardware is to follow our [Tutorials](https://mongoose.ws/documentation/#tutorials):
+
+- Browse for your desired protocol and function, read the tutorial
+- For embedded hardware specifics, browse to your desired board, or the closest one. You'll find links to different IDE, RTOS, and TCP/IP stack options, and a link to our [Wizard](https://mongoose.ws/documentation/#mongoose-wizard), a tool that generates UI code for you.
+
+## Navigating this tree
+
+Steps to get the most out of this code base:
+
+- Most code here has a README.md file that points to a verbose tutorial describing how to get the intended functionality out of Mongoose Network Library. Code there runs as is in Windows, Ubuntu Linux, and Mac (very few cases don't run in Windows).
+  - Navigate your way to the desired protocol or function, read the README.md file
+  - Follow the linked tutorial
+  - In cases were there is no tutorial:
+    - Follow the [Build Tools](https://mongoose.ws/documentation/tutorials/tools/) tutorial to setup your development environment.
+    - run `make all`
+- Embedded hardware tutorials are conveniently linked from OS tutorials, or grouped by vendor and board.
+  - Navigate your way to the desired board or the closest one, read the README.md file. In most cases you'll find a link to our [Wizard](https://mongoose.ws/wizard/); for others, there is a link to a [Tutorial](https://mongoose.ws/documentation/#tutorials), as described at the top of this text. The Wizard will also link you to the tutorials you'll need.
+  - In cases were there you don't find a link to a tutorial:
+    - Follow the [Build Tools](https://mongoose.ws/documentation/tutorials/tools/) tutorial to setup your development environment.
+    - run `make build`
+- Once you have a running example close to your needs, you can start developing your application
+  - Please read our [User Guide](https://mongoose.ws/documentation/#user-guide)
+
+## Contributing
+
+Rules for creating a new example:
+
+- Makefile golden reference for desktop/server examples: [http-server](http/http-server/)
+- Makefile golden reference for embedded examples: [stm32/nucleo-f746zg-baremetal-builtin-rndis](stm32/nucleo-f746zg-baremetal-builtin-rndis/)
+- Examples must build on Windows, Mac and Ubuntu Linux systems
+- Assume that users installed their tools according to the [Build Tools](https://mongoose.ws/documentation/tutorials/tools/) tutorial
+- Makefiles must not include other Makefiles
+- Use `CFLAGS` for system-specific compilation options
+- Use `CFLAGS_MONGOOSE` for Mongoose-specific compilation options
+- Use `$(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA)` to compile
+- If an external repository is required, download it on demand using git shallow clone. See the embedded examples golden reference
+- Keep Makefiles as short as possible, but verbose to understand them easily
+- Symlink files when required, like `mongoose.c`, `ca.pem`, etc. Make no copies
+- Examples README.md files should contain only the title and the link to the corresponding mongoose.ws tutorial page

tutorials/http/uart-bridge/packed_fs.c

@@ -12,7 +12,7 @@ const char *mg_unpack(const char *, size_t *, time_t *);
 #endif
 
 static const unsigned char v1[] = {
-  31, 139,   8,   8,   6,  78, 191, 103,   0,   3, 105, 110, // .....N.g..in
+  31, 139,   8,   8,  67, 234, 193, 103,   0,   3, 105, 110, // ....C..g..in
  100, 101, 120,  46, 104, 116, 109, 108,   0,  93, 144, 177, // dex.html.]..
   78, 196,  48,  12, 134, 247, 123, 138, 144, 153, 180, 176, // N.0...{.....
   49,  36, 149, 208, 245,   6,  38,  24,  64, 130,  49,  77, // 1$....&.@.1M
@@ -37,7 +37,7 @@ static const unsigned char v1[] = {
  130, 117,   1,   0,   0, 0 // .u...
 };
 static const unsigned char v2[] = {
-  31, 139,   8,   8,   6,  78, 191, 103,   0,   3, 109,  97, // .....N.g..ma
+  31, 139,   8,   8,  67, 234, 193, 103,   0,   3, 109,  97, // ....C..g..ma
  105, 110,  46, 106, 115,   0, 181,  88, 109, 111, 219,  70, // in.js..Xmo.F
   18, 254, 174,  95,  49,  80, 125,  37, 121, 165,  72,  43, // ..._1P}%y.H+
  113, 225, 131,  44, 235, 144,   6,  45, 112, 135,  38, 233, // q..,...-p.&.
@@ -204,7 +204,7 @@ static const unsigned char v2[] = {
  154, 248,  11, 218, 252, 214, 171,  12,  23,   0,   0, 0 // ...........
 };
 static const unsigned char v3[] = {
-  31, 139,   8,   8,   6,  78, 191, 103,   0,   3, 112, 114, // .....N.g..pr
+  31, 139,   8,   8,  67, 234, 193, 103,   0,   3, 112, 114, // ....C..g..pr
  101,  97,  99, 116,  46, 109, 105, 110,  46, 106, 115,   0, // eact.min.js.
  157,  91, 123, 119, 219, 182, 146, 255, 127,  63,  69, 164, // .[{w.....?E.
  211, 163,  18,  43,  68, 177, 147, 182, 187,  75,   5, 213, // ...+D....K..
@@ -650,7 +650,7 @@ static const unsigned char v3[] = {
  138,  51,   0,   0, 0 // .3..
 };
 static const unsigned char v4[] = {
-  31, 139,   8,   8,   6,  78, 191, 103,   0,   3, 115, 116, // .....N.g..st
+  31, 139,   8,   8,  67, 234, 193, 103,   0,   3, 115, 116, // ....C..g..st
  121, 108, 101,  46,  99, 115, 115,   0, 149,  85, 193, 142, // yle.css..U..
  155,  48,  16, 189, 231,  43,  92, 173,  42, 181, 171, 192, // .0...+..*...
  134,  16,  96,  33, 151, 222, 250,  17,  85,  15,   6, 155, // ..`!....U...
@@ -727,10 +727,10 @@ static const struct packed_file {
   size_t size;
   time_t mtime;
 } packed_files[] = {
-  {"/web_root/index.html.gz", v1, sizeof(v1), 1740590598},
+  {"/web_root/index.html.gz", v1, sizeof(v1), 1740761667},
-  {"/web_root/main.js.gz", v2, sizeof(v2), 1740590598},
+  {"/web_root/main.js.gz", v2, sizeof(v2), 1740761667},
-  {"/web_root/preact.min.js.gz", v3, sizeof(v3), 1740590598},
+  {"/web_root/preact.min.js.gz", v3, sizeof(v3), 1740761667},
-  {"/web_root/style.css.gz", v4, sizeof(v4), 1740590598},
+  {"/web_root/style.css.gz", v4, sizeof(v4), 1740761667},
   {NULL, NULL, 0, 0}
 };
 

tutorials/infineon/xmc47_relax-make-baremetal-builtin/Makefile

@@ -0,0 +1,29 @@
+BOARD = xmc4700
+IDE = GCC+make
+RTOS = baremetal
+WIZARD_URL ?= http://mongoose.ws/wizard
+
+all build example: firmware.bin
+
+firmware.bin: wizard
+	make -C wizard CFLAGS_EXTRA=$(CFLAGS_EXTRA) && mv wizard/firmware.bin ./
+
+wizard:
+	hash=$$(curl -s -X POST -H "Content-Type: application/json" -d '{"build":{"board":"$(BOARD)","ide":"$(IDE)","rtos":"$(RTOS)"}}' $(WIZARD_URL)/api/hash | jq -r '.hash') \
+	&& curl -s $(WIZARD_URL)/api/zip/$(BOARD)/$(IDE)/$(RTOS)/$$hash -o wizard.zip
+	unzip wizard.zip
+	cd wizard ; rm mongoose.[ch] ; ln -s ../../../../mongoose.c ; ln -s ../../../../mongoose.h
+
+
+# Automated remote test. Requires env variable VCON_API_KEY set. See https://vcon.io/automated-firmware-tests/
+DEVICE_URL ?= https://dash.vcon.io/api/v3/devices/??
+update: firmware.bin
+	curl --fail-with-body -su :$(VCON_API_KEY) $(DEVICE_URL)/ota --data-binary @$<
+
+test update: CFLAGS_EXTRA ="-DUART_DEBUG=USART1"
+test: update
+	curl --fail-with-body -su :$(VCON_API_KEY) $(DEVICE_URL)/tx?t=15 | tee /tmp/output.txt
+	grep 'READY, IP:' /tmp/output.txt       # Check for network init
+
+clean:
+	rm -rf firmware.* wizard*

tutorials/infineon/xmc47_relax-make-baremetal-builtin/README.md

@@ -0,0 +1 @@
+See [Wizard](https://mongoose.ws/wizard/#/output?board=xmc4700&ide=GCC+make&rtos=baremetal&file=README.md)

tutorials/infineon/xmc_plt2go_4400-make-baremetal-builtin/Makefile

@@ -0,0 +1,29 @@
+BOARD = xmc4400
+IDE = GCC+make
+RTOS = baremetal
+WIZARD_URL ?= http://mongoose.ws/wizard
+
+all build example: firmware.bin
+
+firmware.bin: wizard
+	make -C wizard CFLAGS_EXTRA=$(CFLAGS_EXTRA) && mv wizard/firmware.bin ./
+
+wizard:
+	hash=$$(curl -s -X POST -H "Content-Type: application/json" -d '{"build":{"board":"$(BOARD)","ide":"$(IDE)","rtos":"$(RTOS)"}}' $(WIZARD_URL)/api/hash | jq -r '.hash') \
+	&& curl -s $(WIZARD_URL)/api/zip/$(BOARD)/$(IDE)/$(RTOS)/$$hash -o wizard.zip
+	unzip wizard.zip
+	cd wizard ; rm mongoose.[ch] ; ln -s ../../../../mongoose.c ; ln -s ../../../../mongoose.h
+
+
+# Automated remote test. Requires env variable VCON_API_KEY set. See https://vcon.io/automated-firmware-tests/
+DEVICE_URL ?= https://dash.vcon.io/api/v3/devices/??
+update: firmware.bin
+	curl --fail-with-body -su :$(VCON_API_KEY) $(DEVICE_URL)/ota --data-binary @$<
+
+test update: CFLAGS_EXTRA ="-DUART_DEBUG=USART1"
+test: update
+	curl --fail-with-body -su :$(VCON_API_KEY) $(DEVICE_URL)/tx?t=15 | tee /tmp/output.txt
+	grep 'READY, IP:' /tmp/output.txt       # Check for network init
+
+clean:
+	rm -rf firmware.* wizard*

tutorials/infineon/xmc_plt2go_4400-make-baremetal-builtin/README.md

@@ -0,0 +1 @@
+See [Wizard](https://mongoose.ws/wizard/#/output?board=xmc4400&ide=GCC+make&rtos=baremetal&file=README.md)

tutorials/tcpip/tap-driver/net.c

@@ -1 +1 @@
-../../../examples/device-dashboard/net.c
+../../http/device-dashboard/net.c

tutorials/tcpip/tap-driver/net.h

@@ -1 +1 @@
-../../../examples/device-dashboard/net.h
+../../http/device-dashboard/net.h

tutorials/tcpip/tap-driver/packed_fs.c

@@ -1 +1 @@
-../../../examples/device-dashboard/packed_fs.c
+../../http/device-dashboard/packed_fs.c