diff --git a/build.zig b/build.zig index 7fafaec64..15c8ec21d 100644 --- a/build.zig +++ b/build.zig @@ -214,6 +214,12 @@ pub fn build(b: *std.Build) void { .site_title = "Zig 编程语言", .content_dir_path = "content/zh-CN", }, + .{ + .code = "pl-PL", + .name = "Polski", + .site_title = "Język programowania Zig", + .content_dir_path = "content/pl-PL", + }, }, }); } diff --git a/content/pl-PL/download.smd b/content/pl-PL/download.smd new file mode 100644 index 000000000..4f2ab7cf0 --- /dev/null +++ b/content/pl-PL/download.smd @@ -0,0 +1,20 @@ +--- +.title = "Do pobrania", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "download.shtml", +.custom = { + "mobile_menu_title": "Do pobrania", + "OSs": ["Windows", "macOS", "Linux", "FreeBSD"], +}, +--- +# Wydania +Mozesz [zainstalować Ziga za pomocą menedżera pakietów](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager) (ang.). + +Istnieje [wersja tej strony w JSONie]($link.siteAsset('download/index.json')). + +Pliki są podpisywane za pomocą [minisign](https://jedisct1.github.io/minisign/) przy użyciu tego klucza publicznego: + +``` +RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U +``` diff --git a/content/pl-PL/index.smd b/content/pl-PL/index.smd new file mode 100644 index 000000000..590a7befb --- /dev/null +++ b/content/pl-PL/index.smd @@ -0,0 +1,64 @@ +--- +.title = "Strona główna", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "index.shtml", +.custom = { + "mobile_menu_title": "Strona główna", +}, +--- + +[]($section.id("slogan")) +Zig to język programowania ogólnego przeznaczenia i zestaw narzędzi do utrzymywania **solidnego**, **zoptymalizowanego**, **zdatnego do ponownego użycia** oprogramowania + +[]($section.id("features")) +## ⚡ Prosty język +Skup się raczej na odpluskwianiu Twojej aplikacji niż Twojej wiedzy o języku programowania. + +- Bez ukrytego przepływu sterowania +- Bez ukrytych alokacji +- Bez preprocesora, bez makr + +## ⚡ Comptime +Świeże podejście do metaprogramowania oparte o kod wykonywany w czasie kompilacji i leniwe obliczenia. + +- Możesz wywołać dowolną funkcję w czasie kompilacji +- Możesz operować na typach danych jako wartościach bez narzutu środowiska uruchomieniowego +- Comptime emuluje architekturę docelową + +## ⚡ Utrzymuj kod z Zigiem +Stopniowo ulepszaj Twój kod w C/C++/Zigu + +- Używaj Ziga jako gotowy zamiennkik kompilatora C/C++ – bez dodatkowych zależności, ze wsparciem dla kompilacji skrośnej +- Wykorzystaj `zig build` by stworzyć jednolite środowisko rozwoju na wszystkich platformach +- Dodaj jednostkę kompilacji Ziga do projektu w C/C++ i używaj bogatej biblioteki standardowej w Twoim kodzie + + +# [Społeczność]($section.id("community").attrs("section-title")) + +## [Społeczność Ziga jest zdecentralizowana]($section.id("decentralized")) +Każdy może stworzyć i utrzymywać przestrzeń dostępną dla społeczności. +Nie istnieją "oficjalne" bądź "nieoficjalne" kanały społeczności, jednakże każda przestrzeń ma swoje zasady i swoich moderatorów + + +## [Main development]($section.id("main-development")) +Repozytorium Ziga znajduje się pod adresem [https://github.com/ziglang/zig](https://github.com/ziglang/zig). W tym samym miejscu utrzymujemy system śledzenia zgłoszeń i omawiamy propozycje. +Oczekuje się, że współpracownicy będą przestrzegać [Kodeksu postępowania Zig](https://github.com/ziglang/zig/blob/master/.github/CODE_OF_CONDUCT.md). + + +# [Zig Software Foundation (Fundacja Zig Software)]($section.id("zsf").attrs("section-title")) + +## ZSF jest organizacją typu non-profit (501(c)(3)). + +Zig Software Foundation (Fundacja Zig Software) to organizacja typu non-profit założona w 2020 roku przez Andrew Kelleya, twórcę języka Zig. Celem Fundacji jest wspieranie rozwoju języka. Obecnie, ZSF stać na opłacenie po rynkowych stawkach wyłącznie niewielkiej liczby głównych współpracowników. Mamy nadzieję, że w przyszłości będziemy mogli rozszerzyć tę ofertę na większą liczbę głównych współpracowników. + +Fundacja utrzymuje się dzięki darowiznom. + +# [Sponsorzy]($section.id("sponsors").attrs("section-title")) + +## [Sponsorzy biznesowi]($section.id("corporate-sponsors")) +Bezpośrednie wsparcie finansowe fundacji Zig Software zapewniają następujące przedsiębiorstwa: + +## [Wspierający na GitHubie]($section.id("github-sponsors")) +Dzięki ludziom, którzy [sponsorują Ziga]($link.page('zsf')), projekt odpowiada przed społecznością open source, a nie przed udziałowcami biznesowymi. W szczególności, ci wspaniali ludzie wspierają Ziga kwotą co najmniej 200 USD miesięcznie: + diff --git a/content/pl-PL/learn/build-system.smd b/content/pl-PL/learn/build-system.smd new file mode 100644 index 000000000..dd6270ba7 --- /dev/null +++ b/content/pl-PL/learn/build-system.smd @@ -0,0 +1,470 @@ +--- +.title = "Zig Build System", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Zig Build System", + "toc": true, +}, +--- +# [When to bust out the Zig Build System?]($heading.id('build-system')) + +The fundamental commands `zig build-exe`, `zig build-lib`, `zig build-obj`, and +`zig test` are often sufficient. However, sometimes a project needs another +layer of abstraction to manage the complexity of building from source. + +For example, perhaps one of these situations applies: + +- The command line becomes too long and unwieldly, and you want some place to + write it down. +- You want to build many things, or the build process contains many steps. +- You want to take advantage of concurrency and caching to reduce build time. +- You want to expose configuration options for the project. +- The build process is different depending on the target system and other options. +- You have dependencies on other projects. +- You want to avoid an unnecessary dependency on cmake, make, shell, msvc, + python, etc., making the project accessible to more contributors. +- You want to provide a package to be consumed by third parties. +- You want to provide a standardized way for tools such as IDEs to semantically understand + how to build the project. + +If any of these apply, the project will benefit from using the Zig Build System. + +# [Getting Started]($heading.id('getting-started')) +## [Simple Executable]($heading.id('simple')) +This build script creates an executable from a Zig file that contains a public `main` function definition. + +[]($code.language('=html').buildAsset("build-system/1-simple-executable/hello.zig")) +[]($code.language('=html').buildAsset("build-system/1-simple-executable/build.zig")) + +## [Installing Build Artifacts]($heading.id('installing-artifacts')) + +The Zig build system, like most build systems, is based on modeling the project as a directed acyclic graph (DAG) of steps, which are independently and concurrently run. + +By default, the main step in the graph is the **Install** step, whose purpose +is to copy build artifacts into their final resting place. The Install step +starts with no dependencies, and therefore nothing will happen when `zig build` +is run. A project's build script must add to the set of things to install, which +is what the `installArtifact` function call does above. + +**Output** +``` +├── build.zig +├── hello.zig +├── .zig-cache +└── zig-out + └── bin + └── hello +``` + +There are two generated directories in this output: `.zig-cache` and `zig-out`. The first one contains files that will make subsequent builds faster, but these files are not intended to be checked into source-control and this directory can be completely deleted at any time with no consequences. + +The second one, `zig-out`, is an "installation prefix". This maps to the standard file system hierarchy concept. This directory is not chosen by the project, but by the user of `zig build` with the `--prefix` flag (`-p` for short). + +You, as the project maintainer, pick what gets put in this directory, but the user chooses where to install it in their system. The build script cannot hardcode output paths because this would break caching, concurrency, and composability, as well as annoy the final user. + +## [Adding a Convenience Step for Running the Application]($heading.id('run-step')) + +It is common to add a **Run** step to provide a way to run one's main application directly +from the build command. + +[]($code.language('=html').buildAsset("build-system/convenience-run-step/hello.zig")) +[]($code.language('=html').buildAsset("build-system/convenience-run-step/build.zig")) + +# [The Basics]($heading.id('basics')) + +## [User-Provided Options]($heading.id('user-options')) + +Use `b.option` to make the build script configurable to end users as well as +other projects that depend on the project as a package. + +[]($code.language('=html').buildAsset("build-system/2-user-provided-options/build.zig")) +[]($code.language('=html').buildAsset("build-system/2-user-provided-options/example.zig")) + +Please direct your attention to these lines: + +``` +Project-Specific Options: + -Dwindows=[bool] Target Microsoft Windows +``` + +This part of the help menu is auto-generated based on running the `build.zig` logic. Users +can discover configuration options of the build script this way. + +## [Standard Configuration Options]($heading.id('standard-options')) + +Previously, we used a boolean flag to indicate building for Windows. However, we can do +better. + +Most projects want to provide the ability to change the target and optimization settings. +In order to encourage standard naming conventions for these options, Zig provides the +helper functions, `standardTargetOptions` and `standardOptimizeOption`. + +Standard target options allows the person running `zig build` to choose what +target to build for. By default, any target is allowed, and no choice means to +target the host system. Other options for restricting supported target set are +available. + +Standard optimization options allow the person running `zig build` to select +between `Debug`, `ReleaseSafe`, `ReleaseFast`, and `ReleaseSmall`. By default +none of the release options are considered the preferable choice by the build +script, and the user must make a decision in order to create a release build. + +[]($code.language('=html').buildAsset("build-system/3-standard-config-options/hello.zig")) +[]($code.language('=html').buildAsset("build-system/3-standard-config-options/build.zig")) + +Now, our `--help` menu contains more items: + +``` +Project-Specific Options: + -Dtarget=[string] The CPU architecture, OS, and ABI to build for + -Dcpu=[string] Target CPU features to add or subtract + -Doptimize=[enum] Prioritize performance, safety, or binary size (-O flag) + Supported Values: + Debug + ReleaseSafe + ReleaseFast + ReleaseSmall +``` + +It is entirely possible to create these options via `b.option` directly, but this +API provides a commonly used naming convention for these frequently used settings. + +In our terminal output, observe that we passed `-Dtarget=x86_64-windows -Doptimize=ReleaseSmall`. +Compared to the first example, now we see different files in the installation prefix: + +``` +zig-out/ +└── bin + └── hello.exe +``` + +## [Options for Conditional Compilation]($heading.id('conditional-compilation')) + +To pass options from the build script and into the project's Zig code, use +the `Options` step. + +[]($code.language('=html').buildAsset("build-system/conditional-compilation/app.zig")) +[]($code.language('=html').buildAsset("build-system/conditional-compilation/build.zig")) + +In this example, the data provided by `@import("config")` is comptime-known, +preventing the `@compileError` from triggering. If we had passed `-Dversion=0.2.3` +or omitted the option, then we would have seen the compilation of `app.zig` fail with +the "too old" error. + +## [Static Library]($heading.id('static-library')) + +This build script creates a static library from Zig code, and then also an +executable from other Zig code that consumes it. + +[]($code.language('=html').buildAsset("build-system/simple-static-library/fizzbuzz.zig")) +[]($code.language('=html').buildAsset("build-system/simple-static-library/demo.zig")) +[]($code.language('=html').buildAsset("build-system/simple-static-library/build.zig")) + +In this case, only the static library ends up being installed: + +``` +zig-out/ +└── lib + └── libfizzbuzz.a +``` + +However, if you look closely, the build script contains an option to also install the demo. +If we additionally pass `-Denable-demo`, then we see this in the installation prefix: + +``` +zig-out/ +├── bin +│   └── demo +└── lib + └── libfizzbuzz.a +``` + +Note that despite the unconditional call to `addExecutable`, the build system in fact +does not waste any time building the `demo` executable unless it is requested +with `-Denable-demo`, because the build system is based on a Directed Acyclic +Graph with dependency edges. + +## [Dynamic Library]($heading.id('dynamic-library')) + +Here we keep all the files the same from the [Static Library](#static-library) example, except +the `build.zig` file is changed. + +[]($code.language('=html').buildAsset("build-system/dynamic-library/build.zig")) + +**Output** +``` +zig-out +└── lib + ├── libfizzbuzz.so -> libfizzbuzz.so.1 + ├── libfizzbuzz.so.1 -> libfizzbuzz.so.1.2.3 + └── libfizzbuzz.so.1.2.3 +``` + +As in the static library example, to make an executable link against it, use code like this: + +```zig +exe.linkLibrary(libfizzbuzz); +``` + +## [Testing]($heading.id('testing')) + +Individual files can be tested directly with `zig test foo.zig`, however, more +complex use cases can be solved by orchestrating testing via the build script. + +When using the build script, unit tests are broken into two different steps in +the build graph, the **Compile** step and the **Run** step. Without a call to +`addRunArtifact`, which establishes a dependency edge between these two steps, +the unit tests will not be executed. + +The *Compile* step can be configured the same as any executable, library, or +object file, for example by [linking against system libraries](#linking-to-system-libraries), +setting target options, or adding additional compilation units. + +The *Run* step can be configured the same as any Run step, for example by +skipping execution when the host is not capable of executing the binary. + +When using the build system to run unit tests, the build runner and the test +runner communicate via *stdin* and *stdout* in order to run multiple unit test +suites concurrently, and report test failures in a meaningful way without +having their output jumbled together. This is one reason why +[writing to *standard out* in unit tests is problematic](https://github.com/ziglang/zig/issues/15091) - +it will interfere with this communication channel. On the flip side, this +mechanism will enable an upcoming feature, which is is the +[ability for a unit test to expect a *panic*](https://github.com/ziglang/zig/issues/1356). + +[]($code.language('=html').buildAsset("build-system/unit-testing/main.zig")) +[]($code.language('=html').buildAsset("build-system/unit-testing/build.zig")) + +In this case it might be a nice adjustment to enable `skip_foreign_checks` for +the unit tests: + +```diff +@@ -23,6 +23,7 @@ + }); + + const run_unit_tests = b.addRunArtifact(unit_tests); ++ run_unit_tests.skip_foreign_checks = true; + test_step.dependOn(&run_unit_tests.step); + } + } +``` + +[]($code.language('=html').buildAsset("build-system/unit-testing-skip-foreign/build.zig")) + +## [Linking to System Libraries]($heading.id('linking-system-libraries')) + +For satisfying library dependencies, there are two choices: + +1. Provide these libraries via the Zig Build System + (see [Package Management](#package-management) and [Static Library](#static-library)). +2. Use the files provided by the host system. + +For the use case of upstream project maintainers, obtaining these libraries via +the Zig Build System provides the least friction and puts the configuration +power in the hands of those maintainers. Everyone who builds this way will have +reproducible, consistent results as each other, and it will work on every +operating system and even support cross-compilation. Furthermore, it allows the +project to decide with perfect precision the exact versions of its entire +dependency tree it wishes to build against. This is expected to be the +generally preferred way to depend on external libraries. + +However, for the use case of packaging software into repositories such as +Debian, Homebrew, or Nix, it is mandatory to link against system libraries. So, +build scripts must +[detect the build mode](https://github.com/ziglang/zig/issues/14281) and configure accordingly. + +[]($code.language('=html').buildAsset("build-system/system-libraries/build.zig")) + +Users of `zig build` may use `--search-prefix` to provide additional +directories that are considered "system directories" for the purposes of finding +static and dynamic libraries. + +# [Generating Files]($heading.id('generating-files')) + +## [Running System Tools]($heading.id('system-tools')) +This version of hello world expects to find a `word.txt` file in the same path, +and we want to use a system tool to generate it starting from a JSON file. + +Be aware that system dependencies will make your project harder to build for your +users. This build script depends on `jq`, for example, which is not present by +default in most Linux distributions and which might be an unfamiliar tool for +Windows users. + +The next section will replace `jq` with a Zig tool included in the source tree, +which is the preferred approach. + +**`words.json`** +```json +{ + "en": "world", + "it": "mondo", + "ja": "世界" +} +``` + +[]($code.language('=html').buildAsset("build-system/10.5-system-tool/src/main.zig")) +[]($code.language('=html').buildAsset("build-system/10.5-system-tool/build.zig")) + +**Output** + +``` +zig-out +├── hello +└── word.txt +``` + +Note how `captureStdOut` creates a temporary file with the output of the `jq` invocation. + +## [Running the Project's Tools]($heading.id('project-tools')) + +This version of hello world expects to find a `word.txt` file in the same path, +and we want to produce it at build-time by invoking a Zig program on a JSON file. + +**`tools/words.json`** +```json +{ + "en": "world", + "it": "mondo", + "ja": "世界" +} +``` + +[]($code.language('=html').buildAsset("build-system/11-zig-tool/src/main.zig")) + +[]($code.language('=html').buildAsset("build-system/11-zig-tool/tools/word_select.zig")) + +[]($code.language('=html').buildAsset("build-system/11-zig-tool/build.zig")) + +**Output** + +``` +zig-out +├── hello +└── word.txt +``` + + +## [Producing Assets for `@embedFile`]($heading.id('embed-file')) + +This version of hello world wants to `@embedFile` an asset generated at build time, +which we're going to produce using a tool written in Zig. + +**`tools/words.json`** +```json +{ + "en": "world", + "it": "mondo", + "ja": "世界" +} +``` + +[]($code.language('=html').buildAsset("build-system/12-embedfile/src/main.zig")) + +[]($code.language('=html').buildAsset("build-system/12-embedfile/tools/word_select.zig")) + +[]($code.language('=html').buildAsset("build-system/12-embedfile/build.zig")) + +**Output** + +``` +zig-out/ +└── bin +    └── hello +``` + +## [Generating Zig Source Code]($heading.id('generating-zig')) +This build file uses a Zig program to generate a Zig file and then exposes it +to the main program as a module dependency. + +[]($code.language('=html').buildAsset("build-system/13-import/src/main.zig")) +[]($code.language('=html').buildAsset("build-system/13-import/tools/generate_struct.zig")) +[]($code.language('=html').buildAsset("build-system/13-import/build.zig")) + +**Output** + +``` +zig-out/ +└── bin +    └── hello +``` + +## [Dealing With One or More Generated Files]($heading.id('write-files')) + +The **WriteFiles** step provides a way to generate one or more files which +share a parent directory. The generated directory lives inside the local `.zig-cache`, +and each generated file is independently available as a `std.Build.LazyPath`. +The parent directory itself is also available as a `LazyPath`. + +This API supports writing arbitrary strings to the generated directory as well +as copying files into it. + +[]($code.language('=html').buildAsset("build-system/write-files/src/main.zig")) +[]($code.language('=html').buildAsset("build-system/write-files/build.zig")) + +**Output** + +``` +zig-out/ +└── project.tar.gz +``` + +## [Mutating Source Files in Place]($heading.id('mutating-source')) + +It is uncommon, but sometimes the case that a project commits generated files +into version control. This can be useful when the generated files are seldomly updated +and have burdensome system dependencies for the update process, but *only* during the +update process. + +For this, **WriteFiles** provides a way to accomplish this task. This is a feature that +[will be extracted from WriteFiles into its own Build Step](https://github.com/ziglang/zig/issues/14944) +in a future Zig version. + +Be careful with this functionality; it should not be used during the normal +build process, but as a utility run by a developer with intention to update +source files, which will then be committed to version control. If it is done +during the normal build process, it will cause caching and concurrency bugs. + +[]($code.language('=html').buildAsset("build-system/mutate-source-files/tools/proto_gen.zig")) +[]($code.language('=html').buildAsset("build-system/mutate-source-files/src/main.zig")) +[]($code.language('=html').buildAsset("build-system/mutate-source-files/src/protocol.zig")) +[]($code.language('=html').buildAsset("build-system/mutate-source-files/build.zig")) + +```=html +
$ zig build update-protocol --summary all
+Build Summary: 4/4 steps succeeded
+update-protocol success
+└─ WriteFile success
+   └─ run proto_gen (protocol.zig) success 401us MaxRSS:1M
+      └─ zig build-exe proto_gen Debug native success 1s MaxRSS:183M
+
+``` + +After running this command, `src/protocol.zig` is updated in place. + +# [Handy Examples]($heading.id('examples')) + +## [Build for multiple targets to make a release]($heading.id('release')) + +In this example we're going to change some defaults when creating an `InstallArtifact` step in order to put the build for each target into a separate subdirectory inside the install path. + +[]($code.language('=html').buildAsset("build-system/10-release/build.zig")) +[]($code.language('=html').buildAsset("build-system/10-release/hello.zig")) + +**Output** + +``` +zig-out +├── aarch64-linux +│   └── hello +├── aarch64-macos +│   └── hello +├── x86_64-linux-gnu +│   └── hello +├── x86_64-linux-musl +│   └── hello +└── x86_64-windows + ├── hello.exe + └── hello.pdb +``` diff --git a/content/pl-PL/learn/getting-started.smd b/content/pl-PL/learn/getting-started.smd new file mode 100644 index 000000000..c323fa0f2 --- /dev/null +++ b/content/pl-PL/learn/getting-started.smd @@ -0,0 +1,159 @@ +--- +.title = "Getting Started", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Getting Started", + "toc": true, +}, +--- + +# Tagged release or nightly build? +Zig has not yet reached v1.0 and the current release cycle is tied to new releases of LLVM, which have a ~6 months cadence. +In practical terms, **Zig releases tend to be far apart and eventually become stale given the current speed of development**. + +It's fine to evaluate Zig using a tagged version, but if you decide that you like Zig and +want to dive deeper, **we encourage you to upgrade to a nightly build**, mainly because +that way it will be easier for you to get help: most of the community and sites like +[zig.guide](https://zig.guide) track the master branch for the reasons stated above. + +The good news is that it's very easy to switch from one Zig version to another, or even have multiple versions present on the system at the same time: Zig releases are self-contained archives that can be placed anywhere in your system. + + +# Installing Zig +## [Direct download]($heading.id('direct')) +This is the most straight-forward way of obtaining Zig: grab a Zig bundle for your platform from the [Downloads](/download) page, +extract it in a directory and add it to your `PATH` to be able to call `zig` from any location. + +### Setting up PATH on Windows +To setup your path on Windows run **one** of the following snippets of code in a Powershell instance. +Choose if you want to apply this change on a system-wide level (requires running Powershell with admin privileges) +or just for your user, and **make sure to change the snippet to point at the location where your copy of Zig lies**. +The `;` before `C:` is not a typo. + +System wide (**admin** Powershell): +``` +[Environment]::SetEnvironmentVariable( + "Path", + [Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\your-path\zig-windows-x86_64-your-version", + "Machine" +) +``` + +User level (Powershell): +``` +[Environment]::SetEnvironmentVariable( + "Path", + [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\your-path\zig-windows-x86_64-your-version", + "User" +) +``` +After you're done, restart your Powershell instance. + +### Setting up PATH on Linux, macOS, BSD +Add the location of your zig binary to your PATH environment variable. + +This is generally done by adding an export line to your shell startup script (`.profile`, `.zshrc`, ...) +```bash +export PATH=$PATH:~/path/to/zig +``` +After you're done, either `source` your startup file or restart your shell. + + + + +## [Package managers]($heading.id('managers')) +### Windows +**WinGet** +Zig is available on [WinGet](https://github.com/microsoft/winget-pkgs/tree/master/manifests/z/zig/zig). +``` +winget install -e --id zig.zig +``` + +**Chocolatey** +Zig is available on [Chocolatey](https://chocolatey.org/packages/zig). +``` +choco install zig +``` + +**Scoop** +Zig is available on [Scoop](https://scoop.sh/#/apps?q=zig&id=7e124d6047c32d426e4143ab395d863fc9d6d491). +``` +scoop install zig +``` +Latest [dev build](https://scoop.sh/#/apps?q=zig&id=921df07e75042de645204262e784a17c2421944c): +``` +scoop bucket add versions +scoop install versions/zig-dev +``` + +### macOS + +**Homebrew** +Latest tagged release: +``` +brew install zig +``` + +**MacPorts** +``` +sudo port install zig +``` +### Linux +Zig is also present in many package managers for Linux. [Here](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager) +you can find an updated list but keep in mind that some packages might bundle outdated versions of Zig. + +## [Building from source]($heading.id('source')) +[Here](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source) +you can find more information on how to build Zig from source for Linux, macOS and Windows. + +# Recommended tools +## Syntax Highlighters and LSP +All major text editors have syntax highlight support for Zig. +Some bundle it, some others require installing a plugin. + +If you're interested in a deeper integration between Zig and your editor, +checkout [zigtools/zls](https://github.com/zigtools/zls). + +If you're interested in what else is available, checkout the [Tools](tools) section. + + +# Run Hello World +If you completed the installation process correctly, you should now be able to invoke the Zig compiler from your shell. +Let's test this by creating your first Zig program! + +Navigate to your projects directory and run: +```bash +mkdir hello-world +cd hello-world +zig init +``` + +This should output: +``` +info: created build.zig +info: created build.zig.zon +info: created src/main.zig +info: created src/root.zig +info: see `zig build --help` for a menu of options +``` + +Running `zig build run` should then compile the executable and run it, ultimately resulting in: +``` +All your codebase are belong to us. +Run `zig build test` to run the tests. +``` + +Congratulations, you have a working Zig installation! + +# Next steps +**Check out other resources present in the [Learn](/learn) section**, make sure to find the Documentation for your version +of Zig (note: nightly builds should use `master` docs) and consider giving [zig.guide](https://zig.guide) a read. + +Zig is a young project and unfortunately we don't have yet the capacity to produce extensive documentation and learning +materials for everything, so you should consider [joining one of the existing Zig communities](https://github.com/ziglang/zig/wiki/Community) +to get help when you get stuck, as well as checking out initiatives like [Zig SHOWTIME](https://zig.show). + +Finally, if you enjoy Zig and want to help speed up the development, [consider donating to the Zig Software Foundation](/zsf) +. diff --git a/content/pl-PL/learn/index.smd b/content/pl-PL/learn/index.smd new file mode 100644 index 000000000..fd607b257 --- /dev/null +++ b/content/pl-PL/learn/index.smd @@ -0,0 +1,74 @@ +--- +.title = "Learn", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "learn.shtml", +.custom = { + "mobile_menu_title": "Learn", +}, +--- +# [Learn]($section.id('learn')) +This section lists resources useful to go from knowing nothing about Zig up +to understanding its philosophy. + + +## [Guides]($section.id('guides')) +This section is eventually going to be bundled with Zig's standard library documentation, but +in the meantime you can browse it from here. + +- [Zig Build System](./build-system/) +Introduction to the Zig build system. + +## Introduction +These are all introductions to Zig aimed at programmers with different backgrounds. + +- [In-depth Overview](./overview/) +Here's an in-depth feature overview of Zig from a systems-programming perspective. +- [Why Zig When There is Already C++, D, and Rust?](./why_zig_rust_d_cpp/) +An introduction to Zig for C++, D, and Rust programmers. +- [Code Examples](./samples/) +A list of snippets to get a feeling for how Zig code looks. +- [Tools](./tools/) +A list of useful tools that can help you write Zig code. + + +## Getting started +If you're ready to start programming in Zig, this guide will help you setup your environment. + +- [Getting started](./getting-started) + +## Online learning resources +- [Introduction to Zig: a project-based book](https://github.com/pedropark99/zig-book) +An open, technical and introductory book for Zig. +- [zig.guide](https://zig.guide) +A structured introduction to Zig by [Sobeston](https://github.com/sobeston). +- [Ziglings](https://ziglings.org) +Learn Zig by fixing tiny broken programs. +- [Zig on Exercism](https://exercism.org/tracks/zig) +Solve coding exercises and get mentored to develop fluency in Zig. +- [Learning Zig](https://www.openmymind.net/learning_zig/) +Short introduction to Zig well suited for developers coming from garbage-collected languages. + +## Relevant videos and blog posts +- [Road to Zig 1.0](https://www.youtube.com/watch?v=Gv2I7qTux7g) [video] +Video by [Andrew Kelley](https://andrewkelley.me) introducing Zig and its philosophy. +- [Zig's New Relationship with LLVM](https://kristoff.it/blog/zig-new-relationship-llvm/) +A blog post about the work towards building the Zig self-hosted compiler, also featured in [an article by lwn.net](https://lwn.net/Articles/833400/). + + + + + + + + + + + + + + + + + + diff --git a/content/pl-PL/learn/overview.smd b/content/pl-PL/learn/overview.smd new file mode 100644 index 000000000..c59fa3c83 --- /dev/null +++ b/content/pl-PL/learn/overview.smd @@ -0,0 +1,519 @@ +--- +.title = "Overview", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Overview", +}, +--- +# Feature Highlights +## Small, simple language + +Focus on debugging your application rather than debugging your programming language knowledge. + +Zig's entire syntax is specified with a [580-line PEG grammar file](https://ziglang.org/documentation/master/#Grammar). + +There is **no hidden control flow**, no hidden memory allocations, no preprocessor, and no macros. If Zig code doesn't look like it's jumping away to call a function, then it isn't. This means you can be sure that the following code calls only `foo()` and then `bar()`, and this is guaranteed without needing to know the types of anything: + +```zig +var a = b + c.d; +foo(); +bar(); +``` + +Examples of hidden control flow: + +- D has `@property` functions, which are methods that you call with what looks like field access, so in the above example, `c.d` might call a function. +- C++, D, and Rust have operator overloading, so the `+` operator might call a function. +- C++, D, and Go have throw/catch exceptions, so `foo()` might throw an exception, and prevent `bar()` from being called. + + Zig promotes code maintenance and readability by making all control flow managed exclusively with language keywords and function calls. + +## Performance and Safety: Choose Two + +Zig has four [build modes](https://ziglang.org/documentation/master/#Build-Mode), and they can all be mixed and matched all the way down to [scope granularity](https://ziglang.org/documentation/master/#setRuntimeSafety). + +| Parameter | [Debug](/documentation/master/#Debug) | [ReleaseSafe](/documentation/master/#ReleaseSafe) | [ReleaseFast](/documentation/master/#ReleaseFast) | [ReleaseSmall](/documentation/master/#ReleaseSmall) | +|-----------|-------|-------------|-------------|--------------| +Optimizations - improve speed, harm debugging, harm compile time | | -O3 | -O3| -Os | +Runtime Safety Checks - harm speed, harm size, crash instead of undefined behavior | On | On | | | + +Here is what [Integer Overflow](https://ziglang.org/documentation/master/#Integer-Overflow) looks like at compile time, regardless of the build mode: + +[]($code.language('=html').buildAsset('features/1-integer-overflow.zig')) + +Here is what it looks like at runtime, in safety-checked builds: + +[]($code.language('=html').buildAsset('features/2-integer-overflow-runtime.zig')) + + +Those [stack traces work on all targets](#stack-traces-on-all-targets), including [freestanding](https://andrewkelley.me/post/zig-stack-traces-kernel-panic-bare-bones-os.html). + +With Zig one can rely on a safety-enabled build mode, and selectively disable safety at the performance bottlenecks. For example the previous example could be modified like this: + +[]($code.language('=html').buildAsset('features/3-undefined-behavior.zig')) + +Zig uses [undefined behavior](https://ziglang.org/documentation/master/#Undefined-Behavior) as a razor sharp tool for both bug prevention and performance enhancement. + +Speaking of performance, Zig is faster than C. + +- The reference implementation uses LLVM as a backend for state of the art optimizations. +- What other projects call "Link Time Optimization" Zig does automatically. +- For native targets, advanced CPU features are enabled (-march=native), thanks to the fact that [Cross-compiling is a first-class use case](#cross-compiling-is-a-first-class-use-case). +- Carefully chosen undefined behavior. For example, in Zig both signed and unsigned integers have undefined behavior on overflow, contrasted to only signed integers in C. This [facilitates optimizations that are not available in C](https://godbolt.org/z/n_nLEU). +- Zig directly exposes a [SIMD vector type](https://ziglang.org/documentation/master/#Vectors), making it easy to write portable vectorized code. + +Please note that Zig is not a fully safe language. For those interested in following Zig's safety story, subscribe to these issues: + +- [enumerate all kinds of undefined behavior, even that which cannot be safety-checked](https://github.com/ziglang/zig/issues/1966) +- [make Debug and ReleaseSafe modes fully safe](https://github.com/ziglang/zig/issues/2301) + +## Zig competes with C instead of depending on it + +The Zig Standard Library integrates with libc, but does not depend on it. Here's Hello World: + +[]($code.language('=html').buildAsset('features/4-hello.zig')) + +When compiled with `-O ReleaseSmall`, debug symbols stripped, single-threaded mode, this produces a 9.8 KiB static executable for the x86_64-linux target: +``` +$ zig build-exe hello.zig -O ReleaseSmall -fstrip -fsingle-threaded +$ wc -c hello +9944 hello +$ ldd hello + not a dynamic executable +``` + +A Windows build is even smaller, coming out to 4096 bytes: +``` +$ zig build-exe hello.zig -O ReleaseSmall -fstrip -fsingle-threaded -target x86_64-windows +$ wc -c hello.exe +4096 hello.exe +$ file hello.exe +hello.exe: PE32+ executable (console) x86-64, for MS Windows +``` + +## Order independent top level declarations + +Top level declarations such as global variables are order-independent and lazily analyzed. The initialization values of global variables are [evaluated at compile-time](#compile-time-reflection-and-compile-time-code-execution). + +[]($code.language('=html').buildAsset('features/5-global-variables.zig')) + +## Optional type instead of null pointers + +In other programming languages, null references are the source of many runtime exceptions, and even stand accused of being [the worst mistake of computer science](https://www.lucidchart.com/techblog/2015/08/31/the-worst-mistake-of-computer-science/). + +Unadorned Zig pointers cannot be null: + +[]($code.language('=html').buildAsset('features/6-null-to-ptr.zig')) + +However any type can be made into an [optional type](https://ziglang.org/documentation/master/#Optionals) by prefixing it with ?: + +[]($code.language('=html').buildAsset('features/7-optional-syntax.zig')) + +To unwrap an optional value, one can use `orelse` to provide a default value: + +[]($code.language('=html').buildAsset('features/8-optional-orelse.zig')) + +Another option is to use if: + +[]($code.language('=html').buildAsset('features/9-optional-if.zig')) + + The same syntax works with [while](https://ziglang.org/documentation/master/#while): + +[]($code.language('=html').buildAsset('features/10-optional-while.zig')) + +## Manual memory management + +A library written in Zig is eligible to be used anywhere: + +- [Desktop applications](https://github.com/TM35-Metronome/) +- Low latency servers +- [Operating System kernels](https://github.com/AndreaOrru/zen) +- [Embedded devices](https://github.com/skyfex/zig-nrf-demo/) +- Real-time software, e.g. live performances, airplanes, pacemakers +- [In web browsers or other plugins with WebAssembly](https://shritesh.github.io/zigfmt-web/) +- By other programming languages, using the C ABI + +In order to accomplish this, Zig programmers must manage their own memory, and must handle memory allocation failure. + +This is true of the Zig Standard Library as well. Any functions that need to allocate memory accept an allocator parameter. As a result, the Zig Standard Library can be used even for the freestanding target. + +In addition to [A fresh take on error handling](#a-fresh-take-on-error-handling), Zig provides [defer](https://ziglang.org/documentation/master/#defer) and [errdefer](https://ziglang.org/documentation/master/#errdefer) to make all resource management - not only memory - simple and easily verifiable. + +For an example of `defer`, see [Integration with C libraries without FFI/bindings](#integration-with-c-libraries-without-ffibindings). Here is an example of using `errdefer`: +[]($code.language('=html').buildAsset('features/11-errdefer.zig')) + + +## A fresh take on error handling + +Errors are values, and may not be ignored: + +[]($code.language('=html').buildAsset('features/12-errors-as-values.zig')) + +Errors can be handled with [catch](https://ziglang.org/documentation/master/#catch): + +[]($code.language('=html').buildAsset('features/13-errors-catch.zig')) + +The keyword [try](https://ziglang.org/documentation/master/#try) is a shortcut for `catch |err| return err`: + +[]($code.language('=html').buildAsset('features/14-errors-try.zig')) + +Note that is an [Error Return Trace](https://ziglang.org/documentation/master/#Error-Return-Traces), not a [stack trace](#stack-traces-on-all-targets). The code did not pay the price of unwinding the stack to come up with that trace. + +The [switch](https://ziglang.org/documentation/master/#switch) keyword used on an error ensures that all possible errors are handled: + +[]($code.language('=html').buildAsset('features/15-errors-switch.zig')) + +The keyword [unreachable](https://ziglang.org/documentation/master/#unreachable) is used to assert that no errors will occur: + +[]($code.language('=html').buildAsset('features/16-unreachable.zig')) + +This invokes [undefined behavior](#performance-and-safety-choose-two) in the unsafe build modes, so be sure to use it only when success is guaranteed. + +### Stack traces on all targets + +The stack traces and [error return traces](https://ziglang.org/documentation/master/#Error-Return-Traces) shown on this page work on all Tier 1 Support and some Tier 2 Support targets. [Even freestanding](https://andrewkelley.me/post/zig-stack-traces-kernel-panic-bare-bones-os.html)! + +In addition, the standard library has the ability to capture a stack trace at any point and then dump it to standard error later: + +[]($code.language('=html').buildAsset('features/17-stack-traces.zig')) + +You can see this technique being used in the ongoing [GeneralPurposeDebugAllocator project](https://github.com/andrewrk/zig-general-purpose-allocator/#current-status). + +## Generic data structures and functions + +Types are values that must be known at compile-time: + +[]($code.language('=html').buildAsset('features/18-types.zig')) + +A generic data structure is simply a function that returns a `type`: + +[]($code.language('=html').buildAsset('features/19-generics.zig')) + +## Compile-time reflection and compile-time code execution + +The [@typeInfo](https://ziglang.org/documentation/master/#typeInfo) builtin function provides reflection: + +[]($code.language('=html').buildAsset('features/20-reflection.zig')) + +The Zig Standard Library uses this technique to implement formatted printing. Despite being a [Small, simple language](#small-simple-language), Zig's formatted printing is implemented entirely in Zig. Meanwhile, in C, compile errors for printf are hard-coded into the compiler. Similarly, in Rust, the formatted printing macro is hard-coded into the compiler. + +Zig can also evaluate functions and blocks of code at compile-time. In some contexts, such as global variable initializations, the expression is implicitly evaluated at compile-time. Otherwise, one can explicitly evaluate code at compile-time with the [comptime](https://ziglang.org/documentation/master/#comptime) keyword. This can be especially powerful when combined with assertions: + +[]($code.language('=html').buildAsset('features/21-comptime.zig')) + +## Integration with C libraries without FFI/bindings + +[@cImport](https://ziglang.org/documentation/master/#cImport) directly imports types, variables, functions, and simple macros for use in Zig. It even translates inline functions from C into Zig. + +Here is an example of emitting a sine wave using [libsoundio](http://libsound.io/): + +sine.zig +[]($code.language('=html').buildAsset('features/22-sine-wave.zig')) + +``` +$ zig build-exe sine.zig -lsoundio -lc +$ ./sine +Output device: Built-in Audio Analog Stereo +^C +``` + +[This Zig code is significantly simpler than the equivalent C code](https://gist.github.com/andrewrk/d285c8f912169329e5e28c3d0a63c1d8), as well as having more safety protections, and all this is accomplished by directly importing the C header file - no API bindings. + +*Zig is better at using C libraries than C is at using C libraries.* + +### Zig is also a C compiler + +Here's an example of Zig building some C code: + +hello.c +```c +#include + +int main(int argc, char **argv) { + printf("Hello world\n"); + return 0; +} +``` + +``` +$ zig build-exe hello.c --library c +$ ./hello +Hello world +``` + +You can use `--verbose-cc` to see what C compiler command this executed: +``` +$ zig build-exe hello.c --library c --verbose-cc +zig cc -MD -MV -MF .zig-cache/tmp/42zL6fBH8fSo-hello.o.d -nostdinc -fno-spell-checking -isystem /home/andy/dev/zig/build/lib/zig/include -isystem /home/andy/dev/zig/build/lib/zig/libc/include/x86_64-linux-gnu -isystem /home/andy/dev/zig/build/lib/zig/libc/include/generic-glibc -isystem /home/andy/dev/zig/build/lib/zig/libc/include/x86_64-linux-any -isystem /home/andy/dev/zig/build/lib/zig/libc/include/any-linux-any -march=native -g -fstack-protector-strong --param ssp-buffer-size=4 -fno-omit-frame-pointer -o .zig-cache/tmp/42zL6fBH8fSo-hello.o -c hello.c -fPIC +``` + +Note that if you run the command again, there is no output, and it finishes instantly: +``` +$ time zig build-exe hello.c --library c --verbose-cc + +real 0m0.027s +user 0m0.018s +sys 0m0.009s +``` + +This is thanks to [Build Artifact Caching](https://ziglang.org/download/0.4.0/release-notes.html#Build-Artifact-Caching). Zig automatically parses the .d file using a robust caching system to avoid duplicating work. + +Not only can Zig compile C code, but there is a very good reason to use Zig as a C compiler: [Zig ships with libc](#zig-ships-with-libc). + +### Export functions, variables, and types for C code to depend on + +One of the primary use cases for Zig is exporting a library with the C ABI for other programming languages to call into. The `export` keyword in front of functions, variables, and types causes them to be part of the library API: + +mathtest.zig +[]($code.language('=html').buildAsset('features/23-math-test.zig')) + +To make a static library: +``` +$ zig build-lib mathtest.zig +``` + +To make a shared library: +``` +$ zig build-lib mathtest.zig -dynamic +``` + +Here is an example with the [Zig Build System](#zig-build-system): + +test.c +```c +#include "mathtest.h" +#include + +int main(int argc, char **argv) { + int32_t result = add(42, 1337); + printf("%d\n", result); + return 0; +} +``` + +build.zig +[]($code.language('=html').buildAsset('features/24-build.zig')) + +``` +$ zig build test +1379 +``` + +## Cross-compiling is a first-class use case + +Zig can build for any of the targets from the Support Table (see latest release notes) with Tier 3 Support or better. No "cross toolchain" needs to be installed or anything like that. Here's a native Hello World: + +[]($code.language('=html').buildAsset('features/4-hello.zig')) + +Now to build it for x86_64-windows, x86_64-macos, and aarch64-linux: +``` +$ zig build-exe hello.zig -target x86_64-windows +$ file hello.exe +hello.exe: PE32+ executable (console) x86-64, for MS Windows +$ zig build-exe hello.zig -target x86_64-macos +$ file hello +hello: Mach-O 64-bit x86_64 executable, flags: +$ zig build-exe hello.zig -target aarch64-linux +$ file hello +hello: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, with debug_info, not stripped +``` + +This works on any Tier 3+ target, for any Tier 3+ target. + +### Zig ships with libc + +You can find the available libc targets with `zig targets`: +``` +... + "libc": [ + "aarch64_be-linux-gnu", + "aarch64_be-linux-musl", + "aarch64_be-windows-gnu", + "aarch64-linux-gnu", + "aarch64-linux-musl", + "aarch64-windows-gnu", + "armeb-linux-gnueabi", + "armeb-linux-gnueabihf", + "armeb-linux-musleabi", + "armeb-linux-musleabihf", + "armeb-windows-gnu", + "arm-linux-gnueabi", + "arm-linux-gnueabihf", + "arm-linux-musleabi", + "arm-linux-musleabihf", + "arm-windows-gnu", + "mips64el-linux-gnuabi64", + "mips64el-linux-gnuabin32", + "mips64el-linux-musl", + "mips64-linux-gnuabi64", + "mips64-linux-gnuabin32", + "mips64-linux-musl", + "mipsel-linux-gnu", + "mipsel-linux-musl", + "mips-linux-gnu", + "mips-linux-musl", + "powerpc64le-linux-gnu", + "powerpc64le-linux-musl", + "powerpc64-linux-gnu", + "powerpc64-linux-musl", + "powerpc-linux-gnu", + "powerpc-linux-musl", + "riscv64-linux-gnu", + "riscv64-linux-musl", + "s390x-linux-gnu", + "s390x-linux-musl", + "sparc-linux-gnu", + "sparcv9-linux-gnu", + "wasm32-freestanding-musl", + "x86-linux-gnu", + "x86-linux-musl", + "x86-windows-gnu", + "x86_64-linux-gnu", + "x86_64-linux-gnux32", + "x86_64-linux-musl", + "x86_64-windows-gnu" + ], + ``` + +What this means is that `--library c` for these targets *does not depend on any system files*! + +Let's look at that [C hello world example](#zig-is-also-a-c-compiler) again: +``` +$ zig build-exe hello.c --library c +$ ./hello +Hello world +$ ldd ./hello + linux-vdso.so.1 (0x00007ffd03dc9000) + libc.so.6 => /lib/libc.so.6 (0x00007fc4b62be000) + libm.so.6 => /lib/libm.so.6 (0x00007fc4b5f29000) + libpthread.so.0 => /lib/libpthread.so.0 (0x00007fc4b5d0a000) + libdl.so.2 => /lib/libdl.so.2 (0x00007fc4b5b06000) + librt.so.1 => /lib/librt.so.1 (0x00007fc4b58fe000) + /lib/ld-linux-x86-64.so.2 => /lib64/ld-linux-x86-64.so.2 (0x00007fc4b6672000) +``` + +[glibc](https://www.gnu.org/software/libc/) does not support building statically, but [musl](https://www.musl-libc.org/) does: +``` +$ zig build-exe hello.c --library c -target x86_64-linux-musl +$ ./hello +Hello world +$ ldd hello + not a dynamic executable +``` + +In this example, Zig built musl libc from source and then linked against it. The build of musl libc for x86_64-linux remains available thanks to the [caching system](https://ziglang.org/download/0.4.0/release-notes.html#Build-Artifact-Caching), so any time this libc is needed again it will be available instantly. + +This means that this functionality is available on any platform. Windows and macOS users can build Zig and C code, and link against libc, for any of the targets listed above. Similarly code can be cross compiled for other architectures: +``` +$ zig build-exe hello.c --library c -target aarch64-linux-gnu +$ file hello +hello: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 2.0.0, with debug_info, not stripped +``` + +In some ways, Zig is a better C compiler than C compilers! + +This functionality is more than bundling a cross-compilation toolchain along with Zig. For example, the total size of libc headers that Zig ships is 22 MiB uncompressed. Meanwhile, the headers for musl libc + linux headers on x86_64 alone are 8 MiB, and for glibc are 3.1 MiB (glibc is missing the linux headers), yet Zig currently ships with 40 libcs. With a naive bundling that would be 444 MiB. However, thanks to this [process_headers tool](https://github.com/ziglang/zig/blob/0.4.0/libc/process_headers.zig), and some [good old manual labor](https://github.com/ziglang/zig/wiki/Updating-libc), Zig binary tarballs remain roughly 30 MiB total, despite supporting libc for all these targets, as well as compiler-rt, libunwind, and libcxx, and despite being a clang-compatible C compiler. For comparison, the Windows binary build of clang 8.0.0 itself from llvm.org is 132 MiB. + +Note that only the Tier 1 Support targets have been thoroughly tested. It is planned to [add more libcs](https://github.com/ziglang/zig/issues/514) (including for Windows), and to [add test coverage for building against all the libcs](https://github.com/ziglang/zig/issues/2058). + +It's [planned to have a Zig Package Manager](https://github.com/ziglang/zig/issues/943), but it's not done yet. One of the things that will be possible is to create a package for C libraries. This will make the [Zig Build System](#zig-build-system) attractive for Zig programmers and C programmers alike. + +## Zig Build System + +Zig comes with a build system, so you don't need make, cmake, or anything like that. +``` +$ zig init-exe +Created build.zig +Created src/main.zig + +Next, try `zig build --help` or `zig build run` +``` + +src/main.zig +[]($code.language('=html').buildAsset('features/25-all-bases.zig')) + + +build.zig +[]($code.language('=html').buildAsset('features/26-build.zig')) + + +Let's have a look at that `--help` menu. +``` +$ zig build --help +Usage: zig build [steps] [options] + +Steps: + install (default) Copy build artifacts to prefix path + uninstall Remove build artifacts from prefix path + run Run the app + +General Options: + --help Print this help and exit + --verbose Print commands before executing them + --prefix [path] Override default install prefix + --search-prefix [path] Add a path to look for binaries, libraries, headers + +Project-Specific Options: + -Dtarget=[string] The CPU architecture, OS, and ABI to build for. + -Drelease-safe=[bool] optimizations on and safety on + -Drelease-fast=[bool] optimizations on and safety off + -Drelease-small=[bool] size optimizations on and safety off + +Advanced Options: + --build-file [file] Override path to build.zig + --cache-dir [path] Override path to zig cache directory + --override-lib-dir [arg] Override path to Zig lib directory + --verbose-tokenize Enable compiler debug output for tokenization + --verbose-ast Enable compiler debug output for parsing into an AST + --verbose-link Enable compiler debug output for linking + --verbose-ir Enable compiler debug output for Zig IR + --verbose-llvm-ir Enable compiler debug output for LLVM IR + --verbose-cimport Enable compiler debug output for C imports + --verbose-cc Enable compiler debug output for C compilation + --verbose-llvm-cpu-features Enable compiler debug output for LLVM CPU features +``` + +You can see that one of the available steps is run. +``` +$ zig build run +All your base are belong to us. +``` + +Here are some example build scripts: + +- [Build script of OpenGL Tetris game](https://github.com/andrewrk/tetris/blob/master/build.zig) +- [Build script of bare metal Raspberry Pi 3 arcade game](https://github.com/andrewrk/clashos/blob/master/build.zig) +- [Build script of self-hosted Zig compiler](https://github.com/ziglang/zig/blob/master/build.zig) + +## Concurrency via Async Functions + +Zig 0.5.0 [introduced async functions](https://ziglang.org/download/0.5.0/release-notes.html#Async-Functions). This feature has no dependency on a host operating system or even heap-allocated memory. That means async functions are available for the freestanding target. + +Zig infers whether a function is async, and allows `async`/`await` on non-async functions, which means that **Zig libraries are agnostic of blocking vs async I/O**. [Zig avoids function colors](http://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/). + + + +The Zig Standard Library implements an event loop that multiplexes async functions onto a thread pool for M:N concurrency. Multithreading safety and race detection are areas of active research. + +## Wide range of targets supported + +Zig uses a "support tier" system to communicate the level of support for different targets. + +[Support Table as of Zig 0.11.0](https://ziglang.org/download/0.11.0/release-notes.html#Support-Table) + +## Friendly toward package maintainers + +The reference Zig compiler is not completely self-hosted yet, but no matter what, [it will remain exactly 3 steps](https://github.com/ziglang/zig/issues/853) to go from having a system C++ compiler to having a fully self-hosted Zig compiler for any target. As Maya Rashish notes, [porting Zig to other platforms is fun and speedy](http://coypu.sdf.org/porting-zig.html). + +Non-debug [build modes](https://ziglang.org/documentation/master/#Build-Mode) are reproducible/deterministic. + +There is a [JSON version of the download page](https://ziglang.org/download/index.json). + +Several members of the Zig team have experience maintaining packages. + +- [Daurnimator](https://github.com/daurnimator) maintains the [Arch Linux package](https://archlinux.org/packages/extra/x86_64/zig/) +- [Marc Tiehuis](https://tiehuis.github.io/) maintains the Visual Studio Code package. +- [Andrew Kelley](https://andrewkelley.me/) spent a year or so doing [Debian and Ubuntu packaging](https://qa.debian.org/developer.php?login=superjoe30%40gmail.com&comaint=yes), and casually contributes to [nixpkgs](https://github.com/NixOS/nixpkgs/). +- [Jeff Fowler](https://blog.jfo.click/) maintains the Homebrew package and started the [Sublime package](https://github.com/ziglang/sublime-zig-language) (now maintained by [emekoi](https://github.com/emekoi)). diff --git a/content/pl-PL/learn/samples.smd b/content/pl-PL/learn/samples.smd new file mode 100644 index 000000000..580c2e73e --- /dev/null +++ b/content/pl-PL/learn/samples.smd @@ -0,0 +1,48 @@ +--- +.title = "Samples", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Samples", + "toc": true, +}, +--- + +# [Hello world]($heading.id('hello')) +A minimal example printing hello world. + +[]($code.language('=html').buildAsset("samples/hello-world.zig")) + +# [Calling external library functions]($heading.id('ext')) +All system API functions can be invoked this way, you do not need library bindings to interface them. + +[]($code.language('=html').buildAsset("samples/windows-msgbox.zig")) + +# [Memory leak detection]($heading.id('leak')) +Using `std.heap.GeneralPurposeAllocator` you can track double frees and memory leaks. + +[]($code.language('=html').buildAsset("samples/memory-leak.zig")) + + +# [C interoperability]($heading.id('c-interop')) +Example of importing a C header file and linking to both libc and raylib. + +[]($code.language('=html').buildAsset("samples/c-interop.zig")) + + +# [Zigg Zagg]($heading.id('zigg-zagg')) +Zig is *optimized* for coding interviews (not really). + +[]($code.language('=html').buildAsset("samples/ziggzagg.zig")) + + +# [Generic Types]($heading.id('generic')) +In Zig types are comptime values and we use functions that return a type to implement generic algorithms and data structures. In this example we implement a simple generic queue and test its behaviour. + +[]($code.language('=html').buildAsset("samples/generic-type.zig")) + + +# [Using cURL from Zig]($heading.id('curl')) + +[]($code.language('=html').buildAsset("samples/curl.zig")) diff --git a/content/pl-PL/learn/tools.smd b/content/pl-PL/learn/tools.smd new file mode 100644 index 000000000..93ee983df --- /dev/null +++ b/content/pl-PL/learn/tools.smd @@ -0,0 +1,38 @@ +--- +.title = "Tools", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Tools", + "toc": true, +}, +--- + +# [Language Servers]($heading.id('lsp')) +Language servers are editor-agnostic tools for obtaining syntax highlighting, autocompletion, and many other features. Consider using a Language server over a syntax-highlighting extension for a richer development experience. + +- [zigtools/zls](https://github.com/zigtools/zls) + +# [Text Editors]($heading.id('editors')) +Editor-specific tools, mostly syntax highlighters. + +## VS Code +- [ziglang/vscode-zig](https://github.com/ziglang/vscode-zig) + +## Sublime Text +- [ziglang/sublime-zig-language](https://github.com/ziglang/sublime-zig-language) + +## Vim +- [ziglang/zig.vim](https://github.com/ziglang/zig.vim) + +## Emacs +- [ziglang/zig-mode](https://github.com/ziglang/zig-mode) + +## Kate +- [ziglang/kde-syntax-highlighting](https://github.com/ziglang/kde-syntax-highlighting) + +## JetBrains family (IntelliJ IDEA, Fleet) +- [ZigBrains](https://plugins.jetbrains.com/plugin/22456-zigbrains) +- [Zig Fleet Plugin](https://plugins.jetbrains.com/plugin/26070-zig) + diff --git a/content/pl-PL/learn/why_zig_rust_d_cpp.smd b/content/pl-PL/learn/why_zig_rust_d_cpp.smd new file mode 100644 index 000000000..98b9066cb --- /dev/null +++ b/content/pl-PL/learn/why_zig_rust_d_cpp.smd @@ -0,0 +1,158 @@ +--- +.title = "Why Zig When There is Already C++, D, and Rust?", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Why Zig?", +}, +--- + +# No hidden control flow + +If Zig code doesn't look like it's jumping away to call a function, then it isn't. This means you can be sure that the following code calls only `foo()` and then `bar()`, and this is guaranteed without needing to know the types of anything: + +```zig +var a = b + c.d; +foo(); +bar(); +``` + +Examples of hidden control flow: + +* D has `@property` functions, which are methods that you call with what looks like field access, so in the above example, `c.d` might call a function. +* C++, D, and Rust have operator overloading, so the `+` operator might call a function. +* C++, D, and Go have throw/catch exceptions (sometimes also called panic/recover), so `foo()` might throw an exception, and prevent `bar()` from being called. (Of course, even in Zig `foo()` could deadlock and prevent `bar()` from being called, but that can happen in any Turing-complete language.) + +The purpose of this design decision is to improve readability. + +# No hidden allocations + +Zig has a hands-off approach when it comes to heap allocation. There is no `new` keyword +or any other language feature that uses a heap allocator (e.g. string concatenation operator[1]). +The entire concept of the heap is managed by library and application code, not by the language. + +Examples of hidden allocations: + +* Go's `defer` allocates memory to a function-local stack. In addition to being an unintuitive + way for this control flow to work, it can cause out-of-memory failures if you use + `defer` inside a loop. +* C++ coroutines allocate heap memory in order to call a coroutine. +* In Go, a function call can cause heap allocation because goroutines allocate small stacks + that get resized when the call stack gets deep enough. +* The main Rust standard library APIs panic on out of memory conditions, and the alternate + APIs that accept allocator parameters are an afterthought + (see [rust-lang/rust#29802](https://github.com/rust-lang/rust/issues/29802)). + +Nearly all garbage collected languages have hidden allocations strewn about, since the +garbage collector hides the evidence on the cleanup side. + +The main problem with hidden allocations is that it prevents the *reusability* of a +piece of code, unnecessarily limiting the number of environments that code would be +appropriate to be deployed to. Simply put, there are use cases where one must be able +to rely on control flow and function calls not to have the side-effect of memory allocation, +therefore a programming language can only serve these use cases if it can realistically +provide this guarantee. + +In Zig, there are standard library features that provide and work with heap allocators, +but those are optional standard library features, not built into the language itself. +If you never initialize a heap allocator, you can be confident your program will not heap allocate. + +Every standard library feature that needs to allocate heap memory accepts an `Allocator` parameter +in order to do it. This means that the Zig standard library supports freestanding targets. For +example `std.ArrayList` and `std.AutoHashMap` can be used for bare metal programming! + +Custom allocators make manual memory management a breeze. Zig has a debug allocator that +maintains memory safety in the face of use-after-free and double-free. It automatically +detects and prints stack traces of memory leaks. There is an arena allocator so that you can +bundle any number of allocations into one and free them all at once rather than manage +each allocation independently. Special-purpose allocators can be used to improve performance +or memory usage for any particular application's needs. + +[1]: Actually there is a string concatenation operator (generally an array concatenation operator), but it only works at compile time, so it still doesn't do any runtime heap allocation. + +# First-class support for no standard library + +As hinted above, Zig has an entirely optional standard library. Each std lib API only gets compiled +into your program if you use it. Zig has equal support for either linking against libc or +not linking against it. Zig is friendly to bare-metal and high-performance development. + +It's the best of both worlds; for example in Zig, WebAssembly programs can both use +the normal features of the standard library, and still result in the tiniest binaries when +compared to other programming languages that support compiling to WebAssembly. + +# A Portable Language for Libraries + +One of the holy grails of programming is code reuse. Sadly, in practice, we find ourselves re-inventing the wheel many times over again. Often it's justified. + + * If an application has real-time requirements, then any library that uses garbage collection or any other non-deterministic behavior is disqualified as a dependency. + * If a language makes it too easy to ignore errors, and thus hard to verify that a library correctly handles and bubbles up errors, it can be tempting to ignore the library and re-implement it, knowing that one handled all the relevant errors correctly. Zig is designed such that the laziest thing a programmer can do is handle errors correctly, and thus one can be reasonably confident that a library will properly bubble errors up. + * Currently it is pragmatically true that C is the most versatile and portable language. Any language that does not have the ability to interact with C code risks obscurity. Zig is attempting to become the new portable language for libraries by simultaneously making it straightforward to conform to the C ABI for external functions, and introducing safety and language design that prevents common bugs within the implementations. + +# A Package Manager and Build System for Existing Projects + +Zig is a toolchain in addition to a programming language. It comes with a +[build system and package manager](/learn/build-system/) that are useful even +in the context of a traditional C/C++ project. + +Not only can you write Zig code instead of C or C++ code, but you can use Zig +as a replacement for autotools, cmake, make, scons, ninja, etc. And on top of +this, it provides a package manager for native dependencies. This build system +is appropriate even if the entirety of a project's codebase is in C or C++. +For example, by +[porting ffmpeg to the zig build system](https://github.com/andrewrk/ffmpeg), +it becomes possible to compile ffmpeg on any supported system for any supported +system using only a [50 MiB download of zig](/download/). For open source +projects, this streamlined ability to build from source - and even +cross-compile - can be the difference between gaining or losing valuable +contributors. + +System package managers such as apt-get, pacman, homebrew, and others are +instrumental for end user experience, but they can be insufficient for the +needs of developers. A language-specific package manager can be the difference +between having no contributors and having many. For open source projects, the +difficulty of getting the project to build at all is a huge hurdle for +potential contributors. For C/C++ projects, having dependencies can be fatal, +especially on Windows, where there is no package manager. Even when just +building Zig itself, most potential contributors have a difficult time with the +LLVM dependency. Zig offers a way for projects to depend on native libraries +directly - without depending on the users' system package manager to have the +correct version available, and in a way that is practically guaranteed to +successfully build projects on the first try regardless of what system is being +used and independent of what platform is being targeted. + +**Other languages have package managers but they do not eliminate pesky system +dependencies like Zig does.** + +Zig can replace a project's build system with a reasonable language using +a declarative API for building projects, that also provides package management, +and thus the ability to actually depend on other C libraries. The ability to +have dependencies enables higher level abstractions, and thus the proliferation +of reusable high-level code. + +# Simplicity + +C++, Rust, and D have such a large number of features that they can be distracting from the actual meaning of the application you are working on. One finds oneself debugging one's knowledge of the programming language instead of debugging the application itself. + +Zig has no macros yet is still powerful enough to express complex programs in a +clear, non-repetitive way. Even Rust has macros with special cases like +`format!`, which is implemented in the compiler itself. Meanwhile in Zig, the +equivalent function is implemented in the standard library with no special case +code in the compiler. + +# Tooling + +Zig can be downloaded from [the downloads section](/download/). Zig provides +binary archives for Linux, Windows, and macOS. The following describes what you +get with one of these archives: + +* installed by downloading and extracting a single archive, no system configuration needed +* statically compiled so there are no runtime dependencies +* supports using LLVM for optimized release builds while using Zig's custom backends for faster compilation performance +* additionally supports a backend for outputting C code +* out of the box cross-compilation to most major platforms +* ships with source code for libc that will be dynamically compiled when needed for any supported platform +* includes build system with concurrency and caching +* compiles C and C++ code with libc support +* drop-in GCC/Clang command line compatibility with `zig cc` +* Windows resource compiler diff --git a/content/pl-PL/zsf.smd b/content/pl-PL/zsf.smd new file mode 100644 index 000000000..82ce4715f --- /dev/null +++ b/content/pl-PL/zsf.smd @@ -0,0 +1,91 @@ +--- +.title = "Zig Software Foundation", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "ZSF", +}, +--- +# Sponsoring the Zig Software Foundation + +Please consider a recurring donation. It takes ongoing labor to maintain and support high-quality software! + +```=html +
+ Donate + + + +
+``` + + +# Mission statement +The mission of the Zig Software Foundation is to promote, protect, and advance the Zig programming language, to support and facilitate the growth of a diverse and international community of Zig programmers, and to provide education and guidance to students, teaching the next generation of programmers to be competent, ethical, and to hold each other to high standards. + +**ZSF is a 501(c)(3) non-profit corporation.** Finances, meeting minutes, and other details are [available to the public](https://drive.google.com/drive/folders/1ucHARxVbhrBbuZDbhrGHYDTsYAs8_bMH?usp=sharing). + +# Board members + +- [Andrew Kelley](https://andrewkelley.me/) (President) +- [Josh Wolfe](https://github.com/thejoshwolfe/) (Secretary) +- [Mason Remaley](https://www.masonremaley.com/) (Treasurer) + +# Sponsorship + +By donating to ZSF, you are funding development of the Zig Programming Language and its ecosystem, which in turn benefits the greater open source community. Zig community members have landed bug fixes in [LLVM](https://llvm.org/), [Wine](https://winehq.org/), [QEMU](https://qemu.org/), [musl libc](https://musl.libc.org/), [GDB](https://www.gnu.org/software/gdb/) and others. + +ZSF is a small organization and makes efficient use of monetary resources. The plan is to keep it that way, but we do want to turn our unpaid volunteers into paid maintainers to help merge pull requests and make swifter progress towards 1.0. The whole point of ZSF being non-profit is to benefit people. We're trying to get open source maintainers paid for their time. + +# Donation information +Here's useful information to donate through means other than GitHub Sponsors. +Make sure to check your local law to see if you can deduct donations from your taxes. + +## EIN +84-5105214 + +## Address +Zig Software Foundation +1632 1st Ave #21385 +New York, NY 10028 + +## Additional donation methods supported +- [Every](https://www.every.org/zig-software-foundation-inc/) +- [GitHub Sponsors](https://github.com/sponsors/ziglang) +- [Benevity](https://benevity.com) (recommended if your employer matches donations!) +- Bank transfers (including from outside of the US, contact us for more info) +- Physical checks (see the snail mail address listed above) +- [Wise](https://wise.com) + +**Please don't hesitate to contact us at donations@ziglang.org if you have questions or specific needs.** + +# Corporate sponsors + +## Monetary donations +The following companies are providing direct financial support to the Zig Software foundation by donating more than $1000/mo. +[]($code.language('=html').siteAsset('corporate-sponsors.html')) diff --git a/i18n/pl-PL.ziggy b/i18n/pl-PL.ziggy new file mode 100644 index 000000000..90ed55cdf --- /dev/null +++ b/i18n/pl-PL.ziggy @@ -0,0 +1,28 @@ +.back = "← Wstecz do: ", +// index.shtml +.community = "Dołącz do społeczności", +.source = "Źródła", +.get_started = "Rozpocznij", +.latest_release = "Ostatnie wydanie:", +.documentation = "Dokumentacja", +.changes = "Zmiany", +.overview = "Przegląd", +.code_samples = "Więcej przykładów", +.all_communities = "Zobacz wszystkie społeczności", +.learn_more = "Więcej informacji", +.github_sponsors_update_frequency = "Uaktualniamy tę sekcję codziennie.", +// learn.shtml +.version_unstable = "Niestabilna", +.version_latest_stable = "Ostatnia stabilna", +// download.shtml +.release_notes = "Uwagi do wydania", +.language_reference = "Opis języka", +.std_docs = "Dokumentacja biblioteki standardowej", +.download_source = "Źródła", +.download_os = "System operacyjny", +.download_arch = "Architektura", +.download_filename = "Nazwa pliku", +.download_sig = "Sygnatura", +.download_size = "Rozmiar", +// locale.shtml +.languages_menu = "Ta strona jest dostępna również w innych językach:",