README.md 7.07 KB
Newer Older
1
# Personal Prof
Markus Klinik's avatar
Markus Klinik committed
2

Markus Klinik's avatar
README    
Markus Klinik committed
3
4
An automatic code review tool for student Java assignments. See also the
accompanying paper
Markus Klinik's avatar
README    
Markus Klinik committed
5
https://gitlab.science.ru.nl/objectorientatie/personal-prof-paper
Markus Klinik's avatar
Markus Klinik committed
6

Markus Klinik's avatar
README    
Markus Klinik committed
7
8
9
Personal Prof consists of two parts: The rule checker itself and the
Brightspace daemon. The rule checker is called **Personal Prof**, the
Brightspace integration is called **pp-bs-daemon**. The rule checker is written
Markus Klinik's avatar
README    
Markus Klinik committed
10
11
in Rascal, which runs on the Java Virtual Machine (tested with openjdk 11,
newer probably also works). The Brightspace daemon is written in Python 3.
Markus Klinik's avatar
README    
Markus Klinik committed
12

Markus Klinik's avatar
README    
Markus Klinik committed
13
14
15
Running Personal Prof directly is only useful for development and debugging.
For checking assignments you always want pp-bs-daemon.

Markus Klinik's avatar
README    
Markus Klinik committed
16

Markus Klinik's avatar
README    
Markus Klinik committed
17
18
19
20

## Running Personal Prof

To run Personal Prof, you need a rascal jar and the Personal Prof source code.
Markus Klinik's avatar
README    
Markus Klinik committed
21
Both are included in this repository. The rascal jar can be found in `src/lib`
Markus Klinik's avatar
README    
Markus Klinik committed
22
23
24
25
26
27
28
29
30
31
and the source code in `src`. To run Personal Prof, you have to call java as
follows.

```
$ cd src
$ java -Xmx1G -Xss32m -jar lib/rascal-0.15.2-SNAPSHOT.jar Main.rsc <ruleset-name> <absolute-path-to-project-under-test>
```

- Rascal sometimes needs lots of memory to parse big projects, the official
  Rascal documentation recommends running java with `-Xmx1G -Xss32m`
Markus Klinik's avatar
README    
Markus Klinik committed
32
33
- You have to run it from inside the directory where `Main.rsc` is. This is due
  to the way Rascal module loading works.
Markus Klinik's avatar
README    
Markus Klinik committed
34
35
36
37
38
39
40
- Rascal needs absolute paths to open files. The path to the project under test
  must be absolute
- To see which rulesets are available, look at the big switch statement in
  `Main.rsc`

There is a script `run.sh` which simplifies running Personal Prof. This script
can handle relative paths to the project under test.
Markus Klinik's avatar
Markus Klinik committed
41

Markus Klinik's avatar
README    
Markus Klinik committed
42
43
44
```
$ ./run.sh <ruleset-name> <path-to-student-project>
```
Markus Klinik's avatar
README    
Markus Klinik committed
45

Markus Klinik's avatar
README    
Markus Klinik committed
46
For example
Markus Klinik's avatar
Markus Klinik committed
47

Markus Klinik's avatar
README    
Markus Klinik committed
48
49
50
51
52
```
$ ./run.sh hangman ~/tmp/oo-grading-2020/assignment02-hangman/grading/TA_Name/128863\ -\ 34172\ -\ AsgnA\ 142\ -\ Student\ Name\ -\ 2020-02-16T09_23_57.733Z/submission/
Gallows should use StringBuilder
at |java+class:///hangman/Gallows|
```
Markus Klinik's avatar
README    
Markus Klinik committed
53
54


Markus Klinik's avatar
README    
Markus Klinik committed
55
# Running The Brightspace Daemon
Markus Klinik's avatar
README    
Markus Klinik committed
56

Markus Klinik's avatar
README    
Markus Klinik committed
57
58
59
60
pp-bs-daemon is a Python 3 program that periodically polls Brightspace for new
student submissions. When a new student submission is detected, the daemon
downloads it, runs Personal Prof, and uploads the resulting feedback to
Brightspace.
Markus Klinik's avatar
README    
Markus Klinik committed
61

Markus Klinik's avatar
README    
Markus Klinik committed
62
For all this to work, the daemon needs two dependencies: Personal Prof and
Markus Klinik's avatar
README    
Markus Klinik committed
63
no-bs. no-bs is a Python library and command line program to interact with
Markus Klinik's avatar
README    
Markus Klinik committed
64
Brightspace. Everything you need is included in this repository.
Markus Klinik's avatar
README    
Markus Klinik committed
65

Markus Klinik's avatar
README    
Markus Klinik committed
66
67
68
69
70
no-bs is a component that can run independently of the daemon. You have to set
up no-bs first, before you can run the daemon. no-bs has its own configuration
file, and you have to use no-bs to log in to Brightspace. This needs to be done
only once. Logging in with no-bs stores a long-term authentication cookie on
your computer.
Markus Klinik's avatar
README    
Markus Klinik committed
71

Markus Klinik's avatar
README    
Markus Klinik committed
72
The basic steps to set up no-bs are described as follows. For more
Markus Klinik's avatar
README    
Markus Klinik committed
73
74
75
information about no-bs see
https://gitlab.science.ru.nl/objectorientatie/brightspace-grading-tool

Markus Klinik's avatar
README    
Markus Klinik committed
76
77
## To run the pp-bs-daemon, follow these steps.

Markus Klinik's avatar
README    
Markus Klinik committed
78
1. Clone repository
Markus Klinik's avatar
README    
Markus Klinik committed
79

Markus Klinik's avatar
README    
Markus Klinik committed
80
81
82
83
```
$ git clone --recurse-submodules https://gitlab.science.ru.nl/objectorientatie/personal-prof.git
$ cd personal-prof
```
Markus Klinik's avatar
README    
Markus Klinik committed
84

Markus Klinik's avatar
README    
Markus Klinik committed
85
3. Optional: Run tests
Markus Klinik's avatar
README    
Markus Klinik committed
86

Markus Klinik's avatar
README    
Markus Klinik committed
87
88
89
```
$ ./test.sh
```
Markus Klinik's avatar
README    
Markus Klinik committed
90

Markus Klinik's avatar
README    
Markus Klinik committed
91
4. Create config directories for no-bs and pp-bs-daemon
Markus Klinik's avatar
README    
Markus Klinik committed
92

Markus Klinik's avatar
README    
Markus Klinik committed
93
94
95
96
```
$ mkdir -p ~/.config/grading-tools
$ mkdir -p ~/.config/personal-prof
```
Markus Klinik's avatar
README    
Markus Klinik committed
97

Markus Klinik's avatar
README    
Markus Klinik committed
98
5. Copy config files to config direcotries
Markus Klinik's avatar
README    
Markus Klinik committed
99

Markus Klinik's avatar
README    
Markus Klinik committed
100
101
102
103
104
```
$ cd brightspace-integration
$ cp app.json.config ~/.config/personal-prof
$ cp brightspace-grading-tool/grading-tool-python/app.json.config.default ~/.config/grading-tools/app.json.config
```
Markus Klinik's avatar
README    
Markus Klinik committed
105

Markus Klinik's avatar
README    
Markus Klinik committed
106
6. Edit config files. For no-bs you have to set `lms_url` and `courses`.
Markus Klinik's avatar
README    
Markus Klinik committed
107

Markus Klinik's avatar
README    
Markus Klinik committed
108
109
110
```
$ vim ~/.config/personal-prof/app.json.config
```
Markus Klinik's avatar
README    
Markus Klinik committed
111

Markus Klinik's avatar
README    
Markus Klinik committed
112
For pp-bs-daemon you have to set `rascalJar` and `personalProfInstallPath`
Markus Klinik's avatar
README    
Markus Klinik committed
113

Markus Klinik's avatar
README    
Markus Klinik committed
114
115
116
```
$ vim ~/.config/grading-tools/app.json.config
```
Markus Klinik's avatar
README    
Markus Klinik committed
117

Markus Klinik's avatar
README    
Markus Klinik committed
118
119
7. Install d2lvalence python module. This command will install it into your
   local python package store.
Markus Klinik's avatar
README    
Markus Klinik committed
120

Markus Klinik's avatar
README    
Markus Klinik committed
121
122
123
```
$ pip3 install D2LValence
```
Markus Klinik's avatar
README    
Markus Klinik committed
124

Markus Klinik's avatar
README    
Markus Klinik committed
125
8. Log in with no-bs
Markus Klinik's avatar
README    
Markus Klinik committed
126

Markus Klinik's avatar
README    
Markus Klinik committed
127
128
129
130
```
$ cd brightspace-grading-tool/grading-tool-python/
$ ./no-bs login-manual
```
Markus Klinik's avatar
README    
Markus Klinik committed
131

Markus Klinik's avatar
README    
Markus Klinik committed
132
9. See if it works
Markus Klinik's avatar
README    
Markus Klinik committed
133

Markus Klinik's avatar
README    
Markus Klinik committed
134
135
136
137
```
$ ./no-bs list-courses
$ ./no-bs list-folders <course-id>
```
Markus Klinik's avatar
README    
Markus Klinik committed
138

Markus Klinik's avatar
README    
Markus Klinik committed
139
10. Start the daemon
Markus Klinik's avatar
README    
Markus Klinik committed
140

Markus Klinik's avatar
README    
Markus Klinik committed
141
142
143
144
```
$ export PYTHONPATH=`readlink -f brightspace-grading-tool/grading-tool-python`
$ ./personal-prof run <course-name> <folder-id> <target-directory> <ruleset-name>
```
Markus Klinik's avatar
README    
Markus Klinik committed
145

Markus Klinik's avatar
README    
Markus Klinik committed
146
147
11. Keep the daemon running

Markus Klinik's avatar
README    
Markus Klinik committed
148
149
150
151
152
It is recommended to run the daemon on a server, not your personal laptop. All
the above setup procedure needs to be repeated on the server. We always used
lilo, but an AWS instance or something similar should also work (not tested).
To keep the daemon running when you are logged out, use `screen`.

Markus Klinik's avatar
README    
Markus Klinik committed
153
154
155
156
157
158
159
160
161
162

```
$ ssh <science-login>@lilo.science.ru.nl
$ cd path/to/personal-prof/brightspace-integration
$ export PYTHONPATH=`readlink -f brightspace-grading-tool/grading-tool-python`
$ screen
```

From inside screen, open a new tab per pp-bs-daemon instance you need. In each
week we typically need four instances. Two for the current assignment, two for
Markus Klinik's avatar
README    
Markus Klinik committed
163
164
the resit. That's because of the stupid Brightspace restriction that a group
category can only have 200 groups.
Markus Klinik's avatar
README    
Markus Klinik committed
165
166
167
168
169
170
171
172
173

screen quick-reference:

- `Ctrl-a c` create new tab
- `Ctrl-a n` switch to next tab
- `Ctrl-a p` switch to previous tab
- `Ctrl-a d` detach screen to backgrond. You can log out now.
- `$ screen -r` re-attach to a running screen

Markus Klinik's avatar
README    
Markus Klinik committed
174
This is an example session for how to run pp-bs-daemon for the course
Markus Klinik's avatar
README    
Markus Klinik committed
175
oo1920 for assignment 03 groups A and B, and resit 01 groups A and B.
Markus Klinik's avatar
README    
Markus Klinik committed
176
177
178
179
180
181

```
$ ssh <science-login>@lilo.science.ru.nl
$ cd path/to/personal-prof/brightspace-integration
$ export PYTHONPATH=`readlink -f brightspace-grading-tool/grading-tool-python`
$ screen
Markus Klinik's avatar
README    
Markus Klinik committed
182
$ ./pp-bs-daemon help
Markus Klinik's avatar
README    
Markus Klinik committed
183
184
185
186
187
188
189
190
191
192
$ ./pp-bs-daemon list-folders oo1920
33813 Assignment 01 A
33814 Assignment 01 B
33913 Assignment 02 A
33914 Assignment 02 B
34013 Assignment 03 A
34014 Assignment 03 B
34015 Resit 01 A
34016 Resit 01 B
$ ./pp-bs-daemon oo1920 34013 ./pp-work/assignment03a geometric
Markus Klinik's avatar
README    
Markus Klinik committed
193
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
194
$ ./pp-bs-daemon oo1920 34014 ./pp-work/assignment03b geometric
Markus Klinik's avatar
README    
Markus Klinik committed
195
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
196
$ ./pp-bs-daemon oo1920 34015 ./pp-work/resit01a student
Markus Klinik's avatar
README    
Markus Klinik committed
197
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
198
$ ./pp-bs-daemon oo1920 34016 ./pp-work/resit01b student
Markus Klinik's avatar
README    
Markus Klinik committed
199
Ctrl-a d # detach screen
Markus Klinik's avatar
README    
Markus Klinik committed
200
201
```

Markus Klinik's avatar
README    
Markus Klinik committed
202
203
204
205
Both no-bs and pp-bs-daemon work incrementally. You can stop `Ctrl-c` and
re-start pp-bs-daemon by using the exact same command again. It will continue
where it left off by looking at the work directory.

Markus Klinik's avatar
README    
Markus Klinik committed
206
207


Markus Klinik's avatar
README    
Markus Klinik committed
208
209
210
211
# Contributing

To develop rascal code, use eclipse-rcp. Follow the instructions here:
https://www.rascal-mpl.org/start/
Markus Klinik's avatar
README    
Markus Klinik committed
212
213


Markus Klinik's avatar
README    
Markus Klinik committed
214
215
216
217
218
219
## Running the test cases

There are some test projects and test cases to check that the rules give
correct error messages. To run the tests, use the test script. The test script
looks for all files `*Spec.rsc` and executes them

Markus Klinik's avatar
README    
Markus Klinik committed
220
221
222
```
$ ./test.sh
```
Markus Klinik's avatar
README    
Markus Klinik committed
223
224
225

To test only specific files, specify them on the command line.

Markus Klinik's avatar
README    
Markus Klinik committed
226
227
228
```
$ ./test.sh Assignment02RulesSpec.rsc Assignment03RulesSpec.rsc
```
Markus Klinik's avatar
README    
Markus Klinik committed
229
230
231



Markus Klinik's avatar
README    
Markus Klinik committed
232

Markus Klinik's avatar
README    
Markus Klinik committed
233
# References
Markus Klinik's avatar
README    
Markus Klinik committed
234
235
236
237

- Rascal official website https://www.rascal-mpl.org/
- Rascal github https://github.com/usethesource/rascal
- Rascal documentation http://tutor.rascal-mpl.org/Rascal/Rascal.html