Setting Up and Using Rust Offline for Seamless Development: A Step-by-Step Tutorial

출처: https://buildsoftwaresystems.com/post/development/rust/tools/setting_up_and_using_rust_offline_for_seamless_develeopment__a_step_by_step_tutorial/

Setting Up and Using Rust Offline for Seamless Development: A Step-by-Step Tutorial

Aug 31, 2023· 15 min read · 139 views ·RUSTOFFLINE DEVELOPMENTDEVELOPMENT ENVIRONMENTTOOLCHAINDEPENDENCIESSETUP GUIDEPACKAGE MANAGEMENTDOCKERLINUXWINDOWS ·

Share on:

Last update date: Dec 19, 2023

Table of Contents

• Setting Up Rust Development Environment Offline - Locally
  • Step 1: Download the required files on a trusted computer with internet access
  • Step 2: Securely Copy the downloaded files to the offline development computer
  • Step 3: Install the Rust toolchain
  • Step 4: Manage the Rust Toolchain with Rustup
• Setting Up Rust Development Environment Offline - Using Docker development containers
  • Step 1: Download and save the development Docker image on a trusted computer with internet access
  • Step 2: Securely copy the downloaded development Docker image to the offline development computer
  • Step 3: Load the copied development Docker image into Docker (on the offline development computer)
  • Step 4: Use the loaded Docker image to create development containers
• Managing Dependencies and Packages Offline
  • Solution 1: Vendoring Dependency Packages
  • Solution 2: Using a crates.io mirror
• Conclusion

Rust is an exceptional programming language. It is supported by a vast array of tools that comprise the Rust toolchain. The Rustup tool manages the development toolchain. Cargo, on the other hand, manages the build environment. These tools are highly intuitive and user-friendly.

The Rust toolchain can be quickly set up using a single Rustup command. This command automatically downloads all the necessary development tools. Equally, Cargo fetches dependencies and builds crates without any fuss.

However, it is not unusual for Rust developers to work offline. This is particularly true in companies that enforce strict security measures that restrict internet access on development machines.

In such situations, Rustup and Cargo may not function correctly. As a result, affected developers will need to install the Rust development environment and securely manage dependencies offline.

This blog article serves as a complete guide for Rust developers. It is designed for those who work in environments with restricted or no internet access. The aim is to guarantee that these developers can carry on with their work efficiently.

Target OS families

This guide focuses on Linux and Windows Operating Systems.

On Windows, you may need to install the Microsoft C++ Build Tools or Visual Studio according to the official Rust installation instructions.

Setting Up Rust Development Environment Offline - Locally

This section explains local setup of the development environment. For setup using Docker development containers, go the next section below.

To set up an offline Rust development environment locally, you need to obtain, transfer and install 2 files on your offline development machine:

• Rust standalone Installer which includes pre-compiled, ready-to-install Rust toolchain code.
• rustup-init installer which installs the Rustup program.

Rustup is mainly designed for managing multiple installed Rust versions on the same host. This is incredibly valuable when you need to switch between projects that require different Rust versions. Additionally, it serves as a useful tool for experimenting with newer versions of Rust.

When upgrading Rust Version

If you already have Rustup installed on your development machine and want to update Rust, simply obtain and install the Rust standalone installer.

Step 1: Download the required files on a trusted computer with internet access

Begin by downloading the necessary files on an internet-connected computer.

1. Download the Rust Standalone Installers: Obtain the Rust standalone installer tailored for your target development computer's architecture here.
   For example, you can choose to download the x86_64-unknown-linux-gnu Rust standalone installer for x86_64 Linux.
   If you need a specific Rust version, you can modify the version in the download URL.
   Optionally, you can verify the authenticity of the installer by checking the GPG signature using the corresponding '.asc' file.
2. Download rustup-init: Download rustup-init designed for your target development computer's architecture here.
   Keep in mind that rustup-init operates independently of the specific Rust version you intend to install. Its primary purpose is to manage multiple versions of the Rust toolchain.
   Optionally, you can verify the integrity of the downloaded file by comparing its sha256 hash with the corresponding sha256 file.

Automated Download Using Terminal

You can simplify the download process of these 2 files with the following scripted commands.

Select the tab that corresponds to the operating system of your downloading computer

LinuxWindows-PowershellWindows-CMD

##########################
# Configurable constants #
##########################
# Set the variables for the selected target triple, as well as Rust version
RUST_VERSION_STRING="1.73.0"
ARCH_DISTRO_STRING="x86_64-unknown-linux-gnu"
# Set the download folder
DOWNLOAD_FOLDER="${HOME}/Downloads/offline-rust"

########
# Main #
########
# Set the download URLs
rust_standalone_file="rust-${RUST_VERSION_STRING}-${ARCH_DISTRO_STRING}.tar.gz"
rust_standalone_installer_url="https://static.rust-lang.org/dist/${rust_standalone_file}"
rustup_init_file="rustup-init"
rustup_init_url="https://static.rust-lang.org/rustup/dist/${ARCH_DISTRO_STRING}/${rustup_init_file}"

# Ensure that the download folder exists
test -d ${DOWNLOAD_FOLDER} || mkdir -p ${DOWNLOAD_FOLDER}

# Download Rust standalone installer
wget -P ${DOWNLOAD_FOLDER} ${rust_standalone_installer_url}
# Alternatively 'curl' can be used as following:
# cd ${DOWNLOAD_FOLDER}; curl --remote-name ${rust_standalone_installer_url}; cd -

# Download Rustup-init
wget -P ${DOWNLOAD_FOLDER} ${rustup_init_url}
# Alternatively 'curl' can be used as following:
# cd ${DOWNLOAD_FOLDER}; curl --remote-name ${rustup_init_url}; cd -

##################
# Optional check #
##################
# It is also possible to check that the downloaded files 
# were not corrupted during download. 
# This can be done by using the SHA hash file 
# and GPG signature file available on the download web pages.

 

BASH

Step 2: Securely Copy the downloaded files to the offline development computer

Now, securely transfer these 2 downloaded files to the offline development computer through:

• Managed File Transfer (MFT).
• Data storage devices like flash drives.
• Secure shared drives.
• Any other available means.

Step 3: Install the Rust toolchain

With the files on your offline development computer, you can install the Rust toolchain using the following scripted commands.

To proceed, select the tab that corresponds to your target development computer's Operating System.

LinuxWindows-PowershellWindows-CMD

##########################
# Configurable constants #
##########################
# Set the variables for the selected target triple, as well as Rust version
RUST_VERSION_STRING="1.73.0"
ARCH_DISTRO_STRING="x86_64-unknown-linux-gnu"
# Set the copied rust standalone installer file path
COPIED_FILES_FOLDER="${HOME}/Downloads/offline-rust"
# Set the install folder (The defult installation path is /usr/local)
STANDALONE_INSTALL_DIR="${HOME}/rust-install/rust-${RUST_VERSION_STRING}-${ARCH_DISTRO_STRING}"
# Set toolchain installed toolchain name
RUST_TOOLCHAIN_NAME="rust-toolchain-${RUST_VERSION_STRING}"

########
# Main #
########
archive_file=${COPIED_FILES_FOLDER}/rust-${RUST_VERSION_STRING}-${ARCH_DISTRO_STRING}.tar.gz
extract_archive_dir=${COPIED_FILES_FOLDER}/rust-${RUST_VERSION_STRING}-${ARCH_DISTRO_STRING}

# Extract the Rust standalone installer archive
tar -xzf ${archive_file} -C ${COPIED_FILES_FOLDER}

# Run the installation script
# (view custom installation argument by calling the install script with the option: '--help')
${extract_archive_dir}/install.sh --prefix=${STANDALONE_INSTALL_DIR}

# Delete the extracted folder (cleanup)
rm -r ${extract_archive_dir}

 

BASH

These scripted commands install the Rust toolchain to a folder without altering the system PATH. This is crucial to avoid any interference with Rustup in the future.

Rustup ensures the selected toolchain version is available on the system's PATH.

In the next step you will learn how to manage the installed Rust toolchain with Rustup.

Alternative Offline Setup (Without Rustup)

While not advised, it is possible to carry out an offline installation of Rust without Rustup. If you choose to do so, you should then stop at this step and ensure that the absolute path of the Rust binary installation directory (bin) is added to your system's PATH.

However, please note that this method requires manual management of different Rust versions, as well as the upgrade of the Rust toolchain.

Step 4: Manage the Rust Toolchain with Rustup

Now that you've installed the Rust toolchain, it's time to manage it using Rustup. First, make sure Rustup is installed.

I. Install Rustup

If you have not yet installed Rustup, follow these instructions to install it using the downloaded rustup-init installer.

Note that the installation process requires managing 2 directories:

• The Rustup settings directory (which defaults to .rustup in your user's home directory).
• The Cargo settings and toolchain proxies directory (which defaults to .cargo in your user home directory).

You can change the Rustup installation directory by setting the RUSTUP_HOME environment variable during installation. Similarly, you can change the Cargo settings and toolchain proxies directory by setting the CARGO_HOME environment variable during installation.

To proceed, select the tab that corresponds to your target development computer's Operating System.

LinuxWindows-PowershellWindows-CMD

# XXX: Use same "Configurable Constants" as in the scripts in Step 3

# Ensure rustup-init is executable
chmod +x ${COPIED_FILES_FOLDER}/rustup-init
# Run the installation script
# run with the default toolchain set to `none` so that no download is attempted. 
# The '-y' is used to run in batch mode (non interactive).
# This will install `rustup` and set the proxies in the `${CARGO_HOME}/bin` folder.
# It will also configure the system PATH for new sessions
${COPIED_FILES_FOLDER}/rustup-init --default-toolchain none -y

# To make configure the system PATH for the current terminal session:
source ${CARGO_HOME:-${HOME}/.cargo}/env

 

BASH

How rustup-init Works

rustup-init and rustup are essentially the same executable file; they function differently based on the executable's filename.

When you run rustup-init, it creates copies of itself in the $CARGO_HOME/bin (or %CARGO_HOME%\bin on Windows) directory. Each copy is named after a Rust toolchain's tool (e.g., cargo, rustc, rustdoc). These copies serve as proxies and are used by Rustup to manage the toolchain versions.

II. Manage the Installed Rust Toolchain with rustup

Now that you have Rustup installed, you can use it to manage the installed toolchain as a custom toolchain. To manage a newly installed toolchain, follow these simple steps:

1. Link the toolchain.
2. Set it as the default to activate it.

LinuxWindows-PowershellWindows-CMD

# XXX: Use same "Configurable Constants" as in the scripts in Step 3

# Link the installed toolchain to Rustup 
# Rustup will create a symbolik link named '${RUST_TOOLCHAIN_NAME}' to 
# the installation directory '${STANDALONE_INSTALL_DIR}'
rustup toolchain link ${RUST_TOOLCHAIN_NAME} ${STANDALONE_INSTALL_DIR}

# Set the toolchain as default
rustup default ${RUST_TOOLCHAIN_NAME}

# Verify the installation
rustc --version

 

BASH

Uninstallation

To uninstall a Rust toolchain version or Rustup itself, refer to the Rustup help manual.
This is available using the command rustup --help.

Setting Up Rust Development Environment Offline - Using Docker development containers

This section explains how to set up the development environment using development Docker containers. For local setup, go to the previous section above.

The prerequisite is for Docker to be installed on the offline development computer.

To work with the Docker development container, you may use an official Rust toolchain Docker image.

This guide makes use of the rust:1.73-bookworm Rust Docker image for illustration.

Step 1: Download and save the development Docker image on a trusted computer with internet access

To download the development Docker image, use the docker pull command. Afterward, use the docker save command to save the Docker image into a tar file.

LinuxWindows-PowershellWindows-CMD

docker pull rust:1.73-bookworm
docker save -o /tmp/saved_rust_image.tar rust:1.73-bookworm

 

BASH

Step 2: Securely copy the downloaded development Docker image to the offline development computer

This can be done as mentioned in the section above.

Step 3: Load the copied development Docker image into Docker (on the offline development computer)

On the offline development computer, use the docker load command to load the Docker image from the tar file.

LinuxWindows-PowershellWindows-CMD

docker load -i /tmp/saved_rust_image.tar

 

BASH

After this, the Docker image will be available on the offline development computer's for use with docker. The name and tag will be same as downloaded at Step 1 (rust:1.73-bookworm here).

Step 4: Use the loaded Docker image to create development containers

More and more code editors support remote container developments. If your code editor does not have support for remote container development, you can either install one that supports it or just use the development Docker container to build and debug developed software.

Case of Visual Studio Code

Follow the instructions provided in the Visual Studio Code DevContainers documentation to configure your development environment with Docker containers.

Case of (Neo)Vim

Refer to the nvim-remote-containers GitHub repository for instructions on setting up (Neo)Vim with Docker development containers.

Unsupported code editors

Run the Rust development Docker container with the code repository mounted. Make changes to the code and build using the terminal from the Docker container. In order to make debugging simpler, mount the repository on the same path as opened on the code editor.

Managing Dependencies and Packages Offline

When using Cargo in an offline development environment, it is not possible to access dependencies from crates.io (The default Cargo package repository). To resolve this issue, software dependencies must be downloaded and made available offline.

Here, we will outline 2 solutions for managing dependency packages in an offline development environment.

Solution 1: Vendoring Dependency Packages

Vendoring dependencies involves downloading all the dependencies of your software, making them available for both development and runtime, and supporting them with Cargo.

Here's how to work with vendored dependencies in an offline development environment.

I. Setup Cargo to Use Vendored Dependencies

Assuming your vendored dependencies go to the source code repository sub-folder named third-party/vendor (on Windows third-party\vendor), here's what you need to do:

1. Create a .cargo folder in the root of your software repository root directory.
2. In the .cargo folder, create a config.toml file with the following configuration:

# Use Vendored dependencies
[source.crates-io]
replace-with = "vendored-sources"

# Set the vendored sub folder
[source.vendored-sources]
directory = "third-party/vendor"

 

TOML

II. Vendor the Dependencies and Copy to the Development Computer

Here's the step-by-step process:

1. On an internet-connected computer, ensure the Rust toolchain is installed following the official instructions to install.
2. Create a dummy Cargo project.

LinuxWindows-PowershellWindows-CMD

cargo new dummy

 

BASH

1. Copy the dependency sections (including dev and build dependencies) from your software's Cargo.toml file to the end of the dummy project's Cargo.toml.
2. Vendor the dependencies of the dummy project, which will match that of your developed software:

LinuxWindows-PowershellWindows-CMD

# Change to the dummy project
cd dummy

# Vendor (this will generate the 'vendor' folder in the current directory)
cargo vendor --versioned-dirs

 

BASH

1. Securely copy the vendored dependencies' folder vendor to the offline development computer. This can be done as mentioned previously.
2. Copy the vendored dependencies' folder vendor into the Cargo configured location (third-party/vendor), as specified in the file config.toml. Then proceed with building your developed software.

Solution 2: Using a crates.io mirror

Creating a mirror of crate.io is another solution. Two of the existing options are:

• panamax, developed in Rust.
• romt, developed in Python.

Conclusion

Installing and managing the Rust toolchain offline might seem daunting to newcomers, but, as outlined in this article, it's straightforward. There are two options for that:

Option 1: Local installation

1. Download the Rust Standalone Installer and rustup-init Installer (rustup-init only First Time): Begin by acquiring the Rust Standalone Installer and the rustup-init Installer on a device connected to the internet.
2. Securely Copy the Downloaded Files: Transfer these downloaded files securely to your offline development computer.
3. Rustup Installation (Only First Time): Install Rustup on your offline development computer using the rustup-init Installer.
4. Install the Rust Toolchain: Employ the Rust Standalone Installer to install the Rust toolchain on your offline development computer.
5. Manage Installed Toolchains with rustup: Utilize Rustup to effectively manage the installed toolchains.

Option 2: Using Docker Development Container

1. Download and Save the Development Docker Image: Download the development Docker image and save it on a device connected to the internet.
2. Securely Copy the Downloaded Development Docker Image File: Safely transfer the downloaded development Docker image file to your offline development computer.
3. Load the Copied Development Docker Image into Docker: On the offline development computer, use the docker load command to load the Docker image from the saved file.
4. Use the Loaded Docker Image to Create Development Containers: Once loaded, use the Docker image to create development containers for your Rust projects.

For dependency management, it's advisable to use a package repository mirror whenever possible. This approach simplifies the process of adding and updating dependencies. However, in cases where using a mirror isn't possible, dependencies vendoring remains a robust alternative.