mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-04-04 21:05:41 +00:00
Merge remote-tracking branch 'origin/develop' into xap
This commit is contained in:
QMK Bot
commit
aa6881b8c6
1
.gitignore
vendored
1
.gitignore
vendored
@ -45,7 +45,6 @@ quantum/version.h
|
||||
.idea/
|
||||
.project
|
||||
.settings/
|
||||
.vagrant/
|
||||
|
||||
# ?
|
||||
.dep
|
||||
|
||||
95
Vagrantfile
vendored
95
Vagrantfile
vendored
@ -1,95 +0,0 @@
|
||||
# -*- mode: ruby -*-
|
||||
# vi: set ft=ruby :
|
||||
|
||||
Vagrant.configure(2) do |config|
|
||||
# define a name instead of just 'default'
|
||||
config.vm.define "qmk_firmware"
|
||||
|
||||
# VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
|
||||
config.vm.box = "generic/debian10"
|
||||
|
||||
config.vm.synced_folder '.', '/vagrant'
|
||||
|
||||
# This section allows you to customize the Virtualbox VM
|
||||
# settings, ie showing the GUI or upping the memory
|
||||
# or cores if desired
|
||||
config.vm.provider "virtualbox" do |vb|
|
||||
# Hide the VirtualBox GUI when booting the machine
|
||||
vb.gui = false
|
||||
# Uncomment the below lines if you want to program
|
||||
# your Teensy via the VM rather than your host OS
|
||||
#vb.customize ['modifyvm', :id, '--usb', 'on']
|
||||
#vb.customize ['usbfilter', 'add', '0',
|
||||
# '--target', :id,
|
||||
# '--name', 'teensy',
|
||||
# '--vendorid', '0x16c0',
|
||||
# '--productid','0x0478'
|
||||
# ]
|
||||
# Customize the amount of memory on the VM:
|
||||
vb.memory = "512"
|
||||
# Uncomment the below lines if you have time sync
|
||||
# issues with make and incremental builds
|
||||
#vb.customize [ "guestproperty", "set", :id, "/VirtualBox/GuestAdd/VBoxService/--timesync-set-threshold", 1000 ]
|
||||
end
|
||||
|
||||
# This section allows you to customize the VMware VM
|
||||
# settings, ie showing the GUI or upping the memory
|
||||
# or cores if desired
|
||||
config.vm.provider "vmware_workstation" do |vmw|
|
||||
# Hide the VMware GUI when booting the machine
|
||||
vmw.gui = false
|
||||
|
||||
# Customize the amount of memory on the VM:
|
||||
vmw.memory = "512"
|
||||
end
|
||||
|
||||
config.vm.provider "vmware_fusion" do |vmf|
|
||||
# Hide the vmfare GUI when booting the machine
|
||||
vmf.gui = false
|
||||
|
||||
# Customize the amount of memory on the VM:
|
||||
vmf.memory = "512"
|
||||
end
|
||||
|
||||
# Docker provider pulls from hub.docker.com respecting docker.image if
|
||||
# config.vm.box is nil. In this case, we adhoc build util/vagrant/Dockerfile.
|
||||
# Note that this bind-mounts from the current dir to
|
||||
# /vagrant in the guest, so unless your UID is 1000 to match vagrant in the
|
||||
# image, you'll need to: chmod -R a+rw .
|
||||
config.vm.provider "docker" do |docker, override|
|
||||
override.vm.box = nil
|
||||
docker.build_dir = "util/vagrant"
|
||||
docker.has_ssh = true
|
||||
end
|
||||
|
||||
# Unless we are running the docker container directly
|
||||
# 1. run container detached on vm
|
||||
# 2. attach on 'vagrant ssh'
|
||||
["virtualbox", "vmware_workstation", "vmware_fusion"].each do |type|
|
||||
config.vm.provider type do |virt, override|
|
||||
override.vm.provision "docker" do |d|
|
||||
d.run "qmkfm/qmk_cli",
|
||||
cmd: "tail -f /dev/null",
|
||||
args: "--privileged -v /dev:/dev -v '/vagrant:/vagrant'"
|
||||
end
|
||||
|
||||
override.vm.provision "shell", inline: <<-SHELL
|
||||
echo 'docker restart qmkfm-qmk_cli && exec docker exec -it qmkfm-qmk_cli /bin/bash -l' >> ~vagrant/.bashrc
|
||||
SHELL
|
||||
end
|
||||
end
|
||||
|
||||
config.vm.post_up_message = <<-EOT
|
||||
|
||||
Log into the environment using 'vagrant ssh'. QMK directory synchronized with
|
||||
host is located at /vagrant
|
||||
To compile the .hex files use make command inside this directory, e.g.
|
||||
cd /vagrant
|
||||
make <keyboard>:default
|
||||
|
||||
Examples:
|
||||
make planck/rev4:default:dfu
|
||||
make planck/rev4:default
|
||||
|
||||
EOT
|
||||
end
|
||||
@ -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)
|
||||
|
||||
@ -34,7 +34,7 @@ The next Breaking Change is scheduled for May 28, 2023.
|
||||
|
||||
## What changes will be included?
|
||||
|
||||
To see a list of breaking changes merge candidates you can look at the [`core` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Acore+is%3Apr). This label is applied whenever a PR is raised or changed, but only if the PR includes changes to core areas of QMK Firmware. A PR with that label applied is not guaranteed to be merged in the current cycle. New changes might be added between now and when `develop` is closed, and it is generally the responsibility of the submitter to handle conflicts. There is also another label used by QMK Collaborators -- `breaking_change_YYYYqN` -- which signifies to maintainers that it is a strong candidate for inclusion, and should be prioritised for review.
|
||||
To see a list of breaking changes merge candidates you can look at the [`core` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Acore+is%3Apr). This label is applied whenever a PR is raised or changed, but only if the PR includes changes to core areas of QMK Firmware. A PR with that label applied is not guaranteed to be merged in the current cycle. New changes might be added between now and when `develop` is closed, and it is generally the responsibility of the submitter to handle conflicts. There is also another label used by QMK Collaborators -- `breaking_change_YYYYqN` -- which signifies to maintainers that it is a strong candidate for inclusion, and should be prioritized for review.
|
||||
|
||||
If you want your breaking change to be included in this round you need to create a PR and have it accepted by QMK Collaborators before `develop` closes. After `develop` closes, new submissions will be deferred to the next breaking changes cycle.
|
||||
|
||||
@ -127,12 +127,12 @@ This happens immediately after the previous `develop` branch is merged to `maste
|
||||
* Validate each submodule SHA1 matches the qmk fork, e.g. for ChibiOS:
|
||||
* Go to [qmk/ChibiOS](https://github.com/qmk/ChibiOS)
|
||||
* Compare the commit hash in the above output to the commit hash in the repository
|
||||
* If there's a mismatch, that repository needs to have its `master` branch updated to match (otherwise Configurator won't work):
|
||||
* If there's a mismatch, that repository needs to have its `qmk-master` branch updated to match (otherwise Configurator won't work):
|
||||
* `cd lib/chibios`
|
||||
* `git fetch --all`
|
||||
* `git checkout master`
|
||||
* `git checkout qmk-master`
|
||||
* `git reset --hard <commit hash>`
|
||||
* `git push origin master --force-with-lease`
|
||||
* `git push origin qmk-master --force-with-lease`
|
||||
|
||||
* Announce that both `master` and `develop` are now unlocked -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
|
||||
* `@Breaking Changes Updates -- Hey folks, develop has now been merged into master -- newest batch of changes are now available for everyone to use!`
|
||||
|
||||
@ -4,7 +4,7 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
|
||||
|
||||
## Getting ChibiOS
|
||||
|
||||
* `svn` Initialisation:
|
||||
* `svn` Initialization:
|
||||
* Only needed to be done once
|
||||
* You might need to separately install `git-svn` package in your OS's package manager
|
||||
* `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/`
|
||||
@ -21,7 +21,7 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
|
||||
|
||||
## Getting ChibiOS-Contrib
|
||||
|
||||
* `git` Initialisation:
|
||||
* `git` Initialization:
|
||||
* `git clone git@github.com:qmk/ChibiOS-Contrib`
|
||||
* `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib`
|
||||
* `git checkout -b chibios-20.3.x upstream/chibios-20.3.x`
|
||||
@ -57,3 +57,16 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra
|
||||
* `git commit -am 'Update ChibiOS to 99.9.9'`
|
||||
* `git push --set-upstream origin chibios-version-bump`
|
||||
* Make a PR to qmk_firmware with the new branch
|
||||
|
||||
## When merging a PR containing an upgrade of ChibiOS/ChibiOS-Contrib:
|
||||
|
||||
* Update the target branch if the merge target was `master`:
|
||||
* `git checkout qmk-master`
|
||||
* `git reset --hard develop_YYYY_qN`
|
||||
* `git push origin qmk-master --force-with-lease`
|
||||
* Update the target branch if the merge target was `develop`:
|
||||
* `git checkout qmk-develop`
|
||||
* `git reset --hard develop_YYYY_qN`
|
||||
* `git push origin qmk-develop --force-with-lease`
|
||||
|
||||
Note that when merging `develop` to `master`, the first workflow should still be followed.
|
||||
|
||||
@ -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'
|
||||
```
|
||||
@ -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)
|
||||
|
||||
@ -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'
|
||||
```
|
||||
@ -145,7 +145,13 @@ Also, specific to ChibiOS:
|
||||
|
||||
## Core PRs :id=core-pr
|
||||
|
||||
- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
|
||||
- all core PRs must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
|
||||
- as indicated above, the smallest set of changes to core components should be included in each PR
|
||||
- PRs containing multiple areas of change will be asked to be split up and raised separately
|
||||
- keyboard and keymap changes should only be included if they affect base keyboard builds, or the default-like `default`, `via`, `default_????` keymaps etc.
|
||||
- keymap modifications for anything other than the default-like keymaps **should not be included in the initial PR** in order to simplify the review process
|
||||
- the core PR submitter should submit a followup PR affecting other keymaps after initial PR merge
|
||||
- large-scale refactoring or consolidation PRs that affect other keymaps (such as renaming keycodes) should always be raised separately
|
||||
- any new boards adding support for new hardware now requires a corresponding test board under `keyboards/handwired/onekey`
|
||||
- for new MCUs, a new "child" keyboard should be added that targets your newly-added MCU, so that builds can be verified
|
||||
- for new hardware support such as display panels, core-side matrix implementations, or other peripherals, an associated keymap should be provided
|
||||
|
||||
44
docs/support_deprecation_policy.md
Normal file
44
docs/support_deprecation_policy.md
Normal file
@ -0,0 +1,44 @@
|
||||
# Feature support policies
|
||||
|
||||
## System Constraints
|
||||
|
||||
In general, feature development is encouraged to support as many hardware configurations as possible. Depending on system constraints this may not always be achievable, and is usually bound by microcontroller flash and RAM capabilities.
|
||||
|
||||
The most frequently-hit constraint is the amount of code that can be flashed onto an ATmega32U4 -- users almost always need to pick and choose included functionality due to the size constraints.
|
||||
|
||||
!> [Squeezing AVR](https://docs.qmk.fm/#/squeezing_avr) has some steps that users can take in order to minimise the overall firmware size, which in some cases enables the ability for users to include other desired features.
|
||||
|
||||
## Deprecation & Removal Policy
|
||||
|
||||
QMK Firmware strives for innovation wherever possible. With ongoing feature development and other improvements made to the codebase, sometimes the retirement of outdated, under-utilised, or limited-value functionality is selected for deprecation and subsequent removal.
|
||||
|
||||
The intent behind feature deprecation is to maintain and/or improve quality. As a result, perpetually supporting under-utilised features would negatively impact the QMK team's ability to improve other areas of QMK Firmware.
|
||||
|
||||
There may be several motivations behind the deprecation or removal of functionality (keeping in mind that this list is not exhaustive):
|
||||
|
||||
* Better alternatives have already been implemented
|
||||
* Lack of adherence to standards
|
||||
* Poor support from code owners or upstream maintainers
|
||||
* Poor design
|
||||
* Hardware constraints
|
||||
* Minimal use within the QMK Firmware repository
|
||||
* Copyright disputes
|
||||
* Bit-rot
|
||||
|
||||
When a feature is selected for deprecation, future changes to that area will cease to be developed by the QMK team, and Pull Requests submitted against those areas will be declined.
|
||||
|
||||
?> As QMK does not gather metrics from its users, the only way the QMK team can gauge the level of usage is to refer to the main QMK Firmware repository -- searching through forks is not practical due to the sheer number of them.
|
||||
|
||||
### How much advance notice will be given?
|
||||
|
||||
Disregarding emergencies or other high-risk concerns, deprecation of large features or entire subsystems within QMK will be communicated on the `develop` branch at least one breaking changes cycle (3 months) before removal. Advance notice may be extended for higher impact features, and is at the discretion of the QMK team.
|
||||
|
||||
Smaller features may be removed within a breaking changes cycle, and will generally be based on the level of use within the repository. Features with minimal use may be selected for removal at any time on the `develop` branch.
|
||||
|
||||
Third-party software libraries leveraged by QMK are generally forked to mitigate disappearance upstream. If the upstream repository is removed, it will generally be replaced when practical, or dependent features will be removed as per the normal deprecation policy.
|
||||
|
||||
### How will deprecation be communicated?
|
||||
|
||||
Every breaking changes merge from `develop` into `master` is accompanied by a changelog document -- intended and completed deprecations will be communicated here.
|
||||
|
||||
In addition, wherever possible warnings will be issued during firmware compilation when deprecated features are still being used.
|
||||
@ -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-->
|
||||
|
||||
@ -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'
|
||||
```
|
||||
@ -42,15 +42,7 @@ dfu-util: $(BUILD_DIR)/$(TARGET).bin cpfirmware sizeafter
|
||||
$(call EXEC_DFU_UTIL)
|
||||
|
||||
define EXEC_UF2_UTIL_DEPLOY
|
||||
if ! $(UF2CONV) --deploy $(BUILD_DIR)/$(TARGET).uf2 2>/dev/null; then \
|
||||
printf "$(MSG_BOOTLOADER_NOT_FOUND_QUICK_RETRY)" ;\
|
||||
sleep $(BOOTLOADER_RETRY_TIME) ;\
|
||||
while ! $(UF2CONV) --deploy $(BUILD_DIR)/$(TARGET).uf2 2>/dev/null; do \
|
||||
printf "." ;\
|
||||
sleep $(BOOTLOADER_RETRY_TIME) ;\
|
||||
done ;\
|
||||
printf "\n" ;\
|
||||
fi
|
||||
$(UF2CONV) --wait --deploy $(BUILD_DIR)/$(TARGET).uf2
|
||||
endef
|
||||
|
||||
# TODO: Remove once ARM has a way to configure EECONFIG_HANDEDNESS
|
||||
|
||||
@ -8,6 +8,7 @@ import os
|
||||
import os.path
|
||||
import argparse
|
||||
import json
|
||||
from time import sleep
|
||||
|
||||
|
||||
UF2_MAGIC_START0 = 0x0A324655 # "UF2\n"
|
||||
@ -276,23 +277,25 @@ def main():
|
||||
parser = argparse.ArgumentParser(description='Convert to UF2 or flash directly.')
|
||||
parser.add_argument('input', metavar='INPUT', type=str, nargs='?',
|
||||
help='input file (HEX, BIN or UF2)')
|
||||
parser.add_argument('-b' , '--base', dest='base', type=str,
|
||||
parser.add_argument('-b', '--base', dest='base', type=str,
|
||||
default="0x2000",
|
||||
help='set base address of application for BIN format (default: 0x2000)')
|
||||
parser.add_argument('-o' , '--output', metavar="FILE", dest='output', type=str,
|
||||
help='write output to named file; defaults to "flash.uf2" or "flash.bin" where sensible')
|
||||
parser.add_argument('-d' , '--device', dest="device_path",
|
||||
help='select a device path to flash')
|
||||
parser.add_argument('-l' , '--list', action='store_true',
|
||||
help='list connected devices')
|
||||
parser.add_argument('-c' , '--convert', action='store_true',
|
||||
help='do not flash, just convert')
|
||||
parser.add_argument('-D' , '--deploy', action='store_true',
|
||||
help='just flash, do not convert')
|
||||
parser.add_argument('-f' , '--family', dest='family', type=str,
|
||||
parser.add_argument('-f', '--family', dest='family', type=str,
|
||||
default="0x0",
|
||||
help='specify familyID - number or name (default: 0x0)')
|
||||
parser.add_argument('-C' , '--carray', action='store_true',
|
||||
parser.add_argument('-o', '--output', metavar="FILE", dest='output', type=str,
|
||||
help='write output to named file; defaults to "flash.uf2" or "flash.bin" where sensible')
|
||||
parser.add_argument('-d', '--device', dest="device_path",
|
||||
help='select a device path to flash')
|
||||
parser.add_argument('-l', '--list', action='store_true',
|
||||
help='list connected devices')
|
||||
parser.add_argument('-c', '--convert', action='store_true',
|
||||
help='do not flash, just convert')
|
||||
parser.add_argument('-D', '--deploy', action='store_true',
|
||||
help='just flash, do not convert')
|
||||
parser.add_argument('-w', '--wait', action='store_true',
|
||||
help='wait for device to flash')
|
||||
parser.add_argument('-C', '--carray', action='store_true',
|
||||
help='convert binary file to a C array, not UF2')
|
||||
parser.add_argument('-i', '--info', action='store_true',
|
||||
help='display header information from UF2, do not convert')
|
||||
@ -337,20 +340,23 @@ def main():
|
||||
print("Converted to %s, output size: %d, start address: 0x%x" %
|
||||
(ext, len(outbuf), appstartaddr))
|
||||
if args.convert or ext != "uf2":
|
||||
drives = []
|
||||
if args.output == None:
|
||||
args.output = "flash." + ext
|
||||
else:
|
||||
drives = get_drives()
|
||||
|
||||
if args.output:
|
||||
write_file(args.output, outbuf)
|
||||
else:
|
||||
if ext == "uf2" and not args.convert and not args.info:
|
||||
drives = get_drives()
|
||||
if len(drives) == 0:
|
||||
error("No drive to deploy.")
|
||||
for d in drives:
|
||||
print("Flashing %s (%s)" % (d, board_id(d)))
|
||||
write_file(d + "/NEW.UF2", outbuf)
|
||||
if args.wait:
|
||||
print("Waiting for drive to deploy...")
|
||||
while len(drives) == 0:
|
||||
sleep(0.1)
|
||||
drives = get_drives()
|
||||
elif not args.output:
|
||||
error("No drive to deploy.")
|
||||
for d in drives:
|
||||
print("Flashing %s (%s)" % (d, board_id(d)))
|
||||
write_file(d + "/NEW.UF2", outbuf)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@ -77,7 +77,7 @@
|
||||
{
|
||||
"id": "0x57755a57",
|
||||
"short_name": "STM32F4",
|
||||
"description": "ST STM32F401"
|
||||
"description": "ST STM32F4xx"
|
||||
},
|
||||
{
|
||||
"id": "0x5a18069b",
|
||||
@ -188,5 +188,20 @@
|
||||
"id": "0x9af03e33",
|
||||
"short_name": "GD32VF103",
|
||||
"description": "GigaDevice GD32VF103"
|
||||
},
|
||||
{
|
||||
"id": "0x4f6ace52",
|
||||
"short_name": "CSK4",
|
||||
"description": "LISTENAI CSK300x/400x"
|
||||
},
|
||||
{
|
||||
"id": "0x6e7348a8",
|
||||
"short_name": "CSK6",
|
||||
"description": "LISTENAI CSK60xx"
|
||||
},
|
||||
{
|
||||
"id": "0x11de784a",
|
||||
"short_name": "M0SENSE",
|
||||
"description": "M0SENSE BL702"
|
||||
}
|
||||
]
|
||||
]
|
||||
@ -1,33 +0,0 @@
|
||||
FROM qmkfm/qmk_cli
|
||||
|
||||
# Basic upgrades; install sudo and SSH.
|
||||
RUN apt-get update && apt-get install --no-install-recommends -y \
|
||||
sudo \
|
||||
openssh-server \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
RUN mkdir /var/run/sshd
|
||||
RUN sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
|
||||
RUN echo 'UseDNS no' >> /etc/ssh/sshd_config
|
||||
|
||||
# Remove the policy file once we're finished installing software.
|
||||
# This allows invoke-rc.d and friends to work as expected.
|
||||
RUN rm /usr/sbin/policy-rc.d
|
||||
|
||||
# Add the Vagrant user and necessary passwords.
|
||||
RUN groupadd vagrant
|
||||
RUN useradd -c "Vagrant" -g vagrant -d /home/vagrant -m -s /bin/bash vagrant
|
||||
RUN echo 'root:vagrant' | chpasswd
|
||||
RUN echo 'vagrant:vagrant' | chpasswd
|
||||
|
||||
# Allow the vagrant user to use sudo without a password.
|
||||
RUN echo 'vagrant ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/vagrant
|
||||
|
||||
# Install Vagrant's insecure public key so provisioning and 'vagrant ssh' work.
|
||||
RUN mkdir /home/vagrant/.ssh
|
||||
ADD https://raw.githubusercontent.com/mitchellh/vagrant/master/keys/vagrant.pub /home/vagrant/.ssh/authorized_keys
|
||||
RUN chmod 0600 /home/vagrant/.ssh/authorized_keys
|
||||
RUN chown -R vagrant:vagrant /home/vagrant/.ssh
|
||||
RUN chmod 0700 /home/vagrant/.ssh
|
||||
|
||||
EXPOSE 22
|
||||
CMD ["/usr/sbin/sshd", "-D"]
|
||||
@ -1,12 +0,0 @@
|
||||
# QMK Vagrant Utilities
|
||||
|
||||
## Dockerfile
|
||||
Vagrant-friendly `qmkfm/qmk_cli`.
|
||||
|
||||
In order for the Docker provider and `vagrant ssh` to function the container has a few extra requirements.
|
||||
|
||||
* vagrant user
|
||||
* ssh server
|
||||
* configured with expected public key
|
||||
* sudo
|
||||
* passwordless for vagrant user
|
||||
Loading…
Reference in New Issue
Block a user