diff --git a/content/fr-FR/download.smd b/content/fr-FR/download.smd new file mode 100644 index 000000000..00686773e --- /dev/null +++ b/content/fr-FR/download.smd @@ -0,0 +1,24 @@ +--- +.title = "Télécharger", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "download.shtml", +.custom = { + "mobile_menu_title": "Télécharger", + "OSs": ["Windows", "macOS", "Linux", "FreeBSD", "NetBSD"], +}, +--- + +# Versions +Vous pouvez également [installer Zig depuis un gestionnaire de paquets](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager). + +Il existe une [version JSON de cette page]($link.siteAsset('download/index.json')). + +Les fichiers sont signés avec [minisign](https://jedisct1.github.io/minisign/) en utilisant cette clé publique : + +``` +RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U +``` + +> # [Téléchargement automatique ?]($block) +> Si vous automatisez le téléchargement de Zig, vous pourriez vous renseigner sur les [miroirs communautaires](/download/community-mirrors) pour éviter les coupures et diminuer nos coûts de bande passante. diff --git a/content/fr-FR/download/community-mirrors.smd b/content/fr-FR/download/community-mirrors.smd new file mode 100644 index 000000000..b8a7fad20 --- /dev/null +++ b/content/fr-FR/download/community-mirrors.smd @@ -0,0 +1,89 @@ +--- +.title = "Mirroirs communautaires", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "download/community-mirrors.shtml", +.alternatives = [{ + .name = "list", + .layout = "download/community-mirrors-list.shtml", + .output = "/download/community-mirrors.txt", +}], +.custom = { "mobile_menu_title": "Mirrors" }, +--- +Si vous mettez en place un téléchargement automatique de Zig, comme une intégration continue, l'utilisation de miroirs communautaires peut être plus intéréssante qu'un téléchargement depuis ziglang.org. +ziglang.org n'offre aucune garantie d'accessibilité ou de vitesse de téléchargement et peut donc conduire à des échecs ponctuels de téléchargement ou des ralentissements. +De fait, une intégration continue qui télécharge directement depuis ziglang.org contribue aux problèmes d'accessibilité et de téléchargement. +En effet, ce site est [hébergé de manière intentionnelle sur un seul ordinateur](/news/migrate-to-self-hosting). + +Il est donc souvent judicieux de récupérer Zig depuis l'un des nombreux miroirs maintenus par la communauté. +Ces miroirs ne sont pas officiellement approuvés par la Fondation Logicielle Zig, mais ils peuvent être utilisés sans risques de sécurité grâce aux signature des archives. +Aucun miroir individuel ne garantit un accessibilité ou une vitesse minimale, donc utiliser tous les miroirs disponibles pour de l'intégration continue peut significativement améliorer l'accessibilité en pratique. + +> # [Attention]($block) +> Les miroirs communautaires ne sont pas officiellement approuvés ni soutenus par la Fondation Logicielle Zig. +> Ils peuvent en théorie contenir des binaires malveillants. +> Si vous les utilisez, vous **devez** vérifier la signature minisign de chaque archive que vous téléchargez avec la clé publique de la ZSF, disponible sur [la page de téléchargement](/download). + +## Action GitHub +Si vous utilisez les Actions GitHub, vous pourriez être intéressé par l'Action [mlugg/setup-zig](https://github.com/marketplace/actions/setup-zig-compiler), +bien que ce ne soit pas un projet officiel ZSF. +Elle permet d'installer une version Zig de votre choix depuis un miroir communautaire et sauvegarde votre cache Zig entre les exécutions pour accélérer les compilations suivantes. + + +## Utilisation des Miroirs +La liste des miroirs communautaires est disponible dans un fichier texte ASCII séparé par des retours à la ligne sur https://ziglang.org/download/community-mirrors.txt. +Il est recommandé de récupérer cette liste et d'essayer les miroirs dans un ordre aléatoire (pour éviter de mettre une charge excessive sur un seul miroir et donc de ralentir l'accès pour tout le monde). +Chaque archive Zig est associée à une signature [minisign](https://jedisct1.github.io/minisign/), qui peut être téléchargée depuis les miroirs. +Pour chaque archive sur un miroir, veillez à télécharger sa signature et vérifier l'archive avec celle-ci. +Sans cela, vous êtes théoriquement vulnérable à des miroirs malveillants hébergeant des archives modifiées. +La stratégie recommandée peut être résumée comme suit: + +```python +pubkey = "(copy this from https://ziglang.org/download)" +tarball_name = "zig-x86_64-linux-0.14.1.tar.xz" +# To improve uptime, optionally cache this GET: +mirrors = http_get("https://ziglang.org/download/community-mirrors.txt") +# ASCII-encoded, one mirror per line, newlines are LF, there is a trailing newline. +shuffled = shuffle_lines(mirrors) +for mirror_url in shuffled: + tarball = http_get(f"{mirror_url}/{tarball_name}?source=my_automation_name") + if success: + # NEVER SKIP THIS STEP. The signature must be verified before the tarball is deemed safe. + signature = http_get(f"{mirror_url}/{tarball_name}.minisig?source=my_automation_name") + if success and minisign_verify(tarball, signature, pubkey): + print("Successfully fetched Zig 0.14.1!") +``` + +Comme l'accessibilité de ziglang.org n'est pas garantie, le fichier community-mirrors.txt peut parfois être inaccessible. +Il est donc possible de le mettre en cache pour éviter les interruptions quand ziglang.org est inacessible. +Il est recommandé de le re-télécharger quotidiennement. +Les miroirs peuvent être ajoutés ou supprimés une fois par mois selon l'évolution de l'écosystème. Il est donc primordial de re-récupérer périodiquement la liste des miroirs. +Voici la méthode recommandée pour télécharger les archives Zig : + +- La liste des miroirs est disponible à https://ziglang.org/download/community-mirrors.txt. + - Son accessibilité n'est pas garantie, il peut donc être utile de la mettre en cache. +- La liste des miroirs contient des URL en ASCII, séparées par des retours à la ligne (ASCII LF 0x20). La dernière ligne du fichier est un retour à la ligne. +Il n'y a pas d'autres espaces, ni de lignes vides. +- Les miroirs doivent supporter HTTPS. Chaque ligne dans le fichier commence par "https://". +- L'accessibilité des miroirs n'est pas garantie donc si un miroir est inaccessible, il est recommandé d'essayer le suivant. En général, le premier suffit mais un parcours aléatoire de la liste est conseillé. +Si aucun miroir n'est accessible, vous pouvez essayer ziglang.org en dernier recours. +- Pour télécharger une archive depuis un miroir, il faut effecture une requête GET vers "miroir/nomdefichier", où "miroir" est l'URL du miroir, +et "nomdefichier" est le nom de base de l'archive correspondante sur ziglang.org (par ex. zig-x86_64-linux-0.14.1.tar.xz). + - Il est fortement conseillé d'inclure dans la requête un paramètre nommé source contenant une chaîne indiquant l'expédititeur. + Par exemple, l'Action GitHub mlugg/setup-zig le défiint comme provenant de ?source=github-mlugg-setup-zig. + - Les archives sources, bootstrap, et binaires sont disponibles depuis tous les miroirs listés, ainsi que leurs signatures minisign. + - Les archives binaires pour les versions récentes de Zig sont de la forme zig-x86_64-linux-0.14.1.tar.xz. + - Si un miroir répond avec un code de statut HTTP autre que 200 OK : + - `503 Unavailable` peut être du à une maintenance programmée. + - `429 Too Many Requests` peut indiquer que le débit a été limité temporairement.. + - `404 Not Found` est autorisé pour les versions Zig 0.5.0 ou antérieures, ou les versions de développement antérieures à la dernière version actuelle. + - Sinon, n'hésitez pas à [signaler le problème](https://github.com/ziglang/www.ziglang.org/issues/new). + +La Fondation Logicielle Zig ne peut garantir la sécurité d'aucun miroir. Après chaque téléchargement d'une archive, il est **impératif** de télécharger sa signature minisign +(en rajoutant ".minisign" au nom de fichier) et la vérifier avec la clé publique de la ZSF, accessible depuis ziglang.org/download. **Ne jamais sauter cette étape**. + +Si un miroir renvoie `200 OK` mais que la validation de signature échoue, n'hésitez pas à [signaler le problème ](https://github.com/ziglang/www.ziglang.org/issues/new). + +## Héberger un Miroir +Si vous êtes intéressé pour héberger un miroir, veuillez consulter la [documentation dans le dépôt www.ziglang.org](https://github.com/ziglang/www.ziglang.org/blob/main/MIRRORS.md). +Merci d'aider à améliorer et décentraliser l'écosystème Zig ! diff --git a/content/fr-FR/index.smd b/content/fr-FR/index.smd new file mode 100644 index 000000000..11c663b85 --- /dev/null +++ b/content/fr-FR/index.smd @@ -0,0 +1,63 @@ +--- +.title = "Accueil", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "index.shtml", +.custom = { + "mobile_menu_title": "Accueil", +}, +--- + +[]($section.id("slogan")) +Zig est un langage de programmation généraliste et un ensemble d'outils pour maintenir des logiciels **robustes**, **optimaux** et **réutilisables**. + +[]($section.id("features")) +## ⚡ Un langage simple +Concentrez-vous sur le débogage de votre application plutôt que sur le débogage du langage lui-même. + +- Pas de structure de contrôle masquée. +- Pas d'allocation mémoire cachée. +- Pas de préprocesseur, pas de macros. + +## ⚡ Comptime +Cette nouvelle approche de la métaprogrammation est basée sur l'exécution de code pendant la compilation et l'évaluation "paresseuse". + +- Toutes fonctions peuvent être appelées à la compilation. +- Pas de surcoût à l'exécution pour les types et les valeurs. +- Elle émule l'architecture cible. + +## ⚡ Maintenance avec Zig +Améliorez progressivement votre base de code C/C++/Zig. + +- Zig peut être utilité comme un compilateur C/C++ sans dépendance et prêt à l'emploi supportant la compilation croisée dès le départ. +- `zig build` offre un environnement de développement cohérent sur toutes les plateformes. +- Ajoutez Zig à vos projets C/C++ pour profiter de la riche bibliothèque standard+. + +# [Communauté]($section.id("community").attrs("section-title")) + +## [Une communauté décentralisée]($section.id("decentralized")) +Chacun est libre de créer et de maintenir son propre espace de rencontre. +Aucun n'est "officiel" mais chaque lieu de rassemblement a ses propres règles et modérateurs. + +## [Développement]($section.id("main-development")) +Le dépôt Zig se trouve à [https://github.com/ziglang/zig](https://github.com/ziglang/zig), ainsi que le suivi des problèmes et les suggestions. +L'acception du [code de conduite](https://github.com/ziglang/zig/blob/master/.github/CODE_OF_CONDUCT.md) de Zig est nécessaire pour toutes contribution. + +# [Fondation Logicielle Zig]($section.id("zsf").attrs("section-title")) + +## Une société à but non lucratif 501(c)(3). + +La Fondation Logicielle Zig (ZSF en anglais) est une société à but non lucratif fondée en 2020 par Andrew Kelley, le créateur de Zig, pour soutenir le développement du langage. +Actuellement, la ZSF est en mesure d'offrir une rémunération à des tarifs compétitifs pour un nombre restreint de contributeurs principaux. +Nous espérons pouvoir étendre cette offre à davantage de contributeurs à l'avenir. + +La Fondation Logicielle Zig est financée par des dons. + +# [Sponsors]($section.id("sponsors").attrs("section-title")) + +## [Sponsors Corporatifs]($section.id("corporate-sponsors")) +Les entreprises suivantes fournissent un soutien financier direct à la Fondation Logicielle Zig. + +## [Sponsors GitHub]($section.id("github-sponsors")) +Grâce aux personnes qui [sponsorisent Zig]($link.page('zsf')), le projet est responsable seulement devant la communauté open source et non des actionnaires. +En particulier, ces personnes fantastiques sponsorisent Zig pour 200 $/mois ou plus : diff --git a/content/fr-FR/learn/build-system.smd b/content/fr-FR/learn/build-system.smd new file mode 100644 index 000000000..0b35b559f --- /dev/null +++ b/content/fr-FR/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 unwieldy, 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-to-system-libraries')) + +For satisfying library dependencies, there are two choices: + +1. Provide these libraries via the Zig Build System + (see [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/fr-FR/learn/getting-started.smd b/content/fr-FR/learn/getting-started.smd new file mode 100644 index 000000000..c323fa0f2 --- /dev/null +++ b/content/fr-FR/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/fr-FR/learn/index.smd b/content/fr-FR/learn/index.smd new file mode 100644 index 000000000..951920d18 --- /dev/null +++ b/content/fr-FR/learn/index.smd @@ -0,0 +1,17 @@ +--- +.title = "Documentation", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "learn.shtml", +.custom = { + "mobile_menu_title": "Learn", +}, +--- + +# [Documentation]($section.id('learn')) +Cette section liste la documentation utile pour démarrer de zéro et parvenir à comprendre la philosophie de Zig. + + +## [Guides]($section.id('guides')) +Cette section sera un jour dans la documentation de la librairie standard. Pour le moment, elle est accessible ici. + diff --git a/content/fr-FR/learn/overview.smd b/content/fr-FR/learn/overview.smd new file mode 100644 index 000000000..2417b6adf --- /dev/null +++ b/content/fr-FR/learn/overview.smd @@ -0,0 +1,629 @@ +--- +.title = "Overview", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Overview", +}, +--- +# Feature Highlights +## [Small, simple language]($heading.id('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]($heading.id('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](https://ziglang.org/documentation/master/#Debug) | [ReleaseSafe](https://ziglang.org/documentation/master/#ReleaseSafe) | [ReleaseFast](https://ziglang.org/documentation/master/#ReleaseFast) | [ReleaseSmall](https://ziglang.org/documentation/master/#ReleaseSmall) | +|-----------|-------|-------------|-------------|--------------| +Optimizations - improve speed, harm debugging, harm compile time | | On | On | On | +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. + +- All Zig code lives in one compilation unit, optimized together. +- Carefully chosen illegal behavior. For example, in Zig both signed and unsigned integers have illegal 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. +- The standard library provides essential data structures such as hash maps and array lists, whereas in C it is tempting to use linked lists for simplicity. +- Advanced CPU features are enabled by default, unless [cross-compiling](#cross-compiling-is-a-first-class-use-case). + +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]($heading.id('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]($heading.id("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')) + +The standard library's DebugAllocator uses this technique to report leaks and double frees. + +## 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]($heading.id('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]($heading.id('integration-with-c-libraries-without-ffibindings')) + +[@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]($heading.id('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]($heading.id('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]($heading.id('zig-ships-with-libc')) + +You can find the available libc targets with `zig targets`: +``` +... +.libc = .{ + "arc-linux-gnu", + "arm-freebsd-eabihf", + "arm-linux-gnueabi", + "arm-linux-gnueabihf", + "arm-linux-musleabi", + "arm-linux-musleabihf", + "arm-netbsd-eabi", + "arm-netbsd-eabihf", + "armeb-linux-gnueabi", + "armeb-linux-gnueabihf", + "armeb-linux-musleabi", + "armeb-linux-musleabihf", + "armeb-netbsd-eabi", + "armeb-netbsd-eabihf", + "thumb-linux-musleabi", + "thumb-linux-musleabihf", + "thumb-windows-gnu", + "thumbeb-linux-musleabi", + "thumbeb-linux-musleabihf", + "aarch64-freebsd-none", + "aarch64-linux-gnu", + "aarch64-linux-musl", + "aarch64-macos-none", + "aarch64-netbsd-none", + "aarch64-windows-gnu", + "aarch64_be-linux-gnu", + "aarch64_be-linux-musl", + "aarch64_be-netbsd-none", + "csky-linux-gnueabi", + "csky-linux-gnueabihf", + "hexagon-linux-musl", + "loongarch64-linux-gnu", + "loongarch64-linux-gnusf", + "loongarch64-linux-musl", + "loongarch64-linux-muslsf", + "m68k-linux-gnu", + "m68k-linux-musl", + "m68k-netbsd-none", + "mips-linux-gnueabi", + "mips-linux-gnueabihf", + "mips-linux-musleabi", + "mips-linux-musleabihf", + "mips-netbsd-eabi", + "mips-netbsd-eabihf", + "mipsel-linux-gnueabi", + "mipsel-linux-gnueabihf", + "mipsel-linux-musleabi", + "mipsel-linux-musleabihf", + "mipsel-netbsd-eabi", + "mipsel-netbsd-eabihf", + "mips64-linux-gnuabi64", + "mips64-linux-gnuabin32", + "mips64-linux-muslabi64", + "mips64-linux-muslabin32", + "mips64el-linux-gnuabi64", + "mips64el-linux-gnuabin32", + "mips64el-linux-muslabi64", + "mips64el-linux-muslabin32", + "powerpc-freebsd-eabihf", + "powerpc-linux-gnueabi", + "powerpc-linux-gnueabihf", + "powerpc-linux-musleabi", + "powerpc-linux-musleabihf", + "powerpc-netbsd-eabi", + "powerpc-netbsd-eabihf", + "powerpc64-freebsd-none", + "powerpc64-linux-gnu", + "powerpc64-linux-musl", + "powerpc64le-freebsd-none", + "powerpc64le-linux-gnu", + "powerpc64le-linux-musl", + "riscv32-linux-gnu", + "riscv32-linux-musl", + "riscv64-freebsd-none", + "riscv64-linux-gnu", + "riscv64-linux-musl", + "s390x-linux-gnu", + "s390x-linux-musl", + "sparc-linux-gnu", + "sparc-netbsd-none", + "sparc64-linux-gnu", + "sparc64-netbsd-none", + "wasm32-wasi-musl", + "x86-freebsd-none", + "x86-linux-gnu", + "x86-linux-musl", + "x86-netbsd-none", + "x86-windows-gnu", + "x86_64-freebsd-none", + "x86_64-linux-gnu", + "x86_64-linux-gnux32", + "x86_64-linux-musl", + "x86_64-linux-muslx32", + "x86_64-macos-none", + "x86_64-netbsd-none", + "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]($heading.id('zig-build-system')) + +Zig comes with a build system, so you don't need make, cmake, or anything like that. +``` +$ zig init +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 +``` + +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 + test Run unit tests + +General Options: + -p, --prefix [path] Where to install files (default: zig-out) + --prefix-lib-dir [path] Where to install libraries + --prefix-exe-dir [path] Where to install executables + --prefix-include-dir [path] Where to install C header files + + --release[=mode] Request release mode, optionally specifying a + preferred optimization mode: fast, safe, small + + -fdarling, -fno-darling Integration with system-installed Darling to + execute macOS programs on Linux hosts + (default: no) + -fqemu, -fno-qemu Integration with system-installed QEMU to execute + foreign-architecture programs on Linux hosts + (default: no) + --glibc-runtimes [path] Enhances QEMU integration by providing glibc built + for multiple foreign architectures, allowing + execution of non-native programs that link with glibc. + -frosetta, -fno-rosetta Rely on Rosetta to execute x86_64 programs on + ARM64 macOS hosts. (default: no) + -fwasmtime, -fno-wasmtime Integration with system-installed wasmtime to + execute WASI binaries. (default: no) + -fwine, -fno-wine Integration with system-installed Wine to execute + Windows programs on Linux hosts. (default: no) + + -h, --help Print this help and exit + -l, --list-steps Print available steps + --verbose Print commands before executing them + --color [auto|off|on] Enable or disable colored error messages + --prominent-compile-errors Buffer compile errors and display at end + --summary [mode] Control the printing of the build summary + all Print the build summary in its entirety + new Omit cached steps + failures (Default) Only print failed steps + none Do not print the build summary + -j Limit concurrent jobs (default is to use all CPU cores) + --maxrss Limit memory usage (default is to use available memory) + --skip-oom-steps Instead of failing, skip steps that would exceed --maxrss + --fetch Exit after fetching dependency tree + --watch Continuously rebuild when source files are modified + --fuzz Continuously search for unit test failures + --debounce Delay before rebuilding after changed file detected + -fincremental Enable incremental compilation + -fno-incremental Disable incremental compilation + +Project-Specific Options: + -Dtarget=[string] The CPU architecture, OS, and ABI to build for + -Dcpu=[string] Target CPU features to add or subtract + -Dofmt=[string] Target object format + -Ddynamic-linker=[string] Path to interpreter on the target system + -Doptimize=[enum] Prioritize performance, safety, or binary size + Supported Values: + Debug + ReleaseSafe + ReleaseFast + ReleaseSmall + +System Integration Options: + --search-prefix [path] Add a path to look for binaries, libraries, headers + --sysroot [path] Set the system root directory (usually /) + --libc [file] Provide a file which specifies libc paths + + --system [pkgdir] Disable package fetching; enable all integrations + -fsys=[name] Enable a system integration + -fno-sys=[name] Disable a system integration + + Available System Integrations: Enabled: + (none) - + +Advanced Options: + -freference-trace[=num] How many lines of reference trace should be shown per compile error + -fno-reference-trace Disable reference trace + -fallow-so-scripts Allows .so files to be GNU ld scripts + -fno-allow-so-scripts (default) .so files must be ELF files + --build-file [file] Override path to build.zig + --cache-dir [path] Override path to local Zig cache directory + --global-cache-dir [path] Override path to global Zig cache directory + --zig-lib-dir [arg] Override path to Zig lib directory + --build-runner [file] Override path to build runner + --seed [integer] For shuffling dependency traversal order (default: random) + --debug-log [scope] Enable debugging the compiler + --debug-pkg-config Fail if unknown pkg-config flags encountered + --debug-rt Debug compiler runtime libraries + --verbose-link Enable compiler debug output for linking + --verbose-air Enable compiler debug output for Zig AIR + --verbose-llvm-ir[=file] Enable compiler debug output for LLVM IR + --verbose-llvm-bc=[file] Enable compiler debug output for LLVM BC + --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 codebase are belong to us. +Run `zig build test` to run the tests. +``` + +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) + +## 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.14.0](https://ziglang.org/download/0.14.0/release-notes.html#Target-Support) + +## 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/fr-FR/learn/samples.smd b/content/fr-FR/learn/samples.smd new file mode 100644 index 000000000..6d7d161bd --- /dev/null +++ b/content/fr-FR/learn/samples.smd @@ -0,0 +1,49 @@ +--- +.title = "Exemples", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "Samples", + "toc": true, +}, +--- + +# [Hello world]($heading.id('hello')) +Un exemple minimal affichant "Hello world". + +[]($code.language('=html').buildAsset("samples/hello-world.zig")) + +# [Utilisation de librairies externes]($heading.id('ext')) +Toutes les fonctions dans API système peuvent être appellées de cette manière. Il n'y a pas besion d'interface spécifique. + +[]($code.language('=html').buildAsset("samples/windows-msgbox.zig")) + +# [Détection de fuites de mémoire]($heading.id('leak')) +Avec `std.heap.GeneralPurposeAllocator`, on peut suivre les libérations mémoire en double et les fuites de mémoires. + +[]($code.language('=html').buildAsset("samples/memory-leak.zig")) + + +# [Interopérabilité avec le C ]($heading.id('c-interop')) + +Voici une example d'utilisation d'un header en C et d'un linkage avec libc et raylib. + +[]($code.language('=html').buildAsset("samples/c-interop.zig")) + + +# [Zigg Zagg]($heading.id('zigg-zagg')) +Zig est *optimisé* pour les entretiens d'embauches (en fait, non). + +[]($code.language('=html').buildAsset("samples/ziggzagg.zig")) + + +# [Types génériques]($heading.id('generic')) +En Zig, les types sont des valeures "comptime" et l'on peut utiliser dese fonctions qui retournent un type pour implémenter des algorithmes génériques, mais aussi des structures de données. +Par exemple, voici une implémentation simple d'une file d'attente avec des tests. + +[]($code.language('=html').buildAsset("samples/generic-type.zig")) + +# [Utilisation de cURL depuis Zig]($heading.id('curl')) + +[]($code.language('=html').buildAsset("samples/curl.zig")) diff --git a/content/fr-FR/learn/tools.smd b/content/fr-FR/learn/tools.smd new file mode 100644 index 000000000..93ee983df --- /dev/null +++ b/content/fr-FR/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/fr-FR/learn/why_zig_rust_d_cpp.smd b/content/fr-FR/learn/why_zig_rust_d_cpp.smd new file mode 100644 index 000000000..98b9066cb --- /dev/null +++ b/content/fr-FR/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/fr-FR/news/announcing-community-mirrors.smd b/content/fr-FR/news/announcing-community-mirrors.smd new file mode 100644 index 000000000..6d4ccb8f5 --- /dev/null +++ b/content/fr-FR/news/announcing-community-mirrors.smd @@ -0,0 +1,50 @@ +--- +.title = "Community Mirrors: A Better Way To Download Zig", +.date = "2025-06-30", +.author = "", +.layout = "news-page.shtml", +.custom = { + "mobile_menu_title": "Community Mirrors", +} +--- + +With Zig being in active development, it's pretty common to need to download new Zig compiler releases, particularly if you track the "master" pre-releases +instead of tagged releases. There are also some situations where you might want to re-fetch the *same* Zig version, such as stateless CI runs. This brings us to +what might seem like a trivial problem: *how do you actually download Zig*? + +The obvious way to do this has always been to download the tarball from ziglang.org. However, this website is hosted on an [intentionally simple +configuration][self-hosted-website], with the intention of optimizing overall efficiency rather than expending huge amounts of resources on web hosting. So, to +avoid excessive load, we've previously publicly recommended that people use mirrors to download Zig where possible, and we [cryptographically sign our +tarballs][minisign] to make this approach more viable. The official Zig website doesn't provide any uptime or bandwidth guarantees, so download mirrors actually +*directly benefit users* by potentially improving availability and speed. + +There's just one problem: so far, there haven't really been any mirrors available to use. This began to change last year, when the [setup-zig][setup-zig] +project became the first widely-used project to actually utilize download mirrors for Zig tarballs. However, they weren't easily accessible to other projects, +who didn't want to take on the burden of maintaining their own mirror lists. + +**To solve this, we're introducing Community Mirrors.** + +The idea is simple. Instead of downloading tarballs from ziglang.org, automations should instead fetch from it a small text file, maintained by the Zig core +team, which contains URLs of community-run mirrors. This takes the burden off of others to maintain their own lists of mirrors, so makes it simpler for tools to +*efficiently* download Zig. We also have some [nifty automated testing][check-mirrors] to make sure that all of the mirrors are behaving, so there's no risk of +problems with a mirror going unnoticed. + +The Download page now contains a link to the new [Community Mirrors][mirrors] page, which explains how to use the mirrors in your code -- please check it out if +you've written code which downloads Zig. The process boils down to fetching the mirror list (which is just plaintext ASCII with one URL per line), shuffling it, +and attempting each mirror in turn before falling back to ziglang.org. **You must verify the cryptographic signature of tarballs downloaded from mirrors** -- +because they are hosted by third parties, a mirror could theoretically serve you malicious or corrupted files. + +If you have the resources and time, a great way to contribute to the Zig ecosystem is now to [host your own mirror][host-mirror]. You don't need any specific +experience or permission: just check out that link. Hosting a download mirror helps to keep Zig accessible as it grows in popularity, and shouldn't need too +much ongoing maintenance. + +That's all for today. Thanks folks! + +Matthew + +[self-hosted-website]: /news/migrate-to-self-hosting/ +[minisign]: https://jedisct1.github.io/minisign/ +[setup-zig]: https://github.com/marketplace/actions/setup-zig-compiler +[check-mirrors]: https://github.com/ziglang/www.ziglang.org/actions/runs/15976134096#summary-45058979620 +[mirrors]: /download/community-mirrors/ +[host-mirror]: https://github.com/ziglang/www.ziglang.org/blob/main/MIRRORS.md diff --git a/content/fr-FR/news/index.smd b/content/fr-FR/news/index.smd new file mode 100644 index 000000000..27b379c6c --- /dev/null +++ b/content/fr-FR/news/index.smd @@ -0,0 +1,16 @@ +--- +.title = "Actualité", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "news-list.shtml", +.alternatives = [{ + .name = "rss", + .layout = "news-list.xml", + .output = "/news/index.xml", +}], +.custom = { + "mobile_menu_title": "News", +}, +--- + +Cette page est malheureusement en anglais pour le moment. Elle est disponible en [flux RSS](https://ziglang.org/news/index.xml). diff --git a/content/fr-FR/news/migrate-to-self-hosting/aws-breakdown.png b/content/fr-FR/news/migrate-to-self-hosting/aws-breakdown.png new file mode 100644 index 000000000..52d094c26 Binary files /dev/null and b/content/fr-FR/news/migrate-to-self-hosting/aws-breakdown.png differ diff --git a/content/fr-FR/news/migrate-to-self-hosting/aws-expenses.png b/content/fr-FR/news/migrate-to-self-hosting/aws-expenses.png new file mode 100644 index 000000000..ef73f461b Binary files /dev/null and b/content/fr-FR/news/migrate-to-self-hosting/aws-expenses.png differ diff --git a/content/fr-FR/news/migrate-to-self-hosting/deploy-after.png b/content/fr-FR/news/migrate-to-self-hosting/deploy-after.png new file mode 100644 index 000000000..24a563111 Binary files /dev/null and b/content/fr-FR/news/migrate-to-self-hosting/deploy-after.png differ diff --git a/content/fr-FR/news/migrate-to-self-hosting/deploy-before.png b/content/fr-FR/news/migrate-to-self-hosting/deploy-before.png new file mode 100644 index 000000000..c81e747ea Binary files /dev/null and b/content/fr-FR/news/migrate-to-self-hosting/deploy-before.png differ diff --git a/content/fr-FR/news/migrate-to-self-hosting/index.smd b/content/fr-FR/news/migrate-to-self-hosting/index.smd new file mode 100644 index 000000000..77992b2da --- /dev/null +++ b/content/fr-FR/news/migrate-to-self-hosting/index.smd @@ -0,0 +1,82 @@ +--- +.title = "Migrating from AWS to Self-Hosting", +.date = "2024-09-12T20:52:45.536Z", +.author = "Andrew Kelley", +.layout = "news-page.shtml", +.custom = { + "mobile_menu_title": "Website Migration", +} +--- + +You often hear this story in tech news: some project got increasingly popular, +so they had to migrate from their simple, one-computer setup to some kind of +autoscaling cloud hosting solution to meet demands. + +The Rust Foundation for example, reports that they spent +[$404,400 on infrastructure costs in 2023](https://foundation.rust-lang.org/static/publications/annual-reports/annual-report-2023.pdf). +That's 88% of ZSF's [entire operating costs in 2024](https://ziglang.org/news/2024-financials/). +It's hard to find the exact number from Python Software Foundation's financials because their infrastructure +costs are sponsored, but suffice to say +[PyPI wheel storage is huge and exponentially growing](https://www.youtube.com/watch?v=HPmefnqirHk): + +![PyPI data storage over time](pypi.png) + +[source](https://py-code.org/stats) + +In this story, however, we take the opposite approach. + +ziglang.org used to be hosted on Amazon S3 + CloudFront, but as it became more +expensive to run due to increased traffic, we have migrated to a one-computer +solution for the website and tarball hosting. + +Our AWS costs over the last 6 years looks like this: + +![](aws-expenses.png "graph of ZSF AWS monthly costs going up") + +Amazon sometimes offers free credits to organizations like ours, but despite +being a non-profit with our primary source of income being unrestricted +donations, we don't like begging for money, especially from Jeff Bezos and his +ilk. We like the idea of increasing overall computing efficiency rather than +externalizing costs onto someone with deep pockets. + +The thing is, ziglang.org is not an essential service. It's not really an +emergency if it goes down, and 99% uptime is perfectly fine for this use case. +The funny thing about that [last 1% of uptime is that it represents 99% of the +costs](https://en.wikipedia.org/wiki/Pareto_principle). + +With that in mind, here is the plan. As traffic to ziglang.org continues to +increase, we will continue to host the website and tarballs on the same €36 +Hetzner instance, perhaps someday upgrading it to a €100-200 beefier machine, +but not more than that. + +If the website is temporarily unavailable because of too much traffic, so be +it. If it gets accidentally DDoS'd by too many people not [properly caching +their CI runs](https://ziggit.dev/t/github-actions-mlugg-setup-zig/4659), so be +it. That's why we sign artifacts with a static public key, so that you can use +mirrors. + +Instead of spending donation money eating these costs which are ultimately due +to inefficient use of computing resources, we push those otherwise hidden costs +onto users of Zig, causing Zig users in general to avoid waste, and then we +have more money to spend on paying contributors for their time. + +So far, so good. We're enjoying instant website deploys rather than waiting 5 +minutes after pushing. + +![Before: 5 minutes](deploy-before.png) + +![After: instant](deploy-after.png) + +Moving forward, we'll look into providing torrent files for releases. In the +meantime, big thanks to [slimsag](https://slimsag.com/) and +[hryx](https://hryx.net/) for [providing mirrors of Zig +releases](https://github.com/mlugg/setup-zig/blob/45d39f8bb4d61ccfb37ea3bd0ad319a5f20e4e77/main.js#L18-L21). +If you want to join them, please submit a pull request to [Setup Zig +Compiler](https://github.com/marketplace/actions/setup-zig-compiler). In any +case, by using this particular GitHub Action that integrates with mirrors, +you'll not only be doing us a favor, but you'll make your own CI more +resilient. + +Happy hacking, + +Andrew diff --git a/content/fr-FR/news/migrate-to-self-hosting/pypi.png b/content/fr-FR/news/migrate-to-self-hosting/pypi.png new file mode 100644 index 000000000..c81cdad56 Binary files /dev/null and b/content/fr-FR/news/migrate-to-self-hosting/pypi.png differ diff --git a/content/fr-FR/zsf.smd b/content/fr-FR/zsf.smd new file mode 100644 index 000000000..52c4c47cb --- /dev/null +++ b/content/fr-FR/zsf.smd @@ -0,0 +1,94 @@ +--- +.title = "Fondation Logicielle Zig", +.author = "", +.date = @date("2024-08-07:00:00:00"), +.layout = "page.shtml", +.custom = { + "mobile_menu_title": "ZSF", +}, +--- + +# Sponsoriser la Fondation Logicielle Zig + +Veuillez envisager un don récurrent. Il faut un travail de fond pour maintenir et développer des logiciels de qualité ! + +```=html +
+ Donate + + + +
+``` + +# Objectif +La mission de la Fondation Logicielle Zig est de promouvoir, protéger et améliorer le langage de programmation Zig, de soutenir et faciliter le développement d'une communauté hétérogène et internationale de programmeurs/programmeuses Zig, et de fournir une éducation et des conseils aux étudiant(e)s, +apprendre à la prochaine génération de programmeurs à être compétent, à avoir une réflexion éthique et à être exigeants. + +**ZSF est une société à but non lucratif 501(c)(3).** Les finances, procès-verbaux de réunions et autres informations sont [accessibles en lignes pour toutes et tous](https://drive.google.com/drive/folders/1ucHARxVbhrBbuZDbhrGHYDTsYAs8_bMH?usp=sharing). + + +# Membres du conseil d'administration + +- [Andrew Kelley](https://andrewkelley.me/) (Président) +- [Josh Wolfe](https://github.com/thejoshwolfe/) (Secrétaire) +- [Mason Remaley](https://www.masonremaley.com/) (Trésorier) + +# Sponsoring +En donnant à ZSF, vous financez le développement du langage de programmation Zig et de son écosystème, ce qui profite à son tour à la plus grande communauté open source. Les membres de la communauté Zig ont apporté des corrections à [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/) et d'autres. + +ZSF est une petite organisation avec une gestion efficace de ses ressources financières. +Nous souhaitons conserver cette approche, mais voulons aussi offrire une rémunération à nos bénévoles pour fusionner les pull requests et progresser plus rapidement vers la version 1.0. +Tout l'intérêt pour ZSF d'être à but non lucratif est donc d'en faire bénéficier les individus. Nous essayons de rémunérer les mainteneurs open source pour leur temps. + +# Informations sur les dons +Voici des informations utiles pour donner par d'autres moyens que GitHub Sponsors. +Certains dons peuvent être déduits des impôts (voir législation en vigueur) + +## EIN +84-5105214 + +## Adresse +Zig Software Foundation +1632 1st Ave #21385 +New York, NY 10028 + +## Autres méthodes de don +- [Every](https://www.every.org/zig-software-foundation-inc/) +- [GitHub Sponsors](https://github.com/sponsors/ziglang) +- [Benevity](https://benevity.com) (recommandé si votre employeur égale les dons !) +- Virements bancaires (y compris depuis l'extérieur des États-Unis, contactez-nous pour plus d'informations) +- Chèques physiques (voir l'adresse postale listée ci-dessus) +- [Wise](https://wise.com) + +**N'hésitez pas à nous contacter à donations@ziglang.org pour toute question ou besoin spécifique.** + +# Sponsors industriels + +## Dons financiers +Les entreprises suivantes fournissent un soutien financier direct à la Fondation Logicielle Zig en donnant plus de 1000 $/mois. +[]($code.language('=html').siteAsset('corporate-sponsors.html')) diff --git a/i18n/fr-FR.ziggy b/i18n/fr-FR.ziggy new file mode 100644 index 000000000..4af1705b5 --- /dev/null +++ b/i18n/fr-FR.ziggy @@ -0,0 +1,28 @@ +.back = "← Retour à", +// index.shtml +.community = "Rejoindre une Communauté", +.source = "Code source", +.get_started = "TUTORIAL", +.latest_release = "Dernière version:", +.documentation = "Documentation", +.changes = "Modifications", +.overview = "Vue d'ensemble", +.code_samples = "Exemples de code", +.all_communities = "Voir toutes les Communautés", +.learn_more = "En savoir plus", +.github_sponsors_update_frequency = "Cette partie est mise à jour quotidiennement.", +// learn.shtml +.version_unstable = "Version non-stable", +.version_latest_stable = "Dernière version stable", +// download.shtml +.release_notes = "Notes des versions", +.language_reference = "Référence", +.std_docs = "Documentation pour la librairie standard", +.download_source = "Code source", +.download_os = "Système d'exploitation", +.download_arch = "Architecture", +.download_filename = "Fichier", +.download_sig = "Signature", +.download_size = "Taille", +// locale.shtml +.languages_menu = "Ce site est aussi disponible dans les langues suivantes :", diff --git a/zine.ziggy b/zine.ziggy index 4f0eb9061..5715e75dc 100644 --- a/zine.ziggy +++ b/zine.ziggy @@ -45,6 +45,12 @@ Multilingual { .content_dir_path = "content/es-AR", }, { + .code = "fr-FR", + .name = "Français", + .site_title = "Le langage de programmation Zig", + .content_dir_path = "content/fr-FR", + }, + { .code = "ru-RU", .name = "Русский", .site_title = "Язык программирования Zig",