authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2023-01-23 16:54:07-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2023-01-23 16:55:54-07:00
logbbfbb7b22f8db1228e9ccd33f320bb30961ef911
tree1b548a5c81049aa8014aa17b9acc399376119110
parent81035b7eb32aa8382760a0159026357982256895

move CONTRIBUTING.md to the wiki

closes #14427

1 files changed, 3 insertions(+), 212 deletions(-)

.github/CONTRIBUTING.md+3-212
...@@ -1,212 +1,3 @@...@@ -1,212 +1,3 @@
1## Contributing1Please see the
22[Contributing](https://github.com/ziglang/zig/wiki/Contributing)
3### Start a Project Using Zig3page on the wiki.
4
5One of the best ways you can contribute to Zig is to start using it for a
6personal project. Here are some great examples:
7
8 * [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games
9 * [River](https://github.com/ifreund/river/) - a dynamic tiling wayland compositor
10
11More examples can be found on the
12[Community Projects Wiki](https://github.com/ziglang/zig/wiki/Community-Projects).
13
14Without fail, these projects lead to discovering bugs and helping flesh out use
15cases, which lead to further design iterations of Zig. Importantly, each issue
16found this way comes with real world motivations, so it is easy to explain
17your reasoning behind proposals and feature requests.
18
19Ideally, such a project will help you to learn new skills and add something
20to your personal portfolio at the same time.
21
22### Spread the Word
23
24Another way to contribute is to write about Zig, or speak about Zig at a
25conference, or do either of those things for your project which uses Zig.
26Here are some examples:
27
28 * [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html)
29 * [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY)
30 * [Writing a small ray tracer in Rust and Zig](https://nelari.us/post/raytracer_with_rust_and_zig/)
31
32Zig is a brand new language, with no advertising budget. Word of mouth is the
33only way people find out about the project, and the more people hear about it,
34the more people will use it, and the better chance we have to take over the
35world.
36
37### Finding Contributor Friendly Issues
38
39Please note that issues labeled
40[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
41but do not also have the
42[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
43label are still under consideration, and efforts to implement such a proposal
44have a high risk of being wasted. If you are interested in a proposal which is
45still under consideration, please express your interest in the issue tracker,
46providing extra insights and considerations that others have not yet expressed.
47The most highly regarded argument in such a discussion is a real world use case.
48
49The issue label
50[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
51exists to help you find issues that are **limited in scope and/or
52knowledge of Zig internals.**
53
54### Editing Source Code
55
56First, build the Stage 1 compiler as described in
57[Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source).
58
59Zig locates lib files relative to executable path by searching up the
60filesystem tree for a sub-path of `lib/zig/std/std.zig` or `lib/std/std.zig`.
61Typically the former is an install and the latter a git working tree which
62contains the build directory.
63
64During development it is not necessary to perform installs when modifying
65stage1 or userland sources and in fact it is faster and simpler to run,
66test and debug from a git working tree.
67
68- `make` is typically sufficient to build zig during development iterations.
69- `make install` performs a build __and__ install.
70- `msbuild -p:Configuration=Release INSTALL.vcxproj` on Windows performs a
71build and install. To avoid install, pass cmake option `-DZIG_NO_LIB=ON`.
72
73To test changes, do the following from the build directory:
74
751. Run `make` (on POSIX) or
76 `msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows).
772. `$BUILD_DIR/zig build test` (on POSIX) or
78 `$BUILD_DIR/Release\zig.exe build test` (on Windows).
79
80That runs the whole test suite, which does a lot of extra testing that you
81likely won't always need, and can take upwards of 1 hour. This is what the
82CI server runs when you make a pull request. (Note: actually it runs a few
83more tests; keep reading.)
84
85To save time, you can add the `--help` option to the `zig build` command and
86see what options are available. One of the most helpful ones is
87`-Dskip-release`. Adding this option to the command in step 2 above will take
88the time down from around 2 hours to about 6 minutes, and this is a good
89enough amount of testing before making a pull request.
90
91Another example is choosing a different set of things to test. For example,
92`test-std` instead of `test` will only run the standard library tests, and
93not the other ones. Combining this suggestion with the previous one, you could
94do this:
95
96`$BUILD_DIR/bin/zig build test-std -Dskip-release` (on POSIX) or
97`$BUILD_DIR/Release\zig.exe build test-std -Dskip-release` (on Windows).
98
99This will run only the standard library tests, in debug mode only, for all
100targets (it will cross-compile the tests for non-native targets but not run
101them).
102
103When making changes to the compiler source code, the most helpful test step to
104run is `test-behavior`. When editing documentation it is `docs`. You can find
105this information and more in the `--help` menu.
106
107#### Testing Changes to std lib
108
109To quickly test a change to a file in the standard library, you can run zig test and specify a custom lib directory with the follow command-line argument.
110
111```bash
112./build/zig test lib/std/fmt.zig --zig-lib-dir lib --main-pkg-path lib/std
113```
114
115#### Testing Non-Native Architectures with QEMU
116
117The Linux CI server additionally has qemu installed and sets `-fqemu`.
118This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's
119recommended for Linux users to install qemu and enable this testing option
120when editing the standard library or anything related to a non-native
121architecture.
122
123##### glibc
124
125Testing foreign architectures with dynamically linked glibc is one step trickier.
126This requires enabling `--glibc-runtimes /path/to/glibc/multi/install/glibcs`.
127This path is obtained by building glibc for multiple architectures. This
128process for me took an entire day to complete and takes up 65 GiB on my hard
129drive. The CI server does not provide this test coverage. Instructions for
130producing this path can be found
131[on the wiki](https://github.com/ziglang/zig/wiki/Updating-libc#glibc).
132Just the part with `build-many-glibcs.py`.
133
134It's understood that most contributors will not have these tests enabled.
135
136#### Testing Windows from a Linux Machine with Wine
137
138When developing on Linux, another option is available to you: `-fwine`.
139This will enable running behavior tests and std lib tests with Wine. It's
140recommended for Linux users to install Wine and enable this testing option
141when editing the standard library or anything Windows-related.
142
143#### Testing WebAssembly using wasmtime
144
145If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the
146`-fwasmtime` flag which will enable running WASI behavior tests and std
147lib tests. It's recommended for all users to install wasmtime and enable this
148testing option when editing the standard library and especially anything
149WebAssembly-related.
150
151#### Improving Translate-C
152
153Please read the [Editing Source Code](#editing-source-code) section as a
154prerequisite to this one.
155
156`translate-c` is a feature provided by Zig that converts C source code into
157Zig source code. It powers the `zig translate-c` command as well as
158[@cImport](https://ziglang.org/documentation/master/#cImport), allowing Zig
159code to not only take advantage of function prototypes defined in .h files,
160but also `static inline` functions written in C, and even some macros.
161
162This feature works by using libclang API to parse and semantically analyze
163C/C++ files, and then based on the provided AST and type information,
164generating Zig AST, and finally using the mechanisms of `zig fmt` to render
165the Zig AST to a file.
166
167The relevant tests for this feature are:
168
169 * `test/run_translated_c.zig` - each test case is C code with a `main` function. The C code
170 is translated into Zig code, compiled, and run, and tests that the expected output is the
171 same, and that the program exits cleanly. This kind of test coverage is preferred, when
172 possible, because it makes sure that the resulting Zig code is actually viable.
173
174 * `test/stage1/behavior/translate_c_macros.zig` - each test case consists of a Zig test
175 which checks that the relevant macros in `test/stage1/behavior/translate_c_macros.h`.
176 have the correct values. Macros have to be tested separately since they are expanded by
177 Clang in `run_translated_c` tests.
178
179 * `test/translate_c.zig` - each test case is C code, with a list of expected strings which
180 must be found in the resulting Zig code. This kind of test is more precise in what it
181 measures, but does not provide test coverage of whether the resulting Zig code is valid.
182
183This feature is self-hosted, even though Zig is not fully self-hosted yet. In the Zig source
184repo, we maintain a C API on top of Clang's C++ API:
185
186 * `src/zig_clang.h` - the C API that we maintain on top of Clang's C++ API. This
187 file does not include any Clang's C++ headers. Instead, C types and C enums are defined
188 here.
189
190 * `src/zig_clang.cpp` - a lightweight wrapper that fulfills the C API on top of the
191 C++ API. It takes advantage of `static_assert` to make sure we get compile errors when
192 Clang's C++ API changes. This one file necessarily does include Clang's C++ headers, which
193 makes it the slowest-to-compile source file in all of Zig's codebase.
194
195 * `src/clang.zig` - the Zig equivalent of `src/zig_clang.h`. This is a manually
196 maintained list of types and functions that are ABI-compatible with the Clang C API we
197 maintain. In theory this could be generated by running translate-c on `src/zig_clang.h`,
198 but that would introduce a dependency cycle, since we are using this file to implement
199 translate-c.
200
201Finally, the actual source code for the translate-c feature is
202`src/translate_c.zig`. This code uses the Clang C API exposed by
203`src/clang.zig`, and produces Zig AST.
204
205The steps for contributing to translate-c look like this:
206
207 1. Identify a test case you want to improve. Add it as a run-translated-c test
208 case (usually preferable), or as a translate-c test case.
209
210 2. Edit `src/translate_c.zig` to improve the behavior.
211
212 3. Run the relevant tests: `./zig build test-run-translated-c test-translate-c`