Merge pull request #811 from kusumotolab/update-docs

ドキュメントの更新

README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img src="assets/logo.png" width="40%">
+    <img src="assets/logo.png" width="40%" alt="logo">
 </div>
 
 <p align="center">
@@ -31,12 +31,12 @@ There are sample bugs in [kusumotolab/kGenProg-example](https://github.com/kusum
 You can download all the bugs from [here](https://github.com/kusumotolab/kGenProg-example/archive/master.zip).
 
 
-## Gradle
+### Gradle
 kGenProg is also available for Gradle environments.
 Currently, kGenProg is distributed on JitPack.
 To add JitPack repository to your build file, append it in your build.gradle at the end of repositories.
 
-```
+```gradle
 allprojects {
     repositories {
         ...
@@ -47,17 +47,18 @@ allprojects {
 
 Then, please add the dependency to kGenProg.
 
-```
+```gradle
 dependencies {
     implementation 'com.github.kusumotolab:kGenProg:Tag'
+}
 ```
 Please replace `Tag` with the version ID that you want to use.
 You can find more detailed descriptions [here](https://jitpack.io/#kusumotolab/kGenProg/).
 
 
 ## Usage
 ```
-$ java -jar path/to/kGenProg.jar [(-r <path> -s <path>... -t <path>...) | --config <path>]
+$ java -jar path/to/kGenProg.jar [--config <path> | (-r <path> -s <path>... -t <path>...)]
     [-x <fqn>...] [-c <path>...] [-w <path>] [-o <path>] [-v | -q] [--headcount <num>]
     [--max-generation <num>] [--time-limit <sec>] [--test-time-limit <sec>]
     [--required-solutions <num>] [--random-seed <num>] [--fault-localization <name>]
@@ -88,6 +89,7 @@ $ java -jar path/to/kGenProg.jar
 ### Options
 | Option | Description | Default |
 |---|---|---|
+| `--config` |  Specifies the path to config file. | Reads config file named `kgenprog.toml` in the current directory. |
 | `-r`, `--root-dir` | Specifies the path to the root directory of the target project. It is recommended to specify the current directory after moving into the root directory of the target project, for implementation reason. | Nothing |
 | `-s`, `--src` | Specifies paths to "product" source code (i.e. main, non-test code), or to directories containing them. Paths are separated with spaces. | Nothing |
 | `-t`, `--test` | Specifies paths to test source code, or to directories containing them. Paths are separated with spaces. | Nothing |
@@ -96,7 +98,6 @@ $ java -jar path/to/kGenProg.jar
 | `-o`, `--out-dir` | Specifies an output directory. Generated files include patches and history json. They can be enabled by `--patch-output` or `--history-record` | `./kgenprog-out` |
 | `-v`, `--verbose` | Be more verbose, printing DEBUG level logs. | `false` |
 | `-q`, `--quiet` | Be more quiet, suppressing non-ERROR logs. | `false` |
-| `--config` |  Specifies the path to config file. | Reads config file named `kgenprog.toml` in the current directory. |
 | `--mutation-generating-count` | Specifies how many variants are generated in a generation by a mutation. | 10 |
 | `--crossover-generating-count` | Specifies how many variants are generated in a generation by a crossover. | 10 |
 | `--headcount` | Specifies how many variants survive in a generation. | 100 |
@@ -105,14 +106,15 @@ $ java -jar path/to/kGenProg.jar
 | `--test-time-limit` | Specifies a time limit in seconds to build and test each variant. | 10 |
 | `--required-solutions` | Terminates searching solutions when the specified number of solutions are found. | 1 |
 | `--random-seed` | Specifies a random seed used by a random number generator. | 0 |
-| `--scope` | Specify the scope from which source code to be reused is selected. (`PROJECT`, `PACKAGE`, `FILE`). | `PACKAGE` |
+| `--scope` | Specifies the scope from which source code to be reused is selected. (`PROJECT`, `PACKAGE`, `FILE`). | `PACKAGE` |
 | `--fault-localization` | Specifies technique of fault localization. (`Ample`, `Jaccard`, `Ochiai`, `Tarantula`, `Zoltar`). | `Ochiai` |
 | `--mutation-type` | Specifies mutation type. (`Simple`, `Heuristic`). | `Simple` |
-| `--crossover-type` | Specifies crossover type. (`Random`, `Single`, `Uniform`). | `Random` |
+| `--crossover-type` | Specifies crossover type. (`Random`, `Single`, `Uniform`, `Cascade`). | `Random` |
 | `--crossover-first-variant` | Specifies first variant selection strategy for crossover. (`Elite`, `Random`). | `Random` |
 | `--crossover-second-variant` | Specifies second variant selection strategy for crossover.  (`Elite`, `GeneSimilarity`, `Random`, `TestSimilarity`). | `Random` |
 | `--patch-output` | Writes patch files to the output directory specified in `-o` option. | `false` |
 | `--history-record` | Records and writes generation process of all generated variants as JSON format. Note that, this feature significantly reduces overall performance. | `false` |
+| `--version` | Prints the kGenProg version number. | `false` | 
 
 
 ## Use in your research

doc/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for interest in contributing to **kGenProg**.
 This document describes how to setup development environment as a kGenProg contributor.
 
 ## Requirements
-- JDK >=1.8
+- JDK11+
 - Gradle
 
 ## Getting setup
@@ -16,6 +16,7 @@ We strongly recommend to use IntelliJ instead of Eclipse due to the difference o
 ```shell
 $ git clone https://github.com/kusumotolab/kGenProg
 $ cd kGenProg
+$ git submodule update --init
 ```
 
 2. Import the project
@@ -40,7 +41,6 @@ File
   -> Import Scheme
   -> IntelliJ IDEA code style XML
   -> Specify "PATH_TO_REPO/settings/intellij-coding-style.xml"
-
 ```
 
 
@@ -50,6 +50,7 @@ File
 ```shell
 $ git clone https://github.com/kusumotolab/kGenProg
 $ cd kGenProg
+$ git submodule update --init
 ```
 
 2. Resolve dependencies and build the project
@@ -89,7 +90,14 @@ Project
 ```
 
 ## Coding style
-- Contributors must follow our defined coding style ([eclipse](../blob/master/settings/eclipse-coding-style.xml), [intellij](../blob/master/settings/intellij-coding-style.xml)).
+- Contributors must follow our defined coding style ([eclipse](../settings/eclipse-coding-style.xml), [intellij](../settings/intellij-coding-style.xml)).
 This style is based on [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html).
 - Please use **LF** as line ending.
 - Please use **spaces**, do not use tabs.
+
+## Creating JAR files with all dependencies (fat JAR or uber JAR)
+If you want to create a JAR file with all dependencies, run the following command.
+
+```shell
+$ ./gradlew assemble
+```

doc/ja/OVERVIEW.md

@@ -41,7 +41,7 @@ kGenProgにおける自動バグ限局とは，与えられたプログラムと
 
 交叉も変異と同じく，既存の個体（プログラム）から次の世代の個体を生み出す処理である．
 変異と交叉の違いは，変異が1つの個体から次世代の個体を生み出すのに対して，交叉は複数の個体から次世代の個体を生み出す処理である．
-もう一つ変異と交叉との違いは，変異では新しい操作を適用して個体を生成するのに対して，変異ではこれまでに個体に適用された操作を再利用して新しい個体を生成する．
+もう一つ変異と交叉との違いは，変異では新しい操作を適用して個体を生成するのに対して，交叉ではこれまでに個体に適用された操作を再利用して新しい個体を生成する．
 
 ## 塩基と遺伝子
 
@@ -56,22 +56,24 @@ kGenProgでは，実行中に生成される個体はその遺伝子により表
 
 遺伝的プログラミングを用いた自動プログラム修正は，その処理を行う上でさまざまな選択肢がある．
 例えば，kGenProgは自動バグ限局手法としてAmple，Jaccard，Ochiai，Tarantula，Zoltarが実装されている．
-また，これら以外の自動バグ限局手法も詳細実装されるかもしれないし，kGenProgのユーザがこれら以外の手法を利用したい場合もあるだろう．
+また，これら以外の自動バグ限局手法も将来実装されるかもしれないし，kGenProgのユーザがこれら以外の手法を利用したい場合もあるだろう．
 このようなことから，kGenProgでは，自動プログラム修正過程の種々の処理をインターフェース化した実装を行っている．
 よって，新しい自動バグ限局アルゴリズムを実装した場合でも，既存のkGenProgコードの書き換えは最小限の量で済む．
 
-以降，本質では，各処理のインターフェースと実装クラスについて述べる．
+以降，各処理のインターフェースと実装クラスについて述べる．
 
 
 ## 自動バグ限局のインターフェース FaultLocalization
 
-自動バグ限局のインターフェースはjp.kusumotolab.kgenprog.fl.FaultLozalizationである．
+自動バグ限局のインターフェースはjp.kusumotolab.kgenprog.fl.FaultLocalizationである．
 現在のところ，実装クラスとしては以下のものがある．
 - jp.kusumotolab.kgenprog.fl.Ample
+- jp.kusumotolab.kgenprog.fl.DStar
 - jp.kusumotolab.kgenprog.fl.Jaccard
 - jp.kusumotolab.kgenprog.fl.Ochiai
 - jp.kusumotolab.kgenprog.fl.Tarantula
 - jp.kusumotolab.kgenprog.fl.Zoltar
+
 いくつかの論文では，Ochiaiが最も性能が高いと報告している．
 KGenProgのデフォルト値はOchiaiである．
 
@@ -81,16 +83,18 @@ KGenProgのデフォルト値はOchiaiである．
 変異のインターフェースはjp.kusumotolab.kgenprog.ga.mutation.Mutationである．
 現在のところ，実装クラスとしては以下のものがある．
 - jp.kusumotolab.kgenprog.ga.mutation.SimpleMutation：変異により変更する箇所，変異の操作，操作が挿入と置換の場合に利用するプログラム文の取得を，ランダム選択により決定するクラスである．
+- jp.kusumotolab.kgenprog.ga.mutation.HeuristicMutation:変異により変更する箇所，変異の操作，操作が挿入と置換の場合に利用するプログラム文の取得をヒューリティクスを適用して決定するクラスである．
 
 
 ## 交叉のインターフェース Crossover
 
 交叉のインターフェースはjp.kusumotolab.kgenprog.ga.crossover.Crossoverである．
 現在のところ，実装クラスとしては以下のものがある．
 - jp.kusumotolab.kgenprog.ga.crossover.RandomCrossover：二つの親個体から全ての塩基を取得後，それらのうちの半分をランダムに選択して新しい個体を生み出す交叉である．
-- jp.kusumotolab.kgenprog.ga.crossover.SinglePointCrossover：二つの親個体の遺伝子をある一点で前後に分割し，親個体Aの前半遺伝子と親個体Bの後半遺伝子から新しい個体を生み出す較差である．
+- jp.kusumotolab.kgenprog.ga.crossover.SinglePointCrossover：二つの親個体の遺伝子をある一点で前後に分割し，親個体Aの前半遺伝子と親個体Bの後半遺伝子から新しい個体を生み出す交叉である．
 - jp.kusumotolab.kgenprog.ga.crossover.UniformCrossover：二つの親個体の遺伝子を並べ，同じ位置にある塩基のどちらを用いるかをランダム選択する．
 つまり，親個体Aの位置0の塩基と親個体Bの位置0の塩基のどちらかをランダム選択し，親個体Aの位置1の塩基と親個体Bの位置1の塩基のどちらかをランダム選択する，という処理を遺伝子の長さの回数行う．
+- jp.kusumotolab.kgenprog.ga.crossover.CascadeCrossover:二つの親個体から全ての塩基を取得後，塩基の重複を取り除いてつなげ合わせる交叉である．
 
 
 ## 交叉の第一の親を選択するためのインターフェース FirstVariantSelectionStrategy
@@ -101,7 +105,7 @@ KGenProgのデフォルト値はOchiaiである．
 - jp.kusumotolab.kgenprog.ga.crossover.FirstVariantRandomSelection：第一の親としてランダムに個体を選ぶ戦略である．
 
 
-## 交叉の第二の親を選択するためのインターフェースSecondVariantSelectionStrategy
+## 交叉の第二の親を選択するためのインターフェース SecondVariantSelectionStrategy
 
 交叉の第二の親を選択するためのインターフェースはjp.kusumotolab.kgenprog.ga.crossover.SecondVariantSelectionStrategyである．
 現在のところ，実装クラスとしては以下のものがある．
@@ -118,7 +122,7 @@ KGenProgのデフォルト値はOchiaiである．
 現在のところ，実装クラスとしては以下のものがある．
 - jp.kusumotolab.kgenprog.ga.selection.DefaultVariantSelection：適応度が高い個体を選択する．適応度が等しい個体が複数存在する場合はランダムに選択される．
 - jp.kusumotolab.kgenprog.ga.selection.EliteAndOldVariantSelection：適応度が高い個体を選択する．適応度が等しい個体が複数存在する場合は古い世代で生成された個体が選択される．
-- jp.kusumotolab.kgenprog.ga.selection.GenerationalVariantSelection：DefaultVariantSelectionとの違いがいまいち不明
+- jp.kusumotolab.kgenprog.ga.selection.GenerationalVariantSelection：DefaultVariantSelectionとの違いがいまいち不明．
 
 
 ## 個体の適応度を計算するためのインターフェース SourceCodeValidation
@@ -136,14 +140,8 @@ KGenProgのデフォルト値はOchiaiである．
 ## 抽象構文木の変更操作を表すインターフェース JDTOperation
 抽象構文木の変更操作を表すインターフェースは jp.kusumotolab.kgenprog.project.jdt.JDTOperation である．
 現在のところ，実装クラスとしては以下のものがある．
-- jp.kusumotolab.kgenprog.project.jdt.DeleteOperation：プログラム文を削除する
-- jp.kusumotolab.kgenprog.project.jdt.InsertBeforeOperation：対象のプログラム文の前にプログラム文を挿入する
-- jp.kusumotolab.kgenprog.project.jdt.InsertAfterOperation：対象のプログラム文の後ろにプログラム文を挿入する
-- jp.kusumotolab.kgenprog.project.jdt.ReplaceOperation：プログラム文を置換する
-
-
-
-
-
-
+- jp.kusumotolab.kgenprog.project.jdt.DeleteOperation：プログラム文を削除する．
+- jp.kusumotolab.kgenprog.project.jdt.InsertBeforeOperation：対象のプログラム文の前にプログラム文を挿入する．
+- jp.kusumotolab.kgenprog.project.jdt.InsertAfterOperation：対象のプログラム文の後ろにプログラム文を挿入する．
+- jp.kusumotolab.kgenprog.project.jdt.ReplaceOperation：プログラム文を置換する．
 

doc/ja/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img src="../../assets/logo.png" width="40%">
+    <img src="../../assets/logo.png" width="40%" alt="logo">
 </div>
 
 <p align="center">
@@ -31,12 +31,12 @@ kGenProg は単一の jar ファイルにまとめてあります．[ここ](htt
 [ここ](https://github.com/kusumotolab/kGenProg-example/archive/master.zip)からすべてのバグをまとめた zip ファイルをダウンロードできます．
 
 
-## Gradle
+### Gradle
 kGenProgはGradleの環境でも使いやすいように公開されています．
 現在，Gradle用にはJitPackを利用しています．
 GradleのビルドファイルでJitPackリポジトリを参照するには，build.gradleのrepositoriesに以下の'`maven {... `'で始まる行を追加してください．
 
-```
+```gradle
 allprojects {
     repositories {
         ...
@@ -47,17 +47,18 @@ allprojects {
 
 次に，kGenProgへの依存を追加してください．
 
-```
+```gradle
 dependencies {
     implementation 'com.github.kusumotolab:kGenProg:Tag'
+}
 ```
 上記の`Tag`は利用したいkGenProgのバージョンIDで置換してください．
 より詳細な説明は[ここ](https://jitpack.io/#kusumotolab/kGenProg/)に英語で書かれています．
 
 
 ## 使用方法
 ```
-$ java -jar path/to/kGenProg.jar [(-r <path> -s <path>... -t <path>...) | --config <path>]
+$ java -jar path/to/kGenProg.jar [--config <path> | (-r <path> -s <path>... -t <path>...)]
     [-x <fqn>...] [-c <path>...] [-w <path>] [-o <path>] [-v | -q] [--headcount <num>]
     [--max-generation <num>] [--time-limit <sec>] [--test-time-limit <sec>]
     [--required-solutions <num>] [--random-seed <num>] [--fault-localization <name>]
@@ -88,6 +89,7 @@ $ java -jar path/to/kGenProg.jar
 ### オプション
 | オプション | 説明 | デフォルト値/デフォルト動作 |
 |---|---|---|
+| `--config` | 設定ファイルへのパス | カレントディレクトリの `kgenprog.toml` を読み込む |
 | `-r`, `--root-dir` | 修正対象プロジェクトのルートディレクトリへのパス．テスト実行の都合上，対象プロジェクトのルートに移動した上でカレントディレクトリを指定することを推奨します． | なし |
 | `-s`, `--src` | プロダクトコード（単体テスト用のコードを除く実装系のソースコード）へのパス，もしくはプロダクトコードを含むディレクトリへのパス．スペース区切りで複数指定可能． | なし |
 | `-t`, `--test` | テストコード（単体テスト用のソースコード）へのパス，もしくはテストコードを含むディレクトリへのパス．スペース区切りで複数指定可能． | なし |
@@ -96,7 +98,6 @@ $ java -jar path/to/kGenProg.jar
 | `-o`, `--out-dir` | kGenProg が結果を出力するディレクトリへのパス．出力ファイルはパッチファイルとGAの生成過程．それぞれ `--patch-output` と `--history-record` でon/offを切り替え可能． | `./kgenprog-out` |
 | `-v`, `--verbose` | 詳細なログを出力する | `false` |
 | `-q`, `--quiet` | エラー出力のみを行う | `false` |
-| `--config` | 設定ファイルへのパス | カレントディレクトリの `kgenprog.toml` を読み込む |
 | `--mutation-generating-count` | 遺伝的アルゴリズムの変異操作によって1つの世代に生成する個体の数 | 10 |
 | `--crossover-generating-count` | 遺伝的アルゴリズムの交叉操作によって1つの世代に生成する個体の数 | 10 |
 | `--headcount` | 遺伝的アルゴリズムの選択操作によって1世代に残される個体の最大数 | 100 |
@@ -108,11 +109,13 @@ $ java -jar path/to/kGenProg.jar
 | `--scope` | 再利用候補の範囲（`PROJECT`，`PACKAGE`，`FILE`） | `PACKAGE` |
 | `--fault-localization` | 欠陥限局の手法（Fault Localization）（`Ample`，`Jaccard`，`Ochiai`，`Tarantula`，`Zoltar`） | `Ochiai` |
 | `--mutation-type` | 変異種別（`Simple`，`Heuristic`） | `Simple` |
-| `--crossover-type` | 交叉種別（`Random`，`Single`，`Uniform`） | `Random` |
+| `--crossover-type` | 交叉種別（`Random`，`Single`，`Uniform`, `Cascade`） | `Random` |
 | `--crossover-first-variant` | 交叉対象の第一バリアントの選択方法（`Elite`，`Random`） | `Random` |
 | `--crossover-second-variant` | 交叉対象の第二バリアントの選択方法（`Elite`，`GeneSimilarity`，`Random`，`TestComplementary`) | `Random` |
 | `--patch-output` | 解のパッチファイル生成の有無 | `false` |
 | `--history-record` | 個体の生成過程および生成された全個体を記録するJSONファイルの記録の有無．この機能は実行速度の低下に繋がる点に注意 | `false` |
+| `--version` | kGenProg のバーションを出力し終了する | `false` |
+
 
 ## 受賞
 - [Best Poster Award - APSEC 2018](http://www.apsec2018.org/)