diff options
author | liu fengyun <liu@fengy.me> | 2017-02-10 12:08:22 +0100 |
---|---|---|
committer | liu fengyun <liu@fengy.me> | 2017-02-10 19:26:08 +0100 |
commit | 7ca25fbca7bbfa8755ce74ca24b138705a7f904d (patch) | |
tree | 6f1a74f4ac3e3b31aef9be67c816f0304b4ce3ee /docs | |
parent | c7a557c43221c1fbad4117e63b6cd8c255ddc8f7 (diff) | |
download | dotty-7ca25fbca7bbfa8755ce74ca24b138705a7f904d.tar.gz dotty-7ca25fbca7bbfa8755ce74ca24b138705a7f904d.tar.bz2 dotty-7ca25fbca7bbfa8755ce74ca24b138705a7f904d.zip |
add document for debug tests
Diffstat (limited to 'docs')
-rw-r--r-- | docs/docs/contributing/debug-tests.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/docs/docs/contributing/debug-tests.md b/docs/docs/contributing/debug-tests.md new file mode 100644 index 000000000..b3d65c937 --- /dev/null +++ b/docs/docs/contributing/debug-tests.md @@ -0,0 +1,124 @@ +--- +layout: doc-page +title: Tests for Debuggability +--- + +## Tools Requires + +- JDB +- expect + +Both are usually pre-installed on Mac OS and linux distributions. + +## Debug Manually with JDB + +First, compile the file `tests/debug/while.scala`: + +``` +bin/dotc tests/debug/while.scala +``` + +Second, run the compiled class with debugging enabled (suppose the main class is `Test`): + +``` +bin/dotr -d Test +``` + +Third, start JDB: + +``` +jdb -attach 5005 -sourcepath tests/debug/ +``` + +You can run `help` for commands that supported by JDB. + +## Debug Automatically with Expect + +### 1. Annotate the source code with debug information. + +Following file (`tests/debug/while.scala`) is an example of annoated source code: + +```Scala +object Test { + + def main(args: Array[String]): Unit = { + var a = 1 + 2 + a = a + 3 + a = 4 + 5 // [break] [step: while] + + while (a * 8 < 100) { // [step: a += 1] + a += 1 // [step: while] [cont: print] + } + + print(a) // [break] [cont] + } +} +``` + +The debugging information is annotated as comments to the code in brackets: + +```Scala +val x = f(3) // [break] [next: line=5] +val y = 5 +``` + +1. A JDB command must be wrapped in brackets, like `[step]`. All JDB commands can be used. +2. To check output of JDB for a command, use `[cmd: expect]`. +3. If `expect` is wrapped in double quotes, regex is supported. +4. Break commands are collected and set globally. +5. Other commands will be send to jdb in the order they appear in the source file + +Note that JDB uses line number starts from 1. + +### 2. Generate Expect File + +Now we can run the following command to generate an expect file: + +``` +compiler/test/debug/Gen tests/debug/while.scala > robot +``` + +### 3. Run the Test + +First, compile the file `tests/debug/while.scala`: + +``` +bin/dotc tests/debug/while.scala +``` + +Second, run the compiled class with debugging enabled: + +``` +bin/dotr -d Test +``` + +Finally, run the expect script: + +``` +expect robot +``` + +## Other Tips + +### Adding a New Test + +Just put the annotated source file under `tests/debug/`, it will be automatically +run by the test infrastructure. + +### Run All Debug Tests + +``` +./compiler/test/debug/test +``` + +### Debug a Debug Test + +If there is any problem with a debug test, first check if the problematic +test work correctly with JDB without automation. + +Then, uncomment the following line in the generated expect file to check the +output of expect: + +``` +# exp_internal 1 +``` |