micropython/ports/windows
Maarten van der Schrieck 3bca93b2d0 ports: Fix sys.stdout.buffer.write() return value.
MicroPython code may rely on the return value of sys.stdout.buffer.write()
to reflect the number of bytes actually written. While in most scenarios a
write() operation is successful, there are cases where it fails, leading to
data loss. This problem arises because, currently, write() merely returns
the number of bytes it was supposed to write, without indication of
failure.

One scenario where write() might fail, is where USB is used and the
receiving end doesn't read quickly enough to empty the receive buffer. In
that case, write() on the MicroPython side can timeout, resulting in the
loss of data without any indication, a behavior observed notably in
communication between a Pi Pico as a client and a Linux host using the ACM
driver.

A complex issue arises with mp_hal_stdout_tx_strn() when it involves
multiple outputs, such as USB, dupterm and hardware UART. The challenge is
in handling cases where writing to one output is successful, but another
fails, either fully or partially. This patch implements the following
solution:

mp_hal_stdout_tx_strn() attempts to write len bytes to all of the possible
destinations for that data, and returns the minimum successful write
length.

The implementation of this is complicated by several factors:
- multiple outputs may be enabled or disabled at compiled time
- multiple outputs may be enabled or disabled at runtime
- mp_os_dupterm_tx_strn() is one such output, optionally containing
  multiple additional outputs
- each of these outputs may or may not be able to report success
- each of these outputs may or may not be able to report partial writes

As a result, there's no single strategy that fits all ports, necessitating
unique logic for each instance of mp_hal_stdout_tx_strn().

Note that addressing sys.stdout.write() is more complex due to its data
modification process ("cooked" output), and it remains unchanged in this
patch. Developers who are concerned about accurate return values from
write operations should use sys.stdout.buffer.write().

This patch might disrupt some existing code, but it's also expected to
resolve issues, considering that the peculiar return value behavior of
sys.stdout.buffer.write() is not well-documented and likely not widely
known. Therefore, it's improbable that much existing code relies on the
previous behavior.

Signed-off-by: Maarten van der Schrieck <maarten@thingsconnected.nl>
2023-12-22 10:32:46 +11:00
..
msvc extmod/modmachine: Factor ports' machine module dict to common code. 2023-11-30 16:11:11 +11:00
variants extmod/asyncio: Rename uasyncio to asyncio. 2023-06-19 17:33:03 +10:00
.appveyor.yml windows/msvc: Fix module freezing. 2023-02-01 13:10:00 +11:00
.gitignore windows/.gitignore: Simplify by removing build artefacts. 2022-12-13 17:22:11 +11:00
Makefile extmod/modmachine: Factor ports' machine module dict to common code. 2023-11-30 16:11:11 +11:00
README.md windows: Use the MicroPython logo as application icon. 2023-11-07 17:22:52 +11:00
fmode.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
fmode.h
init.c windows: Consolidate all sleep-related functions into windows_mphal.c. 2022-05-04 10:22:09 +10:00
init.h
micropython.rc windows: Use the MicroPython logo as application icon. 2023-11-07 17:22:52 +11:00
micropython.vcxproj extmod/modmachine: Factor ports' machine module dict to common code. 2023-11-30 16:11:11 +11:00
mpconfigport.h windows: Implement MICROPY_INTERNAL_WFE() macro. 2023-12-08 12:49:54 +11:00
mpconfigport.mk windows: Add support for build variants to windows port. 2022-01-04 15:06:26 +11:00
realpath.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
realpath.h
sleep.h windows: Consolidate all sleep-related functions into windows_mphal.c. 2022-05-04 10:22:09 +10:00
windows_mphal.c ports: Fix sys.stdout.buffer.write() return value. 2023-12-22 10:32:46 +11:00
windows_mphal.h all: Update Makefiles and others to build with new ports/ dir layout. 2017-09-06 14:09:13 +10:00

README.md

This is the experimental, community-supported Windows port of MicroPython. It is based on Unix port, and expected to remain so. The port requires additional testing, debugging, and patches. Please consider to contribute.

All gcc-based builds use the gcc compiler from Mingw-w64, which is the advancement of the original mingw project. The latter is getting obsolete and is not actively supported by MicroPython.

Build instruction assume you're in the ports/windows directory.

Building on Debian/Ubuntu Linux system

sudo apt-get install python3 build-essential gcc-mingw-w64
make -C ../../mpy-cross
make CROSS_COMPILE=i686-w64-mingw32-

Building under Cygwin

Install Cygwin, then install following packages using Cygwin's setup.exe:

  • mingw64-i686-gcc-core
  • mingw64-x86_64-gcc-core
  • make
  • python3

Build using:

make -C ../../mpy-cross CROSS_COMPILE=i686-w64-mingw32-
make CROSS_COMPILE=i686-w64-mingw32-

Or for 64bit:

make -C ../../mpy-cross CROSS_COMPILE=x86_64-w64-mingw32-
make CROSS_COMPILE=x86_64-w64-mingw32-

Building under MSYS2

Install MSYS2 from http://repo.msys2.org/distrib, start the msys2.exe shell and install the build tools:

pacman -Syuu
pacman -S make mingw-w64-x86_64-gcc pkg-config python3

Start the mingw64.exe shell and build:

make -C ../../mpy-cross STRIP=echo SIZE=echo
make

Building using MS Visual Studio 2013 (or higher)

Install Python. There are several ways to do this, for example: download and install the latest Python 3 release from https://www.python.org/downloads/windows or from https://docs.conda.io/en/latest/miniconda.html, or open the Microsoft Store app and search for Python and install it.

Install Visual Studio and the C++ toolset (for recent versions: install the free Visual Studio Community edition and the Desktop development with C++ workload).

In the IDE, open micropython-cross.vcxproj and micropython.vcxproj and build.

To build from the command line:

msbuild ../../mpy-cross/mpy-cross.vcxproj
msbuild micropython.vcxproj

Variants

The msvc port supports variants (like the unix and windows mingw ports) and the one which gets built is controlled by the PyVariant msbuild property. It defaults to standard. The other variants can be built like:

msbuild micropython.vcxproj /p:PyVariant=dev

Or by adding a file Directory.build.props in this directory or a parent directory:

<Project>
  <PropertyGroup>
    <PyVariant>dev</PyVariant>
  </PropertyGroup>
</Project>

See paths.props for other related variables like build and variant directories.

Stack usage

The msvc compiler is quite stack-hungry which might result in a "maximum recursion depth exceeded" RuntimeError for code with lots of nested function calls. There are several ways to deal with this:

  • increase the threshold used for detection by altering the argument to mp_stack_set_limit in ports/unix/main.c
  • disable detection all together by setting MICROPY_STACK_CHECK to "0" in ports/windows/mpconfigport.h
  • disable the /GL compiler flag by setting WholeProgramOptimization to "false"

See issue 2927 for more information.

Running the tests

This is similar for all ports:

cd ../../tests
python ./run-tests.py

Though when running on Cygwin and using Cygwin's Python installation you'll need:

python3 ./run-tests.py

Depending on the combination of platform and Python version used it might be needed to first set the MICROPY_MICROPYTHON environment variable to the full path of micropython.exe.

Running on Linux using Wine

The default build (MICROPY_USE_READLINE=1) uses extended Windows console functions and thus should be ran using the wineconsole tool. Depending on the Wine build configuration, you may also want to select the curses backend which has the look&feel of a standard Unix console:

wineconsole --backend=curses ./build-standard/micropython.exe

For more info, see https://www.winehq.org/docs/wineusr-guide/cui-programs .

If built without line editing and history capabilities (MICROPY_USE_READLINE=0), the resulting binary can be run using the standard wine tool.

Generating the icon file

The windows builds use a .ico file for the executable logo. To generate such file from a .png file use ImageMagick, as was done for the icons in the logo/ directory:

magick convert vector-logo-2.png -define icon:auto-resize="256,128,96,64,48,32,16" vector-logo-2.ico

Note that for versions prior to 7.0 the command is convert instead of magick convert.