zig/README.md

131 lines
4.2 KiB
Markdown
Raw Normal View History

2018-05-12 22:07:55 -07:00
![ZIG](https://ziglang.org/zig-logo.svg)
2015-08-05 17:44:05 -07:00
2019-12-30 15:16:40 -08:00
A general-purpose programming language and toolchain for maintaining
**robust**, **optimal**, and **reusable** software.
2015-08-05 17:44:05 -07:00
## Resources
* [Introduction](https://ziglang.org/#Introduction)
* [Download & Documentation](https://ziglang.org/download)
* [Chapter 0 - Getting Started | ZigLearn.org](https://ziglearn.org/)
* [Community](https://github.com/ziglang/zig/wiki/Community)
2019-05-28 11:53:01 -07:00
* [Contributing](https://github.com/ziglang/zig/blob/master/CONTRIBUTING.md)
* [Code of Conduct](https://github.com/ziglang/zig/blob/master/CODE_OF_CONDUCT.md)
* [Frequently Asked Questions](https://github.com/ziglang/zig/wiki/FAQ)
2019-08-11 13:09:23 -07:00
* [Community Projects](https://github.com/ziglang/zig/wiki/Community-Projects)
2016-11-23 23:44:03 -08:00
## Building from Source
2015-12-06 20:55:28 -08:00
2018-11-06 06:55:54 -08:00
[![Build Status](https://dev.azure.com/ziglang/zig/_apis/build/status/ziglang.zig?branchName=master)](https://dev.azure.com/ziglang/zig/_build/latest?definitionId=1&branchName=master)
2017-04-21 08:06:15 -07:00
Note that you can
2020-10-26 06:38:36 -07:00
[download a binary of the master branch](https://ziglang.org/download/#release-master) or
[install Zig from a package manager](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager).
### Stage 1: Build Zig from C++ Source Code
delete all stage1 c++ code not directly related to compiling stage2 Deleted 16,000+ lines of c++ code, including: * an implementation of blake hashing * the cache hash system * compiler.cpp * all the linking code, and everything having to do with building glibc, musl, and mingw-w64 * much of the stage1 compiler internals got slimmed down since it now assumes it is always outputting an object file. More stuff: * stage1 is now built with a different strategy: we have a tiny zig0.cpp which is a slimmed down version of what stage1 main.cpp used to be. Its only purpose is to build stage2 zig code into an object file, which is then linked by the host build system (cmake) into stage1. zig0.cpp uses the same C API that stage2 now has access to, so that stage2 zig code can call into stage1 c++ code. - stage1.h is - stage2.h is - stage1.zig is the main entry point for the Zig/C++ hybrid compiler. It has the functions exported from Zig, called in C++, and bindings for the functions exported from C++, called from Zig. * removed the memory profiling instrumentation from stage1. Abandon ship! * Re-added the sections to the README about how to build stage2 and stage3. * stage2 now knows as a comptime boolean whether it is being compiled as part of stage1 or as stage2. - TODO use this flag to call into stage1 for compiling zig code. * introduce -fdll-export-fns and -fno-dll-export-fns and clarify its relationship to link_mode (static/dynamic) * implement depending on LLVM to detect native target cpu features when LLVM extensions are enabled and zig lacks CPU feature detection for that target architecture. * C importing is broken, will need some stage2 support to function again.
2020-09-17 18:29:38 -07:00
This step must be repeated when you make changes to any of the C++ source code.
#### Dependencies
2017-09-25 09:51:26 -07:00
##### POSIX
2016-02-12 13:07:12 -08:00
* cmake >= 2.8.5
2018-01-15 19:17:22 -08:00
* gcc >= 5.0.0 or clang >= 3.6.0
2020-07-24 16:49:43 -07:00
* LLVM, Clang, LLD development libraries == 11.x, compiled with the same gcc or clang version above
- 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).
2017-09-25 09:51:26 -07:00
##### Windows
* cmake >= 3.15.3
* Microsoft Visual Studio. Supported versions:
- 2017 (version 15.8)
- 2019 (version 16)
2020-07-24 16:49:43 -07:00
* LLVM, Clang, LLD development libraries == 11.x
- Use the [pre-built binaries](https://github.com/ziglang/zig/wiki/Building-Zig-on-Windows) or [build from source](https://github.com/ziglang/zig/wiki/How-to-build-LLVM,-libclang,-and-liblld-from-source#windows).
2017-09-25 09:51:26 -07:00
#### Instructions
2015-12-10 14:34:38 -08:00
2018-01-15 19:17:22 -08:00
##### POSIX
2015-12-06 20:55:28 -08:00
```
mkdir build
cd build
cmake ..
2015-12-10 14:34:38 -08:00
make install
2015-12-06 20:55:28 -08:00
```
2015-12-10 14:34:38 -08:00
Need help? [Troubleshooting Build Issues](https://github.com/ziglang/zig/wiki/Troubleshooting-Build-Issues)
##### MacOS
2017-09-18 07:47:37 -07:00
```
brew install cmake llvm
brew outdated llvm || brew upgrade llvm
2017-09-18 07:47:37 -07:00
mkdir build
cd build
cmake .. -DCMAKE_PREFIX_PATH=$(brew --prefix llvm)
2020-07-02 21:43:05 -07:00
make install
2017-09-18 07:47:37 -07:00
```
##### Windows
See https://github.com/ziglang/zig/wiki/Building-Zig-on-Windows
2020-09-11 11:30:21 -07:00
delete all stage1 c++ code not directly related to compiling stage2 Deleted 16,000+ lines of c++ code, including: * an implementation of blake hashing * the cache hash system * compiler.cpp * all the linking code, and everything having to do with building glibc, musl, and mingw-w64 * much of the stage1 compiler internals got slimmed down since it now assumes it is always outputting an object file. More stuff: * stage1 is now built with a different strategy: we have a tiny zig0.cpp which is a slimmed down version of what stage1 main.cpp used to be. Its only purpose is to build stage2 zig code into an object file, which is then linked by the host build system (cmake) into stage1. zig0.cpp uses the same C API that stage2 now has access to, so that stage2 zig code can call into stage1 c++ code. - stage1.h is - stage2.h is - stage1.zig is the main entry point for the Zig/C++ hybrid compiler. It has the functions exported from Zig, called in C++, and bindings for the functions exported from C++, called from Zig. * removed the memory profiling instrumentation from stage1. Abandon ship! * Re-added the sections to the README about how to build stage2 and stage3. * stage2 now knows as a comptime boolean whether it is being compiled as part of stage1 or as stage2. - TODO use this flag to call into stage1 for compiling zig code. * introduce -fdll-export-fns and -fno-dll-export-fns and clarify its relationship to link_mode (static/dynamic) * implement depending on LLVM to detect native target cpu features when LLVM extensions are enabled and zig lacks CPU feature detection for that target architecture. * C importing is broken, will need some stage2 support to function again.
2020-09-17 18:29:38 -07:00
### Stage 2: Build Self-Hosted Zig from Zig Source Code
Now we use the stage1 binary:
```
zig build --prefix $(pwd)/stage2 -Denable-llvm
```
This produces `stage2/bin/zig` which can be used for testing and development.
Once it is feature complete, it will be used to build stage 3 - the final compiler
binary.
### Stage 3: Rebuild Self-Hosted Zig Using the Self-Hosted Compiler
*Note: Stage 2 compiler is not yet able to build Stage 3. Building Stage 3 is
not yet supported.*
Once the self-hosted compiler can build itself, this will be the actual
compiler binary that we will install to the system. Until then, users should
use stage 1.
#### Debug / Development Build
```
stage2/bin/zig build
```
This produces `zig-cache/bin/zig`.
#### Release / Install Build
```
stage2/bin/zig build install -Drelease
```
2020-09-11 11:30:21 -07:00
## License
The ultimate goal of the Zig project is to serve users. As a first-order
effect, this means users of the compiler, helping programmers to write better
2020-10-26 06:38:36 -07:00
software. Even more important, however, are the end-users.
2020-09-11 11:30:21 -07:00
2020-10-26 06:38:36 -07:00
Zig is intended to be used to help **end-users** accomplish their goals. Zig
should be used to empower end-users, never to exploit them financially, or to
2020-10-21 19:55:35 -07:00
limit their freedom to interact with hardware or software in any way.
2020-09-11 11:30:21 -07:00
However, such problems are best solved with social norms, not with software
licenses. Any attempt to complicate the software license of Zig would risk
2020-10-21 19:55:35 -07:00
compromising the value Zig provides.
2020-09-11 11:30:21 -07:00
Therefore, Zig is available under the MIT (Expat) License, and comes with a
2020-10-26 06:38:36 -07:00
humble request: use it to make software better serve the needs of end-users.
2020-10-21 19:55:35 -07:00
This project redistributes code from other projects, some of which have other
licenses besides MIT. Such licenses are generally similar to the MIT license
for practical purposes. See the subdirectories and files inside lib/ for more
details.