| ... | ... | @@ -1,212 +1,3 @@ |
| 1 | | ## Contributing |
| 2 | | |
| 3 | | ### Start a Project Using Zig |
| 4 | | |
| 5 | | One of the best ways you can contribute to Zig is to start using it for a |
| 6 | | personal 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 | | |
| 11 | | More examples can be found on the |
| 12 | | [Community Projects Wiki](https://github.com/ziglang/zig/wiki/Community-Projects). |
| 13 | | |
| 14 | | Without fail, these projects lead to discovering bugs and helping flesh out use |
| 15 | | cases, which lead to further design iterations of Zig. Importantly, each issue |
| 16 | | found this way comes with real world motivations, so it is easy to explain |
| 17 | | your reasoning behind proposals and feature requests. |
| 18 | | |
| 19 | | Ideally, such a project will help you to learn new skills and add something |
| 20 | | to your personal portfolio at the same time. |
| 21 | | |
| 22 | | ### Spread the Word |
| 23 | | |
| 24 | | Another way to contribute is to write about Zig, or speak about Zig at a |
| 25 | | conference, or do either of those things for your project which uses Zig. |
| 26 | | Here 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 | | |
| 32 | | Zig is a brand new language, with no advertising budget. Word of mouth is the |
| 33 | | only way people find out about the project, and the more people hear about it, |
| 34 | | the more people will use it, and the better chance we have to take over the |
| 35 | | world. |
| 36 | | |
| 37 | | ### Finding Contributor Friendly Issues |
| 38 | | |
| 39 | | Please note that issues labeled |
| 40 | | [Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal) |
| 41 | | but do not also have the |
| 42 | | [Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted) |
| 43 | | label are still under consideration, and efforts to implement such a proposal |
| 44 | | have a high risk of being wasted. If you are interested in a proposal which is |
| 45 | | still under consideration, please express your interest in the issue tracker, |
| 46 | | providing extra insights and considerations that others have not yet expressed. |
| 47 | | The most highly regarded argument in such a discussion is a real world use case. |
| 48 | | |
| 49 | | The issue label |
| 50 | | [Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22) |
| 51 | | exists to help you find issues that are **limited in scope and/or |
| 52 | | knowledge of Zig internals.** |
| 53 | | |
| 54 | | ### Editing Source Code |
| 55 | | |
| 56 | | First, build the Stage 1 compiler as described in |
| 57 | | [Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source). |
| 58 | | |
| 59 | | Zig locates lib files relative to executable path by searching up the |
| 60 | | filesystem tree for a sub-path of `lib/zig/std/std.zig` or `lib/std/std.zig`. |
| 61 | | Typically the former is an install and the latter a git working tree which |
| 62 | | contains the build directory. |
| 63 | | |
| 64 | | During development it is not necessary to perform installs when modifying |
| 65 | | stage1 or userland sources and in fact it is faster and simpler to run, |
| 66 | | test 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 |
| 71 | | build and install. To avoid install, pass cmake option `-DZIG_NO_LIB=ON`. |
| 72 | | |
| 73 | | To test changes, do the following from the build directory: |
| 74 | | |
| 75 | | 1. Run `make` (on POSIX) or |
| 76 | | `msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows). |
| 77 | | 2. `$BUILD_DIR/zig build test` (on POSIX) or |
| 78 | | `$BUILD_DIR/Release\zig.exe build test` (on Windows). |
| 79 | | |
| 80 | | That runs the whole test suite, which does a lot of extra testing that you |
| 81 | | likely won't always need, and can take upwards of 1 hour. This is what the |
| 82 | | CI server runs when you make a pull request. (Note: actually it runs a few |
| 83 | | more tests; keep reading.) |
| 84 | | |
| 85 | | To save time, you can add the `--help` option to the `zig build` command and |
| 86 | | see 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 |
| 88 | | the time down from around 2 hours to about 6 minutes, and this is a good |
| 89 | | enough amount of testing before making a pull request. |
| 90 | | |
| 91 | | Another 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 |
| 93 | | not the other ones. Combining this suggestion with the previous one, you could |
| 94 | | do 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 | | |
| 99 | | This will run only the standard library tests, in debug mode only, for all |
| 100 | | targets (it will cross-compile the tests for non-native targets but not run |
| 101 | | them). |
| 102 | | |
| 103 | | When making changes to the compiler source code, the most helpful test step to |
| 104 | | run is `test-behavior`. When editing documentation it is `docs`. You can find |
| 105 | | this information and more in the `--help` menu. |
| 106 | | |
| 107 | | #### Testing Changes to std lib |
| 108 | | |
| 109 | | To 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 | | |
| 117 | | The Linux CI server additionally has qemu installed and sets `-fqemu`. |
| 118 | | This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's |
| 119 | | recommended for Linux users to install qemu and enable this testing option |
| 120 | | when editing the standard library or anything related to a non-native |
| 121 | | architecture. |
| 122 | | |
| 123 | | ##### glibc |
| 124 | | |
| 125 | | Testing foreign architectures with dynamically linked glibc is one step trickier. |
| 126 | | This requires enabling `--glibc-runtimes /path/to/glibc/multi/install/glibcs`. |
| 127 | | This path is obtained by building glibc for multiple architectures. This |
| 128 | | process for me took an entire day to complete and takes up 65 GiB on my hard |
| 129 | | drive. The CI server does not provide this test coverage. Instructions for |
| 130 | | producing this path can be found |
| 131 | | [on the wiki](https://github.com/ziglang/zig/wiki/Updating-libc#glibc). |
| 132 | | Just the part with `build-many-glibcs.py`. |
| 133 | | |
| 134 | | It's understood that most contributors will not have these tests enabled. |
| 135 | | |
| 136 | | #### Testing Windows from a Linux Machine with Wine |
| 137 | | |
| 138 | | When developing on Linux, another option is available to you: `-fwine`. |
| 139 | | This will enable running behavior tests and std lib tests with Wine. It's |
| 140 | | recommended for Linux users to install Wine and enable this testing option |
| 141 | | when editing the standard library or anything Windows-related. |
| 142 | | |
| 143 | | #### Testing WebAssembly using wasmtime |
| 144 | | |
| 145 | | If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the |
| 146 | | `-fwasmtime` flag which will enable running WASI behavior tests and std |
| 147 | | lib tests. It's recommended for all users to install wasmtime and enable this |
| 148 | | testing option when editing the standard library and especially anything |
| 149 | | WebAssembly-related. |
| 150 | | |
| 151 | | #### Improving Translate-C |
| 152 | | |
| 153 | | Please read the [Editing Source Code](#editing-source-code) section as a |
| 154 | | prerequisite to this one. |
| 155 | | |
| 156 | | `translate-c` is a feature provided by Zig that converts C source code into |
| 157 | | Zig source code. It powers the `zig translate-c` command as well as |
| 158 | | [@cImport](https://ziglang.org/documentation/master/#cImport), allowing Zig |
| 159 | | code to not only take advantage of function prototypes defined in .h files, |
| 160 | | but also `static inline` functions written in C, and even some macros. |
| 161 | | |
| 162 | | This feature works by using libclang API to parse and semantically analyze |
| 163 | | C/C++ files, and then based on the provided AST and type information, |
| 164 | | generating Zig AST, and finally using the mechanisms of `zig fmt` to render |
| 165 | | the Zig AST to a file. |
| 166 | | |
| 167 | | The 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 | | |
| 183 | | This feature is self-hosted, even though Zig is not fully self-hosted yet. In the Zig source |
| 184 | | repo, 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 | | |
| 201 | | Finally, 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 | | |
| 205 | | The 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` |
| 1 | Please see the |
| 2 | [Contributing](https://github.com/ziglang/zig/wiki/Contributing) |
| 3 | page on the wiki. |
Andrew Kelley <andrew@ziglang.org> 2023-01-23 16:54:07-07:00
.github