| ... | @@ -135,7 +135,7 @@ Zig is an open-source programming language designed for **robustness**, | ... | @@ -135,7 +135,7 @@ Zig is an open-source programming language designed for **robustness**, |
| 135 | * Reddit: [/r/zig](https://www.reddit.com/r/zig) | 135 | * Reddit: [/r/zig](https://www.reddit.com/r/zig) |
| 136 | * Email list: [~andrewrk/ziglang@lists.sr.ht](https://lists.sr.ht/%7Eandrewrk/ziglang) | 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 | [](https://dev.azure.com/ziglang/zig/_build/latest?definitionId=1&branchName=master) | 140 | [](https://dev.azure.com/ziglang/zig/_build/latest?definitionId=1&branchName=master) |
| 141 | | 141 | |
| ... | @@ -151,12 +151,14 @@ Note that you can | ... | @@ -151,12 +151,14 @@ Note that you can |
| 151 | * cmake >= 2.8.5 | 151 | * cmake >= 2.8.5 |
| 152 | * gcc >= 5.0.0 or clang >= 3.6.0 | 152 | * gcc >= 5.0.0 or clang >= 3.6.0 |
| 153 | * LLVM, Clang, LLD development libraries == 8.x, compiled with the same gcc or clang version above | 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 | ##### Windows | 156 | ##### Windows |
| 156 | | 157 | |
| 157 | * cmake >= 2.8.5 | 158 | * cmake >= 2.8.5 |
| 158 | * Microsoft Visual Studio 2017 (version 15.8) | 159 | * Microsoft Visual Studio 2017 (version 15.8) |
| 159 | * LLVM, Clang, LLD development libraries == 8.x, compiled with the same MSVC version above | 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 | #### Instructions | 163 | #### Instructions |
| 162 | | 164 | |
| ... | @@ -166,9 +168,7 @@ Note that you can | ... | @@ -166,9 +168,7 @@ Note that you can |
| 166 | mkdir build | 168 | mkdir build |
| 167 | cd build | 169 | cd build |
| 168 | cmake .. | 170 | cmake .. |
| 169 | make | | |
| 170 | make install | 171 | make install |
| 171 | bin/zig build --build-file ../build.zig test | | |
| 172 | ``` | 172 | ``` |
| 173 | | 173 | |
| 174 | ##### MacOS | 174 | ##### MacOS |
| ... | @@ -180,7 +180,6 @@ mkdir build | ... | @@ -180,7 +180,6 @@ mkdir build |
| 180 | cd build | 180 | cd build |
| 181 | cmake .. -DCMAKE_PREFIX_PATH=/usr/local/Cellar/llvm/8.0.0 | 181 | cmake .. -DCMAKE_PREFIX_PATH=/usr/local/Cellar/llvm/8.0.0 |
| 182 | make install | 182 | make install |
| 183 | bin/zig build --build-file ../build.zig test | | |
| 184 | ``` | 183 | ``` |
| 185 | | 184 | |
| 186 | ##### Windows | 185 | ##### Windows |
| ... | @@ -224,25 +223,94 @@ use stage 1. | ... | @@ -224,25 +223,94 @@ use stage 1. |
| 224 | ./stage2/bin/zig build --build-file ../build.zig install -Drelease-fast | 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 | First, build the Stage 1 compiler as described in [the Building section](#building). | 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` | 280 | When making changes to the standard library, be sure to edit the files in the |
| 237 | (on Windows). | 281 | `std` directory and not the installed copy in the build directory. If you add a |
| 238 | 2. Test your changes with `bin/zig test lib/zig/std/<changed file>` (e.g. `bin/zig test lib/zig/std/heap.zig`). | 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 | ``` | 287 | 1. Run `make install` (on POSIX) or |
| 243 | bin/zig build --build-file ../build.zig test -Dskip-release | 288 | `msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows). |
| 244 | ``` | 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 | 314 | When making changes to the compiler source code, the most helpful test step to |
| 247 | all possible build configurations. This shorter test process is good enough when | 315 | run is `test-behavior`. When editing documentation it is `docs`. You can find |
| 248 | submitting pull requests* | 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.