diff --git a/docs/zh-cn/other_eclipse.md b/docs/zh-cn/other_eclipse.md new file mode 100644 index 0000000000..d0783c2070 --- /dev/null +++ b/docs/zh-cn/other_eclipse.md @@ -0,0 +1,90 @@ +# 在Eclipse中设置QMK开发环境 + + + + +[Eclipse][1]是一款广泛用于Java开发的[集成开发环境](https://en.wikipedia.org/wiki/Integrated_development_environment)（IDE），但有着强大的插件体系允许自定义开发其它语言及用途。 + +相对于使用普通的文本编辑器，使用形如Eclipse这样的IDE有着诸多好处，例如： +* 智能代码补全 +* 快速代码跳转 +* 重构工具 +* 构建自动化（无需使用命令行） +* 图形化交互的GIT +* 静态代码分析 +* 以及大量其它工具，如调试器，代码格式化，显示调用链等。 + +本文专注于阐述如何将Eclipse配置为AVR软件开发环境，并用于基于QMK代码的开发工作。 + +注意，在本文编写时，仅在Ubuntu 16.04环境中进行过验证。 + +# 需求 +## 构建环境 +在开始之前，你需要确保遵循了新手教程中的[新手指引](zh-cn/newbs_getting_started.md)一节。通常，此时你应该具备了[通过 `qmk complile` 命令](zh-cn/newbs_building_firmware.md#build-your-firmware)构建固件文件的能力。 + +## Java +Eclipse为Java程序，因此需要安装Java 8或更高版本才能运行。你可以选择JRE或JDK，后者在进行Java开发时需要用到。 + +# 安装Eclipse及插件 +Eclipse有[多种可选安装方式](https://www.eclipse.org/downloads/eclipse-packages/)，取决于你的使用目标。目前没有完备的AVR开发栈安装包，所以我们需要从Eclipse CDT（C/C++ 开发工具环境）开始并安装对应的插件。 + +## 下载安装Eclipse CDT +如果系统中已安装了Eclipse CDT，可以跳过本步骤。同时，为了确保版本支持情况，我们推荐保持其更新至最新版。 + +如果你已安装了Eclipse包，通常也可以[在上面再安装CDT插件](https://eclipse.org/cdt/downloads.php)。但是可能更好的方案是重新全新安装一下，以确保环境轻量，以及防止已安装的工具对后续的工程开发工作产生干扰。 + +安装很简单：遵循[Eclipse安装5步走](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE)，并在第三步选择 **用于C/C++开发者的Eclipse IDE（Eclipse IDE for C/C++ Developers）**。 + +此外，也可以选择直接[下载 用于C/C++开发者的Eclipse IDE](https://www.eclipse.org/downloads/eclipse-packages/)（[最新版直达链接](https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)）并解压至任意目录下（会生成 `eclipse` 目录）。 + +## 首次运行 +在安装完毕后，点击运行按钮。（如果是手动解压的，请在安装目录下双击 `eclipse` 可执行程序 + +在提示你选择工作区目录时，选择一个可用于存储Eclipse元数据及工程的目录。**不要选择 `qmk_firmware` 目录**，这是你的项目目录。可以使用其父目录，或其它（最好是空）目录（默认目标目录如果未作他用亦可使用）。 + +启动后，点击右上角的工作台（Workbench）按钮切换到工作台视图（启动时的欢迎页最下方有个确认框可以在下次启动时不再展示欢迎页）。 + +## 安装必要的插件 +注意：无需在每个插件安装完成时重启Eclipse，全部安装完毕后重启一次即可。 + +### [AVR插件](https://avr-eclipse.sourceforge.net/) +这是最重要的一个插件，可以帮助Eclipse理解AVR下的C语言代码。参照执行[更新网址使用指引](https://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site)，并允许那些未签名内容产生的警告。 + +### [ANSI Escape in Console（命令行下的ANSI转义符）](https://marketplace.eclipse.org/content/ansi-escape-console) +该插件可以允许QMK makefile产生的具有颜色标记的构建输出信息能够正确显示。 + +1. 打开帮助 > Eclipse插件市场… +2. 搜索_ANSI Escape in Console_ +3. 点击插件的安装按钮 +4. 跟随安装指引并再次允许那些未签名的内容产生的警告。 + +在插件皆安装完毕后，依照提示重启Eclipse。 + +# 配置Eclipse QMK环境 +## 导入工程 +1. 点击文件 > 新建 > 现有的Makefile工程代码 +2. 在之后这一页中： + * 选择仓库所克隆到的目录位置作为 _现有代码位置_； + * （可选地）指定一个不同的工程名，如 _QMK_ 或 _Quantum_ ； + * 选择 _AVR-GCC Toolchain_; + * 其它选项保留不动，点击完成 + + ![Importing QMK in Eclipse](https://i.imgur.com/oHYR1yW.png) + +3. 工程即完成加载及分析，其下的文件可以方便地在左侧的 _Project Explorer_ 中查看了。 + +¹ 导入工程时若自定义名称有时会遇到些问题，如果行不通，保留默认的工程名（即目录名，通常是 `qmk_firmware`）再试一次。 + +## 构建你的键盘 + +我们将默认构建目标从 `all` 调整到我们期望构建的键盘及键映射组合上，即 `kinesis/kint36:stapelberg`。此时，形如清理、构建等工程级别的操作可以很快地执行完毕，而不至于耗费大量时间且导致Eclipse卡住。 + +1. 焦点置于工程下的任一编辑器tab中 +2. 打开`工程` > `属性`窗口， 选择 `C/C++构建` 菜单项并切至 `Behavior` 标签。 +3. 将 `Make build target`选项中的全量构建 `all` 改为 `kinesis/kint41:stapelberg`。 +4. 点击 `工程` > `清理...` 以确认配置正确。 + + [1]: https://en.wikipedia.org/wiki/Eclipse_(software) diff --git a/docs/zh-cn/other_vscode.md b/docs/zh-cn/other_vscode.md new file mode 100644 index 0000000000..e4bca0711c --- /dev/null +++ b/docs/zh-cn/other_vscode.md @@ -0,0 +1,122 @@ +# 在Visual Studio Code中设置QMK开发环境 + + + +[Visual Studio Code](https://code.visualstudio.com/) (VS Code) 是一款支援非常多种不同编程语言的开源编辑器。 + +相比于使用简陋的文本编辑器，形如VS Code这样的多功能编辑器有诸多优势，比如： +* 智能的代码补全 +* 便捷的代码导航 +* 重构工具 +* 自动化构建支持（不再需要命令行操作） +* 图形化的GIT界面 +* 调试器、代码格式化、显示调用层级等多种工具 + +本章节旨在阐述如何配置VS Code以在其上进行QMK固件开发。 + +这份指引提供了在Windows及Ubuntu 18.04下所有的配置方法。 + +# 配置VS Code +一开始，你需要首先确认所有的构建工具已经安装配置完成，且QMK Firmware仓库已拷贝至本地。前往参阅[新人指引](zh-cn/newbs_getting_started.md)确保已完成初始配置。 + +## Windows + +### 依赖项 + +* [Git for Windows](https://git-scm.com/download/win) (该链接会自动提示你保存或运行安装包) + + 1. 除 `Git LFS (Large File Support)（大文件支援）` 及 `Check daily for Git for Windows updates（每天检查更新）` 外取消所有可选项。 + 2. 将默认编辑器改为 `Use Visual Studio Code as Git's default editor（将VS Code作为默认编辑器）` + 3. 选择 `Use Git from Git Bash only（仅在Git Bash中使用Git）`，这是应使用的方案。 + 4. 在 `Choosing HTTPS transport backend（选择HTTPS传输服务）` 选项上，皆可。 + 5. 选择 `Checkout as-is, commit Unix-style line endings（检出不作更改，提交时使用Unix风格换行符）`，QMK仓库使用的是Unix style提交。 + 6. 在额外选项页，保持默认选择即可。 + + 该软件是VS Code支持Git的所需项目，是有可能不去使用它，但直接用它会省很多事。 + +* [Git Credential Manager for Windows（Windows版Git凭据管理器）](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) （可选） + + 该软件提供了更好的git 凭据加密存储、多因素身份认证（MFA）及私有访问token生成器。 + + 这个不是严格必须的，但我们依旧推荐使用。 + + +### 安装VS Code + +1. 到[VS Code](https://code.visualstudio.com/)下载安装包 +2. 运行安装包 + +很简单的操作。然而，仍有一些配置我们需要确保是设置正确的。 + +### VS Code设置 + +首先来配置IntelliSense，虽不是严格必要的，但能让你后续使用便捷**很多**。首先，在QMK Firmware目录下创建文件 `.vscode/c_cpp_properties.json`，之后的操作可以手动完成，但我已经完成了大部分。 + +获取[这份文件](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8)，如果你的MSYS2没有安装在默认路径，或在用WSL/LxSS，你可能需要做一下编辑修改。 + +在保存妥当后，如果你有已打开的VS Code，你需要reload一下。 + +?> 在 `.vscode` 目录下你应该还能看到 `extensions.json` 和 `settings.json` 文件。 + +现在，我们配置MSYS2作为VSCode的集成终端。这么做有很多好处，最主要的是可以通过按住control点击错误消息直接跳转到文件，调试起来会简单得多，另外的好处是，你不用在窗口间切换。 + +1. 点击 文件 > 首选项 > > 设置 +2. 点击上方右侧的 {} 按钮，打开 `settings.json` 文件。 +3. 将文件改为： + + ```json + { + "terminal.integrated.profiles.windows": { + "QMK_MSYS": { + "path": "C:/QMK_MSYS/usr/bin/bash.exe", + "env": { + "MSYSTEM": "MINGW64", + "CHERE_INVOKING": "1" + }, + "args": ["--login"] + } + }, + + "terminal.integrated.cursorStyle": "line" + } + ``` + + 如果该文件内已经有一些配置项，将上面的内容粘贴在最外层的花括号内，并用一个逗号将新旧内容分隔开。 + +?> 如果你的MSYS2安装在不同的目录下，你需要将 `terminal.integrated.shell.windows` 更改为你系统中正确的目录。 + +4. 点击Ctrl-` (Grave) 或在 视图 > 终端 可以打开终端界面 (`workbench.action.terminal.toggleTerminal` 命令)。如果没有终端它会自动打开一个。 + + 终端应启动于工程目录中（即 `qmk_firmware` 目录），之后你可以构建键盘了。 + + +## 其它系统 + +1. 到[VS Code](https://code.visualstudio.com/)下载安装包 +2. 运行安装包 +3. 搞定 + +是的，确实是搞定了。安装的时候所有所需的路径配置都会被包含进来，在检查当前工程文件并进行IntelliSense解析上表现也会更好。 + +## 插件 + +有一些你可能感兴趣的扩展可以安装： + +* [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) - 提供了一系列的Git工具可以让你在QMK Firmware中使用Git便捷一些。 +* [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[可选]_ - 可以让你的代码更符合QMK规范。 +* [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2) - _[可选]_ - 可以给大括号着色，可以更好地阅读嵌套代码。 +* [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[可选]_ - 使得VS Code下的markdown预览更符合Github的效果。 +* [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[可选]_ - 这个扩展允许他人访问你的工作区（或反之）进行协作，在你遇到问题需要他人帮助时挺有用。 +* [VIM Keymap](https://marketplace.visualstudio.com/items?itemName=GiuseppeCesarano.vim-keymap) - _[可选]_ - 为那些更喜欢VIM风格的按键操作的人所准备。这样的扩展还有挺多。 + +安装扩展后需要重启VS Code。 + +# 配置VS Code下的QMK +1. 点击 文件 > 打开目录 +2. 打开你从Github克隆的QMK固件仓库所在目录。 +3. 点击 文件 > 保存工作区为... + +此时你已完成了在VS Code下编写QMK固件的准备工作。