mirror of
https://codeberg.org/andyscott/ziglings.git
synced 2024-12-22 06:03:09 -05:00
Merge branch 'ratfactor:main' into testing
This commit is contained in:
Chris Boesch
GitHub
commit
1d7452bf96
2 changed files with 92 additions and 67 deletions
101
README.md
101
README.md
|
|
@ -1,13 +1,14 @@
|
|||
# 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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.)
|
||||
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)
|
||||
|
|
@ -17,24 +18,28 @@ 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.
|
||||
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:
|
||||
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!
|
||||
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.)
|
||||
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:
|
||||
|
||||
|
|
@ -56,23 +61,30 @@ Then run `zig build` and follow the instructions to begin!
|
|||
$ 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.
|
||||
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.
|
||||
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.)_
|
||||
_(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.
|
||||
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.
|
||||
|
||||
|
||||
### Version Changes
|
||||
|
|
@ -98,8 +110,8 @@ Version-0.11.0-dev.2704+83970b6d9
|
|||
|
||||
## Advanced Usage
|
||||
|
||||
It can be handy to check just a single exercise or _start_ from a single
|
||||
exercise:
|
||||
It can be handy to check just a single exercise or _start_ from a
|
||||
single exercise:
|
||||
|
||||
```
|
||||
zig build -Dn=19
|
||||
|
|
@ -112,15 +124,15 @@ You can also run without checking for correctness:
|
|||
zig build -Dn=19 test
|
||||
```
|
||||
|
||||
Or skip the build system entirely and interact directly with the compiler
|
||||
if you're into that sort of thing:
|
||||
Or skip the build system entirely and interact directly with the
|
||||
compiler if you're into that sort of thing:
|
||||
|
||||
```
|
||||
zig run exercises/001_hello.zig
|
||||
```
|
||||
|
||||
Calling all wizards: To prepare an executable for debugging, install it
|
||||
to zig-cache/bin with:
|
||||
Calling all wizards: To prepare an executable for debugging,
|
||||
install it to zig-cache/bin with:
|
||||
|
||||
```
|
||||
zig build -Dn=19 install
|
||||
|
|
@ -131,9 +143,9 @@ To get a list of all possible options, run:
|
|||
```
|
||||
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
|
||||
install Install 019_functions2.zig to prefix path
|
||||
uninstall Uninstall 019_functions2.zig from prefix path
|
||||
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
|
||||
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.
|
||||
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.
|
||||
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
|
||||
|
|
@ -199,13 +212,13 @@ Zig Standard Library
|
|||
|
||||
## 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:
|
||||
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.
|
||||
|
||||
|
||||
Please see [CONTRIBUTING](https://github.com/ratfactor/ziglings/blob/main/CONTRIBUTING.md)
|
||||
in this repo for the full details.
|
||||
|
|
|
|||
58
build.zig
58
build.zig
|
|
@ -111,7 +111,6 @@ pub fn build(b: *Build) !void {
|
|||
}
|
||||
|
||||
const logo =
|
||||
\\
|
||||
\\ _ _ _
|
||||
\\ ___(_) __ _| (_)_ __ __ _ ___
|
||||
\\ |_ | |/ _' | | | '_ \ / _' / __|
|
||||
|
|
@ -119,6 +118,8 @@ pub fn build(b: *Build) !void {
|
|||
\\ /___|_|\__, |_|_|_| |_|\__, |___/
|
||||
\\ |___/ |___/
|
||||
\\
|
||||
\\ "Look out! Broken programs below!"
|
||||
\\
|
||||
\\
|
||||
;
|
||||
|
||||
|
|
@ -259,18 +260,24 @@ const ZiglingStep = struct {
|
|||
|
||||
const exe_path = self.compile(prog_node) catch {
|
||||
if (self.exercise.hint) |hint|
|
||||
print("\n{s}HINT: {s}{s}", .{ bold_text, hint, reset_text });
|
||||
print("\n{s}Ziglings hint: {s}{s}", .{ bold_text, hint, reset_text });
|
||||
|
||||
self.help();
|
||||
std.os.exit(1);
|
||||
|
||||
// NOTE: Returning 0 'success' status because the *exercise* failed,
|
||||
// but Ziglings did not. Otherwise the learner will see this message:
|
||||
// "error: the following build command failed with exit code 1:..."
|
||||
std.os.exit(0);
|
||||
};
|
||||
|
||||
self.run(exe_path, prog_node) catch {
|
||||
if (self.exercise.hint) |hint|
|
||||
print("\n{s}HINT: {s}{s}", .{ bold_text, hint, reset_text });
|
||||
print("\n{s}Ziglings hint: {s}{s}", .{ bold_text, hint, reset_text });
|
||||
|
||||
self.help();
|
||||
std.os.exit(1);
|
||||
|
||||
// NOTE: See note above!
|
||||
std.os.exit(0);
|
||||
};
|
||||
}
|
||||
|
||||
|
|
@ -397,11 +404,12 @@ const ZiglingStep = struct {
|
|||
print("\n", .{});
|
||||
},
|
||||
error.ZigIPCError => {
|
||||
print("{s}{s}: The following command failed to communicate the compilation result:{s}\n", .{
|
||||
red_text, self.exercise.main_file, reset_text,
|
||||
});
|
||||
for (argv) |v| print("{s} ", .{v});
|
||||
print("\n", .{});
|
||||
// Commenting this out for now. It always shows up when compilation fails.
|
||||
//print("{s}{s}: The following command failed to communicate the compilation result:{s}\n", .{
|
||||
// red_text, self.exercise.main_file, reset_text,
|
||||
//});
|
||||
//for (argv) |v| print("{s} ", .{v});
|
||||
//print("\n", .{});
|
||||
},
|
||||
else => {
|
||||
print("{s}{s}: Unexpected error: {s}{s}\n", .{
|
||||
|
|
@ -521,20 +529,22 @@ const ZiglingStep = struct {
|
|||
|
||||
fn help(self: *ZiglingStep) void {
|
||||
const path = self.exercise.main_file;
|
||||
const key = self.exercise.key();
|
||||
|
||||
print("\n{s}Edit exercises/{s} and run 'zig build' again.{s}\n", .{
|
||||
red_text, path, reset_text,
|
||||
});
|
||||
|
||||
const format =
|
||||
\\
|
||||
\\{s}To compile only this exercise, you can also use this command:{s}
|
||||
\\{s}zig build -Dn={s}{s}
|
||||
\\
|
||||
\\
|
||||
;
|
||||
print(format, .{ red_text, reset_text, bold_text, key, reset_text });
|
||||
// NOTE: The README explains this "advanced feature" if anyone wishes to use
|
||||
// it. Otherwise, beginners are thinking they *have* to do this.
|
||||
//const key = self.exercise.key();
|
||||
//const format =
|
||||
// \\
|
||||
// \\{s}To compile only this exercise, you can also use this command:{s}
|
||||
// \\{s}zig build -Dn={s}{s}
|
||||
// \\
|
||||
// \\
|
||||
//;
|
||||
//print(format, .{ red_text, reset_text, bold_text, key, reset_text });
|
||||
}
|
||||
|
||||
fn printErrors(self: *ZiglingStep) void {
|
||||
|
|
@ -691,10 +701,12 @@ const exercises = [_]Exercise{
|
|||
.output = "Hello world!",
|
||||
.hint =
|
||||
\\DON'T PANIC!
|
||||
\\Read the error above.
|
||||
\\See how it has something to do with 'main'?
|
||||
\\Open up the source file as noted and read the comments.
|
||||
\\You can do this!
|
||||
\\Read the compiler messages above. (Something about 'main'?)
|
||||
\\Open up the source file as noted below and read the comments.
|
||||
\\
|
||||
\\(Hints like these will occasionally show up, but for the
|
||||
\\most part, you'll be taking directions from the Zig
|
||||
\\compiler itself.)
|
||||
\\
|
||||
,
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in a new issue