README.md 7 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
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>
```

Markus Klinik's avatar
README    
Markus Klinik committed
30
- Rascal documentation recommends running java with `-Xmx1G -Xss32m`
Markus Klinik's avatar
README    
Markus Klinik committed
31
32
- 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
33
34
35
36
37
38
39
- 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
40

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

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

Markus Klinik's avatar
README    
Markus Klinik committed
47
48
49
50
51
```
$ ./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
52
53


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

Markus Klinik's avatar
README    
Markus Klinik committed
56
57
58
59
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
60

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

Markus Klinik's avatar
README    
Markus Klinik committed
65
66
67
68
69
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
70

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

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

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

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

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

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

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

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

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

Markus Klinik's avatar
README    
Markus Klinik committed
99
100
101
102
103
```
$ 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
104

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

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

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

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

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

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

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

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

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

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

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

Markus Klinik's avatar
README    
Markus Klinik committed
140
141
142
143
```
$ 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
144

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

Markus Klinik's avatar
README    
Markus Klinik committed
147
148
149
150
151
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
152
153
154
155
156
157
158
159
160
161

```
$ 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
162
163
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
164
165
166
167
168
169
170
171
172

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

```
$ 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
181
$ ./pp-bs-daemon help
Markus Klinik's avatar
README    
Markus Klinik committed
182
183
184
185
186
187
188
189
190
191
$ ./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
192
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
193
$ ./pp-bs-daemon oo1920 34014 ./pp-work/assignment03b geometric
Markus Klinik's avatar
README    
Markus Klinik committed
194
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
195
$ ./pp-bs-daemon oo1920 34015 ./pp-work/resit01a student
Markus Klinik's avatar
README    
Markus Klinik committed
196
Ctrl-a c # open new screen tab
Markus Klinik's avatar
README    
Markus Klinik committed
197
$ ./pp-bs-daemon oo1920 34016 ./pp-work/resit01b student
Markus Klinik's avatar
README    
Markus Klinik committed
198
Ctrl-a d # detach screen
Markus Klinik's avatar
README    
Markus Klinik committed
199
200
```

Markus Klinik's avatar
README    
Markus Klinik committed
201
202
203
204
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
205
206


Markus Klinik's avatar
README    
Markus Klinik committed
207
208
209
210
# 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
211
212


Markus Klinik's avatar
README    
Markus Klinik committed
213
214
215
216
217
218
## 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
219
220
221
```
$ ./test.sh
```
Markus Klinik's avatar
README    
Markus Klinik committed
222
223
224

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

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



Markus Klinik's avatar
README    
Markus Klinik committed
231

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

- 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