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 at https://github.com/FuelLabs/fuelup. 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 --proto '=https' --tlsv1.2 -sSf https://fuellabs.github.io/fuelup/fuelup-init.sh | sh

This will install forc, forc-client, forc-fmt, 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 --proto '=https' --tlsv1.2 -sSf https://fuellabs.github.io/fuelup/fuelup-init.sh | 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-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 from https://github.com/FuelLabs/fuelup 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

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 installed to ~/.fuelup/bin. The forc and fuel-core executables installed in ~/.fuelup/bin are proxies that delegate to the real toolchain. fuelup then provides mechanisms to easily change the active toolchain by reconfiguring the behavior of the proxies.

When fuelup-init is first executed, fuelup automatically installs the latest toolchain. Proxies are created in $HOME/.fuelup/bin, while toolchains are installed within $HOME/.fuelup/toolchains, in their own directories.

Running forc on the latest toolchain, for example, runs the proxy, which then executes the appropriate forc found in the latest toolchain directory.

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.

Channels

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

ChannelSourceIntegration TestedUpdate FrequencyAvailable
latestpublished bins✔️checked every 30 minutes✔️
nightlymaster branchnightly (1:00 AM UTC)✔️
beta-1published binsonly when necessary✔️
beta-2published binsonly when necessary✔️

The latest channel

The latest channel is updated by a scheduled GitHub workflow that runs every 30 minutes and checks for new, compatible releases of forc and fuel-core.

The latest channel is fuelup's default channel. It provides access to the latest compatible, published releases of forc and fuel-core.

When installing the latest channel, fuelup will refer to the channel-fuel-latest.toml file published within the fuelup repository in the gh-pages branch to determine the set of forc and fuel-core versions to retrieve. The versions in this file are updated by a scheduled GitHub workflow that runs once every 30 minutes and performs the following steps:

  1. Checks for newly published versions of forc and fuel-core.
  2. Tests compatibility of new versions against a set of integration tests.
  3. Selects the latest set of versions that successfully pass the tests.
  4. Publishes the selected versions to the channel-fuel-latest.toml manifest.

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 entrypoint 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 init 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 (eg. 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.

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 nightlies 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 beta-1 channel

The beta-1 channel is a published TOML file describing the toolchain that is compatible with our beta-1 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-2 channel

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

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 (eg, 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 init 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 forc@0.19.2

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 forc@0.30.1

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, namely 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-wallet - A Forc plugin for managing Fuel wallets.

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.

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 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.

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 in to 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

CommandDescription
fuelup toolchain install latestInstalls the toolchain distributed by the latest channel
fuelup toolchain new my_toolchainCreates a new custom toolchain named 'my_toolchain' and sets it as the default
fuelup toolchain uninstall my_toolchainUninstalls the toolchain named 'my_toolchain'
fuelup default my_toolchainSets 'my_toolchain' as the active toolchain
fuelup component add forcAdds forc to the currently active custom toolchain
fuelup component add fuel-core@0.9.5Adds fuel-core v0.9.5 to the currently active custom toolchain
fuelup component remove forcRemoves forc from the currently active custom toolchain
fuelup self updateUpdates fuelup
fuelup checkChecks for updates to distributable toolchains
fuelup showShows the active toolchain and installed toolchains, as well as the host and fuelup home
fuelup toolchain helpShows the help page for a subcommand (like toolchain)
fuelup completions --shell=zshGenerate shell completions for ZSH

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 Discord.

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 are planning something big, for example, related to multiple components or changes current behaviors, make sure to open an issue to discuss with us 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 mention the issue, which is created at 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 separate by a comma, like:

close #123, ref #456