Skip to content

Commit 3cf2207

Browse files
codilioncodilion
committed
CLI installation guide for all platforms
1 parent b3c4326 commit 3cf2207

2 files changed

Lines changed: 320 additions & 1 deletion

File tree

‎docs/getting-started/install-open-libra-cli.md‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,320 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
14
# Install Open Libra CLI
5+
6+
This guide will walk you through installing the **Open Libra CLI** by building it from source. The CLI provides essential tools for interacting with the Open Libra network.
7+
8+
## Installation Overview
9+
10+
The installation process involves these main steps:
11+
12+
1. **Prerequisites Setup** - Install required system dependencies and Rust toolchain for your operating system
13+
2. **Clone Repository** - Download the Open Libra Framework source code
14+
3. **Build CLI** - Compile the CLI in release mode for optimal performance
15+
4. **Install Binaries** - Copy the built binaries to your system PATH
16+
5. **Verify Installation** - Confirm the CLI is working correctly
17+
18+
## Prerequisites Setup
19+
20+
Before beginning, ensure you have the following tools installed on your system:
21+
22+
- **Rust & Cargo** - The Rust programming language and its package manager
23+
- **Git** - Version control system for cloning the repository
24+
- **cURL** - Command-line tool for downloading files
25+
- **C/C++ toolchain** - Compiler and build tools
26+
- **OpenSSL headers** - Cryptographic library headers
27+
- **CMake** - Cross-platform build system
28+
29+
## System-Specific Setup
30+
31+
Select your operating system for detailed installation instructions of all the prerequisites:
32+
33+
<Tabs
34+
groupId="operating-systems"
35+
defaultValue="linux"
36+
values={[
37+
{ label: 'Linux', value: 'linux' },
38+
{ label: 'macOS', value: 'mac' },
39+
{ label: 'Windows', value: 'windows' },
40+
]}>
41+
42+
<TabItem value="linux">
43+
44+
**Tested on Ubuntu 22.04 LTS and compatible distributions.**
45+
46+
#### System Dependencies
47+
48+
```bash
49+
# Update package lists
50+
sudo apt update
51+
52+
# Install required packages
53+
sudo apt install -y \
54+
build-essential \
55+
clang \
56+
llvm \
57+
lld \
58+
cmake \
59+
git \
60+
curl \
61+
pkg-config \
62+
libssl-dev \
63+
libgmp-dev \
64+
libpq-dev
65+
```
66+
67+
#### Rust & Cargo Installation
68+
69+
The recommended installation method is `rustup`, which manages Rust toolchains:
70+
71+
```bash
72+
# Download and install Rust
73+
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
74+
75+
# Activate the toolchain in your current shell
76+
source "$HOME/.cargo/env"
77+
78+
# Verify the installation
79+
rustc --version && cargo --version
80+
```
81+
82+
**To update an existing Rust installation:**
83+
84+
```bash
85+
rustup update stable
86+
```
87+
88+
</TabItem>
89+
90+
<TabItem value="mac">
91+
92+
#### System Dependencies
93+
94+
Using [Homebrew](https://brew.sh/) (recommended):
95+
96+
```bash
97+
# Install required packages
98+
brew install git curl cmake llvm pkg-config openssl@3 gmp
99+
100+
# Configure OpenSSL for pkg-config
101+
echo 'export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zprofile
102+
103+
# Apply the changes (restart terminal or run one of these)
104+
source ~/.zshrc # if using zsh
105+
source ~/.bash_profile # if using bash
106+
source ~/.profile # for other shells
107+
```
108+
109+
**Alternative: Using MacPorts**
110+
111+
```bash
112+
sudo port install cmake llvm git curl pkgconfig openssl3 gmp
113+
```
114+
115+
#### Rust & Cargo Installation
116+
117+
```bash
118+
# Download and install Rust
119+
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
120+
121+
# Activate the toolchain in your current shell
122+
source "$HOME/.cargo/env"
123+
124+
# Verify the installation
125+
rustc --version && cargo --version
126+
```
127+
128+
**To update an existing Rust installation:**
129+
130+
```bash
131+
rustup update stable
132+
```
133+
134+
</TabItem>
135+
136+
<TabItem value="windows">
137+
138+
#### System Dependencies
139+
140+
**Option 1: Using Chocolatey (Recommended)**
141+
142+
First, install [Chocolatey](https://chocolatey.org/install) if you haven't already, then:
143+
144+
```powershell
145+
# Install required packages
146+
choco install git cmake llvm rust-ms
147+
148+
# Install Visual Studio Build Tools (required for compilation)
149+
choco install visualstudio2022buildtools --package-parameters "--add Microsoft.VisualStudio.Workload.VCTools"
150+
```
151+
152+
**Option 2: Manual Installation**
153+
154+
1. Install [Git for Windows](https://git-scm.com/download/win)
155+
2. Install [CMake](https://cmake.org/download/)
156+
3. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
157+
4. Install [LLVM](https://releases.llvm.org/download.html)
158+
159+
#### Rust & Cargo Installation
160+
161+
```powershell
162+
# Download and install Rust (run in PowerShell)
163+
Invoke-WebRequest -Uri https://win.rustup.rs/x86_64 -OutFile rustup-init.exe
164+
.\rustup-init.exe --default-toolchain stable -y
165+
166+
# Restart your terminal or run:
167+
$env:PATH += ";$env:USERPROFILE\.cargo\bin"
168+
169+
# Verify the installation
170+
rustc --version; cargo --version
171+
```
172+
173+
**To update an existing Rust installation:**
174+
175+
```powershell
176+
rustup update stable
177+
```
178+
179+
</TabItem>
180+
181+
</Tabs>
182+
183+
## Build & Install the CLI
184+
185+
Once you have all prerequisites installed, follow these steps to build and install the Open Libra CLI:
186+
187+
### 1. Clone the Repository
188+
189+
```bash
190+
git clone https://github.com/0LNetworkCommunity/libra-framework.git
191+
cd libra-framework
192+
```
193+
194+
### 2. Build the CLI
195+
196+
```bash
197+
# Build in release mode for optimal performance
198+
cargo build --release -p libra
199+
```
200+
201+
**Note:** The build process may take several minutes depending on your system's performance.
202+
203+
### 3. Install the Binary
204+
205+
<Tabs
206+
groupId="install-methods"
207+
defaultValue="cargo-install"
208+
values={[
209+
{ label: 'Using cargo install (Recommended)', value: 'cargo-install' },
210+
{ label: 'Manual installation', value: 'manual-install' },
211+
]}>
212+
213+
<TabItem value="cargo-install">
214+
215+
```bash
216+
# Install directly using cargo (recommended)
217+
cargo install --path tools/libra --force
218+
```
219+
220+
</TabItem>
221+
222+
<TabItem value="manual-install">
223+
224+
```bash
225+
# Copy the binary to your local bin directory
226+
install -m 755 target/release/libra "$HOME/.cargo/bin"
227+
```
228+
229+
**On Windows (PowerShell):**
230+
231+
```powershell
232+
# Create the directory if it doesn't exist
233+
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cargo\bin"
234+
235+
# Copy the binary
236+
Copy-Item "target\release\libra.exe" -Destination "$env:USERPROFILE\.cargo\bin"
237+
```
238+
239+
</TabItem>
240+
241+
</Tabs>
242+
243+
### 4. Update Your PATH (if needed)
244+
245+
The PATH update is only necessary if you used the manual installation method and chose to install to `$HOME/.cargo/bin`. If you used `cargo install` or installed to `/usr/local/bin`, you can skip this step.
246+
247+
**Linux/macOS:**
248+
249+
```bash
250+
# Add to appropriate shell configuration file
251+
if [[ "$SHELL" == *"zsh"* ]]; then
252+
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
253+
elif [[ "$SHELL" == *"bash"* ]]; then
254+
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
255+
else
256+
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.profile && source ~/.profile
257+
fi
258+
259+
# Alternative: Check manually and add to your preferred shell config
260+
# echo $SHELL # to see which shell you're using
261+
```
262+
263+
**Windows (PowerShell):**
264+
265+
```powershell
266+
# Add to PATH permanently
267+
$oldPath = [Environment]::GetEnvironmentVariable("PATH", "User")
268+
if ($oldPath -notlike "*$env:USERPROFILE\.cargo\bin*") {
269+
[Environment]::SetEnvironmentVariable("PATH", "$oldPath;$env:USERPROFILE\.cargo\bin", "User")
270+
}
271+
```
272+
273+
### Verify Installation
274+
275+
```bash
276+
# Check that the CLI is properly installed
277+
libra --version
278+
279+
# View available commands
280+
libra --help
281+
```
282+
283+
## Troubleshooting
284+
285+
### Common Issues
286+
287+
**Build fails with OpenSSL errors:**
288+
- **Linux:** Ensure `libssl-dev` is installed
289+
- **macOS:** Make sure PKG_CONFIG_PATH includes OpenSSL path
290+
- **Windows:** Install OpenSSL or use the Windows-specific Rust toolchain
291+
292+
**Permission denied when installing:**
293+
- Ensure you have write permissions to `$HOME/.cargo/bin`
294+
- On Windows, run PowerShell as Administrator if needed
295+
296+
**Command not found after installation:**
297+
- Verify `$HOME/.cargo/bin` is in your PATH
298+
- Restart your terminal or source your shell configuration
299+
300+
**Compilation takes too long:**
301+
- The initial build can take 10-30 minutes depending on your system
302+
- Consider using `cargo build --release -j $(nproc)` to use all CPU cores
303+
304+
### Getting Help
305+
306+
If you encounter issues not covered here:
307+
308+
1. Check the [project issues](https://github.com/0LNetworkCommunity/libra-framework/issues) on GitHub
309+
2. Ensure you're using the latest version of Rust and dependencies
310+
311+
## Next Steps
312+
313+
After successful installation:
314+
315+
1. Run `libra --help` to explore available commands
316+
2. Join the Open Libra contributors community on Discord for support and updates
317+
318+
---
319+
320+
**Need pre-built binaries?** Visit the [releases page](https://github.com/0LNetworkCommunity/libra-framework/releases) for downloadable binaries (when available).

‎docusaurus.config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ const config = {
133133
prism: {
134134
theme: lightTheme,
135135
darkTheme: darkTheme,
136-
additionalLanguages: ['rust', 'typescript', 'bash', 'toml', 'json'],
136+
additionalLanguages: ['rust', 'typescript', 'bash', 'toml', 'json', 'powershell'],
137137
},
138138
algolia: {
139139
appId: "E8UE0IN6GG",

0 commit comments

Comments
 (0)