ziglings/README.md

185 lines
5.8 KiB
Markdown
Raw Normal View History

# Ziglings
Welcome to Ziglings! This project contains a series of tiny broken programs.
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 tiny 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
2021-02-06 15:54:56 -05:00
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/
2021-03-10 14:47:23 -05:00
Also, the [Zig community](https://github.com/ziglang/zig/wiki/Community) is incredibly friendly and helpful!
## 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:
```bash
$ zig version
2023-02-21 15:55:32 -05:00
0.11.0-dev.1711+xxxxxxxxx
```
Clone this repository with Git:
```bash
$ git clone https://github.com/ratfactor/ziglings
$ cd ziglings
```
2021-02-11 23:04:36 -05:00
Then run `zig build` and follow the instructions to begin!
```bash
$ zig build
```
## 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
2023-01-31 18:04:50 -05:00
versioned **release** builds. The last stable release was `0.10.1`, but Ziglings
2023-01-14 06:56:52 -05:00
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.
2021-12-20 14:49:25 -05:00
_(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.)_
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
Also note that the current "stage 1" Zig compiler is very strict
about input:
2021-06-30 17:33:38 -04:00
[no tab characters or Windows CR/LF newlines are allowed](https://github.com/ziglang/zig/issues/544).
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
2023-02-21 15:55:32 -05:00
Version-0.11.0-dev.1711+xxxxxxxxx
* *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:
```bash
zig build 19
zig build 19_start
```
You can also run without checking for correctness:
2021-02-11 23:04:36 -05:00
```bash
2021-03-12 19:09:35 -05:00
zig build 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
```bash
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
```bash
2021-03-12 19:09:35 -05:00
zig build 19_install
2021-02-11 23:04:36 -05:00
```
## What's Covered
I've decide to limit Ziglings to the core language and not
attempt coverage of the Standard Library. Perhaps you can change
my mind?
2021-04-30 21:35:56 -04:00
Core Language
* [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
* [ ] Async <--- IN PROGRESS!
2023-02-16 04:35:15 -05:00
* [X] Interfaces
2023-02-16 13:44:35 -05:00
* [X] Working with C
2023-02-19 15:59:52 -05:00
* [ ] String formatting
## 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
* Maybe additional exercises?
Please see CONTRIBUTING.md in this repo for the full details.