Merge pull request #2092 from cesanta/standex

standardize examples

examples/mqtt-client-aws-iot/README.md

@@ -1 +1,2 @@
-See detailed tutorial at https://mongoose.ws/tutorials/mqtt-client-aws-iot/
+- This example requires generating AWS and user credentials and downloading certificates
+- This example requires building with TLS support; before running, see detailed tutorial at https://mongoose.ws/tutorials/mqtt-client-aws-iot/

examples/smtp-client/Makefile

@@ -1,20 +1,32 @@
-PROG ?= example
-CFLAGS ?= -W -Wall -Wextra -O2 $(EXTRA_CFLAGS)
-SSL ?= MBEDTLS
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-ifeq "$(SSL)" "MBEDTLS"
-CFLAGS += -DMG_ENABLE_MBEDTLS=1 -lmbedtls -lmbedcrypto -lmbedx509 -L$(MBEDTLS)/lib -I$(MBEDTLS)/include
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+#CFLAGS_MONGOOSE += -DMG_ENABLE_LINES=1
+
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+  MAKE += WINDOWS=1 CC=$(CC)
 endif
 
-ifeq "$(SSL)" "OPENSSL"
-CFLAGS += -DMG_ENABLE_OPENSSL=1 -lssl -lcrypto -L$(OPENSSL)/lib -I$(OPENSSL)/include
-endif
-
-all: $(PROG)
+all: $(PROG)              # Default target. Build and run program
 	$(RUN) ./$(PROG) $(ARGS)
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. $(CFLAGS) -o $(PROG) main.c
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
 
-clean:
-	rm -rf $(PROG) _CL* *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb mbedtls
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM mbedtls
+
+# see https://mongoose.ws/tutorials/tls/#how-to-build for TLS build options
+
+mbedtls:                  # Pull and build mbedTLS library
+	git clone --depth 1 -b v2.28.2 https://github.com/mbed-tls/mbedtls $@
+	$(MAKE) -C mbedtls/library

examples/smtp-client/README.md

@@ -1,5 +1,2 @@
-# SMTP client example
-
-This example shows how to send emails using Mongoose.
-Before running this example, open main.c and modify settings at the top
-of the file.
+- This example requires changing server name and user credentials on `main.c`
+- This example requires building with TLS support; before running, see detailed tutorial at https://mongoose.ws/tutorials/smtp-client/

examples/smtp-client/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/smtp-client/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/sntp-time-sync/Makefile

@@ -1,10 +1,25 @@
-PROG ?= example
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-all: $(PROG)
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+CFLAGS_MONGOOSE += -DMG_ENABLE_LINES
+
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+endif
+
+all: $(PROG)              # Default target. Build and run program
 	$(RUN) ./$(PROG) $(ARGS)
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. -W -Wall -DMG_ENABLE_LINES=1 $(CFLAGS) -o $(PROG) main.c
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM

examples/sntp-time-sync/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/sntp-time-sync/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/socks5-server/Makefile

@@ -1,19 +1,25 @@
-PROG ?= example
-CFLAGS ?= -DMG_ENABLE_LINES $(CFLAGS_EXTRA)
-MBEDTLS_DIR ?=
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-ifeq "$(MBEDTLS_DIR)" ""
-else
-CFLAGS += -DMG_ENABLE_MBEDTLS=1 -I$(MBEDTLS_DIR)/include -I/usr/include
-CFLAGS += -L$(MBEDTLS_DIR)/lib -lmbedtls -lmbedcrypto -lmbedx509
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+CFLAGS_MONGOOSE += -DMG_ENABLE_LINES
+
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
 endif
 
-all: $(PROG)
-	$(DEBUGGER) ./$(PROG) $(ARGS)
+all: $(PROG)              # Default target. Build and run program
+	$(RUN) ./$(PROG) $(ARGS)
 
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. -W -Wall $(CFLAGS) -o $(PROG) main.c
-
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM

examples/socks5-server/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/socks5-server/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/tcp/Makefile

@@ -1,20 +1,32 @@
-PROG ?= example
-SSL = ?
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-ifeq "$(SSL)" "MBEDTLS"
-CFLAGS += -DMG_ENABLE_MBEDTLS=1 -lmbedtls -lmbedcrypto -lmbedx509
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+#CFLAGS_MONGOOSE += -DMG_ENABLE_LINES=1
+
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+  MAKE += WINDOWS=1 CC=$(CC)
 endif
 
-ifeq "$(SSL)" "OPENSSL"
-CFLAGS += -DMG_ENABLE_OPENSSL=1 -lssl -lcrypto
-endif
+all: $(PROG)              # Default target. Build and run program
+	$(RUN) ./$(PROG) $(ARGS)
 
-all: $(PROG)
-	$(DEBUGGER) ./$(PROG) $(ARGS)
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
 
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM mbedtls
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. -W -Wall $(CFLAGS) $(EXTRA_CFLAGS) -o $(PROG) main.c
+# see https://mongoose.ws/tutorials/tls/#how-to-build for TLS build options
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb
+mbedtls:                  # Pull and build mbedTLS library
+	git clone --depth 1 -b v2.28.2 https://github.com/mbed-tls/mbedtls $@
+	$(MAKE) -C mbedtls/library

examples/tcp/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/tcp/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/timers/Makefile

@@ -1,10 +1,25 @@
-PROG ?= example
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-all: $(PROG)
-	$(DEBUGGER) ./$(PROG) $(ARGS)
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+CFLAGS_MONGOOSE += -DMG_ENABLE_LINES
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. -W -Wall -DMG_ENABLE_LINES=1 $(CFLAGS) -o $(PROG) main.c
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+endif
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb
+all: $(PROG)              # Default target. Build and run program
+	$(RUN) ./$(PROG) $(ARGS)
+
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
+
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM

examples/timers/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/timers/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/uart-bridge/Makefile

@@ -1,19 +1,36 @@
-PROG ?= example
-SOURCES ?= ../../mongoose.c main.c net.c packed_fs.c
-CFLAGS ?= -I../.. -DMG_ENABLE_PACKED_FS=1 -DMG_ENABLE_LINES=1 $(EXTRA_CFLAGS)
-FILES_TO_EMBED ?= $(wildcard web_root/*)
-ROOT ?= $(realpath $(CURDIR)/../../..)
-DOCKER ?= docker run --rm -e Tmp=. -e WINEDEBUG=-all -v $(ROOT):$(ROOT) -w $(CURDIR)
-VC98 ?= $(DOCKER) mdashnet/vc98 wine
-MINGW ?= $(DOCKER) mdashnet/mingw
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c net.c packed_fs.c      # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-all: $(PROG)
-	$(RUN) ./$(PROG)
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+CFLAGS_MONGOOSE += -DMG_ENABLE_PACKED_FS=1 -DMG_ENABLE_LINES=1
 
-$(PROG): $(SOURCES) $(FILES_TO_EMBED)
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+endif
+
+all: $(PROG)              # Default target. Build and run program
+	$(RUN) ./$(PROG) $(ARGS)
+
+ifneq ($(OS),Windows_NT)
+# Before embedding files, gzip them to save space
+packed_fs.c: $(shell find web_root -type f) Makefile
+	rm -rf tmp/web_root && mkdir tmp && cp -r web_root tmp/
+	find tmp -type f | xargs -n1 gzip
 	$(CC) ../../test/pack.c -o pack
-	./pack $(FILES_TO_EMBED) > packed_fs.c
-	$(CC) -W -Wall -Wextra -O0 -g3 $(CFLAGS) -o $(PROG) $(SOURCES)
+	cd tmp && ../pack `find web_root -type f` > ../$@
+endif
+
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
+
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM pack tmp
+
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb log.txt pack config.json

examples/uart-bridge/README.md

@@ -3,14 +3,14 @@
 This example is a demonstration of how Mongoose Library could be integrated
 into an embedded device and provide a UART-to-Network bridge capability:
 
-- A device opens listening TCP port and Websocket port and waits for connections
+- The device opens listening TCP and Websocket ports and waits for connections
 - When a client connects, data is exchanged with the device's UART
-- Everything that client send, is sent to the UART
+- Everything the client sends, is sent to the UART
 - Everything that is read from the UART, gets sent to the client
 - Multiple clients are allowed
 - Live UART console allows to talk to the UART from the web page
 - Web UI is hardcoded into the binary and does not need a filesystem
 
-# Screenshots
-
 ![](screenshots/dashboard.png)
+
+See a detailed tutorial at https://mongoose.ws/tutorials/uart-bridge/

examples/uart-bridge/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/uart-bridge/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/uart-bridge/net.c

@@ -34,7 +34,9 @@ void config_write(struct mg_str config);
 #else
 void uart_init(int tx, int rx, int baud) {
   // We use stdin/stdout as UART. Make stdin non-blocking
+#if MG_ARCH != MG_ARCH_WIN32
   fcntl(0, F_SETFL, fcntl(0, F_GETFL) | O_NONBLOCK);
+#endif
   (void) tx, (void) rx, (void) baud;
 }
 
@@ -44,7 +46,12 @@ void uart_write(const void *buf, size_t len) {
 }
 
 int uart_read(void *buf, size_t len) {
+#if MG_ARCH == MG_ARCH_WIN32
+  (void) buf, (void) len;
+  return 0;
+#else
   return read(0, buf, len);  // Read from stdin
+#endif
 }
 
 char *config_read(void) {
@@ -202,7 +209,8 @@ void uart_bridge_fn(struct mg_connection *c, int ev, void *ev_data,
                     s_state.mqtt.enable ? "true" : "false", "rx", s_state.rx,
                     "tx", s_state.tx, "baud", s_state.baud);
     } else {
-      struct mg_http_serve_opts opts = {0};
+      struct mg_http_serve_opts opts;
+      memset(&opts, 0, sizeof(opts));
 #if 1
       opts.root_dir = "/web_root";
       opts.fs = &mg_fs_packed;

examples/udp-ssdp-search/Makefile

@@ -1,10 +1,25 @@
-PROG ?= example
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-all: $(PROG)
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+#CFLAGS_MONGOOSE += -DMG_ENABLE_LINES
+
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+endif
+
+all: $(PROG)              # Default target. Build and run program
 	$(RUN) ./$(PROG) $(ARGS)
 
-$(PROG): main.c
-	$(CC) ../../mongoose.c -I../.. -W -Wall $(CFLAGS) -o $(PROG) main.c
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM

examples/udp-ssdp-search/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/udp-ssdp-search/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h

examples/video-stream/Makefile

@@ -1,10 +1,25 @@
-PROG ?= example
+PROG ?= example                   # Program we are building
+DELETE = rm -rf                   # Command to remove files
+OUT ?= -o $(PROG)                 # Compiler argument for output file
+SOURCES = main.c mongoose.c       # Source code files
+CFLAGS = -W -Wall -Wextra -g -I.  # Build options
 
-all: $(PROG)
-	$(DEBUGGER) ./$(PROG)
+# Mongoose build options. See https://mongoose.ws/documentation/#build-options
+#CFLAGS_MONGOOSE += -DMG_ENABLE_LINES
 
-$(PROG):
-	$(CC) ../../mongoose.c -I../.. $(CFLAGS) $(EXTRA) -o $(PROG) main.c
+ifeq ($(OS),Windows_NT)   # Windows settings. Assume MinGW compiler. To use VC: make CC=cl CFLAGS=/MD OUT=/Feprog.exe
+  PROG ?= example.exe           # Use .exe suffix for the binary
+  CC = gcc                      # Use MinGW gcc compiler
+  CFLAGS += -lws2_32            # Link against Winsock library
+  DELETE = cmd /C del /Q /F /S  # Command prompt command to delete files
+  OUT ?= -o $(PROG)             # Build output
+endif
 
-clean:
-	rm -rf $(PROG) *.o *.dSYM *.gcov *.gcno *.gcda *.obj *.exe *.ilk *.pdb log.txt
+all: $(PROG)              # Default target. Build and run program
+	$(RUN) ./$(PROG) $(ARGS)
+
+$(PROG): $(SOURCES)       # Build program from sources
+	$(CC) $(SOURCES) $(CFLAGS) $(CFLAGS_MONGOOSE) $(CFLAGS_EXTRA) $(OUT)
+
+clean:                    # Cleanup. Delete built program and all build artifacts
+	$(DELETE) $(PROG) *.o *.obj *.exe *.dSYM

examples/video-stream/main.c

@@ -22,6 +22,7 @@ static void cb(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
       mg_http_serve_dir(c, ev_data, &opts);
     }
   }
+  (void) fn_data;
 }
 
 // The image stream is simulated by sending MJPEG frames specified by the

examples/video-stream/mongoose.c

@@ -0,0 +1 @@
+../../mongoose.c

examples/video-stream/mongoose.h

@@ -0,0 +1 @@
+../../mongoose.h