ziglings/README.md

226 lines
7.3 KiB
Markdown
Raw Normal View History

# Ziglings
Welcome to Ziglings! This project contains a series of tiny
broken programs (and one nasty surprise). By fixing them, you'll
learn how to read and write [Zig](https://ziglang.org/) code.
![ziglings](https://user-images.githubusercontent.com/1458409/109398392-c1069500-790a-11eb-8ed4-7d7d74d32666.jpg)
Those broken programs need your help! (You'll also save the
planet from evil aliens and help some friendly elephants stick
together, which is very sweet of you.)
This project was directly inspired by the brilliant and fun
[rustlings](https://github.com/rust-lang/rustlings)
project for the [Rust](https://www.rust-lang.org/) language.
2021-03-10 14:47:23 -05:00
Indirect inspiration comes from [Ruby Koans](http://rubykoans.com/)
and the Little LISPer/Little Schemer series of books.
## Intended Audience
This will probably be difficult if you've _never_ programmed
before. But no specific programming experience is required. And
in particular, you are _not_ expected to have any prior
experience with "systems programming" or a "systems" level
language such as C.
Each exercise is self-contained and self-explained. However,
you're encouraged to also check out these Zig language resources
for more detail:
* https://ziglang.org/learn/
* https://ziglearn.org/
* https://ziglang.org/documentation/master/
Also, the [Zig community](https://github.com/ziglang/zig/wiki/Community)
is incredibly friendly and helpful!
2021-03-10 14:47:23 -05:00
## Getting Started
Install a [development build](https://ziglang.org/download/) of
the Zig compiler. (See the "master" section of the downloads
page.)
Verify the installation and build number of `zig` like so:
2023-04-13 04:41:34 -04:00
```
$ zig version
0.11.0-dev.3295+xxxxxxxxx
```
Clone this repository with Git:
2023-04-13 04:41:34 -04:00
```
$ git clone https://github.com/ratfactor/ziglings
$ cd ziglings
```
build: restore the exercise chain The new parallel build support in Zig broke the exercise chain, so that each esercise check is no longer strictly serialized. 1. Add the Dexno option, in order to isolate the chain starting from a named exercise from the normal chain, thus simplify the code. The current code have an additional issue: it added 4 x n steps, making reading the help message or the list of steps very hard. Add only the `install`, `uninstall`, `zigling`, `test` and `start` steps. The last three steps match the old steps `n`, `n_test` and `n_start`. The default step is zigling (note the singular form). The `install` step override the builtin install step, showing a custom description and matches the old `n_install` step. The uninstall step was added for consistency, so that the description is consistent. Setup a new chain starting at `zig build -Dexno=n start` so that it is stricly serialized. The behavior should be the same as the old one. 2. Handle the code for all the exercises separately. Add only the `ziglings step`, making it the default step, in addition to the install and uninstall steps. Setup a new chain starting at the first exercise, to that it is strictly serialized. The behavior should be the same as the old one. The current code has a know issue: the messages from the ZiglingStep and the ones from the compiler compilation progress are interleaved, but each message is written atomically, due to the use of `std.debug.getStderrMutex()`. Update the README.md file. Closes #202
2023-04-06 06:47:08 -04:00
Then run `zig build` and follow the instructions to begin!
2023-04-13 04:41:34 -04:00
```
build: restore the exercise chain The new parallel build support in Zig broke the exercise chain, so that each esercise check is no longer strictly serialized. 1. Add the Dexno option, in order to isolate the chain starting from a named exercise from the normal chain, thus simplify the code. The current code have an additional issue: it added 4 x n steps, making reading the help message or the list of steps very hard. Add only the `install`, `uninstall`, `zigling`, `test` and `start` steps. The last three steps match the old steps `n`, `n_test` and `n_start`. The default step is zigling (note the singular form). The `install` step override the builtin install step, showing a custom description and matches the old `n_install` step. The uninstall step was added for consistency, so that the description is consistent. Setup a new chain starting at `zig build -Dexno=n start` so that it is stricly serialized. The behavior should be the same as the old one. 2. Handle the code for all the exercises separately. Add only the `ziglings step`, making it the default step, in addition to the install and uninstall steps. Setup a new chain starting at the first exercise, to that it is strictly serialized. The behavior should be the same as the old one. The current code has a know issue: the messages from the ZiglingStep and the ones from the compiler compilation progress are interleaved, but each message is written atomically, due to the use of `std.debug.getStderrMutex()`. Update the README.md file. Closes #202
2023-04-06 06:47:08 -04:00
$ zig build
```
Note: The output of Ziglings is the unaltered output from the Zig
compiler. Part of the purpose of Ziglings is to acclimate you to
reading these.
## A Note About Versions
The Zig language is under very active development. In order to be
current, Ziglings tracks **development** builds of the Zig
compiler rather than versioned **release** builds. The last
stable release was `0.10.1`, but Ziglings needs a dev build with
pre-release version "0.11.0" and a build number at least as high
as that shown in the example version check above.
It is likely that you'll download a build which is _greater_ than
the minimum.
_(For those who cannot easily update Zig, there are also
community-supported branches in this repo. At the moment, there's
one for v0.8.1. Older version branches may or may not have all
exercises and/or bugfixes.)_
2021-12-20 14:49:25 -05:00
Once you have a build of the Zig compiler that works with
Ziglings, they'll continue to work together. But keep in mind
that if you update one, you may need to also update the other.
2021-06-30 17:30:01 -04:00
2021-04-21 09:47:16 -04:00
### Version Changes
2022-03-19 19:42:22 -04:00
Version-0.11.0-dev.3295+7cb2e653a
* *2023-05-25* zig 0.11.0-dev.3295 - `std.debug.TTY` is now `std.io.tty`
* *2023-04-30* zig 0.11.0-dev.2704 - use of the new `std.Build.ExecutableOptions.link_libc` field
* *2023-04-12* zig 0.11.0-dev.2560 - changes in `std.Build` - remove run() and install()
2023-04-12 13:32:34 -04:00
* *2023-04-07* zig 0.11.0-dev.2401 - fixes of the new build system - see [#212](https://github.com/ratfactor/ziglings/pull/212)
* *2023-02-21* zig 0.11.0-dev.2157 - changes in `build system` - new: parallel processing of the build steps
2023-02-22 05:22:41 -05:00
* *2023-02-21* zig 0.11.0-dev.1711 - changes in `for loops` - new: Multi-Object For-Loops + Struct-of-Arrays
2023-02-15 13:28:27 -05:00
* *2023-02-12* zig 0.11.0-dev.1638 - changes in `std.Build` cache_root now returns a directory struct
2023-02-04 09:20:54 -05:00
* *2023-02-04* zig 0.11.0-dev.1568 - changes in `std.Build` (combine `std.build` and `std.build.Builder` into `std.Build`)
2023-01-21 08:19:48 -05:00
* *2023-01-14* zig 0.11.0-dev.1302 - changes in `@addWithOverflow` (now returns a tuple) and `@typeInfo`; temporary disabled async functionality
2022-09-10 14:41:40 -04:00
* *2022-09-09* zig 0.10.0-dev.3978 - change in `NativeTargetInfo.detect` in build
* *2022-09-06* zig 0.10.0-dev.3880 - Ex 074 correctly fails again: comptime array len
2022-09-10 14:41:40 -04:00
* *2022-08-29* zig 0.10.0-dev.3685 - `@typeName()` output change, stage1 req. for async
* *2022-07-31* zig 0.10.0-dev.3385 - std lib string `fmt()` option changes
2022-03-19 19:42:22 -04:00
* *2022-03-19* zig 0.10.0-dev.1427 - method for getting sentinel of type changed
* *2021-12-20* zig 0.9.0-dev.2025 - `c_void` is now `anyopaque`
* *2021-06-14* zig 0.9.0-dev.137 - std.build.Id `.Custom` is now `.custom`
* *2021-04-21* zig 0.8.0-dev.1983 - std.fmt.format() `any` format string required
* *2021-02-12* zig 0.8.0-dev.1065 - std.fmt.format() `s` (string) format string required
2021-04-21 09:47:16 -04:00
## Advanced Usage
It can be handy to check just a single exercise or _start_ from a
single exercise:
2023-04-13 04:41:34 -04:00
```
zig build -Dn=19
zig build -Dn=19 start
```
You can also run without checking for correctness:
2023-04-13 04:41:34 -04:00
```
zig build -Dn=19 test
2021-02-11 23:04:36 -05:00
```
Or skip the build system entirely and interact directly with the
compiler if you're into that sort of thing:
2021-02-11 23:04:36 -05:00
2023-04-13 04:41:34 -04:00
```
2021-03-12 19:09:35 -05:00
zig run exercises/001_hello.zig
2021-02-11 23:04:36 -05:00
```
Calling all wizards: To prepare an executable for debugging,
install it to zig-cache/bin with:
2021-02-11 23:04:36 -05:00
2023-04-13 04:41:34 -04:00
```
zig build -Dn=19 install
```
To get a list of all possible options, run:
2023-04-09 13:40:39 -04:00
```
zig build -Dn=19 -l
install Install 019_functions2.zig to prefix path
uninstall Uninstall 019_functions2.zig from prefix path
test Run 019_functions2.zig without checking output
...
2021-02-11 23:04:36 -05:00
```
## What's Covered
The primary goal for Ziglings is to cover the core Zig language.
It would be nice to cover the Standard Library as well, but this
is currently challenging because the stdlib is evolving even
faster than the core language (and that's saying something!).
Not only would stdlib coverage change very rapidly, some
exercises might even cease to be relevant entirely.
Having said that, there are some stdlib features that are
probably here to stay or are so important to understand that they
are worth the extra effort to keep current.
Conspicuously absent from Ziglings are a lot of string
manipulation exercises. This is because Zig itself largely avoids
dealing with strings. Hopefully there will be an obvious way to
address this in the future. The Ziglings crew loves strings!
Zig Core Language
2021-04-30 21:35:56 -04:00
* [x] Hello world (main needs to be public)
* [x] Importing standard library
* [x] Assignment
2021-01-03 20:34:26 -05:00
* [x] Arrays
2021-01-05 19:26:02 -05:00
* [x] Strings
2021-01-08 17:53:22 -05:00
* [x] If
2021-01-10 11:46:42 -05:00
* [x] While
2021-01-18 19:21:18 -05:00
* [x] For
2021-01-22 17:42:03 -05:00
* [x] Functions
* [x] Errors (error/try/catch/if-else-err)
* [x] Defer (and errdefer)
2021-01-31 17:48:34 -05:00
* [x] Switch
* [x] Unreachable
* [x] Enums
* [x] Structs
* [x] Pointers
2021-02-16 20:28:34 -05:00
* [x] Optionals
2021-02-28 13:23:22 -05:00
* [x] Struct methods
2021-03-06 21:31:55 -05:00
* [x] Slices
2021-03-13 16:27:14 -05:00
* [x] Many-item pointers
2021-03-09 20:04:43 -05:00
* [x] Unions
2021-04-10 11:39:11 -04:00
* [x] Numeric types (integers, floats)
* [x] Labelled blocks and loops
* [x] Loops as expressions
2021-04-11 11:22:38 -04:00
* [x] Builtins
2021-04-30 21:35:56 -04:00
* [x] Inline loops
* [x] Comptime
2021-05-06 20:32:36 -04:00
* [x] Sentinel termination
2021-05-09 13:10:09 -04:00
* [x] Quoted identifiers @""
2021-05-09 19:53:14 -04:00
* [x] Anonymous structs/tuples/lists
2023-04-23 19:16:03 -04:00
* [ ] Async <--- ironically awaiting upstream Zig updates
2023-02-16 04:35:15 -05:00
* [X] Interfaces
2023-04-23 19:16:03 -04:00
* [X] Bit manipulation
* [X] Working with C
Zig Standard Library
2023-04-19 15:57:37 -04:00
* [X] String formatting
* [X] Testing
## Contributing
Contributions are very welcome! I'm writing this to teach myself
and to create the learning resource I wished for. There will be
tons of room for improvement:
* Wording of explanations
* Idiomatic usage of Zig
* Additional exercises
Please see [CONTRIBUTING](https://github.com/ratfactor/ziglings/blob/main/CONTRIBUTING.md)
in this repo for the full details.