diff --git a/docs/ABOUT.md b/docs/ABOUT.md index 01358614..05789b5f 100644 --- a/docs/ABOUT.md +++ b/docs/ABOUT.md @@ -1,24 +1,25 @@ # About -Zig is a general-purpose programming language equipped with well-rounded toolchains that aims to be simple and familiar, yet disparate from what programmers rely on today. -Its main attributes involve helping programmers to develop **robust**, **optimal**, and **reusable** software. -All the while, Zig aims to remedy the design problems of older languages with features that promote safety through the use of [optionals][optionals], a unique take on [error handling][error-handling], and [compile-time execution][compile-time]. +Zig is a general-purpose programming language and toolchain, which aims to help produce **robust**, **optimal**, and **reusable** software. -From the ground up, Zig was designed to be competitive with other systems programming languages and not be reliant on them. -With bold claims such as, "Zig is faster than C" featured on its home page, being independent from other languages is a major design philosophy that it champions. +It does this by striving for simplicity: there's no hidden control flow, no hidden memory allocations, and no macros. +However, there's still a modern design: a powerful type system with sum types and [optionals][optionals], explicit [error handling][error-handling], and [compile-time execution][compile-time]. -Zig has a lot of faculties that really makes it double down on its notion of independence. -The standard library that Zig provides harbors many common functions that perform fast to ensure that a reliance on FFI and external libraries is not essential. -Zig also provides a well-rounded [build system][build-system] so that Zig is not dependent on alternative build tools, such as make, cmake, or ninja. +Zig tries to be a DSL for emitting optimal machine code. -The home page for Zig is [ziglang.org][ziglang.org]. -Zig provides a complete summary of the language's current features, grammars, and philosophies at [ziglang.org/documentation/master/][ziglang.org/docs]. -It's highly recommended that newcomers use a mix of the documentation and other [community resources][zig-community] to learn Zig in a well-rounded fashion. +For more information, see [ziglang.org][ziglang.org]. + +//Zig provides a complete summary of the language's current features, grammar, and philosophy in the [Zig Language Reference][langref]. +//It's highly recommended that newcomers use a mix of the documentation and other [community resources][zig-community] to learn Zig in a well-rounded fashion. + +// Compatibility with C is as good as it gets: Zig ships with C compiler toolchains, so you can just import a C header file and call functions. +// Zig also provides a [build system][build-system] so that Zig isn't dependent on alternative build tools, such as make, cmake, or ninja. +// And Zig is excellent at cross compilation. [build-system]: https://ziglang.org/learn/overview/#zig-build-system [compile-time]: https://ziglang.org/learn/overview/#compile-time-reflection-and-compile-time-code-execution [error-handling]: https://ziglang.org/learn/overview/#a-fresh-take-on-error-handling +[langref]: https://ziglang.org/documentation/0.12.0/ [optionals]: https://ziglang.org/learn/overview/#optional-type-instead-of-null-pointers [ziglang.org]: https://ziglang.org/ -[ziglang.org/docs]: https://ziglang.org/documentation/master/ [zig-community]: https://github.com/ziglang/zig/wiki/Community diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 0d842e91..bb64c790 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,51 +1,42 @@ # Installation -There are many ways to install Zig, and the number of ways to install Zig are steadily increasing as the language matures. -Fortunately, all of the popular installation methods are listed on the [Zig install page][install-zig]. +You can download Zig from the [Releases][zig-download] page, or [using a package manager][package-manager]. -## Zig version +## Supported Zig version Exercism currently supports Zig 0.12.0 (released on 2024-04-20) only. An exercise may be compatible with a different Zig version, but that isn't guaranteed. -Zig has not yet reached version 1.0, and breaking changes are common. +Zig hasn't yet reached version 1.0, and breaking changes are common. -## Additional utilities +## The Zig Language Server - comprehensive editor support for Zig -### Zig fmt - Generating well-formatted code +This third-party software provides editor completions and enhanced Zig code navigation features, which can help you learn the language faster. -When completing any exercise, you may use all kinds of code styles for your solutions. -However, outside of solving exercises, such as making applications or libraries, it's typically a good idea to make your code consistent and readable. -Those assumption are especially important when others who would want to help out with your projects would have to read your code. +You can install ZLS [here][zls-install]. -To fix this problem the Zig compiler comes with a built-in lightweight [linter][linters] to format your code in a convenient manner. -This code formatter aims to follow the [style guide][style-guide] already established by the [Zig documentation][documentation]. +## Other commands -To see the features of Zig's native formatter use the following command: +### `zig fmt` + +The Zig executable contains a code formatter. +To format `file.zig`, run: ```bash -zig fmt --help +zig fmt file.zig ``` -### Zig Zen - Rules to code by +For more details on the suggested code style, see the [Zig Style Guide][style-guide]. -Sometimes some direction goes a long way when completing any task, even when writing code. -Thankfully we have a fun command built right into the Zig compiler to remind ourselves of some of the goals that go into writing good Zig code. +### `zig zen` -To check out these words of wisdom you can use the following command: +The Zig executable has a command to remind us of Zig's design goals: ```bash zig zen ``` -### The Zig Language Server - Comprehensive editor support for Zig - -This third-party software provides editor completions and enhanced Zig code navigation features which can help you learn the language faster. - -You can install ZLS [here][install-zls]. - -[documentation]: https://ziglang.org/documentation/master/ -[install-zig]: https://ziglang.org/download/ -[linters]: https://en.wikipedia.org/wiki/Lint_(software) -[style-guide]: https://ziglang.org/documentation/master/#Style-Guide -[install-zls]: https://install.zigtools.org/ +[package-manager]: https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager +[style-guide]: https://ziglang.org/documentation/0.12.0/#Style-Guide +[zig-download]: https://ziglang.org/download/ +[zls-install]: https://install.zigtools.org/ diff --git a/docs/LEARNING.md b/docs/LEARNING.md index 049af56a..d073b4b4 100644 --- a/docs/LEARNING.md +++ b/docs/LEARNING.md @@ -1,15 +1,15 @@ # Learning -- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it. -- [Awesome Zig][awesome-zig] is a good collection of Zig projects made by various people. - The collection features projects involving well developed Zig code. -- [Zighelp][zighelp] is an excellent primer that explains the language features that Zig has to offer. -- [Ziglings][ziglings] is highly recommended. - Learn Zig by fixing tiny broken programs. +- [Ziglings][ziglings] is a highly recommended introduction to Zig, which asks you to fix tiny broken programs. +- [zig.guide][zig-guide] is another great introduction to Zig. +- [The Zig Language Reference][langref] is the main reference documentation. +- [Learning Zig][learning-zig] is another great introduction to Zig. +- [Awesome Zig][awesome-zig] is a collection of Zig projects. - [Zig SHOWTIME][zig-showtime] is a livestreamed show where members of the Zig community share code and ideas. [awesome-zig]: https://github.com/catdevnull/awesome-zig -[documentation]: https://ziglang.org/documentation/master/ -[zighelp]: https://zighelp.org/ +[langref]: https://ziglang.org/documentation/0.12.0/ +[learning-zig]: https://www.openmymind.net/learning_zig/ [zig-showtime]: https://zig.show/ +[zig-guide]: https://zig.guide/ [ziglings]: https://github.com/ratfactor/ziglings diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index 0e378844..e2b024dc 100644 --- a/docs/RESOURCES.md +++ b/docs/RESOURCES.md @@ -1,21 +1,24 @@ # Resources -- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it. -- [The Zig Standard Library][std] is a good reference to learn how Zig code is written and shows many of the functions that you could import into your own code. -- [Awesome Zig][awesome-zig] is a curated list of Zig projects. +- [The Zig Language Reference][langref] is the main reference documentation. +- [The Zig Standard Library][std] is one of the best places to read good Zig code. +- [The Zig Programming Language Discord][discord-zig] is the main Zig [Discord][discord]. + It provides a great way to get in touch with the Zig community, and get some quick, direct help for any Zig-related problem. - [#zig][irc] on irc.freenode.net is the main Zig IRC channel. -- [Stack Overflow][stack-overflow] can be used to discover code snippets and solutions to problems that may have already asked and maybe solved by others. -- [/r/Zig][reddit] is the main Zig subreddit. -- [The Zig Programming Language Discord][discord-zig] is the main [Discord][discord]. - It provides a great way to get in touch with the Zig community at large, and get some quick, direct help for any Zig related problem. +- [Awesome Zig][awesome-zig] is a curated list of Zig projects. - [The Zig SHOWTIME Newsletter][newsletter] announces new episodes, important events, and links to interesting new Zig projects. +- [Ziggit][ziggit] is the main Zig forum. +- [/r/Zig][reddit] is the main Zig subreddit. + +For a longer list of community spaces, see the [Community wiki page][community]. [awesome-zig]: https://github.com/catdevnull/awesome-zig +[community]: https://github.com/ziglang/zig/wiki/Community [discord]: https://discordapp.com [discord-zig]: https://discord.com/invite/gxsFFjE -[documentation]: https://ziglang.org/documentation/master [irc]: https://webchat.freenode.net/?channels=%23zig +[langref]: https://ziglang.org/documentation/0.12.0/ [newsletter]: https://zig.show/ [reddit]: https://www.reddit.com/r/Zig -[stack-overflow]: https://stackoverflow.com/questions/tagged/zig -[std]: https://github.com/ziglang/zig/tree/master/lib/std +[std]: https://github.com/ziglang/zig/tree/0.12.0/lib/std +[ziggit]: https://ziggit.dev/ diff --git a/docs/TESTS.md b/docs/TESTS.md index f5cc066d..da4c67db 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -1,31 +1,26 @@ -# Writing the Code +# Writing your solution -Write your code in `.zig`. -Some exercises come with prewritten signatures for specific Zig constructs, such as [constants][constants], [functions][functions], [imports][imports], [structs][structs], and [potentially many more][et-cetera]! +Write your solution in `.zig`. +Exercism provides a solution skeleton there for each exercise. -These prewritten signatures are meant to help you towards completing exercises by providing a clear starting point. -However, starting from these signatures is not necessary. -Especially when any written code which passes their tests are perfectly acceptable solutions. +We intend each skeleton to provide a clear starting point, but you don't need to use everything from it. +In general, any solution that passes every test is valid. -## Running Tests +However, we recommend continuing after you've got the tests to pass. +Try to refactor, and turn your solution into beautiful idiomatic Zig! -To run the tests, all you need to do is run the following command: +## Running the tests + +To test your solution, run the below command in the exercise's root directory: ```bash zig test test_exercise_name.zig ``` replacing `exercise_name` with the name of the exercise. -The command above has to be run in the exercise's root directory since its test file should be in the same spot. -Additionally, all of the tests for any given exercise are enabled by default, and none of the tests are skippable. - -Since all tests have these stipulations, you would have to [comment out][comments] tests that are not passing if you wish to go through each test one by one. -Commenting out a test is as simple as starting each line with a `//`. -Otherwise, when you're confident that your solution can pass the tests, you can un-comment those tests to see if it passes. - -[constants]: https://ziglang.org/documentation/master/#Assignment -[comments]: https://ziglang.org/documentation/master/#Comments -[functions]: https://ziglang.org/documentation/master/#Functions -[et-cetera]: https://ziglang.org/documentation/master/ -[imports]: https://ziglang.org/documentation/master/#import -[structs]: https://ziglang.org/documentation/master/#struct + +By default, the test file enables every test. +That is, no test is currently skipped by default. +To go through tests one at a time, you can [comment out][comments] tests by adding `//` to the start of a line + +[comments]: https://ziglang.org/documentation/0.12.0/#Comments diff --git a/exercises/practice/anagram/.docs/instructions.append.md b/exercises/practice/anagram/.docs/instructions.append.md index b626395c..72931a17 100644 --- a/exercises/practice/anagram/.docs/instructions.append.md +++ b/exercises/practice/anagram/.docs/instructions.append.md @@ -10,9 +10,9 @@ The `BufSet` does that itself. For more details on hash maps in Zig, see: - [Hexops - Zig hashmaps explained][zig-hashmaps-explained] -- [Zighelp - Hash Maps][zighelp] +- [zig.guide - Hash Maps][zig-guide-hashmaps] - [Zig Standard Library - `buf_set.zig`][buf-set] [buf-set]: https://github.com/ziglang/zig/blob/0.12.0/lib/std/buf_set.zig [zig-hashmaps-explained]: https://devlog.hexops.com/2022/zig-hashmaps-explained/ -[zighelp]: https://zighelp.org/chapter-2/#hash-maps +[zig-guide-hashmaps]: https://zig.guide/standard-library/hashmaps diff --git a/exercises/practice/collatz-conjecture/.docs/instructions.append.md b/exercises/practice/collatz-conjecture/.docs/instructions.append.md index c0f82942..69af882d 100644 --- a/exercises/practice/collatz-conjecture/.docs/instructions.append.md +++ b/exercises/practice/collatz-conjecture/.docs/instructions.append.md @@ -13,8 +13,8 @@ For more details about errors in Zig, see: - [Learning Zig - Errors][learning-zig-errors] - [Ziglings - Exercise 21][ziglings-exercise-21] -- [Zighelp - Errors][zighelp-errors] +- [zig.guide - Errors][zig-guide-errors] [learning-zig-errors]: https://www.openmymind.net/learning_zig/language_overview_2/#errors -[zighelp-errors]: https://zighelp.org/chapter-1/#errors +[zig-guide-errors]: https://zig.guide/language-basics/errors [ziglings-exercise-21]: https://codeberg.org/ziglings/exercises/src/commit/0d46acfa02d0c29fdfb3651e82a77284dd8f2e00/exercises/021_errors.zig diff --git a/exercises/shared/.docs/help.md b/exercises/shared/.docs/help.md index 56830f49..b81f2981 100644 --- a/exercises/shared/.docs/help.md +++ b/exercises/shared/.docs/help.md @@ -1,20 +1,21 @@ # Help -- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it. -- [Zig Learn][zig-learn] is an excellent primer that explains the language features that Zig has to offer. -- [Ziglings][ziglings] is highly recommended. - Learn Zig by fixing tiny broken programs. -- [The Zig Programming Language Discord][discord-zig] is the main [Discord][discord]. - It provides a great way to get in touch with the Zig community at large, and get some quick, direct help for any Zig related problem. +- [The Zig Programming Language Discord][discord-zig] is the main Zig [Discord][discord]. + It provides a great way to get in touch with the Zig community, and get some quick, direct help for any Zig-related problem. - [#zig][irc] on irc.freenode.net is the main Zig IRC channel. -- [/r/Zig][reddit] is the main Zig subreddit. -- [Stack Overflow][stack-overflow] can be used to discover code snippets and solutions to problems that may have already asked and maybe solved by others. +- [Ziggit][ziggit] is the main Zig forum. +- [/r/Zig][sureddit] is the main Zig subreddit. +- [Ziglings][ziglings] is a highly recommended introduction to Zig, which asks you to fix tiny broken programs. +- [zig.guide][zig-guide] is a great introduction to Zig. +- [Learning Zig][learning-zig] is another great introduction to Zig. +- [The Zig Language Reference][langref] is the main reference documentation. [discord]: https://discordapp.com [discord-zig]: https://discord.com/invite/gxsFFjE -[documentation]: https://ziglang.org/documentation/master [irc]: https://webchat.freenode.net/?channels=%23zig -[reddit]: https://www.reddit.com/r/Zig -[stack-overflow]: https://stackoverflow.com/questions/tagged/zig -[zig-learn]: https://ziglearn.org/ +[langref]: https://ziglang.org/documentation/0.12.0/ +[learning-zig]: https://www.openmymind.net/learning_zig/ +[sureddit]: https://www.reddit.com/r/Zig +[ziggit]: https://ziggit.dev/ +[zig-guide]: https://zig.guide/ [ziglings]: https://github.com/ratfactor/ziglings