@ -1,13 +1,14 @@
# Ziglings
# Ziglings
Welcome to Ziglings! This project contains a series of tiny broken programs (and one nasty surprise).
Welcome to Ziglings! This project contains a series of tiny
By fixing them, you'll learn how to read and write [Zig ](https://ziglang.org/ ) code.
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 )
![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
Those broken programs need your help! (You'll also save the
evil aliens and help some friendly elephants stick together, which is very
planet from evil aliens and help some friendly elephants stick
sweet of you.)
together, which is very sweet of you.)
This project was directly inspired by the brilliant and fun
This project was directly inspired by the brilliant and fun
[rustlings ](https://github.com/rust-lang/rustlings )
[rustlings ](https://github.com/rust-lang/rustlings )
@ -17,24 +18,28 @@ and the Little LISPer/Little Schemer series of books.
## Intended Audience
## Intended Audience
This will probably be difficult if you've _never_ programmed before.
This will probably be difficult if you've _never_ programmed
But no specific programming experience is required. And in particular,
before. But no specific programming experience is required. And
you are _not_ expected to have any prior experience with "systems programming"
in particular, you are _not_ expected to have any prior
or a "systems" level language such as C.
experience with "systems programming" or a "systems" level
language such as C.
Each exercise is self-contained and self-explained. However, you're encouraged
Each exercise is self-contained and self-explained. However,
to also check out these Zig language resources for more detail:
you're encouraged to also check out these Zig language resources
for more detail:
* https://ziglang.org/learn/
* https://ziglang.org/learn/
* https://ziglearn.org/
* https://ziglearn.org/
* https://ziglang.org/documentation/master/
* https://ziglang.org/documentation/master/
Also, the [Zig community ](https://github.com/ziglang/zig/wiki/Community ) is incredibly friendly and helpful!
Also, the [Zig community ](https://github.com/ziglang/zig/wiki/Community )
is incredibly friendly and helpful!
## Getting Started
## Getting Started
Install a [development build ](https://ziglang.org/download/ ) of the Zig compiler.
Install a [development build ](https://ziglang.org/download/ ) of
(See the "master" section of the downloads page.)
the Zig compiler. (See the "master" section of the downloads
page.)
Verify the installation and build number of `zig` like so:
Verify the installation and build number of `zig` like so:
@ -56,23 +61,30 @@ Then run `zig build` and follow the instructions to begin!
$ zig build
$ 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
## A Note About Versions
The Zig language is under very active development. In order to be current,
The Zig language is under very active development. In order to be
Ziglings tracks **development** builds of the Zig compiler rather than
current, Ziglings tracks **development** builds of the Zig
versioned **release** builds. The last stable release was `0.10.1` , but Ziglings
compiler rather than versioned **release** builds. The last
needs a dev build with pre-release version "0.11.0" and a build number at least
stable release was `0.10.1` , but Ziglings needs a dev build with
as high as that shown in the example version check above.
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.
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
_(For those who cannot easily update Zig, there are also
branches in this repo. At the moment, there's one for v0.8.1. Older version
community-supported branches in this repo. At the moment, there's
branches may or may not have all exercises and/or bugfixes.)_
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
Once you have a build of the Zig compiler that works with
continue to work together. But keep in mind that if you update one, you may
Ziglings, they'll continue to work together. But keep in mind
need to also update the other.
that if you update one, you may need to also update the other.
### Version Changes
### Version Changes
@ -98,8 +110,8 @@ Version-0.11.0-dev.2704+83970b6d9
## Advanced Usage
## Advanced Usage
It can be handy to check just a single exercise or _start_ from a single
It can be handy to check just a single exercise or _start_ from a
exercise:
single exercise:
```
```
zig build -Dn=19
zig build -Dn=19
@ -112,15 +124,15 @@ You can also run without checking for correctness:
zig build -Dn=19 test
zig build -Dn=19 test
```
```
Or skip the build system entirely and interact directly with the compiler
Or skip the build system entirely and interact directly with the
if you're into that sort of thing:
compiler if you're into that sort of thing:
```
```
zig run exercises/001_hello.zig
zig run exercises/001_hello.zig
```
```
Calling all wizards: To prepare an executable for debugging, install it
Calling all wizards: To prepare an executable for debugging,
to zig-cache/bin with:
install it to zig-cache/bin with:
```
```
zig build -Dn=19 install
zig build -Dn=19 install
@ -131,9 +143,9 @@ To get a list of all possible options, run:
```
```
zig build -Dn=19 -l
zig build -Dn=19 -l
install Install 019_functions2.zig to prefix path
install Install 019_functions2.zig to prefix path
uninstall Uninstall 019_functions2.zig from prefix path
uninstall Uninstall 019_functions2.zig from prefix path
test Run 019_functions2.zig without checking output
test Run 019_functions2.zig without checking output
...
...
```
```
@ -144,11 +156,12 @@ 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
It would be nice to cover the Standard Library as well, but this
is currently challenging because the stdlib is evolving even
is currently challenging because the stdlib is evolving even
faster than the core language (and that's saying something!).
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.
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
Having said that, there are some stdlib features that are
to stay or are so important to understand that they are worth the
probably here to stay or are so important to understand that they
extra effort to keep current.
are worth the extra effort to keep current.
Conspicuously absent from Ziglings are a lot of string
Conspicuously absent from Ziglings are a lot of string
manipulation exercises. This is because Zig itself largely avoids
manipulation exercises. This is because Zig itself largely avoids
@ -199,13 +212,13 @@ Zig Standard Library
## Contributing
## Contributing
Contributions are very welcome! I'm writing this to teach myself and to create
Contributions are very welcome! I'm writing this to teach myself
the learning resource I wished for. There will be tons of room for improvement:
and to create the learning resource I wished for. There will be
tons of room for improvement:
* Wording of explanations
* Wording of explanations
* Idiomatic usage of Zig
* Idiomatic usage of Zig
* Additional exercises
* Additional exercises
Please see [CONTRIBUTING ](https://github.com/ratfactor/ziglings/blob/main/CONTRIBUTING.md ) in this repo for the full details.
Please see [CONTRIBUTING ](https://github.com/ratfactor/ziglings/blob/main/CONTRIBUTING.md )
in this repo for the full details.