Mike Frysinger | 07ba090 | 2018-06-14 18:33:17 -0400 | [diff] [blame] | 1 | # Hacking on Minijail |
| 2 | |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 3 | ## Dependencies |
| 4 | |
| 5 | You'll need these to build the source: |
| 6 | * [libcap] |
| 7 | * Linux kernel headers |
| 8 | |
| 9 | You'll need to install the relevant packages from your distro. |
| 10 | |
| 11 | ## Building |
| 12 | |
| 13 | For local experimentation (using Minijail libraries from the source directory): |
| 14 | |
| 15 | ``` |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 16 | $ make LIBDIR=/lib64 |
Mike Frysinger | 0a032ae | 2020-08-24 21:48:40 -0400 | [diff] [blame] | 17 | $ sudo ./minijail0.sh -u ${USER} -g 5000 -- /usr/bin/id |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 18 | ``` |
| 19 | |
Luis Hector Chavez | 9acba45 | 2018-10-11 10:13:25 -0700 | [diff] [blame] | 20 | For 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 Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 22 | |
| 23 | ## Testing |
| 24 | |
| 25 | We use [Google Test] (i.e. `gtest` & `gmock`) for unit tests. |
| 26 | You can download a suitable copy of Google Test using the |
| 27 | [get_googletest.sh](./get_googletest.sh) script. |
| 28 | |
| 29 | ``` |
| 30 | $ ./get_googletest.sh |
| 31 | googletest-release-1.8.0/ |
| 32 | ... |
Luis Hector Chavez | 9acba45 | 2018-10-11 10:13:25 -0700 | [diff] [blame] | 33 | $ make tests |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 34 | ``` |
| 35 | |
| 36 | Building the tests will automatically execute them. |
| 37 | |
Nicole Anderson-Au | 74024f6 | 2020-11-05 22:41:42 +0000 | [diff] [blame] | 38 | ## Code Review |
| 39 | |
| 40 | We use [Android Review] for Minijail code review. The easiest way to submit |
Mike Frysinger | 69f7fd0 | 2022-08-30 05:14:42 -0400 | [diff] [blame] | 41 | changes for review is using `repo upload` on a ChromiumOS or Android checkout. |
Nicole Anderson-Au | 74024f6 | 2020-11-05 22:41:42 +0000 | [diff] [blame] | 42 | Go to [Android Review HTTP Credentials] to obtain credentials to push code. For |
| 43 | more detailed instructions see the [Android source documentation] or the |
Mike Frysinger | 69f7fd0 | 2022-08-30 05:14:42 -0400 | [diff] [blame] | 44 | [ChromiumOS documentation]. |
Nicole Anderson-Au | 74024f6 | 2020-11-05 22:41:42 +0000 | [diff] [blame] | 45 | |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 46 | ## Source Style |
Mike Frysinger | 07ba090 | 2018-06-14 18:33:17 -0400 | [diff] [blame] | 47 | |
| 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 | |
| 59 | Minijail uses markdown for general/source documentation. |
| 60 | We follow the [Google Markdown style guide]. |
| 61 | |
| 62 | ### Man Pages |
| 63 | |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 64 | For users of Minijail (e.g. `minijail0`), we use man pages. |
| 65 | For style guides, check out the [Linux man-pages project] for general guidance. |
| 66 | It 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 Frysinger | 07ba090 | 2018-06-14 18:33:17 -0400 | [diff] [blame] | 71 | |
| 72 | [minijail0.1] documents the command line interface. |
| 73 | Please keep it in sync with [minijail0_cli.c]. |
| 74 | |
| 75 | [minijail0.5] documents the syntax of config files (e.g. seccomp filters). |
| 76 | |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 77 | [libcap]: https://git.kernel.org/pub/scm/linux/kernel/git/morgan/libcap.git/ |
Mike Frysinger | 07ba090 | 2018-06-14 18:33:17 -0400 | [diff] [blame] | 78 | [minijail0.1]: ./minijail0.1 |
| 79 | [minijail0.5]: ./minijail0.5 |
| 80 | [minijail0_cli.c]: ./minijail0_cli.c |
Nicole Anderson-Au | 74024f6 | 2020-11-05 22:41:42 +0000 | [diff] [blame] | 81 | [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 Frysinger | 69f7fd0 | 2022-08-30 05:14:42 -0400 | [diff] [blame] | 84 | [ChromiumOS documentation]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_guide.md |
Mike Frysinger | 07ba090 | 2018-06-14 18:33:17 -0400 | [diff] [blame] | 85 | [Google Markdown style guide]: https://github.com/google/styleguide/blob/gh-pages/docguide/style.md |
Mike Frysinger | 182d452 | 2018-06-14 19:02:18 -0400 | [diff] [blame] | 86 | [Google Test]: https://github.com/google/googletest |