README.md

   1 ![ZIG](https://ziglang.org/img/zig-logo-dynamic.svg)
   2
   3 A general-purpose programming language and toolchain for maintaining
   4 **robust**, **optimal**, and **reusable** software.
   5
   6 https://ziglang.org/
   7
   8 ## Documentation
   9
  10 If you are looking at this README file in a source tree, please refer to the
  11 **Release Notes**, **Language Reference**, or **Standard Library
  12 Documentation** corresponding to the version of Zig that you are using by
  13 following the appropriate link on the
  14 [download page](https://ziglang.org/download).
  15
  16 Otherwise, you're looking at a release of Zig, and you can find documentation
  17 here:
  18
  19  * doc/langref.html
  20  * doc/std/index.html
  21
  22 ## Installation
  23
  24  * [download a pre-built binary](https://ziglang.org/download/)
  25  * [install from a package manager](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager)
  26  * [bootstrap zig for any target](https://github.com/ziglang/zig-bootstrap)
  27
  28 A Zig installation is composed of two things:
  29
  30 1. The Zig executable
  31 2. The lib/ directory
  32
  33 At runtime, the executable searches up the file system for the lib/ directory,
  34 relative to itself:
  35
  36 * lib/
  37 * lib/zig/
  38 * ../lib/
  39 * ../lib/zig/
  40 * (and so on)
  41
  42 In other words, you can **unpack a release of Zig anywhere**, and then begin
  43 using it immediately. There is no need to install it globally, although this
  44 mechanism supports that use case too (i.e. `/usr/bin/zig` and `/usr/lib/zig/`).
  45
  46 ## Building from Source
  47
  48 Ensure you have the required dependencies:
  49
  50  * CMake >= 3.15
  51  * System C/C++ Toolchain
  52  * LLVM, Clang, LLD development libraries == 18.x
  53
  54 Then it is the standard CMake build process:
  55
  56 ```
  57 mkdir build
  58 cd build
  59 cmake ..
  60 make install
  61 ```
  62
  63 For more options, tips, and troubleshooting, please see the
  64 [Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source)
  65 page on the wiki.
  66
  67 ## Building from Source without LLVM
  68
  69 In this case, the only system dependency is a C compiler.
  70
  71 ```
  72 cc -o bootstrap bootstrap.c
  73 ./bootstrap
  74 ```
  75
  76 This produces a `zig2` executable in the current working directory. This is a
  77 "stage2" build of the compiler,
  78 [without LLVM extensions](https://github.com/ziglang/zig/issues/16270), and is
  79 therefore lacking these features:
  80 - Release mode optimizations
  81 - aarch64 machine code backend
  82 - `@cImport` / `zig translate-c`
  83 - Ability to compile C files
  84 - Ability to compile assembly files
  85 - [Some ELF linking features](https://github.com/ziglang/zig/issues/17749)
  86 - [Most COFF/PE linking features](https://github.com/ziglang/zig/issues/17751)
  87 - [Some WebAssembly linking features](https://github.com/ziglang/zig/issues/17750)
  88 - [Ability to create import libs from def files](https://github.com/ziglang/zig/issues/17807)
  89 - [Automatic importlib file generation for Windows DLLs](https://github.com/ziglang/zig/issues/17753)
  90 - [Ability to create static archives from object files](https://github.com/ziglang/zig/issues/9828)
  91 - Ability to compile C++, Objective-C, and Objective-C++ files
  92
  93 However, a compiler built this way does provide a C backend, which may be
  94 useful for creating system packages of Zig projects using the system C
  95 toolchain. In such case, LLVM is not needed!
  96
  97 ## Contributing
  98
  99 [Donate monthly](https://ziglang.org/zsf/).
 100
 101 Zig is Free and Open Source Software. We welcome bug reports and patches from
 102 everyone. However, keep in mind that Zig governance is BDFN (Benevolent
 103 Dictator For Now) which means that Andrew Kelley has final say on the design
 104 and implementation of everything.
 105
 106 One of the best ways you can contribute to Zig is to start using it for an
 107 open-source personal project.
 108
 109 This leads to discovering bugs and helps flesh out use cases, which lead to
 110 further design iterations of Zig. Importantly, each issue found this way comes
 111 with real world motivations, making it straightforward to explain the reasoning
 112 behind proposals and feature requests.
 113
 114 You will be taken much more seriously on the issue tracker if you have a
 115 personal project that uses Zig.
 116
 117 The issue label
 118 [Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
 119 exists to help you find issues that are **limited in scope and/or knowledge of
 120 Zig internals.**
 121
 122 Please note that issues labeled
 123 [Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
 124 but do not also have the
 125 [Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
 126 label are still under consideration, and efforts to implement such a proposal
 127 have a high risk of being wasted. If you are interested in a proposal which is
 128 still under consideration, please express your interest in the issue tracker,
 129 providing extra insights and considerations that others have not yet expressed.
 130 The most highly regarded argument in such a discussion is a real world use case.
 131
 132 For more tips, please see the
 133 [Contributing](https://github.com/ziglang/zig/wiki/Contributing) page on the
 134 wiki.
 135
 136 ## Community
 137
 138 The Zig community is decentralized. Anyone is free to start and maintain their
 139 own space for Zig users to gather. There is no concept of "official" or
 140 "unofficial". Each gathering place has its own moderators and rules. Users are
 141 encouraged to be aware of the social structures of the spaces they inhabit, and
 142 work purposefully to facilitate spaces that align with their values.
 143
 144 Please see the [Community](https://github.com/ziglang/zig/wiki/Community) wiki
 145 page for a public listing of social spaces.