Merge pull request #9 from SamurAI-Coding/README

Update: README.md

README-jp.txt

@@ -1,8 +1,8 @@
 SamurAI Jockey ゲーム用ソフトウェアについて
 
-                                                            2017/09/30
+                                                            2017/12/30
 
-このディレクトリには SamurAI Coding 2017-2018 で用いるために準備中の
+このディレクトリには SamurAI Coding 2017-18 で用いるために準備中の
 SamurAI Jockey ゲーム用のソフトウェアが入っています。
 
 1. ディレクトリ構成
@@ -33,15 +33,35 @@ viewer/viewer.html をブラウザで開きます。
 
 documents ディレクトリには以下の文書が入っています。
 
-  rule-jp.pdf: ゲームのルール案
-  rule-en.pdf: ゲームのルール案 (英語版)
+  rule-jp.pdf: ゲームのルール
+  rule-en.pdf: ゲームのルール (英語版)
   datafiles.pdf: 情報交換に用いるファイルの形式
 
 4. インストール
 
 実行管理システムとサンプルプレイヤについては、各ディレクトリで make を走らせてください。
 インストールには C++11 対応の C++ 言語システムと boost ライブラリが必要です。
 
+boost ライブラリについてはバージョン 1.64.0 以上が必要です。
+パッケージマネージャでインストールする際はそのバージョンについて確認してください。
+特に Ubuntu の apt : Advanced Package Tool では
+標準パッケージアーカイブからインストールができません。
+
+ビルド・インストール方法は下記サイトが参考になります。
+  https://boostjp.github.io/howtobuild.html
+フルインストールするのも選択肢の一つですが、
+実行管理システムを実行するには
+  system, filesystem, program_options
+ライブラリをインストールする必要があるため、 b2 プログラムに
+  --with-system --with-filesystem --with-program_options
+オプションを付けてビルド・インストールすると最小構成になります。
+詳細は本ファイル下部の「付録」をご覧ください。
+
+試験的に boost ライブラリを静的リンクした実行管理システムのバイナリを
+下記 GitHub Release ページにて配布しておりますのでご活用ください。
+  https://github.com/SamurAI-Coding/Software2017-18/releases/latest
+これを利用する際には boost のインストールは必要ありません。
+
 ビューワとエディタについては特段のインストールは不要で、
 Javascript を利用できるウェブブラウザーならすぐ実行できます。
 
@@ -50,7 +70,7 @@ Javascript を利用できるウェブブラウザーならすぐ実行できま
 (1) 実行管理システム
 
 コマンドラインに以下のように引数を指定します。
-　　./official <course file> <player0> <name0> <player1> <name1> [ <log0> <log1> ]
+  ./official <course file> <player0> <name0> <player1> <name1> [<option>...]
 各引数は以下のとおりです。
 
   <course file>:
@@ -62,9 +82,37 @@ Javascript を利用できるウェブブラウザーならすぐ実行できま
     player ディレクトリで make すれば、サンプルが player/greedy にできます。
   <name0>, <name1>:
     Viewer の表示に使う AI プログラムの名前の文字列です。
-  <log0>, <log1>
-    これらのパス名を指定すると、AI プログラムに送ったデータのコピーを格納します。
-    これらを AI プレイヤの入力とすれば、デバッグに便利でしょう。
+  <option>:
+    --stdinLogFile0 <filename>:
+    --stdinLogFile1 <filename>:
+      これらのパス名を指定すると、対象の AI プログラムに送ったデータのコピーを指定した格納します。
+      これらを AI プレイヤの入力とすれば、デバッグに便利でしょう。
+    --stderrLogFile0 <filename>:
+    --stderrLogFile1 <filename>:
+      これらのパス名を指定すると、対象の AI プログラムが出力した標準エラー出力のコピーと
+      システムメッセージが指定したファイルに格納されます。
+      デバッグにご活用ください。
+    --pauseP0 <command>:
+    --resumeP0 <command>:
+    --pauseP1 <command>:
+    --resumeP1 <command>:
+      ルールに記載されているように、「ゲーム管理システムは, 各ステップについて出力を終了した
+      AI の動作を一時停止し, 次ステップの情報を与える際に動作を再開させ」ます。
+      これを実現するためのオプションとなっており、通常はこのオプションを利用する必要がありません。
+    -h [--help]:
+      ヘルプメッセージを出力します。内容はここで書いてあることと同じです。
+
+例えばビルドの済んだトップディレクトリで
+
+  ./official/official samples/sample-course.smrjky player/greedy 0 player/greedy 1 --stdinLogFile0 stdin0.txt --stdinLogFile1 stdin1.txt --stderrLogFile0 stderr0.txt --stderrLogFile1 stderr1.txt > gamelog.json
+
+を実行すると
+  stdin0.txt : player0 に与えられた入力
+  stdin1.txt : player1 に与えられた入力
+  stderr0.txt : player0 の標準エラー出力とシステムメッセージ
+  stderr1.txt : player1 の標準エラー出力とシステムメッセージ
+  gamelog.json : ゲームのログ(後述の(3) レースビューワでその内容を確認できます)
+が得られます。
 
 (2) コース編集ソフトウェア
 
@@ -78,8 +126,77 @@ Javascript を利用できるウェブブラウザーならすぐ実行できま
 
 6. 既知のバグ・未実装機能
 
-- AI プログラムの実行についての制限が未実装
-  - 考慮時間の管理はまだ実装していません。
-  - ファイルやネットワークへのアクセスを制限していません。
+なし
+
+最新の情報については
+  https://github.com/SamurAI-Coding/Software2017-18/issues
+で確認することができます。
+何か問題が発生したらこちらに連絡いただくか
+  samurai-contact@ipsj.or.jp
+宛にメールください。
+もちろん、
+  https://github.com/SamurAI-Coding/Software2017-18/pulls
+から修整を送っていただいても構いません。
+
+付録. boost のビルド・インストール
+
+各環境におけるビルド・インストール方法の一例を紹介します。
+
+(1) Linux
+
+  下記コマンドを実行します。必要に応じて変更してください。
+    wget -O boost_1_65_1.tar.gz https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz
+    tar zxvf boost_1_65_1.tar.gz
+    cd boost_1_65_1
+    ./bootstrap.sh
+    sudo ./b2 install --with-system --with-filesystem --with-program_options --prefix=/usr/local
+
+(2) Mac
+
+  brew (https://brew.sh/index_ja.html) をインストールされていたら
+    brew update
+    brew install boost
+  でインストールできます。
+
+  brew をインストールしておらず、brew をインストールしたくない方は
+  (1) Linux の方法に準じてください。
+
+(3) Windows
+
+  (3-1) msys2/mingw*
+    msys2 (http://www.msys2.org/) をインストールされていたら、
+    mingw 環境において
+      pacman -Syu
+    をしてシステムを更新した後、
+      pacman -Ss boost
+    と検索して該当するパッケージをインストールします。
+    例えば、x86_64 の msys2 をインストールしていて mingw64 環境を利用している場合
+      pacman -S mingw-w64-x86_64-boost
+    とします。
+    インストールされる boost ライブラリは -mt (multi-thread) という接尾辞がついているもののみになるようです。
+    実行管理システムをビルドする際には事前に
+      export BOOST_LIB_SUFFIX=-mt
+    というコマンドを実行してください。この環境変数は make 時に利用されます。
+
+  (3-2) Visual Studio
+    boost ライブラリの最新バージョンの zip アーカイブを
+      C:\Users\<User name>\boost\<Boost Version>
+        ex) C:\Users\samurai\boost\boost_1_65_1
+    に解凍したとします。このとき C:\Users\<User name>\boost\<Boost Version> を BOOST_ROOT として環境変数に登録してください。
+    次に Native Tools コマンドプロンプトを開いてください。例えば Visual Studio 2017 Community Edition をインストールしていたら
+      "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
+    などがそれに該当します。
+    以下のコマンドを実行します。下記コマンドは Visual Studio 2017 がインストールされた環境に合わせています。
+      cd %BOOST_ROOT%
+      .\bootstrap.bat
+      .\b2 install toolset=msvc-14.1 --with-system --with-filesystem --with-program_options --prefix=%BOOST_ROOT%
+      move %BOOST_ROOT%\include\boost-1_65\boost %BOOST_ROOT%\include\boost
+      rd %BOOST_ROOT%\include\boost-1_65
+    toolset には Visual C++ のバージョンを指定します。
+    他バージョンについては
+      https://ja.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B#%E8%A3%BD%E5%93%81%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E3%81%A8%E5%86%85%E9%83%A8%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3
+    が参考になるかと思います。
+    インストールが終了したら、トップレベルの SamurAI_Coding_2017-18_Software.sln を開くとソフトウエアをビルドするためのソリューションが開かれます。
+
 
 以上

README.md

@@ -1 +1,9 @@
-# Software2017-18
+# software for SamurAI Coding 2017-18
+
+[![Build Status](https://travis-ci.org/SamurAI-Coding/Software2017-18.svg?branch=master)](https://travis-ci.org/SamurAI-Coding/Software2017-18)
+
+[This repo](https://github.com/SamurAI-Coding/Software2017-18) contains software including the game manager, the course editor, the visualizer, and samples of AI programs and race courses for [SamurAI Coding 2017-18](http://samuraicoding.info/).  We develop this software using this github repository, and distribute release versions at our contest website.
+
+When you faced any issue, we would be grateful if you could report [Issues](https://github.com/SamurAI-Coding/Software2017-18/issues) and/or make [Pull requests](https://github.com/SamurAI-Coding/Software2017-18/pulls).  We will make some reaction as soon as possible.
+
+For the details about the software, see [this(README.txt)](./README.txt) or [this(README-jp.txt)](./README-jp.txt) first.

README.txt

@@ -1,9 +1,9 @@
 SamurAI Jockey Game Software
 
-                                                            2017/09/30
+                                                            2017/12/30
 
-This directory contains a draft version of software for the SamurAI
-Jockey game, to be used in the SamurAI Coding 2017-2018 contest.
+This directory contains software for the SamurAI Jockey game,
+to be used in the SamurAI Coding 2017-18 contest.
 
 1. Directory Structure
 
@@ -33,54 +33,154 @@ For more details, click the "Help" button to browse the manual page.
 
 The "documents" directory contains the following documents.
 
-  rule-en.pdf: Game rule draft
-  rule-jp.pdf: Game rule draft (in Japanese)
-  datafiles.pdf: Desciption of data file formats
+  rule-en.pdf: Game rule
+  rule-jp.pdf: Game rule (in Japanese)
+  datafiles.pdf: Description of data file formats (in Japanese)
 
 4. Installation
 
-For the execution management system and sample players,
-run "make" in the respective directories.
-A C++ language system conforming C++11 and the boost library is required.
-
-For the viewer and the editor, no installation is needed.
-They can be executed immediately with web browsers capable of executing Javascript.
+To build the execution management system and sample players,
+run "make" in the corresponding directories.
+A C++ language system supporting C++11 and the Boost library are required.
+
+The Boost library must be Version 1.64.0 or newer.
+Check the version of Boost if you install it using package manager.
+Especially, apt (Advanced Package Tool) on Ubuntu
+cannot install Boost of the requierd version from their standard package archives.
+Please get and install Boost manually referring to the following website.
+  http://www.boost.org/doc/libs/1_66_0/more/getting_started/index.html
+You can choose full installation, but our game manager only requires
+  system, filesystem, program_options
+libraries.  So, the minimum configuration is to run b2 program with the following options:
+  --with-system --with-filesystem --with-program_options
+Please refer to Appendix of this file for details.
+
+We also distribute a game manager to which the Boost libraries are statically linked
+(experimental) in the following GitHub Release page:
+  https://github.com/SamurAI-Coding/Software2017-18/releases/latest
+You need not install Boost if you use this.
+
+For the viewer and the editor, no installation operation is necessary.
+They can be executed on a web browser supporting Javascript.
 
 5. Usage
 
 (1) Execution Management System
 
-Arguments in the command line should be specified as follows.
-　　./official <course file> <player0> <name0> <player1> <name1> [ <log0> <log1> ]
+The following command line arguments should be specified.
+　　./official <course file> <player0> <name0> <player1> <name1> [<option>...]
 
   <course file>:
     File describing the course to be used in the race.
-    This is usually a file output by the editor by clicking the "Write" button.
-    A sample can be found in "sample/sample-course.smrjky".
+    This file is usually output by clicking the "Write" button on the course editor.
+    "sample/sample-course.smrjky" is a sample of a course file.
   <player0>, <player1>:
-    Pathnames for executables of AI programs to compete in the race.
-    A sample player executable is made as "player/greedy"
+    Pathnames of executables of AI programs to compete in the race.
+    A sample player executable can be built as "player/greedy"
     by running "make" in the "player" directory.
   <name0>, <name1>:
-    Names of AI programs to be used by the race viewer.
-  <log0>, <log1>
-    When these pathnames are specified, copies of data sent to AI programs
-    will be stored.
-    These might be useful for debugging AI programs.
+    Names of AI programs to be used in the race viewer.
+  <option>:
+    --stdinLogFile0 <filename>:
+    --stdinLogFile1 <filename>:
+      When these pathnames are specified, copies of data sent to AI programs
+      will be stored.
+      These may be useful for debugging AI programs.
+    --stderrLogFile0 <filename>:
+    --stderrLogFile1 <filename>:
+      When these pathnames are specified, the standard error output of AI programs
+      and our system messages will be stored.
+      These may be useful for debugging AI programs.
+    --pauseP0 <command>:
+    --resumeP0 <command>:
+    --pauseP1 <command>:
+    --resumeP1 <command>:
+      The Game Rule says
+        "At each step, the game management system suspends the execution of AI
+         when receiving its output has been completed, and resumes it after giving per step information".
+      These options are used to perform this. You need not specify these options under normal use.
+    -h [--help]:
+      Output the help message.  The content is almost the same to this document.
 
 (2) Course Editor
 
   Open "editor/editor.html" with a web browser.
-  A mannual page can be found by clicking the "Help" button at top right.
+  A manual page can be shown by clicking the "Help" button on the top right.
 
 (3) Race Viewer
 
   Open "viewer/viewer.html" with a web browser.
-  A mannual page can be found by clicking the "Help" button at top right.
-
-6. Known Bugs and Features Not Implemented (yet)
-
-- Restrictions of execution of AI programs
-  - Management of think time is not implemented yet.
-  - File and network accesses are not disabled.
-
+  A manual page can be shown by clicking the "Help" button on the top right.
+
+6. Known Bugs and Features Not Implemented yet
+
+None
+
+Latest infomation:
+  https://github.com/SamurAI-Coding/Software2017-18/issues
+When you faced any issue, please report from this website or by e-mail:
+  samurai-contact@ipsj.or.jp
+Of course you can send a fix from
+  https://github.com/SamurAI-Coding/Software2017-18/pulls
+
+Appendix: How to install the Boost libraries
+
+The followings show examples of installation operations on several platforms.
+
+(1) Linux
+
+  Run the following commands (Please modify them as necessary).
+    wget -O boost_1_66_0.tar.gz https://dl.bintray.com/boostorg/release/1.66.0/source/boost_1_66_0.tar.gz
+    tar zxvf boost_1_66_0.tar.gz
+    cd boost_1_66_0
+    ./bootstrap.sh
+    sudo ./b2 install --with-system --with-filesystem --with-program_options --prefix=/usr/local
+
+(2) Mac
+
+  If you have installed brew (https://brew.sh/), you can run following commands on terminal to install boost.
+    brew update
+    brew install boost
+
+  In case you have not installed and do not want to install brew,
+  follow the process written in (1) Linux.
+
+(3) Windows
+
+  (3-1) msys2/mingw*
+    If you have installed msys2 (http://www.msys2.org/),
+    in mingw environment, run
+      pacman -Syu
+    to update system, and run
+      pacman -Ss boost
+    to search boost packages.
+    In case you use mingw64 on x86_64, you should run
+      pacman -S mingw-w64-x86_64-boost
+    to install.
+    The Boost libraries installed on mingw* seem to be only those with suffix "-mt" (multi-thread).
+    Hence, you may need to run the following command before building our software.
+      export BOOST_LIB_SUFFIX=-mt
+    This environment variable will be used in the "make" process.
+
+  (3-2) Visual Studio
+    Suppose that the zip archive of latest Boost libraries is extrated to the following path:
+      C:\Users\<User name>\boost\<Boost Version>
+      (e.g., C:\Users\samurai\boost\boost_1_66_0)
+    Then, you need to register the environment variable `BOOST_ROOT` as the path written above.
+    You can check this environmnet variable by the following command on a command prompt (cmd.exe).
+      echo %BOOST_ROOT%
+    Next, open a Native tools command prompt.
+    For example, if you have installed Visual Studio 2017 Community Edition, execute
+      "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
+    Lastly, run the following commands on the Native tools command prompt (Please modify them as necessary).
+      cd %BOOST_ROOT%
+      .\bootstrap.bat
+      .\b2 install toolset=msvc-14.1 --with-system --with-filesystem --with-program_options --prefix=%BOOST_ROOT%
+      move %BOOST_ROOT%\include\boost-1_66\boost %BOOST_ROOT%\include\boost
+      rd %BOOST_ROOT%\include\boost-1_66
+    Note that you need to specify the version of Visual C++ to the "toolset" option above.
+    For specifying the versions other than msvc-14.1,
+      https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B
+    will be helpful.
+    After installation, open "SamurAI_Coding_2017-18_Software.sln" in the top level directory.
+    This is the solutiuon file to build our software.