Introduction

fuelup is the official package manager for Fuel that installs The Fuel Toolchain from the official release channels, enabling you to easily switch between different toolchains and keep them updated. It makes building and maintaining Sway applications simpler with forc and fuel-core for common platforms.

Check out the Concepts chapter for an overview of how fuelup works and some of the terminology it uses. The Installation chapter covers installing fuelup and getting started.

The source code of fuelup and this manual may be found here. If you find a problem, check out the issue tracker.

Release notes for fuelup may be found under Releases in our GitHub repository.

Installation

fuelup installs forc and fuel-core, and other plugins like forc-client and forc-fmt to Fuelup's bin directory. On Unix it is located at $HOME/.fuelup/bin.

This directory can automatically be in your PATH environment variable if allowed in the installation step (explained below), which means you can run them from the shell without further configuration.

Quickstart

Installation is done through the fuelup-init script found on our repository, where you may find the source code.

Run the following command:

curl -fsSL https://install.fuel.network/ | sh

This will install forc, forc-client, forc-fmt, forc-crypto, forc-lsp, forc-wallet as well as fuel-core in ~/.fuelup/bin. The script will ask for permission to add ~/.fuelup/bin to your PATH.

Otherwise, you can also pass --no-modify-path so that fuelup-init does not modify your PATH and will not ask for permission to do so:

curl -fsSL https://install.fuel.network/ | sh -s -- --no-modify-path

Ensure that all components are downloaded and works:

fuelup --version
forc --version
fuel-core --version
forc-deploy --version
forc-fmt --version
forc-crypto --version
forc-lsp --version
forc-run --version

Other installation methods

Windows

We currently do not natively support Windows. If you wish to use fuelup on Windows, please use Windows Subsystem for Linux.

Building from source

You can also install fuelup from source. Check out the git repository and run cargo run --release.

You should then manually move the fuelup binary to .fuelup/bin.

Direct download

fuelup binaries are released on our GitHub releases page where you can directly download the appropriate bin for your system as well as check out our changelog.

Concepts

This section will explain how fuelup works on a technical level and explains each component of fuelup.

Terminology

• channel — The Fuel toolchain will be released to different "channels". Currently, it is only released to the latest channel. See the Channels chapter for more details.

• toolchain — A "toolchain" is an installation of the Fuel Orchestrator (forc), its related plugins (like forc-fmt) and the Fuel client (fuel-core). A toolchain specification includes the release channel and the host platform that the toolchain runs on.

  A toolchain can be installed either through the channels, or be modularly constructed as a custom toolchain.

• component — Each release of the Fuel toolchain includes several "components", which are tools used to develop on Fuel. See the Components chapter for more details.

How fuelup works

fuelup is largely inspired by rustup. It installs and manages multiple Fuel toolchains and presents them all through a single set of tools within ~/.fuelup/bin.

Generally, it is not recommended to manually make changes to the fuelup directory, otherwise fuelup might not function as expected. If you have made changes to the directory, we recommend removing the entire directory and re-installing fuelup with fuelup-init.

Proxies

On the surface, the installed executables seem to live in ~/.fuelup/bin, but the forc, fuel-core and other executables installed in ~/.fuelup/bin are actually not the real binaries but are all just symlinks to fuelup itself! fuelup contains logic to act as a proxy for the real binaries, so that it can change its behavior based on what component is being called. This is how fuelup can switch between toolchains.

A common mistake is to directly move binaries into the bin directory, which would break the behavior of fuelup.

Store

All actual executables are installed within the store. This is usually ~/.fuelup/store. This is where the real binaries are installed and cached to be used in toolchains and overrides through symlinks. fuelup will always check the store for existing components before trying to install them - which means you can avoid the download entirely if something is already cached within the store!

Example

To give an example of how this all works together: imagine typing forc build in your terminal. This call invokes forc (which is actually fuelup) within the fuelup bin directory, which in turn executes the correct version of forc based on either an override file (fuel-toolchain.toml) or your currently active toolchain (in order of priority).

Channels

fuelup adopts a simplified version of rustup channels. Currently, the latest, nightly, and beta channels are published and serve as a source of distribution of Fuel toolchain binaries.

The beta-3 channel

The beta-3 channel is a published TOML file describing the toolchain that is compatible with our beta-3 testnet. This toolchain should be used to interact with and build on the testnet. The components to be installed can be found here.

The beta-4 channel

The beta-4 channel is a published TOML file describing the toolchain that is compatible with our beta-4 testnet. This toolchain should be used to interact with and build on the testnet. The components to be installed can be found here.

The nightly channel

The nightly channel is a published TOML file describing successful builds of the master branch of forc and fuel-core for the day. These builds are released in the sway-nightly-binaries repository and the workflows in that repo start building them every day at 00:00 UTC.

The nightly channel within fuelup is updated by a scheduled GitHub workflow that runs every day at 01:00 UTC, after builds have finished. Note that the nightly channel might fail to build, in which case it is possible that the nightly toolchain may not be available for that day.

You should use nightly if you want the latest changes to master that have not been officially released yet. Keep in mind that compatibility between forc and fuel-core is not guaranteed here, and you should expect unstable features to break.

The latest channel

The latest channel is pointing to our latest beta network. This toolchain should be used to interact with and build on the latest testnet. This is also the default channel for fuelup.

Note

The latest channel used to point latest compatible versions of forc and fuel-core, after version v0.20.0 latest is changed to point to the latest network. This is a breaking change and should be taken into account for existing workflows.

Developer Guide

Understanding the latest workflow

Note

Reading the information below is only really necessary if you wish to contribute to the workflows or want a deeper understanding on how channels are updated.

The entry point of the scheduled workflow is within index-versions.yml. We run the Rust script compare-versions to collect versions of forc and fuel-core to be tested. These versions are filtered for incompatible versions prior to being used as a JSON string input to test-toolchain-compatibility.yml, where the testing occurs.

In test-toolchain-compatibility.yml, The versions JSON string input is used to initialize a matrix using the fromJSON expression. We checkout the Sway repo at the given forc version and pull the fuel-core Docker image at the given fuel-core version and run integration tests found in the Sway CI for them.

Note that we only mark versions as incompatible specifically if tests fail, and not if other prior steps fail (e.g. we do not want to mark versions as incompatible if there were errors pulling the Docker image)

The upload-artifact action is used to collect the test results from the matrix to be used later in a download-artifact step.

If tests were not skipped and are now done, we finally get to the index-versions job. We download the artifacts that were previously uploaded to be used here. This job will:

1. upload incompatible versions to gh-pages. These incompatible versions are named in the format incompatible-forc-<FORC_VERSION>@fuel-core-<FUEL_CORE_VERSION>.

2. update the channel by filtering for the latest versions of forc and fuel-core that passed tests within the matrix by running index-versions.sh. These are named in the format compatible-forc-<FORC_VERSION>@fuel-core-<FUEL_CORE_VERSION>. Note that these files are not saved or uploaded onto gh-pages - they are only a way for the test-toolchain-compatibility job to share test results with this job.

Debugging the workflow

If you're contributing to the workflows, it might be a good idea to fork the repo and test any changes you've made on a personal repo first.

Some changes you might want to make to allow for easier testing:

1. You may want to use the push or workflow_dispatch triggers to make testing easier.

2. You can also exit with 0 or 1 in jobs or steps where you want it to pass/fail.

You may also use nektos/act to run the workflow(s) locally.

Toolchains

Many fuelup commands deal with toolchains, a single installation of the Fuel toolchain. fuelup supports two types of toolchains.

1. Distributable toolchains which track the official release channels (e.g., latest, nightly);
2. Custom toolchains and install individual components in a modular manner.

Toolchain specification

Standard release channel toolchain names have the following form:

<channel>[-<date>][-<host>]

<channel>       = latest
<date>          = YYYY-MM-DD
<host>          = <target-triple>

'channel' is a named release channel. Channel names can be optionally appended with an archive date, as in nightly-2014-12-18, in which case the toolchain is downloaded from the archive for that date.

Finally, the host may be specified as a target triple.

Custom toolchains

For most use cases, using the officially packaged toolchains is good enough.

For advanced use cases, fuelup allows you to build a toolchain in a modular manner, and to specify specific versions of components to install.

To initialize a new, empty toolchain:

fuelup toolchain new my_toolchain

Now you can add/remove components to/from the toolchain as you wish:

fuelup component add forc

In custom toolchains, you can specify a specific version of a component to install:

fuelup component add [email protected]

Components

Each toolchain has several "components", which are tools used to develop on Fuel.

The fuelup component command is used to manage the installed components.

Components can be added to an already-installed toolchain with the fuelup component command:

fuelup component add forc

In custom toolchains, you also have the choice of adding a specific version of a component:

fuelup component add [email protected]

Components overview

The following is an overview of components installable through fuelup:

• forc — The Fuel Orchestrator, a suite of tools to work with the Fuel ecosystem. This comes with some built-in plugin executables, including but not limited to: forc-client, forc-fmt and forc-lsp.
• fuel-core — Full node implementation of the Fuel v2 protocol, written in Rust.
• forc-explore — A Forc plugin for running the Fuel Block Explorer.
• forc-crypto — Forc plugin for hashing arbitrary data.
• forc-wallet - A Forc plugin for managing Fuel wallets.
• fuel-indexer - A standalone service that can be used to index various components of the Fuel blockchain.
• forc-index - A Forc plugin used to interact with a Fuel Indexer service.

Proxies

fuelup provides wrappers for the common Fuel toolchain components. These are called proxies and represent commands which are provided by the components themselves.

This is how fuelup knows to differentiate between different toolchains and different versions of the same components, since running a component's command will use fuelup as a proxy to execute.

This allows the developer to switch smoothly between different toolchains if they are working on different projects.

Store

This is where all the actual binaries are installed and sometimes executed through overrides. Components will be installed in directories named in the format <NAME>-<VERSION>.

For example, forc v0.35.5 will be installed in a directory called forc-0.35.5.

Basic usage

The quickest way to get started is to install the latest toolchain, although this step should be automatically done if you installed fuelup via fuelup-init:

fuelup toolchain install latest

Keeping the Fuel toolchain up to date

The Fuel toolchain is distributed on one release channel: latest (with nightly being a WIP). fuelup uses the latest channel by default, which represents the latest stable release of the Fuel toolchain.

When new versions of the components within an distributable Fuel toolchain (latest or nightly) are released, simply type fuelup update to update:

fuelup update

Keeping fuelup up to date

You can request that fuelup update itself to the latest version of fuelup by running:

fuelup self update

Help system

The fuelup command-line is built with clap, which serves a nice, built-in help system that provides more information about each command. Run fuelup help for an overview. Detailed help for each subcommand is also available.

For example, run fuelup component --help for specifics on installing components.

Overrides

fuelup automatically determines which toolchain to use when one of the installed commands like forc is executed.

You can override the installed default toolchain using a fuel-toolchain.toml file.

The toolchain file

The fuel-toolchain.toml file allows projects to "pin" to a specific set of fuel toolchain component versions. This greatly improves the reproducibility of a project, as the fuel-toolchain.toml contains the set of known, working versions for each tool used to build it.

When this file is present, fuelup will override the default toolchain with the specified toolchain when executing binaries in the toolchain.

In these cases, the toolchain can be specified in a file called fuel-toolchain.toml. These toolchains can only be the distributed toolchains at this point in time.

Here's what a sample project might look like:

$ tree -L 1 # 'tree -L 1' shows the project structure up to the depth of 1
.
├── Cargo.toml
├── Forc.toml
├── fuel-toolchain.toml
├── project
├── README.md
└── SPECIFICATION.md

Examples

An application using the beta-3 toolchain:

[toolchain]
channel = "beta-3"

Let's say we have a project on the beta-3 testnet, and we want to try using a different version forc to develop on it:

[toolchain]
channel = "beta-3"

[components]
forc = "0.36.0" # in beta-3, forc is pinned to v0.37.3

Configuration

fuelup has a TOML settings file at .fuelup/settings.toml. The schema for this file is not part of the public interface for fuelup - the fuelup CLI should be used to query and set settings.

Generate Shell Completions

Enable tab completion for Bash, Fish, Zsh, or PowerShell. The script prints output on stdout, allowing one to re-direct the output to the file of their choosing. Where you place the file will depend on which shell, and which operating system you are using. Your particular configuration may also determine where these scripts need to be placed.

Here are some common set ups for the supported shells under Unix and similar operating systems (such as GNU/Linux). For these settings to take effect, you may have to log out and log back into your shell session.

BASH

Completion files are commonly stored in /etc/bash_completion.d/ for system-wide commands, but can be stored in ~/.local/share/bash-completion/completions for user-specific commands.

mkdir -p ~/.local/share/bash-completion/completions
fuelup completions --shell=bash >> ~/.local/share/bash-completion/completions/fuelup

BASH (macOS/Homebrew)

Homebrew stores bash completion files within the Homebrew directory. With the bash-completion brew formula installed.

mkdir -p $(brew --prefix)/etc/bash_completion.d
fuelup completions --shell=bash > $(brew --prefix)/etc/bash_completion.d/fuelup.bash-completion

FISH

Fish completion files are commonly stored in $HOME/.config/fish/completions.

mkdir -p ~/.config/fish/completions
fuelup completions --shell=fish > ~/.config/fish/completions/fuelup.fish

ZSH

ZSH completions are commonly stored in any directory listed in your $fpath variable. To use these completions, you must either add the generated script to one of those directories, or add your own to this list.

Adding a custom directory is often the safest bet if you are unsure of which directory to use. First create the directory; for this example we'll create a hidden directory inside our $HOME directory:

mkdir ~/.zfunc

Then add the following lines to your .zshrc just before compinit:

fpath+=~/.zfunc

Now you can install the completions script using the following command:

fuelup completions --shell=zsh > ~/.zfunc/_fuelup

PowerShell

The powershell completion scripts require PowerShell v5.0+ (which comes with Windows 10, but can be downloaded separately for windows 7 or 8.1).

First, check if a profile has already been set

Test-Path $profile

If the above command returns False run the following

New-Item -path $profile -type file -force

Now open the file provided by $profile (if you used the New-Item command it will be ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1).

Next, we either save the completions file into our profile, or into a separate file and source it inside our profile. To save the completions into our profile simply use

fuelup completions --shell=powershell >> ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

ELVISH

Elvish completions are commonly stored in epm-managed directories.

fuelup completions --shell=elvish > ~/.local/share/elvish/lib/fuelup.elv

Then in rc.elv, add the following line to activate the generated completions.

use fuelup

Examples

Developer Guide

This section serves as a guide for people who are interested on working on and contributing to fuelup.

If you simply wish to use fuelup, you may ignore this section.

This section will go through:

• How to setup fuelup in your environment for contributions,
• How to add support for a component to fuelup
• How build-channel is used in the CI, and how to manually use it to build a channel for fuelup

Contributing To Fuelup

Thanks for your interest in contributing to fuelup! This document outlines the process for installing and setting up fuelup, as well as some conventions on contributing to fuelup.

If you run into any difficulties getting started, you can always ask questions on our Forum.

Getting the repository

1. Visit the fuelup repo and fork the project.
2. Then clone your forked copy to your local machine and get to work.

git clone https://github.com/FuelLabs/fuelup
cd fuelup

Building and testing

The following steps will run the fuelup test suite and ensure that everything is set up correctly.

First, run and ensure all tests pass:

cargo test

There are both unit tests and integration tests. Unit tests involve testing isolated components of the codebase, while integration tests involve directly invoking the fuelup binary in a sandboxed environment with a temporary filesystem.

Note that some integration tests involve installing a toolchain and adding components, which means they will fail without internet connection.

Congratulations! You've now got everything setup and are ready to start making contributions.

Finding something to work on

There are many ways in which you may contribute to fuelup, some of which involve coding knowledge and some which do not. A few examples include:

• Reporting bugs
• Adding documentation to the fuelup book
• Adding new features or bugfixes for which there is already an open issue
• Making feature requests

Check out our Help Wanted, Fuelup Book or Good First Issue issues to find a suitable task.

If you wish to make a significant change that alters current behavior or touches multiple components, make sure to open an issue for discussion before starting on the implementation.

Contribution flow

This is a rough outline of what a contributor's workflow looks like:

• Make sure what you want to contribute is already tracked as an issue.
  • We may discuss the problem and solution in the issue.
• Create a Git branch from where you want to base your work. This is usually master.
• Write code, add test cases, and commit your work.
• Run tests and make sure all tests pass.
• If the PR contains any breaking changes, add the breaking label to your PR.
• Push your changes to a branch in your fork of the repository and submit a pull request.
  • Make sure to mention the issue, which is created in step 1, in the commit message.
• Your PR will be reviewed and some changes may be requested.
  • Once you've made changes, your PR must be re-reviewed and approved.
  • If the PR becomes out of date, you can use GitHub's 'update branch' button.
  • If there are conflicts, you can merge and resolve them locally. Then push to your PR branch. Any changes to the branch will require a re-review.
• Our CI system (Github Actions) automatically tests all authorized pull requests.
• Use Github to merge the PR once approved.

Thanks for your contributions!

Linking issues

Pull requests should be linked to at least one issue in the same repo.

If the pull request resolves the relevant issues, and you want GitHub to close these issues automatically after it merged into the default branch, you can use the syntax (KEYWORD #ISSUE-NUMBER) like this:

close #123

If the pull request links an issue but does not close it, you can use the keyword ref like this:

ref #456

Multiple issues should use full syntax for each issue and be separated by a comma, like:

close #123, ref #456

Adding components

Adding components in fuelup is often just a small PR to components.toml in the repo, followed by a new release of fuelup.

Contributing to components.toml

This section describes how you may add support for a binary within fuelup.

Required interface

All fuelup components must implement the --version argument. fuelup uses this to display version information in its CLI. It should print the name of the executable and the full semver version number. For example:

$ forc-tx --version
forc-tx 0.44.1

Binary packaged natively in forc

This refers to binaries like forc-fmt that are added within the Sway repository.

In this scenario, fuelup will already automatically download the tar file from the Sway repository and unarchive all of them without discrimination. You will be able to use the executables, but certain features like fuelup show may not work until you add them to the components.toml within the source code. fuelup reads from this TOML file to know which components are supported directly through itself, so this step is important. You may follow the PR adding forc-tx as an example of how to add such a component.

Binary packaged outside of forc

This refers to standalone binaries like forc-wallet which have their own repositories.

In this case, fuelup will NOT download the tar file automatically since it does not know where to download it from. Currently, we do not support downloading and using arbitrary forc plugins and components, so information will have to be added to components.toml for fuelup to know how to handle these. You may follow the PR adding forc-wallet as an example of how to add such a component.

Example:

[component.forc-wallet]
name = "forc-wallet"
tarball_prefix = "forc-wallet"
is_plugin = true
executables = ["forc-wallet"]
repository_name = "forc-wallet"
targets = [ "aarch64-unknown-linux-gnu", "x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-apple-darwin" ]
publish = true

A short description of the keys you find above:

name

• Name of the component/plugin.

tarball_prefix

• Fuel binaries mostly conform to the format <name>-<version>-<target> for our tar files. tarball_prefix refers to the <name> part.

executables

• In most cases, the name of the component is the executable itself, but certain components like forc itself and forc-client may package multiple executables and therefore have different names.

repository_name

• The repo name that contains the releases.

targets

• A list of targets the component is released for.

is_plugin

• Optional. This tells you if this component is a forc plugin.

publish

• Optional. Declares if the component is published as a standalone, or packaged with forc.

Building a channel

build-channel is a Rust script that creates a channel that serves as a source of distribution of the Fuel toolchain. This is accomplished by querying and collecting a list of downloadable components that Fuel Labs publishes, creating a TOML file based on the collated data, which is then consumed by fuelup during usage.

To learn about the args and options used in the script, skip to Usage.

Use cases

There are 2 main ways the build-channel script is used: in the CI, and manually.

CI

This script's main usage is found within the fuelup CI. This script is in charge of publishing the latest and nightly channels on a routine basis.

The latest channel is re-built if the check versions workflow detects a new release of forc or fuel-core, and compatibility tests pass after that. This is explained in detail in the latest channel developer guide.

An example of this usage is in test-toolchain-compatibility.yml.

The nightly channel is more straightforward - a channel is built at 01:00 UTC every day, containing the download links to binaries found within the sway-nightly-binaries repository.

An example of this usage is in publish-nightly-channel.yml.

Manual

There may be times when we need a channel for a one-off event e.g. testnets. During these events, we do not

require a routine update, and can essentially publish once and be done. This is when manual publishing is done.

For example, building a beta-3 toolchain is done like so:

# from fuelup project root
cd ci/build-channel && cargo run -- channel-fuel-beta-3.toml 2023-02-13 forc=0.35.0 fuel-core=0.17.1

The above command means that we're building a channel named channel-fuel-beta-3.toml with the date 2023-02-13 (YYYY-MM-DD) and forc and fuel-core versions 0.35.0 and 0.17.1 respectively, and the latest versions for the other unlisted components.

Other than for these one-off events, manually running build-channel locally is a good sanity check when working on this codebase.

Usage

Arguments

OUT_FILE

• Name of TOML file that will be created.

PUBLISH_DATE

• The date for when the channel was created and published.

GITHUB_RUN_ID

• Optional. This is the $GITHUB_RUN_ID variable in the GitHub CI. Identifies the specific run that a channel was published by.

PACKAGES

• Optional. A list of key-value pairs mapping component names to SemVer-compatible versions, e.g. 'fuel-core=0.17.1'

Options

--nightly

• Optional. Specify if we are building a nightly channel.