blob: 415b65ee97abe05cf92a346ef56e0f2151375f5f [file] [log] [blame] [view]
Mike Frysinger07ba0902018-06-14 18:33:17 -04001# Hacking on Minijail
2
Mike Frysinger182d4522018-06-14 19:02:18 -04003## Dependencies
4
5You'll need these to build the source:
6* [libcap]
7* Linux kernel headers
8
9You'll need to install the relevant packages from your distro.
10
11## Building
12
13For local experimentation (using Minijail libraries from the source directory):
14
15```
Mike Frysinger182d4522018-06-14 19:02:18 -040016$ make LIBDIR=/lib64
Mike Frysinger0a032ae2020-08-24 21:48:40 -040017$ sudo ./minijail0.sh -u ${USER} -g 5000 -- /usr/bin/id
Mike Frysinger182d4522018-06-14 19:02:18 -040018```
19
Luis Hector Chavez9acba452018-10-11 10:13:25 -070020For system-wide usage, install `libminijail.so` and `libminijailpreload.so` to
21`/lib64` and `minijail0` to a directory in your `PATH` (e.g. `/usr/bin`).
Mike Frysinger182d4522018-06-14 19:02:18 -040022
23## Testing
24
25We use [Google Test] (i.e. `gtest` & `gmock`) for unit tests.
26You can download a suitable copy of Google Test using the
27[get_googletest.sh](./get_googletest.sh) script.
28
29```
30$ ./get_googletest.sh
31googletest-release-1.8.0/
32...
Luis Hector Chavez9acba452018-10-11 10:13:25 -070033$ make tests
Mike Frysinger182d4522018-06-14 19:02:18 -040034```
35
36Building the tests will automatically execute them.
37
Nicole Anderson-Au74024f62020-11-05 22:41:42 +000038## Code Review
39
40We use [Android Review] for Minijail code review. The easiest way to submit
Mike Frysinger69f7fd02022-08-30 05:14:42 -040041changes for review is using `repo upload` on a ChromiumOS or Android checkout.
Nicole Anderson-Au74024f62020-11-05 22:41:42 +000042Go to [Android Review HTTP Credentials] to obtain credentials to push code. For
43more detailed instructions see the [Android source documentation] or the
Mike Frysinger69f7fd02022-08-30 05:14:42 -040044[ChromiumOS documentation].
Nicole Anderson-Au74024f62020-11-05 22:41:42 +000045
Mike Frysinger182d4522018-06-14 19:02:18 -040046## Source Style
Mike Frysinger07ba0902018-06-14 18:33:17 -040047
48* Minijail uses kernel coding style:
49 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst
50* Utility functions with no side-effects should go in `util.{h|c}`.
51* Functions with side effects or with dependencies on operating system
52 details, but that don't take a `struct minijail` argument, should go
53 in `system.{h|c}`.
54
55## Documentation
56
57### Markdown
58
59Minijail uses markdown for general/source documentation.
60We follow the [Google Markdown style guide].
61
62### Man Pages
63
Mike Frysinger182d4522018-06-14 19:02:18 -040064For users of Minijail (e.g. `minijail0`), we use man pages.
65For style guides, check out the [Linux man-pages project] for general guidance.
66It has a number of useful references for syntax and such.
67
68* [man-pages(7)](http://man7.org/linux/man-pages/man7/man-pages.7.html)
69* [groff-man(7)](http://man7.org/linux/man-pages/man7/groff_man.7.html)
70* [groff(7)](http://man7.org/linux/man-pages/man7/groff.7.html)
Mike Frysinger07ba0902018-06-14 18:33:17 -040071
72[minijail0.1] documents the command line interface.
73Please keep it in sync with [minijail0_cli.c].
74
75[minijail0.5] documents the syntax of config files (e.g. seccomp filters).
76
Mike Frysinger182d4522018-06-14 19:02:18 -040077[libcap]: https://git.kernel.org/pub/scm/linux/kernel/git/morgan/libcap.git/
Mike Frysinger07ba0902018-06-14 18:33:17 -040078[minijail0.1]: ./minijail0.1
79[minijail0.5]: ./minijail0.5
80[minijail0_cli.c]: ./minijail0_cli.c
Nicole Anderson-Au74024f62020-11-05 22:41:42 +000081[Android Review]: https://android-review.googlesource.com/
82[Android Review HTTP Credentials]: https://android-review.googlesource.com/settings/#HTTPCredentials
83[Android source documentation]: https://source.android.com/setup/start
Mike Frysinger69f7fd02022-08-30 05:14:42 -040084[ChromiumOS documentation]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_guide.md
Mike Frysinger07ba0902018-06-14 18:33:17 -040085[Google Markdown style guide]: https://github.com/google/styleguide/blob/gh-pages/docguide/style.md
Mike Frysinger182d4522018-06-14 19:02:18 -040086[Google Test]: https://github.com/google/googletest