diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/getting_started_vagrant.md | 56 | ||||
| -rw-r--r-- | docs/ja/_summary.md | 1 | ||||
| -rw-r--r-- | docs/ja/getting_started_vagrant.md | 61 | ||||
| -rw-r--r-- | docs/zh-cn/_summary.md | 3 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_vagrant.md | 61 |
6 files changed, 1 insertions, 182 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 01808bd675..ce579cb071 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -41,7 +41,6 @@ * [Keymap Overview](keymap.md) * Development Environments * [Docker Guide](getting_started_docker.md) - * [Vagrant Guide](getting_started_vagrant.md) * Flashing * [Flashing](flashing.md) * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md deleted file mode 100644 index b5b5ce1539..0000000000 --- a/docs/getting_started_vagrant.md +++ /dev/null @@ -1,56 +0,0 @@ -# Vagrant Quick Start - -This project includes a `Vagrantfile` that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter. - -## Requirements - -Using the `Vagrantfile` in this repository requires you have [Vagrant](https://www.vagrantup.com/) as well as a supported provider installed: - -* [VirtualBox](https://www.virtualbox.org/) (Version at least 5.0.12) - * Sold as 'the most accessible platform to use Vagrant' -* [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](https://www.vagrantup.com/vmware) - * The (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion -* [Docker](https://www.docker.com/) - -Other than having Vagrant, a suitable provider installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start an environment (either a virtual machine or container) that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below. - -## Flashing the Firmware - -The "easy" way to flash the firmware is using a tool from your host OS: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended) -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) - -If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version. - -## Vagrantfile Overview -The development environment is configured to run the QMK Docker image, `qmkfm/qmk_cli`. This not only ensures predictability between systems, it also mirrors the CI environment. - -## FAQ - -### Why am I seeing issues under Virtualbox? -Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** - -``` -vagrant plugin install vagrant-vbguest -``` - -### How do I remove an existing environment? -Finished with your environment? From anywhere inside the folder where you checked out this project, Execute: - -``` -vagrant destroy -``` - -### What if I want to use Docker directly? -Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker: -``` -vagrant up --provider=docker -``` - -### How do I access the virtual machine instead of the Docker container? -Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image: - -``` -vagrant ssh -c 'sudo -i' -``` diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 8516a5eaaa..e49853bfd4 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -38,7 +38,6 @@ * [キーマップの概要](ja/keymap.md) * 開発環境 * [Docker のガイド](ja/getting_started_docker.md) - * [Vagrant のガイド](ja/getting_started_vagrant.md) * 書き込み * [書き込み](ja/flashing.md) * [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md) diff --git a/docs/ja/getting_started_vagrant.md b/docs/ja/getting_started_vagrant.md deleted file mode 100644 index 0888b7f311..0000000000 --- a/docs/ja/getting_started_vagrant.md +++ /dev/null @@ -1,61 +0,0 @@ -# Vagrant クイックスタート - -<!--- - original document: 0.12.43:docs/getting_started_vagrant.md - git diff 0.12.43 HEAD -- docs/getting_started_vagrant.md | cat ---> - -このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる `Vagrantfile` を含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、ビルドのために Vagrantfile を使っている他のユーザと全く同じ環境を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。 - -## 必要事項 - -このリポジトリ内の `Vagrantfile` を使うには、[Vagrant](https://www.vagrantup.com/) およびサポートされるプロバイダがインストールされている必要があります: - -* [VirtualBox](https://www.virtualbox.org/) (バージョン 5.0.12 以降) - * 「Vagrant を使うために最もアクセスしやすいプラットフォーム」とうたわれています。 -* [VMware Workstation](https://www.vmware.com/products/workstation) および [Vagrant VMware プラグイン](https://www.vagrantup.com/vmware) - * (有料) VMware プラグインには、ライセンスされた VMware Workstation/Fusion のコピーが必要です。 -* [Docker](https://www.docker.com/) - -Vagrant 以外に、適切なプロバイダがインストールされ、その後におそらくコンピュータを再起動すると、このプロジェクトをチェックアウトしたフォルダ内の任意の場所で 'vagrant up' を単純に実行することができ、このプロジェクトをビルドするのに必要な全てのツールが含まれる環境(仮想マシンあるいはコンテナ)が開始されます。Vagrant 起動時にうまく始めるためのヒントが表示されますが、それ以外に、以下のビルドドキュメントを参照することもできます。 - -## ファームウェアの書き込み - -ファームウェアを書き込む「簡単な」方法は、ホスト OS からツールを使うことです: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (推奨) -* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html) - -コマンドラインでプログラムしたい場合は、Vagranfile の ['modifyvm'] 行のコメントを解除して Linux への USB パススルーを有効にし、dfu-util/dfu-programmer のようなコマンドラインツールを使ってプログラムすることができます。あるいは Teensy CLI バージョンをインストールすることができます。 - -## Vagrantfile の概要 -開発環境は QMK Docker イメージ、`qmkfm/qmk_cli` を実行するように設定されています。これはシステム間の予測可能性が保証されるだけでなく、CI 環境もミラーされます。 - -## FAQ - -### Virtualbox で問題が発生するのはなぜですか？ -Virtualbox 5 の特定のバージョンはこの Vagrantfile のボックスにインストールされている Virtualbox の拡張機能と互換性が無いようです。/vagrant のマウントで問題が発生した場合は、Virtualbox のバージョンを少なくとも 5.0.12 にアップグレードしてください。**または、以下のコマンドを実行してみることができます:** - -```console -vagrant plugin install vagrant-vbguest -``` - -### 既存の環境を削除するにはどうすればいいですか？ -あなたの環境での作業が完了しましたか？このプロジェクトをチェックアウトしたフォルダの中のどこからでも、以下を実行してください: - -```console -vagrant destroy -``` - -### Docker を直接使いたい場合はどうしますか？ -仮想マシン無しで Vagrant のワークフローを活用したいですか？Vagrantfile は仮想マシンの実行をバイパスし、コンテナを直接実行するように設定されています。Docker を強制的に使うように環境を立ち上げる場合は、以下を実行してください: -```console -vagrant up --provider=docker -``` - -### Docker コンテナではなく仮想マシンにアクセスするにはどうすればいいですか？ -以下を実行して、公式の QMK ビルダーイメージから直接起動する `vagrant` ユーザをバイパスするようにします: - -```console -vagrant ssh -c 'sudo -i' -``` diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index 3baee6dc2e..b8c26ac275 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -42,7 +42,6 @@ * [键映射总览](zh-cn/keymap.md) * 开发环境 * [Docker指南](zh-cn/getting_started_docker.md) - * [Vagrant指南](zh-cn/getting_started_vagrant.md) * 刷写(Flashing) * [刷写](zh-cn/flashing.md) * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md) @@ -188,5 +187,5 @@ * [Midi辅助功能](zh-cn/internals/midi_util.md) * [发送函数](zh-cn/internals/send_functions.md) * [Sysex工具](zh-cn/internals/sysex_tools.md) - + <!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59--> diff --git a/docs/zh-cn/getting_started_vagrant.md b/docs/zh-cn/getting_started_vagrant.md deleted file mode 100644 index 5e5de44552..0000000000 --- a/docs/zh-cn/getting_started_vagrant.md +++ /dev/null @@ -1,61 +0,0 @@ -# Vagrant快速上手指引 - -<!--- - original document: 0.15.12:docs/getting_started_vagrant.md - git diff 0.15.12 HEAD -- docs/getting_started_vagrant.md | cat ---> - -本工程包含一份 `Vagrantfile`，可以方便地在不更改你系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与也使用Vagrantfile的其它人的一致。当你需要其他人协助你排查遇到的问题时会方便很多。 - -## 需求 - -本工程中的 `Vagrantfile` 需要安装[Vagrant](https://www.vagrantup.com/)以及可用的虚拟机服务： - -* [VirtualBox](https://www.virtualbox.org/) (5.0.12及以后版本) - * 卖点是'最适用于Vagrant的平台' -* [VMware Workstation](https://www.vmware.com/products/workstation) 及 [Vagrant VMware插件](https://www.vagrantup.com/vmware) - * （付费购买的）VMware插件需要在经过正版授权的VMware Workstation/Fusion上运行 -* [Docker](https://www.docker.com/) - -安装了Vagrant之后，在安装合适的虚拟机服务后可能需要重启机器。拉取本工程后在工程目录下执行 'vagrant up' 将启动一个包含了所有本工程所需工具的构建环境（虚拟机或是容器）。最后会有一个vagrant启动提示告知你一切正常就绪，否则你也可以参考一下下面的构建文档。 - -## 刷写固件 - -比较“简单”的方案是在你的宿主系统上借助以下工具刷写固件： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox) (推荐) -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) - -如果你希望通过命令行进行编程工作，可以在Vagrantfile中取消掉['modifyvm']的注释以允许USB直通到Linux环境，既可以使用dfu-util/dfu-programmer之类的命令行工具进行编程工作，或是安装Teensy的命令行版本。 - -## Vagrantfile概览 -开发环境被配置为运行QMK Docker镜像 `qmkfm/qmk_cli`，不仅让各系统下的功能预期一致，也是我们CI环境的镜像。 - -## FAQ - -### 为什么我的VirtualBox环境会有问题？ -VirtualBox 5的某些版本与工程中Vagrantfile中指定的VirtualBox扩展存在兼容问题。如果你遇到了/vagrant挂载不成功的问题，请升级VirtualBox至5.0.12或更高版本。**或者，可以尝试执行如下命令：** - -```console -vagrant plugin install vagrant-vbguest -``` - -### 如何移除一个现有环境？ -不再需要这个环境了是吗？在本工程目录下的任何位置，执行： - -```console -vagrant destroy -``` - -### 如果我是想直接用Docker呢？ -想在不使用虚拟机技术的情况下也能使用Vagrant工作流？Vagrangfile已配置为允许绕过运行虚拟机，直接运行容器。通过如下方式执行命令可以强制使用Docker来启动环境： -```console -vagrant up --provider=docker -``` - -### 如何访问虚拟机环境而非Docker容器？ -通过如下方法跳过 `vagrant` 的用户初始化过程以在QMK构建镜像中直接执行： - -```console -vagrant ssh -c 'sudo -i' -``` |