Merge pull request #16 from statiolake/participate

Explain how to participate in AtCoder using Rust

Author: tatsuya6502

Diff for: src/SUMMARY.md

@@ -2,25 +2,25 @@
 
 # Summary
 
-- [はじめに (TODO)](./introduction.md)
-- [AtCoderの環境について (TODO)](./todo.md)
-  - [ソフトウェアのバージョンなど (TODO)](./todo.md)
-  - [単一のソースファイル (TODO)](./todo.md)
-  - [利用可能なクレート (TODO)](./todo.md)
-- [開発環境の準備 (TODO)](./todo.md)
-  - [Rustツールチェインのインストール (TODO)](./todo.md)
-  - [ソースコードエディタとデバッガの準備 (TODO)](./todo.md)
-  - [cargo-generateテンプレート (TODO)](./todo.md)
-    - [cargo-generateのインストール (TODO)](./todo.md)
-- [コンテストの参加方法 (TODO)](./todo.md)
-  - [Cargoパッケージの作成 (TODO)](./todo.md)
-  - [利用するクレートの選択 (TODO)](./todo.md)
-  - [テストケースの作成 (TODO)](./todo.md)
-  - [プログラムの作成 (TODO)](./todo.md)
-  - [プログラムのテスト (TODO)](./todo.md)
-  - [プログラムの提出 (TODO)](./todo.md)
-- [Tips（小技集） (TODO)](./todo.md)
-  - [クレートの使用例 (TODO)](./todo.md)
+- [はじめに](./introduction.md)
+- [AtCoderの環境について](./environment.md)
+- [開発環境の準備 (TODO)](./installation/index.md)
+  - [Rustツールチェインのインストール (TODO)](./installation/toolchain.md)
+  - [ソースコードエディタの準備 (TODO)](./installation/editor.md)
+  - [Rust Language Server のインストール](./installation/rls.md)
+  - [cargo-generateのインストール](./installation/cargo-generate.md)
+- [コンテストの参加方法 (TODO)](./participate/index.md)
+  - [コンテスト直前の事前準備](./participate/before-contest/index.md)
+    - [Cargoパッケージの作成 (TODO)](./participate/before-contest/generate-project.md)
+    - [利用するクレートの選択とコンパイル (TODO)](./participate/before-contest/choose-crates.md)
+    - [プロジェクトのコピー (TODO)](./participate/before-contest/copy-project.md)]
+  - [コンテスト開始後の流れ](./participate/during-contest/index.md)
+    - [テストケースの作成](./participate/during-contest/write-tests.md)
+    - [プログラムの作成 (TODO)](./participate/during-contest/write-program.md)
+    - [プログラムのテスト](./participate/during-contest/test.md)
+    - [プログラムの提出 (TODO)](./participate/during-contest/submit.md)
+- [Tips（小技集） (TODO)](./tips.md)
+  - [クレートの使用例](./use-crates.md)
 - [AtCoder運営者向けの情報](./atcoder-env/index.md)
   - [本章で想定している環境](./atcoder-env/supported-environment.md)
   - [インストール](./atcoder-env/installation.md)

Diff for: src/atcoder-env/compiling-and-running-using-cargo.md

@@ -1,3 +1,5 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
 # [cargo] ファイルレイアウトとコンパイルの流れ
 
 選手がRustプログラムを提出すると、その内容がジャッジサーバ上のファイルシステムに書き出されます。
@@ -21,7 +23,8 @@ $HOME                      # ユーザのホームディレクトリ
 
 以上でCargoプロジェクトが整いました。
 
-# コンパイルコマンド
+
+## コンパイルコマンド
 
 ツールチェインのインストールのページで説明したように、コンパイルを実行するシェルに以下の環境変数が設定されている必要があります。
 

Diff for: src/atcoder-env/compiling-and-running-using-rustc.md

@@ -1,3 +1,5 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
 # [rustc] ファイルレイアウトとコンパイルの流れ
 
 選手がRustプログラムを提出すると、その内容がジャッジサーバ上のファイルシステムに書き出されます。
@@ -25,7 +27,7 @@ $HOME
 ```
 
 
-# コンパイルコマンド
+## コンパイルコマンド
 
 ツールチェインのインストールのページで説明したように、コンパイルを実行するシェルに以下の環境変数が設定されている必要があります。
 

Diff for: src/atcoder-env/installing-rust-crates.md

@@ -20,6 +20,7 @@
   - 例：標準ライブラリのハッシュ関数はDoS攻撃を避けるために暗号強度があり、計算量が多い。
     競技プログラミングでは暗号強度は求められず、より計算量の少ないハッシュ関数で十分
 
+
 ### AtCoder運営者様へのお願い
 
 対象クレートの一覧は[このページ][crates-2019]にあります。
@@ -38,6 +39,7 @@
 `cargo build`コマンドを実行すると、Cargoはそれらのクレートのソースコードをダウンロードし、適切なオプションと共に`rustc`を実行することでクレートをコンパイルします。
 クレートのソースコードは`$CARGO_HOME/registory/src`にダウンロードされ、コンパイル済みのクレート（`rlib`ファイル）は`Cargo.toml`が置かれたディレクトリを起点とする相対ディレクトリ`./target/release/deps`配下に出力されます。
 
+
 ### 一般的な開発時のファイルレイアウト
 
 ```console
@@ -63,6 +65,7 @@ $HOME   # ユーザのホームディレクトリ
 
 まず、今回は各ファイルを以下のように配置し、クレートのコンパイルは導入時に済ませておくことにします。
 
+
 ### AtCoderジャッジサーバでのファイルレイアウト（導入時に配置するもの）
 
 ```console
@@ -82,6 +85,7 @@ $RUST_HOME (/usr/local/lib/rust)
 
 そしてジャッジの際には[以前説明した](./supported-environment.md#一般的なrustプログラム開発環境との違い)Cargoを利用する方法と`rustc`を利用する方法のいずれかを利用してコンパイルします。
 
+
 ### [cargo] AtCoderジャッジサーバでのファイルレイアウト（ジャッジの際に作成するもの）
 
 ```console
@@ -96,6 +100,7 @@ $HOME                      # ユーザのホームディレクトリ
                 └-- atcoder-rust-base # コンパイル、リンク済みの実行ファイル
 ```
 
+
 ### [rustc] AtCoderジャッジサーバでのファイルレイアウト（ジャッジの際に作成するもの）
 
 Cargoを使用せず、`rustc`に適切なオプション（ライブラリ検索パスなど）を与えて実行することで、事前にコンパイルしておいた`rlib`ファイルとリンクさせます。
@@ -343,6 +348,7 @@ _108 = {package = "whiteread",version = "=0.4.4",default-features = false,featur
 [the-cargo-book-platform-specific-dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies
 [the-cargo-book-specifying-dependencies]:        https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies
 
+
 ## クレートのコンパイル
 
 クレートをコンパイルしましょう。
@@ -371,4 +377,3 @@ $ find target/release/deps/ -type f | egrep -c '\.(rlib|so)$'
 66
 # ↑ 上の数字を確認
 ```
-

Diff for: src/atcoder-env/installing-rustc-dep-option-generator.md

@@ -2,7 +2,7 @@
 
 # （オプション）クレート検索パス生成ツールのインストール
 
-**Note:** この作業は実際のビルドに`rustc`を利用する場合で、クレート検索パスを指定するコンパイルオプションをツールで生成する場合に必要となります。実際のビルドで`cargo`を利用する場合と`cargo build -v`などの出力を元にしてクレート検索パスを指定するコンパイルオプションを手書きする場合などはツールは不要です。
+> Note: この作業は実際のビルドに`rustc`を利用する場合で、クレート検索パスを指定するコンパイルオプションをツールで生成する場合に必要となります。実際のビルドで`cargo`を利用する場合と`cargo build -v`などの出力を元にしてクレート検索パスを指定するコンパイルオプションを手書きする場合などはツールは不要です。
 
 このページでは`rustc`のコマンドライン・オプションを生成するツールである`rustc-dep-option-generator`のインストール手順を説明します。
 このツールはRustで書かれています。
@@ -19,6 +19,7 @@ $ sudo apt install -y libssl-dev
 
 なお`libssl-dev`は`rustc-dep-option-generator`が`cargo`をライブラリとして用いているために必要ですが、このツールではその機能は使いません。ツール実行時のネットワーク・アクセスは不要です。
 
+
 ## ツールのインストール
 
 `cargo install`コマンドでインストールします。

Diff for: src/atcoder-env/supported-environment.md

@@ -2,6 +2,7 @@
 
 # 本章で想定している環境
 
+
 ## 用語
 
 まずは用語を整理します。本章で用いる用語には以下のものがあります。

Diff for: src/environment.md

@@ -0,0 +1,10 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
+# AtCoderの環境について
+
+現在 AtCoder で利用できる最新の環境は 2020 年言語アップデートによって更新された環境です。
+
+- Rust 1.42.0
+- 外部クレートあり
+
+コンパイルオプションや利用できる外部クレートの一覧と簡単な解説やコード例など、この環境についてのより詳しい情報は [2020 Update](https://github.com/rust-lang-ja/atcoder-rust-resources/wiki/2020-Update) のページにまとまっています。ご一読ください。

Diff for: src/installation/cargo-generate.md

@@ -0,0 +1,41 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
+# `cargo-generate` のインストール
+
+AtCoder で利用できる Rust のバージョンやライブラリを指定したプロジェクトを簡単に生成するために、 [atcoder-rust-base の ja ブランチ](https://github.com/rust-lang-ja/atcoder-rust-base/tree/ja)にプロジェクトの雛形を用意しています。この雛形は`cargo generate`というコマンドを使って展開するため、先にこのコマンドをインストールする必要があります。
+
+`cargo generate` サブコマンドを利用できるようにするには `cargo-generate` が必要です。端末 (Windows ユーザーの方はコマンド プロンプト) を開いて `cargo install cargo-generate` コマンドを実行してください。これだけでインストールは完了です。
+
+```console
+$ cargo install cargo-generate
+    Updating crates.io index
+Downloaded cargo-generate v0.5.0
+(...中略...)
+    Compiling cargo-generate v0.5.0
+    Finished release [optimized] target(s) in 5m 46s
+Installing ...
+    Installed package `cargo-generate v0.5.0` (executable `...`)
+```
+
+実際に `cargo generate --help` として実行できるかどうかを確認しましょう。
+
+```console
+$ cargo generate --help
+cargo-generate 0.5.0
+Ashley Williams <[email protected]>
+cargo, make me a project
+
+USAGE:
+    cargo generate [FLAGS] [OPTIONS] --git <git>
+
+FLAGS:
+    -f, --force      Enforce to create a new project without case conversion of project name
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+    -v, --verbose
+
+OPTIONS:
+        --branch <branch>
+        --git <git>
+    -n, --name <name>
+```

Diff for: src/installation/editor.md

@@ -0,0 +1,22 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
+# ソースコードエディタの準備
+
+Rust プログラムのソースコードは単純なテキストファイルです。編集にはテキストエディタというプログラムを使います。単純にテキストを読み書きするという機能に限ればテキストエディタは OS にも付属していますが、よりプログラミングに特化した機能を多く揃えるテキストエディタが無料で簡単に使える時代ですので、ぜひ活用するべきです。それらのエディタが持つ機能には例えば次のようなものがあります。 (一例です)
+
+- コードハイライト  
+    文法構造に合わせてソースコードを色付けして表示する機能です。たとえば型名や関数名などに色がつきます。この機能はコードを視覚的に把握するのに役立ちます。
+- 入力補完  
+    変数名や関数名の最初の何文字かを入力するだけでそれから始まる要素を列挙して表示してくれます。目当てのものがあればキー一つで残りの部分を補完してくれます。
+- エラーハイライト  
+    入力するのと同時にリアルタイムに内容をチェックし、エラーがあればそれをエディタ上に赤線を引くなどの形で表示してくれます。コンパイラを直接実行する手間もエラーメッセージを読み解く手間もなくエラーに気づくことができるメリットがあります。
+- ドキュメント (説明書き) の表示  
+    久しぶりに使う関数の引数の数や順番がわからなくなることはよくあることですが、こういうときにマウスカーソルを関数に合わせるだけでその関数のシグネチャやドキュメントを表示してくれます。
+- 定義へのジャンプ  
+    その関数や型が定義されている場所を開いてくれます。構造体の中身を少し忘れてしまったり、関数の処理の中身を確認したりといったときに簡単にソース上を移動できます。
+
+こういった機能は Language Server Protocol という共通の仕組みの上に実装されているので、これをサポートするエディタであればこれらの機能を享受できます。 Language Server Client を実装しているエディタは無数にあり、どれを使うかは完全に好みです。
+
+本説明はできるだけエディタによらないように進めていくつもりですが、エディタに特有の内容が現れるときは [Visual Studio Code](https://code.visualstudio.com/) を想定して説明します。それ以外のエディタを使われる方は適宜読み替えてお読みください。次節で Rust のコーディング支援機能を導入する方法を説明します。
+
+(TODO: Visual Studio Code のインストールと Rust (rls) 拡張機能のインストールを説明する)

Diff for: src/installation/index.md

@@ -0,0 +1,11 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
+# 開発環境の準備
+
+**TODO** このページは書きかけです。
+
+この章では、手元のパソコンに Rust の開発環境と、テキストエディタとして [Visual Studio Code](https://code.visualstudio.com/) をインストールする方法について説明します。
+
+環境を手元に用意するメリットは普段使い慣れたエディタや環境でコーディングできるようになることです。開発環境を用意して Language Server Protocol に対応するエディタ ([Visual Studio Code](https://code.visualstudio.com/) など) を利用すれば、入力補完やリアルタイムのエラーチェックなど様々な機能の恩恵を受けることができます。逆に言うと、自分の使い慣れたエディタや環境を使いたいと思わずむしろ環境を整える方が面倒だと感じられる方は AtCoder のコードテスト (TODO: リンクが完成次第挿入) を利用するのが最も簡単な方法です。外部ライブラリにまつわる互換性の問題もありません。
+
+既に Rust の開発環境がインストールされており、普段使い慣れたエディタや編集環境もあるという方には前半は全く不要な話となります。[`cargo-generate` のインストール](cargo-generate.md)へお進みください。それもインストールされている方はこの章で説明することはありませんので、実際に[参加方法の説明](../participate/index.md)へお進みください。

Diff for: src/installation/rls.md

@@ -0,0 +1,51 @@
+<!-- -*- coding:utf-8-unix -*- -->
+
+# Rust Language Server のインストール
+
+Rust Language Server (RLS) は、ソースコード編集中の様々な支援機能を提供するためのプログラムです。例えば、プログラムを編集しながらリアルタイムでエラー箇所をハイライトしたり、コード補完機能を提供したり、定義にジャンプしたり、簡単なドキュメントを表示したりといった様々な機能があります。使い慣れたエディタとともにこうした支援機能が使えることが、ローカルに Rust の環境を作る大きなメリットです。
+
+なお、こうしたコーディング支援機能が不要だと考える方はインストールをする必要はありません。
+
+> Note: Visual Studio Code を利用している方は、拡張機能が自動的にインストールしてくれるため、ここで直接インストールする必要はありません。
+
+さて、 RLS は Rust 本体と同時に配布されているため、 RLS のインストールをする前に対応するバージョンの Rust をインストールしなければなりません。現在 AtCoder で使える Rust のバージョンは 1.42.0 ですので、コマンド プロンプトあるいは端末を開いて次のようにコマンドを実行します。
+
+```console
+$ rustup install 1.42.0
+info: syncing channel updates for '1.42.0-x86_64-pc-windows-msvc'
+info: latest update on 2020-03-12, rust version 1.42.0 (b8cedc004 2020-03-09)
+info: downloading component 'cargo'
+info: downloading component 'clippy'
+info: downloading component 'rust-docs'
+ 12.0 MiB /  12.0 MiB (100 %)   5.9 MiB/s in  1s ETA:  0s
+info: downloading component 'rust-std'
+info: downloading component 'rustc'
+ 35.6 MiB /  35.6 MiB (100 %)  28.2 MiB/s in  1s ETA:  0s
+info: downloading component 'rustfmt'
+info: installing component 'cargo'
+info: installing component 'clippy'
+info: installing component 'rust-docs'
+ 12.0 MiB /  12.0 MiB (100 %)   2.4 MiB/s in  4s ETA:  0s
+info: installing component 'rust-std'
+info: installing component 'rustc'
+ 35.6 MiB /  35.6 MiB (100 %)  10.7 MiB/s in  3s ETA:  0s
+info: installing component 'rustfmt'
+
+  1.42.0-x86_64-pc-windows-msvc installed - rustc 1.42.0 (b8cedc004 2020-03-09)
+
+info: checking for self-updates
+```
+
+続けて RLS をインストールします。なお必要なコンポーネントは変わるかもしれませんので、適宜 [RLS のリポジトリ](https://github.com/rust-lang/rls)も参照してください。
+
+```console
+$ rustup component add --toolchain 1.42.0 rls rust-analysis rust-src
+info: downloading component 'rls'
+info: installing component 'rls'
+info: downloading component 'rust-analysis'
+info: installing component 'rust-analysis'
+info: downloading component 'rust-src'
+info: installing component 'rust-src'
+```
+
+両方の実行が完了すれば、 RLS のインストールは終了です。