srctree

README.md
4e38b3ed  Andrew Kelley ![ZIG](https://ziglang.org/img/zig-logo-dynamic.svg) e0993292  Andrew Kelley a3d04b92  Andrew Kelley A general-purpose programming language and toolchain for maintaining a3d04b92  Andrew Kelley **robust**, **optimal**, and **reusable** software. e0993292  Andrew Kelley 9ada2f88  Andrew Kelley https://ziglang.org/ b9880175  Andrew Kelley 9ada2f88  Andrew Kelley ## Documentation 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley If you are looking at this README file in a source tree, please refer to the 9ada2f88  Andrew Kelley **Release Notes**, **Language Reference**, or **Standard Library 9ada2f88  Andrew Kelley Documentation** corresponding to the version of Zig that you are using by 9ada2f88  Andrew Kelley following the appropriate link on the 9ada2f88  Andrew Kelley [download page](https://ziglang.org/download). 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley Otherwise, you're looking at a release of Zig, and you can find documentation 9ada2f88  Andrew Kelley here: 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley * doc/langref.html 9ada2f88  Andrew Kelley * doc/std/index.html 0c22358c  Andrew Kelley 1afea36a  Andrew Kelley ## Installation c6fff3b2  Andrew Kelley 1afea36a  Andrew Kelley * [download a pre-built binary](https://ziglang.org/download/) 1afea36a  Andrew Kelley * [install from a package manager](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager) 1afea36a  Andrew Kelley * [bootstrap zig for any target](https://github.com/ziglang/zig-bootstrap) dc478687  Andrew Kelley 9ada2f88  Andrew Kelley A Zig installation is composed of two things: 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley 1. The Zig executable 9ada2f88  Andrew Kelley 2. The lib/ directory 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley At runtime, the executable searches up the file system for the lib/ directory, 9ada2f88  Andrew Kelley relative to itself: 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley * lib/ 5b512591  snoire * lib/zig/ 9ada2f88  Andrew Kelley * ../lib/ 5b512591  snoire * ../lib/zig/ 9ada2f88  Andrew Kelley * (and so on) 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley In other words, you can **unpack a release of Zig anywhere**, and then begin 9ada2f88  Andrew Kelley using it immediately. There is no need to install it globally, although this 9ada2f88  Andrew Kelley mechanism supports that use case too (i.e. `/usr/bin/zig` and `/usr/lib/zig/`). 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley ## Building from Source 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley Ensure you have the required dependencies: 9ada2f88  Andrew Kelley 5389af2c  dundargoc * CMake >= 3.5 9ada2f88  Andrew Kelley * System C/C++ Toolchain a9f25c7d  Tomasz Lisowski * LLVM, Clang, LLD development libraries == 17.x 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley Then it is the standard CMake build process: 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley ``` 9ada2f88  Andrew Kelley mkdir build 9ada2f88  Andrew Kelley cd build 9ada2f88  Andrew Kelley cmake .. 9ada2f88  Andrew Kelley make install 9ada2f88  Andrew Kelley ``` 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley For more options, tips, and troubleshooting, please see the 9ada2f88  Andrew Kelley [Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source) 9ada2f88  Andrew Kelley page on the wiki. 9ada2f88  Andrew Kelley 621e89a8  Andrew Kelley ## Building from Source without LLVM 621e89a8  Andrew Kelley 621e89a8  Andrew Kelley In this case, the only system dependency is a C compiler. 621e89a8  Andrew Kelley 621e89a8  Andrew Kelley ``` 621e89a8  Andrew Kelley cc -o bootstrap bootstrap.c f8b38a17  Andrew Kelley ./bootstrap 621e89a8  Andrew Kelley ``` 621e89a8  Andrew Kelley f8b38a17  Andrew Kelley This produces a `zig2` executable in the current working directory. This is a f8b38a17  Andrew Kelley "stage2" build of the compiler, f8b38a17  Andrew Kelley [without LLVM extensions](https://github.com/ziglang/zig/issues/16270), and is f8b38a17  Andrew Kelley therefore lacking these features: 910143e5  Andrew Kelley - Release mode optimizations 910143e5  Andrew Kelley - aarch64 machine code backend 910143e5  Andrew Kelley - `@cImport` / `zig translate-c` 910143e5  Andrew Kelley - Ability to compile C files 910143e5  Andrew Kelley - Ability to compile assembly files 910143e5  Andrew Kelley - [Some ELF linking features](https://github.com/ziglang/zig/issues/17749) 910143e5  Andrew Kelley - [Most COFF/PE linking features](https://github.com/ziglang/zig/issues/17751) 910143e5  Andrew Kelley - [Some WebAssembly linking features](https://github.com/ziglang/zig/issues/17750) 910143e5  Andrew Kelley - [Ability to create import libs from def files](https://github.com/ziglang/zig/issues/17807) 910143e5  Andrew Kelley - [Automatic importlib file generation for Windows DLLs](https://github.com/ziglang/zig/issues/17753) 910143e5  Andrew Kelley - [Ability to create static archives from object files](https://github.com/ziglang/zig/issues/9828) 910143e5  Andrew Kelley - Ability to compile C++, Objective-C, and Objective-C++ files 621e89a8  Andrew Kelley f8b38a17  Andrew Kelley However, a compiler built this way does provide a C backend, which may be f8b38a17  Andrew Kelley useful for creating system packages of Zig projects using the system C f8b38a17  Andrew Kelley toolchain. In such case, LLVM is not needed! f8b38a17  Andrew Kelley 9ada2f88  Andrew Kelley ## Contributing 9ada2f88  Andrew Kelley 910143e5  Andrew Kelley [Donate monthly](https://ziglang.org/zsf/). 910143e5  Andrew Kelley 9ada2f88  Andrew Kelley Zig is Free and Open Source Software. We welcome bug reports and patches from 9ada2f88  Andrew Kelley everyone. However, keep in mind that Zig governance is BDFN (Benevolent 9ada2f88  Andrew Kelley Dictator For Now) which means that Andrew Kelley has final say on the design 9ada2f88  Andrew Kelley and implementation of everything. 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley One of the best ways you can contribute to Zig is to start using it for an 9ada2f88  Andrew Kelley open-source personal project. 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley This leads to discovering bugs and helps flesh out use cases, which lead to 9ada2f88  Andrew Kelley further design iterations of Zig. Importantly, each issue found this way comes 9ada2f88  Andrew Kelley with real world motivations, making it straightforward to explain the reasoning 9ada2f88  Andrew Kelley behind proposals and feature requests. 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley You will be taken much more seriously on the issue tracker if you have a 9ada2f88  Andrew Kelley personal project that uses Zig. 9ada2f88  Andrew Kelley 9ada2f88  Andrew Kelley The issue label 9ada2f88  Andrew Kelley [Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22) 9ada2f88  Andrew Kelley exists to help you find issues that are **limited in scope and/or knowledge of 9ada2f88  Andrew Kelley Zig internals.** bee34f5d  Andrew Kelley 9ada2f88  Andrew Kelley Please note that issues labeled 9ada2f88  Andrew Kelley [Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal) 9ada2f88  Andrew Kelley but do not also have the 9ada2f88  Andrew Kelley [Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted) 9ada2f88  Andrew Kelley label are still under consideration, and efforts to implement such a proposal 9ada2f88  Andrew Kelley have a high risk of being wasted. If you are interested in a proposal which is 9ada2f88  Andrew Kelley still under consideration, please express your interest in the issue tracker, 9ada2f88  Andrew Kelley providing extra insights and considerations that others have not yet expressed. 9ada2f88  Andrew Kelley The most highly regarded argument in such a discussion is a real world use case. bee34f5d  Andrew Kelley 9ada2f88  Andrew Kelley For more tips, please see the 9ada2f88  Andrew Kelley [Contributing](https://github.com/ziglang/zig/wiki/Contributing) page on the 9ada2f88  Andrew Kelley wiki. bee34f5d  Andrew Kelley 9ada2f88  Andrew Kelley ## Community bee34f5d  Andrew Kelley 9ada2f88  Andrew Kelley The Zig community is decentralized. Anyone is free to start and maintain their 9ada2f88  Andrew Kelley own space for Zig users to gather. There is no concept of "official" or 9ada2f88  Andrew Kelley "unofficial". Each gathering place has its own moderators and rules. Users are 9ada2f88  Andrew Kelley encouraged to be aware of the social structures of the spaces they inhabit, and 9ada2f88  Andrew Kelley work purposefully to facilitate spaces that align with their values. b61733a4  Andrew Kelley 9ada2f88  Andrew Kelley Please see the [Community](https://github.com/ziglang/zig/wiki/Community) wiki 9ada2f88  Andrew Kelley page for a public listing of social spaces.