From bc41eb58c91db9b825c499132ee445c1f4d9c0e7 Mon Sep 17 00:00:00 2001 From: codilion Date: Wed, 4 Jun 2025 13:29:05 +0200 Subject: [PATCH 1/2] simplify the Windows binary installation guide --- .../install-open-libra-cli-binaries.md | 105 +++++++++++++----- 1 file changed, 80 insertions(+), 25 deletions(-) diff --git a/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md b/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md index 52e30560..af069bf5 100644 --- a/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md +++ b/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md @@ -158,52 +158,107 @@ The pre-built binaries require Ubuntu 24.04. For older versions: ::: + + + -### Native Windows +> **Assumption:** You have downloaded **`libra-windows-x64.exe`** into **`C:\Users\\Downloads`**. + +### TL;DR — One‑liner + +You can set up `libra` in one step. Paste the following commands into the `PowerShell` application, press Enter, and wait for the version output to confirm success: + +```powershell +mkdir "$HOME\bin" -ErrorAction SilentlyContinue; ` +Move-Item "$HOME\Downloads\libra-windows-x64.exe" "$HOME\bin\libra.exe" -Force; ` +setx PATH "$($Env:PATH);$HOME\bin"; ` +$Env:PATH += ";$HOME\bin"; ` +libra version +``` +What it does: +- **Create `$HOME\bin`** if it does not exist. +- **Move and rename** the downloaded file to `$HOME\bin\libra.exe`. +- **Update your `PATH`** permanently so Windows can find `libra` in any new session. +- **Refresh `PATH`** for the current window so you can use `libra` immediately. +- **Verify** by printing the installed version. -1. **Create directory for binary**: +You should see output like: + +``` +LIBRA VERSION 8.0.7 +build timestamp: 2025-06-04T... +``` + +
+ +### Step‑by‑Step guide + +1. **Create a personal `bin` folder** + This folder will hold your local executables and allow you to run them from anywhere. ```powershell - mkdir %HOMEPATH%\bin + mkdir "$HOME\bin" ``` -2. **Copy and rename**: +2. **Move and rename the binary** + Place the downloaded file into your new folder and give it a simple name. ```powershell - copy "Downloads\libra-windows-x64.exe" %HOMEPATH%\bin\libra.exe + Move-Item "$HOME\Downloads\libra-windows-x64.exe" "$HOME\bin\libra.exe" ``` -3. **Add to PATH**: - - Open System Properties → Advanced → Environment Variables - - Add `%HOMEPATH%\bin` to your PATH variable - - Or via command line: +3. **Add the folder to your `PATH` (permanent)** + This makes `libra` available in any future PowerShell window. ```powershell - setx PATH "%PATH%;%HOMEPATH%\bin" + setx PATH "$($Env:PATH);$HOME\bin" ``` + :::caution + This updates the system registry but does not change the `PATH` in the current session. + ::: -4. **Verify installation**: +4. **Apply the new `PATH` to this session** + So you don’t need to close and reopen PowerShell. ```powershell - libra version + $Env:PATH += ";$HOME\bin" ``` -### Windows Subsystem for Linux (WSL2) +5. **Verify the installation** + Run the version command to confirm that `libra` is installed correctly. + ```powershell + libra version # or: libra --help + ``` -:::tip WSL2 Users -For WSL2, use the Linux binary: -1. Download the Linux binary (not Windows) -2. Follow the Linux installation steps above - ::: +If everything is configured, you’ll see `libra` print its version information. + +--- + +--- + +## Windows Subsystem for Linux (WSL2) + +:::tip WSL2 users +In WSL2, install as if on Linux: + +1. Download the **Linux** version into your WSL distro. +2. Follow the [Linux installation steps](../linux) provided in this guide. +::: + + ## Troubleshooting ### Common Issues -| Problem | Solution | -|---------|----------| -| "command not found" | Ensure the binary location is in your PATH | -| "Permission denied" | Make the file executable: `chmod +x libra` | -| "cannot execute binary file" | Wrong architecture - check your system architecture | -| OpenSSL errors | Install OpenSSL for your platform | -| "bad CPU type" (macOS) | Download the correct architecture (x64 vs arm64) | +| Symptom | Likely Cause | Resolution | +|---------------------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| `"command not found"` | Binary location is not in your `PATH` | Ensure the binary location is in your `PATH` | +| `"Permission denied"` | File is not marked as executable | Run `chmod +x libra` to make the file executable | +| `"cannot execute binary file"` | Downloaded binary does not match your system architecture | Check your system architecture and download the correct binary | +| `OpenSSL errors` | OpenSSL is missing or not properly installed | Install or update OpenSSL for your platform | +| `"bad CPU type"` (macOS) | Binary was built for the wrong CPU architecture | Download the correct architecture (x64 vs. arm64) | +| `libra : The term 'libra' is not recognized…` | Current PowerShell session has not picked up the updated `PATH` | Open a new PowerShell window, or run step 4 to refresh `PATH` in the current session | +| Path appears as `C:\Users\win\Downloads\%HOMEPATH%\bin` | `%HOMEPATH%` was used instead of `$HOME` or `%USERPROFILE%` (lacks drive letter) | Re-run steps 1–3 using `$HOME` (PowerShell) or `%USERPROFILE%` (cmd) | +| Need to type `.\libra.exe` instead of `libra` | Windows does not execute files from the current directory by default | Ensure `$HOME\bin` is in your `PATH`; then running `libra` will work without `.\` | + From 75add8b132a684c306898f3da8444c3b70477d70 Mon Sep 17 00:00:00 2001 From: codilion Date: Wed, 4 Jun 2025 13:34:08 +0200 Subject: [PATCH 2/2] fix broken link --- .../install-open-libra-cli/install-open-libra-cli-binaries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md b/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md index af069bf5..4a5473e3 100644 --- a/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md +++ b/docs/getting-started/install-open-libra-cli/install-open-libra-cli-binaries.md @@ -239,7 +239,7 @@ If everything is configured, you’ll see `libra` print its version information. In WSL2, install as if on Linux: 1. Download the **Linux** version into your WSL distro. -2. Follow the [Linux installation steps](../linux) provided in this guide. +2. Follow the Linux installation steps provided in this guide. :::