Anywhere a module is mentioned, use its "non-u" name for consistency.
The "import module" vs "import umodule" is something of a FAQ, and this
commit intends to help clear that up. As a first approximation MicroPython
is Python, and so imports should work the same as Python and use the same
name, to a first approximation. The u-version of a module is a detail that
can be learned later on, when the user wants to understand more and have
finer control over importing.
Existing Python code should just work, as much as it is possible to do that
within the constraints of embedded systems, and the MicroPython
documentation should match the idiomatic way to write Python code.
With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users
can consistently use "import foo" across all ports (with the exception of
the minimal ports). And the ability to override/extend via "foo.py"
continues to work well.
Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
This enables warnings as errors and fixes all current errors, namely:
- reference to terms in the glossary must now be explicit (:term:)
- method overloads must not be declared as a separate method or must
use :noindex:
- 2 cases where `` should have been used instead of `
This commit changes the esp8266 boards to use littlefs v2 as the
filesystem, rather than FAT. Since the esp8266 doesn't expose the
filesystem to the PC over USB there's no strong reason to keep it as FAT.
Littlefs is smaller in code size, is more efficient in use of flash to
store data, is resilient over power failure, and using it saves about 4k of
heap RAM, which can now be used for other things.
This is a backwards incompatible change because all existing esp8266 boards
will need to update their filesystem after installing new firmware (eg
backup old files, install firmware, restore files to new filesystem).
As part of this commit the memory layout of the default board (GENERIC) has
changed. It now allocates all 1M of memory-mapped flash to the firmware,
so the filesystem area starts at the 2M point. This is done to allow more
frozen bytecode to be stored in the 1M of memory-mapped flash. This
requires an esp8266 module with 2M or more of flash to work, so a new board
called GENERIC_1M is added which has the old memory-mapping (but still
changed to use littlefs for the filesystem).
In summary there are now 3 esp8266 board definitions:
- GENERIC_512K: for 512k modules, doesn't have a filesystem.
- GENERIC_1M: for 1M modules, 572k for firmware+frozen code, 396k for
filesystem (littlefs).
- GENERIC: for 2M (or greater) modules, 968k for firmware+frozen code,
1M+ for filesystem (littlefs), FAT driver also included in firmware for
use on, eg, external SD cards.
This system makes it a lot easier to include external libraries as static,
native modules in MicroPython. Simply pass USER_C_MODULES (like
FROZEN_MPY_DIR) as a make parameter.
Replaces "PYB: soft reboot" with "MPY: soft reboot", etc.
Having a consistent prefix across ports reduces the difference between
ports, which is a general goal. And this change won't break pyboard.py
because that tool only looks for "soft reboot".
State that this doc describes generic, "core" MicroPython functionality,
any particular port may diverge in both directions, by both omitting
some functionality, and adding more, both cases described outside the
generic documentation.
We have enough terms or references throughout the docs which may be not
immediately clear or have some important nuances. Referencing terms in
gloassary is the best way to deal with that.
The old intro talked about "differences", but there were hardly any
sections describing differences, mostly MicroPython specific features.
On the other hand, we now have real "differences" chapter, though it's
mostly concerned with stdlib differences.
So, try to avoid confusion by changing wording and linking to the other
chapters and contrasting them with what is described in "MicroPython
language".
Move hardware-specific optimizations to the very end of document, and
add visible note that it gives an example for Pyboard. Remove references
to specific hardware technologies, so the doc can be more naturally
used across ports. Various markup updates to adhere to the latest
docs conventions.
