microsoft/IoT-For-Beginners

There are obstacles to building an environment for virtual single-board computer

mouseart opened this issue · 2 comments

mouseart commented

我们正在翻译这个文档的中文版本，所以测试都是在中文系统下进行。我用中文撰写了这个问题报告，并同步提供了英文翻译版本，也方便中文用户参考这个问题。
We are in the process of translating the Chinese version of this document, so the tests are conducted under the Chinese system. I wrote this problem report in Chinese and provided the English translation simultaneously to facilitate Chinese users to refer to this problem as well.

对这个链接的内容进行测试的时候，遇到一系列问题：
When testing the content of this link, a series of issues were encountered.
https://microsoft.github.io/IoT-For-Beginners/#/1-getting-started/lessons/1-introduction-to-iot/virtual-device

因为这个教程是给初学者使用，所以我邀请了没有太多编程经验的同事，分别在 Mac和在干净的Windows 10系统上，按照教程的步骤操作，但发现按现有的文档提示，他们根本无法顺利的完成。下面先说说我们遇到的问题：
Since this tutorial is for beginners, I invited colleagues with little programming experience to follow the steps of the tutorial on a Mac and on a clean Windows 10, but found that they simply could not complete it successfully by following the available documentation hints. Here are the issues we encountered first.

对于Mac 用户 For Mac users

开始都很顺利，但到了在 VS Code 键入 counterfit 的时候，看到了下面的错误：
It started out fine, but when it came to typing counterfit in VS Code, we saw the following error.

(.venv) (base) mouseart@LeondeMacBook-Pro nightlight % counterfit                                         
Traceback (most recent call last):
  File "/Users/mouseart/nightlight/.venv/bin/counterfit", line 5, in <module>
    from CounterFit.counterfit import main
  File "/Users/mouseart/nightlight/.venv/lib/python3.9/site-packages/CounterFit/counterfit.py", line 13, in <module>
    from flask import Flask, request, render_template
  File "/Users/mouseart/nightlight/.venv/lib/python3.9/site-packages/flask/__init__.py", line 19, in <module>
    from . import json
  File "/Users/mouseart/nightlight/.venv/lib/python3.9/site-packages/flask/json/__init__.py", line 15, in <module>
    from itsdangerous import json as _json
ImportError: cannot import name 'json' from 'itsdangerous' (/Users/mouseart/nightlight/.venv/lib/python3.9/site-packages/itsdangerous/__init__.py)

这个问题，我们请了有经验的程序员，找到了解决办法：
* 首先打开终端，键入：pip3 uninstall Flask pip3 uninstall markupsafe
* 然后安装 Flask==1.1.4 和 markupsafe==2.0.1 ，请忽视兼容性警告：pip3 install Flask==1.1.4
* pip3 install markupsafe==2.0.1
* 最后再次在 venv下运行 counterfit。

  • 如果出现 counterfit 默认端口（5000）被占用，请附加--port参数，例如：counterfit --port 8000
    这个方案，让我们 Mac 的用户能够正常运行了。

For this problem, we asked experienced programmers and found a solution:
* First open a terminal and type: pip3 uninstall Flask pip3 uninstall markupsafe
* Then install Flask==1.1.4 and markupsafe==2.0.1, please ignore the compatibility warning: pip3 install Flask==1.1.4
* pip3 install markupsafe==2.0.1
* Finally, run counterfit under venv again.

  • If it appears that the counterfit default port (5000) is occupied, append the --port parameter, for example: counterfit --port 8000
    This solution, allows our Mac users to run it properly now.

Windows 用户 Windows Users

Windows 用户测试遇到的问题最多，在激活 python 虚拟环境 上开始就遇到了障碍。第3步：激活虚拟环境，如果是 windows 终端 ，运行：.venv/Scripts/activate.bat，但会出现：
Windows users testing encountered the most problems, starting with a roadblock on activating the python virtual environment. Step 3: To activate the virtual environment, if it is a windows terminal , run: .venv/Scripts/activate.bat, but you will get:

C:\Users\LeonFeng\nightlight>.venv/scripts/activate.bat
'.venv' 不是内部或外部命令，也不是可运行的程序或批处理文件。

我们又尝试了 powershell ，输入：..venv\Scripts\Activate.ps1 的时候出现如下错误：
We tried powershell again, typing: . .venv\Scripts\Activate.ps1 with the following error:

PS C:\Users\LeonFeng\nightlight> .\.venv\Scripts\Activate.ps1
.\.venv\Scripts\Activate.ps1 : 无法将“.\.venv\Scripts\Activate.ps1”项识别为 cmdlet、函数、脚本文件或可运行程序的名称
。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。
所在位置 行:1 字符: 1
+ .\.venv\Scripts\Activate.ps1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : ObjectNotFound: (.\.venv\Scripts\Activate.ps1:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException

后来请了有经验的程序员，查出原因可能是在计算机上启动 Windows PowerShell 时，执行策略很可能是 Restricted（默认设置），这个执行策略不允许任何脚本运行。
修改方案是：以管理员身份打开 PowerShell （在底部导航栏 PowerShell 图标上点击鼠标右键，在弹出的菜单中选则：以管理员身份运行。）在管理员身份运行的 PowerShell 终端窗口中输入：set-executionpolicy remotesigned，然后按“Y”回答提示选择。
完成后再运行 ..venv\Scripts\Activate.ps1，才能顺利启动虚拟环境。
Later, I asked an experienced programmer and found out that the reason might be that when Windows PowerShell is started on the computer, the execution policy is probably Restricted (default setting), which does not allow any scripts to run.
The solution is to open PowerShell as administrator (right click on the PowerShell icon in the bottom navigation bar and select Run as administrator in the pop-up menu.) In the PowerShell Terminal window running as administrator, type: set-executionpolicy remotesigned and press "Y" to answer the prompt.
When finished, run . .venv\Scripts\Activate.ps1 to start the virtual environment successfully.

在解决这问题后，按提示安装 CounterFit 的 pip 包，
After resolving this issue, install the CounterFit pip package as prompted.
pip install CounterFit
pip install counterfit-connection
pip install counterfit-shims-grove

在 powershell 下运行这3个命令后，最后出现了一个错误：
After running these 3 commands under powershell, an error finally appears:

 C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.31.31103\bin\HostX86\x64\cl.exe /c /nologo /Ox /W3 /GL /DNDEBUG /MD -I/usr/include/libxml2 -IC:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.31.31103\include -IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt -IC:\Program Files (x86)\Windows Kits\10\\include\10.0.19041.0\\shared -IC:\Program Files (x86)\Windows Kits\10\\include\10.0.19041.0\\um -IC:\Program Files (x86)\Windows Kits\10\\include\10.0.19041.0\\winrt -IC:\Program Files (x86)\Windows Kits\10\\include\10.0.19041.0\\cppwinrt /TcC:\Users\LeonFeng\AppData\Local\Temp\xmlXPathInith4bs6u46.c /FoUsers\LeonFeng\AppData\Local\Temp\xmlXPathInith4bs6u46.obj
      xmlXPathInith4bs6u46.c
      C:\Users\LeonFeng\AppData\Local\Temp\xmlXPathInith4bs6u46.c(1): fatal error C1083: 无法打开包括文件: “libxml/xpath.h”: No such file or directory
      error: command 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Tools\\MSVC\\14.31.31103\\bin\\HostX86\\x64\\cl.exe' failed with exit code 2
      *********************************************************************************
      Could not find function xmlCheckVersion in library libxml2. Is libxml2 installed?
      *********************************************************************************
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> lxml

note: This is an issue with the package mentioned above, not pip.
hint: See above for output from the failure.
(.venv) PS C:\Users\LeonFeng\nightlight>

我们下载并安装了 Visual Studio，但还是不能解决问题，目前没有找到有效的解决方法，让项目继续进行，所以希望能得到帮助。
We have downloaded and installed Visual Studio, but still can't solve the problem, and we haven't found an effective solution to keep the project going, so help would be appreciated.

This tutorial is really well written, and it would be great if it solved these little problems.

jimbobbennett commented

macOS issues:

  • This is related to some incompatibilities with Python 3.10. Should be fixed in the latest version of CounterFit.

Windows problems:

  • You are right about the execution policy setting needed to be set to unrestricted. I'm updating the docs to include this.
  • The lxml issue is now fixed in the latest CounterFit
jimbobbennett commented

Docs are now updated, so closing this. Thanks for your feedback, and please let me know of any other issues.