mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-06 06:13:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Andrew Kelley 2015-12-06 21:55:28 -07:00
parent daa3b6bfa3
commit c6fff3b2c0
1 changed files with 95 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
README.md
View File

@ -2,35 +2,78 @@
An experiment in writing a low-level programming language with the intent to An experiment in writing a low-level programming language with the intent to
replace C. Zig intends to be a small language, yet powerful enough to write replace C. Zig intends to be a small language, yet powerful enough to write
readable, safe, optimal, and concise code to solve any computing problem. optimal, readable, safe, and concise code to solve any computing problem.
Porting a C project to Zig should be a pleasant experience - every C feature
needs a corresponding Zig feature which solves the problem equivalently or
better.
Zig is not afraid to roll the major version number of the language if it
improves simplicity, fixes poor design decisions, or adds a new feature which
compromises backward compatibility.
## Goals ## Goals
* Ability to run arbitrary code at compile time and generate code.
* Completely compatible with C libraries with no wrapper necessary. * Completely compatible with C libraries with no wrapper necessary.
* Creating a C library should be a primary use case. Should be easy to export * In addition to creating executables, creating a C library is a primary use
an auto-generated .h file. case. You can export an auto-generated .h file.
* Generics such as containers.
* Do not depend on libc unless explicitly imported. * Do not depend on libc unless explicitly imported.
* First class error code support. * Provide standard library which competes with the C standard library and is
* Include documentation generator. always compiled against statically in source form.
* Eliminate the need for make, cmake, etc. * Generics so that one can write efficient data structures that work for any
* Friendly toward package maintainers. data type.
* Eliminate the need for C headers (when using zig internally). * Ability to run arbitrary code at compile time and generate code.
* Ability to declare dependencies as Git URLS with commit locking (can * A type which represents an error and has some convenience syntax with
provide a tag or sha1). regards to resources.
* Defer statement.
* Memory zeroed by default, unless you explicitly ask for uninitialized memory.
* Eliminate the need for configure, make, cmake, etc.
* Eliminate the need for header files (when using zig internally).
* Tagged union enum type. * Tagged union enum type.
* Opinionated when it makes life easier.
- Tab character in source code is a compile error.
- Whitespace at the end of line is a compile error.
* Resilient to parsing errors to make IDE integration work well. * Resilient to parsing errors to make IDE integration work well.
* Source code is UTF-8. * Source code is UTF-8.
* Shebang line OK so language can be used for "scripting" as well.
* Ability to mark functions as test and automatically run them in test mode. * Ability to mark functions as test and automatically run them in test mode.
This mode should automatically provide test coverage. This mode should automatically provide test coverage.
* Memory zeroed by default, unless you initialize with "uninitialized". * Friendly toward package maintainers.
* Ability to declare dependencies as Git URLS with commit locking (can
provide a tag or sha1).
* Include documentation generator.
* Shebang line OK so language can be used for "scripting" as well.
### Building ### Current Status
* Core language features are lacking such as structs, enums, loops.
* Have a look in the examples/ folder to see some code examples.
* Optimized machine code that Zig produces is indistinguishable from
optimized machine code produced from equivalent C program.
* Generating dynamic libraries, executables, object files, and C header files
works.
### Roadmap
* structs
* loops
* enums
* calling external variadic functions and exporting variadic functions
* inline assembly and syscalls
* conditional compilation and ability to check target platform and architecture
* main function with command line arguments
* void pointer constant
* sizeof
* static initializers
* assert
* function pointers
* running code at compile time
* standard library print functions
* panic! macro or statement that prints a stack trace to stderr in debug mode
and calls abort() in release mode
* unreachable codegen to panic("unreachable") in debug mode, and nothing in
release mode
* implement a simple game using SDL2
* implement a GUI with several types of widgets and investigate whether we need
any OOP features
## Building
``` ```
mkdir build mkdir build
@ -40,44 +83,37 @@ make
./run_tests ./run_tests
``` ```
## Roadmap ## Primitive Numeric Types:
* loops zig | C equivalent | Description
* structs -------------|---------------------|-------------------------------
* tagged enums bool | bool | unsigned 1-bit integer
* calling external variadic functions and exporting variadic functions i8 | int8_t | signed 8-bit integer
* inline assembly and syscalls u8 | uint8_t | unsigned 8-bit integer
* conditional compilation and ability to check target platform and architecture i16 | int16_t | signed 16-bit integer
* main function with command line arguments u16 | uint16_t | unsigned 16-bit integer
* running code at compile time i32 | int32_t | signed 32-bit integer
* print! macro that takes var args u32 | uint32_t | unsigned 32-bit integer
* panic! macro that prints a stack trace to stderr in debug mode and calls i64 | int64_t | signed 64-bit integer
abort() in release mode u64 | uint64_t | unsigned 64-bit integer
* unreachable codegen to panic("unreachable") in debug mode, and nothing in f32 | float | 32-bit IEE754 floating point
release mode f64 | double | 64-bit IEE754 floating point
* implement a simple game using SDL2 f128 | long double | 128-bit IEE754 floating point
* How should the Widget use case be solved? In Genesis I'm using C++ and inheritance. isize | intptr_t | signed pointer sized integer
usize | uintptr_t | unsigned pointer sized integer
c_char | char | for API compatibility with C
c_schar | signed char | for API compatibility with C
c_uchar | unsigned char | for API compatibility with C
c_short | short | for API compatibility with C
c_ushort | unsigned short | for API compatibility with C
c_int | int | for API compatibility with C
c_uint | unsigned int | for API compatibility with C
c_long | long | for API compatibility with C
c_ulong | unsigned long | for API compatibility with C
c_longlong | long long | for API compatibility with C
c_ulonglong | unsigned long long | for API compatibility with C
### Primitive Numeric Types: ## Grammar
zig | C equivalent | Description
-------|--------------|-------------------------------
bool | bool | unsigned 1-bit integer
i8 | int8_t | signed 8-bit integer
u8 | uint8_t | unsigned 8-bit integer
i16 | int16_t | signed 16-bit integer
u16 | uint16_t | unsigned 16-bit integer
i32 | int32_t | signed 32-bit integer
u32 | uint32_t | unsigned 32-bit integer
i64 | int64_t | signed 64-bit integer
u64 | uint64_t | unsigned 64-bit integer
f32 | float | 32-bit IEE754 floating point
f64 | double | 64-bit IEE754 floating point
f128 | long double | 128-bit IEE754 floating point
isize | intptr_t | signed pointer sized integer
usize | uintptr_t | unsigned pointer sized integer
### Grammar
``` ```
Root : many(TopLevelDecl) token(EOF) Root : many(TopLevelDecl) token(EOF)
@ -116,7 +152,9 @@ Label: token(Symbol) token(Colon)
Expression : BlockExpression | NonBlockExpression Expression : BlockExpression | NonBlockExpression
NonBlockExpression : ReturnExpression | VariableDeclaration | BoolOrExpression NonBlockExpression : ReturnExpression | VariableDeclaration | AssignmentExpression
AssignmentExpression : BoolOrExpression token(Equal) BoolOrExpression | BoolOrExpression
BlockExpression : IfExpression | Block BlockExpression : IfExpression | Block
@ -124,7 +162,7 @@ BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression | BoolAndEx
ReturnExpression : token(Return) option(Expression) ReturnExpression : token(Return) option(Expression)
VariableDeclaration : token(Let) token(Symbole) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression)) VariableDeclaration : token(Let) option(token(Mut)) token(Symbol) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression))
IfExpression : token(If) Expression Block option(Else | ElseIf) IfExpression : token(If) Expression Block option(Else | ElseIf)
@ -173,7 +211,7 @@ GroupedExpression : token(LParen) Expression token(RParen)
KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False) KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False)
``` ```
### Operator Precedence ## Operator Precedence
``` ```
x() x()