diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 784d2c7ecd..60543be685 100644 --- a/.github/workflows/nightly.yml +++ b/.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 diff --git a/.github/workflows/quicktest.yml b/.github/workflows/quicktest.yml index 2cea0b333e..a4ec36a1ac 100644 --- a/.github/workflows/quicktest.yml +++ b/.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 diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index c616737656..0000000000 --- a/examples/README.md +++ /dev/null @@ -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 diff --git a/mongoose.h b/mongoose.h index f3677d55c0..75ea01081b 100644 --- a/mongoose.h +++ b/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: diff --git a/src/fs.h b/src/fs.h index 3f87e0ad2d..8c09947375 100644 --- a/src/fs.h +++ b/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 diff --git a/src/profile.h b/src/profile.h index 27d167a938..905afd987f 100644 --- a/src/profile.h +++ b/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: diff --git a/test/Makefile b/test/Makefile index 01f1ff5811..d2d64ea90a 100644 --- a/test/Makefile +++ b/test/Makefile @@ -14,16 +14,13 @@ 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)) -TUTORIALS_QUICK := $(filter-out ../tutorials/tcpip/pcap-driver/, $(TUTORIALS)) -TUTORIALS_MAC := $(filter-out ../tutorials/tcpip/pcap-driver/ ../tutorials/tcpip/tap-driver/, $(TUTORIALS)) +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)) +# This does not included ESP32, ESP8266, Microchip; all examples that are directly placed under an OS tutorial. Arduino might be caught due to links +TUTORIALS_EMBEDDED := $(filter-out $(wildcard ../tutorials/zephyr/*/), $(dir $(wildcard ../tutorials/*/*/Makefile))) PREFIX ?= /usr/local LIBDIR ?= $(PREFIX)/lib INCLUDEDIR ?= $(PREFIX)/include @@ -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: - @for X in $(EXAMPLES_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X build || exit 1; done -clean_examples_embedded: - for X in $(EXAMPLES_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done +tutorials_embedded: + @for X in $(TUTORIALS_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X build || exit 1; done +clean_tutorials_embedded: + for X in $(TUTORIALS_EMBEDDED); do test -f $$X/Makefile || continue; $(MAKE) -C $$X clean || exit 1; done diff --git a/test/cube/Makefile b/test/cube/Makefile index c234c7da6b..459b4de035 100644 --- a/test/cube/Makefile +++ b/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 diff --git a/test/esp-idf/Makefile b/test/esp-idf/Makefile index a829df196e..e38d72562d 100644 --- a/test/esp-idf/Makefile +++ b/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 diff --git a/test/gcc+make/Makefile b/test/gcc+make/Makefile index 8f0bc52022..2b66b21184 100644 --- a/test/gcc+make/Makefile +++ b/test/gcc+make/Makefile @@ -1,4 +1,4 @@ -PROJECTS ?= $(wildcard ../../examples/*/*-make-*) +PROJECTS ?= $(wildcard ../../tutorials/*/*-make-*) all: $(PROJECTS) echo diff --git a/test/keil/Clean b/test/keil/Clean index 5d1c13fde9..671778cc68 100644 --- a/test/keil/Clean +++ b/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)) diff --git a/test/keil/Makefile b/test/keil/Makefile index 4155f5caee..7238bfaf25 100644 --- a/test/keil/Makefile +++ b/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) diff --git a/test/pico-sdk/Makefile b/test/pico-sdk/Makefile index d74dd9ae63..458bc2629c 100644 --- a/test/pico-sdk/Makefile +++ b/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 diff --git a/test/xpresso/Makefile b/test/xpresso/Makefile index 0ac24e68c2..8b9273bd05 100644 --- a/test/xpresso/Makefile +++ b/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 diff --git a/test/zephyr/Makefile b/test/zephyr/Makefile index 9a2b6d4b92..839d1d2144 100644 --- a/test/zephyr/Makefile +++ b/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 diff --git a/tutorials/README.md b/tutorials/README.md new file mode 100644 index 0000000000..ba75a010fb --- /dev/null +++ b/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