README.md
1# LSS Tests
2
3## Source Layout
4
5The general layout of the tests:
6* [test_skel.h]: Test helpers for common checks/etc...
7* xxx.c: Unittest for the xxx syscall (e.g. `open.c`).
8* [Makefile]: New tests should be registered in the `TESTS` variable.
9
10## Test Guidelines
11
12The unittest itself generally follows the conventions:
13* Written in C (unless a very specific language behavior is needed).
14* You should only need to `#include "test_skel.h"`. For new system headers, try
15 to add them here rather than copying to exact unittest (if possible).
16 It might slow compilation down slightly, but makes the code easier to manage.
17 Make sure it is included first.
18* Use `assert()` on everything to check return values.
19* Use `sys_xxx()` to access the syscall via LSS (compared to `xxx()` which tends
20 to come from the C library).
21* If you need a tempfile, use `tempfile.XXXXXX` for templates with helpers like
22 `mkstemp`. Try to clean them up when you're done with them.
23 These will be created in the cwd, but that's fine.
24* Don't worry about trying to verify the kernel/C library API and various edge
25 cases. The goal of LSS is to make sure that we pass args along correctly to
26 the syscall only.
27* Make sure to leave comments in the test so it's clear what behavior you're
28 trying to verify (and how).
29
30Feel free to extend [test_skel.h] with more helpers if they're useful to more
31than one test.
32
33If you're looking for a simple example, start with [unlink.c](./unlink.c).
34You should be able to copy this over and replace the content of `main()`.
35
36## Running The Tests
37
38Simply run `make`. This will compile & execute all the tests on your local
39system. A standard `make clean` will clean up all the objects.
40
41If you need to debug something, then the programs are simply named `xxx_test`
42and can easily be thrown into `gdb ./xxx_test`.
43
44We have rudimentary cross-compile testing via gcc and clang. Try running
45`make cross` -- for any toolchains you don't have available, it should skip
46things automatically. This only verifies the compilation & linking stages
47though.
48
49The cross-compilers can be created using <http://crosstool-ng.github.io/>.
50
51[Makefile]: ./Makefile
52[test_skel.h]: ./test_skel.h
53