Skip to content

setup.mdx

Latest commit

 

History

History
291 lines (180 loc) · 8.48 KB

setup.mdx

File metadata and controls

291 lines (180 loc) · 8.48 KB
Raw
title Set Up and Configure Your Environment for Writing Smart Contracts
sidebar_label Setup
description Learn how to set up Stellar smart contract development by installing Rust, configuring your editor, and setting up the Stellar CLI with this step-by-step guide.
sidebar_position 0

Setup

import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import { getPlatform } from "@site/src/helpers/getPlatform"; import { getShell } from "@site/src/helpers/getShell"; import { latestVersion } from "@site/src/helpers/stellarCli"; import { getStellarCliLatestReleaseUrl } from "@site/src/helpers/getStellarCliLatestReleaseUrl"; import { StellarCliVersion } from "@site/src/components/StellarCliVersion"; import { StellarCliWingetVersion } from "@site/src/components/StellarCliWingetVersion";

Stellar smart contracts are small programs written in the Rust programming language.

To build and develop contracts you need the following prerequisites:

Install Rust

If you use macOS, Linux, or another Unix-like OS, the simplest method to install a Rust toolchain is to install rustup. Install rustup with the following command.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then restart the terminal.

On Windows, download and run rustup-init.exe. You can continue with the default settings by pressing Enter.

:::tip

The Stellar CLI uses emojis in its output. To properly render them on Windows, it is recommended to use the Windows Terminal. See how to install Windows Terminal on Microsoft Learn. If the CLI is used in the built in Windows Command Prompt or Windows PowerShell the CLI will function as expected but the emojis will appear as question marks.

:::

If you're already using WSL, you can also follow the instructions for Linux.

For other methods of installing Rust, see: https://www.rust-lang.org/tools/install

Stellar smart contracts require Rust toolchain v1.84.0 or higher, as the wasm32v1-none target is only available in recent versions.

To check your version:

rustc --version

If you need to update:

rustup update stable

Install the target

You'll need a "target" for which your smart contract will be compiled. Install the wasm32v1-none target (again, this requires Rust v1.84.0 or higher).

rustup target add wasm32v1-none

:::note

When you install Rust, the WebAssembly target is installed per-toolchain. If you update your Rust version, you'll need to reinstall the wasm32v1-none target for the new toolchain.

:::

You can learn more about the finer points of what this target brings to the table, in our page all about the Stellar Rust dialect. This page describes the subset of Rust functionality that is available to you within Stellar smart contract environment.

Configure an editor

Many editors have support for Rust. Visit the following link to find out how to configure your editor: https://www.rust-lang.org/tools

Here are the tools to you need to configure your editor:

  1. Visual Studio Code as code editor (or another code editor that supports Rust)
  2. Rust Analyzer for Rust language support
  3. CodeLLDB for step-through-debugging

Install the Stellar CLI

The Stellar CLI can execute smart contracts on futurenet, testnet, mainnet, as well as in a local sandbox.

:::info

The latest stable release is v{latestVersion}.

:::

Install

There are a few ways to install the latest release of Stellar CLI.

Install using script (macOS, Linux):

curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh

Install with Homebrew (macOS, Linux):

brew install stellar-cli

Install with cargo from source:

Install using script (macOS, Linux):

curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh

Install with Homebrew (macOS, Linux):

brew install stellar-cli

Install with cargo from source:

:::note

Installing from source requires a C build system. To install a C build system on Debian/Ubuntu, use:

sudo apt update && sudo apt install -y build-essential

:::

Using the installer:

  1. Download the installer from the latest release.
  2. Go to your Downloads folder, double click the installer and follow the wizard instructions.
  3. Restart your terminal to use the stellar command.

Using winget:

Install with cargo from source:

:::info

Report issues and share feedback about the Stellar CLI here.

:::

Documentation

The auto-generated comprehensive reference documentation is available here.

Autocompletion

You can use stellar completion to generate shell completion for different shells. You should absolutely try it out. It will feel like a super power!

To enable autocomplete on the current shell session:

source <(stellar completion --shell bash)

To enable autocomplete permanently, run the following command, then restart your terminal:

echo "source <(stellar completion --shell bash)" >> ~/.bashrc

To enable autocomplete on the current shell session:

source <(stellar completion --shell zsh)

To enable autocomplete permanently, run the following commands, then restart your terminal:

echo "source <(stellar completion --shell zsh)" >> ~/.zshrc

To enable autocomplete on the current shell session:

stellar completion --shell fish | source

To enable autocomplete permanently, run the following command, then restart your terminal:

echo "stellar completion --shell fish | source" >> ~/.config/fish/config.fish

To enable autocomplete on the current shell session:

stellar completion --shell powershell | Out-String | Invoke-Expression

To enable autocomplete permanently, run the following commands, then restart your terminal:

New-Item -ItemType Directory -Path $(Split-Path $PROFILE) -Force
if (-Not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE | Out-Null }
Add-Content $PROFILE 'Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete'
Add-Content $PROFILE 'stellar completion --shell powershell | Out-String | Invoke-Expression'

:::tip

If you get an error like cannot be loaded because running scripts is disabled on this system, you may need to change your Execution Policy with Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser. Before running this command, be sure you understand the implications of doing so.

:::

To enable autocomplete on the current shell session:

source (stellar completion --shell elvish)

To enable autocomplete permanently, run the following commands, then restart your terminal:

echo "source (stellar completion --shell elvish)" >> ~/.elvish/rc.elv