From bbe8180ad904cd432b6f97e9662231fa0548ad0e Mon Sep 17 00:00:00 2001 From: umi <57262844+umi-umi@users.noreply.github.com> Date: Mon, 17 Feb 2020 17:50:26 +0900 Subject: [Docs] add japanese translation (detail guide part) (#7722) * add detail-guide part * some updates for easy reading * some updates for easy reading * some updates for easy reading * some updates for easy reading * some updates for easy reading * some updates for easy reading * some updates for easy reading * some updates for easy reading * update file based on comment * update file based on comment * update file based on comment * update git command in header * update files based on comments, and update git command in header * update file based on comment * update file based on comment * update file based on comment * update file based on comment * update file based on comment * update file based on comment * update file based on comment * update file based on comment Co-Authored-By: shela Co-Authored-By: Takeshi ISHII <2170248+mtei@users.noreply.github.com> --- docs/ja/custom_quantum_functions.md | 518 +++++++++++++++++++++++++++++++++ docs/ja/flashing.md | 247 ++++++++++++++++ docs/ja/getting_started_build_tools.md | 146 ++++++++++ docs/ja/getting_started_make_guide.md | 153 ++++++++++ docs/ja/getting_started_vagrant.md | 62 ++++ docs/ja/keymap.md | 174 +++++++++++ 6 files changed, 1300 insertions(+) create mode 100644 docs/ja/custom_quantum_functions.md create mode 100644 docs/ja/flashing.md create mode 100644 docs/ja/getting_started_build_tools.md create mode 100644 docs/ja/getting_started_make_guide.md create mode 100644 docs/ja/getting_started_vagrant.md create mode 100644 docs/ja/keymap.md (limited to 'docs') diff --git a/docs/ja/custom_quantum_functions.md b/docs/ja/custom_quantum_functions.md new file mode 100644 index 0000000000..f49df8f65b --- /dev/null +++ b/docs/ja/custom_quantum_functions.md @@ -0,0 +1,518 @@ +# キーボードの挙動をカスタマイズする方法 + + + +多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。 + +このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。 + +## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap + +私たちは QMK を階層として構造化しました: + +* コア (`_quantum`) + * キーボード/リビジョン (`_kb`) + * キーマップ (`_user`) + +以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。 + +キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。 + +# カスタムキーコード + +最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。 + +## 新しいキーコードの定義 + +独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。 + + +これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。 + +```c +enum my_keycodes { + FOO = SAFE_RANGE, + BAR +}; +``` + +## 任意のキーコードの挙動のプログラミング + +既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。 + +これらの関数はキーが押されるか放されるたびに呼び出されます。 + +### `process_record_user()` の実装例 + +この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。 + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // 押された時に何かをします + } else { + // 放された時に何かをします + } + return false; // このキーの以降の処理をスキップします + case KC_ENTER: + // enter が押された時に音を再生します + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // QMK に enter のプレスまたはリリースイベントを送信させます + default: + return true; // 他の全てのキーコードを通常通りに処理します + } +} +``` + +### `process_record_*` 関数のドキュメント + +* キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` +* キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` + +`keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。 + +`record` 引数は実際のプレスに関する情報を含みます: + +```c +keyrecord_t record { + keyevent_t event { + keypos_t key { + uint8_t col + uint8_t row + } + bool pressed + uint16_t time + } +} +``` + +# LED 制御 + +QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します: + +* Num Lock +* Caps Lock +* Scroll Lock +* Compose +* Kana + +ロック LED の状態を取得するには2つの方法があります: + +* `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または +* `led_t host_keyboard_led_state()` を呼び出す + +!> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。 + +LED の状態を `uint8_t` として提供する2つの非推奨の関数があります: + +* `uint8_t led_set_kb(uint8_t usb_led)` と `_user(uint8_t usb_led)` +* `uint8_t host_keyboard_leds()` + +## `led_update_user()` + +この関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。 + +慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。 + +以下はいくつかの例です: + +- レイヤー表示のような何かのために LED を使うために LED を上書きする + - `_kb()` 関数を実行したくないので、`false` を返します。これはレイヤーの挙動を上書きするためです。 +- LED がオンあるいはオフになった時に音楽を再生する。 + - `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。 + +?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。 + +### `led_update_kb()` の実装例 + +```c +bool led_update_kb(led_t led_state) { + bool res = led_update_user(led_state); + if(res) { + // writePin は 1 でピンを high に、0 で low に設定します。 + // この例では、ピンは反転していて、 + // low/0 は LED がオンになり、high/1 は LED がオフになります。 + // この挙動は、LED がピンと VCC の間にあるか、ピンと GND の間にあるかどうかに依存します。 + writePin(B0, !led_state.num_lock); + writePin(B1, !led_state.caps_lock); + writePin(B2, !led_state.scroll_lock); + writePin(B3, !led_state.compose); + writePin(B4, !led_state.kana); + } + return res; +} +``` + +### `led_update_user()` の実装例 + +この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。 + +```c +#ifdef AUDIO_ENABLE + float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); + float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); +#endif + +bool led_update_user(led_t led_state) { + #ifdef AUDIO_ENABLE + static uint8_t caps_state = 0; + if (caps_state != led_state.caps_lock) { + led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); + caps_state = led_state.caps_lock; + } + #endif + return true; +} +``` + +### `led_update_*` 関数のドキュメント + +* キーボード/リビジョン: `bool led_update_kb(led_t led_state)` +* キーマップ: `bool led_update_user(led_t led_state)` + +## `host_keyboard_led_state()` + +最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。 + +## 物理的な LED の状態の設定 + +一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。 + +### Ergodox キーボード + +Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。 + +さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。 + +Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。 + +# キーボードの初期化コード + +キーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。 + +3つの主な初期化関数があり、呼び出される順番にリストされています。 + +* `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。 +* `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。 +* `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。 + +!> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。 + +## キーボードの事前初期化コード + +これは USB さえ起動する前の、起動中の非常に早い段階で実行されます。 + +この直後にマトリックスが初期化されます。 + +これは主にハードウェア向きの初期化のためであるため、ほとんどのユーザは使うべきではありません。 + +ただし、初期化が必要なハードウェアがある場合には、これが最適な場所です (LED ピンの初期化など)。 + +### `keyboard_pre_init_user()` の実装例 + +この例は、キーボードレベルで、LED ピンとして B0、B1、B2、B3 および B4 をセットアップします。 + +```c +void keyboard_pre_init_user(void) { + // キーボードの事前初期コードを呼び出します。 + + // LED ピンを出力として設定します + setPinOutput(B0); + setPinOutput(B1); + setPinOutput(B2); + setPinOutput(B3); + setPinOutput(B4); +} +``` + +### `keyboard_pre_init_*` 関数のドキュメント + +* キーボード/リビジョン: `void keyboard_pre_init_kb(void)` +* キーマップ: `void keyboard_pre_init_user(void)` + +## マトリックスの初期化コード + +これは、マトリックスが初期化され、ハードウェアの一部がセットアップされた後で、ただし機能の多くが初期化される前に、呼び出されます。 + +他の場所で必要になるかもしれないものをセットアップするのに役立ちますが、ハードウェアに関連するものではなく、開始場所に依存するものでもありません。 + + +### `matrix_init_*` 関数のドキュメント + +* キーボード/リビジョン: `void matrix_init_kb(void)` +* キーマップ: `void matrix_init_user(void)` + + +## キーボードの事後初期化コード + +キーボードの初期化プロセスの極めて最後のタスクとして実行されます。この時点で初期化される必要があるような、特定の機能を変更したい場合に便利です。 + + +### `keyboard_post_init_user()` の実装例 + +この例は、他の全てのものが初期化された後で実行され、rgb アンダーグローの設定をセットアップします。 + +```c +void keyboard_post_init_user(void) { + // post init コードを呼びます + rgblight_enable_noeeprom(); // 設定を保存せずに Rgb を有効にします + rgblight_sethsv_noeeprom(180, 255, 255); // 保存せずに色を青緑/シアンに設定します + rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 保存せずにモードを高速なブリージングに設定します +} +``` + +### `keyboard_post_init_*` 関数のドキュメント + +* キーボード/リビジョン: `void keyboard_post_init_kb(void)` +* キーマップ: `void keyboard_post_init_user(void)` + +# マトリックススキャンコード :id=matrix-scanning-code + +可能であれば常に `process_record_*()` を使ってキーボードをカスタマイズし、その方法でイベントをフックし、コードがキーボードのパフォーマンスに悪影響を与えないようにします。ただし、まれにマトリックススキャンにフックする必要があります。これらの関数は1秒あたり少なくとも10回は呼び出されるため、これらの関数のコードのパフォーマンスに非常に注意してください。 + +### `matrix_scan_*` の実装例 + +この例は意図的に省略されています。このようなパフォーマンスに敏感な領域にフックする前に、例を使わずにこれを書くために、QMK 内部について十分理解する必要があります。助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new) か [Discord で会話](https://discord.gg/Uq7gcHh)してください。 + +### `matrix_scan_*` 関数のドキュメント + +* キーボード/リビジョン: `void matrix_scan_kb(void)` +* キーマップ: `void matrix_scan_user(void)` + +この関数はマトリックススキャンのたびに呼び出されます。これは基本的に MCU が処理できる頻度です。大量に実行されるため、ここに何を置くかについては注意してください。 + +カスタムマトリックススキャンコードが必要な場合は、この関数を使う必要があります。また、カスタムステータス出力 (LED あるいはディスプレイなど)や、ユーザが入力していない場合でも定期的にトリガーするその他の機能のために使うことができます。 + + +# キーボードアイドリング/ウェイクコード + +キーボードがサポートしている場合、多くの機能を停止することで"アイドル"にすることができます。これの良い例は、RGB ライトあるいはバックライトです。これにより、電力消費を節約できるか、キーボードの動作が改善されるかもしれません。 + +これは2つの関数によって制御されます: `suspend_power_down_*` および `suspend_wakeup_init_*`。これらはシステムキーボードがアイドルになった時と、起動した時のそれぞれで呼ばれます。 + + +### suspend_power_down_user() と suspend_wakeup_init_user() の実装例 + + +```c +void suspend_power_down_user(void) { + rgb_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) { + rgb_matrix_set_suspend_state(false); +} +``` + +### キーボードサスペンド/ウェイク関数のドキュメント + +* キーボード/リビジョン : `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)` +* キーマップ: `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)` + +# レイヤー切り替えコード + +これはレイヤーが切り替えられるたびにコードを実行します。レイヤー表示あるいはカスタムレイヤー処理に役立ちます。 + +### `layer_state_set_*` の実装例 + +この例は、レイヤーに基づいて [RGB アンダーグロー](ja/feature_rgblight.md)を設定する方法を示していて、Planck を例として使っています。 + +```c +layer_state_t layer_state_set_user(layer_state_t state) { + switch (get_highest_layer(state)) { + case _RAISE: + rgblight_setrgb (0x00, 0x00, 0xFF); + break; + case _LOWER: + rgblight_setrgb (0xFF, 0x00, 0x00); + break; + case _PLOVER: + rgblight_setrgb (0x00, 0xFF, 0x00); + break; + case _ADJUST: + rgblight_setrgb (0x7A, 0x00, 0xFF); + break; + default: // 他の全てのレイヤーあるいはデフォルトのレイヤー + rgblight_setrgb (0x00, 0xFF, 0xFF); + break; + } + return state; +} +``` +### `layer_state_set_*` 関数のドキュメント + +* キーボード/リビジョン: `layer_state_t layer_state_set_kb(layer_state_t state)` +* キーマップ: `layer_state_t layer_state_set_user(layer_state_t state)` + + +[キーマップの概要](ja/keymap.md#keymap-layer-status)で説明されるように、`state` はアクティブなレイヤーのビットマスクです。 + + +# 永続的な設定 (EEPROM) + +これによりキーボードのための永続的な設定を設定することができます。これらの設定はコントローラの EEPROM に保存され、電源が落ちた後であっても保持されます。設定は `eeconfig_read_kb` および `eeconfig_read_user` を使って読み取ることができ、`eeconfig_update_kb` および `eeconfig_update_user` を使って書きこむことができます。これは切り替え可能な機能 (rgb レイヤーの表示の切り替えなど)に役立ちます。さらに、`eeconfig_init_kb` および `eeconfig_init_user` を使って EEPROM のデフォルト値を設定できます。 + +ここでの複雑な部分は、EEPROM を介してデータを保存およびアクセスできる方法がたくさんあり、これを行うための"正しい"方法が無いということです。ただし、各関数には DWORD (4 バイト)しかありません。 + +EEPROM の書き込み回数には制限があることに注意してください。これは非常に高い値ですが、EEPROM に書き込むのはこれだけではなく、もし頻繁に書き込むと、MCU の寿命を大幅に短くする可能性があります。 + +* この例を理解していない場合は、この機能はかなり複雑なため、この機能を使うことを避けても構いません。 + +### 実装例 + +これは、設定を追加し、読み書きする例です。この例では、ユーザキーマップを使っています。これは複雑な機能で、多くのことが行われています。実際、動作のために上記の多くの関数を使います！ + + +keymap.c ファイルの中で、先頭にこれを追加します: +```c +typedef union { + uint32_t raw; + struct { + bool rgb_layer_change :1; + }; +} user_config_t; + +user_config_t user_config; +``` + +これは、設定をメモリ内に保存し、EEPROM に書き込むことができる32ビット構造体をセットアップします。これを使うと、この構造体に変数が定義されるため、変数を定義する必要が無くなります。`bool` (boolean) の値は1ビットを使い、`uint8_t` は8ビットを使い、`uint16_t` は16ビットを使うことに注意してください。組み合わせて使うことができますが、順番の変更は読み書きされる値が変更されるため、問題が発生するかもしれません。 + +`layer_state_set_*` 関数のために `rgb_layer_change` を使い、全てを設定するために `keyboard_post_init_user` および `process_record_user` を使います。 + +ここで、上の `keyboard_post_init_user` コードを使って、作成したばかりの構造体を設定するために `eeconfig_read_user()` を追加します。そして、この構造体をすぐに使ってキーマップの機能を制御することができます。それは以下のようになります: +```c +void keyboard_post_init_user(void) { + // キーマップレベルのマトリックスの初期化処理を呼びます + + // EEPROM からユーザ設定を読み込みます + user_config.raw = eeconfig_read_user(); + + // 有効な場合はデフォルトレイヤーを設定します + if (user_config.rgb_layer_change) { + rgblight_enable_noeeprom(); + rgblight_sethsv_noeeprom_cyan(); + rgblight_mode_noeeprom(1); + } +} +``` +上記の関数は読み取ったばかりの EEPROM 設定を使い、デフォルトのレイヤーの RGB 色を設定します。その「生の」値は、上で作成した「共用体」に基づいて使用可能な構造に変換されます。 + +```c +layer_state_t layer_state_set_user(layer_state_t state) { + switch (get_highest_layer(state)) { + case _RAISE: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } + break; + case _LOWER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } + break; + case _PLOVER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } + break; + case _ADJUST: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } + break; + default: // 他の全てのレイヤーあるいはデフォルトのレイヤー + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } + break; + } + return state; +} +``` +これにより、値が有効になっていた場合のみ、RGB アンダーグローが変更されます。この値を設定するために、`RGB_LYR` と呼ばれる `process_record_user` 用の新しいキーコードを作成します。さらに、通常の RGB コードを使う場合、上記の例を使ってオフになることを確認します。以下のようになります: +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // 押された時に何かをします + } else { + // 放された時に何かをします + } + return false; // このキーの以降の処理をスキップします + case KC_ENTER: + // enter が押された時に音を再生します + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // QMK に enter のプレスまたはリリースイベントを送信させます + case RGB_LYR: // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。 + if (record->event.pressed) { + user_config.rgb_layer_change ^= 1; // 状態を切り替えます + eeconfig_update_user(user_config.raw); // 新しい状態を EEPROM に書き込みます + if (user_config.rgb_layer_change) { // レイヤーの状態表示が有効な場合 + layer_state_set(layer_state); // すぐにレイヤーの色を更新します + } + } + return false; break; + case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照) + if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。 + if (user_config.rgb_layer_change) { // 有効な場合のみ + user_config.rgb_layer_change = false; // 無効にします + eeconfig_update_user(user_config.raw); // 設定を EEPROM に書き込みます + } + } + return true; break; + default: + return true; // 他の全てのキーコードを通常通りに処理します + } +} +``` +最後に、`eeconfig_init_user` 関数を追加して、EEPROM がリセットされた時にデフォルト値、さらにはカスタムアクションを指定できるようにします。EEPROM を強制的にリセットするには、`EEP_RST` キーコードあるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。例えば、デフォルトで rgb レイヤー表示を設定し、デフォルト値を保存したい場合。 + +```c +void eeconfig_init_user(void) { // EEPROM がリセットされます！ + user_config.raw = 0; + user_config.rgb_layer_change = true; // デフォルトでこれを有効にします + eeconfig_update_user(user_config.raw); // デフォルト値を EEPROM に書き込みます + + // これらの値も EEPROM に書き込むためには、noeeprom 以外のバージョンを使います + rgblight_enable(); // デフォルトで RGB を有効にします + rgblight_sethsv_cyan(); // デフォルトでシアンに設定します + rgblight_mode(1); // デフォルトでソリッドに設定します +} +``` + +これで完了です。RGB レイヤー表示は必要な場合にのみ機能します。キーボードを取り外した後でも保存されます。RGB コードのいずれかを使うと、レイヤー表示が無効になり、設定したモードと色がそのままになります。 + +### 'EECONFIG' 関数のドキュメント + +* キーボード/リビジョン: `void eeconfig_init_kb(void)`、`uint32_t eeconfig_read_kb(void)` および `void eeconfig_update_kb(uint32_t val)` +* キーマップ: `void eeconfig_init_user(void)`、`uint32_t eeconfig_read_user(void)` および `void eeconfig_update_user(uint32_t val)` + +`val` は EEPROM に書き込みたいデータの値です。`eeconfig_read_*` 関数は EEPROM から32ビット(DWORD) 値を返します。 + +# カスタムタッピング期間 + +デフォルトでは、タッピング期間はグローバルに設定されていて、キーでは設定することができません。ほとんどのユーザにとって、これは全然問題ありません。しかし、場合によっては、`LT` キーとは異なるタイムアウトによって、デュアルファンクションキーが大幅に改善されます。なぜなら、一部のキーは他のキーよりも押し続けやすいためです。それぞれにカスタムキーコードを使う代わりに、キーごとに設定可能な `TAPPING_TERM` を使用できます。 + +この機能を有効にするには、最初に `config.h` に `#define TAPPING_TERM_PER_KEY` を追加する必要があります。 + + +## `get_tapping_term` の実装例 + +キーコードに基づいて `TAPPING TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します: + +```c +uint16_t get_tapping_term(uint16_t keycode) { + switch (keycode) { + case SFT_T(KC_SPC): + return TAPPING_TERM + 1250; + case LT(1, KC_GRV): + return 130; + default: + return TAPPING_TERM; + } +} +``` + +### `get_tapping_term` 関数のドキュメント + +ここにある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。 diff --git a/docs/ja/flashing.md b/docs/ja/flashing.md new file mode 100644 index 0000000000..1118fb5e2f --- /dev/null +++ b/docs/ja/flashing.md @@ -0,0 +1,247 @@ +# 書き込みの手順とブートローダ情報 + + + +キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。 + +`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。この処理を手動で実行するには、`check-size` を付けてコンパイルします。例えば、`make planck/rev4:default:check-size`。 + +## DFU + +Atmel の DFU ブートローダはデフォルトで全ての atmega32u4 チップに搭載されており、PCB (旧 OLKB キーボード、Clueboard) に独自の IC を持つ多くのキーボードで使われています。一部のキーボードは、LUFA の DFU ブートローダ(または QMK のフォーク) (新しい OLKB キーボード)を使う場合もあり、そのハードウェアに固有の追加機能が追加されます。 + +DFU ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください(オプションとして代わりに `lufa-dfu` や `qmk-dfu` が使えます): + +```make +# Bootloader selection +# Teensy halfkay +# Pro Micro caterina +# Atmel DFU atmel-dfu +# LUFA DFU lufa-dfu +# QMK DFU qmk-dfu +# ATmega32A bootloadHID +# ATmega328P USBasp +BOOTLOADER = atmel-dfu +``` + +互換性のあるフラッシャ: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) +* QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン) +* [Atmel の Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (非推奨) + +書き込み手順: + +1. `RESET` キーコードを押すか、RESET ボタンをタップします(または RST を GND にショートします)。 +2. OS がデバイスを検知するのを待ちます。 +3. メモリを消去します(自動的に実行されるかもしれません) +4. .hex ファイルを書き込みます +5. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) + +あるいは: + + make ::dfu + +### QMK DFU + +QMK には LUFA DFU ブートローダのフォークがあり、ブートローダを終了してアプリケーションに戻る時に単純なマトリックススキャンを行うことができます。また、何かが起きた時に、LED を点滅したり、スピーカーでカチカチ音をたてたりします。これらの機能を有効にするには、`config.h` で以下のブロックを有効にします (ブートローダを終了するキーは、ここで定義された INPUT と OUTPUT に接続する必要があります): + + #define QMK_ESC_OUTPUT F1 // 通常 COL + #define QMK_ESC_INPUT D5 // 通常 ROW + #define QMK_LED E6 + #define QMK_SPEAKER C6 + +製造元と製品名は `config.h` から自動的に取得され、製品に「Bootloader」が追加されます。 + +このブートローダを生成するには、`bootloader` ターゲット、例えば `make planck/rev4:default:bootloader` を使います。 + +実稼働対応の .hex ファイル(アプリケーションおよびブートローダを含む)を生成するには、`production` ターゲット、例えば `make planck/rev4:default:production` を使います。 + +### DFU コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。 +* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。 +* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ +* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ + +## Caterina + +Arduino ボードとそのクローンは [Caterina ブートローダ](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (Pro Micro またはそのクローンで構築されたキーボード)を使用し、avr109 プロトコルを使って仮想シリアルを介して通信します。[A-Star](https://www.pololu.com/docs/0J61/9) のようなブートローダは Caterina に基づいています。 + +Caterina ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: + +```make +# Bootloader selection +# Teensy halfkay +# Pro Micro caterina +# Atmel DFU atmel-dfu +# LUFA DFU lufa-dfu +# QMK DFU qmk-dfu +# ATmega32A bootloadHID +# ATmega328P USBasp +BOOTLOADER = caterina +``` + +互換性のあるフラッシャ: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) +* avr109 を使った [avrdude](http://www.nongnu.org/avrdude/) / `:avrdude` (推奨のコマンドライン) +* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) + +書き込み手順: + +1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます) +2. OS がデバイスを検知するのを待ちます。 +3. .hex ファイルを書き込みます +4. デバイスが自動的にリセットされるのを待ちます + +あるいは + + make ::avrdude + + +#### Caterina コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。 +* `:avrdude-loop` - これは `:avrdude` と同じコマンドを実行します。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへ書き込むのに便利です。_Ctrl+C を押して、手動でこの繰り返しを終了させる必要があります。_ +* `:avrdude-split-left` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_ +* `:avrdude-split-right` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_ + + + +## Halfkay + +Halfkay は PJRC によって開発された超スリムなプロトコルであり、HID を使用し、全ての Teensys (つまり 2.0)に搭載されています。 + +Halfkay ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: + +```make +# Bootloader selection +# Teensy halfkay +# Pro Micro caterina +# Atmel DFU atmel-dfu +# LUFA DFU lufa-dfu +# QMK DFU qmk-dfu +# ATmega32A bootloadHID +# ATmega328P USBasp +BOOTLOADER = halfkay +``` + +互換性のあるフラッシャ: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) +* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html) +* [Teensy ローダーコマンドライン](https://www.pjrc.com/teensy/loader_cli.html) (推奨のコマンドライン) + +書き込み手順: + +1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます) +2. OS がデバイスを検知するのを待ちます。 +3. .hex ファイルを書き込みます +4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) + +## USBasploader + +USBasploader は matrixstorm によって開発されたブートローダです。V-USB を実行する ATmega328P のような非 USB AVR チップで使われます。 + +USBasploader ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: + +```make +# Bootloader selection +# Teensy halfkay +# Pro Micro caterina +# Atmel DFU atmel-dfu +# LUFA DFU lufa-dfu +# QMK DFU qmk-dfu +# ATmega32A bootloadHID +# ATmega328P USBasp +BOOTLOADER = USBasp +``` + +互換性のあるフラッシャ: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) +* `usbasp` プログラマを使った [avrdude](http://www.nongnu.org/avrdude/) +* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) + +書き込み手順: + +1. `RESET` キーコードを押すか、RST を GND にすばやくショートしながら、ブートピンを GND にショートしたままにします。 +2. OS がデバイスを検知するのを待ちます。 +3. .hex ファイルを書き込みます +4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) + +## BootloadHID + +BootloadHID は AVR マイクロコントローラ用の USB ブートローダです。アップローダーツールは Windows でカーネルレベルのドライバを必要としないため、DLL をインストールせずに実行することができます。 + +bootloadHID ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください: + +```make +# Bootloader selection +# Teensy halfkay +# Pro Micro caterina +# Atmel DFU atmel-dfu +# LUFA DFU lufa-dfu +# QMK DFU qmk-dfu +# ATmega32A bootloadHID +# ATmega328P USBasp +BOOTLOADER = bootloadHID +``` + +互換性のあるフラッシャ: + +* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (推奨の Windows GUI) +* [bootloadhid コマンドライン](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK の `:BootloadHID` (推奨のコマンドライン) + +書き込み手順: + +1. 以下のいずれかの方法を使ってブートローダに入ります: + * `RESET` キーコードをタップします (全てのデバイスでは動作しないかもしれません) + * キーボードを接続しながらソルトキーを押し続けます (通常はキーボードの readme に書かれています) +2. OS がデバイスを検知するのを待ちます。 +3. .hex ファイルを書き込みます +4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) + +あるいは: + + make ::bootloadHID + +## STM32 + +全ての STM32 チップには、変更も削除もできない工場出荷時のブートローダがプリロードされています。一部の STM32 チップには USB プログラミングが付属していないブートローダがありますが(例えば STM32F103)、プロセスは同じです。 + +現時点では、STM32 の `rules.mk` には、`BOOTLOADER` 変数は不要です。 + +互換性のあるフラッシャ: + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI) +* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (推奨のコマンドライン) + +書き込み手順: + +1. 以下のいずれかの方法を使ってブートローダに入ります: + * `RESET` キーコードをタップします (STM32F042 デバイスでは動作しないかもしれません) + * リセット回路が存在する場合、RESET ボタンをタップします + * それ以外の場合は、(BOOT0 ボタンあるいはブリッジ経由で)BOOT0 を VCC にブリッジし、(REEST ボタンあるいはブリッジ経由で)RESET を GND にショートし、BOOT0 ブリッジを放す必要があります。 +2. OS がデバイスを検知するのを待ちます。 +3. .bin ファイルを書き込みます + * DFU 署名に関する警告が表示されます; 無視してください +4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません) + * コマンドラインからビルドする場合(例えば、`make planck/rev6:default:dfu-util`)、`rules.mk` の中で `:leave` が `DFU_ARGS` 変数に渡されるようにしてください (例えば、`DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`)。そうすれば、書き込みの後でデバイスがリセットされます + +### STM32 コマンド + +ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダデバイスが見つかるまで待機します。 +* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM の設定も行われます。 +* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM の設定も行われます。 +* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。 diff --git a/docs/ja/getting_started_build_tools.md b/docs/ja/getting_started_build_tools.md new file mode 100644 index 0000000000..1f7accb550 --- /dev/null +++ b/docs/ja/getting_started_build_tools.md @@ -0,0 +1,146 @@ +# ビルドツールのインストール + + + +このページは QMK のためのビルド環境のセットアップを説明します。これらの手順は (atmega32u4 のような) AVR プロセッサを対象としてします。 + + + +**注意:** ここが初めての場合は、[QMK 初心者ガイド](ja/newbs.md)ページを調べてください。 + +続ける前に、`make git-submodule` を実行して、サブモジュール(サードパーティライブラリ)が最新であることを再確認してください。 + +## Linux + +常に最新の状態を保つためには、単に `sudo util/qmk_install.sh` を実行してください。全ての必要な依存関係が常にインストールされるはずです。**これは `apt-get upgrade` を実行します。** + +手動でインストールすることもできますが、このドキュメントは常に全ての要件を満たしているとは限りません。 + +現在の要件は以下の通りですが、何をしようとしているかによっては全てが必要とは限りません。また、一部のシステムではパッケージとして全ての依存関係が利用できるとは限らず、あるいは名前が異なる場合があるかもしれません。 + +``` +build-essential +gcc +unzip +wget +zip +gcc-avr +binutils-avr +avr-libc +dfu-programmer +dfu-util +gcc-arm-none-eabi +binutils-arm-none-eabi +libnewlib-arm-none-eabi +git +``` + +好みのパッケージマネージャを使って依存関係をインストールします。 + +Debian / Ubuntu の例: + + sudo apt-get update + sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi + +Fedora / Red Hat の例: + + sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib + +Arch / Manjaro の例: + + pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util + +## Nix + +[NixOS](https://nixos.org/) の場合、あるいは Linux または MacOS に Nix をインストールした場合は、ビルド環境を取得するためにリポジトリのルートで `nix-shell` を実行します。 + +デフォルトでは、これは AVR と ARM の両方のためのコンパイラをダウンロードします。両方が必要ではない場合は、`avr` あるいは `arm` 引数を無効にします。例えば: + + nix-shell --arg arm false + +## macOS +[Homebrew](http://brew.sh/) を使っている場合は、以下のコマンドを使うことができます: + + brew tap osx-cross/avr + brew tap osx-cross/arm + brew update + brew install avr-gcc@8 + brew link --force avr-gcc@8 + brew install dfu-programmer + brew install dfu-util + brew install arm-gcc-bin@8 + brew link --force arm-gcc-bin@8 + brew install avrdude + +これはお勧めの方法です。homebrew が無い場合は、[インストールしてください！](http://brew.sh/) コマンドラインで作業する人にとってとても価値があります。`avr-gcc@8` の homebrew でのインストール中、`make` と `make install` 部分は20分以上かかり、CPU使用率が高くなることに注意してください。 + +## msys2 を使った Windows (推奨) :id=windows-with-msys2-recommended + +Windows Vista 以降のバージョン(7および10でテスト済み)について、使用するのに最適な環境は [msys2](http://www.msys2.org) です。 + +* msys2 をダウンロードし、こちらの指示に従ってインストールしてください: http://www.msys2.org +* ``MSYS2 MingGW 64-bit`` のショートカットを開きます +* QMK リポジトリに移動します。例えば、c ドライブのルートにある場合: +* `$ cd /c/qmk_firmware` +* `util/qmk_install.sh` を実行し、指示に従います + +## Windows 10 (非推奨) +Windows 10 の古い手順です。[上記の概要のように MSYS2](#windows-with-msys2-recommended) を使うことをお勧めします。 + +### Creators Update +Creators Update 以降の Windows 10 の場合、ファームウェアを直接ビルドして書き込むことができます。Creators Update の前は、ビルドだけが可能でした。まだそうではないか、不明な場合は、[これらの指示](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update)に従ってください。 + +### Linux 用の Windows Subsystem +Creators Update に加えて、Linux 用の Windows 10 Subystem が必要ですので、[これらの指示](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/)に従ってインストールしてください。Anniversary update からの Linux 用の Windows 10 Subsystem が既にある場合、一部のキーボードは 14.04LTS に含まれるツールチェーンを使ってコンパイルしないため、16.04LTS に[アップグレード](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/)することをお勧めします。`sudo do-release-upgrade` メソッドを選択した場合は、自分が何をしているかを知る必要があることに注意してください。 + +### Git +すでに Windows ファイルシステムにリポジトリをクローンしている場合は、この章を無視することができます。 + +WSL Git では**なく**、Windows 用の通常の Git を使って Windows ファイルシステムにリポジトリをクローンする必要があります。以前に Git をインストールしたことが無ければ、[ダウンロード](https://git-scm.com/download/win)し、インストールしてください。次に[セットアップします](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)。特に貢献する予定がある場合は、eメールとユーザ名をセットアップすることが重要です。 + +Git がインストールされたら、Git Bash コマンドを開き、QMK をクローンしたい場所へディレクトリを変更します: スラッシュを使う必要があり、c ドライブは `/c/path/to/where/you/want/to/go` のようにアクセスされることに注意してください。次に、`git clone --recurse-submodules https://github.com/qmk/qmk_firmware` を実行します。これは現在のフォルダのサブディレクトリとして新しいフォルダ `qmk_firmware` を作成します。 + +### ツールチェーンのセットアップ +ツールチェーンのセットアップは Linux 用の Windows サブシステムを介して行われ、手順は完全に自動化されています。全てを手動で行いたい場合は、スクリプト以外の手順はありませんが、常に issue を開いて詳細情報を求めることができます。 + +1. スタートメニューから "Bash On Ubuntu On Windows" を開いてください。 +2. クローンした `qmk_firmware` ディレクトリに移動します。パスは WSL 内で `/mnt/` から始まることに注意してください。つまり、例えば `cd /mnt/c/path/to/qmk_firmware` と書く必要があります。 +3. `util/wsl_install.sh` を実行し、画面上の手順に従います。 +4. Bash コマンドウィンドウを閉じ、再び開きます。 +5. ファームウェアをコンパイルし書き込む準備ができました！ + +### 心に留めておくべき幾つかの重要なこと +* 全ての最新の更新を取得するために `util/wsl_install.sh` を再実行することができます。 +* WSL は外部で実行可能ファイルを実行できないため、QMK リポジトリは Windows ファイルシステム上にある必要があります。 +* WSL Git は Windows の Git と互換性が**無い**ため、全ての Git 操作には、Windows Git Bash あるいは windows Git GUI を使ってください。 +* WSL 内あるいは普通に Windows を使ってファイルを編集できますが、makefile あるいはシェルスクリプトを編集する場合は、行末をUnix形式にしてファイルを保存するエディタを使うようにしてください。そうでなければコンパイルは機能しないかもしれません。 + +## Docker + +これが少し複雑な場合は、Docker があなたが必要とするすぐに使える解決法かもしれません。[Docker CE](https://docs.docker.com/install/#supported-platforms) をインストールした後で、キーボード/キーマップをビルドするために `qmk_firmware` ディレクトリから以下のコマンドを実行します: +```bash +util/docker_build.sh keyboard:keymap +# 例えば: util/docker_build.sh ergodox_ez:steno +``` +これは目的のキーボード/キーマップをコンパイルし、結果として書き込み用に `.hex` あるいは `.bin` ファイルを QMK ディレクトリの中に残します。`:keymap` が省略された場合は全てのキーマップが使われます。パラメータの形式は、`make` を使ってビルドする時と同じであることに注意してください。 + +スクリプトをパラメータ無しで開始することもできます。この場合、1つずつビルドパラメータを入力するように求められます。これが使いやすいと思うかもしれません: +```bash +util/docker_build.sh +# パラメータを入力として読み込みます (空白にすると全てのキーボード/キーマップ) +``` + +`target` を指定することで Docker から直接キーボードをビルドし_かつ_書き込むためのサポートもあります。 +```bash +util/docker_build.sh keyboard:keymap:target +# 例えば: util/docker_build.sh planck/rev6:default:flash +``` +Linux を使っている場合は、これはそのままで動作するはずです。Windows と macOS では、実行するのに [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) が必要です。これはセットアップが面倒なので、お勧めではありません: 代わりに [QMK Toolbox](https://github.com/qmk/qmk_toolbox) を使ってください。 + +!> Docker for Windows は[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) を有効にする必要があります。これは、Windows 7、Windows 8 および **Windows 10 Home** のような Hyper-V を搭載していない Windows のバージョンでは機能しないことを意味します。 + +## Vagrant +ファームウェアをビルドするのに問題がある場合は、Vagrant と呼ばれるツールを試してみることができます。それは、ファームウェアをビルドする準備ができた既知の構成を搭載した仮想コンピュータをセットアップします。OLKB はこの仮想コンピュータのためのファイルをホストしません。Vagrant をセットアップする方法の詳細は、[vagrant ガイド](ja/getting_started_vagrant.md)にあります。 diff --git a/docs/ja/getting_started_make_guide.md b/docs/ja/getting_started_make_guide.md new file mode 100644 index 0000000000..d33485ce11 --- /dev/null +++ b/docs/ja/getting_started_make_guide.md @@ -0,0 +1,153 @@ +# より詳細な `make` 手順 + + + +`make` コマンドの完全な構文は `::` です: + +* `` はキーボードのパスです。例えば、`planck` + * 全てのキーボードをコンパイルするには `all` を使います。 + * リビジョンを選択してコンパイルするためのパスを指定します。例えば `planck/rev4` あるいは `planck/rev3` + * キーボードにフォルダが無い場合は、省略することができます + * デフォルトのフォルダをコンパイルする場合は、省略することができます +* `` はキーマップの名前です。例えば、`algernon` + * 全てのキーマップをコンパイルするには `all` を使います。 +* `` の詳細は以下で説明します。 + +`` は以下を意味します +* target が指定されない場合は、以下の `all` と同じです +* `all` は指定されたキーボード/リビジョン/キーマップの可能な全ての組み合わせのコンパイルを行います。例えば、`make planck/rev4:default` は1つの .hex を生成しますが、`make planck/rev4:all` は planck で利用可能な全てのキーマップについて hex を生成します。 +* `flash`、`dfu`、`teensy`、`avrdude`、`dfu-util` または `bootloadHID` はファームウェアをコンパイルし、キーボードにアップロードします。コンパイルが失敗すると、何もアップロードされません。使用するプログラマはキーボードに依存します。ほとんどのキーボードでは `dfu` ですが、ChibiOS キーボードについては `dfu-util` 、標準的な Teensy については `teensy` を使います。キーボードに使うコマンドを見つけるには、キーボード固有の readme をチェックしてください。 +* **注意**: 一部のオペレーティングシステムではこれらのコマンドが機能するためには root アクセスが必要です。その場合、例えば `sudo make planck/rev4:default:flash` を実行する必要があります。 +* `clean` は、全てをゼロからビルドするためにビルド出力フォルダを掃除します。説明できない問題がある場合は、通常のコンパイルの前にこれを実行してください。 + +make コマンドの最後、つまり target の後に追加のオプションを追加することもできます + +* `make COLOR=false` - カラー出力をオフ +* `make SILENT=true` - エラー/警告以外の出力をオフ +* `make VERBOSE=true` - 全ての gcc のものを出力 (デバッグする必要が無い限り面白くありません) +* `make EXTRAFLAGS=-E` - コンパイルせずにコードを前処理 (#define コマンドをデバッグしようとする場合に便利) + +make コマンド自体にもいくつかの追加オプションがあります。詳細は `make --help` を入力してください。最も有用なのはおそらく `-jx` です。これは複数の CPU を使ってコンパイルしたいことを指定し、`x` は使用したい CPU の数を表します。設定すると、特に多くのキーボード/キーマップをコンパイルしている場合は、コンパイル時間を大幅に短縮することができます。通常は、コンパイル中に他の作業を行うための余裕をもたせるために、持っている CPU の数より1つ少ない値に設定します。全てのオペレーティングシステムと make バージョンがオプションをサポートしているわけではないことに注意してください。 + +コマンドの例を幾つか示します + +* `make all:all` は、全てをビルドします (全てのキーボードフォルダ、全てのキーマップ)。`root` から単に `make` を実行すると、これを実行します。 +* `make ergodox_infinity:algernon:clean` は、Ergodox Infinity キーボードのビルド出力を掃除します。 +* `make planck/rev4:default:flash COLOR=false` カラー出力なしでキーマップをビルドしアップロードします。 + +## `rules.mk` オプション + +無効にするにはこれらの変数を `no` に設定します。有効にするには `yes` に設定します。 + +`BOOTMAGIC_ENABLE` + +これにより、1つのキーとソルトキー(デフォルトではスペース)を押し続けることで、電力が失われても持続する様々な EEPROM 設定へアクセスできます。誤って設定が変更されることが多く、デバッグするのが難しい混乱した結果を生成するため、これを無効にしておくことをお勧めします。ヘルプセッションで発生する、より一般的な問題の1つです。 + +`MOUSEKEY_ENABLE` + +これにより、キーコード/カスタム関数を介して、カーソルの動きとクリックを制御することができます。 + +`EXTRAKEY_ENABLE` + +これにより、システムとオーディオ制御キーコードを使うことができます。 + +`CONSOLE_ENABLE` + +これにより、[`hid_listen`](https://www.pjrc.com/teensy/hid_listen.html) を使って読むことができるメッセージを出力することができます。 + +デフォルトで、全てのデバッグ( *dprint* ) 出力 ( *print*、*xprintf* )、およびユーザ出力 ( *uprint* ) メッセージが有効になります。これにより、フラッシュメモリの大部分が消費され、キーボードの .hex ファイルが大きすぎてプログラムできなくなるかもしれません。 + +デバッグメッセージ( *dprint* ) を無効にし、.hex ファイルのサイズを小さくするには、`config.h` に `#define NO_DEBUG` を含めます。 + +出力メッセージ( *print*、*xprintf* )とユーザ出力( *uprint* ) を無効にし、.hex のファイルサイズを小さくするには、`config.h` に `#define NO_PRINT` を含めます。 + +出力メッセージ ( *print*、*xprintf* ) を無効にし、ユーザメッセージ ( *uprint* )を**そのままにする**には、`config.h` に `#define USER_PRINT` を含めま