Commit c6fff3b2c0796180b2232248d8b19f9e29b94011 | zig

author	Andrew Kelley <andrew@ziglang.org> 2015-12-06 21:55:28-07:00
committer	Andrew Kelley <andrew@ziglang.org> 2015-12-06 21:55:28-07:00
log	c6fff3b2c0796180b2232248d8b19f9e29b94011
tree	dda27d47d0830abafc615bc6f60f27d42392a6cc
parent	daa3b6bfa32e3be1c434b20ba91f6a519304c81c

update README

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

README.md

README.md+94-56

...	...	@@ -2,82 +2,118 @@
2	2
3	3	An experiment in writing a low-level programming language with the intent to
4	4	replace C. Zig intends to be a small language, yet powerful enough to write
5		readable, safe, optimal, and concise code to solve any computing problem.
	5	optimal, readable, safe, and concise code to solve any computing problem.
	6
	7	Porting a C project to Zig should be a pleasant experience - every C feature
	8	needs a corresponding Zig feature which solves the problem equivalently or
	9	better.
	10
	11	Zig is not afraid to roll the major version number of the language if it
	12	improves simplicity, fixes poor design decisions, or adds a new feature which
	13	compromises backward compatibility.
6	14
7	15	## Goals
8	16
9		* Ability to run arbitrary code at compile time and generate code.
10	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 export
12		an auto-generated .h file.
13		* Generics such as containers.
	18	* In addition to creating executables, creating a C library is a primary use
	19	case. You can export an auto-generated .h file.
14	20	* Do not depend on libc unless explicitly imported.
15		* First class error code support.
16		* Include documentation generator.
17		* Eliminate the need for make, cmake, etc.
18		* Friendly toward package maintainers.
19		* Eliminate the need for C headers (when using zig internally).
20		* Ability to declare dependencies as Git URLS with commit locking (can
21		provide a tag or sha1).
	21	* Provide standard library which competes with the C standard library and is
	22	always compiled against statically in source form.
	23	* Generics so that one can write efficient data structures that work for any
	24	data type.
	25	* Ability to run arbitrary code at compile time and generate code.
	26	* A type which represents an error and has some convenience syntax with
	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	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	33	* Resilient to parsing errors to make IDE integration work well.
27	34	* Source code is UTF-8.
28		* Shebang line OK so language can be used for "scripting" as well.
29	35	* Ability to mark functions as test and automatically run them in test mode.
30	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.
32	42
33		### Building
	43	### Current Status
34	44
35		```
36		mkdir build
37		cd build
38		cmake ..
39		make
40		./run_tests
41		```
	45	* Core language features are lacking such as structs, enums, loops.
	46	* Have a look in the examples/ folder to see some code examples.
	47	* Optimized machine code that Zig produces is indistinguishable from
	48	optimized machine code produced from equivalent C program.
	49	* Generating dynamic libraries, executables, object files, and C header files
	50	works.
42	51
43		## Roadmap
	52	### Roadmap
44	53
45		* loops
46	54	* structs
47		* tagged enums
	55	* loops
	56	* enums
48	57	* calling external variadic functions and exporting variadic functions
49	58	* inline assembly and syscalls
50	59	* conditional compilation and ability to check target platform and architecture
51	60	* main function with command line arguments
	61	* void pointer constant
	62	* sizeof
	63	* static initializers
	64	* assert
	65	* function pointers
52	66	* running code at compile time
53		* print! macro that takes var args
54		* panic! macro that prints a stack trace to stderr in debug mode and calls
55		abort() in release mode
	67	* standard library print functions
	68	* panic! macro or statement that prints a stack trace to stderr in debug mode
	69	and calls abort() in release mode
56	70	* unreachable codegen to panic("unreachable") in debug mode, and nothing in
57	71	release mode
58	72	* implement a simple game using SDL2
59		* How should the Widget use case be solved? In Genesis I'm using C++ and inheritance.
60
61		### Primitive Numeric Types:
62
63		zig \| C equivalent \| Description
64		-------\|--------------\|-------------------------------
65		bool \| bool \| unsigned 1-bit integer
66		i8 \| int8_t \| signed 8-bit integer
67		u8 \| uint8_t \| unsigned 8-bit integer
68		i16 \| int16_t \| signed 16-bit integer
69		u16 \| uint16_t \| unsigned 16-bit integer
70		i32 \| int32_t \| signed 32-bit integer
71		u32 \| uint32_t \| unsigned 32-bit integer
72		i64 \| int64_t \| signed 64-bit integer
73		u64 \| uint64_t \| unsigned 64-bit integer
74		f32 \| float \| 32-bit IEE754 floating point
75		f64 \| double \| 64-bit IEE754 floating point
76		f128 \| long double \| 128-bit IEE754 floating point
77		isize \| intptr_t \| signed pointer sized integer
78		usize \| uintptr_t \| unsigned pointer sized integer
79
80		### Grammar
	73	* implement a GUI with several types of widgets and investigate whether we need
	74	any OOP features
	75
	76	## Building
	77
	78	```
	79	mkdir build
	80	cd build
	81	cmake ..
	82	make
	83	./run_tests
	84	```
	85
	86	## Primitive Numeric Types:
	87
	88	zig \| C equivalent \| Description
	89	-------------\|---------------------\|-------------------------------
	90	bool \| bool \| unsigned 1-bit integer
	91	i8 \| int8_t \| signed 8-bit integer
	92	u8 \| uint8_t \| unsigned 8-bit integer
	93	i16 \| int16_t \| signed 16-bit integer
	94	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
81	117
82	118	```
83	119	Root : many(TopLevelDecl) token(EOF)
...	...	@@ -116,7 +152,9 @@ Label: token(Symbol) token(Colon)
116	152
117	153	Expression : BlockExpression \| NonBlockExpression
118	154
119		NonBlockExpression : ReturnExpression \| VariableDeclaration \| BoolOrExpression
	155	NonBlockExpression : ReturnExpression \| VariableDeclaration \| AssignmentExpression
	156
	157	AssignmentExpression : BoolOrExpression token(Equal) BoolOrExpression \| BoolOrExpression
120	158
121	159	BlockExpression : IfExpression \| Block
122	160
...	...	@@ -124,7 +162,7 @@ BoolOrExpression : BoolAndExpression token(BoolOr) BoolAndExpression \| BoolAndEx
124	162
125	163	ReturnExpression : token(Return) option(Expression)
126	164
127		VariableDeclaration : token(Let) token(Symbole) (token(Eq) Expression \| token(Colon) Type option(token(Eq) Expression))
	165	VariableDeclaration : token(Let) option(token(Mut)) token(Symbol) (token(Eq) Expression \| token(Colon) Type option(token(Eq) Expression))
128	166
129	167	IfExpression : token(If) Expression Block option(Else \| ElseIf)
130	168
...	...	@@ -173,7 +211,7 @@ GroupedExpression : token(LParen) Expression token(RParen)
173	211	KeywordLiteral : token(Unreachable) \| token(Void) \| token(True) \| token(False)
174	212	```
175	213
176		### Operator Precedence
	214	## Operator Precedence
177	215
178	216	```
179	217	x()