Brush up the AtCoder installation chapter

tatsuya6502 · tatsuya6502 · commit 18ab521bfbc1 · 2019-06-26T19:26:52.000+08:00
diff --git a/src/atcoder-env/compiling-and-running-program.md b/src/atcoder-env/compiling-and-running-program.md
@@ -3,3 +3,8 @@
 # コンパイルコマンドと実行コマンド
 
 **TODO** このページは書きかけです。
+
+
+## コンパイルオプションについて
+
+**TODO**
diff --git a/src/atcoder-env/index.md b/src/atcoder-env/index.md
@@ -2,10 +2,11 @@
 
 # AtCoder運営者向けの情報
 
-**TODO** このページは書きかけです。
-
 本章では以下の内容について説明します。
 
 - Rustツールチェインやクレート（外部ライブラリ）をジャッジサーバへインストールする手順
 - 提出されたプログラムのコンパイルおよび実行手順
 
+内容について質問などがありましたら、[GitHub Issue][gh-issue]などでご連絡ください。
+
+[gh-issue]: https://github.com/rust-lang-ja/atcoder-rust-resources/issues
diff --git a/src/atcoder-env/installation.md b/src/atcoder-env/installation.md
@@ -2,9 +2,9 @@
 
 # インストール
 
-**TODO** このページは書きかけです。
+本節では以下の内容について説明します。
 
 - Rustツールチェインのインストール
-- クレート（外部ライブラリ）のビルドとインストール
-- クレートの検索パス生成プログラムのビルドとインストール
+- クレート（外部ライブラリ）のコンパイルとインストール
+- クレートの検索パス生成ツールのインストール
 - インストール後の動作確認
diff --git a/src/atcoder-env/installing-rust-crates.md b/src/atcoder-env/installing-rust-crates.md
@@ -1,45 +1,49 @@
 <!-- -*- coding:utf-8-unix -*- -->
 
-# Rustクレート（外部ライブラリ）のビルドとインストール
+# クレートのコンパイルとインストール
 
 本ページではAtCoderのジャッジサーバにRustの外部ライブラリであるクレートをインストールする手順を説明します。
 
 
 ## インストールするクレートについて
 
-今回インストールの対象となるクレートは、Slack上のRust日本語コミュニティ「rust-jp」のメンバーによって選定されました。
+今回インストールするクレートは、SlackのRust日本語コミュニティ「rust-jp」のメンバーがAtCoderでぜひ使いたいと考えているものです。
+大半は既存のクレートですが、この機会に新たに開発したものもあります。
 
-選定にあたって、以下の点を重視しました。
+これらのクレートは主に以下の種類に分類されます。
 
-- 他のいくつかの言語の標準ライブラリにあって、Rustにない機能
-  - 例：C++の`lower-bound`や`BitSet`に相当する機能
+- 他のいくつかの言語の標準ライブラリにあって、Rustにない機能を提供するもの
+  - 例：C++の`lower_bound`や`BitSet`に相当する機能
 - 競技プログラミングの面白さを損なわない範囲（ズルにならない範囲）で便利になるもの
-  - 例：Rustでは入出力関連の記述が煩雑になりがちなので、それらを簡潔に記述できるマクロ
-- セキュリティなどの理由から高速性が犠牲になっている機能の置き換え
+  - 例：Rustでは入出力関連の記述が煩雑になりがちなので、それらを簡潔に記述できるマクロ集
+- セキュリティなどの理由から高速性が犠牲になっている機能を置き換えるもの
   - 例：標準ライブラリのハッシュ関数はDoS攻撃を避けるために暗号強度があり、計算量が多い。
-    競技プログラミングでは暗号強度は求められず、より計算量が少ないハッシュ関数で十分
+    競技プログラミングでは暗号強度は求められず、より計算量の少ないハッシュ関数で十分
 
-対象クレートの一覧は このページ（**TODO**） にあります。
-導入して問題がないか、インストール前にレビューをお願いいたします。
+**AtCoder運営者様へのお願い**
 
-質問などがありましたら、[GitHub Issue][gh-issue]などでご連絡ください。
+対象クレートの一覧は このページ（**TODO**、[仮のページはこちら](https://github.com/rust-lang-ja/atcoder-rust-resources/wiki/Crates-2019)） にあります。
+インストールして問題がないか、事前にレビューをお願いいたします。
+
+質問や要望などがありましたら、[GitHub Issue][gh-issue]などでご連絡ください。
 
 [gh-issue]: https://github.com/rust-lang-ja/atcoder-rust-resources/issues
 
 
 ## ファイルレイアウトとクレートの事前コンパイル
 
+インストール作業に入る前に、背景を説明します。
 一般的な`cargo`を使用した開発では、`Cargo.toml`という設定ファイルに依存クレートの情報を記述します。
 `cargo build`コマンドを実行すると、`cargo`はそれらのクレートのソースコードをダウンロードし、適切なオプションと共に`rustc`を実行することでクレートをコンパイルします。
-クレートのソースコードは`$CARGO_HOME/registory/cache`にダウンロードされ、コンパイル済みのクレート（`rlib`ファイル）は`Cargo.toml`が置かれたディレクトリを起点とする相対ディレクトリ`./target/release/deps`配下に出力されます。
+クレートのソースコードは`$CARGO_HOME/registory/src`にダウンロードされ、コンパイル済みのクレート（`rlib`ファイル）は`Cargo.toml`が置かれたディレクトリを起点とする相対ディレクトリ`./target/release/deps`配下に出力されます。
 
 **一般的な開発時のファイルレイアウト**
 
 ```console
 $HOME   # ユーザのホームディレクトリ
 |-- $CARGO_HOME (~/.cargo)
 |   └-- registory
-|       └-- cache
+|       └-- src
 |           └-- クレートのソースコード
 |
 └-- my-package
@@ -58,16 +62,15 @@ $HOME   # ユーザのホームディレクトリ
 もしジャッジサーバでこの方法をとると、ジャッジの際のサーバ負荷が増えてしまいます。
 
 そこで今回は各ファイルを以下のように配置し、クレートのコンパイルは導入時に済ませておくことにします。
-またダウンロードしたクレートのソースコードはコンパイル後は不要ですので削除します。
 
 **AtCoderジャッジサーバでのファイルレイアウト（導入時に配置するもの）**
 
 ```console
 $RUST_HOME (/usr/local/lib/rust)
 |-- $CARGO_HOME (/usr/local/lib/rust/cargo)
 |   └-- registory
-|       └-- cache
-|           └-- クレートのソースコード　（コンパイル後に削除する）
+|       └-- src
+|           └-- クレートのソースコード
 └-- lib
     |-- Cargo.toml          # 設定ファイル。依存クレートの情報が書かれている
     └-- target
@@ -91,9 +94,11 @@ $HOME             # ユーザのホームディレクトリ
 
 ## クレートのコンパイルに使用するCargoパッケージのダウンロード
 
-それではインストールしましょう。
+それではインストール作業に入りましょう。
 クレートの事前コンパイルに使用するCargoパッケージをGitHubからダウンロードし、`/usr/local/lib/rust/lib`に配置します。
-このパッケージには`Cargo.toml`ファイルなどが含まれており、対象となるクレートがあらかじめ設定されています。
+このパッケージには`Cargo.toml`ファイルなどが含まれており、インストール対象のクレートがすでに設定されています。
+（`[dependencies]`セクションに書かれています）
+
 以下のコマンドを実行します。
 
 ```console
@@ -107,11 +112,10 @@ root
 
 ## Cargoパッケージをgit cloneする
 # git clone https://github.com/rust-lang-ja/atcoder-rust-base.git \
-    --branch ja-full --single-branch \
+    --branch ja-all-enabled --single-branch \
     ${RUST_HOME}/lib
 ```
 
-依存クレートの情報は`Cargo.toml`ファイルの`[dependencies]`セクションに書かれています。
 
 
 ## クレートのコンパイル
@@ -120,15 +124,14 @@ root
 以下のコマンドを実行します。
 
 ```console
-# cd ${RUST_HOME}/lib
+# cd $RUST_HOME/lib
 # cargo build --release
 ```
 
 コンパイルに成功すると以下のように表示されます。
 
 ```console
 # cargo build --release
-Compiling autocfg v0.1.4
 ...（中略）...
 
 Finished release [optimized] target(s) in 1m 39s
@@ -143,4 +146,3 @@ $ find target/release/deps/ -name '*.rlib' | wc -l
 58   # この数字を確認
 ```
 
-なお、`$CARGO_HOME/registory/cache`の内容は、次のページの作業が終わった後に削除します。
diff --git a/src/atcoder-env/installing-rustc-dep-option-generator.md b/src/atcoder-env/installing-rustc-dep-option-generator.md
@@ -1,23 +1,33 @@
 <!-- -*- coding:utf-8-unix -*- -->
 
-# クレート検索パス生成プログラムのビルドとインストール
+# クレート検索パス生成ツールのインストール
 
-**TODO** このページは書きかけです。
+前のページで以下のことを説明しました。
 
-- `rustc-dep-option-generator`コマンドをビルドしてインストールします。
+> ジャッジの際には、`cargo`を使用せず、`rustc`に適切なオプション（ライブラリ検索パスなど）を与えて実行することで、事前にコンパイルしておいた`rlib`ファイルとリンクさせます。
+
+本ページではこの`rustc`のコマンドライン・オプションを生成するツールである`rustc-dep-option-generator`のインストール手順を説明します。
+このツールはRustで書かれています。
 
 
 ## 依存ソフトウェアのインストール
 
-ツールのビルドに必要なシステムライブラリをインストールします。
+ツールが依存するシステムライブラリをインストールします。
 
 ```console
 $ sudo apt update
 $ sudo apt install -y libssl-dev
 ```
 
+なお`libssl-dev`はツールが依存しているクレートの1つが要求しているためにインストールしますが、このツールではその機能は使いません。
+ツール実行時のネットワーク・アクセスは不要です。
+
+
+## ツールのインストール
 
-## ツールのビルドとインストール
+`cargo install`コマンドでインストールします。
+以下のコマンドを実行すると、GitHubのリポジトリからツールのソースコードがダウンロードされ、ビルドが実行されます。
+ビルドに成功すると、生成されたバイナリ（実行可能ファイル）が`$CARGO_HOME/bin`配下にインストールされます。
 
 ```console
 $ sudo -i
@@ -28,7 +38,7 @@ root
 # cargo install --git https://github.com/rust-lang-ja/atcoder-rustc-dep-option-generator.git
 ```
 
-ビルドとインストールに成功すると以下のように表示されます。
+インストールの成功時は以下のように表示されます。
 
 ```console
 # cargo install --git https://github.com/rust-lang-ja/atcoder-rustc-dep-option-generator.git
@@ -44,8 +54,12 @@ root
   Installing /usr/local/lib/rust/cargo/bin/rustc-dep-option-generator
 ```
 
+
 ## インストール後の動作確認
 
+ツールが動作することを確認しましょう。
+以下のコマンドを実行します。
+
 ```console
 ## 一般ユーザで実行
 $ which rustc-dep-option-generator
@@ -56,10 +70,18 @@ $ echo $RUST_HOME
 
 $ export RUST_LIB=${RUST_HOME}/lib
 $ rustc-dep-option-generator ${RUST_LIB}/Cargo.toml ${RUST_LIB}/target/release/deps
-...
+--extern arrayvec=/usr/local/lib/rust/lib/target/release/deps/libarrayvec-cc9c39e9e371e142.rlib
+--extern hashbrown=/usr/local/lib/rust/lib/target/release/deps/libhashbrown-106405935e6124e3.rlib
+...（中略）...
+-L dependency=/usr/local/lib/rust/lib/target/release/deps
 
 ## ↑ Errorの文字が表示されなければOK
+##
+## エラーの例
+## Error: StringError("failed to find appropriate path for /arrayvec-0.4.10/")
 
 $ echo $?
-0
+0   # 0ならOK
 ```
+
+これでインストール作業は終了です。
diff --git a/src/atcoder-env/supported-environment.md b/src/atcoder-env/supported-environment.md
@@ -1,6 +1,6 @@
 <!-- -*- coding:utf-8-unix -*- -->
 
-# 本書が想定する環境と利用形態
+# 本章で想定している環境と利用形態
 
 **TODO** このページは書きかけです。
 
@@ -29,3 +29,8 @@
 - プログラムが作成したファイルはテストケースの実行ごとに削除される
 - ユーザプログラムをコンパイル・実行するLinuxユーザは、単一のユーザなのか、複数のユーザなのかは不明
   - 本書では複数ユーザの場合でも対応できるよう、Rustツールチェインやクレートを、ジャッジサーバ上の全Linuxユーザがread-onlyでアクセスできる場所（`/usr/local/lib/rust`）にインストールする
+
+
+## 一般的なRust開発環境との違い
+
+**TODO**
