Getting Started Guide enhancements for Windows

[blemouzy]

Summary

I followed the "Getting Started Guide" yesterday with several students (PCs running Windows, Mac OS, and Linux) and only students under Windows had problems.

I re-do the installation at home this morning under Windows 11, and here are the problems I encountered:

• I was not allowed to source Python virtualenv

  PS C:\Users\Benjamin\Documents\zephyr> .\.venv\Scripts\Activate.ps1
  .\.venv\Scripts\Activate.ps1 : Impossible de charger le fichier
  C:\Users\Benjamin\Documents\zephyr\.venv\Scripts\Activate.ps1, car l’exécution de scripts est désactivée sur ce
  système. Pour plus d’informations, consultez about_Execution_Policies à l’adresse
  https://go.microsoft.com/fwlink/?LinkID=135170.
  Au caractère Ligne:1 : 1
  + .\.venv\Scripts\Activate.ps1
  + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      + CategoryInfo          : Erreur de sécurité : (:) [], PSSecurityException
      + FullyQualifiedErrorId : UnauthorizedAccess
  

  Running

  Set-ExecutionPolicy Unrestricted -Scope Process
  

  solves the problem for the current PowerShell session

• git was not added in PATH after winget installation

  (.venv) PS C:\Users\Benjamin\Documents\zephyr> west init .
  FATAL ERROR: can't find git; install it or ensure it's on your PATH
  

• The Python version installed by winget was too old (Python 3.8):

  (.venv) PS C:\Users\Benjamin\Documents\zephyr> west packages pip --install
  Ignoring python-magic: markers 'sys_platform != "win32"' don't match your environment
  Collecting pyelftools>=0.29
    Using cached pyelftools-0.32-py3-none-any.whl (188 kB)
  Requirement already satisfied: PyYAML>=6.0 in c:\users\benjamin\documents\zephyr\.venv\lib\site-packages (from -r C:\Users\Benjamin\Documents\zephyr\zephyr\scripts\requirements-base.txt (line 11)) (6.0.3)
  Requirement already satisfied: pykwalify in c:\users\benjamin\documents\zephyr\.venv\lib\site-packages (from -r C:\Users\Benjamin\Documents\zephyr\zephyr\scripts\requirements-base.txt (line 14)) (1.8.0)
  Collecting canopen
    Using cached canopen-2.4.1-py3-none-any.whl (67 kB)
  Requirement already satisfied: packaging in c:\users\benjamin\documents\zephyr\.venv\lib\site-packages (from -r C:\Users\Benjamin\Documents\zephyr\zephyr\scripts\requirements-base.txt (line 18)) (25.0)
  Collecting progress
    Downloading progress-1.6.1-py3-none-any.whl (9.8 kB)
  ERROR: Could not find a version that satisfies the requirement patool>=2.0.0 (from versions: 1.7, 1.8, 1.9, 1.10, 1.11, 1.12)
  ERROR: No matching distribution found for patool>=2.0.0
  WARNING: You are using pip version 21.1.1; however, version 25.0.1 is available.
  You should consider upgrading via the 'c:\users\benjamin\documents\zephyr\.venv\scripts\python.exe -m pip install --upgrade pip' command.
  Traceback (most recent call last):
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\app\main.py", line 505, in run_command
      self.run_extension(args.command, argv)
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\app\main.py", line 654, in run_extension
      self.cmd.run(args, unknown, self.topdir, manifest=self.manifest,
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\commands.py", line 194, in run
      self.do_run(args, unknown)
    File "C:\Users\Benjamin\Documents\zephyr\zephyr\scripts\west_commands\packages.py", line 127, in do_run
      return self.do_run_pip(args, unknown[1:])
    File "C:\Users\Benjamin\Documents\zephyr\zephyr\scripts\west_commands\packages.py", line 160, in do_run_pip
      subprocess.check_call(
    File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.8_3.8.2800.0_x64__qbz5n2kfra8p0\lib\subprocess.py", line 364, in check_call
      raise CalledProcessError(retcode, cmd)
  subprocess.CalledProcessError: Command '['c:\\users\\benjamin\\documents\\zephyr\\.venv\\scripts\\python.exe', '-m', 'pip', 'install', '-r', WindowsPath('C:/Users/Benjamin/Documents/zephyr/zephyr/scripts/requirements.txt')]' returned non-zero exit status 1.
  
  During handling of the above exception, another exception occurred:
  
  Traceback (most recent call last):
    File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.8_3.8.2800.0_x64__qbz5n2kfra8p0\lib\runpy.py", line 194, in _run_module_as_main
      return _run_code(code, main_globals, None,
    File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.8_3.8.2800.0_x64__qbz5n2kfra8p0\lib\runpy.py", line 87, in _run_code
      exec(code, run_globals)
    File "C:\Users\Benjamin\Documents\zephyr\.venv\Scripts\west.exe\__main__.py", line 7, in <module>
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\app\main.py", line 1085, in main
      app.run(argv or sys.argv[1:])
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\app\main.py", line 244, in run
      self.run_command(argv, early_args)
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\app\main.py", line 542, in run_command
      self.cmd.err(f'command exited with status {cpe.returncode}: '
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\util.py", line 42, in quote_sh_list
      return ' '.join(shlex.quote(s) for s in cmd)
    File "c:\users\benjamin\documents\zephyr\.venv\lib\site-packages\west\util.py", line 42, in <genexpr>
      return ' '.join(shlex.quote(s) for s in cmd)
    File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.8_3.8.2800.0_x64__qbz5n2kfra8p0\lib\shlex.py", line 325, in quote
      if _find_unsafe(s) is None:
  TypeError: expected string or bytes-like object
  

  Forcing a more recent version (e.g. Python.Python.3.11) solves the issue.

• Some students also had issues during the west sdk install phase

  The message was something like wget no '--show-progress' option but I'm not able to reproduce it on my PC (Windows 10 only issue?).

Describe the solution you'd like

Update the Getting Started Guide for Windows

Alternatives

No response

Additional Context

No response

[sayoojkkarun]

I am facing the issue too! I will try to upgrade python and see.

[pdgendt]

I've opened #97538 to fix some of the issues mentioned here, PTAL.

• git was not added in PATH after winget installation

  (.venv) PS C:\Users\Benjamin\Documents\zephyr> west init .
  FATAL ERROR: can't find git; install it or ensure it's on your PATH
  

Was the terminal closed after installing the dependencies with winget?

• Some students also had issues during the west sdk install phase
  The message was something like wget no '--show-progress' option but I'm not able to reproduce it on my PC (Windows 10 only issue?).

Can you provide more details here? You can always open a new issue if you would run into this again.

[blemouzy]

I've opened #97538 to fix some of the issues mentioned here, PTAL.

Thanks!

• git was not added in PATH after winget installation

  (.venv) PS C:\Users\Benjamin\Documents\zephyr> west init .
  FATAL ERROR: can't find git; install it or ensure it's on your PATH
  

Was the terminal closed after installing the dependencies with winget?

I don't think so...

Do I need to re-open the PS to have an updated PATH?
Maybe this can be added to the doc?
Something like:
"Close the terminal window." --> "Open a new terminal window to have new installed tools in PATH."

• Some students also had issues during the west sdk install phase
  The message was something like wget no '--show-progress' option but I'm not able to reproduce it on my PC (Windows 10 only issue?).

Can you provide more details here? You can always open a new issue if you would run into this again.

No, sorry; I can't reproduce it on my PC.
I just noticed that some students had this error (and they had to follow v3.7 guide to manually install the SDK).

[pdgendt]

Was the terminal closed after installing the dependencies with winget?

I don't think so...

Do I need to re-open the PS to have an updated PATH? Maybe this can be added to the doc? Something like: "Close the terminal window." --> "Open a new terminal window to have new installed tools in PATH."

It's step 4 in the installation section (although not as elaborate):

4. Close the terminal window.

Can you provide more details here? You can always open a new issue if you would run into this again.

No, sorry; I can't reproduce it on my PC. I just noticed that some students had this error (and they had to follow v3.7 guide to manually install the SDK).

Hard to tell what could be wrong here, please open another issue if you see it again!