zig

fork of https://codeberg.org/ziglang/zig
Log | Files | Refs | README | LICENSE

README.md (5853B) - Raw

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