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.

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.

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 (latest and 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 [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, 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.

Examples

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