1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
# Contributing
Want to contribute? Great! First, read this page.
### Contributor License Agreement
Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution;
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.
### Using GOPATH
Some editors may require the code to be structured in a `GOPATH` directory tree.
In this case, you may use the `:gopath` target to generate a directory tree with
symlinks to the original source files.
```
bazel build :gopath
```
You can then set the `GOPATH` in your editor to `bazel-bin/gopath`.
If you use this mechanism, keep in mind that the generated tree is not the
canonical source. You will still need to build and test with `bazel`. New files
will need to be added to the appropriate `BUILD` files, and the `:gopath` target
will need to be re-run to generate appropriate symlinks in the `GOPATH`
directory tree.
Dependencies can be added by using `go mod get`. In order to keep the
`WORKSPACE` file in sync, run `tools/go_mod.sh` in place of `go mod`.
### Coding Guidelines
All code should comply with the [style guide](g3doc/style.md). Note that code
may be automatically formatted per the guidelines when merged.
As a secure runtime, we need to maintain the safety of all of code included in
gVisor. The following rules help mitigate issues.
Definitions for the rules below:
`core`:
* `//pkg/sentry/...`
* Transitive dependencies in `//pkg/...`, etc.
`runsc`:
* `//runsc/...`
Rules:
* No cgo in `core` or `runsc`. The final binary must be a statically-linked
pure Go binary.
* Any files importing "unsafe" must have a name ending in `_unsafe.go`.
* `core` may only depend on the following packages:
* Itself.
* Go standard library.
* Except (transitively) package "net" (this will result in a non-cgo
binary). Use `//pkg/unet` instead.
* `@org_golang_x_sys//unix:go_default_library` (Go import
`golang.org/x/sys/unix`).
* Generated Go protobuf packages.
* `@com_github_golang_protobuf//proto:go_default_library` (Go import
`github.com/golang/protobuf/proto`).
* `@com_github_golang_protobuf//ptypes:go_default_library` (Go import
`github.com/golang/protobuf/ptypes`).
* `runsc` may only depend on the following packages:
* All packages allowed for `core`.
* `@com_github_google_subcommands//:go_default_library` (Go import
`github.com/google/subcommands`).
* `@com_github_opencontainers_runtime_spec//specs_go:go_default_library`
(Go import `github.com/opencontainers/runtime-spec/specs_go`).
### Code reviews
Before sending code reviews, run `bazel test ...` to ensure tests are passing.
Code changes are accepted via [pull request][github].
When approved, the change will be submitted by a team member and automatically
merged into the repository.
### Presubmit checks
Accessing check logs may require membership in the
[gvisor-dev mailing list][gvisor-dev-list], which is public.
### Bug IDs
Some TODOs and NOTEs sprinkled throughout the code have associated IDs of the
form `b/1234`. These correspond to bugs in our internal bug tracker. Eventually
these bugs will be moved to the GitHub Issues, but until then they can simply be
ignored.
### Build and test with Docker
Running `make dev` is a convenient way to build and install `runsc` as a Docker
runtime. The output of this command will show the runtimes installed.
You may use `make refresh` to refresh the binary after any changes. For example:
```bash
make dev
docker run --rm --runtime=my-branch --rm hello-world
make refresh
```
### The small print
Contributions made by corporations are covered by a different agreement than the
one above, the
[Software Grant and Corporate Contributor License Agreement][gccla].
[gcla]: https://cla.developers.google.com/about/google-individual
[gccla]: https://cla.developers.google.com/about/google-corporate
[github]: https://github.com/google/gvisor/compare
[gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev
|
