Introduction
The following guide 🎓 will walk through the Rust and dependencies installation process for Linux, macOS and Windows WSL: for the Linux guides we'll use Ubuntu as an example. If you're on windows, we recommend to setup Windows Subsystem Linux or Ubuntu tutorial and picking a popular distro like Ubuntu. The WSL will let you use Linux applications, utilities and bash command tools you'll find in the tutorial.
Prerequisites
To follow the guide, you will need the following:
- Familiarity with the command-line interface
- Git
You're required to have some experience with the command-line interface 😿 and have Git installed; Also, you should be happy to troubleshoot, since versions might differ from the time of writing and reading. Most times, a simple web search provides the best answers 🙏!
If you don't have Git installed, learn more about it and the instructions by reading the Git documentation.
🤖 As Fleek Network's repositories are in constant development and change, you should consider that the following guide was checked in to commit
5a33b7. While we try our best to update documentation and guides during development, there might be breaking changes that might take some time to reflect in our docs. To avoid disappointment, feel free to check into commit5a33b7or contribute by getting in touch with us, or sending a PR in the relevant context. Learn how to checkout a commit in our repository history here 🙏.
Install Rust with Rustup tool
Visit the Rust website getting started guide, to find, copy and run the Rustup tool for installation and version management.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl is an application that is generally available in most OS, if missing install it. Find more here.
Alternatively, if you have installed Rust in the past, you may want to update it 👌.
rustup update
During the installation process, if asked about preferences, select the default option!
You can uninstall at any time with rustup self uninstall and
these changes will be reverted.
Current installation options:
default host triple: x86_64-unknown-linux-gnu
default toolchain: stable (default)
profile: default
modify PATH variable: yes
1) Proceed with installation (default)
2) Customize installation
3) Cancel installation
Once complete 👍, you'll have to restart your current shell or reload the "PATH" environment variable to include Cargo's bin directory
$HOME/.cargo/bin. This is required to let you use "cargo" command globally.
To configure your current shell, run:
source "$HOME/.cargo/env"
From then on, the latest version of Cargo (Rust's build and package manager tool) should be installed. Learn more about Cargo, here.
Check the version to confirm's working correctly:
cargo --version
Here's the output we got (beware that our version might differ to yours, it's expected 😅).
cargo 1.65.0 (4bc8f24d3 2022-10-20)
Ursa installer rust dependencies
Rustup subcommands deal with toolchains, a collection of programs required to compile a Rust application.
rustup toolchain list
For example, on Linux Ubuntu we generally have it set to the default:
stable-x86_64-unknown-linux-gnu (default)
While on macOS:
stable-x86_64-apple-darwin (default)
Make sure you have Rustup set to the desired toolchain as default if required 💁♀️!
rustup default <TOOLCHAIN-LIST-NAME>
Rust compillation are long and compiler caching can help speed things up immensively. The Ursa CLI project can use to reduce the perceived compilation times down.
Sccache is a ccache-like compiler caching tool. It is used as a compiler wrapper and avoids compilation when possible. This is optional, but recommended!
cargo install sccache
Dependencies by operating system
Find the most common steps to have all the required dependencies (packages, libraries, etc) for Linux, macOS and Windows WSL. As mentioned earlier, the Linux guides use Ubuntu as an example but should give you a good reference for your distro.
MacOS dependencies
Installing the latest version of Xcode Command Line Tools should be enough to build Ursa. Ursa does not require XCode, but XCode compiles software and for that reason installs most of the required packages via the Xcode Command Line Tools.
Clang may already be installed on your macOS. To verify that it is, open a terminal and run the following command:
clang --version
If Clang isn't installed, enter the following command to install it:
xcode-select --install
To verify that is installed, execute the command:
clang --version
Here's the output we got (versions might differ from the time of writing and reading, so don't panic 😅).
Apple clang version 13.0.0 (clang-1300.0.27.3)
Target: x86_64-apple-darwin21.1.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin
Install the Protocol Buffer Compiler, here's an example that uses homebrew package manager, if you don't have homebrew learn about it here. Alternatively, visit the Protocol Buffer Compiler for other installation options.
brew install protobuf
Ensure the compiler version is 3+
protoc --version
Linux Ubuntu dependencies
On Linux Ubuntu (our choice as the Linux distro example), start by updating the package information in the source list and then upgrade all the installed packages with the latest versions (⚠️ do the equivalent for your Linux distro), as follows:
sudo apt-get update
sudo apt-get upgrade
💡 You can optionally pass the y flag to skip any user prompts e.g. sudo apt-get update -y to any remaining apt-get commands.
Install the build-essentials packages, necessary for compiling general software and for our use-case Ursa CLI.
sudo apt-get install build-essential
Followed by the required tools required to compile the application (cmake, clang, pkg-config and libssl-dev ).
sudo apt-get install cmake clang pkg-config libssl-dev
Now install the Protobufer Compiler.
sudo apt-get install protobuf-compiler
Ensure the compiler version is 3+
protoc --version
Windows subsystem linux
The instructions in Linux Ubuntu dependencies for building Ursa apply to WSL users. Check them out!
Once available, run Bash shell instead of Windows powershell 🥴.
Bash on Ubuntu on Windows
Alternatively, try Windows Terminal and open a WSL Ubuntu terminal window.
Generally, users report issues with commands not being found. 🧐 To avoid frustration verify that your system PATH environment variable is setup correctly and includes all the necessary paths (e.g. the Cargo binary directory). Use the Install Rust with Rustup tool, if too difficult for you at this time, you might want to use our Docker solution, which is simpler.
Installing Ursa CLI
If you haven't already 🙄, clone the Fleek Network's Ursa repository to your machine.
You have several ways of doing this:
- Clone via HTTPS
- Clone via SSH
- Download via Github CLI
- Download the zip package from the repository
We recommend HTTPS because it is the easiest to set up on the wild, and by users who are new to all this.
git clone https://github.com/fleek-network/ursa.git
Although, we strongly recommend using an SSH connection when interacting with GitHub. If you are to this and are interested read more about it here.
git clone git@github.com:fleek-network/ursa.git
💡 Optionally, you can pass a directory name at the end of the commands (as the last argument), otherwise defaults to the repository name and for our case the name is ursa. Note that you don't have to use < or > when naming, it's just illustrative.
git clone https://github.com/fleek-network/ursa.git <DIRECTORY-NAME>
When git clone completes 👍, change directory to the project directory e.g. we cloned to the default name ursa:
cd ursa
If you list (ls) the files in the directory, it should be similar to:
.
├── Cargo.toml
├── Dockerfile
├── Makefile
├── README.md
├── crates
├── infra
├── rust-toolchain.toml
└── specs
At this point, you should be able to run the install command successfully.
🙄 If you already had Rust installed, or the project before, and skipped instructions directly here, there might be case where you get errors. So, make sure to clear your work directory:
cargo clean
cargo update
Start the install process by running the command:
make install
The installation process can take some time 🥱, as it compiles the application binary for us. This is where sccache is useful!
🌈 Here's the output when successful!
Finished release [optimized] target(s) in 11m 22s
Installing /root/.cargo/bin/ursa
Installed package `ursa v0.1.0 (/temp/ursa/crates/ursa)` (executable `ursa`)
Once Rust generates the binary you can find it in the Cargo bin directory. On mac and linux, this is located at
$HOME/.cargo/binand on Windows%USERPROFILE%\.cargo\bin. Ifursais not available as a command, it's very likely that you need to add the Cargo bin directory to your operating systemPATHenvironment variable. 🤨 There are plenty of articles explaining how to do it in most operating systems, a matter of using a web search engine.
Run the ursa help command as a checkup:
ursa 0.1.0
CLI options
USAGE:
ursa [FLAGS] [OPTIONS] [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-r, --rpc Allow rpc to be active or not (default = true)
-V, --version Prints version information
OPTIONS:
-c, --config <config> A toml file containing relevant configurations
-r, --rpc-port <rpc-port> Port used for JSON-RPC communication
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
rpc run rpc commands from cli
⚠️ Beware that your output might differ a bit, as Ursa is in constant development. Note that you'll have to "re-install" every time you want to pull updates from the source repository, as the update at the time of writing is done manually and not automatically.
Great 👌 ! You have successfully installed all the required packages, libraries and have compiled and installed Ursa.
To learn more about Fleek Network and Ursa, check our Getting started guide.
Troubleshooting
😈 Applications are constantly updated, and guides can hardly keep up with all the updates, thus being able to do a simple web search can take you a long way...
Failed to run custom build command for X?
Operating systems are highly customizable and you might be missing some dependencies not described in the guide. An easy way around this is to copy the error message and do a web search to find solutions. E.g. error: failed to run custom build command for librocksdb-sys v6.20.3, you'd copy the error message, maybe remove the v6.20.3 and do a web search. Information is out there, let's use it!
Don't have cmake, clang, library X installed?
Follow the guide for your operating system in the Ursa rust dependencies topic. It should help most use cases, but depending on how your operating system is set up, you might need to troubleshoot to find what the missing package is and understand how to install the missing package by copying the error and doing a web search.
Conclusion
A Fleek Network node can be built and run on your local machine.
The project is built with Rust, a general-purpose programming language, to have it installed on a machine there are some packages and libraries that are required.
We have guided you 🦮 through the Rust installation process in macOS, Linux Ubuntu and Windows (Windows Subsystem Linx), OS tools to help the Rust toolchain do the compilation and installation work; and also suggest some tips to help troubleshoot.
While we do our best to provide the clearest instructions, there's always space for improvement 🙏, therefore feel free to make any contributions by messaging us on our Discord or by opening a PR in any of our repositories.
Discover more about the project by watching/contributing on Github, following us on Twitter, and joining our community Discord for all the best updates!
