Browse Source

Transfer build options from README to docs (#1860)

* Transfer build options from README to docs, fixes #1830
* reference tls, u8g, ucg module configuration
Marcel Stör 7 years ago
parent
commit
07341e977f
3 changed files with 69 additions and 60 deletions
  1. 2 52
      README.md
  2. 65 7
      docs/en/build.md
  3. 2 1
      docs/en/extn-developer-faq.md

+ 2 - 52
README.md

@@ -43,10 +43,9 @@ wifi.sta.config("SSID", "password")
 
 # Documentation
 
-The entire [NodeMCU documentation](https://nodemcu.readthedocs.io) is maintained right in this repository at [/docs](docs). The fact that the API documentation is mainted in the same repository as the code that *provides* the API ensures consistency between the two. With every commit the documentation is rebuilt by Read the Docs and thus transformed from terse Markdown into a nicely browsable HTML site at [https://nodemcu.readthedocs.io](https://nodemcu.readthedocs.io). 
+The entire [NodeMCU documentation](https://nodemcu.readthedocs.io) is maintained right in this repository at [/docs](docs). The fact that the API documentation is maintained in the same repository as the code that *provides* the API ensures consistency between the two. With every commit the documentation is rebuilt by Read the Docs and thus transformed from terse Markdown into a nicely browsable HTML site at [https://nodemcu.readthedocs.io](https://nodemcu.readthedocs.io). 
 
 - How to [build the firmware](https://nodemcu.readthedocs.io/en/dev/en/build/)
-- How to [build the filesystem](https://nodemcu.readthedocs.io/en/dev/en/spiffs/)
 - How to [flash the firmware](https://nodemcu.readthedocs.io/en/dev/en/flash/)
 - How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.io/en/dev/en/upload/)
 - API documentation for every module
@@ -65,53 +64,4 @@ See [https://nodemcu.readthedocs.io/en/dev/en/support/](https://nodemcu.readthed
 
 # License
 
-[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html)
-
-# Build Options
-
-The following sections explain some of the options you have if you want to [build your own NodeMCU firmware](http://nodemcu.readthedocs.io/en/dev/en/build/).
-
-### Select Modules
-
-Disable modules you won't be using to reduce firmware size and free up some RAM. The ESP8266 is quite limited in available RAM and running out of memory can cause a system panic. The default configuration is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins.
-
-Edit `app/include/user_modules.h` and comment-out the `#define` statement for modules you don't need. Example:
-
-```c
-...
-#define LUA_USE_MODULES_MQTT
-// #define LUA_USE_MODULES_COAP
-// #define LUA_USE_MODULES_U8G
-...
-```
-
-### Tag Your Build
-
-Identify your firmware builds by editing `app/include/user_version.h`
-
-```c
-#define NODE_VERSION    "NodeMCU 2.0.0+myname"
-#ifndef BUILD_DATE
-#define BUILD_DATE      "YYYYMMDD"
-#endif
-```
-
-### Set UART Bit Rate
-
-The initial baud rate at boot time is 115200bps. You can change this by
-editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`:
-
-```c
-#define BIT_RATE_DEFAULT BIT_RATE_115200
-```
-
-Note that, by default, the firmware runs an auto-baudrate detection algorithm so that typing a few characters at boot time will cause
-the firmware to lock onto that baud rate (between 1200 and 230400). 
-
-### Debugging
-
-To enable runtime debug messages to serial console edit `app/include/user_config.h`
-
-```c
-#define DEVELOP_VERSION
-```
+[MIT](https://github.com/nodemcu/nodemcu-firmware/blob/master/LICENSE) © [zeroday](https://github.com/NodeMCU)/[nodemcu.com](http://nodemcu.com/index_en.html)

+ 65 - 7
docs/en/build.md

@@ -1,14 +1,72 @@
 There are essentially three ways to build your NodeMCU firmware: cloud build service, Docker image, dedicated Linux environment (possibly VM).
 
-**Building manually**
+## Tools
 
-Note that the *default configuration in the C header files* (`user_config.h`, `user_modules.h`) is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins.
-
-## Cloud Build Service
+### Cloud Build Service
 NodeMCU "application developers" just need a ready-made firmware. There's a [cloud build service](http://nodemcu-build.com/) with a nice UI and configuration options for them.
 
-## Docker Image
+### Docker Image
 Occasional NodeMCU firmware hackers don't need full control over the complete tool chain. They might not want to setup a Linux VM with the build environment. Docker to the rescue. Give [Docker NodeMCU build](https://hub.docker.com/r/marcelstoer/nodemcu-build/) a try.
 
-## Linux Build Environment
-NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
+### Linux Build Environment
+NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
+
+## Build Options
+
+The following sections explain some of the options you have if you want to build your own NodeMCU firmware.
+
+### Select Modules
+Disable modules you won't be using to reduce firmware size and free up some RAM. The ESP8266 is quite limited in available RAM and running out of memory can cause a system panic. The *default configuration* is designed to run on all ESP modules including the 512 KB modules like ESP-01 and only includes general purpose interface modules which require at most two GPIO pins.
+
+Edit `app/include/user_modules.h` and comment-out the `#define` statement for modules you don't need. Example:
+
+```c
+...
+#define LUA_USE_MODULES_MQTT
+// #define LUA_USE_MODULES_COAP
+// #define LUA_USE_MODULES_U8G
+...
+```
+
+### TLS/SSL Support
+To enable TLS support edit `app/include/user_config.h` and uncomment the following flag:
+
+```c
+//#define CLIENT_SSL_ENABLE
+```
+
+The complete configuration is stored in `app/include/user_mbedtls.h`. This is the file to edit if you build your own firmware and want to change mbed TLS behavior. See the [`tls` documentation](modules/tls.md) for details.
+
+### Debugging
+To enable runtime debug messages to serial console edit `app/include/user_config.h`
+
+```c
+#define DEVELOP_VERSION
+```
+
+### Set UART Bit Rate
+The initial baud rate at boot time is 115200bps. You can change this by
+editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`:
+
+```c
+#define BIT_RATE_DEFAULT BIT_RATE_115200
+```
+
+Note that, by default, the firmware runs an auto-baudrate detection algorithm so that typing a few characters at boot time will cause
+the firmware to lock onto that baud rate (between 1200 and 230400).
+
+### Tag Your Build
+Identify your firmware builds by editing `app/include/user_version.h`
+
+```c
+#define NODE_VERSION    "NodeMCU 2.0.0+myname"
+#ifndef BUILD_DATE
+#define BUILD_DATE      "YYYYMMDD"
+#endif
+```
+
+### u8g Module Configuration
+Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/u8g_config.h`. See the [`u8g` documentation](modules/u8g.md#displays) for details.
+
+### ucg Module Configuration
+Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/ucg_config.h`. See the [`ucg` documentation](modules/ucg.md#displays) for details.

+ 2 - 1
docs/en/extn-developer-faq.md

@@ -1,6 +1,7 @@
 # Extension Developer FAQ
 
-**# # # Work in Progress # # #**
+## Firmware build options
+[Building the firmware → Build Options](build.md#build-options) lists a few of the common parameters to customize your firmware *at build time*.
 
 ## How does the non-OS SDK structure execution