From 3061ab1dd78e36c2a71c647db6b441bfdf3bf614 Mon Sep 17 00:00:00 2001 From: iBug Date: Sat, 28 Sep 2024 16:23:08 +0800 Subject: [PATCH] Move vscode2vlab to tutorial/, adjust navigation --- docs/{ => tutorial}/vscode2vlab.md | 95 +++++++++++++++--------------- mkdocs.yml | 7 ++- 2 files changed, 53 insertions(+), 49 deletions(-) rename docs/{ => tutorial}/vscode2vlab.md (81%) diff --git a/docs/vscode2vlab.md b/docs/tutorial/vscode2vlab.md similarity index 81% rename from docs/vscode2vlab.md rename to docs/tutorial/vscode2vlab.md index 835ae86c..85e3655c 100644 --- a/docs/vscode2vlab.md +++ b/docs/tutorial/vscode2vlab.md @@ -10,19 +10,19 @@ icon: material/transit-connection-variant 在虚拟机的桌面上，最上面**应用程序**中的 **Vlab 实验软件**里可找到预先安装的的 Vivado，点击进入 Vivado。这里请大家选择 2019.1 版本，不要选择 2016.3 的旧版本。2023.1 版本的 Vivado 虽然更便捷，但可能引起内存不足的警告，因此请大家酌情使用。 -![vlab experiment tools](images/vscode2vlab/vivado1.png) +![vlab experiment tools](../images/vscode2vlab/vivado1.png) 进入 Vivado 后，点击 Create Project: -![Create Project](images/vscode2vlab/vivado2.png) +![Create Project](../images/vscode2vlab/vivado2.png) 然后点击 Next: -![Next](images/vscode2vlab/vivado3.png) +![Next](../images/vscode2vlab/vivado3.png) 在这个界面，你可以设置工程文件的名称和路径： -![Name Path](images/vscode2vlab/vivado4.png) +![Name Path](../images/vscode2vlab/vivado4.png) 随后一路 Next，直到遇到“选择开发板型号”的界面。搜索我们使用的开发板，型号为 `xc7a100tcsg324-1`，点击选择最下面的开发板。 @@ -32,11 +32,11 @@ icon: material/transit-connection-variant 若课程安排有所调整，请以实际课程要求开发板型号为准。 -![ChooseModel](images/vscode2vlab/vivado5.png) +![ChooseModel](../images/vscode2vlab/vivado5.png) 完成后，我们就成功新建了一个工程项目，可以看到如下界面： -![Finish](images/vscode2vlab/vivado6.png) +![Finish](../images/vscode2vlab/vivado6.png) ### 2. 新建设计文件 @@ -44,13 +44,13 @@ icon: material/transit-connection-variant 在界面左侧可以找到 Add Sources，点击它： -![Add Sources](images/vscode2vlab/vivado7.png) +![Add Sources](../images/vscode2vlab/vivado7.png) 接下来我们开始新建设计文件，点击 Next，选择 Create File: -![Next](images/vscode2vlab/vivado8.png) +![Next](../images/vscode2vlab/vivado8.png) -![Create File](images/vscode2vlab/vivado9.png) +![Create File](../images/vscode2vlab/vivado9.png) ??? question "如何把别处的源代码加入此工程项目？" @@ -62,11 +62,11 @@ icon: material/transit-connection-variant 我们可以自行设置新建文件的名称： -![Filename](images/vscode2vlab/vivado10.png) +![Filename](../images/vscode2vlab/vivado10.png) 这样，我们就完成了设计文件的新建。双击文件就可以在编辑器中编辑它了。 -![Finish](images/vscode2vlab/vivado11.png) +![Finish](../images/vscode2vlab/vivado11.png) ## 本地安装并配置 VSCode {#installvs} @@ -78,23 +78,23 @@ Visual Studio Code 是一款由微软开发的免费、轻量级且可扩展的 ### 1. 安装 VSCode -进入 VSCode 的[官方网站](https://code.visualstudio.com/)，点击 Download for Windows 下载。下载完成后打开可执行文件。在**选择附加任务**时建议全部勾选，特别是**添加到 PATH** 要勾选，否则后续还要自己将其添加到环境变量。 +进入 VSCode 的[官方网站](../https://code.visualstudio.com/)，点击 Download for Windows 下载。下载完成后打开可执行文件。在**选择附加任务**时建议全部勾选，特别是**添加到 PATH** 要勾选，否则后续还要自己将其添加到环境变量。 !!! info "注意" 为了 VSCode 使用的稳定性，安装路径不要包含中文。下面要讲的 ctags 和 iverilog 同理，安装路径也要避免中文。 -![Add to path](images/vscode2vlab/vscode1.png) +![Add to path](../images/vscode2vlab/vscode1.png) 在我们完成了 VSCode 的安装后，第一次打开时界面是纯英文，看起来不是很方便。对此我们可以找到左侧的 **Extensions** 点开，搜索 Chinese，安装第一个“中文（简体）”然后重启 VSCode 即可汉化 VSCode。 -![Chinese](images/vscode2vlab/vscode2.png) +![Chinese](../images/vscode2vlab/vscode2.png) ### 2. 安装 Verilog-HDL/SystemVerilog 插件 在汉化 VSCode 后，想必大家已经会在 VSCode 中搜索并安装插件了。对于 Verilog 的开发，我们需要安装 **Verilog-HDL/SystemVerilog** 插件。 -![Verilog-HDL](images/vscode2vlab/vscode3.png) +![Verilog-HDL](../images/vscode2vlab/vscode3.png) 这个插件提供了 Verilog 开发的大多数基础功能，包括： @@ -115,15 +115,15 @@ Visual Studio Code 是一款由微软开发的免费、轻量级且可扩展的 **Linter** 是自动检查源代码中是否存在编程和样式错误的工具。对于 Verilog 的 linter 当然不止一种，本教程中使用的是 iverilog。除此之外还有 xvlog 和 Verilator，但 xvlog 来自于 Vivado，你需要在电脑本地安装 Vivado 才有 xvlog。而 Verilator 则是面向 Linux 平台开发的，截至目前使用官网方法在 Windows 平台上编译的 Verilator 都无法配合 VSCode 完成代码检查，需要在子系统 WSL 中安装并运行 Verilator，这里不再介绍具体步骤。 -我们进入 iverilog 的[下载网站](https://bleyer.org/icarus/)，在 Download 中下载最新版本即可。安装时在 Select Components 界面全部勾选，然后勾选可执行文件所在文件夹加入用户路径。 +我们进入 iverilog 的[下载网站](../https://bleyer.org/icarus/)，在 Download 中下载最新版本即可。安装时在 Select Components 界面全部勾选，然后勾选可执行文件所在文件夹加入用户路径。 -![iverilog GTKWave](images/vscode2vlab/vscode4.png) +![iverilog GTKWave](../images/vscode2vlab/vscode4.png) -![iverilog Path](images/vscode2vlab/vscode5.png) +![iverilog Path](../images/vscode2vlab/vscode5.png) 安装后将 iverilog.exe 和 gtkwave.exe 所在文件夹的路径复制加入用户环境变量。 -![iverilog Environment](images/vscode2vlab/vscode6.png) +![iverilog Environment](../images/vscode2vlab/vscode6.png) !!! question "如何添加环境变量" @@ -157,11 +157,11 @@ gtkwave 弹出这个软件则配置成功。 -![gtkwave](images/vscode2vlab/vscode7.png) +![gtkwave](../images/vscode2vlab/vscode7.png) -接下来我们进入[下载页面](https://github.com/universal-ctags/ctags-win32/releases)安装 **ctags**，可选择最新版本进入下载。 +接下来我们进入[下载页面](../https://github.com/universal-ctags/ctags-win32/releases)安装 **ctags**，可选择最新版本进入下载。 -![ctags](images/vscode2vlab/vscode8.png) +![ctags](../images/vscode2vlab/vscode8.png) 安装后同样将 ctags.exe 所在文件夹路径复制加入环境变量。 @@ -179,11 +179,11 @@ ctags --version 按下面的设置配置 ctags，将 linter 选择为 iverilog，并在 iverilog 的 Argument 一栏中加入 -i 参数。 -![Extension Config](images/vscode2vlab/vscode9.png) +![Extension Config](../images/vscode2vlab/vscode9.png) -![Extension Config](images/vscode2vlab/vscode10.png) +![Extension Config](../images/vscode2vlab/vscode10.png) -![Extension Config](images/vscode2vlab/vscode11.png) +![Extension Config](../images/vscode2vlab/vscode11.png) !!! tip "关于配置的说明" @@ -191,7 +191,7 @@ ctags --version 这样我们就可以在 VSCode 中进行 Verilog 的开发了！ -![verilog](images/vscode2vlab/vscode12.png) +![verilog](../images/vscode2vlab/vscode12.png) !!! info "提示" @@ -204,9 +204,10 @@ Windows 用户应使用以下说明来安装和配置 OpenSSH。 在命令行中输入 `ssh`，若输出以下信息则已经安装，可跳过安装步骤。 -![ssh](images/vscode2vlab/SSH1.png) +![ssh](../images/vscode2vlab/SSH1.png) !!! info "Windows 10 和 Windows 11" + Windows 10 和 Windows 11 版本的 OpenSSH 安装有所区别，请按对应的版本进行操作。 在安装时， @@ -235,20 +236,21 @@ ssh ubuntu@vlab.ustc.edu.cn `Vlab username` 是你的学号（或工号），在登录虚拟机管理页面后可以在右上角看到。 - `Vlab password` 是 Vlab 平台的登录密码。[还没设置？](web.md#change-password) + `Vlab password` 是 Vlab 平台的登录密码。[还没设置？](../web.md#change-password) + +!!! question "Vlab 的登录用户名？" -!!! question "关于 Vlab 的登录用户？" - 这里请参考**虚拟机登录 -> SSH 命令行登录**页面的[登录用户名](login/ssh.md#username)章节。 + 这里请参考**SSH 命令行登录**页面的[登录用户名](../login/ssh.md#username)章节。 在断开与虚拟机的连接时输入 `exit` 即可。 -![ssh](images/vscode2vlab/SSH2.png) +![ssh](../images/vscode2vlab/SSH2.png) ### 2. 使用公钥登录虚拟机 使用公钥登录虚拟机可以免除每次输入密码的麻烦，我们首先要生成密钥对并下载到本地。 -这里下载密钥对的操作请参考**虚拟机登录 -> SSH 命令行登录**页面的[生成 SSH 密钥对并下载到本地](login/ssh.md#get-pubkey)章节。 +这里下载密钥对的操作请参考**SSH 命令行登录**页面的[生成 SSH 密钥对并下载到本地](../login/ssh.md#get-pubkey)章节。 我们将私钥放在 `%UserProfile%\.ssh` 目录中，例如 `%UserProfile%\.ssh\vlab.pem`。 @@ -264,17 +266,17 @@ ssh ubuntu@vlab.ustc.edu.cn 右键单击 `.pem` 文件，进入**属性 -> 安全 -> 高级**，可以看到以下界面。 -![permission](images/vscode2vlab/SSH3.png) +![permission](../images/vscode2vlab/SSH3.png) 然后将所有者改为个人用户（如果已经是则不用改），并且删除掉其他用户的权限（如果这里因为继承权限无法删除，则要先点击"禁用继承"）。如果在权限条目中没有个人用户，则需手动添加：在点击"添加"后点击"选择主体"，然后指定对象类型为"用户"，点击"高级"，开始立即查找，便可找到个人用户。将其权限设置为"完全控制"，确定添加即可。 -![adduser](images/vscode2vlab/SSH4.png) +![adduser](../images/vscode2vlab/SSH4.png) -![adduser](images/vscode2vlab/SSH5.png) +![adduser](../images/vscode2vlab/SSH5.png) 最后设置完毕如下： -![permission finish](images/vscode2vlab/SSH6.png) +![permission finish](../images/vscode2vlab/SSH6.png) 修改权限后，可以在 CMD 或 PowerShell 中使用 ssh 命令登录： @@ -304,38 +306,39 @@ Host vlab 接下来我们在 VSCode 中通过 SSH 登录 Vlab。首先在 VSCode 中安装扩展 **Remote - SSH**。 -![VSCode Extension SSH](images/vscode2vlab/vs_vlab1.png) +![VSCode Extension SSH](../images/vscode2vlab/vs_vlab1.png) 安装后在左侧会出现**远程资源管理器**。如果前面已经按照教程配置好了 SSH，可以看到我们的虚拟机 Vlab。 !!! info "注意" - 若还未配置好 SSH 请按照上面的教程进行 SSH 配置，实现公钥登录并完成配置文件。 + + 请先按照上面的教程进行 SSH 配置，实现公钥登录并完成配置文件。 点击 **vlab** 右侧的图标，在现有的窗口/新窗口中连接 Vlab。在选择远程平台时选择 **Linux**。 -![connect](images/vscode2vlab/vs_vlab2.png) +![connect](../images/vscode2vlab/vs_vlab2.png) 首次连接时会显示“正在下载 VSCode 服务器”。这是正在 Vlab 虚拟机上安装 VSCode 服务器，时间可能比较长，请耐心等待。 -![wait](images/vscode2vlab/vs_vlab3.png) +![wait](../images/vscode2vlab/vs_vlab3.png) 下载好后，左下角显示 **SSH:vlab** 即连接成功。 -![connection success](images/vscode2vlab/vs_vlab4.png) +![connection success](../images/vscode2vlab/vs_vlab4.png) 在上方的**文件->打开文件夹**即可选择要打开的 Vlab 上的文件夹，新建文件同理。 -![open file](images/vscode2vlab/vs_vlab5.png) +![open file](../images/vscode2vlab/vs_vlab5.png) 我们也可以用快捷键 **Ctrl + \`** 打开终端，此时的终端环境是 Vlab 的，可以通过命令行对 Vlab 进行操作。 -![Terminal](images/vscode2vlab/vs_vlab6.png) +![Terminal](../images/vscode2vlab/vs_vlab6.png) ## 本地 VSCode 编辑 Vlab 的 Verilog 项目 {#Vlab-verilog} 截至目前，我们已经能用本地 VSCode 远程编辑 Vlab 上的文件了。但当我们用 VSCode 打开 Vlab 中新建的 `.v` 文件时，却发现没有了语法高亮。这是因为 Verilog-HDL/SystemVerilog 扩展被定义为在远程扩展主机中运行，故在此工作区中被禁用。我们需要在本地已安装的扩展中找到 Verilog-HDL/SystemVerilog，点击**在 SSH:vlab 中安装**，来启用该扩展。 -![Vlab Extention](images/vscode2vlab/vs_vlab7.png) +![Vlab Extention](../images/vscode2vlab/vs_vlab7.png) 然后我们的 Verilog 代码就有了语法高亮。但当我们编写代码时，会发现前面配置好的 ctags 和 iverilog 失效了：鼠标悬停不显示代码声明，“CTRL 鼠标点击跳转到代码声明”的功能失效，代码的语法错误也不会报错。 @@ -351,8 +354,8 @@ sudo apt install iverilog gtkwave universal-ctags 然后在 VSCode 已打开的远程连接 Vlab 中打开 Verilog-HDL/SystemVerilog 的扩展设置，将**远程 [SSH:vlab]**和**工作区**中同[本地配置](#config-extension)（即“用户”一栏中的配置）进行设置。 -![Config Extention](images/vscode2vlab/vs_vlab8.png) +![Config Extention](../images/vscode2vlab/vs_vlab8.png) 完成后，我们就可以在本地 VSCode 对 Vlab 中的 Vivado 设计文件进行编辑了！ -![finish](images/vscode2vlab/vs_vlab9.png) +![finish](../images/vscode2vlab/vs_vlab9.png) diff --git a/mkdocs.yml b/mkdocs.yml index a65b1e16..c24b9d89 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,12 +55,12 @@ extra_css: markdown_extensions: - admonition - attr_list - - codehilite - footnotes - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight - pymdownx.mark - pymdownx.tabbed: alternate_style: true @@ -73,7 +73,6 @@ markdown_extensions: nav: - 简介: index.md - 快速开始: quickstart.md - - 本地 VSCode 远程连接 Vlab: vscode2vlab.md - 虚拟机: - 虚拟机管理: web.md - 虚拟机登录: @@ -87,6 +86,9 @@ nav: - 应用程序: - 在线 VSCode: apps/vscode.md - RISC-V 工具链: apps/riscv.md + - 教程: + - 本地 VSCode 远程连接 Vlab: tutorial/vscode2vlab.md + - Git 简明教程: tutorial/git.md - 其他: - 常见问题: faq.md - 通知公告: announcements.md @@ -100,4 +102,3 @@ nav: - 资源下载: downloads.md - 致谢: credits.md - 招新: recruit.md - - Git 简明教程: tutorial/git.md