authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2015-12-06 21:55:28-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2015-12-06 21:55:28-07:00
logc6fff3b2c0796180b2232248d8b19f9e29b94011
treedda27d47d0830abafc615bc6f60f27d42392a6cc
parentdaa3b6bfa32e3be1c434b20ba91f6a519304c81c

update README

1 files changed, 94 insertions(+), 56 deletions(-)

README.md+94-56
...@@ -2,82 +2,118 @@...@@ -2,82 +2,118 @@
22
3An experiment in writing a low-level programming language with the intent to3An experiment in writing a low-level programming language with the intent to
4replace C. Zig intends to be a small language, yet powerful enough to write4replace C. Zig intends to be a small language, yet powerful enough to write
5readable, safe, optimal, and concise code to solve any computing problem.5optimal, readable, safe, and concise code to solve any computing problem.
6
7Porting a C project to Zig should be a pleasant experience - every C feature
8needs a corresponding Zig feature which solves the problem equivalently or
9better.
10
11Zig is not afraid to roll the major version number of the language if it
12improves simplicity, fixes poor design decisions, or adds a new feature which
13compromises backward compatibility.
614
7## Goals15## Goals
816
9 * Ability to run arbitrary code at compile time and generate code.
10 * Completely compatible with C libraries with no wrapper necessary.17 * Completely compatible with C libraries with no wrapper necessary.
11 * Creating a C library should be a primary use case. Should be easy to export18 * In addition to creating executables, creating a C library is a primary use
12 an auto-generated .h file.19 case. You can export an auto-generated .h file.
13 * Generics such as containers.
14 * Do not depend on libc unless explicitly imported.20 * Do not depend on libc unless explicitly imported.
15 * First class error code support.21 * Provide standard library which competes with the C standard library and is
16 * Include documentation generator.22 always compiled against statically in source form.
17 * Eliminate the need for make, cmake, etc.23 * Generics so that one can write efficient data structures that work for any
18 * Friendly toward package maintainers.24 data type.
19 * Eliminate the need for C headers (when using zig internally).25 * Ability to run arbitrary code at compile time and generate code.
20 * Ability to declare dependencies as Git URLS with commit locking (can26 * A type which represents an error and has some convenience syntax with
21 provide a tag or sha1).27 regards to resources.
28 * Defer statement.
29 * Memory zeroed by default, unless you explicitly ask for uninitialized memory.
30 * Eliminate the need for configure, make, cmake, etc.
31 * Eliminate the need for header files (when using zig internally).
22 * Tagged union enum type.32 * Tagged union enum type.
23 * Opinionated when it makes life easier.
24 - Tab character in source code is a compile error.
25 - Whitespace at the end of line is a compile error.
26 * Resilient to parsing errors to make IDE integration work well.33 * Resilient to parsing errors to make IDE integration work well.
27 * Source code is UTF-8.34 * Source code is UTF-8.
28 * Shebang line OK so language can be used for "scripting" as well.
29 * Ability to mark functions as test and automatically run them in test mode.35 * Ability to mark functions as test and automatically run them in test mode.
30 This mode should automatically provide test coverage.36 This mode should automatically provide test coverage.
31 * Memory zeroed by default, unless you initialize with "uninitialized".37 * Friendly toward package maintainers.
38 * Ability to declare dependencies as Git URLS with commit locking (can
39 provide a tag or sha1).
40 * Include documentation generator.
41 * Shebang line OK so language can be used for "scripting" as well.
3242
33### Building43### Current Status
3444
35```45 * Core language features are lacking such as structs, enums, loops.
36mkdir build46 * Have a look in the examples/ folder to see some code examples.
37cd build47 * Optimized machine code that Zig produces is indistinguishable from
38cmake ..48 optimized machine code produced from equivalent C program.
39make49 * Generating dynamic libraries, executables, object files, and C header files
40./run_tests50 works.
41```
4251
43## Roadmap52### Roadmap
4453
45 * loops
46 * structs54 * structs
47 * tagged enums55 * loops
56 * enums
48 * calling external variadic functions and exporting variadic functions57 * calling external variadic functions and exporting variadic functions
49 * inline assembly and syscalls58 * inline assembly and syscalls
50 * conditional compilation and ability to check target platform and architecture59 * conditional compilation and ability to check target platform and architecture
51 * main function with command line arguments60 * main function with command line arguments
61 * void pointer constant
62 * sizeof
63 * static initializers
64 * assert
65 * function pointers
52 * running code at compile time66 * running code at compile time
53 * print! macro that takes var args67 * standard library print functions
54 * panic! macro that prints a stack trace to stderr in debug mode and calls68 * panic! macro or statement that prints a stack trace to stderr in debug mode
55 abort() in release mode69 and calls abort() in release mode
56 * unreachable codegen to panic("unreachable") in debug mode, and nothing in70 * unreachable codegen to panic("unreachable") in debug mode, and nothing in
57 release mode71 release mode
58 * implement a simple game using SDL272 * implement a simple game using SDL2
59 * How should the Widget use case be solved? In Genesis I'm using C++ and inheritance.73 * implement a GUI with several types of widgets and investigate whether we need
6074 any OOP features
61### Primitive Numeric Types:75
6276## Building
63zig | C equivalent | Description77
64-------|--------------|-------------------------------78```
65 bool | bool | unsigned 1-bit integer79mkdir build
66 i8 | int8_t | signed 8-bit integer80cd build
67 u8 | uint8_t | unsigned 8-bit integer81cmake ..
68 i16 | int16_t | signed 16-bit integer82make
69 u16 | uint16_t | unsigned 16-bit integer83./run_tests
70 i32 | int32_t | signed 32-bit integer84```
71 u32 | uint32_t | unsigned 32-bit integer85
72 i64 | int64_t | signed 64-bit integer86## Primitive Numeric Types:
73 u64 | uint64_t | unsigned 64-bit integer87
74 f32 | float | 32-bit IEE754 floating point88zig | C equivalent | Description
75 f64 | double | 64-bit IEE754 floating point89-------------|---------------------|-------------------------------
76 f128 | long double | 128-bit IEE754 floating point90 bool | bool | unsigned 1-bit integer
77 isize | intptr_t | signed pointer sized integer91 i8 | int8_t | signed 8-bit integer
78 usize | uintptr_t | unsigned pointer sized integer92 u8 | uint8_t | unsigned 8-bit integer
7993 i16 | int16_t | signed 16-bit integer
80### Grammar94 u16 | uint16_t | unsigned 16-bit integer
95 i32 | int32_t | signed 32-bit integer
96 u32 | uint32_t | unsigned 32-bit integer
97 i64 | int64_t | signed 64-bit integer
98 u64 | uint64_t | unsigned 64-bit integer
99 f32 | float | 32-bit IEE754 floating point
100 f64 | double | 64-bit IEE754 floating point
101 f128 | long double | 128-bit IEE754 floating point
102 isize | intptr_t | signed pointer sized integer
103 usize | uintptr_t | unsigned pointer sized integer
104 c_char | char | for API compatibility with C
105 c_schar | signed char | for API compatibility with C
106 c_uchar | unsigned char | for API compatibility with C
107 c_short | short | for API compatibility with C
108 c_ushort | unsigned short | for API compatibility with C
109 c_int | int | for API compatibility with C
110 c_uint | unsigned int | for API compatibility with C
111 c_long | long | for API compatibility with C
112 c_ulong | unsigned long | for API compatibility with C
113 c_longlong | long long | for API compatibility with C
114 c_ulonglong | unsigned long long | for API compatibility with C
115
116## Grammar
81117
82```118```
83Root : many(TopLevelDecl) token(EOF)119Root : many(TopLevelDecl) token(EOF)
...@@ -116,7 +152,9 @@ Label: token(Symbol) token(Colon)...@@ -116,7 +152,9 @@ Label: token(Symbol) token(Colon)
116152
117Expression : BlockExpression | NonBlockExpression153Expression : BlockExpression | NonBlockExpression
118154
119NonBlockExpression : ReturnExpression | VariableDeclaration | BoolOrExpression155NonBlockExpression : ReturnExpression | VariableDeclaration | AssignmentExpression
156
157AssignmentExpression : BoolOrExpression token(Equal) BoolOrExpression | BoolOrExpression
120158
121BlockExpression : IfExpression | Block159BlockExpression : IfExpression | Block
122160
...@@ -124,7 +162,7 @@ BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression | BoolAndEx...@@ -124,7 +162,7 @@ BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression | BoolAndEx
124162
125ReturnExpression : token(Return) option(Expression)163ReturnExpression : token(Return) option(Expression)
126164
127VariableDeclaration : token(Let) token(Symbole) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression))165VariableDeclaration : token(Let) option(token(Mut)) token(Symbol) (token(Eq) Expression | token(Colon) Type option(token(Eq) Expression))
128166
129IfExpression : token(If) Expression Block option(Else | ElseIf)167IfExpression : token(If) Expression Block option(Else | ElseIf)
130168
...@@ -173,7 +211,7 @@ GroupedExpression : token(LParen) Expression token(RParen)...@@ -173,7 +211,7 @@ GroupedExpression : token(LParen) Expression token(RParen)
173KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False)211KeywordLiteral : token(Unreachable) | token(Void) | token(True) | token(False)
174```212```
175213
176### Operator Precedence214## Operator Precedence
177215
178```216```
179x()217x()