From fd6639a17d53e4fc1578b0f52dc8da82a2ecbcc2 Mon Sep 17 00:00:00 2001 From: Arijit Dey Date: Tue, 14 Jan 2025 02:24:23 +0530 Subject: [PATCH] docs: write mdbook docs --- README.md | 67 ------------------------- docs2/.gitignore | 1 + docs2/book.toml | 6 +++ docs2/src/SUMMARY.md | 15 ++++++ docs2/src/compiling.md | 38 ++++++++++++++ docs2/src/installation.md | 40 +++++++++++++++ docs2/src/introduction.md | 36 +++++++++++++ docs2/src/managing-zig-installations.md | 1 + docs2/src/non-trivial-zigverm-root.md | 1 + docs2/src/versioning-in-zigverm.md | 16 ++++++ 10 files changed, 154 insertions(+), 67 deletions(-) create mode 100644 docs2/.gitignore create mode 100644 docs2/book.toml create mode 100644 docs2/src/SUMMARY.md create mode 100644 docs2/src/compiling.md create mode 100644 docs2/src/installation.md create mode 100644 docs2/src/introduction.md create mode 100644 docs2/src/managing-zig-installations.md create mode 100644 docs2/src/non-trivial-zigverm-root.md create mode 100644 docs2/src/versioning-in-zigverm.md diff --git a/README.md b/README.md index e25b93c..1b15619 100644 --- a/README.md +++ b/README.md @@ -16,73 +16,6 @@ Legend: | Linux | 🎉 | 🎉 | 🎉 | ❌ | ❌ | | MacOS | 🎉 | - | 🎉 | - | - | -## Installation - -### For Linux and MacOS (x86_64/aarch64) - -You can use this automated install script which will install zigverm along with the latest version of Zig - -```sh -curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/AMythicDev/zigverm/main/scripts/install.sh | bash -``` - -By default it will create `$HOME/.zigverm` directory as the root folder for zigverm. You can customize -this by setting this by setting the `ZIGVERM_ROOT_DIR` to the directory where you want to install -zigverm. Make sire you add the `ZIGVERM_ROOT_DIR` in your shell config otherwise zigverm would not be able -to locate the installation folder. - -The script will also put the installation directory's `bin` folder to your `$PATH` variable. For -this it will append a line to your `$HOME/.profile` and your shell's rc file. The file for each -shell supported is listed below: - -- Bash: `$HOME/.bashrc` -- Zsh: `$HOME/.zshrc` -- Fish: `$XDG_CONFIG_HOME/fish/config.fish`, if not set then uses `$HOME/.config/fish/config.fish` - -### For Windows - -- Create the following folder structure in `C:\Users\[YOU-USERNAME]\.zigverm`: - -``` -. -├── bin -├── downloads -└── installs -``` - -- Download the latest release for Windows from GitHub and extract it. -- Copy `zigverm.exe` and `zig.exe` to the `bin/` folder. -- Add the `bin` directory to your `PATH` enviroment variable - -### Compiling - -Requirements: - -- Zig >= 0.12.0. See [this](https://github.com/AMythicDev/zigverm#note-for-zig--v014) for Zig v0.14. -- libc on non-Windows systems. Can be provided by Zig itself, if available for the platform. -- `git`, if you want to compile the latest commit or you want to develop `zigverm`. - -Now to compile: - -- Clone the repo or download a source archive depending on if you want to compile the latest `main` - branck or a release. -- Extract the archive and change into the extracted directory. -- Run the following command - -``` -zig build --release=safe -``` - -- If you are devloping `zigverm`, you can omit the `--release=safe` flag. -- You will have `zigverm` and `zig` in `zig-out/bin/` directory -- Lastly follow the same steps [for windows](#for-windows) - -#### Note for Zig >= v0.14 -There have been some API changes in Zig v0.14 (not released yet) which makes zigverm fail -to compile on these versions of Zig. All the changes required to fix this is issue is being -tracked in [this](https://github.com/AMythicDev/zigverm/pull/2) PR. It will be merged into -main once this version of Zig comes out. - ## Features - [x] Install versions (master, stable, x.y x.y.z) diff --git a/docs2/.gitignore b/docs2/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs2/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs2/book.toml b/docs2/book.toml new file mode 100644 index 0000000..a109098 --- /dev/null +++ b/docs2/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Arijit Dey"] +language = "en" +multilingual = false +src = "src" +title = "Zigverm" diff --git a/docs2/src/SUMMARY.md b/docs2/src/SUMMARY.md new file mode 100644 index 0000000..e67ae7a --- /dev/null +++ b/docs2/src/SUMMARY.md @@ -0,0 +1,15 @@ +# Summary +[Introduction](./introduction.md) + +# Getting Started +- [Installation](./installation.md) +- [Compiling](./compiling.md) + +# Usage +- [Managing Zig Installations](./managing-zig-installations.md) + - [Versioning in zigverm](./versioning-in-zigverm.md) + +# Advanced +1. [Non-Trivial zigverm Root](./non-trivial-zigverm-root.md) + +# CLI Reference diff --git a/docs2/src/compiling.md b/docs2/src/compiling.md new file mode 100644 index 0000000..a6a7063 --- /dev/null +++ b/docs2/src/compiling.md @@ -0,0 +1,38 @@ +# Compiling + +## Requirements +- Zig >= 0.12.0. Zig master releases are not supported and may give errors when compiling. +- libc on non-Windows systems. Can be provided by Zig itself, if available for the platform. +- `git`, if you want to compile the latest commit or you want to develop `zigverm`. + +## To compile: +- Clone the repo or download a source archive depending on if you want to compile the latest `main` + branch or a release. + Clone command: + ```sh + git clone github.com/AMythicDev/zigverm.git + ``` +- Extract the archive if you downloaded a tarball and `cd` into the new directory. +- Run the following command + ``` + zig build --release=safe + ``` + +- If you are devloping `zigverm`, you can omit the `--release=safe` flag. +- You will have `zigverm` and `zig` executables in the `zig-out/bin/` directory +- Now create a new directory named `zigverm` under your home directory. See [Non-trivial zigverm Root](./non-trivial-zigverm-root.md) if you want a + different zigverm root directory. +- Now create the following folder structure in your new `zigverm` directory. + ``` + . + ├── bin + ├── downloads + └── installs + ``` + +- Copy `zigverm` and `zig` to the `bin/` folder. +- Optioally you can add the `zigverm/bin` directory to your `PATH` enviroment variable if you want to run zigverm and zig from +anywhere. + + + diff --git a/docs2/src/installation.md b/docs2/src/installation.md new file mode 100644 index 0000000..7a8d714 --- /dev/null +++ b/docs2/src/installation.md @@ -0,0 +1,40 @@ +# Installation + +## For Linux and MacOS (x86_64/aarch64) + +You can use this automated install script which will install zigverm along with the latest version of Zig + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/AMythicDev/zigverm/main/scripts/install.sh | bash +``` + +By default it will create `$HOME/.zigverm` directory as the root folder for zigverm. You can customize +this by setting this by setting the `ZIGVERM_ROOT_DIR` to the directory where you want to install +zigverm. Make sire you add the `ZIGVERM_ROOT_DIR` in your shell config otherwise zigverm would not be able +to locate the installation folder. + +The script will also put the installation directory's `bin` folder to your `$PATH` variable. For +this it will append a line to your `$HOME/.profile` and your shell's rc file. The file for each +shell supported is listed below: + +- Bash: `$HOME/.bashrc` +- Zsh: `$HOME/.zshrc` +- Fish: `$XDG_CONFIG_HOME/fish/config.fish`, if not set then uses `$HOME/.config/fish/config.fish` + +## For Windows +> An automatic installer for Windows is certainly planned however no work has been done for it yet. + +- Create the following folder structure in `C:\Users\[YOU-USERNAME]\.zigverm`: + +``` +. +├── bin +├── downloads +└── installs +``` + +- Download the latest release for Windows from GitHub and extract it. +- Copy `zigverm.exe` and `zig.exe` to the `bin/` folder. +- Add the `bin` directory to your `PATH` enviroment variable + + diff --git a/docs2/src/introduction.md b/docs2/src/introduction.md new file mode 100644 index 0000000..796f802 --- /dev/null +++ b/docs2/src/introduction.md @@ -0,0 +1,36 @@ +# Zigverm +Zigverm is a version manager for the [Zig](https://ziglang.org) programming language. + +Currently Zig does not have any official version manager and zigverm fills this space by providing a solid version manager from the ground up +written in Zig itself. + +## Features +- Easy installation with automatic installers for various platforms +- Manage Zig installations +- Manage global and per-directory overrides +- Open the offline language reference and standard library docs for a Zig version +- Self-update +- Tries to maintain strong compatiblity with the wider zig ecosystem (`zls`, `zig.vim`) + +## Platform support +Although zigverm supports all mainstream platforms, it does not support everything that Zig can be installed on. We intend to support more +platforms in the future however our current focus is to reach a good feature set. + +Here's the current platform support matrix: +Legend: +🎉 - Binary releases + automatic installer available +💪 - Binary releases available +❌ - No binary releases. Maybe supported later. Requires [compiling](#compiling) +\- - Not applicable + +| OS/Arch | x86_64 | x86 | aarch64 | armv7a | riscv64 | +| ------- | ------ | --- | ------- | ------ | ------- | +| Windows | 💪 | 💪 | ❌ | - | - | +| Linux | 🎉 | 🎉 | 🎉 | ❌ | ❌ | +| MacOS | 🎉 | - | 🎉 | - | - | + +## Contributing + +## License +All works to zigverm are available licensed under the [Apache License 2.0](https://github.com/AMythicDev/zigverm/blob/main/LICENSE) +unless explicitly mentioned. diff --git a/docs2/src/managing-zig-installations.md b/docs2/src/managing-zig-installations.md new file mode 100644 index 0000000..2c13912 --- /dev/null +++ b/docs2/src/managing-zig-installations.md @@ -0,0 +1 @@ +# Managing Zig Installations diff --git a/docs2/src/non-trivial-zigverm-root.md b/docs2/src/non-trivial-zigverm-root.md new file mode 100644 index 0000000..0c0c9f2 --- /dev/null +++ b/docs2/src/non-trivial-zigverm-root.md @@ -0,0 +1 @@ +# Non-trivial zigverm root diff --git a/docs2/src/versioning-in-zigverm.md b/docs2/src/versioning-in-zigverm.md new file mode 100644 index 0000000..db9c80a --- /dev/null +++ b/docs2/src/versioning-in-zigverm.md @@ -0,0 +1,16 @@ +# Versioning in zigverm +zigverm offers quite a bit of flexiblity for what versions are installed and how they can be updated. + +## Fixed Versions +These include complete version codes such as `0.13.0`, `0.12.1`, `0.12.0` etc. They are installed once and never updated by zigverm. + +## Fixed Minor Versions +These include partial version codes such as `0.13`, `0.12` etc. When installing/updating these types of versions, the latest patch +release for that specific minor version is installed. + +## `master` +This special version is provided by Zig itself and it closely follows the upstream Zig. + +## `stable` +This special version is provided by zigverm and it installs whatever the latest stable release of Zig is right now. +When installing zigverm using the automatic installers, it will automatically install this version for you.