Commit b09280b48452be8b57b87bbf4eaacd430e6e3537 | zig

author	Andrew Kelley <andrew@ziglang.org> 2022-03-24 12:20:53-07:00
committer	Andrew Kelley <andrew@ziglang.org> 2022-03-24 12:22:23-07:00
log	b09280b48452be8b57b87bbf4eaacd430e6e3537
tree	0f6324a18bf4b4968f8d763f3bd26d259d7bbd67
parent	2af69710a7b1513f3540ae0e1178cb5f3948204d

move some files to the .github directory

5 files changed, 289 insertions(+), 289 deletions(-)

.github
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
README.md

.github/CODE_OF_CONDUCT.md created+75

...	...	@@ -0,0 +1,75 @@
	1	# Code of Conduct
	2
	3	Hello, and welcome! 👋
	4
	5	The Zig community is decentralized. Anyone is free to start and maintain their
	6	own space for people to gather, and edit
	7	[the Community wiki page](https://github.com/ziglang/zig/wiki/Community) to add
	8	a link. There is no concept of "official" or "unofficial", however, each
	9	gathering place has its own moderators and rules.
	10
	11	This is Andrew Kelley speaking. At least for now, I'm the moderator of the
	12	ziglang organization GitHub repositories and the #zig IRC channel on Libera.chat.
	13	This document contains the rules that govern these two spaces only.
	14
	15	The rules here are strict. This space is for focused, on topic, technical work
	16	on the Zig project only. It is everyone's responsibility to maintain a positive
	17	environment, especially when disagreements occur.
	18
	19	## Our Standards
	20
	21	Examples of behavior that contribute to creating a positive environment include:
	22
	23	* Using welcoming and inclusive language.
	24	* Being respectful of differing viewpoints and experiences.
	25	* Gracefully accepting constructive criticism.
	26	* Helping another person accomplish their own goals.
	27	* Showing empathy towards others.
	28	* Showing appreciation for others' work.
	29	* Validating someone else's experience, skills, insight, and use cases.
	30
	31	Examples of unacceptable behavior by participants include:
	32
	33	* Unwelcome sexual attention or advances, or use of sexualized language or
	34	imagery that causes discomfort.
	35	* Trolling, insulting/derogatory comments, and personal attacks. Anything
	36	antagonistic towards someone else.
	37	* Off-topic discussion of any kind - especially offensive or sensitive issues.
	38	* Publishing others' private information, such as a physical or electronic
	39	address, without explicit permission.
	40	* Discussing this Code of Conduct or publicly accusing someone of violating it.
	41	* Making someone else feel like an outsider or implying a lack of technical
	42	abilities.
	43	* Destructive behavior. Anything that harms Zig or another open-source project.
	44
	45	## Enforcement
	46
	47	If you need to report an issue you can contact me or Loris Cro, who are both
	48	paid by the Zig Software Foundation, and so moderation of this space is part of
	49	our job. We will swiftly remove anyone who is antagonizing others or being
	50	generally destructive.
	51
	52	This includes Private Harassment. If person A is directly harassed or
	53	antagonized by person B, person B will be blocked from participating in this
	54	space even if the harassment didn't take place on one of the mediums directly
	55	under rule of this Code of Conduct.
	56
	57	As noted, discussing this Code of Conduct should not take place on GitHub or IRC
	58	because these spaces are for directly working on code, not for meta-discussion.
	59	If you have any issues with it, you can contact me directly, or you can join one
	60	of the community spaces that has different rules.
	61
	62	* Andrew Kelley <andrew@ziglang.org>
	63	* Loris Cro <loris@ziglang.org>
	64
	65	## Conclusion
	66
	67	Thanks for reading the rules. Together, we can make this space welcoming and
	68	inclusive for everyone, regardless of age, body size, disability, ethnicity,
	69	sex characteristics, gender identity and expression, level of experience,
	70	education, socio-economic status, nationality, personal appearance, race,
	71	religion, or sexual identity and orientation.
	72
	73	Sincerely,
	74
	75	Andrew ✌️

.github/CONTRIBUTING.md created+212

...	...	@@ -0,0 +1,212 @@
	1	## Contributing
	2
	3	### Start a Project Using Zig
	4
	5	One of the best ways you can contribute to Zig is to start using it for a
	6	personal project. Here are some great examples:
	7
	8	* [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games
	9	* [River](https://github.com/ifreund/river/) - a dynamic tiling wayland compositor
	10
	11	More examples can be found on the
	12	[Community Projects Wiki](https://github.com/ziglang/zig/wiki/Community-Projects).
	13
	14	Without fail, these projects lead to discovering bugs and helping flesh out use
	15	cases, which lead to further design iterations of Zig. Importantly, each issue
	16	found this way comes with real world motivations, so it is easy to explain
	17	your reasoning behind proposals and feature requests.
	18
	19	Ideally, such a project will help you to learn new skills and add something
	20	to your personal portfolio at the same time.
	21
	22	### Spread the Word
	23
	24	Another way to contribute is to write about Zig, or speak about Zig at a
	25	conference, or do either of those things for your project which uses Zig.
	26	Here are some examples:
	27
	28	* [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html)
	29	* [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY)
	30	* [Writing a small ray tracer in Rust and Zig](https://nelari.us/post/raytracer_with_rust_and_zig/)
	31
	32	Zig is a brand new language, with no advertising budget. Word of mouth is the
	33	only way people find out about the project, and the more people hear about it,
	34	the more people will use it, and the better chance we have to take over the
	35	world.
	36
	37	### Finding Contributor Friendly Issues
	38
	39	Please note that issues labeled
	40	[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
	41	but do not also have the
	42	[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
	43	label are still under consideration, and efforts to implement such a proposal
	44	have a high risk of being wasted. If you are interested in a proposal which is
	45	still under consideration, please express your interest in the issue tracker,
	46	providing extra insights and considerations that others have not yet expressed.
	47	The most highly regarded argument in such a discussion is a real world use case.
	48
	49	The issue label
	50	[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
	51	exists to help you find issues that are **limited in scope and/or
	52	knowledge of Zig internals.**
	53
	54	### Editing Source Code
	55
	56	First, build the Stage 1 compiler as described in
	57	[Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source).
	58
	59	Zig locates lib files relative to executable path by searching up the
	60	filesystem tree for a sub-path of `lib/zig/std/std.zig` or `lib/std/std.zig`.
	61	Typically the former is an install and the latter a git working tree which
	62	contains the build directory.
	63
	64	During development it is not necessary to perform installs when modifying
	65	stage1 or userland sources and in fact it is faster and simpler to run,
	66	test and debug from a git working tree.
	67
	68	- `make` is typically sufficient to build zig during development iterations.
	69	- `make install` performs a build __and__ install.
	70	- `msbuild -p:Configuration=Release INSTALL.vcxproj` on Windows performs a
	71	build and install. To avoid install, pass cmake option `-DZIG_SKIP_INSTALL_LIB_FILES=ON`.
	72
	73	To test changes, do the following from the build directory:
	74
	75	1. Run `make` (on POSIX) or
	76	`msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows).
	77	2. `$BUILD_DIR/zig build test` (on POSIX) or
	78	`$BUILD_DIR/Release\zig.exe build test` (on Windows).
	79
	80	That runs the whole test suite, which does a lot of extra testing that you
	81	likely won't always need, and can take upwards of 1 hour. This is what the
	82	CI server runs when you make a pull request. (Note: actually it runs a few
	83	more tests; keep reading.)
	84
	85	To save time, you can add the `--help` option to the `zig build` command and
	86	see what options are available. One of the most helpful ones is
	87	`-Dskip-release`. Adding this option to the command in step 2 above will take
	88	the time down from around 2 hours to about 6 minutes, and this is a good
	89	enough amount of testing before making a pull request.
	90
	91	Another example is choosing a different set of things to test. For example,
	92	`test-std` instead of `test` will only run the standard library tests, and
	93	not the other ones. Combining this suggestion with the previous one, you could
	94	do this:
	95
	96	`$BUILD_DIR/bin/zig build test-std -Dskip-release` (on POSIX) or
	97	`$BUILD_DIR/Release\zig.exe build test-std -Dskip-release` (on Windows).
	98
	99	This will run only the standard library tests, in debug mode only, for all
	100	targets (it will cross-compile the tests for non-native targets but not run
	101	them).
	102
	103	When making changes to the compiler source code, the most helpful test step to
	104	run is `test-behavior`. When editing documentation it is `docs`. You can find
	105	this information and more in the `--help` menu.
	106
	107	#### Testing Changes to std lib
	108
	109	To quickly test a change to a file in the standard library, you can run zig test and specify a custom lib directory with the follow command-line argument.
	110
	111	```bash
	112	./build/zig test lib/std/fmt.zig --zig-lib-dir lib --main-pkg-path lib/std
	113	```
	114
	115	#### Testing Non-Native Architectures with QEMU
	116
	117	The Linux CI server additionally has qemu installed and sets `-fqemu`.
	118	This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's
	119	recommended for Linux users to install qemu and enable this testing option
	120	when editing the standard library or anything related to a non-native
	121	architecture.
	122
	123	##### glibc
	124
	125	Testing foreign architectures with dynamically linked glibc is one step trickier.
	126	This requires enabling `--glibc-runtimes /path/to/glibc/multi/install/glibcs`.
	127	This path is obtained by building glibc for multiple architectures. This
	128	process for me took an entire day to complete and takes up 65 GiB on my hard
	129	drive. The CI server does not provide this test coverage. Instructions for
	130	producing this path can be found
	131	[on the wiki](https://github.com/ziglang/zig/wiki/Updating-libc#glibc).
	132	Just the part with `build-many-glibcs.py`.
	133
	134	It's understood that most contributors will not have these tests enabled.
	135
	136	#### Testing Windows from a Linux Machine with Wine
	137
	138	When developing on Linux, another option is available to you: `-fwine`.
	139	This will enable running behavior tests and std lib tests with Wine. It's
	140	recommended for Linux users to install Wine and enable this testing option
	141	when editing the standard library or anything Windows-related.
	142
	143	#### Testing WebAssembly using wasmtime
	144
	145	If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the
	146	`-fwasmtime` flag which will enable running WASI behavior tests and std
	147	lib tests. It's recommended for all users to install wasmtime and enable this
	148	testing option when editing the standard library and especially anything
	149	WebAssembly-related.
	150
	151	#### Improving Translate-C
	152
	153	Please read the [Editing Source Code](#editing-source-code) section as a
	154	prerequisite to this one.
	155
	156	`translate-c` is a feature provided by Zig that converts C source code into
	157	Zig source code. It powers the `zig translate-c` command as well as
	158	[@cImport](https://ziglang.org/documentation/master/#cImport), allowing Zig
	159	code to not only take advantage of function prototypes defined in .h files,
	160	but also `static inline` functions written in C, and even some macros.
	161
	162	This feature works by using libclang API to parse and semantically analyze
	163	C/C++ files, and then based on the provided AST and type information,
	164	generating Zig AST, and finally using the mechanisms of `zig fmt` to render
	165	the Zig AST to a file.
	166
	167	The relevant tests for this feature are:
	168
	169	* `test/run_translated_c.zig` - each test case is C code with a `main` function. The C code
	170	is translated into Zig code, compiled, and run, and tests that the expected output is the
	171	same, and that the program exits cleanly. This kind of test coverage is preferred, when
	172	possible, because it makes sure that the resulting Zig code is actually viable.
	173
	174	* `test/stage1/behavior/translate_c_macros.zig` - each test case consists of a Zig test
	175	which checks that the relevant macros in `test/stage1/behavior/translate_c_macros.h`.
	176	have the correct values. Macros have to be tested separately since they are expanded by
	177	Clang in `run_translated_c` tests.
	178
	179	* `test/translate_c.zig` - each test case is C code, with a list of expected strings which
	180	must be found in the resulting Zig code. This kind of test is more precise in what it
	181	measures, but does not provide test coverage of whether the resulting Zig code is valid.
	182
	183	This feature is self-hosted, even though Zig is not fully self-hosted yet. In the Zig source
	184	repo, we maintain a C API on top of Clang's C++ API:
	185
	186	* `src/zig_clang.h` - the C API that we maintain on top of Clang's C++ API. This
	187	file does not include any Clang's C++ headers. Instead, C types and C enums are defined
	188	here.
	189
	190	* `src/zig_clang.cpp` - a lightweight wrapper that fulfills the C API on top of the
	191	C++ API. It takes advantage of `static_assert` to make sure we get compile errors when
	192	Clang's C++ API changes. This one file necessarily does include Clang's C++ headers, which
	193	makes it the slowest-to-compile source file in all of Zig's codebase.
	194
	195	* `src/clang.zig` - the Zig equivalent of `src/zig_clang.h`. This is a manually
	196	maintained list of types and functions that are ABI-compatible with the Clang C API we
	197	maintain. In theory this could be generated by running translate-c on `src/zig_clang.h`,
	198	but that would introduce a dependency cycle, since we are using this file to implement
	199	translate-c.
	200
	201	Finally, the actual source code for the translate-c feature is
	202	`src/translate_c.zig`. This code uses the Clang C API exposed by
	203	`src/clang.zig`, and produces Zig AST.
	204
	205	The steps for contributing to translate-c look like this:
	206
	207	1. Identify a test case you want to improve. Add it as a run-translated-c test
	208	case (usually preferable), or as a translate-c test case.
	209
	210	2. Edit `src/translate_c.zig` to improve the behavior.
	211
	212	3. Run the relevant tests: `./zig build test-run-translated-c test-translate-c`

CODE_OF_CONDUCT.md deleted-75

...	...	@@ -1,75 +0,0 @@
1		# Code of Conduct
2
3		Hello, and welcome! 👋
4
5		The Zig community is decentralized. Anyone is free to start and maintain their
6		own space for people to gather, and edit
7		[the Community wiki page](https://github.com/ziglang/zig/wiki/Community) to add
8		a link. There is no concept of "official" or "unofficial", however, each
9		gathering place has its own moderators and rules.
10
11		This is Andrew Kelley speaking. At least for now, I'm the moderator of the
12		ziglang organization GitHub repositories and the #zig IRC channel on Libera.chat.
13		This document contains the rules that govern these two spaces only.
14
15		The rules here are strict. This space is for focused, on topic, technical work
16		on the Zig project only. It is everyone's responsibility to maintain a positive
17		environment, especially when disagreements occur.
18
19		## Our Standards
20
21		Examples of behavior that contribute to creating a positive environment include:
22
23		* Using welcoming and inclusive language.
24		* Being respectful of differing viewpoints and experiences.
25		* Gracefully accepting constructive criticism.
26		* Helping another person accomplish their own goals.
27		* Showing empathy towards others.
28		* Showing appreciation for others' work.
29		* Validating someone else's experience, skills, insight, and use cases.
30
31		Examples of unacceptable behavior by participants include:
32
33		* Unwelcome sexual attention or advances, or use of sexualized language or
34		imagery that causes discomfort.
35		* Trolling, insulting/derogatory comments, and personal attacks. Anything
36		antagonistic towards someone else.
37		* Off-topic discussion of any kind - especially offensive or sensitive issues.
38		* Publishing others' private information, such as a physical or electronic
39		address, without explicit permission.
40		* Discussing this Code of Conduct or publicly accusing someone of violating it.
41		* Making someone else feel like an outsider or implying a lack of technical
42		abilities.
43		* Destructive behavior. Anything that harms Zig or another open-source project.
44
45		## Enforcement
46
47		If you need to report an issue you can contact me or Loris Cro, who are both
48		paid by the Zig Software Foundation, and so moderation of this space is part of
49		our job. We will swiftly remove anyone who is antagonizing others or being
50		generally destructive.
51
52		This includes Private Harassment. If person A is directly harassed or
53		antagonized by person B, person B will be blocked from participating in this
54		space even if the harassment didn't take place on one of the mediums directly
55		under rule of this Code of Conduct.
56
57		As noted, discussing this Code of Conduct should not take place on GitHub or IRC
58		because these spaces are for directly working on code, not for meta-discussion.
59		If you have any issues with it, you can contact me directly, or you can join one
60		of the community spaces that has different rules.
61
62		* Andrew Kelley <andrew@ziglang.org>
63		* Loris Cro <loris@ziglang.org>
64
65		## Conclusion
66
67		Thanks for reading the rules. Together, we can make this space welcoming and
68		inclusive for everyone, regardless of age, body size, disability, ethnicity,
69		sex characteristics, gender identity and expression, level of experience,
70		education, socio-economic status, nationality, personal appearance, race,
71		religion, or sexual identity and orientation.
72
73		Sincerely,
74
75		Andrew ✌️

CONTRIBUTING.md deleted-212

...	...	@@ -1,212 +0,0 @@
1		## Contributing
2
3		### Start a Project Using Zig
4
5		One of the best ways you can contribute to Zig is to start using it for a
6		personal project. Here are some great examples:
7
8		* [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games
9		* [River](https://github.com/ifreund/river/) - a dynamic tiling wayland compositor
10
11		More examples can be found on the
12		[Community Projects Wiki](https://github.com/ziglang/zig/wiki/Community-Projects).
13
14		Without fail, these projects lead to discovering bugs and helping flesh out use
15		cases, which lead to further design iterations of Zig. Importantly, each issue
16		found this way comes with real world motivations, so it is easy to explain
17		your reasoning behind proposals and feature requests.
18
19		Ideally, such a project will help you to learn new skills and add something
20		to your personal portfolio at the same time.
21
22		### Spread the Word
23
24		Another way to contribute is to write about Zig, or speak about Zig at a
25		conference, or do either of those things for your project which uses Zig.
26		Here are some examples:
27
28		* [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html)
29		* [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY)
30		* [Writing a small ray tracer in Rust and Zig](https://nelari.us/post/raytracer_with_rust_and_zig/)
31
32		Zig is a brand new language, with no advertising budget. Word of mouth is the
33		only way people find out about the project, and the more people hear about it,
34		the more people will use it, and the better chance we have to take over the
35		world.
36
37		### Finding Contributor Friendly Issues
38
39		Please note that issues labeled
40		[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
41		but do not also have the
42		[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
43		label are still under consideration, and efforts to implement such a proposal
44		have a high risk of being wasted. If you are interested in a proposal which is
45		still under consideration, please express your interest in the issue tracker,
46		providing extra insights and considerations that others have not yet expressed.
47		The most highly regarded argument in such a discussion is a real world use case.
48
49		The issue label
50		[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
51		exists to help you find issues that are **limited in scope and/or
52		knowledge of Zig internals.**
53
54		### Editing Source Code
55
56		First, build the Stage 1 compiler as described in
57		[Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source).
58
59		Zig locates lib files relative to executable path by searching up the
60		filesystem tree for a sub-path of `lib/zig/std/std.zig` or `lib/std/std.zig`.
61		Typically the former is an install and the latter a git working tree which
62		contains the build directory.
63
64		During development it is not necessary to perform installs when modifying
65		stage1 or userland sources and in fact it is faster and simpler to run,
66		test and debug from a git working tree.
67
68		- `make` is typically sufficient to build zig during development iterations.
69		- `make install` performs a build __and__ install.
70		- `msbuild -p:Configuration=Release INSTALL.vcxproj` on Windows performs a
71		build and install. To avoid install, pass cmake option `-DZIG_SKIP_INSTALL_LIB_FILES=ON`.
72
73		To test changes, do the following from the build directory:
74
75		1. Run `make` (on POSIX) or
76		`msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows).
77		2. `$BUILD_DIR/zig build test` (on POSIX) or
78		`$BUILD_DIR/Release\zig.exe build test` (on Windows).
79
80		That runs the whole test suite, which does a lot of extra testing that you
81		likely won't always need, and can take upwards of 1 hour. This is what the
82		CI server runs when you make a pull request. (Note: actually it runs a few
83		more tests; keep reading.)
84
85		To save time, you can add the `--help` option to the `zig build` command and
86		see what options are available. One of the most helpful ones is
87		`-Dskip-release`. Adding this option to the command in step 2 above will take
88		the time down from around 2 hours to about 6 minutes, and this is a good
89		enough amount of testing before making a pull request.
90
91		Another example is choosing a different set of things to test. For example,
92		`test-std` instead of `test` will only run the standard library tests, and
93		not the other ones. Combining this suggestion with the previous one, you could
94		do this:
95
96		`$BUILD_DIR/bin/zig build test-std -Dskip-release` (on POSIX) or
97		`$BUILD_DIR/Release\zig.exe build test-std -Dskip-release` (on Windows).
98
99		This will run only the standard library tests, in debug mode only, for all
100		targets (it will cross-compile the tests for non-native targets but not run
101		them).
102
103		When making changes to the compiler source code, the most helpful test step to
104		run is `test-behavior`. When editing documentation it is `docs`. You can find
105		this information and more in the `--help` menu.
106
107		#### Testing Changes to std lib
108
109		To quickly test a change to a file in the standard library, you can run zig test and specify a custom lib directory with the follow command-line argument.
110
111		```bash
112		./build/zig test lib/std/fmt.zig --zig-lib-dir lib --main-pkg-path lib/std
113		```
114
115		#### Testing Non-Native Architectures with QEMU
116
117		The Linux CI server additionally has qemu installed and sets `-fqemu`.
118		This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's
119		recommended for Linux users to install qemu and enable this testing option
120		when editing the standard library or anything related to a non-native
121		architecture.
122
123		##### glibc
124
125		Testing foreign architectures with dynamically linked glibc is one step trickier.
126		This requires enabling `--glibc-runtimes /path/to/glibc/multi/install/glibcs`.
127		This path is obtained by building glibc for multiple architectures. This
128		process for me took an entire day to complete and takes up 65 GiB on my hard
129		drive. The CI server does not provide this test coverage. Instructions for
130		producing this path can be found
131		[on the wiki](https://github.com/ziglang/zig/wiki/Updating-libc#glibc).
132		Just the part with `build-many-glibcs.py`.
133
134		It's understood that most contributors will not have these tests enabled.
135
136		#### Testing Windows from a Linux Machine with Wine
137
138		When developing on Linux, another option is available to you: `-fwine`.
139		This will enable running behavior tests and std lib tests with Wine. It's
140		recommended for Linux users to install Wine and enable this testing option
141		when editing the standard library or anything Windows-related.
142
143		#### Testing WebAssembly using wasmtime
144
145		If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the
146		`-fwasmtime` flag which will enable running WASI behavior tests and std
147		lib tests. It's recommended for all users to install wasmtime and enable this
148		testing option when editing the standard library and especially anything
149		WebAssembly-related.
150
151		#### Improving Translate-C
152
153		Please read the [Editing Source Code](#editing-source-code) section as a
154		prerequisite to this one.
155
156		`translate-c` is a feature provided by Zig that converts C source code into
157		Zig source code. It powers the `zig translate-c` command as well as
158		[@cImport](https://ziglang.org/documentation/master/#cImport), allowing Zig
159		code to not only take advantage of function prototypes defined in .h files,
160		but also `static inline` functions written in C, and even some macros.
161
162		This feature works by using libclang API to parse and semantically analyze
163		C/C++ files, and then based on the provided AST and type information,
164		generating Zig AST, and finally using the mechanisms of `zig fmt` to render
165		the Zig AST to a file.
166
167		The relevant tests for this feature are:
168
169		* `test/run_translated_c.zig` - each test case is C code with a `main` function. The C code
170		is translated into Zig code, compiled, and run, and tests that the expected output is the
171		same, and that the program exits cleanly. This kind of test coverage is preferred, when
172		possible, because it makes sure that the resulting Zig code is actually viable.
173
174		* `test/stage1/behavior/translate_c_macros.zig` - each test case consists of a Zig test
175		which checks that the relevant macros in `test/stage1/behavior/translate_c_macros.h`.
176		have the correct values. Macros have to be tested separately since they are expanded by
177		Clang in `run_translated_c` tests.
178
179		* `test/translate_c.zig` - each test case is C code, with a list of expected strings which
180		must be found in the resulting Zig code. This kind of test is more precise in what it
181		measures, but does not provide test coverage of whether the resulting Zig code is valid.
182
183		This feature is self-hosted, even though Zig is not fully self-hosted yet. In the Zig source
184		repo, we maintain a C API on top of Clang's C++ API:
185
186		* `src/zig_clang.h` - the C API that we maintain on top of Clang's C++ API. This
187		file does not include any Clang's C++ headers. Instead, C types and C enums are defined
188		here.
189
190		* `src/zig_clang.cpp` - a lightweight wrapper that fulfills the C API on top of the
191		C++ API. It takes advantage of `static_assert` to make sure we get compile errors when
192		Clang's C++ API changes. This one file necessarily does include Clang's C++ headers, which
193		makes it the slowest-to-compile source file in all of Zig's codebase.
194
195		* `src/clang.zig` - the Zig equivalent of `src/zig_clang.h`. This is a manually
196		maintained list of types and functions that are ABI-compatible with the Clang C API we
197		maintain. In theory this could be generated by running translate-c on `src/zig_clang.h`,
198		but that would introduce a dependency cycle, since we are using this file to implement
199		translate-c.
200
201		Finally, the actual source code for the translate-c feature is
202		`src/translate_c.zig`. This code uses the Clang C API exposed by
203		`src/clang.zig`, and produces Zig AST.
204
205		The steps for contributing to translate-c look like this:
206
207		1. Identify a test case you want to improve. Add it as a run-translated-c test
208		case (usually preferable), or as a translate-c test case.
209
210		2. Edit `src/translate_c.zig` to improve the behavior.
211
212		3. Run the relevant tests: `./zig build test-run-translated-c test-translate-c`

README.md+2-2

...	...	@@ -9,8 +9,8 @@ A general-purpose programming language and toolchain for maintaining
9	9	* [Download & Documentation](https://ziglang.org/download)
10	10	* [Chapter 0 - Getting Started \| ZigLearn.org](https://ziglearn.org/)
11	11	* [Community](https://github.com/ziglang/zig/wiki/Community)
12		* [Contributing](https://github.com/ziglang/zig/blob/master/CONTRIBUTING.md)
13		* [Code of Conduct](https://github.com/ziglang/zig/blob/master/CODE_OF_CONDUCT.md)
	12	* [Contributing](https://github.com/ziglang/zig/blob/master/.github/CONTRIBUTING.md)
	13	* [Code of Conduct](https://github.com/ziglang/zig/blob/master/.github/CODE_OF_CONDUCT.md)
14	14	* [Frequently Asked Questions](https://github.com/ziglang/zig/wiki/FAQ)
15	15	* [Community Projects](https://github.com/ziglang/zig/wiki/Community-Projects)
16	16