Merge branch 'ratfactor:main' into testing

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.
 
 ![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.)
+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.

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.)
         \\
         ,
     },