| ... | @@ -123,3 +123,61 @@ When developing on Linux, another option is available to you: `-Denable-wine`. | ... | @@ -123,3 +123,61 @@ When developing on Linux, another option is available to you: `-Denable-wine`. |
| 123 | This will enable running behavior tests and std lib tests with Wine. It's | 123 | This will enable running behavior tests and std lib tests with Wine. It's |
| 124 | recommended for Linux users to install Wine and enable this testing option | 124 | recommended for Linux users to install Wine and enable this testing option |
| 125 | when editing the standard library or anything Windows-related. | 125 | when editing the standard library or anything Windows-related. |
| | 126 | |
| | 127 | #### Improving Translate-C |
| | 128 | |
| | 129 | Please read the [Editing Source Code](#editing-source-code) section as a |
| | 130 | prerequisite to this one. |
| | 131 | |
| | 132 | `translate-c` is a feature provided by Zig that converts C source code into |
| | 133 | Zig source code. It powers the `zig translate-c` command as well as |
| | 134 | [@cImport](https://ziglang.org/documentation/master/#cImport), allowing Zig |
| | 135 | code to not only take advantage of function prototypes defined in .h files, |
| | 136 | but also `static inline` functions written in C, and even some macros. |
| | 137 | |
| | 138 | This feature works by using libclang API to parse and semantically analyze |
| | 139 | C/C++ files, and then based on the provided AST and type information, |
| | 140 | generating Zig AST, and finally using the mechanisms of `zig fmt` to render |
| | 141 | the Zig AST to a file. |
| | 142 | |
| | 143 | The relevant tests for this feature are: |
| | 144 | |
| | 145 | * `test/run_translated_c.zig` - each test case is C code with a `main` function. The C code |
| | 146 | is translated into Zig code, compiled, and run, and tests that the expected output is the |
| | 147 | same, and that the program exits cleanly. This kind of test coverage is preferred, when |
| | 148 | possible, because it makes sure that the resulting Zig code is actually viable. |
| | 149 | |
| | 150 | * `test/translate_c.zig` - each test case is C code, with a list of expected strings which |
| | 151 | must be found in the resulting Zig code. This kind of test is more precise in what it |
| | 152 | measures, but does not provide test coverage of whether the resulting Zig code is valid. |
| | 153 | |
| | 154 | This feature is self-hosted, even though Zig is not fully self-hosted yet. In the Zig source |
| | 155 | repo, we maintain a C API on top of Clang's C++ API: |
| | 156 | |
| | 157 | * `src/zig_clang.h` - the C API that we maintain on top of Clang's C++ API. This |
| | 158 | file does not include any Clang's C++ headers. Instead, C types and C enums are defined |
| | 159 | here. |
| | 160 | |
| | 161 | * `src/zig_clang.cpp` - a lightweight wrapper that fulfills the C API on top of the |
| | 162 | C++ API. It takes advantage of `static_assert` to make sure we get compile errors when |
| | 163 | Clang's C++ API changes. This one file necessarily does include Clang's C++ headers, which |
| | 164 | makes it the slowest-to-compile source file in all of Zig's codebase. |
| | 165 | |
| | 166 | * `src-self-hosted/clang.zig` - the Zig equivalent of `src/zig_clang.h`. This is a manually |
| | 167 | maintained list of types and functions that are ABI-compatible with the Clang C API we |
| | 168 | maintain. In theory this could be generated by running translate-c on `src/zig_clang.h`, |
| | 169 | but that would introduce a dependency cycle, since we are using this file to implement |
| | 170 | translate-c. |
| | 171 | |
| | 172 | Finally, the actual source code for the translate-c feature is |
| | 173 | `src-self-hosted/translate_c.zig`. This code uses the Clang C API exposed by |
| | 174 | `src-self-hosted/clang.zig`, and produces Zig AST. |
| | 175 | |
| | 176 | The steps for contributing to translate-c look like this: |
| | 177 | |
| | 178 | 1. Identify a test case you want to improve. Add it as a run-translated-c test |
| | 179 | case (usually preferable), or as a translate-c test case. |
| | 180 | |
| | 181 | 2. Edit `src-self-hosted/translate_c.zig` to improve the behavior. |
| | 182 | |
| | 183 | 3. Run the relevant tests: `./zig build test-run-translated-c test-translate-c` |
Andrew Kelley <andrew@ziglang.org> 2020-01-05 15:42:55-05:00