| ... | ... | @@ -135,7 +135,7 @@ Zig is an open-source programming language designed for **robustness**, |
| 135 | 135 | * Reddit: [/r/zig](https://www.reddit.com/r/zig) |
| 136 | 136 | * Email list: [~andrewrk/ziglang@lists.sr.ht](https://lists.sr.ht/%7Eandrewrk/ziglang) |
| 137 | 137 | |
| 138 | | ## Building |
| 138 | ## Building from Source |
| 139 | 139 | |
| 140 | 140 | [](https://dev.azure.com/ziglang/zig/_build/latest?definitionId=1&branchName=master) |
| 141 | 141 | |
| ... | ... | @@ -151,12 +151,14 @@ Note that you can |
| 151 | 151 | * cmake >= 2.8.5 |
| 152 | 152 | * gcc >= 5.0.0 or clang >= 3.6.0 |
| 153 | 153 | * LLVM, Clang, LLD development libraries == 8.x, compiled with the same gcc or clang version above |
| 154 | - Use the system package manager, or [build from source](https://github.com/ziglang/zig/wiki/How-to-build-LLVM,-libclang,-and-liblld-from-source#posix). |
| 154 | 155 | |
| 155 | 156 | ##### Windows |
| 156 | 157 | |
| 157 | 158 | * cmake >= 2.8.5 |
| 158 | 159 | * Microsoft Visual Studio 2017 (version 15.8) |
| 159 | 160 | * LLVM, Clang, LLD development libraries == 8.x, compiled with the same MSVC version above |
| 161 | - Use the [pre-built binaries](https://github.com/ziglang/zig/wiki/How-to-build-LLVM,-libclang,-and-liblld-from-source#pre-built-binaries) or [build from source](https://github.com/ziglang/zig/wiki/How-to-build-LLVM,-libclang,-and-liblld-from-source#windows). |
| 160 | 162 | |
| 161 | 163 | #### Instructions |
| 162 | 164 | |
| ... | ... | @@ -166,9 +168,7 @@ Note that you can |
| 166 | 168 | mkdir build |
| 167 | 169 | cd build |
| 168 | 170 | cmake .. |
| 169 | | make |
| 170 | 171 | make install |
| 171 | | bin/zig build --build-file ../build.zig test |
| 172 | 172 | ``` |
| 173 | 173 | |
| 174 | 174 | ##### MacOS |
| ... | ... | @@ -180,7 +180,6 @@ mkdir build |
| 180 | 180 | cd build |
| 181 | 181 | cmake .. -DCMAKE_PREFIX_PATH=/usr/local/Cellar/llvm/8.0.0 |
| 182 | 182 | make install |
| 183 | | bin/zig build --build-file ../build.zig test |
| 184 | 183 | ``` |
| 185 | 184 | |
| 186 | 185 | ##### Windows |
| ... | ... | @@ -224,25 +223,94 @@ use stage 1. |
| 224 | 223 | ./stage2/bin/zig build --build-file ../build.zig install -Drelease-fast |
| 225 | 224 | ``` |
| 226 | 225 | |
| 227 | | ## Developing Zig |
| 226 | ## Contributing |
| 228 | 227 | |
| 229 | | ### Standard Library |
| 228 | ### Start a Project Using Zig |
| 229 | |
| 230 | One of the best ways you can contribute to Zig is to start using it for a |
| 231 | personal project. Here are some great examples: |
| 232 | |
| 233 | * [Oxid](https://github.com/dbandstra/oxid) - arcade style game |
| 234 | * [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games |
| 235 | * [trOS](https://github.com/sjdh02/trOS) - tiny aarch64 baremetal OS thingy |
| 236 | |
| 237 | Without fail, these projects lead to discovering bugs and helping flesh out use |
| 238 | cases, which lead to further design iterations of Zig. Importantly, each issue |
| 239 | found this way comes with a real world motivations, so it is easy to explain |
| 240 | your reasoning behind proposals and feature requests. |
| 241 | |
| 242 | Ideally, such a project will help you to learn new skills and add something |
| 243 | to your personal portfolio at the same time. |
| 244 | |
| 245 | ### Spread the Word |
| 246 | |
| 247 | Another way to contribute is to write about Zig, or speak about Zig at a |
| 248 | conference, or do either of those things for your project which uses Zig. |
| 249 | Here are some examples: |
| 250 | |
| 251 | * [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html) |
| 252 | * [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY) |
| 253 | |
| 254 | Zig is a brand new language, with no advertising budget. Word of mouth is the |
| 255 | only way people find out about the project, and the more people hear about it, |
| 256 | the more people will use it, and the better chance we have to take over the |
| 257 | world. |
| 258 | |
| 259 | ### Finding Contributor Friendly Issues |
| 260 | |
| 261 | Please note that issues labeled |
| 262 | [Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal) |
| 263 | but do not also have the |
| 264 | [Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted) |
| 265 | label are still under consideration, and efforts to implement such a proposal |
| 266 | have a high risk of being wasted. If you are interested in a proposal which is |
| 267 | still under consideration, please express your interest in the issue tracker, |
| 268 | providing extra insights and considerations that others have not yet expressed. |
| 269 | The most highly regarded argument in such a discussion is a real world use case. |
| 270 | |
| 271 | The issue label |
| 272 | [Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22) |
| 273 | exists to help contributors find issues that are "limited in scope and/or |
| 274 | knowledge of Zig internals." |
| 275 | |
| 276 | ### Editing Source Code |
| 230 | 277 | |
| 231 | 278 | First, build the Stage 1 compiler as described in [the Building section](#building). |
| 232 | | Then, make your changes to the standard library files in `std` (note: not |
| 233 | | `build/lib/zig/std`). To test changes to the standard library, do the following |
| 234 | | from the build directory: |
| 235 | 279 | |
| 236 | | 1. Run `make install` (on POSIX) or `msbuild -p:Configuration=Release INSTALL.vcxproj` |
| 237 | | (on Windows). |
| 238 | | 2. Test your changes with `bin/zig test lib/zig/std/<changed file>` (e.g. `bin/zig test lib/zig/std/heap.zig`). |
| 280 | When making changes to the standard library, be sure to edit the files in the |
| 281 | `std` directory and not the installed copy in the build directory. If you add a |
| 282 | new file to the standard library, you must also add the file path in |
| 283 | CMakeLists.txt. |
| 239 | 284 | |
| 240 | | Once your changes are finished, run all the zig tests from the build directory: |
| 285 | To test changes, do the following from the build directory: |
| 241 | 286 | |
| 242 | | ``` |
| 243 | | bin/zig build --build-file ../build.zig test -Dskip-release |
| 244 | | ``` |
| 287 | 1. Run `make install` (on POSIX) or |
| 288 | `msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows). |
| 289 | 2. `bin/zig build --build-file ../build.zig test` (on POSIX) or |
| 290 | `bin\zig.exe build --build-file ..\build.zig test` (on Windows). |
| 291 | |
| 292 | That runs the whole test suite, which does a lot of extra testing that you |
| 293 | likely won't always need, and can take upwards of 2 hours. This is what the |
| 294 | CI server runs when you make a pull request. |
| 295 | |
| 296 | To save time, you can add the `--help` option to the `zig build` command and |
| 297 | see what options are available. One of the most helpful ones is |
| 298 | `-Dskip-release`. Adding this option to the command in step 2 above will take |
| 299 | the time down from around 2 hours to about 6 minutes, and this is a good |
| 300 | enough amount of testing before making a pull request. |
| 301 | |
| 302 | Another example is choosing a different set of things to test. For example, |
| 303 | `test-std` instead of `test` will only run the standard library tests, and |
| 304 | not the other ones. Combining this suggestion with the previous one, you could |
| 305 | do this: |
| 306 | |
| 307 | `bin/zig build --build-file ../build.zig test-std -Dskip-release` (on POSIX) or |
| 308 | `bin\zig.exe build --build-file ..\build.zig test-std -Dskip-release` (on Windows). |
| 309 | |
| 310 | This will run only the standard library tests, in debug mode only, for all |
| 311 | targets (it will cross-compile the tests for non-native targets but not run |
| 312 | them). |
| 245 | 313 | |
| 246 | | *Note: The `-Dskip-release` flag will skip running the longer test process that tests |
| 247 | | all possible build configurations. This shorter test process is good enough when |
| 248 | | submitting pull requests* |
| 314 | When making changes to the compiler source code, the most helpful test step to |
| 315 | run is `test-behavior`. When editing documentation it is `docs`. You can find |
| 316 | this information and more in the `--help` menu. |
Andrew Kelley <andrew@ziglang.org> 2019-04-29 18:25:27-04:00
Commit is signed but in an unrecognized format.